@hachej/boring-agent 0.1.90 → 0.1.91

package/dist/types-jcMapYr9.d.ts

@@ -0,0 +1,759 @@
+import * as fastify from 'fastify';
+import { FastifyRequest, FastifyPluginAsync } from 'fastify';
+import { w as ToolReadinessRequirement, T as TelemetrySink, b as Agent, A as AgentHarness, t as AgentTool, u as AgentHarnessFactory } from './harness-Bt_GMNYR.js';
+import { F as FileSearch, b as AgentSessionRef, V as VerifiedAgentScopeClaim, g as AgentGatewayErrorDTO, J as JsonValue, a as AuthorizedAgentScope, A as AgentGateway, h as AgentScopeVerifier } from './errors-BEmw9HMp.js';
+import { o as ChatModelSelection } from './piChatEvent-DBO3M5lu.js';
+import { b as Workspace, c as WorkspaceRuntimeContext, S as Sandbox } from './sandbox-DAD8cWQR.js';
+import { RuntimeHostOperations } from '@hachej/boring-bash/agent';
+import { CreateNodeWorkspaceOptions, BoringAgentRuntimePaths } from '@hachej/boring-sandbox/providers/node-workspace';
+import { PackageSource, ExtensionFactory, SettingsManager } from '@mariozechner/pi-coding-agent';
+import { A as AgentCoreSessionService, g as PiChatSessionService } from './piChatSessionService-BaaVWke7.js';
+
+/**
+ * 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;
+
+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.
+ *
+ * Built-in concrete operations live in `sandboxRuntimeHost.ts`; custom hosts
+ * may inject an equivalent implementation with their Workspace + Sandbox pair.
+ */
+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 {
+    id: string;
+    path: string | URL;
+    target?: string;
+}
+interface RuntimePythonSpec {
+    id: string;
+    projectFile: string | URL;
+    packageName?: string;
+    packageRoot?: string | URL;
+    version?: string;
+    extraLibs?: string[];
+    env?: Record<string, string | URL>;
+    expectedBins?: string[];
+}
+interface RuntimeNodePackageSpec {
+    id: string;
+    packageName: string;
+    packageRoot?: string | URL;
+    version?: string;
+    expectedBins?: string[];
+}
+interface RuntimeProvisioningContribution {
+    templateDirs?: RuntimeTemplateContribution[];
+    python?: RuntimePythonSpec[];
+    nodePackages?: RuntimeNodePackageSpec[];
+}
+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;
+    }>;
+    adapter: WorkspaceProvisioningAdapter;
+    runtimeLayout: BoringAgentRuntimePaths;
+    runtimeHost: AgentRuntimeHostOperations;
+    logger?: ProvisioningLogger;
+    telemetry?: TelemetrySink;
+    telemetryContext?: ProvisioningTelemetryContext;
+}
+
+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>;
+}
+
+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[];
+    defaultModel?: {
+        provider: string;
+        id: 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;
+
+type AgentGatewayEffect = 'session.create' | 'session.rename' | 'session.delete' | 'session.prompt' | 'session.followup' | 'session.interrupt' | 'session.stop' | 'session.queue.clear';
+type AgentRequestTarget = {
+    readonly kind: 'agent';
+    readonly agentTypeId: string;
+} | {
+    readonly kind: 'session';
+    readonly ref: AgentSessionRef;
+};
+interface AgentRequestKey {
+    readonly workspaceScopeId: string;
+    readonly authSubjectId: string;
+    readonly operation: AgentGatewayEffect;
+    readonly target: AgentRequestTarget;
+    readonly requestId: string;
+}
+type AgentRequestFailure = {
+    readonly kind: 'gateway';
+    readonly error: AgentGatewayErrorDTO;
+} | {
+    /** Server-only compatibility envelope; never returned by AgentGateway. */
+    readonly kind: 'legacy-admission';
+    readonly code: string;
+    readonly statusCode: 500;
+    readonly message: string;
+    readonly details?: JsonValue;
+} | {
+    /** Server-only observed legacy service failure; never returned by AgentGateway. */
+    readonly kind: 'legacy-service';
+    readonly name: string;
+    readonly message: string;
+    readonly code?: string;
+    readonly statusCode?: number;
+    readonly retryable?: boolean;
+    readonly details?: JsonValue;
+};
+interface AgentRequestLedgerRecordBase {
+    readonly key: AgentRequestKey;
+    readonly digest: string;
+    readonly updatedAt: number;
+}
+type AgentRequestLedgerRecord = (AgentRequestLedgerRecordBase & {
+    readonly state: 'pending-admission';
+}) | (AgentRequestLedgerRecordBase & {
+    readonly state: 'admission-accepted';
+    readonly admissionReceipt: string;
+}) | (AgentRequestLedgerRecordBase & {
+    readonly state: 'in-flight';
+}) | (AgentRequestLedgerRecordBase & {
+    readonly state: 'rejected';
+    readonly failure: AgentRequestFailure;
+}) | (AgentRequestLedgerRecordBase & {
+    readonly state: 'completed';
+    readonly receipt: JsonValue;
+}) | (AgentRequestLedgerRecordBase & {
+    readonly state: 'outcome-unknown';
+    readonly error: AgentGatewayErrorDTO;
+});
+interface AgentRequestLedger {
+    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>;
+}
+type AgentEffectAdmissionResult = {
+    readonly type: 'accepted';
+    readonly admissionReceipt: string;
+} | {
+    readonly type: 'rejected';
+    readonly error: AgentGatewayErrorDTO;
+} | {
+    readonly type: 'retryable';
+    readonly error: AgentGatewayErrorDTO;
+};
+interface AgentEffectAdmission {
+    /** Must be idempotent and reconcilable on the complete ledger key. */
+    admit(input: {
+        readonly key: AgentRequestKey;
+        readonly digest: string;
+        readonly scope: VerifiedAgentScopeClaim;
+        readonly operation: AgentGatewayEffect;
+        readonly target: AgentRequestTarget;
+    }): Promise<AgentEffectAdmissionResult>;
+}
+interface ConfiguredAgentHostAgentSpec {
+    readonly agentTypeId: string;
+    readonly definition: {
+        readonly instructions: string;
+        readonly label: string;
+        readonly version?: string;
+    };
+    readonly plugins?: readonly {
+        /** Canonical app-preflighted plugin ID. */
+        readonly name: string;
+        readonly config?: JsonValue;
+    }[];
+    readonly model?: {
+        readonly preferred?: string;
+        /** RESERVED / NOT ENFORCED. Per-turn token-limit enforcement is future work. */
+        readonly maxTokensPerTurn?: number;
+    };
+}
+interface LegacyDefaultAgentHostSpec {
+    readonly agentTypeId: 'default';
+    readonly legacyDefault: true;
+}
+type AgentHostAgentSpec = ConfiguredAgentHostAgentSpec | LegacyDefaultAgentHostSpec;
+/**
+ * Server-only compiler output. App-specific validated handles may be attached,
+ * but the Host revalidates the complete agent ID set before freezing it.
+ */
+type CompiledAgentHostAgentSpec = AgentHostAgentSpec & {
+    readonly resolvedPolicy?: Readonly<Record<string, unknown>>;
+    /** Required when resolvedPolicy contains opaque/non-JSON runtime handles. */
+    readonly resolvedPolicyDigest?: string;
+};
+interface AgentFleetCompiler {
+    compile(input: {
+        readonly agents: readonly AgentHostAgentSpec[];
+    }): Promise<readonly CompiledAgentHostAgentSpec[]>;
+}
+interface ResolvedEnvironmentScope {
+    readonly placementIdentity: string;
+    readonly workspaceRoot: string;
+    readonly templatePath?: string;
+    readonly provisioningFingerprint: string;
+    readonly provisionRuntime?: (input: {
+        readonly runtimeBundle: Awaited<ReturnType<RuntimeModeAdapter['create']>>;
+        readonly signal: AbortSignal;
+    }) => Promise<WorkspaceProvisioningResult | undefined>;
+}
+interface ResolvedAgentRuntimeScope {
+    /** Complete app-canonicalized PL1 composition identity. */
+    readonly identity: string;
+    readonly environment: ResolvedEnvironmentScope;
+    readonly sessionNamespace: string;
+    readonly pi?: PiHarnessOptions;
+    readonly extraTools?: readonly AgentTool[];
+    readonly getFilesystemBindings?: (input: {
+        readonly scope: VerifiedAgentScopeClaim;
+        readonly sessionId?: string;
+        readonly requestId: string;
+    }) => Promise<readonly RuntimeFilesystemBinding[] | undefined>;
+    readonly systemPromptAppend?: string;
+    readonly loadSystemPromptAppend?: () => Promise<string | undefined>;
+}
+interface AgentHostLegacyProjectionComposition {
+    readonly agent: Agent;
+    readonly harness: AgentHarness;
+    readonly service: AgentCoreSessionService;
+    readonly tools: readonly AgentTool[];
+    readonly runtimeBundle: RuntimeBundle;
+    readonly readyTracker: ReadyStatusTracker;
+    retire(): Promise<void>;
+}
+/** Narrow Host-owned facade used only while mounting the compatibility profile. */
+interface AgentHostLegacyProjectionRuntime {
+    readonly gateway: AgentGateway;
+    resolveComposition(agentTypeId: string, scope: AuthorizedAgentScope): Promise<AgentHostLegacyProjectionComposition>;
+    createAddressedRoutes(options: {
+        readonly authorizeRequest: (request: FastifyRequest) => Promise<AuthorizedAgentScope>;
+        readonly defaultAgentTypeId: string;
+    }): FastifyPluginAsync;
+    createPiChatService(input: {
+        readonly service: AgentCoreSessionService;
+        readonly scope: AuthorizedAgentScope;
+        readonly agentTypeId: string;
+    }): PiChatSessionService;
+}
+interface AgentHostLegacyProjectionLifecycle {
+    startDraining(): void;
+    closeBindings(): Promise<void>;
+}
+interface AgentHostLegacyRoutePolicyMountInput {
+    readonly app: fastify.FastifyInstance;
+    readonly runtime: AgentHostLegacyProjectionRuntime;
+    readonly defaultAgentTypeId: string;
+    registerLifecycle(lifecycle: AgentHostLegacyProjectionLifecycle): void;
+}
+/**
+ * Normalized legacy/application route profile mounted only through the Host.
+ * Omission keeps the addressed-only HTTP projection.
+ */
+interface AgentHostLegacyRoutePolicy {
+    mount(input: AgentHostLegacyRoutePolicyMountInput): Promise<void>;
+}
+interface AgentHostHttpProjectionBaseOptions {
+    readonly defaultAgentTypeId: string;
+}
+/** Addressed Gateway projection, optionally with its frozen Pi-chat aliases. */
+type AgentHostAddressedHttpProjectionOptions = AgentHostHttpProjectionBaseOptions & {
+    readonly authorizeRequest: (request: FastifyRequest) => Promise<AuthorizedAgentScope>;
+    readonly legacyPiChatAliases?: boolean;
+    readonly legacyRoutePolicy?: never;
+};
+/** Full legacy/application route profile with its own normalized scope bridge. */
+type AgentHostLegacyHttpProjectionOptions = AgentHostHttpProjectionBaseOptions & {
+    readonly legacyRoutePolicy: AgentHostLegacyRoutePolicy;
+    readonly authorizeRequest?: never;
+    readonly legacyPiChatAliases?: never;
+};
+type AgentHostHttpProjectionOptions = AgentHostAddressedHttpProjectionOptions | AgentHostLegacyHttpProjectionOptions;
+interface AgentHostDescription {
+    readonly hostId: string;
+    readonly agents: readonly {
+        readonly agentTypeId: string;
+        readonly label: string;
+    }[];
+    readonly draining: boolean;
+}
+interface AgentHostHandle {
+    readonly hostId: string;
+    describe(): Promise<AgentHostDescription>;
+    drain(): Promise<void>;
+    close(): Promise<void>;
+}
+interface CreateAgentHostOptions {
+    readonly agents: readonly AgentHostAgentSpec[];
+    readonly fleetCompiler: AgentFleetCompiler;
+    readonly hostId?: string;
+    readonly scopeVerifier: AgentScopeVerifier;
+    readonly runtimeModeAdapter: RuntimeModeAdapter;
+    readonly runtimeHost?: AgentRuntimeHostOperations;
+    readonly sessionRoot?: string;
+    readonly resolveRuntimeScope: (input: {
+        readonly agentTypeId: string;
+        readonly scope: AuthorizedAgentScope;
+    }) => Promise<ResolvedAgentRuntimeScope>;
+    readonly telemetry?: TelemetrySink;
+    readonly metering?: AgentMeteringSink;
+    readonly requestLedger?: AgentRequestLedger;
+    readonly requestRetentionMs?: number;
+    readonly effectAdmission?: AgentEffectAdmission;
+    readonly shutdownGraceMs?: number;
+    readonly harnessFactory?: AgentHarnessFactory;
+}
+interface CreatedAgentHost {
+    readonly host: AgentHostHandle;
+    readonly gateway: AgentGateway;
+    registerRoutes(options: AgentHostHttpProjectionOptions): FastifyPluginAsync;
+}
+
+export { type PiPackageSource as $, type AgentGatewayEffect as A, type BuiltinRuntimeModeId as B, type CreateAgentHostOptions as C, type AgentHostHttpProjectionOptions as D, type AgentHostLegacyHttpProjectionOptions as E, type AgentHostLegacyProjectionComposition as F, type AgentHostLegacyProjectionLifecycle as G, type AgentHostLegacyProjectionRuntime as H, type AgentHostLegacyRoutePolicyMountInput as I, type ConfiguredAgentHostAgentSpec as J, type MeteringReleaseInput as K, type LegacyDefaultAgentHostSpec as L, type ModeContext as M, type MeteringReleaseReason as N, type MeteringReservationResult as O, type ProvisionWorkspaceRuntimeOptions as P, type MeteringReserveInput as Q, type RuntimeModeAdapter as R, type MeteringRunKind as S, type MeteringRunScope as T, type MeteringRunStatus as U, type MeteringSettleInput as V, type WorkspaceProvisioningResult as W, type MeteringUsage as X, type MeteringUsageInput as Y, PI_PACKAGE_RESOURCE_FILTERS as Z, type PiExtensionFactory as _, type RuntimeModeId as a, type PluginSkillSource as a0, type ResolvedEnvironmentScope as a1, type RuntimeFilesystemBindingOperations as a2, type RuntimeNodePackageSpec as a3, type RuntimeProvisioningContribution as a4, type RuntimePythonSpec as a5, type RuntimeTemplateContribution as a6, type WorkspaceProvisioningExecResult as a7, compactPiPackages as a8, createResourceSettingsManager as a9, mergePiPackageSources as aa, normalizeMeteringUsage as ab, piPackageSourceKey as ac, type AgentRuntimeHostOperations as b, type RuntimeBashStrategy as c, type RuntimeFilesystemStrategy as d, type WorkspaceProvisioningAdapter as e, type RuntimeBundle as f, type PiHarnessOptions as g, type AgentMeteringSink as h, type RuntimeFilesystemBinding as i, type MeteringErrorLogger as j, ReadyStatusTracker as k, type ResolvedAgentRuntimeScope as l, type CompiledAgentHostAgentSpec as m, type AgentRequestLedger as n, type AgentEffectAdmission as o, type AgentRequestKey as p, type CreatedAgentHost as q, type AgentFleetCompiler as r, type AgentRequestTarget as s, type AgentRequestLedgerRecord as t, type AgentRequestFailure as u, type AgentHostLegacyRoutePolicy as v, type AgentHostAddressedHttpProjectionOptions as w, type AgentHostAgentSpec as x, type AgentHostDescription as y, type AgentHostHandle as z };