@tangle-network/agent-runtime 0.281.1 → 0.282.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (32) hide show
  1. package/dist/{activation-C1ZAyQrQ.js → activation-Bi_oOB1-.js} +2 -2
  2. package/dist/{activation-C1ZAyQrQ.js.map → activation-Bi_oOB1-.js.map} +1 -1
  3. package/dist/agent.d.ts +1 -1
  4. package/dist/agent.js +1 -1
  5. package/dist/durable.d.ts +1 -1
  6. package/dist/{improvement-cycle-DCTCTmNl.js → improvement-cycle-8MUf5Xfp.js} +8 -1772
  7. package/dist/improvement-cycle-8MUf5Xfp.js.map +1 -0
  8. package/dist/{index-C4ygxavE.d.ts → index-CSyzK6Kd.d.ts} +125 -255
  9. package/dist/index.d.ts +2 -2
  10. package/dist/index.js +5 -5
  11. package/dist/intelligence.js +3 -2
  12. package/dist/intelligence.js.map +1 -1
  13. package/dist/kernel.d.ts +2 -2
  14. package/dist/kernel.js +3 -3
  15. package/dist/{loop-runner-bin-Co2eBFbb.js → loop-runner-bin-Cg78CKmf.js} +2 -2
  16. package/dist/{loop-runner-bin-Co2eBFbb.js.map → loop-runner-bin-Cg78CKmf.js.map} +1 -1
  17. package/dist/{loop-runner-bin-B9dTzFL3.d.ts → loop-runner-bin-Dtt8FdYO.d.ts} +2 -2
  18. package/dist/loop-runner-bin.d.ts +1 -1
  19. package/dist/loop-runner-bin.js +1 -1
  20. package/dist/mcp/index.d.ts +1 -1
  21. package/dist/mcp/index.js +1 -1
  22. package/dist/{runtime-B_yRPBjj.js → runtime-Bid-kBes.js} +676 -675
  23. package/dist/runtime-Bid-kBes.js.map +1 -0
  24. package/dist/{shared-box-CZFdugL1.js → search-method-CbUyhdz5.js} +1799 -16
  25. package/dist/search-method-CbUyhdz5.js.map +1 -0
  26. package/dist/testing.d.ts +1 -1
  27. package/dist/testing.js +9 -9
  28. package/dist/tui/index.d.ts +1 -1
  29. package/package.json +1 -1
  30. package/dist/improvement-cycle-DCTCTmNl.js.map +0 -1
  31. package/dist/runtime-B_yRPBjj.js.map +0 -1
  32. package/dist/shared-box-CZFdugL1.js.map +0 -1
@@ -1,26 +1,23 @@
1
- import { $i as detachedSnapshot, $r as runSettledCommand, Br as createOpenInferenceFileExporter, Cr as linkAbort, Gr as padSpanId, Ia as armDeadlineTimer, K as openSlotGroup, Kr as padTraceId, Ur as generateSpanId, Vr as createOtelExporter, di as terminateProcessTreeAndConfirm, jt as createExecutor, qr as toOtelAttributes, wr as runAbortable } from "./supervisor-UXgaPisu.js";
1
+ import { $i as detachedSnapshot, $r as runSettledCommand, Cr as linkAbort, Ia as armDeadlineTimer, di as terminateProcessTreeAndConfirm, jt as createExecutor, wr as runAbortable } from "./supervisor-UXgaPisu.js";
2
2
  import { i as ConfigError } from "./errors-DodWX-cb.js";
3
- import { F as optimizerMethod, L as collectAgentTurn, R as streamAgentTurn, a as sharedBoxPlacement, f as defaultStructuralRolloutPolicy, i as isTransientSandboxFailure } from "./shared-box-CZFdugL1.js";
3
+ import { D as ROLLOUT_POLICY_EXTENSION, E as isCodeSurface, M as structuralRolloutPolicyFromProfile, S as parseExecutionRef, T as assertCandidateSurfaceKind, b as assertCandidateValidator, lt as collectAgentTurn, n as runSearchImprovement, ot as copyImproveCost, st as optimizerMethod, t as isImproveSearchMethod, ut as streamAgentTurn, w as validateProfileCandidate, x as assertProfileTrainingIsHeldOut, y as prepareProfileImprovement } from "./search-method-CbUyhdz5.js";
4
4
  import { a as concreteProfileModel, t as assertExecutableAgentProfile } from "./model-policy-BbSCSak0.js";
5
5
  import { A as verifyCanonicalCandidateDocument, C as canonicalCandidateDigest$1, D as immutableCandidateValue, O as omitTopLevelDigest, S as canonicalCandidateBytes$1, k as sha256Bytes$1, w as canonicalCandidateDocument } from "./workspace-archive-C9lgf77y.js";
6
6
  import { i as syncDurableDirectory, r as publishExclusiveDurableFile } from "./durable-file-DWQA4ooo.js";
7
7
  import { t as runAnalystLoop } from "./analyst-loop-DZw5QWT9.js";
8
8
  import { c as executePreparedAgentCandidate, o as verifiedResourceTextByDigest, s as verifyAgentCandidateBundle, t as prepareAgentCandidateExecution } from "./prepare-DVlvGP7V.js";
9
9
  import { a as assertCandidateProfileBinding, c as createAgentCandidateProfileActivation, d as omitUndefinedObjectFields, f as parseAgentCandidateProfileActivation, i as applyExactAgentProfileDiff, p as parseExactAgentProfile, r as agentCandidateProfileAsAgentProfile, u as materializeAgentCandidateProfilePlan } from "./profile-D3eXNBQV.js";
10
- import { AGENT_IMPROVEMENT_SOURCE_METADATA_KEY, agentCandidateMaterializationReceiptSchema, agentCandidateRunReceiptSchema, agentImprovementActivationSchema, agentImprovementProposalSchema, agentImprovementReviewSchema, agentImprovementSourceMetadata, agentImprovementSourceSchema, agentProfileDiffSchema, agentProfileEnvironmentSchema, agentProfileImprovementArmSchema, agentProfileImprovementExecutionRefSchema, agentProfileModelHintsSchema, agentProfileSchema, agentProfileTrainingSchema, agentTrainingDatasetIdentitySchema, agentTrainingParametersSchema, agentTrainingReceiptSchema, agentTrainingTaskKey, agentTrainingTaskSchema, applyAgentProfileDiff, candidateExecutionEvidenceSchema, canonicalAgentProfileDigest, canonicalCandidateBytes, changedProfileImprovementSurfaces, defineAgentProfileDiff, diffAgentProfiles, numbersApproximatelyEqual, sha256DigestSchema, snapshotAgentProfile, trainedModelIdForArtifact } from "@tangle-network/agent-interface";
11
- import { CostAccountingIncompleteError, CostCeilingReachedError, CostLedger, canonicalJson, costForTokenPricing, costForUsage, makeProposalFinding } from "@tangle-network/agent-eval";
10
+ import { AGENT_IMPROVEMENT_SOURCE_METADATA_KEY, agentCandidateMaterializationReceiptSchema, agentCandidateRunReceiptSchema, agentImprovementActivationSchema, agentImprovementProposalSchema, agentImprovementReviewSchema, agentImprovementSourceMetadata, agentImprovementSourceSchema, agentProfileDiffSchema, agentProfileEnvironmentSchema, agentProfileImprovementArmSchema, agentProfileImprovementExecutionRefSchema, agentProfileModelHintsSchema, agentProfileSchema, agentProfileTrainingSchema, agentTrainingDatasetIdentitySchema, agentTrainingParametersSchema, agentTrainingReceiptSchema, agentTrainingTaskKey, agentTrainingTaskSchema, candidateExecutionEvidenceSchema, canonicalAgentProfileDigest, canonicalCandidateBytes, changedProfileImprovementSurfaces, defineAgentProfileDiff, numbersApproximatelyEqual, sha256DigestSchema, snapshotAgentProfile, trainedModelIdForArtifact } from "@tangle-network/agent-interface";
11
+ import { CostLedger, makeProposalFinding } from "@tangle-network/agent-eval";
12
12
  import { createHash, randomUUID } from "node:crypto";
13
13
  import { spawn, spawnSync } from "node:child_process";
