@synap-core/cli 1.11.0 → 1.13.0

package/dist/commands/worker.d.ts

@@ -0,0 +1,331 @@
+/**
+ * `synap worker` — run Claude Code unattended on THIS machine for the sessions
+ * a person or an AI handed to an agent.
+ *
+ * The door it reuses: a session's roster. Putting an agent on a focus session
+ * (`synap_start_session` agentIds, `synap_update_session` addAgentId, capture
+ * "Give to agent") is how work is handed to it, and `synap_orient` lists those
+ * sessions as `handedToYou` for that agent. The worker is that agent: it polls
+ * orient with the agent's own key, claims each new session once, and launches
+ * the unmodified `claude` binary headless in the workspace with a protocol
+ * prompt. The launched Claude Code does the work and talks in the session room
+ * through the Synap MCP — so the AI that launched the session (the
+ * orchestrator) and the person read and answer it there, and relay shows it.
+ *
+ * Synap never spawns a coding agent: this process runs on the person's own
+ * machine, under their own Claude login, as an agent they connected.
+ *
+ * Which Claude subscription a run uses = which Claude config the process sees:
+ * `--claude-config-dir` sets CLAUDE_CONFIG_DIR for the launched runs (log that
+ * directory in once with `CLAUDE_CONFIG_DIR=<dir> claude login`). API-key
+ * 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. Neither ever holds a token.
+ */
+import { type McpCallClient } from "../lib/mcp-call.js";
+export interface WorkerOptions {
+    agent: string;
+    interval?: string;
+    once?: boolean;
+    cwd?: string;
+    maxParallel?: string;
+    claudeBin?: string;
+    claudeConfigDir?: string;
+    allowedTools?: string;
+    skipPermissions?: boolean;
+    dryRun?: boolean;
+    /** The Claude accounts file (default ~/.config/synap-worker/accounts.json, used when it exists). */
+    accounts?: string;
+    /** Where work-folder runs get their folder, one per session (default ~/synap-work). */
+    workRoot?: string;
+}
+export interface HandedItem {
+    id: string;
+    goal: string | null;
+}
+/** `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;
+    startedAt: string;
+    finishedAt?: string;
+    pid?: number;
+    claudeSessionId?: string;
+    exitCode?: number | null;
+    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;
+}
+interface WorkerState {
+    runs: Record<string, RunRecord>;
+}
+/** "30s" | "2m" | "1h" | "45" (seconds) → milliseconds. */
+export declare function parseInterval(raw: string | undefined, fallbackMs?: number): number;
+/**
+ * The pod hands this agent its work through a provider binding (reach
+ * `dispatch`), so it lists nothing to pull: a worker pulling for it would run
+ * the same work a second time. The worker stops on it.
+ */
+export declare class AgentBoundForDispatchError extends Error {
+    constructor();
+}
+/**
+ * A person PAUSED this agent: it takes no new work until resumed. Not a failed
+ * read — the worker keeps polling and launches nothing.
+ */
+export declare class AgentPausedError extends Error {
+    constructor();
+}
+/**
+ * Read `handedToYou` out of `synap_orient`'s text. A missing or `unavailable`
+ * block is a FAILED read and throws — never "nothing handed to me". A `bound`
+ * block throws `AgentBoundForDispatchError`.
+ */
+export declare function parseHandedToYou(orientText: string): HandedItem[];
+/**
+ * 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). */
+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";
+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): {
+    mcpServers: Record<string, unknown>;
+};
+/** 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;
+    goal: string | null;
+    agentName: string;
+    cwd: string;
+    mcpServer: string;
+    /** A design run: the deliverable is a claude.ai Design artifact. */
+    design?: boolean;
+}): 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. With an
+ * account picked, its token REPLACES any token the worker inherited.
+ */
+export declare function workerEnv(base: NodeJS.ProcessEnv, claudeConfigDir?: string, oauthToken?: string): 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 `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 interface RoomMessage {
+    id?: string;
+    content?: string;
+    timestamp?: string;
+    authorType?: string;
+    routedTeammateId?: string | null;
+}
+/** At most this many follow-up resumes per session (a runaway-loop guard). */
+export declare const MAX_RESUMES = 20;
+/**
+ * Room messages posted after `since` by anyone but this agent — the follow-ups
+ * (an orchestrator's ANSWER, the person's reply) that should resume a finished
+ * 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[];
+/** 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;
+}
+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 {};