diff --git a/docs/api/candidate-execution.md b/docs/api/candidate-execution.md index 80323719..deaf0c9f 100644 --- a/docs/api/candidate-execution.md +++ b/docs/api/candidate-execution.md @@ -500,6 +500,12 @@ Re-exports [PreparedAgentCandidateInstruction](index.md#preparedagentcandidatein *** +### PreparedAgentCandidateKnowledge + +Re-exports [PreparedAgentCandidateKnowledge](index.md#preparedagentcandidateknowledge) + +*** + ### PreparedAgentCandidateLaunch Re-exports [PreparedAgentCandidateLaunch](index.md#preparedagentcandidatelaunch) diff --git a/docs/api/index.md b/docs/api/index.md index 2b9eeee3..1b1713b5 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -1916,7 +1916,7 @@ Maximum time for task verification, executable grading, and receipt construction ### PrepareAgentCandidateExecutionOptions -Defined in: [candidate-execution/prepare.ts:91](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/prepare.ts#L91) +Defined in: [candidate-execution/prepare.ts:92](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/prepare.ts#L92) #### Properties @@ -1924,13 +1924,13 @@ Defined in: [candidate-execution/prepare.ts:91](https://github.com/tangle-networ > `optional` **cleanupTimeoutMs?**: `number` -Defined in: [candidate-execution/prepare.ts:92](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/prepare.ts#L92) +Defined in: [candidate-execution/prepare.ts:93](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/prepare.ts#L93) ##### resultTimeoutMs? > `optional` **resultTimeoutMs?**: `number` -Defined in: [candidate-execution/prepare.ts:94](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/prepare.ts#L94) +Defined in: [candidate-execution/prepare.ts:95](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/prepare.ts#L95) Maximum time for task verification, executable grading, and receipt construction. @@ -2183,7 +2183,7 @@ Evaluator clock; must be the same clock used by the claim store. ### AgentCandidateArtifactPort -Defined in: [candidate-execution/types.ts:34](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L34) +Defined in: [candidate-execution/types.ts:35](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L35) Reads one content-addressed object from the closed S3/IPFS locator set. @@ -2197,7 +2197,7 @@ Reads one content-addressed object from the closed S3/IPFS locator set. > **read**(`ref`): `Promise`\<`Uint8Array`\<`ArrayBufferLike`\>\> -Defined in: [candidate-execution/types.ts:35](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L35) +Defined in: [candidate-execution/types.ts:36](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L36) ###### Parameters @@ -2213,7 +2213,7 @@ Defined in: [candidate-execution/types.ts:35](https://github.com/tangle-network/ ### AgentCandidateOutputArtifactPort -Defined in: [candidate-execution/types.ts:55](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L55) +Defined in: [candidate-execution/types.ts:57](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L57) Durable content-addressed evidence store controlled only by the evaluator. @@ -2227,7 +2227,7 @@ Durable content-addressed evidence store controlled only by the evaluator. > **read**(`ref`): `Promise`\<`Uint8Array`\<`ArrayBufferLike`\>\> -Defined in: [candidate-execution/types.ts:35](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L35) +Defined in: [candidate-execution/types.ts:36](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L36) ###### Parameters @@ -2247,7 +2247,7 @@ Defined in: [candidate-execution/types.ts:35](https://github.com/tangle-network/ > **put**(`input`): `Promise`\<`AgentCandidateArtifactRef`\> -Defined in: [candidate-execution/types.ts:57](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L57) +Defined in: [candidate-execution/types.ts:59](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L59) Must be idempotent for identical bytes and return only a durable S3/IPFS locator. @@ -2281,7 +2281,7 @@ Abort must prevent durable publication when it happens before resolution. ### AgentCandidateRepositoryPort -Defined in: [candidate-execution/types.ts:67](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L67) +Defined in: [candidate-execution/types.ts:69](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L69) Resolves a declared GitHub repository to an already-present local Git object store. @@ -2291,7 +2291,7 @@ Resolves a declared GitHub repository to an already-present local Git object sto > **resolve**(`repository`): `Promise`\<`string`\> -Defined in: [candidate-execution/types.ts:68](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L68) +Defined in: [candidate-execution/types.ts:70](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L70) ###### Parameters @@ -2307,7 +2307,7 @@ Defined in: [candidate-execution/types.ts:68](https://github.com/tangle-network/ ### AgentCandidateVerificationPorts -Defined in: [candidate-execution/types.ts:71](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L71) +Defined in: [candidate-execution/types.ts:73](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L73) #### Extended by @@ -2319,19 +2319,19 @@ Defined in: [candidate-execution/types.ts:71](https://github.com/tangle-network/ > **artifacts**: [`AgentCandidateArtifactPort`](#agentcandidateartifactport) -Defined in: [candidate-execution/types.ts:72](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L72) +Defined in: [candidate-execution/types.ts:74](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L74) ##### repositories > **repositories**: [`AgentCandidateRepositoryPort`](#agentcandidaterepositoryport) -Defined in: [candidate-execution/types.ts:73](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L73) +Defined in: [candidate-execution/types.ts:75](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L75) *** ### AgentCandidateWorkspacePort -Defined in: [candidate-execution/types.ts:83](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L83) +Defined in: [candidate-execution/types.ts:85](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L85) Materializes an already-verified workspace archive. @@ -2345,7 +2345,7 @@ any archive encoding, or no-op when the exact workspace is already present. > **materialize**(`input`): `Promise`\<`void`\> -Defined in: [candidate-execution/types.ts:84](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L84) +Defined in: [candidate-execution/types.ts:86](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L86) ###### Parameters @@ -2353,7 +2353,7 @@ Defined in: [candidate-execution/types.ts:84](https://github.com/tangle-network/ ###### role -`"task"` \| `"memory"` \| `"candidate"` +`"task"` \| `"knowledge"` \| `"memory"` \| `"candidate"` ###### snapshot @@ -2375,7 +2375,7 @@ Defined in: [candidate-execution/types.ts:84](https://github.com/tangle-network/ ### ResolvedAgentCandidateContainer -Defined in: [candidate-execution/types.ts:92](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L92) +Defined in: [candidate-execution/types.ts:94](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L94) #### Properties @@ -2383,37 +2383,37 @@ Defined in: [candidate-execution/types.ts:92](https://github.com/tangle-network/ > **source**: `"pinned-container"` \| `"evaluator-task-container"` -Defined in: [candidate-execution/types.ts:93](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L93) +Defined in: [candidate-execution/types.ts:95](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L95) ##### image > **image**: `string` -Defined in: [candidate-execution/types.ts:94](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L94) +Defined in: [candidate-execution/types.ts:96](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L96) ##### indexDigest > **indexDigest**: `` `sha256:${string}` `` -Defined in: [candidate-execution/types.ts:95](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L95) +Defined in: [candidate-execution/types.ts:97](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L97) ##### manifestDigest > **manifestDigest**: `` `sha256:${string}` `` -Defined in: [candidate-execution/types.ts:96](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L96) +Defined in: [candidate-execution/types.ts:98](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L98) ##### platform > **platform**: `AgentCandidateOciPlatform` -Defined in: [candidate-execution/types.ts:97](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L97) +Defined in: [candidate-execution/types.ts:99](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L99) *** ### AgentCandidateContainerPort -Defined in: [candidate-execution/types.ts:100](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L100) +Defined in: [candidate-execution/types.ts:102](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L102) #### Methods @@ -2421,7 +2421,7 @@ Defined in: [candidate-execution/types.ts:100](https://github.com/tangle-network > **resolve**(`input`): `Promise`\<[`ResolvedAgentCandidateContainer`](#resolvedagentcandidatecontainer)\> -Defined in: [candidate-execution/types.ts:101](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L101) +Defined in: [candidate-execution/types.ts:103](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L103) ###### Parameters @@ -2443,7 +2443,7 @@ Defined in: [candidate-execution/types.ts:101](https://github.com/tangle-network ### AgentCandidateModelPort -Defined in: [candidate-execution/types.ts:107](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L107) +Defined in: [candidate-execution/types.ts:109](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L109) #### Methods @@ -2451,7 +2451,7 @@ Defined in: [candidate-execution/types.ts:107](https://github.com/tangle-network > **resolve**(`input`): `Promise`\<`AgentCandidateResolvedModel`\> -Defined in: [candidate-execution/types.ts:108](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L108) +Defined in: [candidate-execution/types.ts:110](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L110) ###### Parameters @@ -2477,7 +2477,7 @@ Defined in: [candidate-execution/types.ts:108](https://github.com/tangle-network > **reserveGrant**(`input`): `Promise`\<[`AgentCandidateProtectedModelReservation`](#agentcandidateprotectedmodelreservation)\> -Defined in: [candidate-execution/types.ts:118](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L118) +Defined in: [candidate-execution/types.ts:120](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L120) Reserve a stable access identity without creating a live credential. The reservation is scoped to `preparationId` and must automatically expire @@ -2523,7 +2523,7 @@ at `expiresAtMs`, even if this call returns ambiguously to the runtime. > **activateGrant**(`input`): `Promise`\<[`AgentCandidateProtectedModelActivation`](#agentcandidateprotectedmodelactivation)\> -Defined in: [candidate-execution/types.ts:128](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L128) +Defined in: [candidate-execution/types.ts:130](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L130) Create the live scoped credential only after the execution attempt is durably claimed. @@ -2559,7 +2559,7 @@ Create the live scoped credential only after the execution attempt is durably cl > **settleGrant**(`input`): `Promise`\<[`AgentCandidateProtectedModelSettlement`](#agentcandidateprotectedmodelsettlement)\> -Defined in: [candidate-execution/types.ts:141](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L141) +Defined in: [candidate-execution/types.ts:143](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L143) Atomically revoke the grant, drain in-flight calls, and return its immutable final ledger. This operation must be idempotent for the exact preparation and must also @@ -2598,7 +2598,7 @@ different preparation, even when both reservations report the same digest. ### AgentCandidateBenchmarkGraderIdentity -Defined in: [candidate-execution/types.ts:156](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L156) +Defined in: [candidate-execution/types.ts:158](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L158) #### Properties @@ -2606,25 +2606,25 @@ Defined in: [candidate-execution/types.ts:156](https://github.com/tangle-network > **name**: `string` -Defined in: [candidate-execution/types.ts:157](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L157) +Defined in: [candidate-execution/types.ts:159](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L159) ##### version > **version**: `string` -Defined in: [candidate-execution/types.ts:158](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L158) +Defined in: [candidate-execution/types.ts:160](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L160) ##### artifact > **artifact**: `AgentCandidateArtifactRef` -Defined in: [candidate-execution/types.ts:159](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L159) +Defined in: [candidate-execution/types.ts:161](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L161) *** ### AgentCandidateProtectedModelReservation -Defined in: [candidate-execution/types.ts:162](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L162) +Defined in: [candidate-execution/types.ts:164](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L164) #### Properties @@ -2632,19 +2632,19 @@ Defined in: [candidate-execution/types.ts:162](https://github.com/tangle-network > **preparationId**: `string` -Defined in: [candidate-execution/types.ts:163](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L163) +Defined in: [candidate-execution/types.ts:165](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L165) ##### digest > **digest**: `` `sha256:${string}` `` -Defined in: [candidate-execution/types.ts:164](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L164) +Defined in: [candidate-execution/types.ts:166](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L166) ##### expiresAtMs > **expiresAtMs**: `number` -Defined in: [candidate-execution/types.ts:166](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L166) +Defined in: [candidate-execution/types.ts:168](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L168) Evaluator service must expire and revoke this reservation at this epoch millisecond. @@ -2652,7 +2652,7 @@ Evaluator service must expire and revoke this reservation at this epoch millisec > **enforcedLimits**: [`AgentCandidateModelLimits`](#agentcandidatemodellimits) -Defined in: [candidate-execution/types.ts:168](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L168) +Defined in: [candidate-execution/types.ts:170](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L170) The gateway must stop calls before any one of these limits is exceeded. @@ -2660,7 +2660,7 @@ The gateway must stop calls before any one of these limits is exceeded. > **network**: `AgentCandidateModelAccessNetwork` -Defined in: [candidate-execution/types.ts:170](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L170) +Defined in: [candidate-execution/types.ts:172](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L172) Exact public endpoint exception; every other candidate destination stays blocked. @@ -2668,7 +2668,7 @@ Exact public endpoint exception; every other candidate destination stays blocked ### AgentCandidateProtectedModelActivation -Defined in: [candidate-execution/types.ts:173](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L173) +Defined in: [candidate-execution/types.ts:175](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L175) #### Properties @@ -2676,7 +2676,7 @@ Defined in: [candidate-execution/types.ts:173](https://github.com/tangle-network > **env**: `Readonly`\<`Record`\<`string`, `string`\>\> -Defined in: [candidate-execution/types.ts:175](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L175) +Defined in: [candidate-execution/types.ts:177](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L177) Injected only into the trusted executor after all pre-launch checks pass. @@ -2684,7 +2684,7 @@ Injected only into the trusted executor after all pre-launch checks pass. ### AgentCandidateProtectedModelCall -Defined in: [candidate-execution/types.ts:179](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L179) +Defined in: [candidate-execution/types.ts:181](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L181) One evaluator-gateway call in the final, revoked model-access ledger. @@ -2694,13 +2694,13 @@ One evaluator-gateway call in the final, revoked model-access ledger. > **callId**: `string` -Defined in: [candidate-execution/types.ts:180](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L180) +Defined in: [candidate-execution/types.ts:182](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L182) ##### generationId > **generationId**: `string` -Defined in: [candidate-execution/types.ts:182](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L182) +Defined in: [candidate-execution/types.ts:184](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L184) Router-generated public response identity. @@ -2708,7 +2708,7 @@ Router-generated public response identity. > **traceSpanId**: `string` -Defined in: [candidate-execution/types.ts:184](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L184) +Defined in: [candidate-execution/types.ts:186](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L186) Exact protected agent-eval LLM span produced from the router ledger. @@ -2716,55 +2716,55 @@ Exact protected agent-eval LLM span produced from the router ledger. > **status**: `"failed"` \| `"succeeded"` -Defined in: [candidate-execution/types.ts:185](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L185) +Defined in: [candidate-execution/types.ts:187](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L187) ##### model > **model**: `string` -Defined in: [candidate-execution/types.ts:186](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L186) +Defined in: [candidate-execution/types.ts:188](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L188) ##### startedAtMs > **startedAtMs**: `number` -Defined in: [candidate-execution/types.ts:187](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L187) +Defined in: [candidate-execution/types.ts:189](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L189) ##### endedAtMs > **endedAtMs**: `number` -Defined in: [candidate-execution/types.ts:188](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L188) +Defined in: [candidate-execution/types.ts:190](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L190) ##### inputTokens > **inputTokens**: `number` -Defined in: [candidate-execution/types.ts:189](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L189) +Defined in: [candidate-execution/types.ts:191](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L191) ##### outputTokens > **outputTokens**: `number` -Defined in: [candidate-execution/types.ts:190](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L190) +Defined in: [candidate-execution/types.ts:192](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L192) ##### cachedInputTokens > **cachedInputTokens**: `number` -Defined in: [candidate-execution/types.ts:191](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L191) +Defined in: [candidate-execution/types.ts:193](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L193) ##### reasoningTokens > **reasoningTokens**: `number` -Defined in: [candidate-execution/types.ts:192](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L192) +Defined in: [candidate-execution/types.ts:194](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L194) ##### costUsdNanos > **costUsdNanos**: `number` -Defined in: [candidate-execution/types.ts:194](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L194) +Defined in: [candidate-execution/types.ts:196](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L196) Integer billionths of one US dollar; avoids floating-point ledger drift. @@ -2772,7 +2772,7 @@ Integer billionths of one US dollar; avoids floating-point ledger drift. ### AgentCandidateProtectedModelSettlement -Defined in: [candidate-execution/types.ts:197](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L197) +Defined in: [candidate-execution/types.ts:199](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L199) #### Properties @@ -2780,31 +2780,31 @@ Defined in: [candidate-execution/types.ts:197](https://github.com/tangle-network > **preparationId**: `string` -Defined in: [candidate-execution/types.ts:198](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L198) +Defined in: [candidate-execution/types.ts:200](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L200) ##### grantDigest > **grantDigest**: `` `sha256:${string}` `` -Defined in: [candidate-execution/types.ts:199](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L199) +Defined in: [candidate-execution/types.ts:201](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L201) ##### closed > **closed**: `true` -Defined in: [candidate-execution/types.ts:200](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L200) +Defined in: [candidate-execution/types.ts:202](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L202) ##### calls > **calls**: readonly [`AgentCandidateProtectedModelCall`](#agentcandidateprotectedmodelcall)[] -Defined in: [candidate-execution/types.ts:201](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L201) +Defined in: [candidate-execution/types.ts:203](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L203) *** ### AgentCandidateMemoryResetResult -Defined in: [candidate-execution/types.ts:204](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L204) +Defined in: [candidate-execution/types.ts:206](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L206) #### Properties @@ -2812,43 +2812,43 @@ Defined in: [candidate-execution/types.ts:204](https://github.com/tangle-network > **preparationId**: `string` -Defined in: [candidate-execution/types.ts:205](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L205) +Defined in: [candidate-execution/types.ts:207](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L207) ##### accessDigest > **accessDigest**: `` `sha256:${string}` `` -Defined in: [candidate-execution/types.ts:206](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L206) +Defined in: [candidate-execution/types.ts:208](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L208) ##### expiresAtMs > **expiresAtMs**: `number` -Defined in: [candidate-execution/types.ts:207](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L207) +Defined in: [candidate-execution/types.ts:209](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L209) ##### evidence > **evidence**: `AgentCandidateCapturedArtifact` -Defined in: [candidate-execution/types.ts:208](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L208) +Defined in: [candidate-execution/types.ts:210](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L210) ##### emptyStateDigest > **emptyStateDigest**: `` `sha256:${string}` `` -Defined in: [candidate-execution/types.ts:209](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L209) +Defined in: [candidate-execution/types.ts:211](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L211) ##### beforeState > **beforeState**: `AgentCandidateWorkspaceSnapshotEvidence` -Defined in: [candidate-execution/types.ts:210](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L210) +Defined in: [candidate-execution/types.ts:212](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L212) *** ### AgentCandidateMemoryPort -Defined in: [candidate-execution/types.ts:213](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L213) +Defined in: [candidate-execution/types.ts:215](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L215) #### Methods @@ -2856,7 +2856,7 @@ Defined in: [candidate-execution/types.ts:213](https://github.com/tangle-network > **reset**(`input`): `Promise`\<[`AgentCandidateMemoryResetResult`](#agentcandidatememoryresetresult)\> -Defined in: [candidate-execution/types.ts:219](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L219) +Defined in: [candidate-execution/types.ts:221](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L221) Reset and reserve exact task memory without returning live access. The service must scope the reservation to `preparationId`, automatically @@ -2898,7 +2898,7 @@ revoke it at `expiresAtMs`, and never reuse it for another preparation. > **activate**(`input`): `Promise`\<\{ `env`: `Readonly`\<`Record`\<`string`, `string`\>\>; \}\> -Defined in: [candidate-execution/types.ts:231](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L231) +Defined in: [candidate-execution/types.ts:233](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L233) Create live scoped access only after the execution attempt is durably claimed. Activation must match the exact preparation/access pair and may not extend expiry. @@ -2935,7 +2935,7 @@ Activation must match the exact preparation/access pair and may not extend expir > **close**(`input`): `Promise`\<\{ `closed`: `true`; \}\> -Defined in: [candidate-execution/types.ts:243](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L243) +Defined in: [candidate-execution/types.ts:245](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L245) Revoke evaluator-owned access after process death or a failed preparation. Must be idempotent and concurrency-safe for the exact preparation/access @@ -2973,7 +2973,7 @@ pair and must never close a different preparation. ### AgentCandidateExecutionPorts -Defined in: [candidate-execution/types.ts:252](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L252) +Defined in: [candidate-execution/types.ts:254](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L254) #### Extends @@ -2985,7 +2985,7 @@ Defined in: [candidate-execution/types.ts:252](https://github.com/tangle-network > **artifacts**: [`AgentCandidateArtifactPort`](#agentcandidateartifactport) -Defined in: [candidate-execution/types.ts:72](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L72) +Defined in: [candidate-execution/types.ts:74](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L74) ###### Inherited from @@ -2995,7 +2995,7 @@ Defined in: [candidate-execution/types.ts:72](https://github.com/tangle-network/ > **repositories**: [`AgentCandidateRepositoryPort`](#agentcandidaterepositoryport) -Defined in: [candidate-execution/types.ts:73](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L73) +Defined in: [candidate-execution/types.ts:75](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L75) ###### Inherited from @@ -3005,31 +3005,31 @@ Defined in: [candidate-execution/types.ts:73](https://github.com/tangle-network/ > **workspaces**: [`AgentCandidateWorkspacePort`](#agentcandidateworkspaceport) -Defined in: [candidate-execution/types.ts:253](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L253) +Defined in: [candidate-execution/types.ts:255](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L255) ##### containers > **containers**: [`AgentCandidateContainerPort`](#agentcandidatecontainerport) -Defined in: [candidate-execution/types.ts:254](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L254) +Defined in: [candidate-execution/types.ts:256](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L256) ##### models > **models**: [`AgentCandidateModelPort`](#agentcandidatemodelport) -Defined in: [candidate-execution/types.ts:255](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L255) +Defined in: [candidate-execution/types.ts:257](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L257) ##### memory > **memory**: [`AgentCandidateMemoryPort`](#agentcandidatememoryport) -Defined in: [candidate-execution/types.ts:256](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L256) +Defined in: [candidate-execution/types.ts:258](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L258) *** ### AgentCandidateTaskExecution -Defined in: [candidate-execution/types.ts:259](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L259) +Defined in: [candidate-execution/types.ts:261](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L261) #### Properties @@ -3037,37 +3037,37 @@ Defined in: [candidate-execution/types.ts:259](https://github.com/tangle-network > **executionId**: `string` -Defined in: [candidate-execution/types.ts:260](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L260) +Defined in: [candidate-execution/types.ts:262](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L262) ##### benchmark > **benchmark**: `string` -Defined in: [candidate-execution/types.ts:261](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L261) +Defined in: [candidate-execution/types.ts:263](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L263) ##### benchmarkVersion > **benchmarkVersion**: `string` -Defined in: [candidate-execution/types.ts:262](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L262) +Defined in: [candidate-execution/types.ts:264](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L264) ##### taskId > **taskId**: `string` -Defined in: [candidate-execution/types.ts:263](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L263) +Defined in: [candidate-execution/types.ts:265](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L265) ##### splitDigest > **splitDigest**: `` `sha256:${string}` `` -Defined in: [candidate-execution/types.ts:264](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L264) +Defined in: [candidate-execution/types.ts:266](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L266) ##### instruction > **instruction**: `string` -Defined in: [candidate-execution/types.ts:266](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L266) +Defined in: [candidate-execution/types.ts:268](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L268) Exact agent-visible task instruction. The runtime rejects malformed Unicode. @@ -3075,7 +3075,7 @@ Exact agent-visible task instruction. The runtime rejects malformed Unicode. > **repository**: `object` -Defined in: [candidate-execution/types.ts:267](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L267) +Defined in: [candidate-execution/types.ts:269](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L269) ###### identity @@ -3097,13 +3097,13 @@ Defined in: [candidate-execution/types.ts:267](https://github.com/tangle-network > **attempt**: `AgentCandidateAttemptPolicy` -Defined in: [candidate-execution/types.ts:273](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L273) +Defined in: [candidate-execution/types.ts:275](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L275) ##### model > **model**: `object` -Defined in: [candidate-execution/types.ts:274](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L274) +Defined in: [candidate-execution/types.ts:276](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L276) ###### requested @@ -3117,13 +3117,13 @@ Defined in: [candidate-execution/types.ts:274](https://github.com/tangle-network > **grader**: [`AgentCandidateBenchmarkGraderIdentity`](#agentcandidatebenchmarkgraderidentity) -Defined in: [candidate-execution/types.ts:278](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L278) +Defined in: [candidate-execution/types.ts:280](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L280) ##### executionRoots > **executionRoots**: `object` -Defined in: [candidate-execution/types.ts:280](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L280) +Defined in: [candidate-execution/types.ts:282](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L282) Absolute paths inside the evaluator-owned execution environment. @@ -3139,7 +3139,7 @@ Absolute paths inside the evaluator-owned execution environment. > **stagingRoots**: `object` -Defined in: [candidate-execution/types.ts:285](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L285) +Defined in: [candidate-execution/types.ts:287](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L287) Host-side staging roots. These are verified but never signed as container paths. @@ -3159,51 +3159,51 @@ Host-side staging roots. These are verified but never signed as container paths. > **workspace**: `AgentCandidateWorkspaceSnapshotEvidence` -Defined in: [candidate-execution/types.ts:290](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L290) +Defined in: [candidate-execution/types.ts:292](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L292) ##### evaluatorTaskContainer? > `optional` **evaluatorTaskContainer?**: [`ResolvedAgentCandidateContainer`](#resolvedagentcandidatecontainer) -Defined in: [candidate-execution/types.ts:291](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L291) +Defined in: [candidate-execution/types.ts:293](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L293) ##### limits > **limits**: `AgentCandidateExecutionLimits` -Defined in: [candidate-execution/types.ts:292](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L292) +Defined in: [candidate-execution/types.ts:294](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L294) *** ### VerifiedAgentCandidate -Defined in: [candidate-execution/types.ts:295](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L295) +Defined in: [candidate-execution/types.ts:297](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L297) #### Properties ##### bundle -> `readonly` **bundle**: `AgentCandidateBundleV1` +> `readonly` **bundle**: `AgentCandidateBundle` -Defined in: [candidate-execution/types.ts:296](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L296) +Defined in: [candidate-execution/types.ts:298](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L298) ##### materializedTree? > `readonly` `optional` **materializedTree?**: `string` -Defined in: [candidate-execution/types.ts:297](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L297) +Defined in: [candidate-execution/types.ts:299](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L299) ##### \[verifiedCandidateBrand\] > `readonly` **\[verifiedCandidateBrand\]**: `true` -Defined in: [candidate-execution/types.ts:298](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L298) +Defined in: [candidate-execution/types.ts:300](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L300) *** ### CanonicalCandidateDocument -Defined in: [candidate-execution/types.ts:301](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L301) +Defined in: [candidate-execution/types.ts:303](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L303) #### Type Parameters @@ -3217,13 +3217,13 @@ Defined in: [candidate-execution/types.ts:301](https://github.com/tangle-network > `readonly` **value**: `T` -Defined in: [candidate-execution/types.ts:302](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L302) +Defined in: [candidate-execution/types.ts:304](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L304) ##### bytes > `readonly` **bytes**: `Uint8Array` -Defined in: [candidate-execution/types.ts:304](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L304) +Defined in: [candidate-execution/types.ts:306](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L306) Canonical UTF-8 bytes of `value` with its top-level digest omitted. @@ -3231,13 +3231,13 @@ Canonical UTF-8 bytes of `value` with its top-level digest omitted. > `readonly` **digest**: `` `sha256:${string}` `` -Defined in: [candidate-execution/types.ts:305](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L305) +Defined in: [candidate-execution/types.ts:307](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L307) *** ### PreparedAgentCandidateLaunch -Defined in: [candidate-execution/types.ts:308](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L308) +Defined in: [candidate-execution/types.ts:310](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L310) #### Properties @@ -3245,13 +3245,13 @@ Defined in: [candidate-execution/types.ts:308](https://github.com/tangle-network > **executable**: `string` -Defined in: [candidate-execution/types.ts:309](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L309) +Defined in: [candidate-execution/types.ts:311](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L311) ##### args > **args**: readonly `string`[] -Defined in: [candidate-execution/types.ts:311](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L311) +Defined in: [candidate-execution/types.ts:313](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L313) Complete fixed argv, including profile materializer flags but excluding task delivery. @@ -3259,13 +3259,13 @@ Complete fixed argv, including profile materializer flags but excluding task del > **env**: `Readonly`\<`Record`\<`string`, `string`\>\> -Defined in: [candidate-execution/types.ts:312](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L312) +Defined in: [candidate-execution/types.ts:314](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L314) ##### flags > **flags**: readonly `string`[] -Defined in: [candidate-execution/types.ts:314](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L314) +Defined in: [candidate-execution/types.ts:316](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L316) Informational subset already present at the tail of `args`; executors must not append twice. @@ -3273,13 +3273,13 @@ Informational subset already present at the tail of `args`; executors must not a > **cwd**: `string` -Defined in: [candidate-execution/types.ts:315](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L315) +Defined in: [candidate-execution/types.ts:317](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L317) *** ### PreparedAgentCandidateInstruction -Defined in: [candidate-execution/types.ts:318](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L318) +Defined in: [candidate-execution/types.ts:320](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L320) #### Properties @@ -3287,19 +3287,53 @@ Defined in: [candidate-execution/types.ts:318](https://github.com/tangle-network > **bytes**: `Uint8Array` -Defined in: [candidate-execution/types.ts:319](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L319) +Defined in: [candidate-execution/types.ts:321](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L321) ##### delivery > **delivery**: `AgentCandidateInstructionDelivery` -Defined in: [candidate-execution/types.ts:320](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L320) +Defined in: [candidate-execution/types.ts:322](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L322) + +*** + +### PreparedAgentCandidateKnowledge + +Defined in: [candidate-execution/types.ts:326](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L326) + +Exact file-backed knowledge admitted by the candidate bundle. + +#### Properties + +##### candidate + +> `readonly` **candidate**: `AgentCandidateKnowledgeRef` + +Defined in: [candidate-execution/types.ts:327](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L327) + +##### snapshot + +> `readonly` **snapshot**: `AgentCandidateWorkspaceSnapshotEvidence` + +Defined in: [candidate-execution/types.ts:328](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L328) + +##### files + +> `readonly` **files**: readonly [`AgentCandidateExecutorWorkspaceFile`](#agentcandidateexecutorworkspacefile)[] + +Defined in: [candidate-execution/types.ts:329](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L329) + +##### retrievalConfig? + +> `readonly` `optional` **retrievalConfig?**: `Uint8Array`\<`ArrayBufferLike`\> + +Defined in: [candidate-execution/types.ts:330](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L330) *** ### PreparedAgentCandidateTrace -Defined in: [candidate-execution/types.ts:323](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L323) +Defined in: [candidate-execution/types.ts:333](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L333) #### Properties @@ -3307,45 +3341,45 @@ Defined in: [candidate-execution/types.ts:323](https://github.com/tangle-network > **runId**: `string` -Defined in: [candidate-execution/types.ts:324](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L324) +Defined in: [candidate-execution/types.ts:334](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L334) ##### tags > **tags**: `Readonly`\<`Record`\<`string`, `string`\>\> -Defined in: [candidate-execution/types.ts:325](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L325) +Defined in: [candidate-execution/types.ts:335](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L335) ##### env > **env**: `Readonly`\<`Record`\<`string`, `string`\>\> -Defined in: [candidate-execution/types.ts:326](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L326) +Defined in: [candidate-execution/types.ts:336](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L336) *** ### PreparedAgentCandidateExecution -Defined in: [candidate-execution/types.ts:329](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L329) +Defined in: [candidate-execution/types.ts:339](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L339) #### Properties ##### bundle -> `readonly` **bundle**: `AgentCandidateBundleV1` +> `readonly` **bundle**: `AgentCandidateBundle` -Defined in: [candidate-execution/types.ts:330](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L330) +Defined in: [candidate-execution/types.ts:340](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L340) ##### executionId > `readonly` **executionId**: `string` -Defined in: [candidate-execution/types.ts:331](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L331) +Defined in: [candidate-execution/types.ts:341](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L341) ##### roots > `readonly` **roots**: `object` -Defined in: [candidate-execution/types.ts:332](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L332) +Defined in: [candidate-execution/types.ts:342](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L342) ###### execution @@ -3379,7 +3413,7 @@ Defined in: [candidate-execution/types.ts:332](https://github.com/tangle-network > `readonly` **profilePlan**: `object` -Defined in: [candidate-execution/types.ts:343](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L343) +Defined in: [candidate-execution/types.ts:353](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L353) ###### value @@ -3397,7 +3431,7 @@ Defined in: [candidate-execution/types.ts:343](https://github.com/tangle-network > `readonly` **executionPlan**: `object` -Defined in: [candidate-execution/types.ts:348](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L348) +Defined in: [candidate-execution/types.ts:358](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L358) ###### value @@ -3409,69 +3443,57 @@ Defined in: [candidate-execution/types.ts:348](https://github.com/tangle-network ##### materializationReceipt -> `readonly` **materializationReceipt**: [`CanonicalCandidateDocument`](#canonicalcandidatedocument)\<`AgentCandidateMaterializationReceiptV1`\> +> `readonly` **materializationReceipt**: [`CanonicalCandidateDocument`](#canonicalcandidatedocument)\<`AgentCandidateMaterializationReceipt`\> -Defined in: [candidate-execution/types.ts:352](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L352) +Defined in: [candidate-execution/types.ts:362](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L362) ##### launch > `readonly` **launch**: [`PreparedAgentCandidateLaunch`](#preparedagentcandidatelaunch) -Defined in: [candidate-execution/types.ts:353](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L353) +Defined in: [candidate-execution/types.ts:363](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L363) ##### instruction > `readonly` **instruction**: [`PreparedAgentCandidateInstruction`](#preparedagentcandidateinstruction) -Defined in: [candidate-execution/types.ts:354](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L354) +Defined in: [candidate-execution/types.ts:364](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L364) ##### resolvedModel > `readonly` **resolvedModel**: `AgentCandidateResolvedModel` -Defined in: [candidate-execution/types.ts:355](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L355) +Defined in: [candidate-execution/types.ts:365](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L365) ##### knowledge? -> `readonly` `optional` **knowledge?**: `object` - -Defined in: [candidate-execution/types.ts:356](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L356) - -###### snapshotId - -> **snapshotId**: `string` - -###### manifestDigest +> `readonly` `optional` **knowledge?**: [`PreparedAgentCandidateKnowledge`](#preparedagentcandidateknowledge) -> **manifestDigest**: `` `sha256:${string}` `` - -###### manifest - -> **manifest**: `Uint8Array` +Defined in: [candidate-execution/types.ts:366](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L366) ##### trace > `readonly` **trace**: [`PreparedAgentCandidateTrace`](#preparedagentcandidatetrace) -Defined in: [candidate-execution/types.ts:361](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L361) +Defined in: [candidate-execution/types.ts:367](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L367) ##### memory > `readonly` **memory**: `AgentCandidateEffectiveMemory` -Defined in: [candidate-execution/types.ts:362](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L362) +Defined in: [candidate-execution/types.ts:368](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L368) ##### \[preparedCandidateBrand\] > `readonly` **\[preparedCandidateBrand\]**: `true` -Defined in: [candidate-execution/types.ts:363](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L363) +Defined in: [candidate-execution/types.ts:369](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L369) *** ### AgentCandidateProtectedRunCapture -Defined in: [candidate-execution/types.ts:366](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L366) +Defined in: [candidate-execution/types.ts:372](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L372) #### Properties @@ -3479,19 +3501,19 @@ Defined in: [candidate-execution/types.ts:366](https://github.com/tangle-network > **executionId**: `string` -Defined in: [candidate-execution/types.ts:367](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L367) +Defined in: [candidate-execution/types.ts:373](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L373) ##### termination > **termination**: `AgentCandidateTermination` -Defined in: [candidate-execution/types.ts:368](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L368) +Defined in: [candidate-execution/types.ts:374](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L374) *** ### AgentCandidateExecutorTaskOutcomeCapture -Defined in: [candidate-execution/types.ts:372](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L372) +Defined in: [candidate-execution/types.ts:378](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L378) Raw evaluator capture made only after the candidate process is dead. @@ -3501,15 +3523,15 @@ Raw evaluator capture made only after the candidate process is dead. > **resultTree**: `string` -Defined in: [candidate-execution/types.ts:374](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L374) +Defined in: [candidate-execution/types.ts:380](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L380) Claimed final tree. The runtime recomputes it independently from `gitDiff`. ##### afterState -> **afterState**: `AgentCandidateWorkspaceManifestMaterialV1` +> **afterState**: `AgentCandidateWorkspaceManifestMaterial` -Defined in: [candidate-execution/types.ts:376](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L376) +Defined in: [candidate-execution/types.ts:382](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L382) Complete evaluator-captured workspace description after candidate execution. @@ -3517,7 +3539,7 @@ Complete evaluator-captured workspace description after candidate execution. > **archive**: `Uint8Array` -Defined in: [candidate-execution/types.ts:378](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L378) +Defined in: [candidate-execution/types.ts:384](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L384) Reproducible workspace archive corresponding to `afterState`. @@ -3525,7 +3547,7 @@ Reproducible workspace archive corresponding to `afterState`. > **gitDiff**: `Uint8Array` -Defined in: [candidate-execution/types.ts:380](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L380) +Defined in: [candidate-execution/types.ts:386](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L386) Exact binary patch from the signed task base to `afterState`. @@ -3533,7 +3555,7 @@ Exact binary patch from the signed task base to `afterState`. ### AgentCandidateExecutorMemoryCapture -Defined in: [candidate-execution/types.ts:384](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L384) +Defined in: [candidate-execution/types.ts:390](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L390) Raw isolated-memory capture made only after access has been revoked. @@ -3541,21 +3563,21 @@ Raw isolated-memory capture made only after access has been revoked. ##### afterState -> `readonly` **afterState**: `AgentCandidateWorkspaceManifestMaterialV1` +> `readonly` **afterState**: `AgentCandidateWorkspaceManifestMaterial` -Defined in: [candidate-execution/types.ts:385](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L385) +Defined in: [candidate-execution/types.ts:391](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L391) ##### archive > `readonly` **archive**: `Uint8Array` -Defined in: [candidate-execution/types.ts:386](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L386) +Defined in: [candidate-execution/types.ts:392](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L392) *** ### AgentCandidateExecutorFinalCapture -Defined in: [candidate-execution/types.ts:390](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L390) +Defined in: [candidate-execution/types.ts:396](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L396) Idempotent executor result after process death and trace drain. @@ -3565,19 +3587,19 @@ Idempotent executor result after process death and trace drain. > `readonly` **stopped**: `true` -Defined in: [candidate-execution/types.ts:391](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L391) +Defined in: [candidate-execution/types.ts:397](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L397) ##### taskOutcome? > `readonly` `optional` **taskOutcome?**: [`AgentCandidateExecutorTaskOutcomeCapture`](#agentcandidateexecutortaskoutcomecapture) -Defined in: [candidate-execution/types.ts:392](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L392) +Defined in: [candidate-execution/types.ts:398](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L398) ##### memoryAfter? > `readonly` `optional` **memoryAfter?**: [`AgentCandidateExecutorMemoryCapture`](#agentcandidateexecutormemorycapture) -Defined in: [candidate-execution/types.ts:394](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L394) +Defined in: [candidate-execution/types.ts:400](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L400) Required only when the prepared candidate uses isolated task memory. @@ -3585,7 +3607,7 @@ Required only when the prepared candidate uses isolated task memory. ### VerifiedAgentCandidateTaskOutcome -Defined in: [candidate-execution/types.ts:398](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L398) +Defined in: [candidate-execution/types.ts:404](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L404) Branded task outcome that has survived independent patch and tree verification. @@ -3595,7 +3617,7 @@ Branded task outcome that has survived independent patch and tree verification. > `readonly` **evidence**: `AgentCandidateTaskOutcomeEvidence` & `object` -Defined in: [candidate-execution/types.ts:399](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L399) +Defined in: [candidate-execution/types.ts:405](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L405) ###### Type Declaration @@ -3607,19 +3629,19 @@ Defined in: [candidate-execution/types.ts:399](https://github.com/tangle-network > `readonly` **patch**: `Uint8Array` -Defined in: [candidate-execution/types.ts:402](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L402) +Defined in: [candidate-execution/types.ts:408](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L408) ##### \[verifiedTaskOutcomeBrand\] > `readonly` **\[verifiedTaskOutcomeBrand\]**: `true` -Defined in: [candidate-execution/types.ts:403](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L403) +Defined in: [candidate-execution/types.ts:409](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L409) *** ### AgentCandidateBenchmarkGraderPort -Defined in: [candidate-execution/types.ts:415](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L415) +Defined in: [candidate-execution/types.ts:421](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L421) Evaluator-owned executable grader, pinned by immutable implementation bytes. @@ -3635,19 +3657,19 @@ copying an expected digest from ambient configuration. > `readonly` **name**: `string` -Defined in: [candidate-execution/types.ts:416](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L416) +Defined in: [candidate-execution/types.ts:422](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L422) ##### version > `readonly` **version**: `string` -Defined in: [candidate-execution/types.ts:417](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L417) +Defined in: [candidate-execution/types.ts:423](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L423) ##### artifact > `readonly` **artifact**: `AgentCandidateArtifactRef` -Defined in: [candidate-execution/types.ts:418](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L418) +Defined in: [candidate-execution/types.ts:424](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L424) #### Methods @@ -3655,7 +3677,7 @@ Defined in: [candidate-execution/types.ts:418](https://github.com/tangle-network > **run**(`input`): `Promise`\<\{ `evaluation`: `BenchmarkEvaluation`; `evidence`: `Uint8Array`; `binding`: \{ `implementationDigest`: `` `sha256:${string}` ``; `taskOutcomeDigest`: `` `sha256:${string}` ``; `outputDigest`: `` `sha256:${string}` ``; \}; \}\> -Defined in: [candidate-execution/types.ts:419](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L419) +Defined in: [candidate-execution/types.ts:425](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L425) ###### Parameters @@ -3701,7 +3723,7 @@ Frozen result deadline; runners must stop work and side effects when aborted. ### AgentCandidateExecutorRequest -Defined in: [candidate-execution/types.ts:447](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L447) +Defined in: [candidate-execution/types.ts:453](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L453) One detached request passed to the trusted environment-specific executor. @@ -3711,13 +3733,13 @@ One detached request passed to the trusted environment-specific executor. > `readonly` **executionId**: `string` -Defined in: [candidate-execution/types.ts:448](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L448) +Defined in: [candidate-execution/types.ts:454](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L454) ##### inputs > `readonly` **inputs**: `object` -Defined in: [candidate-execution/types.ts:450](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L450) +Defined in: [candidate-execution/types.ts:456](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L456) Immutable bytes from which the executor creates fresh isolated workspaces. @@ -3741,7 +3763,7 @@ Immutable bytes from which the executor creates fresh isolated workspaces. > `readonly` **roots**: `object` -Defined in: [candidate-execution/types.ts:457](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L457) +Defined in: [candidate-execution/types.ts:463](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L463) ###### taskRoot @@ -3755,7 +3777,7 @@ Defined in: [candidate-execution/types.ts:457](https://github.com/tangle-network > `readonly` **profilePlan**: `object` -Defined in: [candidate-execution/types.ts:458](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L458) +Defined in: [candidate-execution/types.ts:464](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L464) ###### value @@ -3773,7 +3795,7 @@ Defined in: [candidate-execution/types.ts:458](https://github.com/tangle-network > `readonly` **executionPlan**: `object` -Defined in: [candidate-execution/types.ts:459](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L459) +Defined in: [candidate-execution/types.ts:465](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L465) ###### value @@ -3785,33 +3807,33 @@ Defined in: [candidate-execution/types.ts:459](https://github.com/tangle-network ##### materializationReceipt -> `readonly` **materializationReceipt**: [`CanonicalCandidateDocument`](#canonicalcandidatedocument)\<`AgentCandidateMaterializationReceiptV1`\> +> `readonly` **materializationReceipt**: [`CanonicalCandidateDocument`](#canonicalcandidatedocument)\<`AgentCandidateMaterializationReceipt`\> -Defined in: [candidate-execution/types.ts:460](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L460) +Defined in: [candidate-execution/types.ts:466](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L466) ##### launch > `readonly` **launch**: [`PreparedAgentCandidateLaunch`](#preparedagentcandidatelaunch) -Defined in: [candidate-execution/types.ts:461](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L461) +Defined in: [candidate-execution/types.ts:467](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L467) ##### instruction > `readonly` **instruction**: [`PreparedAgentCandidateInstruction`](#preparedagentcandidateinstruction) -Defined in: [candidate-execution/types.ts:462](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L462) +Defined in: [candidate-execution/types.ts:468](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L468) ##### resolvedModel > `readonly` **resolvedModel**: `AgentCandidateResolvedModel` -Defined in: [candidate-execution/types.ts:463](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L463) +Defined in: [candidate-execution/types.ts:469](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L469) ##### hardLimits > `readonly` **hardLimits**: `Pick`\<`AgentCandidateExecutionLimits`, `"timeoutMs"`\> -Defined in: [candidate-execution/types.ts:465](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L465) +Defined in: [candidate-execution/types.ts:471](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L471) Mechanically enforced by the runtime plus executor process-death acknowledgement. @@ -3819,45 +3841,33 @@ Mechanically enforced by the runtime plus executor process-death acknowledgement > `readonly` **observedLimits**: `Pick`\<`AgentCandidateExecutionLimits`, `"maxSteps"`\> -Defined in: [candidate-execution/types.ts:467](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L467) +Defined in: [candidate-execution/types.ts:473](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L473) Validity bound checked against protected traces; generic black-box executors cannot preempt it. ##### knowledge? -> `readonly` `optional` **knowledge?**: `object` - -Defined in: [candidate-execution/types.ts:468](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L468) - -###### snapshotId - -> **snapshotId**: `string` +> `readonly` `optional` **knowledge?**: [`PreparedAgentCandidateKnowledge`](#preparedagentcandidateknowledge) -###### manifestDigest - -> **manifestDigest**: `` `sha256:${string}` `` - -###### manifest - -> **manifest**: `Uint8Array` +Defined in: [candidate-execution/types.ts:474](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L474) ##### trace > `readonly` **trace**: [`PreparedAgentCandidateTrace`](#preparedagentcandidatetrace) -Defined in: [candidate-execution/types.ts:469](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L469) +Defined in: [candidate-execution/types.ts:475](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L475) ##### memory > `readonly` **memory**: `AgentCandidateEffectiveMemory` -Defined in: [candidate-execution/types.ts:470](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L470) +Defined in: [candidate-execution/types.ts:476](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L476) *** ### AgentCandidateExecutorPort -Defined in: [candidate-execution/types.ts:481](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L481) +Defined in: [candidate-execution/types.ts:487](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L487) Executes one prepared request inside an evaluator-owned isolation boundary. @@ -3872,7 +3882,7 @@ no candidate-authored usage or score fields. > **execute**(`request`, `context`): `Promise`\<[`AgentCandidateProtectedRunCapture`](#agentcandidateprotectedruncapture)\> -Defined in: [candidate-execution/types.ts:482](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L482) +Defined in: [candidate-execution/types.ts:488](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L488) ###### Parameters @@ -3906,7 +3916,7 @@ Absolute epoch-millisecond deadline owned by the runtime. > **stopAndCapture**(`request`, `context`): `Promise`\<[`AgentCandidateExecutorFinalCapture`](#agentcandidateexecutorfinalcapture)\> -Defined in: [candidate-execution/types.ts:499](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L499) +Defined in: [candidate-execution/types.ts:505](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L505) Kill any process/container still associated with the request, drain trace writes, and capture the final task workspace before teardown. @@ -3950,7 +3960,7 @@ Absolute execution deadline; a later stop acknowledgement cannot produce success ### AgentCandidateExecutorStopRequest -Defined in: [candidate-execution/types.ts:513](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L513) +Defined in: [candidate-execution/types.ts:519](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L519) Opaque process identity used for termination without re-exposing launch credentials. @@ -3960,19 +3970,19 @@ Opaque process identity used for termination without re-exposing launch credenti > `readonly` **executionId**: `string` -Defined in: [candidate-execution/types.ts:514](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L514) +Defined in: [candidate-execution/types.ts:520](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L520) ##### executionPlanDigest > `readonly` **executionPlanDigest**: `` `sha256:${string}` `` -Defined in: [candidate-execution/types.ts:515](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L515) +Defined in: [candidate-execution/types.ts:521](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L521) *** ### AgentCandidateExecutorWorkspaceInput -Defined in: [candidate-execution/types.ts:518](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L518) +Defined in: [candidate-execution/types.ts:524](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L524) #### Properties @@ -3980,19 +3990,19 @@ Defined in: [candidate-execution/types.ts:518](https://github.com/tangle-network > `readonly` **snapshot**: `AgentCandidateWorkspaceSnapshotEvidence` -Defined in: [candidate-execution/types.ts:519](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L519) +Defined in: [candidate-execution/types.ts:525](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L525) ##### files > `readonly` **files**: readonly [`AgentCandidateExecutorWorkspaceFile`](#agentcandidateexecutorworkspacefile)[] -Defined in: [candidate-execution/types.ts:520](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L520) +Defined in: [candidate-execution/types.ts:526](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L526) *** ### AgentCandidateExecutorWorkspaceFile -Defined in: [candidate-execution/types.ts:523](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L523) +Defined in: [candidate-execution/types.ts:529](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L529) #### Properties @@ -4000,25 +4010,25 @@ Defined in: [candidate-execution/types.ts:523](https://github.com/tangle-network > `readonly` **path**: `string` -Defined in: [candidate-execution/types.ts:524](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L524) +Defined in: [candidate-execution/types.ts:530](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L530) ##### mode -> `readonly` **mode**: `420` \| `493` +> `readonly` **mode**: `number` -Defined in: [candidate-execution/types.ts:525](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L525) +Defined in: [candidate-execution/types.ts:531](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L531) ##### bytes > `readonly` **bytes**: `Uint8Array` -Defined in: [candidate-execution/types.ts:526](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L526) +Defined in: [candidate-execution/types.ts:532](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L532) *** ### AgentCandidateExecutorProfileFile -Defined in: [candidate-execution/types.ts:529](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L529) +Defined in: [candidate-execution/types.ts:535](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L535) #### Properties @@ -4026,25 +4036,25 @@ Defined in: [candidate-execution/types.ts:529](https://github.com/tangle-network > `readonly` **path**: `string` -Defined in: [candidate-execution/types.ts:530](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L530) +Defined in: [candidate-execution/types.ts:536](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L536) ##### mode -> `readonly` **mode**: `420` \| `493` +> `readonly` **mode**: `number` -Defined in: [candidate-execution/types.ts:531](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L531) +Defined in: [candidate-execution/types.ts:537](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L537) ##### bytes > `readonly` **bytes**: `Uint8Array` -Defined in: [candidate-execution/types.ts:532](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L532) +Defined in: [candidate-execution/types.ts:538](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L538) *** ### AgentCandidateWorkspaceArchiveLimits -Defined in: [candidate-execution/workspace-archive.ts:52](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/workspace-archive.ts#L52) +Defined in: [candidate-execution/workspace-archive.ts:56](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/workspace-archive.ts#L56) #### Properties @@ -4052,49 +4062,49 @@ Defined in: [candidate-execution/workspace-archive.ts:52](https://github.com/tan > **maxArchiveBytes**: `number` -Defined in: [candidate-execution/workspace-archive.ts:53](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/workspace-archive.ts#L53) +Defined in: [candidate-execution/workspace-archive.ts:57](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/workspace-archive.ts#L57) ##### maxEmbeddedArtifactBytes > **maxEmbeddedArtifactBytes**: `number` -Defined in: [candidate-execution/workspace-archive.ts:54](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/workspace-archive.ts#L54) +Defined in: [candidate-execution/workspace-archive.ts:58](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/workspace-archive.ts#L58) ##### maxFiles > **maxFiles**: `number` -Defined in: [candidate-execution/workspace-archive.ts:55](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/workspace-archive.ts#L55) +Defined in: [candidate-execution/workspace-archive.ts:59](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/workspace-archive.ts#L59) ##### maxFileBytes > **maxFileBytes**: `number` -Defined in: [candidate-execution/workspace-archive.ts:56](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/workspace-archive.ts#L56) +Defined in: [candidate-execution/workspace-archive.ts:60](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/workspace-archive.ts#L60) ##### maxTotalFileBytes > **maxTotalFileBytes**: `number` -Defined in: [candidate-execution/workspace-archive.ts:57](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/workspace-archive.ts#L57) +Defined in: [candidate-execution/workspace-archive.ts:61](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/workspace-archive.ts#L61) ##### maxPathBytes > **maxPathBytes**: `number` -Defined in: [candidate-execution/workspace-archive.ts:58](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/workspace-archive.ts#L58) +Defined in: [candidate-execution/workspace-archive.ts:62](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/workspace-archive.ts#L62) ##### maxRepositoryBundleBytes > **maxRepositoryBundleBytes**: `number` -Defined in: [candidate-execution/workspace-archive.ts:59](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/workspace-archive.ts#L59) +Defined in: [candidate-execution/workspace-archive.ts:63](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/workspace-archive.ts#L63) *** ### CaptureAgentCandidateWorkspaceOptions -Defined in: [candidate-execution/workspace-archive.ts:98](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/workspace-archive.ts#L98) +Defined in: [candidate-execution/workspace-archive.ts:102](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/workspace-archive.ts#L102) #### Properties @@ -4102,7 +4112,7 @@ Defined in: [candidate-execution/workspace-archive.ts:98](https://github.com/tan > `optional` **includeRepository?**: `boolean` -Defined in: [candidate-execution/workspace-archive.ts:100](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/workspace-archive.ts#L100) +Defined in: [candidate-execution/workspace-archive.ts:104](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/workspace-archive.ts#L104) Include Git HEAD so task preparation can prove its exact commit and tree. @@ -4110,13 +4120,13 @@ Include Git HEAD so task preparation can prove its exact commit and tree. > `optional` **limits?**: `Partial`\<[`AgentCandidateWorkspaceArchiveLimits`](#agentcandidateworkspacearchivelimits)\> -Defined in: [candidate-execution/workspace-archive.ts:101](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/workspace-archive.ts#L101) +Defined in: [candidate-execution/workspace-archive.ts:105](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/workspace-archive.ts#L105) ##### artifactPersistence? > `optional` **artifactPersistence?**: `object` -Defined in: [candidate-execution/workspace-archive.ts:103](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/workspace-archive.ts#L103) +Defined in: [candidate-execution/workspace-archive.ts:107](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/workspace-archive.ts#L107) Use the evaluator-owned artifact store when manifest or archive bytes should not be embedded. @@ -4136,7 +4146,7 @@ Use the evaluator-owned artifact store when manifest or archive bytes should not ### CreateAgentCandidateWorkspacePortOptions -Defined in: [candidate-execution/workspace-archive.ts:110](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/workspace-archive.ts#L110) +Defined in: [candidate-execution/workspace-archive.ts:114](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/workspace-archive.ts#L114) #### Properties @@ -4144,13 +4154,13 @@ Defined in: [candidate-execution/workspace-archive.ts:110](https://github.com/ta > `optional` **limits?**: `Partial`\<[`AgentCandidateWorkspaceArchiveLimits`](#agentcandidateworkspacearchivelimits)\> -Defined in: [candidate-execution/workspace-archive.ts:111](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/workspace-archive.ts#L111) +Defined in: [candidate-execution/workspace-archive.ts:115](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/workspace-archive.ts#L115) *** ### CapturedAgentCandidateWorkspace -Defined in: [candidate-execution/workspace-archive.ts:114](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/workspace-archive.ts#L114) +Defined in: [candidate-execution/workspace-archive.ts:118](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/workspace-archive.ts#L118) #### Properties @@ -4158,13 +4168,13 @@ Defined in: [candidate-execution/workspace-archive.ts:114](https://github.com/ta > `readonly` **snapshot**: `AgentCandidateWorkspaceSnapshotEvidence` -Defined in: [candidate-execution/workspace-archive.ts:115](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/workspace-archive.ts#L115) +Defined in: [candidate-execution/workspace-archive.ts:119](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/workspace-archive.ts#L119) ##### archive > `readonly` **archive**: `Uint8Array` -Defined in: [candidate-execution/workspace-archive.ts:117](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/workspace-archive.ts#L117) +Defined in: [candidate-execution/workspace-archive.ts:121](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/workspace-archive.ts#L121) Caller-owned bytes accepted by createAgentCandidateWorkspacePort. @@ -10970,9 +10980,9 @@ Secret-free response from the service's reservation endpoint. ### AgentCandidateOutputPurpose -> **AgentCandidateOutputPurpose** = `"candidate-workspace-manifest"` \| `"candidate-workspace-archive"` \| `"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"` +> **AgentCandidateOutputPurpose** = `"candidate-workspace-manifest"` \| `"candidate-workspace-archive"` \| `"task-manifest"` \| `"task-archive"` \| `"task-patch"` \| `"task-outcome"` \| `"memory-after-manifest"` \| `"memory-after-archive"` \| `"grader-evidence"` \| `"benchmark-result"` \| `"model-settlement"` \| `"trace"` \| `"executor-capture"` \| `"run-receipt"` \| `"failure-evidence"` -Defined in: [candidate-execution/types.ts:38](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L38) +Defined in: [candidate-execution/types.ts:39](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L39) *** @@ -10980,7 +10990,7 @@ Defined in: [candidate-execution/types.ts:38](https://github.com/tangle-network/ > **AgentCandidateModelLimits** = `Pick`\<`AgentCandidateExecutionLimits`, `"maxModelCalls"` \| `"maxInputTokens"` \| `"maxOutputTokens"` \| `"maxCostUsd"`\> -Defined in: [candidate-execution/types.ts:151](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L151) +Defined in: [candidate-execution/types.ts:153](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L153) Limits mechanically enforced by the evaluator-owned model gateway. @@ -10988,15 +10998,15 @@ Limits mechanically enforced by the evaluator-owned model gateway. ### AgentCandidateRunFinalization -> **AgentCandidateRunFinalization** = \{ `succeeded`: `true`; `receipt`: [`CanonicalCandidateDocument`](#canonicalcandidatedocument)\<`AgentCandidateRunReceiptV2`\>; `artifacts`: \{ `modelSettlement`: `AgentCandidateArtifactRef`; `taskOutcome`: `AgentCandidateArtifactRef`; `benchmarkResult`: `AgentCandidateArtifactRef`; `runReceipt`: `AgentCandidateArtifactRef`; \}; \} \| \{ `succeeded`: `false`; `reason`: `string`; `partial`: \{ `executionId`: `string`; `bundleDigest`: `Sha256Digest`; `executionPlanDigest`: `Sha256Digest`; `materializationReceiptDigest`: `Sha256Digest`; `termination?`: `AgentCandidateTermination`; \}; `usage`: `AgentCandidateSpend` \| `null`; \} +> **AgentCandidateRunFinalization** = \{ `succeeded`: `true`; `receipt`: [`CanonicalCandidateDocument`](#canonicalcandidatedocument)\<`AgentCandidateRunReceipt`\>; `artifacts`: \{ `executorCapture`: `AgentCandidateArtifactRef`; `modelSettlement`: `AgentCandidateArtifactRef`; `taskOutcome`: `AgentCandidateArtifactRef`; `benchmarkResult`: `AgentCandidateArtifactRef`; `runReceipt`: `AgentCandidateArtifactRef`; \}; \} \| \{ `succeeded`: `false`; `reason`: `string`; `partial`: \{ `executionId`: `string`; `bundleDigest`: `Sha256Digest`; `executionPlanDigest`: `Sha256Digest`; `materializationReceiptDigest`: `Sha256Digest`; `termination?`: `AgentCandidateTermination`; \}; `usage`: `AgentCandidateSpend` \| `null`; \} -Defined in: [candidate-execution/types.ts:535](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L535) +Defined in: [candidate-execution/types.ts:541](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L541) #### Union Members ##### Type Literal -\{ `succeeded`: `true`; `receipt`: [`CanonicalCandidateDocument`](#canonicalcandidatedocument)\<`AgentCandidateRunReceiptV2`\>; `artifacts`: \{ `modelSettlement`: `AgentCandidateArtifactRef`; `taskOutcome`: `AgentCandidateArtifactRef`; `benchmarkResult`: `AgentCandidateArtifactRef`; `runReceipt`: `AgentCandidateArtifactRef`; \}; \} +\{ `succeeded`: `true`; `receipt`: [`CanonicalCandidateDocument`](#canonicalcandidatedocument)\<`AgentCandidateRunReceipt`\>; `artifacts`: \{ `executorCapture`: `AgentCandidateArtifactRef`; `modelSettlement`: `AgentCandidateArtifactRef`; `taskOutcome`: `AgentCandidateArtifactRef`; `benchmarkResult`: `AgentCandidateArtifactRef`; `runReceipt`: `AgentCandidateArtifactRef`; \}; \} *** @@ -11923,7 +11933,7 @@ MUST map this to `RunRecord.error` rather than recording silent > `const` **CANDIDATE\_TRACE\_TAGS**: `object` -Defined in: [candidate-execution/types.ts:561](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L561) +Defined in: [candidate-execution/types.ts:568](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L568) Protected trace tags that bind a run to one prepared candidate execution. @@ -11951,7 +11961,7 @@ Protected trace tags that bind a run to one prepared candidate execution. > `const` **CANDIDATE\_TRACE\_ENV**: `object` -Defined in: [candidate-execution/types.ts:569](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L569) +Defined in: [candidate-execution/types.ts:576](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/types.ts#L576) Environment keys used to propagate immutable candidate trace identity. @@ -12311,7 +12321,7 @@ Maximum completion tokens, sent as OpenAI-compatible `max_tokens`. Omit for prov ### buildAgentCandidateBundle() -> **buildAgentCandidateBundle**(`input`): `AgentCandidateBundleV1` +> **buildAgentCandidateBundle**(`input`): `AgentCandidateBundle` Defined in: [candidate-execution/builder.ts:76](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/builder.ts#L76) @@ -12329,13 +12339,13 @@ to re-read external knowledge, memory, repository, and workspace artifacts. #### Returns -`AgentCandidateBundleV1` +`AgentCandidateBundle` *** ### sealAgentCandidateBundle() -> **sealAgentCandidateBundle**(`input`): `AgentCandidateBundleV1` +> **sealAgentCandidateBundle**(`input`): `AgentCandidateBundle` Defined in: [candidate-execution/bundle.ts:10](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/bundle.ts#L10) @@ -12349,7 +12359,7 @@ Validate and content-address a candidate bundle before it crosses an approval bo #### Returns -`AgentCandidateBundleV1` +`AgentCandidateBundle` *** @@ -12463,7 +12473,7 @@ Persist evaluator evidence, read it back, and bind the returned locator to the e > **prepareAgentCandidateExecution**(`candidate`, `task`, `ports`, `options?`): `Promise`\<[`PreparedAgentCandidateExecution`](#preparedagentcandidateexecution)\> -Defined in: [candidate-execution/prepare.ts:98](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/prepare.ts#L98) +Defined in: [candidate-execution/prepare.ts:99](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/prepare.ts#L99) Materializes a verified candidate into one immutable evaluator-owned execution plan. @@ -12639,7 +12649,7 @@ Verifies every digest, resource, workspace, and Git object in a candidate bundle > **captureAgentCandidateWorkspace**(`rootInput`, `options?`): `Promise`\<[`CapturedAgentCandidateWorkspace`](#capturedagentcandidateworkspace)\> -Defined in: [candidate-execution/workspace-archive.ts:121](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/workspace-archive.ts#L121) +Defined in: [candidate-execution/workspace-archive.ts:125](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/workspace-archive.ts#L125) Capture one exact regular-file workspace for immutable candidate execution. @@ -12663,7 +12673,7 @@ Capture one exact regular-file workspace for immutable candidate execution. > **captureAgentCandidateWorkspaceFiles**(`input`, `options?`): `Promise`\<[`CapturedAgentCandidateWorkspace`](#capturedagentcandidateworkspace)\> -Defined in: [candidate-execution/workspace-archive.ts:142](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/workspace-archive.ts#L142) +Defined in: [candidate-execution/workspace-archive.ts:146](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/workspace-archive.ts#L146) Capture detached files returned by a remote executor into the standard archive. @@ -12687,7 +12697,7 @@ readonly [`AgentCandidateExecutorWorkspaceFile`](#agentcandidateexecutorworkspac > **createAgentCandidateWorkspacePort**(`options?`): [`AgentCandidateWorkspacePort`](#agentcandidateworkspaceport) -Defined in: [candidate-execution/workspace-archive.ts:204](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/workspace-archive.ts#L204) +Defined in: [candidate-execution/workspace-archive.ts:208](https://github.com/tangle-network/agent-runtime/blob/main/src/candidate-execution/workspace-archive.ts#L208) Create the standard bounded materializer for candidate execution ports. diff --git a/docs/api/intelligence.md b/docs/api/intelligence.md index 582ef37b..5edf42a1 100644 --- a/docs/api/intelligence.md +++ b/docs/api/intelligence.md @@ -1160,7 +1160,7 @@ Defined in: [intelligence/improvement-cycle.ts:76](https://github.com/tangle-net ##### candidateBundle? -> `optional` **candidateBundle?**: `AgentCandidateBundleV1` +> `optional` **candidateBundle?**: `AgentCandidateBundle` Defined in: [intelligence/improvement-cycle.ts:77](https://github.com/tangle-network/agent-runtime/blob/main/src/intelligence/improvement-cycle.ts#L77) @@ -1338,7 +1338,7 @@ Defined in: [intelligence/improvement-cycle.ts:111](https://github.com/tangle-ne ##### buildCandidate? -> `optional` **buildCandidate?**: (`input`) => `AgentCandidateBundleV1` \| [`AgentCandidateBundleInput`](index.md#agentcandidatebundleinput) \| `Promise`\<`AgentCandidateBundleV1` \| [`AgentCandidateBundleInput`](index.md#agentcandidatebundleinput)\> +> `optional` **buildCandidate?**: (`input`) => `AgentCandidateBundle` \| [`AgentCandidateBundleInput`](index.md#agentcandidatebundleinput) \| `Promise`\<`AgentCandidateBundle` \| [`AgentCandidateBundleInput`](index.md#agentcandidatebundleinput)\> Defined in: [intelligence/improvement-cycle.ts:117](https://github.com/tangle-network/agent-runtime/blob/main/src/intelligence/improvement-cycle.ts#L117) @@ -1360,7 +1360,7 @@ measured comparison recommends the candidate. Return the sealed output of ###### Returns -`AgentCandidateBundleV1` \| [`AgentCandidateBundleInput`](index.md#agentcandidatebundleinput) \| `Promise`\<`AgentCandidateBundleV1` \| [`AgentCandidateBundleInput`](index.md#agentcandidatebundleinput)\> +`AgentCandidateBundle` \| [`AgentCandidateBundleInput`](index.md#agentcandidatebundleinput) \| `Promise`\<`AgentCandidateBundle` \| [`AgentCandidateBundleInput`](index.md#agentcandidatebundleinput)\> ##### now? @@ -1464,7 +1464,7 @@ Defined in: [intelligence/improvement-cycle.ts:139](https://github.com/tangle-ne ##### candidateBundle? -> `optional` **candidateBundle?**: `AgentCandidateBundleV1` \| [`AgentCandidateBundleInput`](index.md#agentcandidatebundleinput) +> `optional` **candidateBundle?**: `AgentCandidateBundle` \| [`AgentCandidateBundleInput`](index.md#agentcandidatebundleinput) Defined in: [intelligence/improvement-cycle.ts:140](https://github.com/tangle-network/agent-runtime/blob/main/src/intelligence/improvement-cycle.ts#L140) diff --git a/docs/api/primitive-catalog.md b/docs/api/primitive-catalog.md index c6cde362..4fed3f6c 100644 --- a/docs/api/primitive-catalog.md +++ b/docs/api/primitive-catalog.md @@ -7,7 +7,7 @@ # Primitive catalog — the never-stale anti-reinvention inventory -> **GENERATED** from `@tangle-network/agent-runtime@0.94.12` and `@tangle-network/agent-eval@0.120.1` by `scripts/gen-primitive-catalog.mjs`. Do NOT hand-edit — run `pnpm run docs:api`. This is the mechanical companion to the JUDGMENT in `canonical-api.md` (§2 decision table + §1.5 AgentProfile law): that doc says WHICH primitive to reach for and what NOT to build; this catalog proves WHAT exists. Per-symbol signatures + `file:line` live in the per-module pages under `docs/api/`. +> **GENERATED** from `@tangle-network/agent-runtime@0.94.13` and `@tangle-network/agent-eval@0.120.1` by `scripts/gen-primitive-catalog.mjs`. Do NOT hand-edit — run `pnpm run docs:api`. This is the mechanical companion to the JUDGMENT in `canonical-api.md` (§2 decision table + §1.5 AgentProfile law): that doc says WHICH primitive to reach for and what NOT to build; this catalog proves WHAT exists. Per-symbol signatures + `file:line` live in the per-module pages under `docs/api/`. ## 1. agent-runtime — own public surface @@ -15,7 +15,7 @@ Every subpath this package declares in `package.json` `exports`. Reach for these ### Root — task lifecycle, conversation, RSI verbs, observability -Import from `@tangle-network/agent-runtime` — 341 exports. +Import from `@tangle-network/agent-runtime` — 342 exports. | Symbol | Kind | Summary | |---|---|---| @@ -174,6 +174,7 @@ Import from `@tangle-network/agent-runtime` — 341 exports. | `ModelInfo` | interface | A model entry as returned by the Tangle Router `/v1/models` endpoint. | | `OpenAIChatTool` | interface | OpenAI Chat Completions tool descriptor. The shape mirrors the | | `OtelExportConfig` | interface | OTEL span exporter — streams LoopTraceEvents to an OTLP/HTTP collector. | +| `PreparedAgentCandidateKnowledge` | interface | Exact file-backed knowledge admitted by the candidate bundle. | | `RawTraceDistillerOptions` | interface | `rawTraceDistiller` — the meta-harness `analyzeGeneration` producer. | | `ReflectiveGeneratorOptions` | interface | `reflectiveGenerator` — the cheap, no-sandbox `CandidateGenerator`. It drafts | | `RouterEnv` | interface | Env keys the router base URL is resolved from. | @@ -935,7 +936,7 @@ Import from `@tangle-network/agent-runtime/primeintellect` — 27 exports. ### Candidate execution — immutable prepare, run, grade, and receipt -Import from `@tangle-network/agent-runtime/candidate-execution` — 95 exports. +Import from `@tangle-network/agent-runtime/candidate-execution` — 96 exports. | Symbol | Kind | Summary | |---|---|---| @@ -981,6 +982,7 @@ Import from `@tangle-network/agent-runtime/candidate-execution` — 95 exports. | `AgentCandidateRepositoryPort` | interface | Resolves a declared GitHub repository to an already-present local Git object store. | | `AgentCandidateWorkspacePort` | interface | Materializes an already-verified workspace archive. | | `BuildAgentCandidateBundleInput` | interface | Complete measured surfaces and execution policy compiled into one candidate bundle. | +| `PreparedAgentCandidateKnowledge` | interface | Exact file-backed knowledge admitted by the candidate bundle. | | `VerifiedAgentCandidateTaskOutcome` | interface | Branded task outcome that has survived independent patch and tree verification. | | `AgentCandidateBundleInput` | type | Exact candidate wire shape before the runtime computes its canonical digest. | | `AgentCandidateCodeSource` | type | Explicit control/no-op code or one finalized CodeSurface whose bytes must still verify. | diff --git a/docs/canonical-api.md b/docs/canonical-api.md index d930db64..2edb4355 100644 --- a/docs/canonical-api.md +++ b/docs/canonical-api.md @@ -2,7 +2,7 @@ -> **Version 0.94.12.** The export inventory + per-symbol signatures live in the generated `docs/api/` reference: **`docs/api/primitive-catalog.md`** is the never-stale, grouped list of every primitive to reuse (own surface + the agent-eval judge / authenticity / verification / statistics / campaign / token-usage surfaces), with each one's import path and one-line summary read live from source; the per-module pages hold the full signatures. The pinned substrate is agent-eval `>=0.120.1 <0.121.0`; the sandbox substrate that materializes profiles into harness shapes is `@tangle-network/sandbox` (peer `>=0.8.0 <1.0.0`). The neutral contract types (`AgentProfile`, `AgentProfileMcpServer`, `HarnessType`, `ReasoningEffort`, `Part`/`ToolPart`/`ToolState`, plus environment-provider types) are owned by **`@tangle-network/agent-interface`** (peer `>=0.25.0 <0.26.0`) — the single source of truth. Substrate primitives are re-exported through `@tangle-network/agent-eval/contract` (or `/campaign`), not local to this package — the catalog's §2 shows exactly which subpath each lives under. +> **Version 0.94.13.** The export inventory + per-symbol signatures live in the generated `docs/api/` reference: **`docs/api/primitive-catalog.md`** is the never-stale, grouped list of every primitive to reuse (own surface + the agent-eval judge / authenticity / verification / statistics / campaign / token-usage surfaces), with each one's import path and one-line summary read live from source; the per-module pages hold the full signatures. The pinned substrate is agent-eval `>=0.120.1 <0.121.0`; the sandbox substrate that materializes profiles into harness shapes is `@tangle-network/sandbox` (peer `>=0.8.0 <1.0.0`). The neutral contract types (`AgentProfile`, `AgentProfileMcpServer`, `HarnessType`, `ReasoningEffort`, `Part`/`ToolPart`/`ToolState`, plus environment-provider types) are owned by **`@tangle-network/agent-interface`** (peer `>=0.26.1 <0.27.0`) — the single source of truth. Substrate primitives are re-exported through `@tangle-network/agent-eval/contract` (or `/campaign`), not local to this package — the catalog's §2 shows exactly which subpath each lives under. > > **`./loops` is the runtime barrel** — `package.json` maps it to `src/runtime/index.ts`. Everything below labelled `/loops` is the recursive-atom + loop-kernel surface. > diff --git a/package.json b/package.json index a1223031..4a723def 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@tangle-network/agent-runtime", - "version": "0.94.12", + "version": "0.94.13", "description": "Shared task-lifecycle skeleton for agents: a recursive loop kernel for chat turns, one-shot tasks, and multi-attempt loops, with trace capture and eval-gated self-improvement. Domain behavior lives in adapters; scoring and ship-gates in @tangle-network/agent-eval.", "homepage": "https://github.com/tangle-network/agent-runtime#readme", "repository": { @@ -117,7 +117,7 @@ "devDependencies": { "@biomejs/biome": "^2.4.15", "@tangle-network/agent-eval": "0.120.1", - "@tangle-network/agent-interface": "^0.25.0", + "@tangle-network/agent-interface": "0.26.1", "@tangle-network/sandbox": "^0.9.7", "@types/node": "^25.9.3", "@types/tar-stream": "3.1.4", @@ -148,7 +148,7 @@ "packageManager": "pnpm@10.28.0", "peerDependencies": { "@tangle-network/agent-eval": ">=0.120.1 <0.121.0", - "@tangle-network/agent-interface": ">=0.25.0 <0.26.0", + "@tangle-network/agent-interface": ">=0.26.1 <0.27.0", "@tangle-network/sandbox": ">=0.8.0 <1.0.0", "playwright": "^1.40.0" }, diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 2e91f453..d1de035a 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -25,8 +25,8 @@ importers: specifier: 0.120.1 version: 0.120.1(typescript@5.9.3) '@tangle-network/agent-interface': - specifier: ^0.25.0 - version: 0.25.0 + specifier: 0.26.1 + version: 0.26.1 '@tangle-network/sandbox': specifier: ^0.9.7 version: 0.9.7(viem@2.54.6(typescript@5.9.3)(zod@4.4.3)) diff --git a/src/candidate-execution/artifacts.ts b/src/candidate-execution/artifacts.ts index bcca8faa..4cbe4446 100644 --- a/src/candidate-execution/artifacts.ts +++ b/src/candidate-execution/artifacts.ts @@ -5,8 +5,8 @@ import { relative, resolve, sep } from 'node:path' import type { AgentCandidateArtifactRef, AgentCandidateCapturedArtifact, - AgentCandidateProfilePlanMaterialV1, - AgentCandidateWorkspaceManifestMaterialV1, + AgentCandidateProfilePlanMaterial, + AgentCandidateWorkspaceManifestMaterial, AgentCandidateWorkspaceSnapshotEvidence, } from '@tangle-network/agent-interface' @@ -64,7 +64,7 @@ export async function verifyWorkspaceSnapshotArtifacts( export async function verifyMaterializedWorkspace( root: string, - expected: AgentCandidateWorkspaceManifestMaterialV1, + expected: AgentCandidateWorkspaceManifestMaterial, options: { ignoredProtectedRootEntries?: readonly ('.git' | '.sidecar')[] } = {}, ): Promise { const observed = await scanWorkspace(root, new Set(options.ignoredProtectedRootEntries ?? [])) @@ -82,8 +82,8 @@ export async function captureMaterializedWorkspace( } } = {}, ): Promise<{ - manifest: AgentCandidateWorkspaceManifestMaterialV1 - files: ReadonlyArray<{ path: string; mode: 0o644 | 0o755; bytes: Uint8Array }> + manifest: AgentCandidateWorkspaceManifestMaterial + files: ReadonlyArray<{ path: string; mode: number; bytes: Uint8Array }> }> { const observed = await scanWorkspace( root, @@ -103,9 +103,9 @@ export async function captureMaterializedWorkspace( /** Capture exact verified regular-file bytes for fresh isolated materialization. */ export async function readMaterializedWorkspaceFiles( root: string, - expected: AgentCandidateWorkspaceManifestMaterialV1, + expected: AgentCandidateWorkspaceManifestMaterial, options: { ignoredProtectedRootEntries?: readonly ('.git' | '.sidecar')[] } = {}, -): Promise> { +): Promise> { const observed = await captureMaterializedWorkspace(root, options) assertWorkspaceManifest(observed.manifest, expected) return observed.files.map((file) => @@ -113,9 +113,26 @@ export async function readMaterializedWorkspaceFiles( ) } +export function candidateWorkspaceManifest( + files: ReadonlyArray<{ path: string; mode: number; bytes: Uint8Array }>, +): AgentCandidateWorkspaceManifestMaterial { + return { + schemaVersion: 2, + kind: 'agent-candidate-workspace-manifest', + files: files + .map((file) => ({ + path: file.path, + mode: file.mode, + sha256: sha256Bytes(file.bytes), + byteLength: file.bytes.byteLength, + })) + .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0)), + } +} + function assertWorkspaceManifest( - observed: AgentCandidateWorkspaceManifestMaterialV1, - expected: AgentCandidateWorkspaceManifestMaterialV1, + observed: AgentCandidateWorkspaceManifestMaterial, + expected: AgentCandidateWorkspaceManifestMaterial, ): void { if (!Buffer.from(canonicalCandidateBytes(observed)).equals(canonicalCandidateBytes(expected))) { throw new Error( @@ -126,7 +143,7 @@ function assertWorkspaceManifest( export async function verifyMaterializedProfileWorkspace( root: string, - expected: AgentCandidateProfilePlanMaterialV1, + expected: AgentCandidateProfilePlanMaterial, ): Promise { const observed = await scanWorkspace(root, new Set()) const observedProfile = observed.manifest.files.map(({ path, mode, sha256 }) => ({ @@ -152,8 +169,8 @@ async function scanWorkspace( maxTotalFileBytes: number }, ): Promise<{ - manifest: AgentCandidateWorkspaceManifestMaterialV1 - files: Array<{ path: string; mode: 0o644 | 0o755; bytes: Uint8Array }> + manifest: AgentCandidateWorkspaceManifestMaterial + files: Array<{ path: string; mode: number; bytes: Uint8Array }> }> { const absoluteRoot = resolve(root) const rootStats = await lstat(absoluteRoot) @@ -163,8 +180,7 @@ async function scanWorkspace( if ((await realpath(absoluteRoot)) !== absoluteRoot) { throw new Error('workspace root has a symlinked path component') } - const files: AgentCandidateWorkspaceManifestMaterialV1['files'] = [] - const capturedFiles: Array<{ path: string; mode: 0o644 | 0o755; bytes: Uint8Array }> = [] + const capturedFiles: Array<{ path: string; mode: number; bytes: Uint8Array }> = [] let totalBytes = 0 async function visit(directory: string): Promise { @@ -190,7 +206,7 @@ async function scanWorkspace( if (!stats.isFile()) { throw new Error(`workspace contains a non-regular entry: ${relPath}`) } - if (limits && files.length >= limits.maxFiles) { + if (limits && capturedFiles.length >= limits.maxFiles) { throw new Error('workspace exceeds maxFiles') } const descriptor = await open( @@ -207,9 +223,6 @@ async function scanWorkspace( throw new Error(`workspace contains a hard-linked file: ${relPath}`) } const mode = openedStats.mode & 0o777 - if (mode !== 0o644 && mode !== 0o755) { - throw new Error(`workspace file has unsupported mode ${mode.toString(8)}: ${relPath}`) - } if (limits && openedStats.size > limits.maxFileBytes) { throw new Error(`workspace file exceeds maxFileBytes: ${relPath}`) } @@ -223,14 +236,7 @@ async function scanWorkspace( relPath, ) totalBytes += bytes.byteLength - const supportedMode = mode as 0o644 | 0o755 - files.push({ - path: relPath, - mode: supportedMode, - sha256: sha256Bytes(bytes), - byteLength: bytes.byteLength, - }) - capturedFiles.push({ path: relPath, mode: supportedMode, bytes: Uint8Array.from(bytes) }) + capturedFiles.push({ path: relPath, mode, bytes: Uint8Array.from(bytes) }) } finally { await descriptor.close() } @@ -238,14 +244,8 @@ async function scanWorkspace( } await visit(absoluteRoot) - files.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0)) - capturedFiles.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0)) return { - manifest: { - schemaVersion: 1, - kind: 'agent-candidate-workspace-manifest', - files, - }, + manifest: candidateWorkspaceManifest(capturedFiles), files: capturedFiles, } } diff --git a/src/candidate-execution/builder.ts b/src/candidate-execution/builder.ts index 4fb05fc2..6ff0bd60 100644 --- a/src/candidate-execution/builder.ts +++ b/src/candidate-execution/builder.ts @@ -82,7 +82,7 @@ export function buildAgentCandidateBundle( const compiledProfile = compileCandidateProfile(input.profile) const profileDiffIds = compiledProfile.profileDiffIds const bundle: AgentCandidateBundleInput = { - schemaVersion: 1, + schemaVersion: 2, kind: 'agent-candidate-bundle', digestAlgorithm: 'rfc8785-sha256', profile: compiledProfile.profile, diff --git a/src/candidate-execution/executor-capture.ts b/src/candidate-execution/executor-capture.ts index d8a68cee..df455e12 100644 --- a/src/candidate-execution/executor-capture.ts +++ b/src/candidate-execution/executor-capture.ts @@ -1,7 +1,12 @@ import { + type AgentCandidateTaskOutcomeEvidence, + type AgentCandidateTermination, + type AgentCandidateWorkspaceSnapshotEvidence, agentCandidateTerminationSchema, agentCandidateWorkspaceManifestMaterialSchema, + type Sha256Digest, } from '@tangle-network/agent-interface' +import { canonicalCandidateBytes } from './digest' import { assertExactObjectKeys as assertExactKeys } from './exact-object' import type { AgentCandidateExecutorFinalCapture, AgentCandidateProtectedRunCapture } from './types' @@ -39,6 +44,26 @@ export function sealAgentCandidateExecutorFinalCapture( }) } +/** Encode the complete evaluator-owned process result as one durable artifact. */ +export function encodeAgentCandidateExecutorCapture(input: { + executionId: string + executionPlanDigest: Sha256Digest + termination: AgentCandidateTermination + taskOutcome: AgentCandidateTaskOutcomeEvidence + memoryAfter?: AgentCandidateWorkspaceSnapshotEvidence +}): Uint8Array { + return canonicalCandidateBytes({ + schemaVersion: 1, + kind: 'agent-candidate-executor-capture', + executionId: input.executionId, + executionPlanDigest: input.executionPlanDigest, + termination: input.termination, + stopped: true, + taskOutcome: input.taskOutcome, + ...(input.memoryAfter ? { memoryAfter: input.memoryAfter } : {}), + }) +} + function sealMemoryCapture( value: unknown, ): NonNullable { diff --git a/src/candidate-execution/finalize.ts b/src/candidate-execution/finalize.ts index d06ac49a..02571a02 100644 --- a/src/candidate-execution/finalize.ts +++ b/src/candidate-execution/finalize.ts @@ -8,15 +8,16 @@ import type { AgentCandidateBenchmarkResultEvidence, AgentCandidateMemoryReceipt, AgentCandidateModelSettlementEvidence, - AgentCandidateRunReceiptV2, + AgentCandidateRunReceipt, AgentCandidateSpend, AgentCandidateTermination, } from '@tangle-network/agent-interface' -import { agentCandidateRunReceiptV2Schema } from '@tangle-network/agent-interface' +import { agentCandidateRunReceiptSchema } from '@tangle-network/agent-interface' import { readMaterializedWorkspaceFiles } from './artifacts' import { canonicalCandidateBytes, canonicalCandidateDocument } from './digest' import { + encodeAgentCandidateExecutorCapture, sealAgentCandidateExecutorFinalCapture, sealAgentCandidateProtectedRunCapture, } from './executor-capture' @@ -112,7 +113,6 @@ export async function finalizeAgentCandidateRun( const modelSpans = orderedSpans.filter(isLlmSpan) assertTraceMatchesModelSettlement(modelSpans, settlement) - const usage = settlement.usage enforceLimits(state, run.startedAt, run.endedAt, orderedSpans, settlement) const finalCapture = sealAgentCandidateExecutorFinalCapture(evidence.finalCapture) const memory = await memoryReceipt( @@ -122,6 +122,20 @@ export async function finalizeAgentCandidateRun( protectedValues, signal, ) + const executorCaptureBytes = encodeAgentCandidateExecutorCapture({ + executionId: protectedCapture.executionId, + executionPlanDigest: state.executionPlan.value.digest, + termination: protectedCapture.termination, + taskOutcome: evidence.taskOutcome.evidence, + ...(memory.mode === 'isolated' ? { memoryAfter: memory.afterState } : {}), + }) + assertNoProtectedBytes(executorCaptureBytes, protectedValues) + const executorCapture = await persistCandidateOutputArtifact(evidence.outputArtifacts, { + executionId: state.executionId, + purpose: 'executor-capture', + bytes: executorCaptureBytes, + signal, + }) const redacted = redactProtectedValue( { @@ -167,24 +181,22 @@ export async function finalizeAgentCandidateRun( orderedArtifacts.length, modelCallCount: modelSpans.length, } - const document = canonicalCandidateDocument({ - schemaVersion: 2, + const document = canonicalCandidateDocument({ + schemaVersion: 3, kind: 'agent-candidate-run', digestAlgorithm: 'rfc8785-sha256', bundleDigest: state.bundle.digest, materializationReceiptDigest: state.materializationReceipt.digest, executionPlanDigest: state.executionPlan.value.digest, memory, - usage, - modelUsage: { resolved: state.resolvedModel, usage }, trace, termination, - fixedUsage: settlement.fixedUsage, + executorCapture, modelSettlement: evidence.modelSettlement, taskOutcome: evidence.taskOutcome.evidence, benchmarkResult: evidence.benchmarkResult, }) - agentCandidateRunReceiptV2Schema.parse(document.value) + agentCandidateRunReceiptSchema.parse(document.value) const runReceipt = await persistCandidateOutputArtifact(evidence.outputArtifacts, { executionId: state.executionId, purpose: 'run-receipt', @@ -195,6 +207,7 @@ export async function finalizeAgentCandidateRun( succeeded: true, receipt: document, artifacts: { + executorCapture, modelSettlement: evidence.modelSettlement.artifact, taskOutcome: evidence.taskOutcome.evidence.artifact, benchmarkResult: evidence.benchmarkResult.artifact, diff --git a/src/candidate-execution/git-materialize.ts b/src/candidate-execution/git-materialize.ts index 249b894a..8a530df1 100644 --- a/src/candidate-execution/git-materialize.ts +++ b/src/candidate-execution/git-materialize.ts @@ -7,11 +7,11 @@ import type { AgentCandidateCode, AgentCandidateGitHubRepository, AgentCandidateGitHubResource, - AgentCandidateWorkspaceManifestMaterialV1, + AgentCandidateWorkspaceManifestMaterial, } from '@tangle-network/agent-interface' -import { verifyBytes } from './artifacts' -import { canonicalCandidateBytes, sha256Bytes } from './digest' +import { candidateWorkspaceManifest, verifyBytes } from './artifacts' +import { canonicalCandidateBytes } from './digest' import type { AgentCandidateRepositoryPort } from './types' interface GitResult { @@ -121,7 +121,7 @@ export async function verifyTaskOutcomePatch(input: { baseTree: string resultTree: string patch: Uint8Array - afterState: AgentCandidateWorkspaceManifestMaterialV1 + afterState: AgentCandidateWorkspaceManifestMaterial }): Promise<{ resultTree: string; resultCommit: string }> { const repositoryRoot = resolve(input.repositoryRoot) await verifyTaskCheckout(repositoryRoot, input) @@ -319,20 +319,10 @@ async function workspaceManifestFromGitTree( repositoryRoot: string, tree: string, environment: Record, -): Promise { - const files = (await readCandidateGitTreeFiles(repositoryRoot, tree, environment)).map( - ({ path, mode, bytes }) => ({ - path, - mode, - sha256: sha256Bytes(bytes), - byteLength: bytes.byteLength, - }), +): Promise { + return candidateWorkspaceManifest( + await readCandidateGitTreeFiles(repositoryRoot, tree, environment), ) - return { - schemaVersion: 1, - kind: 'agent-candidate-workspace-manifest', - files, - } } export async function readCandidateGitTreeFiles( diff --git a/src/candidate-execution/index.ts b/src/candidate-execution/index.ts index 0b363fc0..6f3e8701 100644 --- a/src/candidate-execution/index.ts +++ b/src/candidate-execution/index.ts @@ -101,6 +101,7 @@ export { type CanonicalCandidateDocument, type PreparedAgentCandidateExecution, type PreparedAgentCandidateInstruction, + type PreparedAgentCandidateKnowledge, type PreparedAgentCandidateLaunch, type PreparedAgentCandidateTrace, type ResolvedAgentCandidateContainer, diff --git a/src/candidate-execution/knowledge.ts b/src/candidate-execution/knowledge.ts new file mode 100644 index 00000000..90ca254a --- /dev/null +++ b/src/candidate-execution/knowledge.ts @@ -0,0 +1,47 @@ +import { mkdtemp, rm } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { join } from 'node:path' + +import { readMaterializedWorkspaceFiles } from './artifacts' +import type { + AgentCandidateExecutionPorts, + PreparedAgentCandidateKnowledge, + VerifiedAgentCandidate, +} from './types' +import { verifiedArtifactBytes } from './verify' + +/** Verify and detach the exact file-backed knowledge admitted by the bundle. */ +export async function prepareAgentCandidateKnowledge( + candidate: VerifiedAgentCandidate, + ports: AgentCandidateExecutionPorts, +): Promise { + const knowledge = candidate.bundle.knowledge + if (!knowledge) return undefined + + const archive = await verifiedArtifactBytes(candidate, knowledge.snapshot.archive) + const retrievalConfig = knowledge.retrievalConfig + ? await verifiedArtifactBytes(candidate, knowledge.retrievalConfig) + : undefined + const root = await mkdtemp(join(tmpdir(), 'agent-candidate-knowledge-')) + try { + await ports.workspaces.materialize({ + role: 'knowledge', + snapshot: knowledge.snapshot, + archive, + destination: root, + }) + const files = await readMaterializedWorkspaceFiles(root, knowledge.snapshot.material) + return Object.freeze({ + candidate: knowledge.candidate, + snapshot: knowledge.snapshot, + files: Object.freeze( + files.map((file) => + Object.freeze({ path: file.path, mode: file.mode, bytes: Uint8Array.from(file.bytes) }), + ), + ), + ...(retrievalConfig ? { retrievalConfig: Uint8Array.from(retrievalConfig) } : {}), + }) + } finally { + await rm(root, { recursive: true, force: true }) + } +} diff --git a/src/candidate-execution/outcome-evidence.ts b/src/candidate-execution/outcome-evidence.ts index 3cca4e73..e2ac338d 100644 --- a/src/candidate-execution/outcome-evidence.ts +++ b/src/candidate-execution/outcome-evidence.ts @@ -36,6 +36,7 @@ import { persistCandidateWorkspaceSnapshot, provisionalCandidateWorkspaceSnapshot, } from './workspace-snapshot' +import { workspaceTaskRepository } from './workspace-task' export type PersistedAgentCandidateModelSettlement = AgentCandidateModelSettlementEvidence & { artifact: AgentCandidateArtifactRef @@ -105,7 +106,7 @@ export async function persistCandidateModelSettlementEvidence( }) return immutableCandidateValue( agentCandidateModelSettlementEvidenceSchema.parse({ - schemaVersion: 1, + schemaVersion: 2, kind: 'agent-candidate-model-settlement', digest, material, @@ -130,7 +131,7 @@ export async function persistVerifiedCandidateTaskOutcome( assertNoProtectedBytes(archive, protectedValues) const provisional = provisionalCandidateWorkspaceSnapshot(capture.afterState, archive) const afterState = provisional.material - const repository = state.executionPlan.value.material.task.repository + const repository = workspaceTaskRepository(state.executionPlan.value.material.task) const verified = await verifyTaskOutcomePatch({ repositoryRoot: state.roots.staging.taskRoot, baseCommit: repository.baseCommit, @@ -157,25 +158,28 @@ export async function persistVerifiedCandidateTaskOutcome( signal, }) const material = { - schemaVersion: 1 as const, + schemaVersion: 2 as const, kind: 'agent-candidate-task-outcome-material' as const, executionPlanDigest: state.executionPlan.value.digest, - baseRepository: { - identity: repository.identity, - rootIdentity: repository.rootIdentity, - commit: repository.baseCommit, - tree: repository.baseTree, - }, - resultRepository: { - identity: repository.identity, - rootIdentity: repository.rootIdentity, - commit: verified.resultCommit, - tree: verified.resultTree, - }, - afterState: snapshot, - gitDiff: { - format: 'git-diff-binary' as const, - artifact: gitDiff, + outcome: { + kind: 'workspace' as const, + baseRepository: { + identity: repository.identity, + rootIdentity: repository.rootIdentity, + commit: repository.baseCommit, + tree: repository.baseTree, + }, + resultRepository: { + identity: repository.identity, + rootIdentity: repository.rootIdentity, + commit: verified.resultCommit, + tree: verified.resultTree, + }, + afterState: snapshot, + gitDiff: { + format: 'git-diff-binary' as const, + artifact: gitDiff, + }, }, } const bytes = canonicalCandidateBytes(material) @@ -188,7 +192,7 @@ export async function persistVerifiedCandidateTaskOutcome( }) const evidence = immutableCandidateValue( agentCandidateTaskOutcomeEvidenceSchema.parse({ - schemaVersion: 1, + schemaVersion: 2, kind: 'agent-candidate-task-outcome', digest, material, diff --git a/src/candidate-execution/prepare.ts b/src/candidate-execution/prepare.ts index 3579e436..6045c36f 100644 --- a/src/candidate-execution/prepare.ts +++ b/src/candidate-execution/prepare.ts @@ -7,7 +7,7 @@ import type { AgentCandidateEffectiveMemory, AgentCandidateExecutionLimits, AgentCandidateExecutionPlanEvidence, - AgentCandidateExecutionPlanMaterialV1, + AgentCandidateExecutionPlanMaterial, AgentCandidateMaterializationReceipt, AgentCandidateModelAccessNetwork, AgentCandidateResolvedModel, @@ -52,6 +52,7 @@ import { } from './digest' import { candidateExecutionOwnerWindowMs } from './execution-window' import { verifyTaskCheckout } from './git-materialize' +import { prepareAgentCandidateKnowledge } from './knowledge' import { sealAgentCandidateModelSettlement, usdToNanos } from './model-settlement' import { createPreparedCandidateExecution } from './prepared-state' import { assertCandidateProfileExecutionSupport } from './profile' @@ -142,7 +143,7 @@ export async function prepareAgentCandidateExecution( let candidateArchive: Uint8Array | undefined let candidateExecutorFiles: - | ReadonlyArray<{ path: string; mode: 0o644 | 0o755; bytes: Uint8Array }> + | ReadonlyArray<{ path: string; mode: number; bytes: Uint8Array }> | undefined if (bundle.execution.workspace) { if (!task.stagingRoots.candidateRoot || !task.executionRoots.candidateRoot) { @@ -227,13 +228,7 @@ export async function prepareAgentCandidateExecution( cleanupTimeoutMs, ) const memory = preparedMemory.value - const knowledge = bundle.knowledge - ? { - snapshotId: bundle.knowledge.snapshotId, - manifestDigest: bundle.knowledge.manifest.sha256, - manifest: await verifiedArtifactBytes(candidate, bundle.knowledge.manifest), - } - : undefined + const knowledge = await prepareAgentCandidateKnowledge(candidate, ports) const baseLaunch = buildLaunch(candidate, task, profileApplication.flags) const publicEnv = mergePublicEnvironment( @@ -249,8 +244,8 @@ export async function prepareAgentCandidateExecution( : {}, ) const routes = modelRoutes(bundle.profile, task.model.requested) - const executionMaterial: AgentCandidateExecutionPlanMaterialV1 = { - schemaVersion: 1, + const executionMaterial: AgentCandidateExecutionPlanMaterial = { + schemaVersion: 2, kind: 'agent-candidate-execution-plan-material', bundleDigest: bundle.digest, executionId: task.executionId, @@ -267,6 +262,7 @@ export async function prepareAgentCandidateExecution( delivery: bundle.execution.instructionDelivery, }, repository: task.repository, + outcome: { kind: 'workspace' }, workspace: task.workspace, }, workspaces: { @@ -298,7 +294,7 @@ export async function prepareAgentCandidateExecution( env: publicEnv, cwd: bundle.execution.cwd, }, - ...(bundle.knowledge ? { knowledgeManifestDigest: bundle.knowledge.manifest.sha256 } : {}), + ...(bundle.knowledge ? { knowledgeManifestDigest: bundle.knowledge.snapshot.digest } : {}), memory, limits: task.limits, network: { mode: 'disabled' }, @@ -311,7 +307,7 @@ export async function prepareAgentCandidateExecution( } const executionPlan: AgentCandidateExecutionPlanEvidence = agentCandidateExecutionPlanEvidenceSchema.parse({ - schemaVersion: 1, + schemaVersion: 2, kind: 'agent-candidate-execution-plan', digest: executionDigest, material: executionMaterial, @@ -321,7 +317,7 @@ export async function prepareAgentCandidateExecution( const entrypoint = candidateEntrypointReceipt(candidate) const materializationReceipt = canonicalCandidateDocument( { - schemaVersion: 1, + schemaVersion: 2, kind: 'agent-candidate-materialization', digestAlgorithm: 'rfc8785-sha256', bundleDigest: bundle.digest, @@ -334,7 +330,7 @@ export async function prepareAgentCandidateExecution( harnessVersion: bundle.execution.harnessVersion, container, resolvedModel, - ...(bundle.knowledge ? { knowledgeManifestDigest: bundle.knowledge.manifest.sha256 } : {}), + ...(bundle.knowledge ? { knowledgeManifestDigest: bundle.knowledge.snapshot.digest } : {}), ...(entrypoint ? { entrypoint } : {}), }, ) @@ -843,8 +839,8 @@ function unwrapPublicEnvironment( function modelRoutes( profile: VerifiedAgentCandidate['bundle']['profile'], requested: string, -): AgentCandidateExecutionPlanMaterialV1['model']['routes'] { - const routes: AgentCandidateExecutionPlanMaterialV1['model']['routes'] = [ +): AgentCandidateExecutionPlanMaterial['model']['routes'] { + const routes: AgentCandidateExecutionPlanMaterial['model']['routes'] = [ { kind: 'primary', requested }, ] if (profile.model?.small) routes.push({ kind: 'small', requested }) @@ -943,7 +939,7 @@ function modelLimits(limits: AgentCandidateExecutionLimits): { function exactProfileExecutorFiles( sourceFiles: ReadonlyArray<{ relPath: string; content: string; mode?: number }>, expectedFiles: ReadonlyArray<{ relPath: string; mode: number; contentSha256: string }>, -): Array<{ path: string; mode: 0o644 | 0o755; bytes: Uint8Array }> { +): Array<{ path: string; mode: number; bytes: Uint8Array }> { const byPath = new Map(sourceFiles.map((file) => [file.relPath, file])) if (byPath.size !== sourceFiles.length || sourceFiles.length !== expectedFiles.length) { throw new Error('profile source files do not match the signed profile plan') @@ -954,7 +950,9 @@ function exactProfileExecutorFiles( const bytes = Buffer.from(source?.content ?? '', 'utf8') if ( !source || - (mode !== 0o644 && mode !== 0o755) || + !Number.isInteger(mode) || + mode < 0 || + mode > 0o777 || mode !== expected.mode || sha256Bytes(bytes) !== expected.contentSha256 ) { diff --git a/src/candidate-execution/prepared-state.ts b/src/candidate-execution/prepared-state.ts index 87522785..97b1f033 100644 --- a/src/candidate-execution/prepared-state.ts +++ b/src/candidate-execution/prepared-state.ts @@ -22,6 +22,7 @@ import type { PreparedAgentCandidateExecution, } from './types' import { CANDIDATE_TRACE_ENV, CANDIDATE_TRACE_TAGS, preparedCandidateBrand } from './types' +import { workspaceTaskRepository } from './workspace-task' export interface PreparedCandidateState { ports: AgentCandidateExecutionPorts @@ -42,17 +43,17 @@ export interface PreparedCandidateState { executorInputs: { taskFiles: ReadonlyArray<{ path: string - mode: 0o644 | 0o755 + mode: number bytes: Uint8Array }> candidateFiles?: ReadonlyArray<{ path: string - mode: 0o644 | 0o755 + mode: number bytes: Uint8Array }> profileFiles: ReadonlyArray<{ path: string - mode: 0o644 | 0o755 + mode: number bytes: Uint8Array }> } @@ -225,7 +226,7 @@ export async function assertPreparedCandidateWorkspaces( await verifyMaterializedWorkspace(state.roots.staging.taskRoot, plan.task.workspace.material, { ignoredProtectedRootEntries: ['.git', '.sidecar'], }) - await verifyTaskCheckout(state.roots.staging.taskRoot, plan.task.repository) + await verifyTaskCheckout(state.roots.staging.taskRoot, workspaceTaskRepository(plan.task)) await verifyMaterializedProfileWorkspace( state.roots.staging.profileRoot, state.profilePlan.value.material, @@ -298,9 +299,12 @@ function detachPreparedCandidateState(input: PreparedCandidateState): PreparedCa ...(input.knowledge ? { knowledge: Object.freeze({ - snapshotId: input.knowledge.snapshotId, - manifestDigest: input.knowledge.manifestDigest, - manifest: Uint8Array.from(input.knowledge.manifest), + candidate: immutableCandidateValue(input.knowledge.candidate), + snapshot: immutableCandidateValue(input.knowledge.snapshot), + files: immutableExecutorFiles(input.knowledge.files), + ...(input.knowledge.retrievalConfig + ? { retrievalConfig: Uint8Array.from(input.knowledge.retrievalConfig) } + : {}), }), } : {}), @@ -358,6 +362,7 @@ function assertPrivateCandidateIntegrity(state: PreparedCandidateState): void { throw new Error('prepared model access no longer matches the signed execution plan') } assertExecutorInputs(state) + assertPreparedKnowledge(state) if ( (state.memory.mode === 'isolated' && !state.memoryReservation) || (state.memory.mode === 'disabled' && state.memoryReservation) @@ -444,13 +449,20 @@ function bytesView(value: T, key: 'bytes'): T { function knowledgeView( knowledge: NonNullable, ): NonNullable { - const manifest = Uint8Array.from(knowledge.manifest) + const retrievalConfig = knowledge.retrievalConfig + ? Uint8Array.from(knowledge.retrievalConfig) + : undefined return Object.freeze({ - snapshotId: knowledge.snapshotId, - manifestDigest: knowledge.manifestDigest, - get manifest(): Uint8Array { - return Uint8Array.from(manifest) - }, + candidate: knowledge.candidate, + snapshot: knowledge.snapshot, + files: Object.freeze(knowledge.files.map((file) => profileFileView(file))), + ...(retrievalConfig + ? { + get retrievalConfig(): Uint8Array { + return Uint8Array.from(retrievalConfig) + }, + } + : {}), }) } @@ -511,6 +523,36 @@ function assertExecutorInputs(state: PreparedCandidateState): void { } } +function assertPreparedKnowledge(state: PreparedCandidateState): void { + const expected = state.bundle.knowledge + const actual = state.knowledge + if (!expected || !actual) { + if (expected || actual) + throw new Error('prepared knowledge does not match the candidate bundle') + return + } + if ( + canonicalCandidateDigest(actual.candidate) !== canonicalCandidateDigest(expected.candidate) || + canonicalCandidateDigest(actual.snapshot) !== canonicalCandidateDigest(expected.snapshot) || + state.executionPlan.value.material.knowledgeManifestDigest !== expected.snapshot.digest + ) { + throw new Error('prepared knowledge identity does not match the candidate bundle') + } + assertWorkspaceExecutorFiles(actual.files, expected.snapshot.material) + if (!expected.retrievalConfig || !actual.retrievalConfig) { + if (expected.retrievalConfig || actual.retrievalConfig) { + throw new Error('prepared knowledge retrieval config does not match the candidate bundle') + } + return + } + if ( + actual.retrievalConfig.byteLength !== expected.retrievalConfig.byteLength || + sha256Bytes(actual.retrievalConfig) !== expected.retrievalConfig.sha256 + ) { + throw new Error('prepared knowledge retrieval config does not match the candidate bundle') + } +} + function assertWorkspaceExecutorFiles( actualFiles: PreparedCandidateState['executorInputs']['taskFiles'], expected: PreparedAgentCandidateExecution['executionPlan']['value']['material']['task']['workspace']['material'], @@ -536,7 +578,7 @@ function assertWorkspaceExecutorFiles( function immutableExecutorFiles( files: PreparedCandidateState['executorInputs']['taskFiles'], -): ReadonlyArray<{ path: string; mode: 0o644 | 0o755; bytes: Uint8Array }> { +): ReadonlyArray<{ path: string; mode: number; bytes: Uint8Array }> { return Object.freeze( files.map((file) => Object.freeze({ ...file, bytes: Uint8Array.from(file.bytes) })), ) diff --git a/src/candidate-execution/types.ts b/src/candidate-execution/types.ts index 097bc62b..f293a41b 100644 --- a/src/candidate-execution/types.ts +++ b/src/candidate-execution/types.ts @@ -10,17 +10,18 @@ import type { AgentCandidateExecutionPlanEvidence, AgentCandidateGitHubRepository, AgentCandidateInstructionDelivery, + AgentCandidateKnowledgeRef, AgentCandidateMaterializationReceipt, AgentCandidateMemoryReceipt, AgentCandidateModelAccessNetwork, AgentCandidateOciPlatform, AgentCandidateProfilePlanEvidence, AgentCandidateResolvedModel, - AgentCandidateRunReceiptV2, + AgentCandidateRunReceipt, AgentCandidateSpend, AgentCandidateTaskOutcomeEvidence, AgentCandidateTermination, - AgentCandidateWorkspaceManifestMaterialV1, + AgentCandidateWorkspaceManifestMaterial, AgentCandidateWorkspaceSnapshotEvidence, ReasoningEffort, Sha256Digest, @@ -48,6 +49,7 @@ export type AgentCandidateOutputPurpose = | 'benchmark-result' | 'model-settlement' | 'trace' + | 'executor-capture' | 'run-receipt' | 'failure-evidence' @@ -82,7 +84,7 @@ export interface AgentCandidateVerificationPorts { */ export interface AgentCandidateWorkspacePort { materialize(input: { - role: 'task' | 'candidate' | 'memory' + role: 'task' | 'candidate' | 'knowledge' | 'memory' snapshot: AgentCandidateWorkspaceSnapshotEvidence archive: Uint8Array destination: string @@ -320,6 +322,14 @@ export interface PreparedAgentCandidateInstruction { delivery: AgentCandidateInstructionDelivery } +/** Exact file-backed knowledge admitted by the candidate bundle. */ +export interface PreparedAgentCandidateKnowledge { + readonly candidate: AgentCandidateKnowledgeRef + readonly snapshot: AgentCandidateWorkspaceSnapshotEvidence + readonly files: readonly AgentCandidateExecutorWorkspaceFile[] + readonly retrievalConfig?: Uint8Array +} + export interface PreparedAgentCandidateTrace { runId: string tags: Readonly> @@ -353,11 +363,7 @@ export interface PreparedAgentCandidateExecution { readonly launch: PreparedAgentCandidateLaunch readonly instruction: PreparedAgentCandidateInstruction readonly resolvedModel: AgentCandidateResolvedModel - readonly knowledge?: { - snapshotId: string - manifestDigest: Sha256Digest - manifest: Uint8Array - } + readonly knowledge?: PreparedAgentCandidateKnowledge readonly trace: PreparedAgentCandidateTrace readonly memory: AgentCandidateEffectiveMemory readonly [preparedCandidateBrand]: true @@ -373,7 +379,7 @@ export interface AgentCandidateExecutorTaskOutcomeCapture { /** Claimed final tree. The runtime recomputes it independently from `gitDiff`. */ resultTree: string /** Complete evaluator-captured workspace description after candidate execution. */ - afterState: AgentCandidateWorkspaceManifestMaterialV1 + afterState: AgentCandidateWorkspaceManifestMaterial /** Reproducible workspace archive corresponding to `afterState`. */ archive: Uint8Array /** Exact binary patch from the signed task base to `afterState`. */ @@ -382,7 +388,7 @@ export interface AgentCandidateExecutorTaskOutcomeCapture { /** Raw isolated-memory capture made only after access has been revoked. */ export interface AgentCandidateExecutorMemoryCapture { - readonly afterState: AgentCandidateWorkspaceManifestMaterialV1 + readonly afterState: AgentCandidateWorkspaceManifestMaterial readonly archive: Uint8Array } @@ -522,21 +528,22 @@ export interface AgentCandidateExecutorWorkspaceInput { export interface AgentCandidateExecutorWorkspaceFile { readonly path: string - readonly mode: 0o644 | 0o755 + readonly mode: number readonly bytes: Uint8Array } export interface AgentCandidateExecutorProfileFile { readonly path: string - readonly mode: 0o644 | 0o755 + readonly mode: number readonly bytes: Uint8Array } export type AgentCandidateRunFinalization = | { succeeded: true - receipt: CanonicalCandidateDocument + receipt: CanonicalCandidateDocument artifacts: { + executorCapture: AgentCandidateArtifactRef modelSettlement: AgentCandidateArtifactRef taskOutcome: AgentCandidateArtifactRef benchmarkResult: AgentCandidateArtifactRef diff --git a/src/candidate-execution/verify.ts b/src/candidate-execution/verify.ts index befde8e2..03eec2ad 100644 --- a/src/candidate-execution/verify.ts +++ b/src/candidate-execution/verify.ts @@ -87,7 +87,16 @@ export async function verifyAgentCandidateBundle( artifactBytes.set(artifactCacheKey(parsed.execution.workspace.manifest), workspace.manifest) artifactBytes.set(artifactCacheKey(parsed.execution.workspace.archive), workspace.archive) } - if (parsed.knowledge) await readArtifact(parsed.knowledge.manifest) + if (parsed.knowledge) { + const knowledge = await verifyWorkspaceSnapshotArtifacts( + parsed.knowledge.snapshot, + ports.artifacts, + ) + artifactBytes.set(artifactCacheKey(parsed.knowledge.snapshot.manifest), knowledge.manifest) + artifactBytes.set(artifactCacheKey(parsed.knowledge.snapshot.archive), knowledge.archive) + if (parsed.knowledge.retrievalConfig) await readArtifact(parsed.knowledge.retrievalConfig) + await readArtifact(parsed.knowledge.evaluation) + } if (parsed.memory.mode === 'isolated' && parsed.memory.seed) await readArtifact(parsed.memory.seed) diff --git a/src/candidate-execution/workspace-archive.ts b/src/candidate-execution/workspace-archive.ts index 3ca40a71..3f13a3ad 100644 --- a/src/candidate-execution/workspace-archive.ts +++ b/src/candidate-execution/workspace-archive.ts @@ -18,12 +18,16 @@ import { isAnyArrayBuffer, isSharedArrayBuffer } from 'node:util/types' import type { AgentCandidateCapturedArtifact, - AgentCandidateWorkspaceManifestMaterialV1, AgentCandidateWorkspaceSnapshotEvidence, } from '@tangle-network/agent-interface' import { type Entry, extract, type Pack, pack } from 'tar-stream' -import { captureMaterializedWorkspace, verifyBytes, verifyMaterializedWorkspace } from './artifacts' +import { + candidateWorkspaceManifest, + captureMaterializedWorkspace, + verifyBytes, + verifyMaterializedWorkspace, +} from './artifacts' import { canonicalCandidateBytes, canonicalCandidateDigest, @@ -91,7 +95,7 @@ interface WorkspaceArchiveRepositoryMetadataV1 { } interface DecodedWorkspaceArchive { - files: Array<{ path: string; mode: 0o644 | 0o755; bytes: Uint8Array }> + files: Array<{ path: string; mode: number; bytes: Uint8Array }> repository?: WorkspaceArchiveRepositoryV1 } @@ -158,7 +162,7 @@ async function captureWorkspaceFiles( limits: AgentCandidateWorkspaceArchiveLimits, artifactPersistence: CaptureAgentCandidateWorkspaceOptions['artifactPersistence'], ): Promise { - const material = workspaceManifest(files) + const material = candidateWorkspaceManifest(files) const manifest = canonicalCandidateBytes(material) const archive = await encodeWorkspaceArchive(files, repository, limits.maxArchiveBytes) if ( @@ -173,7 +177,7 @@ async function captureWorkspaceFiles( const manifestArtifact = await captureWorkspaceArtifact('manifest', manifest, artifactPersistence) const archiveArtifact = await captureWorkspaceArtifact('archive', archive, artifactPersistence) const snapshot = deepFreezeCandidate({ - schemaVersion: 1, + schemaVersion: 2, kind: 'agent-candidate-workspace-snapshot', digest: canonicalCandidateDigest(material), material, @@ -220,7 +224,7 @@ export function createAgentCandidateWorkspacePort( } async function materializeAgentCandidateWorkspace(input: { - role: 'task' | 'candidate' | 'memory' + role: 'task' | 'candidate' | 'knowledge' | 'memory' snapshot: AgentCandidateWorkspaceSnapshotEvidence archive: Uint8Array destination: string @@ -260,7 +264,7 @@ async function captureRepository( root: string, limits: AgentCandidateWorkspaceArchiveLimits, ): Promise<{ - files: Array<{ path: string; mode: 0o644 | 0o755; bytes: Uint8Array }> + files: Array<{ path: string; mode: number; bytes: Uint8Array }> repository: WorkspaceArchiveRepositoryV1 }> { const stats = await lstat(root) @@ -333,7 +337,7 @@ async function captureRepository( } async function encodeWorkspaceArchive( - files: ReadonlyArray<{ path: string; mode: 0o644 | 0o755; bytes: Uint8Array }>, + files: ReadonlyArray<{ path: string; mode: number; bytes: Uint8Array }>, repository: WorkspaceArchiveRepositoryV1 | undefined, maxArchiveBytes: number, ): Promise { @@ -351,7 +355,7 @@ async function encodeWorkspaceArchive( } async function verifyCanonicalWorkspaceArchive( - files: ReadonlyArray<{ path: string; mode: 0o644 | 0o755; bytes: Uint8Array }>, + files: ReadonlyArray<{ path: string; mode: number; bytes: Uint8Array }>, repository: WorkspaceArchiveRepositoryV1 | undefined, expected: Uint8Array, maxArchiveBytes: number, @@ -376,7 +380,7 @@ async function verifyCanonicalWorkspaceArchive( async function writeWorkspaceArchiveEntries( archive: Pack, - files: ReadonlyArray<{ path: string; mode: 0o644 | 0o755; bytes: Uint8Array }>, + files: ReadonlyArray<{ path: string; mode: number; bytes: Uint8Array }>, repository: WorkspaceArchiveRepositoryV1 | undefined, ): Promise { for (const file of files) { @@ -429,7 +433,7 @@ async function parseWorkspaceArchive( throw new Error('candidate workspace archive has an invalid file count') } const path = safeArchivePath(name.slice(workspaceEntryPrefix.length), limits.maxPathBytes) - if (entry.header.mode !== 0o644 && entry.header.mode !== 0o755) { + if (!isRegularFileMode(entry.header.mode)) { throw new Error(`candidate workspace archive has an unsupported mode: ${path}`) } assertRetainedArchiveSize(bytes.byteLength, retainedEntryBytes, entry.header.size, limits) @@ -572,7 +576,7 @@ function repositoryFromTar( async function writeTarEntry( archive: Pack, name: string, - mode: 0o600 | 0o644 | 0o755, + mode: number, bytes: Uint8Array, ): Promise { await new Promise((resolveEntry, rejectEntry) => { @@ -668,7 +672,7 @@ async function prepareEmptyDestination(destination: string): Promise { async function writeWorkspaceFiles( destination: string, - files: ReadonlyArray<{ path: string; mode: 0o644 | 0o755; bytes: Uint8Array }>, + files: ReadonlyArray<{ path: string; mode: number; bytes: Uint8Array }>, ): Promise { for (const file of files) { const path = workspacePath(destination, file.path) @@ -737,26 +741,11 @@ async function materializeRepository( } } -function workspaceManifest( - files: ReadonlyArray<{ path: string; mode: 0o644 | 0o755; bytes: Uint8Array }>, -): AgentCandidateWorkspaceManifestMaterialV1 { - return { - schemaVersion: 1, - kind: 'agent-candidate-workspace-manifest', - files: files.map((file) => ({ - path: file.path, - mode: file.mode, - sha256: sha256Bytes(file.bytes), - byteLength: file.bytes.byteLength, - })), - } -} - function assertArchiveMatchesSnapshot( - files: ReadonlyArray<{ path: string; mode: 0o644 | 0o755; bytes: Uint8Array }>, + files: ReadonlyArray<{ path: string; mode: number; bytes: Uint8Array }>, snapshot: AgentCandidateWorkspaceSnapshotEvidence, ): void { - const material = workspaceManifest(files) + const material = candidateWorkspaceManifest(files) const materialBytes = canonicalCandidateBytes(material) verifyBytes( materialBytes, @@ -773,7 +762,7 @@ function assertArchiveMatchesSnapshot( } function assertWorkspaceFilesWithinLimits( - files: ReadonlyArray<{ path: string; mode: 0o644 | 0o755; bytes: Uint8Array }>, + files: ReadonlyArray<{ path: string; mode: number; bytes: Uint8Array }>, limits: AgentCandidateWorkspaceArchiveLimits, ): void { if (files.length > limits.maxFiles) { @@ -791,7 +780,7 @@ function assertWorkspaceFilesWithinLimits( 'candidate workspace paths must be unique and sorted', ) previousPath = path - if (file.mode !== 0o644 && file.mode !== 0o755) { + if (!isRegularFileMode(file.mode)) { throw new Error(`candidate workspace file has unsupported mode: ${path}`) } if (file.bytes.byteLength > limits.maxFileBytes) { @@ -833,7 +822,7 @@ function normalizeWorkspaceFiles( const path = safeArchivePath(descriptors.path?.value, limits.maxPathBytes) const mode = descriptors.mode?.value const inputBytes = descriptors.bytes?.value - if (mode !== 0o644 && mode !== 0o755) { + if (!isRegularFileMode(mode)) { throw new Error(`candidate workspace file has unsupported mode: ${path}`) } const view = inspectWorkspaceBytes(inputBytes, path) @@ -854,6 +843,10 @@ function normalizeWorkspaceFiles( return files } +function isRegularFileMode(value: unknown): value is number { + return Number.isInteger(value) && Number(value) >= 0 && Number(value) <= 0o777 +} + function workspaceLimits( overrides: Partial | undefined, ): AgentCandidateWorkspaceArchiveLimits { diff --git a/src/candidate-execution/workspace-snapshot.ts b/src/candidate-execution/workspace-snapshot.ts index cd5ac7f2..19ade3e0 100644 --- a/src/candidate-execution/workspace-snapshot.ts +++ b/src/candidate-execution/workspace-snapshot.ts @@ -1,5 +1,5 @@ import type { - AgentCandidateWorkspaceManifestMaterialV1, + AgentCandidateWorkspaceManifestMaterial, AgentCandidateWorkspaceSnapshotEvidence, } from '@tangle-network/agent-interface' import { @@ -17,7 +17,7 @@ import { persistCandidateOutputArtifact } from './output-artifacts' import type { AgentCandidateOutputArtifactPort } from './types' export interface ProvisionalCandidateWorkspaceSnapshot { - readonly material: AgentCandidateWorkspaceManifestMaterialV1 + readonly material: AgentCandidateWorkspaceManifestMaterial readonly manifestBytes: Uint8Array readonly snapshot: AgentCandidateWorkspaceSnapshotEvidence } @@ -28,7 +28,7 @@ export interface ProvisionalCandidateWorkspaceSnapshot { * provisional value as receipt evidence. */ export function provisionalCandidateWorkspaceSnapshot( - materialInput: AgentCandidateWorkspaceManifestMaterialV1, + materialInput: AgentCandidateWorkspaceManifestMaterial, archive: Uint8Array, ): ProvisionalCandidateWorkspaceSnapshot { const material = immutableCandidateValue( @@ -36,7 +36,7 @@ export function provisionalCandidateWorkspaceSnapshot( ) const manifestBytes = canonicalCandidateBytes(material) const snapshot: AgentCandidateWorkspaceSnapshotEvidence = Object.freeze({ - schemaVersion: 1, + schemaVersion: 2, kind: 'agent-candidate-workspace-snapshot', digest: sha256Bytes(manifestBytes), material, @@ -51,7 +51,7 @@ export async function persistCandidateWorkspaceSnapshot( port: AgentCandidateOutputArtifactPort, input: { executionId: string - material: AgentCandidateWorkspaceManifestMaterialV1 + material: AgentCandidateWorkspaceManifestMaterial archive: Uint8Array purpose: 'task' | 'memory-after' signal?: AbortSignal @@ -76,7 +76,7 @@ export async function persistCandidateWorkspaceSnapshot( ]) return immutableCandidateValue( agentCandidateWorkspaceSnapshotEvidenceSchema.parse({ - schemaVersion: 1, + schemaVersion: 2, kind: 'agent-candidate-workspace-snapshot', digest: sha256Bytes(manifestBytes), material, diff --git a/src/candidate-execution/workspace-task.ts b/src/candidate-execution/workspace-task.ts new file mode 100644 index 00000000..0f378e60 --- /dev/null +++ b/src/candidate-execution/workspace-task.ts @@ -0,0 +1,14 @@ +import type { + AgentCandidateExecutionPlanMaterial, + AgentCandidateTaskRepository, +} from '@tangle-network/agent-interface' + +/** Narrow the runtime's workspace-only task contract after schema validation. */ +export function workspaceTaskRepository( + task: AgentCandidateExecutionPlanMaterial['task'], +): AgentCandidateTaskRepository { + if (task.outcome.kind !== 'workspace' || !task.repository) { + throw new Error('candidate runtime requires a workspace outcome with repository provenance') + } + return task.repository +} diff --git a/tests/candidate-bundle-builder.test.ts b/tests/candidate-bundle-builder.test.ts index 985bc02c..cd55b256 100644 --- a/tests/candidate-bundle-builder.test.ts +++ b/tests/candidate-bundle-builder.test.ts @@ -24,6 +24,7 @@ import { candidateSha, cleanupCandidateFixtures, createCandidateExecutionFixture, + emptyCandidateSnapshot, } from './helpers/candidate-execution-fixture' const temporaryRoots: string[] = [] @@ -71,7 +72,8 @@ describe('public agent candidate bundle builder', () => { }, } const stored = new Map() - const knowledgeManifest = storeArtifact(stored, 'knowledge/manifest.json', '{"version":1}\n') + const knowledgeRetrieval = storeArtifact(stored, 'knowledge/retrieval.json', '{"version":1}\n') + const knowledgeEvaluation = storeArtifact(stored, 'knowledge/evaluation.json', '{"score":1}\n') const memorySeed = storeArtifact(stored, 'memory/seed.json', '{"entries":[]}\n') const input: BuildAgentCandidateBundleInput = { profile: { kind: 'profile-diffs', base, diffs: [diff] }, @@ -81,7 +83,22 @@ describe('public agent candidate bundle builder', () => { repository: { kind: 'github', owner: 'owner', repo: 'repo' }, }, execution: fixture.bundle.execution, - knowledge: { snapshotId: 'knowledge-snapshot-1', manifest: knowledgeManifest }, + knowledge: { + candidate: { + schemaVersion: 1, + kind: 'knowledge-improvement-candidate', + runId: 'knowledge-run-1', + candidateId: 'knowledge-snapshot-1', + goalHash: candidateSha('1'), + baseHash: candidateSha('2'), + candidateHash: candidateSha('3'), + evidenceHash: candidateSha('4'), + promotionPlanHash: candidateSha('5'), + }, + snapshot: emptyCandidateSnapshot('builder-knowledge'), + retrievalConfig: knowledgeRetrieval, + evaluation: knowledgeEvaluation, + }, memory: { mode: 'isolated', scope: 'task', seed: memorySeed }, lineage: { source: 'compound', diff --git a/tests/candidate-execution-core.test.ts b/tests/candidate-execution-core.test.ts index 5b3cb361..a5351e68 100644 --- a/tests/candidate-execution-core.test.ts +++ b/tests/candidate-execution-core.test.ts @@ -13,7 +13,7 @@ import { join } from 'node:path' import type { AgentCandidateGitPatch, - AgentCandidateWorkspaceManifestMaterialV1, + AgentCandidateWorkspaceManifestMaterial, } from '@tangle-network/agent-interface' import { afterEach, describe, expect, it } from 'vitest' @@ -101,8 +101,8 @@ describe('candidate canonical bytes and artifacts', () => { }) it('requires workspace manifest bytes to equal canonical material, not only a locator', async () => { - const material: AgentCandidateWorkspaceManifestMaterialV1 = { - schemaVersion: 1, + const material: AgentCandidateWorkspaceManifestMaterial = { + schemaVersion: 2, kind: 'agent-candidate-workspace-manifest', files: [], } @@ -111,7 +111,7 @@ describe('candidate canonical bytes and artifacts', () => { await expect( verifyWorkspaceSnapshotArtifacts( { - schemaVersion: 1, + schemaVersion: 2, kind: 'agent-candidate-workspace-snapshot', digest: manifest.sha256, material, @@ -124,7 +124,7 @@ describe('candidate canonical bytes and artifacts', () => { await expect( verifyWorkspaceSnapshotArtifacts( { - schemaVersion: 1, + schemaVersion: 2, kind: 'agent-candidate-workspace-snapshot', digest: manifest.sha256, material, @@ -194,15 +194,16 @@ describe('materialized workspace identity', () => { const root = temporaryRoot('candidate-workspace-') mkdirSync(join(root, '.git')) writeFileSync(join(root, '.git', 'ignored'), 'Git internals are not uploaded') - writeFileSync(join(root, 'run.js'), 'ok\n', { mode: 0o755 }) + writeFileSync(join(root, 'run.js'), 'ok\n', { mode: 0o600 }) + chmodSync(join(root, 'run.js'), 0o664) const bytes = Buffer.from('ok\n') - const material: AgentCandidateWorkspaceManifestMaterialV1 = { - schemaVersion: 1, + const material: AgentCandidateWorkspaceManifestMaterial = { + schemaVersion: 2, kind: 'agent-candidate-workspace-manifest', files: [ { path: 'run.js', - mode: 0o755, + mode: 0o664, sha256: embeddedCandidateArtifact(bytes).sha256, byteLength: bytes.byteLength, }, @@ -231,8 +232,8 @@ describe('materialized workspace identity', () => { writeFileSync(join(root, 'source'), 'x') chmodSync(join(root, 'source'), 0o644) symlinkSync('source', join(root, 'symlink')) - const material: AgentCandidateWorkspaceManifestMaterialV1 = { - schemaVersion: 1, + const material: AgentCandidateWorkspaceManifestMaterial = { + schemaVersion: 2, kind: 'agent-candidate-workspace-manifest', files: [], } diff --git a/tests/candidate-execution-execute.test.ts b/tests/candidate-execution-execute.test.ts index 545b5a99..4940f5c4 100644 --- a/tests/candidate-execution-execute.test.ts +++ b/tests/candidate-execution-execute.test.ts @@ -171,9 +171,10 @@ describe('atomic prepared candidate execution', () => { succeeded: true, receipt: { value: { - schemaVersion: 2, - usage: { modelCalls: 0, costUsd: 0 }, - fixedUsage: { modelCalls: 0, costUsdNanos: 0 }, + schemaVersion: 3, + modelSettlement: { + material: { usage: { modelCalls: 0, costUsdNanos: 0 } }, + }, benchmarkResult: { material: { score: 1, @@ -239,7 +240,9 @@ describe('atomic prepared candidate execution', () => { const result = await executePreparedAgentCandidate(prepared, executionOptions) if (!result.succeeded) throw new Error(result.reason) if (!largeArchive) throw new Error('executor did not capture its large task archive') - const afterState = result.receipt.value.taskOutcome.material.afterState + const taskOutcome = result.receipt.value.taskOutcome.material.outcome + if (taskOutcome.kind !== 'workspace') throw new Error('expected workspace task outcome') + const afterState = taskOutcome.afterState const archive = afterState.archive expect(archive).toMatchObject({ byteLength: largeArchive.byteLength, @@ -251,13 +254,21 @@ describe('atomic prepared candidate execution', () => { expect('content' in afterState.manifest).toBe(false) expect(result.receipt.bytes.byteLength).toBeLessThan(100_000) expect(result.receipt.value).toMatchObject({ - usage: { modelCalls: 0, inputTokens: 0, outputTokens: 0, costUsd: 0 }, - fixedUsage: { modelCalls: 0, inputTokens: 0, outputTokens: 0, costUsdNanos: 0 }, + modelSettlement: { + material: { + usage: { modelCalls: 0, inputTokens: 0, outputTokens: 0, costUsdNanos: 0 }, + }, + }, trace: { modelCallCount: 0 }, }) const persistedArchive = await executionOptions.outputArtifacts.read(archive) expect(persistedArchive.byteLength).toBe(largeArchive.byteLength) expect(sha256Bytes(persistedArchive)).toBe(archive.sha256) + const executorCapture = await executionOptions.outputArtifacts.read( + result.artifacts.executorCapture, + ) + expect(executorCapture.byteLength).toBeLessThan(100_000) + expect(Buffer.from(executorCapture).toString('utf8')).not.toContain('content') await expect( executionOptions.outputArtifacts.read(result.artifacts.runReceipt), ).resolves.toEqual(result.receipt.bytes) @@ -321,10 +332,15 @@ describe('atomic prepared candidate execution', () => { ) if (!result.succeeded) throw new Error(result.reason) expect(result.receipt.value).toMatchObject({ - usage: { modelCalls: 1, inputTokens: 10, outputTokens: 5, costUsd: 0.01 }, modelSettlement: { material: { schemaVersion: 2, + usage: { + modelCalls: 1, + inputTokens: 10, + outputTokens: 5, + costUsdNanos: 10_000_000, + }, calls: [ { generationId: 'generation-paid-success', @@ -1500,7 +1516,7 @@ describe('atomic prepared candidate execution', () => { } const memoryBytes = Buffer.from(secret, 'utf8') const afterState = { - schemaVersion: 1 as const, + schemaVersion: 2 as const, kind: 'agent-candidate-workspace-manifest' as const, files: [ { diff --git a/tests/candidate-execution-finalize.test.ts b/tests/candidate-execution-finalize.test.ts index 33707c6b..29b3bf8a 100644 --- a/tests/candidate-execution-finalize.test.ts +++ b/tests/candidate-execution-finalize.test.ts @@ -194,7 +194,7 @@ async function traceStore( } describe('protected candidate run finalization', () => { - it('derives exact V2 evidence and durable trace bytes from tied agent-eval spans', async () => { + it('derives exact V3 evidence and durable trace bytes from tied agent-eval spans', async () => { const execution = await prepared() const store = await traceStore(execution) const outputs = createCandidateOutputFixture() @@ -206,40 +206,31 @@ describe('protected candidate run finalization', () => { ) expect(result.succeeded).toBe(true) if (!result.succeeded) return - expect(result.receipt.value.usage).toEqual({ - costUsd: 0.01, - inputTokens: 10, - outputTokens: 5, - cachedInputTokens: 2, - modelCalls: 1, - }) expect(result.receipt.value.trace).toMatchObject({ eventCount: 3, modelCallCount: 1 }) expect(result.receipt.bytes.byteLength).toBeGreaterThan(0) const task = assertPreparedCandidateIntegrity(execution).executionPlan.value.material.task + if (!task.repository) throw new Error('workspace task repository is missing') expect(result.receipt.value).toMatchObject({ - schemaVersion: 2, - fixedUsage: { - costUsdNanos: 10_000_000, - inputTokens: 10, - outputTokens: 5, - cachedInputTokens: 2, - modelCalls: 1, - }, + schemaVersion: 3, + executorCapture: result.artifacts.executorCapture, taskOutcome: { artifact: result.artifacts.taskOutcome, material: { executionPlanDigest: execution.executionPlan.value.digest, - baseRepository: { - identity: task.repository.identity, - rootIdentity: task.repository.rootIdentity, - commit: task.repository.baseCommit, - tree: task.repository.baseTree, - }, - resultRepository: { - identity: task.repository.identity, - rootIdentity: task.repository.rootIdentity, - commit: expect.stringMatching(/^[0-9a-f]{40}$/), - tree: task.repository.baseTree, + outcome: { + kind: 'workspace', + baseRepository: { + identity: task.repository.identity, + rootIdentity: task.repository.rootIdentity, + commit: task.repository.baseCommit, + tree: task.repository.baseTree, + }, + resultRepository: { + identity: task.repository.identity, + rootIdentity: task.repository.rootIdentity, + commit: expect.stringMatching(/^[0-9a-f]{40}$/), + tree: task.repository.baseTree, + }, }, }, }, @@ -266,13 +257,15 @@ describe('protected candidate run finalization', () => { }, }, }) + const taskOutcome = result.receipt.value.taskOutcome.material.outcome + if (taskOutcome.kind !== 'workspace') throw new Error('expected workspace task outcome') await Promise.all([ expect(outputs.outputArtifacts.read(result.artifacts.runReceipt)).resolves.toEqual( result.receipt.bytes, ), - expect( - outputs.outputArtifacts.read(result.receipt.value.taskOutcome.material.gitDiff.artifact), - ).resolves.toEqual(new Uint8Array()), + expect(outputs.outputArtifacts.read(taskOutcome.gitDiff.artifact)).resolves.toEqual( + new Uint8Array(), + ), expect( outputs.outputArtifacts.read(result.receipt.value.benchmarkResult.material.evidence), ).resolves.toEqual(Uint8Array.from(Buffer.from('{"reward":1}\n', 'utf8'))), @@ -280,6 +273,24 @@ describe('protected candidate run finalization', () => { outputs.outputArtifacts.read(result.receipt.value.benchmarkResult.material.grader.artifact), ).resolves.toEqual(Uint8Array.from(Buffer.from('fixture executable grader', 'utf8'))), ]) + const executorCapture = JSON.parse( + Buffer.from(await outputs.outputArtifacts.read(result.artifacts.executorCapture)).toString( + 'utf8', + ), + ) + expect(executorCapture).toMatchObject({ + schemaVersion: 1, + kind: 'agent-candidate-executor-capture', + executionId: execution.executionId, + executionPlanDigest: execution.executionPlan.value.digest, + termination: { kind: 'exit', exitCode: 0 }, + stopped: true, + taskOutcome: { + digest: result.receipt.value.taskOutcome.digest, + artifact: result.receipt.value.taskOutcome.artifact, + }, + }) + expect(JSON.stringify(executorCapture)).not.toContain('content') }) it('returns invalid capture instead of minting zero usage when provider usage is missing', async () => { @@ -455,7 +466,13 @@ describe('protected candidate run finalization', () => { ) expect(result).toMatchObject({ succeeded: true, - receipt: { value: { usage: { costUsd: 0.3, modelCalls: 2 } } }, + receipt: { + value: { + modelSettlement: { + material: { usage: { costUsdNanos: 300_000_000, modelCalls: 2 } }, + }, + }, + }, }) }) }) diff --git a/tests/candidate-execution-prepare.test.ts b/tests/candidate-execution-prepare.test.ts index c1bf8239..4c54c0f2 100644 --- a/tests/candidate-execution-prepare.test.ts +++ b/tests/candidate-execution-prepare.test.ts @@ -61,10 +61,10 @@ function taskRepository(): { root: string; commit: string; tree: string } { function snapshot( root: string, - files: Array<{ path: string; mode: 0o644 | 0o755 }>, + files: Array<{ path: string; mode: number }>, ): AgentCandidateWorkspaceSnapshotEvidence { const material = { - schemaVersion: 1 as const, + schemaVersion: 2 as const, kind: 'agent-candidate-workspace-manifest' as const, files: files .map((file) => { @@ -83,7 +83,7 @@ function snapshot( } const manifest = embeddedCandidateArtifact(canonicalCandidateBytes(material)) return { - schemaVersion: 1, + schemaVersion: 2, kind: 'agent-candidate-workspace-snapshot', digest: manifest.sha256, material, @@ -97,7 +97,7 @@ function bundle( active?: { commit: string; tree: string; workspace: AgentCandidateWorkspaceSnapshotEvidence }, ): AgentCandidateBundle { const value = { - schemaVersion: 1 as const, + schemaVersion: 2 as const, kind: 'agent-candidate-bundle' as const, digestAlgorithm: 'rfc8785-sha256' as const, profile: { @@ -165,13 +165,13 @@ function redigestBundle( function emptySnapshot(label: string): AgentCandidateWorkspaceSnapshotEvidence { const material = { - schemaVersion: 1 as const, + schemaVersion: 2 as const, kind: 'agent-candidate-workspace-manifest' as const, files: [], } const manifest = embeddedCandidateArtifact(canonicalCandidateBytes(material)) return { - schemaVersion: 1, + schemaVersion: 2, kind: 'agent-candidate-workspace-snapshot', digest: manifest.sha256, material, @@ -328,6 +328,7 @@ describe('candidate execution preparation', () => { delivery: value.bundle.execution.instructionDelivery, }) expect(plan.task.repository).toEqual(value.task.repository) + expect(plan.task.outcome).toEqual({ kind: 'workspace' }) expect(plan.profile).toEqual({ planDigest: prepared.profilePlan.value.digest, targetWorkspace: 'task', @@ -624,18 +625,30 @@ describe('candidate execution preparation', () => { sha256: embeddedCandidateArtifact(seedBytes).sha256, byteLength: seedBytes.byteLength, } - const knowledge = { - locator: { kind: 's3' as const, bucket: 'test-artifacts', key: 'knowledge/manifest.json' }, - sha256: embeddedCandidateArtifact(knowledgeBytes).sha256, - byteLength: knowledgeBytes.byteLength, - } + const knowledgeSnapshot = emptySnapshot('knowledge') + const retrievalConfig = embeddedCandidateArtifact(knowledgeBytes) + const evaluation = embeddedCandidateArtifact(Buffer.from('{"score":1}')) value.bundle = redigestBundle(value.bundle, { memory: { mode: 'isolated', scope: 'task', seed }, - knowledge: { snapshotId: 'knowledge-1', manifest: knowledge }, + knowledge: { + candidate: { + schemaVersion: 1, + kind: 'knowledge-improvement-candidate', + runId: 'knowledge-run-1', + candidateId: 'knowledge-1', + goalHash: sha('1'), + baseHash: sha('2'), + candidateHash: sha('3'), + evidenceHash: sha('4'), + promotionPlanHash: sha('5'), + }, + snapshot: knowledgeSnapshot, + retrievalConfig, + evaluation, + }, }) value.ports.artifacts.read = async (ref) => { if (ref.sha256 === seed.sha256) return seedBytes - if (ref.sha256 === knowledge.sha256) return knowledgeBytes throw new Error(`unexpected artifact ${ref.sha256}`) } let resetInput: Parameters[0] | undefined @@ -664,10 +677,11 @@ describe('candidate execution preparation', () => { }) expect(JSON.stringify(prepared)).not.toContain('TANGLE_MEMORY_NAMESPACE') expect(prepared.knowledge).toMatchObject({ - snapshotId: 'knowledge-1', - manifestDigest: knowledge.sha256, + candidate: { candidateId: 'knowledge-1' }, + snapshot: { digest: knowledgeSnapshot.digest }, + files: [], }) - expect(Buffer.from(prepared.knowledge?.manifest ?? [])).toEqual(knowledgeBytes) + expect(Buffer.from(prepared.knowledge?.retrievalConfig ?? [])).toEqual(knowledgeBytes) }) it('closes memory immediately when reset evidence fails before preparation can retain it', async () => { diff --git a/tests/candidate-execution-task-outcome.test.ts b/tests/candidate-execution-task-outcome.test.ts index 4b907464..2a79e0f3 100644 --- a/tests/candidate-execution-task-outcome.test.ts +++ b/tests/candidate-execution-task-outcome.test.ts @@ -50,7 +50,7 @@ function changedOutcome(root: string, baseTree: string) { const resultTree = git(root, ['write-tree'], undefined, environment) const resultBytes = Buffer.from('export const value = 2\n') const afterState = { - schemaVersion: 1 as const, + schemaVersion: 2 as const, kind: 'agent-candidate-workspace-manifest' as const, files: [ { diff --git a/tests/candidate-execution-workspace-archive.test.ts b/tests/candidate-execution-workspace-archive.test.ts index 0a2fb4de..90012d06 100644 --- a/tests/candidate-execution-workspace-archive.test.ts +++ b/tests/candidate-execution-workspace-archive.test.ts @@ -7,6 +7,7 @@ import { mkdtempSync, readFileSync, rmSync, + statSync, symlinkSync, truncateSync, writeFileSync, @@ -112,7 +113,8 @@ describe('candidate workspace archive', () => { it('restores a non-repository workspace and rejects archive drift', async () => { const source = temporaryRoot('candidate-workspace-files-') - writeFileSync(join(source, 'input.txt'), 'exact bytes', { mode: 0o644 }) + writeFileSync(join(source, 'input.txt'), 'exact bytes', { mode: 0o664 }) + chmodSync(join(source, 'input.txt'), 0o664) const captured = await captureAgentCandidateWorkspace(source) const port = createAgentCandidateWorkspacePort() const destination = join(temporaryRoot('candidate-workspace-parent-'), 'restored') @@ -123,6 +125,7 @@ describe('candidate workspace archive', () => { destination, }) expect(readFileSync(join(destination, 'input.txt'), 'utf8')).toBe('exact bytes') + expect(statSync(join(destination, 'input.txt')).mode & 0o777).toBe(0o664) const tampered = Uint8Array.from(captured.archive) const contentOffset = Buffer.from(tampered).indexOf('exact bytes') diff --git a/tests/helpers/candidate-execution-fixture.ts b/tests/helpers/candidate-execution-fixture.ts index 8f663049..5b77563f 100644 --- a/tests/helpers/candidate-execution-fixture.ts +++ b/tests/helpers/candidate-execution-fixture.ts @@ -65,10 +65,10 @@ function taskRepository(): { root: string; commit: string; tree: string } { function snapshot( root: string, - files: Array<{ path: string; mode: 0o644 | 0o755 }>, + files: Array<{ path: string; mode: number }>, ): AgentCandidateWorkspaceSnapshotEvidence { const material = { - schemaVersion: 1 as const, + schemaVersion: 2 as const, kind: 'agent-candidate-workspace-manifest' as const, files: files .map((file) => { @@ -87,7 +87,7 @@ function snapshot( } const manifest = embeddedCandidateArtifact(canonicalCandidateBytes(material)) return { - schemaVersion: 1, + schemaVersion: 2, kind: 'agent-candidate-workspace-snapshot', digest: manifest.sha256, material, @@ -105,7 +105,7 @@ export function candidateBundle( }, ): AgentCandidateBundle { const value = { - schemaVersion: 1 as const, + schemaVersion: 2 as const, kind: 'agent-candidate-bundle' as const, digestAlgorithm: 'rfc8785-sha256' as const, profile: { @@ -177,13 +177,13 @@ export function redigestCandidateBundle( export function emptyCandidateSnapshot(label: string): AgentCandidateWorkspaceSnapshotEvidence { const material = { - schemaVersion: 1 as const, + schemaVersion: 2 as const, kind: 'agent-candidate-workspace-manifest' as const, files: [], } const manifest = embeddedCandidateArtifact(canonicalCandidateBytes(material)) return { - schemaVersion: 1, + schemaVersion: 2, kind: 'agent-candidate-workspace-snapshot', digest: manifest.sha256, material,