@hachej/boring-agent 0.1.95 → 0.1.96

package/dist/{types-C-Eroi__.d.ts → types-D_SD-7_l.d.ts}

@@ -1,13 +1,77 @@
-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-Cc48o6uS.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-G6T6S7PQ.js';
-import { o as ChatModelSelection } from './piChatEvent-BsMp3MSo.js';
-import { b as Workspace, c as WorkspaceRuntimeContext, S as Sandbox } from './sandbox-DAD8cWQR.js';
-import { RuntimeHostOperations } from '@hachej/boring-bash/agent';
+import { w as ToolReadinessRequirement, T as TelemetrySink, s as AgentTool, t as AgentHarnessFactory } from './harness-DS8jLKIx.js';
+import { F as FileSearch, A as AgentSkillResource, W as WorkspaceAgentDirectRunInput, L as LeaseBoundWorkspaceAgent } from './file-search-QxnanNjO.js';
+import { b as Workspace, R as RuntimeFilesystemCapability, c as WorkspaceRuntimeContext, S as Sandbox } from './sandbox-KQiEdz4W.js';
+import { d as AgentSessionRef, V as VerifiedAgentScopeClaim, f as AgentGatewayErrorDTO, J as JsonValue, c as AuthorizedAgentScope, b as AgentGateway, j as AgentScopeVerifier } from './errors-cNC4HMpV.js';
+import { o as ChatModelSelection } from './piChatEvent-B3ehh9V0.js';
+import { RuntimeHostOperations, RuntimeFilesystemBinding as RuntimeFilesystemBinding$1 } 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-C0KbcGw9.js';
+import { PackageSource, ExtensionFactory } from '@mariozechner/pi-coding-agent';
+
+type SessionFileChangeOp = 'write' | 'edit' | 'unlink' | 'rename' | 'mkdir';
+interface SessionFileChange {
+    op: SessionFileChangeOp;
+    path: string;
+    oldPath?: string;
+    size?: number;
+    timestamp: string;
+}
+interface SessionChangesTracker {
+    record(scope: SessionChangesScope | string, change: SessionFileChange): void;
+    list(scope: SessionChangesScope | string): SessionFileChange[];
+    clear(scope: SessionChangesScope | string): void;
+}
+interface SessionChangesScope {
+    readonly workspaceScopeId?: string;
+    readonly agentTypeId?: string;
+    readonly sessionId: string;
+}
+
+interface AgentModelSelection {
+    provider: string;
+    id: string;
+}
+
+/**
+ * GET /api/v1/agents/:agentTypeId/models
+ *
+ * Returns the list of models pi-coding-agent has auth for (i.e. where
+ * the corresponding provider API key is present in the environment or
+ * `~/.pi/agent/auth.json`). Consumers — including the shadcn example
+ * ChatPanel — fetch this endpoint to populate the model-selector dropdown
+ * instead of hardcoding a short alias list.
+ *
+ * Shape:
+ *   {
+ *     models: [
+ *       { provider: "anthropic", id: "claude-sonnet-4-6", label: "Claude Sonnet 4.6", available: true },
+ *       ...
+ *     ]
+ *   }
+ *
+ * Safe to call unauthenticated — we only report {provider, id, label,
+ * available}, never any key material.
+ */
+
+interface ModelSummary {
+    provider: string;
+    id: string;
+    label: string;
+    available: boolean;
+}
+interface ModelFilterContext {
+    request: FastifyRequest;
+    workspaceId?: string;
+}
+type ModelFilterResult = {
+    models: readonly ModelSummary[];
+    defaultModel?: AgentModelSelection;
+};
+interface ModelsRoutesOptions {
+    path?: string;
+    authorizeRequest?: (request: FastifyRequest) => void | Promise<void>;
+    filterModels?: (ctx: ModelFilterContext, models: readonly ModelSummary[], defaultModel: AgentModelSelection | undefined) => ModelFilterResult | Promise<ModelFilterResult>;
+}
 
 /**
  * Generic metering seam for hosts that bill native Pi usage.
@@ -187,7 +251,13 @@ interface AgentRuntimeHostOperations extends RuntimeHostOperations {
     }>;
     validatePath(root: string, requestedPath: string): string;
     assertRealPathWithinWorkspace(root: string, targetPath: string): Promise<void>;
+    resolveRealWorkspacePath(root: string, targetPath: string): Promise<string>;
     isIgnoredDirName(name: string): boolean;
+    /** Host-owned confined projection for package resources outside the workspace. */
+    createAgentResourceFilesystemBinding(filesystem: string, mounts: readonly {
+        readonly logicalRoot: string;
+        readonly sourceRoot: string;
+    }[]): Promise<RuntimeFilesystemBinding$1>;
 }
 
 interface ProvisioningLogger {
@@ -243,7 +313,7 @@ interface ResolveInstallSourceOpts {
     fingerprint: string;
 }
 interface WorkspaceProvisioningAdapter {
-    mode: 'direct' | 'local' | 'vercel-sandbox';
+    mode: 'direct' | 'local' | 'blaxel' | 'vercel-sandbox';
     exec(command: string, args: string[], opts?: {
         cwd?: string;
         env?: Record<string, string>;
@@ -283,7 +353,7 @@ interface ProvisionWorkspaceRuntimeOptions {
     telemetryContext?: ProvisioningTelemetryContext;
 }
 
-type BuiltinRuntimeModeId = 'direct' | 'local' | 'vercel-sandbox';
+type BuiltinRuntimeModeId = 'direct' | 'local' | 'blaxel' | 'vercel-sandbox';
 type RuntimeModeId = BuiltinRuntimeModeId | (string & {});
 interface RuntimeModeReadinessHooks {
     initialSandboxReady?: boolean;
@@ -352,6 +422,12 @@ interface ModeContext {
     requestId?: string;
     telemetry?: TelemetrySink;
 }
+interface RuntimeFilesystemAccessDecision {
+    readonly filesystem: string;
+    readonly normalizedPath: string;
+    readonly access: 'readonly' | 'readwrite';
+    readonly capabilities: Readonly<Record<RuntimeFilesystemCapability, boolean>>;
+}
 interface RuntimeFilesystemBindingOperations {
     read(descriptor: {
         filesystem: string;
@@ -408,6 +484,14 @@ interface RuntimeFilesystemBindingOperations {
         mtimeMs?: number;
         metadata?: unknown;
     }>;
+    writeBinary?(descriptor: {
+        filesystem: string;
+        path: string;
+        content: Uint8Array;
+    }): Promise<{
+        mtimeMs?: number;
+        metadata?: unknown;
+    }>;
     delete?(descriptor: {
         filesystem: string;
         path: string;
@@ -428,6 +512,10 @@ interface RuntimeFilesystemBindingOperations {
     }): Promise<{
         metadata?: unknown;
     }>;
+    resolveAccess?(descriptor: {
+        filesystem: string;
+        path: string;
+    }): Promise<RuntimeFilesystemAccessDecision>;
     rejectMutation(operation: string, descriptor: {
         filesystem: string;
         path: string;
@@ -459,6 +547,12 @@ interface RuntimeBundle {
     filesystem?: RuntimeFilesystemStrategy;
     /** Optional filesystem bindings prepared for this runtime/session. */
     filesystemBindings?: RuntimeFilesystemBinding[];
+    /**
+     * Workspace-relative prefixes the host protects from mutation. Carried on the
+     * bundle so shell/provisioning enforcement uses the same policy as the
+     * Operations bindings instead of re-deriving it.
+     */
+    readonlyWorkspacePaths?: readonly string[];
     /** Provisioning operations derived from this bundle's acquired Workspace + Sandbox pair. */
     provisioningAdapter?: WorkspaceProvisioningAdapter;
     /** Idempotently releases the acquired Workspace + Sandbox pair. */
@@ -474,6 +568,8 @@ declare function mergePiPackageSources(base?: PiPackageSource[], additional?: Pi
 interface PiHarnessOptions {
     noContextFiles?: boolean;
     noSkills?: boolean;
+    /** Disable ambient Pi extensions (required when tools execute in a remote runtime). */
+    noExtensions?: boolean;
     additionalSkillPaths?: string[];
     defaultModel?: {
         provider: string;
@@ -510,9 +606,36 @@ interface HotReloadablePiResources {
     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';
+/**
+ * GET /api/v1/agents/:agentTypeId/skills
+ *
+ * Returns the list of PI skills discovered for the current workspace —
+ * global skills (~/.pi/agent/skills) plus any project-local SKILL.md files.
+ * The front-end uses this to populate the slash-command picker without
+ * host apps having to hardcode skill names in extraCommands.
+ *
+ * Shape:
+ *   { skills: [{ name: string, description: string }] }
+ */
+
+interface SkillSummary {
+    name: string;
+    description: string;
+    /** Browser-safe locator for opening a supported skill source. */
+    resource?: AgentSkillResource;
+    /** False for management-only rows that Pi did not retain as invocable. */
+    invocable?: boolean;
+    /** Human-readable source/scope label for diagnostics and disabled rows. */
+    source?: string;
+}
+interface AgentSkillResourceSnapshot {
+    readonly generation: string;
+    readonly managedSkills: readonly SkillSummary[];
+    locateSkill(filePath: string): AgentSkillResource | undefined;
+}
+
+type AgentGatewayEffect = 'session.create' | 'session.rename' | 'session.delete' | 'session.prompt' | 'session.followup' | 'session.interrupt' | 'session.stop' | 'session.queue.clear' | 'agent.reload' | 'session.command.execute';
 type AgentRequestTarget = {
     readonly kind: 'agent';
     readonly agentTypeId: string;
@@ -527,25 +650,20 @@ interface AgentRequestKey {
     readonly target: AgentRequestTarget;
     readonly requestId: string;
 }
+interface AgentStableServiceErrorDTO {
+    readonly statusCode: number;
+    readonly error: {
+        readonly code: string;
+        readonly message: string;
+        readonly retryable?: boolean;
+    };
+}
 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;
+    readonly kind: 'service';
+    readonly error: AgentStableServiceErrorDTO;
 };
 interface AgentRequestLedgerRecordBase {
     readonly key: AgentRequestKey;
@@ -570,13 +688,22 @@ type AgentRequestLedgerRecord = (AgentRequestLedgerRecordBase & {
     readonly error: AgentGatewayErrorDTO;
 });
 interface AgentRequestLedger {
-    prepare(key: AgentRequestKey, digest: string): Promise<AgentRequestLedgerRecord>;
+    /** Direct production projections require transactional durable ownership. */
+    readonly durability: 'durable-transactional' | 'in-memory';
+    /** Atomic compare-and-create across every process sharing the durable store. */
+    prepare(key: AgentRequestKey, digest: string): Promise<AgentRequestLedgerPrepareResult>;
+    /** All transitions are compare-and-swap against the exact allowed prior state. */
     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>;
+    close?(): void | Promise<void>;
+}
+interface AgentRequestLedgerPrepareResult {
+    readonly ownership: 'created' | 'existing';
+    readonly record: AgentRequestLedgerRecord;
 }
 type AgentEffectAdmissionResult = {
     readonly type: 'accepted';
@@ -598,13 +725,45 @@ interface AgentEffectAdmission {
         readonly target: AgentRequestTarget;
     }): Promise<AgentEffectAdmissionResult>;
 }
+/**
+ * An authored file that contributes to this agent's instructions, addressed
+ * exactly like every other openable resource (`{filesystem, path}`) so the
+ * client can route it through the same safety guard as skills.
+ *
+ * The Host knows these locations from fleet configuration; clients must never
+ * re-derive them from the agent id (seat and agentTypeId are unrelated
+ * fleet.yaml fields). `role` is a DISCRIMINATOR, not a display string — the
+ * words shown to the user are the client's business.
+ */
+interface AgentInstructionFileRef {
+    readonly filesystem: string;
+    /** Workspace-relative path, e.g. `.agents/personas/concierge/instructions.md`. */
+    readonly path: string;
+    readonly role: 'persona';
+}
 interface ConfiguredAgentHostAgentSpec {
     readonly agentTypeId: string;
     readonly definition: {
         readonly instructions: string;
         readonly label: string;
         readonly version?: string;
+        /**
+         * Computed identity of the compiled definition (instructions + knowledge
+         * bytes). The digest, not the version string, is the definition identity.
+         */
+        readonly digest?: string;
     };
+    /**
+     * Optional agent-carried knowledge shipped inside the definition package.
+     * Composition mounts it as a readonly, agent-scoped filesystem binding;
+     * absent = no binding.
+     */
+    readonly knowledge?: {
+        /** Host path of the package's `knowledge/` folder. */
+        readonly rootDir: string;
+    };
+    /** Authored instruction sources behind `definition.instructions`. */
+    readonly instructionFiles?: readonly AgentInstructionFileRef[];
     readonly plugins?: readonly {
         /** Canonical app-preflighted plugin ID. */
         readonly name: string;
@@ -638,6 +797,8 @@ interface AgentFleetCompiler {
 interface ResolvedEnvironmentScope {
     readonly placementIdentity: string;
     readonly workspaceRoot: string;
+    /** Physical provider workspace identifier; defaults to the verified storage scope. */
+    readonly runtimeWorkspaceId?: string;
     readonly templatePath?: string;
     readonly provisioningFingerprint: string;
     readonly provisionRuntime?: (input: {
@@ -646,81 +807,116 @@ interface ResolvedEnvironmentScope {
     }) => Promise<WorkspaceProvisioningResult | undefined>;
 }
 interface ResolvedAgentRuntimeScope {
-    /** Complete app-canonicalized PL1 composition identity. */
+    /** Persisted semantic compatibility identity. */
     readonly identity: string;
+    /** Stable physical binding slot, independent of semantic resource revisions. */
+    readonly physicalBindingIdentity?: string;
+    /** Canonical digest of the immutable plugin/resource inputs used by reload. */
+    readonly resourceInputDigest?: string;
+    /**
+     * Side-effect-free fence for path-backed reload resources. The Host invokes
+     * it after classification, immediately before the effect, and after every
+     * awaited apply/load stage so a successful receipt always matches the
+     * resourceInputDigest recorded in the ledger.
+     */
+    readonly revalidateResourceInputs?: () => Promise<void>;
     readonly environment: ResolvedEnvironmentScope;
     readonly sessionNamespace: string;
     readonly pi?: PiHarnessOptions;
     readonly extraTools?: readonly AgentTool[];
+    readonly includeFilesystemTools?: boolean;
+    readonly includeUploadTools?: boolean;
+    readonly sessionDir?: string;
+    readonly reloadMetadata?: {
+        readonly diagnostics?: ReadonlyArray<{
+            readonly source: string;
+            readonly message: string;
+            readonly pluginId?: string;
+        }>;
+        readonly restartWarnings?: ReadonlyArray<{
+            readonly id: string;
+            readonly surfaces: readonly string[];
+            readonly message: string;
+        }>;
+    };
+    /**
+     * Host-internal reload mutation. Candidate identity fields above must be
+     * resolved without mutating plugin, backend, or runtime resource state.
+     * The Host invokes this callback only after durable ownership, admission,
+     * immutable identity classification, and the binding operation fence.
+     */
+    readonly applyReload?: (input: {
+        readonly runtimeBundle: RuntimeBundle;
+    }) => Promise<{
+        readonly diagnostics?: ReadonlyArray<{
+            readonly source: string;
+            readonly message: string;
+            readonly pluginId?: string;
+        }>;
+        readonly restartWarnings?: ReadonlyArray<{
+            readonly id: string;
+            readonly surfaces: readonly string[];
+            readonly message: string;
+        }>;
+    } | undefined>;
     readonly getFilesystemBindings?: (input: {
         readonly scope: VerifiedAgentScopeClaim;
         readonly sessionId?: string;
         readonly requestId: string;
     }) => Promise<readonly RuntimeFilesystemBinding[] | undefined>;
+    /**
+     * Skill-resource locator/catalog snapshot for the current reload
+     * generation. Threaded through the capability-projection layer so
+     * `/skills` can resolve package-managed skill locators without going
+     * through the legacy path-shaped `additionalSkillPaths` hot-reload API.
+     */
+    readonly getSkillResourceSnapshot?: (input: {
+        readonly scope: VerifiedAgentScopeClaim;
+        readonly sessionId?: string;
+        readonly requestId: string;
+    }) => Promise<AgentSkillResourceSnapshot | 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;
+interface AuthorizedEnvironmentIntent {
+    readonly kind: 'http-route' | 'dispatcher' | 'agent-binding';
+    readonly requestId: string;
 }
-/**
- * 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 AgentHostEnvironmentScope extends ResolvedEnvironmentScope {
+    /** App-owned environment decoration applied once to the canonical provider generation. */
+    readonly transformRuntimeBundle?: (runtimeBundle: RuntimeBundle) => RuntimeBundle | Promise<RuntimeBundle>;
+    /** Evaluated for every authorized operation; never cached as placement authority. */
+    readonly resolveFilesystemBindings?: (input: {
+        readonly verifiedClaim: VerifiedAgentScopeClaim;
+        readonly requestId: string;
+    }) => Promise<readonly RuntimeFilesystemBinding[] | undefined>;
 }
-interface AgentHostHttpProjectionBaseOptions {
-    readonly defaultAgentTypeId: string;
+interface AgentHostEnvironmentLease {
+    readonly workspace: Workspace;
+    readonly gitWorkspace: Workspace;
+    readonly fileSearch: FileSearch;
+    readonly filesystemBindings?: readonly RuntimeFilesystemBinding[];
+    readonly readiness: Readonly<AgentCapabilityReadiness>;
+    readonly signal: AbortSignal;
+    release(): void;
+}
+interface AgentHostDispatcherRunInput extends WorkspaceAgentDirectRunInput {
+    readonly authorizedScope: AuthorizedAgentScope;
+    readonly request?: FastifyRequest;
+}
+interface AgentHostDirectProjectionOptions {
+    readonly authorizeAgentRequest: (request: FastifyRequest) => Promise<AuthorizedAgentScope>;
+    readonly filterModels?: ModelsRoutesOptions['filterModels'];
+    readonly sessionChangesTracker?: SessionChangesTracker;
+    readonly defaultSessionId?: 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;
+        /** Computed definition identity digest (instructions + knowledge bytes), when the spec carries one. */
+        readonly definitionDigest?: string;
     }[];
     readonly draining: boolean;
 }
@@ -738,13 +934,29 @@ interface CreateAgentHostOptions {
     readonly runtimeModeAdapter: RuntimeModeAdapter;
     readonly runtimeHost?: AgentRuntimeHostOperations;
     readonly sessionRoot?: string;
-    readonly resolveRuntimeScope: (input: {
+    readonly resolveAuthorizedEnvironmentScope?: (input: {
+        readonly authorizedScope: AuthorizedAgentScope;
+        readonly verifiedClaim: VerifiedAgentScopeClaim;
+        readonly intent: AuthorizedEnvironmentIntent;
+    }) => Promise<AgentHostEnvironmentScope>;
+    readonly resolveAuthorizedAgentRuntimeScope?: (input: {
+        readonly authorizedScope: AuthorizedAgentScope;
+        readonly verifiedClaim: VerifiedAgentScopeClaim;
         readonly agentTypeId: string;
-        readonly scope: AuthorizedAgentScope;
-    }) => Promise<ResolvedAgentRuntimeScope>;
+        readonly intent: AuthorizedEnvironmentIntent & {
+            readonly kind: 'agent-binding';
+            readonly operation: 'new-binding' | 'existing-session' | 'reload';
+            readonly sessionId?: string;
+        };
+        readonly environment: AgentHostEnvironmentScope;
+    }) => Promise<Omit<ResolvedAgentRuntimeScope, 'environment'>>;
     readonly telemetry?: TelemetrySink;
     readonly metering?: AgentMeteringSink;
     readonly requestLedger?: AgentRequestLedger;
+    /** Durable effect ledger path, independent of transcript/session storage. */
+    readonly requestLedgerPath?: string;
+    /** Explicit test/dev opt-in for an in-memory ledger. */
+    readonly inMemoryRequestLedgerMode?: 'test' | 'development';
     readonly requestRetentionMs?: number;
     readonly effectAdmission?: AgentEffectAdmission;
     readonly shutdownGraceMs?: number;
@@ -753,7 +965,12 @@ interface CreateAgentHostOptions {
 interface CreatedAgentHost {
     readonly host: AgentHostHandle;
     readonly gateway: AgentGateway;
-    registerRoutes(options: AgentHostHttpProjectionOptions): FastifyPluginAsync;
+    registerDirectRoutes(options: AgentHostDirectProjectionOptions): FastifyPluginAsync;
+    acquireEnvironment(input: {
+        readonly authorizedScope: AuthorizedAgentScope;
+        readonly intent: AuthorizedEnvironmentIntent;
+    }): Promise<AgentHostEnvironmentLease>;
+    runWithWorkspaceAgent(input: AgentHostDispatcherRunInput, run: (binding: LeaseBoundWorkspaceAgent) => Promise<void>): Promise<void>;
 }
 
-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 };
+export { type PiExtensionFactory as $, type AgentGatewayEffect as A, type BuiltinRuntimeModeId as B, type ConfiguredAgentHostAgentSpec as C, type AgentFleetCompiler as D, type AgentRequestTarget as E, type RuntimeFilesystemAccessDecision as F, type AgentHostDescription as G, type AgentHostDirectProjectionOptions as H, type AgentHostDispatcherRunInput as I, type AgentHostEnvironmentLease as J, type AgentHostHandle as K, type LegacyDefaultAgentHostSpec as L, type ModeContext as M, type MeteringReleaseInput as N, type MeteringReleaseReason as O, type ProvisionWorkspaceRuntimeOptions as P, type MeteringReservationResult as Q, type RuntimeModeAdapter as R, type MeteringReserveInput as S, type MeteringRunKind as T, type MeteringRunScope as U, type MeteringRunStatus as V, type WorkspaceProvisioningResult as W, type MeteringSettleInput as X, type MeteringUsage as Y, type MeteringUsageInput as Z, PI_PACKAGE_RESOURCE_FILTERS as _, type PiPackageSource 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, mergePiPackageSources as a9, normalizeMeteringUsage as aa, piPackageSourceKey as ab, type RuntimeModeId as b, type AgentRuntimeHostOperations as c, type RuntimeBashStrategy as d, type RuntimeFilesystemStrategy as e, type WorkspaceProvisioningAdapter as f, type AgentInstructionFileRef as g, type AgentHostAgentSpec as h, type RuntimeBundle as i, type PiHarnessOptions as j, type AgentMeteringSink as k, type RuntimeFilesystemBinding as l, type CreatedAgentHost as m, type MeteringErrorLogger as n, ReadyStatusTracker as o, type ResolvedAgentRuntimeScope as p, type CreateAgentHostOptions as q, type CompiledAgentHostAgentSpec as r, type AgentRequestLedger as s, type AgentEffectAdmission as t, type AuthorizedEnvironmentIntent as u, type AgentHostEnvironmentScope as v, type AgentRequestKey as w, type AgentRequestLedgerPrepareResult as x, type AgentRequestFailure as y, type AgentRequestLedgerRecord as z };

package/docs/AGENT_GATEWAY_V0.md

@@ -97,19 +97,22 @@ shorthand. Prompts add `displayContent?`, `model?`, `thinkingLevel?`,
 
 ## Error codes
 
-Thirteen, exhaustive, order-stable, exported as both a const map and
+Fifteen, exhaustive, order-stable, exported as both a const map and
 `AGENT_GATEWAY_ERROR_CODES`:
 
 `AGENT_TYPE_UNKNOWN` · `AGENT_SESSION_NOT_FOUND` · `AGENT_SCOPE_DENIED` ·
 `AGENT_SESSION_REPLAY_GAP` · `AGENT_SESSION_CURSOR_AHEAD` ·
 `AGENT_SESSION_CURSOR_EXPIRED` · `AGENT_SESSION_CURSOR_INVALID` ·
-`AGENT_REQUEST_CONFLICT` · `AGENT_REQUEST_OUTCOME_UNKNOWN` ·
+`AGENT_REQUEST_CONFLICT` · `AGENT_REQUEST_IN_PROGRESS` ·
+`AGENT_REQUEST_OUTCOME_UNKNOWN` · `AGENT_RUNTIME_RESTART_REQUIRED` ·
 `AGENT_COMMAND_INVALID_STATE` · `AGENT_SESSION_RUNTIME_SCOPE_MISMATCH` ·
 `AGENT_SHARED_ENVIRONMENT_UNAVAILABLE` · `AGENT_GATEWAY_CLOSED`
 
 HTTP mapping lives in `server/agent-host/httpProjection.ts`
 (`statusForGatewayError`). Note `AGENT_SESSION_RUNTIME_SCOPE_MISMATCH`,
-`AGENT_REQUEST_CONFLICT` and `AGENT_COMMAND_INVALID_STATE` project to **409**.
+`AGENT_REQUEST_CONFLICT`, `AGENT_REQUEST_IN_PROGRESS`,
+`AGENT_RUNTIME_RESTART_REQUIRED`, and `AGENT_COMMAND_INVALID_STATE` project to
+**409**.
 
 ## Conformance levels
 

package/docs/AGENT_PACKAGES.md

@@ -0,0 +1,80 @@
+# Workspace agent packages
+
+With `BORING_AGENT_FLEET=1`, a single-workspace host may discover an agent
+definition from either the trusted repository's `.agents/personas/` packages
+or a local package path registered in that workspace's
+`.pi/settings.json#packages`. Registration makes an agent package discoverable.
+It does not activate the agent: the class-B `.agents/factory/fleet.yaml` roster
+must also seat the package's `boring.agent.definitionId`.
+
+Agent fleet changes are boot-time changes. `/reload` can refresh ordinary
+plugin resources, but installing, updating, seating, unseating, or removing an
+agent requires restarting the workspace/CLI host.
+
+The CLI workspaces hub has one Agent Host shared by every registered workspace.
+Its global fleet therefore admits only personas from the trusted repository's
+`.agents/personas/`; it does not admit agent definitions from any workspace's
+local package registrations. Local packages keep their ordinary plugin
+surfaces in their owning workspace. Seating workspace-local agent definitions
+in workspaces mode requires a future workspace-scoped fleet boundary.
+
+## Install and seat
+
+From the workspace root, register a local package directory:
+
+```bash
+boring-ui-plugin install --local --workspace . ../agent-packages/my-agent
+```
+
+The package keeps all of its normal plugin surfaces. Its agent contribution is
+still inert until the fleet roster names its definition id:
+
+```yaml
+seats:
+  - seat: my-agent
+    agentTypeId: my-agent-definition
+    skills: []
+```
+
+Restart a single-workspace host with `BORING_AGENT_FLEET=1`. A valid seated
+package appears in the agent catalog. An installed package without a matching
+seat remains inert and reports `AGENT_DEFINITION_UNSEATED` during fleet
+composition. The shared CLI workspaces hub never admits the local agent
+contribution, even when the global roster names its definition id.
+
+## Update
+
+1. Update the source directory and bump both package/agent versions as needed.
+2. For repository personas under `.agents/personas/`, run
+   `pnpm write:skill-digests` from the repository root.
+3. Restart the workspace/CLI host.
+
+Digest refresh is intentionally repository-local in v1. The script reads only
+`.agents/personas/`; it does not rewrite pins for agent packages installed from
+another local directory. Such packages must already have matching
+seat-authoritative skill pins. A mismatch excludes only that seat with
+`AGENT_FLEET_SEAT_SKILL_DIGEST_MISMATCH`; the rest of the fleet still boots.
+
+## Unseat or remove
+
+To make a package inert but keep it installed, remove its seat from
+`.agents/factory/fleet.yaml` and restart.
+
+To remove its workspace registration as well:
+
+```bash
+boring-ui-plugin remove --local --workspace . my-agent-plugin-id
+```
+
+Then restart. If the roster still names the removed definition, that seat is
+excluded with `AGENT_FLEET_SEAT_PERSONA_INVALID` while other agents boot.
+
+## v1 distribution boundary
+
+Repository personas may contribute agents to any fleet in v1. A
+workspace-registered local package path may contribute an agent only to a
+single-workspace host; it never enters the CLI workspaces hub's global fleet.
+Git/npm package sources — including their materialized `.pi/git/` and
+`.pi/npm/` directories — cannot contribute an agent until the
+remote-distribution trust gate ships. All excluded packages' non-agent plugin
+surfaces continue through the normal plugin pipeline unchanged.