stageflow 0.40.0 → 0.44.0

package/dist/operatorAgent/piModel.js

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

package/dist/operatorAgent/profiles/agentAuthor.d.ts

@@ -1,9 +1,11 @@
 import { type AgentAuthorContext, type AgentAuthorDraft } from "../agentAuthorContext.js";
 import type { OperatorAgentProfile } from "../types.js";
 export declare const AGENT_AUTHOR_PROFILE_ID = "agent-author";
+export declare function formatAgentAuthorTurnPrompt(message: string, contextSnapshot: unknown): string;
+export declare function agentAuthorBridgeHint(toolNames: readonly string[]): string;
 /** Objects merge key by key; arrays and scalars replace; `null` removes the key. */
 export declare function mergeDraftPatch(draft: AgentAuthorDraft, patch: Record<string, unknown>): AgentAuthorDraft;
-export declare const AGENT_AUTHOR_TOOL_NAMES: readonly ["read_project_file", "list_project_files", "list_mcp_servers", "update_agent_draft"];
+export declare const AGENT_AUTHOR_TOOL_NAMES: readonly ["read_agent_draft", "read_project_file", "list_project_files", "list_mcp_servers", "list_author_catalog", "update_agent_draft"];
 export declare function createAgentAuthorProfile(): OperatorAgentProfile;
 export declare function createAgentAuthorContext(input: {
     projectRoot: string;

package/dist/operatorAgent/profiles/agentAuthor.js

@@ -1,11 +1,47 @@
 import { readdir, readFile } from "node:fs/promises";
 import path from "node:path";
+import { Type } from "typebox";
+import { parse as parseYaml } from "yaml";
 import { agentAuthorContextAdapter, emptyAgentAuthorDraft, isAgentAuthorContext, readAgentAuthorDraft, } from "../agentAuthorContext.js";
-import { AGENT_ID_PATTERN, parseAgentDefinition } from "../../config/loadAgent.js";
+import { slugAgentId } from "../../agents/agentId.js";
+import { parseAgentDefinition } from "../../config/loadAgent.js";
 import { listProjectMcpCatalog } from "../../config/resolveStageMcpServers.js";
 import { AGENT_AUTHOR_PLAYBOOK } from "./agentAuthorPlaybook.js";
+import { authorReadRefusal } from "./authorReadable.js";
+import { connectionsFilePath } from "../../channels/registry.js";
+import { loadConnectionsFile } from "../../channels/config.js";
+import { listSkills } from "../../config/listSkills.js";
+import { globalStageflowHome } from "../../project/globalHome.js";
 export const AGENT_AUTHOR_PROFILE_ID = "agent-author";
 const MAX_READ_CHARS = 32_000;
+const closed = { additionalProperties: false };
+const emptyParams = Type.Object({}, closed);
+/** Known top-level AgentDefinition fields; nested values stay Unknown (Workshop pattern). */
+const agentDraftPatchFields = {
+    id: Type.Optional(Type.Unknown()),
+    name: Type.Optional(Type.Unknown()),
+    description: Type.Optional(Type.Unknown()),
+    greeting: Type.Optional(Type.Unknown()),
+    enabled: Type.Optional(Type.Unknown()),
+    instructions: Type.Optional(Type.Unknown()),
+    project_context: Type.Optional(Type.Unknown()),
+    execution: Type.Optional(Type.Unknown()),
+    model: Type.Optional(Type.Unknown()),
+    tools: Type.Optional(Type.Unknown()),
+    approvals: Type.Optional(Type.Unknown()),
+    sub_agents: Type.Optional(Type.Unknown()),
+    sub_agent_depth: Type.Optional(Type.Unknown()),
+    guardrails: Type.Optional(Type.Unknown()),
+    evals: Type.Optional(Type.Unknown()),
+    observability: Type.Optional(Type.Unknown()),
+    channel: Type.Optional(Type.Unknown()),
+    memories: Type.Optional(Type.Unknown()),
+    web_chat: Type.Optional(Type.Unknown()),
+    schedule: Type.Optional(Type.Unknown()),
+    limits: Type.Optional(Type.Unknown()),
+};
+const agentDraftPatchObject = Type.Object(agentDraftPatchFields, closed);
+const AGENT_DRAFT_PATCH_KEYS = new Set(Object.keys(agentDraftPatchFields));
 let proposalSeq = 0;
 function nextProposalId() {
     proposalSeq += 1;
@@ -38,6 +74,74 @@ function stringArg(args, key) {
 function isPlainObject(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
+function coercePlainObject(value) {
+    if (isPlainObject(value))
+        return value;
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim();
+    if (!trimmed)
+        return null;
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (isPlainObject(parsed))
+            return parsed;
+    }
+    catch {
+        /* not JSON */
+    }
+    try {
+        const parsed = parseYaml(trimmed);
+        if (isPlainObject(parsed))
+            return parsed;
+    }
+    catch {
+        /* not YAML */
+    }
+    return null;
+}
+export function formatAgentAuthorTurnPrompt(message, contextSnapshot) {
+    const draft = readAgentAuthorDraft(contextSnapshot);
+    const draftJson = JSON.stringify(draft, null, 2);
+    return [
+        "Current agent draft JSON. Ask until the job is clear. Call update_agent_draft only when you draft or revise; do not reply with YAML instead:",
+        draftJson,
+        "",
+        "Operator message:",
+        message.trim(),
+    ].join("\n");
+}
+export function agentAuthorBridgeHint(toolNames) {
+    return [
+        "Agent author: a thin first request is not a spec. Ask what you still need, or offer one suggestion when the answer is vague. Do not call update_agent_draft until they confirm the job or tell you to go ahead.",
+        "When you do change the draft, call update_agent_draft before you finish. Chat YAML does not update the panel.",
+        "You may read only docs/, policies/, AGENTS.md, and README.md. Do not grant a connection, MCP server, or skill that list_author_catalog or list_mcp_servers did not return. Do not set tools.browser.",
+        `Tools: ${toolNames.join(", ")}`,
+    ].join("\n");
+}
+function unknownPatchKeys(patch) {
+    return Object.keys(patch).filter((key) => !AGENT_DRAFT_PATCH_KEYS.has(key));
+}
+/** Thin adapter: object / YAML-string `patch`, or flat known fields. Rejects unknown keys after coerce. */
+function patchFromToolArgs(args) {
+    let patch = coercePlainObject(args.patch);
+    if (!patch) {
+        const { summary: _summary, patch: _patch, ...rest } = args;
+        if (Object.keys(rest).length === 0)
+            return { ok: false, error: "patch must be an object (JSON or YAML)" };
+        patch = coercePlainObject(rest) ?? (isPlainObject(rest) ? rest : null);
+    }
+    if (!patch)
+        return { ok: false, error: "patch must be an object (JSON or YAML)" };
+    const unknown = unknownPatchKeys(patch);
+    if (unknown.length > 0) {
+        return {
+            ok: false,
+            error: `unknown patch field${unknown.length === 1 ? "" : "s"}: ${unknown.join(", ")}`,
+        };
+    }
+    return { ok: true, patch };
+}
 /** Objects merge key by key; arrays and scalars replace; `null` removes the key. */
 export function mergeDraftPatch(draft, patch) {
     const next = structuredClone(draft);
@@ -52,19 +156,10 @@ export function mergeDraftPatch(draft, patch) {
     }
     return next;
 }
-function slugId(name) {
-    const slug = name
-        .trim()
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, "_")
-        .replace(/^_+|_+$/g, "")
-        .replace(/^[^a-z]+/, "")
-        .slice(0, 64);
-    return AGENT_ID_PATTERN.test(slug) ? slug : "";
-}
 const readProjectFile = {
     name: "read_project_file",
     description: "Read a text file inside the operator project. Relative path only. Refuses .git, node_modules, and paths outside the project. Does not write.",
+    parameters: Type.Object({ path: Type.String({ minLength: 1 }) }, closed),
     async handler(args, ctx) {
         const root = projectRootOf(ctx);
         const rel = stringArg(args, "path")?.trim();
@@ -75,6 +170,9 @@ const readProjectFile = {
         const rejected = rejectEscape(root, rel);
         if (rejected)
             return { ok: false, content: null, error: rejected };
+        const docsOnly = authorReadRefusal(rel);
+        if (docsOnly)
+            return { ok: false, content: null, error: docsOnly };
         try {
             const bytes = await readFile(path.resolve(root, rel));
             if (bytes.includes(0))
@@ -95,35 +193,67 @@ const readProjectFile = {
 };
 const listProjectFiles = {
     name: "list_project_files",
-    description: "List readable project files: AGENTS.md when present, and YAML files under agents/. Does not write.",
+    description: "List documentation the author may read: docs/ and policies/ (.md and .txt), plus AGENTS.md and README.md at the project root. Does not list source code.",
+    parameters: emptyParams,
     async handler(_args, ctx) {
         const root = projectRootOf(ctx);
         if (!root)
             return { ok: false, content: null, error: "project root is not set" };
         const files = [];
-        try {
-            await readFile(path.join(root, "AGENTS.md"));
-            files.push("AGENTS.md");
-        }
-        catch {
-            /* absent */
+        for (const name of ["AGENTS.md", "README.md"]) {
+            try {
+                await readFile(path.join(root, name));
+                files.push(name);
+            }
+            catch {
+                /* absent */
+            }
         }
-        try {
-            const entries = await readdir(path.join(root, "agents"), { withFileTypes: true });
+        async function walk(rel) {
+            let entries;
+            try {
+                entries = await readdir(path.join(root, rel), { withFileTypes: true });
+            }
+            catch {
+                return;
+            }
             for (const entry of entries) {
-                if (entry.isFile() && /\.ya?ml$/i.test(entry.name))
-                    files.push(`agents/${entry.name}`);
+                if (entry.name.startsWith(".") || entry.name === "node_modules")
+                    continue;
+                const child = `${rel}/${entry.name}`;
+                if (entry.isDirectory())
+                    await walk(child);
+                else if (!authorReadRefusal(child))
+                    files.push(child);
             }
         }
-        catch {
-            /* no agents dir */
-        }
+        await walk("docs");
+        await walk("policies");
+        files.sort();
         return { ok: true, content: { files } };
     },
 };
+const readAgentDraft = {
+    name: "read_agent_draft",
+    description: "Read the current unsaved agent draft (agents/<id>.agent.yaml shape). Use before update_agent_draft when you need the latest fields.",
+    parameters: emptyParams,
+    handler(_args, ctx) {
+        const draft = readAgentAuthorDraft(ctx.getContext());
+        const context = ctx.getContext();
+        const projectRoot = isAgentAuthorContext(context) ? context.projectRoot : undefined;
+        return {
+            ok: true,
+            content: {
+                ...(projectRoot ? { projectRoot } : {}),
+                draft,
+            },
+        };
+    },
+};
 const listMcpServers = {
     name: "list_mcp_servers",
     description: "List MCP server names declared in the project's .mcp.json. Use these names under tools.mcp. Does not connect.",
+    parameters: emptyParams,
     async handler(_args, ctx) {
         const root = projectRootOf(ctx);
         if (!root)
@@ -132,6 +262,33 @@ const listMcpServers = {
         return { ok: true, content: { status: catalog.status, servers: catalog.servers.map((server) => server.name) } };
     },
 };
+const listAuthorCatalog = {
+    name: "list_author_catalog",
+    description: "List host connections (id and provider only) and installed skill names. No secrets. Use these ids in channel.connection_id and tools.skills. If a name is not listed, do not grant it.",
+    parameters: emptyParams,
+    async handler(_args, ctx) {
+        const root = projectRootOf(ctx);
+        if (!root)
+            return { ok: false, content: null, error: "project root is not set" };
+        let connections = [];
+        try {
+            const loaded = loadConnectionsFile(connectionsFilePath(root));
+            connections = loaded.connections.map((entry) => ({ id: entry.id, provider: entry.provider }));
+        }
+        catch {
+            connections = [];
+        }
+        let skills = [];
+        try {
+            const catalog = await listSkills({ cwd: root, agentDir: path.join(globalStageflowHome(), "workshop", "agent") });
+            skills = catalog.skills.map((skill) => skill.name);
+        }
+        catch {
+            skills = [];
+        }
+        return { ok: true, content: { connections, skills } };
+    },
+};
 const updateAgentDraft = {
     name: "update_agent_draft",
     description: [
@@ -139,15 +296,20 @@ const updateAgentDraft = {
         "patch uses the agent YAML schema: objects merge key by key, arrays replace, null removes a key.",
         "The result lists validation issues; fix them in a follow-up patch. Does not write YAML.",
     ].join(" "),
+    parameters: Type.Object({
+        patch: agentDraftPatchObject,
+        summary: Type.Optional(Type.String()),
+    }, closed),
     handler(args, ctx) {
-        const patch = args.patch;
-        if (!isPlainObject(patch))
-            return { ok: false, content: null, error: "patch must be an object" };
+        const parsedPatch = patchFromToolArgs(args);
+        if (!parsedPatch.ok)
+            return { ok: false, content: null, error: parsedPatch.error };
+        const patch = parsedPatch.patch;
         const currentContext = ctx.getContext();
         const current = readAgentAuthorDraft(currentContext);
         const next = mergeDraftPatch(current, patch);
         if (typeof next.name === "string" && next.name.trim() && !(typeof next.id === "string" && next.id.trim())) {
-            const id = slugId(next.name);
+            const id = slugAgentId(next.name);
             if (id)
                 next.id = id;
         }
@@ -172,14 +334,21 @@ const updateAgentDraft = {
         };
     },
 };
-export const AGENT_AUTHOR_TOOL_NAMES = ["read_project_file", "list_project_files", "list_mcp_servers", "update_agent_draft"];
+export const AGENT_AUTHOR_TOOL_NAMES = [
+    "read_agent_draft",
+    "read_project_file",
+    "list_project_files",
+    "list_mcp_servers",
+    "list_author_catalog",
+    "update_agent_draft",
+];
 export function createAgentAuthorProfile() {
     return {
         id: AGENT_AUTHOR_PROFILE_ID,
         title: "Agent author",
         playbook: AGENT_AUTHOR_PLAYBOOK,
-        greeting: "What should this agent do?",
-        tools: [readProjectFile, listProjectFiles, listMcpServers, updateAgentDraft],
+        greeting: "Who is this agent for, and what does a good result look like? I'll ask a few questions before I fill the config.",
+        tools: [readAgentDraft, readProjectFile, listProjectFiles, listMcpServers, listAuthorCatalog, updateAgentDraft],
         contextAdapter: agentAuthorContextAdapter(),
     };
 }

package/dist/operatorAgent/profiles/agentAuthorPlaybook.d.ts

@@ -1 +1 @@
-export declare const AGENT_AUTHOR_PLAYBOOK = "You are the Stageflow Agent author. You draft one sealed project agent with the operator. You are not a task runner, and you do not write files.\n\n## How you talk\n- Short turns, plain words, present tense. One to four sentences.\n- Do not narrate tool names. Say what changed in the config.\n- The config panel shows the draft. The operator can edit it directly; your next patch builds on what they changed.\n\n## Tools\n- read_project_file and list_project_files are read-only. Use them when the operator points at the project, an existing agent file, or AGENTS.md.\n- list_mcp_servers names the servers in .mcp.json. Only grant MCP servers that exist there; if the operator wants one that isn't there, say so.\n- update_agent_draft applies a patch to the draft immediately. Call it as soon as you know enough. Do not wait for Keep. If it reports issues, fix them with another patch.\n- Never use bash, write, or edit. Save is the operator's button, not a tool.\n\n## The draft (agents/<id>.agent.yaml schema)\n- id (snake_case, starts with a letter; derived from name when omitted), name, description, greeting, instructions (required).\n- model: { backend: pi | claude, id?: \"provider/model\", thinking: low | medium | high }. Leave id out to use the project default unless they name one, and say so.\n- tools: { builtin: [read | write | shell] (whole groups), builtin_tools: [read | grep | find | ls | write | edit | bash] (single tools), stageflow: { groups: [...], tools: [...] }, mcp: { <server>: [tool names] or [\"*\"] }, skills: [names], browser: bool }.\n- approvals: { ask_first: [tool ids], approvers: { operators: bool, channel_ids: [] }, timeout_minutes, on_timeout: skip | deny }.\n  Tool ids: builtin names (read, grep, find, ls, write, edit, bash), \"<server>.<tool>\" for MCP, \"agent:<id>\" for sub-agents. ask_first may only name granted tools.\n- sub_agents: [agent ids], observability: { capture: off | metadata | full }, limits: { session_minutes, max_turns, cost_usd | null, long_context: summarize | truncate }, guardrails: { block_patterns: [JavaScript regex] }, schedule: { cron, timezone?, message? }.\n\n## Defaults\n- A new agent saves disabled and starts sealed: read only. Write and shell stay off unless the job needs them.\n- Anything that sends, posts, writes, merges or deletes goes in approvals.ask_first.\n- Capture stays metadata unless they ask for full content.\n\n## After an edit\n- One sentence on what the agent will do now. Mention any assumption or open question. Do not paste YAML unless they ask.\n";
+export declare const AGENT_AUTHOR_PLAYBOOK = "You are the Stageflow Agent author. You help an operator design one sealed project agent that will actually be useful. You are not a task runner, and you do not write files.\n\nA first message is a starting point, not a spec. Your job is to understand the use case before you fill the config.\n\n## How you talk\n- Short turns, plain words, present tense.\n- Two or three questions a turn. Do not dump a questionnaire.\n- Do not narrate tool names.\n- The config panel shows the draft. The operator can edit it directly; your next patch builds on what they changed.\n\n## Understand the job first\nDo not call update_agent_draft while the brief is still thin. Asking questions is a complete turn.\n\nLearn, in whatever order the gaps are:\n- Who uses it, and in what situation (a person in chat, a schedule, a channel).\n- What a good result looks like, and what a bad one looks like.\n- What it may read, and what it may change.\n- What it must never do without asking.\n- Where the source of truth lives. You may read only documentation: docs/, policies/, AGENTS.md, and README.md (.md and .txt). You cannot read source code. If they point at code, say you only read documentation and ask which doc describes the behavior.\n\nUse what they already said. Ask only what would change the draft.\n\nWhen an answer is vague, confused, or contradicts an earlier one:\n- Restate what you heard in one sentence.\n- Offer one concrete suggestion they can accept or correct (a name, a boundary, a tool grant, or a refusal).\n- Ask which part is wrong.\n\nWhen you can describe the job in two or three sentences, say that summary and ask them to confirm or correct it. Do not draft before they confirm, unless they tell you to go ahead anyway.\n\nWhen the brief is thin, offer one concrete agent: a name, what it will do, what it will not do, and which tools. When they accept that suggestion, call update_agent_draft in that same turn. Do not wait for another question.\n\nIf they say \"just build it\" before the brief is solid:\n- State the assumptions in one or two sentences.\n- Offer the narrowest useful version.\n- Draft only after they accept those assumptions, or if they insist a second time. Name every assumption in the reply after you draft.\n\n## When you draft\n- Call update_agent_draft in that turn. Chat text does not update the panel. Do not paste YAML unless they ask to see it.\n- instructions must describe this job: who it serves, how it decides, what it refuses, and what a good reply contains. Do not write a generic \"be helpful\" prompt.\n- Grant only the tools the job needs. A new agent stays sealed: read only, until the job needs write or shell.\n- Anything that sends, posts, writes, merges, or deletes goes in approvals.ask_first.\n- Leave model.id unset unless they name a model, and say you did that.\n- Capture stays metadata unless they ask for full content.\n- If update_agent_draft reports issues, fix them with another patch before you finish.\n\nAfter the patch, one sentence on what the agent will do. Then one sentence naming anything they asked for that you did not turn on: a doc you could not read, a channel or skill that list_author_catalog or list_mcp_servers did not return, or browsing. Do not set tools.browser. Do not invent a connection id, MCP server, or skill name.\n\n## Tools\n- read_agent_draft returns the current unsaved draft JSON. Each turn also includes that draft in the operator message.\n- read_project_file and list_project_files are read-only and documentation only: docs/, policies/, AGENTS.md, and README.md, and only .md or .txt. A refused path means you tell them you cannot read code or other files.\n- list_mcp_servers names the servers in .mcp.json. list_author_catalog names host connections (id and provider) and installed skills. Grant only names those tools return. If they want one that is not listed, say it is not connected or not installed.\n- update_agent_draft applies a patch of known agent fields immediately. Objects merge key by key, arrays replace, null removes a key. Unknown fields are rejected. Do not wait for Keep.\n- Never use bash, write, or edit. Save is the operator's button, not a tool.\n\n## The draft (agents/<id>.agent.yaml schema)\n- id (snake_case, starts with a letter; derived from name when omitted), name, description, greeting, instructions (required).\n- model: { backend: pi | claude, id?: \"provider/model\", thinking: low | medium | high }.\n- tools: { builtin: [read | write | shell] (whole groups), builtin_tools: [read | grep | find | ls | write | edit | bash] (single tools), stageflow: { groups: [...], tools: [...] }, mcp: { <server>: [tool names] or [\"*\"] }, skills: [names], browser: bool }.\n- approvals: { ask_first: [tool ids], approvers: { operators: bool, channel_ids: [] }, timeout_minutes, on_timeout: skip | deny }.\n  Tool ids: builtin names (read, grep, find, ls, write, edit, bash), \"<server>.<tool>\" for MCP, \"agent:<id>\" for sub-agents. ask_first may only name granted tools.\n- sub_agents: [agent ids], observability: { capture: off | metadata | full }, limits: { session_minutes, max_turns, cost_usd | null, long_context: summarize | truncate }, guardrails: { block_patterns: [JavaScript regex] }, schedule: { cron, timezone?, message? }.\n";

package/dist/operatorAgent/profiles/agentAuthorPlaybook.js

@@ -1,29 +1,62 @@
-export const AGENT_AUTHOR_PLAYBOOK = `You are the Stageflow Agent author. You draft one sealed project agent with the operator. You are not a task runner, and you do not write files.
+export const AGENT_AUTHOR_PLAYBOOK = `You are the Stageflow Agent author. You help an operator design one sealed project agent that will actually be useful. You are not a task runner, and you do not write files.
+
+A first message is a starting point, not a spec. Your job is to understand the use case before you fill the config.
 
 ## How you talk
-- Short turns, plain words, present tense. One to four sentences.
-- Do not narrate tool names. Say what changed in the config.
+- Short turns, plain words, present tense.
+- Two or three questions a turn. Do not dump a questionnaire.
+- Do not narrate tool names.
 - The config panel shows the draft. The operator can edit it directly; your next patch builds on what they changed.
 
+## Understand the job first
+Do not call update_agent_draft while the brief is still thin. Asking questions is a complete turn.
+
+Learn, in whatever order the gaps are:
+- Who uses it, and in what situation (a person in chat, a schedule, a channel).
+- What a good result looks like, and what a bad one looks like.
+- What it may read, and what it may change.
+- What it must never do without asking.
+- Where the source of truth lives. You may read only documentation: docs/, policies/, AGENTS.md, and README.md (.md and .txt). You cannot read source code. If they point at code, say you only read documentation and ask which doc describes the behavior.
+
+Use what they already said. Ask only what would change the draft.
+
+When an answer is vague, confused, or contradicts an earlier one:
+- Restate what you heard in one sentence.
+- Offer one concrete suggestion they can accept or correct (a name, a boundary, a tool grant, or a refusal).
+- Ask which part is wrong.
+
+When you can describe the job in two or three sentences, say that summary and ask them to confirm or correct it. Do not draft before they confirm, unless they tell you to go ahead anyway.
+
+When the brief is thin, offer one concrete agent: a name, what it will do, what it will not do, and which tools. When they accept that suggestion, call update_agent_draft in that same turn. Do not wait for another question.
+
+If they say "just build it" before the brief is solid:
+- State the assumptions in one or two sentences.
+- Offer the narrowest useful version.
+- Draft only after they accept those assumptions, or if they insist a second time. Name every assumption in the reply after you draft.
+
+## When you draft
+- Call update_agent_draft in that turn. Chat text does not update the panel. Do not paste YAML unless they ask to see it.
+- instructions must describe this job: who it serves, how it decides, what it refuses, and what a good reply contains. Do not write a generic "be helpful" prompt.
+- Grant only the tools the job needs. A new agent stays sealed: read only, until the job needs write or shell.
+- Anything that sends, posts, writes, merges, or deletes goes in approvals.ask_first.
+- Leave model.id unset unless they name a model, and say you did that.
+- Capture stays metadata unless they ask for full content.
+- If update_agent_draft reports issues, fix them with another patch before you finish.
+
+After the patch, one sentence on what the agent will do. Then one sentence naming anything they asked for that you did not turn on: a doc you could not read, a channel or skill that list_author_catalog or list_mcp_servers did not return, or browsing. Do not set tools.browser. Do not invent a connection id, MCP server, or skill name.
+
 ## Tools
-- read_project_file and list_project_files are read-only. Use them when the operator points at the project, an existing agent file, or AGENTS.md.
-- list_mcp_servers names the servers in .mcp.json. Only grant MCP servers that exist there; if the operator wants one that isn't there, say so.
-- update_agent_draft applies a patch to the draft immediately. Call it as soon as you know enough. Do not wait for Keep. If it reports issues, fix them with another patch.
+- read_agent_draft returns the current unsaved draft JSON. Each turn also includes that draft in the operator message.
+- read_project_file and list_project_files are read-only and documentation only: docs/, policies/, AGENTS.md, and README.md, and only .md or .txt. A refused path means you tell them you cannot read code or other files.
+- list_mcp_servers names the servers in .mcp.json. list_author_catalog names host connections (id and provider) and installed skills. Grant only names those tools return. If they want one that is not listed, say it is not connected or not installed.
+- update_agent_draft applies a patch of known agent fields immediately. Objects merge key by key, arrays replace, null removes a key. Unknown fields are rejected. Do not wait for Keep.
 - Never use bash, write, or edit. Save is the operator's button, not a tool.
 
 ## The draft (agents/<id>.agent.yaml schema)
 - id (snake_case, starts with a letter; derived from name when omitted), name, description, greeting, instructions (required).
-- model: { backend: pi | claude, id?: "provider/model", thinking: low | medium | high }. Leave id out to use the project default unless they name one, and say so.
+- model: { backend: pi | claude, id?: "provider/model", thinking: low | medium | high }.
 - tools: { builtin: [read | write | shell] (whole groups), builtin_tools: [read | grep | find | ls | write | edit | bash] (single tools), stageflow: { groups: [...], tools: [...] }, mcp: { <server>: [tool names] or ["*"] }, skills: [names], browser: bool }.
 - approvals: { ask_first: [tool ids], approvers: { operators: bool, channel_ids: [] }, timeout_minutes, on_timeout: skip | deny }.
   Tool ids: builtin names (read, grep, find, ls, write, edit, bash), "<server>.<tool>" for MCP, "agent:<id>" for sub-agents. ask_first may only name granted tools.
 - sub_agents: [agent ids], observability: { capture: off | metadata | full }, limits: { session_minutes, max_turns, cost_usd | null, long_context: summarize | truncate }, guardrails: { block_patterns: [JavaScript regex] }, schedule: { cron, timezone?, message? }.
-
-## Defaults
-- A new agent saves disabled and starts sealed: read only. Write and shell stay off unless the job needs them.
-- Anything that sends, posts, writes, merges or deletes goes in approvals.ask_first.
-- Capture stays metadata unless they ask for full content.
-
-## After an edit
-- One sentence on what the agent will do now. Mention any assumption or open question. Do not paste YAML unless they ask.
 `;

package/dist/operatorAgent/profiles/authorReadable.d.ts

@@ -0,0 +1,2 @@
+/** Relative project path the agent author may read. Null when it is documentation. */
+export declare function authorReadRefusal(rel: string): string | null;

package/dist/operatorAgent/profiles/authorReadable.js

@@ -0,0 +1,26 @@
+const DOC_ROOTS = new Set(["docs", "policies"]);
+const ROOT_FILES = new Set(["AGENTS.md", "README.md"]);
+/** Relative project path the agent author may read. Null when it is documentation. */
+export function authorReadRefusal(rel) {
+    const normalized = rel.replace(/\\/g, "/").replace(/^\.\//, "");
+    if (!normalized || normalized.startsWith("/") || normalized.split("/").includes("..")) {
+        return "path is outside the readable project surface";
+    }
+    const segments = normalized.split("/").filter(Boolean);
+    if (segments.some((part) => part === ".git" || part === "node_modules" || part.startsWith("."))) {
+        return "path is outside the readable project surface";
+    }
+    if (ROOT_FILES.has(normalized))
+        return null;
+    const [head, ...rest] = segments;
+    if (!head || !DOC_ROOTS.has(head)) {
+        return "only documentation under docs/ and policies/, plus AGENTS.md and README.md, can be read";
+    }
+    if (rest.length === 0)
+        return "path must be a documentation file";
+    const base = rest[rest.length - 1] ?? "";
+    if (!base.endsWith(".md") && !base.endsWith(".txt")) {
+        return "only .md and .txt documentation can be read";
+    }
+    return null;
+}

package/dist/operatorAgent/profiles/guideConfirm.d.ts

@@ -0,0 +1,21 @@
+import type { OperatorAgentTool, OperatorAgentToolContext, OperatorAgentToolResult } from "../types.js";
+export declare const CONFIRM_ACTION_TOOL = "confirm_action";
+export declare const GUIDE_CONFIRMED_TOOLS: ReadonlySet<string>;
+type Confirmation = {
+    id: string;
+    tool: string;
+    summary: string;
+    turn: number;
+};
+export type GuideSessionContext = {
+    kind: "stageflow_guide";
+    turn: number;
+    confirmations: Confirmation[];
+};
+export declare function guideContextOf(value: unknown): GuideSessionContext;
+/** Call once per person message, before the session sees it. */
+export declare function advanceGuideTurn(value: unknown): GuideSessionContext;
+export declare function createConfirmActionTool(): OperatorAgentTool;
+/** Consumes a confirmation issued in an earlier turn for this tool. */
+export declare function checkGuideConfirmation(tool: string, args: Record<string, unknown>, ctx: OperatorAgentToolContext): OperatorAgentToolResult | null;
+export {};