@vietor/agent-core 0.7.4 → 0.7.6

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/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/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

@@ -19,6 +19,7 @@ export function createSubAgentRunner(opts) {
             contextLimit: opts.contextLimit,
         });
         const status = await subAgent.run(task, undefined, signal);
+        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/glob.js

@@ -1,6 +1,6 @@
 import { formatRipgrepOutput, ripgrepResultSummary, runRipgrepLines } from "../util/ripgrep.js";
 import { NO_MATCHES } from "../util/constants.js";
-import { resolveOptionalPath } from "../util/file.js";
+import { resolveSearchPath } from "../util/file.js";
 const DESCRIPTION = "List files under a directory, optionally filtered by a glob pattern (e.g. **/*.ts). Skips node_modules and .git.";
 export const globTool = {
     name: "Glob",
@@ -15,12 +15,12 @@ export const globTool = {
         required: [],
     },
     async execute(args, ctx) {
-        const cwd = resolveOptionalPath(args, ctx.cwd);
+        const { cwd, target } = resolveSearchPath(args, ctx.cwd);
         const rgArgs = ["--files"];
         const pattern = args.pattern;
         if (pattern)
             rgArgs.push("-g", pattern);
-        rgArgs.push(".");
+        rgArgs.push(target);
         const { lines, truncated } = await runRipgrepLines(rgArgs, cwd, ctx.signal);
         return { content: formatRipgrepOutput(lines, truncated, NO_MATCHES) };
     },

package/dist/tools/grep.js

@@ -1,6 +1,6 @@
 import { formatRipgrepOutput, ripgrepResultSummary, runRipgrepLines } from "../util/ripgrep.js";
 import { DEFAULT_GREP_LIMIT, NO_MATCHES } from "../util/constants.js";
-import { resolveOptionalPath } from "../util/file.js";
+import { resolveSearchPath } from "../util/file.js";
 const DESCRIPTION = `Search file contents recursively for a regex pattern (RE2 syntax). Skips node_modules and .git. Returns path:line:content, capped at ${DEFAULT_GREP_LIMIT} lines. For large codebases, use output_mode=files_with_matches first, or narrow with glob/type, or raise head_limit.`;
 export const grepTool = {
     name: "Grep",
@@ -10,7 +10,7 @@ export const grepTool = {
         type: "object",
         properties: {
             pattern: { type: "string" },
-            path: { type: "string", description: "root directory, defaults to cwd" },
+            path: { type: "string", description: "file or directory, defaults to cwd" },
             glob: { type: "string", description: "filter files, e.g. *.ts" },
             type: { type: "string", description: "file type, e.g. ts, js, py" },
             output_mode: { type: "string", enum: ["content", "files_with_matches", "count"], description: "defaults to content" },
@@ -25,7 +25,7 @@ export const grepTool = {
         required: ["pattern"],
     },
     async execute(args, ctx) {
-        const cwd = resolveOptionalPath(args, ctx.cwd);
+        const { cwd, target } = resolveSearchPath(args, ctx.cwd);
         const rgArgs = ["--line-number", "--with-filename", "--no-heading"];
         if (args.ignore_case)
             rgArgs.push("-i");
@@ -56,7 +56,7 @@ export const grepTool = {
             rgArgs.push("-c");
         else
             rgArgs.push("-m", String(headLimit));
-        rgArgs.push("--", args.pattern, ".");
+        rgArgs.push("--", args.pattern, target);
         const { lines, truncated } = await runRipgrepLines(rgArgs, cwd, ctx.signal, headLimit);
         return { content: formatRipgrepOutput(lines, truncated, NO_MATCHES) };
     },

package/dist/tools/sub-agent.js

@@ -1,5 +1,7 @@
 import { NOT_EXECUTED_PREFIX } from "../util/constants.js";
+import { summarizeText } from "../util/text.js";
 import { toolError } from "./types.js";
+const MAX_LABEL_LENGTH = 50;
 export const SUB_AGENT_GUIDANCE = '- Consider delegating to the SubAgent tool when the task matches an agent type, when you have independent work to run in parallel, or when answering would mean reading across several files — delegate and keep the conclusion, not the file dumps. type: "explore" — read-only search agent for broad fan-out searches (state the search breadth in the task); type: "plan" — software architect producing implementation plans. For a single-fact lookup where you already know the file, symbol, or value, search directly. Once you have delegated a search, do not also run it yourself — wait for the result. Issue at most 2 SubAgent calls per turn; multiple calls in the same turn run concurrently. Sub-agents are read-only and return only their final report, not intermediate steps — verify important results yourself. For large workloads with many independent items that would exceed the turn budget, split the items into chunks sized so each sub-agent can complete its chunk within its own loop budget, delegate one SubAgent per chunk, and run the remaining chunks in the following turns as results return. Instruct each sub-agent to report results per item in structured lines so you can consolidate.';
 const EXPLORE_PROMPT = [
     "You are the Explore sub-agent — a read-only search agent for broad fan-out searches. Use it when answering means sweeping many files, directories, or naming conventions and the parent needs only the conclusion, not the file dumps. You read excerpts rather than whole files, so you locate code — you do not review or audit it. You are read-only: you must not modify any files.",
@@ -51,11 +53,21 @@ export function createSubAgentTool(deps) {
                     enum: SUB_AGENT_DEFS.map((d) => d.type),
                     description: 'The sub-agent type to invoke: "explore" (read-only fan-out search) or "plan" (implementation plan).',
                 },
+                label: {
+                    type: "string",
+                    maxLength: MAX_LABEL_LENGTH,
+                    description: `Short label (max ${MAX_LABEL_LENGTH} characters) for this sub-agent run, shown in the UI.`,
+                },
                 task: { type: "string", description: "The task or question for the sub-agent, as a self-contained description." },
             },
             required: ["type", "task"],
         },
-        argSummaryKeys: ["type"],
+        summarizeArgs: (args) => {
+            const type = args.type;
+            const label = typeof args.label === "string" ? summarizeText(args.label, MAX_LABEL_LENGTH) : "";
+            const def = SUB_AGENT_DEFS.find((d) => d.type === type);
+            return (def?.name || type) + (label ? ` ${label}` : "");
+        },
         async execute(args, ctx) {
             const type = args.type;
             const task = (args.task ?? "").trim();
@@ -80,7 +92,7 @@ export function createSubAgentTool(deps) {
                 }
             }
             const suffix = stallReason ? ` ${stallReason}` : "";
-            return { content: `Sub-agent "${type}" ended with status ${status}.${suffix}\n\n${reply}`, isError: true };
+            return { content: `Sub-agent "${def.name}" ended with status ${status}.${suffix}\n\n${reply}`, isError: true };
         },
     };
 }

package/dist/util/async.js

@@ -11,7 +11,7 @@ export function isAbortError(e) {
     return name === "AbortError" || name === "APIUserAbortError";
 }
 export function backoffDelay(attempt) {
-    return 1000 * 2 ** attempt;
+    return Math.min(2000 * 2 ** attempt, 60_000);
 }
 export async function withRetry(fn, opts) {
     for (let attempt = 0;; attempt++) {

package/dist/util/file.d.ts

@@ -1,3 +1,6 @@
 export declare function tryReadFileText(path: string): string | undefined;
 export declare function resolveRequiredPath(args: Record<string, unknown>, cwd: string): string;
-export declare function resolveOptionalPath(args: Record<string, unknown>, cwd: string): string;
+export declare function resolveSearchPath(args: Record<string, unknown>, cwd: string): {
+    cwd: string;
+    target: string;
+};

package/dist/util/file.js

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, statSync } from "node:fs";
 import { resolve } from "node:path";
 export function tryReadFileText(path) {
     if (existsSync(path)) {
@@ -14,6 +14,10 @@ export function resolveRequiredPath(args, cwd) {
         throw new Error("path is required");
     return resolve(cwd, path);
 }
-export function resolveOptionalPath(args, cwd) {
-    return resolve(cwd, args.path || "");
+export function resolveSearchPath(args, cwd) {
+    const path = resolve(cwd, args.path || "");
+    if (existsSync(path) && !statSync(path).isDirectory()) {
+        return { cwd, target: path };
+    }
+    return { cwd: path, target: "." };
 }

package/package.json

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