stageflow 0.36.0 → 0.40.0

package/dist/agents/ledgers.d.ts

@@ -0,0 +1,29 @@
+import { type AgentDelivery, type AgentStore } from "./store.js";
+export type DeliveryInput = {
+    turnId: string;
+    sessionId: string;
+    connectionId: string;
+    provider: string;
+    replyTo: string;
+    text: string;
+};
+export type DeliveryClaim = "first" | "retry" | "manual";
+/** What reply delivery needs of storage, and nothing else. */
+export type DeliveryLedger = {
+    create(input: DeliveryInput): AgentDelivery;
+    get(turnId: string): AgentDelivery | undefined;
+    patch(turnId: string, patch: Parameters<AgentStore["updateDelivery"]>[1]): AgentDelivery | undefined;
+    due(): AgentDelivery[];
+    /**
+     * Take the right to send, atomically: moves the delivery to `sending` only if it is still in a state this kind of
+     * attempt may start from. Returns the claimed row, or undefined when someone else holds it or it already went out.
+     */
+    claim(turnId: string, kind: DeliveryClaim): AgentDelivery | undefined;
+};
+export declare function deliveryLedger(store: AgentStore, nowIso: () => string): DeliveryLedger;
+/** What the scheduler needs of storage: when each scheduled agent runs next. */
+export type ScheduleLedger = {
+    nextRun(projectRoot: string, agentId: string): string | undefined;
+    setNextRun(projectRoot: string, agentId: string, nextRunAt: string): void;
+};
+export declare function scheduleLedger(store: AgentStore): ScheduleLedger;

package/dist/agents/ledgers.js

@@ -0,0 +1,31 @@
+import { agentProjectKey } from "./store.js";
+export function deliveryLedger(store, nowIso) {
+    return {
+        create(input) {
+            const now = nowIso();
+            const delivery = { ...input, state: "pending", attempts: 0, errorCode: null, errorMessage: null, retryable: false, nextAttemptAt: null, createdAt: now, updatedAt: now };
+            store.insertDelivery(delivery);
+            return delivery;
+        },
+        get: (turnId) => store.getDelivery(turnId),
+        patch(turnId, patch) {
+            store.updateDelivery(turnId, patch, nowIso());
+            return store.getDelivery(turnId);
+        },
+        due: () => store.dueDeliveries(nowIso()),
+        claim(turnId, kind) {
+            const now = nowIso();
+            return kind === "first"
+                ? store.claimDelivery(turnId, ["pending"], now)
+                : kind === "manual"
+                    ? store.claimDelivery(turnId, ["failed", "unknown"], now)
+                    : store.claimDelivery(turnId, ["failed"], now, { dueRetry: true });
+        },
+    };
+}
+export function scheduleLedger(store) {
+    return {
+        nextRun: (projectRoot, agentId) => store.getScheduleNextRun(agentProjectKey(projectRoot), agentId),
+        setNextRun: (projectRoot, agentId, nextRunAt) => store.setScheduleNextRun(agentProjectKey(projectRoot), agentId, nextRunAt),
+    };
+}

package/dist/agents/lineDiff.d.ts

@@ -0,0 +1,12 @@
+export type DiffLine = {
+    kind: "same" | "added" | "removed";
+    text: string;
+    before?: number;
+    after?: number;
+};
+/**
+ * Line diff by longest common subsequence. Agent YAML files are small (tens to
+ * low hundreds of lines), so the O(n·m) table is fine and keeps this
+ * dependency-free.
+ */
+export declare function diffLines(before: string, after: string): DiffLine[];

package/dist/agents/lineDiff.js

