@hachej/boring-agent 0.1.90 → 0.1.91

package/dist/server/index.d.ts

@@ -1,20 +1,25 @@
-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 { P as ProvisionWorkspaceRuntimeOptions, W as WorkspaceProvisioningResult, R as RuntimeModeAdapter, a as RuntimeModeId, B as BuiltinRuntimeModeId, b as AgentRuntimeHostOperations, c as RuntimeBashStrategy, d as RuntimeFilesystemStrategy, M as ModeContext, e as WorkspaceProvisioningAdapter, f as RuntimeBundle, g as PiHarnessOptions, h as AgentMeteringSink, i as RuntimeFilesystemBinding, j as MeteringErrorLogger, k as ReadyStatusTracker, l as ResolvedAgentRuntimeScope, C as CreateAgentHostOptions, m as CompiledAgentHostAgentSpec, n as AgentRequestLedger, o as AgentEffectAdmission, p as AgentRequestKey, q as CreatedAgentHost, r as AgentFleetCompiler, A as AgentGatewayEffect, s as AgentRequestTarget, t as AgentRequestLedgerRecord, u as AgentRequestFailure, v as AgentHostLegacyRoutePolicy } from '../types-jcMapYr9.js';
+export { w as AgentHostAddressedHttpProjectionOptions, x as AgentHostAgentSpec, y as AgentHostDescription, z as AgentHostHandle, D as AgentHostHttpProjectionOptions, E as AgentHostLegacyHttpProjectionOptions, F as AgentHostLegacyProjectionComposition, G as AgentHostLegacyProjectionLifecycle, H as AgentHostLegacyProjectionRuntime, I as AgentHostLegacyRoutePolicyMountInput, J as ConfiguredAgentHostAgentSpec, L as LegacyDefaultAgentHostSpec, K as MeteringReleaseInput, N as MeteringReleaseReason, O as MeteringReservationResult, Q as MeteringReserveInput, S as MeteringRunKind, T as MeteringRunScope, U as MeteringRunStatus, V as MeteringSettleInput, X as MeteringUsage, Y as MeteringUsageInput, Z as PI_PACKAGE_RESOURCE_FILTERS, _ as PiExtensionFactory, $ as PiPackageSource, a0 as PluginSkillSource, a1 as ResolvedEnvironmentScope, a2 as RuntimeFilesystemBindingOperations, a3 as RuntimeNodePackageSpec, a4 as RuntimeProvisioningContribution, a5 as RuntimePythonSpec, a6 as RuntimeTemplateContribution, a7 as WorkspaceProvisioningExecResult, a8 as compactPiPackages, a9 as createResourceSettingsManager, aa as mergePiPackageSources, ab as normalizeMeteringUsage, ac as piPackageSourceKey } from '../types-jcMapYr9.js';
+import { E as ExecOptions, a as ExecResult, W as WorkspaceChangeEvent, b as Workspace, S as Sandbox } from '../sandbox-DAD8cWQR.js';
+import { R as RemoteWorkerWorkspaceOp, a as RemoteWorkerWorkspaceResult, b as RemoteWorkerExecRequest } from '../middleware-CzW8n7B7.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, j as createAgentAuthMiddleware } from '../middleware-CzW8n7B7.js';
 import { SandboxProviderV1, WorkspaceSandboxPairV1 } from '@hachej/boring-sandbox/shared';
-import { E as ErrorCode, l as SessionCtx, m as ChatModelSelection } from '../piChatEvent-CHgln6yx.js';
+import { S as SandboxHandleStore, C as CompiledAgentBundle, a as Sha256Digest, A as AgentDeployment, b as ShareEntryStore, P as PluginRestartWarning, W as WorkspaceAgentDispatcherContext, c as WorkspaceAgentDispatcher, d as ProviderId, e as CredentialFieldId, R as ResolvedCredentialMaterialV1, f as AuthorizedWorkspaceCredentialScopeV1, V as VerifiedWorkspaceCredentialAuthorityV1, g as WorkspaceCredentialAuthorityVerifierV1, h as CredentialConsumerBindingRegistryV1, i as ProviderRegistryV1, j as WorkspaceCredentialResolverV1, k as ProviderCredentialRefV1, l as ResolvedCredentialLeaseV1 } from '../lease-2aXepSBL.js';
+import { s as AgentConfig, b as Agent, d as AgentActor, j as AgentEvent, t as AgentTool, u as AgentHarnessFactory, T as TelemetrySink, A as AgentHarness } from '../harness-Bt_GMNYR.js';
+export { v as AgentHarnessFactoryInput } from '../harness-Bt_GMNYR.js';
+import { b as PiChatEvent, E as ErrorCode, l as SessionCtx, S as SessionStore, m as SessionListOptions, k as SessionSummary, n as PiChatSnapshot, c as PromptPayload, d as PromptReceipt, F as FollowUpPayload, e as FollowUpReceipt, f as QueueClearPayload, g as QueueClearReceipt, I as InterruptPayload, i as StopPayload, j as StopReceipt } from '../piChatEvent-DBO3M5lu.js';
+import { A as AgentGateway, a as AuthorizedAgentScope, b as AgentSessionRef, c as AgentSessionActivity, V as VerifiedAgentScopeClaim, d as AgentSessionSummary, e as AgentSessionStateSnapshot, f as AgentSessionConnection, J as JsonValue, g as AgentGatewayErrorDTO } from '../errors-BEmw9HMp.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-DDKPOj4x.js';
+import { i as PiSessionRequestContext, g as PiChatSessionService, h as PiSessionCreateInit, e as PiChatEventSubscriber, P as PiChatEventStreamResult, a as AgentEffectAdmission$1 } from '../piChatSessionService-BaaVWke7.js';
+import { BoringAgentRuntimePaths } from '@hachej/boring-sandbox/providers/node-workspace';
+import '@hachej/boring-bash/agent';
+import '@mariozechner/pi-coding-agent';
 import 'zod';
 
