stageflow 0.35.0 → 0.39.0

package/dist/agents/runtime/piRuntime.d.ts

@@ -0,0 +1,52 @@
+import { type AgentSession } from "@earendil-works/pi-coding-agent";
+import { type AgentDefinition } from "../../config/loadAgent.js";
+import { type StageMemory } from "../../memory/access.js";
+import { type SandboxRunner } from "../sandbox.js";
+import { type ToolkitTool } from "../../toolkit/index.js";
+import { type ConversationBackend, type TurnHooks } from "./types.js";
+export type PiRuntimeOptions = {
+    cwd: string;
+    agentDir: string;
+    sandbox?: SandboxRunner;
+    /** Stageflow's own tools, built lazily because they need Host services that start after the runtime. */
+    toolkit?: () => ToolkitTool[];
+    /**
+     * How long a session may sit unused before its Pi session and isolated MCP processes are released. A later message
+     * reopens it from the stored transcript. Default 30 minutes; 0 keeps sessions until released or disposed.
+     */
+    idleReleaseMs?: number;
+    /** Test seam: replaces session construction. */
+    openSession?: (input: OpenSessionInput) => Promise<OpenedSession>;
+};
+export type OpenSessionInput = {
+    projectRoot: string;
+    definition: AgentDefinition;
+    systemPrompt: string;
+    /** Pi tool names the session may expose. */
+    toolNames: string[];
+    /** Runs before each tool call; the session wires it to `pi.on("tool_call")`. */
+    gate: (call: {
+        toolCallId: string;
+        toolName: string;
+        input: Record<string, unknown>;
+    }) => Promise<{
+        block: true;
+        reason: string;
+        terminate?: boolean;
+    } | undefined>;
+    delegateTool?: (agentId: string, message: string) => Promise<string>;
+    /** Stageflow tools this agent is granted. */
+    stageflowTools?: ToolkitTool[];
+    memory?: StageMemory;
+    hooks: () => TurnHooks | undefined;
+};
+export type OpenedSession = {
+    session: Pick<AgentSession, "prompt" | "subscribe" | "dispose"> & {
+        abort?: AgentSession["abort"];
+    };
+    /** Tool names that exist on the session (builtins + MCP + delegation) for grant mapping. */
+    toolNames: string[];
+    shutdown(): Promise<void>;
+};
+export declare const DEFAULT_IDLE_RELEASE_MS: number;
+export declare function createPiAgentRuntime(options: PiRuntimeOptions): ConversationBackend;

package/dist/agents/runtime/piRuntime.js