@@ -0,0 +1,46 @@
+/**
+ * Line diff by longest common subsequence. Agent YAML files are small (tens to
+ * low hundreds of lines), so the O(n·m) table is fine and keeps this
+ * dependency-free.
+ */
+export function diffLines(before, after) {
+    const a = splitLines(before);
+    const b = splitLines(after);
+    const lcs = Array.from({ length: a.length + 1 }, () => new Array(b.length + 1).fill(0));
+    for (let i = a.length - 1; i >= 0; i -= 1) {
+        for (let j = b.length - 1; j >= 0; j -= 1) {
+            lcs[i][j] = a[i] === b[j] ? lcs[i + 1][j + 1] + 1 : Math.max(lcs[i + 1][j], lcs[i][j + 1]);
+        }
+    }
+    const out = [];
+    let i = 0;
+    let j = 0;
+    while (i < a.length && j < b.length) {
+        if (a[i] === b[j]) {
+            out.push({ kind: "same", text: a[i], before: i + 1, after: j + 1 });
+            i += 1;
+            j += 1;
+        }
+        else if (lcs[i + 1][j] >= lcs[i][j + 1]) {
+            out.push({ kind: "removed", text: a[i], before: i + 1 });
+            i += 1;
+        }
+        else {
+            out.push({ kind: "added", text: b[j], after: j + 1 });
+            j += 1;
+        }
+    }
+    for (; i < a.length; i += 1)
+        out.push({ kind: "removed", text: a[i], before: i + 1 });
+    for (; j < b.length; j += 1)
+        out.push({ kind: "added", text: b[j], after: j + 1 });
+    return out;
+}
+function splitLines(text) {
+    if (text === "")
+        return [];
+    const lines = text.split("\n");
+    if (lines.at(-1) === "")
+        lines.pop();
+    return lines;
+}

package/dist/agents/ndjson.d.ts

@@ -0,0 +1,9 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+/** Write one NDJSON frame, waiting for drain. (The request is already consumed here, so only the response state matters.) */
+export declare function writeFrame(res: ServerResponse, frame: unknown): Promise<void>;
+export declare class BodyError extends Error {
+    readonly reason: "too_large" | "not_json" | "not_object";
+    constructor(reason: "too_large" | "not_json" | "not_object");
+}
+/** Read a JSON object body. An empty body is `{}`. Throws BodyError so each surface can answer in its own words. */
+export declare function readJsonBody(req: IncomingMessage, maxBytes: number): Promise<Record<string, unknown>>;

package/dist/agents/ndjson.js

@@ -0,0 +1,47 @@
+/** Write one NDJSON frame, waiting for drain. (The request is already consumed here, so only the response state matters.) */
+export async function writeFrame(res, frame) {
+    if (res.writableEnded || res.destroyed)
+        return;
+    if (res.write(`${JSON.stringify(frame)}\n`))
+        return;
+    await new Promise((resolve) => {
+        const done = () => {
+            res.off("drain", done);
+            res.off("close", done);
+            resolve();
+        };
+        res.once("drain", done);
+        res.once("close", done);
+    });
+}
+export class BodyError extends Error {
+    reason;
+    constructor(reason) {
+        super(reason);
+        this.reason = reason;
+    }
+}
+/** Read a JSON object body. An empty body is `{}`. Throws BodyError so each surface can answer in its own words. */
+export async function readJsonBody(req, maxBytes) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        const buffer = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+        size += buffer.length;
+        if (size > maxBytes)
+            throw new BodyError("too_large");
+        chunks.push(buffer);
+    }
+    if (chunks.length === 0)
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(Buffer.concat(chunks).toString("utf8") || "{}");
+    }
+    catch {
+        throw new BodyError("not_json");
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+        throw new BodyError("not_object");
+    return parsed;
+}

package/dist/agents/otlpExport.d.ts

@@ -0,0 +1,9 @@
+import type { AgentSpan, AgentTurn } from "./store.js";
+/** OTLP/JSON `ExportTraceServiceRequest` for the given turns. */
+export declare function exportTurnsToOtlp(turns: Array<{
+    turn: AgentTurn;
+    spans: AgentSpan[];
+}>, resource: {
+    serviceName: string;
+    agentId: string;
+}): Record<string, unknown>;

package/dist/agents/otlpExport.js

