stageflow 0.35.0 → 0.39.0

package/dist/agents/hostContext.d.ts

@@ -0,0 +1,54 @@
+import type Database from "better-sqlite3";
+import type { ChannelService } from "../channels/service.js";
+import { AgentInboundRouter } from "./communications/inbound.js";
+import { ReplyDelivery } from "./communications/delivery.js";
+import { ChannelSupervisor } from "./communications/supervisor.js";
+import { AgentChatController } from "./chatTurn.js";
+import { type OtlpSink } from "./otlpSink.js";
+import type { ContactInfo } from "../channels/types.js";
+import type { McpToolDeps } from "../mcp/deps.js";
+import { AgentService, type AgentEnvironment } from "./service.js";
+import type { ConversationBackend } from "./sessions.js";
+import { PublicWebChat } from "./webChat/publicChat.js";
+export type AgentHostContext = {
+    service: AgentService;
+    inbound: AgentInboundRouter;
+    publicChat: PublicWebChat;
+    chat: AgentChatController;
+    backend: ConversationBackend;
+    /** Streams held open to AgentMail and iMessage; absent unless the Host listens (not in tests). */
+    channelListeners?: ChannelSupervisor;
+    /** Replies to people on channels: retries, resend, mark delivered. */
+    delivery: ReplyDelivery;
+    /** How people reach a connection (the number to text), cached for a minute. */
+    channelContact(connectionId: string): Promise<{
+        provider: string;
+        contact: ContactInfo;
+    } | undefined>;
+    /** Stop what the Host started for agents (listeners). */
+    stop(): Promise<void>;
+};
+/** Read-only lookups the editor warnings use: `.mcp.json`, skills, and channel connections. */
+export declare function createAgentEnvironment(options: {
+    agentDir: string;
+    cwd: string;
+    channels?: Pick<ChannelService, "list">;
+}): AgentEnvironment;
+/**
+ * Agent runtime for one Host. Agent state shares the Host's SQLite connection
+ * (migration 013). Turns left running by a previous process are failed here,
+ * since nothing can resume them.
+ */
+export declare function createAgentHostContext(options: {
+    cwd: string;
+    agentDir: string;
+    connection: Database.Database;
+    channels?: Pick<ChannelService, "list">;
+    backend?: ConversationBackend;
+    environment?: AgentEnvironment;
+    otlpSink?: OtlpSink | undefined;
+    /** Host services the Stageflow tools need; agent services are added here. Without it agents get no Stageflow tools. */
+    /** Hold streams open to AgentMail and iMessage for agents linked to them. Only a running Host does this. */
+    listenOnChannels?: boolean;
+    toolkitDeps?: Pick<McpToolDeps, "manager" | "store" | "agentDir" | "providerAuthContext" | "projectRoot" | "providerBoot">;
+}): AgentHostContext;

package/dist/agents/hostContext.js

