@tangle-network/agent-runtime 0.91.0 → 0.92.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 (86) hide show
  1. package/README.md +4 -2
  2. package/dist/agent.d.ts +3 -3
  3. package/dist/agent.js +88 -9
  4. package/dist/agent.js.map +1 -1
  5. package/dist/{mcp-serve-verifier-XsX8rkB9.d.ts → agentic-generator-B8oeE2Yv.d.ts} +6 -33
  6. package/dist/analyst-loop.d.ts +1 -1
  7. package/dist/candidate-execution/index.d.ts +104 -0
  8. package/dist/candidate-execution/index.js +34 -0
  9. package/dist/candidate-execution/index.js.map +1 -0
  10. package/dist/chunk-3BE7KTMU.js +1229 -0
  11. package/dist/chunk-3BE7KTMU.js.map +1 -0
  12. package/dist/chunk-3D2RHC4K.js +73 -0
  13. package/dist/chunk-3D2RHC4K.js.map +1 -0
  14. package/dist/chunk-3MDZX7YU.js +125 -0
  15. package/dist/chunk-3MDZX7YU.js.map +1 -0
  16. package/dist/{chunk-NC66AM3S.js → chunk-6O5USWVH.js} +32 -1413
  17. package/dist/chunk-6O5USWVH.js.map +1 -0
  18. package/dist/chunk-6O73TRHW.js +142 -0
  19. package/dist/chunk-6O73TRHW.js.map +1 -0
  20. package/dist/{chunk-JRS3YSRZ.js → chunk-7VJJJ2T2.js} +2 -2
  21. package/dist/chunk-A62TP7SK.js +4784 -0
  22. package/dist/chunk-A62TP7SK.js.map +1 -0
  23. package/dist/chunk-APVPRF4Y.js +2166 -0
  24. package/dist/chunk-APVPRF4Y.js.map +1 -0
  25. package/dist/{chunk-DWWII6N2.js → chunk-AUEIDTR3.js} +2 -2
  26. package/dist/{chunk-FF77IBQM.js → chunk-FRBHUNQ7.js} +2 -141
  27. package/dist/chunk-FRBHUNQ7.js.map +1 -0
  28. package/dist/{chunk-7ON74BQO.js → chunk-GDAQUFG6.js} +2 -2
  29. package/dist/{chunk-AD7JW4QG.js → chunk-I7WVPJBZ.js} +23 -1231
  30. package/dist/chunk-I7WVPJBZ.js.map +1 -0
  31. package/dist/{chunk-IOUUITQA.js → chunk-IGGZGKJD.js} +3 -3
  32. package/dist/chunk-PH65PR4F.js +860 -0
  33. package/dist/chunk-PH65PR4F.js.map +1 -0
  34. package/dist/chunk-RSWM2ZKM.js +659 -0
  35. package/dist/chunk-RSWM2ZKM.js.map +1 -0
  36. package/dist/{chunk-BZF3KQ6G.js → chunk-VSWBYWFK.js} +4 -122
  37. package/dist/chunk-VSWBYWFK.js.map +1 -0
  38. package/dist/{completion-gate-DkAnUmpb.d.ts → completion-gate-BLaiN0-X.d.ts} +1 -1
  39. package/dist/{coordination-rRj5hjJK.d.ts → coordination-DxJ83oZA.d.ts} +12 -5
  40. package/dist/environment-provider.d.ts +2 -2
  41. package/dist/environment-provider.js +2 -1
  42. package/dist/improve-CUVCq7xg.d.ts +152 -0
  43. package/dist/{improvement-adapter-CDR8QNVM.d.ts → improvement-adapter-BieWeK5J.d.ts} +16 -0
  44. package/dist/index.d.ts +27 -1092
  45. package/dist/index.js +108 -6491
  46. package/dist/index.js.map +1 -1
  47. package/dist/intelligence.d.ts +160 -13
  48. package/dist/intelligence.js +535 -59
  49. package/dist/intelligence.js.map +1 -1
  50. package/dist/knowledge.d.ts +6 -6
  51. package/dist/knowledge.js +6 -4
  52. package/dist/lifecycle.d.ts +2 -1
  53. package/dist/lifecycle.js +5 -3
  54. package/dist/lifecycle.js.map +1 -1
  55. package/dist/{loop-runner-bin-DTbZVGfM.d.ts → loop-runner-bin-kKUNGLyV.d.ts} +2 -2
  56. package/dist/loop-runner-bin.d.ts +5 -5
  57. package/dist/loop-runner-bin.js +8 -5
  58. package/dist/loops.d.ts +16 -16
  59. package/dist/loops.js +47 -41
  60. package/dist/mcp/bin.js +6 -4
  61. package/dist/mcp/bin.js.map +1 -1
  62. package/dist/mcp/index.d.ts +8 -8
  63. package/dist/mcp/index.js +9 -6
  64. package/dist/mcp/index.js.map +1 -1
  65. package/dist/mcp-serve-verifier-Bg4C3p5S.d.ts +34 -0
  66. package/dist/{openai-tools-C4ZfUD4L.d.ts → openai-tools-E3woykz9.d.ts} +1 -1
  67. package/dist/prepare-Z08a4heC.d.ts +713 -0
  68. package/dist/profiles.d.ts +1 -1
  69. package/dist/{router-client-DJImUDlm.d.ts → sanitize-C9go6tXj.d.ts} +113 -1
  70. package/dist/{structural-rollout-MwlpgQ-6.d.ts → structural-rollout-DHGDbhvR.d.ts} +3 -3
  71. package/dist/{supervise-DPmYPk0j.d.ts → supervise-T2pazU3G.d.ts} +4 -4
  72. package/dist/{types-SyuwunY_.d.ts → types-B00NtbCs.d.ts} +1 -1
  73. package/dist/{types-eMNgWgFi.d.ts → types-DAdIm4AC.d.ts} +1 -1
  74. package/dist/{worktree-fanout-BDFQIO-Y.d.ts → worktree-fanout-BUb2Ag02.d.ts} +3 -3
  75. package/package.json +26 -35
  76. package/skills/build-with-agent-runtime/SKILL.md +1 -1
  77. package/dist/chunk-AD7JW4QG.js.map +0 -1
  78. package/dist/chunk-BZF3KQ6G.js.map +0 -1
  79. package/dist/chunk-FF77IBQM.js.map +0 -1
  80. package/dist/chunk-IVGYLCFH.js +0 -381
  81. package/dist/chunk-IVGYLCFH.js.map +0 -1
  82. package/dist/chunk-NC66AM3S.js.map +0 -1
  83. /package/dist/{chunk-JRS3YSRZ.js.map → chunk-7VJJJ2T2.js.map} +0 -0
  84. /package/dist/{chunk-DWWII6N2.js.map → chunk-AUEIDTR3.js.map} +0 -0
  85. /package/dist/{chunk-7ON74BQO.js.map → chunk-GDAQUFG6.js.map} +0 -0
  86. /package/dist/{chunk-IOUUITQA.js.map → chunk-IGGZGKJD.js.map} +0 -0
package/dist/index.d.ts CHANGED
@@ -1,28 +1,33 @@
1
- import { BenchmarkEvaluation, TraceStore, AgentProfile, AgentEvalError, AnalystFinding, KnowledgeReadinessReport, RunRecord, ControlEvalResult, KnowledgeRequirement } from '@tangle-network/agent-eval';
1
+ import { AgentProfile, AgentEvalError, AnalystFinding, KnowledgeReadinessReport, RunRecord, ControlEvalResult } from '@tangle-network/agent-eval';
2
2
  export { AgentEvalError, AgentEvalErrorCode, ConfigError, ControlBudget, ControlDecision, ControlEvalResult, ControlRunResult, ControlStep, DataAcquisitionPlan, JudgeError, KnowledgeReadinessReport, KnowledgeRequirement, NotFoundError, RunRecord, ValidationError } from '@tangle-network/agent-eval';
