@koalaauto/agentchannel 3.11.0 → 3.13.0

package/dist/src/service.js

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 function xml(s) {
@@ -140,3 +140,99 @@ export function writeServiceFile(f) {
         mkdirSync(dir, { recursive: true });
     writeFileSync(f.path, f.content, { mode: 0o644 });
 }
+/** Where this platform keeps the files serviceFile() writes. */
+export function serviceDir(platform, env = process.env) {
+    if (platform === 'win32')
+        return join(env.APPDATA || join(homedir(), 'AppData', 'Roaming'), 'Microsoft', 'Windows', 'Start Menu', 'Programs', 'Startup');
+    if (platform === 'darwin')
+        return join(homedir(), 'Library', 'LaunchAgents');
+    return join(homedir(), '.config', 'systemd', 'user');
+}
+const unxml = (s) => s.replace(/&quot;/g, '"').replace(/&gt;/g, '>').replace(/&lt;/g, '<').replace(/&amp;/g, '&');
+/** The inverse of sd(): words of an ExecStart line, quoted or not. */
+function sdWords(line) {
+    const out = [];
+    const re = /"((?:[^"\\]|\\.)*)"|(\S+)/g;
+    let m;
+    while ((m = re.exec(line)))
+        out.push(m[1] !== undefined ? m[1].replace(/\\(.)/g, '$1').replace(/\$\$/g, '$').replace(/%%/g, '%') : m[2]);
+    return out;
+}
+const formatOf = (command) => {
+    if (!command.length)
+        return 'unknown';
+    if (/(^|[\\/])npx(\.cmd)?$/.test(command[0]))
+        return 'npx';
+    return command.slice(1).some((x) => /[\\/]_npx[\\/]/.test(x)) ? 'node-cache' : 'node';
+};
+/** Read a service file this module wrote (launchd plist or systemd unit); null for anything else, a Windows script included. */
+export function parseServiceFile(path, platform, text) {
+    let words = [];
+    const env = {};
+    let logFile = '';
+    let agentName = '';
+    if (platform === 'darwin') {
+        const label = /<key>Label<\/key>\s*<string>([^<]*)<\/string>/.exec(text)?.[1];
+        if (!label?.startsWith('io.agentchannel.runner.'))
+            return null;
+        agentName = unxml(label).slice('io.agentchannel.runner.'.length);
+        const arr = /<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/.exec(text)?.[1] ?? '';
+        words = [...arr.matchAll(/<string>([^<]*)<\/string>/g)].map((m) => unxml(m[1]));
+        const dict = /<key>EnvironmentVariables<\/key>\s*<dict>([\s\S]*?)<\/dict>/.exec(text)?.[1] ?? '';
+        for (const m of dict.matchAll(/<key>([^<]*)<\/key>\s*<string>([^<]*)<\/string>/g))
+            env[unxml(m[1])] = unxml(m[2]);
+        logFile = unxml(/<key>StandardOutPath<\/key>\s*<string>([^<]*)<\/string>/.exec(text)?.[1] ?? '');
+    }
+    else if (platform === 'linux') {
+        const exec = /^ExecStart=(.*)$/m.exec(text)?.[1];
+        const base = path.split(/[\\/]/).pop() ?? '';
+        if (!exec || !/^agentchannel-runner-.+\.service$/.test(base))
+            return null;
+        agentName = base.slice('agentchannel-runner-'.length, -'.service'.length);
+        words = sdWords(exec);
+        for (const m of text.matchAll(/^Environment=(.*)$/gm)) {
+            const kv = sdWords(m[1])[0] ?? '';
+            const i = kv.indexOf('=');
+            if (i > 0)
+                env[kv.slice(0, i)] = kv.slice(i + 1);
+        }
+    }
+    else
+        return null;
+    const run = words.indexOf('run');
+    if (run < 1)
+        return null;
+    const command = words.slice(0, run);
+    return { path, agentName, command, args: words.slice(run + 1), env, logFile, format: formatOf(command) };
+}
+/** Every runner service of this user on this machine (launchd and systemd). */
+export function listServices(platform, dir, env = process.env) {
+    if (platform === 'win32')
+        return [];
+    const d = dir ?? serviceDir(platform, env);
+    let names = [];
+    try {
+        names = readdirSync(d);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const f of names) {
+        if (!(platform === 'darwin' ? /^io\.agentchannel\.runner\..+\.plist$/ : /^agentchannel-runner-.+\.service$/).test(f))
+            continue;
+        try {
+            const s = parseServiceFile(join(d, f), platform, readFileSync(join(d, f), 'utf8'));
+            if (s)
+                out.push(s);
+        }
+        catch {
+            /* unreadable: not ours to judge */
+        }
+    }
+    return out;
+}
+/** The ServiceSpec that would write this service again (so it can be rewritten with another command). */
+export function specOf(s, platform, command = s.command) {
+    return { platform, agentName: s.agentName, command, args: s.args, env: s.env, logFile: s.logFile };
+}

package/dist/src/servicefix.d.ts

