@koalaauto/agentchannel 3.10.0 → 3.12.0

package/dist/src/cli.js

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
-import { execFileSync } from 'node:child_process';
+import { execFileSync, execSync, spawn } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
 import { chmodSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
 import { basename, delimiter, dirname, isAbsolute, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { HELP, parseCli, UsageError } from './args.js';
 import { channelRef, Client, clientFromConfig, HubError, isZh, parseLinkRepo } from './client.js';
-import { closest, decisionTo, explainToUser, matchChannel, mentionNames, unknownMentions } from './names.js';
+import { channelTails, closest, decisionTo, explainToUser, matchChannel, mentionNames, unknownMentions } from './names.js';
 import { refOf, untrustedBlock as wrapUntrusted } from './prompts.js';
 import { achHome, loadConfig, readFileConfig, resolveClaimDelay, saveAdminToken, saveAgentKey, saveCfSecret, writeFileConfig } from './config.js';
 import { achCommand, agentInvitePrompt, decodeInvite, encodeInvite, JOIN_HINT, joinLine, mcpCommands, hubTransportOk, shadowHint } from './invite.js';
@@ -415,7 +415,7 @@ async function dispatch(p, io) {
                 : `joined ${inv.hub} as agent ${me.name}${me.owner_name ? ` (owner ${me.owner_name})` : ''}; key stored in the ${where === 'keychain' ? 'OS keychain' : 'agent-key file (0600)'}.`);
             const { runSetup, doneLine } = await import('./onboard.js');
             const { defaultExec } = await import('./doctor.js');
-            const r = await runSetup({ env, out: io.out, err: io.err, exec: io.exec ?? defaultExec, ask: io.ask, cwd: io.cwd ?? process.cwd() }, { yes: !!v.yes, service: !!v.service, runtime: typeof me.runtime === 'string' ? me.runtime : undefined, zh });
+            const r = await runSetup({ env, out: io.out, err: io.err, exec: io.exec ?? defaultExec, ask: io.ask, cwd: io.cwd ?? process.cwd(), ...(io.ask ? { runTty: (line) => runInTerminal(line, env) } : {}) }, { yes: !!v.yes, service: !!v.service, runtime: typeof me.runtime === 'string' ? me.runtime : undefined, zh });
             out(r.failed.length ? (zh ? `部分步骤失败（${r.failed.join(', ')}）：运行 ach doctor 查看怎么修。` : `Some steps failed (${r.failed.join(', ')}): run ach doctor to see how to fix them.`) : r.tools.length ? doneLine(r.tools, zh) : zh ? '密钥已保存，但还没有接入任何工具（见上面）。' : 'The key is stored, but no tool is connected yet (see above).');
             return r.failed.length ? 1 : 0;
         }
@@ -489,6 +489,7 @@ async function dispatch(p, io) {
                 handoff,
                 ...(str(v['key-question']) ? { key_question: str(v['key-question']) } : {}),
                 ...(Array.isArray(v.depends) && v.depends.length ? { depends_on: v.depends } : {}),
+                ...(v.review ? { review: true } : {}),
                 ...(links ? { links } : {}),
                 ...(str(v.channel) ? { channel: channelRef(str(v.channel)) } : {}),
             }, files());