3
- import { g as AgentBackendInput, O as OpenAIChatTool, h as OpenAIChatToolChoice, i as OpenAIChatResponseFormat, j as AgentExecutionBackend, k as AgentBackendContext, b as RuntimeStreamEvent, K as KnowledgeReadinessDecision, l as RunAgentTaskOptions, m as AgentTaskRunResult, n as RunAgentTaskStreamOptions, o as AgentRuntimeEvent, p as AgentTaskStatus, q as RuntimeSessionStore, r as RuntimeSession, R as RuntimeHooks } from './types-SyuwunY_.js';
4
- export { s as AgentAdapter, t as AgentKnowledgeProvider, u as AgentRuntimeEventSink, v as AgentTaskContext, w as AgentTaskSpec, B as BackendErrorDetail, x as RuntimeDecisionEvidenceRef, y as RuntimeDecisionKind, z as RuntimeDecisionPoint, C as RuntimeHookContext, F as RuntimeHookErrorContext, G as RuntimeHookEvent, H as RuntimeHookPhase, J as RuntimeHookTarget, M as RuntimeRunHandle, N as RuntimeRunPersistenceAdapter, P as RuntimeRunRow, Q as composeRuntimeHooks, T as defineRuntimeHooks, U as notifyRuntimeDecisionPoint, W as notifyRuntimeHookEvent, X as startRuntimeRun } from './types-SyuwunY_.js';
5
- import { AgentCandidateArtifactRef, AgentCandidateTermination, AgentCandidateTaskOutcomeEvidence, Sha256Digest, AgentCandidateContainer, AgentCandidateOciPlatform, AgentCandidateGitHubRepository, AgentCandidateWorkspaceSnapshotEvidence, AgentCandidateBundle, AgentCandidateResolvedModel, AgentCandidateAttemptPolicy, AgentCandidateExecutionLimits, AgentCandidateModelAccessNetwork, AgentCandidateCapturedArtifact, AgentCandidateWorkspaceManifestMaterialV1, AgentCandidateProfilePlanEvidence, AgentCandidateExecutionPlanEvidence, AgentCandidateMaterializationReceipt, AgentCandidateInstructionDelivery, AgentCandidateEffectiveMemory, AgentCandidateRunReceiptV2, AgentCandidateSpend, ReasoningEffort, AgentProfile as AgentProfile$1 } from '@tangle-network/agent-interface';
6
- import { Scenario, ProfileDispatchFn, MutableSurface as MutableSurface$1, SurfaceProposer as SurfaceProposer$1 } from '@tangle-network/agent-eval/campaign';
7
- import { V as Verifier, C as CandidateGenerator } from './mcp-serve-verifier-XsX8rkB9.js';
8
- export { A as AgenticGeneratorOptions, I as ImprovementDriverOptions, M as McpServeSpec, a as VerifyResult, b as agenticGenerator, c as commandVerifier, i as improvementDriver, m as mcpServeVerifier } from './mcp-serve-verifier-XsX8rkB9.js';
9
- import { Scenario as Scenario$1, SurfaceProposer, JudgeConfig, MutableSurface, DispatchContext, SelfImproveBudget, SelfImproveLlm, SelfImproveOptions, SelfImproveResult } from '@tangle-network/agent-eval/contract';
10
- import { L as LocalHarness } from './local-harness-dcD5WTTr.js';
11
- import { S as SurfaceImprovementEdit } from './improvement-adapter-CDR8QNVM.js';
3
+ import { i as AgentBackendInput, O as OpenAIChatTool, j as OpenAIChatToolChoice, k as OpenAIChatResponseFormat, l as AgentExecutionBackend, m as AgentBackendContext, b as RuntimeStreamEvent, K as KnowledgeReadinessDecision, n as RunAgentTaskOptions, o as AgentTaskRunResult, p as RunAgentTaskStreamOptions, q as RuntimeSessionStore, r as RuntimeSession, R as RuntimeHooks } from './types-B00NtbCs.js';
4
+ export { s as AgentAdapter, t as AgentKnowledgeProvider, A as AgentRuntimeEvent, u as AgentRuntimeEventSink, v as AgentTaskContext, w as AgentTaskSpec, c as AgentTaskStatus, B as BackendErrorDetail, x as RuntimeDecisionEvidenceRef, y as RuntimeDecisionKind, z as RuntimeDecisionPoint, C as RuntimeHookContext, F as RuntimeHookErrorContext, G as RuntimeHookEvent, H as RuntimeHookPhase, J as RuntimeHookTarget, M as RuntimeRunHandle, N as RuntimeRunPersistenceAdapter, P as RuntimeRunRow, Q as composeRuntimeHooks, T as defineRuntimeHooks, U as notifyRuntimeDecisionPoint, W as notifyRuntimeHookEvent, X as startRuntimeRun } from './types-B00NtbCs.js';
5
+ export { c as AgentCandidateArtifactPort, d as AgentCandidateBenchmarkGraderIdentity, e as AgentCandidateBenchmarkGraderPort, f as AgentCandidateContainerPort, g as AgentCandidateExecutionAttemptRecord, h as AgentCandidateExecutionAttemptRef, i as AgentCandidateExecutionClaim, j as AgentCandidateExecutionClaimResult, k as AgentCandidateExecutionClaimStore, l as AgentCandidateExecutionCleanupHandles, m as AgentCandidateExecutionFailureClass, n as AgentCandidateExecutionFinishResult, o as AgentCandidateExecutionLease, p as AgentCandidateExecutionPhase, q as AgentCandidateExecutionPhaseResult, a as AgentCandidateExecutionPorts, r as AgentCandidateExecutionRecoveryEvidence, s as AgentCandidateExecutionStageResult, t as AgentCandidateExecutionTerminalRecord, u as AgentCandidateExecutionTerminalResult, v as AgentCandidateExecutionUsage, w as AgentCandidateExecutorFinalCapture, x as AgentCandidateExecutorMemoryCapture, y as AgentCandidateExecutorPort, z as AgentCandidateExecutorProfileFile, B as AgentCandidateExecutorRequest, C as AgentCandidateExecutorStopRequest, D as AgentCandidateExecutorTaskOutcomeCapture, F as AgentCandidateExecutorWorkspaceFile, G as AgentCandidateExecutorWorkspaceInput, H as AgentCandidateMemoryPort, I as AgentCandidateMemoryResetResult, J as AgentCandidateModelLimits, K as AgentCandidateModelPort, L as AgentCandidateOutputArtifactPort, M as AgentCandidateOutputPurpose, N as AgentCandidateProtectedModelActivation, O as AgentCandidateProtectedModelCall, Q as AgentCandidateProtectedModelReservation, R as AgentCandidateProtectedModelSettlement, S as AgentCandidateProtectedRunCapture, T as AgentCandidateRepositoryPort, U as AgentCandidateRetryRejection, b as AgentCandidateRunFinalization, A as AgentCandidateTaskExecution, V as AgentCandidateVerificationPorts, W as AgentCandidateWorkspacePort, X as CANDIDATE_TRACE_ENV, Y as CANDIDATE_TRACE_TAGS, Z as CanonicalCandidateDocument, E as ExecutePreparedAgentCandidateOptions, _ as InMemoryAgentCandidateExecutionClaimStore, P as PrepareAgentCandidateExecutionOptions, $ as PreparedAgentCandidateExecution, a0 as PreparedAgentCandidateInstruction, a1 as PreparedAgentCandidateLaunch, a2 as PreparedAgentCandidateTrace, a3 as ResolvedAgentCandidateContainer, a4 as VerifiedAgentCandidate, a5 as VerifiedAgentCandidateTaskOutcome, a6 as executePreparedAgentCandidate, a7 as prepareAgentCandidateExecution } from './prepare-Z08a4heC.js';
6
+ export { AgentCandidateModelGrantActivateInput, AgentCandidateModelGrantClient, AgentCandidateModelGrantReservation, AgentCandidateModelGrantReserveInput, AgentCandidateModelGrantSettleInput, CreateProtectedAgentCandidateModelPortOptions, DisposePreparedAgentCandidateOptions, FileAgentCandidateExecutionClaimStore, FileAgentCandidateExecutionClaimStoreOptions, RecoverExpiredAgentCandidateOptions, candidateExecutionClaim, createProtectedAgentCandidateModelPort, disposePreparedAgentCandidateExecution, persistCandidateOutputArtifact, recoverExpiredAgentCandidateExecution, verifyAgentCandidateBundle } from './candidate-execution/index.js';
7
+ import { Scenario, ProfileDispatchFn, MutableSurface, SurfaceProposer } from '@tangle-network/agent-eval/campaign';
8
+ import { C as CandidateGenerator } from './agentic-generator-B8oeE2Yv.js';
9
+ export { A as AgenticGeneratorOptions, I as ImprovementDriverOptions, M as ManagedImprovementDriver, V as Verifier, a as VerifyResult, b as agenticGenerator, c as commandVerifier, i as improvementDriver } from './agentic-generator-B8oeE2Yv.js';
10
+ export { c as ImproveCodeOptions, a as ImproveOptions, b as ImproveResult, d as ImproveSkillsOptions, I as ImproveSurface, i as improve } from './improve-CUVCq7xg.js';
11
+ export { M as McpServeSpec, m as mcpServeVerifier } from './mcp-serve-verifier-Bg4C3p5S.js';
12
+ import { Scenario as Scenario$1, SelfImproveOptions } from '@tangle-network/agent-eval/contract';
13
+ import { S as SurfaceImprovementEdit } from './improvement-adapter-BieWeK5J.js';
12
14
  import { I as ImprovementAdapter } from './types-BC3bZpH0.js';
13
- import { S as StructuralRolloutPolicy } from './structural-rollout-MwlpgQ-6.js';
15
+ import { AgentProfile as AgentProfile$1 } from '@tangle-network/agent-interface';
16
+ import { S as StructuralRolloutPolicy } from './structural-rollout-DHGDbhvR.js';
14
17
  export { AgentKnowledgeReadinessCheckOptions, KnowledgeImprovementJobMeasurement, KnowledgeImprovementJobResult, KnowledgeReadinessCheck, KnowledgeReadinessCheckInput, KnowledgeReadinessCheckResult, RESEARCH_SUPERVISOR_SYSTEM_PROMPT, RunKnowledgeImprovementJobOptions, SupervisedKnowledgeUpdateInput, SupervisedKnowledgeUpdateOptions, SupervisedKnowledgeUpdateResult, SupervisedKnowledgeUpdater, createAgentKnowledgeReadinessCheck, createSupervisedKnowledgeUpdater, formatSupervisedKnowledgeTask, knowledgeReadinessDeliverable, runKnowledgeImprovementJob, runSupervisedKnowledgeUpdate } from './knowledge.js';
15
- export { D as DELEGATED_LOOP_MODES, a as DelegatedLoopMode, b as DelegatedLoopRegistry, c as DelegatedLoopResult, d as DelegatedLoopRunner, L as LoopRunnerCliArgs, e as LoopRunnerCliResult, R as ResearchLoopResult, f as ResearchLoopRunnerOptions, g as RunDelegatedLoopOptions, V as VetoedFact, W as WorktreeLoopRunnerOptions, h as auditLoopRunner, i as isDelegatedLoopMode, p as parseLoopRunnerArgv, r as researchLoopRunner, j as runDelegatedLoop, k as runLoopRunnerCli, s as selfImproveLoopRunner, w as worktreeLoopRunner } from './loop-runner-bin-DTbZVGfM.js';
16
- export { m as mcpToolsForRuntimeMcp, a as mcpToolsForRuntimeMcpSubset } from './openai-tools-C4ZfUD4L.js';
17
- export { b0 as EvalRunEvent, b1 as EvalRunGeneration, b2 as EvalRunsExportConfig, b3 as EvalRunsExportResult, b4 as INTELLIGENCE_WIRE_VERSION, b5 as LoopSpanNode, b6 as OtelAttribute, b7 as OtelExportConfig, b8 as OtelExporter, b9 as OtelSpan, ba as buildLoopOtelSpans, bb as buildLoopSpanNodes, bc as createOtelExporter, bd as exportEvalRuns, be as loopEventToOtelSpan } from './coordination-rRj5hjJK.js';
18
+ export { D as DELEGATED_LOOP_MODES, a as DelegatedLoopMode, b as DelegatedLoopRegistry, c as DelegatedLoopResult, d as DelegatedLoopRunner, L as LoopRunnerCliArgs, e as LoopRunnerCliResult, R as ResearchLoopResult, f as ResearchLoopRunnerOptions, g as RunDelegatedLoopOptions, V as VetoedFact, W as WorktreeLoopRunnerOptions, h as auditLoopRunner, i as isDelegatedLoopMode, p as parseLoopRunnerArgv, r as researchLoopRunner, j as runDelegatedLoop, k as runLoopRunnerCli, s as selfImproveLoopRunner, w as worktreeLoopRunner } from './loop-runner-bin-kKUNGLyV.js';
19
+ export { m as mcpToolsForRuntimeMcp, a as mcpToolsForRuntimeMcpSubset } from './openai-tools-E3woykz9.js';
20
+ export { b0 as EvalRunEvent, b1 as EvalRunGeneration, b2 as EvalRunsExportConfig, b3 as EvalRunsExportResult, b4 as INTELLIGENCE_WIRE_VERSION, b5 as LoopSpanNode, b6 as OtelAttribute, b7 as OtelExportConfig, b8 as OtelExporter, b9 as OtelSpan, ba as RuntimeEventOtelOptions, bb as buildLoopOtelSpans, bc as buildLoopSpanNodes, bd as buildRuntimeEventOtelSpans, be as createOtelExporter, bf as exportEvalRuns, bg as loopEventToOtelSpan } from './coordination-DxJ83oZA.js';
21
+ import { c as RuntimeTelemetryOptions } from './sanitize-C9go6tXj.js';
22
+ export { d as RuntimeEventCollector, e as RuntimeStreamEventCollector, S as SanitizedKnowledgeReadinessReport, f as createRuntimeEventCollector, g as createRuntimeStreamEventCollector, s as sanitizeAgentRuntimeEvent, h as sanitizeKnowledgeReadinessReport, i as sanitizeRuntimeStreamEvent } from './sanitize-C9go6tXj.js';
18
23
  import '@tangle-network/sandbox';
24
+ import './local-harness-dcD5WTTr.js';
19
25
  import 'node:child_process';
20
- import './worktree-fanout-BDFQIO-Y.js';
21
- import './types-eMNgWgFi.js';
22
- import './completion-gate-DkAnUmpb.js';
26
+ import './worktree-fanout-BUb2Ag02.js';
27
+ import './types-DAdIm4AC.js';
28
+ import './completion-gate-BLaiN0-X.js';
23
29
  import '@tangle-network/agent-knowledge';
24
- import './supervise-DPmYPk0j.js';
25
- import './router-client-DJImUDlm.js';
30
+ import './supervise-T2pazU3G.js';
26
31
  import './kb-gate-CwHO0vz6.js';
27
32
  import './substrate-DO2GHNg2.js';
28
33
  import './environment-provider.js';
@@ -159,807 +164,6 @@ declare function createOpenAICompatibleBackend<TInput extends AgentBackendInput
159
164
  retry?: BackendRetryPolicy;
160
165
  }): AgentExecutionBackend<TInput>;
161
166
 
