stageflow 0.36.0 → 0.40.0

package/dist/server/agentRoutes.js

@@ -0,0 +1,323 @@
+import { AgentError, isAgentError } from "../agents/errors.js";
+import { describeToolkit } from "../toolkit/index.js";
+import { isSessionStatus } from "../agents/store.js";
+import { BodyError, readJsonBody, writeFrame } from "../agents/ndjson.js";
+const MAX_BODY_BYTES = 256 * 1024;
+const CONSOLE_ACTOR = { source: "console" };
+async function readBody(req) {
+    try {
+        return await readJsonBody(req, MAX_BODY_BYTES);
+    }
+    catch (error) {
+        if (!(error instanceof BodyError))
+            throw error;
+        throw new AgentError("agent.invalid", error.reason === "too_large" ? "Request body is too large" : error.reason === "not_json" ? "Request body is not JSON" : "Request body must be a JSON object");
+    }
+}
+function requireInt(value, name) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+        throw new AgentError("agent.invalid", `${name} must be a non-negative integer`);
+    }
+    return value;
+}
+function requireText(value, name) {
+    if (typeof value !== "string" || value.trim().length === 0)
+        throw new AgentError("agent.invalid", `${name} is required`);
+    return value.trim();
+}
+function optionalText(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+function sessionQuery(url) {
+    const status = url.searchParams.get("status") ?? undefined;
+    if (status !== undefined && !isSessionStatus(status)) {
+        throw new AgentError("agent.invalid", "Unknown session status");
+    }
+    const limit = Number(url.searchParams.get("limit") ?? 25);
+    return {
+        limit: Number.isInteger(limit) && limit > 0 && limit <= 100 ? limit : 25,
+        ...(status && isSessionStatus(status) ? { status } : {}),
+        ...(url.searchParams.get("source") ? { source: url.searchParams.get("source") } : {}),
+        ...(url.searchParams.get("q")?.trim() ? { search: url.searchParams.get("q").trim() } : {}),
+        ...(url.searchParams.get("cursor") ? { cursor: url.searchParams.get("cursor") } : {}),
+    };
+}
+/** A session must belong to the agent named in the path, or the request is a 404. */
+async function sessionFor(ctx, agentId, sessionId) {
+    const detail = await ctx.host.service.getSession(ctx.projectRoot, sessionId);
+    if (detail.session.agentId !== agentId)
+        throw new AgentError("agent.session_not_found");
+    return detail;
+}
+async function chat(ctx, agentId) {
+    const body = await readBody(ctx.req);
+    const message = requireText(body.message, "message");
+    const sessionId = optionalText(body.sessionId);
+    const wantsStream = body.stream === true || String(ctx.req.headers.accept ?? "").includes("application/x-ndjson");
+    const send = (onDelta, onSessionOpened) => ctx.host.chat.send({
+        projectRoot: ctx.projectRoot,
+        agentId,
+        text: message,
+        source: "console",
+        ...(sessionId ? { sessionId } : {}),
+        ...(onDelta ? { onDelta } : {}),
+        ...(onSessionOpened ? { onSessionOpened } : {}),
+    });
+    if (!wantsStream) {
+        ctx.json(ctx.res, 200, await send());
+        return;
+    }
+    ctx.res.writeHead(200, { "Content-Type": "application/x-ndjson; charset=utf-8", "Cache-Control": "no-store" });
+    let writes = Promise.resolve();
+    let finished = false;
+    let openedId = sessionId;
+    ctx.res.once("close", () => {
+        if (finished)
+            return;
+        if (openedId)
+            ctx.host.chat.stop(openedId);
+        else
+            ctx.host.chat.stopOpening(agentId);
+    });
+    try {
+        const detail = await send((text) => {
+            writes = writes.then(() => writeFrame(ctx.res, { type: "delta", text }));
+        }, (id) => {
+            openedId = id;
+            writes = writes.then(() => writeFrame(ctx.res, { type: "session", sessionId: id }));
+        });
+        finished = true;
+        await writes;
+        await writeFrame(ctx.res, { type: "done", session: detail });
+    }
+    catch (error) {
+        finished = true;
+        await writes.catch(() => undefined);
+        await writeFrame(ctx.res, {
+            type: "error",
+            code: isAgentError(error) ? error.code : "agent.internal",
+            ...(isAgentError(error) && error.message !== error.code ? { message: error.message } : {}),
+        });
+    }
+    finally {
+        if (!ctx.res.writableEnded && !ctx.res.destroyed)
+            ctx.res.end();
+    }
+}
+const routes = [
+    {
+        method: "GET",
+        pattern: /^\/api\/agents$/,
+        handle: async (ctx) => ctx.json(ctx.res, 200, { agents: await ctx.host.service.list(ctx.projectRoot) }),
+    },
+    {
+        method: "POST",
+        pattern: /^\/api\/agents$/,
+        handle: async (ctx) => {
+            const body = await readBody(ctx.req);
+            ctx.json(ctx.res, 201, await ctx.host.service.create(ctx.projectRoot, body.definition, CONSOLE_ACTOR));
+        },
+    },
+    {
+        method: "POST",
+        pattern: /^\/api\/agents\/validate$/,
+        handle: async (ctx) => {
+            const body = await readBody(ctx.req);
+            ctx.json(ctx.res, 200, await ctx.host.service.validate(ctx.projectRoot, body.definition));
+        },
+    },
+    {
+        method: "GET",
+        pattern: /^\/api\/agents\/stageflow-tools$/,
+        handle: async ({ res, json }) => json(res, 200, describeToolkit()),
+    },
+    {
+        method: "GET",
+        pattern: /^\/api\/agents\/([^/]+)\/channel$/,
+        handle: async (ctx) => {
+            const detail = await ctx.host.service.get(ctx.projectRoot, ctx.params[0]);
+            const connectionId = detail.definition?.channel?.connection_id ?? null;
+            // `listener` is absent for webhook providers and for agents that are disabled.
+            const listener = connectionId ? ctx.host.channelListeners?.status(connectionId) : undefined;
+            const failed = ctx.host.service.latestUndelivered(ctx.projectRoot, ctx.params[0]);
+            ctx.json(ctx.res, 200, {
+                connectionId,
+                ...(listener ? { listener } : {}),
+                ...(failed ? { lastUndelivered: { turnId: failed.turnId, sessionId: failed.sessionId, state: failed.state, code: failed.errorCode, message: failed.errorMessage, at: failed.updatedAt } } : {}),
+            });
+        },
+    },
+    {
+        method: "POST",
+        pattern: /^\/api\/agents\/([^/]+)\/sessions\/([^/]+)\/turns\/([^/]+)\/delivery\/(resend|delivered)$/,
+        handle: async (ctx) => {
+            const [agentId, sessionId, turnId, action] = ctx.params;
+            const session = await ctx.host.service.getSession(ctx.projectRoot, sessionId);
+            if (session.session.agentId !== agentId || !session.turns.some((turn) => turn.id === turnId))
+                throw new AgentError("agent.session_not_found");
+            if (action === "resend")
+                await ctx.host.delivery.resend(turnId);
+            else
+                ctx.host.delivery.markDelivered(turnId);
+            ctx.json(ctx.res, 200, await ctx.host.service.getSession(ctx.projectRoot, sessionId));
+        },
+    },
+    {
+        method: "GET",
+        pattern: /^\/api\/agents\/([^/]+)\/channel\/contact$/,
+        handle: async (ctx) => {
+            const detail = await ctx.host.service.get(ctx.projectRoot, ctx.params[0]);
+            const connectionId = detail.definition?.channel?.connection_id;
+            const found = connectionId ? await ctx.host.channelContact(connectionId) : undefined;
+            ctx.json(ctx.res, 200, { connectionId: connectionId ?? null, ...(found ?? {}) });
+        },
+    },
+    {
+        method: "GET",
+        pattern: /^\/api\/agents\/sessions$/,
+        handle: async (ctx) => ctx.json(ctx.res, 200, await ctx.host.service.listAllSessions(ctx.projectRoot, sessionQuery(ctx.url), ctx.url.searchParams.get("agent") || undefined)),
+    },
+    {
+        method: "GET",
+        pattern: /^\/api\/agents\/approvals$/,
+        handle: async (ctx) => ctx.json(ctx.res, 200, { approvals: await ctx.host.service.pendingApprovals(ctx.projectRoot) }),
+    },
+    {
+        method: "GET",
+        pattern: /^\/api\/agents\/([^/]+)$/,
+        handle: async (ctx) => ctx.json(ctx.res, 200, await ctx.host.service.get(ctx.projectRoot, ctx.params[0])),
+    },
+    {
+        method: "POST",
+        pattern: /^\/api\/agents\/([^/]+)\/save$/,
+        handle: async (ctx) => {
+            const body = await readBody(ctx.req);
+            ctx.json(ctx.res, 200, await ctx.host.service.save(ctx.projectRoot, ctx.params[0], {
+                baseRevision: requireInt(body.baseRevision, "baseRevision"),
+                definition: body.definition,
+                summary: optionalText(body.summary) ?? null,
+            }, CONSOLE_ACTOR));
+        },
+    },
+    {
+        method: "POST",
+        pattern: /^\/api\/agents\/([^/]+)\/(enable|disable)$/,
+        handle: async (ctx) => ctx.json(ctx.res, 200, await ctx.host.service.setEnabled(ctx.projectRoot, ctx.params[0], ctx.params[1] === "enable", CONSOLE_ACTOR)),
+    },
+    {
+        method: "POST",
+        pattern: /^\/api\/agents\/([^/]+)\/archive$/,
+        handle: async (ctx) => {
+            await ctx.host.service.archive(ctx.projectRoot, ctx.params[0]);
+            ctx.json(ctx.res, 200, { archived: true });
+        },
+    },
+    {
+        method: "GET",
+        pattern: /^\/api\/agents\/([^/]+)\/revisions$/,
+        handle: async (ctx) => ctx.json(ctx.res, 200, { revisions: await ctx.host.service.listRevisions(ctx.projectRoot, ctx.params[0]) }),
+    },
+    {
+        method: "GET",
+        pattern: /^\/api\/agents\/([^/]+)\/revisions\/(\d+)$/,
+        handle: async (ctx) => ctx.json(ctx.res, 200, await ctx.host.service.getRevision(ctx.projectRoot, ctx.params[0], Number(ctx.params[1]))),
+    },
+    {
+        method: "GET",
+        pattern: /^\/api\/agents\/([^/]+)\/revisions\/(\d+)\/diff\/(\d+)$/,
+        handle: async (ctx) => ctx.json(ctx.res, 200, {
+            lines: await ctx.host.service.diffRevisions(ctx.projectRoot, ctx.params[0], Number(ctx.params[1]), Number(ctx.params[2])),
+        }),
+    },
+    {
+        method: "POST",
+        pattern: /^\/api\/agents\/([^/]+)\/revisions\/(\d+)\/restore$/,
+        handle: async (ctx) => {
+            const body = await readBody(ctx.req);
+            ctx.json(ctx.res, 200, await ctx.host.service.restore(ctx.projectRoot, ctx.params[0], { revision: Number(ctx.params[1]), baseRevision: requireInt(body.baseRevision, "baseRevision") }, CONSOLE_ACTOR));
+        },
+    },
+    {
+        method: "GET",
+        pattern: /^\/api\/agents\/([^/]+)\/sessions$/,
+        handle: async (ctx) => ctx.json(ctx.res, 200, await ctx.host.service.listSessions(ctx.projectRoot, ctx.params[0], sessionQuery(ctx.url))),
+    },
+    {
+        method: "GET",
+        pattern: /^\/api\/agents\/([^/]+)\/sessions\/([^/]+)$/,
+        handle: async (ctx) => ctx.json(ctx.res, 200, await sessionFor(ctx, ctx.params[0], ctx.params[1])),
+    },
+    {
+        method: "GET",
+        pattern: /^\/api\/agents\/([^/]+)\/sessions\/([^/]+)\/otlp$/,
+        handle: async (ctx) => {
+            await sessionFor(ctx, ctx.params[0], ctx.params[1]);
+            ctx.res.setHeader("Content-Disposition", `attachment; filename="${ctx.params[1]}.otlp.json"`);
+            ctx.json(ctx.res, 200, ctx.host.service.exportSessionOtlp(ctx.projectRoot, ctx.params[1]));
+        },
+    },
+    {
+        method: "POST",
+        pattern: /^\/api\/agents\/([^/]+)\/sessions\/([^/]+)\/approval\/(approve|deny)$/,
+        handle: async (ctx) => {
+            await sessionFor(ctx, ctx.params[0], ctx.params[1]);
+            const approval = await ctx.host.service.decideApproval(ctx.projectRoot, ctx.params[1], ctx.params[2] === "approve" ? "approve" : "deny", { kind: "operator" });
+            ctx.json(ctx.res, 200, { approval, session: await sessionFor(ctx, ctx.params[0], ctx.params[1]) });
+        },
+    },
+    {
+        method: "POST",
+        pattern: /^\/api\/agents\/([^/]+)\/chat$/,
+        handle: async (ctx) => chat(ctx, ctx.params[0]),
+    },
+    {
+        method: "POST",
+        pattern: /^\/api\/agents\/([^/]+)\/chat\/stop$/,
+        handle: async (ctx) => {
+            const body = await readBody(ctx.req);
+            const sessionId = requireText(body.sessionId, "sessionId");
+            await sessionFor(ctx, ctx.params[0], sessionId);
+            ctx.json(ctx.res, 200, { stopped: ctx.host.chat.stop(sessionId) });
+        },
+    },
+];
+export async function handleAgentRoutes(req, method, pathname, host, projectRoot, res, json) {
+    for (const route of routes) {
+        const match = route.pattern.exec(pathname);
+        if (!match)
+            continue;
+        if (route.method !== method)
+            continue;
+        try {
+            const params = match.slice(1).map((segment) => decodeURIComponent(segment));
+            await route.handle({ req, res, json, host, projectRoot, params, url: new URL(req.url ?? pathname, "http://agents") });
+        }
+        catch (error) {
+            if (res.headersSent) {
+                if (!res.writableEnded)
+                    res.end();
+                return true;
+            }
+            if (error instanceof URIError) {
+                json(res, 400, { code: "agent.invalid", message: "Malformed path" });
+            }
+            else if (isAgentError(error)) {
+                json(res, error.httpStatus, {
+                    code: error.code,
+                    ...(error.message !== error.code ? { message: error.message } : {}),
+                    ...(error.issues.length > 0 ? { issues: error.issues } : {}),
+                });
+            }
+            else {
+                throw error;
+            }
+        }
+        return true;
+    }
+    const known = routes.some((route) => route.pattern.test(pathname));
+    if (known) {
+        json(res, 405, { code: "agent.method_not_allowed" });
+        return true;
+    }
+    return false;
+}

package/dist/server/bootstrap.d.ts

@@ -10,10 +10,13 @@ import { RunManager } from "../runtime/runManager.js";
 import { emailHostFor } from "../email/host.js";
 import { EmailTriggers } from "../email/triggers.js";
 import { type ChannelService } from "../channels/service.js";
+import { type MemoryHost } from "../memory/host.js";
 import { type RunChangeBus } from "../runtime/runChangeBus.js";
 import { type McpHttpHandler } from "../mcp/server.js";
 import { type HostConfig } from "../config/hostConfig.js";
 import { bootProviderConfig } from "../agent/bootProviderConfig.js";
+import { type AgentHostContext } from "../agents/hostContext.js";
+import type { ConversationBackend } from "../agents/sessions.js";
 export declare const DEFAULT_GC_INTERVAL_MS: number;
 export type StageflowHostOptions = {
     agent: StagePort;
@@ -33,6 +36,7 @@ export type StageflowHostOptions = {
     /** Browser support for the runs this Host executes; defaults to the local host with the live view relay. */
     browser?: StageBrowserSupport;
     emailTriggerQueue?: ConstructorParameters<typeof EmailTriggers>[0]["queue"];
+    agentConversationBackend?: ConversationBackend;
 };
 export type StageflowHostBootstrap = {
     a2a?: A2aHost;
@@ -62,6 +66,10 @@ export type StageflowHostBootstrap = {
     stopEmailSource: () => void;
     /** Connections page read model and background health checks. */
     channels?: ChannelService;
+    /** Named markdown pages under `$STAGEFLOW_HOME/memories`. */
+    memories?: MemoryHost;
+    /** Shared agent store, chat controller, and conversation backend for HTTP/MCP. */
+    agentHost?: AgentHostContext;
     email?: ReturnType<typeof emailHostFor> & {
         triggers: EmailTriggers;
         stop: () => Promise<void>;

package/dist/server/bootstrap.js

@@ -2,7 +2,7 @@ import path from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { createA2aHost } from "../a2a/server.js";
 import { A2aStore } from "../a2a/store.js";
-import { createRunStoreWithConnection } from "../runstore/createStore.js";
+import { createRunStoreWithConnection, sqliteConnectionFromStore } from "../runstore/createStore.js";
 import { resolveA2aConfigPath } from "../a2a/configDiscovery.js";
 import { ensureProjectRootsFromEnv } from "../project/ensureProjectRootsFromEnv.js";
 import { ensureGlobalHome, globalStageflowHome } from "../project/globalHome.js";
@@ -21,6 +21,7 @@ import { EmailSource } from "../runtime/emailSource.js";
 import { emailHostFor, releaseEmailHost } from "../email/host.js";
 import { EmailTriggers } from "../email/triggers.js";
 import { startChannelService } from "../channels/service.js";
+import { memoryHostFor } from "../memory/host.js";
 import { fireTrigger } from "../runtime/triggerRunner.js";
 import { createRunChangeBus, getRunChangeBusFromWrappedStore, isRunStoreWrapped, wrapRunStoreWithChangeBus, } from "../runtime/runChangeBus.js";
 import { createMcpHttpHandler, resolveMcpStateless, } from "../mcp/server.js";
@@ -30,16 +31,9 @@ import { readCursorApiKey } from "../agent/cursorProvider.js";
 import { applyPendingRestoreAtBoot, } from "../runstore/restore.js";
 import { assertTmpdirUsable } from "../runstore/assertTmpdir.js";
 import { logger as rootLogger } from "../logging/logger.js";
+import { getModelCatalog } from "../models/catalog.js";
+import { createAgentHostContext } from "../agents/hostContext.js";
 export const DEFAULT_GC_INTERVAL_MS = 60 * 60 * 1000;
-function sqliteConnectionFromStore(store) {
-    const connection = store.connection;
-    if (connection !== undefined &&
-        connection !== null &&
-        typeof connection.prepare === "function") {
-        return connection;
-    }
-    return undefined;
-}
 /** Parse `STAGEFLOW_GC_INTERVAL_MS`; default 1h; `0` disables. */
 export function gcIntervalMsFromEnv(env = process.env) {
     const raw = env.STAGEFLOW_GC_INTERVAL_MS;
@@ -334,10 +328,33 @@ export async function bootstrapStageflowHost(options) {
     }
     const channels = startChannelService(cwd);
     const stopEmailSource = () => {
+        void agentHost?.stop();
         void emailSource.stop();
         void stopAccountEmail();
         void channels.stop();
     };
+    // Resolve the connected-provider list and the default model once at boot so sync callers see the catalog's answer.
+    void getModelCatalog(cwd)
+        .defaultModel()
+        .catch((error) => bootLog.warn("models.catalog_warm_failed", String(error)));
+    const agentHost = sqliteConnection !== undefined
+        ? createAgentHostContext({
+            cwd,
+            agentDir,
+            connection: sqliteConnection,
+            channels,
+            ...(options.agentConversationBackend ? { backend: options.agentConversationBackend } : {}),
+            listenOnChannels: process.env.STAGEFLOW_AGENT_CHANNEL_LISTENERS !== "0",
+            toolkitDeps: {
+                manager,
+                store,
+                agentDir,
+                projectRoot: rootDir,
+                ...(options.providerAuthContext ? { providerAuthContext: options.providerAuthContext } : {}),
+                ...(providerBoot !== undefined ? { providerBoot } : {}),
+            },
+        })
+        : undefined;
     const mcpStateless = resolveMcpStateless({
         mcpStateless: options.mcpStateless,
     });
@@ -349,6 +366,13 @@ export async function bootstrapStageflowHost(options) {
         runChangeBus,
         providerAuthContext: options.providerAuthContext,
         projectRoot: rootDir,
+        ...(agentHost
+            ? {
+                agentService: agentHost.service,
+                agentChat: agentHost.chat,
+                agentConversationBackend: agentHost.backend,
+            }
+            : {}),
         ...(providerBoot !== undefined ? { providerBoot } : {}),
     }, { mcpStateless });
     return {
@@ -378,7 +402,9 @@ export async function bootstrapStageflowHost(options) {
         stopEmailSource,
         email: { ...emailHost, triggers: emailTriggers, stop: stopAccountEmail },
         channels,
+        memories: memoryHostFor(),
         storeFilesystem,
         workspaceCatalog,
+        ...(agentHost ? { agentHost } : {}),
     };
 }

package/dist/server/controlToken.js

@@ -175,6 +175,10 @@ export class BindRefusedError extends Error {
 function isTriggerWebhookRoute(method, pathname) {
     return method === "POST" && /^\/api\/triggers\/[^/]+\/webhook$/.test(pathname);
 }
+/** Agent webhooks authenticate by the provider's own signature against the connection's inbound secret. */
+function isAgentInboundRoute(method, pathname) {
+    return method === "POST" && /^\/api\/agent-inbound\/[^/]+$/.test(pathname);
+}
 /**
  * Live view routes authenticate themselves: the ticket route checks the bearer
  * scope for the requested mode, and the browser's event stream and input posts
@@ -190,6 +194,10 @@ export function requiredScopeFor(method, pathname) {
         return null;
     if (isTriggerWebhookRoute(method, pathname))
         return null;
+    if (isAgentInboundRoute(method, pathname))
+        return null;
+    if (pathname.startsWith("/api/public/chat/"))
+        return null;
     if (isLiveViewRoute(pathname))
         return null;
     if (pathname === "/api/backup" || pathname.startsWith("/api/backup/")) {

package/dist/server/http.d.ts

@@ -3,11 +3,13 @@ import { type ProviderAuthContext } from "../agent/providerAuth.js";
 import { type LiveViewRoutesOptions } from "./liveViewRoutes.js";
 import { WorkshopChatSessionRegistry } from "../workshop/chatTurn.js";
 import { type AgentPort } from "../operatorAgent/index.js";
-import type { RunStoreKind } from "../runstore/createStore.js";
+import { type RunStoreKind } from "../runstore/createStore.js";
 import type { RunStore } from "../runstore/port.js";
 import type { RunManager } from "../runtime/runManager.js";
 import type { RunChangeBus } from "../runtime/runChangeBus.js";
 import type { StageBrowserSupport } from "../browser/browserHost.js";
+import { type AgentHostContext } from "../agents/hostContext.js";
+import type { ConversationBackend } from "../agents/sessions.js";
 import { EmailTriggers } from "../email/triggers.js";
 import { type AllowedHosts } from "./allowedHosts.js";
 import { type ControlTokens } from "./controlToken.js";
@@ -33,6 +35,7 @@ export type UiServerOptions = {
     browser?: StageBrowserSupport;
     /** Optional AgentPort. Workshop is the caller today; tests inject a fake. */
     workshopOperatorHost?: AgentPort;
+    agentConversationBackend?: ConversationBackend;
 };
 export declare function defaultUiDistDir(): string;
 export type OperatorRouteDeps = {
@@ -61,6 +64,10 @@ export type OperatorRouteDeps = {
      * Defaults to a registry owned by this route surface.
      */
     workshopChatRegistry?: WorkshopChatSessionRegistry;
+    /** Injectable agent chat backend (tests). Defaults to Pi conversation host. */
+    agentConversationBackend?: ConversationBackend;
+    /** Shared with MCP when set by bootstrap. */
+    agentHost?: AgentHostContext;
 };
 /**
  * The full operator-console route surface: REST API (runs, stages,