stageflow 0.40.0 → 0.44.0

package/dist/guide/chat.js

@@ -0,0 +1,378 @@
+import { randomUUID } from "node:crypto";
+import { logger as rootLogger } from "../logging/logger.js";
+import { STAGEFLOW_GUIDE_GREETING, STAGEFLOW_GUIDE_PROFILE_ID, createStageflowGuideProfile, } from "../operatorAgent/index.js";
+import { redactString } from "../logging/redact.js";
+import { buildWorkshopChatPrompt, parseWorkshopChatAttachments } from "../workshop/chatAttachments.js";
+import { resolveWorkshopModel } from "../workshop/modelSettings.js";
+import { advanceGuideTurn } from "../operatorAgent/profiles/guideConfirm.js";
+import { GUIDE_UI_TOOL_NAMES } from "./showUi.js";
+import { guideTitleFrom, readGuideThread, saveGuideThread, } from "./threadStore.js";
+const log = rootLogger.child({ component: "guide" });
+export const GUIDE_MAX_MESSAGE_CHARS = 8000;
+export class GuideError extends Error {
+    code;
+    status;
+    constructor(code, status) {
+        super(code);
+        this.code = code;
+        this.status = status;
+        this.name = "GuideError";
+    }
+}
+export const GUIDE_TOOL_RESULT_MAX_BYTES = 20_000;
+const GUIDE_TOOL_ERROR_MAX_CHARS = 300;
+const GUIDE_KEPT_RESULT_TOOLS = new Set(GUIDE_UI_TOOL_NAMES);
+const SECRET_KEY = /secret|password|passwd|token|api_?key/i;
+const sessions = new Map();
+const running = new Set();
+const turnAborts = new Map();
+export function resetGuideSessionsForTests() {
+    for (const controller of turnAborts.values())
+        controller.abort();
+    turnAborts.clear();
+    for (const session of sessions.values())
+        session.close();
+    sessions.clear();
+    running.clear();
+}
+export function guideAgentInfo(host) {
+    const profile = host.getProfile(STAGEFLOW_GUIDE_PROFILE_ID);
+    return {
+        name: profile?.title ?? createStageflowGuideProfile().title,
+        greeting: profile?.greeting ?? STAGEFLOW_GUIDE_GREETING,
+    };
+}
+export function isGuideThreadRunning(threadId) {
+    return running.has(threadId);
+}
+export function abortGuideTurn(threadId) {
+    const controller = turnAborts.get(threadId);
+    if (!controller)
+        return false;
+    controller.abort();
+    return true;
+}
+async function openGuideSession(host, record) {
+    const existing = sessions.get(record.id);
+    if (existing)
+        return existing;
+    const profile = host.getProfile(STAGEFLOW_GUIDE_PROFILE_ID);
+    if (!profile)
+        throw new GuideError("guide.unavailable", 503);
+    const session = host.openSession({
+        profileId: STAGEFLOW_GUIDE_PROFILE_ID,
+        context: { kind: "stageflow_guide" },
+    });
+    sessions.set(record.id, session);
+    if (record.messages.length > 0) {
+        await session.prepareRestart?.(record.messages.map((message) => ({ role: message.role, text: message.text })));
+    }
+    return session;
+}
+function assistantText(events) {
+    return events
+        .filter((event) => event.type === "message" && event.role === "assistant" && typeof event.text === "string")
+        .map((event) => event.text ?? "")
+        .filter(Boolean)
+        .join("\n\n");
+}
+export async function* streamGuideTurn(input) {
+    const text = input.text.trim();
+    const parsedAttachments = parseWorkshopChatAttachments(input.attachments);
+    if (!parsedAttachments.ok)
+        throw new GuideError("guide.attachment", 400);
+    const attachments = parsedAttachments.attachments;
+    if (!text && attachments.length === 0)
+        throw new GuideError("guide.invalid", 400);
+    if (text.length > GUIDE_MAX_MESSAGE_CHARS)
+        throw new GuideError("guide.message_too_long", 413);
+    const record = readGuideThread(input.threadId, input.storeRoot);
+    if (!record)
+        throw new GuideError("guide.not_found", 404);
+    if (running.has(record.id))
+        throw new GuideError("guide.busy", 409);
+    if (input.signal?.aborted)
+        return;
+    const turnAbort = new AbortController();
+    const onExternalAbort = () => turnAbort.abort();
+    if (input.signal) {
+        input.signal.addEventListener("abort", onExternalAbort);
+    }
+    turnAborts.set(record.id, turnAbort);
+    running.add(record.id);
+    let live;
+    try {
+        const now = new Date().toISOString();
+        const attachmentMeta = attachments.map(({ name, size, mediaType }) => ({ name, size, mediaType }));
+        const userMessage = {
+            id: randomUUID(),
+            role: "user",
+            text,
+            createdAt: now,
+            ...(attachmentMeta.length > 0 ? { attachments: attachmentMeta } : {}),
+        };
+        const titled = record.title.trim() ? record : { ...record, title: guideTitleFrom(text || attachments[0]?.name || "") };
+        const incoming = typeof input.model === "string" && input.model.trim() ? input.model.trim() : undefined;
+        const sessionModel = incoming ?? record.model;
+        saveGuideThread({
+            ...titled,
+            updatedAt: now,
+            messages: [...titled.messages, userMessage],
+            ...(sessionModel ? { model: sessionModel } : {}),
+        }, input.storeRoot);
+        const queue = createFrameQueue();
+        live = queue;
+        let streamed = "";
+        const parts = createPartsRecorder();
+        const session = await openGuideSession(input.host, titled);
+        const onAbort = () => {
+            void session.abort();
+        };
+        turnAbort.signal.addEventListener("abort", onAbort);
+        if (turnAbort.signal.aborted)
+            onAbort();
+        const prompt = buildWorkshopChatPrompt(text || "Please look at the attached files.", attachments, null);
+        const modelId = resolveWorkshopModel({ sessionOverride: sessionModel });
+        session.setContext(advanceGuideTurn(session.getContext()));
+        const finished = session
+            .send(prompt, {
+            modelId,
+            onDelta: (delta) => {
+                streamed += delta;
+                parts.text(delta);
+                queue.push({ type: "delta", text: delta });
+            },
+            onActivity: (update) => {
+                queue.push(parts.tool(update));
+            },
+        })
+            .then((events) => ({ ok: true, events }))
+            .catch((err) => ({ ok: false, err }))
+            .finally(() => queue.close());
+        for await (const frame of queue.frames()) {
+            yield frame;
+            if (turnAbort.signal.aborted)
+                break;
+        }
+        const result = await finished;
+        turnAbort.signal.removeEventListener("abort", onAbort);
+        if (turnAbort.signal.aborted) {
+            persistAssistant(input.threadId, input.storeRoot, streamed, parts.finish());
+            return;
+        }
+        if (!result.ok) {
+            if (result.err instanceof GuideError)
+                throw result.err;
+            persistAssistant(input.threadId, input.storeRoot, streamed, parts.finish());
+            log.warn("guide.turn.failed", "turn failed", { threadId: record.id });
+            yield { type: "error", code: "guide.failed", message: "" };
+            return;
+        }
+        const reply = assistantText(result.events) || streamed;
+        const failed = result.events.some((event) => event.type === "error");
+        if (failed && !reply) {
+            log.warn("guide.turn.failed", "turn failed", { threadId: record.id });
+            yield { type: "error", code: "guide.failed", message: "" };
+            return;
+        }
+        if (reply.startsWith(streamed)) {
+            const rest = reply.slice(streamed.length);
+            if (rest) {
+                parts.text(rest);
+                yield { type: "delta", text: rest };
+            }
+        }
+        else if (reply && reply !== streamed) {
+            parts.replaceText(reply);
+            yield { type: "delta", text: reply };
+        }
+        const saved = persistAssistant(input.threadId, input.storeRoot, reply, parts.finish());
+        if (saved)
+            yield { type: "done", message: saved };
+        else
+            yield { type: "error", code: "guide.failed", message: "" };
+    }
+    catch (err) {
+        if (turnAbort.signal.aborted)
+            return;
+        if (err instanceof GuideError)
+            throw err;
+        log.warn("guide.turn.failed", "turn failed", { threadId: record.id });
+        yield { type: "error", code: "guide.failed", message: "" };
+    }
+    finally {
+        input.signal?.removeEventListener("abort", onExternalAbort);
+        live?.close();
+        turnAborts.delete(record.id);
+        running.delete(record.id);
+    }
+}
+function createFrameQueue() {
+    const items = [];
+    let pending = null;
+    let closed = false;
+    return {
+        push(frame) {
+            if (closed)
+                return;
+            if (pending) {
+                const resolve = pending;
+                pending = null;
+                resolve(frame);
+            }
+            else {
+                items.push(frame);
+            }
+        },
+        close() {
+            closed = true;
+            pending?.(null);
+            pending = null;
+        },
+        async *frames() {
+            while (true) {
+                const next = await new Promise((resolve) => {
+                    if (items.length > 0) {
+                        resolve(items.shift() ?? null);
+                        return;
+                    }
+                    if (closed) {
+                        resolve(null);
+                        return;
+                    }
+                    pending = resolve;
+                });
+                if (!next)
+                    return;
+                yield next;
+            }
+        },
+    };
+}
+function scrubSecrets(value) {
+    if (typeof value === "string")
+        return redactString(value);
+    if (Array.isArray(value))
+        return value.map(scrubSecrets);
+    if (value !== null && typeof value === "object") {
+        const out = {};
+        for (const [key, child] of Object.entries(value)) {
+            out[key] = key === "secrets" || (SECRET_KEY.test(key) && typeof child === "string")
+                ? "[redacted]"
+                : scrubSecrets(child);
+        }
+        return out;
+    }
+    return value;
+}
+function boundedResult(name, result) {
+    const scrubbed = scrubSecrets(result);
+    if (GUIDE_KEPT_RESULT_TOOLS.has(name))
+        return scrubbed;
+    let bytes;
+    try {
+        bytes = Buffer.byteLength(JSON.stringify(scrubbed) ?? "");
+    }
+    catch {
+        return { truncated: true };
+    }
+    return bytes > GUIDE_TOOL_RESULT_MAX_BYTES ? { truncated: true } : scrubbed;
+}
+function boundedArgs(args) {
+    const scrubbed = scrubSecrets(args);
+    let bytes;
+    try {
+        bytes = Buffer.byteLength(JSON.stringify(scrubbed));
+    }
+    catch {
+        return { truncated: true };
+    }
+    return bytes > GUIDE_TOOL_RESULT_MAX_BYTES ? { truncated: true } : scrubbed;
+}
+function shortError(message) {
+    const text = redactString((message ?? "").trim()) || "tool_failed";
+    return text.length > GUIDE_TOOL_ERROR_MAX_CHARS ? `${text.slice(0, GUIDE_TOOL_ERROR_MAX_CHARS - 1)}…` : text;
+}
+function createPartsRecorder() {
+    let parts = [];
+    let pending = "";
+    const flush = () => {
+        if (!pending)
+            return;
+        parts.push({ type: "text", text: pending });
+        pending = "";
+    };
+    return {
+        text(delta) {
+            pending += delta;
+        },
+        replaceText(text) {
+            parts = parts.filter((part) => part.type !== "text");
+            pending = text;
+        },
+        tool(update) {
+            const base = { type: "tool", id: update.id, name: update.name };
+            let frame;
+            if (update.status === "running") {
+                frame = { ...base, status: "running", ...(update.args ? { args: boundedArgs(update.args) } : {}) };
+            }
+            else if (update.status === "complete") {
+                frame = { ...base, status: "complete", ...(update.result !== undefined ? { result: boundedResult(update.name, update.result) } : {}) };
+            }
+            else {
+                frame = { ...base, status: "error", error: shortError(update.errorMessage) };
+            }
+            const index = parts.findIndex((part) => part.type === "tool" && part.id === update.id && part.status === "running");
+            if (frame.status === "running") {
+                if (index !== -1)
+                    return frame;
+                flush();
+                parts.push({ ...base, status: "running", ...(frame.args ? { args: frame.args } : {}) });
+                return frame;
+            }
+            const started = index === -1 ? undefined : parts[index];
+            const done = {
+                ...base,
+                status: frame.status,
+                ...(started?.args ? { args: started.args } : {}),
+                ...(frame.result !== undefined ? { result: frame.result } : {}),
+                ...(frame.error !== undefined ? { error: frame.error } : {}),
+            };
+            if (index === -1) {
+                flush();
+                parts.push(done);
+            }
+            else {
+                parts[index] = done;
+            }
+            return frame;
+        },
+        finish() {
+            flush();
+            return parts.map((part) => part.type === "tool" && part.status === "running"
+                ? { ...part, status: "error", error: "guide.tool_interrupted" }
+                : part);
+        },
+    };
+}
+function persistAssistant(threadId, storeRoot, text, parts = []) {
+    const reply = text.trim();
+    if (!reply && !parts.some((part) => part.type === "tool"))
+        return null;
+    const latest = readGuideThread(threadId, storeRoot);
+    if (!latest)
+        return null;
+    const message = {
+        id: randomUUID(),
+        role: "assistant",
+        text: reply,
+        createdAt: new Date().toISOString(),
+        ...(parts.length > 0 ? { parts } : {}),
+    };
+    saveGuideThread({
+        ...latest,
+        updatedAt: message.createdAt,
+        messages: [...latest.messages, message],
+    }, storeRoot);
+    return message;
+}

