@koalaauto/agentchannel 0.0.0-stage → 3.0.0

package/dist/src/client.js

@@ -0,0 +1,449 @@
+import { openAsBlob, statSync } from 'node:fs';
+import { basename } from 'node:path';
+import { attachmentForm, bigFiles, downloadFile, isLinkRef, linkRef, taskFiles, typeOf, uploadTarget } from './attachments.js';
+export const TERMINAL = ['completed', 'failed', 'canceled'];
+export function isTerminal(s) {
+    return !!s && TERMINAL.includes(s);
+}
+/** Parse `name` or `name@base` (CLI `--read-repo`). */
+export function parseLinkRepo(v) {
+    const i = v.indexOf('@');
+    const repo = (i >= 0 ? v.slice(0, i) : v).trim();
+    const base = i >= 0 ? v.slice(i + 1).trim() : '';
+    if (!/^[A-Za-z0-9._-]{1,64}$/.test(repo))
+        throw new Error(`repo must be a name, got "${v}"`);
+    if (i >= 0 && (!/^[A-Za-z0-9._\/-]{1,200}$/.test(base) || base.startsWith('-')))
+        throw new Error(`bad base in "${v}"`);
+    return base ? { repo, base } : { repo };
+}
+export class HubError extends Error {
+    status;
+    code;
+    body;
+    constructor(status, message, code, body) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.body = body;
+        this.name = 'HubError';
+    }
+}
+/** Round 2: human-facing CLI text in Chinese when LANG/LC_ALL starts with zh. */
+export function isZh(env) {
+    return /^zh/i.test(env.LC_ALL || env.LC_MESSAGES || env.LANG || '');
+}
+/** Picks the bearer: run token (spawned agent) beats agent key. */
+export function clientFromConfig(cfg, opts = {}) {
+    if (!cfg.hub) {
+        throw new Error(isZh(process.env)
+            ? '还没有连接 hub：运行面板或管理员给你的 `ach join ach2....` 那一行（或设置 ACH_HUB）。'
+            : 'No hub configured: run the `ach join ach2....` line from the panel or your admin (or set ACH_HUB).');
+    }
+    const token = opts.admin ? cfg.adminToken : cfg.runToken || cfg.key;
+    return new Client({ hub: cfg.hub, token, cfId: cfg.cfId, cfSecret: cfg.cfSecret, fetch: opts.fetch });
+}
+function arr(v) {
+    return Array.isArray(v) ? v : [];
+}
+/** Accept either `{task, handoff, messages, history}` or a bare task record. */
+export function normalizeBundle(raw) {
+    const task = raw?.task ?? raw;
+    return {
+        task,
+        handoff: typeof raw?.handoff === 'string' ? raw.handoff : raw?.handoff?.body ?? task?.handoff ?? '',
+        messages: arr(raw?.messages),
+        history: arr(raw?.handoff_history ?? raw?.history ?? raw?.handoff_versions),
+        handoffAttachments: arr(raw?.handoff?.attachments),
+        wiki: raw?.wiki_context && typeof raw.wiki_context === 'object' ? raw.wiki_context : null,
+    };
+}
+export class Client {
+    hub;
+    token;
+    cfId;
+    cfSecret;
+    fetchFn;
+    constructor(o) {
+        this.hub = o.hub.replace(/\/+$/, '');
+        this.token = o.token;
+        this.cfId = o.cfId;
+        this.cfSecret = o.cfSecret;
+        this.fetchFn = o.fetch ?? ((u, i) => fetch(u, i));
+    }
+    headers(json = true) {
+        const h = json ? { 'content-type': 'application/json', accept: 'application/json' } : { accept: 'application/json' };
+        if (this.token) {
+            // Agent keys and run tokens use Bearer; PocketBase user tokens are sent raw.
+            h.authorization = /^ach_(sk|rt)_/.test(this.token) ? `Bearer ${this.token}` : this.token;
+        }
+        if (this.cfId && this.cfSecret) {
+            h['CF-Access-Client-Id'] = this.cfId;
+            h['CF-Access-Client-Secret'] = this.cfSecret;
+        }
+        return h;
+    }
+    /** `files`: local paths (already checked by resolveAttachments) sent as multipart with the JSON in field "json". */
+    async request(method, path, body, files) {
+        const url = path.startsWith('http') ? path : `${this.hub}${path}`;
+        if (files?.length)
+            ({ body, files } = await this.splitAttachments(path, body, files));
+        const multipart = !!files?.length;
+        const res = await this.fetchFn(url, {
+            method,
+            headers: this.headers(!multipart),
+            body: multipart ? await attachmentForm(body, files) : body === undefined ? undefined : JSON.stringify(body),
+        });
+        const text = await res.text();
+        let data = undefined;
+        if (text) {
+            try {
+                data = JSON.parse(text);
+            }
+            catch {
+                data = text;
+            }
+        }
+        if (!res.ok) {
+            const msg = (data && (data.error || data.message)) || `${res.status} ${res.statusText}`;
+            throw new HubError(res.status, `${method} ${path}: ${typeof msg === 'string' ? msg : JSON.stringify(msg)}`, data?.code, data);
+        }
+        return data;
+    }
+    storageCfg;
+    /** GET /storage/config once per client (null on hubs without it). */
+    storageConfig() {
+        this.storageCfg ??= this.request('GET', '/api/ach/storage/config').catch(() => null);
+        return this.storageCfg;
+    }
+    /**
+     * §20 v1.1: https entries become link references; media files over the hub's
+     * direct-upload threshold go straight to its bucket (presign, PUT, complete)
+     * and become upload references. The rest is sent as multipart, as before.
+     */
+    async splitAttachments(path, body, files) {
+        const refs = files.filter(isLinkRef).map((f) => linkRef(f));
+        let local = files.filter((f) => !isLinkRef(f));
+        const target = uploadTarget(path);
+        // only ask the hub when a file could be over any threshold (>= 5 MB)
+        if (target && local.some((f) => statSync(f).size > 5 * 1048576)) {
+            const big = bigFiles(local, await this.storageConfig());
+            for (const f of big)
+                refs.push(await this.directUpload(f, target));
+            local = local.filter((f) => !big.includes(f));
+        }
+        if (!refs.length)
+            return { body, files: local };
+        const b = body && typeof body === 'object' ? body : {};
+        const prior = Array.isArray(b.attachment_refs) ? b.attachment_refs : [];
+        return { body: { ...b, attachment_refs: [...prior, ...refs] }, files: local };
+    }
+    /** Upload one file directly to the hub's bucket; returns the reference to attach ({upload}). */
+    async directUpload(file, target) {
+        const mime = typeOf(file);
+        const size = statSync(file).size;
+        const p = await this.request('POST', '/api/ach/uploads/presign', { name: basename(file), mime, size, target });
+        const put = p?.put;
+        if (!put?.url || !p?.upload?.id)
+            throw new HubError(502, `presign ${basename(file)}: unexpected answer`);
+        const res = await this.fetchFn(put.url, { method: 'PUT', headers: put.headers ?? { 'content-type': mime }, body: (await openAsBlob(file, { type: mime })) });
+        if (!res.ok) {
+            const text = await res.text().catch(() => '');
+            throw new HubError(res.status, `upload ${basename(file)} to storage: ${res.status} ${res.statusText} ${text.slice(0, 200)}`.trim());
+        }
+        const done = await this.request('POST', '/api/ach/uploads/complete', { upload: p.upload.id });
+        return { upload: String(done?.ref?.upload ?? p.upload.id) };
+    }
+    /** Avatars: send one image as multipart field "file" (plus plain fields). */
+    async sendImage(method, path, bytes, filename, fields = {}) {
+        const fd = new FormData();
+        for (const [k, v] of Object.entries(fields))
+            fd.append(k, v);
+        const type = /\.png$/i.test(filename) ? 'image/png' : /\.gif$/i.test(filename) ? 'image/gif' : /\.webp$/i.test(filename) ? 'image/webp' : 'image/jpeg';
+        fd.append('file', new Blob([bytes], { type }), filename);
+        const res = await this.fetchFn(`${this.hub}${path}`, { method, headers: this.headers(false), body: fd });
+        const text = await res.text();
+        let data;
+        try {
+            data = text ? JSON.parse(text) : undefined;
+        }
+        catch {
+            data = text;
+        }
+        if (!res.ok)
+            throw new HubError(res.status, `${method} ${path}: ${(data && (data.error || data.message)) || res.status}`, data?.code, data);
+        return data;
+    }
+    ach(method, path, body, files) {
+        return this.request(method, `/api/ach${path}`, body, files);
+    }
+    /** All attachments on a task (handoff versions and messages), with hub download URLs. */
+    async taskFiles(taskId) {
+        return taskFiles(await this.getTask(taskId));
+    }
+    /** Download one attachment into `dir`; returns the local path. */
+    async download(a, dir) {
+        const h = this.headers(false);
+        delete h.accept;
+        return downloadFile(this.fetchFn, `${this.hub}${a.url}`, h, dir, a);
+    }
+    // ---- agent routes ----
+    async me() {
+        const r = await this.ach('GET', '/me');
+        const a = r?.agent ?? r;
+        if (r?.owner_name && !a.owner_name)
+            a.owner_name = r.owner_name;
+        return a;
+    }
+    async agents() {
+        const r = await this.ach('GET', '/agents');
+        return Array.isArray(r) ? r : arr(r?.agents ?? r?.items);
+    }
+    async sendTask(input, files) {
+        const r = await this.ach('POST', '/tasks', input, files);
+        return r?.task ?? r;
+    }
+    /** Propose a recurring task (runs after the owner approves). */
+    async proposeSchedule(input) {
+        return this.ach('POST', '/schedules', input);
+    }
+    async schedules() {
+        const r = await this.ach('GET', '/schedules');
+        return arr(r?.schedules);
+    }
+    async scheduleAction(id, action) {
+        return this.ach('POST', `/schedules/${enc(id)}/${action}`, {});
+    }
+    async removeSchedule(id) {
+        return this.ach('DELETE', `/schedules/${enc(id)}`);
+    }
+    /** New handoff body (+ optional header fields, same version). Sender's agent key only. */
+    async updateHandoff(taskId, body, change_note, header = {}, files) {
+        return this.ach('PUT', `/tasks/${enc(taskId)}/handoff`, { ...header, body, change_note }, files);
+    }
+    /** Header fields only (priority, purpose, money, key_question). Sender's agent key only. */
+    async updateHeader(taskId, header, change_note) {
+        return this.ach('PATCH', `/tasks/${enc(taskId)}`, { ...header, ...(change_note ? { change_note } : {}) });
+    }
+    async getTask(taskId) {
+        return normalizeBundle(await this.ach('GET', `/tasks/${enc(taskId)}`));
+    }
+    async claim(taskId, run_id, mode = 'runner') {
+        const r = await this.ach('POST', `/tasks/${enc(taskId)}/claim`, { run_id, ...(mode === 'interactive' ? { mode } : {}) });
+        const b = normalizeBundle(r);
+        return { ...b, run_token: r?.run_token ?? r?.token ?? '' };
+    }
+    /** Mint an answer-mode run token for a question addressed to me (§14.2). */
+    async answerRun(taskId, question_id, run_id) {
+        const r = await this.ach('POST', `/tasks/${enc(taskId)}/answer-run`, { question_id, run_id });
+        return { ...r, run_token: r?.run_token ?? r?.token ?? '' };
+    }
+    async postMessage(taskId, m, files) {
+        const r = await this.ach('POST', `/tasks/${enc(taskId)}/messages`, m, files);
+        // Round 5: a request addressed to someone else cc's the asking agent's owner
+        if (r?.message && r.cc_user && !r.message.cc_user)
+            r.message.cc_user = r.cc_user;
+        return r?.message ?? r;
+    }
+    /** With an agent key the hub requires the task's current run_id (C3); run tokens carry their own. */
+    async complete(taskId, result, run_id, files, handoff_version) {
+        return this.ach('POST', `/tasks/${enc(taskId)}/complete`, { result, ...(run_id ? { run_id } : {}), ...(handoff_version ? { handoff_version } : {}) }, files);
+    }
+    async fail(taskId, reason, run_id) {
+        return this.ach('POST', `/tasks/${enc(taskId)}/fail`, { reason, ...(run_id ? { run_id } : {}) });
+    }
+    /** §23: a grantee agent answers the part of a request its grant covers. */
+    async grantDecide(taskId, message_id, option, grant) {
+        return this.ach('POST', `/tasks/${enc(taskId)}/grant-decide`, { message_id, option, grant });
+    }
+    async createGrant(input) {
+        return this.ach('POST', '/grants', input);
+    }
+    async listGrants() {
+        return this.ach('GET', '/grants');
+    }
+    async revokeGrant(id) {
+        return this.ach('POST', `/grants/${enc(id)}/revoke`, {});
+    }
+    async cancel(taskId, reason) {
+        return this.ach('POST', `/tasks/${enc(taskId)}/cancel`, { reason });
+    }
+    /** The total size of a work prompt (Memory trial metrics). */
+    async promptSize(taskId, run_id, chars, parts = {}) {
+        return this.ach('POST', '/memory/prompt-size', { task: taskId, run_id, chars, parts });
+    }
+    async usage(taskId, run_id, cost_usd, estimated) {
+        return this.ach('POST', `/tasks/${enc(taskId)}/usage`, { run_id, cost_usd, estimated });
+    }
+    /** 409 when the run lost the task. Carries a fresh `run_token` when the old one is near expiry (C5). */
+    async heartbeat(taskId, run_id) {
+        return this.ach('POST', `/tasks/${enc(taskId)}/heartbeat`, { run_id });
+    }
+    /** Revoke the answer token(s) of a finished answer run (C4). */
+    async endRun(taskId, run_id) {
+        return this.ach('POST', `/tasks/${enc(taskId)}/end-run`, { run_id });
+    }
+    async inbox() {
+        const r = await this.ach('GET', '/inbox');
+        return {
+            tasks_to_me: arr(r?.tasks_to_me),
+            questions_to_me: flatMsgs(r?.questions_to_me),
+            answers_to_me: flatMsgs(r?.answers_to_me),
+            decisions_for_me: flatMsgs(r?.decisions_for_me),
+            notes_for_me: flatMsgs(r?.notes_for_me),
+            mentions_for_me: arr(r?.mentions_for_me),
+            updates_on_my_tasks: arr(r?.updates_on_my_tasks),
+            server_time: r?.server_time ?? new Date().toISOString(),
+        };
+    }
+    // ---- channels, posts, mentions, search (§16, §18) ----
+    async channels(all = false) {
+        return arr(await this.ach('GET', `/channels${all ? '?all=1' : ''}`));
+    }
+    async channelPosts(channel, o = {}) {
+        const q = new URLSearchParams();
+        if (o.since)
+            q.set('since', o.since);
+        if (o.before)
+            q.set('before', o.before);
+        if (o.limit)
+            q.set('limit', String(o.limit));
+        const qs = q.toString();
+        return this.ach('GET', `/channels/${enc(channelRef(channel))}/posts${qs ? `?${qs}` : ''}`);
+    }
+    async post(channel, body, files, o = {}) {
+        const r = await this.ach('POST', `/channels/${enc(channelRef(channel))}/posts`, { body, ...(o.announce ? { announce: true } : {}) }, files);
+        return r?.post ?? r;
+    }
+    async reply(postId, body, o = {}, files) {
+        const r = await this.ach('POST', `/posts/${enc(postId)}/replies`, { body, ...(o.evidence ? { evidence: o.evidence } : {}), ...(o.escalate ? { escalate: true } : {}) }, files);
+        return r?.post ?? r;
+    }
+    async thread(postId) {
+        return this.ach('GET', `/posts/${enc(postId)}`);
+    }
+    async search(q, o = {}) {
+        const p = new URLSearchParams({ q });
+        if (o.channel)
+            p.set('channel', channelRef(o.channel));
+        if (o.author)
+            p.set('author', o.author);
+        if (o.limit)
+            p.set('limit', String(o.limit));
+        return this.ach('GET', `/search?${p.toString()}`);
+    }
+    /** Take an @mention: a read-only "mention" run token for its thread. */
+    async mentionRun(mentionId, run_id) {
+        return this.ach('POST', `/mentions/${enc(mentionId)}/run`, { run_id });
+    }
+    async mentionEnd(mentionId, run_id) {
+        return this.ach('POST', `/mentions/${enc(mentionId)}/end`, { run_id });
+    }
+    async mentionUsage(mentionId, run_id, cost_usd, estimated) {
+        return this.ach('POST', `/mentions/${enc(mentionId)}/usage`, { run_id, cost_usd, estimated });
+    }
+    async agentProfile(name) {
+        return this.ach('GET', `/profiles/agents/${enc(name)}`);
+    }
+    // ---- team Memory (§21-revised; routes /api/ach/memory/*, formerly /wiki/*) ----
+    /** `ach remember`: a fact or lesson with its source (hub permalink or GitHub URL); toTeam promotes it to the team overview. */
+    async remember(text, source, o = {}) {
+        return this.ach('POST', '/memory/contributions', { text, source, ...(o.channel ? { channel: channelRef(o.channel) } : {}), ...(o.topic ? { topic: o.topic } : {}), ...(o.toTeam ? { to_team: true } : {}) });
+    }
+    /** `ach decide-draft`: ask the person (a decision request); their reply records the decision. */
+    async decideDraft(input) {
+        return this.ach('POST', '/memory/decisions', { ...input, ...(input.channel ? { channel: channelRef(input.channel) } : {}) });
+    }
+    async wikiIndex(channel) {
+        return this.ach('GET', `/memory${channel ? `?channel=${enc(channelRef(channel))}` : ''}`);
+    }
+    async wikiPage(slug) {
+        return this.ach('GET', `/memory/pages/${enc(slug)}`);
+    }
+    async wikiSearch(q, limit) {
+        return this.ach('GET', `/memory/search?q=${enc(q)}${limit ? `&limit=${limit}` : ''}`);
+    }
+    async wikiExport(channel) {
+        return this.ach('GET', `/memory/export${channel ? `?channel=${enc(channelRef(channel))}` : ''}`);
+    }
+    async wikiPush(input) {
+        return this.ach('POST', '/memory/push', input);
+    }
+    async wikiSeed() {
+        return this.ach('POST', '/memory/seed', { from: 'imports' });
+    }
+    /** A bounded Memory summary for an interactive session (MCP instructions, SessionStart hook). */
+    async memoryBrief(o = {}) {
+        const q = o.task ? `?task=${enc(o.task)}` : o.channel ? `?channel=${enc(channelRef(o.channel))}` : '';
+        return this.ach('GET', `/memory/brief${q}`);
+    }
+    // ---- user routes (decide: also an agent key speaking for its own owner, §23) ----
+    async decide(taskId, message_id, decision, files) {
+        return this.ach('POST', `/tasks/${enc(taskId)}/decide`, { message_id, decision }, files);
+    }
+    /** A human note on a task (user token; admins and the owners of either agent). */
+    async note(taskId, body, files) {
+        return this.ach('POST', `/tasks/${enc(taskId)}/note`, { body }, files);
+    }
+    async panel() {
+        return this.ach('GET', '/panel');
+    }
+    /** §15: a person (email optional) plus a one-time join link (24 h). No password. */
+    async adminCreateUser(input) {
+        return this.ach('POST', '/admin/users', input);
+    }
+    async adminListUsers() {
+        return this.ach('GET', '/admin/users');
+    }
+    /** §15: a fresh one-time login link (24 h) for a person's new device. */
+    async adminUserLoginLink(ref) {
+        return this.ach('POST', `/admin/users/${enc(ref)}/login-link`, {});
+    }
+    async adminPatchUser(ref, patch) {
+        return this.ach('PATCH', `/admin/users/${enc(ref)}`, patch);
+    }
+    /** §15 `ach open`: the agent key mints a 60 s single-use login link for its owner. */
+    async loginLink() {
+        return this.ach('POST', '/login-link', {});
+    }
+    /** Exchange a one-time login link token for a PocketBase user session. */
+    async exchangeLoginLink(token) {
+        return this.ach('POST', '/auth/link', { token });
+    }
+    /** P4/P5: the logged-in human's own profile (notify_webhook, password, name). */
+    async patchMe(patch) {
+        return this.ach('PATCH', '/me', patch);
+    }
+    async adminCreateAgent(input) {
+        return this.ach('POST', '/admin/agents', input);
+    }
+    /** `cf_token`: put the hub's shared front-door token in the invites (opt-in; default false). */
+    async adminRotateKey(agentId, o = {}) {
+        return this.ach('POST', `/admin/agents/${enc(agentId)}/rotate-key`, { cf_token: !!o.cf_token });
+    }
+    async adminPatchAgent(agentId, patch) {
+        return this.ach('PATCH', `/admin/agents/${enc(agentId)}`, patch);
+    }
+    /** PocketBase built-in password auth for humans. */
+    async userLogin(email, password) {
+        return this.request('POST', '/api/collections/users/auth-with-password', { identity: email, password });
+    }
+}
+/** Inbox message entries are `{message, task}`; flatten to the message (task id stays in `message.task`). */
+export function flatMsgs(v) {
+    return arr(v).map((e) => {
+        if (e && e.message && typeof e.message === 'object') {
+            const m = { ...e.message };
+            if (e.task && typeof e.task === 'object')
+                m.task_info = e.task;
+            return m;
+        }
+        return e;
+    });
+}
+/** "#general" -> "general". */
+export function channelRef(c) {
+    return String(c).trim().replace(/^#/, '');
+}
+function enc(s) {
+    return encodeURIComponent(s);
+}

package/dist/src/config.d.ts

@@ -0,0 +1,62 @@
+/** config.json: no secrets (the key, the admin session and the front-door secret live in the key store). */
+export interface FileConfig {
+    hub?: string;
+    /** Who the `ach admin` session belongs to (the session itself is in the key store). */
+    admin_email?: string;
+    /** Cloudflare Access service token id (from `ach join`); its secret is in the key store; env ACH_CF_ID / ACH_CF_SECRET win. */
+    cf_id?: string;
+    /** P3: repo name -> local path for `ach run` (merged with --repo name=path). */
+    repos?: Record<string, string>;
+    /** `ach run` default: hold new tasks for INTERACTIVE_FIRST_DELAY_SEC so the owner can claim them first. */
+    interactive_first?: boolean;
+}
+export interface Config {
+    hub?: string;
+    key?: string;
+    runToken?: string;
+    taskId?: string;
+    agent?: string;
+    cfId?: string;
+    cfSecret?: string;
+    adminToken?: string;
+    repos?: Record<string, string>;
+    interactiveFirst?: boolean;
+}
+/** Claim delay used by `ach run --interactive-first` (or "interactive_first": true in config.json). */
+export declare const INTERACTIVE_FIRST_DELAY_SEC = 600;
+/**
+ * `ach run` claim delay in seconds: an explicit --claim-delay wins; else 600 with
+ * --interactive-first (flag or config); else 0 (claim at once: nobody is
+ * expected to work tasks interactively on this agent).
+ */
+export declare function resolveClaimDelay(o: {
+    claimDelay?: number;
+    interactiveFirst?: boolean;
+}): number;
+/** Default home: $XDG_CONFIG_HOME/agentchannel, else ~/.config/agentchannel (no version in the name). */
+export declare function defaultHome(env?: NodeJS.ProcessEnv): string;
+/** Root dir for config and runner state. AGENTCHANNEL_HOME overrides (used by tests). */
+export declare function achHome(env?: NodeJS.ProcessEnv): string;
+export declare function configPath(env?: NodeJS.ProcessEnv): string;
+/** Write JSON atomically with mode 0600 (dir 0700). */
+export declare function writeJsonPrivate(path: string, data: unknown): void;
+export declare function readJson<T>(path: string, fallback: T): T;
+export declare function readFileConfig(env?: NodeJS.ProcessEnv): FileConfig;
+export declare function writeFileConfig(cfg: FileConfig, env?: NodeJS.ProcessEnv): void;
+/** The agent key: OS keychain, else the 0600 agent-key file. */
+export declare function loadAgentKey(env?: NodeJS.ProcessEnv): string | undefined;
+export declare function saveAgentKey(key: string, env?: NodeJS.ProcessEnv): 'keychain' | 'file';
+/** The front-door service token secret: OS keychain, else <home>/cf-secret. */
+export declare function loadCfSecret(env?: NodeJS.ProcessEnv): string | undefined;
+/** Store the service token secret (or remove it: undefined). */
+export declare function saveCfSecret(secret: string | undefined, env?: NodeJS.ProcessEnv): 'keychain' | 'file';
+/** B1: the `ach admin` session token (keychain or <home>/admin-session; never config.json). */
+export declare function loadAdminToken(env?: NodeJS.ProcessEnv): string | undefined;
+/** Store the admin session; config.json keeps only whose it is. */
+export declare function saveAdminToken(token: string, env?: NodeJS.ProcessEnv, email?: string): 'keychain' | 'file';
+/**
+ * Effective config: env wins over the file. Inside a spawned agent (ACH_RUN_TOKEN
+ * set) nothing is read from disk or the keychain: the run token and ACH_HUB are
+ * the only credentials, so the agent key can never be loaded or re-pointed.
+ */
+export declare function loadConfig(env?: NodeJS.ProcessEnv): Config;

package/dist/src/config.js

@@ -0,0 +1,121 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { cfSecretPath, FileKeyStore, keyFilePath, openAdminSessionStore, openCfSecretStore, openKeyStore } from './keystore.js';
+/** Claim delay used by `ach run --interactive-first` (or "interactive_first": true in config.json). */
+export const INTERACTIVE_FIRST_DELAY_SEC = 600;
+/**
+ * `ach run` claim delay in seconds: an explicit --claim-delay wins; else 600 with
+ * --interactive-first (flag or config); else 0 (claim at once: nobody is
+ * expected to work tasks interactively on this agent).
+ */
+export function resolveClaimDelay(o) {
+    if (o.claimDelay !== undefined)
+        return o.claimDelay;
+    return o.interactiveFirst ? INTERACTIVE_FIRST_DELAY_SEC : 0;
+}
+/** Default home: $XDG_CONFIG_HOME/agentchannel, else ~/.config/agentchannel (no version in the name). */
+export function defaultHome(env = process.env) {
+    return join(env.XDG_CONFIG_HOME || join(env.HOME || homedir(), '.config'), 'agentchannel');
+}
+/** Root dir for config and runner state. AGENTCHANNEL_HOME overrides (used by tests). */
+export function achHome(env = process.env) {
+    return env.AGENTCHANNEL_HOME || defaultHome(env);
+}
+export function configPath(env = process.env) {
+    return join(achHome(env), 'config.json');
+}
+/** Write JSON atomically with mode 0600 (dir 0700). */
+export function writeJsonPrivate(path, data) {
+    const dir = dirname(path);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(data, null, 2) + '\n', { mode: 0o600 });
+    chmodSync(tmp, 0o600);
+    renameSync(tmp, path);
+    chmodSync(path, 0o600);
+}
+export function readJson(path, fallback) {
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return fallback;
+    }
+}
+export function readFileConfig(env = process.env) {
+    return readJson(configPath(env), {});
+}
+export function writeFileConfig(cfg, env = process.env) {
+    writeJsonPrivate(configPath(env), cfg);
+}
+/** The agent key: OS keychain, else the 0600 agent-key file. */
+export function loadAgentKey(env = process.env) {
+    const home = achHome(env);
+    const store = openKeyStore(home, env);
+    return store.get() ?? (store.kind === 'keychain' ? new FileKeyStore(keyFilePath(home)).get() : undefined);
+}
+export function saveAgentKey(key, env = process.env) {
+    const store = openKeyStore(achHome(env), env);
+    store.set(key);
+    return store.kind;
+}
+/** The front-door service token secret: OS keychain, else <home>/cf-secret. */
+export function loadCfSecret(env = process.env) {
+    const home = achHome(env);
+    const store = openCfSecretStore(home, env);
+    return store.get() ?? (store.kind === 'keychain' ? new FileKeyStore(cfSecretPath(home)).get() : undefined);
+}
+/** Store the service token secret (or remove it: undefined). */
+export function saveCfSecret(secret, env = process.env) {
+    const store = openCfSecretStore(achHome(env), env);
+    if (secret)
+        store.set(secret);
+    else
+        store.delete();
+    return store.kind;
+}
+/** B1: the `ach admin` session token (keychain or <home>/admin-session; never config.json). */
+export function loadAdminToken(env = process.env) {
+    return openAdminSessionStore(achHome(env), env).get();
+}
+/** Store the admin session; config.json keeps only whose it is. */
+export function saveAdminToken(token, env = process.env, email) {
+    const store = openAdminSessionStore(achHome(env), env);
+    store.set(token);
+    if (email) {
+        const file = readFileConfig(env);
+        if (file.admin_email !== email)
+            writeFileConfig({ ...file, admin_email: email }, env);
+    }
+    return store.kind;
+}
+/**
+ * Effective config: env wins over the file. Inside a spawned agent (ACH_RUN_TOKEN
+ * set) nothing is read from disk or the keychain: the run token and ACH_HUB are
+ * the only credentials, so the agent key can never be loaded or re-pointed.
+ */
+export function loadConfig(env = process.env) {
+    const runToken = env.ACH_RUN_TOKEN || undefined;
+    const common = {
+        taskId: env.ACH_TASK_ID || undefined,
+        agent: env.ACH_AGENT || undefined,
+        cfId: env.ACH_CF_ID || undefined,
+        cfSecret: env.ACH_CF_SECRET || undefined,
+    };
+    if (runToken) {
+        return { hub: (env.ACH_HUB || '').replace(/\/+$/, '') || undefined, runToken, ...common };
+    }
+    const file = readFileConfig(env);
+    return {
+        hub: (env.ACH_HUB || file.hub || '').replace(/\/+$/, '') || undefined,
+        key: env.ACH_KEY || loadAgentKey(env),
+        ...common,
+        cfId: common.cfId ?? (file.cf_id || undefined),
+        cfSecret: common.cfSecret ?? (file.cf_id ? loadCfSecret(env) : undefined),
+        adminToken: loadAdminToken(env),
+        ...(file.repos && typeof file.repos === 'object' ? { repos: file.repos } : {}),
+        ...(file.interactive_first === true ? { interactiveFirst: true } : {}),
+    };
+}