@hachej/boring-agent 0.1.0

package/dist/harness-CMiJ4kok.d.ts

@@ -0,0 +1,62 @@
+import { UIMessage, UIMessageChunk } from 'ai';
+
+interface SessionStore {
+    list(ctx: SessionCtx): Promise<SessionSummary[]>;
+    create(ctx: SessionCtx, init?: {
+        title?: string;
+    }): Promise<SessionSummary>;
+    load(ctx: SessionCtx, sessionId: string): Promise<SessionDetail>;
+    delete(ctx: SessionCtx, sessionId: string): Promise<void>;
+    /**
+     * Persist a snapshot of UI-layer messages so they survive server restarts.
+     * Called by the client after each completed turn. Optional — stores that
+     * don't implement it simply don't persist UI messages server-side.
+     */
+    saveMessages?(ctx: SessionCtx, sessionId: string, messages: UIMessage[]): Promise<void>;
+}
+interface SessionCtx {
+    workspaceId: string;
+    userId?: string;
+}
+interface SessionSummary {
+    id: string;
+    title: string;
+    createdAt: string;
+    updatedAt: string;
+    turnCount: number;
+}
+interface SessionDetail extends SessionSummary {
+    messages: UIMessage[];
+}
+
+interface AgentHarness {
+    readonly id: string;
+    readonly placement: 'server' | 'browser';
+    /** Send a user message. Yields AI SDK UIMessage stream chunks. */
+    sendMessage(input: SendMessageInput, ctx: RunContext): AsyncIterable<UIMessageChunk>;
+    /** Session lifecycle; may delegate to an underlying runtime (e.g. pi's JSONL). */
+    sessions: SessionStore;
+    /**
+     * Resolved system prompt currently in effect for `sessionId`. Returns
+     * `undefined` when the underlying runtime hasn't yet instantiated a
+     * session (typical pre-first-turn state — pi creates lazily on first
+     * `sendMessage`). Optional so non-pi harnesses can opt out cleanly.
+     */
+    getSystemPrompt?: (sessionId: string) => string | undefined;
+}
+interface SendMessageInput {
+    sessionId: string;
+    message: string;
+    thinkingLevel?: 'off' | 'low' | 'medium' | 'high';
+    model?: {
+        provider: string;
+        id: string;
+    };
+}
+interface RunContext {
+    abortSignal: AbortSignal;
+    workdir: string;
+    userId?: string;
+}
+
+export type { AgentHarness as A, RunContext as R, SendMessageInput as S, SessionCtx as a, SessionDetail as b, SessionStore as c, SessionSummary as d };

package/dist/sandbox-handle-store-OPdvRwie.d.ts

