@tangle-network/agent-runtime 0.94.13 → 0.96.1

package/dist/intelligence.js

@@ -1,35 +1,40 @@
 import {
-  applyImprovementWinnerToProfile,
-  improve
-} from "./chunk-PCURO3DL.js";
+  AgentCandidateExperimentCellExecutionError,
+  buildAgentImprovementActivationTargets,
+  createAgentImprovementActivation,
+  createAgentImprovementActivationResult,
+  createAgentImprovementMeasuredComparison,
+  createAgentImprovementProposal,
+  executeAgentCandidateExperimentCell,
+  executeAgentImprovementActivation,
+  proposeAgentImprovement,
+  reviewAgentImprovementProposal,
+  runAgentCandidateExperiment,
+  verifyAgentImprovementActivation,
+  verifyAgentImprovementActivationResult,
+  verifyAgentImprovementProposal,
+  verifyAgentImprovementReview,
+  verifyCandidateExecutionEvidence
+} from "./chunk-PSOCBNM3.js";
 import {
-  assertCandidateProfileBinding,
-  canonicalCandidateDigest,
-  canonicalCandidateDocument,
-  executePreparedAgentCandidate,
-  immutableCandidateValue,
-  omitTopLevelDigest,
-  parseExactAgentProfile,
-  prepareAgentCandidateExecution,
-  sealAgentCandidateBundle,
-  verifyAgentCandidateBundle
-} from "./chunk-CNH7DF7Z.js";
+  AGENT_CANDIDATE_EXECUTION_SUPPORT,
+  CANDIDATE_KNOWLEDGE_RETRIEVAL_CONFIG_ENV,
+  CANDIDATE_KNOWLEDGE_ROOT_ENV,
+  candidateKnowledgeExecutionPaths,
+  canonicalCandidateBytes,
+  parseAgentCandidateProfileActivation
+} from "./chunk-YOLKCWRV.js";
 import {
   buildLoopOtelSpans,
   buildRuntimeEventOtelSpans,
   createOtelExporter,
   flatOtelSpan
-} from "./chunk-ISTDY47H.js";
-import "./chunk-WIPGQ4GT.js";
+} from "./chunk-HZDEXTSL.js";
+import "./chunk-IMSNJSXH.js";
 import "./chunk-3MDZX7YU.js";
-import {
-  runAnalystLoop
-} from "./chunk-QDSOD7RC.js";
+import "./chunk-FD2MBMOH.js";
 import "./chunk-M22PL4GH.js";
-import "./chunk-D3H7F6L2.js";
-import "./chunk-EP6RVHMX.js";
 import "./chunk-YEJR7IXO.js";
-import "./chunk-DGUM43GV.js";
 
 // src/intelligence/index.ts
 import { contentHash } from "@tangle-network/agent-eval";
@@ -414,318 +419,6 @@ function isJsonSchema(v) {
   return typeof v === "object" && v !== null && !Array.isArray(v);
 }
 
