stageflow 0.35.0 → 0.39.0

package/dist/mcp/agentTools.js

@@ -0,0 +1,132 @@
+import { z } from "zod";
+import { defaultAgentProjectRoot } from "../agents/projectRoot.js";
+import { AGENT_ID_PATTERN } from "../config/loadAgent.js";
+import { AgentError, isAgentError } from "../agents/errors.js";
+import { SESSION_STATUSES } from "../agents/store.js";
+import { textResult } from "./toolResults.js";
+const agentId = z.string().regex(AGENT_ID_PATTERN);
+const MCP_ACTOR = { source: "api", author: "mcp" };
+function required(value, what) {
+    if (value === undefined)
+        throw new Error(`MCP agent tools require ${what} from host bootstrap`);
+    return value;
+}
+/** Run a service call and turn domain failures into tool errors with their code and field issues. */
+async function call(work) {
+    try {
+        return textResult(await work());
+    }
+    catch (error) {
+        if (isAgentError(error)) {
+            return textResult({ code: error.code, message: error.message, ...(error.issues.length ? { issues: error.issues } : {}) }, true);
+        }
+        throw error;
+    }
+}
+/**
+ * Agent management for operators driving Stageflow over MCP. A running agent reaches these
+ * only through the Stageflow tool groups it is granted (`agents.*`); the guard in
+ * `toolkit/guard.ts` stops it acting on its own sessions.
+ */
+export function registerAgentTools(server, deps) {
+    const service = () => required(deps.agentService, "agentService");
+    const chat = () => required(deps.agentChat, "agentChat");
+    const root = () => defaultAgentProjectRoot(deps.cwd);
+    /** A session must belong to the agent named in the call, or it is not found (as in the HTTP routes). */
+    const sessionFor = async (id, sessionId) => {
+        const detail = await service().getSession(root(), sessionId);
+        if (detail.session.agentId !== id)
+            throw new AgentError("agent.session_not_found");
+        return detail;
+    };
+    server.registerTool("list_agents", { description: "List project agents (agents/*.agent.yaml) with status and session stats.", inputSchema: z.object({}) }, () => call(async () => ({ agents: await service().list(root()) })));
+    server.registerTool("get_agent", {
+        description: "Get one agent: summary, full definition, canonical YAML, and warnings.",
+        inputSchema: z.object({ id: agentId }),
+    }, ({ id }) => call(() => service().get(root(), id)));
+    server.registerTool("validate_agent", {
+        description: "Validate an agent definition without saving. Returns field issues, warnings, and canonical YAML.",
+        inputSchema: z.object({ definition: z.record(z.string(), z.unknown()) }),
+    }, ({ definition }) => call(() => service().validate(root(), definition)));
+    server.registerTool("create_agent", {
+        description: "Create an agent. It always starts disabled; enable it with enable_agent.",
+        inputSchema: z.object({ definition: z.record(z.string(), z.unknown()) }),
+    }, ({ definition }) => call(() => service().create(root(), definition, MCP_ACTOR)));
+    server.registerTool("save_agent", {
+        description: "Save a full agent definition as a new revision. baseRevision must be the current revision (optimistic lock).",
+        inputSchema: z.object({
+            id: agentId,
+            baseRevision: z.number().int().nonnegative(),
+            definition: z.record(z.string(), z.unknown()),
+            summary: z.string().max(200).optional(),
+        }),
+    }, ({ id, baseRevision, definition, summary }) => call(() => service().save(root(), id, { baseRevision, definition, summary: summary ?? null }, MCP_ACTOR)));
+    server.registerTool("enable_agent", { description: "Enable an agent for new sessions and turns.", inputSchema: z.object({ id: agentId }) }, ({ id }) => call(() => service().setEnabled(root(), id, true, MCP_ACTOR)));
+    server.registerTool("disable_agent", {
+        description: "Disable an agent. New sessions and turns are refused; a running turn finishes.",
+        inputSchema: z.object({ id: agentId }),
+    }, ({ id }) => call(() => service().setEnabled(root(), id, false, MCP_ACTOR)));
+    server.registerTool("list_agent_revisions", { description: "List an agent's revisions, newest first.", inputSchema: z.object({ id: agentId }) }, ({ id }) => call(async () => ({ revisions: await service().listRevisions(root(), id) })));
+    server.registerTool("restore_agent_revision", {
+        description: "Save an earlier revision's definition as the newest revision.",
+        inputSchema: z.object({
+            id: agentId,
+            revision: z.number().int().positive(),
+            baseRevision: z.number().int().nonnegative(),
+        }),
+    }, ({ id, revision, baseRevision }) => call(() => service().restore(root(), id, { revision, baseRevision }, MCP_ACTOR)));
+    server.registerTool("agent_chat", {
+        description: "Send one message to an agent and wait for its reply. Omit sessionId to start a new session.",
+        inputSchema: z.object({ id: agentId, message: z.string().min(1), sessionId: z.string().optional() }),
+    }, ({ id, message, sessionId }) => call(() => chat().send({
+        projectRoot: root(),
+        agentId: id,
+        text: message,
+        source: "mcp",
+        ...(sessionId ? { sessionId } : {}),
+    })));
+    server.registerTool("get_agent_session", {
+        description: "Fetch a session of an agent: transcript, turns, approvals.",
+        inputSchema: z.object({ id: agentId, sessionId: z.string() }),
+    }, ({ id, sessionId }) => call(() => sessionFor(id, sessionId)));
+    server.registerTool("list_agent_sessions", {
+        description: "List an agent's sessions, newest first, with turn counts, tokens and cost.",
+        inputSchema: z.object({
+            id: agentId,
+            status: z.enum(SESSION_STATUSES).optional(),
+            search: z.string().optional(),
+            limit: z.number().int().min(1).max(100).optional(),
+            cursor: z.string().optional(),
+        }),
+    }, ({ id, status, search, limit, cursor }) => call(() => service().listSessions(root(), id, {
+        limit: limit ?? 25,
+        ...(status ? { status } : {}),
+        ...(search ? { search } : {}),
+        ...(cursor ? { cursor } : {}),
+    })));
+    server.registerTool("stop_agent_session", {
+        description: "Stop the turn currently running in a session. The session stays open.",
+        inputSchema: z.object({ id: agentId, sessionId: z.string() }),
+    }, ({ id, sessionId }) => call(async () => {
+        await sessionFor(id, sessionId);
+        return { stopped: chat().stop(sessionId) };
+    }));
+    server.registerTool("archive_agent", {
+        description: "Archive an agent: its definition leaves the project and new sessions are refused. Past sessions are kept.",
+        inputSchema: z.object({ id: agentId }),
+    }, ({ id }) => call(async () => { await service().archive(root(), id); return { archived: true }; }));
+    server.registerTool("approve_agent_action", {
+        description: "Approve the pending ask-first action on a session of an agent, as an operator.",
+        inputSchema: z.object({ id: agentId, sessionId: z.string() }),
+    }, ({ id, sessionId }) => call(async () => {
+        await sessionFor(id, sessionId);
+        return service().decideApproval(root(), sessionId, "approve", { kind: "operator" });
+    }));
+    server.registerTool("deny_agent_action", {
+        description: "Deny the pending ask-first action on a session of an agent. The agent is told it was refused.",
+        inputSchema: z.object({ id: agentId, sessionId: z.string() }),
+    }, ({ id, sessionId }) => call(async () => {
+        await sessionFor(id, sessionId);
+        return service().decideApproval(root(), sessionId, "deny", { kind: "operator" });
+    }));
+}

