stageflow 0.36.0 → 0.40.0

package/dist/toolkit/meta.js

@@ -0,0 +1,117 @@
+/**
+ * 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 const TOOL_GROUPS = [
+    { id: "discover", title: "Discover the project", summary: "List pipelines, tasks, skills, models and providers; validate and preflight." },
+    { id: "runs.read", title: "Watch runs", summary: "Read runs, stage events, logs, envelopes, artifacts and checkout diffs." },
+    { id: "runs.control", title: "Run and recover pipelines", summary: "Start, rerun, retry, resume and recover runs." },
+    { id: "runs.cleanup", title: "Cancel and delete runs", summary: "Cancel runs, abandon stages, delete runs and collect old ones. Destructive." },
+    { id: "gates.read", title: "See what is waiting", summary: "List the gates and questions waiting on a person." },
+    { id: "gates.decide", title: "Decide gates and approvals", summary: "Answer gates and approve or deny agent actions. Only a person can do this.", operatorOnly: true },
+    { id: "triggers", title: "Triggers", summary: "List, create and fire triggers." },
+    { id: "agents.read", title: "Look at agents", summary: "List agents, revisions and sessions." },
+    { id: "agents.manage", title: "Manage agents", summary: "Create, save, enable, disable and restore agents." },
+    { id: "agents.cleanup", title: "Archive agents", summary: "Archive an agent. Destructive." },
+    { id: "agents.converse", title: "Talk to agents", summary: "Chat with an agent and stop its running turn." },
+    { id: "pipelines.author", title: "Author pipelines and tasks", summary: "Read, create and edit pipelines, stages and tasks directly on disk." },
+];
+const t = (group, risk, operatorOnly) => ({ group, risk, ...(operatorOnly ? { operatorOnly } : {}) });
+export const TOOL_META = {
+    get_started: t("discover", "read", true),
+    list_skills: t("discover", "read"),
+    list_pipelines: t("discover", "read"),
+    list_tasks: t("discover", "read"),
+    list_models: t("discover", "read"),
+    list_providers: t("discover", "read"),
+    get_health: t("discover", "read"),
+    preflight: t("discover", "read"),
+    validate: t("discover", "read"),
+    describe_pipeline: t("discover", "read"),
+    list_project_mcp: t("discover", "read"),
+    probe_project_mcp: t("discover", "external"),
+    list_runs: t("runs.read", "read"),
+    get_run: t("runs.read", "read"),
+    export_run: t("runs.read", "read"),
+    read_artifact: t("runs.read", "read"),
+    wait_run: t("runs.read", "read"),
+    list_stage_events: t("runs.read", "read"),
+    tail_stage_log: t("runs.read", "read"),
+    get_stage_verification: t("runs.read", "read"),
+    get_envelope: t("runs.read", "read"),
+    list_checkout_changes: t("runs.read", "read"),
+    get_run_diff: t("runs.read", "read"),
+    read_checkout_file: t("runs.read", "read"),
+    start_run: t("runs.control", "write"),
+    run_stage: t("runs.control", "write"),
+    rerun: t("runs.control", "write"),
+    retry_stage: t("runs.control", "write"),
+    resume_stage: t("runs.control", "write"),
+    recover_manual_stage: t("runs.control", "write"),
+    stop_manual_recovery: t("runs.control", "write"),
+    cancel_run: t("runs.cleanup", "destructive"),
+    abandon_stage: t("runs.cleanup", "destructive"),
+    delete_run: t("runs.cleanup", "destructive"),
+    gc_runs: t("runs.cleanup", "destructive"),
+    list_waiting: t("gates.read", "read"),
+    get_waiting_summary: t("gates.read", "read"),
+    answer_gate: t("gates.decide", "write", true),
+    decide_feedback_loop: t("gates.decide", "write", true),
+    list_triggers: t("triggers", "read"),
+    get_trigger: t("triggers", "read"),
+    create_trigger: t("triggers", "write"),
+    update_trigger: t("triggers", "write"),
+    set_trigger_enabled: t("triggers", "write"),
+    fire_trigger: t("triggers", "external"),
+    list_agents: t("agents.read", "read"),
+    get_agent: t("agents.read", "read"),
+    validate_agent: t("agents.read", "read"),
+    list_agent_revisions: t("agents.read", "read"),
+    get_agent_session: t("agents.read", "read"),
+    list_agent_sessions: t("agents.read", "read"),
+    create_agent: t("agents.manage", "write"),
+    save_agent: t("agents.manage", "write"),
+    enable_agent: t("agents.manage", "write"),
+    disable_agent: t("agents.manage", "write"),
+    restore_agent_revision: t("agents.manage", "write"),
+    archive_agent: t("agents.cleanup", "destructive"),
+    agent_chat: t("agents.converse", "external"),
+    stop_agent_session: t("agents.converse", "write"),
+    approve_agent_action: t("gates.decide", "write", true),
+    deny_agent_action: t("gates.decide", "write", true),
+    read_pipeline: t("pipelines.author", "read"),
+    create_pipeline: t("pipelines.author", "write"),
+    edit_pipeline: t("pipelines.author", "write"),
+    create_stage: t("pipelines.author", "write"),
+    edit_stage: t("pipelines.author", "write"),
+    create_task: t("pipelines.author", "write"),
+    edit_task: t("pipelines.author", "write"),
+};
+/** The grant id the policy gate and `approvals.ask_first` use for a Stageflow tool. */
+export const STAGEFLOW_GRANT_PREFIX = "stageflow.";
+export const stageflowGrantId = (tool) => `${STAGEFLOW_GRANT_PREFIX}${tool}`;
+export function isToolGroupId(value) {
+    return TOOL_GROUPS.some((group) => group.id === value);
+}
+export function isOperatorOnlyGroup(group) {
+    return TOOL_GROUPS.some((entry) => entry.id === group && entry.operatorOnly === true);
+}
+export function isOperatorOnlyTool(name) {
+    const meta = TOOL_META[name];
+    return meta !== undefined && (meta.operatorOnly === true || isOperatorOnlyGroup(meta.group));
+}
+/** Tools of a group an agent may hold; operator-only tools are left out. */
+export function toolsInGroup(group) {
+    return Object.entries(TOOL_META)
+        .filter(([name, meta]) => meta.group === group && !isOperatorOnlyTool(name))
+        .map(([name]) => name);
+}
+/** Every Stageflow tool name a definition grants, whole groups and single tools together. */
+export function grantedStageflowTools(grants) {
+    const names = new Set(grants.tools.filter((tool) => tool in TOOL_META && !isOperatorOnlyTool(tool)));
+    for (const group of grants.groups)
+        for (const tool of toolsInGroup(group))
+            names.add(tool);
+    return [...names].sort();
+}

