stageflow 0.36.0 → 0.40.0

package/dist/models/catalog.js

@@ -0,0 +1,238 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { ModelRuntime } from "@earendil-works/pi-coding-agent";
+import { getCursorHostStatus } from "../agent/cursorProvider.js";
+import { globalModelFromManifest } from "../config/resolveModel.js";
+import { resolveStageflowContext } from "../project/resolveStageflowContext.js";
+import { resolveCredentialBinding } from "../runtime/credentialBinding.js";
+import { readFactorySettings } from "../runtime/settingsFile.js";
+/** Last resort when nothing is connected and nothing is configured. Pi resolves unknown OpenRouter ids. */
+export const LAST_RESORT_MODEL = "openrouter/nvidia/nemotron-3.5-lightning:free";
+const DEFAULT_TTL_MS = 30_000;
+const DEFAULT_REFRESH_TIMEOUT_MS = 10_000;
+const NOTHING_CONNECTED = {
+    getProviders: () => [],
+    getProviderAuthStatus: () => ({ configured: false }),
+    listCredentials: async () => [],
+    getModels: () => [],
+    refresh: async () => undefined,
+};
+// ModelRuntime.create writes auth.json when it is missing; listing models must not, so no file means nothing connected.
+const defaultCreateRuntime = async (authPath) => !existsSync(authPath)
+    ? NOTHING_CONNECTED
+    : ModelRuntime.create({
+        authPath,
+        // Same layout as the provider routes: models.json and models-store.json sit beside auth.json.
+        modelsPath: path.join(path.dirname(authPath), "models.json"),
+        refreshOnCreate: false,
+    });
+/** Cursor models come from the extension's cached list; they only count once Cursor is connected. */
+function defaultCursorSource(authPath) {
+    return () => {
+        const status = getCursorHostStatus();
+        const connected = status.cursorApiKeyConfigured && status.cursorSdkReady;
+        if (!connected)
+            return { connected, modelIds: [] };
+        const file = path.join(path.dirname(authPath), "cursor-sdk-model-list.json");
+        try {
+            if (!existsSync(file))
+                return { connected, modelIds: [] };
+            const parsed = JSON.parse(readFileSync(file, "utf8"));
+            const ids = (parsed.models ?? [])
+                .map((entry) => (typeof entry.id === "string" ? entry.id : ""))
+                .filter((id) => id.length > 0)
+                .map((id) => `cursor/${id === "default" ? "auto" : id}`);
+            return { connected, modelIds: ids };
+        }
+        catch {
+            return { connected, modelIds: [] };
+        }
+    };
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function isFree(model) {
+    if (model.id.endsWith(":free"))
+        return true;
+    return model.cost !== undefined && model.cost.input === 0 && model.cost.output === 0;
+}
+/**
+ * The one place model lists and the default model come from. Models are those of connected
+ * providers, asked of Pi's registry (live where the provider lists models, built-in otherwise).
+ */
+export class ModelCatalog {
+    options;
+    cached;
+    inflight;
+    lastDefault;
+    constructor(options) {
+        this.options = options;
+    }
+    now() {
+        return (this.options.now ?? Date.now)();
+    }
+    /** Cached list; rebuilt when older than the TTL or when `refresh` forces Pi to refetch provider catalogs. */
+    async snapshot(options = {}) {
+        const ttl = this.options.ttlMs ?? DEFAULT_TTL_MS;
+        if (!options.refresh && this.cached && this.now() - this.cached.builtAt < ttl)
+            return this.cached.snapshot;
+        if (this.inflight && !options.refresh)
+            return this.inflight;
+        const run = this.build(options.refresh === true)
+            .then((snapshot) => {
+            this.cached = { snapshot, builtAt: this.now() };
+            return snapshot;
+        })
+            .catch((error) => {
+            // Keep serving the last good list when a rebuild fails outright.
+            if (this.cached)
+                return this.cached.snapshot;
+            throw error;
+        })
+            .finally(() => {
+            if (this.inflight === run)
+                this.inflight = undefined;
+        });
+        this.inflight = run;
+        return run;
+    }
+    refresh() {
+        return this.snapshot({ refresh: true });
+    }
+    /** True when the id belongs to a connected provider. Custom ids still run; this only drives warnings. */
+    async isKnown(id) {
+        const wanted = id.trim();
+        if (wanted.length === 0)
+            return false;
+        return (await this.snapshot()).models.includes(wanted);
+    }
+    /**
+     * stageflow.yaml `model`, then the Settings workshop model, then the catalog's pick: the last-resort
+     * model when connected, else the first free model, else the first model, else the last resort.
+     */
+    async defaultModel() {
+        const configured = await this.configuredDefault();
+        if (configured)
+            return this.remember(configured);
+        return this.remember(this.pick(await this.snapshot().catch(() => undefined)));
+    }
+    /** Synchronous default for call sites that cannot await: the last resolved default, else the last resort. */
+    peekDefault() {
+        return this.lastDefault ?? this.configuredDefaultSync() ?? this.pick(this.cached?.snapshot);
+    }
+    remember(id) {
+        this.lastDefault = id;
+        lastKnownDefault = id;
+        return id;
+    }
+    async configuredDefault() {
+        const ctx = await resolveStageflowContext(this.options.cwd);
+        const model = globalModelFromManifest(ctx.manifest) ?? readFactorySettings(this.options.cwd).workshopModel;
+        const trimmed = model?.trim();
+        return trimmed ? trimmed : undefined;
+    }
+    configuredDefaultSync() {
+        const trimmed = readFactorySettings(this.options.cwd).workshopModel?.trim();
+        return trimmed ? trimmed : undefined;
+    }
+    pick(snapshot) {
+        const all = snapshot?.providers.flatMap((provider) => provider.models) ?? [];
+        if (all.some((model) => model.id === LAST_RESORT_MODEL))
+            return LAST_RESORT_MODEL;
+        return all.find((model) => model.free && !model.nativeTools)?.id ?? all.find((model) => !model.nativeTools)?.id ?? all[0]?.id ?? LAST_RESORT_MODEL;
+    }
+    async build(force) {
+        const authPath = resolveCredentialBinding(this.options.cwd).authPath;
+        const runtime = await (this.options.createRuntime ?? defaultCreateRuntime)(authPath);
+        const credentials = new Set((await runtime.listCredentials().catch(() => [])).map((entry) => entry.providerId));
+        const connected = runtime
+            .getProviders()
+            .filter((provider) => credentials.has(provider.id) || runtime.getProviderAuthStatus(provider.id).configured);
+        const ids = connected.map((provider) => provider.id);
+        // Restore the cached catalogs first, then ask the providers; a failure leaves the cached or built-in list.
+        const errors = new Map();
+        if (ids.length > 0) {
+            await runtime.refresh({ allowNetwork: false, providers: ids }).catch(() => undefined);
+            const signal = AbortSignal.timeout(this.options.refreshTimeoutMs ?? DEFAULT_REFRESH_TIMEOUT_MS);
+            try {
+                const result = await runtime.refresh({ allowNetwork: true, providers: ids, force, signal });
+                if (result)
+                    for (const [id, error] of result.errors)
+                        errors.set(id, error);
+            }
+            catch (error) {
+                for (const id of ids)
+                    errors.set(id, error instanceof Error ? error : new Error(errorMessage(error)));
+            }
+        }
+        const providers = connected.map((provider) => {
+            const failure = errors.get(provider.id);
+            return {
+                id: provider.id,
+                name: provider.name ?? provider.id,
+                source: failure ? "fallback" : "live",
+                ...(failure ? { error: errorMessage(failure) } : {}),
+                models: runtime
+                    .getModels(provider.id)
+                    .map((model) => ({
+                    id: `${model.provider}/${model.id}`,
+                    provider: model.provider,
+                    name: model.name ?? model.id,
+                    free: isFree(model),
+                    ...(typeof model.contextWindow === "number" ? { contextWindow: model.contextWindow } : {}),
+                    ...(typeof model.reasoning === "boolean" ? { reasoning: model.reasoning } : {}),
+                    nativeTools: false,
+                }))
+                    .sort((a, b) => a.id.localeCompare(b.id)),
+            };
+        });
+        const cursor = (this.options.cursor ?? defaultCursorSource(authPath))();
+        if (cursor.connected && cursor.modelIds.length > 0) {
+            providers.push({
+                id: "cursor",
+                name: "Cursor",
+                source: "live",
+                models: [...new Set(cursor.modelIds)].sort().map((id) => ({
+                    id,
+                    provider: "cursor",
+                    name: id.slice("cursor/".length),
+                    free: false,
+                    nativeTools: true,
+                })),
+            });
+        }
+        providers.sort((a, b) => a.name.localeCompare(b.name));
+        return {
+            providers,
+            models: providers.flatMap((provider) => provider.models.map((model) => model.id)).sort((a, b) => a.localeCompare(b)),
+            fetchedAt: new Date(this.now()).toISOString(),
+        };
+    }
+}
+const catalogs = new Map();
+let lastKnownDefault;
+/**
+ * The most recently resolved default, for call sites that cannot await. Hosts resolve it at boot,
+ * so this is the catalog's answer, not a second source.
+ */
+export function peekDefaultModel() {
+    return lastKnownDefault ?? LAST_RESORT_MODEL;
+}
+/** The Host's catalog for a working directory, shared by every consumer in the process. */
+export function getModelCatalog(cwd) {
+    const key = path.resolve(cwd);
+    let catalog = catalogs.get(key);
+    if (!catalog) {
+        catalog = new ModelCatalog({ cwd: key });
+        catalogs.set(key, catalog);
+    }
+    return catalog;
+}
+export function resetModelCatalogsForTests() {
+    catalogs.clear();
+    lastKnownDefault = undefined;
+}
+export function setModelCatalogForTests(cwd, catalog) {
+    catalogs.set(path.resolve(cwd), catalog);
+}

package/dist/models/response.d.ts

@@ -0,0 +1,29 @@
+import type { RunStore } from "../runstore/port.js";
+import { listModelsMultiProject } from "../config/multiProjectCatalog.js";
+import { type CatalogProvider } from "./catalog.js";
+export type ModelsResponse = {
+    /** Catalog ids plus ids pipelines already use, sorted. Back-compatible with the old flat list. */
+    models: string[];
+    /** Connected providers with their models. */
+    providers: CatalogProvider[];
+    /** The model a new chat, stage or agent starts on. */
+    default: string;
+    fetchedAt: string;
+    /** Ids pipelines use that no connected provider lists. They still run; pickers warn. */
+    unlisted: string[];
+    entries: Array<{
+        id: string;
+        project_root: string;
+    }>;
+    root_errors: Awaited<ReturnType<typeof listModelsMultiProject>>["root_errors"];
+};
+/** The shared answer for GET /api/models, the MCP `list_models` tool and every picker. */
+export declare function buildModelsResponse(options: {
+    store: RunStore;
+    cwd: string;
+    projectRootFilter?: string | undefined;
+    refresh?: boolean;
+}): Promise<{
+    response: ModelsResponse;
+    used: Awaited<ReturnType<typeof listModelsMultiProject>>;
+}>;

package/dist/models/response.js

@@ -0,0 +1,25 @@
+import { listModelsMultiProject } from "../config/multiProjectCatalog.js";
+import { getModelCatalog } from "./catalog.js";
+/** The shared answer for GET /api/models, the MCP `list_models` tool and every picker. */
+export async function buildModelsResponse(options) {
+    const catalog = getModelCatalog(options.cwd);
+    const [snapshot, used, defaultModel] = await Promise.all([
+        catalog.snapshot(options.refresh ? { refresh: true } : {}),
+        listModelsMultiProject({ store: options.store, bootCwd: options.cwd, projectRootFilter: options.projectRootFilter }),
+        catalog.defaultModel(),
+    ]);
+    const listed = new Set(snapshot.models);
+    const unlisted = used.models.filter((id) => !listed.has(id));
+    return {
+        used,
+        response: {
+            models: [...new Set([...snapshot.models, ...used.models])].sort((a, b) => a.localeCompare(b)),
+            providers: snapshot.providers,
+            default: defaultModel,
+            fetchedAt: snapshot.fetchedAt,
+            unlisted,
+            entries: used.items,
+            root_errors: used.root_errors,
+        },
+    };
+}

package/dist/operatorAgent/agentAuthorContext.d.ts

@@ -0,0 +1,17 @@
+import type { OperatorAgentContextAdapter } from "./types.js";
+/**
+ * The unsaved agent definition the author edits: any subset of the v2 agent
+ * schema (src/config/loadAgent.ts). It may be incomplete or invalid while the
+ * operator is still describing the agent; Save validates it.
+ */
+export type AgentAuthorDraft = Record<string, unknown>;
+export type AgentAuthorContext = {
+    kind: "agent_author";
+    projectRoot?: string;
+    draft: AgentAuthorDraft;
+};
+export declare const AGENT_AUTHOR_GREETING = "What should this agent do? Tell me the job, the tools it needs, and anything it must never do without asking.";
+export declare function emptyAgentAuthorDraft(): AgentAuthorDraft;
+export declare function isAgentAuthorContext(value: unknown): value is AgentAuthorContext;
+export declare function readAgentAuthorDraft(context: unknown): AgentAuthorDraft;
+export declare function agentAuthorContextAdapter(): OperatorAgentContextAdapter;

package/dist/operatorAgent/agentAuthorContext.js

@@ -0,0 +1,32 @@
+export const AGENT_AUTHOR_GREETING = "What should this agent do? Tell me the job, the tools it needs, and anything it must never do without asking.";
+export function emptyAgentAuthorDraft() {
+    return {};
+}
+export function isAgentAuthorContext(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const record = value;
+    return (record.kind === "agent_author" &&
+        record.draft !== null &&
+        typeof record.draft === "object" &&
+        !Array.isArray(record.draft));
+}
+export function readAgentAuthorDraft(context) {
+    return isAgentAuthorContext(context) ? structuredClone(context.draft) : emptyAgentAuthorDraft();
+}
+export function agentAuthorContextAdapter() {
+    return {
+        serialize: (context) => context ?? { kind: "agent_author", draft: emptyAgentAuthorDraft() },
+        applyProposal: (context, proposal) => {
+            if (!isAgentAuthorContext(proposal.nextContext))
+                return context;
+            const current = isAgentAuthorContext(context) ? context : undefined;
+            const projectRoot = proposal.nextContext.projectRoot ?? current?.projectRoot;
+            return {
+                kind: "agent_author",
+                ...(projectRoot ? { projectRoot } : {}),
+                draft: structuredClone(proposal.nextContext.draft),
+            };
+        },
+    };
+}

package/dist/operatorAgent/fakeHost.js

@@ -1,4 +1,5 @@
 import { createOperatorAgentHost, invokeProfileTool, } from "./host.js";
+import { createAgentAuthorProfile } from "./profiles/agentAuthor.js";
 import { createWorkshopAuthorProfile, isTaskProposalIntent, proposeStageFromUserMessage, proposeTaskFromUserMessage, WORKSHOP_AUTHOR_PROFILE_ID, } from "./profiles/workshopAuthor.js";
 /**
  * Deterministic Operator Agent Host for Workshop and tests.
@@ -86,6 +87,7 @@ export function createWorkshopOperatorHost(scriptOrOptions) {
             retriever: options.retriever,
             projectRoot: options.projectRoot,
         }),
+        createAgentAuthorProfile(),
     ]);
     return host;
 }

package/dist/operatorAgent/host.js

@@ -1,5 +1,5 @@
-import { readDraftFromContext } from "./draftContext.js";
-import { draftFingerprint, enrichProposal, isMutationConflict, UNDO_MUTATION_CONFLICT_NOTICE, } from "./proposals.js";
+import { profileMayUse } from "../toolkit/profiles.js";
+import { enrichProposal, isMutationConflict, operatorContextFingerprint, UNDO_MUTATION_CONFLICT_NOTICE, } from "./proposals.js";
 import { rejectUnlinkedWorkshopDraftTool } from "../workshop/workshopPin.js";
 function createSession(profile, initialContext, model) {
     let context = initialContext;
@@ -17,7 +17,7 @@ function createSession(profile, initialContext, model) {
             context = profile.contextAdapter.applyProposal(context, enriched);
             const applied = {
                 ...enriched,
-                appliedFingerprint: draftFingerprint(readDraftFromContext(context)),
+                appliedFingerprint: operatorContextFingerprint(context),
             };
             mutations.set(applied.id, applied);
             lastMutationId = applied.id;
@@ -172,6 +172,9 @@ export async function invokeProfileTool(profile, name, args, ctx) {
     if (!tool) {
         return { ok: false, content: null, error: `Unknown tool: ${name}` };
     }
+    if (!profileMayUse(profile.id, name)) {
+        return { ok: false, content: null, error: `${profile.id} is not granted ${name}` };
+    }
     const blocked = rejectUnlinkedWorkshopDraftTool(ctx.getContext(), name);
     if (blocked)
         return blocked;

package/dist/operatorAgent/index.d.ts

@@ -4,6 +4,10 @@ export { createFakeOperatorAgentModel, createWorkshopOperatorHost, type FakeOper
 export { AGENT_PORT_BACKENDS, createPiAgentPort, resolveAgentPort, type AgentPortBackendId, type AgentPort, type AgentPortOptions, } from "./agentPort.js";
 export { createLiveWorkshopOperatorHost, createPiOperatorAgentModel, type LiveWorkshopOperatorHostOptions, type PiOperatorAgentModel, type PiOperatorAgentModelOptions, type PiOperatorOpenSessionInput, type PiOperatorSessionHandle, type WorkshopTranscriptSeedMessage, } from "./piModel.js";
 export { createFailingDocsRetriever, createFilesystemDocsRetriever, createStubDocsRetriever, resolveWorkshopCatalogRoot, type DocsRetrievalHit, type DocsRetrievalResult, type DocsRetriever, } from "./docsRetrieval.js";
+export { agentAuthorContextAdapter, emptyAgentAuthorDraft, isAgentAuthorContext, readAgentAuthorDraft, AGENT_AUTHOR_GREETING, type AgentAuthorContext, type AgentAuthorDraft, } from "./agentAuthorContext.js";
+export { AGENT_AUTHOR_PROFILE_ID, AGENT_AUTHOR_TOOL_NAMES, createAgentAuthorContext, createAgentAuthorProfile, } from "./profiles/agentAuthor.js";
+export { AGENT_AUTHOR_PLAYBOOK } from "./profiles/agentAuthorPlaybook.js";
+export { operatorContextFingerprint } from "./proposals.js";
 export { createWorkshopDraftContext, draftTrackStages, emptyDraftPackage, isWorkshopDraftContext, readDraftFromContext, withDestination, withDraft, withProjectRoot, workshopDraftContextAdapter, WORKSHOP_AUTHOR_GREETING, } from "./draftContext.js";
 export { affectedStageIds, diffDraftPackages, draftFingerprint, enrichProposal, isMutationConflict, STALE_PROPOSAL_NOTICE, UNDO_MUTATION_CONFLICT_NOTICE, } from "./proposals.js";
 export { assertWorkshopAuthorToolsExcludeDiskShell, buildStageAddProposal, buildTaskAddProposal, createWorkshopAuthorProfile, createWorkshopAuthorTools, isTaskProposalIntent, proposeStageFromUserMessage, proposeTaskFromUserMessage, WORKSHOP_AUTHOR_PLAYBOOK, WORKSHOP_AUTHOR_PROFILE_ID, WORKSHOP_AUTHOR_TOOL_NAMES, WORKSHOP_FORBIDDEN_AGENT_TOOLS, workshopAuthorTools, type WorkshopAuthorProfileOptions, } from "./profiles/workshopAuthor.js";

package/dist/operatorAgent/index.js

@@ -3,6 +3,10 @@ export { createFakeOperatorAgentModel, createWorkshopOperatorHost, } from "./fak
 export { AGENT_PORT_BACKENDS, createPiAgentPort, resolveAgentPort, } from "./agentPort.js";
 export { createLiveWorkshopOperatorHost, createPiOperatorAgentModel, } from "./piModel.js";
 export { createFailingDocsRetriever, createFilesystemDocsRetriever, createStubDocsRetriever, resolveWorkshopCatalogRoot, } from "./docsRetrieval.js";
+export { agentAuthorContextAdapter, emptyAgentAuthorDraft, isAgentAuthorContext, readAgentAuthorDraft, AGENT_AUTHOR_GREETING, } from "./agentAuthorContext.js";
+export { AGENT_AUTHOR_PROFILE_ID, AGENT_AUTHOR_TOOL_NAMES, createAgentAuthorContext, createAgentAuthorProfile, } from "./profiles/agentAuthor.js";
+export { AGENT_AUTHOR_PLAYBOOK } from "./profiles/agentAuthorPlaybook.js";
+export { operatorContextFingerprint } from "./proposals.js";
 export { createWorkshopDraftContext, draftTrackStages, emptyDraftPackage, isWorkshopDraftContext, readDraftFromContext, withDestination, withDraft, withProjectRoot, workshopDraftContextAdapter, WORKSHOP_AUTHOR_GREETING, } from "./draftContext.js";
 export { affectedStageIds, diffDraftPackages, draftFingerprint, enrichProposal, isMutationConflict, STALE_PROPOSAL_NOTICE, UNDO_MUTATION_CONFLICT_NOTICE, } from "./proposals.js";
 export { assertWorkshopAuthorToolsExcludeDiskShell, buildStageAddProposal, buildTaskAddProposal, createWorkshopAuthorProfile, createWorkshopAuthorTools, isTaskProposalIntent, proposeStageFromUserMessage, proposeTaskFromUserMessage, WORKSHOP_AUTHOR_PLAYBOOK, WORKSHOP_AUTHOR_PROFILE_ID, WORKSHOP_AUTHOR_TOOL_NAMES, WORKSHOP_FORBIDDEN_AGENT_TOOLS, workshopAuthorTools, } from "./profiles/workshopAuthor.js";

package/dist/operatorAgent/piModel.js

@@ -19,6 +19,7 @@ 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 { createWorkshopAuthorProfile, } from "./profiles/workshopAuthor.js";
 import { readDraftFromContext } from "./draftContext.js";
 export function sessionNeedsExtensionReload(loaded, needed) {
@@ -544,5 +545,6 @@ export function createLiveWorkshopOperatorHost(options) {
             retriever,
             ...(projectRoot !== undefined ? { projectRoot } : {}),
         }),
+        createAgentAuthorProfile(),
     ]);
 }

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

@@ -0,0 +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";
+/** 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 function createAgentAuthorProfile(): OperatorAgentProfile;
+export declare function createAgentAuthorContext(input: {
+    projectRoot: string;
+    draft?: AgentAuthorDraft;
+}): AgentAuthorContext;

package/dist/operatorAgent/profiles/agentAuthor.js

@@ -0,0 +1,192 @@
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { agentAuthorContextAdapter, emptyAgentAuthorDraft, isAgentAuthorContext, readAgentAuthorDraft, } from "../agentAuthorContext.js";
+import { AGENT_ID_PATTERN, parseAgentDefinition } from "../../config/loadAgent.js";
+import { listProjectMcpCatalog } from "../../config/resolveStageMcpServers.js";
+import { AGENT_AUTHOR_PLAYBOOK } from "./agentAuthorPlaybook.js";
+export const AGENT_AUTHOR_PROFILE_ID = "agent-author";
+const MAX_READ_CHARS = 32_000;
+let proposalSeq = 0;
+function nextProposalId() {
+    proposalSeq += 1;
+    return `agent-author-${proposalSeq}`;
+}
+function projectRootOf(ctx) {
+    const context = ctx.getContext();
+    if (!isAgentAuthorContext(context))
+        return undefined;
+    const root = context.projectRoot?.trim();
+    return root || undefined;
+}
+function rejectEscape(root, rel) {
+    if (!rel || path.isAbsolute(rel) || rel.includes("\0"))
+        return "path must be a relative project path";
+    const parts = rel.split(/[/\\]/);
+    if (parts.some((part) => part === ".." || part === ".git" || part === "node_modules")) {
+        return "path is outside the readable project surface";
+    }
+    const target = path.resolve(root, rel);
+    const base = path.resolve(root);
+    if (target !== base && !target.startsWith(base + path.sep))
+        return "path escapes the project";
+    return null;
+}
+function stringArg(args, key) {
+    const value = args[key];
+    return typeof value === "string" ? value : undefined;
+}
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/** Objects merge key by key; arrays and scalars replace; `null` removes the key. */
+export function mergeDraftPatch(draft, patch) {
+    const next = structuredClone(draft);
+    for (const [key, value] of Object.entries(patch)) {
+        if (value === null)
+            delete next[key];
+        else if (isPlainObject(value) && isPlainObject(next[key])) {
+            next[key] = mergeDraftPatch(next[key], value);
+        }
+        else
+            next[key] = structuredClone(value);
+    }
+    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.",
+    async handler(args, ctx) {
+        const root = projectRootOf(ctx);
+        const rel = stringArg(args, "path")?.trim();
+        if (!root)
+            return { ok: false, content: null, error: "project root is not set" };
+        if (!rel)
+            return { ok: false, content: null, error: "path is required" };
+        const rejected = rejectEscape(root, rel);
+        if (rejected)
+            return { ok: false, content: null, error: rejected };
+        try {
+            const bytes = await readFile(path.resolve(root, rel));
+            if (bytes.includes(0))
+                return { ok: false, content: null, error: "file is not text" };
+            const text = bytes.toString("utf8");
+            return {
+                ok: true,
+                content: {
+                    path: rel,
+                    text: text.length > MAX_READ_CHARS ? `${text.slice(0, MAX_READ_CHARS)}\n…truncated` : text,
+                },
+            };
+        }
+        catch {
+            return { ok: false, content: null, error: "file is not readable" };
+        }
+    },
+};
+const listProjectFiles = {
+    name: "list_project_files",
+    description: "List readable project files: AGENTS.md when present, and YAML files under agents/. Does not write.",
+    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 */
+        }
+        try {
+            const entries = await readdir(path.join(root, "agents"), { withFileTypes: true });
+            for (const entry of entries) {
+                if (entry.isFile() && /\.ya?ml$/i.test(entry.name))
+                    files.push(`agents/${entry.name}`);
+            }
+        }
+        catch {
+            /* no agents dir */
+        }
+        return { ok: true, content: { files } };
+    },
+};
+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.",
+    async handler(_args, ctx) {
+        const root = projectRootOf(ctx);
+        if (!root)
+            return { ok: false, content: null, error: "project root is not set" };
+        const catalog = await listProjectMcpCatalog(root);
+        return { ok: true, content: { status: catalog.status, servers: catalog.servers.map((server) => server.name) } };
+    },
+};
+const updateAgentDraft = {
+    name: "update_agent_draft",
+    description: [
+        "Change the unsaved agent draft. Arguments: patch (object, required) and summary (one short sentence).",
+        "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(" "),
+    handler(args, ctx) {
+        const patch = args.patch;
+        if (!isPlainObject(patch))
+            return { ok: false, content: null, error: "patch must be an object" };
+        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);
+            if (id)
+                next.id = id;
+        }
+        const parsed = parseAgentDefinition(next);
+        const summary = stringArg(args, "summary")?.trim() || "Updated the agent draft";
+        const proposal = {
+            id: nextProposalId(),
+            summary,
+            baseContext: currentContext,
+            nextContext: {
+                kind: "agent_author",
+                ...(isAgentAuthorContext(currentContext) && currentContext.projectRoot
+                    ? { projectRoot: currentContext.projectRoot }
+                    : {}),
+                draft: next,
+            },
+        };
+        ctx.emitProposal(proposal);
+        return {
+            ok: true,
+            content: { summary, valid: parsed.ok, issues: parsed.ok ? [] : parsed.issues.map((issue) => `${issue.path || "(draft)"}: ${issue.message}`) },
+        };
+    },
+};
+export const AGENT_AUTHOR_TOOL_NAMES = ["read_project_file", "list_project_files", "list_mcp_servers", "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],
+        contextAdapter: agentAuthorContextAdapter(),
+    };
+}
+export function createAgentAuthorContext(input) {
+    return {
+        kind: "agent_author",
+        projectRoot: input.projectRoot,
+        draft: { ...emptyAgentAuthorDraft(), ...structuredClone(input.draft ?? {}) },
+    };
+}

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

@@ -0,0 +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";