@tangle-network/agent-runtime 0.37.0 → 0.39.0

package/dist/mcp/bin.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/mcp/bin.ts"],"sourcesContent":["#!/usr/bin/env node\n\n/**\n * @experimental\n *\n * `agent-runtime-mcp` — stdio MCP server entry point.\n *\n * Spins up a server with the default coder delegate (wired against the\n * real `@tangle-network/sandbox` client) and, when the optional\n * `@tangle-network/agent-knowledge` peer is installed, a researcher\n * delegate against `multiHarnessResearcherFanout`.\n *\n * Environment variables:\n *   TANGLE_API_KEY                   required — passed to `new Sandbox({ apiKey })`\n *   SANDBOX_BASE_URL                 optional — sandbox-SDK base URL override\n *   TANGLE_FLEET_ID                  optional — when set, delegations dispatch\n *                                    INTO this fleet's shared workspace instead\n *                                    of creating sibling sandboxes. Set by the\n *                                    parent sandbox when launching this MCP\n *                                    server so worker diffs land on the caller's\n *                                    filesystem with no cross-sandbox boundary.\n *   TANGLE_FLEET_EXCLUDE_MACHINES    optional — comma-separated machine ids to\n *                                    skip during fleet-mode round-robin\n *                                    (typically the coordinator machine this\n *                                    MCP server is running on).\n *   MCP_MAX_CONCURRENT_SANDBOXES     default 4 — kernel maxConcurrency cap\n *   MCP_CODER_FANOUT_HARNESSES       comma-separated harness ids to use for variants > 1\n *   MCP_DISABLE_CODER                set to `1` to omit `delegate_code`\n *   MCP_DISABLE_RESEARCHER           set to `1` to omit `delegate_research` even when peer is present\n */\n\nimport type { LoopSandboxClient } from '../loops'\nimport { runLoop } from '../loops'\nimport { detectExecutor } from './bin-helpers'\nimport { createDefaultCoderDelegate, type ResearcherDelegate } from './delegates'\nimport type { DelegationExecutor } from './executor'\nimport { createMcpServer } from './server'\nimport type { ResearchOutputShape } from './types'\n\nasync function main(): Promise<void> {\n  const fanoutHarnesses = parseHarnesses(process.env.MCP_CODER_FANOUT_HARNESSES)\n  const maxConcurrency = parseConcurrency(process.env.MCP_MAX_CONCURRENT_SANDBOXES)\n  const wantCoder = !process.env.MCP_DISABLE_CODER\n  const wantResearcher = !process.env.MCP_DISABLE_RESEARCHER\n  const fleetId = parseFleetId(process.env.TANGLE_FLEET_ID)\n\n  // Skip the sandbox client load entirely when no profile delegate needs it —\n  // the feedback + status + history tools are queue-bound and require no\n  // sandbox. Useful for tooling that mounts the MCP server purely for\n  // self-introspection.\n  const needsSandbox = wantCoder || wantResearcher\n  let sandboxClient: LoopSandboxClient | undefined\n  let executor: DelegationExecutor | undefined\n  if (needsSandbox) {\n    const apiKey = process.env.TANGLE_API_KEY\n    if (!apiKey && !process.env.AGENT_RUNTIME_MCP_ALLOW_NO_KEY) {\n      process.stderr.write(\n        'agent-runtime-mcp: TANGLE_API_KEY is required. Set AGENT_RUNTIME_MCP_ALLOW_NO_KEY=1 to run without it for diagnostics, or MCP_DISABLE_CODER=1 MCP_DISABLE_RESEARCHER=1 to run the queue-only subset.\\n',\n      )\n      process.exit(2)\n    }\n    // Fleet mode against a diagnostic stub is meaningless — the stub can't\n    // resolve a real fleet handle. Refuse rather than silently degrading,\n    // otherwise a fleet-mounted MCP would behave differently than configured.\n    if (fleetId && !apiKey) {\n      process.stderr.write(\n        'agent-runtime-mcp: TANGLE_FLEET_ID was set but TANGLE_API_KEY is missing; cannot resolve fleet handle. Provide an api key or unset TANGLE_FLEET_ID.\\n',\n      )\n      process.exit(2)\n    }\n    sandboxClient = await loadSandboxClient(apiKey)\n    executor = await detectExecutor({ sandboxClient })\n    if (fleetId) {\n      process.stderr.write(`agent-runtime-mcp: fleet-aware delegation: fleetId=${fleetId}\\n`)\n    }\n    process.stderr.write(`agent-runtime-mcp: delegation placement → ${executor.describe()}\\n`)\n  }\n\n  const coderDelegate =\n    wantCoder && executor\n      ? createDefaultCoderDelegate({\n          executor,\n          fanoutHarnesses,\n          maxConcurrency,\n        })\n      : undefined\n\n  const researcherDelegate =\n    wantResearcher && executor\n      ? await loadResearcherDelegate(executor.client, maxConcurrency)\n      : undefined\n\n  const server = createMcpServer({ coderDelegate, researcherDelegate })\n\n  process.on('SIGINT', () => {\n    server.stop()\n    process.exit(0)\n  })\n  process.on('SIGTERM', () => {\n    server.stop()\n    process.exit(0)\n  })\n\n  await server.serve()\n}\n\nasync function loadSandboxClient(apiKey: string | undefined): Promise<LoopSandboxClient> {\n  // Diagnostic mode: AGENT_RUNTIME_MCP_ALLOW_NO_KEY=1 enables tools/list + the\n  // queue-bound tools (status / history / feedback) without sandbox creds.\n  // Coder + researcher delegations require a real client; the stub fails loud\n  // at create() so the agent observes the cause instead of silent success.\n  if (!apiKey) {\n    return {\n      async create() {\n        throw new Error(\n          'agent-runtime-mcp: TANGLE_API_KEY is unset; coder/researcher delegations are disabled in diagnostic mode. Set TANGLE_API_KEY or use MCP_DISABLE_CODER=1 MCP_DISABLE_RESEARCHER=1 to remove the unsupported tools from the tool list.',\n        )\n      },\n    } satisfies LoopSandboxClient\n  }\n  // Dynamic import keeps the bin importable in environments that haven't\n  // installed `@tangle-network/sandbox` yet (the runtime package lists it\n  // as a peer dep, not a hard dep).\n  const mod = await import('@tangle-network/sandbox').catch((err) => {\n    process.stderr.write(\n      `agent-runtime-mcp: failed to load @tangle-network/sandbox (${err.message}); install the peer dependency\\n`,\n    )\n    process.exit(2)\n  })\n  const SandboxCtor = (mod as { Sandbox?: new (config: unknown) => LoopSandboxClient }).Sandbox\n  if (!SandboxCtor) {\n    process.stderr.write(\n      'agent-runtime-mcp: @tangle-network/sandbox does not export Sandbox; cannot construct client\\n',\n    )\n    process.exit(2)\n  }\n  const baseUrl = process.env.SANDBOX_BASE_URL\n  return new SandboxCtor({\n    apiKey,\n    ...(baseUrl ? { baseUrl } : {}),\n  })\n}\n\ninterface ResearcherProfilePreset {\n  agentRunSpec: Parameters<typeof runLoop>[0]['agentRun'] extends infer T ? NonNullable<T> : never\n  output: Parameters<typeof runLoop>[0]['output']\n  validator: Parameters<typeof runLoop>[0]['validator']\n}\n\ninterface ResearcherFanoutPreset {\n  agentRuns: NonNullable<Parameters<typeof runLoop>[0]['agentRuns']>\n  output: Parameters<typeof runLoop>[0]['output']\n  validator: Parameters<typeof runLoop>[0]['validator']\n  driver: Parameters<typeof runLoop>[0]['driver']\n}\n\nasync function loadResearcherDelegate(\n  sandboxClient: LoopSandboxClient,\n  maxConcurrency: number,\n): Promise<ResearcherDelegate | undefined> {\n  // Optional peer — when `@tangle-network/agent-knowledge` isn't installed,\n  // we silently omit the researcher tool from the advertisement. The\n  // dynamic-import path is resolved at runtime; TypeScript cannot see the\n  // peer, so we type the module structurally rather than via its own\n  // declaration file.\n  const profilesSpecifier = '@tangle-network/agent-knowledge/profiles'\n  const mod = await import(profilesSpecifier).catch(() => undefined)\n  if (!mod) return undefined\n  type SingleFactory = (opts: { task: unknown }) => ResearcherProfilePreset\n  type FanoutFactory = (opts: { task: unknown }) => ResearcherFanoutPreset\n  const fanoutFactory = (mod as { multiHarnessResearcherFanout?: FanoutFactory })\n    .multiHarnessResearcherFanout\n  const singleFactory = (mod as { researcherProfile?: SingleFactory }).researcherProfile\n  if (!fanoutFactory || !singleFactory) return undefined\n\n  return async (args, ctx) => {\n    const task = {\n      question: args.question,\n      knowledgeNamespace: args.namespace,\n      scope: args.scope,\n      sources: args.sources,\n      recencyWindow: args.config?.recencyWindow\n        ? {\n            since: args.config.recencyWindow.since\n              ? new Date(args.config.recencyWindow.since)\n              : undefined,\n            until: args.config.recencyWindow.until\n              ? new Date(args.config.recencyWindow.until)\n              : undefined,\n          }\n        : undefined,\n      maxItems: args.config?.maxItems,\n      minConfidence: args.config?.minConfidence,\n    }\n    const variants = Math.max(1, Math.trunc(args.variants ?? 1))\n    ctx.report({ iteration: 0, phase: 'starting' })\n    if (variants <= 1) {\n      const preset = singleFactory({ task })\n      const result = await runLoop({\n        driver: {\n          name: 'mcp-researcher-single',\n          async plan(t, history) {\n            return history.length === 0 ? [t] : []\n          },\n          decide(history) {\n            return history.length > 0 ? 'pick-winner' : 'fail'\n          },\n        },\n        agentRun: preset.agentRunSpec,\n        output: preset.output,\n        validator: preset.validator,\n        task,\n        ctx: { sandboxClient, signal: ctx.signal },\n        maxIterations: 1,\n        maxConcurrency,\n      })\n      const output = result.winner?.output\n      if (!output) throw new Error('researcher delegate produced no winner')\n      ctx.report({ iteration: 1, phase: 'completed' })\n      return output as ResearchOutputShape\n    }\n    const fanout = fanoutFactory({ task })\n    const result = await runLoop({\n      driver: fanout.driver,\n      agentRuns: fanout.agentRuns.slice(0, variants),\n      output: fanout.output,\n      validator: fanout.validator,\n      task,\n      ctx: { sandboxClient, signal: ctx.signal },\n      maxIterations: variants,\n      maxConcurrency: Math.min(maxConcurrency, variants),\n    })\n    const output = result.winner?.output\n    if (!output) throw new Error('researcher delegate fanout produced no winner')\n    ctx.report({ iteration: result.iterations.length, phase: 'completed' })\n    return output as ResearchOutputShape\n  }\n}\n\nfunction parseHarnesses(raw: string | undefined): string[] | undefined {\n  if (!raw) return undefined\n  const list = raw\n    .split(',')\n    .map((entry) => entry.trim())\n    .filter(Boolean)\n  return list.length > 0 ? list : undefined\n}\n\nfunction parseFleetId(raw: string | undefined): string | undefined {\n  if (typeof raw !== 'string') return undefined\n  const trimmed = raw.trim()\n  return trimmed.length > 0 ? trimmed : undefined\n}\n\nfunction parseConcurrency(raw: string | undefined): number {\n  if (!raw) return 4\n  const n = Number(raw)\n  if (!Number.isFinite(n) || n < 1) return 4\n  return Math.min(Math.trunc(n), 32)\n}\n\nmain().catch((err) => {\n  process.stderr.write(`agent-runtime-mcp: ${err instanceof Error ? err.stack : String(err)}\\n`)\n  process.exit(1)\n})\n"],"mappings":"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","names":["result","output"]}
+{"version":3,"sources":["../../src/mcp/bin.ts"],"sourcesContent":["#!/usr/bin/env node\n\n/**\n * @experimental\n *\n * `agent-runtime-mcp` — stdio MCP server entry point.\n *\n * Spins up a server with the default coder delegate (wired against the\n * real `@tangle-network/sandbox` client) and, when the optional\n * `@tangle-network/agent-knowledge` peer is installed, a researcher\n * delegate against `multiHarnessResearcherFanout`.\n *\n * Environment variables:\n *   TANGLE_API_KEY                   required — passed to `new Sandbox({ apiKey })`\n *   SANDBOX_BASE_URL                 optional — sandbox-SDK base URL override\n *   TANGLE_FLEET_ID                  optional — when set, delegations dispatch\n *                                    INTO this fleet's shared workspace instead\n *                                    of creating sibling sandboxes. Set by the\n *                                    parent sandbox when launching this MCP\n *                                    server so worker diffs land on the caller's\n *                                    filesystem with no cross-sandbox boundary.\n *   TANGLE_FLEET_EXCLUDE_MACHINES    optional — comma-separated machine ids to\n *                                    skip during fleet-mode round-robin\n *                                    (typically the coordinator machine this\n *                                    MCP server is running on).\n *   MCP_MAX_CONCURRENT_SANDBOXES     default 4 — kernel maxConcurrency cap\n *   MCP_CODER_FANOUT_HARNESSES       comma-separated harness ids to use for variants > 1\n *   MCP_DISABLE_CODER                set to `1` to omit `delegate_code`\n *   MCP_DISABLE_RESEARCHER           set to `1` to omit `delegate_research` even when peer is present\n */\n\nimport type { LoopSandboxClient } from '../loops'\nimport { runLoop } from '../loops'\nimport { detectExecutor } from './bin-helpers'\nimport { createDefaultCoderDelegate, type ResearcherDelegate } from './delegates'\nimport type { DelegationExecutor } from './executor'\nimport { createMcpServer } from './server'\nimport type { ResearchOutputShape } from './types'\n\nasync function main(): Promise<void> {\n  const fanoutHarnesses = parseHarnesses(process.env.MCP_CODER_FANOUT_HARNESSES)\n  const maxConcurrency = parseConcurrency(process.env.MCP_MAX_CONCURRENT_SANDBOXES)\n  const wantCoder = !process.env.MCP_DISABLE_CODER\n  const wantResearcher = !process.env.MCP_DISABLE_RESEARCHER\n  const fleetId = parseFleetId(process.env.TANGLE_FLEET_ID)\n\n  // Skip the sandbox client load entirely when no profile delegate needs it —\n  // the feedback + status + history tools are queue-bound and require no\n  // sandbox. Useful for tooling that mounts the MCP server purely for\n  // self-introspection.\n  const needsSandbox = wantCoder || wantResearcher\n  let sandboxClient: LoopSandboxClient | undefined\n  let executor: DelegationExecutor | undefined\n  if (needsSandbox) {\n    const apiKey = process.env.TANGLE_API_KEY\n    if (!apiKey && !process.env.AGENT_RUNTIME_MCP_ALLOW_NO_KEY) {\n      process.stderr.write(\n        'agent-runtime-mcp: TANGLE_API_KEY is required. Set AGENT_RUNTIME_MCP_ALLOW_NO_KEY=1 to run without it for diagnostics, or MCP_DISABLE_CODER=1 MCP_DISABLE_RESEARCHER=1 to run the queue-only subset.\\n',\n      )\n      process.exit(2)\n    }\n    // Fleet mode against a diagnostic stub is meaningless — the stub can't\n    // resolve a real fleet handle. Refuse rather than silently degrading,\n    // otherwise a fleet-mounted MCP would behave differently than configured.\n    if (fleetId && !apiKey) {\n      process.stderr.write(\n        'agent-runtime-mcp: TANGLE_FLEET_ID was set but TANGLE_API_KEY is missing; cannot resolve fleet handle. Provide an api key or unset TANGLE_FLEET_ID.\\n',\n      )\n      process.exit(2)\n    }\n    sandboxClient = await loadSandboxClient(apiKey)\n    executor = await detectExecutor({ sandboxClient })\n    if (fleetId) {\n      process.stderr.write(`agent-runtime-mcp: fleet-aware delegation: fleetId=${fleetId}\\n`)\n    }\n    process.stderr.write(`agent-runtime-mcp: delegation placement → ${executor.describe()}\\n`)\n  }\n\n  const coderDelegate =\n    wantCoder && executor\n      ? createDefaultCoderDelegate({\n          executor,\n          fanoutHarnesses,\n          maxConcurrency,\n        })\n      : undefined\n\n  const researcherDelegate =\n    wantResearcher && executor\n      ? await loadResearcherDelegate(executor.client, maxConcurrency)\n      : undefined\n\n  const server = createMcpServer({ coderDelegate, researcherDelegate })\n\n  process.on('SIGINT', () => {\n    server.stop()\n    process.exit(0)\n  })\n  process.on('SIGTERM', () => {\n    server.stop()\n    process.exit(0)\n  })\n\n  await server.serve()\n}\n\nasync function loadSandboxClient(apiKey: string | undefined): Promise<LoopSandboxClient> {\n  // Diagnostic mode: AGENT_RUNTIME_MCP_ALLOW_NO_KEY=1 enables tools/list + the\n  // queue-bound tools (status / history / feedback) without sandbox creds.\n  // Coder + researcher delegations require a real client; the stub fails loud\n  // at create() so the agent observes the cause instead of silent success.\n  if (!apiKey) {\n    return {\n      async create() {\n        throw new Error(\n          'agent-runtime-mcp: TANGLE_API_KEY is unset; coder/researcher delegations are disabled in diagnostic mode. Set TANGLE_API_KEY or use MCP_DISABLE_CODER=1 MCP_DISABLE_RESEARCHER=1 to remove the unsupported tools from the tool list.',\n        )\n      },\n    } satisfies LoopSandboxClient\n  }\n  // Dynamic import keeps the bin importable in environments that haven't\n  // installed `@tangle-network/sandbox` yet (the runtime package lists it\n  // as a peer dep, not a hard dep).\n  const mod = await import('@tangle-network/sandbox').catch((err) => {\n    process.stderr.write(\n      `agent-runtime-mcp: failed to load @tangle-network/sandbox (${err.message}); install the peer dependency\\n`,\n    )\n    process.exit(2)\n  })\n  const SandboxCtor = (mod as { Sandbox?: new (config: unknown) => LoopSandboxClient }).Sandbox\n  if (!SandboxCtor) {\n    process.stderr.write(\n      'agent-runtime-mcp: @tangle-network/sandbox does not export Sandbox; cannot construct client\\n',\n    )\n    process.exit(2)\n  }\n  const baseUrl = process.env.SANDBOX_BASE_URL\n  return new SandboxCtor({\n    apiKey,\n    ...(baseUrl ? { baseUrl } : {}),\n  })\n}\n\ninterface ResearcherProfilePreset {\n  agentRunSpec: Parameters<typeof runLoop>[0]['agentRun'] extends infer T ? NonNullable<T> : never\n  output: Parameters<typeof runLoop>[0]['output']\n  validator: Parameters<typeof runLoop>[0]['validator']\n}\n\ninterface ResearcherFanoutPreset {\n  agentRuns: NonNullable<Parameters<typeof runLoop>[0]['agentRuns']>\n  output: Parameters<typeof runLoop>[0]['output']\n  validator: Parameters<typeof runLoop>[0]['validator']\n  driver: Parameters<typeof runLoop>[0]['driver']\n}\n\nasync function loadResearcherDelegate(\n  sandboxClient: LoopSandboxClient,\n  maxConcurrency: number,\n): Promise<ResearcherDelegate | undefined> {\n  // Optional peer — when `@tangle-network/agent-knowledge` isn't installed,\n  // we silently omit the researcher tool from the advertisement. The\n  // dynamic-import path is resolved at runtime; TypeScript cannot see the\n  // peer, so we type the module structurally rather than via its own\n  // declaration file.\n  const profilesSpecifier = '@tangle-network/agent-knowledge/profiles'\n  const mod = await import(profilesSpecifier).catch(() => undefined)\n  if (!mod) return undefined\n  type SingleFactory = (opts: { task: unknown }) => ResearcherProfilePreset\n  type FanoutFactory = (opts: { task: unknown }) => ResearcherFanoutPreset\n  const fanoutFactory = (mod as { multiHarnessResearcherFanout?: FanoutFactory })\n    .multiHarnessResearcherFanout\n  const singleFactory = (mod as { researcherProfile?: SingleFactory }).researcherProfile\n  if (!fanoutFactory || !singleFactory) return undefined\n\n  return async (args, ctx) => {\n    const task = {\n      question: args.question,\n      knowledgeNamespace: args.namespace,\n      scope: args.scope,\n      sources: args.sources,\n      recencyWindow: args.config?.recencyWindow\n        ? {\n            since: args.config.recencyWindow.since\n              ? new Date(args.config.recencyWindow.since)\n              : undefined,\n            until: args.config.recencyWindow.until\n              ? new Date(args.config.recencyWindow.until)\n              : undefined,\n          }\n        : undefined,\n      maxItems: args.config?.maxItems,\n      minConfidence: args.config?.minConfidence,\n    }\n    const variants = Math.max(1, Math.trunc(args.variants ?? 1))\n    ctx.report({ iteration: 0, phase: 'starting' })\n    if (variants <= 1) {\n      const preset = singleFactory({ task })\n      const result = await runLoop({\n        driver: {\n          name: 'mcp-researcher-single',\n          async plan(t, history) {\n            return history.length === 0 ? [t] : []\n          },\n          decide(history) {\n            return history.length > 0 ? 'pick-winner' : 'fail'\n          },\n        },\n        agentRun: preset.agentRunSpec,\n        output: preset.output,\n        validator: preset.validator,\n        task,\n        ctx: { sandboxClient, signal: ctx.signal },\n        maxIterations: 1,\n        maxConcurrency,\n      })\n      const output = result.winner?.output\n      if (!output) throw new Error('researcher delegate produced no winner')\n      ctx.report({ iteration: 1, phase: 'completed' })\n      return output as ResearchOutputShape\n    }\n    const fanout = fanoutFactory({ task })\n    const result = await runLoop({\n      driver: fanout.driver,\n      agentRuns: fanout.agentRuns.slice(0, variants),\n      output: fanout.output,\n      validator: fanout.validator,\n      task,\n      ctx: { sandboxClient, signal: ctx.signal },\n      maxIterations: variants,\n      maxConcurrency: Math.min(maxConcurrency, variants),\n    })\n    const output = result.winner?.output\n    if (!output) throw new Error('researcher delegate fanout produced no winner')\n    ctx.report({ iteration: result.iterations.length, phase: 'completed' })\n    return output as ResearchOutputShape\n  }\n}\n\nfunction parseHarnesses(raw: string | undefined): string[] | undefined {\n  if (!raw) return undefined\n  const list = raw\n    .split(',')\n    .map((entry) => entry.trim())\n    .filter(Boolean)\n  return list.length > 0 ? list : undefined\n}\n\nfunction parseFleetId(raw: string | undefined): string | undefined {\n  if (typeof raw !== 'string') return undefined\n  const trimmed = raw.trim()\n  return trimmed.length > 0 ? trimmed : undefined\n}\n\nfunction parseConcurrency(raw: string | undefined): number {\n  if (!raw) return 4\n  const n = Number(raw)\n  if (!Number.isFinite(n) || n < 1) return 4\n  return Math.min(Math.trunc(n), 32)\n}\n\nmain().catch((err) => {\n  process.stderr.write(`agent-runtime-mcp: ${err instanceof Error ? err.stack : String(err)}\\n`)\n  process.exit(1)\n})\n"],"mappings":"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","names":["result","output"]}

