@evandu/super-pi 0.1.1 → 0.1.3

package/dist/server/capability.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Proving that a dispatch request came from THIS server's primary agent, rather than from anything else on
+ * the machine that can open a socket to localhost.
+ *
+ * WHY THIS EXISTS, since the dispatch endpoint already looks like it authenticates. It does not. It
+ * validates ANCESTRY - that a claimed `parentRunId` names a real run belonging to the right conversation -
+ * and `docs/AGENT_LOOP_DESIGN.md` states the limit in as many words: "The current HTTP boundary validates
+ * supplied ancestry, not caller identity. A local process that omits both parentRunId and depth is
+ * indistinguishable from a primary caller." That is true, and it was tolerable while the only reachable
+ * primitive was a single dispatch. It stops being tolerable the moment an endpoint can trigger a SEQUENCE
+ * of dispatches: one unauthenticated POST becomes an unattended pipeline of sub-agents writing to the
+ * user's workspace, which is a far larger lever for the same missing check.
+ *
+ * WHY A CAPABILITY RATHER THAN A SHARED SECRET. `SUPER_PI_ACCESS_TOKEN` already exists and every endpoint
+ * already checks it - but it is SERVER-WIDE and optional: unset is the default, and when unset the whole
+ * server runs open on loopback, which is a reasonable choice for an app meant to be run by the person
+ * sitting at the machine. A dispatch capability is narrower and non-optional in the way that matters: it
+ * exists only for the duration of one turn, for one conversation, and only the primary agent's environment
+ * ever holds it. `SubagentSupervisor` passes no `env` to a child at all (`subagents.ts:371-380`), so a
+ * sub-agent - whose whole threat is that a model controls its inputs and therefore its shell commands -
+ * structurally cannot read it back out of its own environment and post it.
+ *
+ * WHAT THIS DOES NOT CLAIM. It is not defence against a compromised primary agent, which can read its own
+ * environment and would simply forward the capability. It is defence against the two neighbours of the
+ * primary that are NOT it: an unrelated local process, and a sub-agent that escaped its read-only
+ * allowlist. Neither is the primary, and neither is handed the token.
+ */
+/**
+ * The environment variable the capability travels in.
+ *
+ * Named on both sides of the wire rather than imported by the extension, for the reason every one of
+ * these names is written out twice: `agents/` is loaded by Pi's module loader and `src/` by tsc, so a
+ * relative import across the two would resolve differently under each. `scripts/task-tool.test.mjs`
+ * asserts the two copies agree, because a rename on one side would otherwise fail at dispatch time with a
+ * message nobody reads.
+ */
+export declare const TASK_CAPABILITY_ENV = "SUPER_PI_TASK_CAPABILITY";
+/**
+ * Mints the capability for one turn of one conversation, and returns it for the extension's environment.
+ *
+ * CALLED AT SPAWN, so the value is decided before the child exists and cannot be changed underneath it.
+ * A turn that never reaches the spawn mints nothing, which is correct: there is no process to hand it to.
+ *
+ * ROTATED EVERY TURN, and that is the property the duration would not give on its own. A token valid for
+ * the whole server lifetime would still be a token an unrelated process could not guess - but a token
+ * valid only while its holder is alive is a token that stops being a credential the moment the turn ends,
+ * so there is no window in which a leaked value is still live.
+ */
+export declare function mintCapability(conversationId: string): string;
+/**
+ * Forgets a conversation's capability, at the end of its turn.
+ *
+ * CALLED FROM `answer()`'s `finally`, so it runs on every exit - a turn that answered, a turn that threw,
+ * and a turn whose child was killed. A capability that outlived its turn would keep working for a process
+ * that no longer exists, which is precisely the shape of a credential with no owner.
+ */
+export declare function releaseCapability(conversationId: string): void;
+/** Forgets every capability. Called on shutdown, so nothing survives the process that minted it. */
+export declare function releaseAllCapabilities(): void;
+/**
+ * The capability currently valid for a conversation, or `undefined` when no primary turn is running.
+ *
+ * Exported for the endpoint's own diagnostics and for a test that needs to assert the lifecycle without
+ * reading a primary turn's environment. Not exported as a way to READ a conversation's capability and use
+ * it - a caller in this process is already inside the trust boundary it protects.
+ */
+export declare function capabilityFor(conversationId: string): string | undefined;
+/** The outcome of a check, with a message written for whoever the refusal will be shown to. */
+export type CapabilityVerdict = {
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Checks a presented capability against the one this conversation's turn was given.
+ *
+ * `timingSafeEqual` rather than `===`, because `===` on a token short-circuits at the first differing byte
+ * and turns the comparison into a timing oracle for the value itself. The length check runs first because
+ * `timingSafeEqual` throws on mismatched lengths rather than returning false.
+ *
+ * THE MESSAGE NAMES BOTH HALVES OF THE PROBLEM, because the reader is a model about to retry and there
+ * are two genuinely different failures here. A conversation with no live capability is being dispatched
+ * from OUTSIDE a turn - the request never came from a primary agent. A conversation with one, and the
+ * presented value does not match it, is a turn whose value was not carried through. An extension that
+ * silently omitted the header would otherwise be indistinguishable from an attacker, and would keep
+ * retrying forever.
+ */
+export declare function verifyCapability(conversationId: string, presented: unknown): CapabilityVerdict;

package/dist/server/capability.js

@@ -0,0 +1,136 @@
+import { randomUUID, timingSafeEqual } from "node:crypto";
+/**
+ * Proving that a dispatch request came from THIS server's primary agent, rather than from anything else on
+ * the machine that can open a socket to localhost.
+ *
+ * WHY THIS EXISTS, since the dispatch endpoint already looks like it authenticates. It does not. It
+ * validates ANCESTRY - that a claimed `parentRunId` names a real run belonging to the right conversation -
+ * and `docs/AGENT_LOOP_DESIGN.md` states the limit in as many words: "The current HTTP boundary validates
+ * supplied ancestry, not caller identity. A local process that omits both parentRunId and depth is
+ * indistinguishable from a primary caller." That is true, and it was tolerable while the only reachable
+ * primitive was a single dispatch. It stops being tolerable the moment an endpoint can trigger a SEQUENCE
+ * of dispatches: one unauthenticated POST becomes an unattended pipeline of sub-agents writing to the
+ * user's workspace, which is a far larger lever for the same missing check.
+ *
+ * WHY A CAPABILITY RATHER THAN A SHARED SECRET. `SUPER_PI_ACCESS_TOKEN` already exists and every endpoint
+ * already checks it - but it is SERVER-WIDE and optional: unset is the default, and when unset the whole
+ * server runs open on loopback, which is a reasonable choice for an app meant to be run by the person
+ * sitting at the machine. A dispatch capability is narrower and non-optional in the way that matters: it
+ * exists only for the duration of one turn, for one conversation, and only the primary agent's environment
+ * ever holds it. `SubagentSupervisor` passes no `env` to a child at all (`subagents.ts:371-380`), so a
+ * sub-agent - whose whole threat is that a model controls its inputs and therefore its shell commands -
+ * structurally cannot read it back out of its own environment and post it.
+ *
+ * WHAT THIS DOES NOT CLAIM. It is not defence against a compromised primary agent, which can read its own
+ * environment and would simply forward the capability. It is defence against the two neighbours of the
+ * primary that are NOT it: an unrelated local process, and a sub-agent that escaped its read-only
+ * allowlist. Neither is the primary, and neither is handed the token.
+ */
+/**
+ * The environment variable the capability travels in.
+ *
+ * Named on both sides of the wire rather than imported by the extension, for the reason every one of
+ * these names is written out twice: `agents/` is loaded by Pi's module loader and `src/` by tsc, so a
+ * relative import across the two would resolve differently under each. `scripts/task-tool.test.mjs`
+ * asserts the two copies agree, because a rename on one side would otherwise fail at dispatch time with a
+ * message nobody reads.
+ */
+export const TASK_CAPABILITY_ENV = "SUPER_PI_TASK_CAPABILITY";
+/**
+ * The live capability per conversation, while that conversation's primary turn is running.
+ *
+ * Keyed by CONVERSATION rather than being one global token, so two conversations being driven at once
+ * cannot dispatch as each other and so releasing one turn's capability cannot revoke another's. The value
+ * is replaced rather than accumulated: a conversation has one primary turn in flight, and a second spawn
+ * for the same conversation supersedes the first.
+ */
+const live = new Map();
+/** A fixed capability, for tests. See `seededCapability` for why this does not weaken anything. */
+const SEED = process.env.SUPER_PI_TASK_CAPABILITY_SEED;
+/** Announced once, because a capability that silently stopped rotating is a security change nobody agreed to. */
+let warnedSeed = false;
+/**
+ * Mints the capability for one turn of one conversation, and returns it for the extension's environment.
+ *
+ * CALLED AT SPAWN, so the value is decided before the child exists and cannot be changed underneath it.
+ * A turn that never reaches the spawn mints nothing, which is correct: there is no process to hand it to.
+ *
+ * ROTATED EVERY TURN, and that is the property the duration would not give on its own. A token valid for
+ * the whole server lifetime would still be a token an unrelated process could not guess - but a token
+ * valid only while its holder is alive is a token that stops being a credential the moment the turn ends,
+ * so there is no window in which a leaked value is still live.
+ */
+export function mintCapability(conversationId) {
+    if (SEED) {
+        if (!warnedSeed) {
+            warnedSeed = true;
+            console.warn(`Super Pi: SUPER_PI_TASK_CAPABILITY_SEED is set, so every dispatch capability is the same fixed value instead of being minted per turn. This is for tests - set it only on a server nothing else can reach.`);
+        }
+        live.set(conversationId, SEED);
+        return SEED;
+    }
+    const token = randomUUID();
+    live.set(conversationId, token);
+    return token;
+}
+/**
+ * Forgets a conversation's capability, at the end of its turn.
+ *
+ * CALLED FROM `answer()`'s `finally`, so it runs on every exit - a turn that answered, a turn that threw,
+ * and a turn whose child was killed. A capability that outlived its turn would keep working for a process
+ * that no longer exists, which is precisely the shape of a credential with no owner.
+ */
+export function releaseCapability(conversationId) {
+    live.delete(conversationId);
+}
+/** Forgets every capability. Called on shutdown, so nothing survives the process that minted it. */
+export function releaseAllCapabilities() {
+    live.clear();
+}
+/**
+ * The capability currently valid for a conversation, or `undefined` when no primary turn is running.
+ *
+ * Exported for the endpoint's own diagnostics and for a test that needs to assert the lifecycle without
+ * reading a primary turn's environment. Not exported as a way to READ a conversation's capability and use
+ * it - a caller in this process is already inside the trust boundary it protects.
+ */
+export function capabilityFor(conversationId) {
+    return live.get(conversationId);
+}
+/**
+ * Checks a presented capability against the one this conversation's turn was given.
+ *
+ * `timingSafeEqual` rather than `===`, because `===` on a token short-circuits at the first differing byte
+ * and turns the comparison into a timing oracle for the value itself. The length check runs first because
+ * `timingSafeEqual` throws on mismatched lengths rather than returning false.
+ *
+ * THE MESSAGE NAMES BOTH HALVES OF THE PROBLEM, because the reader is a model about to retry and there
+ * are two genuinely different failures here. A conversation with no live capability is being dispatched
+ * from OUTSIDE a turn - the request never came from a primary agent. A conversation with one, and the
+ * presented value does not match it, is a turn whose value was not carried through. An extension that
+ * silently omitted the header would otherwise be indistinguishable from an attacker, and would keep
+ * retrying forever.
+ */
+export function verifyCapability(conversationId, presented) {
+    // A seeded server accepts its fixed value for EVERY conversation, including one with no turn running.
+    // That relaxation is exactly the test affordance and nothing else: `SEED` is documented as test-only,
+    // and a process that can set it could set `SUPER_PI_ACCESS_TOKEN` instead and already have full control.
+    // The comparison below is still real - a wrong value is still refused - so a seeded server still catches
+    // a request that simply forgot the capability, which is the mistake a real extension is most likely to make.
+    const expected = live.get(conversationId) ?? SEED;
+    if (!expected) {
+        return {
+            ok: false,
+            message: `No primary turn is running for conversation ${conversationId}, so there is nothing that could have dispatched this. Dispatch happens from inside a turn: send the tool call during a turn rather than posting to the server directly.`,
+        };
+    }
+    if (typeof presented !== "string" || !presented) {
+        return { ok: false, message: `This dispatch carries no ${TASK_CAPABILITY_ENV}. The capability is passed from the primary agent's own environment; a request without it did not come from one. Do not retry the same call - it is not a transient failure.` };
+    }
+    const left = Buffer.from(expected);
+    const right = Buffer.from(presented);
+    if (left.length !== right.length || !timingSafeEqual(left, right)) {
+        return { ok: false, message: `The ${TASK_CAPABILITY_ENV} presented does not match the one this turn was given. It is minted per turn, so a value from an earlier turn - or from another conversation - is not accepted. Do not retry the same call.` };
+    }
+    return { ok: true };
+}

package/dist/server/command-handler.js

@@ -113,6 +113,10 @@ export class CommandHandler {
             this.runService.stopSubagent(command.runId);
             return;
         }
+        if (command.type === "workflow.stop") {
+            this.runService.stopWorkflow(command.workflowId);
+            return;
+        }
         if (command.type === "extension.ui.answer") {
             const answer = command.cancelled
                 ? { cancelled: true }
@@ -132,6 +136,14 @@ export class CommandHandler {
             await this.catalogService.broadcastSubagents();
             return;
         }
+        if (command.type === "agents.setCustomDirs") {
+            await this.catalogService.setCustomDirs(command.dirs);
+            return;
+        }
+        if (command.type === "agents.rescan") {
+            await this.catalogService.rescan();
+            return;
+        }
         throw new Error(`未知的命令类型：${JSON.stringify(command.type ?? null)}`);
     }
 }

