@esso0428/pi-subagents 0.17.5 → 0.17.7

package/dist/workflow/runtime.d.ts

@@ -0,0 +1,335 @@
+/**
+ * runtime.ts — the host half of a workflow run.
+ *
+ * Owns the worker lifecycle, the RPC bridge, the concurrency semaphore, the
+ * per-run caps, and the progress log. The script's only route to an agent is a
+ * `call` message landing here, which is what makes the caps and the abort story
+ * enforceable at all: a script cannot go around them because it has nothing to
+ * go around them *with*.
+ *
+ * Spawning is injected rather than imported. `AgentManager` is a large, stateful
+ * dependency and wiring it in directly would make every test here an integration
+ * test; a {@link WorkflowHost} stub is a dozen lines. The adapter that binds this
+ * to the real manager lives at the call site.
+ */
+import { type WorkflowJournalEntry } from "./journal.js";
+import { type CompiledSchema } from "./json-schema.js";
+import { type WorkflowMeta } from "./meta.js";
+import type { WorkflowEntry } from "./progress.js";
+/** Matches the `script` field's `maxLength` in the tool schema. */
+export declare const MAX_SCRIPT_LENGTH = 524288;
+/** Agents one run may schedule, in total. */
+export declare const WORKFLOW_AGENT_CAP = 1000;
+/** Items one `parallel()` or `pipeline()` call may take. */
+export declare const WORKFLOW_ITEM_CAP = 4096;
+/** Nested `workflow()` invocations allowed per run. */
+export declare const WORKFLOW_NESTED_CAP = 256;
+export declare class WorkflowRuntimeError extends Error {
+}
+/**
+ * Concurrent agents allowed, leaving two cores for the host and the TUI.
+ *
+ * `Math.max(1, …)` is not decoration: the raw `min(16, cpus - 2)` is 0 on a one-
+ * or two-core machine, and a semaphore with zero permits never hands out a slot,
+ * so the run would hang before its first agent rather than fail.
+ */
+export declare function workflowConcurrency(cpuCount?: number): number;
+/** One agent the script asked for. `agentId` is the handle for {@link WorkflowHost.abortAgent}. */
+export interface WorkflowSpawnRequest {
+    agentId: string;
+    /** Position in the run, and the progress entry's stable identity. */
+    index: number;
+    prompt: string;
+    label: string;
+    agentType: string;
+    model?: string;
+    /**
+     * Reasoning effort for this child, as one of pi's thinking levels.
+     *
+     * Typed as a plain string because this interface is the host boundary and
+     * deliberately knows nothing about pi — `host.ts` is where it becomes a
+     * `ThinkingLevel`. The worker has already rejected anything off the list.
+     */
+    effort?: string;
+    isolation?: "worktree";
+    /**
+     * Called by the host once the child's EFFECTIVE configuration is known —
+     * which is when its session exists, not when the spawn resolves.
+     *
+     * Without it a row could only ever show what the script asked for: a fuzzy
+     * `model: "haiku"` stays `haiku` instead of the id it resolved to, an
+     * `agent()` that named no model shows nothing at all, and a level pi clamped
+     * is presented as the level that was requested (#168, #182).
+     *
+     * Plain strings, like `effort` above: this interface is the host boundary and
+     * deliberately knows nothing about pi's `AgentInvocation`. Optional, so a host
+     * that cannot report any of this simply does not, and the row keeps the
+     * requested values it started with.
+     */
+    onResolved?(info: {
+        /**
+         * The host's own id for the child — the manager's `AgentRecord` id here.
+         *
+         * Reported as soon as the host has one, which is earlier than the rest of
+         * this: the model is knowable only once a session exists, but the id is
+         * what lets a reader open that child's conversation, and a child that
+         * never got a model is exactly the one worth opening.
+         */
+        recordId?: string;
+        modelName?: string;
+        modelId?: string;
+        thinking?: string;
+        requestedThinking?: string;
+        requestedModel?: string;
+    }): void;
+    /**
+     * Compiled from the script's `agent({ schema })`.
+     *
+     * The host must give the child a `StructuredOutput` tool built from it and
+     * return the validated payload as JSON text. Compiled rather than raw so the
+     * runtime can re-check the answer without re-parsing the schema per call.
+     */
+    schema?: CompiledSchema;
+    phaseIndex?: number;
+    phaseTitle?: string;
+    /**
+     * The `gate` command this agent is being spawned under, when it has one.
+     *
+     * Passed down rather than run purely from here because an isolated child's
+     * worktree is destroyed as part of its own settle: a host that can reach
+     * inside that settle runs the gate there, against the tree the child wrote,
+     * and reports the outcome back as {@link WorkflowSpawnResult.gate}. A host
+     * that ignores this leaves the gate to {@link applyGate}, which then runs it
+     * itself — so exactly one execution either way.
+     */
+    gate?: string;
+}
+export interface WorkflowSpawnResult {
+    ok: boolean;
+    /** The agent's answer. Present when `ok`. */
+    text?: string;
+    /** Why it failed. Present when not `ok`. */
+    error?: string;
+    /** The user dismissed it rather than it failing; renders as skipped. */
+    skipped?: boolean;
+    tokens?: number;
+    /**
+     * Output tokens only, for the script's `budget.spent()`.
+     *
+     * Separate from {@link tokens}, which is the lifetime total. Claude Code's
+     * budget counts output, and a fan-out's re-sent input would swamp it.
+     */
+    outputTokens?: number;
+    /** Whether the child needed an extra prompt to produce its structured answer. */
+    structuredRetried?: boolean;
+    toolCalls?: number;
+    /**
+     * Where the child actually ran.
+     *
+     * Only meaningful for `isolation: "worktree"`, and the whole reason it exists:
+     * a gate has to run against the tree the child edited, not the main one, or it
+     * verifies the wrong working copy. Left unset, a gate runs wherever the host
+     * runs commands by default.
+     *
+     * Usually unset for a worktree child even so: the copy is removed during the
+     * child's own settle, so it no longer exists by the time this is read. That
+     * is what {@link gate} is for.
+     */
+    cwd?: string;
+    /**
+     * The outcome of this agent's `gate`, when the host already ran it.
+     *
+     * Set only by a host that ran the command itself — inside the child's
+     * worktree, while that directory still existed. Its presence is what tells
+     * {@link applyGate} the command has already been executed; the pass/fail
+     * decision and the error shaping still happen there, in one place.
+     */
+    gate?: WorkflowGateResult;
+}
+/** Outcome of a `gate` command. `output` is what the user is shown when it fails. */
+export interface WorkflowGateResult {
+    ok: boolean;
+    /** Combined stdout/stderr, or whatever the host wants surfaced as the failure. */
+    output: string;
+}
+/** The one seam between a workflow and the rest of the extension. */
+/** How a script names another workflow: a saved name, or a path to a file. */
+export interface WorkflowScriptRef {
+    name?: string;
+    scriptPath?: string;
+}
+export type WorkflowScriptSource = {
+    ok: true;
+    script: string;
+    path?: string;
+} | {
+    ok: false;
+    message: string;
+};
+export interface WorkflowHost {
+    spawnAgent(request: WorkflowSpawnRequest): Promise<WorkflowSpawnResult>;
+    /** Called for every in-flight agent when the run aborts. */
+    abortAgent(agentId: string): void;
+    /**
+     * Continue a child that already ran in this run, keeping its context.
+     *
+     * `agentId` is one previously handed out in a {@link WorkflowSpawnRequest};
+     * the child keeps the agent type, model and tool contract it started with, so
+     * only the follow-up prompt crosses.
+     *
+     * Optional: a host without it rejects `resume` rather than quietly starting a
+     * fresh child that has none of the context the script is counting on.
+     */
+    resumeAgent?(agentId: string, prompt: string, 
+    /**
+     * Same reporter {@link WorkflowSpawnRequest.onResolved} carries, for the
+     * same reason: a resumed row is rebuilt from scratch, so without it the
+     * continuation of a child would show the model the script *asked* for while
+     * the row above it shows the one that ran.
+     */
+    onResolved?: WorkflowSpawnRequest["onResolved"]): Promise<WorkflowSpawnResult>;
+    /**
+     * Run a `gate` command and report whether it passed.
+     *
+     * `cwd` is the child's worktree when it had one. Optional for the same reason
+     * as {@link resumeAgent}, and more sharply: a gate that silently does not run
+     * would mark unverified work as verified, so the runtime fails the call
+     * instead of skipping it.
+     */
+    runGate?(command: string, options: {
+        agentId: string;
+        cwd?: string;
+    }): Promise<WorkflowGateResult>;
+    /**
+     * Resolve a nested `workflow()` reference to source.
+     *
+     * The runtime knows nothing about the filesystem or about pi, so it asks. It
+     * still decides whether what comes back *is* a workflow — see
+     * {@link validateScript} — because those rules belong with the runtime that
+     * enforces them everywhere else.
+     *
+     * Optional for the same reason as {@link resumeAgent}: a host without it
+     * rejects `workflow()` outright rather than silently running nothing.
+     */
+    loadWorkflow?(ref: WorkflowScriptRef): Promise<WorkflowScriptSource> | WorkflowScriptSource;
+}
+/**
+ * What a run can be told to do while it is going, from the workflows dialog.
+ *
+ * Every method is best-effort and idempotent: the dialog renders off a progress
+ * log that lags the runtime slightly, so it will sometimes ask for something
+ * that has just stopped being possible. `false` means "there was nothing to do
+ * that to" — a caller can say so, but it is never an error.
+ */
+export interface WorkflowControl {
+    /**
+     * Stop *starting* agents. Ones already running are left to finish, because
+     * killing model work mid-turn throws away everything it has spent and there
+     * is no way to hand it back its context.
+     */
+    pause(): void;
+    resume(): void;
+    isPaused(): boolean;
+    /**
+     * Give up on the agent at `index`: its `agent()` call returns `null`, exactly
+     * as a terminal failure does, and the row renders skipped.
+     *
+     * Immediate for a running agent and for one held at a pause. An agent parked
+     * behind the concurrency limit takes its skip when it reaches the front —
+     * the alternative is a cancellable semaphore for a case that resolves itself
+     * as soon as any sibling finishes.
+     */
+    skip(index: number): boolean;
+    /**
+     * Start the agent at `index` over: the child is stopped and the same call is
+     * re-run, so the script's `agent()` promise is still the one waiting and it
+     * gets the new answer.
+     *
+     * Only while it is running — that is the whole window. Once the call has
+     * settled its value is already the script's, and re-running would produce a
+     * result with nowhere to go.
+     */
+    retry(index: number): boolean;
+}
+export interface RunWorkflowOptions {
+    /** Full script source, starting with `export const meta = { … }`. */
+    script: string;
+    args?: unknown;
+    host: WorkflowHost;
+    signal?: AbortSignal;
+    /** Fired per batch, not per entry — see the worker's progress batching. */
+    onProgress?(entries: readonly WorkflowEntry[]): void;
+    concurrency?: number;
+    agentCap?: number;
+    itemCap?: number;
+    /**
+     * Hands the caller the run's control surface, once per run.
+     *
+     * A callback rather than a return value because `runWorkflow` resolves when
+     * the run is *over*, which is the one moment there is nothing left to
+     * control. Fired before the first agent starts.
+     */
+    onControl?(control: WorkflowControl): void;
+    /**
+     * How many nested `workflow()` invocations one run may make in total.
+     *
+     * Each costs a compile and a scope rather than a thread, so the ceiling is
+     * generous — but unbounded is worse than capped, on the same reasoning as
+     * {@link agentCap}.
+     */
+    nestedCap?: number;
+    /**
+     * Replay and record, for `resumeFromRunId`.
+     *
+     * The runtime does no file IO — `entries` come in already read and `append`
+     * goes back out — so its tests stay free of a filesystem, the same reason
+     * spawning is behind {@link WorkflowHost}.
+     */
+    journal?: {
+        /** A previous run's settled calls, in position order. Empty replays nothing. */
+        entries?: readonly WorkflowJournalEntry[];
+        /** Called as each call of *this* run settles, so it can be resumed in turn. */
+        append?(entry: WorkflowJournalEntry): void;
+    };
+}
+export interface WorkflowRunResult {
+    status: "completed" | "failed" | "killed";
+    meta: WorkflowMeta;
+    /** The script's return value, JSON-checked at the boundary. */
+    value?: unknown;
+    error?: string;
+    /** The append-only log, in emission order. */
+    progress: WorkflowEntry[];
+    /** Agents scheduled, including those that failed. */
+    agentCount: number;
+    /** How many of those came back from the journal instead of being spawned. */
+    replayedCount: number;
+}
+/**
+ * Reject anything that cannot survive the round trip to the worker and into a
+ * resume journal. Structured clone would happily carry a `Map` or a cycle that
+ * the journal then cannot represent, so the check is stricter than the transport.
+ */
+export declare function assertBoundarySafe(value: unknown, path: string): void;
+/**
+ * Run one workflow script to completion.
+ *
+ * Rejects before starting for a script that cannot run at all (bad `meta`, over
+ * the size limit, control characters, non-JSON `args`). Everything after the
+ * worker is live resolves instead, carrying the failure in `status` — by then
+ * there is a progress log worth handing back.
+ */
+/**
+ * Everything a script must satisfy before it is compiled.
+ *
+ * Extracted so a nested `workflow()` is held to exactly the same standard as a
+ * top-level run: same size limit, same character rules, same `meta` contract.
+ * The host resolves a reference to source; deciding whether that source is a
+ * workflow stays here, where the rules live.
+ */
+export declare function validateScript(script: string): {
+    meta: WorkflowMeta;
+    body: string;
+};
+export declare function runWorkflow(options: RunWorkflowOptions): Promise<WorkflowRunResult>;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/workflow/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/workflow/runtime.ts"],"names":[],"mappings":"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"}