@synap-core/cli 1.12.2 → 1.13.1-next.20261102.246dc73

package/dist/commands/worker.d.ts

@@ -21,10 +21,33 @@
  * variables are removed from the launched environment so a stray key can never
  * silently switch billing away from the subscription.
  *
+ * Several Claude accounts (`--accounts <file>`, default
+ * ~/.config/synap-worker/accounts.json when it exists): before each launch the
+ * accounts are measured and one is picked (worker-accounts.ts); its token goes
+ * into the run's environment only. A run cut off by a usage limit marks that
+ * account full and is RESUMED (same Claude conversation) on the next account.
+ *
+ * A DESIGN run (the session declares an outcome of kind "design") launches as
+ * `claude --bg` — the only mode that has the Artifact tool — on the account
+ * flagged `design`, and is watched through `claude agents --json` and its
+ * transcript.
+ *
+ * Two PROTOCOLS (`sessionProtocol`): a CODE session is worked in a git
+ * worktree on a `devbox/<id>` branch and ends in a draft PR; a WORK-FOLDER
+ * session (a playbook run over pod data — a video edit, an interview) is
+ * worked in `<work root>/<sessionId>/` with no git, files its outputs back to
+ * the pod, and asks the person through the session's human-owned slots.
+ *
  * State (which sessions were launched, their Claude session ids and outcome)
  * lives in ~/.synap/worker/<agent>/state.json; each run's stream-json goes to
- * ~/.synap/worker/<agent>/runs/<sessionId>.jsonl.
+ * ~/.synap/worker/<agent>/runs/<sessionId>.jsonl. Neither ever holds a token.
+ * A run's verdict is ALSO recorded on its session (`settle`), and the worker's
+ * orient poll carries its served stamp (`X-Synap-Runner`): the pod's proof
+ * that a process serves this agent.
  */
