@tangle-network/agent-runtime 0.37.0 → 0.38.0

package/dist/loops.d.ts

@@ -1,115 +1,14 @@
 import { AgentProfile, SandboxEvent } from '@tangle-network/sandbox';
 export { AgentProfile, CreateSandboxOptions, SandboxEvent, SandboxInstance } from '@tangle-network/sandbox';
-import { I as Iteration, D as Driver, L as LoopSandboxClient, A as AgentRunSpec, O as OutputAdapter, V as Validator, E as ExecCtx, a as LoopWinner, b as LoopResult } from './types-CmTjKLyB.js';
-export { c as LoopDecisionPayload, d as LoopEndedPayload, e as LoopIterationDispatchPayload, f as LoopIterationEndedPayload, g as LoopIterationStartedPayload, h as LoopPlanDescription, i as LoopPlanPayload, j as LoopSandboxPlacement, k as LoopStartedPayload, l as LoopTokenUsage, m as LoopTraceEmitter, n as LoopTraceEvent, o as ValidationCtx } from './types-CmTjKLyB.js';
+import { P as PlannerContext, T as TopologyPlanner } from './dynamic-DeOPeeAw.js';
+export { C as CreateDynamicDriverOptions, D as DynamicDecision, a as TopologyMove, c as createDynamicDriver, s as summarizeHistory } from './dynamic-DeOPeeAw.js';
+import { D as Driver, I as Iteration, L as LoopSandboxClient, A as AgentRunSpec, O as OutputAdapter, V as Validator, E as ExecCtx, a as LoopWinner, b as LoopResult } from './types-CmkQl8qE.js';
+export { c as LoopDecisionPayload, d as LoopEndedPayload, e as LoopIterationDispatchPayload, f as LoopIterationEndedPayload, g as LoopIterationStartedPayload, h as LoopPlanDescription, i as LoopPlanPayload, j as LoopSandboxPlacement, k as LoopStartedPayload, l as LoopTokenUsage, m as LoopTraceEmitter, n as LoopTraceEvent, o as ValidationCtx } from './types-CmkQl8qE.js';
 import { DefaultVerdict, AgentProfile as AgentProfile$1 } from '@tangle-network/agent-eval';
 export { DefaultVerdict } from '@tangle-network/agent-eval';
 import { Scenario, DispatchFn, ProfileDispatchFn } from '@tangle-network/agent-eval/campaign';
 import './types-CsCCryln.js';
 
-/**
- * @experimental
- *
- * Dynamic driver — the agent authors the loop topology at runtime.
- *
- * Where `refine` and `fanout-vote` encode a fixed shape as a pure function of
- * history, this driver delegates the per-round shape to an injected
- * `TopologyPlanner`. Each round the planner inspects the task + iteration
- * history and emits one `TopologyMove`:
- *   - `refine` → one task next round (optionally rewritten from the prior attempt)
- *   - `fanout` → N tasks next round (the kernel round-robins `agentRuns`, so a
- *     2-harness fanout dispatches branch 0 to harness A and branch 1 to harness B)
- *   - `stop`   → terminate; the kernel selects the winner across all iterations
- *
- * The planner is the brain; this driver is the structure. It maps moves onto
- * the kernel's `plan`/`decide` contract, enforces the iteration + fanout caps,
- * and fails loud on a malformed move. The planner is injected exactly like
- * `refine`'s `refineTask` and `fanout-vote`'s `selector` — so a test can drive
- * a deterministic policy through the real kernel, and production can wire it to
- * an LLM via `createSandboxPlanner`.
- *
- * Topology is orthogonal to harness: the planner never names a backend. Which
- * harness runs a branch is decided by the `AgentRunSpec` the kernel round-robins
- * to, so one dynamic driver works across claude-code, codex, opencode, pi —
- * including fanning a single round across several at once.
- */
-
-/** Terminal once `decide` returns `'done'` (a kernel terminal decision). */
-type DynamicDecision = 'continue' | 'done';
-/**
- * One topology decision for the next round. `fanout` carries explicit tasks
- * rather than a count so the planner can issue heterogeneous branches (a
- * different sub-task per harness); pass N copies of one task for a homogeneous
- * fanout that relies on `agentRuns` diversity instead.
- *
- * @experimental
- */
-type TopologyMove<Task> = {
-    kind: 'refine';
-    task: Task;
-    rationale?: string;
-} | {
-    kind: 'fanout';
-    tasks: Task[];
-    rationale?: string;
-} | {
-    kind: 'stop';
-    rationale?: string;
-};
-/** @experimental */
-interface PlannerContext<Task, Output> {
-    /** The root task the loop was invoked with — stable across rounds. */
-    task: Task;
-    /** Every iteration so far, in dispatch order, with outputs + verdicts. */
-    history: ReadonlyArray<Iteration<Task, Output>>;
-    /** `history.length` — iterations already spent. */
-    iterationsSpent: number;
-    /** Iterations left before the driver's `maxIterations` cap forces a stop. */
-    iterationsRemaining: number;
-}
-/**
- * Chooses the next topology move from the task + history. Sync or async; an
- * async planner is where an LLM call goes (see `createSandboxPlanner`).
- *
- * @experimental
- */
-type TopologyPlanner<Task, Output> = (ctx: PlannerContext<Task, Output>) => TopologyMove<Task> | Promise<TopologyMove<Task>>;
-/** @experimental */
-interface CreateDynamicDriverOptions<Task, Output> {
-    /** The agent-authored topology policy. Invoked once per round in `plan`. */
-    planner: TopologyPlanner<Task, Output>;
-    /**
-     * Hard safety cap on total iterations. When reached, the driver stops before
-     * consulting the planner. Default 8. Set the kernel's `runLoop`
-     * `maxIterations >= ` this so the driver's cap governs and the loop closes on
-     * a clean `'done'` rather than a truncated `'continue'`.
-     */
-    maxIterations?: number;
-    /** Max branches a single `fanout` move may dispatch. Default 4. */
-    maxFanout?: number;
-    /** Stable identifier surfaced in trace events. Default `'dynamic'`. */
-    name?: string;
-}
-/** @experimental */
-declare function createDynamicDriver<Task, Output>(options: CreateDynamicDriverOptions<Task, Output>): Driver<Task, Output, DynamicDecision>;
-/**
- * Compact, planner-friendly view of iteration history — what an LLM planner
- * needs to choose the next move without the raw event streams. Output is
- * truncated so a long run's prompt stays bounded.
- *
- * @experimental
- */
-declare function summarizeHistory<Task, Output>(history: ReadonlyArray<Iteration<Task, Output>>, opts?: {
-    maxOutputChars?: number;
-}): Array<{
-    index: number;
-    agentRunName: string;
-    valid?: boolean;
-    score?: number;
-    error?: string;
-    output?: string;
-}>;
-
 /**
  * @experimental
  *
@@ -413,4 +312,4 @@ interface UsageSink {
  */
 declare function reportLoopUsage<Task, Output, Decision>(cost: UsageSink, result: Pick<LoopResult<Task, Output, Decision>, 'costUsd' | 'tokenUsage'>, source?: string): void;
 
-export { AgentRunSpec, type CreateDynamicDriverOptions, type CreateFanoutVoteDriverOptions, type CreateRefineDriverOptions, type CreateSandboxPlannerOptions, Driver, type DynamicDecision, ExecCtx, type FanoutVoteDecision, type FanoutVoteScored, Iteration, type LoopDispatchOptions, type LoopOptionsForDispatch, LoopResult, LoopSandboxClient, LoopWinner, OutputAdapter, type PlannerContext, type RefineDecision, type RunLoopOptions, type TopologyMove, type TopologyMoveEnvelope, type TopologyPlanner, type UsageSink, Validator, createDynamicDriver, createFanoutVoteDriver, createRefineDriver, createSandboxPlanner, loopCampaignDispatch, loopDispatch, refineWinnerIndex, reportLoopUsage, runLoop, scoreFanoutVoteIterations, summarizeHistory };
+export { AgentRunSpec, type CreateFanoutVoteDriverOptions, type CreateRefineDriverOptions, type CreateSandboxPlannerOptions, Driver, ExecCtx, type FanoutVoteDecision, type FanoutVoteScored, Iteration, type LoopDispatchOptions, type LoopOptionsForDispatch, LoopResult, LoopSandboxClient, LoopWinner, OutputAdapter, PlannerContext, type RefineDecision, type RunLoopOptions, type TopologyMoveEnvelope, TopologyPlanner, type UsageSink, Validator, createFanoutVoteDriver, createRefineDriver, createSandboxPlanner, loopCampaignDispatch, loopDispatch, refineWinnerIndex, reportLoopUsage, runLoop, scoreFanoutVoteIterations };