@@ -0,0 +1,41 @@
+import { type FoundService, type ServiceSpec } from './service.js';
+/** The config dir this service's runner uses: its own AGENTCHANNEL_HOME, else the default one. It names the agent (one key per home). */
+export declare function homeOfService(s: FoundService, env?: NodeJS.ProcessEnv): string;
+export interface Retired {
+    agentName: string;
+    path: string;
+}
+/**
+ * Stop and delete the other services of the agent whose home this is (not the one at `ownPath`). `run` false only deletes the files
+ * (the installer was told not to load anything). Returns what was retired.
+ */
+export declare function retireSiblings(o: {
+    platform: ServiceSpec['platform'];
+    dir?: string;
+    env: NodeJS.ProcessEnv;
+    ownPath: string;
+    ownHome: string;
+    run: boolean;
+}): Retired[];
+/** Was this process started by its own service (launchd, systemd)? A runner someone started by hand must not be replaced by a restart. */
+export declare function startedByService(agentName: string, platform: string, env: NodeJS.ProcessEnv): boolean;
+export interface Migration {
+    path: string;
+    /** Shell commands that make the supervisor load the rewritten file. */
+    start: string[];
+}
+/**
+ * This agent's own service, when it is in the old form (node on the npx cache): rewritten to start `npx -y <spec>`. Null when there is
+ * none, or it is already fine. Writing only; the caller decides when to reload (that ends this very process).
+ */
+export declare function migrateOldService(o: {
+    agentName: string;
+    platform: ServiceSpec['platform'];
+    dir?: string;
+    env: NodeJS.ProcessEnv;
+    home: string;
+    npx: string;
+    spec: string;
+}): Migration | null;
+/** Run the reload so that it outlives this process (the reload stops it): a detached shell. */
+export declare function reloadDetached(start: string[], env: NodeJS.ProcessEnv): void;

package/dist/src/servicefix.js

@@ -0,0 +1,69 @@
+// Keeping an agent's runner service right (issue #4): one service per agent, and a service that starts `npx -y <spec>`.
+//  - Installing a service retires the others on this machine that run the same agent (same AGENTCHANNEL_HOME): a renamed agent
+//    gets a new service label, and the old one went on running beside it.
+//  - A service written by an early release starts node on a file inside the npx cache. A restart (including the self-update's)
+//    runs that same cached file, so the runner never moves to a newer release. At start the runner rewrites such a service to
+//    `npx -y <spec>` and has the supervisor reload it.
+import { execFileSync, spawn } from 'node:child_process';
+import { unlinkSync } from 'node:fs';
+import { achHome } from './config.js';
+import { listServices, serviceFile, serviceLabel, specOf, writeServiceFile } from './service.js';
+/** The config dir this service's runner uses: its own AGENTCHANNEL_HOME, else the default one. It names the agent (one key per home). */
+export function homeOfService(s, env = process.env) {
+    return s.env.AGENTCHANNEL_HOME || achHome({ ...env, AGENTCHANNEL_HOME: '' });
+}
+/**
+ * Stop and delete the other services of the agent whose home this is (not the one at `ownPath`). `run` false only deletes the files
+ * (the installer was told not to load anything). Returns what was retired.
+ */
+export function retireSiblings(o) {
+    const out = [];
+    for (const s of listServices(o.platform, o.dir, o.env)) {
+        if (s.path === o.ownPath || homeOfService(s, o.env) !== o.ownHome)
+            continue;
+        if (o.run) {
+            for (const c of serviceFile(specOf(s, o.platform), o.dir, o.env).stop) {
+                try {
+                    execFileSync('/bin/sh', ['-c', c], { env: o.env, stdio: 'ignore' });
+                }
+                catch {
+                    /* it was not loaded: the file still goes */
+                }
+            }
+        }
+        try {
+            unlinkSync(s.path);
+            out.push({ agentName: s.agentName, path: s.path });
+        }
+        catch {
+            /* cannot delete: left for the person */
+        }
+    }
+    return out;
+}
+/** Was this process started by its own service (launchd, systemd)? A runner someone started by hand must not be replaced by a restart. */
+export function startedByService(agentName, platform, env) {
+    if (platform === 'darwin')
+        return env.XPC_SERVICE_NAME === serviceLabel(agentName);
+    if (platform === 'linux')
+        return !!env.INVOCATION_ID;
+    return false;
+}
+/**
+ * This agent's own service, when it is in the old form (node on the npx cache): rewritten to start `npx -y <spec>`. Null when there is
+ * none, or it is already fine. Writing only; the caller decides when to reload (that ends this very process).
+ */
+export function migrateOldService(o) {
+    const name = o.agentName.replace(/[^A-Za-z0-9-]/g, '-');
+    const own = listServices(o.platform, o.dir, o.env).find((s) => s.agentName === name && homeOfService(s, o.env) === o.home);
+    if (!own || own.format !== 'node-cache')
+        return null;
+    const f = serviceFile(specOf(own, o.platform, [o.npx, '-y', o.spec]), o.dir, o.env);
+    writeServiceFile(f);
+    return { path: f.path, start: f.start };
+}
+/** Run the reload so that it outlives this process (the reload stops it): a detached shell. */
+export function reloadDetached(start, env) {
+    const child = spawn('/bin/sh', ['-c', `sleep 2; ${start.join(' && ')}`], { env, detached: true, stdio: 'ignore' });
+    child.unref();
+}

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.13.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.13.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.13.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",