@anhlp/alp-runtime 0.0.0-beta.1 → 0.0.0-beta.2

package/dist/session-state.d.ts

@@ -4,6 +4,7 @@ import type { MailEvent } from './mailbox.js';
 import type { Worktree, WorktreeChange, Copy } from './workspace.js';
 import type { Verification } from '@anhlp/alp-core/verify';
 import type { Handoff } from './handoff.js';
+import type { SessionUsage } from './events.js';
 export type Session = {
     runtimeKind: RuntimeKind;
     runtime: RuntimeTransport;
@@ -49,6 +50,8 @@ export type Session = {
     progressAt?: number;
     /** A digest of the instructions the session runs with. */
     instructionsSha?: string;
+    /** The latest usage its runtime reported, shown in viewers' context meters (ALPD §57). */
+    usage?: SessionUsage;
     /** The context advisory was given since the context last emptied (ALPD §57). */
     contextLevel?: number;
     /** An assignment's brief as its requester gave it, repeated after a compaction. */

package/dist/tool-detail.d.ts

@@ -0,0 +1,81 @@
+import type { ToolCallDetail } from '@anhlp/alp-protocol/events';
+/**
+ * Typed tool-call details (ALPD §4.2): what each runtime reports of a tool call, as the
+ * provider-neutral shapes of Paseo's ToolCallDetail. Pure functions; a transport attaches the
+ * detail to the commandExecution it reports as before, and the runtime emits it.
+ *
+ * A function returns undefined for a call that stays `shell` as today (Claude's Bash, ACP's
+ * execute). A tool ALP cannot type gets `unknown` with its raw input and output.
+ */
+export type { ToolCallDetail };
+/** The bounds of a typed detail (not shell, not unknown), as the protocol states them. */
+export declare const DETAIL_TEXT_CHARS = 65536;
+export declare const DETAIL_FILE_PATHS = 200;
+export declare const DETAIL_WEB_RESULTS = 50;
+export declare const ERROR_CHARS = 2000;
+export declare const TOOL_FAILED = "Tool call failed";
+/** The detail types of protocol v1; any other is a later one. */
+export declare const DETAIL_TYPES: readonly ["shell", "read", "edit", "write", "search", "fetch", "sub_agent", "plan", "plain_text", "unknown"];
+/** Text kept to `max` characters: its head, then how much was left out. */
+export declare function clipText(text: string, max?: number): string;
+/** A typed detail within the protocol's bounds; shell and unknown details pass unchanged. */
+export declare function boundDetail(detail: ToolCallDetail): ToolCallDetail;
+/** The error a failed call carries: the tool's own text, clipped, else a fixed one. */
+export declare function toolError(text: unknown): string;
+/** The text of a tool result: a string, or the text blocks of a content array. */
+export declare function resultText(content: unknown): string | undefined;
+/**
+ * Claude's Read output is `cat -n` style (`   12\tcode` or `   12→code`); this is the raw text
+ * and the first line's number, or undefined unless every non-empty line carries the gutter with
+ * consecutive numbers. A reminder Claude appends after the content is dropped first.
+ */
+export declare function stripReadGutter(text: string): {
+    content: string;
+    startLine: number;
+} | undefined;
+/** What Claude's result for a call holds: the tool_result text and the SDK's structured output. */
+export type ClaudeResult = {
+    text?: string;
+    structured?: unknown;
+    error?: boolean;
+};
+/**
+ * The detail of a Claude Code tool call, from its name and input and, once done, its result.
+ * Undefined for Bash, which stays a shell command.
+ */
+export declare function claudeToolDetail(name: string, rawInput: unknown, result?: ClaudeResult): ToolCallDetail | undefined;
+/** What ALP holds of an ACP tool call, merged from its tool_call and tool_call_update notifications. */
+export type AcpCall = {
+    kind?: string;
+    title?: string;
+    rawInput?: unknown;
+    rawOutput?: unknown;
+    locations?: unknown;
+    content?: unknown;
+};
+/** The text parts of an ACP tool call's content. */
+export declare function acpText(content: unknown): string | undefined;
+/**
+ * The detail of an ACP tool call by its kind (read, edit, delete, move, search, fetch, think,
+ * other): its rawInput, rawOutput, locations and content, including diffs. Undefined for execute,
+ * which stays a shell command.
+ */
+export declare function acpToolDetail(call: AcpCall): ToolCallDetail | undefined;
+/**
+ * The detail of an Antigravity tool step from its tool_info (name, parameters, output, error):
+ * run_command is a shell command, view_file a read, write_to_file a write, the replace tools
+ * edits; any other is unknown.
+ */
+export declare function antigravityToolDetail(info: unknown): ToolCallDetail;
+/** A Codex native item ALP shows as a tool call. */
+export type CodexToolCall = {
+    name: string;
+    status: 'running' | 'completed' | 'failed';
+    detail: ToolCallDetail;
+    error?: string;
+};
+/**
+ * Codex's native fileChange, webSearch, mcpToolCall and collabAgentToolCall items as tool calls,
+ * `done` when Codex reported the item completed; undefined for any other item.
+ */
+export declare function codexToolCall(item: any, done: boolean): CodexToolCall | undefined;

package/dist/tool-detail.js

@@ -0,0 +1,329 @@
+// packages/runtime/src/tool-detail.ts
+var DETAIL_TEXT_CHARS = 65536;
+var DETAIL_FILE_PATHS = 200;
+var DETAIL_WEB_RESULTS = 50;
+var ERROR_CHARS = 2e3;
+var TOOL_FAILED = "Tool call failed";
+var DETAIL_TYPES = ["shell", "read", "edit", "write", "search", "fetch", "sub_agent", "plan", "plain_text", "unknown"];
+function clipText(text, max = DETAIL_TEXT_CHARS) {
+  if (text.length <= max) return text;
+  const marker = /\n… \(\d+ more characters\)$/.exec(text);
+  if (marker && marker.index <= max) return text;
+  const end = /[\uD800-\uDBFF]/.test(text[max - 1] ?? "") ? max - 1 : max;
+  return `${text.slice(0, end)}
+\u2026 (${text.length - end} more characters)`;
+}
+function boundDetail(detail) {
+  if (detail.type === "shell" || detail.type === "unknown") return detail;
+  const bounded = {};
+  let cut = false;
+  for (const [key, value] of Object.entries(detail)) {
+    if (value === void 0) continue;
+    if (typeof value === "string") bounded[key] = key === "type" ? value : clipText(value);
+    else if (key === "filePaths" && Array.isArray(value)) {
+      bounded[key] = value.slice(0, DETAIL_FILE_PATHS).map((entry) => clipText(String(entry)));
+      cut = value.length > DETAIL_FILE_PATHS;
+    } else if (key === "webResults" && Array.isArray(value)) {
+      bounded[key] = value.slice(0, DETAIL_WEB_RESULTS).map((entry) => ({ title: clipText(entry.title), url: clipText(entry.url) }));
+    } else bounded[key] = value;
+  }
+  if (cut) bounded.truncated = true;
+  return bounded;
+}
+function toolError(text) {
+  const value = typeof text === "string" ? text.trim().replace(/^<tool_use_error>([\s\S]*)<\/tool_use_error>$/, "$1").trim() : "";
+  return value ? clipText(value, ERROR_CHARS) : TOOL_FAILED;
+}
+var str = (value) => typeof value === "string" && value.trim() ? value : void 0;
+var int = (value) => typeof value === "number" && Number.isInteger(value) ? value : void 0;
+var record = (value) => value && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+var pathOf = (input) => str(input?.file_path) ?? str(input?.filePath) ?? str(input?.path) ?? str(input?.notebook_path) ?? str(input?.AbsolutePath) ?? str(input?.TargetFile);
+var defined = (value) => Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== void 0));
+var typed = (detail) => boundDetail(defined(detail));
+function resultText(content) {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    const parts = content.map((part) => typeof part === "string" ? part : typeof part?.text === "string" ? part.text : "").filter(Boolean);
+    return parts.length ? parts.join("\n") : void 0;
+  }
+  return void 0;
+}
+var READ_GUTTER = /^\s*(\d+)(?:\t|→)(.*)$/;
+function stripReadGutter(text) {
+  const body = text.replace(/\r\n/g, "\n").replace(/\n*<system-reminder>[\s\S]*?<\/system-reminder>\s*$/g, "");
+  const out = [];
+  let start;
+  let previous;
+  for (const line of body.split("\n")) {
+    if (!line) {
+      out.push(line);
+      continue;
+    }
+    const match = READ_GUTTER.exec(line);
+    if (!match) return void 0;
+    const number = Number.parseInt(match[1], 10);
+    if (previous !== void 0 && number !== previous + 1) return void 0;
+    start ??= number;
+    previous = number;
+    out.push(match[2]);
+  }
+  return start === void 0 ? void 0 : { content: out.join("\n"), startLine: start };
+}
+function structuredPatch(patch) {
+  if (!Array.isArray(patch) || !patch.length) return void 0;
+  const hunks = patch.map((hunk) => {
+    const lines = Array.isArray(hunk?.lines) ? hunk.lines.map(String) : [];
+    return [`@@ -${hunk?.oldStart ?? 0},${hunk?.oldLines ?? 0} +${hunk?.newStart ?? 0},${hunk?.newLines ?? 0} @@`, ...lines].join("\n");
+  });
+  return `${hunks.join("\n")}
+`;
+}
+function replacementsDiff(edits) {
+  const side = (text, mark) => String(text ?? "").split("\n").map((line) => `${mark}${line}`);
+  return `${edits.map((edit) => ["@@", ...side(edit.old_string, "-"), ...side(edit.new_string, "+")].join("\n")).join("\n")}
+`;
+}
+var TODO_MARK = { completed: "[x]", in_progress: "[~]", pending: "[ ]" };
+function claudeToolDetail(name, rawInput, result) {
+  if (name === "Bash") return void 0;
+  const input = record(rawInput) ?? {};
+  const ok = result && !result.error;
+  const text = ok ? result.text : void 0;
+  const out = ok ? record(result.structured) : void 0;
+  const unknown = () => ({ type: "unknown", input: rawInput ?? null, output: result?.text ?? null });
+  const filePath = pathOf(input);
+  switch (name) {
+    case "Read": {
+      if (!filePath) return unknown();
+      const file = out?.type === "text" ? record(out.file) : void 0;
+      const stripped = file ? void 0 : text !== void 0 ? stripReadGutter(text) : void 0;
+      const content = typeof file?.content === "string" ? file.content : stripped?.content ?? text;
+      return typed({ type: "read", filePath, content, offset: int(file?.startLine) ?? stripped?.startLine ?? int(input.offset), limit: int(input.limit) });
+    }
+    case "Write":
+      if (!filePath) return unknown();
+      return typed({ type: "write", filePath, content: typeof input.content === "string" ? input.content : void 0 });
+    case "Edit":
+      if (!filePath) return unknown();
+      return typed({ type: "edit", filePath, oldString: typeof input.old_string === "string" ? input.old_string : void 0, newString: typeof input.new_string === "string" ? input.new_string : void 0, unifiedDiff: structuredPatch(out?.structuredPatch) });
+    case "MultiEdit": {
+      if (!filePath) return unknown();
+      const edits = Array.isArray(input.edits) ? input.edits.filter(record) : [];
+      if (edits.length === 1) return typed({ type: "edit", filePath, oldString: str(edits[0].old_string) ?? void 0, newString: typeof edits[0].new_string === "string" ? edits[0].new_string : void 0, unifiedDiff: structuredPatch(out?.structuredPatch) });
+      return typed({ type: "edit", filePath, unifiedDiff: structuredPatch(out?.structuredPatch) ?? (edits.length ? replacementsDiff(edits) : void 0) });
+    }
+    case "NotebookEdit":
+      if (!filePath) return unknown();
+      return typed({ type: "edit", filePath, oldString: typeof out?.old_source === "string" ? out.old_source : void 0, newString: input.edit_mode === "delete" ? void 0 : typeof input.new_source === "string" ? input.new_source : void 0 });
+    case "Grep": {
+      const query = str(input.pattern);
+      if (!query) return unknown();
+      const structured = out && Array.isArray(out.filenames);
+      return typed({
+        type: "search",
+        query,
+        toolName: "grep",
+        content: structured ? typeof out.content === "string" ? out.content : void 0 : text,
+        filePaths: structured && out.filenames.length ? out.filenames.map(String) : void 0,
+        numFiles: structured ? int(out.numFiles) : void 0,
+        numMatches: structured ? int(out.numMatches) : void 0
+      });
+    }
+    case "Glob": {
+      const query = str(input.pattern);
+      if (!query) return unknown();
+      const structured = out && Array.isArray(out.filenames);
+      return typed({
+        type: "search",
+        query,
+        toolName: "glob",
+        content: structured ? void 0 : text,
+        filePaths: structured && out.filenames.length ? out.filenames.map(String) : void 0,
+        numFiles: structured ? int(out.numFiles) : void 0,
+        truncated: structured && typeof out.truncated === "boolean" ? out.truncated : void 0
+      });
+    }
+    case "WebFetch": {
+      const url = str(input.url) ?? str(out?.url);
+      if (!url) return unknown();
+      return typed({ type: "fetch", url, prompt: str(input.prompt), result: typeof out?.result === "string" ? out.result : text, code: int(out?.code) });
+    }
+    case "WebSearch": {
+      const query = str(input.query) ?? str(out?.query);
+      if (!query) return unknown();
+      const entries = Array.isArray(out?.results) ? out.results : [];
+      const webResults = entries.flatMap((entry) => Array.isArray(record(entry)?.content) ? entry.content : []).filter((hit) => typeof hit?.title === "string" && typeof hit?.url === "string").map((hit) => ({ title: hit.title, url: hit.url }));
+      const notes = entries.filter((entry) => typeof entry === "string");
+      return typed({ type: "search", query, toolName: "web_search", webResults: webResults.length ? webResults : void 0, content: out ? notes.length ? notes.join("\n") : void 0 : text });
+    }
+    case "Task":
+    case "Agent": {
+      const report = out && Array.isArray(out.content) ? resultText(out.content) : text;
+      return typed({ type: "sub_agent", subAgentType: str(input.subagent_type), description: str(input.description) ?? str(input.prompt), log: report });
+    }
+    case "ExitPlanMode":
+      return str(input.plan) ? typed({ type: "plan", text: input.plan }) : unknown();
+    case "Skill":
+      return str(input.skill) ? typed({ type: "plain_text", label: input.skill, text }) : unknown();
+    case "TodoWrite": {
+      const todos = Array.isArray(input.todos) ? input.todos.filter(record) : [];
+      if (!todos.length) return unknown();
+      return typed({ type: "plain_text", label: "Todos", text: todos.map((todo) => `${TODO_MARK[todo.status] ?? "[ ]"} ${String(todo.content ?? todo.activeForm ?? "")}`).join("\n") });
+    }
+    default:
+      return unknown();
+  }
+}
+function acpText(content) {
+  const parts = (Array.isArray(content) ? content : []).map((part) => part?.type === "content" && part.content?.type === "text" ? part.content.text : "").filter(Boolean);
+  return parts.length ? parts.join("\n") : void 0;
+}
+function acpToolDetail(call) {
+  const kind = call.kind ?? "other";
+  if (kind === "execute") return void 0;
+  const input = record(call.rawInput);
+  const output = record(call.rawOutput);
+  const locations = (Array.isArray(call.locations) ? call.locations : []).map(record).filter((entry) => Boolean(str(entry?.path)));
+  const diffs = (Array.isArray(call.content) ? call.content : []).map(record).filter((part) => part?.type === "diff" && Boolean(str(part.path)));
+  const text = acpText(call.content) ?? (typeof call.rawOutput === "string" ? call.rawOutput : str(output?.output) ?? str(output?.content));
+  const title = str(call.title);
+  const filePath = locations[0]?.path ?? pathOf(input);
+  const unknown = () => ({ type: "unknown", input: call.rawInput ?? null, output: call.rawOutput ?? text ?? null });
+  switch (kind) {
+    case "read":
+      if (!filePath) return unknown();
+      return typed({ type: "read", filePath, content: text, offset: int(input?.offset) ?? int(input?.line) ?? int(locations[0]?.line), limit: int(input?.limit) });
+    case "edit":
+    case "delete": {
+      const diff = diffs[0];
+      if (diff) {
+        const oldText = typeof diff.oldText === "string" ? diff.oldText : void 0;
+        const newText = typeof diff.newText === "string" ? diff.newText : void 0;
+        if (oldText === void 0 && newText !== void 0 && kind === "edit") return typed({ type: "write", filePath: diff.path, content: newText });
+        return typed({ type: "edit", filePath: diff.path, oldString: oldText, newString: kind === "delete" ? void 0 : newText });
+      }
+      if (!filePath) return unknown();
+      const oldString = str(input?.old_string) ?? str(input?.oldText) ?? str(input?.old_str);
+      const newString = str(input?.new_string) ?? str(input?.newText) ?? str(input?.new_str);
+      const unifiedDiff = str(input?.diff) ?? str(input?.patch) ?? str(input?.unified_diff);
+      if (kind === "edit" && !oldString && !unifiedDiff && typeof input?.content === "string") return typed({ type: "write", filePath, content: input.content });
+      return typed({ type: "edit", filePath, oldString, newString, unifiedDiff });
+    }
+    case "move": {
+      const from = filePath ?? str(input?.from) ?? str(input?.source);
+      const to = locations[1]?.path ?? str(input?.to) ?? str(input?.destination) ?? str(input?.new_path);
+      if (!from) return unknown();
+      return typed({ type: "plain_text", label: title ?? "Move", text: to ? `${from} \u2192 ${to}` : from });
+    }
+    case "search": {
+      const query = str(input?.query) ?? str(input?.pattern) ?? str(input?.q) ?? title;
+      if (!query) return unknown();
+      const paths = locations.map((entry) => entry.path);
+      return typed({ type: "search", query, toolName: "search", content: text, filePaths: paths.length ? paths : void 0 });
+    }
+    case "fetch": {
+      const url = str(input?.url);
+      if (url) return typed({ type: "fetch", url, prompt: str(input?.prompt), result: text });
+      const query = str(input?.query) ?? str(input?.q);
+      if (query) return typed({ type: "search", query, toolName: "web_search", content: text });
+      return unknown();
+    }
+    case "think":
+      return typed({ type: "plain_text", label: title ?? "Thinking", text: text ?? str(input?.thought) ?? str(input?.text) });
+    default:
+      return unknown();
+  }
+}
+function antigravityToolDetail(info) {
+  const tool = record(info);
+  const parameters = record(tool?.parameters) ?? {};
+  const output = typeof tool?.output === "string" && tool.output ? tool.output : void 0;
+  const filePath = str(parameters.AbsolutePath) ?? str(parameters.TargetFile);
+  switch (tool?.name) {
+    case "run_command":
+      if (typeof parameters.CommandLine === "string") return { type: "shell", command: parameters.CommandLine, ...str(parameters.Cwd) ? { cwd: parameters.Cwd } : {}, output: output ?? "" };
+      break;
+    case "view_file":
+      if (filePath) return typed({ type: "read", filePath, content: output, offset: int(parameters.StartLine), limit: int(parameters.EndLine) !== void 0 && int(parameters.StartLine) !== void 0 ? parameters.EndLine - parameters.StartLine + 1 : void 0 });
+      break;
+    case "write_to_file":
+      if (filePath) return typed({ type: "write", filePath, content: typeof parameters.CodeContent === "string" ? parameters.CodeContent : void 0 });
+      break;
+    case "replace_file_content":
+    case "multi_replace_file_content":
+      if (filePath) return typed({ type: "edit", filePath, oldString: typeof parameters.TargetContent === "string" ? parameters.TargetContent : void 0, newString: typeof parameters.ReplacementContent === "string" ? parameters.ReplacementContent : void 0 });
+      break;
+  }
+  return { type: "unknown", input: tool?.parameters ?? null, output: tool?.error?.message ?? output ?? null };
+}
+function withHeaders(path, diff) {
+  return /^(--- |diff --git )/.test(diff) ? diff : `--- a/${path}
++++ b/${path}
+${diff}`;
+}
+var looksLikeDiff = (text) => /^(@@ |--- |\+\+\+ |diff --git )/.test(text);
+function changeDiff(kind, diff) {
+  if (kind !== "add" && kind !== "delete" || !diff || looksLikeDiff(diff)) return diff;
+  const lines = diff.replace(/\r\n?/g, "\n").replace(/\n$/, "").split("\n");
+  const n = lines.length;
+  return kind === "add" ? `@@ -0,0 +1,${n} @@
+${lines.map((line) => `+${line}`).join("\n")}
+` : `@@ -1,${n} +0,0 @@
+${lines.map((line) => `-${line}`).join("\n")}
+`;
+}
+function codexToolCall(item, done) {
+  const raw = String(item?.status ?? "");
+  const status = raw === "inProgress" || !raw && !done ? "running" : raw === "failed" || raw === "declined" ? "failed" : "completed";
+  const failed = (error) => status === "failed" ? { error: toolError(error) } : {};
+  if (item?.type === "fileChange") {
+    const changes = (Array.isArray(item.changes) ? item.changes : []).filter((change) => str(change?.path));
+    if (!changes.length) return { name: "apply_patch", status, detail: { type: "unknown", input: item.changes ?? null, output: null }, ...failed() };
+    let detail;
+    if (changes.length === 1) {
+      const [change] = changes;
+      const diff = typeof change.diff === "string" ? change.diff : "";
+      const kind = change.kind?.type ?? change.kind;
+      detail = kind === "add" && !looksLikeDiff(diff) ? typed({ type: "write", filePath: change.path, content: diff || void 0 }) : typed({ type: "edit", filePath: change.path, unifiedDiff: changeDiff(kind, diff) || void 0 });
+    } else {
+      const diff = changes.map((change) => {
+        const text = typeof change.diff === "string" ? changeDiff(change.kind?.type ?? change.kind, change.diff) : "";
+        return text ? withHeaders(change.path, text.endsWith("\n") ? text : `${text}
+`) : `--- a/${change.path}
++++ b/${change.path}
+`;
+      }).join("");
+      detail = typed({ type: "edit", filePath: changes[0].path, unifiedDiff: diff });
+    }
+    return { name: "apply_patch", status, detail, ...failed() };
+  }
+  if (item?.type === "webSearch") {
+    const query = str(item.query) ?? str(item.action?.query) ?? (Array.isArray(item.action?.queries) ? str(item.action.queries[0]) : void 0) ?? "";
+    return { name: "web_search", status, detail: typed({ type: "search", query, toolName: "web_search" }), ...failed() };
+  }
+  if (item?.type === "mcpToolCall") {
+    return { name: `mcp__${String(item.server ?? "")}__${String(item.tool ?? "")}`, status, detail: { type: "unknown", input: item.arguments ?? null, output: item.result ?? null }, ...failed(item.error?.message) };
+  }
+  if (item?.type === "collabAgentToolCall") {
+    return { name: "Sub-agent", status, detail: typed({ type: "sub_agent", subAgentType: "Sub-agent", description: str(item.prompt) }), ...failed(item.error?.message) };
+  }
+  return void 0;
+}
+export {
+  DETAIL_FILE_PATHS,
+  DETAIL_TEXT_CHARS,
+  DETAIL_TYPES,
+  DETAIL_WEB_RESULTS,
+  ERROR_CHARS,
+  TOOL_FAILED,
+  acpText,
+  acpToolDetail,
+  antigravityToolDetail,
+  boundDetail,
+  claudeToolDetail,
+  clipText,
+  codexToolCall,
+  resultText,
+  stripReadGutter,
+  toolError
+};

