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

package/dist/src/index.d.ts

@@ -0,0 +1,13 @@
+export * from './client.js';
+export * from './config.js';
+export * from './env.js';
+export * from './perm.js';
+export * from './prompts.js';
+export * from './adapters/index.js';
+export { Runner, gcWorktrees, secretPaths, openRequests, unseenReplies, budgetBlocked, approves, type RunnerOptions, type Job } from './runner/runner.js';
+export { GitWorkspace, isSensitivePath, parseRepoFlags, type Workspace } from './runner/workspace.js';
+export * from './invite.js';
+export * from './service.js';
+export * from './keystore.js';
+export { RunnerState } from './runner/state.js';
+export { main, VERSION } from './cli.js';

package/dist/src/index.js

@@ -0,0 +1,13 @@
+export * from './client.js';
+export * from './config.js';
+export * from './env.js';
+export * from './perm.js';
+export * from './prompts.js';
+export * from './adapters/index.js';
+export { Runner, gcWorktrees, secretPaths, openRequests, unseenReplies, budgetBlocked, approves } from './runner/runner.js';
+export { GitWorkspace, isSensitivePath, parseRepoFlags } from './runner/workspace.js';
+export * from './invite.js';
+export * from './service.js';
+export * from './keystore.js';
+export { RunnerState } from './runner/state.js';
+export { main, VERSION } from './cli.js';

package/dist/src/invite.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Everything a teammate needs to connect, in one copy-paste line: `ach join <blob>`,
+ * blob = `ach2.` + base64url(JSON {hub, join, cf_id?, cf_secret?}). `join` is a
+ * one-time token the client exchanges for the agent key (POST
+ * /api/ach/invite/exchange); once used or expired the line is worthless. The
+ * optional Cloudflare Access service token lets the CLI through the hub's front
+ * door. Send the line privately.
+ */
+export interface Invite {
+    hub: string;
+    /** The one-time join token. */
+    join: string;
+    cf_id?: string;
+    cf_secret?: string;
+}
+export declare const JOIN_TOKEN_RE: RegExp;
+export declare function encodeInvite(i: Invite): string;
+export declare function decodeInvite(blob: string): Invite;
+/**
+ * Hosts where plain http:// is acceptable: this machine (localhost,
+ * 127.0.0.1, ::1, *.localhost) and the reserved *.test names (local dev/test
+ * setups). Anything else must be https://.
+ */
+export declare function isLocalHost(hostname: string): boolean;
+/** True when a hub URL is https://, or http:// to a local host (isLocalHost). */
+export declare function hubTransportOk(hub: string): boolean;
+/**
+ * The npm spec in the join line: `@koalaauto/agentchannel@3` (the major), or the
+ * exact version for a prerelease (2.0.0-rc.3 is not matched by the range "2").
+ */
+export declare function npmSpec(version?: string): string;
+/** The one line a teammate pastes: npx fetches the CLI and `join` sets everything up. */
+export declare function joinLine(blob: string, version?: string): string;
+/** `npx -y @koalaauto/agentchannel@<spec>`: how messages and MCP entries start the CLI without relying on PATH. */
+export declare function npxAch(version?: string): string[];
+/** The join line minus the blob (for parsing tests and docs). */
+export declare const JOIN_LINE_RE: RegExp;
+/** What to tell the person who gets the line. */
+export declare const JOIN_HINT: string;
+/** The MCP server name printed for `claude mcp add` / `codex mcp add`. */
+export declare const MCP_SERVER_NAME = "ach";
+/** Every executable `name` on PATH, in PATH order (like `which -a`). */
+export declare function whichAll(name: string, env?: NodeJS.ProcessEnv): string[];
+/**
+ * True for executables that are not the user's own install: anything in an
+ * npx cache (`.../_npx/...`) or in a node_modules/.bin (e.g. npx puts this
+ * package's dependencies' bins, such as the `codex` of @openai/codex-sdk, on
+ * PATH while `npx agentchannel` runs).
+ */
+export declare function isBundledBin(p: string): boolean;
+/** The first user-installed `name` on PATH (bundled/npx-cache bins skipped). */
+export declare function userBin(name: string, env?: NodeJS.ProcessEnv): string | undefined;
+/** True when an executable `name` is on PATH. */
+export declare function onPath(name: string, env?: NodeJS.ProcessEnv): boolean;
+/** This CLI's entry file (dist/src/cli.js). */
+export declare function thisCliPath(): string;
+/**
+ * Which AgentChannel an `ach` executable is, without running it: follow the
+ * symlink (npm global bins are symlinks) up to the nearest package.json.
+ * `ours` = it is this very CLI.
+ */
+export declare function identifyAch(path: string, self?: string): {
+    path: string;
+    real?: string;
+    name?: string;
+    version?: string;
+    ours: boolean;
+};
+/** True for an `ach` of this package (this CLI, or another install of it). */
+export declare function isOurs(i: {
+    ours: boolean;
+    name?: string;
+}): boolean;
+/**
+ * The exact `claude mcp add` / `codex mcp add` commands for this machine. They
+ * are printed, never run. `achCmd` is how to start the CLI (an absolute
+ * `ach`, or `npx -y @koalaauto/agentchannel@<spec>`).
+ */
+export declare function mcpCommands(o: {
+    achCmd: string[];
+    home?: string;
+}): {
+    claude: string;
+    codex: string;
+};
+/**
+ * How the MCP entry starts this CLI: `ach` when the first `ach` on PATH is this
+ * package, else this exact CLI by absolute path (another program called `ach`
+ * earlier on PATH, or none, must never be what the MCP entry runs).
+ */
+export declare function achCommand(env?: NodeJS.ProcessEnv, self?: string): string[];
+/**
+ * When the first `ach` on PATH is some other program, `ach ...` typed by a
+ * person (or their agent) runs that one. The note to print, or undefined when
+ * this package (or nothing) comes first.
+ */
+export declare function shadowHint(env?: NodeJS.ProcessEnv, self?: string, zh?: boolean): string | undefined;
+/**
+ * `ach admin invite <agent>`: a paragraph the admin sends and the engineer
+ * pastes into their own Claude Code / Codex, which then does the setup and
+ * asks before installing the background helper. `line` is joinLine(...).
+ */
+export declare function agentInvitePrompt(line: string, lang?: 'en' | 'zh'): string;