@@ -0,0 +1,474 @@
+import { mkdir, readFile } 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 { collectMcpExtensionToolNames, mcpToolMetadataMissing } from "../../agent/piAdapter.js";
+import { attachIsolatedMcp } from "../../agent/piIsolatedMcp.js";
+import { warmIsolatedMcpMetadata } from "../../agent/piIsolatedMcpProbe.js";
+import { createPiAgentSession, createSealedResourceLoader } from "../../agent/piSessionFactory.js";
+import { bindCursorApiKey, isCursorModelRef } from "../../agent/cursorProvider.js";
+import { findProviderSupport } from "../../agent/providerSupport.js";
+import { grantedBuiltinTools } from "../../config/loadAgent.js";
+import { bindStageMemory } from "../../memory/access.js";
+import { MemoryError, memoryHostFor } from "../../memory/host.js";
+import { memorySession } from "../../tools/memoryTools.js";
+import { resolveSkillByName } from "../../config/listSkills.js";
+import { resolveStageMcpServers } from "../../config/resolveStageMcpServers.js";
+import { globalStageflowHome } from "../../project/globalHome.js";
+import { isUsableAuthFile, resolveCredentialBinding } from "../../runtime/credentialBinding.js";
+import { getModelCatalog } from "../../models/catalog.js";
+import { AgentError } from "../errors.js";
+import { MEMORY_STORE_BASH_DENIED, memoryStorePathInCommand } from "../../memory/bashDeny.js";
+import { memoryHome } from "../../memory/host.js";
+import { forbiddenWriteTarget } from "../policy.js";
+import { prepareExecutionLaunch } from "../sandbox.js";
+import { grantedStageflowTools, isOperatorOnlyTool } from "../../toolkit/index.js";
+import { grantIdForPiTool, STAGEFLOW_PI_PREFIX } from "./types.js";
+function piToolNames(definition) {
+    return grantedBuiltinTools(definition);
+}
+async function projectContext(projectRoot) {
+    for (const name of ["AGENTS.md", "CLAUDE.md"]) {
+        try {
+            const text = await readFile(path.join(projectRoot, name), "utf8");
+            return `\n\n# Project context (${name})\n${text.slice(0, 20_000)}`;
+        }
+        catch {
+            continue;
+        }
+    }
+    return "";
+}
+function textOf(content) {
+    if (!Array.isArray(content))
+        return "";
+    return content
+        .map((block) => (block && typeof block === "object" && block.type === "text" ? String(block.text ?? "") : ""))
+        .join("");
+}
+function replayPrompt(prior) {
+    return [
+        "Earlier conversation in this session (restored after a restart). Continue from it; do not re-ask answered questions.",
+        "",
+        ...prior.map((m) => `${m.role}: ${m.text.trim()}`),
+    ].join("\n");
+}
+async function openPiSession(options, input) {
+    const { definition, projectRoot } = input;
+    const modelId = definition.model.id ?? (await getModelCatalog(options.cwd).defaultModel());
+    // Cursor's SDK agent runs its own file and shell tools beside Pi's, so grants and ask-first cannot hold.
+    if (isCursorModelRef(modelId) && process.env.STAGEFLOW_AGENTS_ALLOW_CURSOR_NATIVE_TOOLS !== "1") {
+        throw new AgentError("agent.backend_unavailable", "Cursor models run their own file and shell tools outside this agent's grants and approvals. Choose another provider's model, or set STAGEFLOW_AGENTS_ALLOW_CURSOR_NATIVE_TOOLS=1 on the Host to accept that.");
+    }
+    const provider = findProviderSupport(modelId);
+    const authPath = resolveCredentialBinding(options.cwd).authPath;
+    if (!provider && !isUsableAuthFile(authPath)) {
+        throw new AgentError("agent.backend_unavailable", "Provider auth is not configured. Add credentials in Providers, then retry.");
+    }
+    const restoreKey = bindCursorApiKey(modelId);
+    const extensionPaths = [];
+    let restoreProvider;
+    if (provider) {
+        const prepared = provider.prepare(modelId);
+        if (prepared.error)
+            throw new AgentError("agent.backend_unavailable", prepared.error);
+        extensionPaths.push(...prepared.extensionPaths);
+        restoreProvider = prepared.restore;
+    }
+    const cleanup = () => {
+        restoreKey?.();
+        restoreProvider?.();
+    };
+    let attached;
+    let session;
+    try {
+        await mkdir(options.agentDir, { recursive: true });
+        const modelRuntime = await ModelRuntime.create({ authPath, modelsPath: path.join(path.dirname(authPath), "models.json") });
+        const settingsManager = SettingsManager.inMemory({ compaction: { enabled: true } });
+        const mcpServers = Object.keys(definition.tools.mcp);
+        const resolvedMcp = mcpServers.length > 0
+            ? await resolveStageMcpServers({ projectRoot, allowlist: mcpServers, env: {}, scope: { kind: "agent" } })
+            : undefined;
+        attached = await attachIsolatedMcp(resolvedMcp, { lifecycle: "lazy" });
+        const skillPaths = [];
+        for (const name of definition.tools.skills) {
+            const skill = await resolveSkillByName(name, { cwd: projectRoot, agentDir: options.agentDir });
+            if (!skill)
+                throw new AgentError("agent.backend_unavailable", `Skill "${name}" is not installed`);
+            skillPaths.push(skill.filePath);
+        }
+        const gateExtension = (pi) => {
+            pi.on("tool_call", async (event) => {
+                const outcome = await input.gate({ toolCallId: event.toolCallId, toolName: event.toolName, input: event.input });
+                return outcome;
+            });
+        };
+        const extensionFactories = [{ name: "stageflow-agent-gate", factory: gateExtension }, ...(attached.extensionFactories ?? [])];
+        const loader = createSealedResourceLoader({
+            cwd: projectRoot,
+            agentDir: options.agentDir,
+            settingsManager,
+            systemPrompt: input.systemPrompt,
+            additionalExtensionPaths: extensionPaths,
+            ...(skillPaths.length > 0 ? { additionalSkillPaths: skillPaths } : {}),
+            extensionFactories,
+            ...(attached.eventBus ? { eventBus: attached.eventBus } : {}),
+        });
+        await loader.reload();
+        if (resolvedMcp && mcpToolMetadataMissing(loader)) {
+            await warmIsolatedMcpMetadata(resolvedMcp, { cwd: projectRoot });
+            await loader.reload();
+            if (mcpToolMetadataMissing(loader)) {
+                throw new AgentError("agent.backend_unavailable", `MCP tool metadata unavailable for: ${mcpServers.join(", ")}`);
+            }
+        }
+        const errors = loader.getExtensions().errors;
+        if (errors.length > 0) {
+            throw new AgentError("agent.backend_unavailable", `Failed to load extension(s): ${errors.map((e) => `${e.path}: ${e.error}`).join("; ")}`);
+        }
+        const toolNames = [...input.toolNames];
+        if (attached.extensionFactories) {
+            const mcp = collectMcpExtensionToolNames(loader);
+            if (!mcp.ok)
+                throw new AgentError("agent.backend_unavailable", `MCP adapter registered unrequested tool(s): ${mcp.unrequested.join(", ")}`);
+            // Only tools the definition grants are exposed; the gate repeats this check on every call.
+            toolNames.push(...mcp.names.filter((name) => {
+                const id = grantIdForPiTool(name, mcpServers, []);
+                const dot = id.indexOf(".");
+                if (dot < 0)
+                    return false;
+                const allowed = definition.tools.mcp[id.slice(0, dot)];
+                return allowed?.includes("*") || allowed?.includes(id.slice(dot + 1));
+            }));
+        }
+        const customTools = [];
+        if (input.delegateTool) {
+            for (const agentId of definition.sub_agents) {
+                customTools.push(defineTool({
+                    name: `agent_${agentId}`,
+                    label: `Ask ${agentId}`,
+                    description: `Hand a task to the "${agentId}" agent and get its reply.`,
+                    parameters: Type.Object({ message: Type.String({ description: "The task or question for the agent." }) }),
+                    execute: async (_id, args) => {
+                        const reply = await input.delegateTool(agentId, args.message);
+                        return { content: [{ type: "text", text: reply }], details: {} };
+                    },
+                }));
+                toolNames.push(`agent_${agentId}`);
+            }
+        }
+        if (input.memory) {
+            for (const definition of memorySession(input.memory).tools) {
+                customTools.push(defineTool(definition));
+                toolNames.push(definition.name);
+            }
+        }
+        for (const tool of input.stageflowTools ?? []) {
+            customTools.push(defineTool({
+                name: `${STAGEFLOW_PI_PREFIX}${tool.name}`,
+                label: tool.name,
+                description: tool.description,
+                parameters: Type.Unsafe(tool.parameters),
+                execute: async (_id, args, signal) => {
+                    const result = await tool.run(args ?? {}, { signal: signal ?? new AbortController().signal, caller: { agentId: definition.id, definition } });
+                    if (!result.ok)
+                        throw new Error(result.text);
+                    return { content: [{ type: "text", text: result.text }], details: {} };
+                },
+            }));
+            toolNames.push(`${STAGEFLOW_PI_PREFIX}${tool.name}`);
+        }
+        const sessionDir = path.join(globalStageflowHome(), "agents", "pi-sessions");
+        await mkdir(sessionDir, { recursive: true });
+        const created = await createPiAgentSession({
+            cwd: projectRoot,
+            agentDir: options.agentDir,
+            modelRuntime,
+            sessionManager: SessionManager.create(projectRoot, sessionDir),
+            settingsManager,
+            resourceLoader: loader,
+            tools: toolNames,
+            customTools,
+        });
+        session = created.session;
+        await session.bindExtensions({});
+        const resolved = resolveCliModel({ cliModel: modelId, modelRuntime });
+        if (resolved.error || !resolved.model)
+            throw new AgentError("agent.backend_unavailable", resolved.error ?? `Model not found: ${modelId}`);
+        await session.setModel(resolved.model);
+        session.setThinkingLevel((resolved.thinkingLevel ?? definition.model.thinking));
+        const live = session;
+        const live_attached = attached;
+        return {
+            session: live,
+            toolNames,
+            shutdown: async () => {
+                try {
+                    live.dispose();
+                }
+                catch {
+                    // best-effort
+                }
+                live_attached.cancel?.();
+                cleanup();
+            },
+        };
+    }
+    catch (error) {
+        try {
+            session?.dispose();
+        }
+        catch {
+            // best-effort
+        }
+        attached?.cancel?.();
+        cleanup();
+        throw error;
+    }
+}
+/** Seconds of silence from the model before a turn is failed. 0 turns the watchdog off. */
+function stallTimeoutMs() {
+    const seconds = Number(process.env.STAGEFLOW_AGENT_STALL_SECONDS ?? 180);
+    return Number.isFinite(seconds) && seconds >= 0 ? seconds * 1000 : 180_000;
+}
+export const DEFAULT_IDLE_RELEASE_MS = 30 * 60_000;
+/** Idle window from the option, else STAGEFLOW_AGENT_SESSION_IDLE_MINUTES, else 30 minutes. 0 disables. */
+function idleReleaseMs(options) {
+    if (options.idleReleaseMs !== undefined)
+        return Math.max(0, options.idleReleaseMs);
+    const minutes = Number(process.env.STAGEFLOW_AGENT_SESSION_IDLE_MINUTES);
+    return process.env.STAGEFLOW_AGENT_SESSION_IDLE_MINUTES !== undefined && Number.isFinite(minutes) && minutes >= 0 ? minutes * 60_000 : DEFAULT_IDLE_RELEASE_MS;
+}
+export function createPiAgentRuntime(options) {
+    const bound = new Map();
+    const idleMs = idleReleaseMs(options);
+    const disarmIdle = (state) => {
+        if (state.idleTimer)
+            clearTimeout(state.idleTimer);
+        state.idleTimer = undefined;
+    };
+    const armIdle = (sessionId, state) => {
+        disarmIdle(state);
+        if (idleMs <= 0)
+            return;
+        state.idleTimer = setTimeout(() => {
+            state.idleTimer = undefined;
+            // A turn that started since is not idle; its end re-arms the timer.
+            if (state.hooks || bound.get(sessionId) !== state)
+                return;
+            bound.delete(sessionId);
+            void state.opened.shutdown().catch(() => undefined);
+        }, idleMs);
+        state.idleTimer.unref?.();
+    };
+    const open = options.openSession ?? ((input) => openPiSession(options, input));
+    async function ensure(input) {
+        const existing = bound.get(input.sessionId);
+        if (existing)
+            return { state: existing, fresh: false };
+        const { definition, projectRoot } = input;
+        if (definition.model.backend !== "pi") {
+            throw new AgentError("agent.backend_unavailable", `The ${definition.model.backend} backend is not available for agents yet.`);
+        }
+        await prepareExecutionLaunch(definition, projectRoot, options.sandbox);
+        const mcpServers = Object.keys(definition.tools.mcp);
+        const subAgents = [...definition.sub_agents];
+        const grantedSf = new Set(grantedStageflowTools(definition.tools.stageflow));
+        const stageflowTools = (options.toolkit?.() ?? []).filter((tool) => grantedSf.has(tool.name) && !isOperatorOnlyTool(tool.name));
+        const state = { opened: undefined, definitionKey: definition.id, hooks: undefined, mcpServers, subAgents };
+        const context = definition.project_context ? await projectContext(projectRoot) : "";
+        let memory;
+        if (definition.memories?.length) {
+            try {
+                memory = await bindStageMemory(memoryHostFor(), definition.memories);
+            }
+            catch (error) {
+                const code = error instanceof MemoryError ? error.code : "MEMORY_UNREADABLE";
+                throw new AgentError("agent.invalid", `Memory could not be opened (${code})`);
+            }
+        }
+        const systemPrompt = `${definition.instructions}${context}${memory ? `\n\n${memorySession(memory).prompt}` : ""}`;
+        state.opened = await open({
+            projectRoot,
+            definition,
+            systemPrompt,
+            toolNames: piToolNames(definition),
+            hooks: () => state.hooks,
+            ...(memory ? { memory } : {}),
+            ...(stageflowTools.length > 0 ? { stageflowTools } : {}),
+            ...(subAgents.length > 0 ? { delegateTool: (agentId, message) => state.hooks.delegate(agentId, message) } : {}),
+            gate: async (call) => {
+                const hooks = state.hooks;
+                if (!hooks)
+                    return { block: true, reason: "No turn is active" };
+                const tool = grantIdForPiTool(call.toolName, mcpServers, subAgents);
+                // Every tool whose arguments name a path is checked, not only write/edit. `bash` cannot be: see forbiddenWriteTarget.
+                if (forbiddenWriteTarget(projectRoot, globalStageflowHome(), call.toolName, call.input) !== undefined) {
+                    return { block: true, reason: "Agent definitions and Stageflow state cannot be written by an agent." };
+                }
+                if (memory && call.toolName === "bash") {
+                    const command = call.input.command;
+                    if (typeof command === "string" && memoryStorePathInCommand(command, memoryHome())) {
+                        return { block: true, reason: MEMORY_STORE_BASH_DENIED };
+                    }
+                }
+                const release = state.stall?.hold();
+                const decision = await hooks.gate({ id: call.toolCallId, tool, input: call.input }).finally(() => release?.());
+                return decision.allow ? undefined : { block: true, reason: decision.reason, ...(decision.stopTurn ? { terminate: true } : {}) };
+            },
+        });
+        bound.set(input.sessionId, state);
+        return { state, fresh: true };
+    }
+    return {
+        id: "pi",
+        async complete(input) {
+            const { state, fresh } = await ensure(input);
+            disarmIdle(state);
+            state.hooks = input.hooks;
+            const user = input.messages.at(-1);
+            if (!user || user.role !== "user")
+                return { text: "", toolOutputs: [] };
+            const { session } = state.opened;
+            const toolOutputs = [];
+            let text = "";
+            const usage = { inputTokens: 0, outputTokens: 0, costUsd: 0 };
+            let startedAt = new Date();
+            const calls = new Map();
+            // A model call that goes quiet (provider queue, dropped connection) must not hold the session forever.
+            // Waiting on a person (approval), a running tool or a sub-agent is not a stall.
+            const stallMs = stallTimeoutMs();
+            let holds = 0;
+            let stalled = false;
+            let stallTimer;
+            const arm = () => {
+                if (stallTimer)
+                    clearTimeout(stallTimer);
+                stallTimer = undefined;
+                if (holds > 0 || stallMs <= 0)
+                    return;
+                stallTimer = setTimeout(() => {
+                    stalled = true;
+                    void session.abort?.();
+                }, stallMs);
+            };
+            state.stall = {
+                hold() {
+                    holds += 1;
+                    arm();
+                    let released = false;
+                    return () => {
+                        if (released)
+                            return;
+                        released = true;
+                        holds -= 1;
+                        arm();
+                    };
+                },
+            };
+            const toolHolds = new Map();
+            const unsubscribe = session.subscribe((event) => {
+                arm();
+                const e = event;
+                if (e.type === "message_start" && e.message?.role === "assistant")
+                    startedAt = new Date();
+                else if (e.type === "message_update" && e.assistantMessageEvent?.type === "text_delta" && typeof e.assistantMessageEvent.delta === "string") {
+                    text += e.assistantMessageEvent.delta;
+                    input.onDelta(e.assistantMessageEvent.delta);
+                }
+                else if (e.type === "message_end" && e.message?.role === "assistant") {
+                    const u = e.message.usage;
+                    const info = { inputTokens: u?.input ?? 0, outputTokens: u?.output ?? 0, costUsd: u?.cost?.total ?? 0 };
+                    usage.inputTokens += info.inputTokens;
+                    usage.outputTokens += info.outputTokens;
+                    usage.costUsd += info.costUsd;
+                    input.hooks.modelFinished({ startedAt, endedAt: new Date(), ...info, ...(e.message.model ? { model: e.message.model } : {}) });
+                    const final = textOf(e.message.content);
+                    if (final && !text)
+                        text = final;
+                }
+                else if (e.type === "tool_execution_start" && e.toolCallId && e.toolName) {
+                    const call = { id: e.toolCallId, tool: grantIdForPiTool(e.toolName, state.mcpServers, state.subAgents), input: e.args ?? {} };
+                    calls.set(e.toolCallId, call);
+                    toolHolds.set(e.toolCallId, state.stall.hold());
+                    input.hooks.toolStarted(call);
+                }
+                else if (e.type === "tool_execution_end" && e.toolCallId) {
+                    toolHolds.get(e.toolCallId)?.();
+                    toolHolds.delete(e.toolCallId);
+                    const call = calls.get(e.toolCallId);
+                    if (call) {
+                        const output = textOf(e.result?.content);
+                        toolOutputs.push(output);
+                        input.hooks.toolFinished(call, { ok: !(e.isError ?? e.result?.isError), output });
+                    }
+                }
+            });
+            const onAbort = () => void session.abort?.();
+            input.signal.addEventListener("abort", onAbort, { once: true });
+            try {
+                const prior = input.messages.slice(0, -1).map((m) => ({ role: m.role, text: m.text }));
+                const prompt = fresh && prior.length > 0 ? `${replayPrompt(prior)}\n\nuser: ${user.text}` : user.text;
+                arm();
+                await session.prompt(prompt);
+            }
+            finally {
+                if (stallTimer)
+                    clearTimeout(stallTimer);
+                for (const release of toolHolds.values())
+                    release();
+                input.signal.removeEventListener("abort", onAbort);
+                unsubscribe();
+                state.hooks = undefined;
+                state.stall = undefined;
+                if (bound.get(input.sessionId) === state)
+                    armIdle(input.sessionId, state);
+            }
+            if (stalled) {
+                throw new AgentError("agent.model_timeout", `The model stopped responding for ${Math.round(stallMs / 1000)} seconds. Try again, or pick a faster model or a lower thinking level.`);
+            }
+            return { text, toolOutputs, usage };
+        },
+        async judge(input) {
+            const opened = await open({
+                projectRoot: input.projectRoot,
+                definition: { ...input.definition, tools: { ...input.definition.tools, builtin: [], builtin_tools: [], mcp: {}, skills: [] }, sub_agents: [] },
+                systemPrompt: "You are a strict evaluator. Answer only with the requested number.",
+                toolNames: [],
+                gate: async () => ({ block: true, reason: "No tools" }),
+                hooks: () => undefined,
+            });
+            let out = "";
+            const unsubscribe = opened.session.subscribe((event) => {
+                const e = event;
+                if (e.type === "message_update" && e.assistantMessageEvent?.type === "text_delta")
+                    out += e.assistantMessageEvent.delta ?? "";
+            });
+            const onAbort = () => void opened.session.abort?.();
+            input.signal.addEventListener("abort", onAbort, { once: true });
+            try {
+                await opened.session.prompt(input.prompt);
+            }
+            finally {
+                input.signal.removeEventListener("abort", onAbort);
+                unsubscribe();
+                await opened.shutdown();
+            }
+            return out;
+        },
+        async release(sessionId) {
+            const state = bound.get(sessionId);
+            bound.delete(sessionId);
+            if (state)
+                disarmIdle(state);
+            await state?.opened.shutdown();
+        },
+        async dispose() {
+            const all = [...bound.values()];
+            bound.clear();
+            for (const state of all)
+                disarmIdle(state);
+            await Promise.all(all.map((state) => state.opened.shutdown()));
+        },
+    };
+}