package/dist/toolkit/profiles.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The Workshop and Agent-author profiles are agents with a fixed grant list.
+ * Their tools are checked through the same grant-id check as any agent's tools,
+ * so there is one permission layer. The lists are literals so this module has no
+ * dependency on the profiles; tests keep them equal to the profiles' tool names.
+ */
+export declare const PROFILE_GRANTS: Readonly<Record<string, {
+    prefix: string;
+    tools: readonly string[];
+}>>;
+export declare function profileGrantIds(profileId: string): Set<string>;
+/** True when the profile holds the grant for this tool. Unknown profiles hold nothing. */
+export declare function profileMayUse(profileId: string, tool: string): boolean;

package/dist/toolkit/profiles.js

@@ -0,0 +1,25 @@
+/**
+ * The Workshop and Agent-author profiles are agents with a fixed grant list.
+ * Their tools are checked through the same grant-id check as any agent's tools,
+ * so there is one permission layer. The lists are literals so this module has no
+ * dependency on the profiles; tests keep them equal to the profiles' tool names.
+ */
+export const PROFILE_GRANTS = {
+    "workshop-author": {
+        prefix: "workshop.",
+        tools: ["list_builds", "focus_build", "create_build", "read_draft", "validate_draft", "create_pipeline", "edit_pipeline", "create_stage", "edit_stage", "create_task", "edit_task", "save", "propose_draft", "retrieve_docs"],
+    },
+    "agent-author": {
+        prefix: "agent_author.",
+        tools: ["read_project_file", "list_project_files", "list_mcp_servers", "update_agent_draft"],
+    },
+};
+export function profileGrantIds(profileId) {
+    const grants = PROFILE_GRANTS[profileId];
+    return new Set((grants?.tools ?? []).map((tool) => `${grants.prefix}${tool}`));
+}
+/** True when the profile holds the grant for this tool. Unknown profiles hold nothing. */
+export function profileMayUse(profileId, tool) {
+    const grants = PROFILE_GRANTS[profileId];
+    return grants !== undefined && profileGrantIds(profileId).has(`${grants.prefix}${tool}`);
+}

