// agent.ts // Reference implementation for exercise 14: the product core — the part of // chapter 14's CLI agent that is pure logic, extractable from the interface. // Three sections mirror the product's lib/ modules (config.mjs, tools.mjs, // loop.mjs) so what you practise here IS what the product ships: // // stage 1 · config: loadConfig(env) -> Config // stage 2 · tools: registry + schema generation + error-as-data executor // stage 3 · loop: runAgent() — think -> act -> observe // // Each gap in the starter has exactly one corresponding implementation here. // Zero dependencies, web platform APIs only (Date / JSON), no imports — the // same suite runs under vitest (CLI) and inside the browser sandbox judge. // ======================= shared types ======================= export interface Config { model: string; apiKey: string; baseUrl: string; temperature: number; maxIterations: number; } export interface ToolParam { name: string; type: string; description: string; required?: boolean; } // The declarative contract the model sees (name + description + parameters). export interface ToolSpec { name: string; description: string; parameters: ToolParam[]; } // One registered tool: the spec (contract) + the plain impl function. export interface ToolEntry { spec: ToolSpec; impl: (args: Record) => unknown; } export interface ToolRegistry { register(spec: ToolSpec, impl: (args: Record) => unknown): void; list(): ToolEntry[]; get(name: string): ToolEntry | undefined; } export interface ToolCall { id: string; name: string; arguments: Record; } export interface Message { role: string; content: string; tool_calls?: ToolCall[]; tool_call_id?: string; } export interface LlmResponse { content: string; toolCalls: ToolCall[]; } // The model-facing tool array the loop derives from the registry. export interface ModelTool { name: string; description: string; schema: Record; } export type CallLlm = (messages: Message[], tools: ModelTool[]) => Promise; // Trace events let the interface log what the loop is doing without the loop // knowing who listens (the CLI prints them; a later chapter turns this hook // into a streaming event protocol). export interface TraceEvent { type: 'think' | 'act' | 'observe' | 'done'; call?: ToolCall; content?: string; finalText?: string; iterations?: number; truncated?: boolean; } export interface RunOptions { callLlm: CallLlm; tools: ToolRegistry; maxIterations?: number; onEvent?: (event: TraceEvent) => void; } export interface RunResult { messages: Message[]; finalText: string; iterations: number; } // ======================= stage 1: config ======================= /** * Reads the runtime configuration from an env-like object with defaults, so * nothing is hard-coded in call sites. Pure: reads only the object it is * given (defaults to {} so it works in a browser, where process.env is * absent). Numeric fields are parsed from strings. */ export function loadConfig(env: Record = {}): Config { return { model: env.MODEL ?? 'mock-model', apiKey: env.API_KEY ?? 'mock-key', baseUrl: env.BASE_URL ?? 'http://localhost:3218', temperature: Number(env.TEMPERATURE ?? 0.7), maxIterations: Number(env.MAX_ITERATIONS ?? 5), }; } // ======================= stage 2: tools ======================= /** * The registry: a name -> { spec, impl, schema } map. register() generates * the model-facing schema ONCE from the spec (single source of truth) and * rejects duplicate names so conflicts surface early. list() returns tools in * registration order; get() looks one up for dispatch. */ export function createToolRegistry(): ToolRegistry { const tools = new Map }>(); return { register(spec, impl) { if (tools.has(spec.name)) { throw new Error(`tool already registered: ${spec.name}`); } tools.set(spec.name, { spec, impl, schema: generateSchemaFromSpec(spec) }); }, list() { return [...tools.values()]; }, get(name) { return tools.get(name); }, }; } /** * Derives the model-facing JSON Schema from the declarative spec. Properties * are required unless the param says required: false. Schema and impl can * never drift, because the schema is computed from the same spec the impl * is registered with. */ export function generateSchemaFromSpec(spec: ToolSpec): Record { const properties: Record = {}; const required: string[] = []; for (const p of spec.parameters) { properties[p.name] = { type: p.type, description: p.description }; if (p.required !== false) required.push(p.name); } return { type: 'object', properties, required }; } /** * Dispatch + error-as-data: NEVER throws. A missing tool or an impl that * throws both come back as { ok: false, error: string } — data the loop feeds * to the model so it can correct itself, instead of a crash. */ export function executeTool( registry: ToolRegistry, name: string, args: Record, ): { ok: true; result: unknown } | { ok: false; error: string } { const entry = registry.get(name); if (!entry) { return { ok: false, error: `unknown tool: ${name}` }; } try { return { ok: true, result: entry.impl(args) }; } catch (err) { const message = err instanceof Error ? err.message : String(err); return { ok: false, error: `Error: ${message}` }; } } /** * The product's built-in tool set: pure, deterministic, side-effect-free * functions only (the safe core of a tool set; side-effecting tools arrive * with a permission layer in a later chapter). */ export function createBaseTools(): ToolRegistry { const registry = createToolRegistry(); registry.register( { name: 'get_time', description: 'Get the current UTC time as an ISO 8601 string.', parameters: [], }, () => new Date().toISOString(), ); registry.register( { name: 'get_weather', description: 'Get the current weather for a given city.', parameters: [ { name: 'location', type: 'string', description: 'City name, e.g. Shanghai.' }, ], }, (args) => { const location = String(args.location ?? 'Shanghai'); const table: Record = { Shanghai: '上海：晴，27°C，微风，紫外线中等', Beijing: '北京：多云，24°C，西北风 3 级', London: '伦敦：小雨，15°C，体感偏凉', }; return table[location] ?? `${location}：晴，20°C`; }, ); registry.register( { name: 'add', description: 'Add two numbers and return the sum.', parameters: [ { name: 'a', type: 'number', description: 'First addend.' }, { name: 'b', type: 'number', description: 'Second addend.' }, ], }, (args) => { const a = args.a; const b = args.b; // The impl owns validation: a non-number is a THROW, and the error // protocol turns it into an informative string the model can read. if (typeof a !== 'number' || typeof b !== 'number') { throw new TypeError( `add() expects numeric a and b, got a=${JSON.stringify(a)}, b=${JSON.stringify(b)}`, ); } return a + b; }, ); return registry; } // ======================= stage 3: loop ======================= export const DEFAULT_MAX_ITERATIONS = 5; /** * The model-facing tool list, in registration order. The loop owns this * registry -> model translation; the provider translates further to the * vendor wire format. */ export function modelTools(registry: ToolRegistry): ModelTool[] { return registry.list().map(({ spec, schema }) => ({ name: spec.name, description: spec.description, schema, })); } /** * The agent loop: think -> act -> observe until the model stops asking for * tools (normal) or the maxIterations fuse blows (safety). Upgrades over the * chapter 07 minimal loop: tools is a REGISTRY executed through * executeTool(), so a failing or unknown tool becomes a model-visible string * instead of aborting the round; and onEvent reports what the loop is doing * without the loop knowing who listens. */ export async function runAgent( initialMessages: Message[], { callLlm, tools, maxIterations = DEFAULT_MAX_ITERATIONS, onEvent }: RunOptions, ): Promise { const messages = [...initialMessages]; // the loop only appends to its own copy let iterations = 0; while (iterations < maxIterations) { // think: full history + the current tool list go to the model. const toolList = modelTools(tools); onEvent?.({ type: 'think' }); const response = await callLlm(messages, toolList); // The model's output always lands in the history first (text + maybe tool_calls). const assistant: Message = { role: 'assistant', content: response.content }; if (response.toolCalls.length > 0) assistant.tool_calls = response.toolCalls; messages.push(assistant); // Stop condition 1 (normal): no tool calls -> the text is the final answer. if (response.toolCalls.length === 0) { onEvent?.({ type: 'done', finalText: response.content, iterations: iterations + 1 }); return { messages, finalText: response.content, iterations: iterations + 1 }; } // act + observe: run each requested tool through the error-as-data // executor and feed the result back as a tool message (a string, paired // with the call id). Failures are data, not crashes. for (const call of response.toolCalls) { onEvent?.({ type: 'act', call }); const outcome = executeTool(tools, call.name, call.arguments); const content = outcome.ok ? stringifyToolResult(outcome.result) : outcome.error; messages.push({ role: 'tool', tool_call_id: call.id, content }); onEvent?.({ type: 'observe', call, content }); } iterations += 1; } // Stop condition 2 (fuse): maxIterations reached — fall back to the last // assistant text so the user never faces an empty answer. const lastAssistant = [...messages].reverse().find((m) => m.role === 'assistant'); const finalText = lastAssistant?.content ?? ''; onEvent?.({ type: 'done', finalText, iterations, truncated: true }); return { messages, finalText, iterations }; } // Tool results must reach the model as strings (wire contract): strings pass // through, anything else is serialized. function stringifyToolResult(result: unknown): string { return typeof result === 'string' ? result : JSON.stringify(result); }