stageflow 0.40.0 → 0.44.0

package/dist/tools/emitStageEnvelope.d.ts

@@ -1,14 +1,3 @@
-/**
- * Custom Pi tool the stage agent must call once when finished.
- *
- * Parameter schemas use `typebox` (Pi's `defineTool` TSchema), not
- * `@sinclair/typebox`. An accepted emit returns `terminate: true` so Pi
- * ends the turn instead of asking the model to continue.
- *
- * Do not abort the session from inside `execute`: providers that bridge tools
- * (e.g. MCP) may still be waiting for this result, and abort-while-running
- * deadlocks waitForIdle so later pipeline stages never start.
- */
 import { Type } from "typebox";
 import type { TSchema } from "typebox/type";
 import { type PreEmitCheckOptions } from "../envelope/preEmitChecks.js";
@@ -23,20 +12,32 @@ export declare function createEmitStageEnvelopeTool(capture: EmitCapture, payloa
     name: string;
     label: string;
     description: string;
-    parameters: Type.TObject<{
-        status: Type.TUnion<[Type.TLiteral<"success">, Type.TLiteral<"failure">]>;
+    parameters: Type.TUnion<[Type.TObject<{
         summary: Type.TString;
         artifacts: Type.TArray<Type.TString>;
-        payload: Type.TOptional<TSchema>;
+        checklist_attestations: Type.TOptional<Type.TArray<Type.TObject<{
+            check_id: Type.TString;
+            items: Type.TArray<Type.TString>;
+        }>>>;
+        stage_id: Type.TOptional<Type.TString>;
+        notes: Type.TOptional<Type.TString>;
+        status: Type.TLiteral<"success">;
+        payload: TSchema;
         fork_choice: Type.TArray<Type.TString>;
-        feedback_loop?: Type.TOptional<TSchema> | undefined;
+        feedback_loop?: TSchema | undefined;
+    }>, Type.TObject<{
+        summary: Type.TString;
+        artifacts: Type.TArray<Type.TString>;
         checklist_attestations: Type.TOptional<Type.TArray<Type.TObject<{
             check_id: Type.TString;
             items: Type.TArray<Type.TString>;
         }>>>;
         stage_id: Type.TOptional<Type.TString>;
         notes: Type.TOptional<Type.TString>;
-    }>;
+        status: Type.TLiteral<"failure">;
+        payload: Type.TOptional<TSchema>;
+        fork_choice: Type.TOptional<Type.TArray<Type.TString>>;
+    }>]>;
     prepareArguments: (args: unknown) => never;
     execute: (_toolCallId: string, params: unknown) => Promise<{
         content: {

package/dist/tools/emitStageEnvelope.js

@@ -9,11 +9,13 @@
  * (e.g. MCP) may still be waiting for this result, and abort-while-running
  * deadlocks waitForIdle so later pipeline stages never start.
  */
+import { EMIT_STAGE_ENVELOPE_TOOL_NAME } from "./stageToolNames.js";
 import { Type } from "typebox";
 import { assertRequiredEnvelope, isAdvancingEnvelope, } from "../envelope/check.js";
 import { assertFeedbackLoopAction } from "../envelope/feedbackLoop.js";
 import { normalizeForkChoice } from "../envelope/forkChoice.js";
 import { assertEnvelopePayload, compilePayloadSchema, } from "../envelope/payloadSchema.js";
+import { assertEmittedArtifactsOnDisk } from "../envelope/assertEmittedArtifacts.js";
 import { assertPreEmitChecks, } from "../envelope/preEmitChecks.js";
 import { prepareEmitStageEnvelopeArguments } from "./prepareToolArguments.js";
 function stringLiteralsSchema(values) {
@@ -22,16 +24,6 @@ function stringLiteralsSchema(values) {
     }
     return Type.Union(values.map((value) => Type.Literal(value)));
 }
-function stageEnvelopeSchema(payloadSchema) {
-    return Type.Object({
-        status: Type.Union([Type.Literal("success"), Type.Literal("failure")]),
-        summary: Type.String({ minLength: 1 }),
-        artifacts: Type.Array(Type.String()),
-        payload: Type.Optional(payloadSchema !== undefined
-            ? payloadSchema
-            : Type.Record(Type.String(), Type.Unknown())),
-    });
-}
 function feedbackLoopActionSchema(context) {
     return Type.Union([
         Type.Object({ action: Type.Literal("continue") }, { additionalProperties: false }),
@@ -41,6 +33,44 @@ function feedbackLoopActionSchema(context) {
         }, { additionalProperties: false }),
     ]);
 }
+const closed = { additionalProperties: false };
+function checklistAttestationsSchema() {
+    return Type.Optional(Type.Array(Type.Object({
+        check_id: Type.String({ minLength: 1 }),
+        items: Type.Array(Type.String()),
+    }, closed)));
+}
+function emitStageEnvelopeParameters(input) {
+    const freePayload = Type.Record(Type.String(), Type.Unknown());
+    const payloadValue = input.compiledPayload ?? freePayload;
+    const forkOptional = Type.Optional(Type.Array(Type.String()));
+    const forkOnSuccess = input.forkEmitContext !== undefined && input.feedbackLoopEmitContext === undefined
+        ? Type.Array(Type.String())
+        : forkOptional;
+    const shared = {
+        summary: Type.String({ minLength: 1 }),
+        artifacts: Type.Array(Type.String()),
+        checklist_attestations: checklistAttestationsSchema(),
+        stage_id: Type.Optional(Type.String()),
+        notes: Type.Optional(Type.String()),
+    };
+    const success = Type.Object({
+        status: Type.Literal("success"),
+        ...shared,
+        payload: input.compiledPayload !== undefined ? input.compiledPayload : Type.Optional(freePayload),
+        fork_choice: forkOnSuccess,
+        ...(input.feedbackLoopEmitContext !== undefined
+            ? { feedback_loop: feedbackLoopActionSchema(input.feedbackLoopEmitContext) }
+            : {}),
+    }, closed);
+    const failure = Type.Object({
+        status: Type.Literal("failure"),
+        ...shared,
+        payload: Type.Optional(payloadValue),
+        fork_choice: forkOptional,
+    }, closed);
+    return Type.Union([success, failure]);
+}
 function toolResult(text, details, options) {
     return {
         content: [{ type: "text", text }],
@@ -54,30 +84,13 @@ export function createEmitStageEnvelopeTool(capture, payloadSchema, forkEmitCont
         ? compilePayloadSchema(payloadSchema)
         : undefined;
     return {
-        name: "emit_stage_envelope",
+        name: EMIT_STAGE_ENVELOPE_TOOL_NAME,
         label: "Emit stage envelope",
         description: "Emit the shared stage handoff envelope. Call exactly once when the stage is complete. The pipeline cannot advance until this tool succeeds.",
-        parameters: Type.Object({
-            status: Type.Union([Type.Literal("success"), Type.Literal("failure")]),
-            summary: Type.String({ minLength: 1 }),
-            artifacts: Type.Array(Type.String()),
-            payload: Type.Optional(compiledPayload !== undefined
-                ? compiledPayload
-                : Type.Record(Type.String(), Type.Unknown())),
-            fork_choice: forkEmitContext !== undefined && feedbackLoopEmitContext === undefined
-                ? Type.Array(Type.String())
-                : Type.Optional(Type.Array(Type.String())),
-            ...(feedbackLoopEmitContext !== undefined
-                ? {
-                    feedback_loop: Type.Optional(feedbackLoopActionSchema(feedbackLoopEmitContext)),
-                }
-                : {}),
-            checklist_attestations: Type.Optional(Type.Array(Type.Object({
-                check_id: Type.String({ minLength: 1 }),
-                items: Type.Array(Type.String()),
-            }))),
-            stage_id: Type.Optional(Type.String()),
-            notes: Type.Optional(Type.String()),
+        parameters: emitStageEnvelopeParameters({
+            compiledPayload,
+            forkEmitContext,
+            feedbackLoopEmitContext,
         }),
         prepareArguments: prepareEmitStageEnvelopeArguments,
         execute: async (_toolCallId, params) => {
@@ -96,6 +109,7 @@ export function createEmitStageEnvelopeTool(capture, payloadSchema, forkEmitCont
                 assertEnvelopePayload(envelope, payloadSchema);
                 if (envelope.status !== "failure") {
                     await assertPreEmitChecks(envelope, preEmitCheckOptions);
+                    await assertEmittedArtifactsOnDisk(envelope.artifacts, preEmitCheckOptions?.artifactPresence);
                 }
                 capture.envelope = envelope;
                 const advancing = isAdvancingEnvelope(envelope);

package/dist/tools/stageToolNames.d.ts

@@ -0,0 +1,4 @@
+/** Names of the tools every stage session shares. The tools register under these names; consumers read them from here. */
+export declare const EMIT_STAGE_ENVELOPE_TOOL_NAME = "emit_stage_envelope";
+export declare const ASK_OPERATOR_TOOL_NAME = "ask_operator";
+export declare const WRITE_STAGE_ARTIFACT_TOOL_NAME = "write_stage_artifact";

package/dist/tools/stageToolNames.js

@@ -0,0 +1,4 @@
+/** Names of the tools every stage session shares. The tools register under these names; consumers read them from here. */
+export const EMIT_STAGE_ENVELOPE_TOOL_NAME = "emit_stage_envelope";
+export const ASK_OPERATOR_TOOL_NAME = "ask_operator";
+export const WRITE_STAGE_ARTIFACT_TOOL_NAME = "write_stage_artifact";

package/dist/tools/workingState.d.ts

@@ -0,0 +1,40 @@
+import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { WorkingStateStore, type WorkingStateEvent } from "../compaction/workingState.js";
+export type WorkingStateToolOptions = {
+    store: WorkingStateStore;
+    persist: (event: WorkingStateEvent) => void;
+    now?: () => string;
+};
+type ToolResult = {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    details: unknown;
+    isError?: boolean;
+};
+export declare function createWorkingStateTool(options: WorkingStateToolOptions): {
+    name: string;
+    label: string;
+    description: string;
+    parameters: Type.TUnion<[Type.TObject<{
+        operation: Type.TLiteral<"set">;
+        key: Type.TString;
+        kind: Type.TUnion<[Type.TLiteral<Type.TLiteralValue>, Type.TLiteral<Type.TLiteralValue>, ...Type.TLiteral<Type.TLiteralValue>[]]>;
+        value: Type.TString;
+    }>, Type.TObject<{
+        operation: Type.TLiteral<"delete">;
+        key: Type.TString;
+    }>, Type.TObject<{
+        operation: Type.TLiteral<"list">;
+    }>]>;
+    execute(_toolCallId: string, input: unknown): Promise<ToolResult>;
+};
+/**
+ * Inline Pi extension: registers the tool, persists each change as a custom
+ * session entry and rebuilds the store from the session file on first use,
+ * so state survives process restarts and resume.
+ */
+export declare function createWorkingStateExtension(): ExtensionFactory;
+export {};

package/dist/tools/workingState.js

@@ -0,0 +1,108 @@
+import { Type } from "typebox";
+import { WORKING_STATE_CUSTOM_TYPE, WORKING_STATE_KINDS, WORKING_STATE_MAX_KEY, WORKING_STATE_MAX_VALUE, WorkingStateStore, workingStateEventsFromEntries, } from "../compaction/workingState.js";
+import { WORKING_STATE_TOOL_NAME } from "../compaction/types.js";
+const closed = { additionalProperties: false };
+function workingStateKindSchema() {
+    return Type.Union(WORKING_STATE_KINDS.map((k) => Type.Literal(k)));
+}
+function workingStateParameters() {
+    return Type.Union([
+        Type.Object({
+            operation: Type.Literal("set"),
+            key: Type.String({ maxLength: WORKING_STATE_MAX_KEY }),
+            kind: workingStateKindSchema(),
+            value: Type.String({ maxLength: WORKING_STATE_MAX_VALUE }),
+        }, closed),
+        Type.Object({
+            operation: Type.Literal("delete"),
+            key: Type.String({ maxLength: WORKING_STATE_MAX_KEY }),
+        }, closed),
+        Type.Object({ operation: Type.Literal("list") }, closed),
+    ]);
+}
+function result(text, isError = false) {
+    return {
+        content: [{ type: "text", text }],
+        details: { isError },
+        ...(isError ? { isError: true } : {}),
+    };
+}
+export function createWorkingStateTool(options) {
+    const { store, persist } = options;
+    const now = options.now ?? (() => new Date().toISOString());
+    return {
+        name: WORKING_STATE_TOOL_NAME,
+        label: "Working state",
+        description: "Keep your own structured working state. Older messages and tool results are trimmed automatically, but this state is kept and shown to you again after every trim. Use `set` as soon as you know something you will need later: exact values and identifiers (fact), choices and reasons (decision), what is finished (progress), what remains (todo), what is stuck (blocker). Keep entries short (one or two lines). Reuse a key to update an entry instead of adding a duplicate; use `delete` when an entry no longer matters; `list` shows everything. Never store secrets.",
+        parameters: workingStateParameters(),
+        async execute(_toolCallId, input) {
+            const params = (input ?? {});
+            if (params.operation === "list") {
+                const rendered = store.render();
+                return result(rendered === "" ? "Working state is empty." : rendered);
+            }
+            if (params.operation === "delete") {
+                if (typeof params.key !== "string" || params.key.trim() === "") {
+                    return result("delete requires key", true);
+                }
+                if (!store.delete(params.key)) {
+                    return result(`No entry "${params.key}".`, true);
+                }
+                persist({ op: "delete", key: params.key.trim(), at: now() });
+                return result(`Deleted ${params.key.trim()}.`);
+            }
+            if (params.operation === "set") {
+                const at = now();
+                const outcome = store.set({
+                    key: params.key ?? "",
+                    kind: params.kind,
+                    value: params.value ?? "",
+                    updatedAt: at,
+                });
+                if (!outcome.ok)
+                    return result(outcome.error, true);
+                persist({
+                    op: "set",
+                    key: outcome.entry.key,
+                    kind: outcome.entry.kind,
+                    value: outcome.entry.value,
+                    at,
+                });
+                const dropped = outcome.dropped.length > 0
+                    ? ` State was full; dropped oldest progress: ${outcome.dropped.join(", ")}.`
+                    : "";
+                const redacted = outcome.redacted
+                    ? " Part of it looked like a secret and was redacted; reword the entry if that removed a fact you need."
+                    : "";
+                return result(`${outcome.replaced ? "Updated" : "Saved"} ${outcome.entry.key} (${store.size} entries).${dropped}${redacted}`);
+            }
+            return result("operation must be set, delete or list", true);
+        },
+    };
+}
+/**
+ * Inline Pi extension: registers the tool, persists each change as a custom
+ * session entry and rebuilds the store from the session file on first use,
+ * so state survives process restarts and resume.
+ */
+export function createWorkingStateExtension() {
+    return (pi) => {
+        const store = new WorkingStateStore();
+        let restored = false;
+        const tool = createWorkingStateTool({
+            store,
+            persist: (event) => pi.appendEntry(WORKING_STATE_CUSTOM_TYPE, event),
+        });
+        pi.registerTool({
+            ...tool,
+            constrainedSampling: { type: "json_schema", strict: "prefer" },
+            async execute(toolCallId, params, _signal, _onUpdate, ctx) {
+                if (!restored) {
+                    restored = true;
+                    store.load(workingStateEventsFromEntries(ctx.sessionManager.getEntries()));
+                }
+                return tool.execute(toolCallId, params);
+            },
+        });
+    };
+}

package/dist/tools/writeStageArtifact.d.ts

@@ -1,12 +1,3 @@
-/**
- * Custom Pi tool for writing factory stage artifact files under the run
- * workspace. Paths are relative to
- * `stages/<stageId>/attempts/<attempt>/artifacts/` and must resolve inside
- * that directory.
- *
- * Parameter schemas use `typebox` (Pi's `defineTool` TSchema), not
- * `@sinclair/typebox`. Unlike emit, this tool does not terminate the turn.
- */
 import { Type } from "typebox";
 export type WriteStageArtifactOptions = {
     runWorkspaceDir: string;

package/dist/tools/writeStageArtifact.js

@@ -7,6 +7,7 @@
  * Parameter schemas use `typebox` (Pi's `defineTool` TSchema), not
  * `@sinclair/typebox`. Unlike emit, this tool does not terminate the turn.
  */
+import { WRITE_STAGE_ARTIFACT_TOOL_NAME } from "./stageToolNames.js";
 import { Type } from "typebox";
 import { resolveArtifactTarget } from "../runstore/workspaceLayout.js";
 import { writeContainedArtifact } from "../runstore/writeContainedArtifact.js";
@@ -20,7 +21,7 @@ function toolResult(text, details, options) {
 export function createWriteStageArtifactTool(options) {
     const { runWorkspaceDir, stageId, attempt } = options;
     return {
-        name: "write_stage_artifact",
+        name: WRITE_STAGE_ARTIFACT_TOOL_NAME,
         label: "Write stage artifact",
         description: "Write a factory artifact file under this stage attempt's artifacts directory in the run workspace. Pass a path relative to stages/<stageId>/attempts/<attempt>/artifacts/ and the file content. Returns the run-relative path to include in emit_stage_envelope artifacts.",
         parameters: Type.Object({

package/dist/types/stageflowManifest.d.ts

@@ -3,10 +3,14 @@ export type StageflowManifestCatalog = {
     pipelines: string[];
     tasks: string[];
     triggers?: string[];
+    evals?: string[];
+    datasets?: string[];
     patterns?: {
         pipeline?: string;
         task?: string;
         trigger?: string;
+        eval?: string;
+        dataset?: string | string[];
     };
     exclude?: string[];
 };
@@ -26,5 +30,7 @@ export type LoadedManifest = {
         pipeline: string;
         task: string;
         trigger: string;
+        eval: string;
+        dataset: string[];
     };
 };