@koalaauto/agentchannel 3.11.0 → 3.12.0

package/dist/src/trace.d.ts

@@ -0,0 +1,51 @@
+import type { AdapterEvent } from './adapters/types.js';
+export type StepKind = 'thinking' | 'text' | 'tool' | 'mark';
+export interface TraceStep {
+    /** Milliseconds since the run started. */
+    t: number;
+    kind: StepKind;
+    /** tool: the tool's name (Bash, Read, shell, ...); mark: what happened (task_completed, ...). */
+    name?: string;
+    /** tool: the command, the file, or the arguments, in a line or two. */
+    input?: string;
+    /** tool: how it ended. */
+    is_error?: boolean;
+    exit?: number;
+    /** tool: what it printed (cut); thinking / text: the words (cut). */
+    output?: string;
+    /** tool: how long it ran. */
+    ms?: number;
+}
+export interface Trace {
+    steps: TraceStep[];
+    /** Steps dropped from the middle of a long run. */
+    omitted: number;
+}
+/** Limits: each text field, the number of steps, and the whole trace as JSON. */
+export declare const FIELD_MAX = 2000;
+export declare const STEPS_MAX = 300;
+export declare const TRACE_BYTES_MAX = 150000;
+/** Cut to `max`, keeping the start and the end (where a command's error usually is). */
+export declare function cut(s: string, max?: number): string;
+/** The command or the file a tool call is about, in a line. */
+export declare function summarizeInput(name: string, input: unknown): string;
+export declare class TraceRecorder {
+    private exact;
+    private now;
+    private start;
+    private steps;
+    private omitted;
+    private open;
+    private marked;
+    private lastText;
+    /** `exact`: secrets this process holds (its key, the run token), masked wherever they appear. */
+    constructor(exact?: readonly string[], now?: () => number, start?: number);
+    private clean;
+    private add;
+    /** Feed one adapter event. Events it does not know are ignored. */
+    event(e: AdapterEvent): void;
+    /** Something happened around the run (the task was completed while the run went on). Once per name. */
+    mark(name: string): void;
+    /** The trace as it is now, within the size limit. */
+    finish(): Trace;
+}

package/dist/src/trace.js