package/dist/agents/runtime/types.d.ts

@@ -0,0 +1,77 @@
+import type { AgentDefinition } from "../../config/loadAgent.js";
+export type ConversationMessage = {
+    role: "user" | "assistant";
+    text: string;
+};
+/** One tool call by its grant id: a builtin name, `<server>.<tool>`, or `agent:<id>`. */
+export type ToolCall = {
+    id: string;
+    tool: string;
+    input: Record<string, unknown>;
+};
+export type GateDecision = {
+    allow: true;
+} | {
+    allow: false;
+    reason: string;
+    stopTurn?: boolean;
+};
+export type RuntimeUsage = {
+    inputTokens: number;
+    outputTokens: number;
+    costUsd: number;
+};
+/** What the runtime reports back to the conversation while a turn runs. */
+export type TurnHooks = {
+    /** Called before every tool call: grants, write guards, and ask-first approval. */
+    gate(call: ToolCall): Promise<GateDecision>;
+    toolStarted(call: ToolCall): void;
+    toolFinished(call: ToolCall, result: {
+        ok: boolean;
+        output: string;
+    }): void;
+    modelFinished(info: {
+        startedAt: Date;
+        endedAt: Date;
+        inputTokens: number;
+        outputTokens: number;
+        costUsd: number;
+        model?: string;
+    }): void;
+    /** Run another agent for a `agent:<id>` call and return its reply. */
+    delegate(agentId: string, message: string): Promise<string>;
+};
+export type CompleteInput = {
+    sessionId: string;
+    projectRoot: string;
+    definition: AgentDefinition;
+    /** Prior transcript followed by the new user message. */
+    messages: ConversationMessage[];
+    signal: AbortSignal;
+    onDelta: (text: string) => void;
+    hooks: TurnHooks;
+};
+export type CompleteResult = {
+    text: string;
+    usage?: RuntimeUsage;
+    toolOutputs: string[];
+};
+export type ConversationBackend = {
+    id: "pi" | "claude";
+    complete(input: CompleteInput): Promise<CompleteResult>;
+    /** One-shot judgement with no tools (groundedness scoring). */
+    judge?(input: {
+        projectRoot: string;
+        definition: AgentDefinition;
+        prompt: string;
+        signal: AbortSignal;
+    }): Promise<string>;
+    /** Drop any cached model session for a conversation session. */
+    release?(sessionId: string): Promise<void>;
+    dispose?(): Promise<void>;
+};
+export declare const BUILTIN_TOOL_GROUP_OF: Record<string, "read" | "write" | "shell">;
+/** Pi tool names for Stageflow's own tools are `stageflow_<tool>`. */
+export declare const STAGEFLOW_PI_PREFIX = "stageflow_";
+/** Map a Pi tool name to its grant id given the granted MCP servers and sub-agents. */
+export declare function grantIdForPiTool(piTool: string, mcpServers: readonly string[], subAgents: readonly string[]): string;

