@koalaauto/agentchannel 0.0.0-stage → 3.0.0

package/dist/src/names.js

@@ -0,0 +1,108 @@
+// Name helpers for `ach post` (channel by name/title, @name check) and
+// `ach ask-human --to` (closest-name suggestions). Pure; the hub stays the
+// authority (it parses mentions and validates `to_user` itself).
+import { HubError } from './client.js';
+/** Same shape as the hub's MENTION_RE (ach_lib.js); code spans/blocks ignored. */
+const MENTION_RE = /(^|[^A-Za-z0-9_.\/-])@([a-z0-9][a-z0-9-]{1,40})(?![A-Za-z0-9-])/g;
+export function mentionNames(text) {
+    const plain = String(text).replace(/```[\s\S]*?```/g, ' ').replace(/`[^`\n]*`/g, ' ');
+    const out = [];
+    for (const m of plain.matchAll(MENTION_RE))
+        if (!out.includes(m[2]))
+            out.push(m[2]);
+    return out;
+}
+export function editDistance(a, b) {
+    const d = Array.from({ length: b.length + 1 }, (_, j) => j);
+    for (let i = 1; i <= a.length; i++) {
+        let prev = d[0];
+        d[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const cur = d[j];
+            d[j] = Math.min(d[j] + 1, d[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1));
+            prev = cur;
+        }
+    }
+    return d[b.length];
+}
+/** Closest candidate (case-insensitive), or undefined when nothing is near. */
+export function closest(name, candidates) {
+    const n = name.toLowerCase();
+    let best;
+    let bd = Infinity;
+    for (const c of candidates) {
+        const l = c.toLowerCase();
+        const d = l.startsWith(n) || n.startsWith(l) ? Math.min(1, editDistance(n, l)) : editDistance(n, l);
+        if (d < bd)
+            [best, bd] = [c, d];
+    }
+    return best !== undefined && bd <= Math.max(2, Math.floor(n.length / 3)) ? best : undefined;
+}
+/** "Ops Data" / "ops-data" / "#ops-data" -> the channel's name, by name or title. */
+export function matchChannel(ref, channels) {
+    const r = String(ref).trim().replace(/^#/, '');
+    const low = r.toLowerCase();
+    const norm = (s) => s.toLowerCase().replace(/[\s_]+/g, '-');
+    return (channels.find((c) => c.name === r) ??
+        channels.find((c) => c.name.toLowerCase() === low) ??
+        channels.find((c) => String(c.title ?? '').trim().toLowerCase() === low) ??
+        channels.find((c) => norm(c.name) === norm(r)));
+}
+/** Handles a person can be written as after @: "Evan Li" -> "evan-li", email local part. */
+export function personHandles(p) {
+    const out = new Set();
+    const n = String(p.name ?? '').trim().toLowerCase();
+    if (n) {
+        out.add(n.replace(/\s+/g, '-'));
+        out.add(n.replace(/\s+/g, ''));
+        out.add(n.split(/\s+/)[0]);
+    }
+    const local = String(p.email ?? '').split('@')[0].toLowerCase();
+    if (local)
+        out.add(local);
+    return [...out].filter(Boolean);
+}
+/** @names in `body` that match no agent or person, each with the closest known name. */
+export function unknownMentions(body, agents, people) {
+    const agentNames = agents.map((a) => a.name).filter(Boolean);
+    const handles = new Map();
+    for (const p of people)
+        for (const h of personHandles(p))
+            handles.set(h, h);
+    const known = new Set([...agentNames.map((a) => a.toLowerCase()), ...handles.keys()]);
+    return mentionNames(body)
+        .filter((n) => !known.has(n.toLowerCase()))
+        .map((n) => ({ name: n, suggest: closest(n, [...agentNames, ...handles.keys()]) }));
+}
+/**
+ * `--to`: omitted = your owner (the hub may add the other side for money), "self" = only your
+ * owner, "both" = both owners, anything else names a person (`to_user`).
+ */
+export function decisionTo(to) {
+    const t = String(to ?? '').trim();
+    if (!t)
+        return {};
+    if (t === 'self' || t === 'both')
+        return { to: t };
+    return { to_user: t.replace(/^@/, '') };
+}
+/** Turns the hub's to_user refusals into one line an agent can act on. */
+export async function explainToUser(e, person, c, taskId) {
+    if (!(e instanceof HubError))
+        return e;
+    const body = e.body ?? {};
+    if (e.status === 403 && e.code === 'not_member') {
+        const ch = await c.getTask(taskId).then((r) => r?.task?.channel_name).catch(() => '');
+        return new HubError(e.status, `${person} is not a member of ${ch ? `#${ch}` : "this task's channel"}; ask someone in the channel (or omit --to to ask your owner)`, e.code, e.body);
+    }
+    if (e.status === 400 && e.code === 'ambiguous') {
+        const cands = (Array.isArray(body.candidates) ? body.candidates : []).map((x) => `${x.name}${x.email ? ` <${x.email}>` : ''}`);
+        return new HubError(e.status, `more than one person is called ${person}${cands.length ? ` (${cands.join(', ')})` : ''}; use --to <email>`, e.code, e.body);
+    }
+    if (e.status === 404 && !/task/i.test(String(body.error ?? body.message ?? ''))) {
+        const owners = await c.agents().then((a) => [...new Set(a.map((x) => x.owner_name ?? '').filter(Boolean))]).catch(() => []);
+        const near = closest(person, owners);
+        return new HubError(e.status, `no active person "${person}"${near ? ` (did you mean ${near}?)` : ''}; use their name or email as the hub knows it`, e.code, e.body);
+    }
+    return e;
+}

package/dist/src/netproxy.d.ts

@@ -0,0 +1,20 @@
+type Env = Record<string, string | undefined>;
+/**
+ * Which proxy, if any, hub requests use. Node's fetch ignores HTTP(S)_PROXY, so
+ * without this `ach` cannot leave a sandbox that only allows its proxy (live
+ * test: inside a Claude worker, plain fetch got ENOTFOUND for public hosts and
+ * EPERM for 127.0.0.1, while the proxy reached both).
+ * - Inside a spawned agent (ACH_RUN_TOKEN): every request goes through the
+ *   proxy, NO_PROXY included, because the sandbox blocks direct connections.
+ * - Elsewhere: the usual HTTP(S)_PROXY / NO_PROXY rules.
+ * Pure, unit-tested; returns null when no proxy is configured.
+ */
+export declare function proxyPlan(env: Env, hub?: string): {
+    kind: 'all';
+    uri: string;
+} | {
+    kind: 'env';
+} | null;
+/** Install the proxy for this process's fetch (global dispatcher). */
+export declare function installProxy(env?: Env, hub?: string | undefined): void;
+export {};

package/dist/src/netproxy.js

@@ -0,0 +1,36 @@
+import { EnvHttpProxyAgent, ProxyAgent, setGlobalDispatcher } from 'undici';
+function proxyFrom(env, https) {
+    const pick = (...names) => names.map((n) => env[n]).find((v) => !!v && v.trim()) ?? '';
+    return https ? pick('HTTPS_PROXY', 'https_proxy', 'ALL_PROXY', 'all_proxy') : pick('HTTP_PROXY', 'http_proxy', 'ALL_PROXY', 'all_proxy');
+}
+/**
+ * Which proxy, if any, hub requests use. Node's fetch ignores HTTP(S)_PROXY, so
+ * without this `ach` cannot leave a sandbox that only allows its proxy (live
+ * test: inside a Claude worker, plain fetch got ENOTFOUND for public hosts and
+ * EPERM for 127.0.0.1, while the proxy reached both).
+ * - Inside a spawned agent (ACH_RUN_TOKEN): every request goes through the
+ *   proxy, NO_PROXY included, because the sandbox blocks direct connections.
+ * - Elsewhere: the usual HTTP(S)_PROXY / NO_PROXY rules.
+ * Pure, unit-tested; returns null when no proxy is configured.
+ */
+export function proxyPlan(env, hub) {
+    const https = !hub || hub.startsWith('https:');
+    const uri = proxyFrom(env, https);
+    if (!uri)
+        return null;
+    return env.ACH_RUN_TOKEN ? { kind: 'all', uri } : { kind: 'env' };
+}
+/** Install the proxy for this process's fetch (global dispatcher). */
+export function installProxy(env = process.env, hub = env.ACH_HUB) {
+    const plan = proxyPlan(env, hub);
+    if (!plan)
+        return;
+    let d;
+    try {
+        d = plan.kind === 'all' ? new ProxyAgent(plan.uri) : new EnvHttpProxyAgent();
+    }
+    catch {
+        return; // a malformed proxy URL: keep direct connections
+    }
+    setGlobalDispatcher(d);
+}

package/dist/src/onboard.d.ts

@@ -0,0 +1,105 @@
+import type { ExecLike } from './doctor.js';
+/**
+ * One-line onboarding: what `ach join` sets up after the key is stored.
+ *
+ *   1. connect: add the `ach` MCP server to the agent's own tool (Claude Code
+ *      for a claude agent, Codex for a codex one; both found ones for "other")
+ *   2. background helper, only with --service: `ach run --install-service`
+ *      (+ --notify on a machine with a desktop). Run through npx, `ach` is
+ *      installed first, so the helper never runs from the npx cache.
+ *
+ * Pasting the line is the consent: with no terminal (an agent ran it) the steps
+ * run and say what they ran. In a terminal each step lists its commands and
+ * files and asks first; --yes skips that. --dry-run prints the plan and changes
+ * nothing (the invite stays unused).
+ */
+export interface SetupIo {
+    env: NodeJS.ProcessEnv;
+    out: (s: string) => void;
+    err: (s: string) => void;
+    exec: ExecLike;
+    /** Asks one question; undefined = not interactive. */
+    ask?: (q: string) => Promise<string>;
+    cwd: string;
+}
+export interface SetupOptions {
+    yes: boolean;
+    /** Install the background helper (step 2). */
+    service?: boolean;
+    /** Print the plan only. */
+    dryRun?: boolean;
+    runtime?: string;
+    zh?: boolean;
+    /** This CLI's entry (tests). */
+    self?: string;
+    /** --dry-run: `ach join` has not used the invite yet; print that step too. */
+    join?: {
+        hub: string;
+    };
+}
+export type Argv = string[];
+export interface Step {
+    id: 'connect' | 'service';
+    question: string;
+    /** Commands, printed as shell lines and run one by one. */
+    commands: Argv[];
+}
+/** The closing line: which tool to open and what to say to it. */
+export declare function doneLine(tools: ('claude' | 'codex')[], zh: boolean): string;
+/** A desktop to show notifications on: macOS, Windows, or Linux with a display. */
+export declare function hasDesktop(env: NodeJS.ProcessEnv, platform?: string): boolean;
+/** The tools an agent of this runtime is added to: its own; both for "other" or unknown. */
+export declare function toolsFor(runtime: string | undefined): ('claude' | 'codex')[];
+/** True when this CLI runs from the npx cache (it disappears; install it first). */
+export declare function runFromNpx(self?: string): boolean;
+export declare function shq(s: string): string;
+export declare function shellLine(a: Argv): string;
+/** `claude mcp add` / `codex mcp add` argv for this CLI. */
+export declare function mcpAddArgv(kind: 'claude' | 'codex', bin: string, achCmd: Argv, home?: string): Argv;
+export declare function mcpRemoveArgv(kind: 'claude' | 'codex', bin: string, name: string): Argv;
+/**
+ * The file `claude mcp add --scope user` / `codex mcp add` writes:
+ * $CLAUDE_CONFIG_DIR/.claude.json (else ~/.claude.json), $CODEX_HOME/config.toml
+ * (else ~/.codex/config.toml).
+ */
+export declare function mcpConfigFile(kind: 'claude' | 'codex', env: NodeJS.ProcessEnv): string;
+export interface Detected {
+    /** User-installed claude / codex (never the bins npx puts on PATH). */
+    claude?: string;
+    codex?: string;
+    npm?: string;
+    npx: boolean;
+    /** An `ach` entry already registered (it is replaced). */
+    claudeHasAch: boolean;
+    codexHasAch: boolean;
+    /** How the MCP entry and service start ach: the pinned npx spec when run through npx, else an absolute `ach`. */
+    achCmd: Argv;
+}
+/** The absolute command that starts this CLI: the first `ach` on PATH when it is this package, else node + this file. */
+export declare function absoluteAch(env: NodeJS.ProcessEnv, self: string): Argv;
+/**
+ * What is on this machine. `probe` = also ask claude/codex (read-only
+ * `mcp get`); without it only PATH is looked at.
+ */
+export declare function detect(env: NodeJS.ProcessEnv, exec: ExecLike, self: string, probe: boolean): Promise<Detected>;
+/** The steps that apply on this machine, in order. */
+export declare function planSteps(d: Detected, o: {
+    home?: string;
+    achCmd: Argv;
+    installSpec: string;
+    cwd: string;
+    zh?: boolean;
+    env?: NodeJS.ProcessEnv;
+    runtime?: string;
+    service?: boolean;
+    desktop?: boolean;
+}): Step[];
+export interface SetupResult {
+    ran: string[];
+    skipped: string[];
+    failed: string[];
+    /** The tools the agent was added to (for the closing line). */
+    tools: ('claude' | 'codex')[];
+}
+/** Run (or, with --dry-run, only print) the setup after `ach join`. */
+export declare function runSetup(io: SetupIo, o: SetupOptions): Promise<SetupResult>;

package/dist/src/onboard.js

@@ -0,0 +1,270 @@
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { identifyAch, isOurs, MCP_SERVER_NAME, npmSpec, npxAch, thisCliPath, userBin, whichAll } from './invite.js';
+import { VERSION } from './version.js';
+/** The closing line: which tool to open and what to say to it. */
+export function doneLine(tools, zh) {
+    const names = [...new Set(tools)].map((k) => (k === 'claude' ? 'Claude Code' : 'Codex'));
+    const where = names.length ? names.join(zh ? ' 或 ' : ' or ') : zh ? '你的 Claude Code 或 Codex' : 'your Claude Code or Codex';
+    return zh ? `完成。打开 ${where}，对它说：看看我的 AgentChannel 收件箱` : `Done. Open ${where} and say: check my AgentChannel inbox`;
+}
+/** A desktop to show notifications on: macOS, Windows, or Linux with a display. */
+export function hasDesktop(env, platform = process.platform) {
+    if (platform === 'darwin' || platform === 'win32')
+        return true;
+    return !!(env.DISPLAY || env.WAYLAND_DISPLAY);
+}
+/** The tools an agent of this runtime is added to: its own; both for "other" or unknown. */
+export function toolsFor(runtime) {
+    return runtime === 'claude' ? ['claude'] : runtime === 'codex' ? ['codex'] : ['claude', 'codex'];
+}
+/** True when this CLI runs from the npx cache (it disappears; install it first). */
+export function runFromNpx(self = thisCliPath()) {
+    return /[\\/]_npx[\\/]/.test(self);
+}
+export function shq(s) {
+    return /^[A-Za-z0-9_./:=@+-]+$/.test(s) ? s : `'${s.replace(/'/g, `'\\''`)}'`;
+}
+export function shellLine(a) {
+    return a.map(shq).join(' ');
+}
+/** `claude mcp add` / `codex mcp add` argv for this CLI. */
+export function mcpAddArgv(kind, bin, achCmd, home) {
+    if (kind === 'claude')
+        return [bin, 'mcp', 'add', '--scope', 'user', ...(home ? ['-e', `AGENTCHANNEL_HOME=${home}`] : []), MCP_SERVER_NAME, '--', ...achCmd, 'mcp'];
+    return [bin, 'mcp', 'add', ...(home ? ['--env', `AGENTCHANNEL_HOME=${home}`] : []), MCP_SERVER_NAME, '--', ...achCmd, 'mcp'];
+}
+export function mcpRemoveArgv(kind, bin, name) {
+    return kind === 'claude' ? [bin, 'mcp', 'remove', '--scope', 'user', name] : [bin, 'mcp', 'remove', name];
+}
+/**
+ * The file `claude mcp add --scope user` / `codex mcp add` writes:
+ * $CLAUDE_CONFIG_DIR/.claude.json (else ~/.claude.json), $CODEX_HOME/config.toml
+ * (else ~/.codex/config.toml).
+ */
+export function mcpConfigFile(kind, env) {
+    const home = env.HOME || homedir();
+    if (kind === 'claude')
+        return env.CLAUDE_CONFIG_DIR ? join(env.CLAUDE_CONFIG_DIR, '.claude.json') : join(home, '.claude.json');
+    return join(env.CODEX_HOME || join(home, '.codex'), 'config.toml');
+}
+/** The absolute command that starts this CLI: the first `ach` on PATH when it is this package, else node + this file. */
+export function absoluteAch(env, self) {
+    const first = whichAll('ach', env)[0];
+    if (first && isOurs(identifyAch(first, self)))
+        return [first];
+    return [process.execPath, self];
+}
+/**
+ * What is on this machine. `probe` = also ask claude/codex (read-only
+ * `mcp get`); without it only PATH is looked at.
+ */
+export async function detect(env, exec, self, probe) {
+    const claude = userBin('claude', env);
+    const codex = userBin('codex', env);
+    const npx = runFromNpx(self);
+    const d = {
+        claude, codex, npm: whichAll('npm', env)[0], npx,
+        claudeHasAch: false, codexHasAch: false,
+        // run through npx: the MCP entry uses the same pinned spec as the join line
+        achCmd: npx ? npxAch() : absoluteAch(env, self),
+    };
+    if (!probe)
+        return d;
+    const has = async (bin) => !!bin && (await exec(bin, ['mcp', 'get', MCP_SERVER_NAME], env)).code === 0;
+    d.claudeHasAch = await has(claude);
+    d.codexHasAch = await has(codex);
+    return d;
+}
+/** "Claude Code and Codex" / "Claude Code" / "Codex" / "" */
+function targets(d, zh) {
+    const t = [d.claude ? 'Claude Code' : '', d.codex ? 'Codex' : ''].filter(Boolean);
+    return t.join(zh ? ' 和 ' : ' and ');
+}
+const changes = (kind, env, zh) => `${zh ? '修改' : 'changes'} ${mcpConfigFile(kind, env)}`;
+/** The steps that apply on this machine, in order. */
+export function planSteps(d, o) {
+    const zh = !!o.zh;
+    const env = o.env ?? {};
+    const steps = [];
+    const want = toolsFor(o.runtime);
+    // 1. connect: the MCP entry in the agent's own tool
+    const connect = { id: 'connect', question: '', commands: [] };
+    const lines = [];
+    for (const kind of want) {
+        const bin = d[kind];
+        if (!bin)
+            continue;
+        if (kind === 'claude' ? d.claudeHasAch : d.codexHasAch)
+            connect.commands.push(mcpRemoveArgv(kind, bin, MCP_SERVER_NAME));
+        const add = mcpAddArgv(kind, bin, o.achCmd, o.home);
+        connect.commands.push(add);
+        lines.push(`  ${shellLine([kind, ...add.slice(1)])}    # ${changes(kind, env, zh)}`);
+    }
+    if (lines.length) {
+        const where = targets({ claude: want.includes('claude') ? d.claude : undefined, codex: want.includes('codex') ? d.codex : undefined }, zh);
+        connect.question = [zh ? `把 AgentChannel 接入 ${where}？会运行：` : `Add AgentChannel to ${where}? This runs:`, ...lines].join('\n') + '\n';
+        steps.push(connect);
+    }
+    // 2. background helper: only when asked for (--service)
+    if (o.service) {
+        const notify = o.desktop !== false;
+        const helper = ['run', '--install-service', ...(notify ? ['--notify'] : []), '--interactive-first', '--dir', o.cwd];
+        const install = d.npx && d.npm ? [[d.npm, 'install', '-g', o.installSpec]] : [];
+        steps.push({
+            id: 'service',
+            question: [
+                zh
+                    ? `安装后台小助手（在 ${o.cwd} 里自动领取任务${notify ? '，并弹出系统通知' : ''}）？会运行：`
+                    : `Install the background helper (picks up tasks in ${o.cwd}${notify ? ' and shows desktop notifications' : ''})? This runs:`,
+                ...install.map(() => `  npm install -g ${o.installSpec}    # ${zh ? '`ach` 命令（后台小助手不能从 npx 缓存运行）' : 'the `ach` command (the helper cannot run from the npx cache)'}`),
+                `  ${shellLine(['ach', ...helper])}`,
+            ].join('\n') + '\n',
+            commands: [...install, [...o.achCmd, ...helper]],
+        });
+    }
+    return steps;
+}
+function yesNo(answer) {
+    const a = answer.trim().toLowerCase();
+    return !a || /^(y|yes|是|好|ok)$/.test(a);
+}
+/** The global `ach` after `npm install -g` (npm prefix -g)/bin/ach. */
+async function globalAch(npm, exec, env) {
+    const r = await exec(npm, ['prefix', '-g'], env);
+    const prefix = r.stdout.trim().split('\n').pop()?.trim();
+    if (r.code !== 0 || !prefix)
+        return undefined;
+    const f = process.platform === 'win32' ? join(prefix, 'ach.cmd') : join(prefix, 'bin', 'ach');
+    return existsSync(f) ? f : undefined;
+}
+/** Run (or, with --dry-run, only print) the setup after `ach join`. */
+export async function runSetup(io, o) {
+    const env = io.env;
+    const self = o.self ?? thisCliPath();
+    const d = await detect(env, io.exec, self, !o.dryRun);
+    const installSpec = npmSpec(VERSION);
+    const home = env.AGENTCHANNEL_HOME || undefined;
+    const result = { ran: [], skipped: [], failed: [], tools: [] };
+    const zh = !!o.zh;
+    const desktop = hasDesktop(env);
+    const plan = planSteps(d, { home, achCmd: d.achCmd, installSpec, cwd: io.cwd, zh, env, runtime: o.runtime, service: o.service, desktop });
+    if (o.dryRun) {
+        printOnly(io, d, plan, { zh, join: o.join });
+        return result;
+    }
+    const ask = async (s) => {
+        // no terminal (an agent ran the line) or --yes: the line itself was the consent; say what runs
+        if (o.yes || !io.ask) {
+            io.out(s.question.replace(/[？?] ?(会运行：|This runs:)/, (_m, w) => (zh ? `。${w}` : `. ${w}`)).trimEnd());
+            return true;
+        }
+        return yesNo(await io.ask(`${s.question}[Y/n] `));
+    };
+    const runCmds = async (cmds) => {
+        // each program's commands are independent: a failed `claude mcp add` still lets `codex mcp add` run
+        const failedBins = new Set();
+        for (const c of cmds) {
+            if (failedBins.has(c[0]))
+                continue;
+            const r = await io.exec(c[0], c.slice(1), env);
+            if (r.code !== 0) {
+                // removing an entry that is not there is fine
+                if (c.includes('remove'))
+                    continue;
+                io.err(`  failed (exit ${r.code}): ${shellLine(c)}${r.stderr.trim() ? `\n  ${r.stderr.trim().split('\n')[0]}` : ''}`);
+                failedBins.add(c[0]);
+                continue;
+            }
+            const kind = c[0] === d.claude ? 'claude' : c[0] === d.codex ? 'codex' : undefined;
+            if (kind && c[1] === 'mcp') {
+                io.out(`  ${c[2] === 'add' ? (zh ? '已添加 MCP "ach" 到' : 'added MCP "ach" to') : zh ? `已从中删除 MCP "${c.at(-1)}"：` : `removed MCP "${c.at(-1)}" from`} ${mcpConfigFile(kind, env)}`);
+                if (c[2] === 'add')
+                    result.tools.push(kind);
+            }
+        }
+        return failedBins.size === 0;
+    };
+    for (const s of plan) {
+        if (!(await ask(s))) {
+            result.skipped.push(s.id);
+            continue;
+        }
+        if (s.id === 'service') {
+            // run through npx: install `ach` first; the helper then runs the installed one, never the npx cache
+            let helper = s.commands.at(-1);
+            if (s.commands.length > 1) {
+                if (!(await runCmds(s.commands.slice(0, -1)))) {
+                    result.failed.push('service');
+                    continue;
+                }
+                const g = await globalAch(d.npm, io.exec, env);
+                if (g)
+                    helper = [g, ...helper.slice(d.achCmd.length)];
+            }
+            const ok = await installAndStartService(io, helper);
+            (ok ? result.ran : result.failed).push('service');
+            continue;
+        }
+        const ok = await runCmds(s.commands);
+        (ok ? result.ran : result.failed).push(s.id);
+    }
+    const want = toolsFor(o.runtime);
+    if (!want.some((k) => d[k])) {
+        const kind = want[0];
+        const name = kind === 'claude' ? 'Claude Code' : 'Codex';
+        io.out(zh ? `没有找到 ${name}。装好后再运行一次这行 join，或者手动执行：` : `${name} was not found. Install it and run the join line again, or add it yourself:`);
+        io.out(`  ${shellLine([kind, ...mcpAddArgv(kind, kind, d.achCmd, home).slice(1)])}    # ${changes(kind, env, zh)}`);
+    }
+    if (!o.service) {
+        const run = shellLine([...(d.npx ? d.achCmd : ['ach']), 'run', '--install-service', ...(desktop ? ['--notify'] : []), '--dir', io.cwd]);
+        io.out(zh ? `可选：让它在后台自动领任务：${run}` : `Optional, to have it pick up tasks in the background: ${run}`);
+    }
+    return result;
+}
+/** `ach run --install-service --json`, then start the unit (unless ACH_SERVICE_DIR points elsewhere: tests). */
+async function installAndStartService(io, argv) {
+    const env = io.env;
+    const r = await io.exec(argv[0], [...argv.slice(1), '--json'], env);
+    if (r.code !== 0) {
+        io.err(`  failed (exit ${r.code}): ${shellLine(argv)}${r.stderr.trim() ? `\n  ${r.stderr.trim().split('\n')[0]}` : ''}`);
+        return false;
+    }
+    let f;
+    try {
+        f = JSON.parse(r.stdout);
+    }
+    catch {
+        io.err('  could not read the service file location');
+        return false;
+    }
+    io.out(`  wrote ${f.path}`);
+    const starts = f.start.map((x) => x.replace(/\s+#.*$/, '')).filter((x) => !/loginctl/.test(x));
+    if (env.ACH_SERVICE_DIR) {
+        io.out(`  start it with: ${starts.join(' && ')}`);
+        return true;
+    }
+    for (const c of starts) {
+        const s = await io.exec('/bin/sh', ['-c', c], env);
+        if (s.code !== 0) {
+            io.err(`  failed (exit ${s.code}): ${c}`);
+            return false;
+        }
+    }
+    io.out('  started');
+    return true;
+}
+/** --dry-run: print what would be run (nothing is run, not even read-only probes). */
+function printOnly(io, d, plan, o) {
+    const zh = o.zh;
+    const out = [zh ? '演练：什么都没有改。会做的事：' : 'Dry run: nothing was changed. What it would do:'];
+    if (o.join) {
+        out[0] = zh ? '演练：什么都没有改，邀请还没有用掉，也没有保存密钥。会做的事：' : 'Dry run: nothing was changed; the invite is still unused and no key was stored. What it would do:';
+        out.push(zh ? `  用这个一次性邀请向 ${o.join.hub} 换取智能体密钥，并保存在本机` : `  exchange the one-time invite with ${o.join.hub} for the agent's key and store it on this machine`);
+    }
+    for (const s of plan)
+        out.push(s.question.trimEnd());
+    out.push('', `${zh ? '随时检查配置：' : 'Check the setup any time with: '}${shellLine([...(d.npx ? d.achCmd : ['ach']), 'doctor'])}`);
+    io.out(out.join('\n'));
+}

package/dist/src/perm.d.ts

@@ -0,0 +1,12 @@
+export type Perm = 'read' | 'workdir' | 'full';
+export declare const PERMS: readonly Perm[];
+export declare function isPerm(v: unknown): v is Perm;
+export declare function permRank(p: Perm): number;
+/** Lower of two permission levels. */
+export declare function minPerm(a: Perm, b: Perm): Perm;
+/**
+ * Effective perm for a run = min(hub perm_level, runner --perm).
+ * An unknown or missing hub level is treated as 'read' (fail closed).
+ * `full` therefore requires both the hub and the runner flag to say full.
+ */
+export declare function effectivePerm(hubLevel: unknown, flag: Perm): Perm;

package/dist/src/perm.js

@@ -0,0 +1,20 @@
+export const PERMS = ['read', 'workdir', 'full'];
+export function isPerm(v) {
+    return typeof v === 'string' && PERMS.includes(v);
+}
+export function permRank(p) {
+    return PERMS.indexOf(p);
+}
+/** Lower of two permission levels. */
+export function minPerm(a, b) {
+    return permRank(a) <= permRank(b) ? a : b;
+}
+/**
+ * Effective perm for a run = min(hub perm_level, runner --perm).
+ * An unknown or missing hub level is treated as 'read' (fail closed).
+ * `full` therefore requires both the hub and the runner flag to say full.
+ */
+export function effectivePerm(hubLevel, flag) {
+    const hub = isPerm(hubLevel) ? hubLevel : 'read';
+    return minPerm(hub, flag);
+}