package/dist/mcp/index.d.ts

@@ -1,6 +1,6 @@
-import { L as LoopSandboxClient, j as LoopSandboxPlacement, m as LoopTraceEmitter } from '../types-CmTjKLyB.js';
-import { F as FleetHandle, D as DelegationExecutor, a as DelegateFeedbackArgs, b as DelegationFeedbackSnapshot, c as DelegationProfile, d as DelegateCodeArgs, e as DelegateResearchArgs, f as DelegationStatus, g as DelegationProgress, h as DelegationResultPayload, i as DelegationError, j as DelegationStatusResult, k as DelegationHistoryArgs, l as DelegationHistoryEntry, C as CoderDelegate, R as ResearcherDelegate, m as DelegateCodeResult, n as DelegateFeedbackResult, o as ResearchSource, p as DelegateResearchResult, q as DelegationHistoryResult, r as DelegationStatusArgs, O as OtelExporter } from '../otel-export-DgFMwsVy.js';
-export { s as CoderReview, t as CoderReviewer, u as CoderWinnerSelection, v as CreateDefaultCoderDelegateOptions, w as DelegateCodeConfig, x as DelegateResearchConfig, y as DelegateRunCtx, z as FeedbackRating, A as FeedbackRefersTo, B as FleetWorkspaceExecutorOptions, E as ResearchOutputShape, S as SiblingSandboxExecutorOptions, G as createDefaultCoderDelegate, H as createFleetWorkspaceExecutor, I as createSiblingSandboxExecutor, J as mcpToolsForRuntimeMcp, K as mcpToolsForRuntimeMcpSubset } from '../otel-export-DgFMwsVy.js';
+import { L as LoopSandboxClient, j as LoopSandboxPlacement, m as LoopTraceEmitter } from '../types-CmkQl8qE.js';
+import { F as FleetHandle, D as DelegationExecutor, a as DelegateFeedbackArgs, b as DelegationFeedbackSnapshot, c as DelegationProfile, d as DelegateCodeArgs, e as DelegateResearchArgs, f as DelegationStatus, g as DelegationProgress, h as DelegationResultPayload, i as DelegationError, j as DelegationStatusResult, k as DelegationHistoryArgs, l as DelegationHistoryEntry, C as CoderDelegate, R as ResearcherDelegate, m as DelegateCodeResult, n as DelegateFeedbackResult, o as ResearchSource, p as DelegateResearchResult, q as DelegationHistoryResult, r as DelegationStatusArgs, O as OtelExporter } from '../otel-export-CNmeg_7B.js';
+export { s as CoderReview, t as CoderReviewer, u as CoderWinnerSelection, v as CreateDefaultCoderDelegateOptions, w as CreateKbGateOptions, x as DelegateCodeConfig, y as DelegateResearchConfig, z as DelegateRunCtx, A as FactCandidate, B as FactJudge, E as FactJudgeVerdict, G as FeedbackRating, H as FeedbackRefersTo, I as FleetWorkspaceExecutorOptions, K as KbGateResult, J as ResearchOutputShape, S as SiblingSandboxExecutorOptions, L as createDefaultCoderDelegate, M as createFleetWorkspaceExecutor, N as createKbGate, P as createSiblingSandboxExecutor, Q as mcpToolsForRuntimeMcp, T as mcpToolsForRuntimeMcpSubset } from '../otel-export-CNmeg_7B.js';
 import { L as LocalHarness, r as runLocalHarness } from '../local-harness-KrdFTY5R.js';
 export { a as LocalHarnessResult, R as RunLocalHarnessOptions } from '../local-harness-KrdFTY5R.js';
 import '@tangle-network/agent-eval';