162
- declare const verifiedCandidateBrand: unique symbol;
163
- declare const preparedCandidateBrand: unique symbol;
164
- declare const verifiedTaskOutcomeBrand: unique symbol;
165
- /** Reads one content-addressed object from the closed S3/IPFS locator set. */
166
- interface AgentCandidateArtifactPort {
167
- read(ref: AgentCandidateArtifactRef): Promise<Uint8Array>;
168
- }
169
- type AgentCandidateOutputPurpose = 'task-manifest' | 'task-archive' | 'task-patch' | 'task-outcome' | 'memory-after-manifest' | 'memory-after-archive' | 'grader-evidence' | 'benchmark-result' | 'model-settlement' | 'trace' | 'run-receipt' | 'failure-evidence';
170
- /** Durable content-addressed evidence store controlled only by the evaluator. */
171
- interface AgentCandidateOutputArtifactPort extends AgentCandidateArtifactPort {
172
- /** Must be idempotent for identical bytes and return only a durable S3/IPFS locator. */
173
- put(input: {
174
- executionId: string;
175
- purpose: AgentCandidateOutputPurpose;
176
- bytes: Uint8Array;
177
- /** Abort must prevent durable publication when it happens before resolution. */
178
- signal?: AbortSignal;
179
- }): Promise<AgentCandidateArtifactRef>;
180
- }
181
- /** Resolves a declared GitHub repository to an already-present local Git object store. */
182
- interface AgentCandidateRepositoryPort {
183
- resolve(repository: AgentCandidateGitHubRepository): Promise<string>;
184
- }
185
- interface AgentCandidateVerificationPorts {
186
- artifacts: AgentCandidateArtifactPort;
187
- repositories: AgentCandidateRepositoryPort;
188
- }
189
- /**
190
- * Materializes an already-verified workspace archive.
191
- *
192
- * The runtime independently scans every resulting byte, mode, and path against
193
- * the signed manifest after this returns. Implementations may therefore unpack
194
- * any archive encoding, or no-op when the exact workspace is already present.
195
- */
196
- interface AgentCandidateWorkspacePort {
197
- materialize(input: {
198
- role: 'task' | 'candidate' | 'memory';
199
- snapshot: AgentCandidateWorkspaceSnapshotEvidence;
200
- archive: Uint8Array;
201
- destination: string;
202
- }): Promise<void>;
203
- }
204
- interface ResolvedAgentCandidateContainer {
205
- source: 'pinned-container' | 'evaluator-task-container';
206
- image: string;
207
- indexDigest: Sha256Digest;
208
- manifestDigest: Sha256Digest;
209
- platform: AgentCandidateOciPlatform;
210
- }
211
- interface AgentCandidateContainerPort {
212
- resolve(input: {
213
- candidate: AgentCandidateContainer | undefined;
214
- evaluatorTaskContainer: ResolvedAgentCandidateContainer | undefined;
215
- }): Promise<ResolvedAgentCandidateContainer>;
216
- }
217
- interface AgentCandidateModelPort {
218
- resolve(input: {
219
- requested: string;
220
- harness: AgentCandidateBundle['execution']['harness'];
221
- reasoningEffort: NonNullable<AgentCandidateBundle['profile']['model']>['reasoningEffort'];
222
- }): Promise<AgentCandidateResolvedModel>;
223
- /**
224
- * Reserve a stable access identity without creating a live credential.
225
- * The reservation is scoped to `preparationId` and must automatically expire
226
- * at `expiresAtMs`, even if this call returns ambiguously to the runtime.
227
- */
228
- reserveGrant(input: {
229
- executionId: string;
230
- preparationId: string;
231
- expiresAtMs: number;
232
- attempt: AgentCandidateAttemptPolicy;
233
- bundleDigest: Sha256Digest;
234
- resolved: AgentCandidateResolvedModel;
235
- limits: AgentCandidateModelLimits;
236
- }): Promise<AgentCandidateProtectedModelReservation>;
237
- /** Create the live scoped credential only after the execution attempt is durably claimed. */
238
- activateGrant(input: {
239
- executionId: string;
240
- preparationId: string;
241
- grantDigest: Sha256Digest;
242
- resolved: AgentCandidateResolvedModel;
243
- deadlineAtMs: number;
244
- }): Promise<AgentCandidateProtectedModelActivation>;
245
- /**
246
- * Atomically revoke the grant, drain in-flight calls, and return its immutable final ledger.
247
- * This operation must be idempotent for the exact preparation and must also
248
- * settle a reservation that was never activated. It must never affect a
249
- * different preparation, even when both reservations report the same digest.
250
- */
251
- settleGrant(input: {
252
- executionId: string;
253
- preparationId: string;
254
- grantDigest: Sha256Digest;
255
- resolved: AgentCandidateResolvedModel;
256
- reason: 'completed' | 'failed' | 'timeout' | 'replayed' | 'preparation-failed' | 'abandoned';
257
- }): Promise<AgentCandidateProtectedModelSettlement>;
258
- }
259
- /** Limits mechanically enforced by the evaluator-owned model gateway. */
260
- type AgentCandidateModelLimits = Pick<AgentCandidateExecutionLimits, 'maxModelCalls' | 'maxInputTokens' | 'maxOutputTokens' | 'maxCostUsd'>;
261
- interface AgentCandidateProtectedModelReservation {
262
- preparationId: string;
263
- digest: Sha256Digest;
264
- /** Evaluator service must expire and revoke this reservation at this epoch millisecond. */
265
- expiresAtMs: number;
266
- /** The gateway must stop calls before any one of these limits is exceeded. */
267
- enforcedLimits: AgentCandidateModelLimits;
268
- /** Exact public endpoint exception; every other candidate destination stays blocked. */
269
- network: AgentCandidateModelAccessNetwork;
270
- }
271
- interface AgentCandidateProtectedModelActivation {
272
- /** Injected only into the trusted executor after all pre-launch checks pass. */
273
- env: Readonly<Record<string, string>>;
274
- }
275
- /** One evaluator-gateway call in the final, revoked model-access ledger. */
276
- interface AgentCandidateProtectedModelCall {
277
- callId: string;
278
- /** Router-generated public response identity. */
279
- generationId: string;
280
- /** Exact protected agent-eval LLM span produced from the router ledger. */
281
- traceSpanId: string;
282
- status: 'succeeded' | 'failed';
283
- model: string;
284
- startedAtMs: number;
285
- endedAtMs: number;
286
- inputTokens: number;
287
- outputTokens: number;
288
- cachedInputTokens: number;
289
- reasoningTokens: number;
290
- /** Integer billionths of one US dollar; avoids floating-point ledger drift. */
291
- costUsdNanos: number;
292
- }
293
- interface AgentCandidateProtectedModelSettlement {
294
- preparationId: string;
295
- grantDigest: Sha256Digest;
296
- closed: true;
297
- calls: readonly AgentCandidateProtectedModelCall[];
298
- }
299
- interface AgentCandidateMemoryResetResult {
300
- preparationId: string;
301
- accessDigest: Sha256Digest;
302
- expiresAtMs: number;
303
- evidence: AgentCandidateCapturedArtifact;
304
- emptyStateDigest: Sha256Digest;
305
- beforeState: AgentCandidateWorkspaceSnapshotEvidence;
306
- }
307
- interface AgentCandidateMemoryPort {
308
- /**
309
- * Reset and reserve exact task memory without returning live access.
310
- * The service must scope the reservation to `preparationId`, automatically
311
- * revoke it at `expiresAtMs`, and never reuse it for another preparation.
312
- */
313
- reset(input: {
314
- executionId: string;
315
- preparationId: string;
316
- expiresAtMs: number;
317
- effectiveNamespace: string;
318
- seed?: Uint8Array;
319
- seedDigest?: Sha256Digest;
320
- }): Promise<AgentCandidateMemoryResetResult>;
321
- /**
322
- * Create live scoped access only after the execution attempt is durably claimed.
323
- * Activation must match the exact preparation/access pair and may not extend expiry.
324
- */
325
- activate(input: {
326
- executionId: string;
327
- preparationId: string;
328
- accessDigest: Sha256Digest;
329
- effectiveNamespace: string;
330
- deadlineAtMs: number;
331
- }): Promise<{
332
- env: Readonly<Record<string, string>>;
333
- }>;
334
- /**
335
- * Revoke evaluator-owned access after process death or a failed preparation.
336
- * Must be idempotent and concurrency-safe for the exact preparation/access
337
- * pair and must never close a different preparation.
338
- */
339
- close(input: {
340
- executionId: string;
341
- preparationId: string;
342
- accessDigest: Sha256Digest;
343
- effectiveNamespace: string;
344
- reason: 'completed' | 'failed' | 'timeout' | 'replayed' | 'preparation-failed' | 'abandoned';
345
- }): Promise<{
346
- closed: true;
347
- }>;
348
- }
349
- interface AgentCandidateExecutionPorts extends AgentCandidateVerificationPorts {
350
- workspaces: AgentCandidateWorkspacePort;
351
- containers: AgentCandidateContainerPort;
352
- models: AgentCandidateModelPort;
353
- memory: AgentCandidateMemoryPort;
354
- }
355
- interface AgentCandidateTaskExecution {
356
- executionId: string;
357
- benchmark: string;
358
- benchmarkVersion: string;
359
- taskId: string;
360
- splitDigest: Sha256Digest;
361
- /** Exact agent-visible task instruction. The runtime rejects malformed Unicode. */
362
- instruction: string;
363
- repository: {
364
- identity: string;
365
- rootIdentity: string;
366
- baseCommit: string;
367
- baseTree: string;
368
- };
369
- attempt: AgentCandidateAttemptPolicy;
370
- model: {
371
- requested: string;
372
- reasoningEffort: ReasoningEffort;
373
- };
374
- /** Absolute paths inside the evaluator-owned execution environment. */
375
- executionRoots: {
376
- taskRoot: string;
377
- candidateRoot?: string;
378
- };
379
- /** Host-side staging roots. These are verified but never signed as container paths. */
380
- stagingRoots: {
381
- taskRoot: string;
382
- candidateRoot?: string;
383
- profileRoot: string;
384
- };
385
- workspace: AgentCandidateWorkspaceSnapshotEvidence;
386
- evaluatorTaskContainer?: ResolvedAgentCandidateContainer;
387
- limits: AgentCandidateExecutionLimits;
388
- }
389
- interface VerifiedAgentCandidate {
390
- readonly bundle: AgentCandidateBundle;
391
- readonly materializedTree?: string;
392
- readonly [verifiedCandidateBrand]: true;
393
- }
394
- interface CanonicalCandidateDocument<T> {
395
- readonly value: T;
396
- /** Canonical UTF-8 bytes of `value` with its top-level digest omitted. */
397
- readonly bytes: Uint8Array;
398
- readonly digest: Sha256Digest;
399
- }
400
- interface PreparedAgentCandidateLaunch {
401
- executable: string;
402
- /** Complete fixed argv, including profile materializer flags but excluding task delivery. */
403
- args: readonly string[];
404
- env: Readonly<Record<string, string>>;
405
- /** Informational subset already present at the tail of `args`; executors must not append twice. */
406
- flags: readonly string[];
407
- cwd: string;
408
- }
409
- interface PreparedAgentCandidateInstruction {
410
- bytes: Uint8Array;
411
- delivery: AgentCandidateInstructionDelivery;
412
- }
413
- interface PreparedAgentCandidateTrace {
414
- runId: string;
415
- tags: Readonly<Record<string, string>>;
416
- env: Readonly<Record<string, string>>;
417
- }
418
- interface PreparedAgentCandidateExecution {
419
- readonly bundle: AgentCandidateBundle;
420
- readonly executionId: string;
421
- readonly roots: {
422
- execution: {
423
- taskRoot: string;
424
- candidateRoot?: string;
425
- };
426
- staging: {
427
- taskRoot: string;
428
- candidateRoot?: string;
429
- profileRoot: string;
430
- };
431
- };
432
- readonly profilePlan: {
433
- value: AgentCandidateProfilePlanEvidence;
434
- bytes: Uint8Array;
435
- written: readonly string[];
436
- };
437
- readonly executionPlan: {
438
- value: AgentCandidateExecutionPlanEvidence;
439
- bytes: Uint8Array;
440
- };
441
- readonly materializationReceipt: CanonicalCandidateDocument<AgentCandidateMaterializationReceipt>;
442
- readonly launch: PreparedAgentCandidateLaunch;
443
- readonly instruction: PreparedAgentCandidateInstruction;
444
- readonly resolvedModel: AgentCandidateResolvedModel;
445
- readonly knowledge?: {
446
- snapshotId: string;
447
- manifestDigest: Sha256Digest;
448
- manifest: Uint8Array;
449
- };
450
- readonly trace: PreparedAgentCandidateTrace;
451
- readonly memory: AgentCandidateEffectiveMemory;
452
- readonly [preparedCandidateBrand]: true;
453
- }
454
- interface AgentCandidateProtectedRunCapture {
455
- executionId: string;
456
- termination: AgentCandidateTermination;
457
- }
458
- /** Raw evaluator capture made only after the candidate process is dead. */
459
- interface AgentCandidateExecutorTaskOutcomeCapture {
460
- /** Claimed final tree. The runtime recomputes it independently from `gitDiff`. */
461
- resultTree: string;
462
- /** Complete evaluator-captured workspace description after candidate execution. */
463
- afterState: AgentCandidateWorkspaceManifestMaterialV1;
464
- /** Reproducible workspace archive corresponding to `afterState`. */
465
- archive: Uint8Array;
466
- /** Exact binary patch from the signed task base to `afterState`. */
467
- gitDiff: Uint8Array;
468
- }
469
- /** Raw isolated-memory capture made only after access has been revoked. */
470
- interface AgentCandidateExecutorMemoryCapture {
471
- readonly afterState: AgentCandidateWorkspaceManifestMaterialV1;
472
- readonly archive: Uint8Array;
473
- }
474
- /** Idempotent executor result after process death and trace drain. */
475
- interface AgentCandidateExecutorFinalCapture {
476
- readonly stopped: true;
477
- readonly taskOutcome?: AgentCandidateExecutorTaskOutcomeCapture;
478
- /** Required only when the prepared candidate uses isolated task memory. */
479
- readonly memoryAfter?: AgentCandidateExecutorMemoryCapture;
480
- }
481
- /** Branded task outcome that has survived independent patch and tree verification. */
482
- interface VerifiedAgentCandidateTaskOutcome {
483
- readonly evidence: AgentCandidateTaskOutcomeEvidence & {
484
- readonly artifact: AgentCandidateArtifactRef;
485
- };
486
- readonly patch: Uint8Array;
487
- readonly [verifiedTaskOutcomeBrand]: true;
488
- }
489
- /**
490
- * Evaluator-owned executable grader, pinned by immutable implementation bytes.
491
- *
492
- * `run` is an isolation boundary, not an arbitrary scoring callback. The
493
- * implementation admitted to that boundary is supplied by the runtime after
494
- * artifact verification. Implementations must derive every returned binding
495
- * digest from the bytes and task outcome they actually admitted, rather than
496
- * copying an expected digest from ambient configuration.
497
- */
498
- interface AgentCandidateBenchmarkGraderPort {
499
- readonly name: string;
500
- readonly version: string;
501
- readonly artifact: AgentCandidateArtifactRef;
502
- run(input: {
503
- readonly executionId: string;
504
- readonly termination: AgentCandidateTermination;
505
- readonly outcome: VerifiedAgentCandidateTaskOutcome;
506
- /** Exact verified artifact bytes. Each read returns a detached copy. */
507
- readonly implementation: {
508
- readonly byteLength: number;
509
- readonly bytes: Uint8Array;
510
- };
511
- /** Frozen result deadline; runners must stop work and side effects when aborted. */
512
- readonly signal: AbortSignal;
513
- }): Promise<{
514
- readonly evaluation: BenchmarkEvaluation;
515
- /** Raw grader output needed to audit or reproduce the normalized result. */
516
- readonly evidence: Uint8Array;
517
- /** Runtime-checked binding between admitted code, task input, and raw output. */
518
- readonly binding: {
519
- /** Digest computed from the implementation bytes admitted to execution. */
520
- readonly implementationDigest: Sha256Digest;
521
- /** Digest of the exact runtime-verified task outcome graded by this run. */
522
- readonly taskOutcomeDigest: Sha256Digest;
523
- /** Digest computed from `evidence` before it leaves the execution boundary. */
524
- readonly outputDigest: Sha256Digest;
525
- };
526
- }>;
527
- }
528
- /** One detached request passed to the trusted environment-specific executor. */
529
- interface AgentCandidateExecutorRequest {
530
- readonly executionId: string;
531
- /** Immutable bytes from which the executor creates fresh isolated workspaces. */
532
- readonly inputs: {
533
- readonly task: AgentCandidateExecutorWorkspaceInput;
534
- readonly candidate?: AgentCandidateExecutorWorkspaceInput;
535
- readonly profile: {
536
- readonly files: readonly AgentCandidateExecutorProfileFile[];
537
- };
538
- };
539
- readonly roots: PreparedAgentCandidateExecution['roots']['execution'];
540
- readonly profilePlan: PreparedAgentCandidateExecution['profilePlan'];
541
- readonly executionPlan: PreparedAgentCandidateExecution['executionPlan'];
542
- readonly materializationReceipt: CanonicalCandidateDocument<AgentCandidateMaterializationReceipt>;
543
- readonly launch: PreparedAgentCandidateLaunch;
544
- readonly instruction: PreparedAgentCandidateInstruction;
545
- readonly resolvedModel: AgentCandidateResolvedModel;
546
- /** Mechanically enforced by the runtime plus executor process-death acknowledgement. */
547
- readonly hardLimits: Pick<AgentCandidateExecutionLimits, 'timeoutMs'>;
548
- /** Validity bound checked against protected traces; generic black-box executors cannot preempt it. */
549
- readonly observedLimits: Pick<AgentCandidateExecutionLimits, 'maxSteps'>;
550
- readonly knowledge?: PreparedAgentCandidateExecution['knowledge'];
551
- readonly trace: PreparedAgentCandidateTrace;
552
- readonly memory: AgentCandidateEffectiveMemory;
553
- }
554
- /**
555
- * Executes one prepared request inside an evaluator-owned isolation boundary.
556
- *
557
- * `request.launch.env` is the complete allowlisted environment, including
558
- * protected model, memory, and trace bindings. Implementations must not merge
559
- * ambient host variables into it. The returned capture deliberately contains
560
- * no candidate-authored usage or score fields.
561
- */
562
- interface AgentCandidateExecutorPort {
563
- execute(request: AgentCandidateExecutorRequest, context: {
564
- traceStore: TraceStore;
565
- /** Aborted by the runtime at the exact frozen wall-time deadline. */
566
- signal: AbortSignal;
567
- /** Absolute epoch-millisecond deadline owned by the runtime. */
568
- deadlineAtMs: number;
569
- }): Promise<AgentCandidateProtectedRunCapture>;
570
- /**
571
- * Kill any process/container still associated with the request, drain trace
572
- * writes, and capture the final task workspace before teardown.
573
- * The runtime calls this on success, failure, and timeout before model settlement.
574
- * Implementations must be idempotent and concurrency-safe for this exact
575
- * execution/plan pair because a fresh worker may repeat crash recovery.
576
- */
577
- stopAndCapture(request: AgentCandidateExecutorStopRequest, context: {
578
- traceStore: TraceStore;
579
- reason: 'completed' | 'failed' | 'timeout';
580
- /** Aborted at the frozen execution deadline or evaluator cleanup deadline. */
581
- signal: AbortSignal;
582
- /** Absolute execution deadline; a later stop acknowledgement cannot produce success. */
583
- deadlineAtMs: number;
584
- }): Promise<AgentCandidateExecutorFinalCapture>;
585
- }
586
- /** Opaque process identity used for termination without re-exposing launch credentials. */
587
- interface AgentCandidateExecutorStopRequest {
588
- readonly executionId: string;
589
- readonly executionPlanDigest: Sha256Digest;
590
- }
591
- interface AgentCandidateExecutorWorkspaceInput {
592
- readonly snapshot: AgentCandidateWorkspaceSnapshotEvidence;
593
- readonly files: readonly AgentCandidateExecutorWorkspaceFile[];
594
- }
595
- interface AgentCandidateExecutorWorkspaceFile {
596
- readonly path: string;
597
- readonly mode: 0o644 | 0o755;
598
- readonly bytes: Uint8Array;
599
- }
600
- interface AgentCandidateExecutorProfileFile {
601
- readonly path: string;
602
- readonly mode: 0o644 | 0o755;
603
- readonly bytes: Uint8Array;
604
- }
605
- type AgentCandidateRunFinalization = {
606
- succeeded: true;
607
- receipt: CanonicalCandidateDocument<AgentCandidateRunReceiptV2>;
608
- artifacts: {
609
- modelSettlement: AgentCandidateArtifactRef;
610
- taskOutcome: AgentCandidateArtifactRef;
611
- benchmarkResult: AgentCandidateArtifactRef;
612
- runReceipt: AgentCandidateArtifactRef;
613
- };
614
- } | {
615
- succeeded: false;
616
- reason: string;
617
- partial: {
618
- executionId: string;
619
- bundleDigest: Sha256Digest;
620
- executionPlanDigest: Sha256Digest;
621
- materializationReceiptDigest: Sha256Digest;
622
- termination?: AgentCandidateTermination;
623
- };
624
- /** Independent evaluator-gateway usage, even when execution or trace capture failed. */
625
- usage: AgentCandidateSpend | null;
626
- };
627
- /** Protected trace tags that bind a run to one prepared candidate execution. */
628
- declare const CANDIDATE_TRACE_TAGS: {
629
- readonly executionId: "tangle.candidate.execution_id";
630
- readonly bundleDigest: "tangle.candidate.bundle_digest";
631
- readonly executionPlanDigest: "tangle.candidate.execution_plan_digest";
632
- readonly materializationReceiptDigest: "tangle.candidate.materialization_receipt_digest";
633
- };
634
- /** Environment keys used to propagate immutable candidate trace identity. */
635
- declare const CANDIDATE_TRACE_ENV: {
636
- readonly executionId: "TANGLE_CANDIDATE_EXECUTION_ID";
637
- readonly bundleDigest: "TANGLE_CANDIDATE_BUNDLE_DIGEST";
638
- readonly executionPlanDigest: "TANGLE_CANDIDATE_EXECUTION_PLAN_DIGEST";
639
- readonly materializationReceiptDigest: "TANGLE_CANDIDATE_MATERIALIZATION_RECEIPT_DIGEST";
640
- readonly traceRunId: "TANGLE_TRACE_RUN_ID";
641
- };
642
-
643
- /** Extract the complete durable claim from a prepared execution. */
644
- declare function candidateExecutionClaim(prepared: PreparedAgentCandidateExecution): AgentCandidateExecutionClaim;
645
-
646
- /** Durable one-shot lifecycle for candidate execution attempts. */
647
-
648
- /** Non-secret identities a trusted recovery worker needs to close an abandoned attempt. */
649
- interface AgentCandidateExecutionCleanupHandles {
650
- readonly preparationId: string;
651
- readonly modelGrantDigest: Sha256Digest;
652
- readonly resolvedModel: AgentCandidateResolvedModel;
653
- readonly traceRunId: string;
654
- readonly cleanupTimeoutMs: number;
655
- readonly memory?: {
656
- readonly accessDigest: Sha256Digest;
657
- readonly effectiveNamespace: string;
658
- };
659
- }
660
- /** Immutable signed identity stored for one execution attempt. */
661
- interface AgentCandidateExecutionClaim {
662
- readonly executionId: string;
663
- readonly attempt: number;
664
- readonly maxAttempts: number;
665
- readonly retryPolicy: AgentCandidateAttemptPolicy['retryPolicy'];
666
- readonly bundleDigest: Sha256Digest;
667
- readonly executionPlanDigest: Sha256Digest;
668
- /** Frozen plan identity with only attempt number and per-attempt grant identity normalized. */
669
- readonly retryLineageDigest: Sha256Digest;
670
- /** The winning lease stops authorizing a new terminal write at this instant. */
671
- readonly leaseExpiresAtMs: number;
672
- /** Frozen budget for task verification, executable grading, and receipt construction. */
673
- readonly resultTimeoutMs: number;
674
- /** Non-secret handles retained so an expired attempt can be closed and reconciled. */
675
- readonly cleanup: AgentCandidateExecutionCleanupHandles;
676
- }
677
- /** Secret capability required to finish the acquired attempt. */
678
- interface AgentCandidateExecutionLease {
679
- readonly executionId: string;
680
- readonly attempt: number;
681
- readonly token: string;
682
- readonly expiresAtMs: number;
683
- }
684
- /** Only the first class is retryable, and only when the closed model ledger has zero calls. */
685
- type AgentCandidateExecutionFailureClass = 'pre-model-infrastructure' | 'execution' | 'post-model-infrastructure' | 'unknown';
686
- /** Exact fixed-point usage proven by the closed evaluator model ledger. */
687
- interface AgentCandidateExecutionUsage {
688
- readonly costUsdNanos: number;
689
- readonly inputTokens: number;
690
- readonly outputTokens: number;
691
- readonly cachedInputTokens: number;
692
- readonly reasoningTokens: number;
693
- readonly modelCalls: number;
694
- }
695
- /** Evaluator-owned terminal facts staged durably before the terminal CAS. */
696
- type AgentCandidateExecutionTerminalResult = {
697
- readonly schemaVersion: 1;
698
- readonly status: 'succeeded';
699
- readonly usage: AgentCandidateExecutionUsage;
700
- readonly modelSettlement: AgentCandidateArtifactRef;
701
- readonly taskOutcome: AgentCandidateArtifactRef;
702
- readonly benchmarkResult: AgentCandidateArtifactRef;
703
- readonly runReceipt: AgentCandidateArtifactRef;
704
- } | {
705
- readonly schemaVersion: 1;
706
- readonly status: 'failed';
707
- readonly failureClass: AgentCandidateExecutionFailureClass;
708
- readonly usage: AgentCandidateExecutionUsage;
709
- readonly modelSettlement: AgentCandidateArtifactRef;
710
- readonly failureEvidence?: AgentCandidateArtifactRef;
711
- };
712
- /** Durable terminal record for one acquired execution attempt. */
713
- type AgentCandidateExecutionTerminalRecord = AgentCandidateExecutionTerminalResult & {
714
- readonly executionId: string;
715
- readonly attempt: number;
716
- readonly bundleDigest: Sha256Digest;
717
- readonly executionPlanDigest: Sha256Digest;
718
- /** RFC 8785 SHA-256 of this record with `terminalDigest` omitted. */
719
- readonly terminalDigest: Sha256Digest;
720
- };
721
- /** Monotonic durable phase: the second value means candidate code could have started. */
722
- type AgentCandidateExecutionPhase = 'claimed' | 'candidate-may-run';
723
- /** Trusted, independently observed closure facts for one expired winning lease. */
724
- interface AgentCandidateExecutionRecoveryEvidence {
725
- readonly failureClass: AgentCandidateExecutionFailureClass;
726
- readonly usage: AgentCandidateExecutionUsage;
727
- readonly modelSettlement: AgentCandidateArtifactRef;
728
- readonly failureEvidence?: AgentCandidateArtifactRef;
729
- readonly process: {
730
- readonly stopped: true;
731
- readonly executionPlanDigest: Sha256Digest;
732
- };
733
- readonly model: {
734
- readonly closed: true;
735
- readonly preparationId: string;
736
- readonly grantDigest: Sha256Digest;
737
- };
738
- readonly memory?: {
739
- readonly closed: true;
740
- readonly preparationId: string;
741
- readonly accessDigest: Sha256Digest;
742
- readonly effectiveNamespace: string;
743
- };
744
- }
745
- interface AgentCandidateExecutionAttemptRef {
746
- readonly executionId: string;
747
- readonly attempt: number;
748
- }
749
- /** Persisted state available to a fresh trusted recovery worker after a crash. */
750
- interface AgentCandidateExecutionAttemptRecord {
751
- readonly claim: AgentCandidateExecutionClaim;
752
- readonly phase: AgentCandidateExecutionPhase;
753
- /** Durable outbox content written before the terminal compare-and-set. */
754
- readonly staged?: AgentCandidateExecutionTerminalRecord;
755
- readonly terminal?: AgentCandidateExecutionTerminalRecord;
756
- }
757
- /** Result of atomically claiming one execution attempt. */
758
- type AgentCandidateExecutionClaimResult = {
759
- readonly acquired: true;
760
- readonly claim: AgentCandidateExecutionClaim;
761
- readonly lease: AgentCandidateExecutionLease;
762
- } | {
763
- readonly acquired: false;
764
- readonly reason: 'already-claimed';
765
- /** The durable winner already occupying this execution-attempt slot. */
766
- readonly claim: AgentCandidateExecutionClaim;
767
- /** True only when every signed claim field matches the durable winner. */
768
- readonly exactReplay: boolean;
769
- } | {
770
- readonly acquired: false;
771
- readonly reason: 'retry-not-eligible';
772
- readonly claim: AgentCandidateExecutionClaim;
773
- readonly detail: AgentCandidateRetryRejection;
774
- };
775
- /** Result of atomically recording an attempt's terminal facts. */
776
- type AgentCandidateExecutionFinishResult = {
777
- readonly finished: true;
778
- readonly terminal: AgentCandidateExecutionTerminalRecord;
779
- } | {
780
- readonly finished: false;
781
- readonly terminal: AgentCandidateExecutionTerminalRecord;
782
- /** True when a repeated finish supplied the same terminal digest. */
783
- readonly exactReplay: boolean;
784
- };
785
- /** Result of durably staging the one immutable terminal outbox entry. */
786
- type AgentCandidateExecutionStageResult = {
787
- readonly staged: true;
788
- readonly terminal: AgentCandidateExecutionTerminalRecord;
789
- } | {
790
- readonly staged: false;
791
- readonly terminal: AgentCandidateExecutionTerminalRecord;
792
- readonly exactReplay: boolean;
793
- };
794
- /** Result of crossing the irreversible candidate-may-run boundary. */
795
- type AgentCandidateExecutionPhaseResult = {
796
- readonly marked: true;
797
- readonly phase: 'candidate-may-run';
798
- } | {
799
- readonly marked: false;
800
- readonly phase: 'candidate-may-run';
801
- };
802
- type AgentCandidateRetryRejection = 'prior-attempt-missing' | 'prior-attempt-running' | 'prior-attempt-succeeded' | 'prior-attempt-spent-model-calls' | 'prior-attempt-not-pre-model-infrastructure' | 'retry-lineage-mismatch';
803
- /**
804
- * Atomic one-shot store for candidate execution attempts.
805
- *
806
- * Implementations must linearize both methods across every process sharing the
807
- * store. Terminal publication is deliberately two-step: `stageTerminal`
808
- * fsyncs the complete immutable outbox record, then `finish` publishes exactly
809
- * those staged bytes by digest. A crash between the two leaves recoverable
810
- * evidence rather than an ambiguous completed run.
811
- */
812
- interface AgentCandidateExecutionClaimStore {
813
- tryClaim(claim: AgentCandidateExecutionClaim): Promise<AgentCandidateExecutionClaimResult>;
814
- getAttempt(attempt: AgentCandidateExecutionAttemptRef): Promise<AgentCandidateExecutionAttemptRecord | undefined>;
815
- /** Persist the point after which candidate code may have run. */
816
- markCandidateMayRun(lease: AgentCandidateExecutionLease): Promise<AgentCandidateExecutionPhaseResult>;
817
- /** Fsync the complete terminal record into the durable outbox. */
818
- stageTerminal(lease: AgentCandidateExecutionLease, result: AgentCandidateExecutionTerminalResult): Promise<AgentCandidateExecutionStageResult>;
819
- /** Publish exactly the staged terminal identified by `terminalDigest`. */
820
- finish(lease: AgentCandidateExecutionLease, terminalDigest: Sha256Digest): Promise<AgentCandidateExecutionFinishResult>;
821
- /**
822
- * Write a failed terminal only after the lease expired and a trusted worker
823
- * independently proved process death plus model and memory closure.
824
- */
825
- recoverExpired(attempt: AgentCandidateExecutionAttemptRef, evidence: AgentCandidateExecutionRecoveryEvidence): Promise<AgentCandidateExecutionFinishResult>;
826
- }
827
- interface InMemoryAgentCandidateExecutionClaimStoreOptions {
828
- /** Testable evaluator clock; defaults to `Date.now`. */
829
- now?: () => number;
830
- }
831
- /** Single-process lifecycle implementation. */
832
- declare class InMemoryAgentCandidateExecutionClaimStore implements AgentCandidateExecutionClaimStore {
833
- private readonly claims;
834
- private readonly now;
835
- constructor(options?: InMemoryAgentCandidateExecutionClaimStoreOptions);
836
- tryClaim(requested: AgentCandidateExecutionClaim): Promise<AgentCandidateExecutionClaimResult>;
837
- getAttempt(requestedAttempt: AgentCandidateExecutionAttemptRef): Promise<AgentCandidateExecutionAttemptRecord | undefined>;
838
- markCandidateMayRun(requestedLease: AgentCandidateExecutionLease): Promise<AgentCandidateExecutionPhaseResult>;
839
- stageTerminal(requestedLease: AgentCandidateExecutionLease, result: AgentCandidateExecutionTerminalResult): Promise<AgentCandidateExecutionStageResult>;
840
- finish(requestedLease: AgentCandidateExecutionLease, requestedTerminalDigest: Sha256Digest): Promise<AgentCandidateExecutionFinishResult>;
841
- recoverExpired(requestedAttempt: AgentCandidateExecutionAttemptRef, evidence: AgentCandidateExecutionRecoveryEvidence): Promise<AgentCandidateExecutionFinishResult>;
842
- private requireClaim;
843
- }
844
-
845
- interface FileAgentCandidateExecutionClaimStoreOptions {
846
- /** Evaluator-owned directory shared by every process allowed to execute candidates. */
847
- directory: string;
848
- /** Testable evaluator clock; defaults to `Date.now`. */
849
- now?: () => number;
850
- }
851
- /** Cross-process lifecycle implemented as fsynced, create-if-absent records. */
852
- declare class FileAgentCandidateExecutionClaimStore implements AgentCandidateExecutionClaimStore {
853
- private readonly directory;
854
- private readonly now;
855
- constructor(options: FileAgentCandidateExecutionClaimStoreOptions);
856
- tryClaim(requested: AgentCandidateExecutionClaim): Promise<AgentCandidateExecutionClaimResult>;
857
- getAttempt(requestedAttempt: AgentCandidateExecutionAttemptRef): Promise<AgentCandidateExecutionAttemptRecord | undefined>;
858
- markCandidateMayRun(requestedLease: AgentCandidateExecutionLease): Promise<AgentCandidateExecutionPhaseResult>;
859
- stageTerminal(requestedLease: AgentCandidateExecutionLease, result: AgentCandidateExecutionTerminalResult): Promise<AgentCandidateExecutionStageResult>;
860
- finish(requestedLease: AgentCandidateExecutionLease, requestedTerminalDigest: Sha256Digest): Promise<AgentCandidateExecutionFinishResult>;
861
- recoverExpired(requestedAttempt: AgentCandidateExecutionAttemptRef, evidence: AgentCandidateExecutionRecoveryEvidence): Promise<AgentCandidateExecutionFinishResult>;
862
- private storedAttempt;
863
- private transitionState;
864
- private retryFailure;
865
- private ownerPublication;
866
- private claimPath;
867
- private terminalPath;
868
- private transitionPath;
869
- }
870
-
871
- interface DisposePreparedAgentCandidateOptions {
872
- cleanupTimeoutMs?: number;
873
- }
874
- /** Revoke reservations held by a prepared candidate that will not be executed. */
875
- declare function disposePreparedAgentCandidateExecution(prepared: PreparedAgentCandidateExecution, options?: DisposePreparedAgentCandidateOptions): Promise<{
876
- disposed: true;
877
- }>;
878
-
879
- interface ExecutePreparedAgentCandidateOptions {
880
- executor: AgentCandidateExecutorPort;
881
- grader: AgentCandidateBenchmarkGraderPort;
882
- outputArtifacts: AgentCandidateOutputArtifactPort;
883
- traceStore: TraceStore;
884
- /** Long-lived evaluator-owned store shared by every process that can run this benchmark. */
885
- claimStore: AgentCandidateExecutionClaimStore;
886
- /** Maximum time to prove process death and revoke protected access after a run ends. */
887
- cleanupTimeoutMs?: number;
888
- /** Maximum time for task verification, executable grading, and receipt construction. */
889
- resultTimeoutMs?: number;
890
- }
891
- /** Executes and finalizes one durably claimed candidate without exposing an unproven result. */
892
- declare function executePreparedAgentCandidate(prepared: PreparedAgentCandidateExecution, options: ExecutePreparedAgentCandidateOptions): Promise<AgentCandidateRunFinalization>;
893
-
894
- /** Persist evaluator evidence, read it back, and bind the returned locator to the exact bytes. */
895
- declare function persistCandidateOutputArtifact(port: AgentCandidateOutputArtifactPort, input: {
896
- executionId: string;
897
- purpose: AgentCandidateOutputPurpose;
898
- bytes: Uint8Array;
899
- signal?: AbortSignal;
900
- }): Promise<AgentCandidateArtifactRef>;
901
-
902
- interface PrepareAgentCandidateExecutionOptions {
903
- cleanupTimeoutMs?: number;
904
- /** Maximum time for task verification, executable grading, and receipt construction. */
905
- resultTimeoutMs?: number;
906
- }
907
- /** Materializes a verified candidate into one immutable evaluator-owned execution plan. */
908
- declare function prepareAgentCandidateExecution(candidate: VerifiedAgentCandidate, task: AgentCandidateTaskExecution, ports: AgentCandidateExecutionPorts, options?: PrepareAgentCandidateExecutionOptions): Promise<PreparedAgentCandidateExecution>;
909
-
910
- type AgentCandidateModelGrantReserveInput = Parameters<AgentCandidateModelPort['reserveGrant']>[0];
911
- type AgentCandidateModelGrantActivateInput = Parameters<AgentCandidateModelPort['activateGrant']>[0];
912
- type AgentCandidateModelGrantSettleInput = Parameters<AgentCandidateModelPort['settleGrant']>[0];
913
- /** Secret-free response from the service's reservation endpoint. */
914
- type AgentCandidateModelGrantReservation = AgentCandidateProtectedModelReservation;
915
- /**
916
- * Narrow transport contract for a service that owns scoped model credentials
917
- * and the authoritative per-call usage ledger.
918
- *
919
- * An HTTP client can bind these methods to control-plane endpoints. Keeping
920
- * transport out of the runtime prevents parent credentials, endpoint paths,
921
- * and retry policy from becoming part of the portable candidate contract.
922
- */
923
- interface AgentCandidateModelGrantClient {
924
- reserve(input: AgentCandidateModelGrantReserveInput): Promise<AgentCandidateModelGrantReservation>;
925
- activate(input: AgentCandidateModelGrantActivateInput): Promise<AgentCandidateProtectedModelActivation>;
926
- settle(input: AgentCandidateModelGrantSettleInput): Promise<AgentCandidateProtectedModelSettlement>;
927
- }
928
- interface CreateProtectedAgentCandidateModelPortOptions {
929
- client: AgentCandidateModelGrantClient;
930
- /** Catalog/snapshot resolution stays separate from credential issuance. */
931
- resolveModel: AgentCandidateModelPort['resolve'];
932
- /** The only public DNS name candidate processes may reach for inference. */
933
- gatewayDomain: string;
934
- /** Exact environment names the activation endpoint must return, no more or fewer. */
935
- activationEnvNames: readonly string[];
936
- }
937
- /**
938
- * Bind a protected model-grant service to the immutable candidate runtime.
939
- *
940
- * The service remains the authority for expiry, admission, revocation, and
941
- * metering. This adapter independently checks every response before allowing
942
- * it to cross into candidate execution or durable receipt finalization.
943
- */
944
- declare function createProtectedAgentCandidateModelPort(options: CreateProtectedAgentCandidateModelPortOptions): AgentCandidateModelPort;
945
-
946
- interface RecoverExpiredAgentCandidateOptions {
947
- attempt: AgentCandidateExecutionAttemptRef;
948
- claimStore: AgentCandidateExecutionClaimStore;
949
- executor: AgentCandidateExecutorPort;
950
- traceStore: TraceStore;
951
- ports: Pick<AgentCandidateExecutionPorts, 'models' | 'memory'>;
952
- outputArtifacts: AgentCandidateOutputArtifactPort;
953
- cleanupTimeoutMs?: number;
954
- /** Evaluator clock; must be the same clock used by the claim store. */
955
- now?: () => number;
956
- }
957
- /** Close an expired crashed attempt from persisted non-secret handles, then record failure. */
958
- declare function recoverExpiredAgentCandidateExecution(options: RecoverExpiredAgentCandidateOptions): Promise<AgentCandidateExecutionFinishResult>;
959
-
960
- /** Verifies every digest, resource, workspace, and Git object in a candidate bundle. */
961
- declare function verifyAgentCandidateBundle(input: unknown, ports: AgentCandidateVerificationPorts): Promise<VerifiedAgentCandidate>;
962
-
963
167
  /**
964
168
  *
965
169
  * Per-call resilience policy for participant backends: deadline, retry with
@@ -1970,166 +1174,6 @@ declare function toolBuildPrompt(args: FindingsArg): string;
1970
1174
  /** Build the starting instruction for a coder agent tasked with implementing a new MCP server. */