package/dist/guide/knowledge/index.d.ts

@@ -0,0 +1,14 @@
+export type GuideKnowledgeTopic = {
+    id: string;
+    title: string;
+    summary: string;
+    body: string;
+};
+export type GuideKnowledgeMatch = {
+    topic: GuideKnowledgeTopic;
+    score: number;
+    excerpt: string;
+};
+export declare const GUIDE_KNOWLEDGE_TOPICS: readonly GuideKnowledgeTopic[];
+export declare function findGuideKnowledge(id: string): GuideKnowledgeTopic | undefined;
+export declare function searchGuideKnowledge(query: string, limit?: number): GuideKnowledgeMatch[];

package/dist/guide/knowledge/index.js

@@ -0,0 +1,109 @@
+import { agentsTopic } from "./topics/agents.js";
+import { bestPracticesTopic } from "./topics/bestPractices.js";
+import { connectionsTopic } from "./topics/connections.js";
+import { consoleMapTopic } from "./topics/consoleMap.js";
+import { evalsTopic } from "./topics/evals.js";
+import { limitationsTopic } from "./topics/limitations.js";
+import { mcpSkillsBrowserTopic } from "./topics/mcpSkillsBrowser.js";
+import { memoriesTopic } from "./topics/memories.js";
+import { modelsAndProvidersTopic } from "./topics/modelsAndProviders.js";
+import { overviewTopic } from "./topics/overview.js";
+import { pipelinesTopic } from "./topics/pipelines.js";
+import { stagesTopic } from "./topics/stages.js";
+import { tasksTopic } from "./topics/tasks.js";
+import { triggersTopic } from "./topics/triggers.js";
+import { troubleshootingTopic } from "./topics/troubleshooting.js";
+export const GUIDE_KNOWLEDGE_TOPICS = [
+    overviewTopic,
+    pipelinesTopic,
+    stagesTopic,
+    tasksTopic,
+    agentsTopic,
+    triggersTopic,
+    connectionsTopic,
+    memoriesTopic,
+    evalsTopic,
+    modelsAndProvidersTopic,
+    mcpSkillsBrowserTopic,
+    bestPracticesTopic,
+    limitationsTopic,
+    troubleshootingTopic,
+    consoleMapTopic,
+];
+const STOP_WORDS = new Set([
+    "a", "an", "and", "are", "as", "at", "be", "by", "can", "do", "does", "for", "from", "how", "i", "if",
+    "in", "is", "it", "me", "my", "of", "on", "or", "should", "that", "the", "this", "to", "what", "when",
+    "where", "which", "who", "why", "with", "you", "your",
+]);
+const EXCERPT_CHARS = 240;
+export function findGuideKnowledge(id) {
+    const key = id.trim().toLowerCase();
+    return GUIDE_KNOWLEDGE_TOPICS.find((topic) => topic.id === key);
+}
+function tokenize(text) {
+    return text
+        .toLowerCase()
+        .split(/[^a-z0-9_.-]+/)
+        .map((token) => token.replace(/^[.-]+|[.-]+$/g, ""))
+        .filter((token) => token.length >= 2 && !STOP_WORDS.has(token));
+}
+function countOccurrences(haystack, needle) {
+    let count = 0;
+    let index = haystack.indexOf(needle);
+    while (index !== -1) {
+        count += 1;
+        index = haystack.indexOf(needle, index + needle.length);
+    }
+    return count;
+}
+function scoreTopic(topic, tokens, phrase) {
+    const id = topic.id.toLowerCase();
+    const title = topic.title.toLowerCase();
+    const summary = topic.summary.toLowerCase();
+    const body = topic.body.toLowerCase();
+    let score = 0;
+    for (const token of tokens) {
+        if (id === token || id.split("_").includes(token))
+            score += 8;
+        score += 5 * Math.min(countOccurrences(title, token), 2);
+        score += 3 * Math.min(countOccurrences(summary, token), 3);
+        score += Math.min(countOccurrences(body, token), 6);
+    }
+    if (tokens.length > 1 && phrase.length > 0) {
+        if (title.includes(phrase) || summary.includes(phrase))
+            score += 6;
+        else if (body.includes(phrase))
+            score += 4;
+    }
+    return score;
+}
+function excerptFor(body, tokens) {
+    const lower = body.toLowerCase();
+    let at = -1;
+    for (const token of tokens) {
+        const index = lower.indexOf(token);
+        if (index !== -1 && (at === -1 || index < at))
+            at = index;
+    }
+    const start = Math.max(0, at === -1 ? 0 : at - EXCERPT_CHARS / 3);
+    let slice = body.slice(start, start + EXCERPT_CHARS);
+    if (start > 0)
+        slice = slice.replace(/^\S*\s/, "");
+    if (start + EXCERPT_CHARS < body.length)
+        slice = slice.replace(/\s\S*$/, "");
+    const text = slice.replace(/\s+/g, " ").trim();
+    return `${start > 0 ? "…" : ""}${text}${start + EXCERPT_CHARS < body.length ? "…" : ""}`;
+}
+export function searchGuideKnowledge(query, limit = 3) {
+    const tokens = [...new Set(tokenize(query))];
+    if (tokens.length === 0)
+        return [];
+    const phrase = tokens.join(" ");
+    const max = Math.max(1, Math.floor(limit));
+    return GUIDE_KNOWLEDGE_TOPICS
+        .map((topic, order) => ({ topic, order, score: scoreTopic(topic, tokens, phrase) }))
+        .filter((entry) => entry.score > 0)
+        .sort((a, b) => b.score - a.score || a.order - b.order)
+        .slice(0, max)
+        .map(({ topic, score }) => ({ topic, score, excerpt: excerptFor(topic.body, tokens) }));
+}

