@hachej/boring-workspace 0.1.53 → 0.1.55

package/dist/runtimeEnv-XVFZ1OkV.d.ts

@@ -0,0 +1,353 @@
+import { B as BoringPackageBoringField, a as BoringPackagePiField } from './manifest-C2vVgH_e.js';
+import { PiPackageSource, PluginSkillSource, ProvisionWorkspaceRuntimeOptions, RuntimeModeId, RuntimeEnvContribution } from '@hachej/boring-agent/server';
+import { FastifyPluginAsync } from 'fastify';
+import { A as AgentTool } from './agent-tool-CB0RQyx9.js';
+import { B as BridgeAuthContext, W as WorkspaceBridgeOperationDefinition, a as WorkspaceBridgeCallRequest, b as WorkspaceBridgeCallResponse, d as BridgeCallerClass } from './workspace-bridge-rpc-A98RA5o6.js';
+import { a as UiCommand, C as CommandResult, W as WorkspaceBridge } from './ui-bridge-BbuUZ5iC.js';
+
+type BoringPluginNativeFrontTargetTrust$1 = "local-trusted-native";
+/**
+ * Host-owned runtime import target for a plugin front entry.
+ *
+ * Only the trusted native/browser-module case exists today. Future
+ * target kinds (iframe/artifact/...) can extend the union without
+ * rewriting list/event payload shapes.
+ */
+interface BoringPluginNativeFrontTarget$1 {
+    kind: "native";
+    entryUrl: string;
+    revision: number;
+    trust: BoringPluginNativeFrontTargetTrust$1;
+}
+/**
+ * Plugin front served as a plain browser module URL — the Vite-dev transport
+ * (`/@fs/...`). Hosts running a Vite dev server let Vite transform the entry;
+ * the CLI's runtime host mints `native` targets instead.
+ */
+interface BoringPluginModuleUrlFrontTarget {
+    kind: "module-url";
+    entryUrl: string;
+    revision: number;
+}
+type BoringPluginFrontTarget$1 = BoringPluginNativeFrontTarget$1 | BoringPluginModuleUrlFrontTarget;
+type BoringPluginEvent$1 = {
+    type: "boring.plugin.load";
+    id: string;
+    boring: BoringPackageBoringField;
+    version: string;
+    revision: number;
+    frontTarget?: BoringPluginFrontTarget$1;
+} | {
+    type: "boring.plugin.unload";
+    id: string;
+    revision: number;
+} | {
+    type: "boring.plugin.error";
+    id: string;
+    revision: number;
+    message: string;
+};
+interface BoringPluginListEntry$1 {
+    id: string;
+    boring: BoringPackageBoringField;
+    pi?: BoringPackagePiField;
+    version: string;
+    revision: number;
+    frontTarget?: BoringPluginFrontTarget$1;
+}
+
+type BoringPluginSourceKind = "internal" | "external";
+interface BoringPluginSource {
+    rootDir: string;
+    kind: BoringPluginSourceKind;
+    workspaceId?: string;
+    /**
+     * True when the user explicitly registered this directory as a plugin
+     * source (e.g. a `packages` entry in Pi settings.json). Registered
+     * sources that are missing, lack a package.json, or carry no plugin
+     * metadata surface as preflight errors instead of being silently
+     * skipped the way speculative scan roots are.
+     */
+    registered?: boolean;
+}
+type BoringPluginSourceInput = string | BoringPluginSource;
+interface BoringServerPluginManifest {
+    id: string;
+    rootDir: string;
+    version: string;
+    boring: BoringPackageBoringField;
+    /** True when package.json explicitly declares a boring manifest. Pi-only packages remain valid Pi resources but are not listed as Boring plugins. */
+    hasBoring: boolean;
+    pi?: BoringPackagePiField;
+    frontPath?: string;
+    /** Legacy Vite-dev browser import fallback (`/@fs/...`). */
+    frontUrl?: string;
+    serverPath?: string;
+    extensionPaths?: string[];
+    skillPaths?: string[];
+    source: BoringPluginSource;
+}
+type BoringPluginNativeFrontTargetTrust = BoringPluginNativeFrontTargetTrust$1;
+type BoringPluginNativeFrontTarget = BoringPluginNativeFrontTarget$1;
+type BoringPluginFrontTarget = BoringPluginFrontTarget$1;
+type BoringPluginListEntry = BoringPluginListEntry$1;
+interface BoringPluginFrontTargetResolverContext {
+    revision: number;
+    /** Plugin-root-relative front entry path normalized for URL-like consumers. */
+    frontEntrySubpath: string;
+}
+type BoringPluginFrontTargetResolver = (plugin: BoringServerPluginManifest, context: BoringPluginFrontTargetResolverContext) => BoringPluginFrontTarget | undefined;
+/**
+ * Surfaces whose changes the hot-reload pipeline can't re-load mid-
+ * session — set when a plugin's load DID succeed but a sub-surface
+ * (the agent-tools registry, Fastify routes) carries stale code from
+ * the previous revision. The /reload caller (chat UI, verify-plugin,
+ * etc.) should surface a "restart needed for X" warning.
+ *
+ * - `'routes'`: a `WorkspaceServerPlugin.routes` function changed. The
+ *   workspace's Fastify instance can't unregister + re-register routes
+ *   mid-flight; the previous routes stay live until next boot.
+ * - `'agentTools'`: a `WorkspaceServerPlugin.agentTools` array changed.
+ *   The current Pi session still has the old tool list; new sessions
+ *   get the new list.
+ * - Multiple surfaces: order is deterministic (`routes` before
+ *   `agentTools`) so subscribers can format consistently.
+ */
+type PluginRestartSurface = "routes" | "agentTools";
+type BoringPluginEvent = (Extract<BoringPluginEvent$1, {
+    type: "boring.plugin.load";
+}> & {
+    /**
+     * Non-empty when the plugin loaded but one or more server-side
+     * surfaces still hold pre-load code. UI consumers should render
+     * a "restart needed: <surfaces>" hint. Empty/omitted = fully
+     * live.
+     */
+    requiresRestart?: PluginRestartSurface[];
+}) | Extract<BoringPluginEvent$1, {
+    type: "boring.plugin.unload";
+}> | Extract<BoringPluginEvent$1, {
+    type: "boring.plugin.error";
+}>;
+
+interface WorkspaceBridgeCallContext extends BridgeAuthContext {
+    requestId?: string;
+    signal?: AbortSignal;
+    emitUiEffect?: (cmd: UiCommand) => Promise<CommandResult>;
+}
+interface WorkspaceBridgeHandlerArgs<TInput = unknown> {
+    input: TInput;
+    context: WorkspaceBridgeCallContext;
+    definition: WorkspaceBridgeOperationDefinition<TInput, unknown>;
+    signal: AbortSignal;
+    emitUiEffect?: WorkspaceBridge["emitUiEffect"];
+}
+type WorkspaceBridgeHandler<TInput = unknown, TOutput = unknown> = (args: WorkspaceBridgeHandlerArgs<TInput>) => TOutput | Promise<TOutput>;
+interface RegisterWorkspaceBridgeHandlerOptions {
+    replace?: boolean;
+}
+interface WorkspaceBridgeRegistryLogger {
+    debug?(message: string, fields?: Record<string, unknown>): void;
+    info?(message: string, fields?: Record<string, unknown>): void;
+    warn?(message: string, fields?: Record<string, unknown>): void;
+    error?(message: string, fields?: Record<string, unknown>): void;
+}
+interface WorkspaceBridgeRegistryOptions {
+    logger?: WorkspaceBridgeRegistryLogger;
+    /** Workspace that owns this registry instance. Calls from other workspace ids are rejected unless the op opts into allowCrossWorkspace. */
+    ownerWorkspaceId?: string;
+}
+interface WorkspaceBridgeRegistryCallOptions {
+    /** Per-call owner override for hosts that reuse a registry across workspaces. */
+    expectedWorkspaceId?: string;
+}
+declare function validateWorkspaceBridgeOperationDefinition(definition: WorkspaceBridgeOperationDefinition): void;
+declare class WorkspaceBridgeRegistry {
+    private readonly handlers;
+    private readonly logger?;
+    private readonly ownerWorkspaceId?;
+    constructor(options?: WorkspaceBridgeRegistryOptions);
+    registerHandler<TInput, TOutput>(definition: WorkspaceBridgeOperationDefinition<TInput, TOutput>, handler: WorkspaceBridgeHandler<TInput, TOutput>, options?: RegisterWorkspaceBridgeHandlerOptions): void;
+    getDefinition(op: string): WorkspaceBridgeOperationDefinition | undefined;
+    listDefinitions(): WorkspaceBridgeOperationDefinition[];
+    call<TInput = unknown, TOutput = unknown>(request: WorkspaceBridgeCallRequest<TInput>, context: WorkspaceBridgeCallContext, options?: WorkspaceBridgeRegistryCallOptions): Promise<WorkspaceBridgeCallResponse<TOutput>>;
+    private failure;
+}
+declare function createWorkspaceBridgeRegistry(options?: WorkspaceBridgeRegistryOptions): WorkspaceBridgeRegistry;
+
+type WorkspaceRuntimeProvisioning = NonNullable<ProvisionWorkspaceRuntimeOptions["plugins"][number]["provisioning"]>;
+interface WorkspaceServerPluginAsset {
+    /** Stable asset name within this plugin, e.g. "sdk" or "workspace-template". */
+    name: string;
+    /** Source directory or file owned by the plugin. Relative strings are resolved by the app integration. */
+    source: string | URL;
+    /** Optional runtime target path within this plugin's asset namespace. Defaults to name. */
+    target?: string;
+}
+interface WorkspaceBridgeHandlerContribution {
+    definition: WorkspaceBridgeOperationDefinition;
+    handler: WorkspaceBridgeHandler;
+}
+interface WorkspaceServerPlugin {
+    id: string;
+    label?: string;
+    /**
+     * Native Pi package sources required by this workspace integration.
+     * Workspace declares them; @hachej/boring-agent applies them through Pi's native
+     * resource loader without asking Pi packages to export Boring adapters.
+     */
+    piPackages?: PiPackageSource[];
+    /**
+     * Native pi extension entrypoints contributed by this plugin.
+     * Passed to DefaultResourceLoader.additionalExtensionPaths so pi owns jiti
+     * loading and ctx.reload() re-imports fresh source.
+     */
+    extensionPaths?: string[];
+    systemPrompt?: string;
+    skills?: PluginSkillSource[];
+    agentTools?: AgentTool[];
+    /** Trusted boot-time host RPC handlers. Only app/internal server plugins should provide these. */
+    workspaceBridgeHandlers?: WorkspaceBridgeHandlerContribution[];
+    provisioning?: WorkspaceRuntimeProvisioning;
+    /** Static filesystem assets this plugin needs in production/serverless bundles. */
+    assets?: WorkspaceServerPluginAsset[];
+    routes?: FastifyPluginAsync;
+    /** UI state keys owned by this plugin that browser state PUTs must not overwrite. */
+    preservedUiStateKeys?: string[];
+}
+declare function validateServerPlugin(plugin: WorkspaceServerPlugin): void;
+declare function defineServerPlugin<T extends WorkspaceServerPlugin>(plugin: T): T;
+
+interface ServerBootstrapOptions {
+    plugins?: WorkspaceServerPlugin[];
+    defaults?: WorkspaceServerPlugin[];
+    excludeDefaults?: string[];
+}
+type WorkspaceRuntimeProvisioningInput = ProvisionWorkspaceRuntimeOptions["plugins"][number];
+type WorkspaceProvisioningContribution = {
+    id: string;
+    provisioning: NonNullable<WorkspaceRuntimeProvisioningInput["provisioning"]>;
+};
+type WorkspaceRouteContribution = {
+    id: string;
+    routes: FastifyPluginAsync;
+};
+interface ServerBootstrapResult {
+    registered: string[];
+    systemPromptAppend: string;
+    piPackages: PiPackageSource[];
+    extensionPaths: string[];
+    agentTools: AgentTool[];
+    runtimePlugins: WorkspaceRuntimeProvisioningInput[];
+    provisioningContributions: WorkspaceProvisioningContribution[];
+    routeContributions: WorkspaceRouteContribution[];
+    workspaceBridgeHandlers: WorkspaceBridgeHandlerContribution[];
+    preservedUiStateKeys: string[];
+}
+declare function bootstrapServer(options: ServerBootstrapOptions): ServerBootstrapResult;
+
+declare function createInMemoryBridge(): WorkspaceBridge;
+
+interface BridgePrincipal {
+    userId: string;
+    email?: string;
+    roles?: readonly string[];
+}
+interface BridgeWorkspaceGrant {
+    allowed: boolean;
+    role?: string;
+    capabilities: readonly string[];
+    resourceScope?: Record<string, unknown>;
+}
+interface BridgeAuthPolicyRequestLike {
+    headers?: Record<string, string | string[] | undefined>;
+    method?: string;
+    /** Host-authenticated principal attached to the Fastify request, if available. */
+    user?: unknown;
+}
+interface BridgeAuthPolicyInput {
+    callerClass: BridgeCallerClass;
+    definition: WorkspaceBridgeOperationDefinition;
+    workspaceId: string;
+    sessionId?: string;
+    pluginId?: string;
+    request?: BridgeAuthPolicyRequestLike;
+    body?: unknown;
+    requiredCapabilities?: readonly string[];
+}
+interface BridgeAuthResolution {
+    context: BridgeAuthContext;
+    effectiveCapabilities: readonly string[];
+    resourceScope?: Record<string, unknown>;
+    principal?: BridgePrincipal;
+}
+interface BridgeAuthPolicy {
+    resolve(input: BridgeAuthPolicyInput): Promise<BridgeAuthResolution> | BridgeAuthResolution;
+}
+interface BrowserBridgeAuthPolicyOptions {
+    getPrincipal(input: BridgeAuthPolicyInput): Promise<BridgePrincipal | null> | BridgePrincipal | null;
+    authorizeWorkspace(input: {
+        principal: BridgePrincipal;
+        workspaceId: string;
+        sessionId?: string;
+        definition: WorkspaceBridgeOperationDefinition;
+        request?: BridgeAuthPolicyRequestLike;
+    }): Promise<BridgeWorkspaceGrant> | BridgeWorkspaceGrant;
+    allowedOrigins?: readonly string[];
+    /**
+     * Require a non-empty x-csrf-token header as a non-simple-request proof.
+     * This policy does not validate a signed token value; hosts that need
+     * cryptographic CSRF tokens should verify them before/inside getPrincipal.
+     */
+    requireCsrfHeader?: boolean;
+}
+interface LocalCliBridgeAuthPolicyOptions {
+    workspaceId: string;
+    capabilities?: readonly string[];
+}
+declare function createBrowserBridgeAuthPolicy(options: BrowserBridgeAuthPolicyOptions): BridgeAuthPolicy;
+/**
+ * Dev/local CLI only. This policy performs no user authentication and grants
+ * the configured capabilities (defaulting to the op's own) to a fixed
+ * local-cli principal. Do not use it for exposed or production servers; pass a
+ * host-owned createBrowserBridgeAuthPolicy-style policy instead.
+ */
+declare function createLocalCliBridgeAuthPolicy(options: LocalCliBridgeAuthPolicyOptions): BridgeAuthPolicy;
+
+type WorkspaceBridgeRuntimeEnvDisabledReason = "bridge-url-missing" | "runtime-token-secret-missing" | "runtime-capabilities-missing" | "remote-bridge-url-must-be-https" | "remote-bridge-url-must-not-be-localhost" | "bridge-url-invalid";
+interface WorkspaceBridgeRuntimeEnvOptions {
+    /** Opt in to runtime SDK/CLI bridge env injection. Defaults to true when bridgeUrl is set. */
+    enabled?: boolean;
+    /** Trusted, externally reachable app origin or full /api/v1/workspace-bridge/call URL. */
+    bridgeUrl?: string;
+    /** Allow plain HTTP for local/dev endpoints. Remote runtimes still require HTTPS. */
+    allowInsecureHttp?: boolean;
+    /**
+     * Explicit capability strings minted into runtime bridge tokens. These are
+     * grants the registry checks at call time, not resource-ownership checks;
+     * operation handlers must still enforce their own domain/resource scope.
+     */
+    capabilities?: readonly string[];
+    /** Runtime call-token TTL. Defaults to the token primitive default. */
+    tokenTtlMs?: number;
+    /** Runtime refresh-token TTL. Defaults to the token primitive default. */
+    refreshTokenTtlMs?: number;
+    /** Optional audit/session claim. */
+    sessionId?: string;
+}
+type WorkspaceBridgeRuntimePlacement = "local" | "remote";
+interface CreateWorkspaceBridgeRuntimeEnvContributionOptions {
+    workspaceId: string;
+    runtimeMode: RuntimeModeId;
+    registry: WorkspaceBridgeRegistry;
+    runtimeTokenSecret?: string;
+    runtimeRefreshTokenSecret?: string;
+    runtimeEnv?: WorkspaceBridgeRuntimeEnvOptions;
+    /** Provider-neutral fallback used when getEnv is called without a RuntimeEnvContributionContext (mostly tests). */
+    runtimePlacement?: WorkspaceBridgeRuntimePlacement;
+}
+declare function createWorkspaceBridgeRuntimeEnvContribution(options: CreateWorkspaceBridgeRuntimeEnvContributionOptions): RuntimeEnvContribution | undefined;
+declare function resolveBridgeCallUrl(value: string | undefined): string | undefined;
+declare function resolveBridgeTokenUrl(value: string | undefined): string | undefined;
+
+export { type WorkspaceBridgeCallContext as A, type BridgeAuthPolicy as B, type CreateWorkspaceBridgeRuntimeEnvContributionOptions as C, type WorkspaceBridgeHandlerArgs as D, type WorkspaceBridgeHandlerContribution as E, type WorkspaceBridgeRegistryCallOptions as F, type WorkspaceBridgeRegistryLogger as G, type WorkspaceBridgeRegistryOptions as H, type WorkspaceBridgeRuntimeEnvDisabledReason as I, type WorkspaceBridgeRuntimePlacement as J, bootstrapServer as K, type LocalCliBridgeAuthPolicyOptions as L, createBrowserBridgeAuthPolicy as M, createLocalCliBridgeAuthPolicy as N, createWorkspaceBridgeRegistry as O, type PluginRestartSurface as P, createWorkspaceBridgeRuntimeEnvContribution as Q, type RegisterWorkspaceBridgeHandlerOptions as R, type ServerBootstrapOptions as S, defineServerPlugin as T, resolveBridgeCallUrl as U, resolveBridgeTokenUrl as V, type WorkspaceServerPlugin as W, validateServerPlugin as X, validateWorkspaceBridgeOperationDefinition as Y, WorkspaceBridgeRegistry as a, type WorkspaceBridgeHandler as b, type WorkspaceBridgeRuntimeEnvOptions as c, type BoringPluginSourceInput as d, type BoringPluginFrontTargetResolver as e, type WorkspaceProvisioningContribution as f, type WorkspaceRouteContribution as g, createInMemoryBridge as h, type WorkspaceRuntimeProvisioningInput as i, type WorkspaceServerPluginAsset as j, type BoringServerPluginManifest as k, type BoringPluginListEntry as l, type BoringPluginFrontTarget as m, type BoringPluginSource as n, type BoringPluginEvent as o, type BoringPluginFrontTargetResolverContext as p, type BoringPluginNativeFrontTarget as q, type BoringPluginNativeFrontTargetTrust as r, type BoringPluginSourceKind as s, type BridgeAuthPolicyInput as t, type BridgeAuthPolicyRequestLike as u, type BridgeAuthResolution as v, type BridgePrincipal as w, type BridgeWorkspaceGrant as x, type BrowserBridgeAuthPolicyOptions as y, type ServerBootstrapResult as z };