1971
1175
  declare function mcpBuildPrompt(args: FindingsArg): string;
1972
1176
 
1973
- /**
1974
- *
1975
- * `improve` — the ONE public, surface-pluggable RSI verb.
1976
- *
1977
- * A thin facade over agent-eval's `selfImprove` (the held-out-gated closed
1978
- * loop). It removes the two things a caller otherwise has to know to drive the
1979
- * loop by hand: WHICH `MutableSurface` of the profile is being optimized, and
1980
- * WHICH `SurfaceProposer` mutates that surface. You name a `surface`; the
1981
- * facade picks the matching default proposer, extracts the baseline surface from
1982
- * the profile, runs `selfImprove`, and (on a ship verdict) writes the promoted
1983
- * winner back into the corresponding profile field.
1984
- *
1985
- * - `surface: 'prompt'` → `gepaProposer` mutates `profile.prompt.systemPrompt`.
1986
- * - `surface: 'skills'` → `skillOptProposer` mutates a skills document string.
1987
- * - `surface: 'rollout-policy'` → `rolloutPolicyProposer` mutates the
1988
- * inference-time `StructuralRolloutPolicy` dials ({ k, repairRounds, testgen })
1989
- * persisted in `profile.extensions['structural-rollout']` — deterministic
1990
- * bounded neighbor enumeration; the held-out gate does the deciding. No-op
1991
- * (nothing proposed, nothing shipped) when the profile has no such extension.
1992
- * - `surface` ∈ {`tools`, `mcp`, `hooks`, `code`} → no zero-config default
1993
- * proposer exists (a code/config proposer needs caller-supplied wiring — a
1994
- * worktree repo root, a candidate generator, a serializer). The facade
1995
- * requires an explicit `opts.generator` for these and throws a `ConfigError`
1996
- * otherwise. This is a designed boundary, not a missing default: there is
1997
- * no safe value the facade could invent for those seams.
1998
- *
1999
- * Everything else (`scenarios`, `judge`, `agent`, `budget`, `llm`) passes
2000
- * straight through to `selfImprove`.
2001
- *
2002
- * @experimental
2003
- */
2004
-
2005
- /** The agent-profile lever `improve` optimizes. Mirrors the AgentProfile-law
2006
- * profile levers; `code` is the implementation-tier surface, `rollout-policy`
2007
- * the inference-time structuralRollout dials
2008
- * (`profile.extensions['structural-rollout']`). */
2009
- type ImproveSurface = 'prompt' | 'skills' | 'tools' | 'mcp' | 'hooks' | 'code' | 'rollout-policy';
2010
- interface ImproveOptions<TScenario extends Scenario$1, TArtifact> {
2011
- /** Which profile lever to optimize. Default `'prompt'`. Selects the default
2012
- * generator + the baseline-surface extraction shape. */
2013
- surface?: ImproveSurface;
2014
- /** The `SurfaceProposer` that mutates the surface. When unset, the facade
2015
- * picks the default for `surface` (`gepaProposer` for prompt, `skillOptProposer`
2016
- * for skills); surfaces with no default REQUIRE this (fail-loud otherwise). */
2017
- generator?: SurfaceProposer;
2018
- /** Gate mode. `'holdout'` (default) runs the held-out promotion gate;
2019
- * `'none'` is a baseline-only run (`budget.generations = 0`). */
2020
- gate?: 'holdout' | 'none';
2021
- /** Scenarios to evaluate against. Passthrough to `selfImprove`. */
2022
- scenarios: TScenario[];
2023
- /** Judge that scores artifacts. Passthrough to `selfImprove`. */
2024
- judge: JudgeConfig<TArtifact, TScenario>;
2025
- /** The agent under improvement — same shape as `selfImprove.agent`: it takes
2026
- * the current surface + scenario + ctx and returns the artifact to judge. */
2027
- agent: (surface: MutableSurface, scenario: TScenario, ctx: DispatchContext) => Promise<TArtifact>;
2028
- /** Budget + loop shape. Passthrough; `gate: 'none'` forces `generations = 0`. */
2029
- budget?: SelfImproveBudget;
2030
- /** LLM config. Passthrough to `selfImprove` AND used to construct the default
2031
- * reflective proposer (`gepaProposer`/`skillOptProposer`) when `generator` is unset. */
2032
- llm?: SelfImproveLlm;
2033
- /** Restrict the run to this subset of models. When set, the reflection model
2034
- * (`llm.model`, or the default when unset) must be a member, or `improve()` throws
2035
- * a `ConfigError` before the generator is built. Unset = unrestricted. */
2036
- allowedModels?: readonly string[];
2037
- /** Run directory passthrough to `selfImprove`. Pass a REAL path to make the loop
2038
- * durable: campaign cells + the loop provenance record land on the filesystem as
2039
- * they complete, so a multi-hour search survives a process/infra death instead of
2040
- * losing every generation with it (the default `mem://` run keeps everything
2041
- * in-process). */
2042
- runDir?: string;
2043
- /** Per-generation findings producer passthrough (see selfImprove.analyzeGeneration).
2044
- * DEFAULT: the built-in failure distiller — after each generation it turns the
2045
- * worst-scoring/errored cells into structured findings ({ scenario, composite,
2046
- * notes, error }) for the NEXT proposal round, so the proposer reasons over what
2047
- * actually failed instead of a static seed. Pass your own producer (e.g. a
2048
- * trace-analyst over the runDir's traces) to replace it; pass `null` to disable
2049
- * and keep the static `findings` all the way through. */
2050
- analyzeGeneration?: SelfImproveOptions<TScenario, TArtifact>['analyzeGeneration'] | null;
2051
- /** META-HARNESS mode: instead of the ~400-char distilled findings, feed the
2052
- * proposer RAW-TRACE FILESYSTEM CONTEXT — the PATHS into the prior generation's
2053
- * real run traces under `runDir` (per-cell `spans.jsonl` event logs +
2054
- * `cached-result.json` scores + artifacts) plus a `grep`/`cat`-to-diagnose
2055
- * instruction — so the coding agent reads the actual failures itself rather than
2056
- * a pre-summary. Requires a REAL `runDir` (that is where the traces live).
2057
- * Ignored when `analyzeGeneration` is set explicitly (that wins) or is `null`
2058
- * (disabled). Equivalent to `analyzeGeneration: rawTraceDistiller()`; this flag
2059
- * is the one-line enable. Default `false` (the distiller stays the default). */
2060
- rawTraceContext?: boolean;
2061
- /** CODE-surface wiring with prompt-parity DX: name `surface: 'code'`, point at a
2062
- * repo, and the facade assembles the whole candidate pipeline — git worktrees
2063
- * (`gitWorktreeAdapter`) driven by `improvementDriver` with the full agentic
2064
- * generator (a real coding harness edits each candidate worktree; a `verify`
2065
- * hook gates candidates before they are ever measured). Ignored when
2066
- * `opts.generator` is supplied. Without either, `surface: 'code'` still fails
2067
- * loud — there is no safe zero-config repo to invent. */
2068
- code?: ImproveCodeOptions;
2069
- /** SKILLS-surface wiring for real skill-DOCUMENT optimization. Without this,
2070
- * `surface: 'skills'` optimizes the profile's skills REFS array (file pointers)
2071
- * — which `skillOptProposer` (a document patcher) cannot meaningfully edit.
2072
- * Provide the document CONTENT to optimize + a `writeBack` to persist the
2073
- * shipped winner (the profile ref points at a file the caller owns). This is
2074
- * what makes skillOpt reachable through improve(). */
2075
- skills?: ImproveSkillsOptions;
2076
- /** Storage passthrough to `selfImprove`; overrides the default chosen from `runDir`. */
2077
- storage?: SelfImproveOptions<TScenario, TArtifact>['storage'];
2078
- }
2079
- interface ImproveSkillsOptions {
2080
- /** The skill document's current text — the baseline `skillOptProposer` patches. */
2081
- document: string;
2082
- /** Persist the shipped winner document (write the file the profile ref points at).
2083
- * Called only on a ship verdict. When omitted, the winner is still returned in
2084
- * `result.raw.winner.surface` for the caller to materialize. */
2085
- writeBack?: (winnerDocument: string) => void;
2086
- }
2087
- interface ImproveCodeOptions {
2088
- /** Repo root candidate worktrees fork from. */
2089
- repoRoot: string;
2090
- /** Base ref candidates fork from. Default `main`. */
2091
- baseRef?: string;
2092
- /** Directory worktrees are created under. Default `<repoRoot>/.worktrees`. */
2093
- worktreeDir?: string;
2094
- /** Coding harness the agentic generator runs in each worktree. Default `claude`. */
2095
- harness?: LocalHarness;
2096
- /** Verify a candidate worktree before it becomes a measurable surface; failures
2097
- * feed the next shot (see `agenticGenerator.verify` / `commandVerifier`). */
2098
- verify?: Verifier;
2099
- /** Per-shot wall-clock timeout for the harness (ms). */
2100
- timeoutMs?: number;
2101
- /** Byte-producer override — the test seam and the escape hatch for custom
2102
- * candidate production. When set, `harness`/`verify`/`timeoutMs` are unused. */
2103
- generator?: CandidateGenerator;
2104
- }
2105
- interface ImproveResult<TScenario extends Scenario$1, TArtifact> {
2106
- /** The profile after improvement: the winner surface applied back into the
2107
- * matching field when the gate shipped, else the input profile unchanged. */
2108
- profile: AgentProfile$1;
2109
- /** True when `gateDecision === 'ship'`. */
2110
- shipped: boolean;
2111
- /** Held-out lift (`winner − baseline` composite). */
2112
- lift: number;
2113
- /** The five-valued gate verdict from `selfImprove`. */
2114
- gateDecision: SelfImproveResult<TScenario, TArtifact>['gateDecision'];
2115
- /** Full `selfImprove` result for advanced inspection. */
2116
- raw: SelfImproveResult<TScenario, TArtifact>;
2117
- }
2118
- /**
2119
- * Run the held-out-gated self-improvement loop on ONE profile surface.
2120
- *
2121
- * @example Optimize the system prompt, default holdout gate:
2122
- *
2123
- * const out = await improve(profile, findings, {
2124
- * surface: 'prompt',
2125
- * scenarios,
2126
- * judge,
2127
- * agent: (surface, scenario, ctx) => runAgent(surface, scenario, ctx.signal),
2128
- * })
2129
- * if (out.shipped) deploy(out.profile)
2130
- */
2131
- declare function improve<TScenario extends Scenario$1, TArtifact>(profile: AgentProfile$1, findings: unknown[], opts: ImproveOptions<TScenario, TArtifact>): Promise<ImproveResult<TScenario, TArtifact>>;
2132
-
2133
1177
  /**
2134
1178
  *
2135
1179
  * `rawTraceDistiller` — the meta-harness `analyzeGeneration` producer.
@@ -2274,7 +1318,7 @@ declare const ROLLOUT_POLICY_BOUNDS: {
2274
1318
  * violates the policy's own invariants: the no-op signal. Unknown dials are
2275
1319
  * dropped; `diverse`/`temperature` ride through untouched (the proposer never
2276
1320
  * mutates them — `diverse` is a measured paired null). */