package/dist/toolkit/record.d.ts

@@ -0,0 +1,15 @@
+import type { ZodType } from "zod";
+import type { McpToolDeps } from "../mcp/deps.js";
+/** An MCP tool as registered: its name, text, input schema and handler. */
+export type RecordedTool = {
+    name: string;
+    description: string;
+    inputSchema: ZodType | undefined;
+    readOnlyHint: boolean | undefined;
+    handler: (args: Record<string, unknown>, ctx: unknown) => unknown;
+};
+/**
+ * Run the real MCP registration against a recorder instead of a server, so the
+ * toolkit describes exactly the tools the MCP surface exposes, with no second list to drift.
+ */
+export declare function recordMcpTools(deps: McpToolDeps): RecordedTool[];

package/dist/toolkit/record.js

@@ -0,0 +1,17 @@
+import { registerMcpTools } from "../mcp/tools.js";
+/**
+ * Run the real MCP registration against a recorder instead of a server, so the
+ * toolkit describes exactly the tools the MCP surface exposes, with no second list to drift.
+ */
+export function recordMcpTools(deps) {
+    const tools = [];
+    const recorder = {
+        registerTool(name, config, handler) {
+            tools.push({ name, description: config.description ?? "", inputSchema: config.inputSchema, readOnlyHint: config.annotations?.readOnlyHint, handler });
+        },
+        registerResource() { },
+        registerPrompt() { },
+    };
+    registerMcpTools(recorder, deps);
+    return tools;
+}

package/dist/tools/memoryTools.d.ts

@@ -0,0 +1,95 @@
+import { Type } from "typebox";
+import { type StageMemory } from "../memory/access.js";
+type ToolResult = {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    details: unknown;
+    isError?: boolean;
+};
+export declare function createReadMemoryTool(memory: StageMemory): {
+    name: string;
+    label: string;
+    description: string;
+    parameters: Type.TObject<{
+        memory: Type.TString;
+    }>;
+    execute(_toolCallId: string, input: unknown): Promise<ToolResult>;
+};
+export declare function createReplaceMemoryTool(memory: StageMemory): {
+    name: string;
+    label: string;
+    description: string;
+    parameters: Type.TObject<{
+        memory: Type.TString;
+        content: Type.TString;
+    }>;
+    execute(_toolCallId: string, input: unknown): Promise<ToolResult>;
+};
+export declare function createAddMemoryCardTool(memory: StageMemory): {
+    name: string;
+    label: string;
+    description: string;
+    parameters: Type.TObject<{
+        memory: Type.TString;
+        key: Type.TString;
+        content: Type.TString;
+    }>;
+    execute(_toolCallId: string, input: unknown): Promise<ToolResult>;
+};
+export declare function createUpdateMemoryCardTool(memory: StageMemory): {
+    name: string;
+    label: string;
+    description: string;
+    parameters: Type.TObject<{
+        memory: Type.TString;
+        key: Type.TString;
+        content: Type.TString;
+    }>;
+    execute(_toolCallId: string, input: unknown): Promise<ToolResult>;
+};
+export declare function createReadMemoryCardTool(memory: StageMemory): {
+    name: string;
+    label: string;
+    description: string;
+    parameters: Type.TObject<{
+        memory: Type.TString;
+        key: Type.TString;
+    }>;
+    execute(_toolCallId: string, input: unknown): Promise<ToolResult>;
+};
+export declare function createSearchMemoryCardsTool(memory: StageMemory): {
+    name: string;
+    label: string;
+    description: string;
+    parameters: Type.TObject<{
+        memory: Type.TString;
+        query: Type.TString;
+    }>;
+    execute(_toolCallId: string, input: unknown): Promise<ToolResult>;
+};
+export declare function memoryPrompt(memory: StageMemory): Promise<string>;
+/** Prompt text and tools for one attached-memory session. */
+export declare function memorySession(memory: StageMemory): {
+    prompt: string;
+    tools: {
+        name: string;
+        label: string;
+        description: string;
+        parameters: Type.TObject<{
+            memory: Type.TString;
+        }>;
+        execute(_toolCallId: string, input: unknown): Promise<ToolResult>;
+    }[];
+};
+export declare function createAttachedMemoryTools(memory: StageMemory): {
+    name: string;
+    label: string;
+    description: string;
+    parameters: Type.TObject<{
+        memory: Type.TString;
+    }>;
+    execute(_toolCallId: string, input: unknown): Promise<ToolResult>;
+}[];
+export {};