@@ -0,0 +1,58 @@
+import { redactSecrets } from "../agent/streamLogRedact.js";
+function attribute(key, value) {
+    if (typeof value === "string")
+        return { key, value: { stringValue: value } };
+    if (typeof value === "boolean")
+        return { key, value: { boolValue: value } };
+    if (typeof value === "number") {
+        return Number.isInteger(value) ? { key, value: { intValue: String(value) } } : { key, value: { doubleValue: value } };
+    }
+    return undefined;
+}
+function unixNanos(iso) {
+    return `${BigInt(Date.parse(iso)) * 1000000n}`;
+}
+const STATUS_CODE = { ok: 1, error: 2, cancelled: 2 };
+function spanAttributes(span) {
+    const attrs = [
+        attribute("gen_ai.operation.name", span.name),
+        attribute("stageflow.span.kind", span.kind),
+        span.inputTokens !== null ? attribute("gen_ai.usage.input_tokens", span.inputTokens) : undefined,
+        span.outputTokens !== null ? attribute("gen_ai.usage.output_tokens", span.outputTokens) : undefined,
+        ...Object.entries(span.attributes).map(([key, value]) => attribute(key, value)),
+        // Bodies were redacted when stored; redact again so a future store path can't leak through export.
+        span.inputText !== null ? attribute("gen_ai.input.messages", redactSecrets(span.inputText)) : undefined,
+        span.outputText !== null ? attribute("gen_ai.output.messages", redactSecrets(span.outputText)) : undefined,
+    ];
+    return attrs.filter((item) => item !== undefined);
+}
+/** OTLP/JSON `ExportTraceServiceRequest` for the given turns. */
+export function exportTurnsToOtlp(turns, resource) {
+    return {
+        resourceSpans: [
+            {
+                resource: {
+                    attributes: [
+                        attribute("service.name", resource.serviceName),
+                        attribute("gen_ai.agent.name", resource.agentId),
+                    ].filter(Boolean),
+                },
+                scopeSpans: [
+                    {
+                        scope: { name: "stageflow.agents" },
+                        spans: turns.flatMap(({ turn, spans }) => spans.map((span) => ({
+                            traceId: turn.traceId,
+                            spanId: span.id,
+                            ...(span.parentSpanId ? { parentSpanId: span.parentSpanId } : {}),
+                            name: span.name,
+                            startTimeUnixNano: unixNanos(span.startedAt),
+                            endTimeUnixNano: unixNanos(span.endedAt ?? span.startedAt),
+                            status: { code: STATUS_CODE[span.status] ?? 0 },
+                            attributes: spanAttributes(span),
+                        }))),
+                    },
+                ],
+            },
+        ],
+    };
+}

package/dist/agents/otlpSink.d.ts

@@ -0,0 +1,7 @@
+export type OtlpSink = (payload: Record<string, unknown>) => Promise<void>;
+/**
+ * Collector from the standard OTel environment (`OTEL_EXPORTER_OTLP_ENDPOINT` or
+ * `..._TRACES_ENDPOINT`, plus `OTEL_EXPORTER_OTLP_HEADERS`). Undefined when none
+ * is configured, so `observability.otlp` is a no-op without a destination.
+ */
+export declare function otlpSinkFromEnv(env?: NodeJS.ProcessEnv, fetchImpl?: typeof fetch): OtlpSink | undefined;

package/dist/agents/otlpSink.js

@@ -0,0 +1,23 @@
+/**
+ * Collector from the standard OTel environment (`OTEL_EXPORTER_OTLP_ENDPOINT` or
+ * `..._TRACES_ENDPOINT`, plus `OTEL_EXPORTER_OTLP_HEADERS`). Undefined when none
+ * is configured, so `observability.otlp` is a no-op without a destination.
+ */
+export function otlpSinkFromEnv(env = process.env, fetchImpl = fetch) {
+    const traces = env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT?.trim();
+    const base = env.OTEL_EXPORTER_OTLP_ENDPOINT?.trim();
+    const url = traces || (base ? `${base.replace(/\/$/, "")}/v1/traces` : undefined);
+    if (!url)
+        return undefined;
+    const headers = { "content-type": "application/json" };
+    for (const pair of (env.OTEL_EXPORTER_OTLP_HEADERS ?? "").split(",")) {
+        const eq = pair.indexOf("=");
+        if (eq > 0)
+            headers[pair.slice(0, eq).trim()] = pair.slice(eq + 1).trim();
+    }
+    return async (payload) => {
+        const res = await fetchImpl(url, { method: "POST", headers, body: JSON.stringify(payload), signal: AbortSignal.timeout(10_000) });
+        if (!res.ok)
+            throw new Error(`OTLP collector responded ${res.status}`);
+    };
+}

