@hachej/boring-agent 0.1.108 → 0.1.110

package/dist/shared/index.js

@@ -11,6 +11,7 @@ import {
   AgentTaskSchema,
   ArtifactLocatorSchema,
   ArtifactRefSchema,
+  CHANNEL_DESCRIPTORS,
   CREDENTIAL_AAD_ENCODING_VERSION,
   CREDENTIAL_AUTH_TAG_BYTE_LENGTH_V1,
   CREDENTIAL_DEK_BYTE_LENGTH_V1,
@@ -47,9 +48,11 @@ import {
   WORKSPACE_KEK_PROVIDER_VERSION,
   WorkspaceFileLocatorSchema,
   agentRefEquals,
+  assertCredentialCustodyScopeV1,
   assertNoConsumptionCycle,
   assertValidTransition,
   assertWithinConsumptionDepth,
+  channelDescriptor,
   createAgentAssetDigest,
   createAgentDefinitionDigest,
   createAgentDeploymentDigest,
@@ -57,6 +60,7 @@ import {
   createNotImplementedSandboxCredentialPayloadResolverV1,
   createProviderCredentialRefFactoryV1,
   createProviderRegistryV1,
+  credentialCustodySubjectKeyV1,
   detectConsumptionCycle,
   isReadonlyFilesystemMutationError,
   isValidTaskTransition,
@@ -65,13 +69,15 @@ import {
   providerCredentialFieldsV1,
   resolveShareEntry,
   sandboxCredentialPayloadMetadataBytesV1,
+  userCredentialCustodyScopeV1,
   validateAgentDefinition,
   validateAgentDeployment,
   validateAgentTask,
   validateConfig,
   validateConsumptionGuards,
-  validateTool
-} from "../chunk-6OANSUEI.js";
+  validateTool,
+  workspaceCredentialCustodyScopeV1
+} from "../chunk-72KT6VWV.js";
 import {
   SAFE_NATIVE_SESSION_ID,
   compareSessionOrder,
@@ -114,7 +120,7 @@ import {
   extractToolUiMetadata,
   isToolUiMetadata,
   sanitizeToolUiMetadata2 as sanitizeToolUiMetadata
-} from "../chunk-MVKXLMH3.js";
+} from "../chunk-KN72XWP7.js";
 import {
   safeRandomUUID
 } from "../chunk-YGRQ4Q5P.js";
@@ -127,7 +133,7 @@ import {
   ERROR_CODES,
   ErrorCode,
   ErrorLogFieldsSchema
-} from "../chunk-3JFPS2O6.js";
+} from "../chunk-KJIEMSQP.js";
 export {
   AGENT_GATEWAY_ERROR_CODES,
   AGENT_KNOWLEDGE_FILESYSTEM_ID,
@@ -153,6 +159,7 @@ export {
   ArtifactRefSchema,
   BoringChatMessageSchema,
   BoringChatPartSchema,
+  CHANNEL_DESCRIPTORS,
   CREDENTIAL_AAD_ENCODING_VERSION,
   CREDENTIAL_AUTH_TAG_BYTE_LENGTH_V1,
   CREDENTIAL_DEK_BYTE_LENGTH_V1,
@@ -216,9 +223,11 @@ export {
   WORKSPACE_KEK_PROVIDER_VERSION,
   WorkspaceFileLocatorSchema,
   agentRefEquals,
+  assertCredentialCustodyScopeV1,
   assertNoConsumptionCycle,
   assertValidTransition,
   assertWithinConsumptionDepth,
+  channelDescriptor,
   compareSessionOrder,
   createAgentAssetDigest,
   createAgentDefinitionDigest,
@@ -227,6 +236,7 @@ export {
   createNotImplementedSandboxCredentialPayloadResolverV1,
   createProviderCredentialRefFactoryV1,
   createProviderRegistryV1,
+  credentialCustodySubjectKeyV1,
   detectConsumptionCycle,
   extractToolUiMetadata,
   isReadonlyFilesystemMutationError,
@@ -241,10 +251,12 @@ export {
   safeRandomUUID,
   sandboxCredentialPayloadMetadataBytesV1,
   sanitizeToolUiMetadata,
+  userCredentialCustodyScopeV1,
   validateAgentDefinition,
   validateAgentDeployment,
   validateAgentTask,
   validateConfig,
   validateConsumptionGuards,
-  validateTool
+  validateTool,
+  workspaceCredentialCustodyScopeV1
 };

package/dist/{types-B7-PN5jV.d.ts → types-DcWoQMn8.d.ts}

@@ -1,14 +1,67 @@
+import { d as PiChatEvent, C as ChatModelSelection } from './piChatEvent-DpE0lIb9.js';
+import { v as SessionStreamIdentity, C as ToolReadinessRequirement, w as TelemetrySink, s as AgentTool, D as AgentHarnessFactory } from './harness-qHlMJhZo.js';
 import { FastifyRequest, FastifyPluginAsync } from 'fastify';
-import { C as ToolReadinessRequirement, w as TelemetrySink, s as AgentTool, D as AgentHarnessFactory } from './harness-Ct0e4RWc.js';
-import { F as FileSearch, b as AgentSkillResource, c as WorkspaceAgentDirectRunInput, L as LeaseBoundWorkspaceAgent } from './file-search-BGUHnW9o.js';
+import { F as FileSearch, g as AgentSkillResource, P as ProviderId, n as CredentialEnvelopeV1, K as WrappedWorkspaceDekV1, B as WorkspaceCredentialAuthorityVerifierV1, V as VerifiedWorkspaceCredentialAuthorityV1, t as WorkspaceAgentDirectRunInput, L as LeaseBoundWorkspaceAgent } from './file-search-BUgMSKZE.js';
 import { b as Workspace, h as RuntimeFilesystemCapability, j as WorkspaceRuntimeContext, c as Sandbox } from './sandbox-BMhut3kh.js';
-import { b as AgentSessionRef, V as VerifiedAgentScopeClaim, k as AgentGatewayErrorDTO, B as JsonValue, a as AuthorizedAgentScope, A as AgentGateway, m as AgentScopeVerifier, F as ResolveAgentAccess } from './errors-CEU4iujR.js';
-import { C as ChatModelSelection } from './piChatEvent-BUWIzw5l.js';
+import { B as CredentialLifecycleStateV1, b as AgentSessionRef, V as VerifiedAgentScopeClaim, k as AgentGatewayErrorDTO, P as JsonValue, a as AuthorizedAgentScope, A as AgentGateway, m as AgentScopeVerifier, T as ResolveAgentAccess } from './admin-DORVQfLn.js';
 import { RuntimeHostOperations, RuntimeFilesystemBinding as RuntimeFilesystemBinding$1 } from '@hachej/boring-bash/agent';
 import { BwrapArgsOptions } from '@hachej/boring-sandbox/providers/bwrap';
 import { CreateNodeWorkspaceOptions, BoringAgentRuntimePaths } from '@hachej/boring-sandbox/providers/node-workspace';
+import { CredentialStore } from '@earendil-works/pi-ai';
 import { PackageSource, ExtensionFactory } from '@mariozechner/pi-coding-agent';
 
+interface EventStreamReadResult {
+    events: Array<{
+        data: unknown;
+        offset: string;
+    }>;
+    nextOffset: string;
+    upToDate: boolean;
+    closed: boolean;
+}
+interface EventStreamMeta {
+    nextOffset: string;
+    closed: boolean;
+}
+interface SessionStreamOwner {
+    readonly path: string;
+    readonly workspaceScopeId: string;
+    readonly sessionId: string;
+    readonly agentTypeId: string | null;
+    readonly authSubjectId: string | null;
+    readonly seatId: string | null;
+    readonly threadId: string | null;
+    readonly keyVersion: number;
+    readonly createdAt: number;
+}
+interface CreateSessionStreamAttributes {
+    readonly agentTypeId: string;
+    readonly authSubjectId?: string;
+}
+declare const ownedSessionStreamBrand: unique symbol;
+interface OwnedSessionStream {
+    readonly [ownedSessionStreamBrand]: true;
+    readonly path: string;
+    readonly identity: SessionStreamIdentity;
+}
+interface EventStreamStore {
+    createStream(path: string): Promise<void>;
+    createSessionStream(identity: SessionStreamIdentity, attrs: CreateSessionStreamAttributes): Promise<OwnedSessionStream>;
+    readStreamOwner(path: string): Promise<SessionStreamOwner | null>;
+    appendEvent(path: string, event: unknown): Promise<string>;
+    appendEventOnce(path: string, key: string, event: unknown): Promise<string>;
+    appendAgentEvent(stream: OwnedSessionStream, chunk: PiChatEvent, opts?: {
+        idempotencyKey?: 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;
+}
+
 type SessionFileChangeOp = 'write' | 'edit' | 'unlink' | 'rename' | 'mkdir';
 interface SessionFileChange {
     op: SessionFileChangeOp;
@@ -320,7 +373,8 @@ interface ResolveInstallSourceOpts {
     fingerprint: string;
 }
 interface WorkspaceProvisioningAdapter {
-    mode: 'direct' | 'local' | 'blaxel' | 'vercel-sandbox';
+    /** Application-owned runtime ID; provisioning does not select builtin adapters. */
+    mode: string;
     exec(command: string, args: string[], opts?: {
         cwd?: string;
         env?: Record<string, string>;
@@ -403,6 +457,51 @@ type RuntimeFilesystemStrategy = {
     kind: 'remote-workspace';
     pathOptions?: RuntimeRemoteWorkspacePathOptions;
 };
+interface RuntimeProjectionRequest {
+    /** Server-private endpoint coordinates. Never expose this request to plugin/front/model code. */
+    port: number;
+    path?: string;
+}
+interface RuntimeProjectionLease {
+    /** Sealed upstream consumed only by the Host projection broker. */
+    readonly url: string;
+    readonly expiresAt: string;
+    revoke(): Promise<void>;
+}
+type RuntimeTrustedServiceOperation = 'start' | 'observe' | 'act' | 'takeover' | 'return-control' | 'stop';
+interface RuntimeTrustedServiceQualificationV1 {
+    readonly serviceRef: 'trusted-service-v1';
+    readonly protocolDigest: string;
+    readonly imageDigest: string;
+    readonly isolation: 'dedicated-uid-private-channel';
+}
+interface RuntimeTrustedServiceLeaseV1 {
+    readonly qualification: RuntimeTrustedServiceQualificationV1;
+    invoke(input: {
+        readonly operation: RuntimeTrustedServiceOperation;
+        readonly payload?: Uint8Array;
+        readonly timeoutMs: number;
+        readonly signal: AbortSignal;
+    }): Promise<{
+        readonly status: 'ok' | 'rejected' | 'unknown-outcome';
+        readonly payload?: Uint8Array;
+    }>;
+    /** Host-only fixed endpoint lookup. No host, port, URL, or provider identity crosses this seam. */
+    createProjection(input: {
+        readonly mode: 'observe' | 'control';
+        readonly expiresAt: Date;
+    }): Promise<RuntimeProjectionLease>;
+    close(): Promise<void>;
+}
+interface RuntimeTrustedServiceMechanismV1 {
+    readonly qualification: RuntimeTrustedServiceQualificationV1;
+    acquire(input: {
+        readonly leaseId: string;
+        readonly idleTtlMs: number;
+        readonly absoluteTtlMs: number;
+        readonly signal: AbortSignal;
+    }): Promise<RuntimeTrustedServiceLeaseV1>;
+}
 interface RuntimeModeAdapter {
     readonly id: RuntimeModeId;
     readonly runtimeHost?: AgentRuntimeHostOperations;
@@ -574,6 +673,10 @@ interface RuntimeBundle {
     filesystem?: RuntimeFilesystemStrategy;
     /** Optional filesystem bindings prepared for this runtime/session. */
     filesystemBindings?: RuntimeFilesystemBinding[];
+    /** Pair-local projection authority captured with this exact RuntimeBundle generation. */
+    createRuntimeProjection?: (request: RuntimeProjectionRequest) => Promise<RuntimeProjectionLease>;
+    /** Qualified fixed service channel. Ordinary Agent tools never receive this field. */
+    trustedServiceV1?: RuntimeTrustedServiceMechanismV1;
     /**
      * Workspace-relative prefixes the host protects from mutation. Carried on the
      * bundle so shell/provisioning enforcement uses the same policy as the
@@ -602,6 +705,8 @@ interface PiHarnessOptions {
     noSkills?: boolean;
     /** Disable ambient Pi extensions (required when tools execute in a remote runtime). */
     noExtensions?: boolean;
+    /** Ignore packages from user/project Pi settings while preserving explicit host package grants. */
+    noAmbientPackages?: boolean;
     additionalSkillPaths?: string[];
     defaultModel?: {
         provider: string;
@@ -631,6 +736,8 @@ interface PiHarnessOptions {
     getHotReloadableResources?: () => HotReloadablePiResources;
     /** Reject an explicit unavailable/unknown model instead of silently falling back. */
     strictModelResolution?: boolean;
+    /** Host-owned, actor-bound credential source. Never projected into the runtime workspace. */
+    credentialStore?: CredentialStore;
 }
 /** Pi harness options with the discovery flags resolved to definite booleans. */
 type ResolvedPiHarnessOptions = PiHarnessOptions & {
@@ -672,7 +779,151 @@ interface AgentSkillResourceSnapshot {
     locateSkill(filePath: string): AgentSkillResource | undefined;
 }
 
-type AgentGatewayEffect = 'session.create' | 'session.rename' | 'session.archive' | 'session.delete' | 'session.prompt' | 'session.followup' | 'session.interrupt' | 'session.stop' | 'session.queue.clear' | 'agent.reload' | 'session.command.execute';
+/**
+ * Injectable persistence port for the credential vault.
+ *
+ * The ratified persistence model (docs/issues/820/byok-secret-vault-plan.md,
+ * "Proposed persistence model") maps one-to-one onto these methods:
+ * `workspace_provider_credentials` -> credential record,
+ * `workspace_credential_keys` -> wrapped DEK,
+ * `workspace_provider_credential_fields` -> field envelope.
+ *
+ * S1 supplies both in-memory and Postgres implementations. Only ciphertext,
+ * nonce, tag, persisted AAD, and metadata-only tombstones cross this port —
+ * never plaintext, never a KEK.
+ */
+type CredentialMaterialKindV1 = 'field-set' | 'none';
+/** Metadata-only projection. Secret envelopes are deliberately unreachable here. */
+interface StoredCredentialMetadataV1 {
+    readonly providerId: ProviderId;
+    readonly displayLabel: string;
+    readonly credentialType: string;
+    readonly state: CredentialLifecycleStateV1;
+    readonly credentialVersion: number;
+    readonly maskedLastFourSuffix?: string;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+}
+interface StoredCredentialRecordV1 {
+    /** Stable per-(workspace, provider) credential identity, bound into AAD. */
+    readonly credentialId: string;
+    readonly credentialVersion: number;
+    readonly dekGeneration: number;
+    readonly materialKind: CredentialMaterialKindV1;
+}
+interface CredentialFieldKeyV1 {
+    readonly workspaceId: string;
+    readonly providerId: ProviderId;
+    readonly credentialVersion: number;
+    /** Required when persisting a live envelope; omitted for keyed reads. */
+    readonly dekGeneration?: number;
+    readonly fieldId: string;
+}
+type CredentialFieldDeletionReasonV1 = 'superseded-version' | 'credential-tombstone' | 'crypto-shred';
+interface WorkspaceDekRotationStateV1 {
+    /** Caller-stable idempotency key. A retry must present the same operation id. */
+    readonly operationId: string;
+    readonly sourceGeneration: number;
+    readonly targetGeneration: number;
+    readonly phase: 'reencrypting' | 'verified' | 'anchor-advanced';
+}
+interface WorkspaceDekRotationReceiptV1 {
+    readonly operationId: string;
+    readonly sourceGeneration: number;
+    readonly targetGeneration: number;
+}
+interface WorkspaceCredentialRecordV1 {
+    readonly providerId: ProviderId;
+    readonly record: StoredCredentialRecordV1;
+}
+interface CommitDekRotationRecordInputV1 {
+    readonly workspaceId: string;
+    readonly providerId: ProviderId;
+    readonly expectedCredentialVersion: number;
+    readonly sourceGeneration: number;
+    readonly targetGeneration: number;
+    readonly fields: ReadonlyMap<string, CredentialEnvelopeV1>;
+}
+interface CredentialFieldTombstoneV1 {
+    readonly deletedAt: string;
+    readonly reason: CredentialFieldDeletionReasonV1;
+}
+interface CommitCredentialVersionInputV1 {
+    readonly workspaceId: string;
+    readonly providerId: ProviderId;
+    readonly expectedCredentialVersion: number;
+    readonly record: StoredCredentialRecordV1;
+    readonly fields: ReadonlyMap<string, CredentialEnvelopeV1>;
+    readonly supersededFieldsTombstone?: CredentialFieldTombstoneV1;
+}
+interface CommitCredentialVersionInputV2 extends CommitCredentialVersionInputV1 {
+    /** Applied in the same durable transaction as the record/version CAS. */
+    readonly metadataUpdate: Readonly<{
+        state: CredentialLifecycleStateV1;
+        displayLabel?: string;
+        credentialType?: string;
+        maskedLastFourSuffix?: string | null;
+    }>;
+}
+interface WorkspaceCredentialLockOptionsV1 {
+    /** Cancels only while waiting to acquire the lock; a running mutation is never interrupted. */
+    readonly signal?: AbortSignal;
+    /** Absolute Unix timestamp in milliseconds by which lock acquisition must finish. */
+    readonly deadlineMs?: number;
+    /** Relative acquisition bound. The earliest of this and deadlineMs wins. */
+    readonly timeoutMs?: number;
+}
+interface CredentialVaultPersistenceV1 {
+    /** Serializes workspace-wide lifecycle mutations and supplies a scoped adapter. */
+    withWorkspaceLock<T>(workspaceId: string, mutate: (locked: CredentialVaultPersistenceV1) => Promise<T>, options?: WorkspaceCredentialLockOptionsV1): Promise<T>;
+    getCredentialMetadata(workspaceId: string, providerId: ProviderId): Promise<StoredCredentialMetadataV1 | undefined>;
+    listCredentialMetadata(workspaceId: string): Promise<readonly StoredCredentialMetadataV1[]>;
+    /** True when any credential row, key, field/tombstone, rotation, or shred fence remains. */
+    hasWorkspaceCredentialArtifacts(workspaceId: string): Promise<boolean>;
+    updateCredentialMetadata(workspaceId: string, providerId: ProviderId, update: Readonly<{
+        state: CredentialLifecycleStateV1;
+        displayLabel?: string;
+        credentialType?: string;
+        maskedLastFourSuffix?: string | null;
+    }>): Promise<StoredCredentialMetadataV1>;
+    getCredentialRecord(workspaceId: string, providerId: ProviderId): Promise<StoredCredentialRecordV1 | undefined>;
+    putCredentialRecord(workspaceId: string, providerId: ProviderId, record: StoredCredentialRecordV1): Promise<void>;
+    /** Atomically CASes the record, fields, and superseded-version tombstones. */
+    commitCredentialVersion(input: CommitCredentialVersionInputV1): Promise<void>;
+    getWrappedDek(workspaceId: string, dekGeneration: number): Promise<WrappedWorkspaceDekV1 | undefined>;
+    putWrappedDek(workspaceId: string, dekGeneration: number, wrapped: WrappedWorkspaceDekV1): Promise<void>;
+    deleteWrappedDek(workspaceId: string, dekGeneration: number): Promise<void>;
+    listCredentialRecords(workspaceId: string): Promise<readonly WorkspaceCredentialRecordV1[]>;
+    listFields(workspaceId: string, providerId: ProviderId, credentialVersion: number): Promise<ReadonlyMap<string, CredentialEnvelopeV1>>;
+    /** Atomically replaces one current record's envelopes during DEK rotation. */
+    commitDekRotationRecord(input: CommitDekRotationRecordInputV1): Promise<void>;
+    getDekRotationState(workspaceId: string): Promise<WorkspaceDekRotationStateV1 | undefined>;
+    putDekRotationState(workspaceId: string, state: WorkspaceDekRotationStateV1): Promise<void>;
+    getDekRotationReceipt(workspaceId: string, operationId: string): Promise<WorkspaceDekRotationReceiptV1 | undefined>;
+    /** Atomically destroys N, clears the active marker, and records the idempotency receipt. */
+    finalizeDekRotation(workspaceId: string, state: WorkspaceDekRotationStateV1): Promise<void>;
+    clearDekRotationState(workspaceId: string): Promise<void>;
+    isWorkspaceCryptoShredded(workspaceId: string): Promise<boolean>;
+    /** Atomically tombstones ciphertext, destroys wrapped DEKs, and records the shred fence. */
+    cryptoShredWorkspace(workspaceId: string, shreddedAt: string): Promise<void>;
+    getField(key: CredentialFieldKeyV1): Promise<CredentialEnvelopeV1 | undefined>;
+    putField(key: CredentialFieldKeyV1, envelope: CredentialEnvelopeV1): Promise<void>;
+    /** Deletes ciphertext and retains metadata-only tombstones for every field. */
+    tombstoneCredentialVersionFields(workspaceId: string, providerId: ProviderId, credentialVersion: number, tombstone: CredentialFieldTombstoneV1): Promise<void>;
+    getFieldTombstone(key: CredentialFieldKeyV1): Promise<CredentialFieldTombstoneV1 | undefined>;
+}
+/** Persistence capability required by the V2 recoverable vault protocol. */
+interface CredentialVaultPersistenceV2 extends CredentialVaultPersistenceV1 {
+    readonly contractVersion: 'boring.credential-vault-persistence.v2';
+    /** Preserves the V2 capability on the transaction-scoped adapter. */
+    withWorkspaceLock<T>(workspaceId: string, mutate: (locked: CredentialVaultPersistenceV2) => Promise<T>, options?: WorkspaceCredentialLockOptionsV1): Promise<T>;
+    /** Atomically CASes record, fields, tombstones, and authenticated metadata. */
+    commitCredentialVersionV2(input: CommitCredentialVersionInputV2): Promise<void>;
+}
+
+/** Single runtime and type-level source of truth for gateway operations persisted in request keys. */
+declare const AGENT_GATEWAY_EFFECTS: readonly ["session.create", "session.rename", "session.archive", "session.delete", "session.prompt", "session.followup", "session.interrupt", "session.stop", "session.queue.clear", "agent.reload", "session.command.execute"];
+type AgentGatewayEffect = typeof AGENT_GATEWAY_EFFECTS[number];
 type AgentRequestTarget = {
     readonly kind: 'agent';
     readonly agentTypeId: string;
@@ -687,6 +938,31 @@ interface AgentRequestKey {
     readonly target: AgentRequestTarget;
     readonly requestId: string;
 }
+type RunId = string;
+interface VerifiedSeatParticipation {
+    readonly seatId: string;
+}
+/** Admission-time identity and provenance reference; never a live authorization grant. */
+interface AcceptedWorkContext {
+    readonly version: 1;
+    readonly identity: {
+        readonly runId: RunId;
+        readonly requestKey: AgentRequestKey;
+        readonly agent: {
+            readonly agentTypeId: string;
+        };
+        readonly participation?: VerifiedSeatParticipation;
+    };
+    readonly operation: AgentGatewayEffect;
+    readonly target: AgentRequestTarget;
+    readonly authority: {
+        readonly workspaceScopeId: string;
+        readonly authSubjectId: string;
+    };
+    readonly delegation: {
+        readonly lineage: readonly RunId[];
+    };
+}
 interface AgentStableServiceErrorDTO {
     readonly statusCode: number;
     readonly error: {
@@ -704,13 +980,17 @@ type AgentRequestFailure = {
 };
 interface AgentRequestLedgerRecordBase {
     readonly key: AgentRequestKey;
+    readonly acceptedWork: AcceptedWorkContext;
     readonly digest: string;
     readonly updatedAt: number;
 }
 type AgentRequestLedgerRecord = (AgentRequestLedgerRecordBase & {
     readonly state: 'pending-admission';
+    /** The last owner stopped before ledger admission acceptance or effect dispatch. */
+    readonly retryable?: true;
 }) | (AgentRequestLedgerRecordBase & {
     readonly state: 'admission-accepted';
+    /** Append-only admission provenance, separate from current authority. */
     readonly admissionReceipt: string;
 }) | (AgentRequestLedgerRecordBase & {
     readonly state: 'in-flight';
@@ -727,8 +1007,10 @@ type AgentRequestLedgerRecord = (AgentRequestLedgerRecordBase & {
 interface AgentRequestLedger {
     /** 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>;
+    /** Atomically create or reclaim explicitly retryable admission across all store users. */
+    prepare(key: AgentRequestKey, digest: string, acceptedWork: AcceptedWorkContext): Promise<AgentRequestLedgerPrepareResult>;
+    /** Release only a pending claim whose owner has stopped before any effect. */
+    markAdmissionRetryable(key: AgentRequestKey): Promise<void>;
     /** All transitions are compare-and-swap against the exact allowed prior state. */
     acceptAdmission(key: AgentRequestKey, admissionReceipt: string): Promise<void>;
     beginEffect(key: AgentRequestKey): Promise<void>;
@@ -739,7 +1021,7 @@ interface AgentRequestLedger {
     close?(): void | Promise<void>;
 }
 interface AgentRequestLedgerPrepareResult {
-    readonly ownership: 'created' | 'existing';
+    readonly ownership: 'created' | 'reclaimed' | 'existing';
     readonly record: AgentRequestLedgerRecord;
 }
 type AgentEffectAdmissionResult = {
@@ -954,8 +1236,21 @@ interface AgentHostEnvironmentScope extends ResolvedEnvironmentScope {
         readonly requestId: string;
     }) => Promise<readonly RuntimeFilesystemBinding[] | undefined>;
 }
+interface AgentHostSessionEnvironmentLease {
+    readonly environmentGenerationId: string;
+    readonly bindingGeneration: number;
+    readonly signal: AbortSignal;
+    acquireTrustedService(input: {
+        readonly leaseId: string;
+        readonly idleTtlMs: number;
+        readonly absoluteTtlMs: number;
+    }): Promise<RuntimeTrustedServiceLeaseV1>;
+    release(): void;
+}
 interface AgentHostEnvironmentLease {
     readonly workspace: Workspace;
+    /** Process execution paired with this exact runtime-owned workspace generation. */
+    readonly sandbox: Sandbox;
     readonly gitWorkspace: Workspace;
     readonly fileSearch: FileSearch;
     readonly filesystemBindings?: readonly RuntimeFilesystemBinding[];
@@ -978,6 +1273,8 @@ interface AgentHostDescription {
     readonly agents: readonly {
         readonly agentTypeId: string;
         readonly label: string;
+        /** Exact package-declared version, when this is a configured Agent. */
+        readonly definitionVersion?: string;
         /** Computed definition identity digest (instructions + knowledge bytes), when the spec carries one. */
         readonly definitionDigest?: string;
     }[];
@@ -1020,12 +1317,45 @@ interface CreateAgentHostOptions {
     readonly requestLedger?: AgentRequestLedger;
     /** Durable effect ledger path, independent of transcript/session storage. */
     readonly requestLedgerPath?: string;
+    /** App-host-owned durable event store, shared with channel outbound tails. */
+    readonly eventStore?: EventStreamStore;
     /** Explicit test/dev opt-in for an in-memory ledger. */
     readonly inMemoryRequestLedgerMode?: 'test' | 'development';
+    /**
+     * Built-in SQLite terminal-payload retention. Values below 24 hours are
+     * raised to 24 hours; omitted retention keeps terminal payloads indefinitely.
+     * Injected ledgers retain ownership of their own storage policy.
+     */
     readonly requestRetentionMs?: number;
     readonly effectAdmission?: AgentEffectAdmission;
     readonly shutdownGraceMs?: number;
     readonly harnessFactory?: AgentHarnessFactory;
+    /**
+     * [1082 slice B] BYOK credential-vault composition inputs. Enablement is
+     * env-driven (`BORING_CREDENTIAL_KMS_BACKEND`); when enabled the host embeds
+     * durable persistence (#1145) and the Core-owned authority verifier here.
+     * The composition is resolved exactly once, at `createAgentHost` startup:
+     * misconfigured env fails host creation with a stable `CREDENTIAL_*` error,
+     * and all runtime bindings share the single host-scope vault composition.
+     * Absent env → composition absent, behavior identical to env-key-only auth.
+     */
+    readonly credentials?: AgentHostCredentialOptionsV1;
+}
+interface WorkspaceCredentialLifecycleV1 {
+    /** Irreversibly fences and destroys credential key access for one workspace. */
+    cryptoShredWorkspace(workspaceId: string): Promise<void>;
+}
+interface AgentHostCredentialOptionsV1 {
+    /** Env-shaped record override; defaults to `process.env`. */
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    /** Durable vault persistence (#1145 Postgres in production). */
+    readonly vaultPersistence?: CredentialVaultPersistenceV2;
+    /** Core-owned authority verifier; pre-binds the credential resolver. */
+    readonly authorityVerifier?: WorkspaceCredentialAuthorityVerifierV1;
+    /** Host authentication adapter for owner-only credential HTTP routes. */
+    readonly authorizeOwnerRequest?: (request: FastifyRequest) => VerifiedWorkspaceCredentialAuthorityV1 | Promise<VerifiedWorkspaceCredentialAuthorityV1>;
+    /** Core deletion composition receives only the narrow irreversible lifecycle seam. */
+    readonly onLifecycleReady?: (lifecycle: WorkspaceCredentialLifecycleV1) => void;
 }
 interface CreatedAgentHost {
     readonly host: AgentHostHandle;
@@ -1035,7 +1365,13 @@ interface CreatedAgentHost {
         readonly authorizedScope: AuthorizedAgentScope;
         readonly intent: AuthorizedEnvironmentIntent;
     }): Promise<AgentHostEnvironmentLease>;
+    /** Trusted composition-only acquisition of the addressed session's exact Environment generation. */
+    acquireSessionEnvironment(input: {
+        readonly authorizedScope: AuthorizedAgentScope;
+        readonly ref: AgentSessionRef;
+        readonly requestId: string;
+    }): Promise<AgentHostSessionEnvironmentLease>;
     runWithWorkspaceAgent(input: AgentHostDispatcherRunInput, run: (binding: LeaseBoundWorkspaceAgent) => Promise<void>): Promise<void>;
 }
 
-export { type MeteringUsageInput as $, type AgentGatewayEffect as A, type BuiltinRuntimeModeId as B, type ConfiguredAgentHostAgentSpec as C, type AgentRequestLedgerRecord as D, type AgentFleetCompiler as E, type AgentRequestTarget as F, type RuntimeFilesystemAccessDecision as G, type AgentHostDescription as H, type AgentHostDirectProjectionOptions as I, type AgentHostDispatcherRunInput as J, type AgentHostEnvironmentLease as K, type AgentHostHandle as L, type ModeContext as M, DEFAULT_AGENT_TYPE_ID as N, type MeteringErrorLogger as O, type ProvisionWorkspaceRuntimeOptions as P, type MeteringReleaseInput as Q, type RuntimeModeAdapter as R, type MeteringReleaseReason as S, type MeteringReservationResult as T, type MeteringReserveInput as U, type MeteringRunKind as V, type WorkspaceProvisioningResult as W, type MeteringRunScope as X, type MeteringRunStatus as Y, type MeteringSettleInput as Z, type MeteringUsage as _, type PiPackageSource as a, PI_PACKAGE_RESOURCE_FILTERS as a0, type PiExtensionFactory as a1, type PluginSkillSource as a2, type ResolvedEnvironmentScope as a3, type RuntimeFilesystemBindingOperations as a4, type RuntimeNodePackageSpec as a5, type RuntimeProvisioningContribution as a6, type RuntimePythonSpec as a7, type RuntimeTemplateContribution as a8, type WorkspaceProvisioningExecResult as a9, compactPiPackages as aa, mergePiPackageSources as ab, normalizeMeteringUsage as ac, piPackageSourceKey as ad, type RuntimeModeId as b, type AgentRuntimeHostOperations as c, type RuntimeBashStrategy as d, type RuntimeFilesystemStrategy as e, type WorkspaceProvisioningAdapter as f, type AgentInstructionSource as g, type AgentInstructionFileRef as h, type AgentHostAgentSpec as i, type RuntimeBundle as j, type PiHarnessOptions as k, type AgentMeteringSink as l, type RuntimeFilesystemBinding as m, type CreatedAgentHost as n, type ResolvedPiHarnessOptions as o, ReadyStatusTracker 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 ResolvedAgentRuntimeScope as w, type AgentRequestKey as x, type AgentRequestLedgerPrepareResult as y, type AgentRequestFailure as z };
+export { type MeteringReleaseInput as $, type AgentGatewayEffect as A, type BuiltinRuntimeModeId as B, type CredentialVaultPersistenceV2 as C, type AgentHostEnvironmentScope as D, type EventStreamStore as E, type ResolvedAgentRuntimeScope as F, type AgentRequestKey as G, type AcceptedWorkContext as H, type AgentRequestLedgerPrepareResult as I, type AgentRequestFailure as J, type AgentRequestLedgerRecord as K, type AgentFleetCompiler as L, type ModeContext as M, type AgentRequestTarget as N, type RuntimeFilesystemAccessDecision as O, type ProvisionWorkspaceRuntimeOptions as P, type AgentHostDescription as Q, type RuntimeModeAdapter as R, type StoredCredentialRecordV1 as S, type AgentHostDirectProjectionOptions as T, type AgentHostDispatcherRunInput as U, type AgentHostEnvironmentLease as V, type WorkspaceProvisioningResult as W, type AgentHostHandle as X, type CredentialVaultPersistenceV1 as Y, DEFAULT_AGENT_TYPE_ID as Z, type MeteringErrorLogger as _, type PiPackageSource as a, type MeteringReleaseReason as a0, type MeteringReservationResult as a1, type MeteringReserveInput as a2, type MeteringRunKind as a3, type MeteringRunScope as a4, type MeteringRunStatus as a5, type MeteringSettleInput as a6, type MeteringUsage as a7, type MeteringUsageInput as a8, PI_PACKAGE_RESOURCE_FILTERS as a9, type PiExtensionFactory as aa, type PluginSkillSource as ab, type ResolvedEnvironmentScope as ac, type RuntimeFilesystemBindingOperations as ad, type RuntimeNodePackageSpec as ae, type RuntimeProvisioningContribution as af, type RuntimePythonSpec as ag, type RuntimeTemplateContribution as ah, type WorkspaceCredentialLifecycleV1 as ai, type WorkspaceProvisioningExecResult as aj, compactPiPackages as ak, mergePiPackageSources as al, normalizeMeteringUsage as am, piPackageSourceKey as an, type CredentialMaterialKindV1 as b, type WorkspaceCredentialLockOptionsV1 as c, type StoredCredentialMetadataV1 as d, type RuntimeModeId as e, type AgentRuntimeHostOperations as f, type RuntimeBashStrategy as g, type RuntimeFilesystemStrategy as h, type WorkspaceProvisioningAdapter as i, type AgentInstructionSource as j, type ConfiguredAgentHostAgentSpec as k, type AgentInstructionFileRef as l, type AgentHostAgentSpec as m, type RuntimeBundle as n, type PiHarnessOptions as o, type AgentMeteringSink as p, type AgentHostCredentialOptionsV1 as q, type RuntimeFilesystemBinding as r, type CreatedAgentHost as s, type ResolvedPiHarnessOptions as t, ReadyStatusTracker as u, type CreateAgentHostOptions as v, type CompiledAgentHostAgentSpec as w, type AgentRequestLedger as x, type AgentEffectAdmission as y, type AuthorizedEnvironmentIntent as z };

package/docs/AGENT_GATEWAY_V0.md

@@ -75,7 +75,9 @@ Note `listAgents` takes `ListAgentsInput`, not a bare `AuthorizedAgentScope`.
 
 ### Output DTOs
 
-`AgentSummary` (`agentTypeId`, `label`, `description?`, `definition?{version,digest}`),
+`AgentSummary` (`agentTypeId`, `label`, `description?`, `definition?{version,digest?}`),
+where `version` is the exact package declaration and `digest`, when available,
+is the computed compiled-definition identity (not a re-hash of the response DTO),
 `AgentSessionSummary` (`ref`, `title`, `status`, `createdAt`, `updatedAt`),
 `AgentSessionPage` (`sessions`, `nextCursor?`), and the receipts
 (`CommandReceipt`, `AgentSendReceipt`, `QueueClearReceipt`, `StopReceipt`) are
@@ -179,11 +181,29 @@ operations.
 
 The Gateway request ledger is the only idempotency authority. A backend method
 may be invoked again after a crash only through a ledger-admitted request; the
-backend itself promises no deduplication. P1-B substitutes the adapter-private
+backend itself promises no deduplication. A runtime load failure before the
+effect begins records a retryable state, so the same request key and payload can
+atomically reclaim admission after recovery; completed, rejected, in-flight, and
+outcome-unknown records retain their normal replay behavior. P1-B substitutes the adapter-private
 replay source below `HarnessPiChatService`, not this interface. Later operations
 may extend the interface only in their named slices (`resumePausedToolCall` in
 A3b and `markTurnInterrupted` in A4); neither is part of the current seam.
 
+An explicit retryable admission result, or a returned prompt-state guard denial,
+releases its pending claim before any effect. The ledger persists
+`pending-admission` with `retryable: true`; `prepare` must atomically consume
+that marker before returning `ownership: 'reclaimed'`. The original key and
+payload digest stay binding, and overlapping requests still receive
+`AGENT_REQUEST_IN_PROGRESS`. This applies to both ordinary and strict-idle
+prompt guards, with their existing idle/error admission policies.
+
+Custom `AgentRequestLedger` implementations must implement
+`markAdmissionRetryable` and atomic reclaim, and refuse `acceptAdmission` until
+the released claim has been reclaimed. A thrown admission/guard error does not
+release ownership. Reopening a durable ledger permits only an explicitly marked
+retry; unmarked pending, admission-accepted, in-flight and outcome-unknown rows
+are never automatically re-executed. This is not general crash reconciliation.
+
 CI pins the boundary in three directions: Agent Host production code cannot
 import a Pi runtime, only `harnessBackend/**` can reference the concrete Pi chat
 service, and Workspace/Core/CLI/playground consumers cannot name the private