@koalaauto/agentchannel 0.0.0-stage → 3.0.0

package/dist/src/runner/runner.d.ts

@@ -0,0 +1,212 @@
+import type { RuntimeAdapter } from '../adapters/types.js';
+import { type Agent, type Client, type MentionItem, type Message } from '../client.js';
+import { type Perm } from '../perm.js';
+import { RunnerState } from './state.js';
+import type { Workspace } from './workspace.js';
+export type RunnerClient = Pick<Client, 'me' | 'inbox' | 'claim' | 'getTask' | 'postMessage' | 'complete' | 'fail' | 'usage' | 'heartbeat' | 'answerRun' | 'endRun'> & Partial<Pick<Client, 'download' | 'channelPosts' | 'mentionRun' | 'mentionEnd' | 'mentionUsage' | 'promptSize'>>;
+export interface RunnerOptions {
+    client: RunnerClient;
+    adapter: RuntimeAdapter;
+    workspace: Workspace;
+    home: string;
+    hub: string;
+    /** --dir: cwd for answer runs on tasks without a worktree. */
+    dir: string;
+    max?: number;
+    perm?: Perm;
+    intervalMs?: number;
+    heartbeatMs?: number;
+    idleMs?: number;
+    cfId?: string;
+    cfSecret?: string;
+    /** Extra env var names passed to spawned agents (`--pass-env`). */
+    passEnv?: string[];
+    baseEnv?: NodeJS.ProcessEnv;
+    log?: (s: string) => void;
+    newRunId?: () => string;
+    /**
+     * P1: leave new tasks alone for this long after they were sent, so the
+     * owner can claim them interactively first (default 0: claim at once).
+     */
+    claimDelayMs?: number;
+    /** Client acting with a run token (posts structured answers for codex). Default: a hub Client. */
+    tokenClient?: (token: string) => Pick<Client, 'postMessage' | 'reply'>;
+    /** §19: base URL for links in prompts (ACH_PUBLIC_URL); default the hub URL. */
+    publicUrl?: string;
+    /** B1: where per-task scratch HOMEs for spawned agents live (default <tmpdir>/ach-homes). */
+    agentHomesDir?: string;
+    /** §16: how many recent channel posts work prompts carry (default 15; 0 = none). */
+    channelContext?: number;
+}
+export type Job = {
+    kind: 'work';
+    taskId: string;
+}
+/** nudge: the agent stopped without finishing; ask it once to complete, fail or ask. */
+ | {
+    kind: 'resume';
+    taskId: string;
+    replies: Message[];
+    nudge?: boolean;
+} | {
+    kind: 'answer';
+    taskId: string;
+    question: Message;
+} | {
+    kind: 'mention';
+    item: MentionItem;
+};
+export declare function jobKey(j: Job): string;
+interface Active {
+    job: Job;
+    controller: AbortController;
+    /** lost: the hub says this run no longer owns the task (heartbeat 409, C3). */
+    reason?: 'cancel' | 'idle' | 'stop' | 'lost' | 'auth';
+    done: Promise<void>;
+    /** Job to start right after this one frees its slot (e.g. resume on replies that arrived mid-run). */
+    followUp?: Job;
+}
+/** A gate decision that lets the run go ahead (S1). Anything else rejects. */
+export declare function approves(decision: string): boolean;
+export declare function newRunId(): string;
+/**
+ * What the worker is still waiting on: its own open questions, blocking decision
+ * requests, and (non-blocking) decision requests that replace one of its questions.
+ */
+export declare function openRequests(messages: Message[], myId: string): Message[];
+/** A human note addressed to me (panel composer / `ach admin note`): wakes a parked run. */
+export declare function isHumanNoteTo(m: Message, myId: string): boolean;
+/** Answers / decisions replying to something I asked, and human notes to me, that the worker has not been shown yet. */
+export declare function unseenReplies(messages: Message[], myId: string, seen: string[]): Message[];
+/**
+ * Runner files a spawned agent must never read: the agent key (config.json), other
+ * runs' tokens (runs.json), session ids and logs. Not the whole home: the per-task
+ * worktrees live in <home>/work and must stay readable.
+ */
+export declare function secretPaths(home: string): string[];
+/**
+ * Runtime config a spawned agent's CLI needs from the real home: linked into the
+ * scratch home. Claude only: its user settings, hooks and MCP servers are not
+ * loaded anyway (settingSources [], strictMcpConfig). Codex is NOT linked: it
+ * gets its own CODEX_HOME (see prepareCodexHome).
+ */
+export declare const RUNTIME_HOME_LINKS: string[];
+/**
+ * macOS (live test): Claude Code keeps its login in the login keychain, which
+ * `security` finds through $HOME/Library/Keychains. Without this link a worker
+ * with a scratch HOME reports "Not logged in". Only the folder is linked; the
+ * sandbox still denies the worker's tools every path under the real home.
+ */
+export declare function runtimeHomeLinks(platform?: NodeJS.Platform): string[];
+/** The config.toml of a worker's own CODEX_HOME: nothing from the user's global config (no mcp_servers, profiles, notify hooks). */
+export declare const CODEX_WORKER_CONFIG: string;
+/**
+ * Codex isolation (live test): a worker run must not load the user's global
+ * Codex config (~/.codex/config.toml: MCP servers with their own credentials,
+ * profiles, notify hooks, AGENTS.md). The run gets its own CODEX_HOME holding
+ * only a generated config.toml and a symlink to the login file (auth.json) of
+ * the user's Codex home. The login file is placed by path only: it is never
+ * opened or copied here. Codex rewrites it in place through the link, so a
+ * refreshed login stays the user's. Sessions of the run stay in this home, so
+ * a resumed run of the same task finds its thread.
+ */
+export declare function prepareCodexHome(home: string, realCodexHome?: string): string;
+/**
+ * B1: a per-task scratch HOME for spawned agents, so `~/.config/agentchannel`
+ * (agent key file, admin session, runner state) is not reachable through
+ * $HOME. Runtime config (.claude, .codex) is linked, the git identity
+ * (.gitconfig) copied; npm keeps the real cache via npm_config_cache.
+ */
+export declare function prepareAgentHome(root: string, agentName: string, key: string, realHome?: string, realCodexHome?: string): {
+    home: string;
+    env: Record<string, string>;
+};
+export declare function budgetBlocked(me: Agent): boolean;
+export declare class Runner {
+    readonly state: RunnerState;
+    readonly queue: Job[];
+    readonly active: Map<string, Active>;
+    me?: Agent;
+    private o;
+    private stopped;
+    private waiters;
+    private lastPrune;
+    /** Last heartbeat sent for each parked run. */
+    private parkedHb;
+    /** B7: set when the hub answered 401 (key rotated, agent or owner deactivated): the runner stops. */
+    fatal?: 'unauthorized';
+    private wake?;
+    constructor(opts: RunnerOptions);
+    private log;
+    private taskLog;
+    private isQueuedOrActive;
+    enqueue(job: Job, front?: boolean): boolean;
+    /** Re-claim runs that were active when the runner died (§14.10). */
+    recover(): void;
+    /**
+     * B7: a 401 from inbox, heartbeat or claim means the key no longer works.
+     * Abort every job without posting anything (no fail, no usage) and stop.
+     */
+    authFailed(where: string): void;
+    /** One poll cycle. */
+    tick(): Promise<void>;
+    private notifyBudget;
+    /**
+     * Cancel running jobs whose task went terminal; forget parked runs of
+     * terminal tasks; keep parked leases alive; and (C1) resume a parked run
+     * whose task is back to `working` with nothing left to wait for.
+     */
+    checkActive(): Promise<void>;
+    /** Heartbeat a run; adopt a refreshed run token (C5). Throws HubError 409 when the run lost the task. */
+    private heartbeat;
+    /** C8: drop runs.json bookkeeping for terminal (or vanished) tasks, every 10 minutes. */
+    prune(force?: boolean): Promise<void>;
+    pump(): void;
+    /** Resolves when nothing is queued or running (tests). */
+    drain(): Promise<void>;
+    private runJob;
+    private ensureMe;
+    private runWork;
+    private runResume;
+    /** S10: the agent cannot write .git, so the runner commits its changes after every work run. */
+    private commitWork;
+    private afterWork;
+    /** Base URL for links shown to agents (§19). */
+    private base;
+    /** The task's absolute permalink: the hub's (ACH_PUBLIC_URL on the hub), else built here. */
+    private linkOf;
+    /** Memory trial metrics: the total size of a full work prompt (best effort, never blocks the run). */
+    private reportPromptSize;
+    /** §16: the latest posts of the task's channel (best effort). */
+    private channelContext;
+    /**
+     * §16 mention run: read-only, in --dir, with a run token that may only read
+     * the channel and reply in this thread. The hub hands each mention out once.
+     */
+    private runMention;
+    /** Codex mention runs: the runner posts the reply the agent returned. */
+    private postStructuredReply;
+    private markHandled;
+    private runAnswer;
+    /** Codex answer runs (S4): read-only and offline; the runner posts what the agent returned. */
+    private postStructuredAnswer;
+    /** Readable roots for the spawned agent besides its cwd (S4). */
+    private readRoots;
+    /** Where a task's attachments are downloaded for its agents (readable, outside the worktree). */
+    filesDir(taskId: string): string;
+    /** The task's attachments, downloaded into filesDir (best effort: a failed download is listed without a path). */
+    private fetchFiles;
+    /** Run the adapter with heartbeat, idle watchdog, session persistence and usage posting. */
+    private execute;
+    /** Polls until stop() or a 401 (B7: resolves 'unauthorized' after aborting every job). */
+    start(): Promise<'stopped' | 'unauthorized'>;
+    /** Stop polling; abort running jobs without failing their tasks (they resume on restart). */
+    stop(): Promise<void>;
+}
+/** `ach run --gc`: remove work dirs of tasks terminal for more than `days` (branches are kept). */
+export declare function gcWorktrees(client: Pick<Client, 'getTask'>, ws: Workspace, o?: {
+    days?: number;
+    now?: number;
+    log?: (s: string) => void;
+}): Promise<string[]>;
+export {};