package/dist/agents/policy.d.ts

@@ -0,0 +1,31 @@
+import { type AgentDefinition } from "../config/loadAgent.js";
+import type { ApprovalActor } from "./store.js";
+export type { ApprovalActor };
+type Grants = Pick<AgentDefinition, "tools" | "sub_agents">;
+/** True when the revision grants this tool id (builtin name, `<server>.<tool>`, or `agent:<id>`). */
+export declare function isToolGranted(definition: Grants, tool: string): boolean;
+/** Tools that always need a human decision, whatever the agent's `ask_first` list says. */
+export declare const ALWAYS_ASK_FIRST: readonly ["bash"];
+/** The tools this agent asks about: its `ask_first` list plus any granted tool that always needs a person. */
+export declare function effectiveAskFirst(definition: Grants & Pick<AgentDefinition, "approvals">): string[];
+export declare function requiresAskFirst(definition: Pick<AgentDefinition, "approvals">, tool: string): boolean;
+export declare function canApprove(definition: Pick<AgentDefinition, "approvals">, actor: ApprovalActor): boolean;
+/**
+ * Agent definitions and Stageflow state are never writable by an agent through a tool that names the path, whatever its
+ * grants. This does not cover `bash` (see `forbiddenWriteTarget`).
+ */
+export declare function isWritePathForbidden(projectRoot: string, stageflowHome: string, targetPath: string): boolean;
+/** Every path-like string the runtime can see in a tool call's arguments (including `paths: [...]`). */
+export declare function pathArgumentsOf(input: Record<string, unknown>): string[];
+/**
+ * The first forbidden path a tool call would write, or undefined. Applies to every tool that can write a path it is
+ * given: `write`, `edit`, and any other tool (an MCP file tool, say) with a path argument. Only Pi's read-only builtins
+ * are exempt. This is a check on arguments, not a sandbox: it cannot see what a tool does with them.
+ *
+ * `bash` is NOT path-confined. The runtime sees a command string, not its effects, so a granted `bash` can modify agent
+ * definitions and Stageflow state however this check is configured. Because of that every `bash` call is ask-first
+ * (ALWAYS_ASK_FIRST) and a person reads the command before it runs. Do not grant `bash` to an agent you need confined;
+ * the editor warns when it is granted (agent.shell_not_path_confined).
+ */
+export declare function forbiddenWriteTarget(projectRoot: string, stageflowHome: string, toolName: string, input: Record<string, unknown>): string | undefined;
+export declare function trustedLocalNotice(): string;

package/dist/agents/policy.js