package/dist/agents/runtime/types.js

@@ -0,0 +1,26 @@
+import { stageflowGrantId, TOOL_META } from "../../toolkit/meta.js";
+export const BUILTIN_TOOL_GROUP_OF = {
+    read: "read",
+    grep: "read",
+    find: "read",
+    ls: "read",
+    write: "write",
+    edit: "write",
+    bash: "shell",
+};
+/** Pi tool names for Stageflow's own tools are `stageflow_<tool>`. */
+export const STAGEFLOW_PI_PREFIX = "stageflow_";
+/** Map a Pi tool name to its grant id given the granted MCP servers and sub-agents. */
+export function grantIdForPiTool(piTool, mcpServers, subAgents) {
+    if (piTool in BUILTIN_TOOL_GROUP_OF)
+        return piTool;
+    if (piTool.startsWith(STAGEFLOW_PI_PREFIX) && piTool.slice(STAGEFLOW_PI_PREFIX.length) in TOOL_META)
+        return stageflowGrantId(piTool.slice(STAGEFLOW_PI_PREFIX.length));
+    const agentMatch = /^agent_(.+)$/.exec(piTool);
+    if (agentMatch && subAgents.includes(agentMatch[1]))
+        return `agent:${agentMatch[1]}`;
+    const server = [...mcpServers].sort((a, b) => b.length - a.length).find((name) => piTool.startsWith(`${name}_`));
+    if (server)
+        return `${server}.${piTool.slice(server.length + 1)}`;
+    return piTool;
+}