2277
- declare function parseRolloutPolicy(surface: MutableSurface$1): StructuralRolloutPolicy | undefined;
1321
+ declare function parseRolloutPolicy(surface: MutableSurface): StructuralRolloutPolicy | undefined;
2278
1322
  /** Normalize an untyped policy bag (a parsed surface or a profile extension) into
2279
1323
  * a full `StructuralRolloutPolicy`, defaults merged. Returns `undefined` when any
2280
1324
  * present dial violates the policy invariants (mirrors `resolvePolicy`: integer
@@ -2306,7 +1350,7 @@ declare function enumerateNeighborPolicies(policy: StructuralRolloutPolicy): Str
2306
1350
  * carries no policy (the profile never opted in) — an empty proposal is the
2307
1351
  * loop-native no-op, mirroring `improvementDriver`'s no-findings behavior.
2308
1352
  */
2309
- declare function rolloutPolicyProposer(): SurfaceProposer$1;
1353
+ declare function rolloutPolicyProposer(): SurfaceProposer;
2310
1354
 
2311
1355
  /**
2312
1356
  *
@@ -2527,115 +1571,6 @@ declare function runAgentTask<TState, TAction, TActionResult, TEval extends Cont
2527
1571
  */
2528
1572
  declare function runAgentTaskStream<TInput extends AgentBackendInput = AgentBackendInput>(options: RunAgentTaskStreamOptions<TInput>): AsyncIterable<RuntimeStreamEvent>;