package/dist/mcp/index.d.ts

@@ -1,8 +1,10 @@
-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-B9O7l-ij.js';
+import { c as FleetHandle, d as DelegationExecutor, e as DelegateFeedbackArgs, f as DelegationFeedbackSnapshot, g as DelegationProfile, D as DelegateCodeArgs, h as DelegateResearchArgs, i as DelegationStatus, j as DelegationProgress, k as DelegationResultPayload, l as DelegationError, m as DelegationStatusResult, n as DelegationHistoryArgs, o as DelegationHistoryEntry, p as CoderDelegate, R as ResearcherDelegate, q as DelegateCodeResult, r as DelegateFeedbackResult, s as ResearchSource, t as DelegateResearchResult, u as DelegationHistoryResult, v as DelegationStatusArgs } from '../kb-gate-YdPNEagq.js';
+export { w as CoderReview, C as CoderReviewer, a as CoderWinnerSelection, x as CreateDefaultCoderDelegateOptions, b as CreateKbGateOptions, y as DelegateCodeConfig, z as DelegateResearchConfig, A as DelegateRunCtx, F 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, O as createSiblingSandboxExecutor } from '../kb-gate-YdPNEagq.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 { O as OtelExporter } from '../otel-export-xgf4J6bo.js';
+export { m as mcpToolsForRuntimeMcp, a as mcpToolsForRuntimeMcpSubset } from '../otel-export-xgf4J6bo.js';
 import '@tangle-network/agent-eval';
 import '@tangle-network/sandbox';
 import '../types-CsCCryln.js';