package/dist/server/http-server.js

@@ -76,6 +76,26 @@ export function createHttpServer(options) {
             }
             return;
         }
+        if (url.pathname === "/api/workflow/run") {
+            if (request.method !== "POST" || !isLoopbackAddress(remote)) {
+                response.writeHead(403, { "content-type": "text/plain; charset=utf-8" }).end("Workflow dispatch requires a loopback POST");
+                return;
+            }
+            let raw = "";
+            for await (const chunk of request)
+                raw += chunk;
+            const json = (status, body) => {
+                response.writeHead(status, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify(body));
+            };
+            try {
+                const result = await runService.runWorkflow(JSON.parse(raw));
+                json(result.status, result.body);
+            }
+            catch (error) {
+                json(400, { error: error instanceof Error ? error.message : "workflow dispatch failed" });
+            }
+            return;
+        }
         if (url.pathname === "/api/todos") {
             if (request.method !== "POST" || !isLoopbackAddress(remote)) {
                 response.writeHead(403, { "content-type": "text/plain; charset=utf-8" }).end("Todo writes require a loopback POST");

package/dist/server/index.js

@@ -4,8 +4,11 @@ import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { defaultStorePath, Store } from "./store.js";
 import { PiRpcRuntime, WelcomeRuntime } from "./runtime.js";
+import { resolveAgentDirectories } from "./agents.js";
+import { releaseAllCapabilities } from "./capability.js";
 import { SubagentSupervisor } from "./subagents.js";
 import { SubagentRunRecorder } from "./subagent-runs.js";
+import { WorkflowEngine } from "./workflow-engine.js";
 import { ExtensionUiService } from "./application/extension-ui-service.js";
 import { CatalogService } from "./application/catalog-service.js";
 import { RunService } from "./application/run-service.js";
@@ -22,7 +25,6 @@ const defaultDataDir = !rootDir.includes("node_modules") && existsSync(join(root
     ? join(rootDir, ".super-pi")
     : join(homedir(), ".super-pi");
 const dataDir = resolve(process.env.SUPER_PI_DATA_DIR ?? defaultDataDir);
-const agentsDir = resolve(process.env.SUPER_PI_AGENTS_DIR ?? join(rootDir, "agents"));
 const agentPromptDir = join(dataDir, "agent-prompts");
 const clientDir = join(rootDir, "dist", "client");
 const accessToken = process.env.SUPER_PI_ACCESS_TOKEN;
@@ -30,23 +32,30 @@ const uploadsDir = join(dataDir, "uploads");
 await mkdir(uploadsDir, { recursive: true }).catch(() => { });
 const taskEndpoint = `http://${host === "0.0.0.0" ? "127.0.0.1" : host}:${port}/api/subagent/dispatch`;
 const todoEndpoint = `http://${host === "0.0.0.0" ? "127.0.0.1" : host}:${port}/api/todos`;
+const workflowEndpoint = `http://${host === "0.0.0.0" ? "127.0.0.1" : host}:${port}/api/workflow/run`;
+// ------------------------------------------------------------- Core singletons
+const store = await Store.open(defaultStorePath(dataDir));
+const initialAgentDirs = resolveAgentDirectories({
+    customDirs: store.snapshot().customAgentDirs,
+    rootDir,
+});
+const agentsDir = initialAgentDirs[0] ?? resolve(process.env.SUPER_PI_AGENTS_DIR ?? join(rootDir, "agents"));
 const paths = {
     dataDir,
     rootDir,
     agentsDir,
+    agentDirs: initialAgentDirs,
     agentPromptDir,
     uploadsDir,
     clientDir,
 };
-// ------------------------------------------------------------- Core singletons
-const store = await Store.open(defaultStorePath(dataDir));
 const runtime = process.env.SUPER_PI_RUNTIME === "welcome"
     ? new WelcomeRuntime()
-    : new PiRpcRuntime(join(dataDir, "pi-sessions"), undefined, { dir: agentsDir, promptDir: agentPromptDir }, { endpoint: taskEndpoint, todoEndpoint, uploadsDir });
+    : new PiRpcRuntime(join(dataDir, "pi-sessions"), undefined, { dir: initialAgentDirs, promptDir: agentPromptDir }, { endpoint: taskEndpoint, todoEndpoint, workflowEndpoint, uploadsDir });
 const broadcaster = new WsBroadcaster(() => store.snapshot());
 const extensionUiService = new ExtensionUiService(broadcaster);
 const supervisor = new SubagentSupervisor(join(dataDir, "pi-sessions"), undefined, {
-    dir: agentsDir,
+    dir: initialAgentDirs,
     promptDir: agentPromptDir,
 });
 const subagents = new SubagentRunRecorder(supervisor, {
@@ -58,11 +67,38 @@ const subagents = new SubagentRunRecorder(supervisor, {
     },
     host: (conversationId, runId) => extensionUiService.createHost(conversationId, runId),
 });
+/**
+ * The orchestration engine: walks a whole plan the primary agent declared, dispatching each step through
+ * the recorder above and handing each step's output to the next.
+ *
+ * Broadcasts `workflow.event` AND the full state, exactly as the recorder does for `subagent.event`. The
+ * extra state frame is what puts a plan into `AppState.workflows`, so a browser that reloads mid-plan
+ * rebuilds the timeline from the file rather than from the events it happened to receive - the same reason
+ * a run's card survives a refresh. It costs nothing in practice because the engine publishes twice per
+ * step rather than per delta.
+ */
+const workflows = new WorkflowEngine(subagents, {
+    store,
+    broadcast: (event) => {
+        broadcaster.broadcast(event);
+        if (event.type === "workflow.event")
+            broadcaster.broadcastState();
+    },
+});
 // ------------------------------------------------------------- Application services
-const catalogService = new CatalogService(runtime, broadcaster, agentsDir);
-const runService = new RunService(store, runtime, subagents, broadcaster, extensionUiService);
-const conversationService = new ConversationService(store, runtime, subagents, broadcaster, catalogService, runService, extensionUiService, agentsDir);
-const workspaceService = new WorkspaceService(store, runtime, broadcaster, catalogService, runService, extensionUiService, uploadsDir, agentsDir);
+const onDirsChanged = (dirs) => {
+    paths.agentDirs = dirs;
+    paths.agentsDir = dirs[0] ?? "";
+    runtime.setAgentsDir?.(dirs);
+    subagents.setAgentsDir(dirs);
+    runService.setAgentsDir(dirs);
+    conversationService.setAgentsDir(dirs);
+    workspaceService.setAgentsDir(dirs);
+};
+const catalogService = new CatalogService(runtime, broadcaster, initialAgentDirs, store, rootDir, onDirsChanged);
+const runService = new RunService(store, runtime, subagents, broadcaster, extensionUiService, initialAgentDirs, workflows);
+const conversationService = new ConversationService(store, runtime, subagents, broadcaster, catalogService, runService, extensionUiService, initialAgentDirs);
+const workspaceService = new WorkspaceService(store, runtime, broadcaster, catalogService, runService, extensionUiService, uploadsDir, initialAgentDirs);
 const serverContext = {
     paths,
     store,
@@ -85,6 +121,8 @@ function shutdown(reason) {
     shuttingDown = true;
     console.log(`Super Pi is shutting down (${reason}).`);
     runService.abortAll();
+    workflows.abortAll();
+    releaseAllCapabilities();
     for (const c of store.snapshot().conversations) {
         extensionUiService.cancelPendingUi(c.id, "aborted");
     }

package/dist/server/runtime.d.ts

@@ -199,6 +199,8 @@ export interface AgentRuntime {
      * refusal, exactly as `revert`'s absence is, rather than passed over.
      */
     fork?(request: ForkRequest): Promise<ForkOutcome>;
+    /** Updates the active agent directory or directories to search. */
+    setAgentsDir?(dir: string | string[]): void;
 }
 /** Deterministic offline runtime used by tests and local UI development. */
 export declare class WelcomeRuntime implements AgentRuntime {
@@ -527,7 +529,7 @@ export declare class PiRpcRuntime implements AgentRuntime {
      * call site keeps its meaning - moving the agent directory into that slot would have silently fed a
      * launcher's file path in as a directory of agent definitions.
      */
-    private readonly agents;
+    private agents;
     /**
      * How the `task` extension reaches this server. A FOURTH positional parameter for the same reason as
      * the third: an options bag in one of the earlier slots would silently change what an existing
@@ -587,7 +589,7 @@ export declare class PiRpcRuntime implements AgentRuntime {
      * launcher's file path in as a directory of agent definitions.
      */
     agents?: {
-        dir: string;
+        dir: string | string[];
         promptDir: string;
     }, 
     /**
@@ -612,6 +614,7 @@ export declare class PiRpcRuntime implements AgentRuntime {
     options?: {
         endpoint?: string;
         todoEndpoint?: string;
+        workflowEndpoint?: string;
         uploadsDir?: string;
     });
     /**
@@ -623,6 +626,7 @@ export declare class PiRpcRuntime implements AgentRuntime {
      * as the conversation's own role.
      */
     agentFor(conversation: Pick<Conversation, "id" | "agentId">): Promise<AgentDefinition | undefined>;
+    setAgentsDir(dir: string | string[]): void;
     /**
      * The `--extension` argv for this turn, or `[]` when the task tool is not available.
      *

package/dist/server/runtime.js

@@ -3,8 +3,9 @@ import { mkdir, readFile, rename, stat, writeFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { resolve, join } from "node:path";
 import { agentSpawnArgs, readAgents } from "./agents.js";
+import { TASK_CAPABILITY_ENV, mintCapability, releaseCapability } from "./capability.js";
 import { resolvePiCommand, shellQuote } from "./pi-command.js";
-import { TASK_CONVERSATION_ENV, TASK_DEPTH_ENV, TASK_ENDPOINT_ENV, TASK_ROSTER_ENV, TASK_TOOL_NAME, TODO_ENDPOINT_ENV, TODO_TOOL_NAME, rosterPayload, } from "./task-tool.js";
+import { TASK_CONVERSATION_ENV, TASK_DEPTH_ENV, TASK_ENDPOINT_ENV, TASK_ROSTER_ENV, TASK_TOOL_NAME, TODO_ENDPOINT_ENV, TODO_TOOL_NAME, WORKFLOW_ENDPOINT_ENV, WORKFLOW_TOOL_NAME, rosterPayload, } from "./task-tool.js";
 import { BLOCKING_UI_METHODS, EXTENSION_UI_METHODS, } from "./types.js";
 import { loadConversationImages } from "./upload.js";
 import { describeToolCall, describeToolCallArgs } from "./tool-calls.js";
@@ -630,9 +631,13 @@ export class PiRpcRuntime {
         const agent = agents.find((item) => item.id === conversation.agentId);
         if (agent)
             return agent;
-        console.warn(`PiRpcRuntime: conversation ${conversation.id} names agent ${JSON.stringify(conversation.agentId)}, which is not a primary agent in ${this.agents.dir}${problems.length ? ` (${problems.length} file(s) there are not usable agents)` : ""} - running as Pi itself.`);
+        const dirLabel = Array.isArray(this.agents.dir) ? this.agents.dir.join(", ") : this.agents.dir;
+        console.warn(`PiRpcRuntime: conversation ${conversation.id} names agent ${JSON.stringify(conversation.agentId)}, which is not a primary agent in ${dirLabel}${problems.length ? ` (${problems.length} file(s) there are not usable agents)` : ""} - running as Pi itself.`);
         return undefined;
     }
+    setAgentsDir(dir) {
+        this.agents.dir = dir;
+    }
     /**
      * The `--extension` argv for this turn, or `[]` when the task tool is not available.
      *
@@ -676,13 +681,19 @@ export class PiRpcRuntime {
     async taskExtensionEnv(conversationId) {
         const { agents, problems } = await readAgents(this.agents.dir, { mode: "subagent" });
         for (const problem of problems)
-            console.warn(`PiRpcRuntime: ${this.agents.dir}/${problem.file} is not a usable sub-agent - ${problem.message}`);
+            console.warn(`PiRpcRuntime: ${problem.file} is not a usable sub-agent - ${problem.message}`);
         return {
             [TASK_ENDPOINT_ENV]: this.options.endpoint ?? "",
             [TASK_ROSTER_ENV]: rosterPayload(agents),
             [TASK_CONVERSATION_ENV]: conversationId,
             [TASK_DEPTH_ENV]: "0",
             [TODO_ENDPOINT_ENV]: this.options.todoEndpoint ?? "",
+            [WORKFLOW_ENDPOINT_ENV]: this.options.workflowEndpoint ?? "",
+            // MINTED HERE, AT SPAWN, rather than read from anywhere: this is the only moment the value is
+            // decided, so it cannot change underneath a running child. `SubagentSupervisor` never calls this
+            // function, so no sub-agent process is ever handed a capability - which is what makes a sub-agent
+            // unable to dispatch, however its allowlist is broken.
+            [TASK_CAPABILITY_ENV]: mintCapability(conversationId),
         };
     }
     async *answer({ conversation, prompt, signal, cwd, host, onPiQueue, onUserEntry, onToolCall, onToolEnd, images }) {
@@ -718,7 +729,7 @@ export class PiRpcRuntime {
         // other. They also share the extension's existence - `extensionArgs` is non-empty exactly when
         // `index.ts` is on disk and an endpoint was configured - so there is no case where one is mounted and
         // the other is not.
-        const agentArgs = await agentSpawnArgs(this.agents.promptDir, agent, { extraAllowedTools: extensionArgs.length ? [TASK_TOOL_NAME, TODO_TOOL_NAME] : [] });
+        const agentArgs = await agentSpawnArgs(this.agents.promptDir, agent, { extraAllowedTools: extensionArgs.length ? [TASK_TOOL_NAME, TODO_TOOL_NAME, WORKFLOW_TOOL_NAME] : [] });
         // Refused here, with the reason, rather than handed to the spawn: an ENOENT from `spawn` reads as
         // "the app is broken" and hides the one fact that matters, which is where it looked for Pi.
         if (!this.pi.found)
@@ -930,6 +941,10 @@ export class PiRpcRuntime {
         finally {
             signal.removeEventListener("abort", abort);
             this.runs.delete(conversation.id);
+            // The capability dies with the turn that was given it. In this `finally`, so it happens on every
+            // exit - a turn that answered, a turn that threw, and a turn whose child was killed - because a
+            // credential whose turn has ended is a credential with no owner.
+            releaseCapability(conversation.id);
             // A steer still unanswered when the turn ends is REJECTED, not left pending. The drain loop above
             // is the only reader of this child's stdout and it has stopped, so nothing would ever settle that
             // promise: the caller would wait for a timeout to learn something this process already knows. The

package/dist/server/server-context.d.ts

@@ -14,6 +14,7 @@ export interface ServerPaths {
     dataDir: string;
     rootDir: string;
     agentsDir: string;
+    agentDirs?: string[];
     agentPromptDir?: string;
     uploadsDir: string;
     clientDir: string;

package/dist/server/store.d.ts

@@ -1,3 +1,4 @@
+import type { WorkflowRun } from "./workflow.js";
 import type { AppState, Conversation, Message, MessageImage, ModelSelection, QueuedMessage, SubagentRun, SubagentRunUpdate, TodoItem, ToolCallBlock, Workspace } from "./types.js";
 /** Mints the id a forked conversation will have, BEFORE its Pi transcript exists.
  *
@@ -31,6 +32,17 @@ export declare function newConversationId(): string;
  * re-deriving it.
  */
 export declare const SUBAGENT_RUN_RETENTION = 100;
+/**
+ * How many orchestrated plans are kept.
+ *
+ * SMALLER THAN THE RUN RETENTION, and deliberately so. A plan does not duplicate the runs it executed -
+ * it holds one row per STEP - so fifty plans point at runs that are themselves evicted at 100. Keeping
+ * more plans than runs would leave timelines whose cards have all been trimmed away, which is a worse
+ * outcome than forgetting the plan: an empty timeline reads as "nothing ran" rather than as "the details
+ * aged out". Fifty is also well past what one working day of orchestration produces, since a plan is a
+ * request that needed several specialists rather than a unit of work.
+ */
+export declare const WORKFLOW_RETENTION = 50;
 /**
  * Everything a revert decided, before anything is changed.
  *
@@ -365,6 +377,36 @@ export declare class Store {
      * back on disk, and one that trimmed on read would show a browser a roster the file still holds.
      */
     beginSubagentRun(run: SubagentRun): Promise<SubagentRun>;
+    /**
+     * Writes a whole plan BEFORE step one runs, and persists it.
+     *
+     * THE ORDER THIS EXISTS TO ENFORCE. A plan recorded only as it executes leaves a reload showing
+     * nothing recoverable - which steps were intended, in what order, under which failure policy - because
+     * a transcript of the model asking for a plan is not the plan. Writing it whole first makes the record
+     * a CLAIM the engine then makes good, exactly the relationship a run has to its child process, and it
+     * means an engine that dies mid-plan leaves a document a person can read instead of a gap.
+     *
+     * Steps arrive already in their pending form with empty `attempts`, rather than being built as the
+     * engine reaches them, so what lands on disk before anything runs is the whole intention.
+     *
+     * `structuredClone` on the way out, like `beginSubagentRun`: the engine mutates its own copy on every
+     * transition, and a caller holding a live reference would watch the record change under itself.
+     */
+    beginWorkflow(plan: WorkflowRun): Promise<WorkflowRun>;
+    /**
+     * Replaces a plan wholesale, and persists it.
+     *
+     * THE WHOLE PLAN RATHER THAN A FIELD PATCH, and the reason is that a plan's live state is three moving
+     * parts at once - `currentIndex`, the status of one step, and an appended attempt - so a patch type
+     * narrow enough to be safe for all three is a shape nothing could be typechecked against. Writing the
+     * plan also cannot forget a field, which is the failure a hand-maintained patch list invites as the
+     * plan grows new parts.
+     *
+     * The whole array is cloned before the write, for the same reason the recorder keeps its own copy of a
+     * run (`subagent-runs.ts:170`): the caller mutates the object it is about to hand back here, and a store
+     * that persisted by reference would write out those edits before they were ever announced.
+     */
+    setWorkflow(plan: WorkflowRun): Promise<WorkflowRun>;
     setBackgroundTask(summary: AppState["backgroundTasks"][number]): Promise<void>;
     removeBackgroundTask(id: string): Promise<void>;
     /**
@@ -406,6 +448,12 @@ export declare class Store {
         todos: TodoItem[];
         dropped: number;
     }>;
+    /**
+     * Updates user-configured custom agent discovery directories.
+     * Empty/whitespace paths are ignored, and if no valid paths remain, the key is deleted
+     * to keep state.json clean.
+     */
+    setCustomAgentDirs(dirs: string[]): Promise<string[]>;
     /**
      * Writes the whole state atomically: a temp file, then a rename over the real one.
      *