+import { type McpCallClient } from "../lib/mcp-call.js";
+import { type GithubRunEnv, type InstallationTokenSource } from "./worker-github-app.js";
+import { type GitFn } from "./worker-worktrees.js";
 export interface WorkerOptions {
     agent: string;
     interval?: string;
@@ -33,16 +56,29 @@ export interface WorkerOptions {
     maxParallel?: string;
     claudeBin?: string;
     claudeConfigDir?: string;
-    mcpServer?: string;
     allowedTools?: string;
     skipPermissions?: boolean;
     dryRun?: boolean;
+    /** The Claude accounts file (default ~/.config/synap-worker/accounts.json, used when it exists). */
+    accounts?: string;
+    /** The GitHub App env file ({GITHUB_APP_ID, GITHUB_APP_PRIVATE_KEY_FILE}; default ~/.config/synap-agent-app.env when it exists). */
+    githubApp?: string;
+    /** Where work-folder runs get their folder, one per session (default ~/synap-work). */
+    workRoot?: string;
 }
 export interface HandedItem {
     id: string;
     goal: string | null;
+    /**
+     * A session that went quiet (stale) while handed to this agent, handed back
+     * to be RESUMED: it never launches fresh. Absent from an older pod's items.
+     */
+    resume?: true;
+    /** When it went quiet (ISO), with `resume`. */
+    quietSince?: string;
 }
-export type RunStatus = "running" | "done" | "failed";
+/** `limited`: cut off by a usage limit, waiting to be resumed on another account. */
+export type RunStatus = "running" | "done" | "failed" | "limited";
 export interface RunRecord {
     sessionId: string;
     status: RunStatus;
@@ -54,6 +90,58 @@ export interface RunRecord {
     result?: string;
     /** How many times a room follow-up resumed this Claude conversation. */
     resumes?: number;
+    /** How many times a run that failed before Claude started was relaunched. */
+    launchRetries?: number;
+    /** The accounts-file id the latest launch ran on — an id, never a token. */
+    accountId?: string;
+    /** `print` = `claude -p` (default); `bg` = `claude --bg`, a design run. */
+    mode?: "print" | "bg";
+    /** The short id `claude --bg` printed (what `claude agents|stop` take). */
+    bgId?: string;
+    /** When the latest launch (first or resumed) started. */
+    launchedAt?: string;
+    /** How many times a run cut off by a usage limit was resumed on another account. */
+    limitResumes?: number;
+    /** A background run first seen blocked (needs input) at this time. */
+    blockedSince?: string;
+    /** Which protocol the run was launched with (absent: a run from before protocols = code). */
+    protocol?: WorkerProtocol;
+    /** A work-folder run's folder: its cwd, which every resume reuses (Claude finds a conversation by its cwd). */
+    workDir?: string;
+    /** A code run's own folder for its worktrees: its cwd, which every resume reuses. */
+    treeDir?: string;
+    /** Worktrees a finished run left because they hold unpushed or uncommitted work. */
+    keptTrees?: string[];
+    /** The latest launch's process identity (`X-Synap-Process`), what its runner row is keyed by. */
+    process?: string;
+    /** The model the run's Claude Code said it runs (its stream's `init`), reported as `X-Synap-Model`. */
+    model?: string;
+    /** The quiet period (its `quietSince`, "" when the pod gave none) this run was last resumed for. */
+    resumedQuietSince?: string;
+    /** The latest launch's end, not yet recorded on the pod (`settle`): retried each tick until it lands. */
+    unsettled?: PendingSettle;
+    /** When the latest end was recorded on the pod. */
+    settledAt?: string;
+}
+/**
+ * A run's end the pod has not heard yet, saved before the first try so that a
+ * crash or an MCP blip between the local save and the pod write loses nothing:
+ * the next tick (of this worker, or of the next one after a restart) retries it.
+ * It names its own launch, so a later resume of the same session never changes
+ * which runner it ends or which Result post it is.
+ */
+export interface PendingSettle {
+    /** The launch's process identity and conversation: what the pod's runner row is keyed by. */
+    process?: string;
+    claudeSessionId?: string;
+    /** The verdict to record; absent: the pod only hears the runner ended. */
+    verdict?: {
+        status: VerdictStatus;
+        sentence: string;
+    };
+    /** The Result post's `idempotencyKey`: a retry returns the post that already landed. */
+    key: string;
+    attempts: number;
 }
 interface WorkerState {
     runs: Record<string, RunRecord>;
@@ -81,14 +169,67 @@ export declare class AgentPausedError extends Error {
  * block throws `AgentBoundForDispatchError`.
  */
 export declare function parseHandedToYou(orientText: string): HandedItem[];
-/** Sessions handed to the agent that this worker has not launched yet. */
-export declare function pickNew(items: HandedItem[], state: WorkerState, slots: number): HandedItem[];
 /**
- * The MCP server name the local Claude Code uses for THIS pod: the entry in
- * ~/.claude.json whose URL is `<podUrl>/mcp` (user or project scope).
+ * A run that failed BEFORE Claude started (no Claude session: an expired login,
+ * exhausted credits) is relaunched after 30 min, then 1 h, 2 h and 4 h, enough
+ * to outlast a credit reset. A run Claude did start is resumed only by a room
+ * follow-up, never relaunched from scratch.
+ */
+export declare const LAUNCH_RETRY_BASE_MS: number;
+export declare const MAX_LAUNCH_RETRIES = 4;
+/**
+ * Sessions to launch now: never launched, or due a relaunch (see above). A
+ * `resume` item is never one of them: it continues its conversation or waits
+ * (see `tick`), so an empty state file never relaunches every quiet session.
+ */
+export declare function pickNew(items: HandedItem[], state: WorkerState, slots: number, now?: number): HandedItem[];
+/**
+ * The pod MCP server every run gets, under this name, carrying the WORKER
+ * AGENT's own key. Runs never inherit the server in ~/.claude.json: whatever
+ * key that file holds (a `synap login --reconnect` on the box rewrites it with
+ * another agent's) would decide who the run posts as, and the worker would
+ * then read its own posts as follow-ups (2026-10-20).
+ */
+export declare const RUN_MCP_SERVER = "synap-worker";
+/**
+ * The provider every run's model is served by: Anthropic, on the account's
+ * subscription. By construction of the run's environment (`workerEnv`): no
+ * `ANTHROPIC_*` (key, token, base URL) and no provider switch
+ * (`RUN_ENV_BLOCKLIST`) reaches it. Reported as `X-Synap-Model-Provider`.
+ */
+export declare const WORKER_MODEL_PROVIDER = "anthropic";
+export declare function runMcpConfig(podUrl: string, apiKey: string, 
+/** The run's Claude session id: names the conversation to the pod, one id across resumes. */
+claudeSessionId?: string, 
+/** The launch's process identity (`runProcessIdentity`): the pod keeps one runner row per process. */
+processIdentity?: string, 
+/** The model the run is known to use (a resume: what its first launch said), when known. */
+model?: string): {
+    mcpServers: Record<string, unknown>;
+};
+/**
+ * A launch's process identity, `<host>:<pid>:<startedAtMs>` (the pod's
+ * `X-Synap-Process`). The config is written before `claude` exists, so the pid
+ * is the worker's and the time is the launch's: a resume is a new launch and
+ * reads as a new process, never a twin of the one that ended.
+ */
+export declare function runProcessIdentity(launchedAtMs: number, hostname?: string, pid?: number): string;
+/**
+ * The headers of the worker's calls once a run's process exited: the run's
+ * conversation and process, state `ended`, so the pod ends that runner at once
+ * rather than when its live window runs out. None for a run that never named
+ * its conversation or process.
  */
-export declare function findMcpServerName(claudeJson: unknown, podUrl: string): string | null;
+export declare function runEndHeaders(rec: Pick<RunRecord, "claudeSessionId" | "process" | "model">): Record<string, string> | undefined;
+/** Writes the run config owner-only (it holds the key) and returns its path. */
+export declare function writeRunMcpConfig(dir: string, config: {
+    mcpServers: Record<string, unknown>;
+}, name?: string): string;
 export declare const DEFAULT_ALLOWED_TOOLS: string[];
+/** The tools a design run adds: the claude.ai Artifact tool (and the search that loads deferred tools). */
+export declare const DESIGN_EXTRA_TOOLS: string[];
+/** The tools a work-folder run adds: skills (the HyperFrames workflow is one). */
+export declare const WORK_FOLDER_EXTRA_TOOLS: string[];
 /** The protocol the launched Claude Code follows for one handed session. */
 export declare function buildWorkerPrompt(p: {
     sessionId: string;
@@ -96,11 +237,216 @@ export declare function buildWorkerPrompt(p: {
     agentName: string;
     cwd: string;
     mcpServer: string;
+    /** A design run: the deliverable is a claude.ai Design artifact. */
+    design?: boolean;
+    /** A code run's own folder: where its worktrees go, so two runs never share a checkout. */
+    treeDir?: string;
+}): string;
+/** How long a work-folder run waits for an answer to its ask before it ends `blocked`. */
+export declare const ASK_WAIT_MINUTES = 30;
+/**
+ * The protocol for a WORK-FOLDER session (`sessionProtocol`): no git; files in
+ * the session's folder; outputs filed to the pod; questions asked through a
+ * human-owned slot with an ask (what Content Studio, Relay and the Needs-you
+ * list show), never a room `QUESTION:` line.
+ */
+export declare function buildWorkFolderPrompt(p: {
+    sessionId: string;
+    goal: string | null;
+    agentName: string;
+    workDir: string;
+    mcpServer: string;
 }): string;
-/** The launched environment: the subscription, never a stray API key. */
-export declare function workerEnv(base: NodeJS.ProcessEnv, claudeConfigDir?: string): NodeJS.ProcessEnv;
+/**
+ * What the allowlist's `CLAUDE_*` must NOT pass: the variables that switch
+ * Claude Code off the subscription to another provider (Bedrock, Vertex,
+ * Foundry, Bedrock Mantle, Claude Platform on AWS — `CLAUDE_CODE_USE_*`), skip
+ * that provider's own auth for a gateway (`CLAUDE_CODE_SKIP_*_AUTH`), or hand
+ * routing to a host platform (`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`). Any
+ * future `CLAUDE_CODE_USE_*` provider is blocked too; the one `USE_` flag that
+ * is not a provider (the Windows PowerShell tool) passes. Without this a run
+ * would report `anthropic` while another provider served it.
+ */
+export declare const RUN_ENV_BLOCKLIST: RegExp[];
+export declare const RUN_ENV_ALLOWLIST: RegExp[];
+/**
+ * The launched environment, built from an ALLOWLIST: a secret in the worker's
+ * own environment (its env file holds deploy tokens) never reaches a run's
+ * Bash. The subscription, never a stray API key. With an account picked, its
+ * token REPLACES any token the worker inherited. GitHub: only the App's.
+ */
+export declare function workerEnv(base: NodeJS.ProcessEnv, claudeConfigDir?: string, oauthToken?: string, github?: GithubRunEnv): NodeJS.ProcessEnv;
+export interface LimitHit {
+    error: string;
+    /** When the limit lifts (ms), when Claude Code said. */
+    resetsAt?: number;
+}
+/** What one run's events say about how it ended. */
+export interface RunEnd {
+    claudeSessionId?: string;
+    /** The model the stream's `init` names, when it is an id the pod keeps. */
+    model?: string;
+    /** The `result` text (stream) or the last main assistant text (transcript). */
+    text?: string;
+    /** Set when the run's LAST main-thread turn was refused by a usage limit. */
+    limit?: LimitHit;
+    isError?: boolean;
+}
+/**
+ * Fold one event (a stream-json line of `claude -p`, or a transcript line of
+ * a background session — the two spell the fields differently) into the run's
+ * ending. A later healthy assistant message clears an earlier limit: only a
+ * run whose last turn hit the limit "ended on a limit".
+ */
+export declare function foldRunEvent(end: RunEnd, ev: Record<string, unknown>, rejectedResetsAt?: {
+    at?: number;
+}): RunEnd;
+/** A run that printed its WORKER-RESULT verdict finished its protocol: never a limit. */
+export declare function endedOnLimit(end: RunEnd): LimitHit | undefined;
+/** How long an account stays out after a limit with no reset time given. */
+export declare function limitUntil(hit: LimitHit, now: number): number;
+/** At most this many usage-limit resumes per session. */
+export declare const MAX_LIMIT_RESUMES = 6;
+/** The prompt that resumes a run a usage limit cut off, on another account. */
+export declare const LIMIT_RESUME_PROMPT = "Continue where you stopped. Your previous turn was cut off by a Claude usage limit and this session moved to another account. Same protocol; end with one line: WORKER-RESULT: done | blocked | failed \u2014 <one sentence>.";
+/**
+ * The structured signal for a DESIGN run: the session declares an outcome of
+ * kind "design" (`synap_get_session` → `outcomes.outcomes[].kind`, the
+ * playbook's `expectedOutputs: [{kind: "design", label: "Design"}]`). The goal
+ * text is never read for it. A session whose outcomes could not be read
+ * THROWS: an unreadable session is not "not a design run".
+ */
+export declare const DESIGN_OUTCOME_KIND = "design";
+export declare function isDesignSession(getSessionText: string): boolean;
+/**
+ * `code`: a git worktree, a `devbox/<id>` branch, a draft PR, room `QUESTION:`s.
+ * `work-folder`: a folder per session, no git, outputs filed to the pod, asks
+ * through the session's human-owned slots.
+ */
+export type WorkerProtocol = "code" | "work-folder";
+/** The run params that name a repository — the ones the pod's dispatch path mounts (`repoInputs`, external-agent-executor.ts). */
+export declare const REPO_PARAM_KEYS: readonly ["repo", "repos", "branch"];
+/** Deliverable kinds that only code work yields: the dispatch path's code outputs (`ExternalAgentOutputKey`) and `code`. */
+export declare const CODE_OUTPUT_KINDS: readonly ["pull_request", "branch", "code"];
+/**
+ * Which protocol a handed session gets, from the `synap_get_session` read.
+ *
+ * A session that runs NO playbook is an ad-hoc hand-off ("start this on my
+ * devbox"): the code protocol, exactly as before protocols existed. A PLAYBOOK
+ * RUN (`session.playbookId`) is a process over pod data — Produce Content's
+ * video edit, a CRM list, an interview — and gets the work-folder protocol,
+ * unless it carries code context: a repo or branch in its run params
+ * (`session.metadata.params`, read the same way the dispatch path reads them)
+ * or a code deliverable declared on the session or on any of its stages
+ * (`expectedOutputs`, `stages[].expectedOutputs`), so a code playbook stays
+ * code from its first stage on. The goal text is never read. An unreadable
+ * session THROWS: it is not "a code session".
+ */
+export declare function sessionProtocol(getSessionText: string): WorkerProtocol;
+/** A work-folder run's folder: `<root>/<sessionId>`. */
+export declare function workFolderFor(root: string, sessionId: string): string;
+/** The short id `claude --bg` prints ("backgrounded · fd009109"). */
+export declare function parseBgId(output: string): string | undefined;
+export interface BgEntry {
+    id: string;
+    sessionId?: string;
+    /** Background sessions: working | blocked | done | failed (Claude Code 2.1.296+). */
+    state?: string;
+    status?: string;
+}
+/** `claude agents --json --all` → entries. Anything but a JSON list THROWS (a failed read is not "gone"). */
+export declare function parseAgentsList(text: string): BgEntry[];
+export type BgPhase = "running" | "finished" | "blocked" | "gone";
+export declare function bgPhase(entry: BgEntry | undefined): BgPhase;
+/** The transcript of a Claude session: `<config>/projects/<any>/<sessionId>.jsonl`. */
+export declare function findTranscript(claudeConfigDir: string | undefined, sessionId: string): string | undefined;
+/** How a background run's transcript ends, reading only entries written since `sinceMs`. */
+export declare function readTranscriptEnd(text: string, sinceMs: number): RunEnd & {
+    seen: number;
+};
+/** A background run blocked (it needs input nobody will give) this long is ended. */
+export declare const BG_BLOCKED_MAX_MS: number;
+/** A background run not yet listed, or listed with nothing new, is waited for this long after launch. */
+export declare const BG_SETTLE_MS: number;
 /** The final `WORKER-RESULT:` line of a run's result text, if present. */
 export declare function workerVerdict(resultText: string | undefined): string | undefined;
+export type VerdictStatus = "done" | "blocked" | "failed";
+/**
+ * `done — <sentence>` (a `workerVerdict`) → its status and sentence; anything
+ * else is no verdict. The prompt's own template echoed back
+ * (`done | blocked | failed — …`) names no status: it is no verdict either.
+ */
+export declare function parseVerdict(verdict: string | undefined): {
+    status: VerdictStatus;
+    sentence: string;
+} | undefined;
+/**
+ * The verdict the session hears, given how the process ended: `done` only from
+ * a run that exited cleanly; a run that said `done` and then exited non-zero is
+ * `failed`, with what it said kept. `blocked` and `failed` stand as they are.
+ */
+export declare function verdictForExit(v: {
+    status: VerdictStatus;
+    sentence: string;
+}, exitedOk: boolean, exitCode?: number | null): {
+    status: VerdictStatus;
+    sentence: string;
+};
+/** The one room line a verdict becomes. */
+export declare function verdictRoomLine(v: {
+    status: VerdictStatus;
+    sentence: string;
+}): string;
+/**
+ * What the room hears from a run that FAILED without a verdict (it crashed,
+ * exited non-zero without `WORKER-RESULT:`, sat blocked, vanished, ran out of
+ * usage-limit resumes, or the worker restarted under it): how it ended and the
+ * reason the record keeps, on one line.
+ */
+export declare function deadRunSentence(rec: Pick<RunRecord, "result" | "exitCode">): string;
+/**
+ * At most this many tries to record one run's end on the pod. A retry runs
+ * only after the tick's orient read answered, so a pod outage does not use them up.
+ */
+export declare const MAX_SETTLE_ATTEMPTS = 10;
+/**
+ * The end a run owes the pod, given what it said and how its process ended:
+ * its verdict (`verdictForExit`), or for a run that failed without one a
+ * synthesised `failed` (`deadRunSentence`), so a dead run is never silent.
+ * `undefined` when there is nothing to tell (no verdict, not failed, and no
+ * runner to end).
+ */
+export declare function pendingSettle(rec: RunRecord, verdictLine: string | undefined, exitedOk: boolean): PendingSettle | undefined;
+/**
+ * Outcome kinds a verdict never claims: a pull request is delivered only when
+ * it merges (rule work-units), and the merge sweeper marks it met then; a
+ * branch or a commit is a step toward that PR, not a deliverable of its own.
+ */
+export declare const UNCLAIMABLE_OUTCOME_KINDS: ReadonlySet<string>;
+/** What the session read says a `done` verdict may claim. */
+export type VerdictClaim = {
+    kind: "one";
+    key: string;
+} | {
+    kind: "none";
+} | {
+    kind: "several";
+    keys: string[];
+}
+/** The outcomes list could not be read: nothing is claimed, and that is said. */
+ | {
+    kind: "unreadable";
+    why: string;
+};
+/**
+ * The outcome a `done` verdict claims, from the `synap_get_session` read: the
+ * session's ONE open deliverable the agent owns (not a fact, not the person's,
+ * not met, not withdrawn, never a PR, branch or commit). None, or several, and
+ * nothing is claimed: which of several the run finished is the run's to say
+ * (it claims each as it records it). An outcomes list that could not be read is
+ * `unreadable`, never "none open".
+ */
+export declare function verdictClaim(getSessionText: string): VerdictClaim;
 export interface RoomMessage {
     id?: string;
     content?: string;
@@ -116,7 +462,57 @@ export declare const MAX_RESUMES = 20;
  * run. The worker's own posts carry its agent id and never resume it.
  */
 export declare function followUpsSince(messages: RoomMessage[], since: string, selfAgentId: string): RoomMessage[];
+/**
+ * Whether a session's quiet period began with THIS worker's own run: the pod's
+ * `quietSince` is the session's newest activity, and the run's own room posts
+ * (its claim, its "Look at first:", the worker's `Result:` line) count. Quiet
+ * since then means the run ended and nothing happened after it; resuming it
+ * would only re-run it (up to MAX_RESUMES paid runs). Someone else's message
+ * after the run resumes it through the follow-up path instead.
+ */
+export declare function quietIsOwnRun(item: Pick<HandedItem, "quietSince">, rec: Pick<RunRecord, "launchedAt">): boolean;
+/** The prompt that resumes a run whose session went quiet and was handed back (`resume`). */
+export declare function buildQuietResumePrompt(quietSince: string | undefined): string;
 /** The prompt that resumes a finished run with the room's new messages. */
 export declare function buildFollowUpPrompt(messages: RoomMessage[]): string;
+export interface ExecResult {
+    code: number | null;
+    stdout: string;
+    stderr: string;
+}
+/** Runs a short-lived command (`claude --bg`, `claude agents`, `claude stop`). */
+export type ExecFn = (bin: string, args: string[], o: {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+}) => Promise<ExecResult>;
+export interface WorkerDeps {
+    mcp: McpCallClient;
+    podUrl: string;
+    apiKey: string;
+    /** The worker agent's own user id: its posts never resume it. */
+    selfAgentId: string;
+    exec?: ExecFn;
+    /** The account probe's fetch (tests stub it). */
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+    say?: (line: string) => void;
+    /** The App's installation token (tests stub it); default: from the GitHub App file, when there is one. */
+    githubToken?: InstallationTokenSource;
+    /** `git` for the worktree sweep (tests stub it). */
+    git?: GitFn;
+}
+export interface Worker {
+    tick(): Promise<{
+        handed: number;
+        launched: number;
+    }>;
+    /** Re-read the background runs' state (design runs). */
+    watch(): Promise<void>;
+    waitForChildren(): Promise<void>;
+    backgroundRunning(): number;
+    stop(): void;
+    readonly state: WorkerState;
+}
+export declare function createWorker(opts: WorkerOptions, deps: WorkerDeps): Worker;
 export declare function workerCommand(opts: WorkerOptions): Promise<void>;
 export {};