stageflow 0.36.0 → 0.40.0

package/dist/server/projectMcpRoutes.js

@@ -1,5 +1,9 @@
 import { probeProjectMcpServer } from "../agent/piIsolatedMcpProbe.js";
-import { listProjectMcpCatalog } from "../config/resolveStageMcpServers.js";
+import { assertServerName, deleteMcpSecret, isMcpHostStateError, mcpEnvAllowNames, listMcpSecretNames, parsePastedMcpJson, readHostMcpServers, removeHostMcpServer, requiredVars, saveHostMcpServer, setMcpSecret, } from "../config/mcpHostCatalog.js";
+import { maskEntry } from "../config/mcpRedaction.js";
+import { listCachedMcpTools } from "../config/mcpToolCache.js";
+import { completeMcpOAuth, MCP_OAUTH_HTTP_STATUS, mcpOAuthStatus, McpOAuthError, removeMcpOAuth, startMcpOAuth, } from "../config/mcpOAuth.js";
+import { listProjectMcpCatalog, loadMcpCatalog, StageMcpError, } from "../config/resolveStageMcpServers.js";
 function requestAbortSignal(req) {
     const controller = new AbortController();
     const abort = () => {
@@ -14,8 +18,59 @@ function requestAbortSignal(req) {
     req.once("close", abort);
     return controller.signal;
 }
+/** decodeURIComponent that reports malformed percent-encoding instead of throwing. */
+function decodeSegment(raw) {
+    try {
+        return decodeURIComponent(raw ?? "");
+    }
+    catch {
+        return undefined;
+    }
+}
 export async function handleProjectMcpRoutes(req, res, ctx) {
-    const { projectRoot, json } = ctx;
+    try {
+        return await handleRoutes(req, res, ctx);
+    }
+    catch (err) {
+        // A corrupt host-state file is never read as empty and never overwritten.
+        if (isMcpHostStateError(err)) {
+            ctx.json(res, 409, { error: err.message, code: err.code });
+            return true;
+        }
+        throw err;
+    }
+}
+async function handleRoutes(req, res, ctx) {
+    const { projectRoot, json, readJsonBody } = ctx;
+    const hostFailure = (err) => {
+        const code = err?.code;
+        if (code === "invalid_server" || code === "invalid_secret" || code === "reserved_name") {
+            json(res, 400, { error: err.message, code });
+            return true;
+        }
+        return false;
+    };
+    const bodyObject = async () => {
+        try {
+            const body = await readJsonBody(req);
+            if (body !== null && typeof body === "object" && !Array.isArray(body)) {
+                return body;
+            }
+        }
+        catch {
+            /* fall through */
+        }
+        json(res, 400, { error: "Body must be a JSON object", code: "invalid_body" });
+        return undefined;
+    };
+    /** Decoded `:name` segment, or a 400 has been sent and undefined is returned. */
+    const nameParam = (raw) => {
+        const name = decodeSegment(raw);
+        if (name === undefined) {
+            json(res, 400, { error: "Malformed percent-encoding in the name", code: "invalid_name" });
+        }
+        return name;
+    };
     const method = req.method ?? "GET";
     const rawUrl = req.url ?? "/";
     const pathname = new URL(rawUrl, "http://localhost").pathname;
@@ -23,9 +78,192 @@ export async function handleProjectMcpRoutes(req, res, ctx) {
         json(res, 200, await listProjectMcpCatalog(projectRoot));
         return true;
     }
+    if (method === "POST" && pathname === "/api/project-mcp/import") {
+        const body = await bodyObject();
+        if (!body)
+            return true;
+        try {
+            const entries = parsePastedMcpJson(body.json ?? body);
+            const added = [];
+            const secretsStored = [];
+            const errors = [];
+            for (const [name, entry] of Object.entries(entries)) {
+                try {
+                    const saved = saveHostMcpServer(name, entry);
+                    added.push(name);
+                    secretsStored.push(...saved.secretsStored);
+                }
+                catch (err) {
+                    if (err.code === undefined)
+                        throw err;
+                    errors.push({ name, error: err.message });
+                }
+            }
+            json(res, 200, { added, secretsStored, errors });
+        }
+        catch (err) {
+            if (!hostFailure(err))
+                throw err;
+        }
+        return true;
+    }
+    if (pathname === "/api/mcp-secrets" && method === "GET") {
+        const servers = (await loadMcpCatalog(projectRoot, { scope: { kind: "validate" } }).catch((err) => {
+            if (err instanceof StageMcpError && err.code === "host_state_corrupt")
+                throw err;
+            return undefined;
+        }))?.servers ?? {};
+        const usedBy = new Map();
+        for (const [server, entry] of Object.entries(servers)) {
+            for (const v of requiredVars(entry))
+                usedBy.set(v, [...(usedBy.get(v) ?? []), server]);
+        }
+        const stored = new Set(listMcpSecretNames());
+        const allowed = new Set(mcpEnvAllowNames());
+        json(res, 200, {
+            secrets: [...stored].map((name) => ({ name, usedBy: usedBy.get(name) ?? [] })),
+            // Placeholders servers reference; `set` = a stored console secret, or an allow-listed
+            // (STAGEFLOW_MCP_ENV_ALLOW) Host env var that is present. Other Host env is never consulted.
+            needed: [...usedBy].map(([name, by]) => ({
+                name,
+                usedBy: by,
+                set: stored.has(name) || (allowed.has(name) && (process.env[name] ?? "") !== ""),
+            })),
+        });
+        return true;
+    }
+    const secretMatch = pathname.match(/^\/api\/mcp-secrets\/([^/]+)$/);
+    if (secretMatch && (method === "PUT" || method === "DELETE")) {
+        const name = nameParam(secretMatch[1]);
+        if (name === undefined)
+            return true;
+        if (method === "DELETE") {
+            if (!deleteMcpSecret(name))
+                json(res, 404, { error: "Secret not found", code: "not_found" });
+            else
+                json(res, 200, { name });
+            return true;
+        }
+        const body = await bodyObject();
+        if (!body)
+            return true;
+        if (typeof body.value !== "string") {
+            json(res, 400, { error: "value must be a string", code: "invalid_secret" });
+            return true;
+        }
+        try {
+            setMcpSecret(name, body.value);
+            json(res, 200, { name });
+        }
+        catch (err) {
+            if (!hostFailure(err))
+                throw err;
+        }
+        return true;
+    }
+    const toolsMatch = pathname.match(/^\/api\/project-mcp\/([^/]+)\/tools$/);
+    if (toolsMatch && method === "GET") {
+        const name = nameParam(toolsMatch[1]);
+        if (name === undefined)
+            return true;
+        const cached = listCachedMcpTools(name);
+        json(res, 200, cached ? { name, tools: cached.tools, cachedAt: cached.cachedAt } : { name, tools: null });
+        return true;
+    }
+    const oauthMatch = pathname.match(/^\/api\/project-mcp\/([^/]+)\/oauth(\/start|\/complete)?$/);
+    if (oauthMatch) {
+        const name = nameParam(oauthMatch[1]);
+        if (name === undefined)
+            return true;
+        const action = oauthMatch[2];
+        try {
+            assertServerName(name);
+            if (method === "GET" && !action) {
+                json(res, 200, { name, status: await mcpOAuthStatus(name, projectRoot) });
+                return true;
+            }
+            if (method === "DELETE" && !action) {
+                await removeMcpOAuth(name, projectRoot);
+                json(res, 200, { name, status: "not_authenticated" });
+                return true;
+            }
+            if (method === "POST" && action === "/start") {
+                json(res, 200, { name, ...(await startMcpOAuth(projectRoot, name)) });
+                return true;
+            }
+            if (method === "POST" && action === "/complete") {
+                const body = await bodyObject();
+                if (!body)
+                    return true;
+                if (typeof body.input !== "string" || body.input.trim() === "") {
+                    json(res, 400, { error: "Paste the full address from the browser", code: "invalid_body" });
+                    return true;
+                }
+                json(res, 200, { name, status: await completeMcpOAuth(name, body.input, projectRoot) });
+                return true;
+            }
+        }
+        catch (err) {
+            if (err instanceof McpOAuthError) {
+                json(res, MCP_OAUTH_HTTP_STATUS[err.code] ?? 500, { error: err.message, code: err.code });
+                return true;
+            }
+            if (hostFailure(err))
+                return true;
+            if (err instanceof StageMcpError) {
+                json(res, 400, { error: err.message, code: err.code });
+                return true;
+            }
+            throw err;
+        }
+    }
+    const serverMatch = pathname.match(/^\/api\/project-mcp\/([^/]+)$/);
+    if (serverMatch && method === "GET") {
+        const name = nameParam(serverMatch[1]);
+        if (name === undefined)
+            return true;
+        const config = readHostMcpServers()[name];
+        if (config)
+            json(res, 200, { name, origin: "console", config: maskEntry(config) });
+        else
+            json(res, 404, { error: "Only servers saved from the console can be read back", code: "not_found" });
+        return true;
+    }
+    if (serverMatch && method === "PUT") {
+        const name = nameParam(serverMatch[1]);
+        if (name === undefined)
+            return true;
+        const body = await bodyObject();
+        if (!body)
+            return true;
+        try {
+            json(res, 200, saveHostMcpServer(name, body.config));
+        }
+        catch (err) {
+            if (!hostFailure(err))
+                throw err;
+        }
+        return true;
+    }
+    if (serverMatch && method === "DELETE") {
+        const name = nameParam(serverMatch[1]);
+        if (name === undefined)
+            return true;
+        if (removeHostMcpServer(name)) {
+            json(res, 200, { name });
+            return true;
+        }
+        const inProject = (await listProjectMcpCatalog(projectRoot)).servers.some((e) => e.name === name);
+        json(res, inProject ? 409 : 404, inProject
+            ? { error: "Defined in the project .mcp.json; edit that file to remove it", code: "project_defined" }
+            : { error: "Server not found", code: "not_found" });
+        return true;
+    }
     const probeMatch = pathname.match(/^\/api\/project-mcp\/([^/]+)\/probe$/);
     if (method === "POST" && probeMatch) {
-        const name = decodeURIComponent(probeMatch[1] ?? "");
+        const name = nameParam(probeMatch[1]);
+        if (name === undefined)
+            return true;
         const result = await probeProjectMcpServer({
             projectRoot,
             name,

package/dist/toolkit/guard.d.ts

@@ -0,0 +1,27 @@
+import type { AgentDefinition } from "../config/loadAgent.js";
+import type { AgentService } from "../agents/service.js";
+/** The running agent on whose behalf a toolkit tool is called. Absent for operators (MCP, CLI, console). */
+export type ToolCaller = {
+    agentId: string;
+    definition: AgentDefinition;
+};
+/**
+ * Everything `candidate` would be able to do that `caller` cannot: tool grants
+ * (builtin, MCP, Stageflow, sub-agents), skills and the browser. An agent may
+ * only hand out what it holds itself.
+ */
+export declare function grantsBeyond(caller: AgentDefinition, candidate: AgentDefinition): string[];
+/**
+ * Tools the caller must ask a person about that the candidate could run without asking.
+ * Handing out a tool is not enough to check: the copy must not drop the approval too.
+ */
+export declare function approvalsWeakened(caller: AgentDefinition, candidate: AgentDefinition): string[];
+/**
+ * Checks that only apply when an agent (not an operator) calls an agent-management tool:
+ * no editing itself, no granting what it does not hold, no deciding its own approvals.
+ * Returns a refusal message, or null when the call may proceed.
+ */
+export declare function checkAgentCaller(tool: string, args: Record<string, unknown>, caller: ToolCaller, service: AgentService | undefined, projectRoot: string): Promise<{
+    ok: false;
+    message: string;
+} | null>;

package/dist/toolkit/guard.js

@@ -0,0 +1,98 @@
+import { grantedToolIds, parseAgentDefinition } from "../config/loadAgent.js";
+/**
+ * Everything `candidate` would be able to do that `caller` cannot: tool grants
+ * (builtin, MCP, Stageflow, sub-agents), skills and the browser. An agent may
+ * only hand out what it holds itself.
+ */
+export function grantsBeyond(caller, candidate) {
+    const held = grantedToolIds(caller);
+    const beyond = [];
+    for (const id of grantedToolIds(candidate)) {
+        if (held.has(id))
+            continue;
+        const [server, tool] = [id.slice(0, id.indexOf(".")), id.slice(id.indexOf(".") + 1)];
+        // A wildcard on the caller's MCP server covers every tool of that server.
+        if (id.includes(".") && caller.tools.mcp[server]?.includes("*") && candidate.tools.mcp[server]?.includes(tool))
+            continue;
+        beyond.push(id);
+    }
+    for (const server of Object.keys(candidate.tools.mcp)) {
+        if (candidate.tools.mcp[server]?.includes("*") && !caller.tools.mcp[server]?.includes("*"))
+            beyond.push(`${server}.*`);
+    }
+    for (const skill of candidate.tools.skills)
+        if (!caller.tools.skills.includes(skill))
+            beyond.push(`skill ${skill}`);
+    if (candidate.tools.browser && !caller.tools.browser)
+        beyond.push("browser");
+    return [...new Set(beyond)].sort();
+}
+/**
+ * Tools the caller must ask a person about that the candidate could run without asking.
+ * Handing out a tool is not enough to check: the copy must not drop the approval too.
+ */
+export function approvalsWeakened(caller, candidate) {
+    const held = grantedToolIds(candidate);
+    const holds = (id) => {
+        if (held.has(id))
+            return true;
+        const dot = id.indexOf(".");
+        return dot > 0 && candidate.tools.mcp[id.slice(0, dot)]?.includes("*") === true;
+    };
+    return caller.approvals.ask_first.filter((id) => holds(id) && !candidate.approvals.ask_first.includes(id)).sort();
+}
+const refusal = (message) => ({ ok: false, message });
+/**
+ * Checks that only apply when an agent (not an operator) calls an agent-management tool:
+ * no editing itself, no granting what it does not hold, no deciding its own approvals.
+ * Returns a refusal message, or null when the call may proceed.
+ */
+export async function checkAgentCaller(tool, args, caller, service, projectRoot) {
+    if (!service)
+        return null;
+    const self = caller.agentId;
+    const checkDefinition = (candidate, what) => {
+        const beyond = grantsBeyond(caller.definition, candidate);
+        if (beyond.length > 0)
+            return refusal(`${what} would grant tools this agent does not hold: ${beyond.join(", ")}.`);
+        const weakened = approvalsWeakened(caller.definition, candidate);
+        return weakened.length > 0 ? refusal(`${what} would let tools run without asking first that this agent must ask about: ${weakened.join(", ")}.`) : null;
+    };
+    switch (tool) {
+        case "create_agent": {
+            const parsed = parseAgentDefinition(args.definition);
+            return parsed.ok ? checkDefinition(parsed.value, "That agent") : null;
+        }
+        case "save_agent": {
+            if (args.id === self)
+                return refusal("An agent cannot edit its own definition.");
+            const parsed = parseAgentDefinition(args.definition);
+            return parsed.ok ? checkDefinition(parsed.value, "That change") : null;
+        }
+        case "restore_agent_revision": {
+            if (args.id === self)
+                return refusal("An agent cannot edit its own definition.");
+            if (typeof args.id !== "string" || typeof args.revision !== "number")
+                return null;
+            const definition = await service.definitionAt(projectRoot, args.id, args.revision).catch(() => null);
+            return definition ? checkDefinition(definition, "That revision") : null;
+        }
+        case "archive_agent":
+            return args.id === self ? refusal("An agent cannot archive itself.") : null;
+        case "enable_agent": {
+            if (typeof args.id !== "string")
+                return null;
+            const detail = await service.get(projectRoot, args.id).catch(() => null);
+            return detail?.definition ? checkDefinition(detail.definition, "Enabling that agent") : null;
+        }
+        case "approve_agent_action":
+        case "deny_agent_action": {
+            if (typeof args.sessionId !== "string")
+                return null;
+            const session = await service.getSession(projectRoot, args.sessionId).catch(() => null);
+            return session?.session.agentId === self ? refusal("An agent cannot decide approvals on its own sessions.") : null;
+        }
+        default:
+            return null;
+    }
+}

package/dist/toolkit/index.d.ts

@@ -0,0 +1,48 @@
+import type { McpToolDeps } from "../mcp/deps.js";
+import { type ToolCaller } from "./guard.js";
+import { type ToolMeta } from "./meta.js";
+export * from "./meta.js";
+export { grantsBeyond, type ToolCaller } from "./guard.js";
+export type ToolkitResult = {
+    ok: boolean;
+    text: string;
+};
+export type ToolkitTool = ToolMeta & {
+    name: string;
+    /** The id the policy gate and `approvals.ask_first` use. */
+    grantId: string;
+    description: string;
+    /** JSON Schema of the arguments. */
+    parameters: Record<string, unknown>;
+    run(args: Record<string, unknown>, ctx: {
+        signal: AbortSignal;
+        caller?: ToolCaller;
+    }): Promise<ToolkitResult>;
+};
+/** Drop mentions of HTTP routes: a model cannot call them, and the text only confuses it. */
+export declare function plainDescription(text: string): string;
+/**
+ * Every Stageflow tool, derived from the MCP registrations. A tool with no
+ * metadata (or metadata with no tool) is a programming error, caught here
+ * and by the coverage test.
+ */
+export declare function buildToolkit(deps: McpToolDeps): ToolkitTool[];
+export declare function toolkitNames(toolkit: readonly ToolkitTool[]): string[];
+export type ToolkitCatalog = {
+    groups: Array<{
+        id: string;
+        title: string;
+        summary: string;
+        /** True when the whole group is for operators only; the console lists it as locked. */
+        operatorOnly: boolean;
+        tools: Array<{
+            name: string;
+            grantId: string;
+            risk: ToolMeta["risk"];
+            description: string;
+            operatorOnly: boolean;
+        }>;
+    }>;
+};
+/** The groups and tools the console offers for granting. Handlers are never run, so no Host services are needed. */
+export declare function describeToolkit(): ToolkitCatalog;

package/dist/toolkit/index.js

@@ -0,0 +1,82 @@
+import { z } from "zod";
+import { defaultAgentProjectRoot } from "../agents/projectRoot.js";
+import { checkAgentCaller } from "./guard.js";
+import { isOperatorOnlyTool, stageflowGrantId, TOOL_GROUPS, TOOL_META } from "./meta.js";
+import { recordMcpTools } from "./record.js";
+export * from "./meta.js";
+export { grantsBeyond } from "./guard.js";
+function toResult(raw) {
+    const result = (raw ?? {});
+    const text = (result.content ?? []).map((part) => (part.type === "text" ? (part.text ?? "") : `[${part.type}]`)).join("\n");
+    return { ok: result.isError !== true, text };
+}
+/** Drop mentions of HTTP routes: a model cannot call them, and the text only confuses it. */
+export function plainDescription(text) {
+    const withoutParens = text.replace(/\s*\([^()]*\/api\/[^()]*\)/g, "");
+    const sentences = withoutParens.split(/(?<=\.)\s+/).filter((sentence) => !sentence.includes("/api/"));
+    return sentences.join(" ").replace(/\s+([.,:])/g, "$1").trim();
+}
+function jsonSchema(schema) {
+    if (!schema)
+        return { type: "object", properties: {} };
+    const { $schema: _ignored, ...rest } = z.toJSONSchema(schema, { io: "input", unrepresentable: "any" });
+    return rest;
+}
+/**
+ * Every Stageflow tool, derived from the MCP registrations. A tool with no
+ * metadata (or metadata with no tool) is a programming error, caught here
+ * and by the coverage test.
+ */
+export function buildToolkit(deps) {
+    const recorded = recordMcpTools(deps);
+    const missing = recorded.filter((tool) => !(tool.name in TOOL_META)).map((tool) => tool.name);
+    if (missing.length > 0)
+        throw new Error(`Toolkit metadata missing for: ${missing.join(", ")}`);
+    const root = () => defaultAgentProjectRoot(deps.cwd);
+    return recorded.map((tool) => {
+        const meta = TOOL_META[tool.name];
+        return {
+            ...meta,
+            name: tool.name,
+            grantId: stageflowGrantId(tool.name),
+            description: plainDescription(tool.description),
+            parameters: jsonSchema(tool.inputSchema),
+            async run(args, ctx) {
+                const parsed = tool.inputSchema ? tool.inputSchema.safeParse(args) : { success: true, data: args };
+                if (!parsed.success)
+                    return { ok: false, text: JSON.stringify({ error: "Invalid arguments", issues: parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`) }) };
+                if (ctx.caller) {
+                    const refused = await checkAgentCaller(tool.name, parsed.data, ctx.caller, deps.agentService, root());
+                    if (refused)
+                        return { ok: false, text: JSON.stringify({ error: refused.message }) };
+                }
+                const mcpCtx = { mcpReq: { signal: ctx.signal, _meta: undefined, notify: async () => undefined } };
+                const raw = tool.inputSchema ? await tool.handler(parsed.data, mcpCtx) : await tool.handler(mcpCtx);
+                return toResult(raw);
+            },
+        };
+    });
+}
+export function toolkitNames(toolkit) {
+    return toolkit.map((tool) => tool.name);
+}
+let catalogCache;
+/** The groups and tools the console offers for granting. Handlers are never run, so no Host services are needed. */
+export function describeToolkit() {
+    if (catalogCache)
+        return catalogCache;
+    const described = recordMcpTools({ cwd: process.cwd(), store: {}, manager: {} });
+    const byName = new Map(described.map((tool) => [tool.name, tool.description]));
+    catalogCache = {
+        groups: TOOL_GROUPS.map((group) => ({
+            id: group.id,
+            title: group.title,
+            summary: group.summary,
+            operatorOnly: group.operatorOnly === true,
+            tools: Object.entries(TOOL_META)
+                .filter(([, meta]) => meta.group === group.id)
+                .map(([name, meta]) => ({ name, grantId: stageflowGrantId(name), risk: meta.risk, description: plainDescription(byName.get(name) ?? ""), operatorOnly: isOperatorOnlyTool(name) })),
+        })),
+    };
+    return catalogCache;
+}

package/dist/toolkit/meta.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Pure description of Stageflow's own tools: which group each belongs to and
+ * how risky it is. No handlers live here, so config validation and the console
+ * can import it without pulling in the runtime.
+ */
+export type ToolRisk = "read" | "write" | "destructive" | "external";
+export type ToolGroupId = "discover" | "runs.read" | "runs.control" | "runs.cleanup" | "gates.read" | "gates.decide" | "triggers" | "agents.read" | "agents.manage" | "agents.cleanup" | "agents.converse" | "pipelines.author";
+export type ToolGroup = {
+    id: ToolGroupId;
+    title: string;
+    summary: string;
+    /** Never offered to agents: these decide things a person must decide (approvals, gates). */
+    operatorOnly?: true;
+};
+export declare const TOOL_GROUPS: readonly ToolGroup[];
+export type ToolMeta = {
+    group: ToolGroupId;
+    risk: ToolRisk;
+    /** Not offered to agents even though its group is. */
+    operatorOnly?: true;
+};
+export declare const TOOL_META: Readonly<Record<string, ToolMeta>>;
+export type StageflowGrants = {
+    groups: readonly string[];
+    tools: readonly string[];
+};
+/** The grant id the policy gate and `approvals.ask_first` use for a Stageflow tool. */
+export declare const STAGEFLOW_GRANT_PREFIX = "stageflow.";
+export declare const stageflowGrantId: (tool: string) => string;
+export declare function isToolGroupId(value: string): value is ToolGroupId;
+export declare function isOperatorOnlyGroup(group: string): boolean;
+export declare function isOperatorOnlyTool(name: string): boolean;
+/** Tools of a group an agent may hold; operator-only tools are left out. */
+export declare function toolsInGroup(group: string): string[];
+/** Every Stageflow tool name a definition grants, whole groups and single tools together. */
+export declare function grantedStageflowTools(grants: StageflowGrants): string[];