stageflow 0.9.0 → 0.13.0

package/dist/agent/claudeTools.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Claude Agent SDK tool wrappers for the stage tool set.
+ *
+ * The actual envelope/artifact business logic lives in
+ * `tools/emitStageEnvelope.ts` / `tools/writeStageArtifact.ts` and is fully
+ * SDK-agnostic (typed `params: unknown`, no Pi imports) — this file reuses
+ * those `execute` functions as-is and only translates the *declaration*
+ * layer (typebox → Zod) and the *result* layer (drops Pi-only `terminate`/
+ * `details` fields, keeping just the MCP `CallToolResult` shape).
+ *
+ * `ask_operator` is different: `tools/askOperator.ts`'s own `execute` blocks
+ * on an injected wait bridge (Pi's in-process mechanism), which is exactly
+ * what Phase 3's "never let it go dangling" design avoids. This file reuses
+ * only the pure parsing/validation helpers from that module
+ * (`parseAskOperatorParams`, `normalizePromptIds`) and writes its own
+ * non-blocking handler: record the prompt on `capture`, return an immediate
+ * placeholder result, and rely on the adapter's `interrupt()` backstop
+ * (called right after this result lands) to end the turn — see
+ * claudeAdapter.ts.
+ *
+ * Registered under one in-process MCP server named "stageflow", so the model
+ * sees these as `mcp__stageflow__emit_stage_envelope`,
+ * `mcp__stageflow__write_stage_artifact`, and `mcp__stageflow__ask_operator`
+ * — those exact strings are what `composeStageUserPrompt`'s hints and the
+ * adapter's resume prompts must reference.
+ */
+import { type McpServerConfig } from "@anthropic-ai/claude-agent-sdk";
+import { z } from "zod";
+import { type EmitCapture } from "../tools/emitStageEnvelope.js";
+import { type WriteStageArtifactOptions } from "../tools/writeStageArtifact.js";
+import { type AskOperatorKind, type AskOperatorPrompt } from "../tools/askOperator.js";
+import type { CloneEmitContext, ForkEmitContext } from "../types/forkChoice.js";
+import type { PreEmitCheckOptions } from "../envelope/preEmitChecks.js";
+export declare const STAGEFLOW_MCP_SERVER_NAME = "stageflow";
+export declare const EMIT_STAGE_ENVELOPE_TOOL_NAME = "mcp__stageflow__emit_stage_envelope";
+export declare const WRITE_STAGE_ARTIFACT_TOOL_NAME = "mcp__stageflow__write_stage_artifact";
+export declare const ASK_OPERATOR_TOOL_NAME = "mcp__stageflow__ask_operator";
+export type AskOperatorCapture = {
+    prompt?: AskOperatorPrompt;
+};
+/**
+ * Exported so a parity test can assert this stays field-for-field aligned
+ * with `tools/emitStageEnvelope.ts`'s typebox schema — the two are hand
+ * written against the same envelope shape with no shared source, so
+ * nothing else catches one drifting from the other.
+ *
+ * Field presence mirrors the typebox schema's own conditionality:
+ * `clone_forks` only exists when a stage can clone-fork at all, and
+ * `fork_choice` is required (not just present) when the stage has a fork
+ * to route. Building this statically would silently offer the model a
+ * `clone_forks` field on stages that have nowhere to route one.
+ */
+export declare function buildEmitStageEnvelopeShape(options: {
+    forkEmitContext?: ForkEmitContext;
+    cloneEmitContext?: CloneEmitContext;
+}): {
+    status: z.ZodEnum<{
+        failure: "failure";
+        success: "success";
+    }>;
+    summary: z.ZodString;
+    artifacts: z.ZodArray<z.ZodString>;
+    payload: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    fork_choice: z.ZodArray<z.ZodString> | z.ZodOptional<z.ZodArray<z.ZodString>>;
+    clone_forks?: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>> | undefined;
+    checklist_attestations: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        check_id: z.ZodString;
+        items: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>>;
+    stage_id: z.ZodOptional<z.ZodString>;
+    notes: z.ZodOptional<z.ZodString>;
+};
+/** Exported for the same parity-test reason as `emitStageEnvelopeShape` above. */
+export declare const writeStageArtifactShape: {
+    path: z.ZodString;
+    content: z.ZodString;
+};
+export declare function buildStageflowMcpServer(options: {
+    capture: EmitCapture;
+    payloadSchema?: unknown;
+    forkEmitContext?: ForkEmitContext;
+    cloneEmitContext?: CloneEmitContext;
+    preEmitCheckOptions?: PreEmitCheckOptions;
+    writeStageArtifact: WriteStageArtifactOptions;
+    askOperator?: {
+        capture: AskOperatorCapture;
+        allowedKinds?: readonly AskOperatorKind[];
+    };
+}): McpServerConfig;

package/dist/agent/claudeTools.js

@@ -0,0 +1,135 @@
+/**
+ * Claude Agent SDK tool wrappers for the stage tool set.
+ *
+ * The actual envelope/artifact business logic lives in
+ * `tools/emitStageEnvelope.ts` / `tools/writeStageArtifact.ts` and is fully
+ * SDK-agnostic (typed `params: unknown`, no Pi imports) — this file reuses
+ * those `execute` functions as-is and only translates the *declaration*
+ * layer (typebox → Zod) and the *result* layer (drops Pi-only `terminate`/
+ * `details` fields, keeping just the MCP `CallToolResult` shape).
+ *
+ * `ask_operator` is different: `tools/askOperator.ts`'s own `execute` blocks
+ * on an injected wait bridge (Pi's in-process mechanism), which is exactly
+ * what Phase 3's "never let it go dangling" design avoids. This file reuses
+ * only the pure parsing/validation helpers from that module
+ * (`parseAskOperatorParams`, `normalizePromptIds`) and writes its own
+ * non-blocking handler: record the prompt on `capture`, return an immediate
+ * placeholder result, and rely on the adapter's `interrupt()` backstop
+ * (called right after this result lands) to end the turn — see
+ * claudeAdapter.ts.
+ *
+ * Registered under one in-process MCP server named "stageflow", so the model
+ * sees these as `mcp__stageflow__emit_stage_envelope`,
+ * `mcp__stageflow__write_stage_artifact`, and `mcp__stageflow__ask_operator`
+ * — those exact strings are what `composeStageUserPrompt`'s hints and the
+ * adapter's resume prompts must reference.
+ */
+import { createSdkMcpServer, tool, } from "@anthropic-ai/claude-agent-sdk";
+import { z } from "zod";
+import { createEmitStageEnvelopeTool, } from "../tools/emitStageEnvelope.js";
+import { createWriteStageArtifactTool, } from "../tools/writeStageArtifact.js";
+import { ASK_OPERATOR_KINDS, AskOperatorError, normalizePromptIds, parseAskOperatorParams, } from "../tools/askOperator.js";
+export const STAGEFLOW_MCP_SERVER_NAME = "stageflow";
+export const EMIT_STAGE_ENVELOPE_TOOL_NAME = `mcp__${STAGEFLOW_MCP_SERVER_NAME}__emit_stage_envelope`;
+export const WRITE_STAGE_ARTIFACT_TOOL_NAME = `mcp__${STAGEFLOW_MCP_SERVER_NAME}__write_stage_artifact`;
+export const ASK_OPERATOR_TOOL_NAME = `mcp__${STAGEFLOW_MCP_SERVER_NAME}__ask_operator`;
+/**
+ * Exported so a parity test can assert this stays field-for-field aligned
+ * with `tools/emitStageEnvelope.ts`'s typebox schema — the two are hand
+ * written against the same envelope shape with no shared source, so
+ * nothing else catches one drifting from the other.
+ *
+ * Field presence mirrors the typebox schema's own conditionality:
+ * `clone_forks` only exists when a stage can clone-fork at all, and
+ * `fork_choice` is required (not just present) when the stage has a fork
+ * to route. Building this statically would silently offer the model a
+ * `clone_forks` field on stages that have nowhere to route one.
+ */
+export function buildEmitStageEnvelopeShape(options) {
+    return {
+        status: z.enum(["success", "failure"]),
+        summary: z.string().min(1),
+        artifacts: z.array(z.string()),
+        payload: z.record(z.string(), z.unknown()).optional(),
+        fork_choice: options.forkEmitContext !== undefined
+            ? z.array(z.string())
+            : z.array(z.string()).optional(),
+        ...(options.cloneEmitContext !== undefined
+            ? { clone_forks: z.array(z.record(z.string(), z.unknown())) }
+            : {}),
+        checklist_attestations: z
+            .array(z.object({
+            check_id: z.string().min(1),
+            items: z.array(z.string()),
+        }))
+            .optional(),
+        stage_id: z.string().optional(),
+        notes: z.string().optional(),
+    };
+}
+/** Exported for the same parity-test reason as `emitStageEnvelopeShape` above. */
+export const writeStageArtifactShape = {
+    path: z.string().min(1),
+    content: z.string(),
+};
+const askOperatorShape = {
+    kind: z.string(),
+    message: z.string().optional(),
+    id: z.string().optional(),
+    questions: z.array(z.record(z.string(), z.unknown())).optional(),
+    artifacts: z.array(z.string()).optional(),
+};
+/** Adapts a `{content, details?, isError?, terminate?}` tool result to plain MCP CallToolResult. */
+function toCallToolResult(result) {
+    return {
+        content: result.content,
+        ...(result.isError ? { isError: true } : {}),
+    };
+}
+function buildAskOperatorTool(capture, allowedKinds) {
+    const allowed = allowedKinds && allowedKinds.length > 0
+        ? new Set(allowedKinds)
+        : null;
+    const kindList = allowed ? [...allowed].join(", ") : ASK_OPERATOR_KINDS.join(", ");
+    return tool("ask_operator", `Ask the operator a question and stop. Supports ${kindList} prompts. Calling this tool immediately ends your turn — after it returns, do not call any more tools and do not keep talking; you will be resumed in a new turn once the operator has answered. Does not complete the stage — call emit_stage_envelope when finished.`, askOperatorShape, async (args) => {
+        try {
+            const parsed = parseAskOperatorParams(args);
+            if (allowed && !allowed.has(parsed.kind)) {
+                throw new AskOperatorError(`unsupported prompt kind "${parsed.kind}" (allowed: ${kindList})`);
+            }
+            capture.prompt = normalizePromptIds(parsed);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                content: [{ type: "text", text: `Invalid ask_operator params: ${message}` }],
+                isError: true,
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "Question recorded for the operator. Stop here — do not call any more tools or continue this turn; you will be resumed with the operator's answer in a new turn.",
+                },
+            ],
+        };
+    });
+}
+export function buildStageflowMcpServer(options) {
+    const emitDef = createEmitStageEnvelopeTool(options.capture, options.payloadSchema, options.forkEmitContext, options.cloneEmitContext, options.preEmitCheckOptions);
+    const artifactDef = createWriteStageArtifactTool(options.writeStageArtifact);
+    const emitTool = tool(emitDef.name, emitDef.description, buildEmitStageEnvelopeShape({
+        forkEmitContext: options.forkEmitContext,
+        cloneEmitContext: options.cloneEmitContext,
+    }), async (args) => toCallToolResult(await emitDef.execute("claude-tool-call", args)));
+    const artifactTool = tool(artifactDef.name, artifactDef.description, writeStageArtifactShape, async (args) => toCallToolResult(await artifactDef.execute("claude-tool-call", args)));
+    const tools = [emitTool, artifactTool];
+    if (options.askOperator) {
+        tools.push(buildAskOperatorTool(options.askOperator.capture, options.askOperator.allowedKinds));
+    }
+    return createSdkMcpServer({
+        name: STAGEFLOW_MCP_SERVER_NAME,
+        tools,
+    });
+}