@@ -0,0 +1,137 @@
+// The execution trace of one run: what the agent thought (the model's own summary), which commands and files it touched, how each
+// ended and what they printed, and how long each took. Built from the adapter's events, masked and cut down before anything
+// leaves this machine, and uploaded to the hub with the result so both sides of a task can audit it.
+import { isSecretFile, redact } from './redact.js';
+/** Limits: each text field, the number of steps, and the whole trace as JSON. */
+export const FIELD_MAX = 2000;
+export const STEPS_MAX = 300;
+export const TRACE_BYTES_MAX = 150_000;
+/** Cut to `max`, keeping the start and the end (where a command's error usually is). */
+export function cut(s, max = FIELD_MAX) {
+    if (s.length <= max)
+        return s;
+    const head = Math.floor(max * 0.7);
+    const tail = max - head;
+    return `${s.slice(0, head)}\n…[${s.length - max} characters omitted]…\n${s.slice(s.length - tail)}`;
+}
+const asText = (v) => {
+    if (typeof v === 'string')
+        return v;
+    if (v === undefined || v === null)
+        return '';
+    try {
+        return JSON.stringify(v);
+    }
+    catch {
+        return String(v);
+    }
+};
+/** The command or the file a tool call is about, in a line. */
+export function summarizeInput(name, input) {
+    const o = input && typeof input === 'object' ? input : {};
+    const pick = (...keys) => keys.map((k) => o[k]).find((v) => typeof v === 'string' && v);
+    if (typeof input === 'string')
+        return input;
+    const cmd = pick('command', 'cmd');
+    if (cmd)
+        return cmd;
+    const file = pick('file_path', 'path', 'notebook_path');
+    if (file)
+        return file + (typeof o.pattern === 'string' ? `  ${o.pattern}` : '');
+    const other = pick('pattern', 'query', 'url', 'prompt', 'description');
+    if (other)
+        return other;
+    return asText(input);
+}
+export class TraceRecorder {
+    exact;
+    now;
+    start;
+    steps = [];
+    omitted = 0;
+    open = new Map();
+    marked = new Set();
+    lastText = '';
+    /** `exact`: secrets this process holds (its key, the run token), masked wherever they appear. */
+    constructor(exact = [], now = Date.now, start = now()) {
+        this.exact = exact;
+        this.now = now;
+        this.start = start;
+    }
+    clean(s, max = FIELD_MAX) {
+        // cut first (a command can print megabytes), keeping the start and the end; mask what is left; then the exact limit
+        return cut(redact(cut(s, max * 2), this.exact), max);
+    }
+    add(step) {
+        this.steps.push(step);
+        // a long run keeps its beginning and its end: drop the step after the first 60% of the budget
+        if (this.steps.length > STEPS_MAX) {
+            this.steps.splice(Math.floor(STEPS_MAX * 0.6), 1);
+            this.omitted++;
+        }
+        return step;
+    }
+    /** Feed one adapter event. Events it does not know are ignored. */
+    event(e) {
+        const d = e.data;
+        const t = this.now() - this.start;
+        if (e.type === 'thinking') {
+            const text = asText(d).trim();
+            if (text)
+                this.add({ t, kind: 'thinking', output: this.clean(text) });
+        }
+        else if (e.type === 'text') {
+            const text = asText(d).trim();
+            // the same words twice in a row (a final message repeated) are one step
+            if (text && text !== this.lastText)
+                this.add({ t, kind: 'text', output: this.clean(text) });
+            this.lastText = text;
+        }
+        else if (e.type === 'tool_start' && d && typeof d === 'object') {
+            const id = String(d.id ?? '');
+            const name = String(d.name ?? d.type ?? 'tool');
+            const input = summarizeInput(name, d.input);
+            const secret = /^(read|cat|view)$/i.test(name) && isSecretFile(String(d.input?.file_path ?? d.input?.path ?? ''));
+            const step = this.add({ t, kind: 'tool', name, input: this.clean(input) });
+            if (id)
+                this.open.set(id, { step, at: this.now(), secret });
+        }
+        else if (e.type === 'tool_end' && d && typeof d === 'object') {
+            const id = String(d.id ?? '');
+            const o = this.open.get(id);
+            const step = o?.step ?? this.add({ t, kind: 'tool', name: String(d.name ?? 'tool') });
+            if (o) {
+                step.ms = this.now() - o.at;
+                this.open.delete(id);
+            }
+            if (d.is_error !== undefined)
+                step.is_error = !!d.is_error;
+            if (typeof d.exit === 'number')
+                step.exit = d.exit;
+            const out = asText(d.output);
+            if (out)
+                step.output = o?.secret ? '[contents of a secrets file not recorded]' : this.clean(out);
+        }
+    }
+    /** Something happened around the run (the task was completed while the run went on). Once per name. */
+    mark(name) {
+        if (this.marked.has(name))
+            return;
+        this.marked.add(name);
+        this.add({ t: this.now() - this.start, kind: 'mark', name });
+    }
+    /** The trace as it is now, within the size limit. */
+    finish() {
+        let steps = this.steps.map((s) => ({ ...s }));
+        let omitted = this.omitted;
+        const size = () => JSON.stringify(steps).length;
+        // too big: shorten what each step printed, then drop from the middle
+        if (size() > TRACE_BYTES_MAX)
+            steps = steps.map((s) => (s.output && s.output.length > 600 ? { ...s, output: cut(s.output, 600) } : s));
+        while (size() > TRACE_BYTES_MAX && steps.length > 20) {
+            steps.splice(Math.floor(steps.length / 2), 1);
+            omitted++;
+        }
+        return { steps, omitted };
+    }
+}

package/dist/src/version.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "3.11.0";
+export declare const VERSION = "3.12.0";
 /** The npm package (scripts/release.mjs keeps it and VERSION in step with package.json). */
 export declare const PKG_NAME = "@koalaauto/agentchannel";
 /**

package/dist/src/version.js

@@ -1,4 +1,4 @@
-export const VERSION = '3.11.0';
+export const VERSION = '3.12.0';
 /** The npm package (scripts/release.mjs keeps it and VERSION in step with package.json). */
 export const PKG_NAME = '@koalaauto/agentchannel';
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@koalaauto/agentchannel",
-  "version": "3.11.0",
+  "version": "3.12.0",
   "description": "Hand work between your team's agents (Claude Code, Codex) and follow it in one panel: the ach CLI, MCP server and runner for AgentChannel v2",
   "keywords": [
     "agentchannel",