@@ -643,7 +644,7 @@ async function dispatch(p, io) {
                 out('no channels');
             else
                 for (const c of list)
-                    out(`#${c.name}${c.archived ? ' [archived]' : ''}  ${c.post_count ?? 0} posts${c.last_post_at ? `, last ${c.last_post_at}` : ''}${c.description ? `  ${c.description}` : ''}`);
+                    out(`#${c.name}${c.archived ? ' [archived]' : ''}${c.access && c.access !== 'team' ? ` [${c.access}]` : ''}  ${c.post_count ?? 0} posts${c.last_post_at ? `, last ${c.last_post_at}` : ''}${c.description ? `  ${c.description}` : ''}`);
             return 0;
         }
         case 'channel': {
@@ -683,6 +684,9 @@ async function dispatch(p, io) {
             const chans = await c.channels().catch(() => []);
             const hit = matchChannel(name, chans);
             if (!hit && chans.length) {
+                const many = channelTails(name, chans);
+                if (many.length > 1)
+                    throw new UsageError(`post: "${channelRef(name)}" is more than one channel (${many.map((x) => '#' + x.name).join(', ')}): write the full path.`);
                 const near = closest(channelRef(name), chans.flatMap((x) => [x.name, String(x.title ?? '')]).filter(Boolean));
                 const nearName = near && (chans.find((x) => x.name === near || x.title === near)?.name ?? near);
                 throw new UsageError(`post: no channel "${channelRef(name)}" you can post in${nearName ? ` (did you mean #${nearName}?)` : ''}. List them with \`ach channels\`.`);
@@ -853,23 +857,45 @@ async function dispatch(p, io) {
             const runId = str(v['run-id']) ?? (env.ACH_RUN_TOKEN ? undefined : await implicitRunId(c, id, true));
             // A spawned worker says which handoff it worked from; the hub refuses an outdated one.
             const shown = Number(env.ACH_HANDOFF_VERSION) || undefined;
-            const r = await c.complete(id, result, runId, att, shown);
+            const r = await c.complete(id, result, runId, att, shown, str(v['owner-action']));
             out(v.json ? r : 'completed');
             return 0;
         }
+        case 'accept': {
+            // the sender's side: a task sent with --review waits for this (or request-changes) when its worker is done
+            // `ach accept TASK-12 [note]` or `ach accept --task TASK-12 [note]`
+            const id = str(v.task) ?? p.positionals[0];
+            if (!id)
+                throw new UsageError('accept: <task> is required (TASK-<n>)');
+            const note = (str(v.task) ? p.positionals : p.positionals.slice(1)).join(' ').trim();
+            const r = await client().acceptTask(id, note || undefined);
+            out(v.json ? r : `accepted ${id}`);
+            return 0;
+        }
+        case 'request-changes': {
+            const id = str(v.task) ?? p.positionals[0];
+            if (!id)
+                throw new UsageError('request-changes: <task> is required (TASK-<n>)');
+            const text = (str(v.task) ? p.positionals : p.positionals.slice(1)).join(' ').trim();
+            if (!text)
+                throw new UsageError('request-changes: <task> "<what to change>" is required');
+            const r = await client().requestChanges(id, text);
+            out(v.json ? r : `sent ${id} back to its worker`);
+            return 0;
+        }
         case 'fail': {
             const c = client();
             const id = taskIdOf(p, io);
             const reason = text(p, '<reason>');
             const runId = str(v['run-id']) ?? (env.ACH_RUN_TOKEN ? undefined : await implicitRunId(c, id, false));
-            const r = await c.fail(id, reason, runId);
+            const r = await c.fail(id, reason, runId, str(v['owner-action']));
             out(v.json ? r : 'failed');
             return 0;
         }
         case 'claim': {
             const id = p.positionals[0] ?? str(v.task);
             if (!id)
-                throw new UsageError('claim: <task> is required (id or T-<n>)');
+                throw new UsageError('claim: <task> is required (id or TASK-<n>)');
             const c = client();
             const me = await c.me();
             const b = await c.claim(id, newInteractiveRunId(), 'interactive');
@@ -894,7 +920,7 @@ async function dispatch(p, io) {
         case 'remember': {
             const source = str(v.source);
             if (!source)
-                throw new UsageError('remember: --source <link> is required (a hub permalink like #/t/T-12 or a GitHub URL)');
+                throw new UsageError('remember: --source <link> is required (a hub permalink like #/t/TASK-12 or a GitHub URL)');
             const r = await client().remember(text(p, '"<fact or lesson>"'), source, { channel: str(v.channel), topic: str(v.topic), toTeam: !!v['to-team'] });
             if (v.json)
                 out(r);
@@ -1318,12 +1344,12 @@ async function dispatch(p, io) {
                     out(list);
                 else
                     for (const c of list)
-                        out(`#${c.name}${c.title && c.title !== c.name ? `  ${c.title}` : ''}${c.archived ? ' [archived]' : ''}${c.visibility === 'private' ? ` [private, ${c.member_count ?? 0} members]` : ''}  ${c.post_count ?? 0} posts`);
+                        out(`#${c.name}${c.title && c.title !== c.name ? `  ${c.title}` : ''}${c.archived ? ' [archived]' : ''}${c.visibility === 'private' ? ` [${c.access && c.access !== 'private' ? c.access : 'private'}, ${c.member_count ?? 0} members]` : ''}  ${c.post_count ?? 0} posts`);
                 return 0;
             }
             if (sub === 'create') {
                 const title = str(v.title) ?? rest.join(' ').trim();
-                const r = await a.request('POST', '/api/ach/channels', { ...(str(v.name) ? { name: str(v.name) } : {}), ...(title ? { title } : {}), ...(str(v.description) ? { description: str(v.description) } : {}) });
+                const r = await a.request('POST', '/api/ach/channels', { ...(str(v.name) ? { name: str(v.name) } : {}), ...(str(v.folder) ? { folder: str(v.folder) } : {}), ...(title ? { title } : {}), ...(str(v.description) ? { description: str(v.description) } : {}) });
                 out(v.json ? r : `created #${r.name}`);
                 return 0;
             }
@@ -1338,10 +1364,18 @@ async function dispatch(p, io) {
                 // private: only members (and admins) see the channel, its posts, wiki pages and files
                 if (!rest[0])
                     throw new UsageError(`admin channels ${sub}: <#name> is required`);
-                const r = await a.request('PATCH', `/api/ach/channels/${encodeURIComponent(channelRef(rest[0]))}`, { visibility: sub });
+                const r = await a.request('PATCH', `/api/ach/channels/${encodeURIComponent(channelRef(rest[0]))}`, { visibility: sub, ...(v.cascade ? { cascade: true } : {}) });
                 out(v.json ? r : `#${r.name}: ${r.visibility}`);
                 return 0;
             }
+            if (sub === 'move' || sub === 'rename') {
+                // a new path: what is under it goes along, and the old path keeps finding it
+                if (!rest[0] || !rest[1])
+                    throw new UsageError(`admin channels ${sub}: <#old-path> <#new-path> is required (e.g. onair-mmgr reela/mmgr)`);
+                const r = await a.request('PATCH', `/api/ach/channels/${encodeURIComponent(channelRef(rest[0]))}`, { name: channelRef(rest[1]) });
+                out(v.json ? r : `#${r.name} (the old path #${channelRef(rest[0])} still finds it)`);
+                return 0;
+            }
             if (sub === 'members') {
                 if (!rest[0])
                     throw new UsageError('admin channels members: <#name> [--add a,b] [--remove c] is required');
@@ -1356,7 +1390,7 @@ async function dispatch(p, io) {
                 out(v.json ? r : `#${r?.name}: ${r?.visibility ?? 'team'}, ${r?.member_count ?? 0} member(s)`);
                 return 0;
             }
-            throw new UsageError('admin channels: list | create [--name n] [--title t] | archive <#name> | unarchive <#name> | private <#name> | team <#name> | members <#name> [--add a,b] [--remove c]');
+            throw new UsageError('admin channels: list | create [--name path] [--folder f] [--title t] | move <#old> <#new-path> | archive <#name> | unarchive <#name> | private <#name> [--cascade] | team <#name> | members <#name> [--add a,b] [--remove c]');
         }
         case 'admin embeds': {
             const a = admin();
@@ -1397,6 +1431,20 @@ async function dispatch(p, io) {
             }
             return 0;
         }
+        case 'admin memory-maintainers': {
+            const a = admin();
+            const names = p.positionals.flatMap(splitList);
+            const r = (names.length ? await a.request('PUT', '/api/ach/admin/memory/settings', { maintainers: { agents: names } }) : await a.request('GET', '/api/ach/admin/memory/settings'));
+            const list = (r.maintainers?.agents ?? []);
+            out(v.json ? r : list.length ? `Memory maintainers: ${list.join(', ')}` : 'no Memory maintainer is set: the admin agent with no setup problem that was seen most recently is used (name one to choose)');
+            return 0;
+        }
+        case 'admin memory-upkeep': {
+            const name = p.positionals[0];
+            const r = (await admin().request('POST', '/api/ach/admin/memory/overview', name ? { channel: channelRef(name) } : {}));
+            out(v.json ? r : r.upkeep_task ? `queued ${r.upkeep_task.ref}${r.upkeep_task.url ? `: ${r.upkeep_task.url}` : ''}` : 'nothing waiting for upkeep');
+            return 0;
+        }
         case 'admin retention': {
             const name = p.positionals[0];
             if (!name)
@@ -1485,6 +1533,14 @@ function linkOf(env, t) {
 function splitList(v) {
     return v.split(',').map((x) => x.trim()).filter(Boolean);
 }
+/** A shell line with this terminal's stdin/stdout/stderr (sudo asks for its password there); its exit code. */
+function runInTerminal(line, env) {
+    return new Promise((res) => {
+        const c = spawn('/bin/sh', ['-c', line], { env, stdio: 'inherit' });
+        c.on('error', () => res(127));
+        c.on('exit', (code) => res(code ?? 1));
+    });
+}
 function shq(s) {
     return `'${s.replace(/'/g, `'\\''`)}'`;
 }
@@ -1511,7 +1567,7 @@ async function runCommand(p, io) {
     const cfg = loadConfig(env);
     if (!cfg.key)
         throw new UsageError('run: no agent key. Run `ach login` or set ACH_KEY.');
-    const c = clientFromConfig(cfg, { fetch: io.fetch });
+    const c = clientFromConfig(cfg, { fetch: io.fetch, role: 'runner' });
     const home = achHome(env);
     const dir = resolve(io.cwd ?? process.cwd(), str(v.dir) ?? '.');
     const { GitWorkspace, parseRepoFlags } = await import('./runner/workspace.js');
@@ -1568,6 +1624,7 @@ async function runCommand(p, io) {
         claimDelayMs: claimDelay * 1000,
         cfId: cfg.cfId,
         cfSecret: cfg.cfSecret,
+        secrets: [cfg.key ?? ''].filter(Boolean),
         publicUrl: env.ACH_PUBLIC_URL || undefined,
         onClientTooOld: () => void updater?.nudge(),
         passEnv: (Array.isArray(v['pass-env']) ? v['pass-env'] : []).flatMap(splitList),
@@ -1576,6 +1633,10 @@ async function runCommand(p, io) {
             return shim ? { ...env, PATH: `${shim}${delimiter}${env.PATH ?? ''}` } : env;
         })(),
         log: io.err,
+        sandboxCheck: async () => {
+            const { probeEnvironment } = await import('./envcheck.js');
+            return probeEnvironment(runtime === 'codex' ? 'codex' : 'claude', { env });
+        },
     });
     io.err(`ach run: agent ${me.name}, runtime ${runtime}, perm min(${me.perm_level}, ${perm}), dir ${dir}` +
         (Object.keys(repos).length ? `, repos ${Object.entries(repos).map(([k, x]) => `${k}=${x}`).join(' ')}` : '') +
@@ -1666,8 +1727,8 @@ async function installService(p, io, o) {
     const { isBundledBin, npmSpec, whichAll } = await import('./invite.js');
     const env = io.env;
     const platform = (env.ACH_SERVICE_PLATFORM || process.platform);
-    if (platform !== 'darwin' && platform !== 'linux')
-        throw new UsageError(`run --install-service: unsupported platform ${platform} (macOS launchd or Linux systemd only)`);
+    if (platform !== 'darwin' && platform !== 'linux' && platform !== 'win32')
+        throw new UsageError(`run --install-service: unsupported platform ${platform} (macOS, Linux and Windows only)`);
     const v = p.values;
     const args = ['--dir', o.dir];
     for (const [name, path] of Object.entries(o.repos))
@@ -1704,14 +1765,17 @@ async function installService(p, io, o) {
         args,
         env: svcEnv,
         logFile: join(o.home, 'logs', 'runner.log'),
-    }, env.ACH_SERVICE_DIR || undefined);
+    }, env.ACH_SERVICE_DIR || undefined, env);
     writeServiceFile(f);
     const load = !env.ACH_SERVICE_DIR;
     let failed = '';
     if (load) {
         for (const c of f.start) {
             try {
-                execFileSync('/bin/sh', ['-c', c], { env, stdio: ['ignore', 'ignore', 'pipe'] });
+                if (platform === 'win32')
+                    execSync(c, { env, stdio: ['ignore', 'ignore', 'pipe'] }); // cmd.exe
+                else
+                    execFileSync('/bin/sh', ['-c', c], { env, stdio: ['ignore', 'ignore', 'pipe'] });
             }
             catch (e) {
                 failed = `${c}: ${String(e?.stderr ?? e?.message ?? e).trim().split('\n')[0]}`;

package/dist/src/client.d.ts

@@ -1,6 +1,6 @@
 import type { Config } from './config.js';
 import { type Attachment, type StorageConfig, type TaskFile } from './attachments.js';
-export type TaskStatus = 'submitted' | 'working' | 'input-required' | 'completed' | 'failed' | 'canceled';
+export type TaskStatus = 'submitted' | 'working' | 'input-required' | 'awaiting_acceptance' | 'completed' | 'failed' | 'canceled';
 export declare const TERMINAL: readonly TaskStatus[];
 export declare function isTerminal(s: string | undefined): boolean;
 export type MessageKind = 'question' | 'answer' | 'decision_request' | 'decision' | 'progress' | 'result' | 'note';
@@ -43,7 +43,7 @@ export interface Task {
     result?: string;
     created?: string;
     updated?: string;
-    /** §19: human-friendly number ("T-128" = ref) and permalink. */
+    /** §19: human-friendly number ("TASK-128" = ref) and permalink. */
     seq?: number;
     ref?: string;
     url?: string;
@@ -142,6 +142,8 @@ export interface ClaimResult extends TaskBundle {
 export type ClaimMode = 'runner' | 'interactive';
 export interface Inbox {
     tasks_to_me: Task[];
+    /** Tasks that said done and wait for acceptance, which this agent may accept or send back (accept_task / request_changes). */
+    tasks_to_review?: Task[];
     questions_to_me: Message[];
     answers_to_me: Message[];
     decisions_for_me: Message[];
@@ -175,7 +177,15 @@ export interface Post {
 }
 export interface Channel {
     id: string;
+    /** The path: `reela/onair` (up to 3 levels). */
     name: string;
+    /** The folder it sits in ('' at the top). */
+    parent?: string;
+    depth?: number;
+    /** team | private | inherited (follows its parent's people) | narrowed (a subset of them). */
+    access?: 'team' | 'private' | 'inherited' | 'narrowed';
+    /** Paths it had before a rename or move; they still find it. */
+    former_names?: string[];
     description?: string;
     archived?: boolean;
     post_count?: number;
@@ -228,6 +238,8 @@ export interface SendTaskInput {
     key_question?: string;
     depends_on?: string[];
     links?: Record<string, unknown>;
+    /** The task waits for acceptance when its worker is done (status awaiting_acceptance) until the sender's side accepts it or sends it back. */
+    review?: boolean;
     /** §16: channel name; default = the channel named like links.repo, else #general. */
     channel?: string;
 }
@@ -288,6 +300,8 @@ export interface ClientOptions {
     cfId?: string;
     cfSecret?: string;
     fetch?: FetchLike;
+    /** `runner`: this is `ach run` polling, not a person's session or an MCP server (the hub notes which agents have a runner). */
+    role?: 'runner';
 }
 /** Round 2: human-facing CLI text in Chinese when LANG/LC_ALL starts with zh. */
 export declare function isZh(env: NodeJS.ProcessEnv): boolean;
@@ -295,6 +309,7 @@ export declare function isZh(env: NodeJS.ProcessEnv): boolean;
 export declare function clientFromConfig(cfg: Config, opts?: {
     admin?: boolean;
     fetch?: FetchLike;
+    role?: 'runner';
 }): Client;
 /** Accept either `{task, handoff, messages, history}` or a bare task record. */
 export declare function normalizeBundle(raw: any): TaskBundle;
@@ -305,6 +320,7 @@ export declare class Client {
     private cfSecret?;
     private fetchFn;
     constructor(o: ClientOptions);
+    private role?;
     private ownFetch;
     /**
      * The hub's change stream (GET /api/ach/events, a WebSocket that says "something changed", ids only). The token
@@ -338,6 +354,10 @@ export declare class Client {
     me(): Promise<Agent>;
     agents(): Promise<Agent[]>;
     sendTask(input: SendTaskInput, files?: string[]): Promise<Task>;
+    /** The sender's side accepts a task that waits for acceptance: it is completed. */
+    acceptTask(taskId: string, note?: string): Promise<any>;
+    /** The sender's side sends a finished, failed or waiting task back with what to change; the worker redoes it. */
+    requestChanges(taskId: string, body: string): Promise<any>;
     /** Propose a recurring task (runs after the owner approves). */
     proposeSchedule(input: Record<string, unknown>): Promise<any>;
     schedules(): Promise<any[]>;
@@ -356,8 +376,9 @@ export declare class Client {
     }>;
     postMessage(taskId: string, m: PostMessageInput, files?: string[]): Promise<Message>;
     /** With an agent key the hub requires the task's current run_id (C3); run tokens carry their own. */
-    complete(taskId: string, result: string, run_id?: string, files?: string[], handoff_version?: number): Promise<any>;
-    fail(taskId: string, reason: string, run_id?: string): Promise<any>;
+    /** `owner_action`: a step only the owner of the executing agent can do; it reaches them as an Inbox item. */
+    complete(taskId: string, result: string, run_id?: string, files?: string[], handoff_version?: number, owner_action?: string): Promise<any>;
+    fail(taskId: string, reason: string, run_id?: string, owner_action?: string): Promise<any>;
     /** §23: a grantee agent answers the part of a request its grant covers. */
     grantDecide(taskId: string, message_id: string, option: number, grant: string): Promise<any>;
     createGrant(input: {
@@ -379,6 +400,29 @@ export declare class Client {
     /** The total size of a work prompt (Memory trial metrics). */
     promptSize(taskId: string, run_id: string, chars: number, parts?: Record<string, number>): Promise<any>;
     usage(taskId: string, run_id: string, cost_usd: number, estimated: boolean): Promise<any>;
+    /**
+     * design §27: what keeps this agent's runner from taking tasks on its machine (null: nothing). The hub shows it as
+     * "needs setup" with the fix.
+     */
+    /**
+     * The execution trace of one run (or one stretch of it), already masked and cut down: steps with thinking summaries, commands,
+     * exit codes and output excerpts. Idempotent by `traceId`; a second call updates the fields it carries (the commit, say).
+     */
+    putTrace(taskId: string, traceId: string, body: Record<string, unknown>): Promise<any>;
+    /** The traces of a task, oldest first. */
+    traces(taskId: string): Promise<any>;
+    /** The worker cannot run on its machine (not logged in, sandbox broken): the task goes back to submitted, not failed. */
+    release(taskId: string, reason: string, run_id?: string): Promise<any>;
+    reportSetup(sandbox: {
+        tool: string;
+        problem: string;
+        detail?: string;
+        fix?: {
+            en: string;
+            zh: string;
+            commands: string[];
+        };
+    } | null): Promise<any>;
     /** 409 when the run lost the task. Carries a fresh `run_token` when the old one is near expiry (C5). */
     heartbeat(taskId: string, run_id: string): Promise<{
         ok: boolean;

package/dist/src/client.js

@@ -44,7 +44,7 @@ export function clientFromConfig(cfg, opts = {}) {
             : 'No hub configured: run the `ach join ach2....` line from the panel or your admin (or set ACH_HUB).');
     }
     const token = opts.admin ? cfg.adminToken : cfg.runToken || cfg.key;
-    return new Client({ hub: cfg.hub, token, cfId: cfg.cfId, cfSecret: cfg.cfSecret, fetch: opts.fetch });
+    return new Client({ hub: cfg.hub, token, cfId: cfg.cfId, cfSecret: cfg.cfSecret, fetch: opts.fetch, role: opts.role });
 }
 function arr(v) {
     return Array.isArray(v) ? v : [];
@@ -74,7 +74,9 @@ export class Client {
         this.cfSecret = o.cfSecret;
         this.fetchFn = o.fetch ?? ((u, i) => fetch(u, i));
         this.ownFetch = !!o.fetch;
+        this.role = o.role;
     }
+    role;
     ownFetch;
     /**
      * The hub's change stream (GET /api/ach/events, a WebSocket that says "something changed", ids only). The token
@@ -95,6 +97,8 @@ export class Client {
     }
     headers(json = true) {
         const h = { ...CLIENT_HEADERS, ...(json ? { 'content-type': 'application/json', accept: 'application/json' } : { accept: 'application/json' }) };
+        if (this.role)
+            h['x-ach-role'] = this.role;
         if (this.token) {
             // Agent keys and run tokens use Bearer; a person's session token is sent as it is.
             h.authorization = /^ach_(sk|rt)_/.test(this.token) ? `Bearer ${this.token}` : this.token;
@@ -225,6 +229,14 @@ export class Client {
         const r = await this.ach('POST', '/tasks', input, files);
         return r?.task ?? r;
     }
+    /** The sender's side accepts a task that waits for acceptance: it is completed. */
+    async acceptTask(taskId, note) {
+        return this.ach('POST', `/tasks/${enc(taskId)}/accept`, note ? { note } : {});
+    }
+    /** The sender's side sends a finished, failed or waiting task back with what to change; the worker redoes it. */
+    async requestChanges(taskId, body) {
+        return this.ach('POST', `/tasks/${enc(taskId)}/request-changes`, { body });
+    }
     /** Propose a recurring task (runs after the owner approves). */
     async proposeSchedule(input) {
         return this.ach('POST', '/schedules', input);
@@ -268,11 +280,12 @@ export class Client {
         return r?.message ?? r;
     }
     /** With an agent key the hub requires the task's current run_id (C3); run tokens carry their own. */
-    async complete(taskId, result, run_id, files, handoff_version) {
-        return this.ach('POST', `/tasks/${enc(taskId)}/complete`, { result, ...(run_id ? { run_id } : {}), ...(handoff_version ? { handoff_version } : {}) }, files);
+    /** `owner_action`: a step only the owner of the executing agent can do; it reaches them as an Inbox item. */
+    async complete(taskId, result, run_id, files, handoff_version, owner_action) {
+        return this.ach('POST', `/tasks/${enc(taskId)}/complete`, { result, ...(run_id ? { run_id } : {}), ...(handoff_version ? { handoff_version } : {}), ...(owner_action ? { owner_action } : {}) }, files);
     }
-    async fail(taskId, reason, run_id) {
-        return this.ach('POST', `/tasks/${enc(taskId)}/fail`, { reason, ...(run_id ? { run_id } : {}) });
+    async fail(taskId, reason, run_id, owner_action) {
+        return this.ach('POST', `/tasks/${enc(taskId)}/fail`, { reason, ...(run_id ? { run_id } : {}), ...(owner_action ? { owner_action } : {}) });
     }
     /** §23: a grantee agent answers the part of a request its grant covers. */
     async grantDecide(taskId, message_id, option, grant) {
@@ -297,6 +310,28 @@ export class Client {
     async usage(taskId, run_id, cost_usd, estimated) {
         return this.ach('POST', `/tasks/${enc(taskId)}/usage`, { run_id, cost_usd, estimated });
     }
+    /**
+     * design §27: what keeps this agent's runner from taking tasks on its machine (null: nothing). The hub shows it as
+     * "needs setup" with the fix.
+     */
+    /**
+     * The execution trace of one run (or one stretch of it), already masked and cut down: steps with thinking summaries, commands,
+     * exit codes and output excerpts. Idempotent by `traceId`; a second call updates the fields it carries (the commit, say).
+     */
+    async putTrace(taskId, traceId, body) {
+        return this.ach('PUT', `/tasks/${enc(taskId)}/traces/${enc(traceId)}`, body);
+    }
+    /** The traces of a task, oldest first. */
+    async traces(taskId) {
+        return this.ach('GET', `/tasks/${enc(taskId)}/traces`);
+    }
+    /** The worker cannot run on its machine (not logged in, sandbox broken): the task goes back to submitted, not failed. */
+    async release(taskId, reason, run_id) {
+        return this.ach('POST', `/tasks/${enc(taskId)}/release`, { reason, ...(run_id ? { run_id } : {}) });
+    }
+    async reportSetup(sandbox) {
+        return this.ach('PUT', '/me/setup', { sandbox });
+    }
     /** 409 when the run lost the task. Carries a fresh `run_token` when the old one is near expiry (C5). */
     async heartbeat(taskId, run_id) {
         return this.ach('POST', `/tasks/${enc(taskId)}/heartbeat`, { run_id });
@@ -309,6 +344,7 @@ export class Client {
         const r = await this.ach('GET', '/inbox');
         return {
             tasks_to_me: arr(r?.tasks_to_me),
+            tasks_to_review: arr(r?.tasks_to_review),
             questions_to_me: flatMsgs(r?.questions_to_me),
             answers_to_me: flatMsgs(r?.answers_to_me),
             decisions_for_me: flatMsgs(r?.decisions_for_me),

package/dist/src/desknotify.d.ts

@@ -77,13 +77,13 @@ export declare function notifyCommand(o: {
 } | null;
 /** The options a decision item offers (labels/details from `options`, tokens from `actions` by option index). Pure. */
 export declare function itemOptions(x: NotifyItem): NotifyOption[];
-/** Task ref and message id of a decision item: fields, else its link `t/T-12/m/<id>`. Pure. */
+/** Task ref and message id of a decision item: fields, else its link `t/TASK-12/m/<id>`. Pure. */
 export declare function itemTarget(x: NotifyItem): {
     task?: string;
     message?: string;
 };
 /**
- * The panel link with option `i` preselected: `…/#/t/T-12/m/<id>?pick=<i>`
+ * The panel link with option `i` preselected: `…/#/t/TASK-12/m/<id>?pick=<i>`
  * (the query goes inside the hash route, where the panel reads it). Pure.
  */
 export declare function pickUrl(url: string, i: number): string;

package/dist/src/desknotify.js

@@ -121,7 +121,7 @@ export function itemOptions(x) {
     });
     return out.slice(0, 4);
 }
-/** Task ref and message id of a decision item: fields, else its link `t/T-12/m/<id>`. Pure. */
+/** Task ref and message id of a decision item: fields, else its link `t/TASK-12/m/<id>`. Pure. */
 export function itemTarget(x) {
     const m = /(?:^|#\/|\/)t\/([^/?#]+)\/m\/([A-Za-z0-9_-]+)/.exec(String(x.path ?? '') || String(x.url ?? ''));
     return { task: x.task_id || x.task_ref || (m ? decodeURIComponent(m[1]) : undefined), message: x.message_id || (m ? m[2] : undefined) };
@@ -132,7 +132,7 @@ function isDecision(x) {
     return x.decision === true || /decision_request|memory_question/.test(String(x.event ?? '')) || itemOptions(x).length > 0;
 }
 /**
- * The panel link with option `i` preselected: `…/#/t/T-12/m/<id>?pick=<i>`
+ * The panel link with option `i` preselected: `…/#/t/TASK-12/m/<id>?pick=<i>`
  * (the query goes inside the hash route, where the panel reads it). Pure.
  */
 export function pickUrl(url, i) {

package/dist/src/doctor.d.ts

@@ -49,6 +49,10 @@ export declare function runDoctor(o: {
     fetch?: FetchLike;
     exec?: ExecLike;
     self?: string;
+    /** the sandbox probe (tests) */
+    sandbox?: (tool: 'claude' | 'codex', o: {
+        env: NodeJS.ProcessEnv;
+    }) => Promise<import('./sandboxcheck.js').SandboxStatus>;
 }): Promise<DoctorCheck[]>;
 /**
  * Command, args and AGENTCHANNEL_HOME of an MCP entry from `claude mcp get`

package/dist/src/doctor.js

@@ -247,6 +247,7 @@ export async function runDoctor(o) {
             const { serviceFile, serviceLabel } = await import('./service.js');
             const platform = (env.ACH_SERVICE_PLATFORM || process.platform);
             if (platform === 'darwin' || platform === 'linux') {
+                // (Windows: the Startup script has no status command; doctor says nothing rather than guess)
                 const f = serviceFile({ platform, agentName, command: [], args: [], env: {}, logFile: '' }, env.ACH_SERVICE_DIR || undefined);
                 if (!existsSync(f.path))
                     add('background', 'info', 'no background runner on this machine (optional: ach run --dir <repo> --install-service --interactive-first)');
@@ -299,6 +300,17 @@ export async function runDoctor(o) {
         if (codexPath)
             await mcpCheck('codex', codexPath);
     }
+    // design §27: the agent tool's sandbox, probed for real (every run that answers a question or an @mention is sandboxed)
+    const { probeSandbox } = await import('./sandboxcheck.js');
+    const tools = runtime === 'codex' ? ['codex'] : runtime === 'claude' ? ['claude'] : [...(claude ? ['claude'] : []), ...(codexPath || bundled ? ['codex'] : [])];
+    for (const t of tools) {
+        const st = await (o.sandbox ?? probeSandbox)(t, { env });
+        const name = `${t} sandbox`;
+        if (st.ok)
+            add(name, st.unverified ? 'info' : 'ok', st.unverified ? `not checked: ${st.detail ?? 'unknown'}` : 'starts, and stops writes outside the task directory');
+        else
+            add(name, runtime ? 'fail' : 'warn', `${st.fix?.en ?? st.detail ?? st.problem}${runtime ? ' The background runner takes no tasks until this is fixed.' : ''}`, 'machine', st.fix?.commands.length ? st.fix.commands.join('\n            ') : st.fix?.en);
+    }
     return out;
     /**
      * The `ach` MCP entry as the runtime itself reports it (`<runtime> mcp get

package/dist/src/envcheck.d.ts

@@ -0,0 +1,22 @@
+import { type ProbeOptions, type Run, type SandboxStatus, type SandboxTool } from './sandboxcheck.js';
+/** The tool authenticates from the environment (an API key, a cloud provider): there is no login to check. */
+export declare function authFromEnv(tool: SandboxTool, env: NodeJS.ProcessEnv): string | undefined;
+/** Is `tool` logged in here? Never throws. A tool that is not installed, or whose status command cannot be read, does not block (unverified). */
+export declare function probeLogin(tool: SandboxTool, o?: {
+    env?: NodeJS.ProcessEnv;
+    run?: Run;
+    claude?: string;
+    codex?: string[];
+    platform?: NodeJS.Platform;
+}): Promise<SandboxStatus>;
+/** The whole check: login first (cheap, and what a fresh machine lacks), then the sandbox. The first problem is the answer. */
+export declare function probeEnvironment(tool: SandboxTool, o?: ProbeOptions & {
+    claude?: string;
+}): Promise<SandboxStatus>;
+/**
+ * A run's error as the task's failure reason: the lines that carry the cause, not just the first one. Noise lines are dropped,
+ * lines that look like a cause come first (at most 3), then the first remaining line; capped at 600 characters.
+ */
+export declare function summarizeRuntimeError(raw: string): string;
+/** Does a run's error say the tool is not logged in (or its key was refused)? */
+export declare function looksLikeLoginError(s: string): boolean;