stageflow 0.42.0 → 0.44.0

package/dist/mcp/memoryHostTools.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/server";
+import type { McpToolDeps } from "./deps.js";
+export declare function registerMemoryHostTools(server: McpServer, deps: McpToolDeps): void;

package/dist/mcp/memoryHostTools.js

@@ -0,0 +1,72 @@
+import { z } from "zod";
+import { MemoryError } from "../memory/host.js";
+import { textResult } from "./toolResults.js";
+async function call(deps, work) {
+    const host = deps.memories;
+    if (!host)
+        return textResult({ error: "MEMORIES_UNAVAILABLE" }, true);
+    try {
+        return textResult(await work(host));
+    }
+    catch (error) {
+        if (error instanceof MemoryError)
+            return textResult({ error: error.code }, true);
+        throw error;
+    }
+}
+export function registerMemoryHostTools(server, deps) {
+    server.registerTool("list_memories", {
+        description: "List host memories (id, description, and card count).",
+        inputSchema: z.object({}),
+    }, () => call(deps, async (host) => ({ memories: await host.list() })));
+    server.registerTool("get_memory", {
+        description: "Read one host memory: its description, cover page, and card keys.",
+        inputSchema: z.object({
+            id: z.string(),
+        }),
+    }, ({ id }) => call(deps, async (host) => {
+        const meta = await host.readMeta(id);
+        const body = await host.read(id);
+        const keys = await host.listCards(id);
+        return { ...meta, body, keys };
+    }));
+    server.registerTool("create_memory", {
+        description: "Create a host memory with an id and description. The cover page starts empty.",
+        inputSchema: z.object({
+            id: z.string(),
+            description: z.string(),
+        }),
+    }, ({ id, description }) => call(deps, (host) => host.create({ id, description })));
+    server.registerTool("write_memory", {
+        description: "Replace the cover page of a host memory.",
+        inputSchema: z.object({
+            id: z.string(),
+            body: z.string(),
+        }),
+    }, ({ id, body }) => call(deps, async (host) => {
+        await host.replace(id, body);
+        const meta = await host.readMeta(id);
+        return { ...meta, body };
+    }));
+    server.registerTool("write_memory_card", {
+        description: "Replace an existing host memory card. A missing card is not created.",
+        inputSchema: z.object({
+            id: z.string(),
+            key: z.string(),
+            body: z.string(),
+        }),
+    }, ({ id, key, body }) => call(deps, async (host) => {
+        await host.updateCard(id, key, body);
+        return { body };
+    }));
+    server.registerTool("delete_memory_card", {
+        description: "Delete one card from a host memory.",
+        inputSchema: z.object({
+            id: z.string(),
+            key: z.string(),
+        }),
+    }, ({ id, key }) => call(deps, async (host) => {
+        await host.deleteCard(id, key);
+        return { removed: true };
+    }));
+}

package/dist/mcp/pipelineAuthorTools.js

