@vietor/agent-core 0.7.3 → 0.7.5

package/README.md

@@ -46,8 +46,10 @@ const session = await createSession({
 
 session.onEvent((e) => {
   if (e.type === "assistant_delta") process.stdout.write(e.text);
-  else if (e.type === "run_metrics")
-    console.log(`tokens: ${e.inputTokens} prompt / ${e.outputTokens} completion`);
+  else if (e.type === "run_metrics") {
+    const inputTokens = e.cacheInputTokens + e.missInputTokens;
+    console.log(`tokens: ${inputTokens} input / ${e.outputTokens} output`);
+  }
 });
 
 const result = await session.prompt("What files are in the current directory?");
@@ -219,7 +221,8 @@ interface RunMetrics {
   elapsed: number;         // seconds since the current prompt started
   thinkingElapsed: number; // seconds before the first assistant text token (incl. thinking/tools)
   replyElapsed: number;    // seconds after the first assistant text token (incl. later tool rounds)
-  inputTokens: number;     // cumulative input (prompt) tokens for the current run
+  cacheInputTokens: number; // cumulative cached input (prompt) tokens for the current run
+  missInputTokens: number; // cumulative non-cached input (prompt) tokens for the current run
   outputTokens: number;    // cumulative output (completion) tokens for the current run
 }
 ```

package/dist/create-session.js

@@ -2,7 +2,7 @@ import { createLLM } from "./llm/client.js";
 import { Session } from "./runtime/session.js";
 import { ToolRegistry } from "./tools/registry.js";
 import { MCPServerManager } from "./mcp/manager.js";
-import { TOOL_USE_PROMPT } from "./runtime/prompts.js";
+import { renderToolUsePrompt } from "./runtime/prompts.js";
 import { DEFAULT_MAX_TURNS } from "./util/constants.js";
 import { TODO_WRITE_GUIDANCE } from "./tools/todo-write.js";
 import { ASK_USER_GUIDANCE } from "./tools/ask-user.js";
@@ -13,7 +13,7 @@ function contextLimitFor(maxInputTokens) {
 }
 function buildSystemPrompt(base, skills, builtInTools, maxTurns) {
     const parts = [base];
-    const toolUseLines = [TOOL_USE_PROMPT, `- Turn budget: ${maxTurns} tool-calling turns per run.`];
+    const toolUseLines = [renderToolUsePrompt(maxTurns)];
     if (typeof builtInTools === "object") {
         if (builtInTools.todoWrite)
             toolUseLines.push(TODO_WRITE_GUIDANCE);

package/dist/llm/anthropic.js

@@ -44,7 +44,7 @@ export class AnthropicAdapter extends BaseAdapter {
         const stream = this.client.messages.stream(params, { signal: opts.signal });
         if (opts.onUsage)
             stream.on("streamEvent", (e) => { if (e.type === "message_start")
-                opts.onUsage(e.message.usage.input_tokens, 0); });
+                opts.onUsage(0, e.message.usage.input_tokens, 0); });
         if (opts.onDelta)
             stream.on("text", (delta) => opts.onDelta(delta));
         if (opts.onThinking)
@@ -53,7 +53,8 @@ export class AnthropicAdapter extends BaseAdapter {
             stream.on("contentBlock", (block) => { if (block.type === "tool_use")
                 opts.onToolCall(); });
         const final = await stream.finalMessage();
-        opts.onUsage?.(final.usage.input_tokens, final.usage.output_tokens);
+        const cacheTokens = (final.usage.cache_read_input_tokens ?? 0) + (final.usage.cache_creation_input_tokens ?? 0);
+        opts.onUsage?.(cacheTokens, final.usage.input_tokens, final.usage.output_tokens);
         const thinking = [];
         let text = "";
         const toolCalls = [];

package/dist/llm/completions.js

@@ -31,7 +31,8 @@ export class CompletionsAdapter extends BaseAdapter {
         const stream = await this.client.chat.completions.create(params, { signal });
         for await (const chunk of stream) {
             if (chunk.usage) {
-                onUsage?.(chunk.usage.prompt_tokens ?? 0, chunk.usage.completion_tokens ?? 0);
+                const cached = chunk.usage.prompt_tokens_details?.cached_tokens ?? 0;
+                onUsage?.(cached, chunk.usage.prompt_tokens ?? 0, chunk.usage.completion_tokens ?? 0);
             }
             const delta = chunk.choices[0]?.delta;
             if (!delta)

package/dist/llm/responses.js

@@ -59,7 +59,8 @@ export class ResponsesAdapter extends BaseAdapter {
             throw new Error(`Responses API error: ${detail}`);
         }
         if (finalResponse.usage) {
-            onUsage?.(finalResponse.usage.input_tokens, finalResponse.usage.output_tokens);
+            const cacheTokens = finalResponse.usage.input_tokens_details.cached_tokens;
+            onUsage?.(cacheTokens, finalResponse.usage.input_tokens, finalResponse.usage.output_tokens);
         }
         const textParts = [];
         const toolCalls = [];

package/dist/llm/types.d.ts

@@ -23,7 +23,7 @@ export interface ChatOptions {
     onDelta?: (text: string) => void;
     onThinking?: (text: string) => void;
     onRetry?: (attempt: number, max: number, error: unknown) => void;
-    onUsage?: (inputTokens: number, outputTokens: number) => void;
+    onUsage?: (cacheInputTokens: number, missInputTokens: number, outputTokens: number) => void;
     onToolCall?: () => void;
     thinking?: boolean;
     signal?: AbortSignal;

package/dist/runtime/agent.d.ts

@@ -31,15 +31,18 @@ export declare class Agent {
     private todoSnapshot;
     private resolveSkill?;
     private onCompact?;
-    private inputTokens;
+    private cacheInputTokens;
+    private missInputTokens;
     private outputTokens;
     constructor(opts: AgentOptions);
     get contextTokens(): number;
     get usage(): {
-        inputTokens: number;
+        cacheInputTokens: number;
+        missInputTokens: number;
         outputTokens: number;
     };
     resetUsage(): void;
+    addUsage(cacheInputTokens: number, missInputTokens: number, outputTokens: number): void;
     get model(): string;
     get thinkingEffort(): import("../llm/types.js").LLMThinkingEffort;
     clear(): void;

package/dist/runtime/agent.js

@@ -18,7 +18,8 @@ export class Agent {
     todoSnapshot = [];
     resolveSkill;
     onCompact;
-    inputTokens = 0;
+    cacheInputTokens = 0;
+    missInputTokens = 0;
     outputTokens = 0;
     constructor(opts) {
         this.llm = opts.llm;
@@ -37,12 +38,18 @@ export class Agent {
         return this.conversation.getEstimatedTokens();
     }
     get usage() {
-        return { inputTokens: this.inputTokens, outputTokens: this.outputTokens };
+        return { cacheInputTokens: this.cacheInputTokens, missInputTokens: this.missInputTokens, outputTokens: this.outputTokens };
     }
     resetUsage() {
-        this.inputTokens = 0;
+        this.cacheInputTokens = 0;
+        this.missInputTokens = 0;
         this.outputTokens = 0;
     }
+    addUsage(cacheInputTokens, missInputTokens, outputTokens) {
+        this.cacheInputTokens += cacheInputTokens;
+        this.missInputTokens += missInputTokens;
+        this.outputTokens += outputTokens;
+    }
     get model() {
         return this.llm.model;
     }
@@ -207,6 +214,7 @@ export class Agent {
     }
     async chatOnce(opts, onAbort) {
         try {
+            let usage;
             const message = await withAbort(this.llm.chat({
                 messages: opts.messages,
                 tools: opts.tools,
@@ -214,12 +222,13 @@ export class Agent {
                 onDelta: (text) => opts.onEvent?.({ type: "assistant_delta", text }),
                 onThinking: (text) => opts.onEvent?.({ type: "thinking_delta", text }),
                 onRetry: (attempt, max, error) => opts.onEvent?.({ type: "retry", attempt, max, reason: toErrorMessage(error) }),
-                onUsage: (inputTokens, outputTokens) => {
-                    this.inputTokens = inputTokens;
-                    this.outputTokens = outputTokens;
+                onUsage: (cacheInputTokens, missInputTokens, outputTokens) => {
+                    usage = { cacheInputTokens, missInputTokens, outputTokens };
                 },
                 signal: opts.signal,
             }), opts.signal);
+            if (usage)
+                this.addUsage(usage.cacheInputTokens, usage.missInputTokens, usage.outputTokens);
             return { ok: true, message };
         }
         catch (e) {

package/dist/runtime/events.d.ts

@@ -3,7 +3,8 @@ export interface RunMetrics {
     elapsed: number;
     thinkingElapsed: number;
     replyElapsed: number;
-    inputTokens: number;
+    cacheInputTokens: number;
+    missInputTokens: number;
     outputTokens: number;
 }
 export declare const INITIAL_RUN_METRICS: RunMetrics;

package/dist/runtime/events.js

@@ -1 +1 @@
-export const INITIAL_RUN_METRICS = { running: false, elapsed: 0, thinkingElapsed: 0, replyElapsed: 0, inputTokens: 0, outputTokens: 0 };
+export const INITIAL_RUN_METRICS = { running: false, elapsed: 0, thinkingElapsed: 0, replyElapsed: 0, cacheInputTokens: 0, missInputTokens: 0, outputTokens: 0 };

package/dist/runtime/prompts.d.ts

@@ -1,5 +1,6 @@
 import type { Todo } from "../tools/types.js";
 export declare const TOOL_USE_PROMPT: string;
+export declare function renderToolUsePrompt(maxTurns: number): string;
 export declare const COMPACT_PROMPT: string;
 export declare function renderTodoReminder(todos: readonly Todo[]): string;
 export declare function renderIncompleteTodoNudge(todos: readonly Todo[]): string;

package/dist/runtime/prompts.js

@@ -8,6 +8,9 @@ export const TOOL_USE_PROMPT = [
     "- For file operations (read/write/edit/glob/grep) and fetching URLs, use the dedicated tool. Fall back to Shell only when no dedicated tool covers the task and Shell is available. A runtime error does not make Shell the fallback; do not retry that same operation through Shell.",
     "- If a tool call fails, read the error, adjust the arguments or approach, and continue; do not repeat the identical call and do not abandon the task over a single failure.",
 ].join("\n");
+export function renderToolUsePrompt(maxTurns) {
+    return [TOOL_USE_PROMPT, `- Turn budget: ${maxTurns} tool-calling turns per run.`].join("\n");
+}
 export const COMPACT_PROMPT = [
     "Summarize the conversation above for context continuation. Preserve:\n",
     "1. Primary goal, sub-goals, constraints, acceptance criteria.\n",
@@ -34,7 +37,7 @@ export function renderTodoReminder(todos) {
     const focusLine = focus ? ` Current focus: ${focus.content}` : "";
     const incomplete = todos.filter(t => t.status !== "completed");
     const warning = incomplete.length > 0
-        ? ` ${incomplete.length} incomplete. You MUST complete EVERY task before your final text-only response — update status via TodoWrite after each task finishes.`
+        ? ` ${incomplete.length} incomplete. You MUST complete EVERY task before your final text-only response. Mark them complete via TodoWrite as they finish; the final update may go in the same turn as your last tool call.`
         : "";
     return `<system-reminder>Tasks: ${items.join(" | ")}${focusLine}${warning}</system-reminder>`;
 }

package/dist/runtime/session-messages.d.ts

@@ -30,6 +30,7 @@ export declare class SessionMessages {
     add(msg: SessionMessage): void;
     toLLM(): LLMMessage[];
     export(): SessionMessage[];
+    lastAssistantText(): string;
     import(messages: SessionMessage[]): void;
     normalizeInterruptedToolCalls(): void;
     clear(): void;

package/dist/runtime/session-messages.js

@@ -86,6 +86,9 @@ export class SessionMessages {
     export() {
         return this.messages.slice();
     }
+    lastAssistantText() {
+        return lastAssistantText(this.messages);
+    }
     import(messages) {
         this.resetMessages(messages.slice(), messages.reduce((sum, m) => sum + estimateTokens(messageText(m)), 0));
         this.normalizeInterruptedToolCalls();

package/dist/runtime/session.js

@@ -211,6 +211,7 @@ export class Session {
                     maxTurns: deps.maxTurns ?? DEFAULT_MAX_TURNS,
                     stallThreshold: deps.stallThreshold ?? DEFAULT_STALL_THRESHOLD,
                     contextLimit: deps.contextLimit,
+                    onUsage: (cacheInputTokens, missInputTokens, outputTokens) => this.agent.addUsage(cacheInputTokens, missInputTokens, outputTokens),
                 })(systemPrompt, task, signal),
             },
         });

package/dist/runtime/sub-agent-runner.d.ts

@@ -9,6 +9,7 @@ export interface SubAgentRunOptions {
     maxTurns: number;
     stallThreshold: number;
     contextLimit: number;
+    onUsage?: (cacheInputTokens: number, missInputTokens: number, outputTokens: number) => void;
 }
 export interface SubAgentRunResult {
     status: RunStatus;

package/dist/runtime/sub-agent-runner.js

@@ -1,10 +1,10 @@
-import { SessionMessages, lastAssistantText } from "./session-messages.js";
+import { SessionMessages } from "./session-messages.js";
 import { Agent } from "./agent.js";
-import { TOOL_USE_PROMPT } from "./prompts.js";
+import { renderToolUsePrompt } from "./prompts.js";
 import { ToolRegistry } from "../tools/registry.js";
 export function createSubAgentRunner(opts) {
     return async (systemPrompt, task, signal) => {
-        const conversation = new SessionMessages([systemPrompt, TOOL_USE_PROMPT, `- Turn budget: ${opts.maxTurns} tool-calling turns per run.`].join("\n\n"));
+        const conversation = new SessionMessages([systemPrompt, renderToolUsePrompt(opts.maxTurns)].join("\n\n"));
         const subTools = new ToolRegistry();
         subTools.registerAll(opts.tools.filter((t) => t.readOnly === true));
         const subAgent = new Agent({
@@ -19,8 +19,9 @@ export function createSubAgentRunner(opts) {
             contextLimit: opts.contextLimit,
         });
         const status = await subAgent.run(task, undefined, signal);
-        const messages = conversation.export();
-        const reply = lastAssistantText(messages) || `(sub-agent produced no final text; status ${status})`;
+        opts.onUsage?.(subAgent.usage.cacheInputTokens, subAgent.usage.missInputTokens, subAgent.usage.outputTokens);
+        const reply = conversation.lastAssistantText() || `(sub-agent produced no final text; status ${status})`;
+        const messages = status !== "ok" ? conversation.export() : [];
         return { status, reply, messages };
     };
 }

package/dist/tools/sub-agent.js

@@ -69,11 +69,16 @@ export function createSubAgentTool(deps) {
             const { status, reply, messages } = await deps.runSubAgent(def.systemPrompt, task, ctx.signal);
             if (status === "ok")
                 return { content: reply };
-            const stallReason = status === "stalled"
-                ? [...messages].reverse()
-                    .map((m) => m.content)
-                    .find((c) => typeof c === "string" && c.startsWith(NOT_EXECUTED_PREFIX))
-                : undefined;
+            let stallReason;
+            if (status === "stalled") {
+                for (let i = messages.length - 1; i >= 0; i--) {
+                    const content = messages[i].content;
+                    if (typeof content === "string" && content.startsWith(NOT_EXECUTED_PREFIX)) {
+                        stallReason = content;
+                        break;
+                    }
+                }
+            }
             const suffix = stallReason ? ` ${stallReason}` : "";
             return { content: `Sub-agent "${type}" ended with status ${status}.${suffix}\n\n${reply}`, isError: true };
         },

package/dist/tools/todo-write.d.ts

@@ -1,3 +1,3 @@
 import type { Tool, Todo } from "./types.js";
-export declare const TODO_WRITE_GUIDANCE = "- For multi-step tasks (3+ steps), you MUST use TodoWrite: create the task list first, then update each task's status as you execute. Never execute a multi-step task without a TodoWrite task list.";
+export declare const TODO_WRITE_GUIDANCE = "- For multi-step tasks (5+ steps), you MUST use TodoWrite: create the task list first, then update statuses as tasks complete. Never execute a 5+ step task without a TodoWrite task list.";
 export declare function createTodoWriteTool(setTodos: (todos: Todo[]) => void): Tool;

package/dist/tools/todo-write.js

@@ -1,7 +1,7 @@
 import { toolError } from "./types.js";
-export const TODO_WRITE_GUIDANCE = "- For multi-step tasks (3+ steps), you MUST use TodoWrite: create the task list first, then update each task's status as you execute. Never execute a multi-step task without a TodoWrite task list.";
+export const TODO_WRITE_GUIDANCE = "- For multi-step tasks (5+ steps), you MUST use TodoWrite: create the task list first, then update statuses as tasks complete. Never execute a 5+ step task without a TodoWrite task list.";
 const STATUSES = ["pending", "inProgress", "completed"];
-const DESCRIPTION = "Manage the task list for tasks with 3+ steps. Pass the FULL list each call; it replaces the previous list. Keep one inProgress at a time. status: pending, inProgress, completed.";
+const DESCRIPTION = "Manage the task list for tasks with 5+ steps. Pass the FULL list each call; it replaces the previous list. Keep one inProgress at a time. status: pending, inProgress, completed.";
 function parseTodos(args) {
     const raw = args.todos;
     if (!Array.isArray(raw)) {
@@ -32,6 +32,13 @@ function parseTodos(args) {
         }
         todos.push({ content, status });
     }
+    if (!seenInProgress) {
+        const firstPending = todos.find((t) => t.status === "pending");
+        if (firstPending) {
+            firstPending.status = "inProgress";
+            normalized++;
+        }
+    }
     return { todos, done, normalized };
 }
 export function createTodoWriteTool(setTodos) {

package/dist/util/net.js

@@ -1,4 +1,4 @@
-import { ProxyAgent } from "undici";
+import { fetch, ProxyAgent } from "undici";
 let proxyAgent;
 let noProxyList;
 let proxyInitialized = false;
@@ -11,11 +11,12 @@ function ensureProxy() {
     proxyAgent = proxyUrl ? new ProxyAgent(proxyUrl) : null;
     noProxyList = noProxy?.split(",").map((s) => s.trim()).filter(Boolean);
 }
+const undiciFetch = fetch;
 export async function netFetch(input, init) {
     if (!proxyInitialized)
         ensureProxy();
     if (!proxyAgent)
-        return fetch(input, init);
+        return undiciFetch(input, init);
     const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
     if (noProxyList) {
         const hostname = new URL(url).hostname;
@@ -25,7 +26,7 @@ export async function netFetch(input, init) {
             return hostname === p || hostname.endsWith("." + p);
         });
         if (shouldBypass)
-            return fetch(input, init);
+            return undiciFetch(input, init);
     }
-    return fetch(input, { ...init, dispatcher: proxyAgent });
+    return undiciFetch(input, { ...init, dispatcher: proxyAgent });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vietor/agent-core",
-  "version": "0.7.3",
+  "version": "0.7.5",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",