@@ -0,0 +1,84 @@
+import path from "node:path";
+import { grantedToolIds } from "../config/loadAgent.js";
+/** True when the revision grants this tool id (builtin name, `<server>.<tool>`, or `agent:<id>`). */
+export function isToolGranted(definition, tool) {
+    if (grantedToolIds(definition).has(tool))
+        return true;
+    const dot = tool.indexOf(".");
+    if (dot <= 0)
+        return false;
+    return definition.tools.mcp[tool.slice(0, dot)]?.includes("*") ?? false;
+}
+/** Tools that always need a human decision, whatever the agent's `ask_first` list says. */
+export const ALWAYS_ASK_FIRST = ["bash"];
+/** The tools this agent asks about: its `ask_first` list plus any granted tool that always needs a person. */
+export function effectiveAskFirst(definition) {
+    const forced = ALWAYS_ASK_FIRST.filter((tool) => isToolGranted(definition, tool));
+    return [...new Set([...definition.approvals.ask_first, ...forced])];
+}
+export function requiresAskFirst(definition, tool) {
+    return ALWAYS_ASK_FIRST.includes(tool) || definition.approvals.ask_first.includes(tool);
+}
+export function canApprove(definition, actor) {
+    const { approvers } = definition.approvals;
+    if (actor.kind === "operator")
+        return approvers.operators;
+    return approvers.channel_ids.includes(actor.channelId);
+}
+/**
+ * Agent definitions and Stageflow state are never writable by an agent through a tool that names the path, whatever its
+ * grants. This does not cover `bash` (see `forbiddenWriteTarget`).
+ */
+export function isWritePathForbidden(projectRoot, stageflowHome, targetPath) {
+    const resolved = path.resolve(targetPath);
+    const within = (dir) => resolved === dir || resolved.startsWith(`${dir}${path.sep}`);
+    const root = path.resolve(projectRoot);
+    // The project may live under the Stageflow home (container workspace); only outside it is the home off limits.
+    if (!within(root) && within(path.resolve(stageflowHome)))
+        return true;
+    const relative = path.relative(path.join(root, "agents"), resolved);
+    if (relative && !relative.startsWith("..") && !path.isAbsolute(relative)) {
+        return relative.endsWith(".agent.yaml");
+    }
+    return false;
+}
+const READ_ONLY_BUILTINS = new Set(["read", "grep", "find", "ls"]);
+/** Argument names that carry a filesystem path in Pi's builtin tools and in common MCP file tools. */
+const PATH_ARGUMENTS = ["path", "file_path", "filePath", "file", "target", "destination", "dest", "output_path"];
+/** Every path-like string the runtime can see in a tool call's arguments (including `paths: [...]`). */
+export function pathArgumentsOf(input) {
+    const found = [];
+    for (const key of PATH_ARGUMENTS) {
+        const value = input[key];
+        if (typeof value === "string" && value.length > 0)
+            found.push(value);
+    }
+    if (Array.isArray(input.paths))
+        for (const value of input.paths)
+            if (typeof value === "string" && value.length > 0)
+                found.push(value);
+    return found;
+}
+/**
+ * The first forbidden path a tool call would write, or undefined. Applies to every tool that can write a path it is
+ * given: `write`, `edit`, and any other tool (an MCP file tool, say) with a path argument. Only Pi's read-only builtins
+ * are exempt. This is a check on arguments, not a sandbox: it cannot see what a tool does with them.
+ *
+ * `bash` is NOT path-confined. The runtime sees a command string, not its effects, so a granted `bash` can modify agent
+ * definitions and Stageflow state however this check is configured. Because of that every `bash` call is ask-first
+ * (ALWAYS_ASK_FIRST) and a person reads the command before it runs. Do not grant `bash` to an agent you need confined;
+ * the editor warns when it is granted (agent.shell_not_path_confined).
+ */
+export function forbiddenWriteTarget(projectRoot, stageflowHome, toolName, input) {
+    if (READ_ONLY_BUILTINS.has(toolName))
+        return undefined;
+    for (const target of pathArgumentsOf(input)) {
+        const resolved = path.isAbsolute(target) ? target : path.resolve(projectRoot, target);
+        if (isWritePathForbidden(projectRoot, stageflowHome, resolved))
+            return target;
+    }
+    return undefined;
+}
+export function trustedLocalNotice() {
+    return "This agent runs in trusted-local mode on the host filesystem. Use sandbox execution for isolation.";
+}

package/dist/agents/projectRoot.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Where agents live when no project is named: the Host's own project, or the workspace catalog
+ * when that directory is not writable (a container runs from a read-only install dir).
+ */
+export declare function defaultAgentProjectRoot(cwd: string): string;

package/dist/agents/projectRoot.js

@@ -0,0 +1,15 @@
+import { accessSync, constants } from "node:fs";
+import { workspaceCatalogPath } from "../project/workspaceCatalog.js";
+/**
+ * Where agents live when no project is named: the Host's own project, or the workspace catalog
+ * when that directory is not writable (a container runs from a read-only install dir).
+ */
+export function defaultAgentProjectRoot(cwd) {
+    try {
+        accessSync(cwd, constants.W_OK);
+        return cwd;
+    }
+    catch {
+        return workspaceCatalogPath();
+    }
+}

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;