package/dist/usage.d.ts

@@ -1,3 +1,4 @@
+import type { SessionUsage } from './events.js';
 /** Account-free usage data shown in ALP's viewers. */
 export type UsageWindow = {
     name: string;
@@ -13,3 +14,12 @@ export type ProviderUsage = {
     windows: UsageWindow[];
 };
 export declare function providerUsage(runtime: ProviderUsage['runtime'], usage: any, checkedAt?: string): ProviderUsage;
+/**
+ * A session's usage after one token report (ALPD §57), as Paseo's AgentUsage. Every transport
+ * reports as Codex's thread/tokenUsage/updated does: `last` the latest model call, of which
+ * `totalTokens` is what the context holds now; `modelContextWindow` the window once known;
+ * `totalCostUsd` the session's cost where the runtime counts it. The fields a report carries
+ * replace the session's; the others are kept, except that the latest response's input, cached and
+ * output counts are replaced together. Undefined when the report changes nothing.
+ */
+export declare function sessionUsage(previous: SessionUsage | undefined, report: any): SessionUsage | undefined;

package/dist/usage.js

@@ -30,6 +30,31 @@ function providerUsage(runtime, usage, checkedAt = (/* @__PURE__ */ new Date()).
     windows
   };
 }
+var tokens = (value, least = 0) => typeof value === "number" && Number.isInteger(value) && value >= least ? value : void 0;
+function sessionUsage(previous, report) {
+  if (!report || typeof report !== "object") return void 0;
+  const last = report.last && typeof report.last === "object" ? report.last : {};
+  const cost = report.totalCostUsd;
+  const fields = {
+    contextWindowUsedTokens: tokens(last.totalTokens),
+    contextWindowMaxTokens: tokens(report.modelContextWindow, 1),
+    inputTokens: tokens(last.inputTokens),
+    cachedInputTokens: tokens(last.cachedInputTokens ?? report.cachedInputTokens),
+    outputTokens: tokens(last.outputTokens),
+    totalCostUsd: typeof cost === "number" && Number.isFinite(cost) && cost >= 0 ? cost : void 0
+  };
+  const next = { ...previous };
+  if (fields.inputTokens !== void 0 || fields.cachedInputTokens !== void 0 || fields.outputTokens !== void 0) {
+    delete next.inputTokens;
+    delete next.cachedInputTokens;
+    delete next.outputTokens;
+  }
+  for (const [key, value] of Object.entries(fields)) if (value !== void 0) next[key] = value;
+  const keys = Object.keys(next);
+  if (keys.length === Object.keys(previous ?? {}).length && keys.every((key) => previous?.[key] === next[key])) return void 0;
+  return next;
+}
 export {
-  providerUsage
+  providerUsage,
+  sessionUsage
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anhlp/alp-runtime",
-  "version": "0.0.0-beta.1",
+  "version": "0.0.0-beta.2",
   "type": "module",
   "description": "ALP runtime module",
   "files": [
@@ -222,8 +222,8 @@
     "node": ">=22.12"
   },
   "dependencies": {
-    "@anhlp/alp-core": "0.0.0-beta.1",
-    "@anhlp/alp-protocol": "0.0.0-beta.1",
+    "@anhlp/alp-core": "0.0.0-beta.2",
+    "@anhlp/alp-protocol": "0.0.0-beta.2",
     "@anthropic-ai/claude-agent-sdk": "^0.3.292",
     "@modelcontextprotocol/sdk": "^1.32.1",
     "@agentclientprotocol/sdk": "1.7.0",

package/src/acp-transport.ts

@@ -8,6 +8,7 @@ import path from 'node:path';
 import { createInterface } from 'node:readline';
 import { commandDecision, unwrapShell, type PermissionProfile } from '@anhlp/alp-core/permissions';
 import { launchCommand } from '@anhlp/alp-core/providers';
+import { acpText, acpToolDetail, type AcpCall } from './tool-detail.js';
 
 /**
  * ACP agents (ALPD §46): a generic transport for any agent that speaks the Agent Client
@@ -146,6 +147,13 @@ function acpServers(servers: Record<string, any>, http: boolean) {
 }
 
 /** Maps an ACP agent over stdio to the normalized runtime protocol. */
+/** One turn-input part as ACP's: text, or a data-URL image as an ACP image block; anything else is dropped. */
+export function acpContent(part: any) {
+  if (typeof part?.text === 'string') return { type: 'text', text: part.text };
+  const image = part?.type === 'image' && typeof part.url === 'string' ? /^data:(image\/(?:png|jpeg|gif|webp));base64,([A-Za-z0-9+/]+={0,2})$/.exec(part.url) : null;
+  return image ? { type: 'image', mimeType: image[1], data: image[2] } : null;
+}
+
 export class AcpTransport {
   private child?: ChildProcessWithoutNullStreams;
   private exit: Promise<void> = Promise.resolve();
@@ -156,6 +164,8 @@ export class AcpTransport {
   private requestHandler?: RequestHandler;
   private closed = false;
   private capabilities: any = {};
+  /** ACP agents say in initialize whether a prompt may hold images (promptCapabilities.image). */
+  takesImages() { return this.capabilities?.promptCapabilities?.image === true; }
   private sessionId = '';
   private config: any;
   /** Instructions go with the first prompt of a new session; a loaded one has them already. */
@@ -167,7 +177,7 @@ export class AcpTransport {
   /** Text of the running turn's current message; a tool call starts the next one. */
   private message?: { id: string; text: string };
   private messages = 0;
-  private toolCalls = new Map<string, { command: string; alp: boolean }>();
+  private toolCalls = new Map<string, { command: string; alp: boolean; state: AcpCall; done?: boolean }>();
   /** Permission questions of the running turn, answered cancelled when it is cancelled. */
   private questions = new Set<(value: unknown) => void>();
   private bridge?: { server: net.Server; socket: string; token: string; connections: Set<net.Socket> };
@@ -230,13 +240,14 @@ export class AcpTransport {
       const turnId = randomUUID();
       this.activeTurn = turnId;
       this.message = undefined;
-      const prompt = (params.input ?? []).filter((part: any) => typeof part?.text === 'string').map((part: any) => ({ type: 'text', text: part.text }));
+      const prompt = (params.input ?? []).map(acpContent).filter(Boolean) as Array<Record<string, unknown>>;
+      if (prompt.some(part => part.type === 'image') && !this.takesImages()) throw new Error(`${this.provider.label} takes no images`);
       if (!this.instructionsSent && this.config?.developerInstructions) {
         prompt.unshift({ type: 'text', text: `Instructions from ALP, which runs you. Follow them for this whole session.\n\n${this.config.developerInstructions}` });
         this.instructionsSent = true;
       }
       this.prompting = this.call('session/prompt', { sessionId: this.sessionId, prompt }).then(
-        result => this.endTurn(turnId, result?.stopReason),
+        result => { this.turnUsage(turnId, result?.usage); this.endTurn(turnId, result?.stopReason); },
         error => this.endTurn(turnId, 'error', error instanceof Error ? error.message : String(error)),
       ).finally(() => { if (this.activeTurn === undefined || this.activeTurn === turnId) this.prompting = undefined; });
       return { turn: { id: turnId } };
@@ -272,6 +283,13 @@ export class AcpTransport {
     await this.call('session/set_model', { sessionId: this.sessionId, modelId: wanted }, 30_000);
   }
 
+  /** The tokens of the turn the prompt response says (ACP's unstable usage), before its end. */
+  private turnUsage(turnId: string, usage: any) {
+    if (this.closed || this.activeTurn !== turnId || !usage || typeof usage !== 'object') return;
+    const last = { inputTokens: usage.inputTokens, outputTokens: usage.outputTokens, cachedInputTokens: usage.cachedReadTokens };
+    this.emit('thread/tokenUsage/updated', { threadId: this.sessionId, turnId, tokenUsage: { last } });
+  }
+
   private endTurn(turnId: string, stopReason: string, error?: string) {
     if (this.closed || this.activeTurn !== turnId) return;
     this.closeMessage();
@@ -304,25 +322,42 @@ export class AcpTransport {
       const id = String(update.toolCallId ?? '');
       if (!id) return;
       let call = this.toolCalls.get(id);
+      const first = !call;
+      // A call reported done stays done: a late update must not reopen it or replace its detail.
+      if (call?.done) return;
       if (!call) {
         const request = acpPermission(update, this.tools.map(tool => tool.name));
-        call = { command: request.command ?? `${request.kind}: ${request.title}`, alp: request.alpTool };
+        call = { command: request.command ?? `${request.kind}: ${request.title}`, alp: request.alpTool, state: {} };
         this.toolCalls.set(id, call);
         this.closeMessage();
-        // ALP's own tools show as ALP tool calls; the agent's call to the bridge would repeat them.
-        if (!call.alp) this.emit('item/started', { threadId: this.sessionId, item: { type: 'commandExecution', id, command: call.command, cwd: this.cwd, status: 'inProgress', aggregatedOutput: '' } });
       }
-      if ((update.status === 'completed' || update.status === 'failed') && !call.alp) {
+      // An update carries only what changed; the call's detail is built from all of it.
+      for (const field of ['kind', 'title', 'rawInput', 'rawOutput', 'locations', 'content'] as const) if (update[field] !== undefined && update[field] !== null) call.state[field] = update[field];
+      if (call.alp) return;
+      // The command stays what skill use, copy escapes and the journal read; the typed detail rides along.
+      const detail = acpToolDetail(call.state);
+      const typed = detail ? { tool: call.state.title || call.state.kind || 'tool', detail } : {};
+      const done = update.status === 'completed' || update.status === 'failed';
+      // ALP's own tools show as ALP tool calls; the agent's call to the bridge would repeat them.
+      if (first) this.emit('item/started', { threadId: this.sessionId, item: { type: 'commandExecution', id, command: call.command, cwd: this.cwd, status: 'inProgress', aggregatedOutput: '', ...typed } });
+      else if (!done && detail) this.emit('item/updated', { threadId: this.sessionId, item: { type: 'commandExecution', id, command: call.command, cwd: this.cwd, status: 'inProgress', aggregatedOutput: '', ...typed } });
+      if (done) {
+        // What the call held is in its detail now; a long turn need not keep every result.
+        call.state = {};
+        call.done = true;
         const output = (Array.isArray(update.content) ? update.content : [])
           .map((part: any) => part?.type === 'content' && part.content?.type === 'text' ? part.content.text : part?.type === 'diff' ? `diff ${part.path}` : '')
           .filter(Boolean).join('\n');
-        this.emit('item/completed', { threadId: this.sessionId, item: { type: 'commandExecution', id, command: call.command, cwd: this.cwd, status: update.status, exitCode: update.status === 'failed' ? 1 : 0, aggregatedOutput: output } });
+        const error = update.status === 'failed' && detail ? { error: acpText(update.content) ?? (typeof update.rawOutput === 'string' ? update.rawOutput : undefined) } : {};
+        this.emit('item/completed', { threadId: this.sessionId, item: { type: 'commandExecution', id, command: call.command, cwd: this.cwd, status: update.status, exitCode: update.status === 'failed' ? 1 : 0, aggregatedOutput: output, ...typed, ...error } });
       }
       return;
     }
     if (kind === 'usage_update' && typeof update.used === 'number') {
       const last = { totalTokens: update.used };
-      this.emit('thread/tokenUsage/updated', { threadId: this.sessionId, turnId: this.activeTurn, tokenUsage: { last, total: last, ...(typeof update.size === 'number' ? { modelContextWindow: update.size } : {}) } });
+      // ACP's cost is the session's, in its currency; only US dollars are shown.
+      const cost = update.cost?.currency === 'USD' && typeof update.cost.amount === 'number' ? { totalCostUsd: update.cost.amount } : {};
+      this.emit('thread/tokenUsage/updated', { threadId: this.sessionId, turnId: this.activeTurn, tokenUsage: { last, total: last, ...(typeof update.size === 'number' ? { modelContextWindow: update.size } : {}), ...cost } });
     }
   }