package/dist/server.d.ts

@@ -1,9 +1,11 @@
-import { f as WorkspaceServerPluginAsset, g as BoringServerPluginManifest, B as BoringPluginSourceInput, a as BoringPluginFrontTargetResolver, h as BoringPluginListEntry, i as BoringPluginFrontTarget, j as BoringPluginSource, k as BoringPluginEvent, P as PluginRestartSurface } from './createInMemoryBridge-siFWq_R_.js';
-export { l as BoringPluginFrontTargetResolverContext, m as BoringPluginNativeFrontTarget, n as BoringPluginNativeFrontTargetTrust, o as BoringPluginSourceKind, S as ServerBootstrapOptions, p as ServerBootstrapResult, b as WorkspaceProvisioningContribution, c as WorkspaceRouteContribution, W as WorkspaceServerPlugin, q as bootstrapServer, d as createInMemoryBridge, r as defineServerPlugin, v as validateServerPlugin } from './createInMemoryBridge-siFWq_R_.js';
+import { j as WorkspaceServerPluginAsset, a as WorkspaceBridgeRegistry, B as BridgeAuthPolicy, b as WorkspaceBridgeHandler, k as BoringServerPluginManifest, d as BoringPluginSourceInput, e as BoringPluginFrontTargetResolver, l as BoringPluginListEntry, m as BoringPluginFrontTarget, n as BoringPluginSource, o as BoringPluginEvent, P as PluginRestartSurface } from './runtimeEnv-XVFZ1OkV.js';
+export { p as BoringPluginFrontTargetResolverContext, q as BoringPluginNativeFrontTarget, r as BoringPluginNativeFrontTargetTrust, s as BoringPluginSourceKind, t as BridgeAuthPolicyInput, u as BridgeAuthPolicyRequestLike, v as BridgeAuthResolution, w as BridgePrincipal, x as BridgeWorkspaceGrant, y as BrowserBridgeAuthPolicyOptions, C as CreateWorkspaceBridgeRuntimeEnvContributionOptions, L as LocalCliBridgeAuthPolicyOptions, R as RegisterWorkspaceBridgeHandlerOptions, S as ServerBootstrapOptions, z as ServerBootstrapResult, A as WorkspaceBridgeCallContext, D as WorkspaceBridgeHandlerArgs, E as WorkspaceBridgeHandlerContribution, F as WorkspaceBridgeRegistryCallOptions, G as WorkspaceBridgeRegistryLogger, H as WorkspaceBridgeRegistryOptions, I as WorkspaceBridgeRuntimeEnvDisabledReason, c as WorkspaceBridgeRuntimeEnvOptions, J as WorkspaceBridgeRuntimePlacement, f as WorkspaceProvisioningContribution, g as WorkspaceRouteContribution, W as WorkspaceServerPlugin, K as bootstrapServer, M as createBrowserBridgeAuthPolicy, h as createInMemoryBridge, N as createLocalCliBridgeAuthPolicy, O as createWorkspaceBridgeRegistry, Q as createWorkspaceBridgeRuntimeEnvContribution, T as defineServerPlugin, U as resolveBridgeCallUrl, V as resolveBridgeTokenUrl, X as validateServerPlugin, Y as validateWorkspaceBridgeOperationDefinition } from './runtimeEnv-XVFZ1OkV.js';
 import { FastifyRequest, FastifyInstance } from 'fastify';