package/dist/src/invite.js

@@ -0,0 +1,229 @@
+import { accessSync, constants, readFileSync, realpathSync } from 'node:fs';
+import { delimiter, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { PKG_NAME, VERSION } from './version.js';
+const PREFIX = 'ach2.';
+export const JOIN_TOKEN_RE = /^ach_jt_[a-z0-9]{15}_[A-Za-z0-9]{40}$/;
+export function encodeInvite(i) {
+    const o = { hub: i.hub.replace(/\/+$/, ''), join: i.join };
+    if (i.cf_id && i.cf_secret) {
+        o.cf_id = i.cf_id;
+        o.cf_secret = i.cf_secret;
+    }
+    return PREFIX + Buffer.from(JSON.stringify(o), 'utf8').toString('base64url');
+}
+export function decodeInvite(blob) {
+    const s = blob.trim();
+    if (!s.startsWith(PREFIX))
+        throw new Error('not an AgentChannel invite (expected ach2.<...>; copy the line from the panel)');
+    let o;
+    try {
+        o = JSON.parse(Buffer.from(s.slice(PREFIX.length), 'base64url').toString('utf8'));
+    }
+    catch {
+        throw new Error('invite is corrupted (copy the whole line)');
+    }
+    if (!o || typeof o.hub !== 'string' || !/^https?:\/\/[^\s]+$/.test(o.hub))
+        throw new Error('invite has no valid hub URL');
+    let hubUrl;
+    try {
+        hubUrl = new URL(o.hub);
+    }
+    catch {
+        throw new Error('invite has no valid hub URL');
+    }
+    // the join token (exchanged for a key) and the front-door pass travel to this address
+    if (hubUrl.protocol !== 'https:' && !isLocalHost(hubUrl.hostname)) {
+        throw new Error(`invite points at ${hubUrl.host} over plain http://: refusing to send a key there (ask your admin for the https:// line)`);
+    }
+    if (typeof o.join !== 'string' || !JOIN_TOKEN_RE.test(o.join))
+        throw new Error('invite has no valid join token');
+    const out = { hub: o.hub.replace(/\/+$/, ''), join: o.join };
+    if (typeof o.cf_id === 'string' && typeof o.cf_secret === 'string' && o.cf_id && o.cf_secret) {
+        out.cf_id = o.cf_id;
+        out.cf_secret = o.cf_secret;
+    }
+    return out;
+}
+/**
+ * Hosts where plain http:// is acceptable: this machine (localhost,
+ * 127.0.0.1, ::1, *.localhost) and the reserved *.test names (local dev/test
+ * setups). Anything else must be https://.
+ */
+export function isLocalHost(hostname) {
+    const h = hostname.toLowerCase().replace(/^\[|\]$/g, '').replace(/\.$/, '');
+    return h === 'localhost' || h === '127.0.0.1' || h === '::1' || h.endsWith('.localhost') || h.endsWith('.test');
+}
+/** True when a hub URL is https://, or http:// to a local host (isLocalHost). */
+export function hubTransportOk(hub) {
+    try {
+        const u = new URL(hub);
+        return u.protocol === 'https:' || (u.protocol === 'http:' && isLocalHost(u.hostname));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The npm spec in the join line: `@koalaauto/agentchannel@3` (the major), or the
+ * exact version for a prerelease (2.0.0-rc.3 is not matched by the range "2").
+ */
+export function npmSpec(version = VERSION) {
+    return /-/.test(version) ? `${PKG_NAME}@${version}` : `${PKG_NAME}@${version.split('.')[0]}`;
+}
+/** The one line a teammate pastes: npx fetches the CLI and `join` sets everything up. */
+export function joinLine(blob, version = VERSION) {
+    return `npx -y ${npmSpec(version)} join ${blob}`;
+}
+/** `npx -y @koalaauto/agentchannel@<spec>`: how messages and MCP entries start the CLI without relying on PATH. */
+export function npxAch(version = VERSION) {
+    return ['npx', '-y', npmSpec(version)];
+}
+/** The join line minus the blob (for parsing tests and docs). */
+export const JOIN_LINE_RE = /^npx -y @koalaauto\/agentchannel@\S+ join (ach2\.\S+)$/;
+/** What to tell the person who gets the line. */
+export const JOIN_HINT = 'They paste the line in a terminal (Node 20+); npx fetches the CLI. To type `ach` yourself: `npm i -g ' + PKG_NAME + '@next`. ' +
+    '`ach doctor` checks the setup.';
+/** The MCP server name printed for `claude mcp add` / `codex mcp add`. */
+export const MCP_SERVER_NAME = 'ach';
+/** Every executable `name` on PATH, in PATH order (like `which -a`). */
+export function whichAll(name, env = process.env) {
+    const out = [];
+    for (const d of (env.PATH ?? '').split(delimiter)) {
+        if (!d)
+            continue;
+        const f = join(d, name);
+        try {
+            accessSync(f, constants.X_OK);
+            if (!out.includes(f))
+                out.push(f);
+        }
+        catch {
+            /* next */
+        }
+    }
+    return out;
+}
+/**
+ * True for executables that are not the user's own install: anything in an
+ * npx cache (`.../_npx/...`) or in a node_modules/.bin (e.g. npx puts this
+ * package's dependencies' bins, such as the `codex` of @openai/codex-sdk, on
+ * PATH while `npx agentchannel` runs).
+ */
+export function isBundledBin(p) {
+    return /[\\/]_npx[\\/]/.test(p) || /[\\/]node_modules[\\/]\.bin[\\/]/.test(p);
+}
+/** The first user-installed `name` on PATH (bundled/npx-cache bins skipped). */
+export function userBin(name, env = process.env) {
+    return whichAll(name, env).find((p) => !isBundledBin(p) && !isBundledBin(real(p) ?? p));
+}
+/** True when an executable `name` is on PATH. */
+export function onPath(name, env = process.env) {
+    return whichAll(name, env).length > 0;
+}
+/** This CLI's entry file (dist/src/cli.js). */
+export function thisCliPath() {
+    return fileURLToPath(new URL('./cli.js', import.meta.url));
+}
+function real(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Which AgentChannel an `ach` executable is, without running it: follow the
+ * symlink (npm global bins are symlinks) up to the nearest package.json.
+ * `ours` = it is this very CLI.
+ */
+export function identifyAch(path, self = thisCliPath()) {
+    const r = real(path);
+    const ours = !!r && r === real(self);
+    let d = r ? dirname(r) : undefined;
+    for (let i = 0; d && i < 6; i++, d = dirname(d)) {
+        try {
+            const pj = JSON.parse(readFileSync(join(d, 'package.json'), 'utf8'));
+            if (pj && typeof pj.name === 'string')
+                return { path, real: r, name: pj.name, version: String(pj.version ?? ''), ours };
+        }
+        catch {
+            /* go up */
+        }
+        if (dirname(d) === d)
+            break;
+    }
+    return { path, real: r, ours };
+}
+/** True for an `ach` of this package (this CLI, or another install of it). */
+export function isOurs(i) {
+    return i.ours || i.name === PKG_NAME;
+}
+function shq(s) {
+    return /^[A-Za-z0-9_./:=@-]+$/.test(s) ? s : `'${s.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * The exact `claude mcp add` / `codex mcp add` commands for this machine. They
+ * are printed, never run. `achCmd` is how to start the CLI (an absolute
+ * `ach`, or `npx -y @koalaauto/agentchannel@<spec>`).
+ */
+export function mcpCommands(o) {
+    const cmd = o.achCmd.map(shq).join(' ');
+    const envClaude = o.home ? ` -e AGENTCHANNEL_HOME=${shq(o.home)}` : '';
+    const envCodex = o.home ? ` --env AGENTCHANNEL_HOME=${shq(o.home)}` : '';
+    return {
+        claude: `claude mcp add --scope user${envClaude} ${MCP_SERVER_NAME} -- ${cmd} mcp`,
+        codex: `codex mcp add${envCodex} ${MCP_SERVER_NAME} -- ${cmd} mcp`,
+    };
+}
+/**
+ * How the MCP entry starts this CLI: `ach` when the first `ach` on PATH is this
+ * package, else this exact CLI by absolute path (another program called `ach`
+ * earlier on PATH, or none, must never be what the MCP entry runs).
+ */
+export function achCommand(env = process.env, self = thisCliPath()) {
+    // run through npx: the cache may be cleared, so entries use the pinned npx spec
+    if (/[\\/]_npx[\\/]/.test(self))
+        return npxAch();
+    const first = whichAll('ach', env)[0];
+    if (first && isOurs(identifyAch(first, self)))
+        return ['ach'];
+    return [process.execPath, self];
+}
+/**
+ * When the first `ach` on PATH is some other program, `ach ...` typed by a
+ * person (or their agent) runs that one. The note to print, or undefined when
+ * this package (or nothing) comes first.
+ */
+export function shadowHint(env = process.env, self = thisCliPath(), zh = false) {
+    const first = whichAll('ach', env)[0];
+    if (!first)
+        return undefined;
+    const i = identifyAch(first, self);
+    if (isOurs(i))
+        return undefined;
+    const what = i.name ? `${i.name}${i.version ? `@${i.version}` : ''}` : first;
+    const npx = `${npxAch().join(' ')} …`;
+    return zh
+        ? `注意：PATH 上第一个 \`ach\` 是 ${what}（${first}），不是 AgentChannel 的，所以 \`ach ...\` 会运行它。修复：卸载它，或改用 ${npx}。`
+        : `Note: the first \`ach\` on your PATH is ${what} (${first}), not AgentChannel's, so \`ach ...\` runs that. Fix: remove it, or use ${npx}.`;
+}
+/**
+ * `ach admin invite <agent>`: a paragraph the admin sends and the engineer
+ * pastes into their own Claude Code / Codex, which then does the setup and
+ * asks before installing the background helper. `line` is joinLine(...).
+ */
+export function agentInvitePrompt(line, lang = 'en') {
+    // the line is the consent: run by an agent it stores the key and connects the agent's own tool, nothing else
+    const spec = /^npx -y (\S+) join /.exec(line)?.[1] ?? npmSpec();
+    const npx = `npx -y ${spec}`;
+    if (lang === 'zh') {
+        return (`请帮我接入团队的 AgentChannel：在终端运行 \`${line}\`。` +
+            `它会保存这个智能体的密钥，并把 AgentChannel 接入你自己，不会安装别的东西；这行只能用一次。` +
+            `完成后告诉我收件箱里有什么。如果出错，运行 \`${npx} doctor\`，按提示修好再继续。`);
+    }
+    return (`Please connect me to my team's AgentChannel: run \`${line}\` in a terminal. ` +
+        `It stores this agent's key and adds AgentChannel to you; it installs nothing else (the line works once). ` +
+        `Then tell me what is in my inbox. If anything fails, run \`${npx} doctor\`, fix what it says, and continue.`);
+}

package/dist/src/invite_person.d.ts

@@ -0,0 +1,16 @@
+import type { Client, FetchLike } from './client.js';
+import { type Exec } from './import.js';
+/**
+ * `ach admin invite <person>`: one copyable one-time login link (24 h; a new
+ * one replaces the older one). Send options appear only for delivery that is
+ * set up on this machine (Feishu through lark-cli). A reminder about the hub's
+ * sign-in gate appears only when the hub has one and its allowed list (as the
+ * hub knows it) does not include the person's email.
+ */
+export declare function invitePerson(ref: string, values: Record<string, unknown>, io: {
+    env: NodeJS.ProcessEnv;
+    out: (s: string) => void;
+    err: (s: string) => void;
+    fetch?: FetchLike;
+    exec?: Exec;
+}, a: Client): Promise<number>;

package/dist/src/invite_person.js

@@ -0,0 +1,75 @@
+import { UsageError } from './args.js';
+import { makeExec, inviteMessage } from './import.js';
+import { syncFeishuAvatars } from './avatars.js';
+/**
+ * `ach admin invite <person>`: one copyable one-time login link (24 h; a new
+ * one replaces the older one). Send options appear only for delivery that is
+ * set up on this machine (Feishu through lark-cli). A reminder about the hub's
+ * sign-in gate appears only when the hub has one and its allowed list (as the
+ * hub knows it) does not include the person's email.
+ */
+export async function invitePerson(ref, values, io, a) {
+    const want = ref.trim().toLowerCase().replace(/^@/, '');
+    const users = await a.adminListUsers();
+    const u = users.find((x) => x.id === ref) ?? users.find((x) => String(x.email ?? '').toLowerCase() === want) ?? users.find((x) => String(x.name ?? '').toLowerCase() === want);
+    if (!u)
+        throw new UsageError(`admin invite: no person or agent named ${ref} (add a person with \`ach admin create-user --name <n> --email <e>\`)`);
+    if (u.deactivated)
+        throw new UsageError(`admin invite: ${u.name || u.email} is deactivated (reactivate with \`ach admin user ${u.email || u.id} --reactivate\`)`);
+    const link = await a.adminUserLoginLink(u.id);
+    const url = link.url && /^https?:/.test(link.url) ? link.url : `${a.hub}${link.path}`;
+    const exec = io.exec ?? makeExec(io.env);
+    const lark = (await exec('lark-cli', ['--version'])).code === 0;
+    const settings = await a.request('GET', '/api/ach/settings').catch(() => null);
+    const workspace = settings?.workspace_name || undefined;
+    const result = { person: u.name, email: u.email ?? '', url, expires_at: link.expires_at };
+    if (values.feishu) {
+        if (!lark)
+            io.err('Feishu is not set up on this machine (lark-cli not found): send the link yourself.');
+        else {
+            const r = await sendFeishu(exec, u, inviteMessage(u.name || u.email, url, workspace));
+            if (r.ok) {
+                result.sent = 'feishu';
+                io.err(`sent a Feishu message to ${u.name || u.email}`);
+                await syncFeishuAvatars(a, [{ id: u.id, name: u.name, email: u.email }], { exec, fetch: io.fetch, log: io.err });
+            }
+            else
+                io.err(`Feishu message to ${u.name || u.email} failed (${r.why}): send the link yourself.`);
+        }
+    }
+    if (values.json)
+        io.out(JSON.stringify(result, null, 2));
+    else
+        io.out(url);
+    io.err(`One-time login link for ${u.name || u.email}: works once, expires in 24 h.`);
+    if (!values.feishu && lark && u.email)
+        io.err(`Send it on Feishu: ach admin invite ${u.email} --feishu`);
+    if (u.email) {
+        const gate = await a.request('GET', `/api/ach/admin/access-check?email=${encodeURIComponent(u.email)}`).catch(() => null);
+        if (gate?.cf && gate.covered === false) {
+            io.err(`Note: ${u.email} is not on the hub's list of people allowed through its sign-in page yet. Add the email there, or the link will not open for them.`);
+        }
+    }
+    return 0;
+}
+async function sendFeishu(exec, u, text) {
+    let openId = typeof u.feishu_open_id === 'string' && /^ou_/.test(u.feishu_open_id) ? u.feishu_open_id : '';
+    if (!openId && u.email) {
+        const r = await exec('lark-cli', ['contact', '+search-user', '--query', u.email, '--as', 'user', '--exclude-external-users', '--format', 'json']);
+        if (r.code !== 0)
+            return { ok: false, why: (r.stderr.trim() || r.stdout.trim()).split('\n')[0] || `exit ${r.code}` };
+        try {
+            const j = JSON.parse(r.stdout);
+            const list = j?.data?.users ?? j?.users ?? [];
+            const hit = list.find((x) => [x.email, x.enterprise_email].some((e) => String(e ?? '').toLowerCase() === String(u.email).toLowerCase()));
+            openId = hit?.open_id ?? '';
+        }
+        catch {
+            /* unexpected output */
+        }
+    }
+    if (!openId)
+        return { ok: false, why: 'not found in Feishu by email' };
+    const r = await exec('lark-cli', ['im', '+messages-send', '--user-id', openId, '--text', text, '--idempotency-key', `ach-inv-${u.id}-${Date.now().toString(36)}`.slice(0, 50)]);
+    return r.code === 0 ? { ok: true, why: '' } : { ok: false, why: r.stderr.trim().split('\n')[0] || `exit ${r.code}` };
+}

package/dist/src/keystore.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Where the agent key lives (S2). Default: the OS keychain via @napi-rs/keyring
+ * (macOS Keychain, Windows Credential Manager, Linux Secret Service). When the
+ * keychain is unavailable (e.g. Linux without a secret service) or
+ * ACH_KEYSTORE=file is set, the key goes to <home>/agent-key with mode 0600.
+ * The key is never written to config.json any more.
+ */
+export interface KeyStore {
+    readonly kind: 'keychain' | 'file';
+    get(): string | undefined;
+    set(key: string): void;
+    delete(): void;
+}
+export declare const KEYCHAIN_SERVICE = "agentchannel";
+export declare function keyFilePath(home: string): string;
+export declare class FileKeyStore implements KeyStore {
+    readonly path: string;
+    readonly kind: "file";
+    constructor(path: string);
+    get(): string | undefined;
+    set(key: string): void;
+    delete(): void;
+}
+interface KeyringEntry {
+    getPassword(): string | null;
+    setPassword(p: string): void;
+    deletePassword(): boolean;
+}
+export declare class KeychainKeyStore implements KeyStore {
+    private entry;
+    readonly kind: "keychain";
+    constructor(entry: KeyringEntry);
+    get(): string | undefined;
+    set(key: string): void;
+    delete(): void;
+}
+/** The keychain entry for this AGENTCHANNEL_HOME, or undefined if no usable keychain. */
+export declare function openKeychain(home: string, account?: string): KeychainKeyStore | undefined;
+/** Keychain unless ACH_KEYSTORE=file or the keychain is unavailable. */
+export declare function openKeyStore(home: string, env?: NodeJS.ProcessEnv): KeyStore;
+/**
+ * B1: the human session of `ach admin` (a PocketBase user token). Kept out of
+ * config.json: the OS keychain (account "admin-session:<home>"), else
+ * <home>/admin-session (0600), a file the runner denies to spawned agents.
+ */
+export declare function adminSessionPath(home: string): string;
+export declare function openAdminSessionStore(home: string, env?: NodeJS.ProcessEnv): KeyStore;
+/**
+ * The secret half of the hub's front-door service token (from the `ach join`
+ * line): OS keychain (account "cf-secret:<home>"), else <home>/cf-secret
+ * (0600). The id stays in config.json; the secret never does.
+ */
+export declare function cfSecretPath(home: string): string;
+export declare function openCfSecretStore(home: string, env?: NodeJS.ProcessEnv): KeyStore;
+export {};

package/dist/src/keystore.js

@@ -0,0 +1,108 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+export const KEYCHAIN_SERVICE = 'agentchannel';
+export function keyFilePath(home) {
+    return join(home, 'agent-key');
+}
+export class FileKeyStore {
+    path;
+    kind = 'file';
+    constructor(path) {
+        this.path = path;
+    }
+    get() {
+        try {
+            const v = readFileSync(this.path, 'utf8').trim();
+            return v || undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    set(key) {
+        const dir = dirname(this.path);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true, mode: 0o700 });
+        writeFileSync(this.path, key + '\n', { mode: 0o600 });
+        chmodSync(this.path, 0o600);
+    }
+    delete() {
+        rmSync(this.path, { force: true });
+    }
+}
+export class KeychainKeyStore {
+    entry;
+    kind = 'keychain';
+    constructor(entry) {
+        this.entry = entry;
+    }
+    get() {
+        return this.entry.getPassword() ?? undefined;
+    }
+    set(key) {
+        this.entry.setPassword(key);
+    }
+    delete() {
+        try {
+            this.entry.deletePassword();
+        }
+        catch {
+            /* already gone */
+        }
+    }
+}
+/** The keychain entry for this AGENTCHANNEL_HOME, or undefined if no usable keychain. */
+export function openKeychain(home, account = `agent-key:${home}`) {
+    try {
+        const req = createRequire(import.meta.url);
+        const { Entry } = req('@napi-rs/keyring');
+        const entry = new Entry(KEYCHAIN_SERVICE, account);
+        entry.getPassword(); // probe: throws when no credential store is reachable
+        return new KeychainKeyStore(entry);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Keychain unless ACH_KEYSTORE=file or the keychain is unavailable. */
+export function openKeyStore(home, env = process.env) {
+    if (env.ACH_KEYSTORE !== 'file') {
+        const k = openKeychain(home);
+        if (k)
+            return k;
+    }
+    return new FileKeyStore(keyFilePath(home));
+}
+/**
+ * B1: the human session of `ach admin` (a PocketBase user token). Kept out of
+ * config.json: the OS keychain (account "admin-session:<home>"), else
+ * <home>/admin-session (0600), a file the runner denies to spawned agents.
+ */
+export function adminSessionPath(home) {
+    return join(home, 'admin-session');
+}
+export function openAdminSessionStore(home, env = process.env) {
+    if (env.ACH_KEYSTORE !== 'file') {
+        const k = openKeychain(home, `admin-session:${home}`);
+        if (k)
+            return k;
+    }
+    return new FileKeyStore(adminSessionPath(home));
+}
+/**
+ * The secret half of the hub's front-door service token (from the `ach join`
+ * line): OS keychain (account "cf-secret:<home>"), else <home>/cf-secret
+ * (0600). The id stays in config.json; the secret never does.
+ */
+export function cfSecretPath(home) {
+    return join(home, 'cf-secret');
+}
+export function openCfSecretStore(home, env = process.env) {
+    if (env.ACH_KEYSTORE !== 'file') {
+        const k = openKeychain(home, `cf-secret:${home}`);
+        if (k)
+            return k;
+    }
+    return new FileKeyStore(cfSecretPath(home));
+}