+declare function provisionWorkspaceRuntime(opts: ProvisionWorkspaceRuntimeOptions): Promise<WorkspaceProvisioningResult>;
+
 /**
  * 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`.
@@ -50,364 +55,6 @@ declare function prepareDeploymentSnapshot(provider: DeploymentSnapshotProvider,
 
 declare function resolveWorkspaceRoot(defaultRoot?: string): string;
 
-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;
-}
-
-/**
- * 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.
- */
-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;
-    warn?(message: string, fields?: Record<string, unknown>): void;
-    error?(message: string, fields?: Record<string, unknown>): void;
-}
-
-interface PluginSkillSource {
-    name: string;
-    source: string | URL;
-}
-interface RuntimeTemplateContribution$1 {
-    id: string;
-    path: string | URL;
-    target?: string;
-}
-interface RuntimePythonSpec$1 {
-    id: string;
-    projectFile: string | URL;
-    packageName?: string;
-    packageRoot?: string | URL;
-    version?: string;
-    extraLibs?: string[];
-    env?: Record<string, string | URL>;
-    expectedBins?: string[];
-}
-interface RuntimeNodePackageSpec$1 {
-    id: string;
-    packageName: string;
-    packageRoot?: string | URL;
-    version?: string;
-    expectedBins?: string[];
-}
-interface RuntimeProvisioningContribution$1 {
-    templateDirs?: RuntimeTemplateContribution$1[];
-    python?: RuntimePythonSpec$1[];
-    nodePackages?: RuntimeNodePackageSpec$1[];
-}
-interface WorkspaceProvisioningResult {
-    changed: boolean;
-    env: Record<string, string>;
-    pathEntries: string[];
-    skillPaths: string[];
-}
-interface WorkspaceProvisioningExecResult {
-    stdout?: string;
-    stderr?: string;
-}
-interface ResolveInstallSourceOpts {
-    kind: 'node' | 'python';
-    id: string;
-    fingerprint: string;
-}
-interface WorkspaceProvisioningAdapter {
-    mode: 'direct' | 'local' | 'vercel-sandbox';
-    exec(command: string, args: string[], opts?: {
-        cwd?: string;
-        env?: Record<string, string>;
-        timeoutMs?: number;
-    }): Promise<WorkspaceProvisioningExecResult | void>;
-    resolveInstallSource(source: string | URL, opts: ResolveInstallSourceOpts): Promise<string>;
-    workspaceFs: {
-        exists(workspaceRelativePath: string): Promise<boolean>;
-        /** Remove a workspace-relative generated path. Missing path is success. */
-        rm(workspaceRelativePath: string): Promise<void>;
-        /** Create a workspace-relative directory recursively. */
-        mkdir(workspaceRelativePath: string): Promise<void>;
-        writeText(workspaceRelativePath: string, content: string): Promise<void>;
-        readText(workspaceRelativePath: string): Promise<string | null>;
-        /** Copy a host file or directory into the workspace; directory copies are recursive. */
-        copyFromHost(hostSourcePath: string | URL, workspaceRelativeTarget: string): Promise<void>;
-    };
-    getRuntimeCacheRoot(): string;
-}
-interface ProvisioningTelemetryContext {
-    workspaceId?: string;
-    sessionId?: string;
-    requestId?: string;
-    runtimeMode?: string;
-}
-interface ProvisionWorkspaceRuntimeOptions {
-    plugins: Array<{
-        id: string;
-        skills?: PluginSkillSource[];
-        provisioning?: RuntimeProvisioningContribution$1;
-    }>;
-    adapter: WorkspaceProvisioningAdapter;
-    runtimeLayout: BoringAgentRuntimePaths;
-    runtimeHost: AgentRuntimeHostOperations;
-    logger?: ProvisioningLogger;
-    telemetry?: TelemetrySink;
-    telemetryContext?: ProvisioningTelemetryContext;
-}
-
-declare function provisionWorkspaceRuntime(opts: ProvisionWorkspaceRuntimeOptions): Promise<WorkspaceProvisioningResult>;
-
-type BuiltinRuntimeModeId = 'direct' | 'local' | 'vercel-sandbox';
-type RuntimeModeId = BuiltinRuntimeModeId | (string & {});
-interface RuntimeModeReadinessHooks {
-    initialSandboxReady?: boolean;
-    initialWorkspaceReadiness?: CapabilityReadinessDetail;
-    onTrackerCreated?: (tracker: ReadyStatusTracker) => void;
-}
-type RuntimeCachedBindingHealthCheckResult = {
-    state: 'ok';
-} | {
-    state: 'recreate';
-    message?: string;
-    error?: unknown;
-};
-interface RuntimeCachedBindingHealthCheck {
-    intervalMs?: number;
-    check(ctx: {
-        runtimeBundle: RuntimeBundle;
-        workspaceId: string;
-    }): Promise<RuntimeCachedBindingHealthCheckResult>;
-}
-type RuntimeBashStrategy = {
-    kind: 'host';
-    preserveHostHome?: boolean;
-} | {
-    kind: 'local-sandbox';
-    sandboxRoot: string;
-} | {
-    kind: 'remote';
-    defaultPath?: string;
-};
-interface RuntimeRemoteWorkspacePathOptions {
-    rootAliases?: string[];
-    toRemotePath?: (value: string) => string;
-    toRuntimePath?: (value: string) => string;
-    sanitizeErrorText?: (value: string) => string;
-}
-type RuntimeFilesystemStrategy = {
-    kind: 'host';
-} | {
-    kind: 'remote-workspace';
-    pathOptions?: RuntimeRemoteWorkspacePathOptions;
-};
-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
-     * host-side fs checks/prompts are safe without hard-coding sandbox IDs.
-     */
-    readonly workspaceFsCapability?: Workspace['fsCapability'];
-    readonly readiness?: RuntimeModeReadinessHooks;
-    readonly cachedBindingHealthCheck?: RuntimeCachedBindingHealthCheck;
-    create(ctx: ModeContext): Promise<RuntimeBundle>;
-    getRuntimeLayoutRoot?(ctx: ModeContext): string;
-    evictCachedRuntime?(ctx: {
-        workspaceId: string;
-    }): void | Promise<void>;
-    dispose?(): Promise<void>;
-}
-interface ModeContext {
-    workspaceRoot: string;
-    sessionId: string;
-    workspaceId?: string;
-    templatePath?: string;
-    requestId?: string;
-    telemetry?: TelemetrySink;
-}
-interface RuntimeFilesystemBindingOperations {
-    read(descriptor: {
-        filesystem: string;
-        path: string;
-    }): Promise<{
-        content: string;
-        mtimeMs?: number;
-        metadata?: unknown;
-    }>;
-    list(descriptor: {
-        filesystem: string;
-        path: string;
-    }): Promise<{
-        entries: string[];
-        metadata?: unknown;
-    }>;
-    find(descriptor: {
-        filesystem: string;
-        path: string;
-    }, pattern: string, options?: {
-        limit?: number;
-        offset?: number;
-    }): Promise<{
-        paths: string[];
-        metadata?: unknown;
-    }>;
-    grep(descriptor: {
-        filesystem: string;
-        path: string;
-    }, pattern: string, options?: {
-        limit?: number;
-        offset?: number;
-    }): Promise<{
-        matches: Array<{
-            path: string;
-            line: number;
-            text: string;
-        }>;
-        metadata?: unknown;
-    }>;
-    stat(descriptor: {
-        filesystem: string;
-        path: string;
-    }): Promise<{
-        isDirectory: boolean;
-        metadata?: unknown;
-    }>;
-    write?(descriptor: {
-        filesystem: string;
-        path: string;
-        content: string;
-        expectedMtimeMs?: number;
-    }): Promise<{
-        mtimeMs?: number;
-        metadata?: unknown;
-    }>;
-    delete?(descriptor: {
-        filesystem: string;
-        path: string;
-    }): Promise<{
-        metadata?: unknown;
-    }>;
-    move?(descriptor: {
-        filesystem: string;
-        from: string;
-        to: string;
-    }): Promise<{
-        metadata?: unknown;
-    }>;
-    mkdir?(descriptor: {
-        filesystem: string;
-        path: string;
-        recursive?: boolean;
-    }): Promise<{
-        metadata?: unknown;
-    }>;
-    rejectMutation(operation: string, descriptor: {
-        filesystem: string;
-        path: string;
-    }): never;
-}
-interface RuntimeFilesystemBinding {
-    readonly filesystem: string;
-    readonly access: 'readonly' | 'readwrite';
-    readonly operations: RuntimeFilesystemBindingOperations;
-}
-interface RuntimeBundle {
-    runtimeContext?: WorkspaceRuntimeContext;
-    /**
-     * Server-private host/storage root for host-side filesystem work. Do not use
-     * this as the agent-visible cwd; Workspace.root remains the public runtime
-     * namespace shown to tools/model.
-     */
-    storageRoot?: string;
-    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. */
-    bash?: RuntimeBashStrategy;
-    /** Runtime-owned filesystem strategy, consumed by the agent filesystem tool builder. */
-    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 {
     baseUrl: string;
     token: string;
@@ -559,6 +206,44 @@ interface ProviderRuntimeModeAdapterOptions {
 }
 declare function createProviderRuntimeModeAdapter(options: ProviderRuntimeModeAdapterOptions): RuntimeModeAdapter;
 
+declare const sandboxRuntimeHostOperations: AgentRuntimeHostOperations;
+interface SandboxRuntimeModeOptions {
+    readonly sandboxHandleStore?: SandboxHandleStore;
+}
+/** Built-in runtime layout root without exposing provider package constants to consumers. */
+declare function resolveBuiltinRuntimeLayoutRoot(mode: BuiltinRuntimeModeId, workspaceRoot: string): string;
+declare function createSandboxRuntimeModeAdapter(mode: BuiltinRuntimeModeId, options?: SandboxRuntimeModeOptions): RuntimeModeAdapter;
+
+interface EventStreamReadResult {
+    events: Array<{
+        data: unknown;
+        offset: string;
+    }>;
+    nextOffset: string;
+    upToDate: boolean;
+    closed: boolean;
+}
+interface EventStreamMeta {
+    nextOffset: string;
+    closed: boolean;
+}
+interface EventStreamStore {
+    createStream(path: string): Promise<void>;
+    appendEvent(path: string, event: unknown): Promise<string>;
+    appendEventOnce(path: string, key: string, event: unknown): Promise<string>;
+    appendAgentEvent(sessionId: string, chunk: PiChatEvent, opts?: {
+        idempotencyKey?: string;
+        streamPath?: string;
+    }): Promise<string>;
+    readEvents(path: string, opts?: {
+        offset?: string;
+        limit?: number;
+    }): Promise<EventStreamReadResult>;
+    closeStream(path: string): Promise<void>;
+    getStreamMeta(path: string): Promise<EventStreamMeta | null>;
+    subscribe(path: string, listener: () => void): () => void;
+}
+
 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';
@@ -577,21 +262,18 @@ 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<{
+type AuthoredAgentMaterializationErrorCode = Extract<ErrorCode, 'AUTHORED_AGENT_ID_INVALID' | 'AUTHORED_AGENT_TYPE_MISMATCH' | 'AUTHORED_AGENT_REFERENCE_UNSUPPORTED'>;
+type AuthoredAgentSourceV1 = Readonly<{
     schemaVersion: 1;
     agentTypeId: string;
     version: string;
     label?: string;
+    description?: 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;
@@ -602,7 +284,11 @@ declare class AuthoredAgentMaterializationError extends Error {
         message: string;
     });
 }
-declare function materializeAgentDirectory(input: MaterializeAgentDirectoryInput): Promise<MaterializedAgentSourceV1>;
+/**
+ * Loads declarative authored identity, safe metadata, and instructions.
+ * Executable behavior is selected only by trusted host/plugin policy.
+ */
+declare function materializeAgentDirectory(input: MaterializeAgentDirectoryInput): Promise<AuthoredAgentSourceV1>;
 
 interface ResolvedAgentDigestInput {
     readonly workspaceId: string;
@@ -725,7 +411,13 @@ interface ManagedAgentCollectArtifactsInput {
     events: readonly AgentEvent[];
 }
 interface ManagedAgentMcpDelegateOptions {
-    agent?: Agent;
+    gateway?: AgentGateway;
+    agentTypeId?: string;
+    resolveGatewayScope?(input: {
+        brief: string;
+        ctx: SessionCtx;
+        request: ManagedAgentDelegateRequestContext;
+    }): AuthorizedAgentScope | Promise<AuthorizedAgentScope>;
     resolveSessionCtx(input: {
         brief: string;
         request: ManagedAgentDelegateRequestContext;
@@ -774,7 +466,7 @@ declare class ManagedAgentMcpDelegateController {
     private resolveSessionCtx;
     private resolveWorkspace;
     private resolveRunnerWorkspace;
-    private createAgentDelegateRunner;
+    private createGatewayDelegateRunner;
     private assertNotAborted;
     private stopDelegatedSession;
     private resolveActor;
@@ -863,150 +555,6 @@ interface RuntimeEnvContribution {
     getEnv(ctx: RuntimeEnvContributionContext): Record<string, string> | Promise<Record<string, string>>;
 }
 
-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 PiHarnessOptions {
-    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.
-     */
-    packages?: PiPackageSource[];
-    /**
-     * Additional native pi extension entrypoints. Pi loads these through jiti and
-     * re-imports them on ctx.reload(), which is required for hot-reloadable
-     * boring agent plugins.
-     */
-    extensionPaths?: string[];
-    /** In-process host extensions. Use only for trusted built-ins; hot plugin code should use paths. */
-    extensionFactories?: ExtensionFactory[];
-    /**
-     * Optional source of hot-reloadable Pi resources. Pi calls it on every
-     * reloadSession() (and once at session build) and merges the result with
-     * the static fields above. Lets the workspace plugin layer refresh
-     * package.json-discovered skills/packages/extensions without mutating
-     * arrays that the harness already captured.
-     */
-    getHotReloadableResources?: () => HotReloadablePiResources;
-    /** Reject an explicit unavailable/unknown model instead of silently falling back. */
-    strictModelResolution?: boolean;
-}
-interface HotReloadablePiResources {
-    additionalSkillPaths?: string[];
-    packages?: PiPackageSource[];
-    extensionPaths?: string[];
-}
-type PiExtensionFactory = ExtensionFactory;
-declare function createResourceSettingsManager(cwd: string, agentDir: string, piPackages: PiPackageSource[]): SettingsManager;
-
-/**
- * Generic metering seam for hosts that bill native Pi usage.
- *
- * The agent package owns lifecycle correctness (when to reserve, record,
- * settle, release based on native Pi events); the host-provided sink owns
- * persistence and product policy (credits, pricing, currencies, hard stops).
- *
- * Lifecycle per accepted prompt/follow-up ("run", identified by `runId`):
- *
- *   reserveRun        before execution starts; throwing rejects the request
- *                     (fail closed) so hosts can enforce hard stops.
- *   recordUsage       once per native assistant message carrying usage.
- *                     `usageId` is a stable idempotency key.
- *   settleRun         when the run reaches a native terminal state and usage
- *                     was recorded (or it finished ok).
- *   releaseRun        when the run never produced billable usage: rejected
- *                     execution, cleared queue, cancel/abort, or error before
- *                     any usage arrived.
- *
- * Every run terminates with exactly one settle or release from the
- * coordinator; sinks should still treat all four methods as idempotent
- * because process restarts and client retries can replay transitions.
- */
-interface AgentMeteringSink {
-    /** False means the sink is installed but policy is disabled/no-op. Omitted means active for fail-closed callers. */
-    isEnabled?: () => boolean;
-    reserveRun(input: MeteringReserveInput): Promise<MeteringReservationResult>;
-    /** Records the usage and returns the credit micros it was actually billed. The
-     * coordinator counts a usage as billable from this charged amount (not raw provider
-     * fields), so a row that prices to 0 (e.g. cost-only usage when provider cost isn't
-     * trusted) doesn't make a free run settle. */
-    recordUsage(input: MeteringUsageInput): Promise<MeteringUsageResult>;
-    settleRun(input: MeteringSettleInput): Promise<void>;
-    releaseRun(input: MeteringReleaseInput): Promise<void>;
-}
-interface MeteringUsageResult {
-    /** Credit micros this usage row was billed (0 = no real debit). */
-    billedMicros: number;
-}
-interface MeteringRunScope {
-    workspaceId?: string;
-    userId?: string;
-    userEmail?: string;
-    userEmailVerified?: boolean;
-    sessionId: string;
-    /** Stable id for one accepted prompt/follow-up run. */
-    runId: string;
-    source: 'pi-chat';
-}
-type MeteringRunKind = 'prompt' | 'followup';
-interface MeteringReserveInput extends MeteringRunScope {
-    kind: MeteringRunKind;
-    message: string;
-    model?: ChatModelSelection;
-}
-/** Sinks without reservation rows can return an empty object. */
-interface MeteringReservationResult {
-    reservationId?: string;
-}
-interface MeteringUsage {
-    input: number;
-    output: number;
-    cacheRead: number;
-    cacheWrite: number;
-    cost: {
-        input: number;
-        output: number;
-        cacheRead: number;
-        cacheWrite: number;
-        total: number;
-    };
-}
-interface MeteringUsageInput extends MeteringRunScope {
-    reservationId?: string;
-    /** Stable idempotency key for this usage row. */
-    usageId: string;
-    messageId?: string;
-    model?: {
-        provider?: string;
-        id?: string;
-    };
-    usage: MeteringUsage;
-    stopReason?: string;
-    metadata?: Record<string, unknown>;
-}
-type MeteringRunStatus = 'ok' | 'error' | 'aborted';
-interface MeteringSettleInput extends MeteringRunScope {
-    reservationId?: string;
-    status: MeteringRunStatus;
-}
-type MeteringReleaseReason = 'run-rejected' | 'queue-cleared' | 'cancelled' | 'error-before-usage' | 'usage-write-failed' | 'fallback-hold-charge';
-interface MeteringReleaseInput extends MeteringRunScope {
-    reservationId?: string;
-    reason: MeteringReleaseReason;
-}
-type MeteringErrorLogger = (message: string, error: unknown) => void;
-/** Native Pi usage objects always carry token + cost breakdowns; normalize
- * defensively (zero-filling gaps and clamping negatives) so a partial object
- * from an unexpected provider still meters as zeros instead of NaN. */
-declare function normalizeMeteringUsage(value: unknown): MeteringUsage | undefined;
-
 interface WorkspaceAgentDispatcherResolveOptions {
     request?: FastifyRequest;
 }
@@ -1066,6 +614,11 @@ interface CreateAgentAppOptions {
         userEmailVerified?: boolean;
         requestId?: string;
     }) => RuntimeFilesystemBinding[] | undefined | Promise<RuntimeFilesystemBinding[] | undefined>;
+    /**
+     * Trusted host seam for resolving Pi HTTP session scope. The default keeps
+     * unauthenticated requests workspace-only and authenticated requests user-scoped.
+     */
+    resolvePiSessionRequestContext?: (request: FastifyRequest, defaultContext: PiSessionRequestContext) => PiSessionRequestContext | Promise<PiSessionRequestContext>;
     /** Generic runtime env contributors. Agent stays workspace-neutral; hosts decide env names/values. */
     runtimeEnvContributions?: RuntimeEnvContribution[];
     /** Runtime-aware provisioning hook. Runs after Workspace/Sandbox creation and before tools/harness. */
@@ -1118,6 +671,302 @@ interface CreateAgentAppOptions {
 }
 declare function createAgentApp(opts?: CreateAgentAppOptions): Promise<FastifyInstance>;
 
+interface HarnessPiChatServiceOptions {
+    harness: AgentHarness;
+    sessionStore: SessionStore;
+    workdir: string;
+    workspace?: Workspace;
+    eventStore?: EventStreamStore;
+    /**
+     * Optional host billing sink. When set, accepted prompts/follow-ups reserve
+     * before execution (a rejecting sink blocks the request), native assistant
+     * usage is recorded per message, and every run settles or releases from
+     * native terminal lifecycle.
+     */
+    metering?: AgentMeteringSink;
+    /** Host-owned process-lifetime projection of live session activity. */
+    onEvent?: (sessionId: string, event: PiChatEvent) => void;
+    /** Receives non-fatal metering pipeline failures (default: console.warn). */
+    meteringLogger?: MeteringErrorLogger;
+}
+declare class HarnessPiChatService implements PiChatSessionService {
+    private readonly harness;
+    private readonly sessionStore;
+    private readonly workdir;
+    private readonly workspace?;
+    private readonly eventStore?;
+    private readonly onEvent?;
+    private readonly channels;
+    private readonly channelCreations;
+    private readonly messageMetadata;
+    private readonly activePromptRuns;
+    private readonly syntheticPromptFailures;
+    private readonly activeSyntheticPromptErrors;
+    private readonly lifecycle;
+    private readonly metering?;
+    private disposePromise?;
+    constructor(options: HarnessPiChatServiceOptions);
+    /** Test/diagnostic hook: resolves once queued metering sink calls settle. */
+    flushMetering(): Promise<void>;
+    dispose(): Promise<void>;
+    private disposeService;
+    listSessions(ctx: PiSessionRequestContext, options?: SessionListOptions): Promise<SessionSummary[]>;
+    createSession(ctx: PiSessionRequestContext, init?: PiSessionCreateInit): Promise<SessionSummary>;
+    deleteSession(ctx: PiSessionRequestContext, sessionId: string): Promise<void>;
+    private deleteSessionBeforeDispose;
+    readAttachment(ctx: PiSessionRequestContext, sessionId: string, messageId: string, index: number): Promise<{
+        data: Uint8Array;
+        mediaType: string;
+        filename?: string;
+    }>;
+    readState(ctx: PiSessionRequestContext, sessionId: string): Promise<PiChatSnapshot>;
+    private readStateBeforeDispose;
+    private harnessMayHaveLiveSession;
+    private readPersistedState;
+    subscribe(ctx: PiSessionRequestContext, sessionId: string, cursor: number, subscriber: PiChatEventSubscriber): Promise<PiChatEventStreamResult>;
+    private subscribeBeforeDispose;
+    prompt(ctx: PiSessionRequestContext, sessionId: string, payload: PromptPayload): Promise<PromptReceipt>;
+    private promptBeforeDispose;
+    followUp(ctx: PiSessionRequestContext, sessionId: string, payload: FollowUpPayload): Promise<FollowUpReceipt>;
+    private followUpBeforeDispose;
+    clearQueue(ctx: PiSessionRequestContext, sessionId: string, payload: QueueClearPayload): Promise<QueueClearReceipt>;
+    private clearQueueBeforeDispose;
+    interrupt(ctx: PiSessionRequestContext, sessionId: string, _payload: InterruptPayload): Promise<{
+        accepted: true;
+        cursor: number;
+    }>;
+    private interruptBeforeDispose;
+    stop(ctx: PiSessionRequestContext, sessionId: string, _payload: StopPayload): Promise<StopReceipt>;
+    private stopBeforeDispose;
+    private clearAllFollowUps;
+    private nextFollowUpForInterrupt;
+    private autoPostInterruptedFollowUp;
+    private runPrompt;
+    private trackActiveRun;
+    private clearAutoPostedFollowUpForFallback;
+    private canClearAutoPostedFollowUpForFallback;
+    private enrichSyntheticPromptFailures;
+    private publishAutoPostedFollowUpRunError;
+    private publishChannelEvents;
+    private publishChannelEventSync;
+    private publishPromptRunError;
+    private runAndDrainPublishQueue;
+    private drainPublishQueue;
+    private getAdapter;
+    private getChannel;
+    private ensureChannel;
+    /** Coalesce concurrent cold callers so only one adapter subscription wins. */
+    private createChannelOnce;
+    private buildChannel;
+    private readDurableLatestPiChatSeq;
+    private assertCanAccessSession;
+    private sessionKey;
+}
+
+interface EnvironmentProvisioningSnapshot {
+    readonly changed: boolean;
+    readonly env: Readonly<Record<string, string>>;
+    readonly pathEntries: readonly string[];
+    readonly skillPaths: readonly string[];
+}
+interface EnvironmentLease {
+    readonly bundle: RuntimeBundle;
+    /** One immutable Environment-owned snapshot shared by every compatible Agent binding. */
+    readonly provisioning?: EnvironmentProvisioningSnapshot;
+    release(): void;
+    retire(): Promise<void>;
+}
+
+interface BuiltAgentComposition {
+    readonly agent: Agent;
+    readonly harness: AgentHarness;
+    readonly sessionStore: SessionStore;
+    readonly service: HarnessPiChatService;
+    readonly tools: readonly AgentTool[];
+    readonly runtimeBundle: RuntimeBundle;
+    readonly readyTracker: ReadyStatusTracker;
+    readonly runtimeScopeIdentity: string;
+    dispose(): Promise<void>;
+}
+
+interface AgentSessionRuntimeAuthority {
+    readonly runtimeScope: ResolvedAgentRuntimeScope;
+    /** Absent only for a pre-AH0 transcript created before runtime pins existed. */
+    readonly runtimeScopeIdentity?: string;
+}
+/** Process-lifetime live-turn projection. Reads never create activity rows. */
+declare class AgentSessionActivityIndex {
+    private readonly activity;
+    get(workspaceScopeId: string, ref: AgentSessionRef): AgentSessionActivity;
+    set(workspaceScopeId: string, ref: AgentSessionRef, activity: AgentSessionActivity): void;
+    delete(workspaceScopeId: string, ref: AgentSessionRef): void;
+    observe(workspaceScopeId: string, ref: AgentSessionRef, event: PiChatEvent): void;
+}
+
+interface RuntimeBinding {
+    readonly key: string;
+    readonly scope: ResolvedAgentRuntimeScope;
+    readonly environmentLease: EnvironmentLease;
+    readonly composition: BuiltAgentComposition;
+}
+interface AgentHostRuntime {
+    readonly options: CreateAgentHostOptions;
+    readonly compiledAgents: readonly CompiledAgentHostAgentSpec[];
+    readonly compiledById: ReadonlyMap<string, CompiledAgentHostAgentSpec>;
+    readonly ledger: AgentRequestLedger;
+    readonly effectAdmission: AgentEffectAdmission;
+    readonly activity: AgentSessionActivityIndex;
+    listSessionSummaries(agentTypeId: string, scope: AuthorizedAgentScope, claim: VerifiedAgentScopeClaim): Promise<readonly SessionSummary[]>;
+    isDraining(): boolean;
+    assertOpen(): void;
+    verify(scope: AuthorizedAgentScope): Promise<VerifiedAgentScopeClaim>;
+    resolveSessionRuntime(agentTypeId: string, scope: AuthorizedAgentScope, claim: VerifiedAgentScopeClaim, sessionId: string): Promise<AgentSessionRuntimeAuthority | undefined>;
+    resolveBinding(agentTypeId: string, scope: AuthorizedAgentScope, claim: VerifiedAgentScopeClaim, resolvedRuntimeScope?: ResolvedAgentRuntimeScope): Promise<RuntimeBinding>;
+    startDrain(): void;
+    drainRuntime(): Promise<void>;
+    registerSubscription(close: () => void | Promise<void>): () => void;
+    trackEffect<T>(effect: Promise<T>, key: AgentRequestKey): Promise<T>;
+    retireCompatibilityComposition(composition: BuiltAgentComposition): Promise<void>;
+    closeRuntime(): Promise<void>;
+}
+declare function createAgentHost(options: CreateAgentHostOptions): Promise<CreatedAgentHost>;
+
+declare const AgentFleetCompilationErrorCode: {
+    readonly AGENT_FLEET_PLUGIN_UNKNOWN: "AGENT_FLEET_PLUGIN_UNKNOWN";
+    readonly AGENT_FLEET_CONFIG_BINDING_UNKNOWN: "AGENT_FLEET_CONFIG_BINDING_UNKNOWN";
+    readonly AGENT_FLEET_MODEL_POLICY_UNCOMPILED: "AGENT_FLEET_MODEL_POLICY_UNCOMPILED";
+};
+type AgentFleetCompilationErrorCode = (typeof AgentFleetCompilationErrorCode)[keyof typeof AgentFleetCompilationErrorCode];
+declare class AgentFleetCompilationError extends Error {
+    readonly code: AgentFleetCompilationErrorCode;
+    readonly details: Readonly<Record<string, string>>;
+    constructor(code: AgentFleetCompilationErrorCode, message: string, details: Readonly<Record<string, string>>);
+}
+interface AgentFleetPluginBindingContract {
+    readonly id: string;
+    readonly configKeys?: readonly string[];
+}
+interface CreateValidatingAgentFleetCompilerOptions {
+    readonly plugins: readonly AgentFleetPluginBindingContract[];
+    readonly compiler?: AgentFleetCompiler;
+    /**
+     * Keeps Core's existing fail-closed policy when it has no app compiler.
+     * This is not model allowlist validation.
+     */
+    readonly requireCompilerForModelPolicy?: boolean;
+}
+/**
+ * The one reusable fleet binding-validation funnel. Apps supply only their
+ * already-resolved plugin contracts and optional stricter policy compiler.
+ */
+declare function createValidatingAgentFleetCompiler(options: CreateValidatingAgentFleetCompilerOptions): AgentFleetCompiler;
+
+declare class EmbeddedAgentGateway implements AgentGateway {
+    private readonly runtime;
+    private readonly cursorSecret;
+    private readonly connections;
+    private readonly effects;
+    private readonly pins;
+    private readonly writerTails;
+    private sessionRuntimeResolutionObserver?;
+    private closed;
+    constructor(runtime: AgentHostRuntime);
+    /** Server-only test observer for distinguishing runtime pin resolution paths. */
+    setSessionRuntimeResolutionObserverForTesting(observer: (input: {
+        readonly source: 'pre-ah0-compatibility-fallback' | 'persisted-runtime-pin';
+        readonly runtimeScopeIdentity: string;
+    }) => void): void;
+    /** Test-only activity seam used by the shared implementation conformance. */
+    setActivityForTesting(workspaceScopeId: string, ref: AgentSessionRef, activity: AgentSessionActivity): void;
+    private assertOpen;
+    private verify;
+    listAgents(input: {
+        readonly scope: AuthorizedAgentScope;
+    }): Promise<{
+        definition?: {
+            version: string;
+            digest: string;
+        } | undefined;
+        agentTypeId: string;
+        label: string;
+    }[]>;
+    listSessions(input: Parameters<AgentGateway['listSessions']>[0]): Promise<{
+        nextCursor?: string | undefined;
+        sessions: AgentSessionSummary[];
+    }>;
+    createSession(input: Parameters<AgentGateway['createSession']>[0]): Promise<AgentSessionRef>;
+    readSessionState(input: Parameters<AgentGateway['readSessionState']>[0]): Promise<AgentSessionStateSnapshot>;
+    connectSession(input: Parameters<AgentGateway['connectSession']>[0]): Promise<AgentSessionConnection>;
+    private send;
+    renameSession(input: Parameters<AgentGateway['renameSession']>[0]): Promise<AgentSessionSummary>;
+    deleteSession(input: Parameters<AgentGateway['deleteSession']>[0]): Promise<void>;
+    close(): Promise<void>;
+    private bindingForSession;
+    private loadSummary;
+    private sessionEffect;
+    /** Internal legacy-alias seam; never exposed through the public Gateway contract. */
+    runLegacyCompatibilityEffect(input: {
+        readonly scope: AuthorizedAgentScope;
+        readonly operation: AgentGatewayEffect;
+        readonly target: AgentRequestTarget;
+        readonly requestId: string;
+        readonly payload: JsonValue;
+        readonly action: () => Promise<unknown>;
+    }): Promise<unknown>;
+    private effect;
+    private replayReceipt;
+    private failure;
+    private withWriter;
+    private encodeCursor;
+    private decodeCursor;
+}
+
+/** Process-lifetime Level-B ledger with the exact published state machine. */
+declare class InMemoryAgentRequestLedger implements AgentRequestLedger {
+    private readonly records;
+    prepare(key: AgentRequestKey, digest: string): Promise<AgentRequestLedgerRecord>;
+    acceptAdmission(key: AgentRequestKey, admissionReceipt: string): Promise<void>;
+    beginEffect(key: AgentRequestKey): Promise<void>;
+    reject(key: AgentRequestKey, failure: AgentRequestFailure): Promise<void>;
+    complete(key: AgentRequestKey, receipt: JsonValue): Promise<void>;
+    markOutcomeUnknown(key: AgentRequestKey, error: AgentGatewayErrorDTO): Promise<void>;
+    read(key: AgentRequestKey): Promise<AgentRequestLedgerRecord | undefined>;
+    private transition;
+}
+
+interface RuntimeScopeIdentityInput {
+    readonly artifacts: readonly {
+        readonly pluginId: string;
+        readonly digest: string;
+    }[];
+    readonly validatedConfig: JsonValue;
+    readonly grants: readonly string[];
+    readonly placementIdentity: string;
+    readonly isolationMode: string;
+    readonly toolContractDigests: readonly string[];
+    readonly provisioningGeneration: string;
+    readonly bindingInputs?: JsonValue;
+}
+interface EnvironmentProvisioningIdentityInput {
+    readonly placementIdentity: string;
+    readonly providerDigest: string;
+    readonly provisioningArtifactDigests: readonly string[];
+    readonly provisioningGeneration: string;
+    readonly templateDigest?: string;
+}
+/**
+ * Produces the complete Agent-binding identity. Grants intentionally
+ * participate here even though they do not participate in Environment
+ * provisioning identity.
+ */
+declare function createResolvedRuntimeScopeIdentity(input: RuntimeScopeIdentityInput): string;
+/**
+ * Produces only the Environment-mutating identity. Contribution grants and
+ * tool contracts are deliberately absent, so grant-only changes share the
+ * same canonical Environment lease.
+ */
+declare function createEnvironmentProvisioningFingerprint(input: EnvironmentProvisioningIdentityInput): string;
+
 interface HeaderLike {
     setHeader(name: string, value: string): void;
 }
@@ -1169,7 +1018,29 @@ interface ModelsRoutesOptions {
     filterModels?: (ctx: ModelFilterContext, models: readonly ModelSummary[], defaultModel: AgentModelSelection | undefined) => ModelFilterResult | Promise<ModelFilterResult>;
 }
 
+type PiSessionRequestContextResolver = (request: FastifyRequest, defaultContext: PiSessionRequestContext) => PiSessionRequestContext | Promise<PiSessionRequestContext>;
+
+interface PrebuiltAgentHostRoutePolicy {
+    /** The sole Host instance constructed by the embedding composition root. */
+    readonly created: CreatedAgentHost;
+    /** Default Agent used by the legacy unaddressed route family. */
+    readonly defaultAgentTypeId: string;
+    /**
+     * App-owned capability issuer. The app may replace workspaceScopeId with its
+     * canonical workspace/storage partition while retaining the normalized
+     * runtime scope as private issuer context.
+     */
+    issueScope(input: {
+        readonly claim: VerifiedAgentScopeClaim;
+        readonly runtimeScope: ResolvedAgentRuntimeScope;
+    }): AuthorizedAgentScope;
+}
 interface RegisterAgentRoutesOptions {
+    /**
+     * Reuse a Host created by the embedding composition root. Omission preserves
+     * the historical wrapper behavior and constructs one legacy default Host.
+     */
+    agentHost?: PrebuiltAgentHostRoutePolicy;
     workspaceRoot?: string;
     sessionId?: string;
     templatePath?: string;
@@ -1185,6 +1056,8 @@ interface RegisterAgentRoutesOptions {
     runtimeHost?: AgentRuntimeHostOperations;
     version?: string;
     extraTools?: AgentTool[];
+    /** When true, omit the six filesystem tools (read/write/edit/find/grep/ls). */
+    disableDefaultFileTools?: boolean;
     getExtraTools?: (ctx: {
         workspaceId: string;
         workspaceRoot: string;
@@ -1223,10 +1096,12 @@ interface RegisterAgentRoutesOptions {
     sessionNamespace?: string;
     /** Optional explicit root for file-backed Pi chat transcript storage. */
     sessionRoot?: string;
+    /** Trusted host seam for resolving Pi HTTP session scope. */
+    resolvePiSessionRequestContext?: PiSessionRequestContextResolver;
     /** Optional best-effort telemetry sink supplied by an embedding host. */
     telemetry?: TelemetrySink;
     /** Optional host admission called immediately before each agent effect. */
-    admitEffect?: AgentEffectAdmission;
+    admitEffect?: AgentEffectAdmission$1;
     /** Generic request-aware model filtering seam. Hosts may filter per user/workspace. */
     filterModels?: ModelsRoutesOptions['filterModels'];
     /** Generic per-request/per-run filesystem binding seam. Hosts may return user/session-filtered bindings. */
@@ -1285,6 +1160,8 @@ interface RegisterAgentRoutesOptions {
         runtimeMode: RuntimeModeId;
         runtimeLayout: BoringAgentRuntimePaths;
         provisioningAdapter?: WorkspaceProvisioningAdapter;
+        /** Already-created paired Workspace/Sandbox runtime for this binding. */
+        runtimeBundle: RuntimeBundle;
         request?: FastifyRequest;
         /** Aborted when this binding retires; retirement still drains the task before provider disposal. */
         signal: AbortSignal;
@@ -1315,13 +1192,59 @@ interface RegisterAgentRoutesOptions {
      */
     onWorkspaceAgentDispatcher?: (resolver: WorkspaceAgentDispatcherResolver) => void;
 }
+interface AgentHostLegacyRouteScopePolicy {
+    /** App-owned capability issuer for the already-created Host. */
+    issueScope(input: {
+        readonly claim: VerifiedAgentScopeClaim;
+        readonly runtimeScope: ResolvedAgentRuntimeScope;
+    }): AuthorizedAgentScope;
+    /** True only for the legacy wrapper whose Host admission calls admitEffect. */
+    readonly gatewayUsesLegacyAdmission?: boolean;
+}
+type AgentHostLegacyRoutePolicyOptions = Omit<RegisterAgentRoutesOptions, 'agentHost' | 'runtimeModeAdapter'> & {
+    readonly runtimeModeAdapter: RuntimeModeAdapter;
+};
+
+/** Normalize legacy options into the nested Host projection seam. */
+declare function createAgentHostLegacyRoutePolicy(options: AgentHostLegacyRoutePolicyOptions, scopePolicy: AgentHostLegacyRouteScopePolicy): AgentHostLegacyRoutePolicy;
+
 /**
- * Fastify plugin that mounts agent routes onto a host app (typically core-built).
+ * Compatibility wrapper for legacy embedding callers.
  *
- * 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.
+ * It normalizes legacy construction inputs, creates or reuses exactly one Host,
+ * and delegates the complete route profile through CreatedAgentHost.registerRoutes().
  */
 declare const registerAgentRoutes: FastifyPluginAsync<RegisterAgentRoutesOptions>;
 
-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 };
+interface CredentialStoreBackendV1 {
+    read(workspaceId: string, providerId: ProviderId, allowedFieldIds: readonly CredentialFieldId[]): Promise<ResolvedCredentialMaterialV1 & {
+        credentialVersion: number;
+    }>;
+}
+interface HostSideCredentialResolverOptionsV1 {
+    readonly authorityVerifier: WorkspaceCredentialAuthorityVerifierV1;
+    readonly bindingRegistry: CredentialConsumerBindingRegistryV1;
+    readonly providerRegistry: ProviderRegistryV1;
+    /**
+     * Storage boundary only. Vault/KmsBackend composition is deferred to bead
+     * 16f.2 and will implement this interface without changing the resolver.
+     */
+    readonly backend: CredentialStoreBackendV1;
+}
+interface InMemoryCredentialBackendEntryV1 {
+    readonly workspaceId: string;
+    readonly providerId: ProviderId;
+    readonly material: ResolvedCredentialMaterialV1;
+    readonly credentialVersion: number;
+}
+interface FakeAuthorityVerifierGrantV1 {
+    readonly scope: AuthorizedWorkspaceCredentialScopeV1;
+    readonly authority: VerifiedWorkspaceCredentialAuthorityV1;
+}
+declare function createHostSideCredentialResolverV1(options: HostSideCredentialResolverOptionsV1): WorkspaceCredentialResolverV1;
+declare function createFakeAuthorityVerifierV1(grants: readonly FakeAuthorityVerifierGrantV1[]): WorkspaceCredentialAuthorityVerifierV1;
+declare function createInMemoryCredentialBackendV1(entries: readonly InMemoryCredentialBackendEntryV1[]): CredentialStoreBackendV1;
+
+declare function withResolvedCredential<T>(resolver: WorkspaceCredentialResolverV1, workspace: AuthorizedWorkspaceCredentialScopeV1, ref: ProviderCredentialRefV1, fn: (lease: ResolvedCredentialLeaseV1) => T | Promise<T>): Promise<T>;
+
+export { AgentConfig, AgentDirectoryCompilerError, type AgentDirectoryCompilerErrorCode, type AgentDirectoryCompilerPublicErrorCode, AgentEffectAdmission, AgentFleetCompilationError, AgentFleetCompilationErrorCode, AgentFleetCompiler, type AgentFleetPluginBindingContract, AgentGatewayEffect, AgentHarnessFactory, AgentHostLegacyRoutePolicy, type AgentHostLegacyRoutePolicyOptions, type AgentHostLegacyRouteScopePolicy, AgentMeteringSink, AgentRequestKey, AgentRequestLedger, AgentRequestLedgerRecord, AgentRuntimeHostOperations, AuthoredAgentMaterializationError, type AuthoredAgentMaterializationErrorCode, type AuthoredAgentSourceV1, AuthorizedAgentScope, BuiltinRuntimeModeId, CompiledAgentHostAgentSpec, type CreateAgentAppOptions, CreateAgentHostOptions, type CreateValidatingAgentFleetCompilerOptions, CreatedAgentHost, type CredentialStoreBackendV1, type DeploymentSnapshotProvider, type DeploymentSnapshotRecipe, type DeploymentSnapshotResult, type DeploymentSnapshotStatus, EmbeddedAgentGateway, type FakeAuthorityVerifierGrantV1, type HostSideCredentialResolverOptionsV1, InMemoryAgentRequestLedger, type InMemoryCredentialBackendEntryV1, 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, MeteringErrorLogger, ModeContext, PiHarnessOptions, type PrebuiltAgentHostRoutePolicy, type ProvisionRuntimeWorkspaceOptions, ProvisionWorkspaceRuntimeOptions, type ProvisioningArtifactRequest, type RegisterAgentRoutesOptions, RemoteWorkerClient, RemoteWorkerClientError, type RemoteWorkerClientOptions, RemoteWorkerExecRequest, type RemoteWorkerModeAdapterOptions, RemoteWorkerWorkspaceOp, RemoteWorkerWorkspaceResult, type ResolvedAgent, type ResolvedAgentDigestInput, ResolvedAgentRuntimeScope, RuntimeBundle, type RuntimeEnvContribution, type RuntimeEnvContributionContext, RuntimeFilesystemBinding, RuntimeModeAdapter, RuntimeModeId, type RuntimeWorkspaceProvisioningResult, type SandboxRuntimeModeOptions, type ShareEntryMcpResourceOptions, UV_SETUP_COMMANDS, VerifiedAgentScopeClaim, type WorkspaceAgentDispatcherBinding, type WorkspaceAgentDispatcherResolveOptions, type WorkspaceAgentDispatcherResolver, WorkspaceProvisioningAdapter, WorkspaceProvisioningResult, applyCspHeaders, autoDetectMode, buildDeploymentSnapshotRecipe, compileAgentDirectory, constantTimeTokenEqual, createAgent, createAgentApp, createAgentHost, createAgentHostLegacyRoutePolicy, createDirectModeAdapter, createEnvironmentProvisioningFingerprint, createFakeAuthorityVerifierV1, createHostSideCredentialResolverV1, createInMemoryCredentialBackendV1, createLocalModeAdapter, createManagedAgentMcpDelegateController, createManagedAgentMcpHttpHandler, createManagedAgentMcpServer, createProviderRuntimeModeAdapter, createRemoteWorkerModeAdapter, createRemoteWorkerSandbox, createRemoteWorkerWorkspace, createResolvedAgentDigest, createResolvedRuntimeScopeIdentity, createSandboxRuntimeModeAdapter, createValidatingAgentFleetCompiler, createVercelSandboxModeAdapter, decodeBytesFromWorker, encodeBytesForWorker, hasBwrap, materializeAgentDirectory, prepareDeploymentSnapshot, provisionRuntimeWorkspace, provisionWorkspaceRuntime, registerAgentRoutes, registerShareEntryResources, resolveAgentDeployment, resolveBuiltinRuntimeLayoutRoot, resolveMode, resolveWorkspaceRoot, sandboxRuntimeHostOperations, shareResourceUri, withResolvedCredential };