@hachej/boring-agent 0.1.89 → 0.1.90

package/dist/server/index.d.ts

@@ -1,140 +1,20 @@
-import { W as WorkspaceRuntimeContext, S as Sandbox, a as Workspace, E as ExecOptions, b as ExecResult, c as WorkspaceChangeEvent } from '../sandbox-DthfJaOB.js';
-import { R as RemoteWorkerWorkspaceOp, a as RemoteWorkerWorkspaceResult, b as RemoteWorkerExecRequest } from '../protocol-B_OQKfbI.js';
-export { B as BwrapResourceLimits, C as CreateBwrapSandboxOptions, c as REMOTE_WORKER_PROVIDER, d as REMOTE_WORKER_RUNTIME_CWD, e as RemoteWorkerErrorPayload, f as RemoteWorkerExecResponse, g as RemoteWorkerFsEventEnvelope, W as WORKER_INTERNAL_TOKEN_HEADER, h as WORKER_REQUEST_ID_HEADER, i as WORKER_WORKSPACE_ID_HEADER, j as createBwrapSandbox } from '../protocol-B_OQKfbI.js';
-import { S as SandboxHandleStore, a as SandboxHandleRecord, F as FileSearch, C as CompiledAgentBundle, b as Sha256Digest, A as AgentDeployment, c as ShareEntryStore, P as PluginRestartWarning, W as WorkspaceAgentDispatcherContext, d as WorkspaceAgentDispatcher } from '../workspaceAgentDispatcher-CKEeNPjW.js';
-import { Sandbox as Sandbox$1 } from '@vercel/sandbox';
-import { T as TelemetrySink, s as ToolReadinessRequirement, t as AgentConfig, b as Agent, d as AgentActor, j as AgentEvent, u as AgentTool, v as AgentHarnessFactory } from '../harness-VvP0l5Mj.js';
-export { w as AgentHarnessFactoryInput } from '../harness-VvP0l5Mj.js';
-import { FastifyInstance, FastifyRequest, FastifyPluginAsync } from 'fastify';
-import { E as ErrorCode, l as SessionCtx, m as ChatModelSelection } from '../piChatEvent-nmOBSNU9.js';
+import { F as FileSearch, C as CompiledAgentBundle, S as Sha256Digest, A as AgentDeployment, a as ShareEntryStore, P as PluginRestartWarning, W as WorkspaceAgentDispatcherContext, b as WorkspaceAgentDispatcher } from '../workspaceAgentDispatcher-50Uzuxhs.js';
+import { W as Workspace, a as WorkspaceRuntimeContext, S as Sandbox, E as ExecOptions, b as ExecResult, c as WorkspaceChangeEvent } from '../sandbox-OEG_l9GE.js';
+import { T as ToolReadinessRequirement, s as TelemetrySink, t as AgentConfig, b as Agent, u as AgentTool, d as AgentActor, j as AgentEvent, v as AgentHarnessFactory } from '../harness-Rbkdpvse.js';
+export { w as AgentHarnessFactoryInput } from '../harness-Rbkdpvse.js';
+import { RuntimeHostOperations } from '@hachej/boring-bash/agent';
+import { CreateNodeWorkspaceOptions, BoringAgentRuntimePaths } from '@hachej/boring-sandbox/providers/node-workspace';
+import { R as RemoteWorkerWorkspaceOp, a as RemoteWorkerWorkspaceResult, b as RemoteWorkerExecRequest } from '../protocol-CDA4bcP9.js';
+export { c as REMOTE_WORKER_PROVIDER, d as REMOTE_WORKER_RUNTIME_CWD, e as RemoteWorkerErrorPayload, f as RemoteWorkerExecResponse, g as RemoteWorkerFsEventEnvelope, W as WORKER_INTERNAL_TOKEN_HEADER, h as WORKER_REQUEST_ID_HEADER, i as WORKER_WORKSPACE_ID_HEADER } from '../protocol-CDA4bcP9.js';
+import { SandboxProviderV1, WorkspaceSandboxPairV1 } from '@hachej/boring-sandbox/shared';
+import { E as ErrorCode, l as SessionCtx, m as ChatModelSelection } from '../piChatEvent-CHgln6yx.js';
 import { IncomingMessage, ServerResponse } from 'node:http';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { FastifyRequest, FastifyInstance, FastifyPluginAsync } from 'fastify';
 import { PackageSource, ExtensionFactory, SettingsManager } from '@mariozechner/pi-coding-agent';
