stageflow 0.33.0 → 0.36.0

package/dist/runtime/triggerRunner.js

@@ -1,8 +1,8 @@
-import path from "node:path";
 import { catalogContextFromStageflow } from "../config/resolveCatalogContext.js";
 import { getCatalogScanPaths } from "../config/browseCatalog.js";
 import { resolveStageflowContext } from "../project/resolveStageflowContext.js";
-import { findCatalogPathById, findTriggerDefinition } from "./triggerCatalog.js";
+import { findCatalogPathById } from "./triggerCatalog.js";
+import { findCatalogTrigger, triggerStoreId, } from "../config/triggerCatalog.js";
 /**
  * Resolves a trigger id to its `*.trigger.yaml` catalog definition, resolves its
  * `pipeline`/`task` refs to catalog files, and starts a real run through
@@ -14,17 +14,22 @@ import { findCatalogPathById, findTriggerDefinition } from "./triggerCatalog.js"
  * dynamic-mode trigger (`task` absent) requires one.
  */
 export async function fireTrigger(triggerId, store, runManager, options = {}) {
-    const cwd = options.cwd ?? process.cwd();
-    const ctx = catalogContextFromStageflow(await resolveStageflowContext(cwd));
-    const scanPaths = await getCatalogScanPaths(ctx);
-    if (!scanPaths) {
-        return { ok: false, reason: "No Stageflow catalog found", status: 404 };
-    }
-    const found = await findTriggerDefinition(scanPaths.triggerPaths, triggerId);
-    if (!found) {
-        return { ok: false, reason: `Trigger not found: ${triggerId}`, status: 404 };
+    const bootCwd = options.cwd ?? process.cwd();
+    const located = await findCatalogTrigger({
+        store,
+        bootCwd,
+        triggerId,
+        projectRootFilter: options.project_root,
+    });
+    if (!located.ok) {
+        return {
+            ok: false,
+            reason: located.reason,
+            status: located.status,
+        };
     }
-    const { path: triggerPath, definition: trigger } = found;
+    const { match } = located;
+    const trigger = match.definition;
     if (!trigger.enabled) {
         return { ok: false, reason: `Trigger is disabled: ${triggerId}`, status: 409 };
     }
@@ -45,6 +50,11 @@ export async function fireTrigger(triggerId, store, runManager, options = {}) {
             code: "trigger.task_required",
         };
     }
+    const ctx = catalogContextFromStageflow(await resolveStageflowContext(match.rootPath));
+    const scanPaths = await getCatalogScanPaths(ctx);
+    if (!scanPaths) {
+        return { ok: false, reason: "No Stageflow catalog found", status: 404 };
+    }
     const pipelinePath = await findCatalogPathById(scanPaths.pipelinePaths, trigger.pipeline);
     if (!pipelinePath) {
         return {
@@ -68,22 +78,19 @@ export async function fireTrigger(triggerId, store, runManager, options = {}) {
     else {
         taskInput = suppliedTask;
     }
-    const projectRoot = ctx.projectRoot ?? undefined;
-    const definitionRef = projectRoot !== undefined
-        ? path.relative(projectRoot, triggerPath).replace(/\\/g, "/")
-        : triggerPath;
+    const storeId = triggerStoreId(match.project_root, trigger.id);
     await store.upsertTrigger({
-        id: triggerId,
-        definitionRef,
+        id: storeId,
+        definitionRef: match.definition_ref,
         enabled: trigger.enabled,
     });
     const started = await runManager.startRun({
         pipeline: pipelinePath,
         task: taskInput,
-        ...(projectRoot !== undefined ? { projectRoot } : {}),
+        projectRoot: match.rootPath,
     });
     if (started.ok) {
-        await store.recordTriggerFired(triggerId, started.runId);
+        await store.recordTriggerFired(storeId, started.runId);
     }
     return started;
 }

package/dist/runtime/webhookAccept.d.ts

@@ -0,0 +1,25 @@
+import type { TaskFile } from "../types/task.js";
+import type { TriggerFile } from "../types/trigger.js";
+export type WebhookHeaderMap = {
+    readonly [name: string]: string | string[] | undefined;
+};
+export type WebhookAcceptResult = {
+    kind: "not_configured";
+} | {
+    kind: "bad_signature";
+} | {
+    kind: "bad_json";
+    error: "Invalid JSON body" | "Invalid JSON body: expected an object";
+} | {
+    kind: "no_match";
+} | {
+    kind: "fire";
+    task?: TaskFile;
+};
+export declare function acceptWebhook(input: {
+    trigger: TriggerFile;
+    rawBody: Buffer;
+    headers: WebhookHeaderMap;
+    env: NodeJS.ProcessEnv;
+    now?: () => number;
+}): WebhookAcceptResult;

package/dist/runtime/webhookAccept.js

@@ -0,0 +1,56 @@
+import { readSecretFromEnvOrFile } from "../config/secretFromEnvOrFile.js";
+import { matchesEventFilter } from "./triggerEventMatch.js";
+import { verifyHmacSignature } from "./webhookSignature.js";
+export function acceptWebhook(input) {
+    const { trigger, rawBody, headers, env } = input;
+    const now = input.now ?? Date.now;
+    const config = trigger.event?.config;
+    const secretRef = typeof config?.secretRef === "string" ? config.secretRef : undefined;
+    const header = typeof config?.header === "string" ? config.header : undefined;
+    if (secretRef === undefined || header === undefined) {
+        return { kind: "not_configured" };
+    }
+    const scheme = config?.scheme === "base64" ? "base64" : "hex";
+    let secret;
+    try {
+        secret = readSecretFromEnvOrFile(env, secretRef);
+    }
+    catch {
+        secret = undefined;
+    }
+    if (secret === undefined) {
+        return { kind: "not_configured" };
+    }
+    const headerValue = headers[header.toLowerCase()];
+    const signature = Array.isArray(headerValue) ? headerValue[0] : headerValue;
+    if (typeof signature !== "string" ||
+        signature.length === 0 ||
+        !verifyHmacSignature(rawBody, signature, secret, scheme)) {
+        return { kind: "bad_signature" };
+    }
+    let payload;
+    try {
+        payload = rawBody.length === 0 ? {} : JSON.parse(rawBody.toString("utf8"));
+    }
+    catch {
+        return { kind: "bad_json", error: "Invalid JSON body" };
+    }
+    if (payload === null || typeof payload !== "object" || Array.isArray(payload)) {
+        return { kind: "bad_json", error: "Invalid JSON body: expected an object" };
+    }
+    const payloadRecord = payload;
+    if (!matchesEventFilter(trigger.event?.match, payloadRecord)) {
+        return { kind: "no_match" };
+    }
+    if (trigger.task !== undefined) {
+        return { kind: "fire" };
+    }
+    return {
+        kind: "fire",
+        task: {
+            id: `${trigger.id}-webhook-${now()}`,
+            goal: `Handle webhook event for trigger "${trigger.id}"`,
+            input: payloadRecord,
+        },
+    };
+}

package/dist/server/bootstrap.d.ts

@@ -1,19 +1,22 @@
 import { type A2aHost } from "../a2a/server.js";
-import type { AgentPort } from "../agent/port.js";
+import type { StagePort } from "../agent/port.js";
 import type { ProviderAuthContext } from "../agent/providerAuth.js";
 import { type RunStoreKind } from "../runstore/createStore.js";
+import { type WorkspaceProvisionResult } from "../project/workspaceCatalog.js";
 import type { RunStore } from "../runstore/port.js";
 import type { StoreFilesystemClassification } from "../runstore/storeFilesystem.js";
+import type { StageBrowserSupport } from "../browser/browserHost.js";
 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 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";
 export declare const DEFAULT_GC_INTERVAL_MS: number;
 export type StageflowHostOptions = {
-    agent: AgentPort;
+    agent: StagePort;
     cwd?: string;
     agentDir?: string;
     rootDir?: string;
@@ -27,6 +30,8 @@ export type StageflowHostOptions = {
     hostConfig?: HostConfig;
     /** Skip HostConfig load (tests that inject store/manager pieces only). */
     skipHostConfig?: boolean;
+    /** 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"];
 };
 export type StageflowHostBootstrap = {
@@ -48,12 +53,15 @@ export type StageflowHostBootstrap = {
     /** Periodic retention GC handle when enabled; already `.unref()`'d. */
     gcInterval?: NodeJS.Timeout;
     stopGcInterval: () => void;
+    workspaceCatalog?: WorkspaceProvisionResult;
     /** Stops the schedule-trigger tick loop started at boot. */
     stopScheduleSource: () => void;
     /** Stops the GitHub poll-trigger loop started at boot. */
     stopGithubPollSource: () => void;
     /** Stops the email-trigger IMAP/IDLE listeners started at boot. */
     stopEmailSource: () => void;
+    /** Connections page read model and background health checks. */
+    channels?: ChannelService;
     email?: ReturnType<typeof emailHostFor> & {
         triggers: EmailTriggers;
         stop: () => Promise<void>;

package/dist/server/bootstrap.js

@@ -4,12 +4,15 @@ import { createA2aHost } from "../a2a/server.js";
 import { A2aStore } from "../a2a/store.js";
 import { createRunStoreWithConnection } from "../runstore/createStore.js";
 import { resolveA2aConfigPath } from "../a2a/configDiscovery.js";
-import { ensureGlobalHome } from "../project/globalHome.js";
+import { ensureProjectRootsFromEnv } from "../project/ensureProjectRootsFromEnv.js";
+import { ensureGlobalHome, globalStageflowHome } from "../project/globalHome.js";
+import { ensureWorkspaceCatalog, } from "../project/workspaceCatalog.js";
 import { resolveStageflowContext } from "../project/resolveStageflowContext.js";
 import { findProjectRoot } from "../project/findProjectRoot.js";
 import { warnDurableRootDiskIfNeeded } from "../runstore/diskUsage.js";
 import { assertStoreFilesystemSupported } from "../runstore/storeFilesystem.js";
 import { assertStoreQuickCheck, isSqliteCorruptError, maybeCheckpointResidualWal, rethrowAsStoreIntegrityFailed, } from "../runstore/sqlite/applyStorePragmas.js";
+import { consoleStageBrowserSupport } from "../browser/stageBrowserEnv.js";
 import { RunManager } from "../runtime/runManager.js";
 import { PI_CODING_AGENT_DIR_ENV } from "../runtime/stageRoots.js";
 import { ScheduleSource, triggerTickIntervalMsFromEnv, } from "../runtime/scheduleSource.js";
@@ -17,6 +20,7 @@ import { GithubPollSource, githubPollIntervalMsFromEnv, } from "../runtime/githu
 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 { fireTrigger } from "../runtime/triggerRunner.js";
 import { createRunChangeBus, getRunChangeBusFromWrappedStore, isRunStoreWrapped, wrapRunStoreWithChangeBus, } from "../runtime/runChangeBus.js";
 import { createMcpHttpHandler, resolveMcpStateless, } from "../mcp/server.js";
@@ -82,6 +86,7 @@ export async function bootstrapStageflowHost(options) {
     const invocationCwd = options.cwd ?? process.cwd();
     const ctx = await resolveStageflowContext(invocationCwd);
     const cwd = ctx.invocationCwd;
+    void globalStageflowHome();
     ensureGlobalHome();
     const cursorKey = readCursorApiKey(env);
     if (cursorKey !== undefined &&
@@ -227,6 +232,11 @@ export async function bootstrapStageflowHost(options) {
     }
     const runChangeBus = options.runChangeBus ?? boundBus ?? createRunChangeBus();
     const store = wrapRunStoreWithChangeBus(rawStore, runChangeBus);
+    await ensureProjectRootsFromEnv(env, store);
+    const workspaceCatalog = ensureWorkspaceCatalog(ctx.globalHome);
+    if (!workspaceCatalog.ok) {
+        bootLog.warn("workspace.provision_failed", workspaceCatalog.reason ?? "unknown");
+    }
     const manager = new RunManager({
         agent: options.agent,
         cwd,
@@ -245,6 +255,7 @@ export async function bootstrapStageflowHost(options) {
         ])),
         operatorCatalog: { cwd, agentDir },
         a2aStore,
+        browser: options.browser ?? consoleStageBrowserSupport(),
     });
     await manager.attachWaitingStages();
     await manager.reconcileOrphanedStages();
@@ -269,6 +280,9 @@ export async function bootstrapStageflowHost(options) {
             const result = await fireTrigger(event.triggerId, store, manager, {
                 cwd,
                 task: event.task,
+                ...(event.project_root !== undefined
+                    ? { project_root: event.project_root }
+                    : {}),
             });
             if (!result.ok) {
                 bootLog.error("trigger.fire_failed", `trigger "${event.triggerId}" fire failed: ${result.reason}`);
@@ -318,9 +332,11 @@ export async function bootstrapStageflowHost(options) {
         await Promise.all([stopAccountEmail(), emailSource.stop(), scheduleSource.stop(), githubPollSource.stop()]);
         throw error;
     }
+    const channels = startChannelService(cwd);
     const stopEmailSource = () => {
         void emailSource.stop();
         void stopAccountEmail();
+        void channels.stop();
     };
     const mcpStateless = resolveMcpStateless({
         mcpStateless: options.mcpStateless,
@@ -361,6 +377,8 @@ export async function bootstrapStageflowHost(options) {
         stopGithubPollSource,
         stopEmailSource,
         email: { ...emailHost, triggers: emailTriggers, stop: stopAccountEmail },
+        channels,
         storeFilesystem,
+        workspaceCatalog,
     };
 }

package/dist/server/channelRoutes.d.ts

@@ -0,0 +1,9 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { ChannelService } from "../channels/service.js";
+type Json = (res: ServerResponse, status: number, body: unknown) => void;
+/**
+ * Listing, live checks and edits. Request bodies carry secret values on the way in only; nothing
+ * the API returns contains one, and failures answer with a code, never the request or its values.
+ */
+export declare function handleChannelRoutes(req: IncomingMessage, method: string, pathname: string, service: ChannelService, res: ServerResponse, json: Json): Promise<boolean>;
+export {};

package/dist/server/channelRoutes.js

@@ -0,0 +1,88 @@
+import { ChannelError } from "../channels/errors.js";
+import { channelErrorStatus } from "../channels/errorInfo.js";
+const MAX_BODY_BYTES = 65536;
+async function readBody(req) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        const buffer = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+        size += buffer.length;
+        if (size > MAX_BODY_BYTES)
+            throw new ChannelError("CHANNEL_RESOURCE_LIMIT");
+        chunks.push(buffer);
+    }
+    if (chunks.length === 0)
+        return {};
+    try {
+        return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    }
+    catch {
+        throw new ChannelError("CHANNEL_INVALID_INPUT");
+    }
+}
+/**
+ * Listing, live checks and edits. Request bodies carry secret values on the way in only; nothing
+ * the API returns contains one, and failures answer with a code, never the request or its values.
+ */
+export async function handleChannelRoutes(req, method, pathname, service, res, json) {
+    const idMatch = pathname.match(/^\/api\/connections\/([^/]+)(?:\/(check|validate-target))?$/);
+    const isCollection = pathname === "/api/connections";
+    const isTest = pathname === "/api/connections/test";
+    const isMeta = pathname === "/api/connections/meta";
+    if (!isCollection && !isTest && !isMeta && !idMatch)
+        return false;
+    try {
+        if (isMeta && method === "GET") {
+            json(res, 200, service.meta());
+            return true;
+        }
+        if (isCollection && method === "GET") {
+            json(res, 200, service.list());
+            return true;
+        }
+        if (isCollection && method === "POST") {
+            json(res, 201, await service.create(await readBody(req)));
+            return true;
+        }
+        if (isTest && method === "POST") {
+            json(res, 200, await service.test(await readBody(req)));
+            return true;
+        }
+        if (idMatch) {
+            let id;
+            try {
+                id = decodeURIComponent(idMatch[1]);
+            }
+            catch {
+                throw new ChannelError("CHANNEL_INVALID_INPUT");
+            }
+            if (idMatch[2] === "check" && method === "POST") {
+                const health = await service.checkNow(id);
+                if (health)
+                    json(res, 200, health);
+                else
+                    json(res, 404, { code: "CHANNEL_NOT_FOUND" });
+                return true;
+            }
+            if (idMatch[2] === "validate-target" && method === "POST") {
+                json(res, 200, service.validateTarget(id, await readBody(req)));
+                return true;
+            }
+            if (!idMatch[2] && method === "PATCH") {
+                json(res, 200, await service.update(id, await readBody(req)));
+                return true;
+            }
+            if (!idMatch[2] && method === "DELETE") {
+                await service.remove(id);
+                json(res, 200, { removed: true });
+                return true;
+            }
+        }
+    }
+    catch (error) {
+        const code = error instanceof ChannelError ? error.code : "CHANNEL_STORAGE_FAILED";
+        json(res, channelErrorStatus(code), { code });
+        return true;
+    }
+    return false;
+}

package/dist/server/controlToken.d.ts

@@ -27,7 +27,7 @@ export declare function hasDriveToken(tokens: ControlTokens): boolean;
 export declare function hasAnyToken(tokens: ControlTokens): boolean;
 export declare function isLoopbackBind(bind: string): boolean;
 export declare function refuseBindMessage(bind: string): string;
-export declare function assertBindAllowed(bind: string, tokens: ControlTokens): void;
+export declare function assertBindAllowed(bind: string, tokens: ControlTokens, env?: NodeJS.ProcessEnv): void;
 export declare class BindRefusedError extends Error {
     readonly exitCode = 1;
     constructor(message: string);

package/dist/server/controlToken.js

@@ -1,6 +1,7 @@
 import { createHash, timingSafeEqual } from "node:crypto";
 import { readSecretFromEnvOrFile } from "../config/secretFromEnvOrFile.js";
 import { isLoopbackHostname } from "./allowedHosts.js";
+import { matchLiveViewRoute } from "./liveViewPath.js";
 const CONTROL_TOKEN_PREFIX = "STAGEFLOW_CONTROL_TOKEN_";
 const DEFAULT_CALLER_ID = "default";
 function digest(value) {
@@ -144,9 +145,14 @@ Set one of:
   STAGEFLOW_CONTROL_TOKEN_<NAME>=<at least 32 characters>
 
 Or bind to loopback instead:
-  --host 127.0.0.1   (or unset STAGEFLOW_BIND)`;
+  --host 127.0.0.1   (or unset STAGEFLOW_BIND)
+
+Or, only when the published port stays on this machine:
+  STAGEFLOW_ALLOW_UNAUTHENTICATED_BIND=1`;
 }
-export function assertBindAllowed(bind, tokens) {
+export function assertBindAllowed(bind, tokens, env = process.env) {
+    if (env.STAGEFLOW_ALLOW_UNAUTHENTICATED_BIND === "1")
+        return;
     if (!isLoopbackBind(bind) && !hasDriveToken(tokens)) {
         throw new BindRefusedError(refuseBindMessage(bind));
     }
@@ -169,6 +175,14 @@ export class BindRefusedError extends Error {
 function isTriggerWebhookRoute(method, pathname) {
     return method === "POST" && /^\/api\/triggers\/[^/]+\/webhook$/.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
+ * carry a ticket-derived cookie instead of a bearer token.
+ */
+function isLiveViewRoute(pathname) {
+    return matchLiveViewRoute(pathname) !== null;
+}
 export function requiredScopeFor(method, pathname) {
     if (pathname === "/mcp")
         return "drive";
@@ -176,6 +190,8 @@ export function requiredScopeFor(method, pathname) {
         return null;
     if (isTriggerWebhookRoute(method, pathname))
         return null;
+    if (isLiveViewRoute(pathname))
+        return null;
     if (pathname === "/api/backup" || pathname.startsWith("/api/backup/")) {
         return "drive";
     }

package/dist/server/healthSurfaces.d.ts

@@ -1,5 +1,17 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
+import { type CatalogRoot, type ResolveCatalogRootsOptions } from "../config/resolveCatalogRoots.js";
 import type { StageflowHostBootstrap } from "./bootstrap.js";
+export type CatalogRootApiRecord = {
+    project_root: string;
+    kind: CatalogRoot["kind"];
+    label: string;
+    read_only: boolean;
+    available: boolean;
+    unavailable_reason?: string;
+};
+export declare function catalogRootLabel(root: CatalogRoot): string;
+export declare function mapCatalogRootForApi(root: CatalogRoot): CatalogRootApiRecord;
+export declare function listCatalogRootsForApi(options: ResolveCatalogRootsOptions): Promise<CatalogRootApiRecord[]>;
 export declare function handleLivez(_req: IncomingMessage, res: ServerResponse): void;
 export declare function handleReadyz(_req: IncomingMessage, res: ServerResponse, boot: StageflowHostBootstrap): Promise<void>;
 export declare function buildRichHealthPayload(boot: StageflowHostBootstrap): Promise<Record<string, unknown>>;

package/dist/server/healthSurfaces.js

@@ -1,12 +1,37 @@
+import path from "node:path";
 import { getAuthStatus, } from "../agent/providerAuth.js";
 import { PACKAGE_VERSION, BUILD_SHA } from "../package-meta.js";
 import { globalStageflowHome } from "../project/globalHome.js";
 import { redactHostConfig } from "../config/hostConfig.js";
-import { resolveCatalogRoots } from "../config/resolveCatalogRoots.js";
+import { resolveCatalogRoots, } from "../config/resolveCatalogRoots.js";
 import { json } from "./createHttpHost.js";
 import { livezBody, probeGitVersion, readSchemaHealth, runReadyzChecks, } from "../diagnostics/checks.js";
 import { buildEgressHealth } from "../net/proxy.js";
 import { toolchainHealthMap } from "../preflight/toolchain.js";
+export function catalogRootLabel(root) {
+    if (root.kind === "workspace")
+        return "Workspace";
+    if (root.kind === "seeded")
+        return "Examples (read-only)";
+    const base = path.basename(root.path.replace(/\\/g, "/"));
+    return base || root.project_root;
+}
+export function mapCatalogRootForApi(root) {
+    return {
+        project_root: root.project_root,
+        kind: root.kind,
+        label: catalogRootLabel(root),
+        read_only: root.read_only,
+        available: root.available !== false,
+        ...(root.available === false && root.unavailable_reason
+            ? { unavailable_reason: root.unavailable_reason }
+            : {}),
+    };
+}
+export async function listCatalogRootsForApi(options) {
+    const roots = await resolveCatalogRoots(options);
+    return roots.map(mapCatalogRootForApi);
+}
 function bootProvidersSnapshot(providerBoot) {
     return providerBoot
         ? {
@@ -101,11 +126,7 @@ export async function buildRichHealthPayload(boot) {
         toolchain: toolchainHealthMap(),
         store_filesystem: boot.storeFilesystem ?? null,
         egress: buildEgressHealth(),
-        catalog_roots: catalogRoots.map((r) => ({
-            project_root: r.project_root,
-            kind: r.kind,
-            read_only: r.read_only,
-        })),
+        catalog_roots: catalogRoots.map(mapCatalogRootForApi),
         boot_providers,
         providers_live,
         providers: boot_providers,

package/dist/server/http.d.ts

@@ -1,18 +1,20 @@
-import type { AgentPort } from "../agent/port.js";
+import type { StagePort } from "../agent/port.js";
 import { type ProviderAuthContext } from "../agent/providerAuth.js";
+import { type LiveViewRoutesOptions } from "./liveViewRoutes.js";
 import { WorkshopChatSessionRegistry } from "../workshop/chatTurn.js";
-import { type OperatorAgentHost } from "../operatorAgent/index.js";
+import { type AgentPort } from "../operatorAgent/index.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 { EmailTriggers } from "../email/triggers.js";
 import { type AllowedHosts } from "./allowedHosts.js";
 import { type ControlTokens } from "./controlToken.js";
 import { DEFAULT_PORT, type HttpHostEnvelope, type HttpHostRouteContext } from "./createHttpHost.js";
 import { type ShutdownController } from "./shutdown.js";
 export type UiServerOptions = {
-    agent: AgentPort;
+    agent: StagePort;
     cwd?: string;
     agentDir?: string;
     rootDir?: string;
@@ -28,8 +30,9 @@ export type UiServerOptions = {
     runChangeBus?: RunChangeBus;
     allowedHosts?: AllowedHosts;
     controlTokens?: ControlTokens;
-    /** Optional Workshop Operator Agent Host (fake in tests). */
-    workshopOperatorHost?: OperatorAgentHost;
+    browser?: StageBrowserSupport;
+    /** Optional AgentPort. Workshop is the caller today; tests inject a fake. */
+    workshopOperatorHost?: AgentPort;
 };
 export declare function defaultUiDistDir(): string;
 export type OperatorRouteDeps = {
@@ -43,14 +46,16 @@ export type OperatorRouteDeps = {
     uiDistDir?: string;
     allowedHosts?: AllowedHosts;
     controlTokens?: ControlTokens;
+    /** Test seams for live view (fake relay, clock, audit sink); production builds everything from persisted state. */
+    liveView?: Omit<LiveViewRoutesOptions, "store" | "controlTokens">;
     /** Live shutdown controller; set after listen so restore can beginDrain. */
     getShutdown?: () => import("./shutdown.js").ShutdownController | undefined;
     /**
-     * Optional Operator Agent Host for Workshop chat (tests inject the fake host).
-     * Distinct from stage-execution AgentPort. Defaults to live Pi Workshop Author
-     * (fake remains available via createWorkshopOperatorHost / test injection).
+     * Optional AgentPort (tests inject the fake host).
+     * Distinct from StagePort. Defaults to resolveAgentPort (Pi).
+     * The fake host remains available via createWorkshopOperatorHost.
      */
-    workshopOperatorHost?: OperatorAgentHost;
+    workshopOperatorHost?: AgentPort;
     /**
      * Optional durable Workshop chat registry (host sessions keyed by session id).
      * Defaults to a registry owned by this route surface.
@@ -64,7 +69,11 @@ export type OperatorRouteDeps = {
  * `startMcpServer` (headless global-service daemon) — both need the REST
  * API; only the former needs the UI files.
  */
-export declare function createOperatorRoutes(deps: OperatorRouteDeps): (ctx: HttpHostRouteContext) => Promise<boolean | void>;
+export type OperatorRoutes = ((ctx: HttpHostRouteContext) => Promise<boolean | void>) & {
+    /** Ends live view streams, credentials and relay sessions. Browsers are not torn down. */
+    dispose(): Promise<void>;
+};
+export declare function createOperatorRoutes(deps: OperatorRouteDeps): OperatorRoutes;
 export declare function startUiServer(options: UiServerOptions): Promise<HttpHostEnvelope & {
     shutdown: ShutdownController;
 }>;