@@ -285,81 +285,6 @@ interface InProcessExecutorDescribePlacement extends LoopSandboxPlacement {
  */
 declare function createInProcessExecutor(options: InProcessExecutorOptions): DelegationExecutor;
 
-/**
- * @experimental
- *
- * `createKbGate` — the valid-only knowledge-base growth gate, distilled from
- * physim's KB-research subsystem. A research-in-a-loop delegate (or any KB
- * writer) runs candidate facts through this before persisting, so the KB grows
- * with ONLY grounded facts — hallucinated, unsourced, or laundered claims are
- * vetoed at the gate.
- *
- * Fail-closed by construction: every judge must `accept`; the FIRST veto wins
- * and the fact is rejected. The non-negotiable floor (always on, can't be
- * disabled) is the **passage-present guard** — a fact's `verbatimPassage` MUST
- * literally appear in its `sourceText`. That single check kills the dominant
- * failure mode (a confident claim decoupled from any real source).
- *
- * Pure + dependency-free: it operates on fact candidates, not on a store, so it
- * composes with `@tangle-network/agent-knowledge` or any persistence layer
- * without importing it. The remediation policy (correct-on-veto vs
- * escalate-as-unverified) is the caller's — this returns the verdict; it never
- * drops a fact silently.
- */
-/** @experimental A fact proposed for the KB, with its grounding. */
-interface FactCandidate {
-    /** The atomic claim text. */
-    claim: string;
-    /** Optional extracted value (number or string) the claim asserts. */
-    value?: string | number;
-    /** Verbatim span lifted from the source that backs the claim. */
-    verbatimPassage: string;
-    /** The raw source text the passage must be grounded in. */
-    sourceText: string;
-    /** Where the fact claims to come from — checked for circular/self citations. */
-    citation?: string;
-}
-/** @experimental */
-interface FactJudgeVerdict {
-    accept: boolean;
-    reason?: string;
-}
-/** @experimental A pluggable fact validator. Throw is NOT allowed — return a
- *  verdict; a thrown judge is a programmer error, not a veto. */
-interface FactJudge {
-    name: string;
-    judge(candidate: FactCandidate): FactJudgeVerdict | Promise<FactJudgeVerdict>;
-}
-/** @experimental */
-interface KbGateResult {
-    accepted: boolean;
-    /** Name of the judge that vetoed; undefined when accepted. */
-    vetoedBy?: string;
-    reason?: string;
-}
-/** @experimental */
-interface CreateKbGateOptions {
-    /** Extra judges appended after the built-in floor (e.g. an LLM judge). */
-    judges?: FactJudge[];
-    /** Minimum verbatim-passage length. Default 12 — kills empty/stub passages. */
-    minPassageChars?: number;
-    /**
-     * Citation tokens that denote a SELF-generated artifact (e.g. `'spec'`,
-     * `'cad_params'`, `'requirements'`). A citation naming one is circular
-     * (laundering) — the fact cites a derived artifact, not a real source.
-     * Default `[]` (no circular check unless the consumer declares its kinds).
-     */
-    selfArtifactKinds?: string[];
-}
-/**
- * @experimental
- *
- * Build a fail-closed KB gate. The returned function runs the built-in floor
- * (passage-non-empty → passage-present → value-in-passage → no-circular-citation)
- * then any consumer judges, returning on the first veto.
- */
-declare function createKbGate(options?: CreateKbGateOptions): (candidate: FactCandidate) => Promise<KbGateResult>;
-
 /**
  * @experimental
  *
@@ -947,4 +872,4 @@ declare function createPropagatingTraceEmitter(ctx: TraceContext): {
  */
 declare function traceContextToEnv(ctx: TraceContext): Record<string, string>;
 
-export { CoderDelegate, type CreateKbGateOptions, type CreateWorktreeOptions, DELEGATE_CODE_DESCRIPTION, DELEGATE_CODE_INPUT_SCHEMA, DELEGATE_CODE_TOOL_NAME, DELEGATE_FEEDBACK_DESCRIPTION, DELEGATE_FEEDBACK_INPUT_SCHEMA, DELEGATE_FEEDBACK_TOOL_NAME, DELEGATE_RESEARCH_DESCRIPTION, DELEGATE_RESEARCH_INPUT_SCHEMA, DELEGATE_RESEARCH_TOOL_NAME, DELEGATION_HISTORY_DESCRIPTION, DELEGATION_HISTORY_INPUT_SCHEMA, DELEGATION_HISTORY_TOOL_NAME, DELEGATION_STATUS_DESCRIPTION, DELEGATION_STATUS_INPUT_SCHEMA, DELEGATION_STATUS_TOOL_NAME, DelegateCodeArgs, DelegateCodeResult, DelegateFeedbackArgs, DelegateFeedbackResult, DelegateResearchArgs, DelegateResearchResult, DelegationError, DelegationExecutor, DelegationFeedbackSnapshot, DelegationHistoryArgs, DelegationHistoryEntry, DelegationHistoryResult, DelegationProfile, DelegationProgress, type DelegationRecord, DelegationResultPayload, DelegationStatus, DelegationStatusArgs, DelegationStatusResult, DelegationTaskQueue, type DelegationTaskQueueOptions, type DetectExecutorArgs, type DiffOptions, type DiffResult, type FactCandidate, type FactJudge, type FactJudgeVerdict, type FeedbackEvent, type FeedbackStore, FleetHandle, type GitRunner, InMemoryFeedbackStore, type InProcessExecutorDescribePlacement, type InProcessExecutorOptions, type JsonRpcMessage, type JsonRpcResponse, type KbGateResult, LocalHarness, type McpServer, type McpServerOptions, type McpToolDescriptor, type McpTransport, type RemoveWorktreeOptions, ResearchSource, ResearcherDelegate, type SubmitInput, type SubmitOutput, type TraceContext, type WorktreeHandle, captureWorktreeDiff, createDelegateCodeHandler, createDelegateFeedbackHandler, createDelegateResearchHandler, createDelegationHistoryHandler, createDelegationStatusHandler, createInProcessExecutor, createInProcessTransport, createKbGate, createMcpServer, createPropagatingTraceEmitter, createWorktree, detectExecutor, eventToSnapshot, hashIdempotencyInput, readTraceContextFromEnv, removeWorktree, runLocalHarness, traceContextToEnv, validateDelegateCodeArgs, validateDelegateFeedbackArgs, validateDelegateResearchArgs, validateDelegationHistoryArgs, validateDelegationStatusArgs };
+export { CoderDelegate, type CreateWorktreeOptions, DELEGATE_CODE_DESCRIPTION, DELEGATE_CODE_INPUT_SCHEMA, DELEGATE_CODE_TOOL_NAME, DELEGATE_FEEDBACK_DESCRIPTION, DELEGATE_FEEDBACK_INPUT_SCHEMA, DELEGATE_FEEDBACK_TOOL_NAME, DELEGATE_RESEARCH_DESCRIPTION, DELEGATE_RESEARCH_INPUT_SCHEMA, DELEGATE_RESEARCH_TOOL_NAME, DELEGATION_HISTORY_DESCRIPTION, DELEGATION_HISTORY_INPUT_SCHEMA, DELEGATION_HISTORY_TOOL_NAME, DELEGATION_STATUS_DESCRIPTION, DELEGATION_STATUS_INPUT_SCHEMA, DELEGATION_STATUS_TOOL_NAME, DelegateCodeArgs, DelegateCodeResult, DelegateFeedbackArgs, DelegateFeedbackResult, DelegateResearchArgs, DelegateResearchResult, DelegationError, DelegationExecutor, DelegationFeedbackSnapshot, DelegationHistoryArgs, DelegationHistoryEntry, DelegationHistoryResult, DelegationProfile, DelegationProgress, type DelegationRecord, DelegationResultPayload, DelegationStatus, DelegationStatusArgs, DelegationStatusResult, DelegationTaskQueue, type DelegationTaskQueueOptions, type DetectExecutorArgs, type DiffOptions, type DiffResult, type FeedbackEvent, type FeedbackStore, FleetHandle, type GitRunner, InMemoryFeedbackStore, type InProcessExecutorDescribePlacement, type InProcessExecutorOptions, type JsonRpcMessage, type JsonRpcResponse, LocalHarness, type McpServer, type McpServerOptions, type McpToolDescriptor, type McpTransport, type RemoveWorktreeOptions, ResearchSource, ResearcherDelegate, type SubmitInput, type SubmitOutput, type TraceContext, type WorktreeHandle, captureWorktreeDiff, createDelegateCodeHandler, createDelegateFeedbackHandler, createDelegateResearchHandler, createDelegationHistoryHandler, createDelegationStatusHandler, createInProcessExecutor, createInProcessTransport, createMcpServer, createPropagatingTraceEmitter, createWorktree, detectExecutor, eventToSnapshot, hashIdempotencyInput, readTraceContextFromEnv, removeWorktree, runLocalHarness, traceContextToEnv, validateDelegateCodeArgs, validateDelegateFeedbackArgs, validateDelegateResearchArgs, validateDelegationHistoryArgs, validateDelegationStatusArgs };

package/dist/mcp/index.js

@@ -9,10 +9,11 @@ import {
 } from "../chunk-M65QJD35.js";
 import {
   buildLoopOtelSpans,
+  createKbGate,
   createOtelExporter,
   mcpToolsForRuntimeMcp,
   mcpToolsForRuntimeMcpSubset
-} from "../chunk-T3GJBKHA.js";
+} from "../chunk-Z523NPJK.js";
 import {
   DELEGATE_CODE_DESCRIPTION,
   DELEGATE_CODE_INPUT_SCHEMA,
@@ -56,62 +57,6 @@ import "../chunk-PY6NMZYX.js";
 import "../chunk-SQSCRJ7U.js";
 import "../chunk-DGUM43GV.js";
 
-// src/mcp/kb-gate.ts
-var norm = (s) => s.toLowerCase().replace(/\s+/g, " ").trim();
-function valueAppears(value, passageNorm) {
-  if (passageNorm.includes(norm(String(value)))) return true;
-  if (typeof value !== "number" || !Number.isFinite(value)) return false;
-  const forms = [value.toLocaleString("en-US")];
-  if (Math.abs(value) >= 1e9) forms.push(`${trimZero(value / 1e9)} billion`);
-  if (Math.abs(value) >= 1e6) forms.push(`${trimZero(value / 1e6)} million`);
-  return forms.some((f) => passageNorm.includes(norm(f)));
-}
-function trimZero(n) {
-  return Number.isInteger(n) ? String(n) : String(Number(n.toFixed(2)));
-}
-function builtinJudges(minPassageChars, selfArtifactKinds) {
-  const kinds = selfArtifactKinds.map((k) => k.toLowerCase());
-  return [
-    {
-      name: "passage-non-empty",
-      judge: (c) => c.verbatimPassage.trim().length >= minPassageChars ? { accept: true } : { accept: false, reason: `passage shorter than ${minPassageChars} chars` }
-    },
-    {
-      // THE anti-hallucination floor — the passage must literally be in the source.
-      name: "passage-present",
-      judge: (c) => norm(c.sourceText).includes(norm(c.verbatimPassage)) ? { accept: true } : { accept: false, reason: "verbatim passage not found in source (unbacked fact)" }
-    },
-    {
-      name: "value-in-passage",
-      judge: (c) => c.value === void 0 || valueAppears(c.value, norm(c.verbatimPassage)) ? { accept: true } : { accept: false, reason: `value ${JSON.stringify(c.value)} not present in passage` }
-    },
-    {
-      name: "no-circular-citation",
-      judge: (c) => {
-        if (!c.citation || kinds.length === 0) return { accept: true };
-        const cite = c.citation.toLowerCase();
-        const hit = kinds.find((k) => cite.includes(k));
-        return hit ? { accept: false, reason: `circular citation to self-generated artifact "${hit}"` } : { accept: true };
-      }
-    }
-  ];
-}
-function createKbGate(options = {}) {
-  const judges = [
-    ...builtinJudges(options.minPassageChars ?? 12, options.selfArtifactKinds ?? []),
-    ...options.judges ?? []
-  ];
-  return async (candidate) => {
-    for (const j of judges) {
-      const verdict = await j.judge(candidate);
-      if (!verdict.accept) {
-        return { accepted: false, vetoedBy: j.name, reason: verdict.reason };
-      }
-    }
-    return { accepted: true };
-  };
-}
-
 // src/mcp/trace-propagation.ts
 function readTraceContextFromEnv() {
   const traceId = process.env.TRACE_ID || generateTraceId();

package/dist/mcp/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/mcp/kb-gate.ts","../../src/mcp/trace-propagation.ts"],"sourcesContent":["/**\n * @experimental\n *\n * `createKbGate` — the valid-only knowledge-base growth gate, distilled from\n * physim's KB-research subsystem. A research-in-a-loop delegate (or any KB\n * writer) runs candidate facts through this before persisting, so the KB grows\n * with ONLY grounded facts — hallucinated, unsourced, or laundered claims are\n * vetoed at the gate.\n *\n * Fail-closed by construction: every judge must `accept`; the FIRST veto wins\n * and the fact is rejected. The non-negotiable floor (always on, can't be\n * disabled) is the **passage-present guard** — a fact's `verbatimPassage` MUST\n * literally appear in its `sourceText`. That single check kills the dominant\n * failure mode (a confident claim decoupled from any real source).\n *\n * Pure + dependency-free: it operates on fact candidates, not on a store, so it\n * composes with `@tangle-network/agent-knowledge` or any persistence layer\n * without importing it. The remediation policy (correct-on-veto vs\n * escalate-as-unverified) is the caller's — this returns the verdict; it never\n * drops a fact silently.\n */\n\n/** @experimental A fact proposed for the KB, with its grounding. */\nexport interface FactCandidate {\n  /** The atomic claim text. */\n  claim: string\n  /** Optional extracted value (number or string) the claim asserts. */\n  value?: string | number\n  /** Verbatim span lifted from the source that backs the claim. */\n  verbatimPassage: string\n  /** The raw source text the passage must be grounded in. */\n  sourceText: string\n  /** Where the fact claims to come from — checked for circular/self citations. */\n  citation?: string\n}\n\n/** @experimental */\nexport interface FactJudgeVerdict {\n  accept: boolean\n  reason?: string\n}\n\n/** @experimental A pluggable fact validator. Throw is NOT allowed — return a\n *  verdict; a thrown judge is a programmer error, not a veto. */\nexport interface FactJudge {\n  name: string\n  judge(candidate: FactCandidate): FactJudgeVerdict | Promise<FactJudgeVerdict>\n}\n\n/** @experimental */\nexport interface KbGateResult {\n  accepted: boolean\n  /** Name of the judge that vetoed; undefined when accepted. */\n  vetoedBy?: string\n  reason?: string\n}\n\n/** @experimental */\nexport interface CreateKbGateOptions {\n  /** Extra judges appended after the built-in floor (e.g. an LLM judge). */\n  judges?: FactJudge[]\n  /** Minimum verbatim-passage length. Default 12 — kills empty/stub passages. */\n  minPassageChars?: number\n  /**\n   * Citation tokens that denote a SELF-generated artifact (e.g. `'spec'`,\n   * `'cad_params'`, `'requirements'`). A citation naming one is circular\n   * (laundering) — the fact cites a derived artifact, not a real source.\n   * Default `[]` (no circular check unless the consumer declares its kinds).\n   */\n  selfArtifactKinds?: string[]\n}\n\nconst norm = (s: string): string => s.toLowerCase().replace(/\\s+/g, ' ').trim()\n\n/** Does `value` appear in the (normalized) passage — literally, comma-grouped,\n *  or in billion/million shorthand (the forms a source actually writes). */\nfunction valueAppears(value: string | number, passageNorm: string): boolean {\n  if (passageNorm.includes(norm(String(value)))) return true\n  if (typeof value !== 'number' || !Number.isFinite(value)) return false\n  const forms = [value.toLocaleString('en-US')]\n  if (Math.abs(value) >= 1e9) forms.push(`${trimZero(value / 1e9)} billion`)\n  if (Math.abs(value) >= 1e6) forms.push(`${trimZero(value / 1e6)} million`)\n  return forms.some((f) => passageNorm.includes(norm(f)))\n}\n\nfunction trimZero(n: number): string {\n  return Number.isInteger(n) ? String(n) : String(Number(n.toFixed(2)))\n}\n\n/** The always-on floor judges. Order matters: cheapest / most-fundamental first. */\nfunction builtinJudges(minPassageChars: number, selfArtifactKinds: string[]): FactJudge[] {\n  const kinds = selfArtifactKinds.map((k) => k.toLowerCase())\n  return [\n    {\n      name: 'passage-non-empty',\n      judge: (c) =>\n        c.verbatimPassage.trim().length >= minPassageChars\n          ? { accept: true }\n          : { accept: false, reason: `passage shorter than ${minPassageChars} chars` },\n    },\n    {\n      // THE anti-hallucination floor — the passage must literally be in the source.\n      name: 'passage-present',\n      judge: (c) =>\n        norm(c.sourceText).includes(norm(c.verbatimPassage))\n          ? { accept: true }\n          : { accept: false, reason: 'verbatim passage not found in source (unbacked fact)' },\n    },\n    {\n      name: 'value-in-passage',\n      judge: (c) =>\n        c.value === undefined || valueAppears(c.value, norm(c.verbatimPassage))\n          ? { accept: true }\n          : { accept: false, reason: `value ${JSON.stringify(c.value)} not present in passage` },\n    },\n    {\n      name: 'no-circular-citation',\n      judge: (c) => {\n        if (!c.citation || kinds.length === 0) return { accept: true }\n        const cite = c.citation.toLowerCase()\n        const hit = kinds.find((k) => cite.includes(k))\n        return hit\n          ? { accept: false, reason: `circular citation to self-generated artifact \"${hit}\"` }\n          : { accept: true }\n      },\n    },\n  ]\n}\n\n/**\n * @experimental\n *\n * Build a fail-closed KB gate. The returned function runs the built-in floor\n * (passage-non-empty → passage-present → value-in-passage → no-circular-citation)\n * then any consumer judges, returning on the first veto.\n */\nexport function createKbGate(\n  options: CreateKbGateOptions = {},\n): (candidate: FactCandidate) => Promise<KbGateResult> {\n  const judges = [\n    ...builtinJudges(options.minPassageChars ?? 12, options.selfArtifactKinds ?? []),\n    ...(options.judges ?? []),\n  ]\n  return async (candidate) => {\n    for (const j of judges) {\n      const verdict = await j.judge(candidate)\n      if (!verdict.accept) {\n        return { accepted: false, vetoedBy: j.name, reason: verdict.reason }\n      }\n    }\n    return { accepted: true }\n  }\n}\n","/**\n * @experimental\n *\n * Trace context propagation for MCP subprocess.\n *\n * When the MCP server is launched as a child process by a sandbox harness,\n * the parent passes trace context via environment variables:\n *\n *   TRACE_ID=<current-run-trace-id>\n *   PARENT_SPAN_ID=<span-that-dispatched-the-delegation>\n *\n * The MCP server reads these at startup and uses them as the root of its\n * internal trace tree. All spans emitted by `runLoop` invocations inside\n * the MCP are children of the parent's delegation span.\n *\n * When these env vars are absent, the MCP generates a fresh trace root —\n * the server operates standalone without trace joining.\n */\n\nimport type { LoopTraceEmitter, LoopTraceEvent } from '../loops/types'\nimport type { OtelExporter } from '../otel-export'\nimport { buildLoopOtelSpans, createOtelExporter } from '../otel-export'\n\nexport interface TraceContext {\n  /** Trace id inherited from the parent process, or a fresh one. */\n  traceId: string\n  /** Parent span id from the delegation that launched this MCP server. */\n  parentSpanId?: string\n}\n\n/**\n * Read trace context from the process environment.\n * Returns a context with inherited ids or a freshly generated root.\n */\nexport function readTraceContextFromEnv(): TraceContext {\n  const traceId = process.env.TRACE_ID || generateTraceId()\n  const parentSpanId = process.env.PARENT_SPAN_ID || undefined\n  return { traceId, parentSpanId }\n}\n\n/**\n * Create a LoopTraceEmitter that:\n *   1. Parents all spans under the inherited PARENT_SPAN_ID.\n *   2. Exports spans to OTEL when OTEL_EXPORTER_OTLP_ENDPOINT is set.\n *\n * Returns both the emitter and the optional exporter handle for shutdown.\n */\nexport function createPropagatingTraceEmitter(ctx: TraceContext): {\n  emitter: LoopTraceEmitter\n  exporter: OtelExporter | undefined\n  context: TraceContext\n} {\n  const exporter = createOtelExporter()\n\n  // Buffer events per loop run, then emit the full nested span tree on\n  // `loop.ended` so the topology hierarchy (loop → round → branch) reaches the\n  // OTLP collector — not a flat list of zero-duration point spans. A run that\n  // never reaches `loop.ended` (hard abort) drops its buffer; acceptable for\n  // the short-lived MCP subprocess.\n  const buffers = new Map<string, LoopTraceEvent[]>()\n\n  const emitter: LoopTraceEmitter = {\n    emit(event: LoopTraceEvent) {\n      if (!exporter) return\n      const buf = buffers.get(event.runId)\n      if (buf) buf.push(event)\n      else buffers.set(event.runId, [event])\n      if (event.kind === 'loop.ended') {\n        const events = buffers.get(event.runId) ?? [event]\n        buffers.delete(event.runId)\n        for (const span of buildLoopOtelSpans(events, ctx.traceId, ctx.parentSpanId)) {\n          exporter.exportSpan(span)\n        }\n      }\n    },\n  }\n\n  return { emitter, exporter, context: ctx }\n}\n\n/**\n * Build env vars to pass to a child MCP subprocess so it inherits the\n * current trace context.\n */\nexport function traceContextToEnv(ctx: TraceContext): Record<string, string> {\n  const env: Record<string, string> = { TRACE_ID: ctx.traceId }\n  if (ctx.parentSpanId) env.PARENT_SPAN_ID = ctx.parentSpanId\n  return env\n}\n\nfunction generateTraceId(): string {\n  const bytes = new Uint8Array(16)\n  if (typeof globalThis.crypto?.getRandomValues === 'function') {\n    globalThis.crypto.getRandomValues(bytes)\n  } else {\n    for (let i = 0; i < 16; i++) bytes[i] = Math.floor(Math.random() * 256)\n  }\n  return Array.from(bytes)\n    .map((b) => b.toString(16).padStart(2, '0'))\n    .join('')\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwEA,IAAM,OAAO,CAAC,MAAsB,EAAE,YAAY,EAAE,QAAQ,QAAQ,GAAG,EAAE,KAAK;AAI9E,SAAS,aAAa,OAAwB,aAA8B;AAC1E,MAAI,YAAY,SAAS,KAAK,OAAO,KAAK,CAAC,CAAC,EAAG,QAAO;AACtD,MAAI,OAAO,UAAU,YAAY,CAAC,OAAO,SAAS,KAAK,EAAG,QAAO;AACjE,QAAM,QAAQ,CAAC,MAAM,eAAe,OAAO,CAAC;AAC5C,MAAI,KAAK,IAAI,KAAK,KAAK,IAAK,OAAM,KAAK,GAAG,SAAS,QAAQ,GAAG,CAAC,UAAU;AACzE,MAAI,KAAK,IAAI,KAAK,KAAK,IAAK,OAAM,KAAK,GAAG,SAAS,QAAQ,GAAG,CAAC,UAAU;AACzE,SAAO,MAAM,KAAK,CAAC,MAAM,YAAY,SAAS,KAAK,CAAC,CAAC,CAAC;AACxD;AAEA,SAAS,SAAS,GAAmB;AACnC,SAAO,OAAO,UAAU,CAAC,IAAI,OAAO,CAAC,IAAI,OAAO,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC;AACtE;AAGA,SAAS,cAAc,iBAAyB,mBAA0C;AACxF,QAAM,QAAQ,kBAAkB,IAAI,CAAC,MAAM,EAAE,YAAY,CAAC;AAC1D,SAAO;AAAA,IACL;AAAA,MACE,MAAM;AAAA,MACN,OAAO,CAAC,MACN,EAAE,gBAAgB,KAAK,EAAE,UAAU,kBAC/B,EAAE,QAAQ,KAAK,IACf,EAAE,QAAQ,OAAO,QAAQ,wBAAwB,eAAe,SAAS;AAAA,IACjF;AAAA,IACA;AAAA;AAAA,MAEE,MAAM;AAAA,MACN,OAAO,CAAC,MACN,KAAK,EAAE,UAAU,EAAE,SAAS,KAAK,EAAE,eAAe,CAAC,IAC/C,EAAE,QAAQ,KAAK,IACf,EAAE,QAAQ,OAAO,QAAQ,uDAAuD;AAAA,IACxF;AAAA,IACA;AAAA,MACE,MAAM;AAAA,MACN,OAAO,CAAC,MACN,EAAE,UAAU,UAAa,aAAa,EAAE,OAAO,KAAK,EAAE,eAAe,CAAC,IAClE,EAAE,QAAQ,KAAK,IACf,EAAE,QAAQ,OAAO,QAAQ,SAAS,KAAK,UAAU,EAAE,KAAK,CAAC,0BAA0B;AAAA,IAC3F;AAAA,IACA;AAAA,MACE,MAAM;AAAA,MACN,OAAO,CAAC,MAAM;AACZ,YAAI,CAAC,EAAE,YAAY,MAAM,WAAW,EAAG,QAAO,EAAE,QAAQ,KAAK;AAC7D,cAAM,OAAO,EAAE,SAAS,YAAY;AACpC,cAAM,MAAM,MAAM,KAAK,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC;AAC9C,eAAO,MACH,EAAE,QAAQ,OAAO,QAAQ,iDAAiD,GAAG,IAAI,IACjF,EAAE,QAAQ,KAAK;AAAA,MACrB;AAAA,IACF;AAAA,EACF;AACF;AASO,SAAS,aACd,UAA+B,CAAC,GACqB;AACrD,QAAM,SAAS;AAAA,IACb,GAAG,cAAc,QAAQ,mBAAmB,IAAI,QAAQ,qBAAqB,CAAC,CAAC;AAAA,IAC/E,GAAI,QAAQ,UAAU,CAAC;AAAA,EACzB;AACA,SAAO,OAAO,cAAc;AAC1B,eAAW,KAAK,QAAQ;AACtB,YAAM,UAAU,MAAM,EAAE,MAAM,SAAS;AACvC,UAAI,CAAC,QAAQ,QAAQ;AACnB,eAAO,EAAE,UAAU,OAAO,UAAU,EAAE,MAAM,QAAQ,QAAQ,OAAO;AAAA,MACrE;AAAA,IACF;AACA,WAAO,EAAE,UAAU,KAAK;AAAA,EAC1B;AACF;;;ACtHO,SAAS,0BAAwC;AACtD,QAAM,UAAU,QAAQ,IAAI,YAAY,gBAAgB;AACxD,QAAM,eAAe,QAAQ,IAAI,kBAAkB;AACnD,SAAO,EAAE,SAAS,aAAa;AACjC;AASO,SAAS,8BAA8B,KAI5C;AACA,QAAM,WAAW,mBAAmB;AAOpC,QAAM,UAAU,oBAAI,IAA8B;AAElD,QAAM,UAA4B;AAAA,IAChC,KAAK,OAAuB;AAC1B,UAAI,CAAC,SAAU;AACf,YAAM,MAAM,QAAQ,IAAI,MAAM,KAAK;AACnC,UAAI,IAAK,KAAI,KAAK,KAAK;AAAA,UAClB,SAAQ,IAAI,MAAM,OAAO,CAAC,KAAK,CAAC;AACrC,UAAI,MAAM,SAAS,cAAc;AAC/B,cAAM,SAAS,QAAQ,IAAI,MAAM,KAAK,KAAK,CAAC,KAAK;AACjD,gBAAQ,OAAO,MAAM,KAAK;AAC1B,mBAAW,QAAQ,mBAAmB,QAAQ,IAAI,SAAS,IAAI,YAAY,GAAG;AAC5E,mBAAS,WAAW,IAAI;AAAA,QAC1B;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAEA,SAAO,EAAE,SAAS,UAAU,SAAS,IAAI;AAC3C;AAMO,SAAS,kBAAkB,KAA2C;AAC3E,QAAM,MAA8B,EAAE,UAAU,IAAI,QAAQ;AAC5D,MAAI,IAAI,aAAc,KAAI,iBAAiB,IAAI;AAC/C,SAAO;AACT;AAEA,SAAS,kBAA0B;AACjC,QAAM,QAAQ,IAAI,WAAW,EAAE;AAC/B,MAAI,OAAO,WAAW,QAAQ,oBAAoB,YAAY;AAC5D,eAAW,OAAO,gBAAgB,KAAK;AAAA,EACzC,OAAO;AACL,aAAS,IAAI,GAAG,IAAI,IAAI,IAAK,OAAM,CAAC,IAAI,KAAK,MAAM,KAAK,OAAO,IAAI,GAAG;AAAA,EACxE;AACA,SAAO,MAAM,KAAK,KAAK,EACpB,IAAI,CAAC,MAAM,EAAE,SAAS,EAAE,EAAE,SAAS,GAAG,GAAG,CAAC,EAC1C,KAAK,EAAE;AACZ;","names":[]}
+{"version":3,"sources":["../../src/mcp/trace-propagation.ts"],"sourcesContent":["/**\n * @experimental\n *\n * Trace context propagation for MCP subprocess.\n *\n * When the MCP server is launched as a child process by a sandbox harness,\n * the parent passes trace context via environment variables:\n *\n *   TRACE_ID=<current-run-trace-id>\n *   PARENT_SPAN_ID=<span-that-dispatched-the-delegation>\n *\n * The MCP server reads these at startup and uses them as the root of its\n * internal trace tree. All spans emitted by `runLoop` invocations inside\n * the MCP are children of the parent's delegation span.\n *\n * When these env vars are absent, the MCP generates a fresh trace root —\n * the server operates standalone without trace joining.\n */\n\nimport type { LoopTraceEmitter, LoopTraceEvent } from '../loops/types'\nimport type { OtelExporter } from '../otel-export'\nimport { buildLoopOtelSpans, createOtelExporter } from '../otel-export'\n\nexport interface TraceContext {\n  /** Trace id inherited from the parent process, or a fresh one. */\n  traceId: string\n  /** Parent span id from the delegation that launched this MCP server. */\n  parentSpanId?: string\n}\n\n/**\n * Read trace context from the process environment.\n * Returns a context with inherited ids or a freshly generated root.\n */\nexport function readTraceContextFromEnv(): TraceContext {\n  const traceId = process.env.TRACE_ID || generateTraceId()\n  const parentSpanId = process.env.PARENT_SPAN_ID || undefined\n  return { traceId, parentSpanId }\n}\n\n/**\n * Create a LoopTraceEmitter that:\n *   1. Parents all spans under the inherited PARENT_SPAN_ID.\n *   2. Exports spans to OTEL when OTEL_EXPORTER_OTLP_ENDPOINT is set.\n *\n * Returns both the emitter and the optional exporter handle for shutdown.\n */\nexport function createPropagatingTraceEmitter(ctx: TraceContext): {\n  emitter: LoopTraceEmitter\n  exporter: OtelExporter | undefined\n  context: TraceContext\n} {\n  const exporter = createOtelExporter()\n\n  // Buffer events per loop run, then emit the full nested span tree on\n  // `loop.ended` so the topology hierarchy (loop → round → branch) reaches the\n  // OTLP collector — not a flat list of zero-duration point spans. A run that\n  // never reaches `loop.ended` (hard abort) drops its buffer; acceptable for\n  // the short-lived MCP subprocess.\n  const buffers = new Map<string, LoopTraceEvent[]>()\n\n  const emitter: LoopTraceEmitter = {\n    emit(event: LoopTraceEvent) {\n      if (!exporter) return\n      const buf = buffers.get(event.runId)\n      if (buf) buf.push(event)\n      else buffers.set(event.runId, [event])\n      if (event.kind === 'loop.ended') {\n        const events = buffers.get(event.runId) ?? [event]\n        buffers.delete(event.runId)\n        for (const span of buildLoopOtelSpans(events, ctx.traceId, ctx.parentSpanId)) {\n          exporter.exportSpan(span)\n        }\n      }\n    },\n  }\n\n  return { emitter, exporter, context: ctx }\n}\n\n/**\n * Build env vars to pass to a child MCP subprocess so it inherits the\n * current trace context.\n */\nexport function traceContextToEnv(ctx: TraceContext): Record<string, string> {\n  const env: Record<string, string> = { TRACE_ID: ctx.traceId }\n  if (ctx.parentSpanId) env.PARENT_SPAN_ID = ctx.parentSpanId\n  return env\n}\n\nfunction generateTraceId(): string {\n  const bytes = new Uint8Array(16)\n  if (typeof globalThis.crypto?.getRandomValues === 'function') {\n    globalThis.crypto.getRandomValues(bytes)\n  } else {\n    for (let i = 0; i < 16; i++) bytes[i] = Math.floor(Math.random() * 256)\n  }\n  return Array.from(bytes)\n    .map((b) => b.toString(16).padStart(2, '0'))\n    .join('')\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkCO,SAAS,0BAAwC;AACtD,QAAM,UAAU,QAAQ,IAAI,YAAY,gBAAgB;AACxD,QAAM,eAAe,QAAQ,IAAI,kBAAkB;AACnD,SAAO,EAAE,SAAS,aAAa;AACjC;AASO,SAAS,8BAA8B,KAI5C;AACA,QAAM,WAAW,mBAAmB;AAOpC,QAAM,UAAU,oBAAI,IAA8B;AAElD,QAAM,UAA4B;AAAA,IAChC,KAAK,OAAuB;AAC1B,UAAI,CAAC,SAAU;AACf,YAAM,MAAM,QAAQ,IAAI,MAAM,KAAK;AACnC,UAAI,IAAK,KAAI,KAAK,KAAK;AAAA,UAClB,SAAQ,IAAI,MAAM,OAAO,CAAC,KAAK,CAAC;AACrC,UAAI,MAAM,SAAS,cAAc;AAC/B,cAAM,SAAS,QAAQ,IAAI,MAAM,KAAK,KAAK,CAAC,KAAK;AACjD,gBAAQ,OAAO,MAAM,KAAK;AAC1B,mBAAW,QAAQ,mBAAmB,QAAQ,IAAI,SAAS,IAAI,YAAY,GAAG;AAC5E,mBAAS,WAAW,IAAI;AAAA,QAC1B;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAEA,SAAO,EAAE,SAAS,UAAU,SAAS,IAAI;AAC3C;AAMO,SAAS,kBAAkB,KAA2C;AAC3E,QAAM,MAA8B,EAAE,UAAU,IAAI,QAAQ;AAC5D,MAAI,IAAI,aAAc,KAAI,iBAAiB,IAAI;AAC/C,SAAO;AACT;AAEA,SAAS,kBAA0B;AACjC,QAAM,QAAQ,IAAI,WAAW,EAAE;AAC/B,MAAI,OAAO,WAAW,QAAQ,oBAAoB,YAAY;AAC5D,eAAW,OAAO,gBAAgB,KAAK;AAAA,EACzC,OAAO;AACL,aAAS,IAAI,GAAG,IAAI,IAAI,IAAK,OAAM,CAAC,IAAI,KAAK,MAAM,KAAK,OAAO,IAAI,GAAG;AAAA,EACxE;AACA,SAAO,MAAM,KAAK,KAAK,EACpB,IAAI,CAAC,MAAM,EAAE,SAAS,EAAE,EAAE,SAAS,GAAG,GAAG,CAAC,EAC1C,KAAK,EAAE;AACZ;","names":[]}

package/dist/optimize-prompt-cmH9wZdH.d.ts

@@ -0,0 +1,129 @@
+import { LlmClientOptions } from '@tangle-network/agent-eval';
+import { Scenario, DispatchContext, JudgeConfig, ImprovementDriver, Gate, CampaignStorage, GateResult, RunImprovementLoopResult } from '@tangle-network/agent-eval/campaign';
+
+/**
+ * @experimental
+ *
+ * `optimizePrompt` — identity-gated optimization for any TEXT prompt surface
+ * (system prompt, planner prompt, judge rubric, skill doc).
+ *
+ * The text-surface sibling to this module's `improvementDriver` (the
+ * CODE-surface / worktree path). Both feed agent-eval's `runImprovementLoop`;
+ * this one defaults the driver to agent-eval's `gepaDriver` (reflective text
+ * mutator) and the gate to `heldOutGate`.
+ *
+ * IDENTITY-GATED BY CONSTRUCTION — the whole point. The loop runs evals,
+ * collects per-scenario signal, proposes candidates, and the gate compares
+ * candidate-vs-baseline ON THE HELDOUT. `result.prompt` is the baseline
+ * (identity) UNLESS the gate decided `'ship'`. So wiring a surface up is safe:
+ * a surface with no beneficial mutation simply keeps its baseline. You never
+ * regress by registering a prompt — you only ever improve when the held-out
+ * data earns it.
+ *
+ * Generic over the runtime: `runWithPrompt` is the only domain seam — given a
+ * candidate prompt + scenario, run it however the surface runs (sandbox
+ * `streamPrompt`, a `runLoop`, a direct model call) and return the artifact the
+ * judges score. The optimizer never assumes how a prompt is executed.
+ */
+
+/** Reflection config for the default `gepaDriver`. Omit when passing a custom
+ *  `driver`. */
+interface OptimizePromptReflection {
+    /** Router transport for the reflection model. */
+    llm: LlmClientOptions;
+    /** Model that performs the reflective rewrite. */
+    model: string;
+    /** What is being optimized — orients the reflection prompt. Default
+     *  `'system prompt'`. */
+    target?: string;
+    /** Surface-specific mutation levers offered to the reflector. */
+    mutationPrimitives?: string[];
+    /** H2 (`## Foo`) headings that MUST survive every candidate. gepaDriver's
+     *  only structural guard — load-bearing sections of the prompt should be
+     *  `##` headings so a rewrite cannot drop them. */
+    preserveSections?: string[];
+    /** Max sentence-level edits per candidate vs the parent (a textual learning
+     *  rate). Caps a rewrite from wiping prior rules in one generation. */
+    maxSentenceEdits?: number;
+}
+/** @experimental */
+interface OptimizePromptOptions<TScenario extends Scenario, TArtifact> {
+    /** The prompt being optimized — the identity baseline the gate protects. */
+    baselinePrompt: string;
+    /** Domain seam: run a candidate prompt against a scenario → artifact the
+     *  judges score. The optimizer is agnostic to HOW the prompt runs. */
+    runWithPrompt: (prompt: string, scenario: TScenario, ctx: DispatchContext) => Promise<TArtifact>;
+    /** Training pool — scored each generation to rank candidates. */
+    scenarios: TScenario[];
+    /** Held out of training — scored ONLY for the gate's baseline-vs-winner
+     *  delta. Disjoint from `scenarios`; this is what makes promotion measure
+     *  generalization, not memorization. */
+    holdoutScenarios: TScenario[];
+    /** Scorers — deterministic checks or LLM judges. */
+    judges: JudgeConfig<TArtifact, TScenario>[];
+    /** Where artifacts + traces land (opaque key under in-memory storage). */
+    runDir: string;
+    /** Default driver = `gepaDriver` built from this. Required UNLESS `driver`
+     *  is supplied. */
+    reflection?: OptimizePromptReflection;
+    /** Override the improvement strategy (custom driver / deterministic tests). */
+    driver?: ImprovementDriver;
+    /** Override the promotion gate. Default `heldOutGate` over `holdoutScenarios`
+     *  — zero extra LLM. Wrap `defaultProductionGate` for red-team/reward-hacking
+     *  hardening on production wiring. */
+    gate?: Gate<TArtifact, TScenario>;
+    /** Minimum held-out composite lift to ship, forwarded to the default
+     *  `heldOutGate`. When omitted the gate uses its own default. */
+    deltaThreshold?: number;
+    /** Candidates proposed per generation. Default 4. */
+    populationSize?: number;
+    /** Generations to run. Default 3. */
+    maxGenerations?: number;
+    /** Candidates carried to the next generation. Default 2. */
+    promoteTopK?: number;
+    /** Storage backend. Pass `inMemoryCampaignStorage()` for filesystem-less /
+     *  test runs. Default: Node filesystem. */
+    storage?: CampaignStorage;
+    /** Reproducibility seed. Default 42. */
+    seed?: number;
+    /** Per-scenario replicates for CI bands. Default 1. */
+    reps?: number;
+    /** Max concurrent cells. Default 2. */
+    maxConcurrency?: number;
+    /** Test seam — override the wall clock. */
+    now?: () => Date;
+    /** On a shipped gate: `'pr'` opens a PR, `'none'` just reports. Default
+     *  `'none'`. */
+    autoOnPromote?: 'pr' | 'none';
+    ghOwner?: string;
+    ghRepo?: string;
+}
+/** @experimental */
+interface OptimizePromptResult<TArtifact, TScenario extends Scenario> {
+    /** The prompt to USE. Identity (the baseline) unless the gate shipped a
+     *  winner — so a caller can always assign `result.prompt` unconditionally. */
+    prompt: string;
+    /** True only when the gate promoted a candidate over baseline on holdout. */
+    improved: boolean;
+    /** The gate's verdict (`'ship' | 'hold' | 'need_more_work' | ...`). */
+    decision: GateResult['decision'];
+    /** Human-readable reasons the gate gave. */
+    reasons: string[];
+    /** Mean held-out composite of the baseline. */
+    baselineComposite: number;
+    /** Mean held-out composite of the winner candidate. */
+    winnerComposite: number;
+    /** Held-out lift (winner − baseline); the gate's `delta` when it reported one. */
+    delta: number;
+    /** Why the winner was proposed — present when a shipped winner carried a
+     *  driver rationale. */
+    rationale?: string;
+    /** Unified baseline→winner diff (empty when the winner is the baseline). */
+    diff: string;
+    /** The full loop result for callers that need generations / campaigns. */
+    raw: RunImprovementLoopResult<TArtifact, TScenario>;
+}
+/** @experimental */
+declare function optimizePrompt<TScenario extends Scenario, TArtifact>(opts: OptimizePromptOptions<TScenario, TArtifact>): Promise<OptimizePromptResult<TArtifact, TScenario>>;
+
+export { type OptimizePromptOptions as O, type OptimizePromptReflection as a, type OptimizePromptResult as b, optimizePrompt as o };

package/dist/{otel-export-DgFMwsVy.d.ts → otel-export-CNmeg_7B.d.ts}

@@ -1,5 +1,5 @@
 import { CoderOutput, CoderTask } from './profiles.js';
-import { L as LoopSandboxClient } from './types-CmTjKLyB.js';
+import { L as LoopSandboxClient } from './types-CmkQl8qE.js';
 import { SandboxInstance } from '@tangle-network/sandbox';
 import { O as OpenAIChatTool } from './types-CsCCryln.js';
 
@@ -361,6 +361,81 @@ interface CreateDefaultCoderDelegateOptions {
  */
 declare function createDefaultCoderDelegate(options: CreateDefaultCoderDelegateOptions): CoderDelegate;
 
+/**
+ * @experimental
+ *
+ * `createKbGate` — the valid-only knowledge-base growth gate, distilled from
+ * physim's KB-research subsystem. A research-in-a-loop delegate (or any KB
+ * writer) runs candidate facts through this before persisting, so the KB grows
+ * with ONLY grounded facts — hallucinated, unsourced, or laundered claims are
+ * vetoed at the gate.
+ *
+ * Fail-closed by construction: every judge must `accept`; the FIRST veto wins
+ * and the fact is rejected. The non-negotiable floor (always on, can't be
+ * disabled) is the **passage-present guard** — a fact's `verbatimPassage` MUST
+ * literally appear in its `sourceText`. That single check kills the dominant
+ * failure mode (a confident claim decoupled from any real source).
+ *
+ * Pure + dependency-free: it operates on fact candidates, not on a store, so it
+ * composes with `@tangle-network/agent-knowledge` or any persistence layer
+ * without importing it. The remediation policy (correct-on-veto vs
+ * escalate-as-unverified) is the caller's — this returns the verdict; it never
+ * drops a fact silently.
+ */
+/** @experimental A fact proposed for the KB, with its grounding. */
+interface FactCandidate {
+    /** The atomic claim text. */
+    claim: string;
+    /** Optional extracted value (number or string) the claim asserts. */
+    value?: string | number;
+    /** Verbatim span lifted from the source that backs the claim. */
+    verbatimPassage: string;
+    /** The raw source text the passage must be grounded in. */
+    sourceText: string;
+    /** Where the fact claims to come from — checked for circular/self citations. */
+    citation?: string;
+}
+/** @experimental */
+interface FactJudgeVerdict {
+    accept: boolean;
+    reason?: string;
+}
+/** @experimental A pluggable fact validator. Throw is NOT allowed — return a
+ *  verdict; a thrown judge is a programmer error, not a veto. */
+interface FactJudge {
+    name: string;
+    judge(candidate: FactCandidate): FactJudgeVerdict | Promise<FactJudgeVerdict>;
+}
+/** @experimental */
+interface KbGateResult {
+    accepted: boolean;
+    /** Name of the judge that vetoed; undefined when accepted. */
+    vetoedBy?: string;
+    reason?: string;
+}
+/** @experimental */
+interface CreateKbGateOptions {
+    /** Extra judges appended after the built-in floor (e.g. an LLM judge). */
+    judges?: FactJudge[];
+    /** Minimum verbatim-passage length. Default 12 — kills empty/stub passages. */
+    minPassageChars?: number;
+    /**
+     * Citation tokens that denote a SELF-generated artifact (e.g. `'spec'`,
+     * `'cad_params'`, `'requirements'`). A citation naming one is circular
+     * (laundering) — the fact cites a derived artifact, not a real source.
+     * Default `[]` (no circular check unless the consumer declares its kinds).
+     */
+    selfArtifactKinds?: string[];
+}
+/**
+ * @experimental
+ *
+ * Build a fail-closed KB gate. The returned function runs the built-in floor
+ * (passage-non-empty → passage-present → value-in-passage → no-circular-citation)
+ * then any consumer judges, returning on the first veto.
+ */
+declare function createKbGate(options?: CreateKbGateOptions): (candidate: FactCandidate) => Promise<KbGateResult>;
+
 /**
  * @experimental
  *
@@ -549,4 +624,4 @@ interface EvalRunsExportResult {
  */
 declare function exportEvalRuns(events: EvalRunEvent[], config?: EvalRunsExportConfig): Promise<EvalRunsExportResult>;
 
-export { type FeedbackRefersTo as A, type FleetWorkspaceExecutorOptions as B, type CoderDelegate as C, type DelegationExecutor as D, type ResearchOutputShape as E, type FleetHandle as F, createDefaultCoderDelegate as G, createFleetWorkspaceExecutor as H, createSiblingSandboxExecutor as I, mcpToolsForRuntimeMcp as J, mcpToolsForRuntimeMcpSubset as K, type EvalRunEvent as L, type EvalRunGeneration as M, type EvalRunsExportConfig as N, type OtelExporter as O, type EvalRunsExportResult as P, INTELLIGENCE_WIRE_VERSION as Q, type ResearcherDelegate as R, type SiblingSandboxExecutorOptions as S, type OtelAttribute as T, type OtelExportConfig as U, type OtelSpan as V, buildLoopOtelSpans as W, createOtelExporter as X, exportEvalRuns as Y, loopEventToOtelSpan as Z, type DelegateFeedbackArgs as a, type DelegationFeedbackSnapshot as b, type DelegationProfile as c, type DelegateCodeArgs as d, type DelegateResearchArgs as e, type DelegationStatus as f, type DelegationProgress as g, type DelegationResultPayload as h, type DelegationError as i, type DelegationStatusResult as j, type DelegationHistoryArgs as k, type DelegationHistoryEntry as l, type DelegateCodeResult as m, type DelegateFeedbackResult as n, type ResearchSource as o, type DelegateResearchResult as p, type DelegationHistoryResult as q, type DelegationStatusArgs as r, type CoderReview as s, type CoderReviewer as t, type CoderWinnerSelection as u, type CreateDefaultCoderDelegateOptions as v, type DelegateCodeConfig as w, type DelegateResearchConfig as x, type DelegateRunCtx as y, type FeedbackRating as z };
+export { type OtelSpan as $, type FactCandidate as A, type FactJudge as B, type CoderDelegate as C, type DelegationExecutor as D, type FactJudgeVerdict as E, type FleetHandle as F, type FeedbackRating as G, type FeedbackRefersTo as H, type FleetWorkspaceExecutorOptions as I, type ResearchOutputShape as J, type KbGateResult as K, createDefaultCoderDelegate as L, createFleetWorkspaceExecutor as M, createKbGate as N, type OtelExporter as O, createSiblingSandboxExecutor as P, mcpToolsForRuntimeMcp as Q, type ResearcherDelegate as R, type SiblingSandboxExecutorOptions as S, mcpToolsForRuntimeMcpSubset as T, type EvalRunEvent as U, type EvalRunGeneration as V, type EvalRunsExportConfig as W, type EvalRunsExportResult as X, INTELLIGENCE_WIRE_VERSION as Y, type OtelAttribute as Z, type OtelExportConfig as _, type DelegateFeedbackArgs as a, buildLoopOtelSpans as a0, createOtelExporter as a1, exportEvalRuns as a2, loopEventToOtelSpan as a3, type DelegationFeedbackSnapshot as b, type DelegationProfile as c, type DelegateCodeArgs as d, type DelegateResearchArgs as e, type DelegationStatus as f, type DelegationProgress as g, type DelegationResultPayload as h, type DelegationError as i, type DelegationStatusResult as j, type DelegationHistoryArgs as k, type DelegationHistoryEntry as l, type DelegateCodeResult as m, type DelegateFeedbackResult as n, type ResearchSource as o, type DelegateResearchResult as p, type DelegationHistoryResult as q, type DelegationStatusArgs as r, type CoderReview as s, type CoderReviewer as t, type CoderWinnerSelection as u, type CreateDefaultCoderDelegateOptions as v, type CreateKbGateOptions as w, type DelegateCodeConfig as x, type DelegateResearchConfig as y, type DelegateRunCtx as z };

package/dist/profiles.d.ts

@@ -1,5 +1,5 @@
 import { AgentProfile } from '@tangle-network/sandbox';
-import { O as OutputAdapter, V as Validator, A as AgentRunSpec, D as Driver } from './types-CmTjKLyB.js';
+import { O as OutputAdapter, V as Validator, A as AgentRunSpec, D as Driver } from './types-CmkQl8qE.js';
 import '@tangle-network/agent-eval';
 import './types-CsCCryln.js';
 

package/dist/{types-CmTjKLyB.d.ts → types-CmkQl8qE.d.ts}

@@ -1,5 +1,5 @@
 import { DefaultVerdict } from '@tangle-network/agent-eval';
-import { CreateSandboxOptions, SandboxInstance, AgentProfile, SandboxEvent } from '@tangle-network/sandbox';
+import { CreateSandboxOptions, SandboxInstance, SandboxEvent, AgentProfile } from '@tangle-network/sandbox';
 import { A as AgentTaskSpec, R as RuntimeStreamEvent } from './types-CsCCryln.js';
 
 /**

package/dist/{types-D_MXrmJP.d.ts → types-p8dWBIXL.d.ts}

@@ -1,4 +1,4 @@
-import { AnalystRunEvent, AnalystRunInputs, AnalystFinding, AnalystRunResult, FindingsDiff } from '@tangle-network/agent-eval';
+import { AnalystRunInputs, AnalystFinding, AnalystRunResult, AnalystRunEvent, FindingsDiff } from '@tangle-network/agent-eval';
 
 /**
  * Public types for the closed-loop analyst orchestrator.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-runtime",
-  "version": "0.37.0",
+  "version": "0.38.0",
   "description": "Reusable runtime lifecycle for domain-specific agents.",
   "homepage": "https://github.com/tangle-network/agent-runtime#readme",
   "repository": {