package/dist/agent/fakeAgent.js

@@ -1,12 +1,13 @@
 import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { assertRequiredEnvelope, isAdvancingEnvelope, } from "../envelope/check.js";
+import { assertFeedbackLoopAction } from "../envelope/feedbackLoop.js";
 import { assertEnvelopePayload } from "../envelope/payloadSchema.js";
 import { assertCloneForks } from "../envelope/cloneForks.js";
 import { assertForkEnvelope } from "../envelope/forkChoice.js";
 import { assertAnswerMatchesPrompt, parseAskOperatorAnswer, } from "../tools/askOperator.js";
 import { tryParsePendingPrompt } from "../runtime/stageHitl.js";
-import { runtimeStageId, runStageViaOpen } from "./port.js";
+import { runtimeStageId, runStageViaOpen, createCompletedOnlyStageHandle, } from "./port.js";
 function opaqueEqual(a, b) {
     if (Object.is(a, b))
         return true;
@@ -68,6 +69,17 @@ export class FakeAgent {
         let answerPromise;
         let started = false;
         let resumeCorrupt = false;
+        const sessionMode = input.sessionMode ?? "fresh";
+        const skipHitlPark = sessionMode === "feedback_resume" || sessionMode === "new_session";
+        if (sessionMode === "feedback_resume" && input.feedbackLoopContext === undefined) {
+            return createCompletedOnlyStageHandle({
+                stageId: runtimeStageId(input),
+                run: async () => ({
+                    ok: false,
+                    reason: "feedback_resume requires feedbackLoopContext",
+                }),
+            });
+        }
         const armWait = () => {
             waiting = true;
             answerPromise = new Promise((resolve) => {
@@ -83,7 +95,7 @@ export class FakeAgent {
             answerPromise = undefined;
             return answer;
         };
-        if (behavior.type === "wait_then_emit") {
+        if (behavior.type === "wait_then_emit" && !skipHitlPark) {
             const loaded = loadFakeHitlResume(input.roots, runtimeStageId(input));
             if (loaded === "corrupt") {
                 resumeCorrupt = true;
@@ -99,6 +111,12 @@ export class FakeAgent {
                 armWait();
             }
         }
+        if (sessionMode === "feedback_resume" && behavior.type === "wait_then_emit") {
+            behavior = {
+                type: "emit",
+                envelope: behavior.envelope,
+            };
+        }
         const emitStartActivity = () => {
             if (started)
                 return;
@@ -137,10 +155,12 @@ export class FakeAgent {
                 : undefined;
             try {
                 const envelope = assertRequiredEnvelope(envelopeValue);
-                if (input.forkEmitContext !== undefined) {
+                assertFeedbackLoopAction(envelope, input.feedbackLoopEmitContext);
+                const isFeedbackSendBack = envelope.feedback_loop?.action === "send_back";
+                if (!isFeedbackSendBack && input.forkEmitContext !== undefined) {
                     assertForkEnvelope(envelope, input.forkEmitContext);
                 }
-                if (input.cloneEmitContext !== undefined) {
+                if (!isFeedbackSendBack && input.cloneEmitContext !== undefined) {
                     assertCloneForks(envelope, input.cloneEmitContext);
                 }
                 assertEnvelopePayload(envelope, input.stage.payload_schema);

package/dist/agent/piAdapter.d.ts

@@ -1,15 +1,17 @@
-import { type AgentSession, DefaultResourceLoader, SessionManager, SettingsManager } from "@earendil-works/pi-coding-agent";
+import { type AgentSession, type EventBus, type InlineExtension, DefaultResourceLoader, SessionManager, SettingsManager } from "@earendil-works/pi-coding-agent";
 import type { StageRoots } from "../runtime/stageRoots.js";
 import { type AskOperatorPrompt, type AskOperatorWaitBridge } from "../tools/askOperator.js";
 import "./cursorProvider.js";
 import { type StageActivityObserver } from "./activityObserver.js";
 import type { AgentPort, OpaqueAnswer, StageHandle, StageHandleCloseOptions, StageRunInput, StageRunResult } from "./port.js";
+import type { StageGateKind } from "../types/stage.js";
 /**
  * Stage tool allowlist for sealed Pi sessions.
- * Always includes `ask_operator` (R7); `write_stage_artifact` when registered
- * (always, for bound and unbound — bound/unbound only gates cwd / env bind).
+ * Includes `ask_operator` unless `gateKinds` is an empty list (R6).
+ * `write_stage_artifact` when registered (always, for bound and unbound —
+ * bound/unbound only gates cwd / env bind).
  */
-export declare function resolveStageToolNames(emitToolName: string, artifactToolName?: string, askOperatorToolName?: string): string[];
+export declare function resolveStageToolNames(emitToolName: string, artifactToolName?: string, askOperatorToolName?: string, gateKinds?: StageGateKind[]): string[];
 /**
  * In-process wait channel for `ask_operator` → StageHandle yield/deliver.
  * HITL `openStage` connects this via `setWaitHandler` + handle `deliverAnswer`.
@@ -62,6 +64,7 @@ export type RouteSessionEventToProgressOptions = {
  */
 export declare function routeSessionEventToProgress(event: Record<string, unknown>, options: RouteSessionEventToProgressOptions): void;
 export declare function composeStageUserPrompt(input: StageRunInput, emitToolName: string, emitHintOverride?: string, artifactToolName?: string): string;
+export declare function composeFeedbackResumePrompt(input: StageRunInput): string;
 /**
  * DefaultResourceLoader with host/global discovery turned off.
  *
@@ -69,9 +72,9 @@ export declare function composeStageUserPrompt(input: StageRunInput, emitToolNam
  * up the consumer project's AGENTS.md, `.agents/skills/`, `.pi/extensions`,
  * and APPEND_SYSTEM.md. Stages must not inherit that context.
  *
- * `additionalExtensionPaths` is the only way extensions enter a sealed stage
- * (used by StageProviderSupport implementations). With `noExtensions: true`,
- * discovered global/project packages stay out; only allowlisted paths load.
+ * `additionalExtensionPaths` is the Cursor/provider seam. `extensionFactories`
+ * is the isolated MCP seam. With `noExtensions: true`, discovered
+ * global/project packages stay out; only those allowlists load.
  * `additionalSkillPaths` is the matching allowlist for one named skill.
  */
 export declare function createSealedResourceLoader(options: {
@@ -81,6 +84,8 @@ export declare function createSealedResourceLoader(options: {
     systemPrompt: string;
     additionalExtensionPaths?: string[];
     additionalSkillPaths?: string[];
+    extensionFactories?: InlineExtension[];
+    eventBus?: EventBus;
 }): DefaultResourceLoader;
 /** Stable Pi session JSONL path under the run workspace stage dir. */
 export declare function stageSessionFilePath(roots: Pick<StageRoots, "runWorkspaceDir" | "attempt">, stageId: string): string;