stageflow 0.42.0 → 0.46.0

package/dist/server/internalAgentRoutes.js

@@ -0,0 +1,12 @@
+import { describeInternalAgents, internalAgentsVisible } from "../operatorAgent/internalAgents.js";
+export const INTERNAL_AGENTS_PATH = "/api/internal-agents";
+export function handleInternalAgentRoutes(method, pathname, host, res, json, env = process.env) {
+    if (pathname !== INTERNAL_AGENTS_PATH || method !== "GET")
+        return false;
+    if (!internalAgentsVisible(env)) {
+        json(res, 200, { visible: false, agents: [] });
+        return true;
+    }
+    json(res, 200, { visible: true, agents: describeInternalAgents(host) });
+    return true;
+}

package/dist/server/mcpHost.js

@@ -30,6 +30,8 @@ export async function startMcpServer(options) {
             ...(boot.agentHost ? { agentHost: boot.agentHost } : {}),
             ...(boot.evalRunManager ? { evalRunManager: boot.evalRunManager } : {}),
             ...(boot.evalServices ? { evalServices: boot.evalServices } : {}),
+            ...(boot.channels ? { channels: boot.channels } : {}),
+            ...(boot.memories ? { memories: boot.memories } : {}),
         });
     const envelope = await createHttpHost({
         boot,

package/dist/toolkit/meta.d.ts

@@ -4,7 +4,7 @@
  * can import it without pulling in the runtime.
  */
 export type ToolRisk = "read" | "write" | "destructive" | "external";
-export type ToolGroupId = "discover" | "runs.read" | "runs.control" | "runs.cleanup" | "gates.read" | "gates.decide" | "triggers" | "agents.read" | "agents.manage" | "agents.cleanup" | "agents.converse" | "evals.read" | "evals.run" | "pipelines.author";
+export type ToolGroupId = "discover" | "runs.read" | "runs.control" | "runs.cleanup" | "gates.read" | "gates.decide" | "triggers" | "agents.read" | "agents.manage" | "agents.cleanup" | "agents.converse" | "evals.read" | "evals.run" | "evals.write" | "evals.cleanup" | "pipelines.author" | "connections" | "connections.cleanup" | "memories" | "memories.cleanup";
 export type ToolGroup = {
     id: ToolGroupId;
     title: string;

package/dist/toolkit/meta.js

@@ -16,8 +16,14 @@ export const TOOL_GROUPS = [
     { id: "agents.cleanup", title: "Archive agents", summary: "Archive an agent. Destructive." },
     { id: "agents.converse", title: "Talk to agents", summary: "Chat with an agent and stop its running turn." },
     { id: "pipelines.author", title: "Author pipelines and tasks", summary: "Read, create and edit pipelines, stages and tasks directly on disk." },
+    { id: "connections", title: "Connections", summary: "List, create, test and update host connections. Secret values are stored and never returned." },
+    { id: "connections.cleanup", title: "Remove connections", summary: "Remove a connection and its stored secrets. Destructive." },
+    { id: "memories", title: "Memories", summary: "List, create and edit host memories and their cards." },
+    { id: "memories.cleanup", title: "Delete memory cards", summary: "Delete one card from a host memory. Destructive." },
     { id: "evals.read", title: "Read evals", summary: "List evals, runs and results; validate and compare. Free." },
-    { id: "evals.run", title: "Run evals", summary: "Start and cancel eval runs. Calls models and costs money." },
+    { id: "evals.run", title: "Run evals", summary: "Start and cancel eval runs, and try one case. Calls models and costs money." },
+    { id: "evals.write", title: "Author evals", summary: "Create and edit evals and datasets, install a sample, and review or sort suggestions." },
+    { id: "evals.cleanup", title: "Delete eval runs", summary: "Delete an eval run and its stored results. Destructive." },
 ];
 const t = (group, risk, operatorOnly) => ({ group, risk, ...(operatorOnly ? { operatorOnly } : {}) });
 export const TOOL_META = {
@@ -70,6 +76,8 @@ export const TOOL_META = {
     get_agent: t("agents.read", "read"),
     validate_agent: t("agents.read", "read"),
     list_agent_revisions: t("agents.read", "read"),
+    get_agent_revision: t("agents.read", "read"),
+    diff_agent_revisions: t("agents.read", "read"),
     get_agent_session: t("agents.read", "read"),
     list_agent_sessions: t("agents.read", "read"),
     create_agent: t("agents.manage", "write"),
@@ -89,6 +97,24 @@ export const TOOL_META = {
     edit_stage: t("pipelines.author", "write"),
     create_task: t("pipelines.author", "write"),
     edit_task: t("pipelines.author", "write"),
+    create_task_file: t("pipelines.author", "write"),
+    update_task_file: t("pipelines.author", "write"),
+    import_task_file: t("pipelines.author", "external"),
+    create_stage_file: t("pipelines.author", "write"),
+    write_catalog_file: t("pipelines.author", "write"),
+    validate_catalog_draft: t("pipelines.author", "read"),
+    list_connections: t("connections", "read"),
+    create_connection: t("connections", "write"),
+    update_connection: t("connections", "write"),
+    test_connection: t("connections", "external"),
+    validate_connection_target: t("connections", "read"),
+    remove_connection: t("connections.cleanup", "destructive"),
+    list_memories: t("memories", "read"),
+    get_memory: t("memories", "read"),
+    create_memory: t("memories", "write"),
+    write_memory: t("memories", "write"),
+    write_memory_card: t("memories", "write"),
+    delete_memory_card: t("memories.cleanup", "destructive"),
     list_evals: t("evals.read", "read"),
     get_eval: t("evals.read", "read"),
     validate_eval: t("evals.read", "read"),
@@ -99,9 +125,23 @@ export const TOOL_META = {
     compare_eval_runs: t("evals.read", "read"),
     get_eval_failure_suggestions: t("evals.read", "read"),
     get_eval_failure_sort_status: t("evals.read", "read"),
+    get_eval_run_export: t("evals.read", "read"),
     run_eval: t("evals.run", "external"),
     sort_eval_failures: t("evals.run", "external"),
+    list_grader_calibrations: t("evals.read", "read"),
+    calibrate_eval_grader: t("evals.run", "external"),
     cancel_eval_run: t("evals.run", "write"),
+    try_eval_case: t("evals.run", "external"),
+    create_eval: t("evals.write", "write"),
+    update_eval: t("evals.write", "write"),
+    create_dataset: t("evals.write", "write"),
+    update_dataset_cases: t("evals.write", "write"),
+    convert_dataset: t("evals.write", "write"),
+    install_eval_sample: t("evals.write", "write"),
+    put_eval_review: t("evals.write", "write"),
+    accept_eval_failure_suggestions: t("evals.write", "write"),
+    dismiss_eval_failure_suggestions: t("evals.write", "write"),
+    delete_eval_run: t("evals.cleanup", "destructive"),
 };
 /** The grant id the policy gate and `approvals.ask_first` use for a Stageflow tool. */
 export const STAGEFLOW_GRANT_PREFIX = "stageflow.";

package/dist/toolkit/profiles.d.ts

@@ -3,7 +3,12 @@
  * Their tools are checked through the same grant-id check as any agent's tools,
  * so there is one permission layer. The lists are literals so this module has no
  * dependency on the profiles; tests keep them equal to the profiles' tool names.
+ * Guide is the exception: it may call every Stageflow tool a person could grant,
+ * except the ones only a person may decide.
  */
+export declare const GUIDE_OWN_TOOL_NAMES: readonly ["confirm_action", "show_ui", "list_guide_topics", "read_guide_topic"];
+/** Tool names Guide may call. Operator-only decisions stay out. */
+export declare function stageflowGuideToolNames(): readonly string[];
 export declare const PROFILE_GRANTS: Readonly<Record<string, {
     prefix: string;
     tools: readonly string[];

package/dist/toolkit/profiles.js

@@ -1,9 +1,17 @@
+import { isOperatorOnlyTool, TOOL_META } from "./meta.js";
 /**
  * The Workshop and Agent-author profiles are agents with a fixed grant list.
  * Their tools are checked through the same grant-id check as any agent's tools,
  * so there is one permission layer. The lists are literals so this module has no
  * dependency on the profiles; tests keep them equal to the profiles' tool names.
+ * Guide is the exception: it may call every Stageflow tool a person could grant,
+ * except the ones only a person may decide.
  */
+export const GUIDE_OWN_TOOL_NAMES = ["confirm_action", "show_ui", "list_guide_topics", "read_guide_topic"];
+/** Tool names Guide may call. Operator-only decisions stay out. */
+export function stageflowGuideToolNames() {
+    return [...Object.keys(TOOL_META).filter((name) => !isOperatorOnlyTool(name)), ...GUIDE_OWN_TOOL_NAMES];
+}
 export const PROFILE_GRANTS = {
     "workshop-author": {
         prefix: "workshop.",
@@ -13,6 +21,10 @@ export const PROFILE_GRANTS = {
         prefix: "agent_author.",
         tools: ["read_agent_draft", "read_project_file", "list_project_files", "list_mcp_servers", "list_author_catalog", "update_agent_draft"],
     },
+    "stageflow-guide": {
+        prefix: "guide.",
+        tools: stageflowGuideToolNames(),
+    },
 };
 export function profileGrantIds(profileId) {
     const grants = PROFILE_GRANTS[profileId];

package/dist/tools/askOperator.js

@@ -7,6 +7,7 @@
  * Do not abort the session from inside `execute`: the tool Promise is the
  * live blocking surface until the operator answers (or stage teardown).
  */
+import { ASK_OPERATOR_TOOL_NAME } from "./stageToolNames.js";
 import { randomUUID } from "node:crypto";
 import { Type } from "typebox";
 import { prepareAskOperatorArguments } from "./prepareToolArguments.js";
@@ -399,7 +400,7 @@ export function createAskOperatorTool(options) {
         ? [...allowed].join(", ")
         : ASK_OPERATOR_KINDS.join(", ");
     return {
-        name: "ask_operator",
+        name: ASK_OPERATOR_TOOL_NAME,
         label: "Ask operator",
         description: `Ask the operator a question and wait for their answer. Supports ${kindList} prompts. Does not complete the stage — call emit_stage_envelope when finished.`,
         parameters: askOperatorParamsSchemaFor(allowedKinds),

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({