@@ -0,0 +1,156 @@
+import { listSkills } from "../config/listSkills.js";
+import { listProjectMcpCatalog } from "../config/resolveStageMcpServers.js";
+import { channelInboundConnections } from "./communications/channelConnections.js";
+import { channelHostFor } from "../channels/host.js";
+import { channelIdentity } from "./communications/identity.js";
+import { AgentInboundRouter } from "./communications/inbound.js";
+import { ReplyDelivery } from "./communications/delivery.js";
+import { ChannelSupervisor } from "./communications/supervisor.js";
+import { AgentChatController } from "./chatTurn.js";
+import { otlpSinkFromEnv } from "./otlpSink.js";
+import { buildToolkit } from "../toolkit/index.js";
+import { createPiAgentRuntime } from "./runtime/piRuntime.js";
+import { AgentService } from "./service.js";
+import { getModelCatalog } from "../models/catalog.js";
+import { defaultAgentProjectRoot } from "./projectRoot.js";
+import { PublicWebChat } from "./webChat/publicChat.js";
+import { AgentStore } from "./store.js";
+/** Read-only lookups the editor warnings use: `.mcp.json`, skills, and channel connections. */
+export function createAgentEnvironment(options) {
+    return {
+        async mcpServerNames(projectRoot) {
+            const catalog = await listProjectMcpCatalog(projectRoot);
+            return catalog.status === "ok" ? catalog.servers.map((server) => server.name) : [];
+        },
+        async skillNames(projectRoot) {
+            const catalog = await listSkills({ cwd: projectRoot, agentDir: options.agentDir });
+            return catalog.skills.map((skill) => skill.name);
+        },
+        async modelInfo(id) {
+            const snapshot = await getModelCatalog(options.cwd).snapshot().catch(() => undefined);
+            if (!snapshot || snapshot.providers.length === 0)
+                return undefined;
+            const model = snapshot.providers.flatMap((provider) => provider.models).find((entry) => entry.id === id);
+            return { known: model !== undefined, nativeTools: model?.nativeTools ?? false };
+        },
+        async connectionIdentity(connectionId) {
+            try {
+                const connection = channelHostFor(defaultAgentProjectRoot(options.cwd)).registry.resolve(connectionId, false);
+                return channelIdentity({ id: connection.id, provider: connection.provider, config: connection.config, credential: connection.credential ? { secrets: connection.credential.secrets } : undefined });
+            }
+            catch {
+                return undefined;
+            }
+        },
+        async connectionIds() {
+            if (!options.channels)
+                return undefined;
+            return options.channels.list().connections.map((connection) => connection.id);
+        },
+    };
+}
+/**
+ * Agent runtime for one Host. Agent state shares the Host's SQLite connection
+ * (migration 013). Turns left running by a previous process are failed here,
+ * since nothing can resume them.
+ */
+export function createAgentHostContext(options) {
+    const service = new AgentService({
+        store: new AgentStore(options.connection),
+        environment: options.environment ??
+            createAgentEnvironment({
+                agentDir: options.agentDir,
+                cwd: options.cwd,
+                ...(options.channels ? { channels: options.channels } : {}),
+            }),
+    });
+    service.recoverInterruptedTurns();
+    let toolkit;
+    let chatRef;
+    const backend = options.backend ??
+        createPiAgentRuntime({
+            cwd: options.cwd,
+            agentDir: options.agentDir,
+            ...(options.toolkitDeps
+                ? {
+                    toolkit: () => (toolkit ??= buildToolkit({
+                        ...options.toolkitDeps,
+                        cwd: options.cwd,
+                        agentService: service,
+                        ...(chatRef ? { agentChat: chatRef } : {}),
+                    })),
+                }
+                : {}),
+        });
+    const chat = new AgentChatController({
+        service,
+        backend,
+        otlpSink: "otlpSink" in options ? options.otlpSink : otlpSinkFromEnv(),
+        logError: (message) => console.error(message),
+    });
+    chatRef = chat;
+    // Archived agents will not run again: let the runtime drop what it holds for their sessions.
+    service.onArchived((_agentId, sessionIds) => {
+        for (const sessionId of sessionIds)
+            void chat.release(sessionId);
+    });
+    // The send ledger lives under the project root, so use the agents' writable root, not a read-only install dir.
+    const channelConnectionsForAgents = channelInboundConnections(defaultAgentProjectRoot(options.cwd));
+    const delivery = new ReplyDelivery({
+        service,
+        reply: (connectionId, to, text, key) => channelConnectionsForAgents.reply(connectionId, to, text, key),
+        log: (message) => console.error(message),
+    });
+    const inbound = new AgentInboundRouter({
+        service,
+        chat,
+        connections: channelConnectionsForAgents,
+        projectRoot: defaultAgentProjectRoot(options.cwd),
+        logError: (message) => console.error(message),
+        delivery,
+    });
+    const publicChat = new PublicWebChat({
+        service,
+        chat,
+        projectRoot: defaultAgentProjectRoot(options.cwd),
+        allowedOrigins: (process.env.STAGEFLOW_PUBLIC_CHAT_ORIGINS ?? "")
+            .split(",")
+            .map((origin) => origin.trim())
+            .filter((origin) => origin.length > 0),
+        logError: (message) => console.error(message),
+    });
+    const connections = channelConnectionsForAgents;
+    const channelListeners = options.listenOnChannels
+        ? new ChannelSupervisor({
+            service,
+            projectRoot: defaultAgentProjectRoot(options.cwd),
+            resolve: (id) => connections.resolve?.(id),
+            deliver: (message) => inbound.deliver(message),
+            log: (message) => console.error(message),
+        })
+        : undefined;
+    const contactCache = new Map();
+    const channelContact = async (connectionId) => {
+        const cached = contactCache.get(connectionId);
+        if (cached && Date.now() - cached.at < 60_000)
+            return cached.value;
+        const provider = connections.resolve?.(connectionId)?.provider;
+        const contact = provider ? await connections.contact?.(connectionId) : undefined;
+        const value = provider && contact ? { provider, contact } : undefined;
+        // A failed lookup is retried on the next ask rather than remembered.
+        if (value?.contact.ok !== false)
+            contactCache.set(connectionId, { at: Date.now(), value });
+        return value;
+    };
+    channelListeners?.start();
+    if (options.listenOnChannels)
+        delivery.start();
+    if (options.listenOnChannels)
+        void inbound.resumeInterrupted().catch((error) => console.error(`agent resume failed: ${String(error)}`));
+    return { service, chat, backend, inbound, publicChat, channelContact, ...(channelListeners ? { channelListeners } : {}), delivery, stop: async () => {
+            delivery.stop();
+            await channelListeners?.stop();
+            // The Host owns every runtime session's lifetime: nothing outlives it.
+            await backend.dispose?.().catch((error) => console.error(`agent runtime dispose failed: ${String(error)}`));
+        } };
+}

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();
+    }
+}