-// src/intelligence/improvement-cycle.ts
-import { assertNoJudgeVerdict } from "@tangle-network/agent-eval/analyst";
-import { agentCandidateBundleSchema } from "@tangle-network/agent-interface";
-async function rethrowAfterImprovementDispose(cause, improvement) {
-  const disposeErrors = [];
-  for (let attempt = 0; attempt < 2; attempt += 1) {
-    try {
-      await improvement.dispose();
-    } catch (disposeCause) {
-      disposeErrors.push(disposeCause);
-      continue;
-    }
-    if (disposeErrors.length === 0) throw cause;
-    throw new AggregateError(
-      [cause, ...disposeErrors],
-      "proposeAgentImprovement failed; the improvement cleanup retry succeeded"
-    );
-  }
-  throw new AggregateError(
-    [cause, ...disposeErrors],
-    "proposeAgentImprovement failed and its improvement resources could not be cleaned"
-  );
-}
-async function proposeAgentImprovement(options) {
-  const writeBackSurface = options.improvement.skills?.writeBack ? "skill" : options.improvement.memory?.writeBack ? "memory" : null;
-  if (writeBackSurface) {
-    throw new Error(
-      `proposeAgentImprovement cannot write ${writeBackSurface} before human approval`
-    );
-  }
-  const analysis = await runAnalystLoop({
-    ...options.analysis,
-    runId: options.runId
-  });
-  const findings = assertNoJudgeVerdict(
-    analysis.analystResult.findings,
-    "proposeAgentImprovement findings"
-  );
-  const improvement = await improve(options.profile, [...findings], options.improvement);
-  try {
-    const candidateBundle = improvement.shipped && options.buildCandidate ? await options.buildCandidate({ analysis, improvement }) : void 0;
-    const proposal = createAgentImprovementProposal({
-      runId: options.runId,
-      surface: options.improvement.surface ?? "prompt",
-      baselineProfile: options.profile,
-      candidateProfile: improvement.profile,
-      findings,
-      evaluation: improvement.raw,
-      ...candidateBundle ? { candidateBundle } : {},
-      ...options.now ? { now: options.now } : {}
-    });
-    return { analysis, improvement, proposal };
-  } catch (cause) {
-    return rethrowAfterImprovementDispose(cause, improvement);
-  }
-}
-function createAgentImprovementProposal(options) {
-  const findings = assertNoJudgeVerdict(
-    [...options.findings],
-    "createAgentImprovementProposal findings"
-  );
-  const candidateBundle = options.candidateBundle ? sealBuiltCandidate(options.candidateBundle) : void 0;
-  const baselineProfile = parseExactAgentProfile(
-    options.baselineProfile,
-    "proposal baseline profile"
-  );
-  const candidateProfile = parseExactAgentProfile(
-    options.candidateProfile,
-    "proposal candidate profile"
-  );
-  assertMeasuredProfileBinding({
-    surface: options.surface,
-    baselineProfile,
-    candidateProfile,
-    evaluation: options.evaluation,
-    hasExecutableBundle: candidateBundle !== void 0
-  });
-  if (candidateBundle) {
-    if (options.evaluation.gateDecision !== "ship") {
-      throw new Error("executable candidate bundle requires a passing measured comparison");
-    }
-    assertCandidateProfileBinding(candidateProfile, candidateBundle.profile);
-  }
-  const withoutDigest = {
-    schemaVersion: 1,
-    kind: "agent-improvement-proposal",
-    runId: options.runId,
-    surface: options.surface,
-    proposedAt: (options.now ?? (() => /* @__PURE__ */ new Date()))().toISOString(),
-    baselineProfile,
-    baselineProfileHash: canonicalCandidateDigest(baselineProfile),
-    candidateProfile,
-    candidateProfileHash: canonicalCandidateDigest(candidateProfile),
-    findings: canonicalJsonValue([...findings]),
-    evaluation: canonicalJsonValue(improvementEvaluation(options.evaluation)),
-    ...candidateBundle ? { candidateBundle } : {}
-  };
-  return canonicalCandidateDocument(withoutDigest).value;
-}
-function reviewAgentImprovementProposal(inputProposal, input) {
-  const proposal = verifyAgentImprovementProposal(inputProposal);
-  if (!input.reviewedBy.trim()) throw new Error("candidate review requires reviewedBy");
-  if (!input.reason.trim()) throw new Error("candidate review requires a reason");
-  if (input.decision === "approve") {
-    if (proposal.evaluation.gateDecision !== "ship") {
-      throw new Error("candidate cannot be approved without a passing measured comparison");
-    }
-    if (!proposal.candidateBundle) {
-      throw new Error("candidate cannot be approved until an executable bundle is sealed");
-    }
-  }
-  const withoutDigest = {
-    schemaVersion: 1,
-    kind: "agent-improvement-review",
-    proposalDigest: proposal.digest,
-    ...proposal.candidateBundle ? { candidateBundleDigest: proposal.candidateBundle.digest } : {},
-    decision: input.decision,
-    reviewedBy: input.reviewedBy,
-    reviewedAt: (input.now ?? (() => /* @__PURE__ */ new Date()))().toISOString(),
-    reason: input.reason,
-    ...input.feedback === void 0 ? {} : { feedback: input.feedback }
-  };
-  return canonicalCandidateDocument(withoutDigest).value;
-}
-async function executeApprovedAgentCandidate(options) {
-  const proposal = verifyAgentImprovementProposal(options.proposal);
-  const review = verifyAgentImprovementReview(options.review);
-  if (review.decision !== "approve") throw new Error("candidate review is not an approval");
-  if (review.proposalDigest !== proposal.digest) {
-    throw new Error("candidate approval does not match the proposed improvement");
-  }
-  const bundle = proposal.candidateBundle;
-  if (!bundle) throw new Error("approved proposal does not contain an executable candidate bundle");
-  if (review.candidateBundleDigest !== bundle.digest) {
-    throw new Error("candidate approval does not match the executable bundle");
-  }
-  if (!await options.authorizeReview(review, proposal)) {
-    throw new Error("candidate approval was not authorized by the configured authority");
-  }
-  const verified = await verifyAgentCandidateBundle(bundle, options.ports);
-  const prepared = await prepareAgentCandidateExecution(
-    verified,
-    options.task,
-    options.ports,
-    options.preparation
-  );
-  const finalization = await executePreparedAgentCandidate(prepared, options.execution);
-  return {
-    finalization,
-    evidence: {
-      proposalDigest: proposal.digest,
-      reviewDigest: review.digest,
-      bundleDigest: bundle.digest,
-      executionId: prepared.executionId,
-      executionPlanDigest: prepared.executionPlan.value.digest,
-      materializationReceiptDigest: prepared.materializationReceipt.digest,
-      succeeded: finalization.succeeded,
-      ...finalization.succeeded ? { runReceiptDigest: finalization.receipt.digest } : {}
-    }
-  };
-}
-function verifyAgentImprovementProposal(input) {
-  if (!isRecord(input) || input.kind !== "agent-improvement-proposal" || input.schemaVersion !== 1) {
-    throw new Error("invalid agent improvement proposal");
-  }
-  const proposal = input;
-  const parsedBaselineProfile = parseExactAgentProfile(
-    proposal.baselineProfile,
-    "proposal baseline profile"
-  );
-  if (proposal.baselineProfileHash !== canonicalCandidateDigest(parsedBaselineProfile)) {
-    throw new Error("proposal baselineProfileHash does not match baselineProfile");
-  }
-  const parsedProfile = parseExactAgentProfile(
-    proposal.candidateProfile,
-    "proposal candidate profile"
-  );
-  if (proposal.candidateProfileHash !== canonicalCandidateDigest(parsedProfile)) {
-    throw new Error("proposal candidateProfileHash does not match candidateProfile");
-  }
-  assertMeasuredProfileBinding({
-    surface: proposal.surface,
-    baselineProfile: parsedBaselineProfile,
-    candidateProfile: parsedProfile,
-    evaluation: proposal.evaluation,
-    hasExecutableBundle: proposal.candidateBundle !== void 0
-  });
-  if (!Array.isArray(proposal.findings)) throw new Error("proposal findings must be an array");
-  if (!isSha256Digest(proposal.digest)) throw new Error("proposal digest is invalid");
-  if (proposal.candidateBundle) {
-    const parsedBundle = agentCandidateBundleSchema.parse(proposal.candidateBundle);
-    const sealed = sealAgentCandidateBundle(omitTopLevelDigest(parsedBundle));
-    if (sealed.digest !== parsedBundle.digest)
-      throw new Error("proposal candidate bundle digest is invalid");
-    assertCandidateProfileBinding(parsedProfile, sealed.profile);
-  }
-  const actual = canonicalCandidateDigest(omitTopLevelDigest(proposal));
-  if (actual !== proposal.digest)
-    throw new Error("agent improvement proposal digest does not match");
-  return immutableCandidateValue(proposal);
-}
-function assertMeasuredProfileBinding(input) {
-  const baselineDigest = canonicalCandidateDigest(input.baselineProfile);
-  if (input.evaluation.gateDecision !== "ship") {
-    if (canonicalCandidateDigest(input.candidateProfile) !== baselineDigest) {
-      throw new Error("non-shipping evaluation must retain the baseline candidate profile");
-    }
-    return;
-  }
-  const measured = measuredWinnerProfile(
-    input.baselineProfile,
-    input.surface,
-    input.evaluation.winner.surface
-  );
-  if (!measured) {
-    if (input.hasExecutableBundle) {
-      throw new Error(
-        `executable '${input.surface}' candidate cannot be bound to its measured winner surface`
-      );
-    }
-    if (canonicalCandidateDigest(input.candidateProfile) !== baselineDigest) {
-      throw new Error(
-        `unbound '${input.surface}' improvement must retain the baseline candidate profile`
-      );
-    }
-    return;
-  }
-  if (canonicalCandidateDigest(input.candidateProfile) !== canonicalCandidateDigest(measured)) {
-    throw new Error("proposal candidate profile does not match the measured winner surface");
-  }
-}
-function measuredWinnerProfile(baselineProfile, surface, winner) {
-  if (surface === "code" || surface === "memory") return null;
-  if (typeof winner !== "string") {
-    throw new Error(`measured '${surface}' winner is not a serializable profile surface`);
-  }
-  if (surface !== "skills") {
-    return applyImprovementWinnerToProfile(baselineProfile, surface, winner);
-  }
-  try {
-    return applyImprovementWinnerToProfile(baselineProfile, surface, winner);
-  } catch {
-    return null;
-  }
-}
-function sealBuiltCandidate(input) {
-  if (!("digest" in input)) return sealAgentCandidateBundle(input);
-  const parsed = agentCandidateBundleSchema.parse(input);
-  const sealed = sealAgentCandidateBundle(omitTopLevelDigest(parsed));
-  if (sealed.digest !== parsed.digest) {
-    throw new Error("built candidate bundle digest is invalid");
-  }
-  return sealed;
-}
-function verifyAgentImprovementReview(input) {
-  if (!isRecord(input) || input.kind !== "agent-improvement-review" || input.schemaVersion !== 1) {
-    throw new Error("invalid agent improvement review");
-  }
-  const review = input;
-  if (!isSha256Digest(review.digest) || !isSha256Digest(review.proposalDigest)) {
-    throw new Error("candidate review digest is invalid");
-  }
-  if (review.candidateBundleDigest !== void 0 && !isSha256Digest(review.candidateBundleDigest)) {
-    throw new Error("candidate review bundle digest is invalid");
-  }
-  if (!["approve", "reject", "request-changes"].includes(review.decision)) {
-    throw new Error("candidate review decision is invalid");
-  }
-  const actual = canonicalCandidateDigest(omitTopLevelDigest(review));
-  if (actual !== review.digest) throw new Error("agent improvement review digest does not match");
-  return immutableCandidateValue(review);
-}
-function improvementEvaluation(result) {
-  return {
-    baseline: result.baseline,
-    winner: result.winner,
-    lift: result.lift,
-    diff: result.diff,
-    provenance: result.provenance,
-    gateDecision: result.gateDecision,
-    generationsExplored: result.generationsExplored,
-    durationMs: result.durationMs,
-    totalCostUsd: result.totalCostUsd,
-    insight: result.insight,
-    ...result.power === void 0 ? {} : { power: result.power }
-  };
-}
-function isRecord(value) {
-  return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-function isSha256Digest(value) {
-  return typeof value === "string" && /^sha256:[a-f0-9]{64}$/.test(value);
-}
-function canonicalJsonValue(value, path = "$") {
-  if (value === null || typeof value === "string" || typeof value === "boolean") return value;
-  if (typeof value === "number") {
-    if (!Number.isFinite(value)) throw new Error(`non-finite number at ${path}`);
-    return value;
-  }
-  if (Array.isArray(value)) {
-    return value.map((entry, index) => {
-      if (entry === void 0) throw new Error(`undefined array entry at ${path}[${index}]`);
-      return canonicalJsonValue(entry, `${path}[${index}]`);
-    });
-  }
-  if (typeof value === "object") {
-    const entries = Object.entries(value).filter(([, entry]) => entry !== void 0).map(([key, entry]) => [key, canonicalJsonValue(entry, `${path}.${key}`)]);
-    return Object.fromEntries(entries);
-  }
-  throw new Error(`unsupported proposal value at ${path}`);
-}
-
 // src/intelligence/resolver.ts
 function emptyAccumulator() {
   return {
@@ -1101,6 +794,467 @@ async function composeCertifiedProfileFromWire(base, profile, ctx = {}) {
   return composeCertifiedProfile(base, manifestFromProfile(profile), ctx);
 }
 
+// src/intelligence/sandbox-approved-candidate.ts
+import { posix } from "path";
+var sandboxCandidateExperimentExecutionSupport = Object.freeze({
+  outcomes: Object.freeze(["output"]),
+  outputMediaTypes: Object.freeze(["text/*", "application/json", "*+json"]),
+  code: Object.freeze(["disabled"]),
+  memory: Object.freeze(["disabled"]),
+  knowledge: true,
+  profile: AGENT_CANDIDATE_EXECUTION_SUPPORT.profile,
+  isolation: Object.freeze({
+    freshSandbox: true,
+    exactProcess: true,
+    egress: Object.freeze(["blocked", "strict"])
+  })
+});
+function createSandboxCandidateExperimentExecutor(options) {
+  const executor = new SandboxAgentCandidateExecutor(
+    options.client,
+    options.sandbox,
+    options.resultTimeoutMs
+  );
+  return Object.freeze({
+    executor,
+    async execute(input) {
+      return await executeAgentCandidateExperimentCell({
+        ...input,
+        attempt: input.attempt ?? 1,
+        executionId: input.executionId,
+        executionRoots: input.executionRoots,
+        stagingRoots: input.stagingRoots,
+        ports: options.ports,
+        ...input.preparation ? { preparation: input.preparation } : {},
+        execution: {
+          executor,
+          grader: options.grader,
+          outputArtifacts: options.outputArtifacts,
+          traceStore: options.traceStore,
+          claimStore: options.claimStore,
+          ...options.cleanupTimeoutMs === void 0 ? {} : { cleanupTimeoutMs: options.cleanupTimeoutMs },
+          ...options.resultTimeoutMs === void 0 ? {} : { resultTimeoutMs: options.resultTimeoutMs }
+        }
+      });
+    }
+  });
+}
+var SandboxAgentCandidateExecutor = class {
+  constructor(client, options = {}, captureTimeoutMs = 12e4) {
+    this.client = client;
+    this.options = options;
+    this.captureTimeoutMs = captureTimeoutMs;
+  }
+  client;
+  options;
+  captureTimeoutMs;
+  states = /* @__PURE__ */ new Map();
+  async execute(request, context) {
+    assertSupportedRequest(request);
+    const outcome = request.benchmark.task.outcome;
+    if (outcome.kind !== "output") throw new Error("sandbox executor requires an output task");
+    const key = executionKey(request.executionId, request.executionPlan.value.digest);
+    const sandbox = await this.client.create(sandboxCreateOptions(request, this.options), {
+      signal: context.signal,
+      timeoutMs: this.options.createTimeoutMs ?? 12e4
+    });
+    const state = { sandbox };
+    this.states.set(key, state);
+    if ((await sandbox.process.list()).length !== 0) {
+      throw new Error("fresh candidate sandbox already contains a process");
+    }
+    await materializeRequest(sandbox, request);
+    const launch = exactLaunch(request);
+    const startedAt = Date.now();
+    state.trace = {
+      runId: request.trace.runId,
+      scenarioId: request.benchmark.task.scenario.id,
+      startedAt,
+      deadlineAtMs: context.deadlineAtMs,
+      timeoutMs: request.hardLimits.timeoutMs,
+      tags: { ...request.trace.tags, sandboxId: sandbox.id },
+      written: false
+    };
+    const process2 = await sandbox.process.spawnExact(launch.executable, launch.args, {
+      cwd: request.launch.cwd,
+      env: { ...request.launch.env },
+      ...launch.stdin === void 0 ? {} : { stdin: launch.stdin },
+      timeoutMs: request.hardLimits.timeoutMs
+    });
+    const outputPromise = collectOutput(process2, outcome.maxBytes);
+    let cancellation;
+    let cancellationTermination;
+    let processExited = false;
+    const cancel = () => {
+      if (processExited) return;
+      cancellationTermination = Date.now() >= context.deadlineAtMs ? { kind: "timeout", timeoutMs: request.hardLimits.timeoutMs } : { kind: "cancelled" };
+      cancellation ??= killProcess(process2);
+    };
+    context.signal.addEventListener("abort", cancel, { once: true });
+    if (context.signal.aborted) cancel();
+    try {
+      const waitedExitCode = await process2.wait();
+      processExited = true;
+      context.signal.removeEventListener("abort", cancel);
+      if (cancellation) await cancellation;
+      const status = await process2.status();
+      if (status.running || status.exitCode !== waitedExitCode) {
+        throw new Error("sandbox process returned an inconsistent terminal status");
+      }
+      state.output = await awaitOutput(outputPromise, context.signal, context.deadlineAtMs);
+      state.termination = cancellationTermination ?? processTermination(status);
+      await appendSandboxTrace(state, context.traceStore, status);
+      return { executionId: request.executionId, termination: state.termination };
+    } finally {
+      context.signal.removeEventListener("abort", cancel);
+      void outputPromise.catch(() => void 0);
+    }
+  }
+  async stop(request, context) {
+    context.signal.throwIfAborted();
+    const sandbox = await this.resolve(request, true);
+    if (!sandbox) return { stopped: true };
+    const statuses = await sandbox.process.list();
+    if (statuses.length > 1) throw new Error("candidate sandbox contains more than one process");
+    const status = statuses[0];
+    if (status?.running) {
+      const process2 = await sandbox.process.get(status.pid);
+      if (!process2) throw new Error("candidate sandbox lost its running process handle");
+      await killProcess(process2);
+    }
+    context.signal.throwIfAborted();
+    const remaining = await sandbox.process.list();
+    if (remaining.some((entry) => entry.running)) {
+      throw new Error("candidate sandbox process termination is not proven");
+    }
+    const state = this.states.get(executionKey(request.executionId, request.executionPlanDigest));
+    if (state) {
+      if (context.reason === "timeout") {
+        state.termination = { kind: "timeout", timeoutMs: state.trace?.timeoutMs ?? 0 };
+      }
+      await appendSandboxTrace(state, context.traceStore, remaining[0]);
+    }
+    return { stopped: true };
+  }
+  async capture(request, context) {
+    context.signal.throwIfAborted();
+    const sandbox = await this.resolve(request, false);
+    const statuses = await sandbox.process.list();
+    if (statuses.length > 1 || statuses.some((entry) => entry.running)) {
+      throw new Error("candidate sandbox must contain one stopped process before capture");
+    }
+    const state = this.states.get(executionKey(request.executionId, request.executionPlanDigest));
+    let output = state?.output;
+    let termination = state?.termination;
+    const status = statuses[0];
+    if (status && !output) {
+      const process2 = await sandbox.process.get(status.pid);
+      if (!process2) throw new Error("candidate sandbox lost its captured process handle");
+      const expected = sandboxOutputSpec(sandbox);
+      output = await awaitOutput(
+        collectOutput(process2, expected.maxBytes),
+        context.signal,
+        Date.now() + this.captureTimeoutMs
+      );
+    }
+    if (status && !termination) {
+      termination = processTermination(status);
+    }
+    context.signal.throwIfAborted();
+    const evidence = canonicalCandidateBytes({
+      kind: "sandbox-agent-candidate-capture",
+      sandboxId: sandbox.id,
+      executionId: request.executionId,
+      executionPlanDigest: request.executionPlanDigest,
+      ...status ? {
+        process: {
+          pid: status.pid,
+          exitCode: status.exitCode,
+          ...status.exitSignal ? { exitSignal: status.exitSignal } : {}
+        }
+      } : {},
+      ...termination ? { termination } : {}
+    });
+    return {
+      ...output ? { taskOutcome: { kind: "output", bytes: output } } : {},
+      evidence
+    };
+  }
+  async dispose(request, context) {
+    context.signal.throwIfAborted();
+    const sandbox = await this.resolve(request, true);
+    if (!sandbox) return { disposed: true };
+    try {
+      await sandbox.delete();
+    } catch (error) {
+      if (await this.client.get(sandbox.id)) throw error;
+    }
+    context.signal.throwIfAborted();
+    this.states.delete(executionKey(request.executionId, request.executionPlanDigest));
+    return { disposed: true };
+  }
+  async resolve(request, missingIsDeleted) {
+    const key = executionKey(request.executionId, request.executionPlanDigest);
+    const active = this.states.get(key)?.sandbox;
+    if (active) return active;
+    const matches = [];
+    const scope = this.options.teamId ? `team:${this.options.teamId}` : "personal";
+    for (let offset = 0; ; offset += 100) {
+      const page = await this.client.list({ scope, limit: 100, offset });
+      for (const candidate of page) {
+        if (matchesExecution(candidate, request)) matches.push(candidate);
+      }
+      if (page.length < 100) break;
+    }
+    if (matches.length === 1) return matches[0];
+    if (matches.length > 1) throw new Error("multiple sandboxes match one candidate execution");
+    if (missingIsDeleted) return void 0;
+    throw new Error("candidate sandbox evidence is unavailable");
+  }
+};
+async function appendSandboxTrace(state, traceStore, status) {
+  const trace = state.trace;
+  if (!trace || trace.written) return;
+  const endedAt = Math.max(trace.startedAt, Math.min(Date.now(), trace.deadlineAtMs));
+  await traceStore.appendRun({
+    runId: trace.runId,
+    scenarioId: trace.scenarioId,
+    startedAt: trace.startedAt,
+    endedAt,
+    status: state.termination?.kind !== "timeout" && status?.running === false && status.exitCode === 0 ? "completed" : "failed",
+    tags: trace.tags
+  });
+  trace.written = true;
+}
+function assertSupportedRequest(request) {
+  if (request.benchmark.task.outcome.kind !== "output") {
+    throw new Error("sandbox candidate executor does not support workspace outcomes; use Pier");
+  }
+  if (request.executionPlan.value.material.codeKind !== "disabled" || request.inputs.candidate) {
+    throw new Error("sandbox candidate executor does not support code workspaces; use Pier");
+  }
+  if (request.memory.mode !== "disabled") {
+    throw new Error("sandbox candidate executor does not support isolated memory");
+  }
+  const mediaType = request.benchmark.task.outcome.mediaType.toLowerCase();
+  if (!(mediaType.startsWith("text/") || mediaType === "application/json" || mediaType.endsWith("+json"))) {
+    throw new Error("sandbox candidate executor supports only UTF-8 text and JSON outputs");
+  }
+}
+function sandboxCreateOptions(request, options = {}) {
+  const material = request.executionPlan.value.material;
+  const retentionSeconds = options.evidenceRetentionSeconds ?? 900;
+  if (!Number.isSafeInteger(retentionSeconds) || retentionSeconds < 60) {
+    throw new Error("sandbox evidence retention must be at least 60 seconds");
+  }
+  const maxLifetimeSeconds = Math.ceil(request.hardLimits.timeoutMs / 1e3) + retentionSeconds;
+  const network = material.model.access.network;
+  const egressPolicy = network.mode === "disabled" ? { mode: "blocked" } : {
+    mode: "strict",
+    allowDomains: [...network.domains],
+    includeImplicitDomains: false
+  };
+  const value = {
+    image: exactImage(material.container.image, material.container.manifestDigest),
+    bare: true,
+    publicEdge: false,
+    ephemeral: true,
+    sshEnabled: false,
+    webTerminalEnabled: false,
+    secrets: [],
+    capabilities: [],
+    egressPolicy,
+    maxLifetimeSeconds,
+    idempotencyKey: `candidate-${request.executionPlan.value.digest.slice("sha256:".length)}`,
+    metadata: {
+      kind: "agent-candidate-execution",
+      executionId: request.executionId,
+      executionPlanDigest: request.executionPlan.value.digest,
+      outputMediaType: request.benchmark.task.outcome.kind === "output" ? request.benchmark.task.outcome.mediaType : "",
+      outputMaxBytes: request.benchmark.task.outcome.kind === "output" ? request.benchmark.task.outcome.maxBytes : 0
+    },
+    ...options.teamId ? { teamId: options.teamId } : {},
+    ...options.resources ? { resources: options.resources } : {}
+  };
+  return value;
+}
+async function materializeRequest(sandbox, request) {
+  const knowledgePaths = assertKnowledgeExecutionBinding(request);
+  for (const file of request.inputs.task.files) {
+    await writeExactFile(sandbox, beneath(request.roots.taskRoot, file.path), file.bytes, file.mode);
+  }
+  const profileRoot = request.executionPlan.value.material.profile.targetWorkspace === "task" ? request.roots.taskRoot : request.roots.candidateRoot;
+  if (!profileRoot) throw new Error("candidate profile targets a missing workspace");
+  for (const file of request.profileActivation.files) {
+    await writeExactFile(
+      sandbox,
+      beneath(profileRoot, file.path),
+      Buffer.from(file.content, "utf8"),
+      file.mode
+    );
+  }
+  if (request.knowledge && knowledgePaths) {
+    for (const file of request.knowledge.files) {
+      await writeExactFile(sandbox, beneath(knowledgePaths.root, file.path), file.bytes, file.mode);
+    }
+    if (request.knowledge.retrievalConfig && knowledgePaths.retrievalConfig) {
+      await writeExactFile(
+        sandbox,
+        knowledgePaths.retrievalConfig,
+        request.knowledge.retrievalConfig,
+        420
+      );
+    }
+  }
+  if (request.instruction.delivery.kind === "utf8-file") {
+    await writeExactFile(
+      sandbox,
+      request.instruction.delivery.path,
+      request.instruction.bytes,
+      420
+    );
+  }
+}
+function assertKnowledgeExecutionBinding(request) {
+  const knowledge = request.knowledge;
+  if (!knowledge) {
+    if (request.launch.env[CANDIDATE_KNOWLEDGE_ROOT_ENV] !== void 0 || request.launch.env[CANDIDATE_KNOWLEDGE_RETRIEVAL_CONFIG_ENV] !== void 0) {
+      throw new Error("candidate launch declares knowledge paths without verified knowledge");
+    }
+    return void 0;
+  }
+  const paths = candidateKnowledgeExecutionPaths(
+    request.roots.taskRoot,
+    knowledge.retrievalConfig !== void 0
+  );
+  if (request.launch.env[CANDIDATE_KNOWLEDGE_ROOT_ENV] !== paths.root || request.launch.env[CANDIDATE_KNOWLEDGE_RETRIEVAL_CONFIG_ENV] !== paths.retrievalConfig) {
+    throw new Error("candidate knowledge paths do not match the signed launch environment");
+  }
+  const reserved = [paths.root, paths.retrievalConfig].filter(
+    (value) => value !== void 0
+  );
+  const profileRoot = request.executionPlan.value.material.profile.targetWorkspace === "task" ? request.roots.taskRoot : request.roots.candidateRoot;
+  const otherFiles = [
+    ...request.inputs.task.files.map((file) => beneath(request.roots.taskRoot, file.path)),
+    ...profileRoot ? request.profileActivation.files.map((file) => beneath(profileRoot, file.path)) : [],
+    ...request.instruction.delivery.kind === "utf8-file" ? [request.instruction.delivery.path] : []
+  ];
+  if (otherFiles.some(
+    (path) => reserved.some(
+      (reservedPath) => path === reservedPath || path.startsWith(`${reservedPath}/`) || reservedPath.startsWith(`${path}/`)
+    )
+  )) {
+    throw new Error("candidate knowledge paths overlap other execution inputs");
+  }
+  return paths;
+}
+function exactLaunch(request) {
+  const instruction = new TextDecoder("utf-8", { fatal: true }).decode(request.instruction.bytes);
+  switch (request.instruction.delivery.kind) {
+    case "argv-append":
+      return { executable: request.launch.executable, args: [...request.launch.args, instruction] };
+    case "stdin-utf8":
+      return {
+        executable: request.launch.executable,
+        args: request.launch.args,
+        stdin: instruction
+      };
+    case "utf8-file":
+      return { executable: request.launch.executable, args: request.launch.args };
+  }
+}
+async function writeExactFile(sandbox, path, bytes, mode) {
+  await sandbox.fs.write(path, Buffer.from(bytes).toString("base64"), {
+    encoding: "base64",
+    mode
+  });
+}
+async function collectOutput(process2, maxBytes) {
+  const chunks = [];
+  let byteLength = 0;
+  for await (const chunk of process2.stdout()) {
+    const bytes = Buffer.from(chunk, "utf8");
+    byteLength += bytes.byteLength;
+    if (byteLength > maxBytes) {
+      await killProcess(process2);
+      throw new Error(`sandbox candidate output exceeds its ${maxBytes}-byte maximum`);
+    }
+    chunks.push(bytes);
+  }
+  return Uint8Array.from(Buffer.concat(chunks, byteLength));
+}
+async function awaitOutput(output, signal, deadlineAtMs) {
+  signal.throwIfAborted();
+  const remainingMs = deadlineAtMs - Date.now();
+  if (remainingMs <= 0) throw new Error("sandbox candidate output deadline expired");
+  let timer;
+  let onAbort;
+  try {
+    return await Promise.race([
+      output,
+      new Promise((_resolve, reject) => {
+        onAbort = () => reject(signal.reason ?? new Error("sandbox candidate output cancelled"));
+        signal.addEventListener("abort", onAbort, { once: true });
+        timer = setTimeout(
+          () => reject(new Error("sandbox candidate output deadline expired")),
+          remainingMs
+        );
+      })
+    ]);
+  } finally {
+    if (onAbort) signal.removeEventListener("abort", onAbort);
+    if (timer) clearTimeout(timer);
+  }
+}
+async function killProcess(process2) {
+  const before = await process2.status();
+  if (!before.running) return;
+  try {
+    await process2.kill("SIGKILL", { tree: true });
+  } catch (error) {
+    if ((await process2.status()).running) throw error;
+  }
+}
+function processTermination(status) {
+  if (status.running) throw new Error("candidate process is still running");
+  if (status.exitSignal) {
+    if (!/^SIG[A-Z0-9]+$/.test(status.exitSignal)) {
+      throw new Error("sandbox returned an invalid process signal");
+    }
+    return { kind: "signal", signal: status.exitSignal };
+  }
+  return { kind: "exit", exitCode: status.exitCode };
+}
+function matchesExecution(sandbox, request) {
+  return sandbox.metadata?.kind === "agent-candidate-execution" && sandbox.metadata.executionId === request.executionId && sandbox.metadata.executionPlanDigest === request.executionPlanDigest;
+}
+function sandboxOutputSpec(sandbox) {
+  const maxBytes = sandbox.metadata?.outputMaxBytes;
+  if (!Number.isSafeInteger(maxBytes) || Number(maxBytes) < 1) {
+    throw new Error("candidate sandbox output bound is unavailable");
+  }
+  return { maxBytes: Number(maxBytes) };
+}
+function executionKey(executionId, executionPlanDigest) {
+  return `${executionId}\0${executionPlanDigest}`;
+}
+function exactImage(image, manifestDigest) {
+  const marker = image.lastIndexOf("@");
+  if (marker < 0) return `${image}@${manifestDigest}`;
+  if (image.slice(marker + 1) !== manifestDigest) {
+    throw new Error("candidate container image conflicts with its resolved manifest");
+  }
+  return image;
+}
+function beneath(root, relativePath) {
+  if (posix.isAbsolute(relativePath)) throw new Error("candidate input path must be relative");
+  const path = posix.normalize(relativePath);
+  if (path === ".." || path.startsWith("../")) {
+    throw new Error("candidate input path escapes its execution root");
+  }
+  return posix.join(root, path);
+}
+
 // src/intelligence/with-intelligence.ts
 import { applyAgentProfileDiff } from "@tangle-network/agent-interface";
 function summarizeRuntimeEvents(events) {
@@ -1373,16 +1527,13 @@ function createIntelligenceClient(config) {
         } : {},
         ...record.runtimeEvents ? { "tangle.runtime.event_count": record.runtimeEvents.length } : {},
         ...record.candidateExecution ? {
-          "tangle.candidate.proposal_digest": record.candidateExecution.proposalDigest,
-          "tangle.candidate.review_digest": record.candidateExecution.reviewDigest,
-          "tangle.candidate.bundle_digest": record.candidateExecution.bundleDigest,
-          "tangle.candidate.execution_id": record.candidateExecution.executionId,
-          "tangle.candidate.execution_plan_digest": record.candidateExecution.executionPlanDigest,
-          "tangle.candidate.materialization_receipt_digest": record.candidateExecution.materializationReceiptDigest,
-          "tangle.candidate.succeeded": record.candidateExecution.succeeded,
-          ...record.candidateExecution.runReceiptDigest ? {
-            "tangle.candidate.run_receipt_digest": record.candidateExecution.runReceiptDigest
-          } : {}
+          "tangle.candidate.bundle_digest": record.candidateExecution.receipt.bundleDigest,
+          "tangle.candidate.experiment_digest": record.candidateExecution.materializationReceipt.executionPlan.material.runCell.experimentDigest,
+          "tangle.candidate.execution_id": record.candidateExecution.materializationReceipt.executionPlan.material.executionId,
+          "tangle.candidate.execution_plan_digest": record.candidateExecution.receipt.executionPlanDigest,
+          "tangle.candidate.materialization_receipt_digest": record.candidateExecution.receipt.materializationReceiptDigest,
+          "tangle.candidate.succeeded": record.candidateExecution.receipt.termination.kind === "exit" && record.candidateExecution.receipt.termination.exitCode === 0 && record.candidateExecution.receipt.benchmarkResult.material.passed,
+          "tangle.candidate.run_receipt_digest": record.candidateExecution.receipt.digest
         } : {}
       };
       if (record.profile) {
@@ -1532,28 +1683,41 @@ function createIntelligenceClient(config) {
   };
 }
 export {
+  AgentCandidateExperimentCellExecutionError,
   CapabilityNotAdmittedError,
+  buildAgentImprovementActivationTargets,
   compileEffort,
   composeCertifiedProfile,
   composeCertifiedProfileFromWire,
   composeCertifiedPrompt,
+  createAgentImprovementActivation,
+  createAgentImprovementActivationResult,
+  createAgentImprovementMeasuredComparison,
   createAgentImprovementProposal,
   createCertifiedPromptSource,
   createIntelligenceClient,
+  createSandboxCandidateExperimentExecutor,
   defaultEffortTier,
   defaultRedactor,
-  executeApprovedAgentCandidate,
+  executeAgentCandidateExperimentCell,
+  executeAgentImprovementActivation,
   isIntelligenceOff,
   manifestFromProfile,
   normalizeCertifiedProfile,
+  parseAgentCandidateProfileActivation as parseCandidateProfileMaterialization,
   proposeAgentImprovement,
   pullCertified,
   resolveEffort,
   resolveIntelligenceBaseUrl,
   resolveRedactor,
   reviewAgentImprovementProposal,
+  runAgentCandidateExperiment,
+  sandboxCandidateExperimentExecutionSupport,
+  verifyAgentImprovementActivation,
+  verifyAgentImprovementActivationResult,
   verifyAgentImprovementProposal,
   verifyAgentImprovementReview,
+  verifyCandidateExecutionEvidence,
   withIntelligence
 };
 //# sourceMappingURL=intelligence.js.map