2529
1573
 
2530
- /**
2531
- *
2532
- * Sanitization for runtime telemetry. The rule: nothing user-controlled leaks
2533
- * unless the caller opts in with a `RuntimeTelemetryOptions` flag. This is the
2534
- * envelope that ends up in `agent_run.metadata.runtimeEvents` on every
2535
- * consumer, so the default must be safe.
2536
- *
2537
- * @stable
2538
- */
2539
-
2540
- /** @stable */
2541
- interface RuntimeTelemetryOptions {
2542
- /**
2543
- * Include raw task inputs. Off by default because task inputs often contain
2544
- * customer facts, credentials, source text, or internal IDs.
2545
- */
2546
- includeInputs?: boolean;
2547
- /** Include requirement descriptions. Secret requirements are always redacted. */
2548
- includeRequirementDescriptions?: boolean;
2549
- /** Include evidence IDs. Off by default; counts are safer for shared reports. */
2550
- includeEvidenceIds?: boolean;
2551
- /** Include user answers from question preflight. Off by default. */
2552
- includeUserAnswers?: boolean;
2553
- /** Include action payloads and action results for control steps. Off by default. */
2554
- includeControlPayloads?: boolean;
2555
- /** Include task metadata. Off by default because metadata may carry IDs or policy internals. */
2556
- includeMetadata?: boolean;
2557
- /** Include eval detail/evidence strings. Off by default because validators may echo private input. */
2558
- includeEvalDetails?: boolean;
2559
- }
2560
- /** @stable */
2561
- interface SanitizedKnowledgeRequirement {
2562
- id: string;
2563
- description?: string;
2564
- requiredFor: string[];
2565
- category: KnowledgeRequirement['category'];
2566
- acquisitionMode: KnowledgeRequirement['acquisitionMode'];
2567
- importance: KnowledgeRequirement['importance'];
2568
- freshness: KnowledgeRequirement['freshness'];
2569
- sensitivity: KnowledgeRequirement['sensitivity'];
2570
- confidenceNeeded: number;
2571
- currentConfidence: number;
2572
- evidenceCount: number;
2573
- evidenceIds?: string[];
2574
- fallbackPolicy: KnowledgeRequirement['fallbackPolicy'];
2575
- }
2576
- /** @stable */
2577
- interface SanitizedKnowledgeReadinessReport {
2578
- taskId: string;
2579
- readinessScore: number;
2580
- recommendedAction: KnowledgeReadinessReport['recommendedAction'];
2581
- severity: KnowledgeReadinessReport['severity'];
2582
- reason: string;
2583
- blockingMissingRequirements: SanitizedKnowledgeRequirement[];
2584
- nonBlockingGaps: SanitizedKnowledgeRequirement[];
2585
- evidenceCount: number;
2586
- evidenceIds?: string[];
2587
- missingRequirementIds: string[];
2588
- }
2589
- /** Strip PII and large blobs from a `KnowledgeReadinessReport` for safe telemetry emission. @stable */
2590
- declare function sanitizeKnowledgeReadinessReport(report: KnowledgeReadinessReport, options?: RuntimeTelemetryOptions): SanitizedKnowledgeReadinessReport;
2591
- /** Reduce an `AgentRuntimeEvent` to a PII-safe, serializable plain object for telemetry. @stable */
2592
- declare function sanitizeAgentRuntimeEvent<TState, TAction, TActionResult, TEval extends ControlEvalResult>(event: AgentRuntimeEvent<TState, TAction, TActionResult, TEval>, options?: RuntimeTelemetryOptions): Record<string, unknown>;
2593
- /** Reduce a `RuntimeStreamEvent` to a PII-safe, serializable plain object for telemetry. @stable */
2594
- declare function sanitizeRuntimeStreamEvent(event: RuntimeStreamEvent, options?: RuntimeTelemetryOptions): Record<string, unknown>;
2595
- /** @stable */
2596
- interface RuntimeEventCollector<TState = unknown, TAction = unknown, TActionResult = unknown, TEval extends ControlEvalResult = ControlEvalResult> {
2597
- onEvent: (event: AgentRuntimeEvent<TState, TAction, TActionResult, TEval>) => void;
2598
- events: Array<Record<string, unknown>>;
2599
- }
2600
- /** @stable */
2601
- type RuntimeStreamEventSink = (event: RuntimeStreamEvent) => void;
2602
- /** @stable */
2603
- interface RuntimeStreamEventSummary {
2604
- /** Total count of sanitized events collected. */
2605
- eventCount: number;
2606
- /** Count of events per `type`. Useful for log-line summaries. */
2607
- eventCountsByType: Record<string, number>;
2608
- /** First session id observed in a `session_created` / `session_resumed` event, if any. */
2609
- firstSessionId?: string;
2610
- /** Last `final` event's status, if a final event was observed. */
2611
- finalStatus?: AgentTaskStatus;
2612
- /** Last `final` event's reason, if a final event was observed. */
2613
- finalReason?: string;
2614
- /** Concatenated `text_delta.text` across the stream, even when payloads are redacted. */
2615
- finalText: string;
2616
- }
2617
- /** @stable */
2618
- interface RuntimeStreamEventCollector {
2619
- onEvent: RuntimeStreamEventSink;
2620
- events: Array<Record<string, unknown>>;
2621
- /** Snapshot of a small streaming-flavored summary derived from collected events. */
2622
- summary(): RuntimeStreamEventSummary;
2623
- }
2624
- /** Build an in-memory collector that sanitizes and accumulates `AgentRuntimeEvent`s for inspection. @stable */
2625
- declare function createRuntimeEventCollector<TState = unknown, TAction = unknown, TActionResult = unknown, TEval extends ControlEvalResult = ControlEvalResult>(options?: RuntimeTelemetryOptions): RuntimeEventCollector<TState, TAction, TActionResult, TEval>;
2626
- /**
2627
- *
2628
- * Streaming-event counterpart of `createRuntimeEventCollector`. Pass each
2629
- * event yielded by `runAgentTaskStream` through `onEvent` and read the
2630
- * sanitized copies off `events`; the same `RuntimeTelemetryOptions` redaction
2631
- * flags apply. Kept distinct from `createRuntimeEventCollector` because the
2632
- * stream and non-stream event shapes overlap on `type` literals — dispatching
2633
- * on `type` alone would misroute events.
2634
- *
2635
- * @stable
2636
- */
2637
- declare function createRuntimeStreamEventCollector(options?: RuntimeTelemetryOptions): RuntimeStreamEventCollector;
2638
-
2639
1574
  /**
2640
1575
  *
2641
1576
  * Session helpers + an in-memory `RuntimeSessionStore` implementation suitable
@@ -2842,4 +1777,4 @@ interface StreamToolLoopOptions<Raw> {
2842
1777
  * `capped` if it stops for any non-completed reason with calls still pending. */
