@hachej/boring-agent 0.1.110 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (156) hide show
  1. package/LICENSE +1 -1
  2. package/README.md +262 -51
  3. package/dist/agents.d.ts +75 -0
  4. package/dist/agents.js +91 -0
  5. package/dist/approval.d.ts +71 -0
  6. package/dist/approval.js +126 -0
  7. package/dist/artifacts.d.ts +53 -0
  8. package/dist/artifacts.js +129 -0
  9. package/dist/ask-user.d.ts +40 -0
  10. package/dist/ask-user.js +134 -0
  11. package/dist/attachment.d.ts +5 -0
  12. package/dist/attachment.js +4 -0
  13. package/dist/browser-task.d.ts +32 -0
  14. package/dist/browser-task.js +119 -0
  15. package/dist/chat-transport.d.ts +80 -0
  16. package/dist/chat-transport.js +306 -0
  17. package/dist/contracts.d.ts +40 -0
  18. package/dist/contracts.js +1 -0
  19. package/dist/conversations.d.ts +136 -0
  20. package/dist/conversations.js +366 -0
  21. package/dist/definitions.d.ts +37 -0
  22. package/dist/definitions.js +99 -0
  23. package/dist/delivery-input.d.ts +35 -0
  24. package/dist/delivery-input.js +56 -0
  25. package/dist/delivery.d.ts +33 -0
  26. package/dist/delivery.js +154 -0
  27. package/dist/durable-wait.d.ts +23 -0
  28. package/dist/durable-wait.js +79 -0
  29. package/dist/file-convert.d.ts +46 -0
  30. package/dist/file-convert.js +159 -0
  31. package/dist/file-guard.d.ts +50 -0
  32. package/dist/file-guard.js +171 -0
  33. package/dist/file-types.d.ts +17 -0
  34. package/dist/file-types.js +95 -0
  35. package/dist/gateway-provider.d.ts +24 -0
  36. package/dist/gateway-provider.js +42 -0
  37. package/dist/git.d.ts +34 -0
  38. package/dist/git.js +79 -0
  39. package/dist/harness-pool.d.ts +38 -0
  40. package/dist/harness-pool.js +134 -0
  41. package/dist/index.d.ts +4 -0
  42. package/dist/index.js +1 -0
  43. package/dist/json-schema-tool.d.ts +25 -0
  44. package/dist/json-schema-tool.js +19 -0
  45. package/dist/memory/optchat-core.d.ts +118 -0
  46. package/dist/memory/optchat-core.js +317 -0
  47. package/dist/memory/optchat.d.ts +156 -0
  48. package/dist/memory/optchat.js +432 -0
  49. package/dist/mentions.d.ts +56 -0
  50. package/dist/mentions.js +140 -0
  51. package/dist/metering.d.ts +183 -0
  52. package/dist/metering.js +443 -0
  53. package/dist/model-gateway.d.ts +86 -0
  54. package/dist/model-gateway.js +241 -0
  55. package/dist/native-version.d.ts +9 -0
  56. package/dist/native-version.js +7 -0
  57. package/dist/native.d.ts +4 -0
  58. package/dist/native.js +1 -0
  59. package/dist/presentation.d.ts +17 -0
  60. package/dist/presentation.js +39 -0
  61. package/dist/projection-format.d.ts +68 -0
  62. package/dist/projection-format.js +118 -0
  63. package/dist/projection-window.d.ts +9 -0
  64. package/dist/projection-window.js +93 -0
  65. package/dist/projection.d.ts +22 -0
  66. package/dist/projection.js +153 -0
  67. package/dist/question-response.d.ts +20 -0
  68. package/dist/question-response.js +75 -0
  69. package/dist/questions.d.ts +74 -0
  70. package/dist/questions.js +199 -0
  71. package/dist/self-evolving.d.ts +55 -0
  72. package/dist/self-evolving.js +239 -0
  73. package/dist/skills.d.ts +15 -0
  74. package/dist/skills.js +51 -0
  75. package/dist/tool-evidence.d.ts +14 -0
  76. package/dist/tool-evidence.js +54 -0
  77. package/dist/validation.d.ts +38 -0
  78. package/dist/validation.js +68 -0
  79. package/dist/workspaces.d.ts +107 -0
  80. package/dist/workspaces.js +212 -0
  81. package/package.json +145 -150
  82. package/dist/DebugDrawer-JNA43SVR.js +0 -8
  83. package/dist/admin-DORVQfLn.d.ts +0 -340
  84. package/dist/chunk-2BGLZZ7T.js +0 -10
  85. package/dist/chunk-42D6KAQV.js +0 -2882
  86. package/dist/chunk-4XOW57KJ.js +0 -343
  87. package/dist/chunk-72KT6VWV.js +0 -1338
  88. package/dist/chunk-7XAOVFSN.js +0 -28
  89. package/dist/chunk-KJIEMSQP.js +0 -198
  90. package/dist/chunk-KN72XWP7.js +0 -394
  91. package/dist/chunk-N6THTH7P.js +0 -110
  92. package/dist/chunk-V3H5A3BR.js +0 -22501
  93. package/dist/chunk-YGRQ4Q5P.js +0 -20
  94. package/dist/chunk-YTUZFKB3.js +0 -78
  95. package/dist/core/index.d.ts +0 -28
  96. package/dist/core/index.js +0 -617
  97. package/dist/createHarness-DOLOHA62.js +0 -18
  98. package/dist/eval/index.d.ts +0 -247
  99. package/dist/eval/index.js +0 -541
  100. package/dist/file-search-BUgMSKZE.d.ts +0 -289
  101. package/dist/front/artifacts.d.ts +0 -34
  102. package/dist/front/artifacts.js +0 -21
  103. package/dist/front/index.d.ts +0 -1082
  104. package/dist/front/index.js +0 -12912
  105. package/dist/front/styles.css +0 -5380
  106. package/dist/harness-qHlMJhZo.d.ts +0 -276
  107. package/dist/middleware-CaAEXpi5.d.ts +0 -115
  108. package/dist/piChatEvent-DpE0lIb9.d.ts +0 -450
  109. package/dist/piChatSessionService-CBct-hmz.d.ts +0 -86
  110. package/dist/sandbox-BMhut3kh.d.ts +0 -317
  111. package/dist/server/agent-host/testing/compositionRouteProof.d.ts +0 -8
  112. package/dist/server/agent-host/testing/compositionRouteProof.js +0 -78
  113. package/dist/server/agent-host/testing/gatewayConformance.d.ts +0 -43
  114. package/dist/server/agent-host/testing/gatewayConformance.js +0 -605
  115. package/dist/server/index.d.ts +0 -2278
  116. package/dist/server/index.js +0 -274
  117. package/dist/server/pi-session-readability.d.ts +0 -12
  118. package/dist/server/pi-session-readability.js +0 -23
  119. package/dist/server/worker/index.d.ts +0 -68
  120. package/dist/server/worker/index.js +0 -377
  121. package/dist/share-entry-CxS6UJ_L.d.ts +0 -330
  122. package/dist/shared/index.d.ts +0 -2111
  123. package/dist/shared/index.js +0 -262
  124. package/dist/types-DcWoQMn8.d.ts +0 -1377
  125. package/docs/ACCESSIBILITY.md +0 -52
  126. package/docs/AGENT_GATEWAY_V0.md +0 -212
  127. package/docs/AGENT_PACKAGES.md +0 -90
  128. package/docs/API.md +0 -123
  129. package/docs/AUTHORING.md +0 -68
  130. package/docs/CSP.md +0 -41
  131. package/docs/ERROR_CODES.md +0 -229
  132. package/docs/KNOWN_LIMITATIONS.md +0 -100
  133. package/docs/MIGRATION.md +0 -50
  134. package/docs/PERFORMANCE.md +0 -68
  135. package/docs/PLUGINS.md +0 -138
  136. package/docs/README.md +0 -98
  137. package/docs/RISKS-MULTI-TAB.md +0 -46
  138. package/docs/SESSION_IDENTITY.md +0 -91
  139. package/docs/STYLING.md +0 -73
  140. package/docs/UI-SHADCN.md +0 -56
  141. package/docs/VERCEL_COSTS.md +0 -103
  142. package/docs/plans/archive/AGENT_EVAL_FRAMEWORK.md +0 -466
  143. package/docs/plans/archive/agent-package-spec.md +0 -1777
  144. package/docs/plans/archive/harness-followup-capabilities.md +0 -440
  145. package/docs/plans/archive/harness-tool-ui-capabilities.md +0 -144
  146. package/docs/plans/archive/pi-followup-history-projection.md +0 -229
  147. package/docs/plans/archive/pi-tools-migration.md +0 -1061
  148. package/docs/plans/archive/reviews/pi-followup-history-codex-review.md +0 -11
  149. package/docs/plans/archive/reviews/pi-followup-history-gpt-review.md +0 -64
  150. package/docs/plans/archive/reviews/pi-followup-history-opus-review.md +0 -43
  151. package/docs/plans/archive/reviews/pi-followup-history-xai-review.md +0 -43
  152. package/docs/plans/archive/vercel-base-snapshot-template-plan.md +0 -527
  153. package/docs/plans/archive/vercel-persistent-sandbox-adapter.md +0 -553
  154. package/docs/runtime-provisioning.md +0 -157
  155. package/docs/runtime.md +0 -296
  156. package/docs/tools.md +0 -102