package/dist/agents/sandbox.d.ts

@@ -0,0 +1,17 @@
+import type { AgentDefinition } from "../config/loadAgent.js";
+export type SandboxRunner = {
+    prepareLaunch(input: {
+        projectRoot: string;
+        definition: AgentDefinition;
+    }): Promise<{
+        ref: string;
+    }>;
+};
+export type ExecutionLaunch = {
+    mode: "trusted-local";
+} | {
+    mode: "sandbox";
+    ref: string;
+};
+/** A sandboxed agent never falls back to trusted-local when no sandbox is available. */
+export declare function prepareExecutionLaunch(definition: AgentDefinition, projectRoot: string, runner: SandboxRunner | undefined): Promise<ExecutionLaunch>;

package/dist/agents/sandbox.js

@@ -0,0 +1,10 @@
+import { AgentError } from "./errors.js";
+/** A sandboxed agent never falls back to trusted-local when no sandbox is available. */
+export async function prepareExecutionLaunch(definition, projectRoot, runner) {
+    if (definition.execution === "trusted-local")
+        return { mode: "trusted-local" };
+    if (!runner)
+        throw new AgentError("agent.sandbox_unavailable");
+    const launched = await runner.prepareLaunch({ projectRoot, definition });
+    return { mode: "sandbox", ref: launched.ref };
+}