2843
1778
  declare function streamToolLoop<Raw>(opts: StreamToolLoopOptions<Raw>): AsyncGenerator<StreamToolLoopYield<Raw>, void, unknown>;
2844
1779
 
2845
- export { AgentBackendContext, AgentBackendInput, type AgentBackendKind, type AgentCandidateArtifactPort, type AgentCandidateBenchmarkGraderPort, type AgentCandidateContainerPort, type AgentCandidateExecutionAttemptRecord, type AgentCandidateExecutionAttemptRef, type AgentCandidateExecutionClaim, type AgentCandidateExecutionClaimResult, type AgentCandidateExecutionClaimStore, type AgentCandidateExecutionCleanupHandles, type AgentCandidateExecutionFailureClass, type AgentCandidateExecutionFinishResult, type AgentCandidateExecutionLease, type AgentCandidateExecutionPhase, type AgentCandidateExecutionPhaseResult, type AgentCandidateExecutionPorts, type AgentCandidateExecutionRecoveryEvidence, type AgentCandidateExecutionStageResult, type AgentCandidateExecutionTerminalRecord, type AgentCandidateExecutionTerminalResult, type AgentCandidateExecutionUsage, type AgentCandidateExecutorFinalCapture, type AgentCandidateExecutorMemoryCapture, type AgentCandidateExecutorPort, type AgentCandidateExecutorProfileFile, type AgentCandidateExecutorRequest, type AgentCandidateExecutorStopRequest, type AgentCandidateExecutorTaskOutcomeCapture, type AgentCandidateExecutorWorkspaceFile, type AgentCandidateExecutorWorkspaceInput, type AgentCandidateMemoryPort, type AgentCandidateMemoryResetResult, type AgentCandidateModelGrantActivateInput, type AgentCandidateModelGrantClient, type AgentCandidateModelGrantReservation, type AgentCandidateModelGrantReserveInput, type AgentCandidateModelGrantSettleInput, type AgentCandidateModelLimits, type AgentCandidateModelPort, type AgentCandidateOutputArtifactPort, type AgentCandidateOutputPurpose, type AgentCandidateProtectedModelActivation, type AgentCandidateProtectedModelCall, type AgentCandidateProtectedModelReservation, type AgentCandidateProtectedModelSettlement, type AgentCandidateProtectedRunCapture, type AgentCandidateRepositoryPort, type AgentCandidateRetryRejection, type AgentCandidateRunFinalization, type AgentCandidateTaskExecution, type AgentCandidateVerificationPorts, type AgentCandidateWorkspacePort, AgentExecutionBackend, AgentRuntimeEvent, AgentTaskRunResult, AgentTaskStatus, type AuthSource, type BackendCallPolicy, BackendTransportError, CANDIDATE_TRACE_ENV, CANDIDATE_TRACE_TAGS, CandidateGenerator, type CanonicalCandidateDocument, type ChatStreamEvent, type ChatTurnHooks, type ChatTurnIdentity, type ChatTurnProducer, type ChatTurnResult, type CircuitBreakerConfig, CircuitBreakerState, CircuitOpenError, type Conversation, type ConversationDriveState, type ConversationJournal, type ConversationJournalEntry, type ConversationParticipant, type ConversationPolicy, type ConversationResult, type ConversationStreamEvent, type ConversationTurn, type CreateProtectedAgentCandidateModelPortOptions, type D1DatabaseLike, type D1StmtLike, DEFAULT_MAX_DEPTH, DEFAULT_ROUTER_BASE_URL, DeadlineExceededError, type DisposePreparedAgentCandidateOptions, type ExecutePreparedAgentCandidateOptions, FORWARD_HEADERS, FileAgentCandidateExecutionClaimStore, type FileAgentCandidateExecutionClaimStoreOptions, FileConversationJournal, type ForwardHeaderName, type HaltContext, type HaltPredicate, type HaltReason, type HaltSignal, type ImproveOptions, type ImproveResult, type ImproveSurface, InMemoryAgentCandidateExecutionClaimStore, InMemoryConversationJournal, InMemoryRuntimeSessionStore, type ModelInfo, OpenAIChatResponseFormat, OpenAIChatTool, OpenAIChatToolChoice, type PersonaConversationResult, type PersonaDriver, PlannerError, type PrepareAgentCandidateExecutionOptions, type PreparedAgentCandidateExecution, type PreparedAgentCandidateInstruction, type PreparedAgentCandidateLaunch, type PreparedAgentCandidateTrace, type PropagatedHeaders, ROLLOUT_POLICY_BOUNDS, ROLLOUT_POLICY_EXTENSION, type RawTraceDistillerOptions, type RecoverExpiredAgentCandidateOptions, type ReflectiveGeneratorOptions, type ResolveAgentBackendOptions, type ResolvedAgentCandidateContainer, type ResolvedChatModel, type RetryBackoff, type RetryableErrorPredicate, type RouterEnv, type RunChatTurnInput, type RunConversationOptions, type RunPersonaConfig, type RunPersonaConversationOptions, type RunToolLoopOptions, type RuntimeEventCollector, RuntimeHooks, RuntimeRunStateError, RuntimeSessionStore, RuntimeStreamEvent, type RuntimeStreamEventCollector, type RuntimeTelemetryOptions, type SanitizedKnowledgeReadinessReport, type SqlAdapter, SqlConversationJournal, type StreamToolLoopOptions, type StreamToolLoopYield, type ToolCallOutcome, type ToolLoopAssistantToolCall, type ToolLoopCall, type ToolLoopEvent, type ToolLoopMessage, type ToolLoopResult, type ToolLoopStopReason, type TurnOrder, type VerifiedAgentCandidate, type VerifiedAgentCandidateTaskOutcome, Verifier, applyRolloutPolicyToProfile, applyRunRecordDefaults, buildForwardHeaders, candidateExecutionClaim, cleanModelId, computeBackoff, createConversationBackend, createIterableBackend, createOpenAICompatibleBackend, createProtectedAgentCandidateModelPort, createRuntimeEventCollector, createRuntimeStreamEventCollector, createSandboxPromptBackend, d1ToSqlAdapter, decideKnowledgeReadiness, defaultIsRetryable, defineConversation, deriveExecutionId, disposePreparedAgentCandidateExecution, enumerateNeighborPolicies, executePreparedAgentCandidate, getModels, handleChatTurn, improve, isDepthExceeded, makePerAttemptSignal, mcpBuildPrompt, normalizeRolloutPolicy, parseRolloutPolicy, persistCandidateOutputArtifact, prepareAgentCandidateExecution, rawTraceDistiller, readDepth, readinessServerSentEvent, recoverExpiredAgentCandidateExecution, reflectiveGenerator, resolveAgentBackend, resolveChatModel, resolveRouterBaseUrl, rolloutPolicyProposer, runAgentTask, runAgentTaskStream, runConversation, runConversationStream, runPersonaConversation, runPersonaDispatch, runToolLoop, runtimeStreamServerSentEvent, sanitizeAgentRuntimeEvent, sanitizeKnowledgeReadinessReport, sanitizeRuntimeStreamEvent, serializeRolloutPolicy, sleep, slugifySpeaker, streamToolLoop, structuralRolloutPolicyFromProfile, toolBuildPrompt, turnId, validateChatModelId, verifyAgentCandidateBundle };
1780
+ export { AgentBackendContext, AgentBackendInput, type AgentBackendKind, AgentExecutionBackend, AgentTaskRunResult, type AuthSource, type BackendCallPolicy, BackendTransportError, CandidateGenerator, type ChatStreamEvent, type ChatTurnHooks, type ChatTurnIdentity, type ChatTurnProducer, type ChatTurnResult, type CircuitBreakerConfig, CircuitBreakerState, CircuitOpenError, type Conversation, type ConversationDriveState, type ConversationJournal, type ConversationJournalEntry, type ConversationParticipant, type ConversationPolicy, type ConversationResult, type ConversationStreamEvent, type ConversationTurn, type D1DatabaseLike, type D1StmtLike, DEFAULT_MAX_DEPTH, DEFAULT_ROUTER_BASE_URL, DeadlineExceededError, FORWARD_HEADERS, FileConversationJournal, type ForwardHeaderName, type HaltContext, type HaltPredicate, type HaltReason, type HaltSignal, InMemoryConversationJournal, InMemoryRuntimeSessionStore, type ModelInfo, OpenAIChatResponseFormat, OpenAIChatTool, OpenAIChatToolChoice, type PersonaConversationResult, type PersonaDriver, PlannerError, type PropagatedHeaders, ROLLOUT_POLICY_BOUNDS, ROLLOUT_POLICY_EXTENSION, type RawTraceDistillerOptions, type ReflectiveGeneratorOptions, type ResolveAgentBackendOptions, type ResolvedChatModel, type RetryBackoff, type RetryableErrorPredicate, type RouterEnv, type RunChatTurnInput, type RunConversationOptions, type RunPersonaConfig, type RunPersonaConversationOptions, type RunToolLoopOptions, RuntimeHooks, RuntimeRunStateError, RuntimeSessionStore, RuntimeStreamEvent, RuntimeTelemetryOptions, type SqlAdapter, SqlConversationJournal, type StreamToolLoopOptions, type StreamToolLoopYield, type ToolCallOutcome, type ToolLoopAssistantToolCall, type ToolLoopCall, type ToolLoopEvent, type ToolLoopMessage, type ToolLoopResult, type ToolLoopStopReason, type TurnOrder, applyRolloutPolicyToProfile, applyRunRecordDefaults, buildForwardHeaders, cleanModelId, computeBackoff, createConversationBackend, createIterableBackend, createOpenAICompatibleBackend, createSandboxPromptBackend, d1ToSqlAdapter, decideKnowledgeReadiness, defaultIsRetryable, defineConversation, deriveExecutionId, enumerateNeighborPolicies, getModels, handleChatTurn, isDepthExceeded, makePerAttemptSignal, mcpBuildPrompt, normalizeRolloutPolicy, parseRolloutPolicy, rawTraceDistiller, readDepth, readinessServerSentEvent, reflectiveGenerator, resolveAgentBackend, resolveChatModel, resolveRouterBaseUrl, rolloutPolicyProposer, runAgentTask, runAgentTaskStream, runConversation, runConversationStream, runPersonaConversation, runPersonaDispatch, runToolLoop, runtimeStreamServerSentEvent, serializeRolloutPolicy, sleep, slugifySpeaker, streamToolLoop, structuralRolloutPolicyFromProfile, toolBuildPrompt, turnId, validateChatModelId };