-import { U as UiBridge } from './ui-bridge-LeBuZqfA.js';
-export { C as CommandResult, a as UiCommand, b as UiState } from './ui-bridge-LeBuZqfA.js';
+import { U as UiBridge, W as WorkspaceBridge } from './ui-bridge-BbuUZ5iC.js';
+export { C as CommandResult, a as UiCommand, b as UiState } from './ui-bridge-BbuUZ5iC.js';
 import { A as AgentTool } from './agent-tool-CB0RQyx9.js';
+import { W as WorkspaceBridgeOperationDefinition, a as WorkspaceBridgeCallRequest, B as BridgeAuthContext, b as WorkspaceBridgeCallResponse, c as WorkspaceBridgeError, d as BridgeCallerClass, e as BridgeIdempotencyPolicy } from './workspace-bridge-rpc-A98RA5o6.js';
+export { f as BridgeActorAttribution, g as BridgeActorKind, h as BridgeRedactedActorRef, i as WorkspaceBridgeCallFailure, j as WorkspaceBridgeCallSuccess, k as WorkspaceBridgeErrorCode, l as WorkspaceBridgeFileAssetPointer, m as WorkspaceBridgeJsonValue, n as createWorkspaceBridgeError } from './workspace-bridge-rpc-A98RA5o6.js';
 import { PiPackageSource } from '@hachej/boring-agent/server';
 export { PiPackageSource as WorkspacePiPackageSource } from '@hachej/boring-agent/server';
 import { PluginLogger } from './runtime-server.js';