@@ -88,7 +88,20 @@ export function registerPipelineAuthorTools(server, deps) {
     }, ({ path: relPath, allow_invalid, ...args }) => mutate(relPath, "overwrite", (draft) => buildCreateStageDraft(draft, args), { allowInvalid: allow_invalid }));
     server.registerTool("edit_stage", {
         description: "Edit an existing stage on disk by id: body fields and/or its pipeline entry (route, entry, uses).",
-        inputSchema: z.looseObject({ path: pipelinePath, id: z.string(), allow_invalid: allowInvalid }),
+        inputSchema: z.object({
+            path: pipelinePath,
+            id: z.string(),
+            patch: record.optional(),
+            body: record.optional(),
+            pipeline_entry: record.optional(),
+            entry: z.boolean().optional(),
+            route: z.array(record).optional(),
+            uses: z.string().optional(),
+            system_prompt: z.string().optional(),
+            model: z.string().optional(),
+            io: record.optional(),
+            allow_invalid: allowInvalid,
+        }),
     }, ({ path: relPath, allow_invalid, ...args }) => mutate(relPath, "overwrite", (draft) => buildEditStageDraft(draft, args), { allowInvalid: allow_invalid }));
     server.registerTool("create_task", {
         description: "Create or replace the task beside a pipeline on disk (id and goal, optional body).",

package/dist/mcp/server.js

@@ -50,6 +50,11 @@ function toolDepsFrom(deps) {
             ? { agentConversationBackend: deps.agentConversationBackend }
             : {}),
         ...(deps.evalRunManager !== undefined ? { evalRunManager: deps.evalRunManager } : {}),
+        ...(deps.evalEngineStatus !== undefined ? { evalEngineStatus: deps.evalEngineStatus } : {}),
+        ...(deps.triage !== undefined ? { triage: deps.triage } : {}),
+        ...(deps.channels !== undefined ? { channels: deps.channels } : {}),
+        ...(deps.memories !== undefined ? { memories: deps.memories } : {}),
+        ...(deps.issueFetch !== undefined ? { issueFetch: deps.issueFetch } : {}),
     };
 }
 function attachBusNotifications(server, bus) {

package/dist/mcp/tools.js

@@ -10,7 +10,10 @@ import { registerTriggerTools } from "./triggerTools.js";
 import { textResult } from "./toolResults.js";
 import { DEFAULT_TIMEOUT_MS, waitRun } from "./waitRun.js";
 import { registerAgentTools } from "./agentTools.js";
+import { registerCatalogWriteTools } from "./catalogWriteTools.js";
+import { registerConnectionTools } from "./connectionTools.js";
 import { registerGetStartedTool } from "./getStartedTool.js";
+import { registerMemoryHostTools } from "./memoryHostTools.js";
 export function registerMcpTools(server, deps) {
     const { store } = deps;
     registerGetStartedTool(server, deps);
@@ -22,6 +25,9 @@ export function registerMcpTools(server, deps) {
     registerTriggerTools(server, deps);
     registerEvalTools(server, deps);
     registerPipelineAuthorTools(server, deps);
+    registerCatalogWriteTools(server, deps);
+    registerConnectionTools(server, deps);
+    registerMemoryHostTools(server, deps);
     registerAgentTools(server, deps);
     server.registerTool("wait_run", {
         description: "Long-poll until a run is waiting for HITL input and/or terminal (succeeded/failed), or until timeout_ms. Default until=any wakes on waiting OR terminal. Abort cancels only this wait (not the run). Optional notifications/progress when the client supplies _meta.progressToken. Compose: wait_run → answer_gate → wait_run.",

package/dist/mcp/triggerTools.js

@@ -2,6 +2,7 @@ import { z } from "zod";
 import { CatalogPathError, catalogPathErrorBody, resolveWritableCatalogRoot, } from "../config/catalogRelativePath.js";
 import { createTrigger, parseCreateTriggerBody } from "../config/createTrigger.js";
 import { parsePatchTriggerBody, parsePutTriggerBody, updateTriggerDefinition, updateTriggerEnabled } from "../config/updateTrigger.js";
+import { readTriggerAdapterStatus } from "../config/triggerAdapterStatus.js";
 import { loadCatalogTriggers } from "../config/triggerCatalog.js";
 import { writeAudit } from "../logging/audit.js";
 import { logger as rootLogger } from "../logging/logger.js";
@@ -41,23 +42,58 @@ const triggerEventSchema = z.object({
     match: z.record(z.string(), z.unknown()).optional(),
     config: z.record(z.string(), z.unknown()).optional(),
 });
-const createTriggerSchema = z.object({
-    project_root: z
-        .string()
-        .optional()
-        .describe("Catalog project root to write into; required when multiple catalog roots are configured and no sole non-seeded root exists"),
+function findListedTrigger(items, id, projectRoot) {
+    if (projectRoot) {
+        const found = items.find((item) => item.id === id && item.project_root === projectRoot);
+        if (!found)
+            return { error: `Trigger not found: ${id}`, status: 404 };
+        return found;
+    }
+    const matches = items.filter((item) => item.id === id);
+    if (matches.length === 0)
+        return { error: `Trigger not found: ${id}`, status: 404 };
+    if (matches.length > 1) {
+        return {
+            error: `Trigger id is ambiguous across catalog roots: ${id}`,
+            status: 409,
+            project_roots: [...new Set(matches.map((item) => item.project_root))].sort((a, b) => a.localeCompare(b)),
+        };
+    }
+    return matches[0];
+}
+const triggerProjectRoot = z
+    .string()
+    .optional()
+    .describe("Catalog project root to write into; required when multiple catalog roots are configured and no sole non-seeded root exists");
+const triggerTask = z
+    .string()
+    .optional()
+    .describe("Catalog task id; omit to create a dynamic-mode trigger whose task is supplied at fire time");
+const createTriggerBase = {
+    project_root: triggerProjectRoot,
     directory: z.string(),
     id: z.string(),
     pipeline: z.string(),
-    task: z
-        .string()
-        .optional()
-        .describe("Catalog task id; omit to create a dynamic-mode trigger whose task is supplied at fire time"),
-    kind: z.enum(["manual", "schedule", "event"]),
-    schedule: triggerScheduleSchema.optional(),
-    event: triggerEventSchema.optional(),
+    task: triggerTask,
     enabled: z.boolean().optional(),
-});
+};
+const createTriggerSchema = z.discriminatedUnion("kind", [
+    z.object({ ...createTriggerBase, kind: z.literal("manual") }),
+    z.object({ ...createTriggerBase, kind: z.literal("schedule"), schedule: triggerScheduleSchema }),
+    z.object({ ...createTriggerBase, kind: z.literal("event"), event: triggerEventSchema }),
+]);
+const updateTriggerBase = {
+    id: z.string(),
+    project_root: z.string().optional(),
+    pipeline: z.string(),
+    task: z.string().optional(),
+    enabled: z.boolean(),
+};
+const updateTriggerSchema = z.discriminatedUnion("kind", [
+    z.object({ ...updateTriggerBase, kind: z.literal("manual") }),
+    z.object({ ...updateTriggerBase, kind: z.literal("schedule"), schedule: triggerScheduleSchema }),
+    z.object({ ...updateTriggerBase, kind: z.literal("event"), event: triggerEventSchema }),
+]);
 export function registerTriggerTools(server, deps) {
     const { store, cwd, manager } = deps;
     server.registerTool("list_triggers", {
@@ -65,32 +101,51 @@ export function registerTriggerTools(server, deps) {
         inputSchema: z.object({}),
     }, async () => {
         const items = await loadCatalogTriggers({ store, bootCwd: cwd });
-        return textResult({ triggers: items });
+        const triggers = await Promise.all(items.map(async (item) => ({
+            ...item,
+            adapter_status: await readTriggerAdapterStatus(item, store),
+        })));
+        return textResult({ triggers });
     });
     server.registerTool("get_trigger", {
         description: "Look up one catalog trigger by id (same source as GET /api/triggers/:id).",
         inputSchema: z.object({
             id: z.string(),
+            project_root: z
+                .string()
+                .optional()
+                .describe("Catalog project root; required when the same trigger id exists in more than one root"),
         }),
-    }, async ({ id }) => {
+    }, async ({ id, project_root }) => {
         const items = await loadCatalogTriggers({ store, bootCwd: cwd });
-        const found = items.find((item) => item.id === id);
-        if (!found) {
-            return textResult({ error: `Trigger not found: ${id}`, status: 404 }, true);
+        const found = findListedTrigger(items, id, project_root);
+        if ("error" in found) {
+            return textResult({ error: found.error, status: found.status, ...(found.project_roots ? { project_roots: found.project_roots } : {}) }, true);
         }
-        return textResult(found);
+        return textResult({
+            ...found,
+            adapter_status: await readTriggerAdapterStatus(found, store),
+        });
     });
     server.registerTool("fire_trigger", {
         description: "Fire a catalog trigger by id: resolves its pipeline/task refs and starts a run through the same RunManager.startRun path as start_run (same as POST /api/triggers/:id/fire). Returns { runId } or { runId, queued: true, queuePosition }. Fails not_found (404) for an unknown id, or 409 when the trigger is disabled.",
         inputSchema: z.object({
             id: z.string(),
+            project_root: z
+                .string()
+                .optional()
+                .describe("Catalog project root; required when the same trigger id exists in more than one root"),
             task: taskFileSchema
                 .optional()
                 .describe("Inline TaskFile, required to fire a dynamic-mode trigger (no catalog task) and rejected for a catalog-mode trigger"),
         }),
-    }, async ({ id, task }) => {
+    }, async ({ id, task, project_root }) => {
         const callerId = callerIdFromRequestAuth();
-        const result = await fireTrigger(id, store, manager, { cwd, task });
+        const result = await fireTrigger(id, store, manager, {
+            cwd,
+            task,
+            ...(project_root ? { project_root } : {}),
+        });
         if (!result.ok) {
             writeAudit(auditLog, {
                 caller_id: callerId,
@@ -170,16 +225,7 @@ export function registerTriggerTools(server, deps) {
     });
     server.registerTool("update_trigger", {
         description: "Replace a trigger's definition (pipeline, task, kind, schedule or event, enabled). Same validation and write path as PUT /api/triggers/:id; the id cannot change.",
-        inputSchema: z.object({
-            id: z.string(),
-            project_root: z.string().optional(),
-            pipeline: z.string(),
-            task: z.string().optional(),
-            kind: z.enum(["manual", "schedule", "event"]),
-            schedule: triggerScheduleSchema.optional(),
-            event: triggerEventSchema.optional(),
-            enabled: z.boolean().optional(),
-        }),
+        inputSchema: updateTriggerSchema,
     }, async ({ id, project_root, ...body }) => {
         const parsed = parsePutTriggerBody(body, id);
         if ("ok" in parsed)

package/dist/operatorAgent/evalGate.d.ts

@@ -0,0 +1,22 @@
+import { type EvalToolCallRecord, type EvalToolPolicy } from "../agents/evalGate.js";
+import type { OperatorAgentToolResult } from "./types.js";
+export type OperatorEvalPolicy = {
+    tools: EvalToolPolicy;
+    mocks: Record<string, {
+        result?: unknown;
+        error?: string;
+    }>;
+};
+/**
+ * Tool gate for an eval of a built-in operator agent. Reads may run. Writes, sends and deletes
+ * are stubbed or mocked and never reach the handler. `real` is treated as read-only: these
+ * agents write the operator's own project, so an eval cannot opt into that.
+ */
+export declare function createOperatorEvalGate(options: {
+    policy: OperatorEvalPolicy;
+    turn: () => number;
+}): {
+    decide(name: string, args: Record<string, unknown>): OperatorAgentToolResult | null;
+    observe(name: string, result: OperatorAgentToolResult): void;
+    records(): EvalToolCallRecord[];
+};

package/dist/operatorAgent/evalGate.js

@@ -0,0 +1,77 @@
+import { randomUUID } from "node:crypto";
+import { STUB_RESULT } from "../agents/evalGate.js";
+import { TOOL_META } from "../toolkit/meta.js";
+const ALWAYS_BLOCKED = new Set([
+    "run_eval",
+    "agent_chat",
+    "fire_trigger",
+    "sort_eval_failures",
+    "cancel_eval_run",
+    "start_run",
+    "run_stage",
+    "rerun",
+    "retry_stage",
+    "resume_stage",
+    "delete_run",
+    "cancel_run",
+    "gc_runs",
+    "remove_connection",
+    "delete_eval_run",
+    "delete_memory_card",
+    "archive_agent",
+    "enable_agent",
+    "set_trigger_enabled",
+    "test_connection",
+    "import_task_file",
+    "probe_project_mcp",
+]);
+/** Tools that only talk to the person or read Stageflow's own docs. They never change the project. */
+const SAFE = new Set(["confirm_action", "show_ui", "list_guide_topics", "read_guide_topic"]);
+/**
+ * Tool gate for an eval of a built-in operator agent. Reads may run. Writes, sends and deletes
+ * are stubbed or mocked and never reach the handler. `real` is treated as read-only: these
+ * agents write the operator's own project, so an eval cannot opt into that.
+ */
+export function createOperatorEvalGate(options) {
+    const records = [];
+    let pending;
+    const push = (record) => {
+        records.push(record);
+    };
+    return {
+        decide(name, args) {
+            const base = { id: randomUUID(), turn: options.turn(), name, args };
+            const mock = options.policy.mocks[name];
+            const deny = (result, policyOutcome) => {
+                push({ ...base, policyOutcome, status: "not_run", result });
+                return { ok: false, error: "eval.tool_not_run", content: { error: "eval.tool_not_run", message: result } };
+            };
+            if (ALWAYS_BLOCKED.has(name))
+                return deny(`${name} cannot run in an evaluation.`, "denied");
+            if (mock && (options.policy.tools === "mocked" || !mayRun(name))) {
+                const text = mock.error ?? (typeof mock.result === "string" ? mock.result : JSON.stringify(mock.result ?? null));
+                push({ ...base, policyOutcome: "mocked", status: mock.error !== undefined ? "error" : "ok", result: text });
+                return { ok: mock.error === undefined, ...(mock.error !== undefined ? { error: mock.error } : {}), content: mock.result ?? mock.error };
+            }
+            if (!mayRun(name))
+                return deny(STUB_RESULT(name), "stubbed");
+            pending = { ...base, policyOutcome: "ran", status: "ok" };
+            push(pending);
+            return null;
+        },
+        observe(_name, result) {
+            if (!pending)
+                return;
+            pending.result = typeof result.content === "string" ? result.content : JSON.stringify(result.content ?? null);
+            if (!result.ok)
+                pending.status = "error";
+            pending = undefined;
+        },
+        records: () => records,
+    };
+}
+function mayRun(name) {
+    if (SAFE.has(name))
+        return true;
+    return TOOL_META[name]?.risk === "read";
+}

package/dist/operatorAgent/fakeHost.js

@@ -1,5 +1,6 @@
 import { createOperatorAgentHost, invokeProfileTool, } from "./host.js";
 import { createAgentAuthorProfile } from "./profiles/agentAuthor.js";
+import { createStageflowGuideProfile } from "./profiles/stageflowGuide.js";
 import { createWorkshopAuthorProfile, isTaskProposalIntent, proposeStageFromUserMessage, proposeTaskFromUserMessage, WORKSHOP_AUTHOR_PROFILE_ID, } from "./profiles/workshopAuthor.js";
 /**
  * Deterministic Operator Agent Host for Workshop and tests.
@@ -8,7 +9,7 @@ import { createWorkshopAuthorProfile, isTaskProposalIntent, proposeStageFromUser
 export function createFakeOperatorAgentModel(script = [{ type: "propose_stage" }]) {
     let index = 0;
     return {
-        async complete({ profile, message, tools }) {
+        async complete({ profile, message, tools, onActivity }) {
             const turn = script[Math.min(index, script.length - 1)] ?? {
                 type: "propose_stage",
             };
@@ -28,7 +29,13 @@ export function createFakeOperatorAgentModel(script = [{ type: "propose_stage" }
                 };
             }
             if (turn.type === "call_tool") {
-                const result = await invokeProfileTool(profile, turn.name, turn.args ?? {}, tools);
+                const args = turn.args ?? {};
+                const callId = `${turn.name}-${index}`;
+                onActivity?.({ id: callId, name: turn.name, status: "running", args });
+                const result = await invokeProfileTool(profile, turn.name, args, tools);
+                onActivity?.(result.ok
+                    ? { id: callId, name: turn.name, status: "complete", result: result.content }
+                    : { id: callId, name: turn.name, status: "error", errorMessage: result.error ?? "unknown error" });
                 const events = [
                     { type: "tool_result", name: turn.name, result },
                 ];
@@ -88,6 +95,7 @@ export function createWorkshopOperatorHost(scriptOrOptions) {
             projectRoot: options.projectRoot,
         }),
         createAgentAuthorProfile(),
+        createStageflowGuideProfile(),
     ]);
     return host;
 }

package/dist/operatorAgent/host.js

@@ -1,7 +1,7 @@
 import { profileMayUse } from "../toolkit/profiles.js";
 import { enrichProposal, isMutationConflict, operatorContextFingerprint, UNDO_MUTATION_CONFLICT_NOTICE, } from "./proposals.js";
 import { rejectUnlinkedWorkshopDraftTool } from "../workshop/workshopPin.js";
-function createSession(profile, initialContext, model) {
+function createSession(profile, initialContext, model, evalGate) {
     let context = initialContext;
     let closed = false;
     const mutations = new Map();
@@ -23,6 +23,7 @@ function createSession(profile, initialContext, model) {
             lastMutationId = applied.id;
             lastEmitted = applied;
         },
+        ...(evalGate ? { evalGate } : {}),
     };
     function resolveMutation(mutationId) {
         if (mutations.size === 0)
@@ -165,6 +166,16 @@ export function createOperatorAgentHost(model, seedProfiles = []) {
             }
             return createSession(profile, context, model);
         },
+        openEvalSession({ profileId, context, gate }) {
+            if (!gate) {
+                throw new Error("An internal-agent eval session requires a tool gate");
+            }
+            const profile = profiles.get(profileId);
+            if (!profile) {
+                throw new Error(`Unknown operator agent profile: ${profileId}`);
+            }
+            return createSession(profile, context, model, gate);
+        },
     };
 }
 export async function invokeProfileTool(profile, name, args, ctx) {
@@ -178,5 +189,10 @@ export async function invokeProfileTool(profile, name, args, ctx) {
     const blocked = rejectUnlinkedWorkshopDraftTool(ctx.getContext(), name);
     if (blocked)
         return blocked;
-    return tool.handler(args, ctx);
+    const refused = ctx.evalGate?.decide(name, args);
+    if (refused)
+        return refused;
+    const result = await tool.handler(args, ctx);
+    ctx.evalGate?.observe(name, result);
+    return result;
 }

package/dist/operatorAgent/index.d.ts

@@ -6,6 +6,7 @@ export { createLiveWorkshopOperatorHost, createPiOperatorAgentModel, type LiveWo
 export { createFailingDocsRetriever, createFilesystemDocsRetriever, createStubDocsRetriever, resolveWorkshopCatalogRoot, type DocsRetrievalHit, type DocsRetrievalResult, type DocsRetriever, } from "./docsRetrieval.js";
 export { agentAuthorContextAdapter, emptyAgentAuthorDraft, isAgentAuthorContext, readAgentAuthorDraft, AGENT_AUTHOR_GREETING, type AgentAuthorContext, type AgentAuthorDraft, } from "./agentAuthorContext.js";
 export { AGENT_AUTHOR_PROFILE_ID, AGENT_AUTHOR_TOOL_NAMES, createAgentAuthorContext, createAgentAuthorProfile, } from "./profiles/agentAuthor.js";
+export { STAGEFLOW_GUIDE_GREETING, STAGEFLOW_GUIDE_PLAYBOOK, STAGEFLOW_GUIDE_PROFILE_ID, STAGEFLOW_GUIDE_TOOL_NAMES, createStageflowGuideProfile, } from "./profiles/stageflowGuide.js";
 export { AGENT_AUTHOR_PLAYBOOK } from "./profiles/agentAuthorPlaybook.js";
 export { operatorContextFingerprint } from "./proposals.js";
 export { createWorkshopDraftContext, draftTrackStages, emptyDraftPackage, isWorkshopDraftContext, readDraftFromContext, withDestination, withDraft, withProjectRoot, workshopDraftContextAdapter, WORKSHOP_AUTHOR_GREETING, } from "./draftContext.js";

package/dist/operatorAgent/index.js

@@ -5,6 +5,7 @@ export { createLiveWorkshopOperatorHost, createPiOperatorAgentModel, } from "./p
 export { createFailingDocsRetriever, createFilesystemDocsRetriever, createStubDocsRetriever, resolveWorkshopCatalogRoot, } from "./docsRetrieval.js";
 export { agentAuthorContextAdapter, emptyAgentAuthorDraft, isAgentAuthorContext, readAgentAuthorDraft, AGENT_AUTHOR_GREETING, } from "./agentAuthorContext.js";
 export { AGENT_AUTHOR_PROFILE_ID, AGENT_AUTHOR_TOOL_NAMES, createAgentAuthorContext, createAgentAuthorProfile, } from "./profiles/agentAuthor.js";
+export { STAGEFLOW_GUIDE_GREETING, STAGEFLOW_GUIDE_PLAYBOOK, STAGEFLOW_GUIDE_PROFILE_ID, STAGEFLOW_GUIDE_TOOL_NAMES, createStageflowGuideProfile, } from "./profiles/stageflowGuide.js";
 export { AGENT_AUTHOR_PLAYBOOK } from "./profiles/agentAuthorPlaybook.js";
 export { operatorContextFingerprint } from "./proposals.js";
 export { createWorkshopDraftContext, draftTrackStages, emptyDraftPackage, isWorkshopDraftContext, readDraftFromContext, withDestination, withDraft, withProjectRoot, workshopDraftContextAdapter, WORKSHOP_AUTHOR_GREETING, } from "./draftContext.js";

package/dist/operatorAgent/internalAgents.d.ts

@@ -0,0 +1,11 @@
+import type { OperatorAgentHost } from "./types.js";
+export declare const SHOW_INTERNAL_AGENTS_ENV = "STAGEFLOW_SHOW_INTERNAL_AGENTS";
+export type InternalAgentInfo = {
+    id: string;
+    title: string;
+    greeting?: string;
+    playbook: string;
+    tools: string[];
+};
+export declare function internalAgentsVisible(env?: NodeJS.ProcessEnv): boolean;
+export declare function describeInternalAgents(host: OperatorAgentHost): InternalAgentInfo[];

package/dist/operatorAgent/internalAgents.js

@@ -0,0 +1,13 @@
+export const SHOW_INTERNAL_AGENTS_ENV = "STAGEFLOW_SHOW_INTERNAL_AGENTS";
+export function internalAgentsVisible(env = process.env) {
+    return env[SHOW_INTERNAL_AGENTS_ENV] === "1";
+}
+export function describeInternalAgents(host) {
+    return host.listProfiles().map((profile) => ({
+        id: profile.id,
+        title: profile.title,
+        ...(profile.greeting !== undefined ? { greeting: profile.greeting } : {}),
+        playbook: profile.playbook,
+        tools: profile.tools.map((tool) => tool.name),
+    }));
+}

package/dist/operatorAgent/piModel.d.ts

@@ -1,5 +1,6 @@
 import { type AgentSession, defineTool, SessionManager } from "@earendil-works/pi-coding-agent";
 import "../agent/cursorProvider.js";
+import type { McpToolDeps } from "../mcp/deps.js";
 import { type OperatorAgentModel } from "./host.js";
 import { type WorkshopAuthorProfileOptions } from "./profiles/workshopAuthor.js";
 import type { OperatorAgentHost, OperatorAgentProfile, OperatorAgentToolContext, OperatorAgentToolResult, WorkshopToolActivityUpdate } from "./types.js";
@@ -76,5 +77,8 @@ export declare function workshopToolActivity(id: string, name: string, phase: "s
  * Pi OperatorAgentModel: durable session per host tool-context, Workshop tools only.
  */
 export declare function createPiOperatorAgentModel(options: PiOperatorAgentModelOptions): PiOperatorAgentModel;
-export type LiveWorkshopOperatorHostOptions = WorkshopAuthorProfileOptions & PiOperatorAgentModelOptions;
+export type LiveWorkshopOperatorHostOptions = WorkshopAuthorProfileOptions & PiOperatorAgentModelOptions & {
+    /** When set, Guide can call the Stageflow catalog. Without it, Guide only talks. */
+    guideDeps?: McpToolDeps;
+};
 export declare function createLiveWorkshopOperatorHost(options: LiveWorkshopOperatorHostOptions): OperatorAgentHost;

package/dist/operatorAgent/piModel.js

@@ -8,9 +8,10 @@
  */
 import { mkdir } from "node:fs/promises";
 import path from "node:path";
-import { defineTool, ModelRuntime, resolveCliModel, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
-import { Type } from "typebox";
+import { defineTool, ModelRuntime, resolveCliModel, SessionManager, } from "@earendil-works/pi-coding-agent";
 import { createPiAgentSession, createSealedResourceLoader, resolveWorkshopToolNames, } from "../agent/piSessionFactory.js";
+import { createPiSettingsManager } from "../agent/piSettings.js";
+import { createSessionContextWiring } from "../compaction/sessionWiring.js";
 import { bindCursorApiKey, cursorBridgePrompt, isCursorModelRef } from "../agent/cursorProvider.js";
 import { findProviderSupport } from "../agent/providerSupport.js";
 import "../agent/cursorProvider.js";
@@ -20,6 +21,7 @@ import { isUsableAuthFile, resolveCredentialBinding, } from "../runtime/credenti
 import { resolveWorkshopModel } from "../workshop/modelSettings.js";
 import { createOperatorAgentHost, invokeProfileTool, } from "./host.js";
 import { AGENT_AUTHOR_PROFILE_ID, agentAuthorBridgeHint, createAgentAuthorProfile, formatAgentAuthorTurnPrompt, } from "./profiles/agentAuthor.js";
+import { createStageflowGuideProfile } from "./profiles/stageflowGuide.js";
 import { createWorkshopAuthorProfile, } from "./profiles/workshopAuthor.js";
 import { readDraftFromContext } from "./draftContext.js";
 export function sessionNeedsExtensionReload(loaded, needed) {
@@ -37,7 +39,6 @@ function extensionPathsForModel(modelId) {
         return [];
     return prepared.extensionPaths;
 }
-const FLEX_PARAMS = Type.Object({}, { additionalProperties: true });
 const workshopLog = rootLogger.child({ component: "workshop" });
 export function workshopToolLogFields(args, result) {
     const body = args.body;
@@ -106,7 +107,8 @@ function buildWorkshopCustomTools(profileTools, getProfile, getTools, onToolResu
         name: tool.name,
         label: tool.name,
         description: tool.description,
-        parameters: FLEX_PARAMS,
+        parameters: tool.parameters,
+        constrainedSampling: { type: "json_schema", strict: "prefer" },
         execute: async (_toolCallId, params) => {
             const args = params !== null && typeof params === "object" && !Array.isArray(params)
                 ? params
@@ -119,6 +121,7 @@ function buildWorkshopCustomTools(profileTools, getProfile, getTools, onToolResu
             reportActivity({
                 ...workshopToolActivity(callId, tool.name, "start", args),
                 ...(pinnedBuildId ? { buildId: pinnedBuildId } : {}),
+                args,
             });
             const result = await invokeProfileTool(getProfile(), tool.name, args, getTools());
             const fields = workshopToolLogFields(args, result);
@@ -136,6 +139,7 @@ function buildWorkshopCustomTools(profileTools, getProfile, getTools, onToolResu
                     ...update,
                     draft,
                     ...(doneBuildId ? { buildId: doneBuildId } : {}),
+                    result: result.content,
                 });
             }
             else {
@@ -225,14 +229,14 @@ async function openDefaultPiSession(input) {
         authPath: input.authPath,
         modelsPath: path.join(path.dirname(input.authPath), "models.json"),
     });
-    const settingsManager = SettingsManager.inMemory({
-        compaction: { enabled: false },
-    });
+    const settingsManager = createPiSettingsManager();
+    const contextWiring = createSessionContextWiring({ workingState: true });
     const loader = createSealedResourceLoader({
         cwd: input.cwd,
         agentDir: input.agentDir,
         settingsManager,
-        systemPrompt: input.systemPrompt,
+        systemPrompt: contextWiring.guidance ? `${input.systemPrompt}\n\n${contextWiring.guidance}` : input.systemPrompt,
+        extensionFactories: contextWiring.extensions,
         ...(additionalExtensionPaths.length > 0
             ? { additionalExtensionPaths }
             : {}),
@@ -257,7 +261,7 @@ async function openDefaultPiSession(input) {
             sessionManager,
             settingsManager,
             resourceLoader: loader,
-            tools: input.toolNames,
+            tools: [...input.toolNames, ...contextWiring.toolNames],
             customTools: input.customTools,
         });
         session = created.session;
@@ -542,7 +546,7 @@ export function createPiOperatorAgentModel(options) {
     return model;
 }
 export function createLiveWorkshopOperatorHost(options) {
-    const { cwd, agentDir, authPath, model, settingsDefault, profileDefault, piSessionDir, openPiSession, resolveModelId, retriever, projectRoot, } = options;
+    const { cwd, agentDir, authPath, model, settingsDefault, profileDefault, piSessionDir, openPiSession, resolveModelId, retriever, projectRoot, guideDeps, } = options;
     return createOperatorAgentHost(createPiOperatorAgentModel({
         cwd,
         ...(agentDir !== undefined ? { agentDir } : {}),
@@ -559,5 +563,6 @@ export function createLiveWorkshopOperatorHost(options) {
             ...(projectRoot !== undefined ? { projectRoot } : {}),
         }),
         createAgentAuthorProfile(),
+        createStageflowGuideProfile(guideDeps),
     ]);
 }