@@ -0,0 +1,283 @@
+interface Workspace {
+    readonly root: string;
+    readFile(relPath: string): Promise<string>;
+    writeFile(relPath: string, data: string): Promise<void>;
+    /**
+     * Optional optimized read+metadata operation. Remote workspaces should
+     * implement this as one round trip when possible.
+     */
+    readFileWithStat?(relPath: string): Promise<{
+        content: string;
+        stat: Stat;
+    }>;
+    /**
+     * Optional optimized write+metadata operation. Remote workspaces should
+     * implement this as one round trip when possible.
+     */
+    writeFileWithStat?(relPath: string, data: string): Promise<Stat>;
+    unlink(relPath: string): Promise<void>;
+    readdir(relPath: string): Promise<Entry[]>;
+    stat(relPath: string): Promise<Stat>;
+    mkdir(relPath: string, opts?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    rename(fromRelPath: string, toRelPath: string): Promise<void>;
+    /**
+     * Optional change-event channel. Implementations that can observe
+     * out-of-band file changes (e.g. local fs via chokidar, or an
+     * in-process EventEmitter for sandbox-driven tool writes) return a
+     * watcher; implementations that can't observe changes (and don't
+     * want to fake it via polling) omit this method or leave it
+     * undefined.
+     *
+     * Frontends should always assume the method may be missing and
+     * degrade to "rely on tool-reported events + window-focus refetch."
+     * Calling `watch()` more than once on a single workspace must yield
+     * watchers that share the same underlying observation source —
+     * spawning N OS-level watchers per HTTP connection is not allowed.
+     */
+    watch?(): WorkspaceWatcher;
+    /**
+     * Capability hint for hosts that want to render a UI affordance
+     * ("connected"/"polling"/"manual refresh"). Optional — absence
+     * means "treat as 'none' and consult `watch?` for the truth." When
+     * present this is purely advisory; the actual events flow through
+     * `watch()`.
+     */
+    readonly fsCapability?: FsCapability;
+}
+type FsCapability = 'none' | 'best-effort' | 'strong';
+interface Entry {
+    name: string;
+    kind: 'file' | 'dir';
+}
+interface Stat {
+    size: number;
+    mtimeMs: number;
+    kind: 'file' | 'dir';
+}
+/**
+ * Single fs-event payload. `op` is the canonical mutation kind, the
+ * paths are workspace-relative, and `mtimeMs` is filled when the
+ * implementation can stat the result cheaply (lets the client run an
+ * idempotent staleness check without a follow-up stat request).
+ */
+interface WorkspaceChangeEvent {
+    op: 'write' | 'unlink' | 'rename' | 'mkdir';
+    path: string;
+    /** Set on rename only — the path before the move. */
+    oldPath?: string;
+    mtimeMs?: number;
+}
+interface WorkspaceWatcher {
+    /**
+     * Add a listener for change events. Returns an unsubscribe fn —
+     * the underlying observation source stays open until the workspace
+     * itself is disposed, so unsubscribing one listener is cheap and
+     * does NOT tear down the watcher.
+     */
+    subscribe(listener: (event: WorkspaceChangeEvent) => void): () => void;
+    /**
+     * Tear down the underlying observation source (chokidar instance,
+     * sandbox emitter binding, …). Idempotent. Subscribers added after
+     * close are no-ops. Hosts call this on workspace disposal.
+     */
+    close(): void;
+}
+
+/**
+ * Capabilities a sandbox advertises. Consumers use this set to decide
+ * whether a tool can run (e.g. `executeIsolatedCodeTool` only registers
+ * when `'isolated-code'` is present). Backends opt in by including the
+ * capability string in their `Sandbox.capabilities` array.
+ *
+ * Open string union — backends and downstream packages can extend it
+ * without modifying this file (TypeScript declaration-merging or just
+ * casting). New capabilities to expect over time:
+ *   - `'gpu'`           — backend can attach GPUs to isolated-code calls
+ *   - `'persistent-fs'` — backend retains workspace state across sessions
+ *   - `'snapshot'`      — backend supports baking + restoring snapshots
+ *   - `'network-allow'` — backend can apply egress allow/deny lists
+ */
+type SandboxCapability = 'exec' | 'isolated-code' | (string & {});
+/**
+ * Where the sandbox actually executes — relative to the agent backend
+ * process running pi.
+ *
+ * - `'server'` — same process / same host as the agent backend (e.g.
+ *   `DirectSandbox`, `BwrapSandbox`).
+ * - `'remote'` — a separate machine reached over the network (e.g.
+ *   `VercelSandboxExec` Firecracker VM, SSH, Modal, Docker host
+ *   accessed by API). Implementations must tolerate higher latency and
+ *   handle abort by signalling the remote.
+ * - `'browser'` — runs in the user's browser (e.g. WASM bash,
+ *   `JustBashSandbox`). Reserved for future browser-agent mode.
+ */
+type SandboxPlacement = 'server' | 'remote' | 'browser';
+interface Sandbox {
+    /** Stable identifier for this sandbox instance. */
+    readonly id: string;
+    /** Where the sandbox runs relative to the agent backend. */
+    readonly placement: SandboxPlacement;
+    /**
+     * Provider name — e.g. `'direct'`, `'bwrap'`, `'vercel-sandbox'`,
+     * `'docker'`, `'modal'`, `'apple-container'`, `'ssh'`. Used for
+     * telemetry, diagnostics, and capability negotiation. Free-form
+     * convention: matches the runtime mode id where one exists.
+     */
+    readonly provider: string;
+    /** Capabilities this sandbox advertises (used for tool gating). */
+    readonly capabilities: readonly SandboxCapability[];
+    /**
+     * Optional initialization hook. Some backends bind to a workspace +
+     * session at construction (Vercel: snapshot warm-up; Bwrap: bind
+     * mounts). Ephemeral backends (Direct, on-demand Docker exec) can
+     * omit this entirely.
+     */
+    init?(ctx: {
+        workspace: Workspace;
+        sessionId: string;
+    }): Promise<void>;
+    /**
+     * Run a shell command. Required capability: `'exec'`.
+     *
+     * Implementations MUST honor `signal` for abort, `timeoutMs` for
+     * timeout, and `maxOutputBytes` for output truncation (and set
+     * `truncated: true` in the result when truncation fires).
+     *
+     * The optional `onStdout` / `onStderr` callbacks (when implemented)
+     * stream output incrementally as bytes arrive. When omitted,
+     * implementations buffer normally and surface output via
+     * `ExecResult.stdout` / `stderr` only. See `Sandbox.exec` streaming
+     * extension under bead [Phase 1.0].
+     */
+    exec(cmd: string, opts?: ExecOptions): Promise<ExecResult>;
+    /**
+     * Run a self-contained snippet of code in an ephemeral sandbox
+     * instance. Capability: `'isolated-code'`. Optional — backends that
+     * cannot offer per-call isolation (`DirectSandbox`, `BwrapSandbox`)
+     * omit this method entirely.
+     */
+    executeIsolatedCode?(input: IsolatedCodeInput): Promise<IsolatedCodeOutput>;
+    dispose?(): Promise<void>;
+}
+interface ExecOptions {
+    cwd?: string;
+    env?: Record<string, string>;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    maxOutputBytes?: number;
+    onHeartbeat?: (elapsedMs: number) => void;
+    onStdout?: (chunk: Uint8Array) => void;
+    onStderr?: (chunk: Uint8Array) => void;
+}
+interface ExecResult {
+    stdout: Uint8Array;
+    stderr: Uint8Array;
+    exitCode: number;
+    durationMs: number;
+    truncated: boolean;
+    stdoutEncoding?: 'utf-8' | 'binary';
+    stderrEncoding?: 'utf-8' | 'binary';
+}
+/**
+ * Abstract resource hints for `executeIsolatedCode`. Backends round to
+ * their own size tiers (Vercel: `xxs`/…/`l`; Modal: `cpu`/`memory`
+ * floats; Docker: cgroups). Each field is a HINT, not a contract — a
+ * backend may ignore or clamp values it cannot honor.
+ */
+interface SandboxResources {
+    /** Requested logical CPU cores. Backend rounds up. */
+    cpuCores?: number;
+    /** Requested memory in MB. Backend rounds up. */
+    memoryMb?: number;
+    /**
+     * GPU class hint. Free-form vendor-specific token (e.g. `'t4'`,
+     * `'a10g'`, `'h100'`). Empty/omitted means CPU-only. Only honored
+     * when the sandbox advertises capability `'gpu'`.
+     */
+    gpu?: string;
+}
+interface IsolatedCodeInput {
+    code: string;
+    language: 'python' | 'shell';
+    /**
+     * Container / snapshot identifier. Format is vendor-specific:
+     * Docker → image ref (`node:20`), Vercel → `snapshotId`, Modal →
+     * image name, Apple-container → bundle path. Treat as opaque.
+     */
+    image?: string;
+    /**
+     * Per-call dependencies (npm/pip-style). Honored by backends that
+     * build environments on demand (Modal, Vercel snapshot-bake).
+     * Ignored by backends that require pre-built images (vanilla Docker
+     * exec).
+     */
+    packages?: string[];
+    /** Reuse an existing sandbox handle if the backend supports it. */
+    sandboxId?: string;
+    /** Generic resource request. Backends round to their own size tiers. */
+    resources?: SandboxResources;
+    /**
+     * Backend-specific knobs that don't fit the generic shape — opaque
+     * pass-through. Example: Modal's `min_containers`, Docker's
+     * `--cap-add`, Vercel's `region`. Consumers should never read this
+     * field; it exists so callers can target a specific provider.
+     */
+    vendorHints?: Record<string, unknown>;
+    /**
+     * @deprecated Use `resources` instead. Vercel-specific t-shirt
+     * sizes; kept for back-compat. Backends MAY map this to their own
+     * size taxonomy or ignore it. New consumers should use `resources`.
+     */
+    vmSize?: 'xxs' | 'xs' | 's' | 'm' | 'l';
+}
+interface IsolatedCodeOutput {
+    sandboxId: string;
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+
+type JSONSchema = Record<string, unknown>;
+interface AgentTool {
+    name: string;
+    description: string;
+    /** Optional one-line prompt entry. Pi-built tools should preserve pi's snippet verbatim. */
+    promptSnippet?: string;
+    parameters: JSONSchema;
+    execute(params: Record<string, unknown>, ctx: ToolExecContext): Promise<ToolResult>;
+}
+interface ToolExecContext {
+    abortSignal: AbortSignal;
+    toolCallId: string;
+    onUpdate?: (partial: string) => void;
+}
+interface ToolResult {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError?: boolean;
+    details?: unknown;
+}
+
+interface FileSearch {
+    search(glob: string, limit?: number): Promise<string[]>;
+}
+
+interface SandboxHandleRecord {
+    workspaceId: string;
+    sandboxId: string;
+    snapshotId?: string;
+    createdAt: string;
+    lastUsedAt: string;
+}
+interface SandboxHandleStore {
+    get(workspaceId: string): Promise<SandboxHandleRecord | null>;
+    put(record: SandboxHandleRecord): Promise<void>;
+    delete(workspaceId: string): Promise<void>;
+    list(): Promise<SandboxHandleRecord[]>;
+}
+
+export type { AgentTool as A, Entry as E, FileSearch as F, IsolatedCodeInput as I, JSONSchema as J, Sandbox as S, ToolExecContext as T, Workspace as W, ExecOptions as a, ExecResult as b, IsolatedCodeOutput as c, SandboxCapability as d, SandboxHandleRecord as e, SandboxHandleStore as f, Stat as g, ToolResult as h };

package/dist/server/index.d.ts

@@ -0,0 +1,327 @@
+import { S as Sandbox, f as SandboxHandleStore, e as SandboxHandleRecord, W as Workspace, F as FileSearch, A as AgentTool } from '../sandbox-handle-store-OPdvRwie.js';
+import { Sandbox as Sandbox$1 } from '@vercel/sandbox';
+import { FastifyInstance, FastifyRequest, FastifyPluginAsync } from 'fastify';
+import { PackageSource } from '@mariozechner/pi-coding-agent';
+
+declare function createDirectSandbox(): Sandbox;
+
+declare function createBwrapSandbox(): Sandbox;
+
+interface FileHandleStoreOptions {
+    storePath?: string;
+}
+declare class FileHandleStore implements SandboxHandleStore {
+    private readonly storePath;
+    constructor(opts?: FileHandleStoreOptions);
+    get(workspaceId: string): Promise<SandboxHandleRecord | null>;
+    put(record: SandboxHandleRecord): Promise<void>;
+    delete(workspaceId: string): Promise<void>;
+    list(): Promise<SandboxHandleRecord[]>;
+    private readStore;
+    private writeStore;
+}
+
+interface ResolveSandboxCreateParams {
+    name?: string;
+    persistent?: boolean;
+    snapshotExpiration?: number;
+    source?: {
+        type: 'snapshot';
+        snapshotId: string;
+    } | {
+        type: 'tarball';
+        url: string;
+    };
+}
+type VercelSandboxHandle = Sandbox$1 & {
+    sandboxId?: string;
+    name?: string;
+    currentSnapshotId?: string;
+    sourceSnapshotId?: string;
+};
+interface VercelSandboxClient {
+    create(params?: ResolveSandboxCreateParams): Promise<VercelSandboxHandle>;
+    get(params: {
+        sandboxId?: string;
+        name?: string;
+        resume?: boolean;
+    }): Promise<VercelSandboxHandle>;
+}
+interface SandboxLifecycleLogger {
+    info?(message: string, metadata: Record<string, unknown>): void;
+    warn?(message: string, metadata: Record<string, unknown>): void;
+}
+type ExpiredSandboxPolicy = 'recreate' | 'error';
+interface ResolveSandboxHandleOptions {
+    tarballUrl?: string;
+    maxIdleMs?: number;
+    now?: () => number;
+    logger?: SandboxLifecycleLogger;
+    expiredSandboxPolicy?: ExpiredSandboxPolicy;
+}
+declare function resolveSandboxHandle(workspaceId: string, store: SandboxHandleStore, vercel: VercelSandboxClient, opts?: ResolveSandboxHandleOptions): Promise<VercelSandboxHandle>;
+
+interface VercelCommandResult {
+    exitCode: number;
+    stdout(opts?: {
+        signal?: AbortSignal;
+    }): Promise<string>;
+    stderr(opts?: {
+        signal?: AbortSignal;
+    }): Promise<string>;
+}
+interface VercelBakeSandbox {
+    runCommand(command: string, args?: string[], opts?: {
+        signal?: AbortSignal;
+    }): Promise<VercelCommandResult>;
+    snapshot(opts?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        snapshotId: string;
+    }>;
+    stop?(opts?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+}
+interface VercelBakeClient {
+    create(params?: {
+        runtime?: string;
+    }): Promise<VercelBakeSandbox>;
+}
+interface BakeLogger {
+    info?: (...args: unknown[]) => void;
+    warn?: (...args: unknown[]) => void;
+}
+type SnapshotBakeStatus = 'skipped' | 'cache-hit' | 'baked' | 'failed';
+type SnapshotBakeReason = 'snapshot-id-configured' | 'no-packages' | 'cache-hit' | 'baked' | 'bake-failed';
+interface SnapshotBakeResult {
+    status: SnapshotBakeStatus;
+    reason: SnapshotBakeReason;
+    hash?: string;
+    snapshotId?: string;
+    error?: unknown;
+}
+interface SnapshotBakeOptions {
+    client: VercelBakeClient;
+    pythonPackages?: readonly string[];
+    systemPackages?: readonly string[];
+    setupCommands?: readonly string[];
+    snapshotId?: string;
+    runtime?: string;
+    cachePath?: string;
+    logger?: BakeLogger;
+    now?: () => Date;
+}
+declare function buildPackageHash(input: {
+    pythonPackages?: readonly string[];
+    systemPackages?: readonly string[];
+}): string;
+declare function buildSnapshotRecipeHash(input: {
+    runtime?: string;
+    pythonPackages?: readonly string[];
+    systemPackages?: readonly string[];
+    setupCommands?: readonly string[];
+}): string;
+declare function bakeSnapshotIfNeeded(opts: SnapshotBakeOptions): Promise<SnapshotBakeResult>;
+
+declare const UV_SETUP_COMMANDS: readonly ["command -v uv >/dev/null 2>&1 || python3 -m pip install --upgrade uv", "uv --version"];
+type DeploymentSnapshotStatus = 'skipped' | 'cache-hit' | 'baked' | 'failed';
+interface DeploymentSnapshotRecipe {
+    /** Provider runtime/image selector. Example: Vercel's python3.13 runtime. */
+    runtime?: string;
+    /** OS packages to bake into the reusable runtime layer. */
+    systemPackages?: readonly string[];
+    /** Python packages to bake into the reusable runtime layer. */
+    pythonPackages?: readonly string[];
+    /** Ordered setup commands for runtime primitives such as uv. */
+    setupCommands?: readonly string[];
+}
+interface DeploymentSnapshotResult {
+    status: DeploymentSnapshotStatus;
+    reason: string;
+    hash?: string;
+    snapshotId?: string;
+    error?: unknown;
+}
+interface DeploymentSnapshotProvider {
+    prepareDeploymentSnapshot(recipe: DeploymentSnapshotRecipe): Promise<DeploymentSnapshotResult>;
+}
+interface BuildDeploymentSnapshotRecipeOptions extends DeploymentSnapshotRecipe {
+    /** Defaults true: install/check uv at deploy-time so workspaces boot fast. */
+    includeUv?: boolean;
+}
+declare function buildDeploymentSnapshotRecipe(opts?: BuildDeploymentSnapshotRecipeOptions): DeploymentSnapshotRecipe;
+declare function prepareDeploymentSnapshot(provider: DeploymentSnapshotProvider, recipe: DeploymentSnapshotRecipe): Promise<DeploymentSnapshotResult>;
+
+interface VercelDeploymentSnapshotOptions {
+    client: VercelBakeClient;
+    snapshotId?: string;
+    runtime?: string;
+    cachePath?: string;
+    logger?: BakeLogger;
+    now?: () => Date;
+    /**
+     * Extra deploy-time setup commands baked into the reusable snapshot.
+     * Use for runtime primitives such as uv or OS tools, not workspace content.
+     */
+    setupCommands?: readonly string[];
+    pythonPackages?: readonly string[];
+    systemPackages?: readonly string[];
+}
+declare function createVercelDeploymentSnapshotProvider(opts: Omit<VercelDeploymentSnapshotOptions, 'runtime' | 'setupCommands' | 'pythonPackages' | 'systemPackages'>): DeploymentSnapshotProvider;
+declare function prepareVercelDeploymentSnapshot(opts: VercelDeploymentSnapshotOptions): Promise<SnapshotBakeResult>;
+
+declare function createNodeWorkspace(root: string): Workspace;
+
+interface RuntimeTemplateContribution {
+    id: string;
+    path: string | URL;
+    target?: string;
+}
+interface RuntimePythonSpec {
+    id: string;
+    /** uv-compatible pyproject.toml. Console scripts declared here are exposed to the agent. */
+    projectFile: string | URL;
+    /** Extra workspace libraries to install into the same environment. */
+    extraLibs?: string[];
+    /** Env vars exported by command shims, e.g. plugin builtin paths. */
+    env?: Record<string, string | URL>;
+}
+interface RuntimeProvisioningContribution {
+    templateDirs?: RuntimeTemplateContribution[];
+    python?: RuntimePythonSpec[];
+}
+interface ProvisionRuntimeWorkspaceOptions {
+    workspaceRoot: string;
+    contributions?: Array<{
+        id: string;
+        provisioning?: RuntimeProvisioningContribution;
+    }>;
+    force?: boolean;
+}
+interface RuntimeWorkspaceProvisioningResult {
+    fingerprint: string;
+    changed: boolean;
+    env: Record<string, string>;
+    binDir: string;
+}
+declare function provisionRuntimeWorkspace({ workspaceRoot, contributions, force, }: ProvisionRuntimeWorkspaceOptions): Promise<RuntimeWorkspaceProvisioningResult>;
+
+interface VercelSandboxWorkspace extends Workspace {
+    invalidateMetadataCache(): void;
+}
+interface VercelSandboxWorkspaceOptions {
+    onMutation?: () => void;
+}
+declare function createVercelSandboxWorkspace(sandbox: Sandbox$1, workspaceOpts?: VercelSandboxWorkspaceOptions): VercelSandboxWorkspace;
+
+type RuntimeModeId = 'direct' | 'local' | 'vercel-sandbox';
+interface RuntimeModeAdapter {
+    readonly id: RuntimeModeId;
+    create(ctx: ModeContext): Promise<RuntimeBundle>;
+    dispose?(): Promise<void>;
+}
+interface ModeContext {
+    workspaceRoot: string;
+    sessionId: string;
+    workspaceId?: string;
+    templatePath?: string;
+}
+interface RuntimeBundle {
+    workspace: Workspace;
+    sandbox: Sandbox;
+    fileSearch: FileSearch;
+}
+
+declare function hasBwrap(): boolean;
+declare function autoDetectMode(): RuntimeModeId;
+declare function resolveMode(mode?: RuntimeModeId): RuntimeModeAdapter;
+
+type PiPackageSource = PackageSource;
+declare const PI_PACKAGE_RESOURCE_FILTERS: readonly ["extensions", "skills", "prompts", "themes"];
+declare function piPackageSourceKey(source: PiPackageSource): string;
+declare function compactPiPackages(sources: Array<PiPackageSource | undefined>): PiPackageSource[];
+declare function mergePiPackageSources(base?: PiPackageSource[], additional?: PiPackageSource[]): PiPackageSource[];
+
+interface PiResourceLoaderOptions {
+    noContextFiles?: boolean;
+    noSkills?: boolean;
+    additionalSkillPaths?: string[];
+    /**
+     * Additional native Pi package sources to enable for this agent runtime.
+     * These are applied as in-memory SettingsManager overrides, so host/plugin
+     * declarations do not mutate .pi/settings.json.
+     */
+    piPackages?: PiPackageSource[];
+}
+
+interface CreateAgentAppOptions {
+    workspaceRoot?: string;
+    sessionId?: string;
+    templatePath?: string;
+    mode?: RuntimeModeId;
+    authToken?: string;
+    version?: string;
+    logger?: boolean;
+    extraTools?: AgentTool[];
+    /** When true, omit the six filesystem tools (read/write/edit/find/grep/ls). */
+    disableDefaultFileTools?: boolean;
+    /**
+     * Append-only addendum to the underlying agent's system prompt. Cannot
+     * replace the base prompt — host apps EXTEND it (e.g. document app-
+     * specific tools, panes, data conventions). Plumbed to pi-coding-agent
+     * via DefaultResourceLoader's `appendSystemPromptSource`.
+     */
+    systemPromptAppend?: string;
+    /** Optional pi resource-loader isolation knobs. */
+    resourceLoaderOptions?: PiResourceLoaderOptions;
+}
+declare function createAgentApp(opts?: CreateAgentAppOptions): Promise<FastifyInstance>;
+
+interface HeaderLike {
+    setHeader(name: string, value: string): void;
+}
+declare function applyCspHeaders(response: HeaderLike, opts?: {
+    dev?: boolean;
+}): void;
+
+interface RegisterAgentRoutesOptions {
+    workspaceRoot?: string;
+    sessionId?: string;
+    templatePath?: string;
+    mode?: RuntimeModeId;
+    version?: string;
+    extraTools?: AgentTool[];
+    getExtraTools?: (ctx: {
+        workspaceId: string;
+        workspaceRoot: string;
+        runtimeMode: RuntimeModeId;
+    }) => AgentTool[] | Promise<AgentTool[]>;
+    systemPromptAppend?: string;
+    resourceLoaderOptions?: PiResourceLoaderOptions;
+    registerHealthRoute?: boolean;
+    sandboxHandleStore?: SandboxHandleStore;
+    getWorkspaceId?: (request: FastifyRequest) => string | Promise<string>;
+    getWorkspaceRoot?: (workspaceId: string, request: FastifyRequest) => string | Promise<string>;
+}
+/**
+ * Fastify plugin that mounts agent routes onto a host app (typically core-built).
+ *
+ * Shape B counterpart to createAgentApp (Shape A). The host provides its own
+ * Fastify instance, auth, and stores; this plugin only adds routes + runtime.
+ * No auth middleware is registered — the host's authHook handles authentication.
+ */
+declare const registerAgentRoutes: FastifyPluginAsync<RegisterAgentRoutesOptions>;
+
+interface LogFields {
+    [key: string]: unknown;
+}
+interface Logger {
+    debug(msg: string, fields?: LogFields): void;
+    info(msg: string, fields?: LogFields): void;
+    warn(msg: string, fields?: LogFields): void;
+    error(msg: string, fields?: LogFields): void;
+}
+declare function createLogger(prefix: string): Logger;
+
+export { type CreateAgentAppOptions, type DeploymentSnapshotProvider, type DeploymentSnapshotRecipe, type DeploymentSnapshotResult, type DeploymentSnapshotStatus, FileHandleStore, type LogFields, type Logger, type ModeContext, PI_PACKAGE_RESOURCE_FILTERS, type PiPackageSource, type PiResourceLoaderOptions, type ProvisionRuntimeWorkspaceOptions, type RegisterAgentRoutesOptions, type RuntimeBundle, type RuntimeModeAdapter, type RuntimeModeId, type RuntimeProvisioningContribution, type RuntimePythonSpec, type RuntimeTemplateContribution, type RuntimeWorkspaceProvisioningResult, type SnapshotBakeOptions, type SnapshotBakeResult, UV_SETUP_COMMANDS, UV_SETUP_COMMANDS as VERCEL_UV_SETUP_COMMANDS, type VercelBakeClient, type VercelBakeSandbox, type VercelDeploymentSnapshotOptions, applyCspHeaders, autoDetectMode, bakeSnapshotIfNeeded, buildDeploymentSnapshotRecipe, buildPackageHash, buildSnapshotRecipeHash, compactPiPackages, createAgentApp, createBwrapSandbox, createDirectSandbox, createLogger, createNodeWorkspace, createVercelDeploymentSnapshotProvider, createVercelSandboxWorkspace, hasBwrap, mergePiPackageSources, piPackageSourceKey, prepareDeploymentSnapshot, prepareVercelDeploymentSnapshot, provisionRuntimeWorkspace, registerAgentRoutes, resolveMode, resolveSandboxHandle };