14
- import { constants, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
14
+ import { constants, existsSync, mkdtempSync, readFileSync, readdirSync, realpathSync, rmSync } from "node:fs";
15
15
  import { basename, dirname, isAbsolute, join, resolve } from "node:path";
16
16
  import { chmod, mkdir, mkdtemp, open, realpath, rm, writeFile } from "node:fs/promises";
17
17
  import { tmpdir } from "node:os";
18
- import { ATTR, branchSpan } from "@tangle-network/agent-trace-contract";
19
- import { redact } from "@tangle-network/agent-eval/traces";
20
18
  import { assertProposalFindings } from "@tangle-network/agent-eval/analyst";
21
- import { SearchRecorder, aide, asha, campaignCellSearchResult, campaignScenarioIdentity, campaignSplitDigestFromIdentities, compareOptimizationMethods, createRunCostLedger, fsCampaignStorage, gitWorktreeAdapter, isProposedCandidate, openSearchLedger, renderSearchSummary, resolveRunDir, runCampaign, runSearch, searchClaimReserveUsd, searchNodeId, searchProposalExecution, searchProposerView, searchReceiptAccounting, verifyCodeSurface, verifySearchHistoryArtifact } from "@tangle-network/agent-eval/campaign";
19
+ import { campaignSplitDigestFromIdentities, compareOptimizationMethods, fsCampaignStorage, gitWorktreeAdapter, verifyCodeSurface, verifySearchHistoryArtifact } from "@tangle-network/agent-eval/campaign";
22
20
  import { measuredComparisonFromAgentProfileImprovementExperiment, measuredComparisonFromCandidateExperiment, runAgentProfileImprovementExperiment, runCandidateExperiment, sealAgentProfileImprovementExperiment, sealAgentProfileImprovementSuite, sealAgentProfileImprovementTask, sealCandidateExperiment, selfImprove, verifyAgentProfileImprovementExperimentComparison, verifyCandidateExperiment, verifyCandidateExperimentComparison } from "@tangle-network/agent-eval/contract";
23
- import { defineEvaluationClaim, summarizeEvaluationUnits } from "@tangle-network/agent-eval/experiment";
24
21
  //#region src/improvement/worktree-tree.ts
25
22
  /**
26
23
  * The exact content of a candidate worktree, as a Git tree object.
@@ -689,15 +686,6 @@ async function rethrowAfterCleanup(cause, cleanup, context) {
689
686
  throw new AggregateError([cause, ...cleanupErrors], `${context}; cleanup failed`);
690
687
  }
691
688
  //#endregion
692
- //#region src/improvement/improve-result.ts
693
- function copyImproveCost(cost) {
694
- return {
695
- totalCostUsd: cost.totalCostUsd,
696
- accountingComplete: cost.accountingComplete,
697
- incompleteReasons: [...cost.incompleteReasons]
698
- };
699
- }
700
- //#endregion
701
689
  //#region src/improvement/improvement-driver.ts
702
690
  /**
703
691
  * Code-only candidate driver for Runtime-owned git worktrees.
@@ -810,334 +798,6 @@ function advanceToIncumbent(worktree, incumbent) {
810
798
  if (head.error || head.status !== 0 || head.stdout.trim() !== incumbent.candidateCommit) throw new Error("improvementDriver: candidate worktree did not reach the incumbent commit");
811
799
  }
812
800
  //#endregion
813
- //#region src/improvement/rollout-policy.ts
814
- /** The profile extensions namespace the policy persists under. */
815
- const ROLLOUT_POLICY_EXTENSION = "structural-rollout";
816
- const isBoundedInt = (v, min) => typeof v === "number" && Number.isInteger(v) && v >= min;
817
- /** Parse a serialized policy surface. Returns `undefined` for non-strings,
818
- * malformed JSON, or values outside the policy invariants. Unknown fields are
819
- * dropped; supported optional fields are preserved. */
820
- function parseRolloutPolicy(surface) {
821
- if (typeof surface !== "string" || surface.trim().length === 0) return void 0;
822
- let raw;
823
- try {
824
- raw = JSON.parse(surface);
825
- } catch {
826
- return;
827
- }
828
- return normalizeRolloutPolicy(raw);
829
- }
830
- /** Normalize an untyped policy bag (a parsed surface or a profile extension) into
831
- * a full `StructuralRolloutPolicy`, defaults merged. Returns `undefined` when any
832
- * present dial violates the policy invariants (mirrors `resolvePolicy`: integer
833
- * k ≥ 1, repairRounds ≥ 0, testgen ≥ 0) — a corrupt config must read as "not
834
- * configured", never as a fabricated recipe. */
835
- function normalizeRolloutPolicy(raw) {
836
- if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return void 0;
837
- const bag = raw;
838
- const k = bag.k ?? defaultStructuralRolloutPolicy.k;
839
- const repairRounds = bag.repairRounds ?? defaultStructuralRolloutPolicy.repairRounds;
840
- const testgen = bag.testgen ?? defaultStructuralRolloutPolicy.testgen;
841
- if (!isBoundedInt(k, 1) || !isBoundedInt(repairRounds, 0) || !isBoundedInt(testgen, 0)) return;
842
- return {
843
- k,
844
- repairRounds,
845
- testgen,
846
- ...typeof bag.diverse === "boolean" ? { diverse: bag.diverse } : {}
847
- };
848
- }
849
- /** Stable serialization with fixed field order. */
850
- function serializeRolloutPolicy(policy) {
851
- return JSON.stringify({
852
- k: policy.k,
853
- repairRounds: policy.repairRounds,
854
- testgen: policy.testgen,
855
- ...policy.diverse !== void 0 ? { diverse: policy.diverse } : {}
856
- });
857
- }
858
- /** Read the persisted policy off the profile. `undefined` when the profile does
859
- * not opt into structural rollout. */
860
- function structuralRolloutPolicyFromProfile(profile) {
861
- const bag = profile.extensions?.[ROLLOUT_POLICY_EXTENSION];
862
- if (bag === void 0) return void 0;
863
- return normalizeRolloutPolicy(bag);
864
- }
865
- /** Persist a detached policy under the profile extension without mutating the input. */
866
- function applyRolloutPolicyToProfile(profile, policy) {
867
- const candidate = structuredClone(profile);
868
- const bag = {
869
- k: policy.k,
870
- repairRounds: policy.repairRounds,
871
- testgen: policy.testgen,
872
- ...policy.diverse !== void 0 ? { diverse: policy.diverse } : {}
873
- };
874
- return {
875
- ...candidate,
876
- extensions: {
877
- ...candidate.extensions,
878
- [ROLLOUT_POLICY_EXTENSION]: bag
879
- }
880
- };
881
- }
882
- //#endregion
883
- //#region src/improvement/profile-surface.ts
884
- /** Extract the baseline optimized by a method and retain its structured value
885
- * so external optimizers can inspect it for private fields before serialization. */
886
- function prepareProfileSurface(profile, surface, skills, profileComponents) {
887
- switch (surface) {
888
- case "prompt": return {
889
- surface: profile.prompt?.systemPrompt ?? "",
890
- value: profile.prompt?.systemPrompt ?? ""
891
- };
892
- case "skills": {
893
- const value = inlineSkill(profile, skills).content;
894
- return {
895
- surface: value,
896
- value
897
- };
898
- }
899
- case "tools": {
900
- const value = profile.tools ?? {};
901
- return {
902
- surface: canonicalJson(value),
903
- value
904
- };
905
- }
906
- case "mcp": {
907
- const value = profile.mcp ?? {};
908
- return {
909
- surface: canonicalJson(value),
910
- value
911
- };
912
- }
913
- case "hooks": {
914
- const value = profile.hooks ?? {};
915
- return {
916
- surface: canonicalJson(value),
917
- value
918
- };
919
- }
920
- case "subagents": {
921
- const value = profile.subagents ?? {};
922
- return {
923
- surface: canonicalJson(value),
924
- value
925
- };
926
- }
927
- case "agent-profile":
928
- if (profileComponents) {
929
- if (profileComponents.encoding !== void 0 && profileComponents.encoding !== "components" && profileComponents.encoding !== "json") throw new ConfigError("improve(): profileComponents.encoding must be components or json");
930
- const value = profileComponents.read(profile);
931
- const components = componentSurface(value, "profileComponents.read");
932
- return {
933
- surface: profileComponents.encoding === "json" ? canonicalJson(components.components) : components,
934
- value
935
- };
936
- }
937
- return {
938
- surface: canonicalJson(profile),
939
- value: profile
940
- };
941
- case "memory": {
942
- const value = profileInstructions(profile);
943
- return {
944
- surface: value,
945
- value
946
- };
947
- }
948
- case "rollout-policy": {
949
- const policy = structuralRolloutPolicyFromProfile(profile);
950
- return {
951
- surface: policy ? serializeRolloutPolicy(policy) : "",
952
- value: policy ?? null
953
- };
954
- }
955
- case "code": throw new ConfigError("improve(): code requires the isolated baseline created from opts.code.repoRoot");
956
- }
957
- }
958
- function isCodeSurface(surface) {
959
- return typeof surface === "object" && surface !== null && surface.kind === "code";
960
- }
961
- function isComponentSurface(surface) {
962
- return typeof surface === "object" && surface !== null && surface.kind === "components";
963
- }
964
- function componentSurface(components, source) {
965
- const entries = validateComponents(components, source);
966
- return immutableCandidateValue({
967
- kind: "components",
968
- components: Object.fromEntries(entries)
969
- });
970
- }
971
- function validateComponents(components, source) {
972
- if (typeof components !== "object" || components === null || Array.isArray(components)) throw new ConfigError(`improve(): ${source} must return a component record`);
973
- const entries = Object.entries(components);
974
- if (entries.length === 0) throw new ConfigError(`improve(): ${source} must return at least one component`);
975
- for (const [name, value] of entries) if (!name || name.trim() !== name || typeof value !== "string") throw new ConfigError(`improve(): ${source} must return trimmed component names with string values`);
976
- return entries;
977
- }
978
- /** Parse a JSON winner surface with a typed, contextual error. */
979
- function parseWinnerJson(winner, surface) {
980
- try {
981
- return JSON.parse(winner);
982
- } catch (cause) {
983
- throw new ConfigError(`improve(): the '${surface}' candidate is not valid JSON, so it cannot form a profile candidate: ${cause.message}`);
984
- }
985
- }
986
- function assertCandidateSurfaceKind(surface, baseline, winner) {
987
- if (surface === "code") {
988
- if (isCodeSurface(winner)) return;
989
- throw new ConfigError(`improve(): the '${surface}' candidate returned an incompatible surface value`);
990
- }
991
- if (typeof baseline === "string") {
992
- if (typeof winner === "string") return;
993
- throw new ConfigError(`improve(): the '${surface}' candidate changed from a text surface to an incompatible surface value`);
994
- }
995
- if (!isComponentSurface(baseline) || !isComponentSurface(winner)) throw new ConfigError(`improve(): the '${surface}' candidate returned an incompatible surface value`);
996
- validateComponents(winner.components, `the '${surface}' candidate`);
997
- const baselineNames = Object.keys(baseline.components).sort();
998
- const winnerNames = Object.keys(winner.components).sort();
999
- if (baselineNames.length !== winnerNames.length || baselineNames.some((name, index) => name !== winnerNames[index])) throw new ConfigError(`improve(): the '${surface}' candidate must preserve the exact component names`);
1000
- }
1001
- /** Materialize a detached profile candidate without changing the baseline. */
1002
- function materializeImprovementProfileCandidate(profile, surface, winner, skills, profileComponents) {
1003
- let candidate;
1004
- if (isComponentSurface(winner)) {
1005
- if (surface !== "agent-profile" || !profileComponents) throw new ConfigError(`improve(): the '${surface}' candidate has no profile component mapping`);
1006
- const winnerComponents = immutableCandidateValue({ ...winner.components });
1007
- const validated = parseMaterializedProfile(profileComponents.apply(profile, winnerComponents), surface);
1008
- const materializedComponents = Object.fromEntries(validateComponents(profileComponents.read(validated), "profileComponents.read after apply"));
1009
- const names = Object.keys(winnerComponents);
1010
- if (names.length !== Object.keys(materializedComponents).length || names.some((name) => materializedComponents[name] !== winnerComponents[name])) throw new ConfigError("improve(): profileComponents.apply must round-trip every winning component exactly");
1011
- return validated;
1012
- }
1013
- if (typeof winner !== "string") throw new ConfigError(`improve(): the '${surface}' candidate cannot form an AgentProfile`);
1014
- switch (surface) {
1015
- case "prompt":
1016
- candidate = {
1017
- ...profile,
1018
- prompt: {
1019
- ...profile.prompt,
1020
- systemPrompt: winner
1021
- }
1022
- };
1023
- break;
1024
- case "skills": {
1025
- const selectedSkill = inlineSkill(profile, skills);
1026
- candidate = {
1027
- ...profile,
1028
- resources: {
1029
- ...profile.resources,
1030
- skills: profile.resources?.skills?.map((resource) => resource === selectedSkill ? {
1031
- ...resource,
1032
- content: winner
1033
- } : resource)
1034
- }
1035
- };
1036
- break;
1037
- }
1038
- case "tools":
1039
- candidate = {
1040
- ...profile,
1041
- tools: parseWinnerJson(winner, surface)
1042
- };
1043
- break;
1044
- case "mcp":
1045
- candidate = {
1046
- ...profile,
1047
- mcp: parseWinnerJson(winner, surface)
1048
- };
1049
- break;
1050
- case "hooks":
1051
- candidate = {
1052
- ...profile,
1053
- hooks: parseWinnerJson(winner, surface)
1054
- };
1055
- break;
1056
- case "subagents":
1057
- candidate = {
1058
- ...profile,
1059
- subagents: parseWinnerJson(winner, surface)
1060
- };
1061
- break;
1062
- case "agent-profile":
1063
- candidate = parseWinnerJson(winner, surface);
1064
- break;
1065
- case "memory":
1066
- candidate = {
1067
- ...profile,
1068
- resources: {
1069
- ...profile.resources,
1070
- instructions: replaceProfileInstructions(profile, winner)
1071
- }
1072
- };
1073
- break;
1074
- case "rollout-policy": {
1075
- const policy = normalizeRolloutPolicy(parseWinnerJson(winner, surface));
1076
- if (!policy) throw new ConfigError(`improve(): the shipped 'rollout-policy' winner is not a valid StructuralRolloutPolicy (integer k >= 1, repairRounds >= 0, testgen >= 0), so it cannot be applied: ${winner}`);
1077
- candidate = applyRolloutPolicyToProfile(profile, policy);
1078
- break;
1079
- }
1080
- }
1081
- return parseMaterializedProfile(candidate, surface);
1082
- }
1083
- function parseMaterializedProfile(candidate, surface) {
1084
- const parsed = agentProfileSchema.safeParse(candidate);
1085
- if (!parsed.success) throw new ConfigError(`improve(): the '${surface}' candidate does not produce a valid AgentProfile: ${parsed.error.message}`);
1086
- return immutableCandidateValue(parsed.data);
1087
- }
1088
- function createProfileCandidateMaterializer(profile, surface, baselineSurface, skills, profileComponents) {
1089
- const decode = (candidate) => {
1090
- if (profileComponents?.encoding !== "json") return candidate;
1091
- if (typeof candidate !== "string") throw new ConfigError("improve(): JSON profile components require a text surface");
1092
- return componentSurface(parseWinnerJson(candidate, surface), "JSON profile components");
1093
- };
1094
- const decodedBaseline = decode(baselineSurface);
1095
- const baselineDigest = canonicalCandidateDigest$1(baselineSurface);
1096
- if (profileComponents) {
1097
- if (canonicalAgentProfileDigest(materializeImprovementProfileCandidate(profile, surface, decodedBaseline, skills, profileComponents)) !== canonicalAgentProfileDigest(profile)) throw new ConfigError("improve(): profileComponents.apply(profile, profileComponents.read(profile)) must reproduce the complete baseline profile exactly");
1098
- }
1099
- const candidates = /* @__PURE__ */ new Map([[baselineDigest, profile]]);
1100
- return (candidateSurface) => {
1101
- assertCandidateSurfaceKind(surface, baselineSurface, candidateSurface);
1102
- const decodedCandidate = decode(candidateSurface);
1103
- assertCandidateSurfaceKind(surface, decodedBaseline, decodedCandidate);
1104
- const digest = canonicalCandidateDigest$1(candidateSurface);
1105
- const existing = candidates.get(digest);
1106
- if (existing) return existing;
1107
- const candidate = materializeImprovementProfileCandidate(profile, surface, immutableCandidateValue(decodedCandidate), skills, profileComponents);
1108
- candidates.set(digest, candidate);
1109
- return candidate;
1110
- };
1111
- }
1112
- function inlineSkill(profile, options) {
1113
- const resourceName = options?.resourceName.trim();
1114
- if (!resourceName) throw new ConfigError("improve(): surface 'skills' requires opts.skills.resourceName for one inline profile skill");
1115
- assertFailClosedResources(profile, "skills");
1116
- const matches = (profile.resources?.skills ?? []).filter((resource) => resource.name === resourceName);
1117
- if (matches.length !== 1 || matches[0]?.kind !== "inline") throw new ConfigError(`improve(): skill '${resourceName}' must identify exactly one inline profile resource`);
1118
- return matches[0];
1119
- }
1120
- function profileInstructions(profile) {
1121
- assertFailClosedResources(profile, "memory");
1122
- const instructions = profile.resources?.instructions;
1123
- if (instructions === void 0) return "";
1124
- if (typeof instructions === "string") return instructions;
1125
- if (instructions.kind === "inline") return instructions.content;
1126
- throw new ConfigError("improve(): surface 'memory' requires inline profile instructions so candidate bytes are exact");
1127
- }
1128
- function replaceProfileInstructions(profile, content) {
1129
- const instructions = profile.resources?.instructions;
1130
- if (typeof instructions !== "object") return content;
1131
- if (instructions.kind !== "inline") throw new ConfigError("improve(): surface 'memory' requires inline profile instructions so candidate bytes are exact");
1132
- return {
1133
- ...instructions,
1134
- content
1135
- };
1136
- }
1137
- function assertFailClosedResources(profile, surface) {
1138
- if (profile.resources?.failOnError !== true) throw new ConfigError(`improve(): surface '${surface}' requires profile.resources.failOnError: true`);
1139
- }
1140
- //#endregion
1141
801
  //#region src/improvement/raw-trace-distiller.ts
1142
802
  /**
1143
803
  *
@@ -1682,233 +1342,6 @@ function methodHistoricalReceipts(ledger, optimizerRun, invocationId) {
1682
1342
  return ledger.list({ tags: { optimizerRun } }).filter((receipt) => receipt.tags?.[INVOCATION_TAG] !== invocationId);
1683
1343
  }
1684
1344
  //#endregion
1685
- //#region src/improvement/candidate-validation.ts
1686
- /** One spelling of the execution-identity rule for optimization, training, and the harness. */
1687
- function parseExecutionRef(value, label) {
1688
- const parsed = sha256DigestSchema.safeParse(value);
1689
- if (!parsed.success) throw new ConfigError(`${label}: executionRef must be a lowercase sha256:<64 hex> digest`);
1690
- return parsed.data;
1691
- }
1692
- /** Validate the callback itself before any optimizer, trainer, or candidate work starts. */
1693
- function assertCandidateValidator(validator) {
1694
- if (validator !== void 0 && typeof validator !== "function") throw new ConfigError("validateCandidate must be a function when present");
1695
- }
1696
- /** A validator accepts synchronously by returning void, or rejects by throwing. */
1697
- function validateProfileCandidate(validator, input) {
1698
- assertCandidateValidator(validator);
1699
- const result = validator?.(Object.freeze(input));
1700
- if (result !== void 0) {
1701
- Promise.resolve(result).catch(() => {});
1702
- throw new ConfigError("candidate validators must return void synchronously or throw");
1703
- }
1704
- }
1705
- /**
1706
- * Refuse exact held-out content digests already declared in this profile's training lineage.
1707
- * Both training and trainer-visible validation rows are exposure. This is an exact
1708
- * provenance check, not fuzzy decontamination or proof that undeclared training was fresh.
1709
- */
1710
- function assertProfileTrainingIsHeldOut(profile, heldOutDigests) {
1711
- const training = profile.metadata?.training;
1712
- if (!training) return;
1713
- for (const receipt of [training.receipt, ...training.ancestors]) if (receipt.dataset.tasks.some((task) => heldOutDigests.has(task.contentDigest))) throw new ConfigError("known training exposure overlaps held-out evaluation");
1714
- }
1715
- /**
1716
- * JSON paths of credential and private values in candidate content, found by
1717
- * the redaction core, which names each value it would change. A candidate that
1718
- * leaves Runtime (an external optimizer, a search ledger) is refused on any.
1719
- */
1720
- function privateValuePaths(values) {
1721
- return [...new Set(values.flatMap((value) => redact(value).report.findings.map((finding) => jsonPathOf(finding.path))))];
1722
- }
1723
- /** `/remote/url` or `/tools/0/env` as `$.remote.url` or `$.tools[0].env`. */
1724
- function jsonPathOf(pointer) {
1725
- return pointer.split("/").slice(1).map((segment) => segment.replaceAll("~1", "/").replaceAll("~0", "~")).reduce((path, segment) => /^\d+$/.test(segment) ? `${path}[${segment}]` : `${path}.${segment}`, "$");
1726
- }
1727
- //#endregion
1728
- //#region src/improvement/method-identity.ts
1729
- function buildMethodEvaluationIdentity(input) {
1730
- const optimizationReps = input.optimizationRunOptions?.reps ?? 1;
1731
- const finalTestReps = input.reps ?? 1;
1732
- const scenarioPartitions = immutableCandidateValue({
1733
- train: input.trainScenarios.map(campaignScenarioIdentity),
1734
- selection: input.selectionScenarios.map(campaignScenarioIdentity),
1735
- finalTest: input.testScenarios.map(campaignScenarioIdentity),
1736
- optimizationReps,
1737
- finalTestReps
1738
- });
1739
- const developmentSplitDigest = canonicalCandidateDigest$1({
1740
- train: campaignSplitDigestFromIdentities(scenarioPartitions.train, optimizationReps),
1741
- selection: campaignSplitDigestFromIdentities(scenarioPartitions.selection, optimizationReps)
1742
- });
1743
- const finalTestSplitDigest = campaignSplitDigestFromIdentities(scenarioPartitions.finalTest, finalTestReps);
1744
- const judgeDescriptors = input.judges.map(judgeDescriptor);
1745
- return {
1746
- evaluationRef: canonicalCandidateDigest$1({
1747
- executionRef: input.executionRef,
1748
- baselineProfileDigest: input.baselineProfileDigest,
1749
- coordinate: profileCoordinate(input.surface, input.baselineSurface, input.skills),
1750
- candidateValidation: input.validateCandidate ? Function.prototype.toString.call(input.validateCandidate) : null,
1751
- developmentSplitDigest,
1752
- finalTestSplitDigest,
1753
- findings: input.findings,
1754
- judges: judgeDescriptors,
1755
- run: {
1756
- seed: input.seed ?? 42,
1757
- finalReps: input.reps ?? 1,
1758
- optimizationReps,
1759
- costCeiling: input.costCeiling ?? null,
1760
- resumable: input.optimizationRunOptions?.resumable ?? true,
1761
- maxConcurrency: input.optimizationRunOptions?.maxConcurrency ?? 2,
1762
- abortOnCellError: input.optimizationRunOptions?.abortOnCellError ?? false,
1763
- dispatchTimeoutMs: input.optimizationRunOptions?.dispatchTimeoutMs ?? null,
1764
- dispatchShutdownTimeoutMs: input.optimizationRunOptions?.dispatchShutdownTimeoutMs ?? 5e3,
1765
- tracing: input.optimizationRunOptions?.tracing ?? "on",
1766
- expectUsage: input.optimizationRunOptions?.expectUsage ?? "warn",
1767
- captureSource: input.optimizationRunOptions?.captureSource ?? null,
1768
- captureSourceVersionHash: input.optimizationRunOptions?.captureSourceVersionHash ?? null
1769
- }
1770
- }),
1771
- developmentSplitDigest,
1772
- finalTestSplitDigest,
1773
- scenarioPartitions,
1774
- judgeDescriptors
1775
- };
1776
- }
1777
- function profileCoordinate(surface, baselineSurface, skills) {
1778
- return {
1779
- surface,
1780
- resourceName: surface === "skills" ? skills?.resourceName.trim() ?? null : null,
1781
- componentNames: typeof baselineSurface === "object" && baselineSurface !== null && baselineSurface.kind === "components" ? Object.keys(baselineSurface.components).sort() : []
1782
- };
1783
- }
1784
- function judgeDescriptor(judge) {
1785
- return {
1786
- name: judge.name,
1787
- dimensions: judge.dimensions.map((dimension) => ({ ...dimension })),
1788
- declaredVersion: judge.judgeVersion ?? null,
1789
- scoreImplementation: Function.prototype.toString.call(judge.score),
1790
- appliesToImplementation: judge.appliesTo ? Function.prototype.toString.call(judge.appliesTo) : null
1791
- };
1792
- }
1793
- //#endregion
1794
- //#region src/improvement/profile-improvement.ts
1795
- /**
1796
- * What every profile improvement prepares before any optimizer or search runs:
1797
- * the exact surface and its baseline, the evaluation identity, identified
1798
- * judges, the identities a search ledger records, and one materializer that
1799
- * admits a candidate only after the held-out and caller checks. `improve()`
1800
- * with an external method and with `searchMethod` share it, so a candidate is
1801
- * materialized and admitted the same way on both paths.
1802
- */
1803
- function prepareProfileImprovement(profile, input) {
1804
- const { surface = "prompt", validateCandidate, skills, profileComponents, minimumLift = 0 } = input;
1805
- assertCandidateValidator(validateCandidate);
1806
- if (!Number.isFinite(minimumLift) || minimumLift < 0) throw new ConfigError("improve(): minimumLift must be a finite number greater than or equal to 0");
1807
- if (profileComponents && surface !== "agent-profile") throw new ConfigError("improve(): profileComponents is valid only with surface 'agent-profile'");
1808
- if (input.subject !== void 0 && (typeof input.subject !== "string" || !input.subject.trim() || input.subject !== input.subject.trim())) throw new ConfigError("improve(): subject must be a trimmed non-empty string");
1809
- const executionRef = parseExecutionRef(input.executionRef, "improve()");
1810
- const findings = immutableCandidateValue([...assertProposalFindings(input.findings ?? [], "improve() method findings")]);
1811
- const preparedSurface = prepareProfileSurface(profile, surface, skills, profileComponents);
1812
- const baselineSurface = preparedSurface.surface;
1813
- const baselineValue = immutableCandidateValue(preparedSurface.value);
1814
- const baselineProfileDigest = canonicalAgentProfileDigest(profile);
1815
- const identity = buildMethodEvaluationIdentity({
1816
- executionRef,
1817
- baselineProfileDigest,
1818
- baselineSurface,
1819
- surface,
1820
- skills,
1821
- validateCandidate,
1822
- findings,
1823
- trainScenarios: input.trainScenarios,
1824
- selectionScenarios: input.selectionScenarios,
1825
- testScenarios: input.testScenarios,
1826
- judges: input.judges,
1827
- seed: input.seed,
1828
- reps: input.reps,
1829
- costCeiling: input.costCeiling,
1830
- optimizationRunOptions: input.optimizationRunOptions
1831
- });
1832
- const judges = input.judges.map((judge, index) => Object.freeze({
1833
- ...judge,
1834
- judgeVersion: canonicalCandidateDigest$1({
1835
- evaluationRef: identity.evaluationRef,
1836
- descriptor: identity.judgeDescriptors[index]
1837
- })
1838
- }));
1839
- const rawMaterializeProfile = createProfileCandidateMaterializer(profile, surface, baselineSurface, skills, profileComponents);
1840
- const baselineSurfaceDigest = canonicalCandidateDigest$1(baselineSurface);
1841
- const heldOutDigests = new Set(identity.scenarioPartitions.finalTest.map((task) => task.scenarioDigest));
1842
- const validatedCandidates = /* @__PURE__ */ new Set();
1843
- const validateMaterialized = (validator, candidate, candidateSurface, isBaseline) => {
1844
- const prepared = prepareProfileSurface(candidate, surface, skills, profileComponents);
1845
- validateProfileCandidate(validator, {
1846
- profile: candidate,
1847
- surface,
1848
- candidateSurface,
1849
- value: immutableCandidateValue(prepared.value),
1850
- isBaseline
1851
- });
1852
- };
1853
- const admitCandidate = (candidate, candidateSurface) => {
1854
- const candidateDigest = canonicalCandidateDigest$1(candidateSurface);
1855
- if (validatedCandidates.has(candidateDigest)) return;
1856
- assertProfileTrainingIsHeldOut(candidate, heldOutDigests);
1857
- validateMaterialized(validateCandidate, candidate, immutableCandidateValue(candidateSurface), candidateDigest === baselineSurfaceDigest);
1858
- validatedCandidates.add(candidateDigest);
1859
- };
1860
- const materializeProfile = (candidateSurface) => {
1861
- const candidate = rawMaterializeProfile(candidateSurface);
1862
- admitCandidate(candidate, candidateSurface);
1863
- return candidate;
1864
- };
1865
- materializeProfile(baselineSurface);
1866
- return {
1867
- profile,
1868
- surface,
1869
- executionRef,
1870
- findings,
1871
- minimumLift,
1872
- baselineSurface,
1873
- baselineValue,
1874
- baselineProfileDigest,
1875
- identity,
1876
- invocationId: `runtime-optimization:${randomUUID()}`,
1877
- judges,
1878
- searchIdentity: Object.freeze({
1879
- subject: input.subject ?? profile.name ?? "agent-profile",
1880
- agent: {
1881
- uri: "agent-runtime:improve-execution-ref",
1882
- revision: executionRef
1883
- },
1884
- judge: {
1885
- uri: "agent-runtime:improve-judges",
1886
- revision: canonicalCandidateDigest$1(identity.judgeDescriptors)
1887
- },
1888
- model: profileModel(profile)
1889
- }),
1890
- surfaceOf: (candidate) => prepareProfileSurface(candidate, surface, skills, profileComponents).surface,
1891
- materializeCandidate: rawMaterializeProfile,
1892
- admitCandidate,
1893
- materializeProfile,
1894
- validateMaterialized
1895
- };
1896
- }
1897
- /** The profile's model hint as a moving alias; each cell records what it resolved. */
1898
- function profileModel(profile) {
1899
- const hint = profile.model?.default;
1900
- if (!hint) return {
1901
- provider: "unspecified",
1902
- alias: "unspecified",
1903
- unknown: "the profile names no model; each cell records the model it resolved"
1904
- };
1905
- return {
1906
- provider: profile.model?.provider ?? "unspecified",
1907
- alias: hint,
1908
- unknown: "the profile names a model hint, not a snapshot; each cell records the model it resolved"
1909
- };
1910
- }
1911
- //#endregion
1912
1345
  //#region src/improvement/method-execution.ts
1913
1346
  function resolveOptimizationMethod(source, context) {
1914
1347
  const method = typeof source === "function" ? source(context) : source;
@@ -2045,1203 +1478,6 @@ async function runMethodImprovement(profile, opts) {
2045
1478
  };
2046
1479
  }
2047
1480
  //#endregion
2048
- //#region src/improvement/search-executor.ts
2049
- /**
2050
- * The search kernel's executor port for cells Runtime runs.
2051
- *
2052
- * A lane is a pool of execution slots with one cost rule: a shared box, dedicated
2053
- * environments, subscription seats, or the router. The kernel places each cell on a lane and
2054
- * bounds each lane's running cells by its capacity. This executor adds what one search cannot
2055
- * see or enforce on its own:
2056
- *
2057
- * - Fleet slots. A `WorkerSlots` allocator shared by concurrent searches bounds working cells
2058
- * across all of them. A cell waits for a slot, and the wait is its `queueMs`.
2059
- * - Fleet dollars. On a hard lane a cell holds its enforced maximum as a `BudgetPool` ticket
2060
- * before it starts, waits while open tickets could return enough, and settles the ticket
2061
- * with its measured spend. Estimate lanes take no ticket: they cannot bound a cell, and an
2062
- * unknown cost would close a capped pool for every search that shares it.
2063
- * - Hard caps. On a hard lane every paid call of the cell, the agent's and the judges', holds
2064
- * its maximum against the lane's `cellUsd` and is refused when it would pass it, so the
2065
- * kernel's hard reservation is a bound and not a hope.
2066
- * - Adoption. A finished attempt is written under its run id before the kernel sees it, so a
2067
- * kernel that restarts adopts the attempt instead of running it again. The run id is stable
2068
- * across restarts; an agent that runs remote work keys it by `ctx.search.runId`, so a lost
2069
- * response is fetched again rather than executed again.
2070
- * - Accounting. Every paid call is tagged with its search and attempt, and an attempt's cost is
2071
- * every call tagged with its run id, including calls a process that ended made for it. A
2072
- * reopened search settles those interrupted calls first: from the provider through the lane's
2073
- * `recoverReceipt`, else with an unknown cost, never as free.
2074
- * - Environment faults. A `SearchEnvironmentFault`, or a platform failure a repeated request
2075
- * can change, settles `errored` and retryable, and the kernel runs a fresh attempt.
2076
- * - Traces. Each attempt is one trace whose root span carries `agent.branch.id` = the node id.
2077
- * The spans the attempt's exporter wrote and dropped go into the cell's `traceRef`.
2078
- */
2079
- function laneReceipts(options) {
2080
- return options.recoverReceipt ? { recoverReceipt: options.recoverReceipt } : {};
2081
- }
2082
- const acceptEveryProfile = () => void 0;
2083
- function laneName(name, fallback) {
2084
- const resolved = name ?? fallback;
2085
- if (!/^[A-Za-z0-9._-]{1,64}$/u.test(resolved)) throw new ConfigError(`search lane name '${resolved}' must be 1-64 of [A-Za-z0-9._-]`);
2086
- return resolved;
2087
- }
2088
- function positiveInteger(value, name) {
2089
- if (!Number.isSafeInteger(value) || value < 1) throw new ConfigError(`${name} must be a positive integer`);
2090
- return value;
2091
- }
2092
- function dollars(value, name) {
2093
- if (!Number.isFinite(value) || value < 0) throw new ConfigError(`${name} must be a finite non-negative number of dollars`);
2094
- return value;
2095
- }
2096
- /**
2097
- * Cells as workers packed into shared Sandbox boxes, `workersPerBox` to a box.
2098
- *
2099
- * Capacity is `boxes × workersPerBox`. The workers of one box share its router key, which caps
2100
- * no single worker, so the lane holds an estimate (`cellUsd` is the prior until 20 cells settle).
2101
- * A profile the placement refuses (a repository writer, a replaced system prompt, MCP servers,
2102
- * hooks, subagents, tool grants) needs another lane. The agent reaches the box through
2103
- * `lane.placement.providerFor({ nodeId: ctx.search.runId })`, which names the attempt to the
2104
- * router on every call.
2105
- */
2106
- function sharedBoxLane(options) {
2107
- const { name, boxes, cellUsd, recoverReceipt, ...placementOptions } = options;
2108
- const placement = sharedBoxPlacement(placementOptions);
2109
- const workersPerBox = placementOptions.workersPerBox ?? 8;
2110
- return Object.freeze({
2111
- name: laneName(name, "shared-box"),
2112
- kind: "shared-box",
2113
- capacity: positiveInteger(boxes, "sharedBoxLane(): boxes") * workersPerBox,
2114
- costCap: "estimate",
2115
- cellUsd: dollars(cellUsd, "sharedBoxLane(): cellUsd"),
2116
- refusal: (profile) => placement.refusal(profile),
2117
- ...laneReceipts({ recoverReceipt }),
2118
- placement
2119
- });
2120
- }
2121
- /**
2122
- * Cells that each run in their own environment, `capacity` at once. The lane cannot bound a
2123
- * cell's dollars, so it holds an estimate: `cellUsd` until 20 cells settle, then 1.5 × the p99
2124
- * of its settled cells.
2125
- */
2126
- function dedicatedLane(options) {
2127
- return Object.freeze({
2128
- name: laneName(options.name, "dedicated"),
2129
- kind: "dedicated",
2130
- capacity: positiveInteger(options.capacity, "dedicatedLane(): capacity"),
2131
- costCap: "estimate",
2132
- cellUsd: dollars(options.cellUsd, "dedicatedLane(): cellUsd"),
2133
- refusal: acceptEveryProfile,
2134
- ...laneReceipts(options)
2135
- });
2136
- }
2137
- /**
2138
- * Cells on subscription seats, one cell a seat. A seat charges no dollar per call, so its own
2139
- * work costs $0 and reports no tokens. `cellUsd` bounds the cell's priced calls, such as its
2140
- * judges; every one of them must declare a maximum, and the lane refuses a call past it.
2141
- */
2142
- function subscriptionLane(options) {
2143
- return Object.freeze({
2144
- name: laneName(options.name, "subscription"),
2145
- kind: "subscription",
2146
- capacity: positiveInteger(options.seats, "subscriptionLane(): seats"),
2147
- costCap: "hard",
2148
- cellUsd: dollars(options.cellUsd ?? 0, "subscriptionLane(): cellUsd"),
2149
- refusal: acceptEveryProfile,
2150
- ...laneReceipts(options)
2151
- });
2152
- }
2153
- /**
2154
- * Cells whose model calls are priced router calls, `capacity` at once. Every paid call of a
2155
- * cell must declare its maximum charge, and the lane refuses a call that would take the cell
2156
- * past `cellUsd`, so `cellUsd` is each cell's hard maximum.
2157
- */
2158
- function routerLane(options) {
2159
- return Object.freeze({
2160
- name: laneName(options.name, "router"),
2161
- kind: "router",
2162
- capacity: positiveInteger(options.capacity, "routerLane(): capacity"),
2163
- costCap: "hard",
2164
- cellUsd: dollars(options.cellUsd, "routerLane(): cellUsd"),
2165
- refusal: acceptEveryProfile,
2166
- ...laneReceipts(options)
2167
- });
2168
- }
2169
- /** Check a lane list: at least one lane, unique names, a hard lane's cap known. */
2170
- function assertSearchLanes(lanes, context) {
2171
- if (!Array.isArray(lanes) || lanes.length === 0) throw new ConfigError(`${context}: lanes needs at least one lane`);
2172
- const names = /* @__PURE__ */ new Set();
2173
- for (const lane of lanes) {
2174
- if (!lane || typeof lane.refusal !== "function" || typeof lane.kind !== "string") throw new ConfigError(`${context}: every lane comes from sharedBoxLane, dedicatedLane, subscriptionLane or routerLane`);
2175
- if (names.has(lane.name)) throw new ConfigError(`${context}: lane '${lane.name}' appears twice`);
2176
- names.add(lane.name);
2177
- }
2178
- }
2179
- /**
2180
- * The environment, not the candidate, ended the attempt: a box that died, a platform that
2181
- * refused the run, a quota. The attempt settles `errored` and retryable, and the kernel runs a
2182
- * fresh attempt up to its `maxAttempts`. Throw anything else for the agent's own failure.
2183
- */
2184
- var SearchEnvironmentFault = class extends Error {
2185
- constructor(message, options) {
2186
- super(message, options);
2187
- this.name = "SearchEnvironmentFault";
2188
- }
2189
- };
2190
- /** Whether an attempt's error is the environment's: a `SearchEnvironmentFault`, or a platform,
2191
- * gateway or network failure that a repeated request can change. */
2192
- function isSearchEnvironmentFault(error) {
2193
- return error instanceof SearchEnvironmentFault || isTransientSandboxFailure(error);
2194
- }
2195
- const USD_TOLERANCE = 1e-9;
2196
- /** The kernel's executor port over Runtime lanes. */
2197
- function searchExecutor(options) {
2198
- assertSearchLanes(options.lanes, "searchExecutor()");
2199
- const lanes = new Map(options.lanes.map((lane) => [lane.name, lane]));
2200
- const placed = new Map(options.lanes.map((lane) => [lane.name, 0]));
2201
- const slots = options.workerSlots ? openSlotGroup(options.workerSlots) : null;
2202
- const attempts = attemptStore(options.storage, join(options.dir, "attempts"));
2203
- const tracing = searchTracing(options);
2204
- const laneOf = (work) => {
2205
- const lane = lanes.get(work.lane);
2206
- if (!lane) throw new Error(`search cell ${work.cellId} was placed on unknown lane '${work.lane}'`);
2207
- return lane;
2208
- };
2209
- return {
2210
- lanes: () => options.lanes,
2211
- place(cell) {
2212
- const profile = options.profileOf(cell.nodeId);
2213
- let chosen;
2214
- for (const lane of options.lanes) {
2215
- if (profile && lane.refusal(profile) !== void 0) continue;
2216
- if (chosen === void 0 || placed.get(lane.name) / lane.capacity < placed.get(chosen.name) / chosen.capacity) chosen = lane;
2217
- }
2218
- if (!chosen) throw new Error(`no search lane can run node ${cell.nodeId}; admission should have refused it`);
2219
- placed.set(chosen.name, placed.get(chosen.name) + 1);
2220
- return chosen.name;
2221
- },
2222
- async adopt(work) {
2223
- return attempts.read(work.runId);
2224
- },
2225
- async run(work) {
2226
- const lane = laneOf(work);
2227
- const queuedAt = Date.now();
2228
- let hold;
2229
- try {
2230
- hold = await holdFleet(lane, work, options.budgetPool, slots);
2231
- } catch (error) {
2232
- if (work.signal.aborted) return interrupted(work, lane, options.identity, error);
2233
- throw error;
2234
- }
2235
- const queueMs = Date.now() - queuedAt;
2236
- const trace = tracing.open(work, lane);
2237
- let result;
2238
- try {
2239
- const context = Object.freeze({
2240
- searchId: work.searchId,
2241
- cellId: work.cellId,
2242
- nodeId: work.nodeId,
2243
- taskId: work.taskId,
2244
- split: work.split,
2245
- stage: work.stage,
2246
- attempt: work.attempt,
2247
- runId: work.runId,
2248
- lane,
2249
- trace: trace.ids
2250
- });
2251
- const tags = searchCallTags(work.searchId, {
2252
- run: work.runId,
2253
- lane: lane.name
2254
- });
2255
- const measured = await options.runAttempt({
2256
- work,
2257
- lane,
2258
- context,
2259
- costLedger: attemptLedger(options.costLedger, lane, tags),
2260
- span: trace.span
2261
- });
2262
- result = {
2263
- ...measured,
2264
- accounting: attemptAccounting(options.costLedger, lane, tags),
2265
- queueMs,
2266
- placement: {
2267
- lane: lane.name,
2268
- boxId: measured.placement?.boxId ?? null
2269
- },
2270
- traceRef: await trace.finish(measured)
2271
- };
2272
- } finally {
2273
- hold.release(result);
2274
- }
2275
- if (!work.signal.aborted) attempts.write(work.runId, result);
2276
- return result;
2277
- }
2278
- };
2279
- }
2280
- function interrupted(work, lane, identity, error) {
2281
- return {
2282
- outcome: {
2283
- status: "errored",
2284
- metrics: {},
2285
- error: {
2286
- code: "interrupted",
2287
- message: `search cell ${work.runId} was interrupted before it ran: ${error instanceof Error ? error.message : String(error)}`,
2288
- retryable: true
2289
- }
2290
- },
2291
- accounting: {
2292
- tokens: {
2293
- status: "known",
2294
- inputTokens: 0,
2295
- outputTokens: 0,
2296
- cachedTokens: 0
2297
- },
2298
- cost: {
2299
- status: "known",
2300
- usd: 0,
2301
- source: "free"
2302
- }
2303
- },
2304
- identity,
2305
- placement: {
2306
- lane: lane.name,
2307
- boxId: null
2308
- },
2309
- traceRef: { unknown: "the attempt never started" }
2310
- };
2311
- }
2312
- /** Take the attempt's fleet dollars, then its fleet slot. A cell waiting for budget holds no
2313
- * slot, so it cannot hold a slot the cells it waits on need. */
2314
- async function holdFleet(lane, work, pool, slots) {
2315
- let ticket;
2316
- if (pool && lane.costCap === "hard" && lane.cellUsd > 0) {
2317
- const reserved = pool.reserve({
2318
- maxUsd: lane.cellUsd,
2319
- maxTokens: 0,
2320
- maxIterations: 0
2321
- }, {
2322
- label: work.runId,
2323
- stage: "admitted"
2324
- }, { wait: true });
2325
- if (!reserved.ok) throw new Error(`the fleet budget pool refused search cell ${work.runId} on lane ${lane.name}: ${reserved.reason}`);
2326
- ticket = reserved.ticket;
2327
- if (reserved.granted) try {
2328
- await abortable(reserved.granted, work.signal);
2329
- } catch (error) {
2330
- pool.reconcile(ticket, noSpend());
2331
- throw error;
2332
- }
2333
- pool.attribute(ticket, {
2334
- label: work.runId,
2335
- stage: "executing"
2336
- });
2337
- }
2338
- const permit = slots?.acquire(0);
2339
- if (permit) try {
2340
- await abortable(permit.ready, work.signal);
2341
- } catch (error) {
2342
- permit.release();
2343
- if (ticket) pool.reconcile(ticket, noSpend());
2344
- throw error;
2345
- }
2346
- return { release(result) {
2347
- permit?.release();
2348
- if (!ticket) return;
2349
- try {
2350
- pool.reconcile(ticket, result ? spendOf(result) : unknownSpend());
2351
- } catch {}
2352
- } };
2353
- }
2354
- function abortable(promise, signal) {
2355
- if (signal.aborted) return Promise.reject(signal.reason ?? /* @__PURE__ */ new Error("search cell aborted"));
2356
- return new Promise((resolve, reject) => {
2357
- const onAbort = () => reject(signal.reason ?? /* @__PURE__ */ new Error("search cell aborted"));
2358
- signal.addEventListener("abort", onAbort, { once: true });
2359
- promise.then((value) => {
2360
- signal.removeEventListener("abort", onAbort);
2361
- resolve(value);
2362
- }, (error) => {
2363
- signal.removeEventListener("abort", onAbort);
2364
- reject(error);
2365
- });
2366
- });
2367
- }
2368
- function noSpend() {
2369
- return {
2370
- iterations: 0,
2371
- tokens: {
2372
- input: 0,
2373
- output: 0
2374
- },
2375
- usd: 0,
2376
- ms: 0
2377
- };
2378
- }
2379
- function unknownSpend() {
2380
- return {
2381
- ...noSpend(),
2382
- usdKnown: false,
2383
- tokensKnown: false
2384
- };
2385
- }
2386
- /** The attempt's spend as the budget pool reads it. Unknown dollars carry their proven floor. */
2387
- function spendOf(result) {
2388
- const { cost, tokens } = result.accounting;
2389
- return {
2390
- iterations: 0,
2391
- tokens: tokens.status === "known" ? {
2392
- input: tokens.inputTokens,
2393
- output: tokens.outputTokens
2394
- } : {
2395
- input: 0,
2396
- output: 0
2397
- },
2398
- ...tokens.status === "known" ? {} : { tokensKnown: false },
2399
- usd: cost.status === "known" ? cost.usd : cost.knownLowerBoundUsd,
2400
- ...cost.status === "known" ? {} : { usdKnown: false },
2401
- ms: result.wallMs ?? 0
2402
- };
2403
- }
2404
- /** The dollar maximum a paid call declares, or null when it declares no priced one. */
2405
- function chargeMaximumUsd(maximum) {
2406
- if (!maximum) return null;
2407
- if ("externallyEnforcedMaximumUsd" in maximum) return maximum.externallyEnforcedMaximumUsd;
2408
- if ("customTokenPricing" in maximum) return costForTokenPricing(maximum.customTokenPricing, maximum);
2409
- const priced = costForUsage(maximum.model, maximum);
2410
- return priced.costUnknown ? null : priced.costUsd;
2411
- }
2412
- const TAG_SEARCH = "searchId";
2413
- const TAG_RUN = "searchRunId";
2414
- const TAG_LANE = "searchLane";
2415
- const TAG_OPERATION = "searchOperation";
2416
- /** The cost-ledger tags of one search's calls: a cell attempt's, or a proposal operation's. */
2417
- function searchCallTags(searchId, of) {
2418
- return "run" in of ? {
2419
- [TAG_SEARCH]: searchId,
2420
- [TAG_RUN]: of.run,
2421
- [TAG_LANE]: of.lane
2422
- } : {
2423
- [TAG_SEARCH]: searchId,
2424
- [TAG_OPERATION]: of.operation
2425
- };
2426
- }
2427
- /** The search ledger with `tags` added to every paid call. */
2428
- function taggedLedger(ledger, tags) {
2429
- return ledgerView(ledger, (input) => ledger.runPaidCall({
2430
- ...input,
2431
- tags: {
2432
- ...input.tags,
2433
- ...tags
2434
- }
2435
- }));
2436
- }
2437
- function ledgerView(ledger, runPaidCall) {
2438
- return new Proxy(ledger, { get(target, property) {
2439
- if (property === "runPaidCall") return runPaidCall;
2440
- const value = Reflect.get(target, property, target);
2441
- return typeof value === "function" ? value.bind(target) : value;
2442
- } });
2443
- }
2444
- /**
2445
- * The search ledger seen by one attempt: every paid call carries the attempt's tags. On a hard
2446
- * lane every call also holds its declared maximum against the lane's `cellUsd` until its
2447
- * receipt replaces the hold with the charge, and a call that would pass the cap, or declares no
2448
- * priced maximum, is refused. A charge the provider left unknown keeps its maximum held.
2449
- */
2450
- function attemptLedger(ledger, lane, tags) {
2451
- const tagged = taggedLedger(ledger, tags);
2452
- if (lane.costCap !== "hard") return tagged;
2453
- let heldUsd = 0;
2454
- const runPaidCall = async (input) => {
2455
- const maximumUsd = chargeMaximumUsd(input.maximumCharge);
2456
- if (maximumUsd === null) return {
2457
- succeeded: false,
2458
- error: new CostAccountingIncompleteError(`lane ${lane.name} caps each cell at $${lane.cellUsd}, so paid call '${input.actor}' during '${input.phase}' needs a priced maximumCharge`)
2459
- };
2460
- if (heldUsd + maximumUsd > lane.cellUsd + USD_TOLERANCE) return {
2461
- succeeded: false,
2462
- error: new CostCeilingReachedError(lane.cellUsd, heldUsd, maximumUsd, input.phase, input.actor)
2463
- };
2464
- heldUsd += maximumUsd;
2465
- const result = await tagged.runPaidCall(input);
2466
- const { receipt } = result;
2467
- if (receipt && !receipt.costUnknown) heldUsd += receipt.costUsd - maximumUsd;
2468
- return result;
2469
- };
2470
- return ledgerView(tagged, runPaidCall);
2471
- }
2472
- /**
2473
- * An attempt's cost is every call tagged with its run id, a call a process that ended made for
2474
- * it included; a call still pending makes the cost unknown with the settled calls as its floor.
2475
- * A subscription seat reports no tokens, and its own work charges no dollar.
2476
- */
2477
- function attemptAccounting(ledger, lane, tags) {
2478
- const receipts = ledger.list({ tags });
2479
- const accounting = searchReceiptAccounting(receipts);
2480
- const pending = ledger.listPending?.({ tags }) ?? [];
2481
- const floorUsd = accounting.cost.status === "known" ? accounting.cost.usd : accounting.cost.knownLowerBoundUsd;
2482
- const cost = pending.length > 0 ? {
2483
- status: "unknown",
2484
- knownLowerBoundUsd: floorUsd,
2485
- reason: `${pending.length} paid call(s) of the attempt had no receipt when it ended`
2486
- } : accounting.cost.status === "known" && accounting.cost.usd > 0 && receipts.some((receipt) => receipt.actualCostUsd === void 0) ? {
2487
- ...accounting.cost,
2488
- source: "pricing-table"
2489
- } : accounting.cost;
2490
- return {
2491
- tokens: lane.kind === "subscription" ? {
2492
- status: "unknown",
2493
- reason: "a subscription seat reports no token usage"
2494
- } : accounting.tokens,
2495
- cost
2496
- };
2497
- }
2498
- /**
2499
- * Settle every paid call of `searchId` that a process which ended left pending, before the
2500
- * reopened search makes a new one: a capped ledger refuses new paid work while one is
2501
- * unresolved. A cell's call is asked of its lane's provider through `recoverReceipt`; any other
2502
- * call, or one the provider cannot answer, settles failed with an unknown cost.
2503
- */
2504
- async function reconcileInterruptedSearchCalls(ledger, searchId, lanes) {
2505
- const interrupted = (ledger.listPending?.({ tags: { [TAG_SEARCH]: searchId } }) ?? []).filter((call) => call.state === "interrupted");
2506
- let recovered = 0;
2507
- for (const call of interrupted) {
2508
- const receipt = await lanes.find((candidate) => candidate.name === call.tags?.[TAG_LANE])?.recoverReceipt?.(call) ?? null;
2509
- if (receipt) {
2510
- ledger.reconcile(call.callId, receipt);
2511
- recovered += 1;
2512
- } else ledger.reconcile(call.callId, {
2513
- model: call.model,
2514
- inputTokens: 0,
2515
- outputTokens: 0,
2516
- costUnknown: true,
2517
- usageUnknown: true
2518
- }, { error: "the process that made this call ended before its receipt" });
2519
- }
2520
- return {
2521
- recovered,
2522
- unknown: interrupted.length - recovered
2523
- };
2524
- }
2525
- /** Finished attempts by run id: the record a restarted kernel adopts. */
2526
- function attemptStore(storage, dir) {
2527
- const pathOf = (runId) => join(dir, `${runId.replace(/[^A-Za-z0-9_-]/gu, ".")}.json`);
2528
- storage.ensureDir(dir);
2529
- return {
2530
- read(runId) {
2531
- const text = storage.read(pathOf(runId));
2532
- if (text === void 0) return null;
2533
- const record = JSON.parse(text);
2534
- if (record.runId !== runId || !record.result) throw new Error(`attempt record ${pathOf(runId)} does not hold run ${runId}`);
2535
- return record.result;
2536
- },
2537
- write(runId, result) {
2538
- const text = `${JSON.stringify({
2539
- runId,
2540
- result
2541
- })}\n`;
2542
- const path = pathOf(runId);
2543
- if (storage.kind !== "filesystem") {
2544
- storage.write(path, text);
2545
- return;
2546
- }
2547
- mkdirSync(dirname(path), { recursive: true });
2548
- const temporary = `${path}.${process.pid}.tmp`;
2549
- writeFileSync(temporary, text);
2550
- renameSync(temporary, path);
2551
- }
2552
- };
2553
- }
2554
- const STATUS_OK = 1;
2555
- const STATUS_ERROR = 2;
2556
- const MAX_ATTRIBUTE_CHARS = 256;
2557
- function searchTracing(options) {
2558
- const mode = options.trace;
2559
- const fileExporter = mode === void 0 && options.storage.kind === "filesystem" ? createOpenInferenceFileExporter(join(options.dir, "spans.otlp.jsonl")) : void 0;
2560
- const off = (reason) => ({
2561
- ids: null,
2562
- span: () => ({
2563
- setAttribute() {},
2564
- end() {}
2565
- }),
2566
- finish: async () => ({ unknown: reason })
2567
- });
2568
- return { open(work, lane) {
2569
- if (mode === "off") return off("tracing is off for this search");
2570
- const exporter = mode === void 0 ? fileExporter : createOtelExporter(mode.otlp);
2571
- if (!exporter) return off(mode === void 0 ? "the search storage is not the filesystem and no OTLP exporter was configured" : "the OTLP exporter has no endpoint");
2572
- return attemptTrace(work, lane, exporter, mode !== void 0);
2573
- } };
2574
- }
2575
- /**
2576
- * One attempt's trace. Its ids derive from the run id, so an attempt run again after a restart
2577
- * writes into the same trace. A shared file exporter writes each span synchronously, so the
2578
- * attempt's written and dropped counts are the change in the exporter's own counts across each
2579
- * of its spans; an attempt's own OTLP exporter is shut down at the end and read whole.
2580
- */
2581
- function attemptTrace(work, lane, exporter, ownsExporter) {
2582
- const traceId = padTraceId(`search-cell:${work.runId}`);
2583
- const rootSpanId = padSpanId(`search-cell:${work.runId}`);
2584
- const startMs = Date.now();
2585
- let written = 0;
2586
- let dropped = 0;
2587
- const exportCounted = (span) => {
2588
- if (ownsExporter) {
2589
- exporter.exportSpan(span);
2590
- return;
2591
- }
2592
- const before = exporter.stats();
2593
- exporter.exportSpan(span);
2594
- const after = exporter.stats();
2595
- written += after.written - before.written;
2596
- dropped += after.dropped - before.dropped;
2597
- };
2598
- return {
2599
- ids: {
2600
- traceId,
2601
- spanId: rootSpanId
2602
- },
2603
- span(name, attributes = {}) {
2604
- const opened = Date.now();
2605
- const record = { ...attributes };
2606
- let ended = false;
2607
- return {
2608
- setAttribute(key, value) {
2609
- record[key] = value;
2610
- },
2611
- end(endAttributes = {}) {
2612
- if (ended) return;
2613
- ended = true;
2614
- exportCounted(otelSpan({
2615
- traceId,
2616
- spanId: generateSpanId(),
2617
- parentSpanId: rootSpanId,
2618
- name,
2619
- startMs: opened,
2620
- endMs: Date.now(),
2621
- attributes: {
2622
- ...record,
2623
- ...endAttributes
2624
- },
2625
- status: STATUS_OK
2626
- }));
2627
- }
2628
- };
2629
- },
2630
- async finish(result) {
2631
- const root = branchSpan({
2632
- traceId,
2633
- spanId: rootSpanId,
2634
- name: "search.cell",
2635
- startTime: new Date(startMs).toISOString(),
2636
- branchId: work.nodeId,
2637
- arm: lane.name,
2638
- attributes: {
2639
- "tangle.search.id": work.searchId,
2640
- "tangle.search.cell_id": work.cellId,
2641
- "tangle.search.run_id": work.runId,
2642
- "tangle.search.task_id": work.taskId,
2643
- "tangle.search.split": work.split,
2644
- "tangle.search.stage": work.stage,
2645
- "tangle.search.attempt": work.attempt,
2646
- "tangle.search.lane": lane.name,
2647
- "tangle.search.lane_kind": lane.kind,
2648
- "tangle.search.outcome": result.outcome.status,
2649
- ..."score" in result.outcome ? { [ATTR.score]: result.outcome.score } : {}
2650
- }
2651
- });
2652
- exportCounted(otelSpan({
2653
- traceId,
2654
- spanId: rootSpanId,
2655
- name: root.name,
2656
- startMs,
2657
- endMs: Date.now(),
2658
- attributes: root.attributes,
2659
- status: result.outcome.status === "errored" ? STATUS_ERROR : STATUS_OK
2660
- }));
2661
- if (ownsExporter) {
2662
- await exporter.shutdown();
2663
- const stats = exporter.stats();
2664
- written = stats.written;
2665
- dropped = stats.dropped;
2666
- }
2667
- return {
2668
- traceId,
2669
- execRunId: null,
2670
- spansWritten: written,
2671
- spansDropped: dropped
2672
- };
2673
- }
2674
- };
2675
- }
2676
- function otelSpan(input) {
2677
- const attributes = {};
2678
- for (const [key, value] of Object.entries(input.attributes)) if (typeof value === "number" || typeof value === "boolean") attributes[key] = value;
2679
- else if (typeof value === "string") attributes[key] = value.slice(0, MAX_ATTRIBUTE_CHARS);
2680
- return {
2681
- traceId: input.traceId,
2682
- spanId: input.spanId,
2683
- ...input.parentSpanId ? { parentSpanId: input.parentSpanId } : {},
2684
- name: input.name,
2685
- kind: 1,
2686
- startTimeUnixNano: (BigInt(Math.floor(input.startMs)) * 1000000n).toString(),
2687
- endTimeUnixNano: (BigInt(Math.floor(Math.max(input.startMs, input.endMs))) * 1000000n).toString(),
2688
- attributes: toOtelAttributes(attributes),
2689
- status: { code: input.status }
2690
- };
2691
- }
2692
- //#endregion
2693
- //#region src/improvement/search-method.ts
2694
- /** Build Runtime's native search for `improve(profile, { method })`. */
2695
- function searchMethod(options) {
2696
- if (!options || typeof options !== "object") throw new ConfigError("searchMethod(): options are required");
2697
- const { proposer } = options;
2698
- if (!proposer || typeof proposer.kind !== "string" || typeof proposer.propose !== "function") throw new ConfigError("searchMethod(): proposer must be a SurfaceProposer");
2699
- const count = (name, value, fallback, min) => {
2700
- const resolved = value ?? fallback;
2701
- if (!Number.isSafeInteger(resolved) || resolved < min) throw new ConfigError(`searchMethod(): ${name} must be an integer of at least ${min}`);
2702
- return resolved;
2703
- };
2704
- const dollars = (name, value) => {
2705
- if (value === void 0) return null;
2706
- if (!Number.isFinite(value) || value < 0) throw new ConfigError(`searchMethod(): ${name} must be a finite non-negative number`);
2707
- return value;
2708
- };
2709
- if (options.deadline !== void 0 && !Number.isFinite(Date.parse(options.deadline))) throw new ConfigError("searchMethod(): deadline must be an ISO time");
2710
- const name = options.name ?? "search";
2711
- if (!name.trim() || name.trim() !== name) throw new ConfigError("searchMethod(): name must be a trimmed non-empty string");
2712
- assertSearchLanes(options.lanes, "searchMethod()");
2713
- return Object.freeze({
2714
- kind: "search",
2715
- name,
2716
- policy: options.policy ?? aide(),
2717
- allocation: options.allocation ?? asha(),
2718
- proposer,
2719
- maxExpansions: count("maxExpansions", options.maxExpansions, NaN, 0),
2720
- childrenPerProposal: count("childrenPerProposal", options.childrenPerProposal, 1, 1),
2721
- lanes: Object.freeze([...options.lanes]),
2722
- claimReserveUsd: dollars("claimReserveUsd", options.claimReserveUsd),
2723
- deadline: options.deadline === void 0 ? null : new Date(options.deadline).toISOString(),
2724
- maxAttempts: count("maxAttempts", options.maxAttempts, 3, 1)
2725
- });
2726
- }
2727
- function isImproveSearchMethod(value) {
2728
- return typeof value === "object" && value !== null && value.kind === "search";
2729
- }
2730
- const SEARCH_METHOD_SOURCE = {
2731
- uri: "npm:@tangle-network/agent-runtime#searchMethod",
2732
- revision: canonicalCandidateDigest$1({
2733
- name: "agent-runtime.search-method.2026-09",
2734
- node: "an exact AgentProfile materialized from the baseline and one surface, content-addressed by canonicalAgentProfileDigest; a surface that does not materialize is a node addressed by its surface and refused",
2735
- edge: "the Interface diffs from the parent profile to the child, stored when they reproduce the child digest",
2736
- admission: "a candidate is refused when it does not materialize, declares training on a test task, fails the caller validator, carries a credential or private value, or no lane can run its profile",
2737
- cell: "a one-cell runCampaign of the materialized profile in a directory addressed by its digest, on a lane that accepts the profile; a cached cell is read back, not run again; a finished attempt is recorded by run id before it settles and adopted after a restart",
2738
- lanes: "a hard lane refuses a paid call that declares no priced maximum or would take the cell past its cellUsd; an environment fault settles errored and retryable; a subscription seat reports no tokens and charges no dollars",
2739
- proposer: "a SurfaceProposer reads the parents, the train view and the train summary; paid calls it makes are its operation accounting",
2740
- ship: "the claim shipped, re-derives from the ledger, cost accounting is complete, and the shipped finalist test lower bound exceeds minimumLift"
2741
- })
2742
- };
2743
- async function runSearchImprovement(profile, opts) {
2744
- const { method, claim: inputClaim, agent, trainScenarios, selectionScenarios, testScenarios, judges: _judges, surface: _surface, executionRef: _executionRef, validateCandidate: _validateCandidate, findings: _findings, skills: _skills, profileComponents: _profileComponents, minimumLift: _minimumLift, subject: _subject, costCeiling, costLedger: inputCostLedger, seed = 42, signal, workerSlots, budgetPool, trace, ...campaignOptions } = opts;
2745
- if (!isImproveSearchMethod(method)) throw new ConfigError("improve(): a search needs method: searchMethod(...)");
2746
- const claim = defineEvaluationClaim(inputClaim);
2747
- if (claim.minimumEffect === void 0) throw new ConfigError("improve(): a search claim needs minimumEffect for its power check");
2748
- for (const [name, split] of [
2749
- ["trainScenarios", trainScenarios],
2750
- ["selectionScenarios", selectionScenarios],
2751
- ["testScenarios", testScenarios]
2752
- ]) if (!Array.isArray(split) || split.length === 0) throw new ConfigError(`improve(): a search needs at least one of ${name}`);
2753
- const { allocation, policy, lanes } = method;
2754
- const reps = allocation.reps;
2755
- const concurrency = lanes.reduce((total, lane) => total + lane.capacity, 0);
2756
- const prepared = prepareProfileImprovement(profile, {
2757
- ...opts,
2758
- seed,
2759
- reps,
2760
- optimizationRunOptions: {
2761
- reps,
2762
- maxConcurrency: concurrency
2763
- }
2764
- });
2765
- const { evaluationRef } = prepared.identity;
2766
- const storage = campaignOptions.storage ?? fsCampaignStorage();
2767
- const runDir = resolveRunDir(campaignOptions.runDir, campaignOptions.repo);
2768
- const searchId = `improve-${canonicalCandidateDigest$1({
2769
- evaluationRef,
2770
- process: SEARCH_METHOD_SOURCE,
2771
- method: searchMethodDescriptor(method)
2772
- }).slice(7, 31)}`;
2773
- const searchDir = `${runDir}/search/${searchId}`;
2774
- const costLedger = inputCostLedger ?? createRunCostLedger({
2775
- storage,
2776
- runDir: searchDir,
2777
- costCeilingUsd: costCeiling
2778
- });
2779
- const unitOf = (scenario) => summarizeEvaluationUnits(claim, [scenario]).units[0].id;
2780
- const tasks = (scenarios) => scenarios.map((scenario) => ({
2781
- taskId: scenario.id,
2782
- unitId: unitOf(scenario),
2783
- source: {
2784
- uri: `scenario://${scenario.id}`,
2785
- revision: canonicalCandidateDigest$1(scenario)
2786
- }
2787
- }));
2788
- const splits = {
2789
- train: tasks(trainScenarios),
2790
- selection: tasks(selectionScenarios),
2791
- test: tasks(testScenarios)
2792
- };
2793
- const developmentUnits = new Set([...splits.train, ...splits.selection].map((task) => task.unitId));
2794
- const execution = {
2795
- model: prepared.searchIdentity.model,
2796
- agent: prepared.searchIdentity.agent,
2797
- benchmark: {
2798
- uri: "agent-runtime:improve-splits",
2799
- revision: canonicalCandidateDigest$1({
2800
- development: prepared.identity.developmentSplitDigest,
2801
- test: prepared.identity.finalTestSplitDigest
2802
- })
2803
- }
2804
- };
2805
- const reservedClaimUsd = Math.max(method.claimReserveUsd ?? 0, searchClaimReserveUsd({
2806
- testTasks: splits.test.length,
2807
- reps,
2808
- cellUsd: Math.max(...lanes.map((lane) => lane.cellUsd))
2809
- }));
2810
- const recorder = await SearchRecorder.open({
2811
- ledger: storage.kind === "filesystem" ? openSearchLedger({
2812
- path: `${searchDir}/ledger.jsonl`,
2813
- searchId
2814
- }) : openSearchLedger({
2815
- path: `${searchDir}/ledger.jsonl`,
2816
- searchId,
2817
- store: storage
2818
- }),
2819
- storage
2820
- }, {
2821
- subject: prepared.searchIdentity.subject,
2822
- process: {
2823
- name: method.name,
2824
- executionRef: SEARCH_METHOD_SOURCE
2825
- },
2826
- artifactKind: "agent-profile",
2827
- objective: {
2828
- metric: "composite",
2829
- direction: "maximize",
2830
- judge: prepared.searchIdentity.judge,
2831
- claim
2832
- },
2833
- splits: {
2834
- ...splits,
2835
- heldOutUnits: splits.test.every((task) => !developmentUnits.has(task.unitId))
2836
- },
2837
- policy: {
2838
- expansion: policy.name,
2839
- allocation: allocation.name,
2840
- seed
2841
- },
2842
- budget: {
2843
- maxUsd: costCeiling ?? null,
2844
- maxCells: null,
2845
- maxNodes: 1 + method.maxExpansions * method.childrenPerProposal,
2846
- deadline: method.deadline,
2847
- maxConcurrency: concurrency,
2848
- reservedClaimUsd: costCeiling === void 0 ? 0 : reservedClaimUsd
2849
- },
2850
- containment: null,
2851
- derivedFrom: null,
2852
- identity: execution
2853
- });
2854
- const nodeOf = (candidateSurface) => {
2855
- const surface = immutableCandidateValue(candidateSurface);
2856
- try {
2857
- return {
2858
- surface,
2859
- profile: prepared.materializeCandidate(surface),
2860
- refusal: null
2861
- };
2862
- } catch (error) {
2863
- return {
2864
- surface,
2865
- profile: null,
2866
- refusal: refusalText(error)
2867
- };
2868
- }
2869
- };
2870
- const profiles = /* @__PURE__ */ new Map();
2871
- const profiled = profileCodec(prepared);
2872
- const codec = {
2873
- node(recorder, node) {
2874
- const registered = profiled.node(recorder, node);
2875
- profiles.set(searchNodeId(searchId, registered.artifactDigest), node.profile);
2876
- return registered;
2877
- },
2878
- diff: profiled.diff,
2879
- load(recorder, node) {
2880
- const loaded = profiled.load(recorder, node);
2881
- profiles.set(node.nodeId, loaded.profile);
2882
- return loaded;
2883
- }
2884
- };
2885
- for (const node of (await recorder.state()).nodes()) codec.load(recorder, node);
2886
- await reconcileInterruptedSearchCalls(costLedger, searchId, lanes);
2887
- const laneRefusal = (nodeProfile) => {
2888
- const refusals = lanes.map((lane) => `${lane.name}: ${lane.refusal(nodeProfile)}`);
2889
- return lanes.some((lane) => lane.refusal(nodeProfile) === void 0) ? null : `no lane can run the profile (${refusals.join("; ")})`;
2890
- };
2891
- const root = nodeOf(prepared.baselineSurface);
2892
- if (root.profile) {
2893
- const refused = laneRefusal(root.profile);
2894
- if (refused) throw new ConfigError(`improve(): the baseline profile cannot run: ${refused}`);
2895
- }
2896
- const scenarios = [
2897
- ...trainScenarios,
2898
- ...selectionScenarios,
2899
- ...testScenarios
2900
- ];
2901
- const scenarioIds = /* @__PURE__ */ new Set();
2902
- for (const scenario of scenarios) {
2903
- if (scenarioIds.has(scenario.id)) throw new ConfigError(`improve(): scenario '${scenario.id}' appears in more than one split`);
2904
- scenarioIds.add(scenario.id);
2905
- }
2906
- const executor = searchExecutor({
2907
- lanes,
2908
- profileOf(nodeId) {
2909
- const known = profiles.get(nodeId);
2910
- if (known === void 0) throw new Error(`improve(): node ${nodeId} was placed unregistered`);
2911
- return known;
2912
- },
2913
- costLedger,
2914
- identity: execution,
2915
- storage,
2916
- dir: searchDir,
2917
- ...workerSlots ? { workerSlots } : {},
2918
- ...budgetPool ? { budgetPool } : {},
2919
- ...trace ? { trace } : {},
2920
- async runAttempt({ work, lane, context, costLedger: cellLedger, span }) {
2921
- const nodeProfile = work.artifact.profile;
2922
- if (!nodeProfile) throw new Error(`improve(): refused node ${work.nodeId} was given a cell`);
2923
- const profileDigest = canonicalAgentProfileDigest(nodeProfile);
2924
- let fault;
2925
- const cell = (await runCampaign({
2926
- ...campaignOptions,
2927
- ...lane.kind === "subscription" && campaignOptions.expectUsage === void 0 ? { expectUsage: "off" } : {},
2928
- scenarios,
2929
- judges: prepared.judges,
2930
- seed,
2931
- reps,
2932
- storage,
2933
- runDir: `${searchDir}/nodes/${profileDigest.slice(7)}`,
2934
- dispatchRef: `improve:${evaluationRef}:${profileDigest}`,
2935
- async dispatch(scenario, ctx) {
2936
- try {
2937
- return await agent(nodeProfile, scenario, {
2938
- ...ctx,
2939
- search: context
2940
- });
2941
- } catch (error) {
2942
- if (isSearchEnvironmentFault(error)) fault = error;
2943
- throw error;
2944
- }
2945
- },
2946
- cellFilter: ({ scenario, rep }) => scenario.id === work.taskId && rep === work.rep,
2947
- resumable: true,
2948
- maxConcurrency: 1,
2949
- costLedger: cellLedger,
2950
- costPhase: `search.${work.stage}`,
2951
- buildTraceWriter: () => ({
2952
- span,
2953
- flush: async () => {}
2954
- }),
2955
- signal: work.signal
2956
- })).cells[0];
2957
- if (!cell) throw new Error(`improve(): cell ${work.cellId} produced no campaign cell`);
2958
- return faultResult(campaignCellSearchResult(cell, {
2959
- execution,
2960
- lane: lane.name
2961
- }), cell.errorStage === "dispatch" ? fault : void 0);
2962
- }
2963
- });
2964
- const { proposer } = method;
2965
- const proposerSource = {
2966
- uri: `proposer:${proposer.kind}`,
2967
- revision: canonicalCandidateDigest$1({
2968
- kind: proposer.kind,
2969
- propose: Function.prototype.toString.call(proposer.propose),
2970
- decide: proposer.decide ? Function.prototype.toString.call(proposer.decide) : null
2971
- })
2972
- };
2973
- const proposalPhase = "search.proposal";
2974
- const port = {
2975
- name: proposer.kind,
2976
- kind: "optimizer",
2977
- source: proposerSource,
2978
- execution: {
2979
- kind: "deterministic",
2980
- source: proposerSource
2981
- },
2982
- childrenPerProposal: method.childrenPerProposal,
2983
- async propose(request) {
2984
- const tags = searchCallTags(searchId, { operation: request.operationId });
2985
- const state = await recorder.state();
2986
- const parents = request.parents.map(({ nodeId, artifact }) => ({
2987
- nodeId,
2988
- artifact: artifact.surface
2989
- }));
2990
- const context = Object.freeze({
2991
- currentSurface: parents[0]?.artifact ?? prepared.baselineSurface,
2992
- operator: request.operator,
2993
- parents,
2994
- train: searchProposerView(state),
2995
- summary: renderSearchSummary(state, { split: "train" }),
2996
- history: [],
2997
- findings: prepared.findings,
2998
- populationSize: method.childrenPerProposal,
2999
- generation: request.expansion,
3000
- signal: request.signal,
3001
- costLedger: taggedLedger(costLedger, tags),
3002
- costPhase: proposalPhase
3003
- });
3004
- const decision = proposer.decide?.({ history: [] });
3005
- const proposed = decision?.stop ? [] : await proposer.propose(context);
3006
- if (!Array.isArray(proposed)) throw new ConfigError("improve(): the search proposer must return an array");
3007
- const fresh = costLedger.list({
3008
- phase: proposalPhase,
3009
- tags
3010
- });
3011
- return {
3012
- children: proposed.slice(0, method.childrenPerProposal).map((child) => isProposedCandidate(child) ? {
3013
- artifact: nodeOf(child.surface),
3014
- label: child.label,
3015
- rationale: child.rationale,
3016
- ...child.attribution ? { attribution: child.attribution } : {}
3017
- } : {
3018
- artifact: nodeOf(child),
3019
- label: "",
3020
- rationale: ""
3021
- }),
3022
- ...decision?.stop ? { stop: decision.reason ?? "the proposer decided to stop" } : {},
3023
- accounting: searchReceiptAccounting(fresh),
3024
- execution: searchProposalExecution(fresh, prepared.searchIdentity.model.provider, proposerSource)
3025
- };
3026
- }
3027
- };
3028
- const admit = (node) => {
3029
- if (node.refusal !== null || node.profile === null) return node.refusal;
3030
- try {
3031
- prepared.admitCandidate(node.profile, node.surface);
3032
- } catch (error) {
3033
- return refusalText(error);
3034
- }
3035
- const paths = privateValuePaths([node.surface]);
3036
- if (paths.length > 0) return `the surface carries a credential or private value at ${paths.slice(0, 8).join(", ")}`;
3037
- return laneRefusal(node.profile);
3038
- };
3039
- const startedAt = Date.now();
3040
- const result = await runSearch({
3041
- recorder,
3042
- root,
3043
- codec,
3044
- policy,
3045
- allocation,
3046
- proposer: port,
3047
- executor,
3048
- admit,
3049
- maxExpansions: method.maxExpansions,
3050
- maxAttempts: method.maxAttempts,
3051
- ...signal ? { signal } : {}
3052
- });
3053
- const { state } = result;
3054
- const claimResult = result.claim;
3055
- if (!claimResult || !result.claimVerification) throw new Error(`improve(): search ${searchId} closed without a claim`);
3056
- const kept = codec.load(recorder, state.node(result.leader));
3057
- if (!kept.profile) throw new Error(`improve(): search ${searchId} kept a refused node`);
3058
- const candidate = Object.freeze({
3059
- surface: prepared.surface,
3060
- value: kept.surface,
3061
- profile: kept.profile
3062
- });
3063
- const cost = copyImproveCost(costLedger.summary());
3064
- const shipped = claimResult.finalists.find((finalist) => finalist.nodeId === claimResult.selected && finalist.test !== null);
3065
- const { decision, reason } = runtimeShipDecision({
3066
- claim: claimResult,
3067
- verified: result.claimVerification.status === "verified",
3068
- accountingComplete: cost.accountingComplete,
3069
- lowerBound: shipped?.test?.interval[0] ?? null,
3070
- minimumLift: prepared.minimumLift
3071
- });
3072
- return {
3073
- mode: "search",
3074
- method: method.name,
3075
- candidate,
3076
- decision,
3077
- reason,
3078
- claim: claimResult,
3079
- claimVerification: result.claimVerification,
3080
- ...shipped?.test ? {
3081
- lift: shipped.test.delta,
3082
- liftInterval: {
3083
- low: shipped.test.interval[0],
3084
- high: shipped.test.interval[1]
3085
- }
3086
- } : {},
3087
- searchHistory: recorder.receipt({
3088
- producerId: method.name,
3089
- runId: searchId
3090
- }),
3091
- cost,
3092
- durationMs: Date.now() - startedAt,
3093
- lineage: Object.freeze({
3094
- invocationId: prepared.invocationId,
3095
- runId: searchId,
3096
- developmentSplitDigest: prepared.identity.developmentSplitDigest,
3097
- finalTestSplitDigest: prepared.identity.finalTestSplitDigest,
3098
- scenarioPartitions: prepared.identity.scenarioPartitions,
3099
- executionRef: prepared.executionRef,
3100
- baselineProfileDigest: prepared.baselineProfileDigest
3101
- }),
3102
- async dispose() {}
3103
- };
3104
- }
3105
- /** Runtime's ship rule over the kernel's statistical claim (design §6.5 step 5). */
3106
- function runtimeShipDecision(input) {
3107
- const { claim } = input;
3108
- if (claim.decision !== "ship") return {
3109
- decision: "hold",
3110
- reason: claim.reason
3111
- };
3112
- if (!input.verified) return {
3113
- decision: "hold",
3114
- reason: "the claim shipped, but it does not re-derive from the ledger under this rule revision"
3115
- };
3116
- if (!input.accountingComplete) return {
3117
- decision: "hold",
3118
- reason: "the claim shipped, but the search cost accounting is incomplete"
3119
- };
3120
- if (input.lowerBound === null || !(input.lowerBound > input.minimumLift)) return {
3121
- decision: "hold",
3122
- reason: `the claim shipped, but its test lower bound ${input.lowerBound} does not exceed minimumLift ${input.minimumLift}`
3123
- };
3124
- return {
3125
- decision: "ship",
3126
- reason: claim.reason
3127
- };
3128
- }
3129
- /** Profiles as search artifacts: nodes by profile digest, edges by profile diffs. */
3130
- function profileCodec(prepared) {
3131
- const surfaceId = prepared.surface;
3132
- return {
3133
- node(recorder, node) {
3134
- if (node.profile) {
3135
- const artifact = recorder.blob("agent-profile", {
3136
- kind: "agent-profile",
3137
- profile: node.profile
3138
- });
3139
- return {
3140
- artifactDigest: canonicalAgentProfileDigest(node.profile),
3141
- artifact,
3142
- surfaces: [{
3143
- surfaceId,
3144
- kind: "agent-profile",
3145
- artifact
3146
- }]
3147
- };
3148
- }
3149
- const artifact = recorder.blob("surface", {
3150
- kind: "unmaterialized-surface",
3151
- surface: node.surface,
3152
- refusal: node.refusal
3153
- });
3154
- return {
3155
- artifactDigest: canonicalCandidateDigest$1({
3156
- kind: "unmaterialized-surface",
3157
- surface: node.surface
3158
- }),
3159
- artifact,
3160
- surfaces: [{
3161
- surfaceId,
3162
- kind: "agent-profile",
3163
- artifact
3164
- }]
3165
- };
3166
- },
3167
- diff(recorder, parent, child) {
3168
- if (!parent.profile || !child.profile) return { unknown: "a surface that does not materialize has no profile to diff" };
3169
- const diffs = diffAgentProfiles(parent.profile, child.profile);
3170
- const to = canonicalAgentProfileDigest(child.profile);
3171
- if (canonicalAgentProfileDigest(diffs.reduce(applyAgentProfileDiff, parent.profile)) !== to) return { unknown: "the Interface profile diffs do not reproduce the child profile" };
3172
- return recorder.blob("diff", {
3173
- kind: "agent-profile-diff",
3174
- from: canonicalAgentProfileDigest(parent.profile),
3175
- to,
3176
- diffs
3177
- });
3178
- },
3179
- load(recorder, node) {
3180
- const stored = recorder.readBlob(node.artifact);
3181
- if (stored.kind === "agent-profile") {
3182
- const parsed = agentProfileSchema.safeParse(stored.profile);
3183
- if (!parsed.success) throw new Error(`improve(): node ${node.nodeId} holds an invalid AgentProfile`);
3184
- const loaded = immutableCandidateValue(parsed.data);
3185
- return {
3186
- surface: prepared.surfaceOf(loaded),
3187
- profile: loaded,
3188
- refusal: null
3189
- };
3190
- }
3191
- if (stored.kind === "unmaterialized-surface" && stored.surface !== void 0) return {
3192
- surface: stored.surface,
3193
- profile: null,
3194
- refusal: stored.refusal ?? null
3195
- };
3196
- throw new Error(`improve(): node ${node.nodeId} holds no profile search artifact`);
3197
- }
3198
- };
3199
- }
3200
- /** Everything that decides which search a call continues. */
3201
- function searchMethodDescriptor(method) {
3202
- return {
3203
- name: method.name,
3204
- policy: method.policy.name,
3205
- allocation: method.allocation.name,
3206
- reps: method.allocation.reps,
3207
- proposer: method.proposer.kind,
3208
- maxExpansions: method.maxExpansions,
3209
- childrenPerProposal: method.childrenPerProposal,
3210
- lanes: method.lanes.map(({ name, kind, capacity, costCap, cellUsd }) => ({
3211
- name,
3212
- kind,
3213
- capacity,
3214
- costCap,
3215
- cellUsd
3216
- })),
3217
- claimReserveUsd: method.claimReserveUsd,
3218
- deadline: method.deadline,
3219
- maxAttempts: method.maxAttempts
3220
- };
3221
- }
3222
- /**
3223
- * An environment fault the agent raised settles retryable. The campaign reports every error as
3224
- * final because it applies its own retry policy; here the kernel owns retries.
3225
- */
3226
- function faultResult(result, fault) {
3227
- if (fault === void 0 || result.outcome.status !== "errored") return result;
3228
- return {
3229
- ...result,
3230
- outcome: {
3231
- ...result.outcome,
3232
- error: {
3233
- code: "environment-fault",
3234
- message: refusalText(fault),
3235
- retryable: true
3236
- }
3237
- }
3238
- };
3239
- }
3240
- /** A refusal as the ledger stores it: redacted with the share profile. */
3241
- function refusalText(error) {
3242
- return redact(error instanceof Error ? error.message : String(error), { profile: "share" }).value;
3243
- }
3244
- //#endregion
3245
1481
  //#region src/improvement/training.ts
3246
1482
  function positiveLimit(value, label) {
3247
1483
  if (!Number.isSafeInteger(value) || value <= 0) throw new Error(`invalid ${label}`);
@@ -4860,6 +3096,6 @@ function sameOrderedValues(left, right) {
4860
3096
  return left.length === right.length && left.every((value, index) => value === right[index]);
4861
3097
  }
4862
3098
  //#endregion
4863
- export { applyRolloutPolicyToProfile as $, agentImprovementTargetInput as A, SearchEnvironmentFault as B, optimizationActivationReceiptFromMetadata as C, agentImprovementProfileSurfaceDigest as D, agentImprovementProfileDiffs as E, isAgentImprovementProfileSurface as F, subscriptionLane as G, isSearchEnvironmentFault as H, isAgentProfileMeasuredSurface as I, parseExecutionRef as J, assertCandidateValidator as K, improve as L, agentProfileImprovementStateDigest as M, assertProfileImprovementTargetsShareIdentity as N, agentImprovementProfileSurfaceInput as O, buildAgentImprovementActivationTargets as P, ROLLOUT_POLICY_EXTENSION as Q, createCommandProfileTrainer as R, createOptimizationActivationReceipt as S, AGENT_PROFILE_MEASURED_SURFACES as T, routerLane as U, dedicatedLane as V, sharedBoxLane as W, withMethodRuntimeControls as X, privateValuePaths as Y, rawTraceDistiller as Z, profilePolicyWithBudget as _, executeAgentCandidateExperimentCell as a, commandVerifier as at, profileTaskScenarioIdentity as b, requireSealedCandidateExperiment as c, verifyAgentImprovementActivation as d, normalizeRolloutPolicy as et, verifyAgentImprovementProposal as f, profileImprovementMetadata as g, createProfileImprovementCostLedger as h, createAgentImprovementProposal as i, agenticGenerator as it, agentImprovementTargetProfileDiffs as j, agentImprovementTargetDigest as k, reviewAgentImprovementProposal as l, verifyCandidateExecutionEvidence as m, createAgentImprovementActivation as n, serializeRolloutPolicy as nt, proposeAgentImprovement as o, defaultBuildPrompt as ot, verifyAgentImprovementReview as p, assertProfileTrainingIsHeldOut as q, createAgentImprovementMeasuredComparison as r, structuralRolloutPolicyFromProfile as rt, proposeAgentProfileImprovement as s, AgentCandidateExperimentCellExecutionError as t, parseRolloutPolicy as tt, runAgentCandidateExperiment as u, profilePreparationAccounting as v, AGENT_IMPROVEMENT_PROFILE_SURFACES as w, sealProfileImprovementBenchmark as x, profileStateDigest as y, searchMethod as z };
3099
+ export { agentImprovementTargetInput as A, rawTraceDistiller as B, optimizationActivationReceiptFromMetadata as C, agentImprovementProfileSurfaceDigest as D, agentImprovementProfileDiffs as E, isAgentImprovementProfileSurface as F, commandVerifier as H, isAgentProfileMeasuredSurface as I, improve as L, agentProfileImprovementStateDigest as M, assertProfileImprovementTargetsShareIdentity as N, agentImprovementProfileSurfaceInput as O, buildAgentImprovementActivationTargets as P, createCommandProfileTrainer as R, createOptimizationActivationReceipt as S, AGENT_PROFILE_MEASURED_SURFACES as T, defaultBuildPrompt as U, agenticGenerator as V, profilePolicyWithBudget as _, executeAgentCandidateExperimentCell as a, profileTaskScenarioIdentity as b, requireSealedCandidateExperiment as c, verifyAgentImprovementActivation as d, verifyAgentImprovementProposal as f, profileImprovementMetadata as g, createProfileImprovementCostLedger as h, createAgentImprovementProposal as i, agentImprovementTargetProfileDiffs as j, agentImprovementTargetDigest as k, reviewAgentImprovementProposal as l, verifyCandidateExecutionEvidence as m, createAgentImprovementActivation as n, proposeAgentImprovement as o, verifyAgentImprovementReview as p, createAgentImprovementMeasuredComparison as r, proposeAgentProfileImprovement as s, AgentCandidateExperimentCellExecutionError as t, runAgentCandidateExperiment as u, profilePreparationAccounting as v, AGENT_IMPROVEMENT_PROFILE_SURFACES as w, sealProfileImprovementBenchmark as x, profileStateDigest as y, withMethodRuntimeControls as z };
4864
3100
 
4865
- //# sourceMappingURL=improvement-cycle-DCTCTmNl.js.map
3101
+ //# sourceMappingURL=improvement-cycle-8MUf5Xfp.js.map