-import { a as AgentEffectAdmission } from '../piChatSessionService-DPjJ0g71.js';
+import { a as AgentEffectAdmission } from '../piChatSessionService-DDKPOj4x.js';
 import 'zod';
 
-interface CreateDirectSandboxOptions {
-    runtimeContext?: WorkspaceRuntimeContext;
-}
-declare function createDirectSandbox(opts?: CreateDirectSandboxOptions): 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>;
-
 /**
  * uv setup for Python-family runtimes (e.g. Vercel `python3.13`), which already
  * ship `pip` and usually `uv`. Verify-or-install via the on-PATH `uv`.
@@ -168,63 +48,88 @@ interface BuildDeploymentSnapshotRecipeOptions extends DeploymentSnapshotRecipe
 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 resolveWorkspaceRoot(defaultRoot?: string): string;
 
-interface CreateNodeWorkspaceOptions {
-    runtimeContext?: WorkspaceRuntimeContext;
+type ReadyState = 'provisioning' | 'ready' | 'degraded';
+type CapabilityState = 'not-started' | 'preparing' | 'ready' | 'failed';
+interface CapabilityReadinessDetail {
+    state: CapabilityState;
+    requirement?: ToolReadinessRequirement;
+    startedAt?: string;
+    completedAt?: string;
+    errorCode?: string;
+    causeCode?: string;
+    retryable?: boolean;
+    message?: string;
+}
+interface AgentCapabilityReadiness {
+    chat: CapabilityReadinessDetail;
+    workspace: CapabilityReadinessDetail;
+    runtimeDependencies: CapabilityReadinessDetail;
+}
+interface ReadyStatusEvent {
+    state: ReadyState;
+    sandboxReady: boolean;
+    harnessReady: boolean;
+    capabilities: AgentCapabilityReadiness;
+    message?: string;
+    timestamp: string;
+}
+interface ReadinessSnapshot {
+    sandboxReady: boolean;
+    harnessReady: boolean;
+    capabilities: AgentCapabilityReadiness;
+    degradedReason?: string;
+}
+type StatusHandler = (event: ReadyStatusEvent) => void;
+declare class ReadyStatusTracker {
+    private _sandboxReady;
+    private _harnessReady;
+    private _degradedReason?;
+    private _capabilities;
+    private subscribers;
+    constructor(opts?: {
+        sandboxReady?: boolean;
+        harnessReady?: boolean;
+        capabilities?: Partial<AgentCapabilityReadiness>;
+    });
+    get state(): ReadyState;
+    isReady(): boolean;
+    getReadiness(): ReadinessSnapshot;
+    getCapabilities(): AgentCapabilityReadiness;
+    updateCapability(name: keyof AgentCapabilityReadiness, detail: CapabilityReadinessDetail): void;
+    updateRuntimeDependencies(detail: CapabilityReadinessDetail): void;
+    markSandboxReady(): void;
+    markHarnessReady(): void;
+    markDegraded(reason: string): void;
+    clearDegraded(): void;
+    subscribe(handler: StatusHandler): () => void;
+    private emit;
+    private snapshot;
 }
-declare function createNodeWorkspace(root: string, opts?: CreateNodeWorkspaceOptions): Workspace;
 
 /**
- * Validate and resolve a user-provided relative path under workspaceRoot.
- */
-declare function validatePath(workspaceRoot: string, relPath: string): string;
-/**
- * Resolve symlinks and ensure candidate path remains under workspaceRoot.
+ * Host-owned values used by Agent's provider-neutral runtime composition.
+ *
+ * The concrete implementation lives outside packages/agent/src so Agent can
+ * consume an injected Workspace + Sandbox pair without importing provider
+ * runtime values.
  */