package/dist/guide/knowledge/topics/agents.d.ts

@@ -0,0 +1,2 @@
+import type { GuideKnowledgeTopic } from "../index.js";
+export declare const agentsTopic: GuideKnowledgeTopic;

package/dist/guide/knowledge/topics/agents.js

@@ -0,0 +1,58 @@
+export const agentsTopic = {
+    id: "agents",
+    title: "Project agents: definition, tools, approvals, reach and limits",
+    summary: "Agent YAML fields, tool grants, ask-first approvals, memories, one inbound channel, schedule, web chat, limits, sub-agents, revisions, and the rules that an agent cannot grant beyond what it holds or edit itself.",
+    body: `# Project agents
+
+An agent is one file, \`agents/<id>.agent.yaml\`. It is a configured assistant that talks over many turns. It is not the stage \`agent:\` field (that picks the Pi or Claude backend for stages).
+
+Minimum: \`id\`, \`name\`, \`instructions\`. Unknown keys are rejected (\`agent.unknown_field\`).
+
+## Fields
+
+- \`id\`: \`^[a-z][a-z0-9_]{0,63}$\`, must match the file name, fixed after create. Made from \`name\` when omitted. \`sessions\`, \`approvals\`, \`new\` are reserved.
+- \`name\` (1–120), \`description\` (≤ 500), \`greeting\` (≤ 500, shown on web chat), \`instructions\` (the system prompt).
+- \`enabled\`: default \`false\`. **A new agent is always created disabled**; enabling is a separate step (\`enable_agent\`) and its own revision. Enabling is refused while the file has issues.
+- \`project_context\`: adds the project's \`AGENTS.md\` (or \`CLAUDE.md\`) to the prompt, first 20,000 characters.
+- \`model\`: \`{ backend: pi|claude, id?, thinking: off|low|medium|high }\`. Only \`pi\` runs; \`claude\` saves with a warning and sessions fail. \`id\` defaults to the project default model.
+- \`execution\`: \`trusted-local\` (default). \`sandbox\` is not installed yet; sessions fail.
+- \`tools\`: \`builtin\` groups (\`read\` = read, grep, find, ls; \`write\` = write, edit; \`shell\` = bash), \`builtin_tools\` (single tools), \`mcp\` (\`{ server: [tool names] }\` or \`["*"]\`), \`skills\`, \`stageflow\` (\`{ groups, tools }\`), \`browser\` (stored, not wired to anything yet).
+- \`approvals\`: \`ask_first\` (tool ids the agent holds: \`edit\`, \`bash\`, \`stageflow.<tool>\`, \`<server>.<tool>\`, \`agent:<id>\`), \`approvers.operators\` (default true), \`timeout_minutes\` (default 30), \`on_timeout\` (\`skip\` default, or \`deny\`). \`approvers.channel_ids\` is reserved and ignored; never set \`operators: false\`.
+- \`sub_agents\` (agent ids, not itself) and \`sub_agent_depth\` (1–5, default 1).
+- \`guardrails.block_patterns\`: regexes checked on the finished reply; a match fails the turn and the reply is not sent. Streaming is held back for agents with patterns.
+- \`evals.groundedness\`, \`observability\` (\`capture: off|metadata|full\`, \`otlp\`).
+- \`channel\`: \`{ connection_id, allow_from }\`. One connection per agent and one agent per connection (\`agent.channel_in_use\`). Empty \`allow_from\` lets nobody in; \`*\` lets anyone in. Entries: email, \`@domain\` (AgentMail), \`+E164\` phone (iMessage), Slack user id \`U…\`/\`W…\`, Telegram \`@username\`.
+- \`memories\`: memory ids every session can use. Must already exist (\`agent.memory_unavailable\` blocks save and enable). Sub-agents do not inherit them.
+- \`web_chat\`: \`{ enabled, slug, rate_limit_per_minute (1–120, default 10), max_message_chars (1–20000, default 4000) }\`. Agents created through console, API, CLI or MCP start with web chat on and a random slug; the link \`/chat/<slug>\` is the credential. It is live only while the agent is enabled.
+- \`schedule\`: \`{ cron, timezone?, message? }\`. The first tick only stores the next run; a missed time fires once.
+- \`limits\`: \`session_minutes\` (default 10), \`max_turns\` (default 40), \`cost_usd\` (default none), \`long_context\` (\`summarize\`/\`truncate\`), \`always_on\` (ignores time and turns; cost counts per 24 hours). Limits are checked when a turn starts, not during it.
+
+## Tools and the gate
+
+Every tool call passes one gate: path guard (no writes to \`agents/*.agent.yaml\` or \`$STAGEFLOW_HOME\` through path arguments), then "is it granted", then "ask first". \`bash\` is **always** ask-first when granted and is not path-confined, so an agent with \`bash\` can still change agent files and Stageflow state (\`agent.shell_not_path_confined\` warning). MCP tools appear as \`<server>_<tool>\` with grant id \`<server>.<tool>\`; Stageflow tools as \`stageflow_<tool>\` with grant id \`stageflow.<tool>\`; sub-agents as \`agent_<id>\`.
+
+Stageflow tool groups: \`discover\`, \`runs.read\`, \`runs.control\`, \`runs.cleanup\`, \`gates.read\`, \`triggers\`, \`agents.read\`, \`agents.manage\`, \`agents.cleanup\`, \`agents.converse\`, \`evals.read\`, \`evals.run\`, \`evals.write\`, \`evals.cleanup\`, \`pipelines.author\`, \`connections\`, \`connections.cleanup\`, \`memories\`, \`memories.cleanup\`. \`gates.decide\` and \`get_started\` are operator-only and cannot be granted (\`agent.stageflow_operator_only\`). Destructive tools have their own \`*.cleanup\` groups. The console turns on ask-first for every non-read tool when you tick a group.
+
+## Asking first
+
+A call to an ask-first tool pauses the turn until a person decides in the Inbox, the session page, \`sf agents\` or MCP. One pending approval per session. An identical call approved once is not asked again in that session. Pending approvals do not survive a Host restart. Channels cannot approve.
+
+## Rules for agents that manage agents
+
+- An agent cannot hand out more than it holds: \`create_agent\`, \`save_agent\`, \`restore_agent_revision\` and \`enable_agent\` called by an agent refuse any tool, MCP tool, MCP wildcard, skill or browser grant the caller does not hold, and refuse a definition that drops an ask-first the caller itself must obey.
+- An agent cannot edit, restore or archive its own definition.
+- An agent cannot decide approvals on its own sessions, and no agent can decide approvals at all.
+
+## Revisions and sessions
+
+Every valid save is a revision with a source. A save based on an old revision is refused (\`agent.conflict\`). Identical saves are no-ops. Restore saves an old revision as the newest. Removing the file or \`archive_agent\` archives the agent (history kept). A session stays on the revision it started with; edits reach new sessions only.
+
+## Reach
+
+Console only by default, plus web chat for agents created through tools. Inbound channels: AgentMail and iMessage (the Host keeps a stream open, no public URL needed), Slack and Telegram (webhook at \`/api/agent-inbound/<connection id>\`, needs an \`inboundSecret\` and a URL the provider can reach). WhatsApp is send-only. On a channel the system sends the reply; an unknown delivery outcome is never resent and fails the turn as \`agent.reply_undelivered\`.
+
+## Tools for agents
+
+\`list_agents\`, \`get_agent\`, \`validate_agent\`, \`create_agent\` (always disabled), \`save_agent\`, \`enable_agent\`, \`disable_agent\`, \`restore_agent_revision\`, \`list_agent_revisions\`, \`diff_agent_revisions\`, \`archive_agent\`, \`agent_chat\`, \`get_agent_session\`, \`list_agent_sessions\`, \`stop_agent_session\`.
+`,
+};

