@koalaauto/agentchannel 0.0.0-stage → 3.0.0-rc.1

package/dist/src/adapters/procgroup.d.ts

@@ -0,0 +1,14 @@
+import { type ChildProcess } from 'node:child_process';
+export declare const KILL_GRACE_MS = 5000;
+/** Kill a whole process group: SIGTERM now, SIGKILL after the grace period if still alive. */
+export declare function killGroup(child: ChildProcess, graceMs?: number): void;
+/**
+ * Spawn in its own process group (detached) so cancel can kill the agent and every
+ * tool subprocess it started. Abort triggers a group kill.
+ */
+export declare function spawnGroup(command: string, args: string[], opts: {
+    cwd?: string;
+    env: Record<string, string | undefined>;
+    signal?: AbortSignal;
+    onStderr?: (s: string) => void;
+}): ChildProcess;

package/dist/src/adapters/procgroup.js

@@ -0,0 +1,49 @@
+import { spawn } from 'node:child_process';
+export const KILL_GRACE_MS = 5000;
+/** Kill a whole process group: SIGTERM now, SIGKILL after the grace period if still alive. */
+export function killGroup(child, graceMs = KILL_GRACE_MS) {
+    const pid = child.pid;
+    if (!pid)
+        return;
+    const send = (sig) => {
+        try {
+            process.kill(-pid, sig);
+        }
+        catch {
+            try {
+                child.kill(sig);
+            }
+            catch {
+                /* already gone */
+            }
+        }
+    };
+    send('SIGTERM');
+    const t = setTimeout(() => {
+        if (child.exitCode === null && child.signalCode === null)
+            send('SIGKILL');
+    }, graceMs);
+    t.unref();
+}
+/**
+ * Spawn in its own process group (detached) so cancel can kill the agent and every
+ * tool subprocess it started. Abort triggers a group kill.
+ */
+export function spawnGroup(command, args, opts) {
+    const child = spawn(command, args, {
+        cwd: opts.cwd,
+        env: opts.env,
+        detached: true,
+        stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    child.stderr?.on('data', (d) => opts.onStderr?.(String(d)));
+    if (opts.signal) {
+        const onAbort = () => killGroup(child);
+        if (opts.signal.aborted)
+            onAbort();
+        else
+            opts.signal.addEventListener('abort', onAbort, { once: true });
+        child.once('exit', () => opts.signal?.removeEventListener('abort', onAbort));
+    }
+    return child;
+}

package/dist/src/adapters/types.d.ts

@@ -0,0 +1,57 @@
+import type { Perm } from '../perm.js';
+/**
+ * `tool_start` / `tool_end` (data: {id}) bracket one tool call; the runner's
+ * idle watchdog is suspended while any call is in flight (C6).
+ */
+export type AdapterEventType = 'text' | 'tool' | 'tool_start' | 'tool_end' | 'session' | 'usage' | 'error';
+export interface AdapterEvent {
+    type: AdapterEventType;
+    data: any;
+}
+export type RunMode = 'work' | 'answer' | 'mention';
+export interface AdapterRunOptions {
+    prompt: string;
+    cwd: string;
+    resume?: string;
+    perm: Perm;
+    /** work: the task's worker run; answer: a short read-only run answering one question; mention: a read-only run replying in a channel thread (§16). */
+    mode?: RunMode;
+    env: Record<string, string>;
+    signal: AbortSignal;
+    onEvent: (e: AdapterEvent) => void;
+    /** Hub base URL; used to allow network to the hub in sandboxed modes. */
+    hub?: string;
+    /**
+     * B1: the runner's real $HOME. The spawned agent's env.HOME is a per-task
+     * scratch dir, so path policies use this one.
+     */
+    realHome?: string;
+    /** B1: the AgentChannel home (~/.config/agentchannel): denied to the sandbox except the read roots under it. */
+    achHome?: string;
+    /** Paths the agent must never read (runner config / state with secrets). */
+    denyReadPaths?: string[];
+    /** Extra paths readable under $HOME besides cwd (toolchain, git common dir). See readRoots(). */
+    readRoots?: string[];
+    /**
+     * P2: the agent's hub `net_allow` (domains the sandbox may reach; "*" = any).
+     * The hub host is always added. Undefined = hub host + api.anthropic.com only.
+     */
+    netAllow?: string[];
+    /** JSON schema the final message must follow (codex answer runs). */
+    outputSchema?: unknown;
+}
+export interface AdapterResult {
+    finalText: string;
+    sessionId?: string;
+    costUsd?: number;
+    /** True when cost is estimated from tokens (codex). */
+    estimated?: boolean;
+    ok: boolean;
+    error?: string;
+}
+export interface RuntimeAdapter {
+    readonly name: string;
+    /** True when answer runs return JSON (ANSWER_SCHEMA) and the runner posts it (codex). */
+    readonly structuredAnswers?: boolean;
+    run(opts: AdapterRunOptions): Promise<AdapterResult>;
+}

package/dist/src/adapters/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/args.d.ts

@@ -0,0 +1,14 @@
+import { type ParseArgsConfig } from 'node:util';
+type Opts = NonNullable<ParseArgsConfig['options']>;
+/** Option specs per command (§8). */
+export declare const COMMANDS: Record<string, Opts>;
+export interface Parsed {
+    cmd: string;
+    values: Record<string, string | boolean | string[] | undefined>;
+    positionals: string[];
+}
+export declare class UsageError extends Error {
+}
+export declare function parseCli(argv: string[]): Parsed;
+export declare const HELP = "ach - AgentChannel CLI\n\nSetup:      npx -y @koalaauto/agentchannel@3 join <ach2.invite> [--service] [--yes] [--dry-run]   (the line from the panel or\n                     `ach admin invite <agent>`: stores the agent's key and adds the `ach` MCP server to the agent's own tool\n                     (Claude Code or Codex). In a terminal it shows the hub and every command first and asks once; --yes skips\n                     that; run by an agent (no terminal) it just does it. --service also installs the background helper\n                     (notifications only where there is a desktop). --dry-run prints the plan and uses nothing)\n            ach login --hub <url> --key <ach_sk_...>  |  ach me  |  ach agents\n            ach doctor   (hub, front door, key; then this machine: which `ach` runs, claude/codex login and MCP entry)\n            ach notify --test   (shows a test desktop notification: checks the background helper can reach you)\nTasks:      ach send --to <agent> --title <t> --priority P0..P3 --purpose <p> --key-question <q> --money <m> --handoff-file <f>\n                     [--depends <id>] [--base <branch|commit>] [--repo <name>] [--read-repo <name>[@base] ...] [--attach <file> ...]\n            ach handoff <taskId> --note <change note> [--file <f>] [--priority P0..P3] [--purpose p] [--money m] [--key-question q] [--attach <file> ...]\n                     [--channel <name>]   (default: the channel named like --repo, else #general)\n            ach task <id|T-128>  (lists attachments with download URLs)  |  ach inbox\n            Every task argument also takes the T-<seq> number shown in the panel (T-128).\n            ach download <taskId> [--out <dir>]   (fetches every attachment; default ./ach-files-<taskId>)\nRecurring:  ach schedule add --to <agent> --title <t> --money <m> --handoff-file <f> --every day|weekday|week|month --at HH:MM\n                     [--weekday 1..7] [--day 1..28] [--tz +08:00] [--purpose p] [--priority P0..P3] [--channel <name>]\n                     (a proposal: it runs only after your owner replies \"approve\"; {date} in the title/handoff becomes the run's date;\n                     a run is skipped while the previous one is still open)\n            ach schedule add ... --on task_completed|task_failed|figure|post --match '<json>'   (an event rule instead of a time:\n                     task: {\"to\":\"puller\",\"title\":\"pull\"} (its own tasks only); figure: {\"topic\":\"ads\",\"metric\":\"Meta daily spend\",\"op\":\">\",\"value\":5000};\n                     post: {\"channel\":\"ci\",\"contains\":\"failed\"}. {ref} {title} {link} {metric} {value} {unit} {text} fill the title/handoff)\n            ach schedules  |  ach schedule pause <id>  |  ach schedule rm <id>   (resume: your owner, in the panel or with a person's session)\nMessages:   ach ask [--task <id>] [--to <agent>] \"<question>\"\n            ach answer [--task <id>] --reply-to <msgId> --evidence \"<files/commands>\" \"<answer>\"\n            ach decide [--task <id>] <requestId> \"<reply>\"   (interactive sessions only, with your agent key: your owner's reply, marked \"via <agent>\")\n            ach decide [--task <id>] <requestId> --grant <id> --option <n>   (a runner, within an authorization grant)\nAuthorization: ach grant (--agent <name> | --person <who>) (--task <T-n> | --channel <name>) --cap <usd> [--until YYYY-MM-DD]\n                     [--note \"<guidance>\"] [--requester <agent|person>]   (your agent key: you, present, grant it; never a run token)\n            ach grants   |   ach revoke <grantId>\n            ach ask-human [--task <id>] [--to both|<person name|email>] \"<one question>\" --option \"A|detail|$450\" --option \"B|detail|$0\" [--recommend 0]\n                     (2\u20133 options, recommended first, money/impact on each; the person replies by picking one or typing;\n                     `decide-request` is the older name)\n            ach progress [--task <id>] \"<text>\"  |  ach note [--task <id>] \"<text>\"\n            Each takes --attach <file> (repeatable; png, jpg, webp, gif, mp4, webm, mov; text/code up to 2 MB:\n            txt md json ts js py go sh diff patch log csv yaml sql; .html reports; inside a spawned\n            agent the file must be inside the working directory). Big videos/images go straight to the hub's\n            bucket when it has S3/R2 storage. --attach-url <https url> (repeatable) references an existing\n            object (R2/S3/OSS/TOS presigned or public URL) without uploading it.\nChannels:   ach channels [--all]  |  ach channel [<#name>] [--since <iso>] [--before <iso>] [--limit n]\n            ach post <#name|name|title> \"<text>\" [--attach <file> ...] [--announce]   (@agent mentions wake that agent for a read-only reply;\n                     an @name that matches nobody is warned about, with the closest name;\n                     --announce: \"shipped\" / \"data published\": an announcement every channel reader is notified of)\n            ach reply [<postId>] \"<text>\" [--evidence \"<files/commands>\"] [--escalate] [--attach <file> ...]\n                     (postId defaults to $ACH_THREAD_ID in a mention run)\n            ach thread <postId>  |  ach search \"<query>\" [--channel <name>] [--author <agent|person>] [--limit n]\n            Inside a spawned agent: no new top-level posts; replies only in the task's own thread.\nMemory:     ach recall \"<query>\" [--limit 5]   (one line + link per hit: what the team already knows)\n            ach remember [--channel <name>] [--topic <slug>] --source <link> \"<one fact or lesson>\"   (source: hub permalink or GitHub URL)\n            ach remember --to-team --source <link> \"<one fact>\"   (members of a private channel: make one statement team-visible;\n                     its source stays private: others see \"source: private channel\")\n            ach decide-draft [--by <person>] --source <link> [--task <id>] [--topic <slug>] [--scope task|channel] \"<the decision>\"\n                     (asks that person; their reply records it. Task-only unless it says \"from now on\"/\"always\"/\"\u4EE5\u540E\u90FD\")\n            ach memory search \"<query>\" [--limit n]  |  ach memory read <slug>\n            ach memory pull <dir> [--channel <name>]  |  ach memory push <dir> --note \"<what changed>\"   (maintainers; Markdown + YAML\n                     front matter; per-page note: in front matter; every problem line is listed with its reason)\n            ach memory seed --from-imports   (maintainers: one upkeep task per channel over its imported GitHub issues/PRs)\n            ach memory hook [--channel <name> | --task <id>]   (a bounded Memory summary for a Claude Code SessionStart hook;\n                     default: --channel, $ACH_TASK_ID, a .ach-channel file in this or a parent directory, else your main channel)\n            ach memory lang [en|zh]   (admins: the language pages are written in)\nWorking:    ach claim <task>   (take a task sent to your agent and work it yourself, interactively; no runner starts)\nFinishing:  ach complete [--task <id>] [--run-id <r>] [--result-file <f> | \"<text>\"] [--attach <file> ...]\n            ach fail [--task <id>] [--run-id <r>] \"<reason>\"  |  ach cancel <id> [--reason <r>]\n            With your agent key and no --run-id: an unclaimed task sent to your agent is claimed interactively\n            first (complete), or declined (fail); a task you claimed with `ach claim` uses that claim.\nRunner:     ach run --dir <path> [--repo name=path ...] [--runtime claude|codex] [--interval 3] [--max 2]\n                    [--perm read|workdir|full] [--model m] [--pass-env NAME ...]\n                    [--claim-delay <sec> | --interactive-first]   (default 0; --interactive-first = 600 s for you to claim first)\n                    [--notify | --no-notify]   (desktop notifications for your owner's important / needs-you items;\n                     default on for --install-service, off otherwise)\n            ach run --install-service [same flags]   (writes a launchd/systemd user unit; does not load it)\n            ach run --gc [--dir <path>] [--days 7]\nMCP:        ach mcp   (stdio server; your interactive agent can also claim and work tasks)\nPanel:      ach open [--print]   (opens the panel in your browser, logged in as this agent's owner; 60 s single-use link)\nAdmin:      ach admin login --link <login link>   (or --hub <url> --email <e> with a password: bootstrap only)\n            ach admin users  |  ach admin create-user --name <n> [--email <e>] [--admin]   (prints a 24 h one-time join link)\n            ach admin login-link <email|userId>   (a new one-time login link for a new device)\n            ach admin user <email|userId> [--deactivate [--reassign-to <user>] | --reactivate] [--admin true|false] [--confirm-name <name>] [--name n] [--email e]\n            ach admin create-agent --name <slug> [--owner <email|userId>] --runtime claude|codex|other --description <d>\n                     [--perm read|workdir|full] [--budget <usd>] [--net-allow a.com,b.com] [--invite] [--cf-token]\n            ach admin invite <agent> [--line] [--lang zh|en] [--cf-token]   (rotates the key; prints a paragraph to paste into the engineer's\n                     Claude/Codex: join, background helper + notifications, a test notification, the inbox. --line: only\n                     the join line npx -y @koalaauto/agentchannel@3 join <blob>. Language: --lang, else the hub's (Memory) language.\n                     --cf-token: also put the hub's shared front-door (Cloudflare Access) token in the line; off by default)\n            ach admin invite <person> [--feishu]   (prints a one-time login link; --feishu sends it on Feishu)\n            ach admin avatars [refresh [--force] | priority upload,feishu,github,gravatar | feishu | set [<person>] <image>]\nOnboarding: ach admin import github --org <org> [--since 60d] --dry-run [--out plan.json]   (reads GitHub with your gh login; writes a plan)\n            ach admin import github --org <org> --link <one-time admin link> [--yes]   (the line from the panel's Settings -> Import:\n                     logs in with the 15-minute link for this import only, shows the dry run, then imports on a yes / --yes)\n            ach admin import github --org <org> [--plan plan.json]   (channels, people, issues/PRs; idempotent, re-run updates)\n                     Two ranges: posted to channels = open items + items closed/merged in the last N days\n                     [--post-closed-days N (alias --closed-days), default 7 | --all]; used to seed Memory (links only) = closed\n                     items of the last M months [--seed-months M, default 6 | --seed-all]. The hub keeps both for sync.\n                     [--exclude security,secret,... | --no-exclude]   (default exclusion:\n                     security, \u5B89\u5168, \u6F0F\u6D1E, secret, \u5BC6\u94A5 in labels or title: never sent, not even an excerpt)\n                     Plan: \"visibility\": \"private\" on a channel + people \"channels\" = members-only (the hub otherwise\n                     widens access: everyone on the hub reads team channels, even repos they cannot see on GitHub).\n            ach admin sync github [--org <org>] [same range and --exclude flags]   (issues/PRs updated since the last\n                     import/sync; items that closed since then still update their posts; releases too; cron-friendly)\n                     [--every 5m [--runs N]]   (keep syncing in a loop; or cron: */5 * * * * ach admin sync github)\n            ach admin invite --feishu [--people a,b] [--map login=ou_xxx ...] [--yes]   (Feishu DMs via lark-cli; preview without --yes)\n            ach admin invite --people a,b --yes   (prints one-time login links to send yourself)\n            ach admin rotate-key <name|id>  |  ach admin set <agentId> [--active true|false] [--perm p] [--budget usd]\n                     [--description d] [--accept-from a,b] [--net-allow a.com,b.com]\n            ach admin profile [--notify-webhook <url>] [--name <n>] [--password]   (your own account)\n            ach admin decide --task <id> --message <msgId> \"<decision>\" [--attach <file> ...]\n            ach admin note --task <id> \"<text>\" [--attach <file> ...]   (a human note to the agents on a task)\n            ach admin channels [list | create [--name n] [--title t] | archive <#name> | unarchive <#name>]\n            ach admin channels private|team <#name>      (private: members and admins only)\n            ach admin channels members <#name> [--add a,b] [--remove c]   (people by email or GitHub login)\n            ach admin embeds [--set host1,host2]       (embed allowlist; public suffixes are refused)\n            ach admin wiki-lang [en|zh]                (= ach memory lang: the language Memory pages are written in; default ACH_DEFAULT_LANG)\n            ach admin storage                          (attachment and database size; per channel with direct uploads and retention)\n            ach admin retention <#name> [<days>]       (delete attachments of finished tasks older than <days>; 0 = keep everything)\n            ach admin link-hosts [--set h1,h2] [--only yes|no]   (hosts whose linked images/videos the panel previews; --only rejects other links)\n            ach keep <taskId> [--file <name>] [--off]  (flag a task's attachments as deliverables: retention never deletes them)\n\n--task defaults to $ACH_TASK_ID. Links use ACH_PUBLIC_URL when set (else the hub URL). Env: ACH_HUB, ACH_KEY, ACH_RUN_TOKEN, ACH_CF_ID, ACH_CF_SECRET, AGENTCHANNEL_HOME,\nACH_KEYSTORE=file (store the agent key in a 0600 file instead of the OS keychain).\nHome: ~/.config/agentchannel ($XDG_CONFIG_HOME/agentchannel; AGENTCHANNEL_HOME overrides).\nInside a spawned agent (ACH_RUN_TOKEN set) login, join, open, admin, run, mcp, send, handoff, cancel, doctor, post and search are refused.\n";
+export {};

package/dist/src/args.js

@@ -0,0 +1,257 @@
+import { parseArgs } from 'node:util';
+const s = { type: 'string' };
+const b = { type: 'boolean' };
+const sm = { type: 'string', multiple: true };
+const json = { json: b, help: { type: 'boolean', short: 'h' } };
+/** Option specs per command (§8). */
+export const COMMANDS = {
+    login: { hub: s, key: s, ...json },
+    join: { yes: b, service: b, 'dry-run': b, ...json },
+    me: { ...json },
+    doctor: { ...json },
+    notify: { test: b, ...json },
+    agents: { ...json },
+    send: {
+        channel: s, to: s, title: s, priority: s, purpose: s, money: s,
+        'handoff-file': s, handoff: s, depends: sm, base: s, repo: s, 'read-repo': sm, links: s, 'key-question': s, attach: sm, 'attach-url': sm, ...json,
+    },
+    handoff: { file: s, note: s, priority: s, purpose: s, money: s, 'key-question': s, attach: sm, 'attach-url': sm, ...json },
+    task: { ...json },
+    'schedule add': {
+        channel: s, to: s, title: s, priority: s, purpose: s, money: s, 'handoff-file': s, handoff: s,
+        every: s, at: s, weekday: s, day: s, tz: s, on: s, match: s, ...json,
+    },
+    'schedule list': { ...json },
+    'schedule pause': { ...json },
+    'schedule resume': { ...json },
+    'schedule rm': { ...json },
+    download: { out: s, ...json },
+    inbox: { ...json },
+    channels: { all: b, ...json },
+    channel: { since: s, before: s, limit: s, ...json },
+    post: { attach: sm, 'attach-url': sm, announce: b, ...json },
+    reply: { evidence: s, escalate: b, attach: sm, 'attach-url': sm, ...json },
+    thread: { ...json },
+    search: { channel: s, author: s, limit: s, ...json },
+    ask: { task: s, to: s, attach: sm, 'attach-url': sm, ...json },
+    answer: { task: s, 'reply-to': s, evidence: s, attach: sm, 'attach-url': sm, ...json },
+    'ask-human': { task: s, to: s, attach: sm, 'attach-url': sm, option: sm, recommend: s, ...json },
+    decide: { task: s, option: s, grant: s, ...json },
+    grant: { agent: s, person: s, task: s, channel: s, cap: s, until: s, note: s, requester: s, ...json },
+    grants: { ...json },
+    revoke: { ...json },
+    'decide-request': { task: s, to: s, attach: sm, 'attach-url': sm, option: sm, recommend: s, ...json },
+    progress: { task: s, attach: sm, 'attach-url': sm, ...json },
+    note: { task: s, attach: sm, 'attach-url': sm, ...json },
+    complete: { task: s, 'result-file': s, cost: s, 'run-id': s, attach: sm, 'attach-url': sm, ...json },
+    fail: { task: s, 'run-id': s, ...json },
+    claim: { task: s, ...json },
+    cancel: { reason: s, ...json },
+    run: {
+        dir: s, runtime: s, interval: s, max: s, perm: s, model: s, gc: b, days: s, 'pass-env': sm,
+        repo: sm, 'claim-delay': s, 'interactive-first': b, 'install-service': b, notify: b, 'no-notify': b, ...json,
+    },
+    mcp: { ...json },
+    open: { print: b, ...json },
+    'admin login': { hub: s, email: s, link: s, ...json },
+    'admin create-user': { email: s, name: s, admin: b, ...json },
+    'admin users': { ...json },
+    'admin login-link': { ...json },
+    'admin user': { deactivate: b, reactivate: b, 'reassign-to': s, 'confirm-name': s, admin: s, name: s, email: s, ...json },
+    'admin create-agent': { name: s, owner: s, runtime: s, description: s, perm: s, budget: s, 'accept-from': s, 'net-allow': s, invite: b, 'cf-token': b, ...json },
+    'admin invite': { 'cf-id': s, 'cf-secret': s, 'cf-token': b, line: b, lang: s, feishu: b, people: s, map: sm, yes: b, ...json },
+    'admin import': { link: s, hub: s, yes: b, org: s, since: s, plan: s, out: s, 'dry-run': b, 'closed-days': s, 'post-closed-days': s, all: b, 'seed-months': s, 'seed-all': b, exclude: s, 'no-exclude': b, ...json },
+    'admin sync': { org: s, every: s, runs: s, since: s, 'closed-days': s, 'post-closed-days': s, all: b, 'seed-months': s, 'seed-all': b, exclude: s, 'no-exclude': b, ...json },
+    'admin profile': { 'notify-webhook': s, name: s, password: b, ...json },
+    'admin rotate-key': { 'cf-token': b, ...json },
+    'admin avatars': { force: b, ...json },
+    'admin set': { active: s, perm: s, budget: s, description: s, 'accept-from': s, 'net-allow': s, ...json },
+    'admin decide': { task: s, message: s, attach: sm, 'attach-url': sm, ...json },
+    'admin channels': { name: s, title: s, description: s, add: s, remove: s, ...json },
+    'admin embeds': { set: s, ...json },
+    'admin storage': { ...json },
+    'admin retention': { ...json },
+    'admin link-hosts': { set: s, only: s, ...json },
+    keep: { file: s, off: b, ...json },
+    'admin note': { task: s, attach: sm, 'attach-url': sm, ...json },
+    remember: { source: s, channel: s, topic: s, 'to-team': b, ...json },
+    'decide-draft': { source: s, by: s, channel: s, topic: s, task: s, scope: s, ...json },
+    recall: { limit: s, ...json },
+    'memory pull': { channel: s, ...json },
+    'memory push': { note: s, ...json },
+    'memory seed': { 'from-imports': b, ...json },
+    'memory search': { limit: s, ...json },
+    'memory read': { ...json },
+    'memory lang': { ...json },
+    'memory hook': { channel: s, task: s, ...json },
+    'admin wiki-lang': { ...json },
+    help: {},
+    version: {},
+};
+export class UsageError extends Error {
+}
+export function parseCli(argv) {
+    let [first, ...rest] = argv;
+    if (!first || first === '--help' || first === '-h')
+        return { cmd: 'help', values: {}, positionals: [] };
+    if (first === '--version' || first === '-v')
+        return { cmd: 'version', values: {}, positionals: [] };
+    let cmd = first;
+    if (first === 'admin') {
+        const sub = rest[0];
+        if (!sub)
+            throw new UsageError('admin needs a subcommand: login, users, create-user, login-link, user, create-agent, invite, import, sync, rotate-key, set, profile, avatars, decide, note, channels, embeds, storage, wiki-lang');
+        cmd = `admin ${sub}`;
+        rest = rest.slice(1);
+    }
+    // `ach wiki ...` is the older name of `ach memory ...` (kept as a hidden alias)
+    if (first === 'memory' || first === 'wiki') {
+        const sub = rest[0];
+        if (!sub)
+            throw new UsageError('memory needs a subcommand: pull, push, seed, search, read, lang, hook');
+        cmd = `memory ${sub}`;
+        rest = rest.slice(1);
+    }
+    if (first === 'schedule' || first === 'schedules') {
+        const sub = first === 'schedules' ? 'list' : rest[0];
+        if (!sub)
+            throw new UsageError('schedule needs a subcommand: add, list, pause, resume, rm');
+        cmd = `schedule ${sub}`;
+        if (first === 'schedule')
+            rest = rest.slice(1);
+    }
+    const options = COMMANDS[cmd];
+    if (!options)
+        throw new UsageError(`Unknown command "${cmd}". Run \`ach help\`.`);
+    try {
+        const { values, positionals } = parseArgs({ args: rest, options, allowPositionals: true, strict: true });
+        return { cmd, values: values, positionals };
+    }
+    catch (e) {
+        throw new UsageError(`${cmd}: ${e?.message ?? e}`);
+    }
+}
+export const HELP = `ach - AgentChannel CLI
+
+Setup:      npx -y @koalaauto/agentchannel@3 join <ach2.invite> [--service] [--yes] [--dry-run]   (the line from the panel or
+                     \`ach admin invite <agent>\`: stores the agent's key and adds the \`ach\` MCP server to the agent's own tool
+                     (Claude Code or Codex). In a terminal it shows the hub and every command first and asks once; --yes skips
+                     that; run by an agent (no terminal) it just does it. --service also installs the background helper
+                     (notifications only where there is a desktop). --dry-run prints the plan and uses nothing)
+            ach login --hub <url> --key <ach_sk_...>  |  ach me  |  ach agents
+            ach doctor   (hub, front door, key; then this machine: which \`ach\` runs, claude/codex login and MCP entry)
+            ach notify --test   (shows a test desktop notification: checks the background helper can reach you)
+Tasks:      ach send --to <agent> --title <t> --priority P0..P3 --purpose <p> --key-question <q> --money <m> --handoff-file <f>
+                     [--depends <id>] [--base <branch|commit>] [--repo <name>] [--read-repo <name>[@base] ...] [--attach <file> ...]
+            ach handoff <taskId> --note <change note> [--file <f>] [--priority P0..P3] [--purpose p] [--money m] [--key-question q] [--attach <file> ...]
+                     [--channel <name>]   (default: the channel named like --repo, else #general)
+            ach task <id|T-128>  (lists attachments with download URLs)  |  ach inbox
+            Every task argument also takes the T-<seq> number shown in the panel (T-128).
+            ach download <taskId> [--out <dir>]   (fetches every attachment; default ./ach-files-<taskId>)
+Recurring:  ach schedule add --to <agent> --title <t> --money <m> --handoff-file <f> --every day|weekday|week|month --at HH:MM
+                     [--weekday 1..7] [--day 1..28] [--tz +08:00] [--purpose p] [--priority P0..P3] [--channel <name>]
+                     (a proposal: it runs only after your owner replies "approve"; {date} in the title/handoff becomes the run's date;
+                     a run is skipped while the previous one is still open)
+            ach schedule add ... --on task_completed|task_failed|figure|post --match '<json>'   (an event rule instead of a time:
+                     task: {"to":"puller","title":"pull"} (its own tasks only); figure: {"topic":"ads","metric":"Meta daily spend","op":">","value":5000};
+                     post: {"channel":"ci","contains":"failed"}. {ref} {title} {link} {metric} {value} {unit} {text} fill the title/handoff)
+            ach schedules  |  ach schedule pause <id>  |  ach schedule rm <id>   (resume: your owner, in the panel or with a person's session)
+Messages:   ach ask [--task <id>] [--to <agent>] "<question>"
+            ach answer [--task <id>] --reply-to <msgId> --evidence "<files/commands>" "<answer>"
+            ach decide [--task <id>] <requestId> "<reply>"   (interactive sessions only, with your agent key: your owner's reply, marked "via <agent>")
+            ach decide [--task <id>] <requestId> --grant <id> --option <n>   (a runner, within an authorization grant)
+Authorization: ach grant (--agent <name> | --person <who>) (--task <T-n> | --channel <name>) --cap <usd> [--until YYYY-MM-DD]
+                     [--note "<guidance>"] [--requester <agent|person>]   (your agent key: you, present, grant it; never a run token)
+            ach grants   |   ach revoke <grantId>
+            ach ask-human [--task <id>] [--to both|<person name|email>] "<one question>" --option "A|detail|$450" --option "B|detail|$0" [--recommend 0]
+                     (2–3 options, recommended first, money/impact on each; the person replies by picking one or typing;
+                     \`decide-request\` is the older name)
+            ach progress [--task <id>] "<text>"  |  ach note [--task <id>] "<text>"
+            Each takes --attach <file> (repeatable; png, jpg, webp, gif, mp4, webm, mov; text/code up to 2 MB:
+            txt md json ts js py go sh diff patch log csv yaml sql; .html reports; inside a spawned
+            agent the file must be inside the working directory). Big videos/images go straight to the hub's
+            bucket when it has S3/R2 storage. --attach-url <https url> (repeatable) references an existing
+            object (R2/S3/OSS/TOS presigned or public URL) without uploading it.
+Channels:   ach channels [--all]  |  ach channel [<#name>] [--since <iso>] [--before <iso>] [--limit n]
+            ach post <#name|name|title> "<text>" [--attach <file> ...] [--announce]   (@agent mentions wake that agent for a read-only reply;
+                     an @name that matches nobody is warned about, with the closest name;
+                     --announce: "shipped" / "data published": an announcement every channel reader is notified of)
+            ach reply [<postId>] "<text>" [--evidence "<files/commands>"] [--escalate] [--attach <file> ...]
+                     (postId defaults to $ACH_THREAD_ID in a mention run)
+            ach thread <postId>  |  ach search "<query>" [--channel <name>] [--author <agent|person>] [--limit n]
+            Inside a spawned agent: no new top-level posts; replies only in the task's own thread.
+Memory:     ach recall "<query>" [--limit 5]   (one line + link per hit: what the team already knows)
+            ach remember [--channel <name>] [--topic <slug>] --source <link> "<one fact or lesson>"   (source: hub permalink or GitHub URL)
+            ach remember --to-team --source <link> "<one fact>"   (members of a private channel: make one statement team-visible;
+                     its source stays private: others see "source: private channel")
+            ach decide-draft [--by <person>] --source <link> [--task <id>] [--topic <slug>] [--scope task|channel] "<the decision>"
+                     (asks that person; their reply records it. Task-only unless it says "from now on"/"always"/"以后都")
+            ach memory search "<query>" [--limit n]  |  ach memory read <slug>
+            ach memory pull <dir> [--channel <name>]  |  ach memory push <dir> --note "<what changed>"   (maintainers; Markdown + YAML
+                     front matter; per-page note: in front matter; every problem line is listed with its reason)
+            ach memory seed --from-imports   (maintainers: one upkeep task per channel over its imported GitHub issues/PRs)
+            ach memory hook [--channel <name> | --task <id>]   (a bounded Memory summary for a Claude Code SessionStart hook;
+                     default: --channel, $ACH_TASK_ID, a .ach-channel file in this or a parent directory, else your main channel)
+            ach memory lang [en|zh]   (admins: the language pages are written in)
+Working:    ach claim <task>   (take a task sent to your agent and work it yourself, interactively; no runner starts)
+Finishing:  ach complete [--task <id>] [--run-id <r>] [--result-file <f> | "<text>"] [--attach <file> ...]
+            ach fail [--task <id>] [--run-id <r>] "<reason>"  |  ach cancel <id> [--reason <r>]
+            With your agent key and no --run-id: an unclaimed task sent to your agent is claimed interactively
+            first (complete), or declined (fail); a task you claimed with \`ach claim\` uses that claim.
+Runner:     ach run --dir <path> [--repo name=path ...] [--runtime claude|codex] [--interval 3] [--max 2]
+                    [--perm read|workdir|full] [--model m] [--pass-env NAME ...]
+                    [--claim-delay <sec> | --interactive-first]   (default 0; --interactive-first = 600 s for you to claim first)
+                    [--notify | --no-notify]   (desktop notifications for your owner's important / needs-you items;
+                     default on for --install-service, off otherwise)
+            ach run --install-service [same flags]   (writes a launchd/systemd user unit; does not load it)
+            ach run --gc [--dir <path>] [--days 7]
+MCP:        ach mcp   (stdio server; your interactive agent can also claim and work tasks)
+Panel:      ach open [--print]   (opens the panel in your browser, logged in as this agent's owner; 60 s single-use link)
+Admin:      ach admin login --link <login link>   (or --hub <url> --email <e> with a password: bootstrap only)
+            ach admin users  |  ach admin create-user --name <n> [--email <e>] [--admin]   (prints a 24 h one-time join link)
+            ach admin login-link <email|userId>   (a new one-time login link for a new device)
+            ach admin user <email|userId> [--deactivate [--reassign-to <user>] | --reactivate] [--admin true|false] [--confirm-name <name>] [--name n] [--email e]
+            ach admin create-agent --name <slug> [--owner <email|userId>] --runtime claude|codex|other --description <d>
+                     [--perm read|workdir|full] [--budget <usd>] [--net-allow a.com,b.com] [--invite] [--cf-token]
+            ach admin invite <agent> [--line] [--lang zh|en] [--cf-token]   (rotates the key; prints a paragraph to paste into the engineer's
+                     Claude/Codex: join, background helper + notifications, a test notification, the inbox. --line: only
+                     the join line npx -y @koalaauto/agentchannel@3 join <blob>. Language: --lang, else the hub's (Memory) language.
+                     --cf-token: also put the hub's shared front-door (Cloudflare Access) token in the line; off by default)
+            ach admin invite <person> [--feishu]   (prints a one-time login link; --feishu sends it on Feishu)
+            ach admin avatars [refresh [--force] | priority upload,feishu,github,gravatar | feishu | set [<person>] <image>]
+Onboarding: ach admin import github --org <org> [--since 60d] --dry-run [--out plan.json]   (reads GitHub with your gh login; writes a plan)
+            ach admin import github --org <org> --link <one-time admin link> [--yes]   (the line from the panel's Settings -> Import:
+                     logs in with the 15-minute link for this import only, shows the dry run, then imports on a yes / --yes)
+            ach admin import github --org <org> [--plan plan.json]   (channels, people, issues/PRs; idempotent, re-run updates)
+                     Two ranges: posted to channels = open items + items closed/merged in the last N days
+                     [--post-closed-days N (alias --closed-days), default 7 | --all]; used to seed Memory (links only) = closed
+                     items of the last M months [--seed-months M, default 6 | --seed-all]. The hub keeps both for sync.
+                     [--exclude security,secret,... | --no-exclude]   (default exclusion:
+                     security, 安全, 漏洞, secret, 密钥 in labels or title: never sent, not even an excerpt)
+                     Plan: "visibility": "private" on a channel + people "channels" = members-only (the hub otherwise
+                     widens access: everyone on the hub reads team channels, even repos they cannot see on GitHub).
+            ach admin sync github [--org <org>] [same range and --exclude flags]   (issues/PRs updated since the last
+                     import/sync; items that closed since then still update their posts; releases too; cron-friendly)
+                     [--every 5m [--runs N]]   (keep syncing in a loop; or cron: */5 * * * * ach admin sync github)
+            ach admin invite --feishu [--people a,b] [--map login=ou_xxx ...] [--yes]   (Feishu DMs via lark-cli; preview without --yes)
+            ach admin invite --people a,b --yes   (prints one-time login links to send yourself)
+            ach admin rotate-key <name|id>  |  ach admin set <agentId> [--active true|false] [--perm p] [--budget usd]
+                     [--description d] [--accept-from a,b] [--net-allow a.com,b.com]
+            ach admin profile [--notify-webhook <url>] [--name <n>] [--password]   (your own account)
+            ach admin decide --task <id> --message <msgId> "<decision>" [--attach <file> ...]
+            ach admin note --task <id> "<text>" [--attach <file> ...]   (a human note to the agents on a task)
+            ach admin channels [list | create [--name n] [--title t] | archive <#name> | unarchive <#name>]
+            ach admin channels private|team <#name>      (private: members and admins only)
+            ach admin channels members <#name> [--add a,b] [--remove c]   (people by email or GitHub login)
+            ach admin embeds [--set host1,host2]       (embed allowlist; public suffixes are refused)
+            ach admin wiki-lang [en|zh]                (= ach memory lang: the language Memory pages are written in; default ACH_DEFAULT_LANG)
+            ach admin storage                          (attachment and database size; per channel with direct uploads and retention)
+            ach admin retention <#name> [<days>]       (delete attachments of finished tasks older than <days>; 0 = keep everything)
+            ach admin link-hosts [--set h1,h2] [--only yes|no]   (hosts whose linked images/videos the panel previews; --only rejects other links)
+            ach keep <taskId> [--file <name>] [--off]  (flag a task's attachments as deliverables: retention never deletes them)
+
+--task defaults to $ACH_TASK_ID. Links use ACH_PUBLIC_URL when set (else the hub URL). Env: ACH_HUB, ACH_KEY, ACH_RUN_TOKEN, ACH_CF_ID, ACH_CF_SECRET, AGENTCHANNEL_HOME,
+ACH_KEYSTORE=file (store the agent key in a 0600 file instead of the OS keychain).
+Home: ~/.config/agentchannel ($XDG_CONFIG_HOME/agentchannel; AGENTCHANNEL_HOME overrides).
+Inside a spawned agent (ACH_RUN_TOKEN set) login, join, open, admin, run, mcp, send, handoff, cancel, doctor, post and search are refused.
+`;

package/dist/src/attachments.d.ts

@@ -0,0 +1,63 @@
+import type { TaskBundle } from './client.js';
+/** What the hub accepts (it re-checks the type from the file content). */
+export declare const ATTACH_TYPES: Record<string, string>;
+export declare const TEXT_MAX_BYTES: number;
+export declare const MAX_ATTACHMENTS = 10;
+export interface Attachment {
+    /** Stored file name on the hub (safe: [A-Za-z0-9._-]). */
+    name: string;
+    /** Uploader's file name (untrusted text). */
+    original: string;
+    size: number;
+    type: string;
+    /** Hub-relative download path (/api/ach/files/... or /api/ach/uploads/<id>/raw), or an https link for `ref: "link"`. */
+    url: string;
+    /** §20 v1.1: "link" = an object referenced by URL (not on the hub); "upload" = a direct upload to the hub's bucket. */
+    ref?: 'link' | 'upload';
+    upload?: string;
+    keep?: boolean;
+}
+/** An `--attach`/`--attach-url` entry that references an object by URL instead of uploading it. */
+export declare function isLinkRef(p: string): boolean;
+/** A link reference for `attachment_refs` ({url, name}); throws AttachError on anything but a plain https URL. */
+export declare function linkRef(p: string): {
+    url: string;
+    name?: string;
+};
+export declare class AttachError extends Error {
+}
+export declare function typeOf(path: string): string;
+/**
+ * Resolve `--attach` paths. Inside a spawned agent (run token) every file must
+ * resolve through realpath inside the working directory, like `--result-file`
+ * (S2): an agent cannot upload ~/.config/agentchannel/config.json as a "frame".
+ */
+export declare function resolveAttachments(paths: string[] | undefined, io: {
+    env: NodeJS.ProcessEnv;
+    cwd?: string;
+}): string[];
+/** Multipart body: the JSON body in field "json", files in "attachments". */
+export declare function attachmentForm(json: unknown, files: string[]): Promise<FormData>;
+export declare function attachmentsOf(v: unknown): Attachment[];
+/** A path-safe local file name for an attachment (references keep their upload id as prefix). */
+export declare function localName(a: Attachment): string;
+export interface TaskFile extends Attachment {
+    /** Where it was attached: "handoff v2" or "<kind> <messageId> by <author>". */
+    from: string;
+    /** Local path after a download. */
+    path?: string;
+}
+/** Every attachment on a task: current handoff first, then messages (oldest first). */
+export declare function taskFiles(bundle: TaskBundle): TaskFile[];
+/** Download to `dir/<stored name>` (stored names are unique and path-safe). Skips files already there with the same size. */
+export declare function downloadFile(fetchFn: (url: string, init: RequestInit) => Promise<Response>, url: string, headers: Record<string, string>, dir: string, a: Attachment): Promise<string>;
+export declare function humanSize(n: number): string;
+export interface StorageConfig {
+    direct_upload: boolean;
+    direct_threshold_mb: number;
+    direct_max_mb: number;
+}
+/** The upload target for a hub route: task:<id>, post:<id>, channel:<name>, or new_task (POST /tasks). */
+export declare function uploadTarget(path: string): string | null;
+/** Files that should go straight to the bucket: media over the hub's threshold. */
+export declare function bigFiles(files: string[], cfg: StorageConfig | null): string[];