-declare function assertRealPathWithinWorkspace(workspaceRoot: string, absPath: string): Promise<void>;
-
-declare function resolveWorkspaceRoot(defaultRoot?: string): string;
-
-interface BoringAgentRuntimePaths {
-    /** Runtime-visible workspace root. This is BORING_AGENT_WORKSPACE_ROOT. */
-    workspaceRoot: string;
-    agentDir: string;
-    node: string;
-    nodeModules: string;
-    nodeBin: string;
-    venv: string;
-    venvBin: string;
-    venvPython: string;
-    sdk: string;
-    uvHome: string;
-    uvBin: string;
-    skills: string;
-    cache: string;
-    nodeCache: string;
-    uvCache: string;
-    pipCache: string;
-    tmp: string;
-}
-declare function getBoringAgentRuntimePaths(runtimeWorkspaceRoot: string): BoringAgentRuntimePaths;
-declare function getBoringAgentPathEntries(paths: BoringAgentRuntimePaths): string[];
-declare function getBoringAgentRuntimeEnv(paths: BoringAgentRuntimePaths, adapterCacheRoot?: string): Record<string, string>;
+interface AgentRuntimeHostOperations extends RuntimeHostOperations {
+    createNodeWorkspace(root: string, options?: CreateNodeWorkspaceOptions): Workspace;
+    getNodeWorkspaceHostRoot(workspace: Workspace): string | undefined;
+    getBoringAgentRuntimePaths(workspaceRoot: string): BoringAgentRuntimePaths;
+    getBoringAgentRuntimeEnv(paths: BoringAgentRuntimePaths, cacheRoot?: string): Record<string, string>;
+    getBoringAgentPathEntries(paths: BoringAgentRuntimePaths): string[];
+    readonly runtimeLayout: Readonly<{
+        agentDir: string;
+        runtimeDirNames: readonly string[];
+        gitignoreContent: string;
+    }>;
+    validatePath(root: string, requestedPath: string): string;
+    assertRealPathWithinWorkspace(root: string, targetPath: string): Promise<void>;
+    isIgnoredDirName(name: string): boolean;
+}
 
 interface ProvisioningLogger {
     info?(message: string, fields?: Record<string, unknown>): void;
@@ -313,6 +218,7 @@ interface ProvisionWorkspaceRuntimeOptions {
     }>;
     adapter: WorkspaceProvisioningAdapter;
     runtimeLayout: BoringAgentRuntimePaths;
+    runtimeHost: AgentRuntimeHostOperations;
     logger?: ProvisioningLogger;
     telemetry?: TelemetrySink;
     telemetryContext?: ProvisioningTelemetryContext;
@@ -320,64 +226,6 @@ interface ProvisionWorkspaceRuntimeOptions {
 
 declare function provisionWorkspaceRuntime(opts: ProvisionWorkspaceRuntimeOptions): Promise<WorkspaceProvisioningResult>;
 
-type ReadyState = 'provisioning' | 'ready' | 'degraded';
-type CapabilityState = 'not-started' | 'preparing' | 'ready' | 'failed';
-interface CapabilityReadinessDetail {
-    state: CapabilityState;
-    requirement?: ToolReadinessRequirement;
-    startedAt?: string;
-    completedAt?: string;
-    errorCode?: string;
-    causeCode?: string;
-    retryable?: boolean;
-    message?: string;
-}
-interface AgentCapabilityReadiness {
-    chat: CapabilityReadinessDetail;
-    workspace: CapabilityReadinessDetail;
-    runtimeDependencies: CapabilityReadinessDetail;
-}
-interface ReadyStatusEvent {
-    state: ReadyState;
-    sandboxReady: boolean;
-    harnessReady: boolean;
-    capabilities: AgentCapabilityReadiness;
-    message?: string;
-    timestamp: string;
-}
-interface ReadinessSnapshot {
-    sandboxReady: boolean;
-    harnessReady: boolean;
-    capabilities: AgentCapabilityReadiness;
-    degradedReason?: string;
-}
-type StatusHandler = (event: ReadyStatusEvent) => void;
-declare class ReadyStatusTracker {
-    private _sandboxReady;
-    private _harnessReady;
-    private _degradedReason?;
-    private _capabilities;
-    private subscribers;
-    constructor(opts?: {
-        sandboxReady?: boolean;
-        harnessReady?: boolean;
-        capabilities?: Partial<AgentCapabilityReadiness>;
-    });
-    get state(): ReadyState;
-    isReady(): boolean;
-    getReadiness(): ReadinessSnapshot;
-    getCapabilities(): AgentCapabilityReadiness;
-    updateCapability(name: keyof AgentCapabilityReadiness, detail: CapabilityReadinessDetail): void;
-    updateRuntimeDependencies(detail: CapabilityReadinessDetail): void;
-    markSandboxReady(): void;
-    markHarnessReady(): void;
-    markDegraded(reason: string): void;
-    clearDegraded(): void;
-    subscribe(handler: StatusHandler): () => void;
-    private emit;
-    private snapshot;
-}
-
 type BuiltinRuntimeModeId = 'direct' | 'local' | 'vercel-sandbox';
 type RuntimeModeId = BuiltinRuntimeModeId | (string & {});
 interface RuntimeModeReadinessHooks {
@@ -423,6 +271,7 @@ type RuntimeFilesystemStrategy = {
 };
 interface RuntimeModeAdapter {
     readonly id: RuntimeModeId;
+    readonly runtimeHost?: AgentRuntimeHostOperations;
     /**
      * Declares whether the workspace files are strongly available on the host
      * path before create() runs. Composition layers use this to decide whether
@@ -432,11 +281,10 @@ interface RuntimeModeAdapter {
     readonly readiness?: RuntimeModeReadinessHooks;
     readonly cachedBindingHealthCheck?: RuntimeCachedBindingHealthCheck;
     create(ctx: ModeContext): Promise<RuntimeBundle>;
-    createProvisioningAdapter?(runtimeLayout: BoringAgentRuntimePaths, ctx?: ModeContext): WorkspaceProvisioningAdapter;
     getRuntimeLayoutRoot?(ctx: ModeContext): string;
     evictCachedRuntime?(ctx: {
         workspaceId: string;
-    }): void;
+    }): void | Promise<void>;
     dispose?(): Promise<void>;
 }
 interface ModeContext {
@@ -544,6 +392,8 @@ interface RuntimeBundle {
     workspace: Workspace;
     sandbox: Sandbox;
     fileSearch: FileSearch;
+    /** Host-owned provider utilities injected at the application boundary. */
+    runtimeHost?: AgentRuntimeHostOperations;
     /** Optional per-execution runtime env provider for local/direct operations that do not call Sandbox.exec. */
     getRuntimeEnv?: () => Promise<Record<string, string>>;
     /** Runtime-owned bash execution strategy, consumed by the agent bash tool builder. */
@@ -552,6 +402,10 @@ interface RuntimeBundle {
     filesystem?: RuntimeFilesystemStrategy;
     /** Optional filesystem bindings prepared for this runtime/session. */
     filesystemBindings?: RuntimeFilesystemBinding[];
+    /** Provisioning operations derived from this bundle's acquired Workspace + Sandbox pair. */
+    provisioningAdapter?: WorkspaceProvisioningAdapter;
+    /** Idempotently releases the acquired Workspace + Sandbox pair. */
+    disposeRuntime?: () => Promise<void>;
 }
 
 interface RemoteWorkerClientOptions {
@@ -611,13 +465,6 @@ declare function createRemoteWorkerWorkspace(client: RemoteWorkerClient): Worksp
 
 declare function createRemoteWorkerSandbox(client: RemoteWorkerClient): Sandbox;
 
-declare function fileRoutes(app: FastifyInstance, opts: {
-    workspace?: Workspace;
-    getWorkspace?: (request: FastifyRequest) => Workspace | Promise<Workspace>;
-    filesystemBindings?: RuntimeFilesystemBinding[];
-    getFilesystemBindings?: (request: FastifyRequest) => RuntimeFilesystemBinding[] | undefined | Promise<RuntimeFilesystemBinding[] | undefined>;
-}, done: (err?: Error) => void): void;
-
 interface RuntimeTemplateContribution {
     id: string;
     path: string | URL;
@@ -660,15 +507,6 @@ interface RuntimeWorkspaceProvisioningResult {
 }
 declare function provisionRuntimeWorkspace({ workspaceRoot, contributions, force, }: ProvisionRuntimeWorkspaceOptions): Promise<RuntimeWorkspaceProvisioningResult>;
 
-declare const VERCEL_SANDBOX_WORKSPACE_ROOT = "/workspace";
-interface VercelSandboxWorkspace extends Workspace {
-    invalidateMetadataCache(): void;
-}
-interface VercelSandboxWorkspaceOptions {
-    onMutation?: () => void;
-}
-declare function createVercelSandboxWorkspace(sandbox: Sandbox$1, workspaceOpts?: VercelSandboxWorkspaceOptions): VercelSandboxWorkspace;
-
 type ProvisioningArtifactKind = 'node' | 'python';
 /** What a per-mode packer receives to produce one artifact. `id`/`fingerprint`
  * are passed through (not used by the default packer, but part of the public
@@ -681,27 +519,46 @@ interface ProvisioningArtifactRequest {
     outputPath: string;
 }
 
-declare const VERCEL_PROVISIONING_CACHE_ROOT = "/tmp/boring-agent-cache";
-interface CreateVercelProvisioningAdapterOptions {
-    runtimeLayout: BoringAgentRuntimePaths;
-    workspaceFs: WorkspaceProvisioningAdapter['workspaceFs'];
-    exec(command: string, args: string[], opts?: {
-        cwd?: string;
-        env?: Record<string, string>;
-        timeoutMs?: number;
-    }): Promise<WorkspaceProvisioningExecResult | void>;
-    prepareArtifact(request: ProvisioningArtifactRequest): Promise<void>;
-    cacheRoot?: string;
-}
-declare function createVercelProvisioningAdapter(options: CreateVercelProvisioningAdapterOptions): WorkspaceProvisioningAdapter;
-
 declare function hasBwrap(): boolean;
 declare function autoDetectMode(): RuntimeModeId;
 interface ResolveModeOptions {
-    sandboxHandleStore?: SandboxHandleStore;
+    adapters?: Readonly<Record<BuiltinRuntimeModeId, RuntimeModeAdapter>>;
 }
 declare function resolveMode(mode?: RuntimeModeId, opts?: ResolveModeOptions): RuntimeModeAdapter;
 
+declare function createDirectModeAdapter(options: {
+    provider: SandboxProviderV1;
+    runtimeHost: AgentRuntimeHostOperations;
+}): RuntimeModeAdapter;
+
+declare function createLocalModeAdapter(options: {
+    provider: SandboxProviderV1;
+    runtimeHost: AgentRuntimeHostOperations;
+}): RuntimeModeAdapter;
+
+declare function createVercelSandboxModeAdapter(options: {
+    provider: SandboxProviderV1;
+    runtimeHost: AgentRuntimeHostOperations;
+    remoteRoot: string;
+    workspaceRoot: string;
+}): RuntimeModeAdapter;
+
+interface ProviderRuntimeModeAdapterOptions {
+    id: 'direct' | 'local' | 'vercel-sandbox';
+    provider: SandboxProviderV1;
+    runtimeHost: AgentRuntimeHostOperations;
+    workspaceFsCapability: 'strong' | 'best-effort';
+    bash: RuntimeBashStrategy;
+    filesystem: RuntimeFilesystemStrategy;
+    storageRoot?: (context: ModeContext) => string | undefined;
+    preflight?: (context: ModeContext) => void | Promise<void>;
+    prepare?: (context: ModeContext) => Promise<void>;
+    provisioningAdapter?: (context: ModeContext, pair: WorkspaceSandboxPairV1) => WorkspaceProvisioningAdapter | undefined;
+    healthCheckIntervalMs?: number;
+    readiness?: RuntimeModeAdapter['readiness'];
+}
+declare function createProviderRuntimeModeAdapter(options: ProviderRuntimeModeAdapterOptions): RuntimeModeAdapter;
+
 declare function createAgent(config: AgentConfig): Agent;
 
 type AgentDirectoryCompilerErrorCode = 'AGENT_DIRECTORY_NOT_FOUND' | 'AGENT_DIRECTORY_NOT_DIRECTORY' | 'AGENT_MANIFEST_NOT_FOUND' | 'AGENT_MANIFEST_NOT_FILE' | 'AGENT_MANIFEST_INVALID_UTF8' | 'AGENT_MANIFEST_INVALID_JSON' | 'AGENT_ASSET_NOT_FOUND' | 'AGENT_ASSET_NOT_FILE' | 'AGENT_ASSET_INVALID_UTF8' | 'AGENT_PATH_SYMLINK_ESCAPE' | 'AGENT_PATH_CHANGED_DURING_READ' | 'AGENT_DIRECTORY_IO_FAILED';
@@ -720,6 +577,33 @@ declare class AgentDirectoryCompilerError extends Error {
 }
 declare function compileAgentDirectory(directory: string): Promise<CompiledAgentBundle>;
 
+type AuthoredAgentMaterializationErrorCode = Extract<ErrorCode, 'AUTHORED_AGENT_ID_INVALID' | 'AUTHORED_AGENT_TYPE_MISMATCH' | 'AUTHORED_AGENT_CATALOG_REQUIRED' | 'AUTHORED_AGENT_CATALOG_INVALID' | 'AUTHORED_AGENT_REFERENCE_UNKNOWN' | 'AUTHORED_AGENT_REFERENCE_UNSUPPORTED' | 'AUTHORED_AGENT_TOOL_INVALID' | 'AUTHORED_AGENT_TOOL_COLLISION'>;
+type MaterializedAgentSourceV1 = Readonly<{
+    schemaVersion: 1;
+    agentTypeId: string;
+    version: string;
+    label?: string;
+    instructions: string;
+    tools: readonly AgentTool[];
+    declaredToolRefs: readonly string[];
+}>;
+type AuthoredAgentToolCatalog = ReadonlyMap<string, AgentTool>;
+interface MaterializeAgentDirectoryInput {
+    directory: string;
+    expectedAgentTypeId?: string;
+    toolCatalog?: AuthoredAgentToolCatalog;
+}
+declare class AuthoredAgentMaterializationError extends Error {
+    readonly code: AuthoredAgentMaterializationErrorCode;
+    readonly field?: string;
+    constructor(input: {
+        code: AuthoredAgentMaterializationErrorCode;
+        field?: string;
+        message: string;
+    });
+}
+declare function materializeAgentDirectory(input: MaterializeAgentDirectoryInput): Promise<MaterializedAgentSourceV1>;
+
 interface ResolvedAgentDigestInput {
     readonly workspaceId: string;
     readonly defaultDeploymentId: string;
@@ -1142,6 +1026,8 @@ interface CreateAgentAppOptions {
     mode?: RuntimeModeId;
     /** Supply a custom runtime adapter to plug in non-built-in sandbox/workspace modes. */
     runtimeModeAdapter?: RuntimeModeAdapter;
+    /** Provider/runtime values supplied by the embedding host. */
+    runtimeHost?: AgentRuntimeHostOperations;
     authToken?: string;
     version?: string;
     logger?: boolean;
@@ -1295,6 +1181,8 @@ interface RegisterAgentRoutesOptions {
     mode?: RuntimeModeId;
     /** Supply a custom runtime adapter to plug in non-built-in sandbox/workspace modes. */
     runtimeModeAdapter?: RuntimeModeAdapter;
+    /** Provider/runtime values supplied by the embedding host. */
+    runtimeHost?: AgentRuntimeHostOperations;
     version?: string;
     extraTools?: AgentTool[];
     getExtraTools?: (ctx: {
@@ -1373,7 +1261,6 @@ interface RegisterAgentRoutesOptions {
         userId?: string;
     }) => string | undefined | Promise<string | undefined>;
     registerHealthRoute?: boolean;
-    sandboxHandleStore?: SandboxHandleStore;
     /**
      * Optional Lane W share-entry store (AR1-002/AR1-003, same-workspace
      * shareable links, `docs/issues/391/runtime-refactor/work/
@@ -1437,15 +1324,4 @@ interface RegisterAgentRoutesOptions {
  */
 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 { AgentConfig, AgentDirectoryCompilerError, type AgentDirectoryCompilerErrorCode, type AgentDirectoryCompilerPublicErrorCode, AgentHarnessFactory, type AgentMeteringSink, type BoringAgentRuntimePaths, type BuiltinRuntimeModeId, type CreateAgentAppOptions, type CreateVercelProvisioningAdapterOptions, type DeploymentSnapshotProvider, type DeploymentSnapshotRecipe, type DeploymentSnapshotResult, type DeploymentSnapshotStatus, FileHandleStore, type LogFields, type Logger, MANAGED_AGENT_MCP_DELIVERY_RULE, MANAGED_AGENT_MCP_ORIGIN_SURFACE, type ManagedAgentArtifact, type ManagedAgentArtifactCandidate, type ManagedAgentArtifactRef, type ManagedAgentBoundRunnerWorkspace, type ManagedAgentCollectArtifactsInput, type ManagedAgentDelegateInput, type ManagedAgentDelegateProgress, type ManagedAgentDelegateRequestContext, type ManagedAgentDelegateResult, type ManagedAgentDelegateRunInput, type ManagedAgentDelegateRunner, type ManagedAgentDelegateStatus, type ManagedAgentDelegateStatusResult, ManagedAgentMcpDelegateController, type ManagedAgentMcpDelegateOptions, ManagedAgentMcpError, type ManagedAgentMcpHttpHandlerOptions, type ManagedAgentMcpServerOptions, type ManagedAgentSafeError, type ManagedAgentWorkspaceResolutionInput, type MeteringErrorLogger, type MeteringReleaseInput, type MeteringReleaseReason, type MeteringReservationResult, type MeteringReserveInput, type MeteringRunKind, type MeteringRunScope, type MeteringRunStatus, type MeteringSettleInput, type MeteringUsage, type MeteringUsageInput, type ModeContext, PI_PACKAGE_RESOURCE_FILTERS, type PiExtensionFactory, type PiHarnessOptions, type PiPackageSource, type PluginSkillSource, type ProvisionRuntimeWorkspaceOptions, type ProvisionWorkspaceRuntimeOptions, type ProvisioningArtifactRequest, type RegisterAgentRoutesOptions, RemoteWorkerClient, RemoteWorkerClientError, type RemoteWorkerClientOptions, RemoteWorkerExecRequest, type RemoteWorkerModeAdapterOptions, RemoteWorkerWorkspaceOp, RemoteWorkerWorkspaceResult, type ResolvedAgent, type ResolvedAgentDigestInput, type RuntimeBundle, type RuntimeEnvContribution, type RuntimeEnvContributionContext, type RuntimeFilesystemBinding, type RuntimeFilesystemBindingOperations, type RuntimeModeAdapter, type RuntimeModeId, type RuntimeNodePackageSpec$1 as RuntimeNodePackageSpec, type RuntimeProvisioningContribution$1 as RuntimeProvisioningContribution, type RuntimePythonSpec$1 as RuntimePythonSpec, type RuntimeTemplateContribution$1 as RuntimeTemplateContribution, type RuntimeWorkspaceProvisioningResult, type ShareEntryMcpResourceOptions, type SnapshotBakeOptions, type SnapshotBakeResult, UV_SETUP_COMMANDS, VERCEL_PROVISIONING_CACHE_ROOT, VERCEL_SANDBOX_WORKSPACE_ROOT, UV_SETUP_COMMANDS as VERCEL_UV_SETUP_COMMANDS, type VercelBakeClient, type VercelBakeSandbox, type VercelDeploymentSnapshotOptions, type WorkspaceAgentDispatcherBinding, type WorkspaceAgentDispatcherResolveOptions, type WorkspaceAgentDispatcherResolver, type WorkspaceProvisioningAdapter, type WorkspaceProvisioningExecResult, type WorkspaceProvisioningResult, applyCspHeaders, assertRealPathWithinWorkspace, autoDetectMode, bakeSnapshotIfNeeded, buildDeploymentSnapshotRecipe, buildPackageHash, buildSnapshotRecipeHash, compactPiPackages, compileAgentDirectory, constantTimeTokenEqual, createAgent, createAgentApp, createDirectSandbox, createLogger, createManagedAgentMcpDelegateController, createManagedAgentMcpHttpHandler, createManagedAgentMcpServer, createNodeWorkspace, createRemoteWorkerModeAdapter, createRemoteWorkerSandbox, createRemoteWorkerWorkspace, createResolvedAgentDigest, createResourceSettingsManager, createVercelDeploymentSnapshotProvider, createVercelProvisioningAdapter, createVercelSandboxWorkspace, decodeBytesFromWorker, encodeBytesForWorker, fileRoutes, getBoringAgentPathEntries, getBoringAgentRuntimeEnv, getBoringAgentRuntimePaths, hasBwrap, mergePiPackageSources, normalizeMeteringUsage, piPackageSourceKey, prepareDeploymentSnapshot, prepareVercelDeploymentSnapshot, provisionRuntimeWorkspace, provisionWorkspaceRuntime, registerAgentRoutes, registerShareEntryResources, resolveAgentDeployment, resolveMode, resolveSandboxHandle, resolveWorkspaceRoot, shareResourceUri, validatePath };
+export { AgentConfig, AgentDirectoryCompilerError, type AgentDirectoryCompilerErrorCode, type AgentDirectoryCompilerPublicErrorCode, AgentHarnessFactory, type AgentMeteringSink, type AgentRuntimeHostOperations, AuthoredAgentMaterializationError, type AuthoredAgentMaterializationErrorCode, type AuthoredAgentToolCatalog, type BuiltinRuntimeModeId, type CreateAgentAppOptions, type DeploymentSnapshotProvider, type DeploymentSnapshotRecipe, type DeploymentSnapshotResult, type DeploymentSnapshotStatus, MANAGED_AGENT_MCP_DELIVERY_RULE, MANAGED_AGENT_MCP_ORIGIN_SURFACE, type ManagedAgentArtifact, type ManagedAgentArtifactCandidate, type ManagedAgentArtifactRef, type ManagedAgentBoundRunnerWorkspace, type ManagedAgentCollectArtifactsInput, type ManagedAgentDelegateInput, type ManagedAgentDelegateProgress, type ManagedAgentDelegateRequestContext, type ManagedAgentDelegateResult, type ManagedAgentDelegateRunInput, type ManagedAgentDelegateRunner, type ManagedAgentDelegateStatus, type ManagedAgentDelegateStatusResult, ManagedAgentMcpDelegateController, type ManagedAgentMcpDelegateOptions, ManagedAgentMcpError, type ManagedAgentMcpHttpHandlerOptions, type ManagedAgentMcpServerOptions, type ManagedAgentSafeError, type ManagedAgentWorkspaceResolutionInput, type MaterializeAgentDirectoryInput, type MaterializedAgentSourceV1, type MeteringErrorLogger, type MeteringReleaseInput, type MeteringReleaseReason, type MeteringReservationResult, type MeteringReserveInput, type MeteringRunKind, type MeteringRunScope, type MeteringRunStatus, type MeteringSettleInput, type MeteringUsage, type MeteringUsageInput, type ModeContext, PI_PACKAGE_RESOURCE_FILTERS, type PiExtensionFactory, type PiHarnessOptions, type PiPackageSource, type PluginSkillSource, type ProvisionRuntimeWorkspaceOptions, type ProvisionWorkspaceRuntimeOptions, type ProvisioningArtifactRequest, type RegisterAgentRoutesOptions, RemoteWorkerClient, RemoteWorkerClientError, type RemoteWorkerClientOptions, RemoteWorkerExecRequest, type RemoteWorkerModeAdapterOptions, RemoteWorkerWorkspaceOp, RemoteWorkerWorkspaceResult, type ResolvedAgent, type ResolvedAgentDigestInput, type RuntimeBundle, type RuntimeEnvContribution, type RuntimeEnvContributionContext, type RuntimeFilesystemBinding, type RuntimeFilesystemBindingOperations, type RuntimeModeAdapter, type RuntimeModeId, type RuntimeNodePackageSpec$1 as RuntimeNodePackageSpec, type RuntimeProvisioningContribution$1 as RuntimeProvisioningContribution, type RuntimePythonSpec$1 as RuntimePythonSpec, type RuntimeTemplateContribution$1 as RuntimeTemplateContribution, type RuntimeWorkspaceProvisioningResult, type ShareEntryMcpResourceOptions, UV_SETUP_COMMANDS, type WorkspaceAgentDispatcherBinding, type WorkspaceAgentDispatcherResolveOptions, type WorkspaceAgentDispatcherResolver, type WorkspaceProvisioningAdapter, type WorkspaceProvisioningExecResult, type WorkspaceProvisioningResult, applyCspHeaders, autoDetectMode, buildDeploymentSnapshotRecipe, compactPiPackages, compileAgentDirectory, constantTimeTokenEqual, createAgent, createAgentApp, createDirectModeAdapter, createLocalModeAdapter, createManagedAgentMcpDelegateController, createManagedAgentMcpHttpHandler, createManagedAgentMcpServer, createProviderRuntimeModeAdapter, createRemoteWorkerModeAdapter, createRemoteWorkerSandbox, createRemoteWorkerWorkspace, createResolvedAgentDigest, createResourceSettingsManager, createVercelSandboxModeAdapter, decodeBytesFromWorker, encodeBytesForWorker, hasBwrap, materializeAgentDirectory, mergePiPackageSources, normalizeMeteringUsage, piPackageSourceKey, prepareDeploymentSnapshot, provisionRuntimeWorkspace, provisionWorkspaceRuntime, registerAgentRoutes, registerShareEntryResources, resolveAgentDeployment, resolveMode, resolveWorkspaceRoot, shareResourceUri };