package/dist/mcp/catalogTools.js

@@ -1,6 +1,7 @@
+import { buildModelsResponse } from "../models/response.js";
 import { z } from "zod";
 import { catalogPathErrorBody, CatalogPathError, resolveCatalogRelativePath, resolveCatalogStartInput, selectCatalogRootForStart, } from "../config/catalogRelativePath.js";
-import { listModelsMultiProject, listPipelinesMultiProject, listTasksMultiProject, } from "../config/multiProjectCatalog.js";
+import { listPipelinesMultiProject, listTasksMultiProject, } from "../config/multiProjectCatalog.js";
 import { resolveCatalogRoots } from "../config/resolveCatalogRoots.js";
 import { describePipeline } from "../config/describePipeline.js";
 import { loadPipeline } from "../config/loadPipeline.js";
@@ -63,6 +64,7 @@ const inlinePipelineSchema = z
     model: z.unknown().optional(),
     schemas: z.unknown().optional(),
     requires: z.unknown().optional(),
+    channels: z.unknown().optional(),
 })
     .strict();
 const startRunSchema = z
@@ -232,14 +234,14 @@ export function registerCatalogTools(server, deps) {
         });
     });
     server.registerTool("list_models", {
-        description: "List catalog model ids across every project this host knows about (same multi-root source as GET /api/models). Optional project_root filter narrows.",
+        description: "List model ids from the providers connected on this host, plus ids pipelines use (same source as GET /api/models). Returns models, providers (grouped), the default model and unlisted ids. Optional project_root filter narrows the pipeline-used ids.",
         inputSchema: z.object({
             project_root: z.string().optional(),
         }),
     }, async ({ project_root }) => {
-        const result = await listModelsMultiProject({
+        const { response, used: result } = await buildModelsResponse({
             store,
-            bootCwd: cwd,
+            cwd,
             projectRootFilter: project_root,
         });
         if (result.root_errors.some((e) => e.code === "unknown_project_root") &&
@@ -250,11 +252,7 @@ export function registerCatalogTools(server, deps) {
                 root_errors: result.root_errors,
             }, true);
         }
-        return textResult({
-            models: result.models,
-            entries: result.items,
-            root_errors: result.root_errors,
-        });
+        return textResult(response);
     });
     server.registerTool("list_runs", {
         description: "List known pipeline runs. Optional filters: status, since (ISO created_at lower bound), pipeline (id or path), caller_id.",

package/dist/mcp/deps.d.ts

@@ -1,5 +1,8 @@
 import type { BootProviderResult } from "../agent/bootProviderConfig.js";
 import type { ProviderAuthContext } from "../agent/providerAuth.js";
+import type { AgentChatController } from "../agents/chatTurn.js";
+import type { ConversationBackend } from "../agents/sessions.js";
+import type { AgentService } from "../agents/service.js";
 import type { RunStore } from "../runstore/port.js";
 import type { RunChangeBus } from "../runtime/runChangeBus.js";
 import type { RunManager } from "../runtime/runManager.js";
@@ -11,6 +14,9 @@ export type McpToolDeps = {
     providerAuthContext?: ProviderAuthContext;
     projectRoot?: string;
     providerBoot?: BootProviderResult;
+    agentService?: AgentService;
+    agentChat?: AgentChatController;
+    agentConversationBackend?: ConversationBackend;
 };
 export type McpHttpDeps = McpToolDeps & {
     runChangeBus: RunChangeBus;

package/dist/mcp/pipelineAuthorSupport.d.ts

@@ -0,0 +1,19 @@
+import { loadDraftPackage, validateDraftPackage, type DraftPackage } from "../config/draftPackage.js";
+export { loadDraftPackage, validateDraftPackage, type DraftPackage };
+export type PublishFacadeResult = {
+    ok: true;
+    pipelinePath: string;
+    stagePaths: string[];
+    taskPath?: string;
+} | {
+    ok: false;
+    error: string;
+    status: number;
+};
+/** Write a package the way the Workshop's save does, flattening its result shape. */
+export declare function publishDraftPackageFacade(projectRoot: string, input: {
+    directory: string;
+    draft: DraftPackage;
+    pipelineFilename: string;
+    allowInvalid?: boolean;
+}, mode: "create" | "overwrite"): Promise<PublishFacadeResult>;

package/dist/mcp/pipelineAuthorSupport.js

@@ -0,0 +1,10 @@
+import { loadDraftPackage, validateDraftPackage } from "../config/draftPackage.js";
+import { publishDraftPackage } from "../config/publishDraftPackage.js";
+export { loadDraftPackage, validateDraftPackage };
+/** Write a package the way the Workshop's save does, flattening its result shape. */
+export async function publishDraftPackageFacade(projectRoot, input, mode) {
+    const { write } = await publishDraftPackage(projectRoot, input, mode);
+    if (!write.ok)
+        return { ok: false, error: write.error, status: write.status };
+    return { ok: true, pipelinePath: write.pipelinePath, stagePaths: write.stagePaths, ...(write.taskPath !== undefined ? { taskPath: write.taskPath } : {}) };
+}

package/dist/mcp/pipelineAuthorTools.d.ts

@@ -0,0 +1,8 @@
+import type { McpServer } from "@modelcontextprotocol/server";
+import type { McpToolDeps } from "./deps.js";
+/**
+ * Author pipelines and tasks straight on disk. Each mutation loads the package,
+ * applies the same builder the Workshop uses, and writes it back through the
+ * Workshop's publish path (validate first, nothing written when invalid).
+ */
+export declare function registerPipelineAuthorTools(server: McpServer, deps: McpToolDeps): void;

package/dist/mcp/pipelineAuthorTools.js

@@ -0,0 +1,109 @@
+import path from "node:path";
+import { z } from "zod";
+import { loadDraftPackage, publishDraftPackageFacade, validateDraftPackage } from "./pipelineAuthorSupport.js";
+import { buildCreatePipelineDraft, buildCreateStageDraft, buildCreateTaskDraft, buildEditPipelineDraft, buildEditStageDraft, buildEditTaskDraft, } from "../operatorAgent/profiles/workshopAuthorTools.js";
+import { textResult } from "./toolResults.js";
+const pipelinePath = z
+    .string()
+    .describe("Pipeline YAML path relative to the project root, e.g. workshop/release/pipeline.yaml");
+const record = z.record(z.string(), z.unknown());
+const allowInvalid = z
+    .boolean()
+    .optional()
+    .describe("Write even when validation fails, so a pipeline can be built up step by step. Default false.");
+/**
+ * Author pipelines and tasks straight on disk. Each mutation loads the package,
+ * applies the same builder the Workshop uses, and writes it back through the
+ * Workshop's publish path (validate first, nothing written when invalid).
+ */
+export function registerPipelineAuthorTools(server, deps) {
+    const root = () => deps.projectRoot ?? deps.cwd;
+    async function mutate(relPath, mode, build, options = {}) {
+        const projectRoot = root();
+        let draft = { pipeline: { id: "", stages: [] } };
+        if (mode === "overwrite") {
+            const loaded = await loadDraftPackage(projectRoot, relPath, options.taskPath ? { taskPath: options.taskPath } : {});
+            if (!loaded.ok)
+                return textResult({ error: loaded.error, status: loaded.status }, true);
+            draft = loaded.draft;
+        }
+        const built = build(draft);
+        if (!built.ok)
+            return textResult({ error: built.error }, true);
+        const directory = path.posix.dirname(relPath.replace(/\\/g, "/")) || ".";
+        const published = await publishDraftPackageFacade(projectRoot, {
+            directory,
+            draft: built.nextDraft,
+            pipelineFilename: path.posix.basename(relPath),
+            ...(options.allowInvalid ? { allowInvalid: true } : {}),
+        }, mode);
+        if (!published.ok)
+            return textResult({ error: published.error, status: published.status }, true);
+        return textResult({ pipelinePath: published.pipelinePath, stagePaths: published.stagePaths, taskPath: published.taskPath ?? null });
+    }
+    server.registerTool("read_pipeline", {
+        description: "Read a pipeline package from disk (pipeline, stage files, optional task) with its validation result. Use before editing.",
+        inputSchema: z.object({ path: pipelinePath, task_path: z.string().optional().describe("Task file to include, relative to the project root") }),
+    }, async ({ path: relPath, task_path }) => {
+        const loaded = await loadDraftPackage(root(), relPath, task_path ? { taskPath: task_path } : {});
+        if (!loaded.ok)
+            return textResult({ error: loaded.error, status: loaded.status }, true);
+        const validation = await validateDraftPackage(loaded.draft, { cwd: deps.cwd, projectRoot: root() });
+        return textResult({ draft: loaded.draft, destination: loaded.destination, validation });
+    });
+    server.registerTool("create_pipeline", {
+        description: "Create a new pipeline package on disk (id, optional model/stages). Fails if it already exists; use edit_pipeline instead. A pipeline needs at least one stage to validate, so add stages or pass allow_invalid and then create_stage.",
+        inputSchema: z.object({
+            directory: z.string().describe("Catalog folder relative to the project root, e.g. workshop/release. The file is written as <id>.pipeline.yaml"),
+            id: z.string(),
+            model: z.string().optional(),
+            agent: z.unknown().optional(),
+            stages: z.array(record).optional(),
+            pipeline: record.optional().describe("Whole pipeline object, instead of id/model/stages"),
+            allow_invalid: allowInvalid,
+        }),
+    }, ({ directory, allow_invalid, ...args }) => {
+        const folder = directory.replace(/[\\/]+$/, "");
+        const file = `${typeof args.id === "string" ? args.id : ""}.pipeline.yaml`;
+        return mutate(folder === "" || folder === "." ? file : `${folder}/${file}`, "create", (draft) => buildCreatePipelineDraft(draft, args), { allowInvalid: allow_invalid });
+    });
+    server.registerTool("edit_pipeline", {
+        description: "Edit pipeline fields on disk (id, model, agent, stages wiring, schemas, requires). Pass the fields to change under patch.",
+        inputSchema: z.object({ path: pipelinePath, patch: record, allow_invalid: allowInvalid }),
+    }, ({ path: relPath, patch, allow_invalid }) => mutate(relPath, "overwrite", (draft) => buildEditPipelineDraft(draft, { patch }), { allowInvalid: allow_invalid }));
+    server.registerTool("create_stage", {
+        description: "Add a file-backed stage to a pipeline on disk (uses: ./id.yaml plus the stage body with io).",
+        inputSchema: z.object({
+            path: pipelinePath,
+            id: z.string().optional(),
+            summary: z.string().optional(),
+            system_prompt: z.string().optional(),
+            model: z.string().optional(),
+            entry: z.boolean().optional(),
+            route: z.array(record).optional(),
+            io: record.optional(),
+            body: record.optional().describe("Extra stage body fields"),
+            allow_invalid: allowInvalid,
+        }),
+    }, ({ path: relPath, allow_invalid, ...args }) => mutate(relPath, "overwrite", (draft) => buildCreateStageDraft(draft, args), { allowInvalid: allow_invalid }));
+    server.registerTool("edit_stage", {
+        description: "Edit an existing stage on disk by id: body fields and/or its pipeline entry (route, entry, uses).",
+        inputSchema: z.looseObject({ path: pipelinePath, id: z.string(), allow_invalid: allowInvalid }),
+    }, ({ path: relPath, allow_invalid, ...args }) => mutate(relPath, "overwrite", (draft) => buildEditStageDraft(draft, args), { allowInvalid: allow_invalid }));
+    server.registerTool("create_task", {
+        description: "Create or replace the task beside a pipeline on disk (id and goal, optional body).",
+        inputSchema: z.object({ path: pipelinePath, id: z.string().optional(), goal: z.string().optional(), filename: z.string().optional(), body: record.optional(), allow_invalid: allowInvalid }),
+    }, ({ path: relPath, allow_invalid, ...args }) => mutate(relPath, "overwrite", (draft) => buildCreateTaskDraft(draft, args), { allowInvalid: allow_invalid }));
+    server.registerTool("edit_task", {
+        description: "Edit the task of a pipeline on disk (id, goal, body fields).",
+        inputSchema: z.object({
+            path: pipelinePath,
+            task_path: z.string().describe("Task file relative to the project root"),
+            id: z.string().optional(),
+            goal: z.string().optional(),
+            patch: record.optional(),
+            body: record.optional(),
+            allow_invalid: allowInvalid,
+        }),
+    }, ({ path: relPath, task_path, allow_invalid, ...args }) => mutate(relPath, "overwrite", (draft) => buildEditTaskDraft(draft, args), { taskPath: task_path, allowInvalid: allow_invalid }));
+}

package/dist/mcp/server.js

@@ -44,6 +44,11 @@ function toolDepsFrom(deps) {
             : {}),
         ...(deps.projectRoot !== undefined ? { projectRoot: deps.projectRoot } : {}),
         ...(deps.providerBoot !== undefined ? { providerBoot: deps.providerBoot } : {}),
+        ...(deps.agentService !== undefined ? { agentService: deps.agentService } : {}),
+        ...(deps.agentChat !== undefined ? { agentChat: deps.agentChat } : {}),
+        ...(deps.agentConversationBackend !== undefined
+            ? { agentConversationBackend: deps.agentConversationBackend }
+            : {}),
     };
 }
 function attachBusNotifications(server, bus) {

package/dist/mcp/tools.js

@@ -3,10 +3,12 @@ import { registerCatalogTools } from "./catalogTools.js";
 import { registerCheckoutTools } from "./checkoutTools.js";
 import { registerControlTools } from "./controlTools.js";
 import { registerProjectMcpTools } from "./projectMcpTools.js";
+import { registerPipelineAuthorTools } from "./pipelineAuthorTools.js";
 import { registerProviderTools } from "./providerTools.js";
 import { registerTriggerTools } from "./triggerTools.js";
 import { textResult } from "./toolResults.js";
 import { DEFAULT_TIMEOUT_MS, waitRun } from "./waitRun.js";
+import { registerAgentTools } from "./agentTools.js";
 import { registerGetStartedTool } from "./getStartedTool.js";
 export function registerMcpTools(server, deps) {
     const { store } = deps;
@@ -17,6 +19,8 @@ export function registerMcpTools(server, deps) {
     registerProviderTools(server, deps);
     registerProjectMcpTools(server, deps);
     registerTriggerTools(server, deps);
+    registerPipelineAuthorTools(server, deps);
+    registerAgentTools(server, deps);
     server.registerTool("wait_run", {
         description: "Long-poll until a run is waiting for HITL input and/or terminal (succeeded/failed), or until timeout_ms. Default until=any wakes on waiting OR terminal. Abort cancels only this wait (not the run). Optional notifications/progress when the client supplies _meta.progressToken. Compose: wait_run → answer_gate → wait_run.",
         inputSchema: z.object({

package/dist/mcp/triggerTools.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { CatalogPathError, catalogPathErrorBody, resolveWritableCatalogRoot, } from "../config/catalogRelativePath.js";
 import { createTrigger, parseCreateTriggerBody } from "../config/createTrigger.js";
+import { parsePatchTriggerBody, parsePutTriggerBody, updateTriggerDefinition, updateTriggerEnabled } from "../config/updateTrigger.js";
 import { loadCatalogTriggers } from "../config/triggerCatalog.js";
 import { writeAudit } from "../logging/audit.js";
 import { logger as rootLogger } from "../logging/logger.js";
@@ -167,4 +168,35 @@ export function registerTriggerTools(server, deps) {
         });
         return textResult(result.trigger);
     });
+    server.registerTool("update_trigger", {
+        description: "Replace a trigger's definition (pipeline, task, kind, schedule or event, enabled). Same validation and write path as PUT /api/triggers/:id; the id cannot change.",
+        inputSchema: z.object({
+            id: z.string(),
+            project_root: z.string().optional(),
+            pipeline: z.string(),
+            task: z.string().optional(),
+            kind: z.enum(["manual", "schedule", "event"]),
+            schedule: triggerScheduleSchema.optional(),
+            event: triggerEventSchema.optional(),
+            enabled: z.boolean().optional(),
+        }),
+    }, async ({ id, project_root, ...body }) => {
+        const parsed = parsePutTriggerBody(body, id);
+        if ("ok" in parsed)
+            return textResult({ error: parsed.error, status: parsed.status }, true);
+        const result = await updateTriggerDefinition(cwd, store, id, parsed, { projectRootFilter: project_root });
+        writeAudit(auditLog, { caller_id: callerIdFromRequestAuth(), surface: getRequestAuth()?.surface ?? "mcp", action: "trigger_update", outcome: result.ok ? "ok" : "error" });
+        return result.ok ? textResult(result.trigger) : textResult({ error: result.error, status: result.status }, true);
+    });
+    server.registerTool("set_trigger_enabled", {
+        description: "Enable or disable a trigger. Same write path as PATCH /api/triggers/:id.",
+        inputSchema: z.object({ id: z.string(), enabled: z.boolean(), project_root: z.string().optional() }),
+    }, async ({ id, enabled, project_root }) => {
+        const parsed = parsePatchTriggerBody({ enabled });
+        if ("ok" in parsed)
+            return textResult({ error: parsed.error, status: parsed.status }, true);
+        const result = await updateTriggerEnabled(cwd, store, id, parsed.enabled, { projectRootFilter: project_root });
+        writeAudit(auditLog, { caller_id: callerIdFromRequestAuth(), surface: getRequestAuth()?.surface ?? "mcp", action: "trigger_patch", outcome: result.ok ? "ok" : "error" });
+        return result.ok ? textResult(result.trigger) : textResult({ error: result.error, status: result.status }, true);
+    });
 }

package/dist/memory/access.d.ts

@@ -0,0 +1,36 @@
+import { type MemoryCardHit, type MemoryHost, type MemoryMeta } from "./host.js";
+/** What a stage or agent session is allowed to do with the memories attached to it. */
+export type StageMemory = {
+    attachments: MemoryMeta[];
+    refreshAttachments(): Promise<MemoryMeta[]>;
+    read(id: string): Promise<string>;
+    replace(id: string, content: string): Promise<void>;
+    addCard(id: string, key: string, body: string): Promise<void>;
+    updateCard(id: string, key: string, body: string): Promise<void>;
+    readCard(id: string, key: string): Promise<string>;
+    searchCards(id: string, query: string): Promise<MemoryCardHit[]>;
+};
+/** Unchecked reads and writes. The attachment allowlist sits in front of this. */
+export type MemoryPort = {
+    meta(id: string): Promise<MemoryMeta>;
+    read(id: string): Promise<string>;
+    replace(id: string, content: string): Promise<void>;
+    addCard(id: string, key: string, body: string): Promise<void>;
+    updateCard(id: string, key: string, body: string): Promise<void>;
+    readCard(id: string, key: string): Promise<string>;
+    searchCards(id: string, query: string): Promise<MemoryCardHit[]>;
+};
+declare const MEMORY_VERBS: readonly ["memory.read", "memory.replace", "memory.meta", "memory.addCard", "memory.updateCard", "memory.readCard", "memory.searchCards"];
+export type MemoryVerb = (typeof MEMORY_VERBS)[number];
+export declare function isMemoryVerb(type: string | undefined): type is MemoryVerb;
+/** One allowlist in front of either the host or the worker port. */
+export declare function attachMemory(ids: readonly string[], port: MemoryPort): Promise<StageMemory>;
+export declare function bindStageMemory(host: MemoryHost, ids: readonly string[]): Promise<StageMemory>;
+/** Parent-side dispatch for a stage worker. Refuses an id the stage was not given. */
+export declare function runMemoryRequest(host: MemoryHost, allowed: readonly string[], type: MemoryVerb, input: unknown): Promise<{
+    body?: string;
+    meta?: MemoryMeta;
+    hits?: MemoryCardHit[];
+}>;
+export declare function formatMemoryPrompt(attachments: readonly MemoryMeta[]): string;
+export {};

package/dist/memory/access.js

@@ -0,0 +1,116 @@
+import { MemoryError } from "./host.js";
+const MEMORY_VERBS = [
+    "memory.read",
+    "memory.replace",
+    "memory.meta",
+    "memory.addCard",
+    "memory.updateCard",
+    "memory.readCard",
+    "memory.searchCards",
+];
+export function isMemoryVerb(type) {
+    return type !== undefined && MEMORY_VERBS.includes(type);
+}
+function gate(allowed, id) {
+    if (!allowed.has(id))
+        throw new MemoryError("MEMORY_NOT_ATTACHED");
+}
+/** One allowlist in front of either the host or the worker port. */
+export async function attachMemory(ids, port) {
+    const attachments = [];
+    for (const id of ids)
+        attachments.push(await port.meta(id));
+    const allowed = new Set(ids);
+    return {
+        attachments,
+        async refreshAttachments() {
+            const next = [];
+            for (const id of ids)
+                next.push(await port.meta(id));
+            attachments.length = 0;
+            attachments.push(...next);
+            return next;
+        },
+        async read(id) {
+            gate(allowed, id);
+            return port.read(id);
+        },
+        async replace(id, content) {
+            gate(allowed, id);
+            await port.replace(id, content);
+        },
+        async addCard(id, key, body) {
+            gate(allowed, id);
+            await port.addCard(id, key, body);
+        },
+        async updateCard(id, key, body) {
+            gate(allowed, id);
+            await port.updateCard(id, key, body);
+        },
+        async readCard(id, key) {
+            gate(allowed, id);
+            return port.readCard(id, key);
+        },
+        async searchCards(id, query) {
+            gate(allowed, id);
+            return port.searchCards(id, query);
+        },
+    };
+}
+export function bindStageMemory(host, ids) {
+    return attachMemory(ids, {
+        meta: (id) => host.readMeta(id),
+        read: (id) => host.read(id),
+        replace: (id, content) => host.replace(id, content),
+        addCard: (id, key, body) => host.addCard(id, key, body),
+        updateCard: (id, key, body) => host.updateCard(id, key, body),
+        readCard: (id, key) => host.readCard(id, key),
+        searchCards: (id, query) => host.searchCards(id, query),
+    });
+}
+/** Parent-side dispatch for a stage worker. Refuses an id the stage was not given. */
+export async function runMemoryRequest(host, allowed, type, input) {
+    const args = (input ?? {});
+    const id = args.memory;
+    if (typeof id !== "string" || !allowed.includes(id))
+        throw new MemoryError("MEMORY_NOT_ATTACHED");
+    if (type === "memory.read")
+        return { body: await host.read(id) };
+    if (type === "memory.replace") {
+        if (typeof args.content !== "string")
+            throw new MemoryError("MEMORY_UNREADABLE");
+        await host.replace(id, args.content);
+        return {};
+    }
+    if (type === "memory.addCard" || type === "memory.updateCard") {
+        if (typeof args.key !== "string")
+            throw new MemoryError("MEMORY_INVALID_KEY");
+        if (typeof args.content !== "string")
+            throw new MemoryError("MEMORY_UNREADABLE");
+        if (type === "memory.addCard")
+            await host.addCard(id, args.key, args.content);
+        else
+            await host.updateCard(id, args.key, args.content);
+        return {};
+    }
+    if (type === "memory.readCard") {
+        if (typeof args.key !== "string")
+            throw new MemoryError("MEMORY_INVALID_KEY");
+        return { body: await host.readCard(id, args.key) };
+    }
+    if (type === "memory.searchCards") {
+        const query = typeof args.query === "string" ? args.query : "";
+        return { hits: await host.searchCards(id, query) };
+    }
+    return { meta: await host.readMeta(id) };
+}
+export function formatMemoryPrompt(attachments) {
+    const lines = attachments.map((item) => `- ${item.id}: ${item.description}`);
+    return [
+        "Memories you can read and replace:",
+        ...lines,
+        "Call read_memory with the memory id to get the page. Call replace_memory with the full new page.",
+        "Call add_memory_card, update_memory_card, and read_memory_card with the memory id and the card key. Call search_memory_cards with the memory id and a query.",
+        "The page is not shown here. Card bodies are not shown here. Do not try to open memory files yourself.",
+    ].join("\n");
+}

package/dist/memory/agentIssues.d.ts

@@ -0,0 +1,3 @@
+import type { AgentIssue } from "../config/loadAgent.js";
+/** Hard errors for an agent that names a memory the data directory does not have. */
+export declare function agentMemoryIssues(ids: readonly string[] | undefined, env?: NodeJS.ProcessEnv): AgentIssue[];

package/dist/memory/agentIssues.js

@@ -0,0 +1,23 @@
+import { inspectMemorySync, memoryHome } from "./host.js";
+const MESSAGE = {
+    MEMORY_NOT_FOUND: (id) => `Memory "${id}" does not exist. Create it before attaching it.`,
+    MEMORY_MISMATCH: (id) => `Memory "${id}" does not match the id in its file.`,
+    MEMORY_UNREADABLE: (id) => `Memory "${id}" could not be read.`,
+    MEMORY_INVALID_ID: (id) => `Memory "${id}" is not a valid id.`,
+};
+/** Hard errors for an agent that names a memory the data directory does not have. */
+export function agentMemoryIssues(ids, env = process.env) {
+    if (!ids?.length)
+        return [];
+    const home = memoryHome(env);
+    return ids.flatMap((id, index) => {
+        const inspected = inspectMemorySync(home, id);
+        if (inspected.ok)
+            return [];
+        return [{
+                path: `memories.${index}`,
+                code: "agent.memory_unavailable",
+                message: (MESSAGE[inspected.code] ?? MESSAGE.MEMORY_UNREADABLE)(id),
+            }];
+    });
+}

package/dist/memory/bashDeny.d.ts

@@ -0,0 +1,6 @@
+import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
+export declare const MEMORY_STORE_BASH_DENIED = "The memory store cannot be accessed with shell commands. Use the memory tools.";
+export declare function memoryStorePathInCommand(command: string, home: string): boolean;
+export declare function createMemoryStoreBashDenyExtension(options: {
+    home: string;
+}): ExtensionFactory;