@@ -285,81 +287,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 +874,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

@@ -6,13 +6,13 @@ import {
   createWorktree,
   detectExecutor,
   removeWorktree
-} from "../chunk-M65QJD35.js";
+} from "../chunk-PK5DYSNO.js";
 import {
   buildLoopOtelSpans,
   createOtelExporter,
   mcpToolsForRuntimeMcp,
   mcpToolsForRuntimeMcpSubset
-} from "../chunk-T3GJBKHA.js";
+} from "../chunk-7ZECSZ3C.js";
 import {
   DELEGATE_CODE_DESCRIPTION,
   DELEGATE_CODE_INPUT_SCHEMA,
@@ -31,14 +31,11 @@ import {
   DELEGATION_STATUS_TOOL_NAME,
   DelegationTaskQueue,
   InMemoryFeedbackStore,
-  createDefaultCoderDelegate,
   createDelegateCodeHandler,
   createDelegateFeedbackHandler,
   createDelegateResearchHandler,
   createDelegationHistoryHandler,
   createDelegationStatusHandler,
-  createFleetWorkspaceExecutor,
-  createSiblingSandboxExecutor,
   eventToSnapshot,
   hashIdempotencyInput,
   validateDelegateCodeArgs,
@@ -46,7 +43,15 @@ import {
   validateDelegateResearchArgs,
   validateDelegationHistoryArgs,
   validateDelegationStatusArgs
-} from "../chunk-V6GURW4W.js";
+} from "../chunk-HSX6PFZR.js";
+import {
+  createKbGate
+} from "../chunk-FNMGYYSS.js";
+import {
+  createDefaultCoderDelegate,
+  createFleetWorkspaceExecutor,
+  createSiblingSandboxExecutor
+} from "../chunk-VLXRXMTF.js";
 import {
   runLocalHarness
 } from "../chunk-GLR25NG7.js";
@@ -56,62 +61,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":"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","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-D-urF2wW.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 OptimizePromptResult as a, type OptimizePromptReflection as b, optimizePrompt as o };