package/dist/guide/knowledge/topics/bestPractices.d.ts

@@ -0,0 +1,2 @@
+import type { GuideKnowledgeTopic } from "../index.js";
+export declare const bestPracticesTopic: GuideKnowledgeTopic;

package/dist/guide/knowledge/topics/bestPractices.js

@@ -0,0 +1,67 @@
+export const bestPracticesTopic = {
+    id: "best_practices",
+    title: "Best practices for building on Stageflow",
+    summary: "Opinionated, product-specific advice: small stages with typed io, real verify checks, gates only where a person decides, run once before adding a trigger, evals before relying on a stage or agent, safe agent grants, cost limits.",
+    body: `# Best practices
+
+Each point follows from how Stageflow behaves.
+
+## Designing pipelines
+
+1. **Start with one or two stages and run them.** Every stage is a fresh model session, so each extra stage costs time and money and adds a handoff. Split a stage only when a step has its own output, needs another model or tools, needs a person's decision, or needs its own check.
+2. **Make the output schema carry the handoff.** The next stage reads the parent's \`payload\` and \`summary\`, not the transcript. Put every fact the next stage needs into required fields of \`io.output.schema\`. Keep \`io.input.schema\` of the child a subset of the parent's output, or the pipeline will not load (\`pipeline.io_incompatible\`).
+3. **Make fields you branch on required.** A route \`if\` can only read required, non-array fields. Add an explicit field such as \`severity\` or \`needs_review: boolean\` rather than asking the model to decide successors.
+4. **Do not use \`on: [failed]\` to build a "failure path".** It does not launch a stage after a failure. Model the decision as a succeeded payload field and branch with \`if\`.
+5. **Name the payload in the prompt.** Tell the stage exactly which fields to put in \`payload\`, what to write as artifacts, and to call \`emit_stage_envelope\` once at the end.
+6. **Follow the Artifact contract for file handoff.** Durable files only via \`write_stage_artifact\`; list those returned paths on emit (emit rejects missing files). Prefer required \`payload\` fields for facts. Under a stage sandbox, the assignment lists each prior file's sandbox path under \`/workspace/grants/<stage>/…\` (that path is the file). Teach the consumer to read those paths or payload, never \`stages/…/artifacts\` host paths and never \`/workspace/work\` as handoff. Do not add after-phase \`verify\` \`type: artifact\` on every bare \`create_stage\` — only when an explicit basename needs hard proof.
+7. **Use the pipeline \`model\` default** so stages follow one setting. When adding stages with tools, pass the model explicitly or the Host default gets written into each stage file.
+8. **Clone chains for "do this for each item".** Gate the empty-list case before the emitter (an empty array fails the emitter), and set \`clone_cap\` to a real maximum.
+
+## Checks
+
+9. **Back up claims with after-phase \`verify\`.** A \`command\` check (tests, a linter, a script that checks the output) or an \`artifact\` with \`path\` and \`nonempty: true\` is evidence. A \`checklist\` is only the agent's word; pair it with a real check. Emit disk-truth already requires listed files to exist; after-phase artifact verify is optional extra proof, not a default on every stage.
+10. **Use \`on_verify_fail: repair\` only for repeatable work** (\`retry_safety: idempotent\`) with a small \`max_attempts\` such as 2 or 3. Use \`mode: manual\` for anything that publishes, pays, sends or deploys.
+11. **Make approvals binding.** \`gate_kinds\` alone lets the agent skip the question. Add \`verify: [{ type: gate, kind: confirm }]\` (or \`artifact_backed\`) so success cannot be emitted without an accepted answer.
+
+## People in the loop
+
+12. **Add a gate only where a person must decide** (approve a plan, confirm a send, choose between options). Every gate stops the run until someone answers, blocks CI unless \`--skip-gates\` (which fails instead), and makes the stage impossible to evaluate (\`EVAL_STAGE_NEEDS_INPUT\`).
+13. **Put side effects after the decision.** Put the send or publish stage after the gated stage, with \`replay_safe: false\` if a feedback loop could replay it.
+
+## Sending messages
+
+14. **One channel per stage.** Two providers means two stages. Write the message content in the stage before the send, so the send stage stays small.
+15. **Test the connection before the run** (\`test_connection\`) and check the recipient (\`validate_connection_target\`). Telegram, iMessage and WhatsApp have extra rules (start the bot first, text the line first, 24-hour window).
+16. **Never resend an unknown outcome.** If a send reports \`CHANNEL_SEND_OUTCOME_UNKNOWN\`, check with the recipient first.
+
+## Triggers
+
+17. **Create a catalog task and run the pipeline by hand once before adding a trigger.** Then add the trigger with that task. Schedules need a catalog task.
+18. **Start triggers disabled if the pipeline sends messages or costs a lot**, then enable after a manual fire works.
+19. **For event triggers in dynamic mode, shape the entry stage's input schema around the event's fields** (GitHub: \`action\`, \`number\`, \`title\`, \`url\`, \`author\`, \`repo\`, \`updatedAt\`; email: \`from\`, \`subject\`, \`date\`, \`text\`).
+
+## Agents
+
+20. **Grant the least.** Start with \`read\` tools and the specific Stageflow tools needed. \`bash\` is always ask-first and not path-confined; avoid it for agents that should stay confined.
+21. **Put risky tools in \`approvals.ask_first\`**, and keep \`approvers.operators: true\` (channel approvers are ignored, so turning operators off leaves nobody able to decide).
+22. **Set limits.** Keep \`max_turns\`, \`session_minutes\` and \`cost_usd\` for public web chat and channel agents. With \`always_on\`, \`cost_usd\` is per day.
+23. **Lock down reach.** Use a specific \`allow_from\` list, not \`*\`. Treat the web chat link as a password; rotate it with \`slug: ""\`. A web chat agent that can read agent sessions can read visitors' messages.
+24. **Enable last.** Agents are created disabled. Validate, try it in the console session page, then enable.
+
+## Memories
+
+25. **Write a clear description** (the session only sees id and description until it calls a tool), use stable card keys (email, ticket id), and keep cards under 64,000 characters and 200 per memory.
+
+## Evals
+
+26. **Add an eval before you rely on a stage or agent, and before changing its prompt, model or tools.** Start with deterministic graders (\`schema\`, \`field\`, \`tool_calls\`, \`conversation_check\`); add \`rubric\` or \`goal_reached\` for what rules cannot say.
+27. **At least 5 cases, \`repeats: 3\`.** Fewer cases give wide intervals; one repeat hides flakiness. Read reliability (pass on every repeat), not only pass rate.
+28. **Baseline first, change one thing per run, compare.** Use a judge model different from the target's model.
+29. **Keep agent evals on \`read_only\`.** Use \`tool_mocks\` for tools that would change things. Use \`real\` only on a throwaway copy of the project.
+30. **Keep \`max_cost_usd\` and \`concurrency\` low** (defaults 2 and 4 for stages, 1 and 2 for agents) until you know the cost per case.
+
+## Cost control in general
+
+Pipelines have no run-level cost cap. Control cost with cheaper models for simple stages, fewer stages, small \`max_attempts\` for repair, \`timeout_ms\` on long stages, agent \`limits.cost_usd\`, and eval \`max_cost_usd\`.
+`,
+};

package/dist/guide/knowledge/topics/connections.d.ts

@@ -0,0 +1,2 @@
+import type { GuideKnowledgeTopic } from "../index.js";
+export declare const connectionsTopic: GuideKnowledgeTopic;