@@ -1,2278 +0,0 @@
1
- import { P as ProvisionWorkspaceRuntimeOptions, W as WorkspaceProvisioningResult, a as PiPackageSource, C as CredentialVaultPersistenceV2, b as CredentialMaterialKindV1, c as WorkspaceCredentialLockOptionsV1, S as StoredCredentialRecordV1, d as StoredCredentialMetadataV1, R as RuntimeModeAdapter, e as RuntimeModeId, B as BuiltinRuntimeModeId, f as AgentRuntimeHostOperations, g as RuntimeBashStrategy, h as RuntimeFilesystemStrategy, M as ModeContext, i as WorkspaceProvisioningAdapter, j as AgentInstructionSource, k as ConfiguredAgentHostAgentSpec, l as AgentInstructionFileRef, m as AgentHostAgentSpec, n as RuntimeBundle, o as PiHarnessOptions, p as AgentMeteringSink, q as AgentHostCredentialOptionsV1, r as RuntimeFilesystemBinding, E as EventStreamStore, s as CreatedAgentHost, t as ResolvedPiHarnessOptions, u as ReadyStatusTracker, v as CreateAgentHostOptions, w as CompiledAgentHostAgentSpec, x as AgentRequestLedger, y as AgentEffectAdmission, z as AuthorizedEnvironmentIntent, D as AgentHostEnvironmentScope, F as ResolvedAgentRuntimeScope, G as AgentRequestKey, H as AcceptedWorkContext, I as AgentRequestLedgerPrepareResult, J as AgentRequestFailure, K as AgentRequestLedgerRecord, L as AgentFleetCompiler, N as AgentRequestTarget, O as RuntimeFilesystemAccessDecision } from '../types-DcWoQMn8.js';
2
- export { A as AgentGatewayEffect, Q as AgentHostDescription, T as AgentHostDirectProjectionOptions, U as AgentHostDispatcherRunInput, V as AgentHostEnvironmentLease, X as AgentHostHandle, Y as CredentialVaultPersistenceV1, Z as DEFAULT_AGENT_TYPE_ID, _ as MeteringErrorLogger, $ as MeteringReleaseInput, a0 as MeteringReleaseReason, a1 as MeteringReservationResult, a2 as MeteringReserveInput, a3 as MeteringRunKind, a4 as MeteringRunScope, a5 as MeteringRunStatus, a6 as MeteringSettleInput, a7 as MeteringUsage, a8 as MeteringUsageInput, a9 as PI_PACKAGE_RESOURCE_FILTERS, aa as PiExtensionFactory, ab as PluginSkillSource, ac as ResolvedEnvironmentScope, ad as RuntimeFilesystemBindingOperations, ae as RuntimeNodePackageSpec, af as RuntimeProvisioningContribution, ag as RuntimePythonSpec, ah as RuntimeTemplateContribution, ai as WorkspaceCredentialLifecycleV1, aj as WorkspaceProvisioningExecResult, ak as compactPiPackages, al as mergePiPackageSources, am as normalizeMeteringUsage, an as piPackageSourceKey } from '../types-DcWoQMn8.js';
3
- import { d as ExecOptions, a as ExecResult, W as WorkspaceChangeEvent, b as Workspace, c as Sandbox } from '../sandbox-BMhut3kh.js';
4
- export { h as RuntimeFilesystemCapability } from '../sandbox-BMhut3kh.js';
5
- import { b as RemoteWorkerHealthResponse, R as RemoteWorkerWorkspaceOp, a as RemoteWorkerWorkspaceResult, c as RemoteWorkerExecRequest } from '../middleware-CaAEXpi5.js';
6
- export { d as REMOTE_WORKER_EXCLUSIVE_BINARY_CREATE_CAPABILITY, e as REMOTE_WORKER_PROVIDER, f as REMOTE_WORKER_RUNTIME_CWD, g as RemoteWorkerErrorPayload, h as RemoteWorkerExecResponse, i as RemoteWorkerFsEventEnvelope, W as WORKER_INTERNAL_TOKEN_HEADER, j as WORKER_REQUEST_ID_HEADER, k as WORKER_WORKSPACE_ID_HEADER, l as createAgentAuthMiddleware } from '../middleware-CaAEXpi5.js';
7
- import { SandboxProviderV1, WorkspaceSandboxPairV1 } from '@hachej/boring-sandbox/shared';
8
- import { BwrapSandboxProviderOptions } from '@hachej/boring-sandbox/providers/bwrap';
9
- import { r as ResolvedCredentialMaterialV1, k as CredentialConsumerBindingRegistryV1, W as WorkspaceCredentialResolverV1, t as SandboxHandleStore, C as CompiledAgentBundle, a as Sha256Digest, g as AgentDeployment, z as ShareEntryStore, P as ProviderCredentialRefV1, R as ResolvedCredentialLeaseV1 } from '../share-entry-CxS6UJ_L.js';
10
- import { H as ErrorCode, k as SessionCtx, O as OriginChannel, a as SessionListOptions, b as SessionSummary, U as SessionCreateInit, c as PiChatSnapshot, d as PiChatEvent, e as PromptReceipt, F as FollowUpPayload, f as FollowUpReceipt, Q as QueueClearPayload, g as QueueClearReceipt, I as InterruptPayload, h as CommandReceipt, i as StopPayload, j as StopReceipt, S as SessionStore } from '../piChatEvent-DpE0lIb9.js';
11
- import { B as CredentialLifecycleStateV1, P as JsonValue, A as AgentGateway, a as AuthorizedAgentScope, b as AgentSessionRef, c as AgentSessionActivity, V as VerifiedAgentScopeClaim, g as AgentAccessOperation, f as AgentAccessDecision, k as AgentGatewayErrorDTO, r as AgentSessionSummary, q as AgentSessionStateSnapshot, n as AgentSessionConnection } from '../admin-DORVQfLn.js';
12
- export { T as ResolveAgentAccess, U as ResolveAgentAccessInput } from '../admin-DORVQfLn.js';
13
- import { d as AgentActor, j as AgentEvent, w as TelemetrySink, s as AgentTool, D as AgentHarnessFactory, A as AgentHarness } from '../harness-qHlMJhZo.js';
14
- export { u as AgentConfig, E as AgentHarnessFactoryInput } from '../harness-qHlMJhZo.js';
15
- import { IncomingMessage, ServerResponse } from 'node:http';
16
- import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
17
- import { FastifyRequest, FastifyInstance, FastifyPluginCallback } from 'fastify';
18
- import { i as PiSessionRequestContext, j as AgentPromptPayload, k as PiChatAttachmentResult } from '../piChatSessionService-CBct-hmz.js';
19
- import { P as ProviderId, I as WorkspaceKekProviderV1, a as CredentialFieldId, B as WorkspaceCredentialAuthorityVerifierV1, b as ProviderRegistryV1, t as WorkspaceAgentDirectRunInput, s as WorkspaceAgentDirectRunCallback, w as WorkspaceAgentDispatcherContext, v as WorkspaceAgentDispatcher, z as WorkspaceAgentGatewayBinding, C as CredentialConsumerBindingId, N as AgentInvocationFundingPolicyV1, A as AuthorizedWorkspaceCredentialScopeV1 } from '../file-search-BUgMSKZE.js';
20
- export { L as LeaseBoundWorkspaceAgent } from '../file-search-BUgMSKZE.js';
21
- import { CredentialStore, AuthPrompt } from '@earendil-works/pi-ai';
22
- import { SettingsManager, ModelRuntime } from '@mariozechner/pi-coding-agent';
23
- import postgres from 'postgres';
24
- import '@hachej/boring-bash/agent';
25
- import '@hachej/boring-sandbox/providers/node-workspace';
26
- import 'zod';
27
-
28
- interface SqlResult {
29
- toArray(): Array<Record<string, unknown>>;
30
- }
31
- interface SqlStorage {
32
- exec(query: string, ...bindings: unknown[]): SqlResult;
33
- }
34
- /**
35
- * `deferred` (SQLite's plain `BEGIN`) postpones acquiring any lock until the
36
- * first read or write inside the transaction. That is fine for read-only
37
- * transactions, but a transaction that reads THEN writes (e.g. a
38
- * check-then-insert) starts under a read lock and must upgrade to a write
39
- * lock mid-transaction — and SQLite refuses that upgrade with SQLITE_BUSY
40
- * immediately if another connection holds the write lock, WITHOUT honoring
41
- * `busy_timeout` (the busy handler only runs for the initial lock
42
- * acquisition, not a lock *upgrade*). `immediate` (`BEGIN IMMEDIATE`)
43
- * acquires the write lock up front, so `busy_timeout` applies normally and
44
- * a concurrent writer simply waits instead of erroring. Use `immediate` for
45
- * any transaction that writes — especially read-then-write — and reserve
46
- * `deferred` for genuinely read-only transactions.
47
- */
48
- type SqlTransactionMode = 'deferred' | 'immediate';
49
- type RunTransaction = <T>(fn: () => T, mode?: SqlTransactionMode) => T;
50
-
51
- declare function provisionWorkspaceRuntime(opts: ProvisionWorkspaceRuntimeOptions): Promise<WorkspaceProvisioningResult>;
52
-
53
- declare function createResourceSettingsManager(cwd: string, agentDir: string, piPackages: PiPackageSource[], options?: {
54
- includePackage?: (source: PiPackageSource) => boolean;
55
- includeConfiguredPackages?: boolean;
56
- }): SettingsManager;
57
-
58
- declare function createInMemoryCredentialVaultPersistenceV1(): CredentialVaultPersistenceV2;
59
-
60
- interface PostgresCredentialVaultPersistenceOptionsV1 {
61
- /** Independently pooled connection used only to evict an uncertain lock holder. */
62
- readonly evictionSql: postgres.Sql;
63
- /** Default bound for advisory-lock acquisition. */
64
- readonly lockAcquireTimeoutMs?: number;
65
- /** Delay between non-blocking advisory-lock attempts. */
66
- readonly lockPollIntervalMs?: number;
67
- /** Bound for confirming advisory unlock before evicting the connection. */
68
- readonly lockReleaseTimeoutMs?: number;
69
- }
70
- type Sql = postgres.Sql | postgres.TransactionSql;
71
- declare function createPostgresCredentialVaultPersistenceV1(sql: Sql, options: PostgresCredentialVaultPersistenceOptionsV1): CredentialVaultPersistenceV2;
72
-
73
- /** Deployment-owned schema registration for durable credential vault storage. */
74
- declare function runCredentialVaultPostgresMigrationsV1(sql: postgres.Sql): Promise<void>;
75
-
76
- interface WorkspaceCredentialVersionStateV1 {
77
- readonly counter: number;
78
- /** Monotonic irreversible fence; any positive value means the workspace was shredded. */
79
- readonly cryptoShredGeneration: number;
80
- /** Monotonic workspace-wide fence for replayed wrapped DEKs and records. */
81
- readonly dekGeneration: number;
82
- /** Authenticated idempotency receipts for completed DEK rotations. */
83
- readonly dekRotationReceipts: Readonly<Record<string, number>>;
84
- readonly credentialVersions: Readonly<Record<string, number>>;
85
- readonly credentialMaterialKinds: Readonly<Record<string, CredentialMaterialKindV1>>;
86
- readonly credentialFieldIds: Readonly<Record<string, readonly string[]>>;
87
- readonly credentialLifecycleStates: Readonly<Record<string, CredentialLifecycleStateV1>>;
88
- readonly credentialTypes: Readonly<Record<string, string>>;
89
- }
90
- interface PendingCredentialVersionMutationV1 {
91
- readonly operationId: string;
92
- readonly providerId: ProviderId;
93
- readonly expectedStateDigest: string;
94
- readonly nextStateDigest: string;
95
- readonly nextCredentialVersion: number;
96
- readonly nextCredentialMaterialKind: CredentialMaterialKindV1;
97
- readonly nextCredentialFieldIds: readonly string[];
98
- readonly nextCredentialLifecycleState: CredentialLifecycleStateV1;
99
- readonly nextCredentialType: string;
100
- readonly nextDekGeneration: number;
101
- }
102
- interface CredentialVersionMutationStateV1 {
103
- readonly nextCredentialVersion: number;
104
- readonly nextCredentialMaterialKind: CredentialMaterialKindV1;
105
- readonly nextCredentialFieldIds: readonly string[];
106
- readonly nextCredentialLifecycleState: CredentialLifecycleStateV1;
107
- readonly nextCredentialType: string;
108
- readonly nextDekGeneration: number;
109
- }
110
- interface CredentialVersionMutationResultV1<T> {
111
- readonly nextCredentialVersion: number;
112
- readonly nextCredentialMaterialKind: CredentialMaterialKindV1;
113
- readonly nextCredentialFieldIds: readonly string[];
114
- readonly nextCredentialLifecycleState: CredentialLifecycleStateV1;
115
- readonly nextCredentialType: string;
116
- readonly nextDekGeneration: number;
117
- readonly result: T;
118
- }
119
- /**
120
- * V2 write-ahead mutation contract. The anchor seals both authenticated digests
121
- * before invoking `commit`, then finalizes only after `commit` succeeds.
122
- */
123
- type CredentialVersionMutationResultV2<T> = CredentialVersionMutationStateV1 & {
124
- readonly expectedStateDigest: string;
125
- readonly nextStateDigest: string;
126
- readonly commit: () => Promise<T>;
127
- };
128
- interface DekGenerationMutationResultV1<T> {
129
- readonly nextDekGeneration: number;
130
- readonly nextDekRotationOperationId: string;
131
- readonly result: T;
132
- }
133
- interface CredentialLifecycleMutationResultV1<T> {
134
- readonly nextCredentialLifecycleState: CredentialLifecycleStateV1;
135
- readonly result: T;
136
- }
137
- interface CryptoShredMutationResultV1<T> {
138
- readonly result: T;
139
- }
140
- interface CredentialVersionAnchorReadOptionsV1 {
141
- /**
142
- * A provider-list probe may treat a never-provisioned anchor file as empty
143
- * only when persistence has no credential metadata. Existing malformed or
144
- * unauthenticated anchor files still fail closed.
145
- */
146
- readonly allowUnprovisioned?: boolean;
147
- }
148
- type CredentialVersionAnchorReaderV1 = (options?: CredentialVersionAnchorReadOptionsV1) => Promise<WorkspaceCredentialVersionStateV1 | undefined>;
149
- interface WorkspaceCredentialVersionAnchorV1 {
150
- read(workspaceId: string, options?: CredentialVersionAnchorReadOptionsV1): Promise<WorkspaceCredentialVersionStateV1 | undefined>;
151
- /** Serializes a persistence inspection with anchor mutations. */
152
- withReadLock<T>(workspaceId: string, inspect: (readLocked: CredentialVersionAnchorReaderV1) => Promise<T>): Promise<T>;
153
- /**
154
- * Holds the external workspace mutation lock through the supplied DB CAS.
155
- * If the DB commit succeeds but advancing this external anchor fails, the
156
- * mismatch deliberately fail-stops; accepting DB-ahead state would turn an
157
- * attacker replay into an automatic rollback. S1 prefers security over
158
- * availability here and does not claim cross-store crash atomicity.
159
- */
160
- withMutation<T>(workspaceId: string, providerId: ProviderId, mutate: (current: WorkspaceCredentialVersionStateV1 | undefined) => Promise<CredentialVersionMutationResultV1<T>>): Promise<T>;
161
- /** Authenticates a lifecycle-only state transition without minting a version. */
162
- withLifecycleMutation<T>(workspaceId: string, providerId: ProviderId, mutate: (current: WorkspaceCredentialVersionStateV1 | undefined) => Promise<CredentialLifecycleMutationResultV1<T>>): Promise<T>;
163
- /**
164
- * Irreversibly advances the authenticated external shred fence before
165
- * destructive persistence finalization. Repeated calls retain the fence and
166
- * re-run finalization so cleanup is recoverable and idempotent.
167
- */
168
- withCryptoShredMutation<T>(workspaceId: string, mutate: (current: WorkspaceCredentialVersionStateV1) => Promise<CryptoShredMutationResultV1<T>>): Promise<T>;
169
- /** Advances the authenticated workspace DEK fence exactly one generation. */
170
- withDekGenerationMutation<T>(workspaceId: string, mutate: (current: WorkspaceCredentialVersionStateV1 | undefined) => Promise<DekGenerationMutationResultV1<T>>): Promise<T>;
171
- }
172
- /** Recovery-capable authority required by the durable vault backend. */
173
- interface WorkspaceCredentialVersionAnchorV2 extends WorkspaceCredentialVersionAnchorV1 {
174
- readonly contractVersion: 'boring.workspace-credential-version-anchor.v2';
175
- readPendingMutation(workspaceId: string, options?: CredentialVersionAnchorReadOptionsV1): Promise<PendingCredentialVersionMutationV1 | undefined>;
176
- recoverPendingMutation(workspaceId: string, durableStateDigest: string): Promise<void>;
177
- /**
178
- * Holds the external workspace mutation lock through a write-ahead,
179
- * KEK-authenticated intent, the supplied DB CAS, and anchor finalization.
180
- * This is recoverable deferred commit, not cross-store atomicity.
181
- */
182
- withRecoverableMutation<T>(workspaceId: string, providerId: ProviderId, mutate: (current: WorkspaceCredentialVersionStateV1 | undefined) => Promise<CredentialVersionMutationResultV2<T>>): Promise<T>;
183
- }
184
- /** Test/development anchor. Production local-KEK composition uses the sealed file adapter. */
185
- declare function createInMemoryCredentialVersionAnchorV1(): WorkspaceCredentialVersionAnchorV2;
186
- interface LocalCredentialVersionAnchorOptionsV1 {
187
- readonly anchorFilePath: string;
188
- readonly loadKek: () => Promise<Uint8Array>;
189
- }
190
- /** Explicit one-time provisioning; refuses to replace an existing anchor. */
191
- declare function initializeLocalFileCredentialVersionAnchorV1(options: LocalCredentialVersionAnchorOptionsV1): Promise<void>;
192
- /**
193
- * Local-KEK rollback anchor. The pre-provisioned file lives on the
194
- * operator-controlled durable mount beside the KEK, never in Postgres or a
195
- * workspace. One counter advances per workspace; authenticated provider
196
- * context is necessary because unchanged providers legitimately trail it.
197
- *
198
- * S1 rejects a replayed DB current-version pointer. It only narrows exposure:
199
- * S2 makes exfiltrated old ciphertext cryptographically dead by destroying the
200
- * superseded DEK generation.
201
- */
202
- declare function createLocalFileCredentialVersionAnchorV1(options: LocalCredentialVersionAnchorOptionsV1): WorkspaceCredentialVersionAnchorV2;
203
-
204
- /**
205
- * Convenience composition for self-host deployments. Returns `undefined` when
206
- * the local-KEK backend was not explicitly selected; the caller must then fail
207
- * closed rather than substitute a default.
208
- */
209
- declare function createLocalKekWorkspaceKekProviderFromEnvV1(env: Readonly<Record<string, string | undefined>>): WorkspaceKekProviderV1 | undefined;
210
- declare function createLocalCredentialVersionAnchorFromEnvV1(env: Readonly<Record<string, string | undefined>>): WorkspaceCredentialVersionAnchorV2 | undefined;
211
-
212
- interface CredentialStoreBackendV1 {
213
- read(workspaceId: string, providerId: ProviderId, allowedFieldIds: readonly CredentialFieldId[]): Promise<ResolvedCredentialMaterialV1 & {
214
- credentialVersion: number;
215
- }>;
216
- }
217
- interface HostSideCredentialResolverOptionsV1 {
218
- readonly authorityVerifier: WorkspaceCredentialAuthorityVerifierV1;
219
- readonly bindingRegistry: CredentialConsumerBindingRegistryV1;
220
- readonly providerRegistry: ProviderRegistryV1;
221
- /**
222
- * Storage boundary only. Vault/KmsBackend composition is deferred to bead
223
- * 16f.2 and will implement this interface without changing the resolver.
224
- */
225
- readonly backend: CredentialStoreBackendV1;
226
- }
227
- interface InMemoryCredentialBackendEntryV1 {
228
- readonly workspaceId: string;
229
- readonly providerId: ProviderId;
230
- readonly material: ResolvedCredentialMaterialV1;
231
- readonly credentialVersion: number;
232
- }
233
- declare function createHostSideCredentialResolverV1(options: HostSideCredentialResolverOptionsV1): WorkspaceCredentialResolverV1;
234
- declare function createInMemoryCredentialBackendV1(entries: readonly InMemoryCredentialBackendEntryV1[]): CredentialStoreBackendV1;
235
-
236
- /**
237
- * Composes a `WorkspaceKekProviderV1` (KmsBackend) with AAD-bound AES-256-GCM
238
- * field crypto and an injectable persistence port into the
239
- * `CredentialStoreBackendV1` that `createHostSideCredentialResolverV1` already
240
- * consumes. The resolver contract is unchanged.
241
- *
242
- * Fail-closed rules: an unready backend, an unknown record, a wrong/absent
243
- * KEK, or any tampered ciphertext/nonce/tag/AAD component throws a stable
244
- * `CredentialResolutionError`. Nothing here ever returns "absent" in place of
245
- * an authentication failure, and nothing ever falls back to another backend or
246
- * to plaintext. Plaintext DEKs and field values are overwritten in `finally` on
247
- * a best-effort basis (Node/V8 cannot guarantee erasure).
248
- */
249
- interface VaultCredentialStoreOptionsV1$1 {
250
- readonly kmsBackend: WorkspaceKekProviderV1;
251
- readonly persistence: CredentialVaultPersistenceV2;
252
- readonly versionAnchor: WorkspaceCredentialVersionAnchorV2;
253
- }
254
- interface WriteCredentialFieldsInputV1 {
255
- readonly workspaceId: string;
256
- readonly providerId: ProviderId;
257
- readonly credentialId?: string;
258
- readonly fields: ReadonlyMap<CredentialFieldId, Uint8Array>;
259
- readonly metadata?: Readonly<{
260
- displayLabel?: string;
261
- credentialType?: string;
262
- maskedLastFourSuffix?: string;
263
- }>;
264
- }
265
- interface VaultCredentialStoreBackendV1 extends CredentialStoreBackendV1 {
266
- read(workspaceId: string, providerId: ProviderId, allowedFieldIds: readonly CredentialFieldId[], options?: WorkspaceCredentialLockOptionsV1): Promise<ResolvedCredentialMaterialV1 & {
267
- credentialVersion: number;
268
- }>;
269
- /** Cross-process workspace serialization for Pi CredentialStore.modify(). */
270
- withWorkspaceLock<T>(workspaceId: string, mutate: (locked: VaultCredentialStoreBackendV1) => Promise<T>, options?: WorkspaceCredentialLockOptionsV1): Promise<T>;
271
- /**
272
- * Writes (or rotates to) a new credential version for a workspace/provider.
273
- * Every write mints a fresh credential version; nonces are never reused.
274
- */
275
- writeCredentialFields(input: WriteCredentialFieldsInputV1): Promise<StoredCredentialRecordV1>;
276
- /** Marks a workspace/provider credential as deliberately field-less. */
277
- writeAbsentCredential(workspaceId: string, providerId: ProviderId, options?: WorkspaceCredentialLockOptionsV1): Promise<StoredCredentialRecordV1>;
278
- getCredentialMetadata(workspaceId: string, providerId: ProviderId): Promise<StoredCredentialMetadataV1 | undefined>;
279
- listCredentialMetadata(workspaceId: string): Promise<readonly StoredCredentialMetadataV1[]>;
280
- setCredentialLifecycleState(workspaceId: string, providerId: ProviderId, state: CredentialLifecycleStateV1): Promise<StoredCredentialMetadataV1>;
281
- /** Rotates the KEK wrapping for one workspace DEK generation in place. */
282
- rewrapWorkspaceDek(workspaceId: string, dekGeneration: number): Promise<void>;
283
- /** Re-encrypts all live workspace credentials under a fresh DEK generation. */
284
- rotateWorkspaceDek(workspaceId: string, operationId: string): Promise<number>;
285
- /** Irreversibly destroys workspace credential key access and fails closed thereafter. */
286
- cryptoShredWorkspace(workspaceId: string): Promise<void>;
287
- }
288
- declare function createVaultCredentialStoreBackendV1(options: VaultCredentialStoreOptionsV1$1): VaultCredentialStoreBackendV1;
289
-
290
- /**
291
- * uv setup for Python-family runtimes (e.g. Vercel `python3.13`), which already
292
- * ship `pip` and usually `uv`. Verify-or-install via the on-PATH `uv`.
293
- */
294
- declare const UV_SETUP_COMMANDS: readonly ["command -v uv >/dev/null 2>&1 || python3 -m pip install --upgrade uv", "uv --version"];
295
- type DeploymentSnapshotStatus = 'skipped' | 'cache-hit' | 'baked' | 'failed';
296
- interface DeploymentSnapshotRecipe {
297
- /** Provider runtime/image selector. Example: Vercel's python3.13 runtime. */
298
- runtime?: string;
299
- /** OS packages to bake into the reusable runtime layer. */
300
- systemPackages?: readonly string[];
301
- /** Python packages to bake into the reusable runtime layer. */
302
- pythonPackages?: readonly string[];
303
- /** Ordered setup commands for runtime primitives such as uv. */
304
- setupCommands?: readonly string[];
305
- }
306
- interface DeploymentSnapshotResult {
307
- status: DeploymentSnapshotStatus;
308
- reason: string;
309
- hash?: string;
310
- snapshotId?: string;
311
- error?: unknown;
312
- }
313
- interface DeploymentSnapshotProvider {
314
- prepareDeploymentSnapshot(recipe: DeploymentSnapshotRecipe): Promise<DeploymentSnapshotResult>;
315
- }
316
- interface BuildDeploymentSnapshotRecipeOptions extends DeploymentSnapshotRecipe {
317
- /** Defaults true: install/check uv at deploy-time so workspaces boot fast. */
318
- includeUv?: boolean;
319
- }
320
- declare function buildDeploymentSnapshotRecipe(opts?: BuildDeploymentSnapshotRecipeOptions): DeploymentSnapshotRecipe;
321
- declare function prepareDeploymentSnapshot(provider: DeploymentSnapshotProvider, recipe: DeploymentSnapshotRecipe): Promise<DeploymentSnapshotResult>;
322
-
323
- declare function resolveWorkspaceRoot(defaultRoot?: string): string;
324
-
325
- interface RemoteWorkerClientOptions {
326
- baseUrl: string;
327
- token: string;
328
- workspaceId: string;
329
- requestId?: string;
330
- fetchImpl?: typeof fetch;
331
- requestTimeoutMs?: number;
332
- execTimeoutMs?: number;
333
- execRequestGraceMs?: number;
334
- }
335
- declare class RemoteWorkerClientError extends Error {
336
- readonly statusCode: number;
337
- readonly code: string;
338
- readonly details?: unknown;
339
- constructor(message: string, opts: {
340
- statusCode: number;
341
- code?: string;
342
- details?: unknown;
343
- });
344
- }
345
- declare class RemoteWorkerClient {
346
- private readonly baseUrl;
347
- private readonly token;
348
- private readonly workspaceId;
349
- private readonly requestId?;
350
- private readonly fetchImpl;
351
- private readonly requestTimeoutMs;
352
- private readonly execTimeoutMs;
353
- private readonly execRequestGraceMs;
354
- constructor(opts: RemoteWorkerClientOptions);
355
- private timeoutError;
356
- private abortedError;
357
- private fetchWithTimeout;
358
- health(): Promise<RemoteWorkerHealthResponse>;
359
- workspace(op: RemoteWorkerWorkspaceOp): Promise<RemoteWorkerWorkspaceResult>;
360
- exec(input: RemoteWorkerExecRequest, opts?: Pick<ExecOptions, 'signal'>): Promise<ExecResult>;
361
- watch(onEvent: (event: WorkspaceChangeEvent) => void, onError?: (error: Error) => void): {
362
- close(): void;
363
- };
364
- private consumeEvents;
365
- private handleSseFrame;
366
- }
367
- declare function encodeBytesForWorker(bytes: Uint8Array): string;
368
- declare function decodeBytesFromWorker(value: string): Uint8Array;
369
- declare function constantTimeTokenEqual(a: string, b: string): boolean;
370
-
371
- interface RemoteWorkerModeAdapterOptions {
372
- baseUrl?: string;
373
- token?: string;
374
- fetchImpl?: RemoteWorkerClientOptions['fetchImpl'];
375
- }
376
- declare function createRemoteWorkerModeAdapter(opts?: RemoteWorkerModeAdapterOptions): RuntimeModeAdapter;
377
-
378
- declare function createRemoteWorkerWorkspace(client: RemoteWorkerClient, supportsExclusiveBinaryCreate?: boolean): Workspace;
379
-
380
- declare function createRemoteWorkerSandbox(client: RemoteWorkerClient): Sandbox;
381
-
382
- interface RuntimeTemplateContribution {
383
- id: string;
384
- path: string | URL;
385
- target?: string;
386
- }
387
- interface RuntimePythonSpec {
388
- id: string;
389
- /** uv-compatible pyproject.toml. Console scripts declared here are exposed to the agent. */
390
- projectFile: string | URL;
391
- /** Extra workspace libraries to install into the same environment. */
392
- extraLibs?: string[];
393
- /** Env vars exported by command shims, e.g. plugin builtin paths. */
394
- env?: Record<string, string | URL>;
395
- }
396
- interface RuntimeNodePackageSpec {
397
- id: string;
398
- /** Package name materialized under workspaceRoot/node_modules, e.g. @boring/workspace. */
399
- packageName: string;
400
- /** Source package root. The provisioner copies the built package payload into node_modules. */
401
- packageRoot: string | URL;
402
- }
403
- interface RuntimeProvisioningContribution {
404
- templateDirs?: RuntimeTemplateContribution[];
405
- python?: RuntimePythonSpec[];
406
- nodePackages?: RuntimeNodePackageSpec[];
407
- }
408
- interface ProvisionRuntimeWorkspaceOptions {
409
- workspaceRoot: string;
410
- contributions?: Array<{
411
- id: string;
412
- provisioning?: RuntimeProvisioningContribution;
413
- }>;
414
- force?: boolean;
415
- }
416
- interface RuntimeWorkspaceProvisioningResult {
417
- fingerprint: string;
418
- changed: boolean;
419
- env: Record<string, string>;
420
- binDir: string;
421
- }
422
- declare function provisionRuntimeWorkspace({ workspaceRoot, contributions, force, }: ProvisionRuntimeWorkspaceOptions): Promise<RuntimeWorkspaceProvisioningResult>;
423
-
424
- type ProvisioningArtifactKind = 'node' | 'python';
425
- /** What a per-mode packer receives to produce one artifact. `id`/`fingerprint`
426
- * are passed through (not used by the default packer, but part of the public
427
- * `prepareArtifact` contract — consumers key their own artifact paths off them). */
428
- interface ProvisioningArtifactRequest {
429
- kind: ProvisioningArtifactKind;
430
- id: string;
431
- fingerprint: string;
432
- source: string | URL;
433
- outputPath: string;
434
- }
435
-
436
- declare function hasBwrap(): boolean;
437
- declare function autoDetectMode(): RuntimeModeId;
438
- interface ResolveModeOptions {
439
- adapters?: Readonly<Record<BuiltinRuntimeModeId, RuntimeModeAdapter>>;
440
- }
441
- declare function resolveMode(mode?: RuntimeModeId, opts?: ResolveModeOptions): RuntimeModeAdapter;
442
-
443
- declare function createDirectModeAdapter(options: {
444
- provider: SandboxProviderV1;
445
- runtimeHost: AgentRuntimeHostOperations;
446
- }): RuntimeModeAdapter;
447
-
448
- declare function createLocalModeAdapter(options: {
449
- provider: SandboxProviderV1;
450
- runtimeHost: AgentRuntimeHostOperations;
451
- }): RuntimeModeAdapter;
452
-
453
- declare function createVercelSandboxModeAdapter(options: {
454
- provider: SandboxProviderV1;
455
- runtimeHost: AgentRuntimeHostOperations;
456
- remoteRoot: string;
457
- workspaceRoot: string;
458
- }): RuntimeModeAdapter;
459
-
460
- declare function createBlaxelSandboxModeAdapter(options: {
461
- provider: SandboxProviderV1;
462
- runtimeHost: AgentRuntimeHostOperations;
463
- }): RuntimeModeAdapter;
464
-
465
- interface ProviderRuntimeModeAdapterOptions {
466
- id: RuntimeModeId;
467
- provider: SandboxProviderV1;
468
- runtimeHost: AgentRuntimeHostOperations;
469
- workspaceFsCapability: 'strong' | 'best-effort';
470
- bash: RuntimeBashStrategy;
471
- filesystem: RuntimeFilesystemStrategy;
472
- storageRoot?: (context: ModeContext) => string | undefined;
473
- preflight?: (context: ModeContext) => void | Promise<void>;
474
- prepare?: (context: ModeContext) => Promise<void>;
475
- provisioningAdapter?: (context: ModeContext, pair: WorkspaceSandboxPairV1) => WorkspaceProvisioningAdapter | undefined;
476
- healthCheckIntervalMs?: number;
477
- readiness?: RuntimeModeAdapter['readiness'];
478
- }
479
- declare function createProviderRuntimeModeAdapter(options: ProviderRuntimeModeAdapterOptions): RuntimeModeAdapter;
480
-
481
- declare const sandboxRuntimeHostOperations: AgentRuntimeHostOperations;
482
- interface SandboxRuntimeModeOptions {
483
- readonly sandboxHandleStore?: SandboxHandleStore;
484
- readonly bwrap?: BwrapSandboxProviderOptions;
485
- }
486
- /** Built-in runtime layout root without exposing provider package constants to consumers. */
487
- declare function resolveBuiltinRuntimeLayoutRoot(mode: BuiltinRuntimeModeId, workspaceRoot: string): string;
488
- declare function createSandboxRuntimeModeAdapter(mode: RuntimeModeId, options?: SandboxRuntimeModeOptions): RuntimeModeAdapter;
489
-
490
- type AgentDirectoryCompilerErrorCode = 'AGENT_DIRECTORY_NOT_FOUND' | 'AGENT_DIRECTORY_NOT_DIRECTORY' | 'AGENT_MANIFEST_NOT_FOUND' | 'AGENT_MANIFEST_NOT_FILE' | 'AGENT_MANIFEST_INVALID_UTF8' | 'AGENT_MANIFEST_INVALID_JSON' | 'AGENT_MANIFEST_MISSING_BORING_AGENT' | 'AGENT_ASSET_NOT_FOUND' | 'AGENT_ASSET_NOT_FILE' | 'AGENT_ASSET_INVALID_UTF8' | 'AGENT_PATH_SYMLINK_ESCAPE' | 'AGENT_PATH_CHANGED_DURING_READ' | 'AGENT_DIRECTORY_IO_FAILED';
491
- type AgentDirectoryCompilerPublicErrorCode = Extract<ErrorCode, 'CONFIG_INVALID' | 'PATH_NOT_FOUND' | 'PATH_SYMLINK_ESCAPE'>;
492
- declare class AgentDirectoryCompilerError extends Error {
493
- readonly code: AgentDirectoryCompilerPublicErrorCode;
494
- readonly compilerCode: AgentDirectoryCompilerErrorCode;
495
- readonly field: string;
496
- constructor(input: {
497
- code: AgentDirectoryCompilerPublicErrorCode;
498
- compilerCode: AgentDirectoryCompilerErrorCode;
499
- field: string;
500
- message: string;
501
- cause?: unknown;
502
- });
503
- }
504
- declare function compileAgentDirectory(directory: string): Promise<CompiledAgentBundle>;
505
- /**
506
- * Compiles a persona authored as a plugin-shaped package: `package.json`'s
507
- * `boring.agent` block stands in for `agent.json`, `instructions.md` is
508
- * unchanged. Used for `.agents/personas/<seat>` fleet packages.
509
- */
510
- declare function compilePersonaPackageDirectory(directory: string): Promise<CompiledAgentBundle>;
511
-
512
- type AuthoredAgentMaterializationErrorCode = Extract<ErrorCode, 'AUTHORED_AGENT_ID_INVALID' | 'AUTHORED_AGENT_TYPE_MISMATCH' | 'AUTHORED_AGENT_REFERENCE_UNSUPPORTED'>;
513
- type AuthoredAgentSourceV1 = Readonly<{
514
- schemaVersion: 1;
515
- agentTypeId: string;
516
- version: string;
517
- label?: string;
518
- description?: string;
519
- instructions: string;
520
- /**
521
- * Computed identity of the compiled definition (instructions + knowledge
522
- * bytes). The digest, not the version string, is the definition identity.
523
- */
524
- definitionDigest?: string;
525
- /** Host path of the package's optional `knowledge/` folder, when present. */
526
- knowledgeDir?: string;
527
- }>;
528
- interface MaterializeAgentDirectoryInput {
529
- directory: string;
530
- expectedAgentTypeId?: string;
531
- /**
532
- * Manifest shape to compile. Defaults to `agent.json` for backward
533
- * compatibility. `package.json` reads the `boring.agent` block, used by
534
- * plugin-shaped personas (`.agents/personas/<seat>`).
535
- */
536
- manifest?: 'agent.json' | 'package.json';
537
- }
538
- declare class AuthoredAgentMaterializationError extends Error {
539
- readonly code: AuthoredAgentMaterializationErrorCode;
540
- readonly field?: string;
541
- constructor(input: {
542
- code: AuthoredAgentMaterializationErrorCode;
543
- field?: string;
544
- message: string;
545
- });
546
- }
547
- /**
548
- * Loads declarative authored identity, safe metadata, and instructions.
549
- * Executable behavior is selected only by trusted host/plugin policy.
550
- */
551
- declare function materializeAgentDirectory(input: MaterializeAgentDirectoryInput): Promise<AuthoredAgentSourceV1>;
552
-
553
- interface TrustedAgentInstructionAppendix {
554
- readonly name: string;
555
- readonly content: string;
556
- readonly digest: Sha256Digest;
557
- }
558
- interface TrustedAuthoredAgentPolicy {
559
- readonly fallbackLabel?: string;
560
- /**
561
- * Authored instruction sources for this agent as host absolute paths,
562
- * supplied by the trusted composer that actually knows where they live.
563
- * Addressing them against a served workspace root is a per-request concern.
564
- */
565
- readonly instructionSources?: readonly AgentInstructionSource[];
566
- readonly instructionAppendices?: readonly TrustedAgentInstructionAppendix[];
567
- readonly plugins?: readonly {
568
- readonly name: string;
569
- readonly config?: JsonValue;
570
- }[];
571
- readonly preferredModel?: string;
572
- }
573
- interface CreateConfiguredAgentHostAgentSpecInput {
574
- readonly source: AuthoredAgentSourceV1;
575
- readonly policy?: TrustedAuthoredAgentPolicy;
576
- }
577
- declare class TrustedAgentCompositionError extends Error {
578
- readonly code: "CONFIG_INVALID";
579
- readonly field: string;
580
- constructor(field: string, message: string);
581
- }
582
- /**
583
- * Maps identity-only authored data into AgentHost configuration. Every behavior
584
- * input is supplied separately by trusted host composition.
585
- */
586
- declare function createConfiguredAgentHostAgentSpec(input: CreateConfiguredAgentHostAgentSpecInput): Promise<ConfiguredAgentHostAgentSpec>;
587
-
588
- interface ModelTierCandidate {
589
- readonly provider: string;
590
- readonly id: string;
591
- readonly envVar: string;
592
- }
593
- interface FleetSkillBinding {
594
- readonly name: string;
595
- readonly digest: Sha256Digest;
596
- }
597
- interface FleetSeatBinding {
598
- readonly seat: string;
599
- readonly agentTypeId: string;
600
- readonly skills: readonly FleetSkillBinding[];
601
- }
602
- interface DiscoveredAgentPackageDescriptor {
603
- readonly rootDir: string;
604
- readonly manifest: {
605
- readonly boring: {
606
- readonly agent: {
607
- readonly definitionId: string;
608
- readonly version: string;
609
- readonly label?: string;
610
- readonly description?: string;
611
- readonly instructionsRef: string;
612
- };
613
- };
614
- readonly pi?: {
615
- readonly skills?: readonly string[];
616
- };
617
- };
618
- readonly preflight: {
619
- readonly ok: boolean;
620
- readonly errors?: readonly {
621
- readonly code: string;
622
- readonly message: string;
623
- }[];
624
- };
625
- }
626
- interface LoadConfiguredAgentFleetOptions {
627
- /** Plugin-manager scan descriptors injected by the workspace/CLI boot layer. */
628
- readonly discoveredPackages: readonly DiscoveredAgentPackageDescriptor[];
629
- /** Path to `.agents/factory/fleet.yaml`. */
630
- readonly fleetConfigPath: string;
631
- /** Path to `.agents/factory/policy.yaml` (read for `models.seats` tiers). */
632
- readonly policyPath: string;
633
- /**
634
- * Directory containing `<skill>/SKILL.md` canonical skill sources.
635
- * This root is host-owned because shared skill names are not package paths.
636
- */
637
- readonly skillsRoot: string;
638
- /** Overridable for tests; defaults to `process.env`. */
639
- readonly env?: NodeJS.ProcessEnv;
640
- }
641
- type FleetLoaderDiagnosticCode = Extract<ErrorCode, 'AGENT_FLEET_SEAT_PERSONA_INVALID' | 'AGENT_FLEET_SEAT_SKILL_DIGEST_MISMATCH' | 'AGENT_DEFINITION_ID_CONFLICT' | 'AGENT_DEFINITION_UNSEATED'>;
642
- interface FleetLoaderDiagnostic {
643
- readonly seat?: string;
644
- readonly agentTypeId: string;
645
- readonly code: FleetLoaderDiagnosticCode;
646
- readonly message: string;
647
- }
648
- interface LoadConfiguredAgentFleetResult {
649
- readonly agents: readonly ConfiguredAgentHostAgentSpec[];
650
- readonly diagnostics: readonly FleetLoaderDiagnostic[];
651
- }
652
- type FleetConfigErrorCode = Extract<ErrorCode, 'AGENT_FLEET_CONFIG_FILE_INVALID'>;
653
- /** Thrown for whole-fleet configuration failures (not per-seat, fail-closed). */
654
- declare class FleetConfigError extends Error {
655
- readonly code: FleetConfigErrorCode;
656
- readonly field: string;
657
- constructor(input: {
658
- field: string;
659
- message: string;
660
- cause?: unknown;
661
- });
662
- }
663
- /**
664
- * Loads the config-driven production/CLI agent fleet: `.agents/factory/fleet.yaml`
665
- * seat → skill-digest bindings, boot-injected plugin-shaped persona package
666
- * descriptors, `.agents/factory/policy.yaml` `models.seats` tiers, and the
667
- * priority-ordered `models.tiers` candidates declared in fleet.yaml.
668
- *
669
- * Excludes an individual package when a configured seat cannot materialize or
670
- * verify, allowing valid sibling seats to boot. Whole-fleet config errors
671
- * (including unreadable/malformed fleet or policy YAML) throw `FleetConfigError`.
672
- */
673
- declare function loadConfiguredAgentFleet(options: LoadConfiguredAgentFleetOptions): Promise<LoadConfiguredAgentFleetResult>;
674
-
675
- type InstructionRefWithholdingCode = Extract<ErrorCode, 'AGENT_FLEET_SEAT_INSTRUCTIONS_PATH_UNPUBLISHABLE'>;
676
- interface WithheldInstructionRef {
677
- readonly code: InstructionRefWithholdingCode;
678
- /** Host absolute path of the authored source that could not be addressed. */
679
- readonly absolutePath: string;
680
- readonly message: string;
681
- }
682
- interface ResolvedInstructionFileRefs {
683
- readonly refs: readonly AgentInstructionFileRef[];
684
- readonly withheld: readonly WithheldInstructionRef[];
685
- }
686
- /**
687
- * Addresses authored instruction sources against the workspace root a SINGLE
688
- * request is served from, which is the only moment a multi-workspace host
689
- * (the CLI hub, core) knows one — composition time sees a fleet shared by
690
- * every workspace (gh-1189).
691
- *
692
- * Publication is deterministic and fails closed: a ref is emitted only when
693
- * the source canonically resolves inside the served root AND composes a path
694
- * the client-side openable-resource guard accepts. Anything else is withheld
695
- * with the stable `AGENT_FLEET_SEAT_INSTRUCTIONS_PATH_UNPUBLISHABLE` code, so
696
- * the invariant from #1176 holds: a rendered link always resolves.
697
- *
698
- * Canonicalization (not lexical containment) on BOTH sides is the point:
699
- * dotfile managers make a symlinked `.agents` ordinary, and a lexical check
700
- * would call `~/project/.agents -> ~/dotfiles/agents` "inside the workspace"
701
- * and publish a link the `user` filesystem cannot open.
702
- */
703
- declare function resolveAgentInstructionFileRefs(input: {
704
- readonly sources: readonly AgentInstructionSource[] | undefined;
705
- /** Root the `user` filesystem serves for THIS request, when the host resolved one. */
706
- readonly workspaceRoot: string | null | undefined;
707
- }): Promise<ResolvedInstructionFileRefs>;
708
-
709
- /**
710
- * A real, regular Agent used by hosts that do not opt into authored fleet
711
- * discovery. Platform host adapters preserve the established `default` ID's
712
- * plugin, skill, and transcript behavior without a separate pseudo-Agent type.
713
- */
714
- declare const DEFAULT_AGENT_FLEET: readonly AgentHostAgentSpec[];
715
- interface ResolveDefaultAgentFleetOptions {
716
- /** Repository root used to resolve `.agents/{factory,skills}`. Defaults to `process.cwd()`. */
717
- readonly repositoryRoot?: string;
718
- /** Asset-manager scan results supplied by the workspace/CLI boot layer. */
719
- readonly discoveredPackages?: readonly DiscoveredAgentPackageDescriptor[];
720
- /** Overridable for tests; defaults to `process.env`. */
721
- readonly env?: NodeJS.ProcessEnv;
722
- }
723
- /**
724
- * Resolves one deployment-static fleet for Core, Workspace, and CLI hosts.
725
- *
726
- * The built-in default is a regular configured Agent. When authored fleet
727
- * discovery is enabled it remains available alongside valid discovered seats
728
- * so old `default` session references stay routable. Missing fleet config and
729
- * individual package failures degrade to that valid subset; malformed whole-
730
- * fleet configuration still rejects boot.
731
- */
732
- declare function resolveDefaultAgentFleet(options: ResolveDefaultAgentFleetOptions): Promise<readonly AgentHostAgentSpec[]>;
733
-
734
- interface ResolvedAgentDigestInput {
735
- readonly workspaceId: string;
736
- readonly defaultDeploymentId: string;
737
- readonly workspaceCompositionDigest: Sha256Digest;
738
- readonly definitionDigest: Sha256Digest;
739
- readonly deploymentDigest: Sha256Digest;
740
- }
741
- declare function createResolvedAgentDigest(input: ResolvedAgentDigestInput): Promise<Sha256Digest>;
742
- interface ResolvedAgent {
743
- readonly workspace: Readonly<{
744
- workspaceId: string;
745
- defaultDeploymentId: string;
746
- compositionDigest: Sha256Digest;
747
- }>;
748
- readonly deployment: Readonly<{
749
- deploymentId: string;
750
- version: string;
751
- agentId: string;
752
- digest: Sha256Digest;
753
- }>;
754
- readonly definition: Readonly<{
755
- definitionId: string;
756
- version: string;
757
- digest: Sha256Digest;
758
- instructionsRef: string;
759
- }>;
760
- readonly instructions: Readonly<{
761
- ref: string;
762
- content: string;
763
- }>;
764
- readonly resolvedDigest: Sha256Digest;
765
- }
766
- declare function resolveAgentDeployment(bundle: CompiledAgentBundle, deployment: AgentDeployment, authorizedBinding: unknown): Promise<ResolvedAgent>;
767
-
768
- declare const MANAGED_AGENT_MCP_ORIGIN_SURFACE = "mcp-managed-agent";
769
- declare const MANAGED_AGENT_MCP_DELIVERY_RULE = "M1 DELIVERY v0: delegate_task returns bounded final assistant text and at most one complete authorized inline Markdown artifact; no artifact paths, truncation, or share-link delivery.";
770
- type ManagedAgentDelegationStatus = 'running' | 'completed' | 'error';
771
- type ManagedAgentDelegateStatus = ManagedAgentDelegationStatus;
772
- interface ManagedAgentArtifactCandidate {
773
- path: string;
774
- mediaType?: string;
775
- title?: string;
776
- content?: unknown;
777
- truncated?: unknown;
778
- }
779
- /** @deprecated Use ManagedAgentArtifactCandidate for internal artifact path candidates. */
780
- type ManagedAgentArtifactRef = ManagedAgentArtifactCandidate;
781
- interface ManagedAgentArtifact {
782
- content: string;
783
- sha256: `sha256:${string}`;
784
- byteSize: number;
785
- mediaType?: string;
786
- title?: string;
787
- }
788
- interface ManagedAgentWorkspaceResolutionInput {
789
- brief: string;
790
- ctx: SessionCtx;
791
- request: ManagedAgentDelegateRequestContext;
792
- }
793
- interface ManagedAgentDelegateRunInput {
794
- brief: string;
795
- ctx: SessionCtx;
796
- request: ManagedAgentDelegateRequestContext;
797
- actor: AgentActor;
798
- signal?: AbortSignal;
799
- onSessionStarted?: (sessionId: string) => void;
800
- }
801
- interface ManagedAgentDelegateRunner {
802
- run(input: ManagedAgentDelegateRunInput): AsyncIterable<AgentEvent>;
803
- stop?(sessionId: string, ctx: SessionCtx): Promise<void> | void;
804
- }
805
- interface ManagedAgentBoundRunnerWorkspace {
806
- runner: ManagedAgentDelegateRunner;
807
- workspace: Workspace;
808
- }
809
- interface ManagedAgentDelegateProgress {
810
- at: string;
811
- eventIndex: number;
812
- kind: string;
813
- message: string;
814
- }
815
- interface ManagedAgentDelegateResult {
816
- delegationId: string;
817
- status: 'completed';
818
- finalAssistantText: string;
819
- artifact?: ManagedAgentArtifact;
820
- deliveryRule: typeof MANAGED_AGENT_MCP_DELIVERY_RULE;
821
- }
822
- interface ManagedAgentDelegateStatusResult {
823
- delegationId: string;
824
- status: ManagedAgentDelegationStatus;
825
- progress: ManagedAgentDelegateProgress[];
826
- lastEventIndex?: number;
827
- eventCount: number;
828
- result?: ManagedAgentDelegateResult;
829
- error?: ManagedAgentSafeError;
830
- }
831
- interface ManagedAgentSafeError {
832
- code: ErrorCode;
833
- message: string;
834
- }
835
- interface ManagedAgentDelegateRequestContext {
836
- sessionId?: string;
837
- authInfo?: unknown;
838
- }
839
- interface ManagedAgentDelegateInput {
840
- brief: string;
841
- request?: ManagedAgentDelegateRequestContext;
842
- onDelegationCreated?: (status: ManagedAgentDelegateStatusResult) => void | Promise<void>;
843
- onProgress?: (progress: ManagedAgentDelegateProgress) => void | Promise<void>;
844
- signal?: AbortSignal;
845
- }
846
- interface ManagedAgentCollectArtifactsInput {
847
- delegationId: string;
848
- sessionId: string;
849
- ctx: SessionCtx;
850
- request: ManagedAgentDelegateRequestContext;
851
- finalAssistantText: string;
852
- events: readonly AgentEvent[];
853
- }
854
- interface ManagedAgentMcpDelegateOptions {
855
- gateway?: AgentGateway;
856
- agentTypeId: string;
857
- resolveGatewayScope?(input: {
858
- brief: string;
859
- ctx: SessionCtx;
860
- request: ManagedAgentDelegateRequestContext;
861
- }): AuthorizedAgentScope | Promise<AuthorizedAgentScope>;
862
- resolveSessionCtx(input: {
863
- brief: string;
864
- request: ManagedAgentDelegateRequestContext;
865
- }): SessionCtx | Promise<SessionCtx>;
866
- resolveWorkspace?(input: ManagedAgentWorkspaceResolutionInput): Workspace | Promise<Workspace>;
867
- resolveRunnerWorkspace?(input: ManagedAgentWorkspaceResolutionInput & {
868
- actor: AgentActor;
869
- }): ManagedAgentBoundRunnerWorkspace | Promise<ManagedAgentBoundRunnerWorkspace>;
870
- resolveActor?(input: {
871
- brief: string;
872
- ctx: SessionCtx;
873
- request: ManagedAgentDelegateRequestContext;
874
- }): AgentActor | Promise<AgentActor>;
875
- collectArtifacts?(input: ManagedAgentCollectArtifactsInput): ManagedAgentArtifactCandidate[] | Promise<ManagedAgentArtifactCandidate[]>;
876
- createDelegationId?: () => string;
877
- now?: () => Date;
878
- maxBriefBytes?: number;
879
- /** Optional additional character cap retained for host compatibility. */
880
- maxBriefChars?: number;
881
- terminalRetentionMs?: number;
882
- maxDelegations?: number;
883
- redactionCanaries?: readonly string[];
884
- }
885
- declare class ManagedAgentMcpError extends Error {
886
- readonly code: ErrorCode;
887
- constructor(code: ErrorCode, message: string);
888
- }
889
- declare class ManagedAgentMcpDelegateController {
890
- private readonly options;
891
- private readonly delegations;
892
- private readonly createDelegationId;
893
- private readonly now;
894
- private readonly maxBriefBytes;
895
- private readonly maxBriefChars?;
896
- private readonly terminalRetentionMs;
897
- private readonly maxDelegations;
898
- private readonly redactionCanaries;
899
- constructor(options: ManagedAgentMcpDelegateOptions);
900
- delegateTask(input: ManagedAgentDelegateInput): Promise<ManagedAgentDelegateResult>;
901
- getStatusForRequest(delegationId: string, request: ManagedAgentDelegateRequestContext): Promise<ManagedAgentDelegateStatusResult>;
902
- getStatus(delegationId: string, ctx: SessionCtx): ManagedAgentDelegateStatusResult;
903
- private createRecord;
904
- private markTerminal;
905
- private pruneDelegations;
906
- private parseBrief;
907
- private resolveSessionCtx;
908
- private resolveWorkspace;
909
- private resolveRunnerWorkspace;
910
- private createGatewayDelegateRunner;
911
- private assertNotAborted;
912
- private stopDelegatedSession;
913
- private resolveActor;
914
- private observeEvent;
915
- private pushProgress;
916
- private validateFinalAssistantText;
917
- private collectArtifacts;
918
- private toSafeError;
919
- private assertPublicPayloadSafe;
920
- private containsSecret;
921
- private timestamp;
922
- }
923
- declare function createManagedAgentMcpDelegateController(options: ManagedAgentMcpDelegateOptions): ManagedAgentMcpDelegateController;
924
-
925
- interface ManagedAgentMcpPresentationOptions {
926
- name?: string;
927
- version?: string;
928
- maxBriefChars?: number;
929
- /**
930
- * Optional Lane W (AR1-002/AR1-004) share-entry store. When supplied
931
- * together with `resolveShareSessionCtx`/`resolveShareWorkspace`, the
932
- * server exposes `listResources`/`readResource` scoped to the
933
- * authenticated workspace's share entries, on this SAME MCP server
934
- * process (no second MCP runtime owner). Hosts that omit any of the
935
- * three leave Lane W unmounted — no widening.
936
- */
937
- shareEntryStore?: ShareEntryStore;
938
- /** Resolves the authenticated SessionCtx for a share resource request. */
939
- resolveShareSessionCtx?: (request: ManagedAgentDelegateRequestContext) => SessionCtx | Promise<SessionCtx>;
940
- /** Resolves the authorized Workspace to read share targets from, for a given SessionCtx. */
941
- resolveShareWorkspace?: (ctx: SessionCtx) => Workspace | Promise<Workspace>;
942
- }
943
- interface ManagedAgentMcpServerOptions extends ManagedAgentMcpDelegateOptions, ManagedAgentMcpPresentationOptions {
944
- }
945
- type ManagedAgentMcpHttpHandlerOptions = (ManagedAgentMcpPresentationOptions & {
946
- controller: ManagedAgentMcpDelegateController;
947
- }) | (ManagedAgentMcpServerOptions & {
948
- controller?: undefined;
949
- });
950
- declare function createManagedAgentMcpServer(options: ManagedAgentMcpServerOptions): McpServer;
951
- declare function createManagedAgentMcpHttpHandler(options: ManagedAgentMcpHttpHandlerOptions): (req: IncomingMessage, res: ServerResponse, parsedBody?: unknown) => Promise<void>;
952
-
953
- interface ShareEntryMcpResourceOptions {
954
- /** Lane W (AR1-002) opaque share-entry store — the single source of truth for entries. */
955
- store: ShareEntryStore;
956
- /** Resolves the authenticated SessionCtx for a resource request (list or read). */
957
- resolveSessionCtx(request: ManagedAgentDelegateRequestContext): SessionCtx | Promise<SessionCtx>;
958
- /** Resolves the authorized Workspace to read share targets from, for a given SessionCtx. */
959
- resolveWorkspace(ctx: SessionCtx): Workspace | Promise<Workspace>;
960
- }
961
- /** Builds the opaque share resource URI for a given share-entry id. */
962
- declare function shareResourceUri(id: string): string;
963
- /**
964
- * Registers `listResources`/`readResource` for Lane W share entries on an
965
- * already-constructed managed-agent `McpServer`. A no-op call site (host
966
- * omits `shareEntryStore`) leaves Lane W unmounted — see
967
- * `managedAgentMcpServer.ts`'s optional wiring.
968
- */
969
- declare function registerShareEntryResources(server: McpServer, options: ShareEntryMcpResourceOptions): void;
970
-
971
- interface RuntimeEnvContributionContext {
972
- workspaceId: string;
973
- workspaceRoot: string;
974
- runtimeMode: RuntimeModeId;
975
- runtimeBundle: RuntimeBundle;
976
- }
977
- interface RuntimeEnvContribution {
978
- id: string;
979
- getEnv(ctx: RuntimeEnvContributionContext): Record<string, string> | Promise<Record<string, string>>;
980
- }
981
- declare function withRuntimeEnvContributions(runtimeBundle: RuntimeBundle, baseContext: RuntimeEnvContributionContext, contributions: RuntimeEnvContribution[], telemetry?: TelemetrySink): RuntimeBundle;
982
-
983
- interface AuthorizedSessionRunDetails {
984
- runId: string;
985
- terminalEntryId: string;
986
- state: 'success' | 'error' | 'aborted' | 'interrupted';
987
- createdAt?: string;
988
- details: readonly unknown[];
989
- }
990
- /** Redact a session snapshot to terminal run identity and allowlisted structured details. */
991
- declare function projectAuthorizedSessionRunDetails(messages: readonly unknown[], detailKinds: readonly string[]): AuthorizedSessionRunDetails[];
992
-
993
- interface WorkspaceAgentDispatcherResolveOptions {
994
- request?: FastifyRequest;
995
- }
996
- interface PiSessionVisibleUserTurnTarget {
997
- /** Advisory snapshot; sendIfIdle is the authoritative atomic admission. */
998
- isIdle(): Promise<boolean>;
999
- sendIfIdle(input: {
1000
- /** Stable across busy/transient retries; also used as the Pi client nonce. */
1001
- requestId: string;
1002
- message: string;
1003
- displayMessage?: string;
1004
- }): Promise<{
1005
- status: 'accepted';
1006
- cursor: number;
1007
- duplicate?: boolean;
1008
- } | {
1009
- status: 'busy';
1010
- } | {
1011
- status: 'gone';
1012
- }>;
1013
- }
1014
- interface BoundPiSession {
1015
- /** Trusted target closed over one exact logical Pi session. */
1016
- visibleUserMessageTarget: PiSessionVisibleUserTurnTarget;
1017
- }
1018
- interface WorkspaceAgentDispatcherBinding {
1019
- dispatcher: WorkspaceAgentDispatcher;
1020
- workspace: Workspace;
1021
- /**
1022
- * Trusted host seam used by local integrations that must bind durable work
1023
- * to the exact logical Pi session before accepting it.
1024
- */
1025
- bindPiSession?(sessionId: string, sessionCtx?: {
1026
- workspaceId?: string;
1027
- userId?: string;
1028
- }): Promise<BoundPiSession>;
1029
- }
1030
- interface WorkspaceAgentDispatcherResolver {
1031
- /** Callback-scoped canonical Host operation; no dispatcher or Workspace escapes. */
1032
- runWithWorkspaceAgent(input: WorkspaceAgentDirectRunInput & {
1033
- request?: FastifyRequest;
1034
- }, run: WorkspaceAgentDirectRunCallback): Promise<void>;
1035
- resolve(ctx: WorkspaceAgentDispatcherContext, options?: WorkspaceAgentDispatcherResolveOptions): Promise<WorkspaceAgentDispatcher>;
1036
- resolveWithWorkspace?(ctx: WorkspaceAgentDispatcherContext, options?: WorkspaceAgentDispatcherResolveOptions): Promise<WorkspaceAgentDispatcherBinding>;
1037
- /** Authorize one exact addressed native session without exposing transcript data. */
1038
- authorizeSession?(ctx: WorkspaceAgentDispatcherContext, ref: AgentSessionRef, options?: WorkspaceAgentDispatcherResolveOptions): Promise<void>;
1039
- /** Authorized transcript-redacted projection of allowlisted structured run details. */
1040
- readSessionRunDetails?(ctx: WorkspaceAgentDispatcherContext, ref: AgentSessionRef, detailKinds: readonly string[], options?: WorkspaceAgentDispatcherResolveOptions): Promise<readonly AuthorizedSessionRunDetails[]>;
1041
- }
1042
- /**
1043
- * Bind the compatibility dispatcher surface to one addressed AgentGateway
1044
- * capability. The gateway, scope, and agent type are supplied only by the
1045
- * trusted composition root.
1046
- */
1047
- declare function createBoundWorkspaceAgentDispatcher(binding: WorkspaceAgentGatewayBinding, ctx: WorkspaceAgentDispatcherContext): WorkspaceAgentDispatcher;
1048
-
1049
- interface CreateStandaloneAgentHostAppOptions {
1050
- workspaceRoot?: string;
1051
- sessionId?: string;
1052
- templatePath?: string;
1053
- mode?: RuntimeModeId;
1054
- runtimeModeAdapter?: RuntimeModeAdapter;
1055
- runtimeHost?: AgentRuntimeHostOperations;
1056
- authToken?: string;
1057
- version?: string;
1058
- logger?: boolean;
1059
- /** Standalone defaults to a warm runtime; readiness smokes may keep binding lazy. */
1060
- initializeRuntime?: boolean;
1061
- extraTools?: AgentTool[];
1062
- disableDefaultFileTools?: boolean;
1063
- systemPromptAppend?: string;
1064
- harnessFactory?: AgentHarnessFactory;
1065
- pi?: PiHarnessOptions;
1066
- /** Additional host roots allowed to contribute local Pi resource bytes. */
1067
- piResourceAuthorizedRoots?: string[];
1068
- runtimeProvisioning?: WorkspaceProvisioningResult;
1069
- getRuntimeProvisioning?: () => WorkspaceProvisioningResult | undefined;
1070
- sessionNamespace?: string;
1071
- telemetry?: TelemetrySink;
1072
- metering?: AgentMeteringSink;
1073
- credentials?: AgentHostCredentialOptionsV1;
1074
- getFilesystemBindings?: (ctx: {
1075
- request?: FastifyRequest;
1076
- sessionId?: string;
1077
- workspaceId: string;
1078
- workspaceRoot: string;
1079
- userId?: string;
1080
- userEmail?: string;
1081
- userEmailVerified?: boolean;
1082
- requestId?: string;
1083
- }) => RuntimeFilesystemBinding[] | undefined | Promise<RuntimeFilesystemBinding[] | undefined>;
1084
- resolvePiSessionRequestContext?: (request: FastifyRequest, defaultContext: PiSessionRequestContext) => PiSessionRequestContext | Promise<PiSessionRequestContext>;
1085
- runtimeEnvContributions?: RuntimeEnvContribution[];
1086
- runtimeProvisioner?: (ctx: {
1087
- workspaceRoot: string;
1088
- runtimeMode: RuntimeModeId;
1089
- runtimeBundle: RuntimeBundle;
1090
- }) => Promise<void>;
1091
- sessionDir?: string;
1092
- sessionRoot?: string;
1093
- /**
1094
- * Durable request ledger file. Host application state, not workspace content:
1095
- * point it at host-owned storage. Defaults per
1096
- * {@link resolveRequestLedgerPath}.
1097
- */
1098
- requestLedgerPath?: string;
1099
- externalPlugins?: boolean;
1100
- beforeReload?: () => void | {
1101
- readonly diagnostics?: ReadonlyArray<{
1102
- source: string;
1103
- message: string;
1104
- pluginId?: string;
1105
- }>;
1106
- readonly restart_warnings?: ReadonlyArray<{
1107
- id: string;
1108
- surfaces: readonly string[];
1109
- message: string;
1110
- }>;
1111
- } | undefined | Promise<void | {
1112
- readonly diagnostics?: ReadonlyArray<{
1113
- source: string;
1114
- message: string;
1115
- pluginId?: string;
1116
- }>;
1117
- readonly restart_warnings?: ReadonlyArray<{
1118
- id: string;
1119
- surfaces: readonly string[];
1120
- message: string;
1121
- }>;
1122
- } | undefined>;
1123
- systemPromptDynamic?: () => string | undefined | Promise<string | undefined>;
1124
- getPluginDiagnostics?: (args: {
1125
- workspaceId: string;
1126
- workspaceRoot: string;
1127
- }) => Promise<Array<{
1128
- source: string;
1129
- message: string;
1130
- pluginId?: string;
1131
- }>>;
1132
- onWorkspaceAgentDispatcher?: (resolver: WorkspaceAgentDispatcherResolver) => void;
1133
- }
1134
- /** Thin standalone HTTP shell over one directly composed CreatedAgentHost. */
1135
- declare function createStandaloneAgentHostApp(options?: CreateStandaloneAgentHostAppOptions): Promise<FastifyInstance>;
1136
-
1137
- type ChannelBindingStatus = 'active' | 'revoked';
1138
- type ChannelInboundStatus = 'pending' | 'processing' | 'processed' | 'parked';
1139
- type ChannelOutboundStatus = 'active' | 'parked';
1140
- interface ChannelBinding {
1141
- readonly channel: string;
1142
- readonly conversationKey: string;
1143
- readonly agentTypeId: string;
1144
- readonly workspaceId: string;
1145
- readonly authSubjectId: string;
1146
- readonly bindingVersion: number;
1147
- readonly status: ChannelBindingStatus;
1148
- readonly sessionKey?: string;
1149
- readonly lastInboundAt?: number;
1150
- readonly outboundCursor: string;
1151
- readonly outboundStatus: ChannelOutboundStatus;
1152
- readonly sessionResetPending: boolean;
1153
- readonly templateSentForInboundAt?: number;
1154
- }
1155
- interface ProvisionChannelBindingInput extends Omit<ChannelBinding, 'bindingVersion' | 'status' | 'lastInboundAt' | 'outboundCursor' | 'outboundStatus' | 'sessionResetPending' | 'templateSentForInboundAt'> {
1156
- readonly status?: ChannelBindingStatus;
1157
- /** Tail of an existing target stream; omitted only for a new/empty session. */
1158
- readonly outboundCursor?: string;
1159
- }
1160
- interface InboundChannelMessage {
1161
- readonly channel: string;
1162
- readonly conversationKey: string;
1163
- readonly providerMessageId: string;
1164
- readonly text: string;
1165
- readonly receivedAt: number;
1166
- }
1167
- interface QueuedChannelInbound extends InboundChannelMessage {
1168
- readonly id: number;
1169
- readonly agentTypeId: string;
1170
- readonly workspaceId: string;
1171
- readonly authSubjectId: string;
1172
- readonly bindingVersion: number;
1173
- readonly claimOwner: string;
1174
- readonly attempts: number;
1175
- readonly status: ChannelInboundStatus;
1176
- readonly errorCode?: string;
1177
- }
1178
- type EnqueueInboundResult = {
1179
- readonly disposition: 'enqueued';
1180
- readonly binding: ChannelBinding;
1181
- readonly queueId: number;
1182
- } | {
1183
- readonly disposition: 'duplicate';
1184
- readonly binding?: ChannelBinding;
1185
- } | {
1186
- readonly disposition: 'unknown_binding';
1187
- };
1188
- interface ChannelIntentionRecord {
1189
- readonly questionId: string;
1190
- readonly sessionId: string;
1191
- readonly channel: string;
1192
- readonly conversationKey: string;
1193
- readonly agentTypeId: string;
1194
- readonly bindingVersion: number;
1195
- readonly fieldName: string;
1196
- readonly options: readonly {
1197
- value: string;
1198
- label: string;
1199
- description?: string;
1200
- }[];
1201
- readonly title?: string;
1202
- readonly context?: string;
1203
- readonly status: 'pending' | 'projecting' | 'window-held' | 'projected' | 'answering' | 'answered' | 'closed';
1204
- readonly answerValues?: Readonly<Record<string, unknown>>;
1205
- readonly answerProviderMessageId?: string;
1206
- }
1207
- type ClaimIntentionReplyResult = {
1208
- readonly disposition: 'claimed';
1209
- readonly intention: ChannelIntentionRecord;
1210
- } | {
1211
- readonly disposition: 'duplicate';
1212
- } | {
1213
- readonly disposition: 'no_intention';
1214
- };
1215
- type ClaimInvalidIntentionReplyResult = {
1216
- readonly disposition: 'claimed';
1217
- } | {
1218
- readonly disposition: 'duplicate';
1219
- } | {
1220
- readonly disposition: 'no_intention';
1221
- };
1222
- type NextInboundResult = {
1223
- readonly disposition: 'claimed';
1224
- readonly inbound: QueuedChannelInbound;
1225
- } | {
1226
- readonly disposition: 'blocked';
1227
- readonly retryAt: number;
1228
- } | {
1229
- readonly disposition: 'empty';
1230
- };
1231
- interface EnsureSessionOptions {
1232
- readonly reservationTtlMs?: number;
1233
- readonly maxReservationCycles?: number;
1234
- readonly initialBackoffMs?: number;
1235
- readonly allocate: () => Promise<string>;
1236
- readonly admit: (sessionKey: string) => Promise<void>;
1237
- }
1238
- declare class ChannelSessionCreateTimeoutError extends Error {
1239
- readonly code: "SESSION_CREATE_TIMEOUT";
1240
- constructor(channel: string, conversationKey: string, agentTypeId: string);
1241
- }
1242
- declare class ChannelBindingStore {
1243
- private readonly sql;
1244
- private readonly runTransaction;
1245
- constructor(sql: SqlStorage, runTransaction: RunTransaction);
1246
- private migrate;
1247
- private ensureColumn;
1248
- provision(input: ProvisionChannelBindingInput): ChannelBinding;
1249
- getBinding(channel: string, conversationKey: string, agentTypeId: string): ChannelBinding | undefined;
1250
- enqueueInbound(message: InboundChannelMessage, agentTypeId: string): EnqueueInboundResult;
1251
- recordIntentionInboundActivity(binding: Pick<ChannelBinding, 'channel' | 'conversationKey' | 'agentTypeId' | 'bindingVersion'>, receivedAt: number): ChannelBinding | undefined;
1252
- activeBindings(): ChannelBinding[];
1253
- bindingForSession(sessionId: string, workspaceId: string): ChannelBinding | undefined;
1254
- recordIntention(input: Omit<ChannelIntentionRecord, 'status'>): boolean;
1255
- openIntentions(): ChannelIntentionRecord[];
1256
- terminalIntention(channel: string, conversationKey: string, agentTypeId: string): ChannelIntentionRecord | undefined;
1257
- activeIntention(channel: string, conversationKey: string, agentTypeId: string): ChannelIntentionRecord | undefined;
1258
- claimIntentionProjection(questionId: string, owner: string, ttlMs?: number): ChannelIntentionRecord | undefined;
1259
- holdIntentionForWindow(questionId: string, owner: string): boolean;
1260
- releaseWindowHeldIntentions(binding: Pick<ChannelBinding, 'channel' | 'conversationKey' | 'agentTypeId' | 'bindingVersion'>): void;
1261
- ownsIntentionClaim(questionId: string, owner: string): boolean;
1262
- renewIntentionClaim(questionId: string, owner: string, ttlMs?: number): boolean;
1263
- completeIntentionProjection(questionId: string, owner: string): boolean;
1264
- claimIntentionReply(intention: ChannelIntentionRecord, providerMessageId: string, values: Readonly<Record<string, unknown>>, owner: string, ttlMs?: number): ClaimIntentionReplyResult;
1265
- claimRecoverableIntentionAnswer(questionId: string, owner: string, ttlMs?: number): ChannelIntentionRecord | undefined;
1266
- completeIntentionAnswer(questionId: string, owner: string): boolean;
1267
- reconcileIntentionAnswered(questionId: string): void;
1268
- reconcileIntentionClosed(questionId: string): void;
1269
- claimInvalidIntentionReply(intention: ChannelIntentionRecord, providerMessageId: string, owner: string, ttlMs?: number): ClaimInvalidIntentionReplyResult;
1270
- completeInvalidIntentionReply(channel: string, providerMessageId: string, owner: string): boolean;
1271
- pendingInvalidIntentionReplies(): Array<{
1272
- intention: ChannelIntentionRecord;
1273
- providerMessageId: string;
1274
- retryAt: number;
1275
- }>;
1276
- hasIntentionReply(channel: string, providerMessageId: string): boolean;
1277
- claimOutbound(binding: ChannelBinding, owner: string, claimTtlMs?: number): boolean;
1278
- outboundClaimRetryAt(binding: ChannelBinding): number | undefined;
1279
- ownsOutboundClaim(owner: string): boolean;
1280
- renewOutbound(owner: string, claimTtlMs?: number): boolean;
1281
- releaseOutbound(owner: string): void;
1282
- parkOutboundBinding(binding: ChannelBinding, claimOwner: string, errorCode: string): boolean;
1283
- compareAndSetOutboundCursor(binding: ChannelBinding, claimOwner: string, nextCursor: string): boolean;
1284
- markTemplateSent(binding: ChannelBinding, claimOwner: string): boolean;
1285
- parkOutbound(binding: ChannelBinding, claimOwner: string, terminalOffset: string, errorCode: string): boolean;
1286
- acknowledgeSessionReset(binding: ChannelBinding, claimOwner: string): boolean;
1287
- markSessionGone(binding: ChannelBinding, claimOwner: string): boolean;
1288
- pendingBindings(): ChannelBinding[];
1289
- nextPending(channel: string, conversationKey: string, agentTypeId: string, claimOwner: string, claimTtlMs?: number): NextInboundResult;
1290
- renewInbound(id: number, claimOwner: string, claimTtlMs?: number): boolean;
1291
- completeInbound(id: number, claimOwner: string): boolean;
1292
- retryInbound(id: number, claimOwner: string, errorCode: string): void;
1293
- parkInbound(id: number, errorCode: string, claimOwner?: string): void;
1294
- getInbound(id: number): QueuedChannelInbound | undefined;
1295
- ensureSession(binding: ChannelBinding, options: EnsureSessionOptions): Promise<{
1296
- sessionKey: string;
1297
- created: boolean;
1298
- }>;
1299
- private readCreation;
1300
- private claimCreation;
1301
- private transitionCreation;
1302
- private finishCreation;
1303
- private recoverAdmitting;
1304
- }
1305
-
1306
- declare const CHANNEL_UNKNOWN_BINDING: "CHANNEL_UNKNOWN_BINDING";
1307
- declare const CHANNEL_INBOUND_PARKED: "CHANNEL_INBOUND_PARKED";
1308
- interface ChannelAdapter {
1309
- readonly channelId: string;
1310
- parseInbound(request: Request): Promise<readonly InboundChannelMessage[]>;
1311
- renderOutbound(turn: unknown): readonly unknown[];
1312
- send(message: unknown): Promise<void>;
1313
- }
1314
- /**
1315
- * Trusted, host-injected seam. Implementations resolve workspace membership
1316
- * from the binding and never receive the adapter-owned conversation key.
1317
- */
1318
- interface ChannelAgentInvoker {
1319
- createSession(input: {
1320
- readonly workspaceId: string;
1321
- readonly authSubjectId: string;
1322
- readonly agentTypeId: string;
1323
- readonly originChannel: OriginChannel;
1324
- /** Stable opaque id for replaying this binding generation's allocation. */
1325
- readonly requestId: string;
1326
- }): Promise<string>;
1327
- isSessionBusy(input: {
1328
- readonly workspaceId: string;
1329
- readonly authSubjectId: string;
1330
- readonly agentTypeId: string;
1331
- readonly sessionKey: string;
1332
- }): Promise<boolean>;
1333
- /**
1334
- * Implementations MUST durably deduplicate requestId and serialize
1335
- * deliverySequence for a session before resolving. This is the downstream
1336
- * fence that makes an expired queue lease safe to replay.
1337
- */
1338
- prompt(input: ChannelAgentInvocation): Promise<void>;
1339
- /** Same durable idempotency and sequence contract as prompt. */
1340
- followUp(input: ChannelAgentInvocation): Promise<void>;
1341
- }
1342
- interface ChannelAgentInvocation {
1343
- readonly workspaceId: string;
1344
- readonly authSubjectId: string;
1345
- readonly agentTypeId: string;
1346
- readonly sessionKey: string;
1347
- readonly requestId: string;
1348
- /** Monotonic durable queue id; stale/lower deliveries must be a no-op. */
1349
- readonly deliverySequence: number;
1350
- readonly text: string;
1351
- }
1352
- type ChannelInboundAck = {
1353
- readonly accepted: true;
1354
- readonly duplicate: boolean;
1355
- readonly code: typeof ErrorCode.enum.CHANNEL_INBOUND_ACCEPTED;
1356
- } | {
1357
- readonly accepted: false;
1358
- readonly duplicate: boolean;
1359
- readonly code: typeof CHANNEL_UNKNOWN_BINDING;
1360
- };
1361
- declare class ChannelInboundService {
1362
- private readonly store;
1363
- private readonly invoker;
1364
- private readonly options;
1365
- private readonly drains;
1366
- private readonly retryTimers;
1367
- private readonly claimOwner;
1368
- private disposed;
1369
- constructor(store: ChannelBindingStore, invoker: ChannelAgentInvoker, options?: {
1370
- readonly maxAttempts?: number;
1371
- readonly inboundClaimTtlMs?: number;
1372
- readonly drainRetryMs?: number;
1373
- /** Called after durable completion, including work resumed at startup. */
1374
- readonly onInboundDelivered?: (binding: ChannelBinding) => void;
1375
- });
1376
- /** Durable enqueue is the acknowledgement boundary; agent work stays async. */
1377
- accept(message: InboundChannelMessage, agentTypeId: string): ChannelInboundAck;
1378
- waitForIdle(): Promise<void>;
1379
- dispose(): Promise<void>;
1380
- resume(binding: ChannelBinding): void;
1381
- private scheduleDrain;
1382
- private drain;
1383
- }
1384
-
1385
- interface ChannelIntentionOption {
1386
- readonly value: string;
1387
- readonly label: string;
1388
- readonly description?: string;
1389
- }
1390
- interface ChannelIntentionQuestion {
1391
- readonly questionId: string;
1392
- readonly sessionId: string;
1393
- readonly ownerPrincipalId: string;
1394
- readonly status: 'ready' | 'answered' | 'cancelled' | 'abandoned';
1395
- readonly title?: string;
1396
- readonly context?: string;
1397
- readonly schema?: {
1398
- readonly wireVersion: 1;
1399
- readonly fields: readonly ChannelIntentionField[];
1400
- };
1401
- }
1402
- type ChannelIntentionField = {
1403
- readonly type: string;
1404
- readonly name: string;
1405
- readonly label: string;
1406
- readonly options?: readonly ChannelIntentionOption[];
1407
- };
1408
- interface ChannelIntentionRuntime {
1409
- /** Trusted workspace scope owning this ask_user store. */
1410
- readonly workspaceId: string;
1411
- listPending(): Promise<readonly ChannelIntentionQuestion[]>;
1412
- getByQuestionId(questionId: string): Promise<ChannelIntentionQuestion | null>;
1413
- submitAnswer(questionId: string, sessionId: string, values: Readonly<Record<string, string>>): Promise<unknown>;
1414
- subscribe(listener: () => void): () => void;
1415
- }
1416
- interface ChannelIntentionSource {
1417
- listPending(): Promise<readonly ChannelIntentionQuestion[]>;
1418
- getByQuestionId(questionId: string): Promise<ChannelIntentionQuestion | null>;
1419
- subscribe(listener: (...args: readonly unknown[]) => void): () => void;
1420
- }
1421
- /** Adapts the real ask_user store/runtime pair without introducing a package cycle. */
1422
- declare function createChannelIntentionRuntime(workspaceId: string, source: ChannelIntentionSource, answers: Pick<ChannelIntentionRuntime, 'submitAnswer'>): ChannelIntentionRuntime;
1423
- interface ChannelIntentionAdapter {
1424
- readonly serviceWindowMs?: number;
1425
- send(input: {
1426
- readonly conversationKey: string;
1427
- readonly text: string;
1428
- }): Promise<void>;
1429
- sendWindowTemplate?(input: {
1430
- readonly conversationKey: string;
1431
- }): Promise<void>;
1432
- }
1433
- type ChannelIntentionAck = {
1434
- readonly handled: false;
1435
- } | {
1436
- readonly handled: true;
1437
- readonly accepted: boolean;
1438
- readonly duplicate: boolean;
1439
- readonly questionId?: string;
1440
- };
1441
- type ChannelMessageAck = {
1442
- readonly kind: 'intention';
1443
- readonly ack: Exclude<ChannelIntentionAck, {
1444
- handled: false;
1445
- }>;
1446
- } | {
1447
- readonly kind: 'agent';
1448
- readonly ack: ChannelInboundAck;
1449
- };
1450
- interface ChannelIntentionServiceOptions {
1451
- readonly claimTtlMs?: number;
1452
- readonly retryDelayMs?: number;
1453
- }
1454
- /**
1455
- * Projects answerable ask_user questions to a bound channel and routes one
1456
- * reply back into the same durable Human Intention. The runtime is an injected
1457
- * seam so the channel core does not depend on the ask-user plugin package.
1458
- */
1459
- declare class ChannelIntentionService {
1460
- private readonly store;
1461
- private readonly runtime;
1462
- private readonly adapters;
1463
- private readonly options;
1464
- private readonly owner;
1465
- private scan?;
1466
- private rescan;
1467
- private timer?;
1468
- private unsubscribe?;
1469
- private disposed;
1470
- constructor(store: ChannelBindingStore, runtime: ChannelIntentionRuntime, adapters: ReadonlyMap<string, ChannelIntentionAdapter>, options?: ChannelIntentionServiceOptions);
1471
- start(): void;
1472
- waitForIdle(): Promise<void>;
1473
- dispose(): Promise<void>;
1474
- notifyInbound(binding: {
1475
- channel: string;
1476
- conversationKey: string;
1477
- agentTypeId: string;
1478
- bindingVersion: number;
1479
- }): void;
1480
- accept(message: InboundChannelMessage, agentTypeId: string): Promise<ChannelIntentionAck>;
1481
- private schedule;
1482
- private scanOnce;
1483
- private consumeAnswer;
1484
- private armRetry;
1485
- }
1486
- /** Canonical ingress composition: approval replies never fall through to the agent prompt queue. */
1487
- declare class ChannelMessageRouter {
1488
- private readonly intentions;
1489
- private readonly inbound;
1490
- constructor(intentions: ChannelIntentionService, inbound: ChannelInboundService);
1491
- accept(message: InboundChannelMessage, agentTypeId: string): Promise<ChannelMessageAck>;
1492
- }
1493
-
1494
- declare const CHANNEL_OUTBOUND_PARKED: "CHANNEL_OUTBOUND_PARKED";
1495
- declare const CHANNEL_TURN_STALLED: "CHANNEL_TURN_STALLED";
1496
- interface ChannelOutboundTurn {
1497
- readonly turnId: string;
1498
- readonly status: 'ok' | 'aborted' | 'error' | 'stalled';
1499
- readonly text: string;
1500
- }
1501
- interface ChannelOutboundAdapter<Message = unknown> {
1502
- /** Adapter-owned delivery constraint; omit for channels without a service window. */
1503
- readonly serviceWindowMs?: number;
1504
- renderOutbound(turn: ChannelOutboundTurn): readonly Message[];
1505
- send(input: {
1506
- readonly conversationKey: string;
1507
- readonly message: Message;
1508
- }): Promise<void>;
1509
- sendWindowTemplate?(input: {
1510
- readonly conversationKey: string;
1511
- }): Promise<void>;
1512
- }
1513
- interface ChannelOutboundRuntime {
1514
- /** Returns undefined only when the persisted session no longer exists. */
1515
- resolveStreamPath(binding: ChannelBinding): Promise<string | undefined>;
1516
- createSession(binding: ChannelBinding): Promise<string>;
1517
- }
1518
- interface ChannelOutboundServiceOptions {
1519
- readonly maxSendAttempts?: number;
1520
- readonly retryDelayMs?: number;
1521
- readonly stallTimeoutMs?: number;
1522
- readonly outboundClaimTtlMs?: number;
1523
- readonly now?: () => number;
1524
- }
1525
- interface AssembledTurn {
1526
- readonly turn: ChannelOutboundTurn;
1527
- readonly terminalOffset: string;
1528
- }
1529
- declare class ChannelOutboundService<Message = unknown> {
1530
- private readonly store;
1531
- private readonly events;
1532
- private readonly runtime;
1533
- private readonly adapters;
1534
- private readonly options;
1535
- private readonly drains;
1536
- private readonly pendingDrains;
1537
- private readonly subscriptions;
1538
- private readonly stallTimers;
1539
- private readonly claimTimers;
1540
- private disposed;
1541
- constructor(store: ChannelBindingStore, events: EventStreamStore, runtime: ChannelOutboundRuntime, adapters: ReadonlyMap<string, ChannelOutboundAdapter<Message>>, options?: ChannelOutboundServiceOptions);
1542
- start(): void;
1543
- notifyInbound(binding: ChannelBinding): void;
1544
- waitForIdle(): Promise<void>;
1545
- dispose(): Promise<void>;
1546
- private schedule;
1547
- private drain;
1548
- private readUnreadEvents;
1549
- private scheduleClaimRetry;
1550
- private ensureSubscription;
1551
- private scheduleStall;
1552
- private clearStall;
1553
- private sendWindowTemplate;
1554
- private sendWithRetry;
1555
- private resolveStreamPath;
1556
- private current;
1557
- private isInsideServiceWindow;
1558
- private stallTimeoutMs;
1559
- private now;
1560
- }
1561
- declare function assembleNextTurn(entries: ReadonlyArray<{
1562
- data: unknown;
1563
- offset: string;
1564
- }>, now?: number, stallTimeoutMs?: number): AssembledTurn | undefined;
1565
- declare function shapeChannelText(text: string, dialect: string, maxLength?: number): string[];
1566
-
1567
- declare const CHANNELS_ENV_FLAG = "BORING_AGENT_CHANNELS";
1568
- declare const CHANNEL_DURABLE_STREAM_REQUIRED: "CHANNEL_DURABLE_STREAM_REQUIRED";
1569
- declare function areChannelsEnabled(): boolean;
1570
- declare function assertChannelDurability(durableStreamEnabled: boolean): void;
1571
-
1572
- interface AgentHostEnvironmentHttpProjectionOptions {
1573
- readonly created: CreatedAgentHost;
1574
- readonly authorizeAgentRequest: (request: FastifyRequest) => Promise<AuthorizedAgentScope>;
1575
- readonly runtimeHost?: AgentRuntimeHostOperations;
1576
- readonly getWorkspaceHostRoot?: (request: FastifyRequest) => string | undefined | Promise<string | undefined>;
1577
- }
1578
- /**
1579
- * Mount application-owned filesystem routes over finite Host Environment leases.
1580
- * The FS event stream explicitly retains its lease until the transport closes.
1581
- */
1582
- declare function registerAgentHostEnvironmentRoutes(app: FastifyInstance, options: AgentHostEnvironmentHttpProjectionOptions): Promise<void>;
1583
-
1584
- interface EnvironmentProvisioningSnapshot {
1585
- readonly changed: boolean;
1586
- readonly env: Readonly<Record<string, string>>;
1587
- readonly pathEntries: readonly string[];
1588
- readonly skillPaths: readonly string[];
1589
- }
1590
- interface EnvironmentLease {
1591
- /** Opaque immutable identity for this exact provider/provisioning generation. */
1592
- readonly generationId: string;
1593
- readonly bundle: RuntimeBundle;
1594
- /** One immutable Environment-owned snapshot shared by every compatible Agent binding. */
1595
- readonly provisioning?: EnvironmentProvisioningSnapshot;
1596
- readonly signal: AbortSignal;
1597
- /** Retains this exact generation; never resolves the workspace's current generation. */
1598
- retain(): EnvironmentLease;
1599
- release(): void;
1600
- retire(): Promise<void>;
1601
- }
1602
-
1603
- /** Workspace-scoped addressing. Pi-native identities remain adapter-private. */
1604
- interface HarnessSessionAddress {
1605
- readonly workspaceScopeId: string;
1606
- readonly ref: AgentSessionRef;
1607
- }
1608
- interface HarnessAgentScope {
1609
- readonly workspaceScopeId: string;
1610
- readonly agentTypeId: string;
1611
- }
1612
- /** Attribution only: authSubjectId is never session-storage ownership. */
1613
- interface HarnessRequestContext {
1614
- readonly requestId: string;
1615
- readonly authSubjectId: string;
1616
- }
1617
- type HarnessWatchResult = {
1618
- readonly type: 'ok';
1619
- unsubscribe(): void;
1620
- readonly closed?: Promise<void>;
1621
- } | {
1622
- readonly type: 'replay_gap' | 'cursor_ahead';
1623
- readonly latestSeq: number;
1624
- readonly minReplaySeq: number;
1625
- };
1626
- /**
1627
- * Private D29 runtime seam. The Gateway ledger is the sole idempotency
1628
- * authority; callers may retry only after ledger admission.
1629
- */
1630
- interface AgentHarnessBackend {
1631
- listSessions(scope: HarnessAgentScope, ctx: HarnessRequestContext, options?: SessionListOptions): Promise<SessionSummary[]>;
1632
- createSession(scope: HarnessAgentScope, ctx: HarnessRequestContext, init?: SessionCreateInit): Promise<SessionSummary>;
1633
- readSnapshot(address: HarnessSessionAddress, ctx: HarnessRequestContext): Promise<PiChatSnapshot>;
1634
- watchEvents(address: HarnessSessionAddress, ctx: HarnessRequestContext, cursor: number, subscriber: (event: PiChatEvent) => void): Promise<HarnessWatchResult>;
1635
- submitPrompt(address: HarnessSessionAddress, ctx: HarnessRequestContext, payload: AgentPromptPayload): Promise<PromptReceipt>;
1636
- submitFollowUp(address: HarnessSessionAddress, ctx: HarnessRequestContext, payload: FollowUpPayload): Promise<FollowUpReceipt>;
1637
- clearQueue(address: HarnessSessionAddress, ctx: HarnessRequestContext, payload: QueueClearPayload): Promise<QueueClearReceipt>;
1638
- interrupt(address: HarnessSessionAddress, ctx: HarnessRequestContext, payload: InterruptPayload): Promise<CommandReceipt>;
1639
- stop(address: HarnessSessionAddress, ctx: HarnessRequestContext, payload: StopPayload): Promise<StopReceipt>;
1640
- renameSession(address: HarnessSessionAddress, ctx: HarnessRequestContext, title: string): Promise<SessionSummary>;
1641
- deleteSession(address: HarnessSessionAddress, ctx: HarnessRequestContext): Promise<void>;
1642
- readAttachment(address: HarnessSessionAddress, ctx: HarnessRequestContext, messageId: string, index: number): Promise<PiChatAttachmentResult>;
1643
- close(): Promise<void>;
1644
- }
1645
-
1646
- type PiLlmAuthKindV1 = 'api-key' | 'oauth';
1647
- interface PiDerivedLlmProviderV1 {
1648
- readonly providerId: ProviderId;
1649
- readonly displayName: string;
1650
- /** Auth kinds pi supports for this provider; metadata for later slices. */
1651
- readonly authKinds: readonly PiLlmAuthKindV1[];
1652
- readonly egressOrigins: readonly `https://${string}`[];
1653
- readonly bindingId: CredentialConsumerBindingId;
1654
- }
1655
- /**
1656
- * Narrowed per-binding surface. Runtime bindings only ever see registries and
1657
- * the pre-bound resolver; the raw vault backend (plaintext write path) and
1658
- * resolver minting stay host-scope-only on the full composition.
1659
- */
1660
- interface WorkspaceCredentialRuntimeViewV1 {
1661
- readonly providerRegistry: ProviderRegistryV1;
1662
- readonly bindingRegistry: CredentialConsumerBindingRegistryV1;
1663
- readonly catalog: readonly PiDerivedLlmProviderV1[];
1664
- readonly skippedProviderIds: readonly string[];
1665
- /** Present when an authority verifier was supplied at composition time. */
1666
- readonly resolver?: WorkspaceCredentialResolverV1;
1667
- /** Actor-bound Pi credential store; workspace identity is fixed at construction. */
1668
- createPiCredentialStore(workspaceId: string, userId: string | undefined, options: {
1669
- readonly allowSubscriptionOAuth: boolean;
1670
- readonly revokedOAuthReplacementVersion?: number;
1671
- }): CredentialStore;
1672
- }
1673
-
1674
- interface BuiltAgentComposition {
1675
- readonly harness: AgentHarness;
1676
- readonly sessionStore: SessionStore;
1677
- readonly backend: AgentHarnessBackend;
1678
- readonly tools: readonly AgentTool[];
1679
- readonly pi: ResolvedPiHarnessOptions;
1680
- readonly runtimeBundle: RuntimeBundle;
1681
- readonly readyTracker: ReadyStatusTracker;
1682
- readonly getFilesystemBindings?: (ctx: {
1683
- sessionId?: string;
1684
- userId?: string;
1685
- requestId?: string;
1686
- }) => Promise<readonly RuntimeFilesystemBinding[]>;
1687
- /**
1688
- * [1082 slice B] Narrowed per-binding credential view (registries + the
1689
- * pre-bound resolver). Present only when `BORING_CREDENTIAL_KMS_BACKEND`
1690
- * selected a backend at host startup. The raw vault backend and resolver
1691
- * minting stay on the host-scope composition and are deliberately not
1692
- * exposed here.
1693
- */
1694
- readonly credentials?: WorkspaceCredentialRuntimeViewV1;
1695
- dispose(): Promise<void>;
1696
- }
1697
-
1698
- interface AgentSessionActivityUpdate {
1699
- readonly ref: AgentSessionRef;
1700
- readonly status: AgentSessionActivity;
1701
- }
1702
- /** Process-lifetime live-turn projection. Reads never create activity rows. */
1703
- declare class AgentSessionActivityIndex {
1704
- private readonly activity;
1705
- private readonly subscribers;
1706
- get(workspaceScopeId: string, ref: AgentSessionRef): AgentSessionActivity;
1707
- set(workspaceScopeId: string, ref: AgentSessionRef, status: AgentSessionActivity): void;
1708
- snapshot(workspaceScopeId: string): AgentSessionActivityUpdate[];
1709
- subscribe(workspaceScopeId: string, subscriber: (update: AgentSessionActivityUpdate) => void): () => void;
1710
- delete(workspaceScopeId: string, ref: AgentSessionRef): void;
1711
- observe(workspaceScopeId: string, ref: AgentSessionRef, event: PiChatEvent): void;
1712
- }
1713
-
1714
- interface RuntimeBinding {
1715
- readonly key: string;
1716
- readonly agentTypeId: string;
1717
- readonly workspaceScopeId: string;
1718
- readonly authSubjectId: string;
1719
- readonly fundingPolicy: AgentInvocationFundingPolicyV1;
1720
- readonly generation: number;
1721
- readonly scope: ResolvedAgentRuntimeScope;
1722
- readonly environmentLease: EnvironmentLease;
1723
- readonly composition: BuiltAgentComposition;
1724
- }
1725
- interface AgentHostRuntime {
1726
- readonly options: CreateAgentHostOptions;
1727
- readonly compiledAgents: readonly CompiledAgentHostAgentSpec[];
1728
- readonly compiledById: ReadonlyMap<string, CompiledAgentHostAgentSpec>;
1729
- readonly ledger: AgentRequestLedger;
1730
- readonly effectAdmission: AgentEffectAdmission;
1731
- readonly activity: AgentSessionActivityIndex;
1732
- readonly shutdownGraceMs: number;
1733
- listSessionSummaries(agentTypeId: string, scope: AuthorizedAgentScope, claim: VerifiedAgentScopeClaim, options?: SessionListOptions): Promise<readonly SessionSummary[]>;
1734
- setSessionArchived?(agentTypeId: string, scope: AuthorizedAgentScope, claim: VerifiedAgentScopeClaim, sessionId: string, archived: boolean): Promise<SessionSummary>;
1735
- isDraining(): boolean;
1736
- assertOpen(): void;
1737
- verify(scope: AuthorizedAgentScope): Promise<VerifiedAgentScopeClaim>;
1738
- resolveAgentAccess?(agentTypeId: string, scope: AuthorizedAgentScope, claim: VerifiedAgentScopeClaim, operation: AgentAccessOperation): Promise<AgentAccessDecision>;
1739
- assertAgentAccess?(agentTypeId: string, scope: AuthorizedAgentScope, claim: VerifiedAgentScopeClaim, operation: AgentAccessOperation): Promise<void>;
1740
- resolveEnvironmentScope(scope: AuthorizedAgentScope, claim: VerifiedAgentScopeClaim, intent: AuthorizedEnvironmentIntent): Promise<AgentHostEnvironmentScope>;
1741
- acquireEnvironment(scope: AuthorizedAgentScope, claim: VerifiedAgentScopeClaim, intent: AuthorizedEnvironmentIntent): Promise<EnvironmentLease>;
1742
- acquireResolvedEnvironment(workspaceScopeId: string, environment: AgentHostEnvironmentScope): Promise<EnvironmentLease>;
1743
- resolveSessionRuntime(agentTypeId: string, scope: AuthorizedAgentScope, claim: VerifiedAgentScopeClaim, sessionId: string): Promise<ResolvedAgentRuntimeScope | undefined>;
1744
- resolveAgentRuntimeScope(agentTypeId: string, scope: AuthorizedAgentScope, claim: VerifiedAgentScopeClaim, operation: 'new-binding' | 'existing-session' | 'reload', requestId: string, sessionId?: string): Promise<ResolvedAgentRuntimeScope>;
1745
- resolveBinding(agentTypeId: string, scope: AuthorizedAgentScope, claim: VerifiedAgentScopeClaim, resolvedRuntimeScope?: ResolvedAgentRuntimeScope, fundingPolicy?: AgentInvocationFundingPolicyV1): Promise<RuntimeBinding>;
1746
- findPublishedCurrentBinding(agentTypeId: string, workspaceScopeId: string, authSubjectId: string, physicalBindingIdentity: string, bindingIdentity?: string, provisioningFingerprint?: string, fundingPolicy?: AgentInvocationFundingPolicyV1): RuntimeBinding | undefined;
1747
- startDrain(): void;
1748
- drainRuntime(): Promise<void>;
1749
- registerSubscription(close: () => void | Promise<void>): () => void;
1750
- startPreparedEffect<T>(key: AgentRequestKey, effect: () => Promise<T>): Promise<T>;
1751
- runBindingOperation<T>(bindingKey: string, operation: () => Promise<T>): Promise<T>;
1752
- closeRuntime(): Promise<void>;
1753
- }
1754
- declare function createAgentHost(options: CreateAgentHostOptions): Promise<CreatedAgentHost>;
1755
-
1756
- declare const CHANNEL_RUNTIME_FILE_NAME = ".agent-channel-runtime.sqlite";
1757
- interface AgentHostChannelStorage {
1758
- readonly bindings: ChannelBindingStore;
1759
- readonly events: EventStreamStore;
1760
- close(): void;
1761
- }
1762
- /**
1763
- * Opens the host-owned durable state shared by Agent Host event production and
1764
- * channel delivery. App hosts pass `events` to their Agent Host composition and
1765
- * the complete storage handle to {@link createAgentHostChannelRuntime}.
1766
- */
1767
- declare function createAgentHostChannelStorage(input: {
1768
- readonly sessionRoot: string;
1769
- readonly fileName?: string;
1770
- }): AgentHostChannelStorage;
1771
- interface CreateAgentHostChannelRuntimeOptions<Message> {
1772
- readonly gateway: AgentGateway;
1773
- readonly storage: AgentHostChannelStorage;
1774
- /** Reissues an app-owned capability after validating the durable binding. */
1775
- readonly resolveAuthorizedScope: (binding: Pick<ChannelBinding, 'workspaceId' | 'authSubjectId' | 'agentTypeId'>) => Promise<AuthorizedAgentScope>;
1776
- readonly outboundAdapters: ReadonlyMap<string, ChannelOutboundAdapter<Message>>;
1777
- /** Workspace-scoped ask_user source/answer seam; omit only when channels cannot ask owners. */
1778
- readonly intentionRuntime?: ChannelIntentionRuntime;
1779
- readonly outbound?: ChannelOutboundServiceOptions;
1780
- }
1781
- interface AgentHostChannelRuntime<Message> {
1782
- readonly bindings: ChannelBindingStore;
1783
- readonly events: EventStreamStore;
1784
- readonly outboundAdapters: ReadonlyMap<string, ChannelOutboundAdapter<Message>>;
1785
- provision(input: ProvisionChannelBindingInput): ChannelBinding;
1786
- /** Durable enqueue is the acknowledgement boundary; delivery continues asynchronously. */
1787
- acceptInbound(message: InboundChannelMessage, agentTypeId: string): ReturnType<ChannelInboundService['accept']> | ReturnType<ChannelMessageRouter['accept']>;
1788
- waitForIdle(): Promise<void>;
1789
- close(): Promise<void>;
1790
- }
1791
- /**
1792
- * Concrete, provider-neutral app-host composition for channel state, session
1793
- * invocation, durable event tails, outbound adapter lookup, restart recovery,
1794
- * and lifecycle disposal. Provider packages only supply adapters and webhook
1795
- * parsing; they never own workspace authority or durable state.
1796
- */
1797
- declare function createAgentHostChannelRuntime<Message>(options: CreateAgentHostChannelRuntimeOptions<Message>): AgentHostChannelRuntime<Message>;
1798
-
1799
- declare const MIN_REQUEST_RETENTION_MS: number;
1800
- interface SqliteAgentRequestLedgerOptions {
1801
- /** Terminal payload retention. Values below 24 hours are raised to the minimum. */
1802
- readonly retentionMs?: number;
1803
- /** Injectable clock for deterministic storage tests. */
1804
- readonly now?: () => number;
1805
- }
1806
- /** SQLite-backed atomic ownership/CAS ledger for direct and production projections. */
1807
- declare class SqliteAgentRequestLedger implements AgentRequestLedger {
1808
- readonly durability: "durable-transactional";
1809
- private readonly database;
1810
- private readonly now;
1811
- private readonly retentionMs;
1812
- constructor(path: string, options?: SqliteAgentRequestLedgerOptions);
1813
- prepare(key: AgentRequestKey, digest: string, acceptedWork: AcceptedWorkContext): Promise<AgentRequestLedgerPrepareResult>;
1814
- markAdmissionRetryable(key: AgentRequestKey): Promise<void>;
1815
- acceptAdmission(key: AgentRequestKey, admissionReceipt: string): Promise<void>;
1816
- beginEffect(key: AgentRequestKey): Promise<void>;
1817
- reject(key: AgentRequestKey, failure: AgentRequestFailure): Promise<void>;
1818
- complete(key: AgentRequestKey, receipt: JsonValue): Promise<void>;
1819
- markOutcomeUnknown(key: AgentRequestKey, error: AgentGatewayErrorDTO): Promise<void>;
1820
- read(key: AgentRequestKey): Promise<AgentRequestLedgerRecord | undefined>;
1821
- close(): void;
1822
- private migrateLegacyAcceptedWork;
1823
- private readSync;
1824
- private readActiveSync;
1825
- private readTombstoneSync;
1826
- private pruneExpiredTerminalRows;
1827
- private immediateTransaction;
1828
- private transition;
1829
- }
1830
-
1831
- /**
1832
- * Compatibility location a host falls back to when it has neither an explicit
1833
- * ledger path nor a host-owned session root.
1834
- *
1835
- * Hosts historically disagreed on this tail, so it is the *only* part of the
1836
- * chain that is parameterized. Everything before it is identical for every
1837
- * host and is owned solely by {@link resolveRequestLedgerPath}.
1838
- */
1839
- type LegacyRequestLedgerLocation =
1840
- /** `<workspaceRoot>/.boring/agent-request-ledger.sqlite` (standalone + workspace hosts). */
1841
- {
1842
- readonly layout: 'workspace-boring-dir';
1843
- readonly workspaceRoot: string;
1844
- }
1845
- /** `<workspaceRoot>/.agent-request-ledger.sqlite` (core workspace host). */
1846
- | {
1847
- readonly layout: 'workspace-host-file';
1848
- readonly workspaceRoot: string;
1849
- };
1850
- interface ResolveRequestLedgerPathInput {
1851
- /** Explicit host-configured ledger file. Wins over every fallback. */
1852
- readonly requestLedgerPath?: string;
1853
- /** Host-owned session root supplied by the caller, if any. */
1854
- readonly sessionRoot?: string;
1855
- /**
1856
- * Also accept `BORING_AGENT_SESSION_ROOT` as a host-owned root when the
1857
- * caller supplied no `sessionRoot`. Hosts that already fold that env var
1858
- * into their own session-root chain omit this.
1859
- */
1860
- readonly acceptSessionRootEnv?: boolean;
1861
- /**
1862
- * Last-resort compatibility location. Omit for hosts that must fail closed
1863
- * instead of inventing an in-workspace ledger; they get `undefined`.
1864
- */
1865
- readonly legacy?: LegacyRequestLedgerLocation;
1866
- }
1867
- /**
1868
- * Resolve the durable request ledger file for an agent host.
1869
- *
1870
- * **Ledger cutover note:** adopting BORING_AGENT_SESSION_ROOT (or an
1871
- * explicit requestLedgerPath) after running with the legacy in-workspace
1872
- * location RELOCATES the sqlite ledger. Effect-idempotency keys recorded
1873
- * at the legacy path are stranded there; retries that span the upgrade
1874
- * may be re-admitted once against the new ledger. Copy or drain the
1875
- * legacy file as part of the cutover if exactly-once effects must
1876
- * survive it.
1877
- *
1878
- * The request ledger is host application state, not workspace content, so the
1879
- * chain prefers host-owned storage: explicit option, then the caller's
1880
- * `sessionRoot` (optionally `BORING_AGENT_SESSION_ROOT`), and only then the
1881
- * host's legacy in-workspace location.
1882
- *
1883
- * This is the sole owner of that chain: no host may re-encode any part of it.
1884
- */
1885
- declare function resolveRequestLedgerPath(input: ResolveRequestLedgerPathInput & {
1886
- readonly legacy: LegacyRequestLedgerLocation;
1887
- }): string;
1888
- declare function resolveRequestLedgerPath(input: ResolveRequestLedgerPathInput): string | undefined;
1889
-
1890
- declare const AgentFleetCompilationErrorCode: {
1891
- readonly AGENT_FLEET_PLUGIN_UNKNOWN: "AGENT_FLEET_PLUGIN_UNKNOWN";
1892
- readonly AGENT_FLEET_CONFIG_BINDING_UNKNOWN: "AGENT_FLEET_CONFIG_BINDING_UNKNOWN";
1893
- readonly AGENT_FLEET_MODEL_POLICY_UNCOMPILED: "AGENT_FLEET_MODEL_POLICY_UNCOMPILED";
1894
- };
1895
- type AgentFleetCompilationErrorCode = (typeof AgentFleetCompilationErrorCode)[keyof typeof AgentFleetCompilationErrorCode];
1896
- declare class AgentFleetCompilationError extends Error {
1897
- readonly code: AgentFleetCompilationErrorCode;
1898
- readonly details: Readonly<Record<string, string>>;
1899
- constructor(code: AgentFleetCompilationErrorCode, message: string, details: Readonly<Record<string, string>>);
1900
- }
1901
- interface AgentFleetPluginBindingContract {
1902
- readonly id: string;
1903
- readonly configKeys?: readonly string[];
1904
- }
1905
- interface CreateValidatingAgentFleetCompilerOptions {
1906
- readonly plugins: readonly AgentFleetPluginBindingContract[];
1907
- readonly compiler?: AgentFleetCompiler;
1908
- /**
1909
- * Keeps Core's existing fail-closed policy when it has no app compiler.
1910
- * This is not model allowlist validation.
1911
- */
1912
- readonly requireCompilerForModelPolicy?: boolean;
1913
- }
1914
- /**
1915
- * The one reusable fleet binding-validation funnel. Apps supply only their
1916
- * already-resolved plugin contracts and optional stricter policy compiler.
1917
- */
1918
- declare function createValidatingAgentFleetCompiler(options: CreateValidatingAgentFleetCompilerOptions): AgentFleetCompiler;
1919
-
1920
- declare class EmbeddedAgentGateway implements AgentGateway {
1921
- private readonly runtime;
1922
- private readonly sessionInventoryPager;
1923
- private readonly connections;
1924
- private readonly writerTails;
1925
- private readonly knownSessions;
1926
- private closed;
1927
- constructor(runtime: AgentHostRuntime);
1928
- /** Host-owned addressed runtime-capability effect seam. */
1929
- runHostEffect(input: {
1930
- readonly scope: AuthorizedAgentScope;
1931
- readonly operation: 'agent.reload' | 'session.command.execute';
1932
- readonly target: AgentRequestTarget;
1933
- readonly requestId: string;
1934
- readonly payload: JsonValue;
1935
- readonly action: () => Promise<JsonValue>;
1936
- readonly classify?: () => Promise<{
1937
- readonly kind: 'execute';
1938
- } | {
1939
- readonly kind: 'reject';
1940
- readonly error: AgentGatewayErrorDTO;
1941
- }>;
1942
- }): Promise<JsonValue>;
1943
- /** Host-internal resolver shared by every session-bearing capability route. */
1944
- resolveHostSessionBinding(scope: AuthorizedAgentScope, ref: AgentSessionRef): Promise<{
1945
- claim: VerifiedAgentScopeClaim;
1946
- binding: RuntimeBinding;
1947
- }>;
1948
- /** Side-effect-free reload lookup: validates session access and requires the current binding to be published. */
1949
- inspectPublishedSessionBinding(scope: AuthorizedAgentScope, ref: AgentSessionRef): Promise<{
1950
- claim: VerifiedAgentScopeClaim;
1951
- binding: RuntimeBinding;
1952
- }>;
1953
- /** Test-only activity seam used by the shared implementation conformance. */
1954
- setActivityForTesting(workspaceScopeId: string, ref: AgentSessionRef, activity: AgentSessionActivity): void;
1955
- private assertOpen;
1956
- private verify;
1957
- private resolveAgentAccess;
1958
- private throwForAgentAccessDecision;
1959
- private assertAgentAccess;
1960
- authorizeAgentAccess(input: {
1961
- readonly scope: AuthorizedAgentScope;
1962
- readonly agentTypeId: string;
1963
- readonly operation: AgentAccessOperation;
1964
- }): Promise<void>;
1965
- listAgents(input: {
1966
- readonly scope: AuthorizedAgentScope;
1967
- }): Promise<{
1968
- definition?: {
1969
- digest?: string | undefined;
1970
- version: string;
1971
- } | undefined;
1972
- pluginIds?: string[] | undefined;
1973
- agentTypeId: string;
1974
- label: string;
1975
- }[]>;
1976
- listSessions(input: Parameters<AgentGateway['listSessions']>[0]): Promise<{
1977
- sessions: AgentSessionSummary[];
1978
- nextCursor?: string;
1979
- }>;
1980
- createSession(input: Parameters<AgentGateway['createSession']>[0]): Promise<AgentSessionRef>;
1981
- readSessionState(input: Parameters<AgentGateway['readSessionState']>[0]): Promise<AgentSessionStateSnapshot>;
1982
- connectSession(input: Parameters<AgentGateway['connectSession']>[0]): Promise<AgentSessionConnection>;
1983
- private send;
1984
- renameSession(input: Parameters<AgentGateway['renameSession']>[0]): Promise<AgentSessionSummary>;
1985
- /**
1986
- * Visibility only. This never reaches the delete path: the session
1987
- * repository records the flag beside the transcript and hands back the same
1988
- * summary, so `archived: false` restores the row untouched.
1989
- */
1990
- setSessionArchived(input: Parameters<AgentGateway['setSessionArchived']>[0]): Promise<AgentSessionSummary>;
1991
- deleteSession(input: Parameters<AgentGateway['deleteSession']>[0]): Promise<void>;
1992
- private authorizedEvents;
1993
- close(): Promise<void>;
1994
- private bindingForSession;
1995
- private loadSummary;
1996
- private sessionEffect;
1997
- private effect;
1998
- private applyClassification;
1999
- private replayReceipt;
2000
- private failure;
2001
- private promptAdmission;
2002
- private queueClearAdmission;
2003
- private withWriter;
2004
- }
2005
-
2006
- /** Process-lifetime Level-B ledger with the exact published state machine. */
2007
- declare class InMemoryAgentRequestLedger implements AgentRequestLedger {
2008
- readonly durability: "in-memory";
2009
- private readonly records;
2010
- prepare(key: AgentRequestKey, digest: string, acceptedWork: AcceptedWorkContext): Promise<AgentRequestLedgerPrepareResult>;
2011
- markAdmissionRetryable(key: AgentRequestKey): Promise<void>;
2012
- acceptAdmission(key: AgentRequestKey, admissionReceipt: string): Promise<void>;
2013
- beginEffect(key: AgentRequestKey): Promise<void>;
2014
- reject(key: AgentRequestKey, failure: AgentRequestFailure): Promise<void>;
2015
- complete(key: AgentRequestKey, receipt: JsonValue): Promise<void>;
2016
- markOutcomeUnknown(key: AgentRequestKey, error: AgentGatewayErrorDTO): Promise<void>;
2017
- read(key: AgentRequestKey): Promise<AgentRequestLedgerRecord | undefined>;
2018
- private transition;
2019
- }
2020
-
2021
- /** Canonical, collision-safe projection. The complete request key is the run identity. */
2022
- declare function projectAgentRequestRunId(key: AgentRequestKey): string;
2023
-
2024
- interface RuntimeScopeIdentityInput {
2025
- readonly artifacts: readonly {
2026
- readonly pluginId: string;
2027
- readonly digest: string;
2028
- }[];
2029
- readonly validatedConfig: JsonValue;
2030
- readonly grants: readonly string[];
2031
- /** Stable semantic placement class; never an absolute root or lease key. */
2032
- readonly placementClassIdentity: string;
2033
- readonly isolationMode: string;
2034
- readonly toolContractDigests: readonly string[];
2035
- /** Stable semantic provisioning contract. */
2036
- readonly provisioningIdentity: string;
2037
- readonly bindingInputs?: JsonValue;
2038
- }
2039
- interface EnvironmentProvisioningIdentityInput {
2040
- readonly placementIdentity: string;
2041
- readonly providerDigest: string;
2042
- readonly provisioningArtifactDigests: readonly string[];
2043
- readonly provisioningGeneration: string;
2044
- readonly templateDigest?: string;
2045
- }
2046
- /**
2047
- * Produces the complete Agent-binding identity. Grants intentionally
2048
- * participate here even though they do not participate in Environment
2049
- * provisioning identity.
2050
- */
2051
- declare function createResolvedRuntimeScopeIdentity(input: RuntimeScopeIdentityInput): string;
2052
- /**
2053
- * Produces only the Environment-mutating identity. Contribution grants and
2054
- * tool contracts are deliberately absent, so grant-only changes share the
2055
- * same canonical Environment lease.
2056
- */
2057
- declare function createEnvironmentProvisioningFingerprint(input: EnvironmentProvisioningIdentityInput): string;
2058
-
2059
- interface HeaderLike {
2060
- setHeader(name: string, value: string): void;
2061
- }
2062
- declare function applyCspHeaders(response: HeaderLike, opts?: {
2063
- dev?: boolean;
2064
- }): void;
2065
-
2066
- interface DeepLinkRoutesOptions {
2067
- /** Workspace-agnostic store: entries carry their own `workspaceId`. */
2068
- store: ShareEntryStore;
2069
- workspace?: Workspace;
2070
- /**
2071
- * Resolves the `Workspace` already authorized for the request's scoped
2072
- * workspace (the same `getWorkspace` shape used by fileRoutes/treeRoutes —
2073
- * membership for this workspace is enforced upstream, before this route's
2074
- * handler runs, by the host's existing `onRequest` seam).
2075
- */
2076
- getWorkspace?: (request: FastifyRequest) => Workspace | Promise<Workspace>;
2077
- }
2078
- declare const deepLinkRoutes: FastifyPluginCallback<DeepLinkRoutesOptions>;
2079
-
2080
- interface SkillMetadataFrontmatter {
2081
- readonly name?: string;
2082
- readonly description?: string;
2083
- }
2084
- declare function parseSkillMetadataFrontmatter(content: string): SkillMetadataFrontmatter;
2085
-
2086
- interface PiResourceDigestLimits {
2087
- readonly maxDepth: number;
2088
- readonly maxFiles: number;
2089
- readonly maxFileBytes: number;
2090
- readonly maxTotalBytes: number;
2091
- }
2092
- declare const DEFAULT_PI_RESOURCE_DIGEST_LIMITS: PiResourceDigestLimits;
2093
- interface PiResourceDigestInput {
2094
- /** Cwd passed to Pi. Explicit skills/extensions resolve from here. */
2095
- readonly piCwd: string;
2096
- /** Pi user agent directory. User settings/package sources resolve from here. */
2097
- readonly piAgentDir: string;
2098
- /** User home Pi uses for ~/.agents skill discovery. */
2099
- readonly piUserHome: string;
2100
- /** Mirrors Pi's noSkills resource-loader option. */
2101
- readonly noSkills: boolean;
2102
- /** Mirrors Pi's noContextFiles resource-loader option; omitted stays sealed. */
2103
- readonly noContextFiles?: boolean;
2104
- readonly promptParts?: readonly (string | undefined)[];
2105
- readonly additionalSkillPaths?: readonly string[];
2106
- readonly packages?: readonly PiPackageSource[];
2107
- readonly extensionPaths?: readonly string[];
2108
- /** Lexical roots explicitly authorized by the embedding Workspace/CLI. */
2109
- readonly authorizedRoots: readonly string[];
2110
- readonly limits?: Partial<PiResourceDigestLimits>;
2111
- }
2112
- interface PiResourceSet {
2113
- readonly promptParts?: readonly (string | undefined)[];
2114
- readonly additionalSkillPaths?: readonly string[];
2115
- readonly packages?: readonly PiPackageSource[];
2116
- readonly extensionPaths?: readonly string[];
2117
- }
2118
- /** Canonical normalization shared by Workspace and CLI resource resolvers. */
2119
- declare function createPiResourceDigestInput(input: {
2120
- readonly piCwd: string;
2121
- readonly piAgentDir?: string;
2122
- readonly piUserHome?: string;
2123
- readonly noSkills?: boolean;
2124
- readonly noContextFiles?: boolean;
2125
- readonly resourceSets: readonly PiResourceSet[];
2126
- readonly authorizedRoots: readonly string[];
2127
- readonly limits?: Partial<PiResourceDigestLimits>;
2128
- }): PiResourceDigestInput;
2129
- /** Bounded asynchronous content identity for the exact Pi resources considered by a reload candidate. */
2130
- declare function digestPiResourceInputs(input: PiResourceDigestInput): Promise<string>;
2131
- /** Immutable digest plus the reload fences that defend that exact snapshot. */
2132
- declare function createPiResourceDigestFence(resolveInput: () => PiResourceDigestInput | Promise<PiResourceDigestInput>): Promise<{
2133
- readonly resourceInputDigest: string;
2134
- readonly revalidateResourceInputs: () => Promise<void>;
2135
- }>;
2136
-
2137
- /**
2138
- * `plugin_diagnostics` built-in agent tool.
2139
- *
2140
- * Surfaces current plugin/skill loading errors to the agent so it can iterate
2141
- * on them without the failures being silently swallowed. It merges three
2142
- * sources:
2143
- *
2144
- * - `lastReloadDiagnostics`: diagnostics captured by the most recent
2145
- * /api/v1/agents/:agentTypeId/reload (hook + harness resource diagnostics).
2146
- * - `resourceDiagnostics`: live Pi skill/extension load diagnostics for the
2147
- * current session, read straight from the harness.
2148
- * - `pluginErrors`: host-provided plugin load/preflight errors for the
2149
- * workspace (wired by the embedding host).
2150
- *
2151
- * The tool is informational: it returns the diagnostics as data and never
2152
- * reports `isError`, even when diagnostics exist.
2153
- */
2154
-
2155
- interface PluginDiagnostic {
2156
- source: string;
2157
- message: string;
2158
- pluginId?: string;
2159
- }
2160
- interface PluginDiagnosticsToolDeps {
2161
- /** Diagnostics stashed by the last /reload. Read via a thunk because the
2162
- * runtime binding is assigned after the tool catalog is built. */
2163
- getLastReloadDiagnostics: () => ReadonlyArray<PluginDiagnostic>;
2164
- /** Live harness, used to read per-session resource diagnostics. */
2165
- getHarness: () => AgentHarness | undefined;
2166
- /** Optional host callback returning workspace plugin load/preflight errors. */
2167
- getPluginErrors?: () => Promise<ReadonlyArray<PluginDiagnostic>>;
2168
- }
2169
- declare function createPluginDiagnosticsTool(deps: PluginDiagnosticsToolDeps): AgentTool;
2170
-
2171
- declare const RUNTIME_FILESYSTEM_BINDING_DUPLICATE_CODE: "RUNTIME_FILESYSTEM_BINDING_DUPLICATE";
2172
- declare class RuntimeFilesystemBindingConfigurationError extends Error {
2173
- readonly code: "RUNTIME_FILESYSTEM_BINDING_DUPLICATE";
2174
- readonly filesystem: string;
2175
- constructor(filesystem: string);
2176
- }
2177
- /**
2178
- * Canonical final merge seam for runtime-owned and request-scoped bindings.
2179
- * Duplicates *within* either list stay configuration errors; a host/request
2180
- * collision on the same id composes as an intersection of both capabilities.
2181
- */
2182
- declare function mergeRuntimeFilesystemBindings<T extends RuntimeFilesystemBinding>(runtimeBindings: readonly T[] | undefined, requestBindings: readonly T[] | undefined): readonly RuntimeFilesystemBinding[] | undefined;
2183
-
2184
- declare const RUNTIME_READONLY_FILESYSTEM_POLICY_INVALID_CODE: "RUNTIME_READONLY_FILESYSTEM_POLICY_INVALID";
2185
- declare class RuntimeReadonlyFilesystemPolicyError extends Error {
2186
- readonly code: "RUNTIME_READONLY_FILESYSTEM_POLICY_INVALID";
2187
- constructor();
2188
- }
2189
- /**
2190
- * Default protected prefixes applied when a host does not configure its own.
2191
- * `.agents` holds agent governance/skill definitions: agents may read them but
2192
- * must never rewrite the rules they run under. Hosts opt out with an explicit
2193
- * empty array.
2194
- */
2195
- declare const DEFAULT_READONLY_WORKSPACE_PATHS: readonly string[];
2196
- interface RuntimeReadonlyFilesystemPolicy {
2197
- readonly readonlyPaths: readonly string[];
2198
- readonly revision: string;
2199
- }
2200
- declare function normalizeRuntimeReadonlyFilesystemPolicy(paths: readonly string[]): RuntimeReadonlyFilesystemPolicy;
2201
- /** Resolve policy after the Workspace adapter has normalized/confined the path. */
2202
- declare function resolveRuntimeReadonlyFilesystemAccess(policy: RuntimeReadonlyFilesystemPolicy, descriptor: {
2203
- readonly filesystem: string;
2204
- readonly normalizedPath: string;
2205
- }): RuntimeFilesystemAccessDecision;
2206
-
2207
- /** Primary-user Operations adapter shared by HTTP and Pi filesystem tools. */
2208
- declare function createUserFilesystemBinding(workspace: Workspace, policy: RuntimeReadonlyFilesystemPolicy, resolvePolicyPath: (path: string) => Promise<string>): RuntimeFilesystemBinding;
2209
-
2210
- declare function withResolvedCredential<T>(resolver: WorkspaceCredentialResolverV1, workspace: AuthorizedWorkspaceCredentialScopeV1, ref: ProviderCredentialRefV1, fn: (lease: ResolvedCredentialLeaseV1) => T | Promise<T>): Promise<T>;
2211
-
2212
- /** Opaque, encrypted vault field containing Pi's canonical OAuth credential. */
2213
- declare const PI_OAUTH_CREDENTIAL_FIELD_ID_V1: CredentialFieldId;
2214
- interface VaultCredentialStoreOptionsV1 {
2215
- readonly workspaceId: string;
2216
- /** Verified actor identity. Required whenever subscription OAuth is enabled. */
2217
- readonly userId?: string;
2218
- readonly vaultBackend: VaultCredentialStoreBackendV1;
2219
- /** Subscription OAuth is interactive-only; unattended seats set this false. */
2220
- readonly allowSubscriptionOAuth: boolean;
2221
- /** Login-only store's durable version fence for replacing a revoked OAuth tombstone. */
2222
- readonly revokedOAuthReplacementVersion?: number;
2223
- readonly allowedOAuthProviderIds?: readonly string[];
2224
- }
2225
- /**
2226
- * Adapts Pi's async CredentialStore to one authorized workspace's encrypted
2227
- * vault. The adapter is actor-bound at construction and never accepts a
2228
- * workspace id from callers. Pi remains the sole owner of login and refresh.
2229
- */
2230
- declare function createVaultCredentialStoreV1(options: VaultCredentialStoreOptionsV1): CredentialStore;
2231
-
2232
- type SafeOAuthEventV1 = {
2233
- readonly type: 'auth_url';
2234
- readonly url: string;
2235
- } | {
2236
- readonly type: 'device_code';
2237
- readonly userCode: string;
2238
- readonly verificationUri: string;
2239
- readonly expiresInSeconds?: number;
2240
- } | {
2241
- readonly type: 'progress';
2242
- };
2243
- interface SafeOAuthPromptV1 {
2244
- readonly type: AuthPrompt['type'];
2245
- readonly options?: readonly {
2246
- readonly id: string;
2247
- readonly label: string;
2248
- }[];
2249
- }
2250
- interface OAuthFlowSnapshotV1 {
2251
- readonly flowId: string;
2252
- readonly providerId: 'openai-codex';
2253
- readonly status: 'pending' | 'succeeded' | 'failed' | 'cancelled';
2254
- readonly events: readonly SafeOAuthEventV1[];
2255
- readonly prompt?: SafeOAuthPromptV1;
2256
- readonly createdAt: string;
2257
- readonly completedAt?: string;
2258
- }
2259
- interface CodexDisconnectResultV1 {
2260
- /** Pi logout is local credential orchestration; it does not currently attest upstream revocation. */
2261
- readonly logoutStatus: 'completed' | 'failed';
2262
- readonly upstreamStatus: 'pending';
2263
- }
2264
- interface OpenAiCodexOAuthBrokerV1 {
2265
- start(workspaceId: string, userId: string): Promise<OAuthFlowSnapshotV1>;
2266
- get(workspaceId: string, userId: string, flowId: string): OAuthFlowSnapshotV1 | undefined;
2267
- respond(workspaceId: string, userId: string, flowId: string, value: string): Promise<OAuthFlowSnapshotV1>;
2268
- cancel(workspaceId: string, userId: string, flowId: string): Promise<void>;
2269
- disconnect(workspaceId: string, userId: string): Promise<CodexDisconnectResultV1>;
2270
- }
2271
- interface OpenAiCodexOAuthBrokerOptionsV1 {
2272
- readonly credentialStoreForActor: (workspaceId: string, userId: string) => CredentialStore | Promise<CredentialStore>;
2273
- readonly createRuntime?: (credentials: CredentialStore) => Promise<Pick<ModelRuntime, 'login' | 'logout'>>;
2274
- readonly now?: () => number;
2275
- }
2276
- declare function createOpenAiCodexOAuthBrokerV1(options: OpenAiCodexOAuthBrokerOptionsV1): OpenAiCodexOAuthBrokerV1;
2277
-
2278
- export { AgentAccessDecision, AgentAccessOperation, AgentDirectoryCompilerError, type AgentDirectoryCompilerErrorCode, type AgentDirectoryCompilerPublicErrorCode, AgentEffectAdmission, AgentFleetCompilationError, AgentFleetCompilationErrorCode, AgentFleetCompiler, type AgentFleetPluginBindingContract, AgentHarnessFactory, AgentHostAgentSpec, type AgentHostChannelRuntime, type AgentHostChannelStorage, AgentHostCredentialOptionsV1, type AgentHostEnvironmentHttpProjectionOptions, AgentHostEnvironmentScope, AgentInstructionFileRef, AgentInstructionSource, AgentMeteringSink, AgentRequestKey, AgentRequestLedger, AgentRequestLedgerPrepareResult, AgentRequestLedgerRecord, AgentRuntimeHostOperations, AuthoredAgentMaterializationError, type AuthoredAgentMaterializationErrorCode, type AuthoredAgentSourceV1, AuthorizedAgentScope, AuthorizedEnvironmentIntent, type AuthorizedSessionRunDetails, BuiltinRuntimeModeId, CHANNELS_ENV_FLAG, CHANNEL_DURABLE_STREAM_REQUIRED, CHANNEL_INBOUND_PARKED, CHANNEL_OUTBOUND_PARKED, CHANNEL_RUNTIME_FILE_NAME, CHANNEL_TURN_STALLED, CHANNEL_UNKNOWN_BINDING, type ChannelAdapter, type ChannelAgentInvocation, type ChannelAgentInvoker, type ChannelBinding, ChannelBindingStore, type ChannelInboundAck, ChannelInboundService, type ChannelIntentionAck, type ChannelIntentionAdapter, type ChannelIntentionField, type ChannelIntentionOption, type ChannelIntentionQuestion, type ChannelIntentionRecord, type ChannelIntentionRuntime, ChannelIntentionService, type ChannelIntentionServiceOptions, type ChannelIntentionSource, type ChannelMessageAck, ChannelMessageRouter, type ChannelOutboundAdapter, type ChannelOutboundRuntime, ChannelOutboundService, type ChannelOutboundServiceOptions, type ChannelOutboundTurn, ChannelSessionCreateTimeoutError, CompiledAgentHostAgentSpec, ConfiguredAgentHostAgentSpec, type CreateAgentHostChannelRuntimeOptions, CreateAgentHostOptions, type CreateConfiguredAgentHostAgentSpecInput, type CreateStandaloneAgentHostAppOptions, type CreateValidatingAgentFleetCompilerOptions, CreatedAgentHost, type CredentialStoreBackendV1, CredentialVaultPersistenceV2, DEFAULT_AGENT_FLEET, DEFAULT_PI_RESOURCE_DIGEST_LIMITS, DEFAULT_READONLY_WORKSPACE_PATHS, type DeploymentSnapshotProvider, type DeploymentSnapshotRecipe, type DeploymentSnapshotResult, type DeploymentSnapshotStatus, type DiscoveredAgentPackageDescriptor, EmbeddedAgentGateway, FleetConfigError, type FleetConfigErrorCode, type FleetLoaderDiagnostic, type FleetLoaderDiagnosticCode, type FleetSeatBinding, type FleetSkillBinding, type HostSideCredentialResolverOptionsV1, InMemoryAgentRequestLedger, type InMemoryCredentialBackendEntryV1, type InboundChannelMessage, type LegacyRequestLedgerLocation, type LoadConfiguredAgentFleetOptions, type LoadConfiguredAgentFleetResult, type LocalCredentialVersionAnchorOptionsV1, MANAGED_AGENT_MCP_DELIVERY_RULE, MANAGED_AGENT_MCP_ORIGIN_SURFACE, MIN_REQUEST_RETENTION_MS, type ManagedAgentArtifact, type ManagedAgentArtifactCandidate, type ManagedAgentArtifactRef, type ManagedAgentBoundRunnerWorkspace, type ManagedAgentCollectArtifactsInput, type ManagedAgentDelegateInput, type ManagedAgentDelegateProgress, type ManagedAgentDelegateRequestContext, type ManagedAgentDelegateResult, type ManagedAgentDelegateRunInput, type ManagedAgentDelegateRunner, type ManagedAgentDelegateStatus, type ManagedAgentDelegateStatusResult, ManagedAgentMcpDelegateController, type ManagedAgentMcpDelegateOptions, ManagedAgentMcpError, type ManagedAgentMcpHttpHandlerOptions, type ManagedAgentMcpServerOptions, type ManagedAgentSafeError, type ManagedAgentWorkspaceResolutionInput, type MaterializeAgentDirectoryInput, ModeContext, type ModelTierCandidate, type OpenAiCodexOAuthBrokerV1, PI_OAUTH_CREDENTIAL_FIELD_ID_V1, PiHarnessOptions, PiPackageSource, type PiResourceDigestInput, type PiResourceDigestLimits, type PiResourceSet, type ProvisionChannelBindingInput, type ProvisionRuntimeWorkspaceOptions, ProvisionWorkspaceRuntimeOptions, type ProvisioningArtifactRequest, type QueuedChannelInbound, RUNTIME_FILESYSTEM_BINDING_DUPLICATE_CODE, RUNTIME_READONLY_FILESYSTEM_POLICY_INVALID_CODE, RemoteWorkerClient, RemoteWorkerClientError, type RemoteWorkerClientOptions, RemoteWorkerExecRequest, type RemoteWorkerModeAdapterOptions, RemoteWorkerWorkspaceOp, RemoteWorkerWorkspaceResult, type ResolveDefaultAgentFleetOptions, type ResolveRequestLedgerPathInput, type ResolvedAgent, type ResolvedAgentDigestInput, ResolvedAgentRuntimeScope, type ResolvedInstructionFileRefs, RuntimeBundle, type RuntimeEnvContribution, type RuntimeEnvContributionContext, RuntimeFilesystemAccessDecision, RuntimeFilesystemBinding, RuntimeFilesystemBindingConfigurationError, RuntimeModeAdapter, RuntimeModeId, type RuntimeReadonlyFilesystemPolicy, RuntimeReadonlyFilesystemPolicyError, type RuntimeWorkspaceProvisioningResult, type SandboxRuntimeModeOptions, type ShareEntryMcpResourceOptions, type SkillMetadataFrontmatter, SqliteAgentRequestLedger, StoredCredentialRecordV1, TrustedAgentCompositionError, type TrustedAgentInstructionAppendix, type TrustedAuthoredAgentPolicy, UV_SETUP_COMMANDS, type VaultCredentialStoreBackendV1, type VaultCredentialStoreOptionsV1, VerifiedAgentScopeClaim, type WithheldInstructionRef, type WorkspaceAgentDispatcherBinding, type WorkspaceAgentDispatcherResolveOptions, type WorkspaceAgentDispatcherResolver, type WorkspaceCredentialVersionAnchorV1, type WorkspaceCredentialVersionAnchorV2, type WorkspaceCredentialVersionStateV1, WorkspaceProvisioningAdapter, WorkspaceProvisioningResult, applyCspHeaders, areChannelsEnabled, assembleNextTurn, assertChannelDurability, autoDetectMode, buildDeploymentSnapshotRecipe, compileAgentDirectory, compilePersonaPackageDirectory, constantTimeTokenEqual, createAgentHost, createAgentHostChannelRuntime, createAgentHostChannelStorage, createBlaxelSandboxModeAdapter, createBoundWorkspaceAgentDispatcher, createChannelIntentionRuntime, createConfiguredAgentHostAgentSpec, createDirectModeAdapter, createEnvironmentProvisioningFingerprint, createHostSideCredentialResolverV1, createInMemoryCredentialBackendV1, createInMemoryCredentialVaultPersistenceV1, createInMemoryCredentialVersionAnchorV1, createLocalCredentialVersionAnchorFromEnvV1, createLocalFileCredentialVersionAnchorV1, createLocalKekWorkspaceKekProviderFromEnvV1, createLocalModeAdapter, createManagedAgentMcpDelegateController, createManagedAgentMcpHttpHandler, createManagedAgentMcpServer, createOpenAiCodexOAuthBrokerV1, createPiResourceDigestFence, createPiResourceDigestInput, createPluginDiagnosticsTool, createPostgresCredentialVaultPersistenceV1, createProviderRuntimeModeAdapter, createRemoteWorkerModeAdapter, createRemoteWorkerSandbox, createRemoteWorkerWorkspace, createResolvedAgentDigest, createResolvedRuntimeScopeIdentity, createResourceSettingsManager, createSandboxRuntimeModeAdapter, createStandaloneAgentHostApp, createUserFilesystemBinding, createValidatingAgentFleetCompiler, createVaultCredentialStoreBackendV1, createVaultCredentialStoreV1, createVercelSandboxModeAdapter, decodeBytesFromWorker, deepLinkRoutes, digestPiResourceInputs, encodeBytesForWorker, hasBwrap, initializeLocalFileCredentialVersionAnchorV1, loadConfiguredAgentFleet, materializeAgentDirectory, mergeRuntimeFilesystemBindings, normalizeRuntimeReadonlyFilesystemPolicy, parseSkillMetadataFrontmatter, prepareDeploymentSnapshot, projectAgentRequestRunId, projectAuthorizedSessionRunDetails, provisionRuntimeWorkspace, provisionWorkspaceRuntime, registerAgentHostEnvironmentRoutes, registerShareEntryResources, resolveAgentDeployment, resolveAgentInstructionFileRefs, resolveBuiltinRuntimeLayoutRoot, resolveDefaultAgentFleet, resolveMode, resolveRequestLedgerPath, resolveRuntimeReadonlyFilesystemAccess, resolveWorkspaceRoot, runCredentialVaultPostgresMigrationsV1, sandboxRuntimeHostOperations, shapeChannelText, shareResourceUri, withResolvedCredential, withRuntimeEnvContributions };