@@ -111,8 +113,8 @@ interface ExecUiToolOptions {
      */
     verifyIntervalMs?: number;
 }
-declare function createGetUiStateTool(uiBridge: UiBridge): AgentTool;
-declare function createExecUiTool(uiBridge: UiBridge, opts?: ExecUiToolOptions): AgentTool;
+declare function createGetUiStateTool(workspaceBridge: WorkspaceBridge): AgentTool;
+declare function createExecUiTool(workspaceBridge: WorkspaceBridge, opts?: ExecUiToolOptions): AgentTool;
 /**
  * Convenience: returns both UI tools as an `AgentTool[]` ready to merge into
  * `extraTools`. `createWorkspaceAgentServer` calls this internally; hosts that
@@ -124,7 +126,233 @@ declare function createExecUiTool(uiBridge: UiBridge, opts?: ExecUiToolOptions):
  *   })
  *   await app.register(uiRoutes, { bridge })
  */
-declare function createWorkspaceUiTools(uiBridge: UiBridge, opts?: ExecUiToolOptions): AgentTool[];
+declare function createWorkspaceUiTools(workspaceBridge: WorkspaceBridge, opts?: ExecUiToolOptions): AgentTool[];
+
+declare function stableStringify(value: unknown): string;
+
+type IdempotencyRecordStatus = "pending" | "completed";
+interface WorkspaceBridgeIdempotencyRecord<TOutput = unknown> {
+    scopeKey: string;
+    inputHash: string;
+    status: IdempotencyRecordStatus;
+    createdAt: string;
+    updatedAt: string;
+    expiresAt: string;
+    response?: WorkspaceBridgeCallResponse<TOutput>;
+}
+type IdempotencyBeginResult<TOutput = unknown> = {
+    action: "execute";
+    scopeKey: string;
+    inputHash: string;
+} | {
+    action: "replay";
+    record: WorkspaceBridgeIdempotencyRecord<TOutput>;
+} | {
+    action: "reject";
+    error: WorkspaceBridgeError;
+};
+interface BeginIdempotencyOptions<TInput = unknown> {
+    definition: WorkspaceBridgeOperationDefinition<TInput, unknown>;
+    request: WorkspaceBridgeCallRequest<TInput>;
+    auth: Pick<BridgeAuthContext, "workspaceId" | "sessionId" | "pluginId" | "tokenId">;
+    nowMs?: number;
+    ttlMs?: number;
+}
+interface CompleteIdempotencyOptions<TOutput = unknown> {
+    scopeKey: string;
+    inputHash: string;
+    response: WorkspaceBridgeCallResponse<TOutput>;
+    nowMs?: number;
+    ttlMs?: number;
+}
+interface WorkspaceBridgeIdempotencyStore {
+    begin<TInput = unknown, TOutput = unknown>(options: BeginIdempotencyOptions<TInput>): Promise<IdempotencyBeginResult<TOutput>>;
+    complete<TOutput = unknown>(options: CompleteIdempotencyOptions<TOutput>): Promise<void>;
+    /**
+     * Release a pending record so the same key can be retried. Used when a
+     * mutation fails transiently: caching the failure would otherwise block
+     * legitimate same-key retries until the record's TTL expires.
+     */
+    release(scopeKey: string, inputHash: string): Promise<void>;
+    gc(nowMs?: number): Promise<number>;
+}
+declare class InMemoryWorkspaceBridgeIdempotencyStore implements WorkspaceBridgeIdempotencyStore {
+    private readonly records;
+    private lastGcMs;
+    begin<TInput, TOutput>(options: BeginIdempotencyOptions<TInput>): Promise<IdempotencyBeginResult<TOutput>>;
+    complete<TOutput>(options: CompleteIdempotencyOptions<TOutput>): Promise<void>;
+    release(scopeKey: string, inputHash: string): Promise<void>;
+    gc(nowMs?: number): Promise<number>;
+}
+declare function runWithWorkspaceBridgeIdempotency<TInput, TOutput>(store: WorkspaceBridgeIdempotencyStore | undefined, options: BeginIdempotencyOptions<TInput>, execute: () => Promise<WorkspaceBridgeCallResponse<TOutput>>): Promise<WorkspaceBridgeCallResponse<TOutput>>;
+declare function hashNormalizedInput(input: unknown): string;
+
+declare const WORKSPACE_BRIDGE_TOKEN_AUDIENCE = "workspace-bridge";
+declare const WORKSPACE_BRIDGE_REFRESH_TOKEN_AUDIENCE = "workspace-bridge-refresh";
+declare const DEFAULT_WORKSPACE_BRIDGE_RUNTIME_TOKEN_TTL_MS: number;
+declare const DEFAULT_WORKSPACE_BRIDGE_RUNTIME_REFRESH_TOKEN_TTL_MS: number;
+declare const MAX_WORKSPACE_BRIDGE_RUNTIME_TOKEN_TTL_MS: number;
+interface WorkspaceBridgeTokenClaimsBase {
+    aud: string;
+    workspaceId: string;
+    sessionId?: string;
+    runtimeId?: string;
+    capabilities: readonly string[];
+    iat: number;
+    exp: number;
+    jti: string;
+    tokenTtlMs?: number;
+}
+interface WorkspaceBridgeRuntimeTokenClaims extends WorkspaceBridgeTokenClaimsBase {
+    aud: typeof WORKSPACE_BRIDGE_TOKEN_AUDIENCE;
+}
+interface WorkspaceBridgeRuntimeRefreshTokenClaims extends WorkspaceBridgeTokenClaimsBase {
+    aud: typeof WORKSPACE_BRIDGE_REFRESH_TOKEN_AUDIENCE;
+    /** Short-lived call-token TTL to use when this refresh token re-mints. */
+    tokenTtlMs?: number;
+}
+interface MintWorkspaceBridgeRuntimeTokenOptions {
+    secret: string;
+    workspaceId: string;
+    sessionId?: string;
+    runtimeId?: string;
+    capabilities: readonly string[];
+    ttlMs?: number;
+    nowMs?: number;
+    jti?: string;
+}
+interface MintWorkspaceBridgeRuntimeRefreshTokenOptions extends MintWorkspaceBridgeRuntimeTokenOptions {
+    /** Short-lived call-token TTL to use when this refresh token re-mints. */
+    tokenTtlMs?: number;
+}
+interface VerifyWorkspaceBridgeRuntimeTokenOptions {
+    secret: string;
+    nowMs?: number;
+    requiredCapabilities?: readonly string[];
+}
+interface VerifyWorkspaceBridgeRuntimeRefreshTokenOptions {
+    secret: string;
+    nowMs?: number;
+}
+interface VerifiedWorkspaceBridgeRuntimeToken {
+    claims: WorkspaceBridgeRuntimeTokenClaims;
+    authContext: BridgeAuthContext;
+}
+interface VerifiedWorkspaceBridgeRuntimeRefreshToken {
+    claims: WorkspaceBridgeRuntimeRefreshTokenClaims;
+}
+declare function mintWorkspaceBridgeRuntimeToken(options: MintWorkspaceBridgeRuntimeTokenOptions): string;
+declare function mintWorkspaceBridgeRuntimeRefreshToken(options: MintWorkspaceBridgeRuntimeRefreshTokenOptions): string;
+declare function verifyWorkspaceBridgeRuntimeToken(token: string, options: VerifyWorkspaceBridgeRuntimeTokenOptions): VerifiedWorkspaceBridgeRuntimeToken;
+declare function verifyWorkspaceBridgeRuntimeRefreshToken(token: string, options: VerifyWorkspaceBridgeRuntimeRefreshTokenOptions): VerifiedWorkspaceBridgeRuntimeRefreshToken;
+declare function clampWorkspaceBridgeRuntimeTokenTtlMs(ttlMs: number | undefined): number | undefined;
+declare function runtimeClaimsToBridgeAuthContext(claims: WorkspaceBridgeRuntimeTokenClaims): BridgeAuthContext;
+
+interface WorkspaceBridgeRuntimeRefreshTokenUseOptions {
+    jti: string;
+    nowMs?: number;
+    windowMs: number;
+    maxUses: number;
+    /** Expiry time for the refresh token that owns this jti. Used for bounded in-memory GC. */
+    expiresAtMs?: number;
+}
+type WorkspaceBridgeRuntimeRefreshTokenUseResult = {
+    allowed: true;
+} | {
+    allowed: false;
+    reason: "revoked";
+} | {
+    allowed: false;
+    reason: "rate-limited";
+    retryAfterMs: number;
+};
+interface WorkspaceBridgeRuntimeRefreshTokenStore {
+    revoke(jti: string, expiresAtMs?: number): void | Promise<void>;
+    recordUse(options: WorkspaceBridgeRuntimeRefreshTokenUseOptions): WorkspaceBridgeRuntimeRefreshTokenUseResult | Promise<WorkspaceBridgeRuntimeRefreshTokenUseResult>;
+}
+declare class InMemoryWorkspaceBridgeRuntimeRefreshTokenStore implements WorkspaceBridgeRuntimeRefreshTokenStore {
+    private readonly revoked;
+    private readonly rateLimits;
+    private lastGcMs;
+    revoke(jti: string, expiresAtMs?: number): void;
+    recordUse(options: WorkspaceBridgeRuntimeRefreshTokenUseOptions): WorkspaceBridgeRuntimeRefreshTokenUseResult;
+    gc(nowMs?: number): number;
+}
+
+interface WorkspaceBridgeHttpRoutesOptions {
+    registry?: WorkspaceBridgeRegistry;
+    getRegistry?: (request: FastifyRequest, body: WorkspaceBridgeCallRequest) => WorkspaceBridgeRegistry | Promise<WorkspaceBridgeRegistry>;
+    browserAuthPolicy?: BridgeAuthPolicy;
+    runtimeTokenSecret?: string;
+    runtimeRefreshTokenSecret?: string;
+    runtimeRefreshTokenStore?: WorkspaceBridgeRuntimeRefreshTokenStore;
+    getRuntimeRefreshTokenStore?: (request: FastifyRequest, claims: WorkspaceBridgeRuntimeRefreshTokenClaims) => WorkspaceBridgeRuntimeRefreshTokenStore | undefined | Promise<WorkspaceBridgeRuntimeRefreshTokenStore | undefined>;
+    refreshTokenRateLimit?: {
+        maxUses?: number;
+        windowMs?: number;
+    };
+    ownerWorkspaceId?: string;
+    getOwnerWorkspaceId?: (request: FastifyRequest, body: WorkspaceBridgeCallRequest, auth: BridgeAuthContext) => string | undefined | Promise<string | undefined>;
+    idempotencyStore?: WorkspaceBridgeIdempotencyStore;
+    getIdempotencyStore?: (request: FastifyRequest, body: WorkspaceBridgeCallRequest) => WorkspaceBridgeIdempotencyStore | undefined | Promise<WorkspaceBridgeIdempotencyStore | undefined>;
+    maxBodyBytes?: number;
+}
+declare function workspaceBridgeHttpRoutes(app: FastifyInstance, opts: WorkspaceBridgeHttpRoutesOptions, done: (err?: Error) => void): void;
+
+interface TrustedDomainBridgeHandlerPolicy {
+    /** Default true. Trusted app/domain ops should be versioned: domain.v1.action. */
+    requireVersionedOp?: boolean;
+    /** Default rejects generic workspace file proxy surfaces. */
+    reservedOpPrefixes?: readonly string[];
+}
+interface TrustedDomainBridgeHandlerOptions<TInput = unknown, TOutput = unknown> {
+    op: string;
+    version: number;
+    owner: string;
+    callerClassesAllowed: readonly BridgeCallerClass[];
+    requiredCapabilities: readonly string[];
+    inputSchema: unknown;
+    outputSchema?: unknown;
+    timeoutMs?: number;
+    maxInputBytes?: number;
+    maxOutputBytes: number;
+    idempotencyPolicy?: BridgeIdempotencyPolicy;
+    handler: WorkspaceBridgeHandler<TInput, TOutput>;
+    policy?: TrustedDomainBridgeHandlerPolicy;
+}
+interface TrustedDomainBridgeHandlerRegistration<TInput = unknown, TOutput = unknown> {
+    definition: WorkspaceBridgeOperationDefinition<TInput, TOutput>;
+    handler: WorkspaceBridgeHandler<TInput, TOutput>;
+}
+/**
+ * Trusted-only helper for app/core/domain-owned WorkspaceBridge handlers.
+ *
+ * This is intentionally NOT a generated-plugin host-process handler API:
+ * generated/runtime plugins must keep using sandbox/runtime SDK calls and must
+ * not self-register arbitrary host handlers or Fastify routes.
+ */
+declare function defineTrustedDomainBridgeHandler<TInput = unknown, TOutput = unknown>(options: TrustedDomainBridgeHandlerOptions<TInput, TOutput>): TrustedDomainBridgeHandlerRegistration<TInput, TOutput>;
+
+interface WorkspaceBridgeRuntimeCoreOptions {
+    /** Reuse an existing registry; otherwise a fresh in-memory one is created. */
+    registry?: WorkspaceBridgeRegistry;
+    /** Host/app/internal plugin bridge handlers to register at boot. */
+    handlers?: ReadonlyArray<{
+        definition: WorkspaceBridgeOperationDefinition;
+        handler: WorkspaceBridgeHandler;
+    }>;
+    /** Workspace that owns a newly-created registry. Ignored when registry is provided. */
+    ownerWorkspaceId?: string;
+}
+interface WorkspaceBridgeRuntimeCore {
+    registry: WorkspaceBridgeRegistry;
+}
+/**
+ * Shared bridge bootstrap: build/accept a registry and register host-supplied
+ * bridge handlers. Domain handlers belong to the app/internal plugin that owns
+ * the domain; workspace only owns the generic registry/runtime composition.
+ */
+declare function createWorkspaceBridgeRuntimeCore(options?: WorkspaceBridgeRuntimeCoreOptions): WorkspaceBridgeRuntimeCore;
 
 /**
  * boring-ui system prompt — workflow steps + a Pi-style docs pointer
@@ -392,4 +620,4 @@ interface RuntimeBackendGatewayOptions {
 }
 declare function runtimeBackendGateway(app: FastifyInstance, opts: RuntimeBackendGatewayOptions): Promise<void>;
 
-export { BoringPluginAssetManager, BoringPluginEvent, BoringPluginFrontTarget, BoringPluginFrontTargetResolver, BoringPluginListEntry, type BoringPluginScanResult, BoringPluginSource, BoringPluginSourceInput, BoringServerPluginManifest, type PluginRestartWarning, type RuntimeBackendDiagnostic, type RuntimeBackendDispatchRequest, type RuntimeBackendDispatchResponse, type RuntimeBackendDispatcher, RuntimeBackendError, type RuntimeBackendGatewayOptions, RuntimeBackendRegistry, type RuntimeBackendReloadResult, UiBridge, type UiRoutesOptions, WorkspaceServerPluginAsset, aggregatePluginPrompts, boringPluginRoutes, buildBoringSystemPrompt, collectRestartWarnings, createExecUiTool, createGetUiStateTool, createWorkspaceUiTools, definePluginAsset, pluginFileSignature, preflightBoringPlugins, readBoringPlugins, readPluginSignatureCache, resolvePluginAssetPath, runtimeBackendGateway, scanBoringPlugins, uiRoutes, writePluginSignatureCache };
+export { type BeginIdempotencyOptions, BoringPluginAssetManager, BoringPluginEvent, BoringPluginFrontTarget, BoringPluginFrontTargetResolver, BoringPluginListEntry, type BoringPluginScanResult, BoringPluginSource, BoringPluginSourceInput, BoringServerPluginManifest, BridgeAuthContext, BridgeAuthPolicy, BridgeCallerClass, BridgeIdempotencyPolicy, type CompleteIdempotencyOptions, DEFAULT_WORKSPACE_BRIDGE_RUNTIME_REFRESH_TOKEN_TTL_MS, DEFAULT_WORKSPACE_BRIDGE_RUNTIME_TOKEN_TTL_MS, type IdempotencyBeginResult, type IdempotencyRecordStatus, InMemoryWorkspaceBridgeIdempotencyStore, InMemoryWorkspaceBridgeRuntimeRefreshTokenStore, MAX_WORKSPACE_BRIDGE_RUNTIME_TOKEN_TTL_MS, type MintWorkspaceBridgeRuntimeRefreshTokenOptions, type MintWorkspaceBridgeRuntimeTokenOptions, type PluginRestartWarning, type RuntimeBackendDiagnostic, type RuntimeBackendDispatchRequest, type RuntimeBackendDispatchResponse, type RuntimeBackendDispatcher, RuntimeBackendError, type RuntimeBackendGatewayOptions, RuntimeBackendRegistry, type RuntimeBackendReloadResult, type TrustedDomainBridgeHandlerOptions, type TrustedDomainBridgeHandlerPolicy, type TrustedDomainBridgeHandlerRegistration, UiBridge, type UiRoutesOptions, type VerifiedWorkspaceBridgeRuntimeRefreshToken, type VerifiedWorkspaceBridgeRuntimeToken, type VerifyWorkspaceBridgeRuntimeRefreshTokenOptions, type VerifyWorkspaceBridgeRuntimeTokenOptions, WORKSPACE_BRIDGE_REFRESH_TOKEN_AUDIENCE, WORKSPACE_BRIDGE_TOKEN_AUDIENCE, WorkspaceBridge, WorkspaceBridgeCallRequest, WorkspaceBridgeCallResponse, WorkspaceBridgeError, WorkspaceBridgeHandler, type WorkspaceBridgeHttpRoutesOptions, type WorkspaceBridgeIdempotencyRecord, type WorkspaceBridgeIdempotencyStore, WorkspaceBridgeOperationDefinition, WorkspaceBridgeRegistry, type WorkspaceBridgeRuntimeCore, type WorkspaceBridgeRuntimeCoreOptions, type WorkspaceBridgeRuntimeRefreshTokenClaims, type WorkspaceBridgeRuntimeRefreshTokenStore, type WorkspaceBridgeRuntimeRefreshTokenUseOptions, type WorkspaceBridgeRuntimeRefreshTokenUseResult, type WorkspaceBridgeRuntimeTokenClaims, WorkspaceServerPluginAsset, aggregatePluginPrompts, boringPluginRoutes, buildBoringSystemPrompt, clampWorkspaceBridgeRuntimeTokenTtlMs, collectRestartWarnings, createExecUiTool, createGetUiStateTool, createWorkspaceBridgeRuntimeCore, createWorkspaceUiTools, definePluginAsset, defineTrustedDomainBridgeHandler, hashNormalizedInput, mintWorkspaceBridgeRuntimeRefreshToken, mintWorkspaceBridgeRuntimeToken, pluginFileSignature, preflightBoringPlugins, readBoringPlugins, readPluginSignatureCache, resolvePluginAssetPath, runWithWorkspaceBridgeIdempotency, runtimeBackendGateway, runtimeClaimsToBridgeAuthContext, scanBoringPlugins, stableStringify, uiRoutes, verifyWorkspaceBridgeRuntimeRefreshToken, verifyWorkspaceBridgeRuntimeToken, workspaceBridgeHttpRoutes, writePluginSignatureCache };