package/dist/tools/memoryTools.js

@@ -0,0 +1,179 @@
+import { Type } from "typebox";
+import { MEMORY_KEY_MAX, MEMORY_PAGE_CAP } from "../memory/ids.js";
+import { MemoryError } from "../memory/host.js";
+import { formatMemoryPrompt } from "../memory/access.js";
+function fault(error) {
+    return { code: error instanceof MemoryError ? error.code : "MEMORY_UNREADABLE" };
+}
+function refused(error) {
+    const details = fault(error);
+    return { content: [{ type: "text", text: JSON.stringify(details) }], details, isError: true };
+}
+export function createReadMemoryTool(memory) {
+    return {
+        name: "read_memory",
+        label: "Read memory",
+        description: "Read the whole page of a memory attached to this stage or agent. Pass the memory id.",
+        parameters: Type.Object({
+            memory: Type.String(),
+        }),
+        async execute(_toolCallId, input) {
+            try {
+                const id = input.memory;
+                if (typeof id !== "string")
+                    throw new MemoryError("MEMORY_INVALID_ID");
+                const body = await memory.read(id);
+                return { content: [{ type: "text", text: body }], details: { memory: id } };
+            }
+            catch (error) {
+                return refused(error);
+            }
+        },
+    };
+}
+export function createReplaceMemoryTool(memory) {
+    return {
+        name: "replace_memory",
+        label: "Replace memory",
+        description: "Replace the whole page of a memory attached to this stage or agent. Pass the memory id and the full new page. A page over the character cap is refused.",
+        parameters: Type.Object({
+            memory: Type.String(),
+            content: Type.String({ maxLength: MEMORY_PAGE_CAP }),
+        }),
+        async execute(_toolCallId, input) {
+            try {
+                const args = input;
+                if (typeof args.memory !== "string")
+                    throw new MemoryError("MEMORY_INVALID_ID");
+                if (typeof args.content !== "string")
+                    throw new MemoryError("MEMORY_TOO_LARGE");
+                await memory.replace(args.memory, args.content);
+                return { content: [{ type: "text", text: "ok" }], details: { memory: args.memory } };
+            }
+            catch (error) {
+                return refused(error);
+            }
+        },
+    };
+}
+function cardWriteArgs(input) {
+    const args = input;
+    if (typeof args.memory !== "string")
+        throw new MemoryError("MEMORY_INVALID_ID");
+    if (typeof args.key !== "string")
+        throw new MemoryError("MEMORY_INVALID_KEY");
+    if (typeof args.content !== "string")
+        throw new MemoryError("MEMORY_TOO_LARGE");
+    return { memory: args.memory, key: args.key, content: args.content };
+}
+const cardParameters = Type.Object({
+    memory: Type.String(),
+    key: Type.String({ maxLength: MEMORY_KEY_MAX }),
+    content: Type.String({ maxLength: MEMORY_PAGE_CAP }),
+});
+export function createAddMemoryCardTool(memory) {
+    return {
+        name: "add_memory_card",
+        label: "Add memory card",
+        description: "Add a card to a memory attached to this stage or agent. Pass the memory id, the card key, and the card body. A second add of the same key is refused.",
+        parameters: cardParameters,
+        async execute(_toolCallId, input) {
+            try {
+                const args = cardWriteArgs(input);
+                await memory.addCard(args.memory, args.key, args.content);
+                return { content: [{ type: "text", text: "ok" }], details: { memory: args.memory, key: args.key } };
+            }
+            catch (error) {
+                return refused(error);
+            }
+        },
+    };
+}
+export function createUpdateMemoryCardTool(memory) {
+    return {
+        name: "update_memory_card",
+        label: "Update memory card",
+        description: "Replace the current body of a card on a memory attached to this stage or agent. Pass the memory id, the card key, and the new body.",
+        parameters: cardParameters,
+        async execute(_toolCallId, input) {
+            try {
+                const args = cardWriteArgs(input);
+                await memory.updateCard(args.memory, args.key, args.content);
+                return { content: [{ type: "text", text: "ok" }], details: { memory: args.memory, key: args.key } };
+            }
+            catch (error) {
+                return refused(error);
+            }
+        },
+    };
+}
+export function createReadMemoryCardTool(memory) {
+    return {
+        name: "read_memory_card",
+        label: "Read memory card",
+        description: "Read the current body of a card on a memory attached to this stage or agent. Pass the memory id and the card key.",
+        parameters: Type.Object({
+            memory: Type.String(),
+            key: Type.String({ maxLength: MEMORY_KEY_MAX }),
+        }),
+        async execute(_toolCallId, input) {
+            try {
+                const args = input;
+                if (typeof args.memory !== "string")
+                    throw new MemoryError("MEMORY_INVALID_ID");
+                if (typeof args.key !== "string")
+                    throw new MemoryError("MEMORY_INVALID_KEY");
+                const body = await memory.readCard(args.memory, args.key);
+                return { content: [{ type: "text", text: body }], details: { memory: args.memory, key: args.key } };
+            }
+            catch (error) {
+                return refused(error);
+            }
+        },
+    };
+}
+export function createSearchMemoryCardsTool(memory) {
+    return {
+        name: "search_memory_cards",
+        label: "Search memory cards",
+        description: "Search the current cards of a memory attached to this stage or agent. Pass the memory id and a query. Returns matching keys and short snippets.",
+        parameters: Type.Object({
+            memory: Type.String(),
+            query: Type.String(),
+        }),
+        async execute(_toolCallId, input) {
+            try {
+                const args = input;
+                if (typeof args.memory !== "string")
+                    throw new MemoryError("MEMORY_INVALID_ID");
+                if (typeof args.query !== "string")
+                    throw new MemoryError("MEMORY_UNREADABLE");
+                const hits = await memory.searchCards(args.memory, args.query);
+                return { content: [{ type: "text", text: JSON.stringify(hits) }], details: { memory: args.memory } };
+            }
+            catch (error) {
+                return refused(error);
+            }
+        },
+    };
+}
+export async function memoryPrompt(memory) {
+    return formatMemoryPrompt(await memory.refreshAttachments());
+}
+/** Prompt text and tools for one attached-memory session. */
+export function memorySession(memory) {
+    return {
+        prompt: formatMemoryPrompt(memory.attachments),
+        tools: createAttachedMemoryTools(memory),
+    };
+}
+export function createAttachedMemoryTools(memory) {
+    return [
+        createReadMemoryTool(memory),
+        createReplaceMemoryTool(memory),
+        createAddMemoryCardTool(memory),
+        createUpdateMemoryCardTool(memory),
+        createReadMemoryCardTool(memory),
+        createSearchMemoryCardsTool(memory),
+    ];
+}

package/dist/types/pipeline.d.ts

@@ -15,6 +15,8 @@ export type PipelineConfig = {
     requires?: ToolRequirement[];
     /** Default channels inherited by every stage that does not override them. */
     channels?: StageChannel[];
+    /** Memory ids every stage in this pipeline can read and replace. */
+    memories?: string[];
 };
 /** An inline pipeline definition authored directly in a `start_run` call, with no backing file. */
 export type InlinePipelineDefinition = {
@@ -25,6 +27,7 @@ export type InlinePipelineDefinition = {
     schemas?: unknown;
     requires?: unknown;
     channels?: unknown;
+    memories?: unknown;
 };
 export type PipelineForkConfig = {
     select: "one" | "subset";

package/dist/types/stage.d.ts

@@ -69,6 +69,8 @@ export type StageConfig = {
     mcp?: string[];
     /** Communication channels this stage may send on. Inherits pipeline `channels` defaults. */
     channels?: StageChannel[];
+    /** Memory ids copied from the pipeline at load. Not a stage YAML key. */
+    memories?: string[];
     /** Declared Host secret names this stage may receive (Slot 6). */
     secrets?: StageSecretDecl[];
     /** Declared toolchain binaries this stage needs (Slot 9). */

package/dist/types/task.d.ts

@@ -2,12 +2,22 @@ export type TaskGitIdentity = {
     name?: string;
     email?: string;
 };
+/**
+ * A string points at a pre-made checkout directory (validated, never
+ * created — today's behavior). An object asks Stageflow to create/reuse a
+ * git worktree for `branch` (auto-named from the task id when omitted),
+ * branching off `base` (default: HEAD) the first time it's created.
+ */
+export type CheckoutDescriptor = string | {
+    branch?: string;
+    base?: string;
+};
 export type TaskFile = {
     id: string;
     goal: string;
     context?: string;
     constraints?: string;
-    checkout?: string;
+    checkout?: CheckoutDescriptor;
     repository?: string;
     ref?: string;
     run_branch_template?: string;