@tangle-network/agent-runtime 0.36.0 → 0.38.0

package/dist/index.d.ts

@@ -2,8 +2,16 @@ import { AgentEvalError, KnowledgeReadinessReport, RunRecord, ControlEvalResult,
 export { AgentEvalError, AgentEvalErrorCode, ConfigError, ControlBudget, ControlDecision, ControlEvalResult, ControlRunResult, ControlStep, DataAcquisitionPlan, JudgeError, KnowledgeReadinessReport, KnowledgeRequirement, NotFoundError, RunRecord, ValidationError } from '@tangle-network/agent-eval';
 import { a as AgentBackendInput, b as AgentExecutionBackend, O as OpenAIChatTool, c as OpenAIChatToolChoice, d as AgentBackendContext, R as RuntimeStreamEvent, K as KnowledgeReadinessDecision, e as RunAgentTaskOptions, f as AgentTaskRunResult, g as RunAgentTaskStreamOptions, h as AgentRuntimeEvent, i as AgentTaskStatus, j as RuntimeSessionStore, k as RuntimeSession } from './types-CsCCryln.js';
 export { l as AgentAdapter, m as AgentKnowledgeProvider, n as AgentRuntimeEventSink, o as AgentTaskContext, A as AgentTaskSpec, B as BackendErrorDetail } from './types-CsCCryln.js';
-export { E as EvalRunEvent, b as EvalRunGeneration, c as EvalRunsExportConfig, d as EvalRunsExportResult, I as INTELLIGENCE_WIRE_VERSION, e as OtelAttribute, f as OtelExportConfig, O as OtelExporter, g as OtelSpan, h as buildLoopOtelSpans, i as createOtelExporter, j as exportEvalRuns, l as loopEventToOtelSpan, m as mcpToolsForRuntimeMcp, a as mcpToolsForRuntimeMcpSubset } from './otel-export-xgf4J6bo.js';
-export { R as RuntimeRunHandle, a as RuntimeRunPersistenceAdapter, b as RuntimeRunRow, s as startRuntimeRun } from './runtime-run-B8VIiOhI.js';
+import { Scenario } from '@tangle-network/agent-eval/campaign';
+import { R as RunAnalystLoopOpts, a as RunAnalystLoopResult } from './types-p8dWBIXL.js';
+import { O as OptimizePromptOptions, b as OptimizePromptResult } from './optimize-prompt-cmH9wZdH.js';
+import { T as TopologyPlanner, D as DynamicDecision } from './dynamic-DeOPeeAw.js';
+import { L as LoopSandboxClient, O as OutputAdapter, V as Validator, A as AgentRunSpec, b as LoopResult } from './types-CmkQl8qE.js';
+export { R as RuntimeRunHandle, p as RuntimeRunPersistenceAdapter, q as RuntimeRunRow, s as startRuntimeRun } from './types-CmkQl8qE.js';
+import { d as DelegateCodeArgs, t as CoderReviewer, u as CoderWinnerSelection, A as FactCandidate, w as CreateKbGateOptions } from './otel-export-CNmeg_7B.js';
+export { U as EvalRunEvent, V as EvalRunGeneration, W as EvalRunsExportConfig, X as EvalRunsExportResult, Y as INTELLIGENCE_WIRE_VERSION, Z as OtelAttribute, _ as OtelExportConfig, O as OtelExporter, $ as OtelSpan, a0 as buildLoopOtelSpans, a1 as createOtelExporter, a2 as exportEvalRuns, a3 as loopEventToOtelSpan, Q as mcpToolsForRuntimeMcp, T as mcpToolsForRuntimeMcpSubset } from './otel-export-CNmeg_7B.js';
+import { CoderOutput } from './profiles.js';
+import '@tangle-network/sandbox';
 
 /**
  * @stable
@@ -1007,6 +1015,143 @@ declare class PlannerError extends AgentEvalError {
     });
 }
 
+/**
+ * @experimental
+ *
+ * `runDelegatedLoop` — the configured delegated loop-runner.
+ *
+ * One typed entrypoint a worker agent (or a scheduled routine) calls to run a
+ * disciplined loop in a chosen MODE, over agent-runtime's hardened engines:
+ *
+ *   code         → build-in-a-loop via the coder delegate (no-op + secret floor,
+ *                  optional reviewer gate, winner-selection)
+ *   review       → code mode with a REQUIRED reviewer (the gate is the point)
+ *   research     → research-in-a-loop with valid-only KB growth (createKbGate)
+ *   audit        → analyze trace/run data → findings (runAnalystLoop, caller-wired)
+ *   self-improve → identity-gated prompt optimization (optimizePrompt, caller-wired)
+ *   dynamic      → agent-authored topology (runLoop + createDynamicDriver)
+ *
+ * It is intentionally a thin façade: the value is that EVERY product reuses the
+ * one hardened engine instead of forking delegation logic. The dispatcher owns
+ * mode routing, timing, fail-loud on an unregistered mode, and a uniform result
+ * shape; each mode's engine is a pre-configured runner in the registry (build it
+ * with the factories below, or inject your own / a stub).
+ */
+
+/** @experimental */
+type DelegatedLoopMode = 'code' | 'review' | 'research' | 'audit' | 'self-improve' | 'dynamic';
+/** @experimental A pre-configured loop for one mode. Returns the mode's raw
+ *  output; the dispatcher wraps it in a {@link DelegatedLoopResult}. */
+type DelegatedLoopRunner<T = unknown> = (signal: AbortSignal) => Promise<T>;
+/** @experimental Mode → configured runner. Partial: only register the modes a
+ *  given product/routine actually uses. */
+type DelegatedLoopRegistry = Partial<Record<DelegatedLoopMode, DelegatedLoopRunner>>;
+/** @experimental Uniform result — never throws from a registered runner; a
+ *  thrown engine becomes `{ ok: false, error }` so a routine can record + move on. */
+interface DelegatedLoopResult<T = unknown> {
+    mode: DelegatedLoopMode;
+    ok: boolean;
+    output?: T;
+    error?: string;
+    durationMs: number;
+}
+/** @experimental */
+interface RunDelegatedLoopOptions {
+    signal?: AbortSignal;
+    /** Clock override for deterministic tests. */
+    now?: () => number;
+}
+/**
+ * @experimental
+ *
+ * Dispatch a configured loop by mode. Fails loud (throws `ConfigError`) when no
+ * runner is registered for the mode — a routine pointed at an unwired mode is a
+ * config bug, not a silent no-op. A runner that throws is captured as
+ * `{ ok: false }` so unattended runs record the failure rather than crash.
+ */
+declare function runDelegatedLoop<T = unknown>(mode: DelegatedLoopMode, registry: DelegatedLoopRegistry, options?: RunDelegatedLoopOptions): Promise<DelegatedLoopResult<T>>;
+/** @experimental Options for the default `code`/`review` runner. */
+interface CoderLoopRunnerOptions {
+    sandboxClient: LoopSandboxClient;
+    /** What to build — the delegate args (goal, repoRoot, variants, config, …). */
+    args: DelegateCodeArgs;
+    /** Adversarial reviewer. REQUIRED for `review` mode (see `reviewLoopRunner`). */
+    reviewer?: CoderReviewer;
+    /** Winner-selection strategy. Default `highest-score`. */
+    winnerSelection?: CoderWinnerSelection;
+    /** Harnesses for `variants > 1` fanout. */
+    fanoutHarnesses?: string[];
+}
+/** @experimental Build a `code`-mode runner over the hardened coder delegate. */
+declare function coderLoopRunner(options: CoderLoopRunnerOptions): DelegatedLoopRunner<CoderOutput>;
+/**
+ * @experimental
+ *
+ * `review` mode = `code` with a REQUIRED reviewer. The gate is the whole point,
+ * so the type forces a reviewer (a "review loop" with no reviewer is a code loop).
+ */
+declare function reviewLoopRunner(options: CoderLoopRunnerOptions & {
+    reviewer: CoderReviewer;
+}): DelegatedLoopRunner<CoderOutput>;
+/** @experimental Options for the default `dynamic` runner. */
+interface DynamicLoopRunnerOptions<Task, Output> {
+    sandboxClient: LoopSandboxClient;
+    /** The agent-authored topology planner (e.g. `createSandboxPlanner(...)`). */
+    planner: TopologyPlanner<Task, Output>;
+    task: Task;
+    output: OutputAdapter<Output>;
+    validator?: Validator<Output>;
+    /** Exactly one of `agentRun` / `agentRuns` (runLoop validates). */
+    agentRun?: AgentRunSpec<Task>;
+    agentRuns?: AgentRunSpec<Task>[];
+    maxIterations?: number;
+    maxFanout?: number;
+}
+/** @experimental `dynamic` mode — agent-authored topology over `runLoop`. */
+declare function dynamicLoopRunner<Task, Output>(o: DynamicLoopRunnerOptions<Task, Output>): DelegatedLoopRunner<LoopResult<Task, Output, DynamicDecision>>;
+/** @experimental A fact rejected at the KB gate — surfaced, never dropped. */
+interface VetoedFact {
+    candidate: FactCandidate;
+    vetoedBy?: string;
+    reason?: string;
+}
+/** @experimental */
+interface ResearchLoopResult {
+    /** Facts that passed the fail-closed gate — safe to write to the KB. */
+    accepted: FactCandidate[];
+    /** Facts the gate vetoed in the final round — escalate, do not silently drop. */
+    vetoed: VetoedFact[];
+    /** Research rounds actually run. */
+    rounds: number;
+}
+/** @experimental Options for the default `research` runner. */
+interface ResearchLoopRunnerOptions {
+    /**
+     * The research engine (the consumer's web/doc searcher + extractor). Called
+     * each round with the prior round's vetoes so it can re-research the gaps.
+     * Returns fact candidates carrying their grounding (`verbatimPassage` +
+     * `sourceText`).
+     */
+    research: (round: number, vetoed: VetoedFact[]) => Promise<FactCandidate[]>;
+    /** Gate config (extra judges, self-artifact kinds, …). The floor is always on. */
+    gate?: CreateKbGateOptions;
+    /** Max research rounds (correct-on-veto remediation). Default 1. */
+    maxRounds?: number;
+}
+/**
+ * @experimental `research` mode — research-in-a-loop with valid-only KB growth.
+ *
+ * Each round: research → gate every candidate (fail-closed; passage MUST be in
+ * the source) → accept the clean ones → re-research the vetoed ones next round,
+ * up to `maxRounds`. Vetoed facts in the final round are RETURNED (escalate,
+ * never silently dropped) so the caller audits vs retries.
+ */
+declare function researchLoopRunner(o: ResearchLoopRunnerOptions): DelegatedLoopRunner<ResearchLoopResult>;
+/** @experimental `self-improve` mode — identity-gated prompt optimization. */
+declare function selfImproveLoopRunner<TScenario extends Scenario, TArtifact>(options: OptimizePromptOptions<TScenario, TArtifact>): DelegatedLoopRunner<OptimizePromptResult<TArtifact, TScenario>>;
+/** @experimental `audit` mode — analyst loop over captured trace/run data. */
+declare function auditLoopRunner<TProposal = unknown, TEdit = unknown>(options: RunAnalystLoopOpts): DelegatedLoopRunner<RunAnalystLoopResult<TProposal, TEdit>>;
+
 /**
  * @stable
  *
@@ -1288,4 +1433,4 @@ declare function readinessServerSentEvent(report: KnowledgeReadinessReport, opti
 /** @stable */
 declare function runtimeStreamServerSentEvent(event: RuntimeStreamEvent, options?: RuntimeTelemetryOptions & ServerSentEventOptions): string;
 
-export { AgentBackendContext, AgentBackendInput, AgentExecutionBackend, AgentRuntimeEvent, AgentTaskRunResult, AgentTaskStatus, type AuthSource, type BackendCallPolicy, BackendTransportError, type ChatStreamEvent, type ChatTurnHooks, type ChatTurnIdentity, type ChatTurnProducer, type ChatTurnResult, type CircuitBreakerConfig, CircuitBreakerState, CircuitOpenError, type Conversation, type ConversationDriveState, type ConversationJournal, type ConversationJournalEntry, type ConversationParticipant, type ConversationPolicy, type ConversationResult, type ConversationStreamEvent, type ConversationTurn, type D1DatabaseLike, type D1StmtLike, DEFAULT_MAX_DEPTH, DEFAULT_ROUTER_BASE_URL, DeadlineExceededError, FORWARD_HEADERS, FileConversationJournal, type ForwardHeaderName, type HaltContext, type HaltPredicate, type HaltReason, type HaltSignal, InMemoryConversationJournal, InMemoryRuntimeSessionStore, type ModelInfo, OpenAIChatTool, OpenAIChatToolChoice, PlannerError, type PropagatedHeaders, type ResolvedChatModel, type RetryBackoff, type RetryableErrorPredicate, type RouterEnv, type RunChatTurnInput, type RunConversationOptions, type RuntimeEventCollector, RuntimeRunStateError, RuntimeSessionStore, RuntimeStreamEvent, type RuntimeStreamEventCollector, type RuntimeTelemetryOptions, type SanitizedKnowledgeReadinessReport, type SqlAdapter, SqlConversationJournal, type TurnOrder, applyRunRecordDefaults, buildForwardHeaders, cleanModelId, computeBackoff, createConversationBackend, createIterableBackend, createOpenAICompatibleBackend, createRuntimeEventCollector, createRuntimeStreamEventCollector, createSandboxPromptBackend, d1ToSqlAdapter, decideKnowledgeReadiness, defaultIsRetryable, defineConversation, deriveExecutionId, getModels, handleChatTurn, isDepthExceeded, makePerAttemptSignal, readDepth, readinessServerSentEvent, resolveChatModel, resolveRouterBaseUrl, runAgentTask, runAgentTaskStream, runConversation, runConversationStream, runtimeStreamServerSentEvent, sanitizeAgentRuntimeEvent, sanitizeKnowledgeReadinessReport, sanitizeRuntimeStreamEvent, sleep, slugifySpeaker, turnId, validateChatModelId };
+export { AgentBackendContext, AgentBackendInput, AgentExecutionBackend, AgentRuntimeEvent, AgentTaskRunResult, AgentTaskStatus, type AuthSource, type BackendCallPolicy, BackendTransportError, type ChatStreamEvent, type ChatTurnHooks, type ChatTurnIdentity, type ChatTurnProducer, type ChatTurnResult, type CircuitBreakerConfig, CircuitBreakerState, CircuitOpenError, type CoderLoopRunnerOptions, type Conversation, type ConversationDriveState, type ConversationJournal, type ConversationJournalEntry, type ConversationParticipant, type ConversationPolicy, type ConversationResult, type ConversationStreamEvent, type ConversationTurn, type D1DatabaseLike, type D1StmtLike, DEFAULT_MAX_DEPTH, DEFAULT_ROUTER_BASE_URL, DeadlineExceededError, type DelegatedLoopMode, type DelegatedLoopRegistry, type DelegatedLoopResult, type DelegatedLoopRunner, type DynamicLoopRunnerOptions, FORWARD_HEADERS, FileConversationJournal, type ForwardHeaderName, type HaltContext, type HaltPredicate, type HaltReason, type HaltSignal, InMemoryConversationJournal, InMemoryRuntimeSessionStore, type ModelInfo, OpenAIChatTool, OpenAIChatToolChoice, PlannerError, type PropagatedHeaders, type ResearchLoopResult, type ResearchLoopRunnerOptions, type ResolvedChatModel, type RetryBackoff, type RetryableErrorPredicate, type RouterEnv, type RunChatTurnInput, type RunConversationOptions, type RunDelegatedLoopOptions, type RuntimeEventCollector, RuntimeRunStateError, RuntimeSessionStore, RuntimeStreamEvent, type RuntimeStreamEventCollector, type RuntimeTelemetryOptions, type SanitizedKnowledgeReadinessReport, type SqlAdapter, SqlConversationJournal, type TurnOrder, type VetoedFact, applyRunRecordDefaults, auditLoopRunner, buildForwardHeaders, cleanModelId, coderLoopRunner, computeBackoff, createConversationBackend, createIterableBackend, createOpenAICompatibleBackend, createRuntimeEventCollector, createRuntimeStreamEventCollector, createSandboxPromptBackend, d1ToSqlAdapter, decideKnowledgeReadiness, defaultIsRetryable, defineConversation, deriveExecutionId, dynamicLoopRunner, getModels, handleChatTurn, isDepthExceeded, makePerAttemptSignal, readDepth, readinessServerSentEvent, researchLoopRunner, resolveChatModel, resolveRouterBaseUrl, reviewLoopRunner, runAgentTask, runAgentTaskStream, runConversation, runConversationStream, runDelegatedLoop, runtimeStreamServerSentEvent, sanitizeAgentRuntimeEvent, sanitizeKnowledgeReadinessReport, sanitizeRuntimeStreamEvent, selfImproveLoopRunner, sleep, slugifySpeaker, turnId, validateChatModelId };

package/dist/index.js

@@ -1,13 +1,28 @@
+import {
+  runAnalystLoop
+} from "./chunk-XBUG326M.js";
+import {
+  optimizePrompt
+} from "./chunk-VOX6Z3II.js";
 import {
   INTELLIGENCE_WIRE_VERSION,
   buildLoopOtelSpans,
+  createKbGate,
   createOtelExporter,
   exportEvalRuns,
   loopEventToOtelSpan,
   mcpToolsForRuntimeMcp,
   mcpToolsForRuntimeMcpSubset
-} from "./chunk-7ZECSZ3C.js";
-import "./chunk-HSX6PFZR.js";
+} from "./chunk-Z523NPJK.js";
+import {
+  createDefaultCoderDelegate
+} from "./chunk-V6GURW4W.js";
+import {
+  createDynamicDriver,
+  runLoop
+} from "./chunk-7JBDJQLO.js";
+import "./chunk-3HMHSN22.js";
+import "./chunk-PY6NMZYX.js";
 import {
   AgentEvalError,
   BackendTransportError,
@@ -1724,6 +1739,91 @@ function deriveExecutionId(input) {
   return `${input.projectId}:${input.sessionId}:${input.turnIndex}`;
 }
 
+// src/loop-runner.ts
+async function runDelegatedLoop(mode, registry, options = {}) {
+  const runner = registry[mode];
+  if (!runner) {
+    throw new ConfigError(
+      `runDelegatedLoop: no runner registered for mode '${mode}' (registered: ${Object.keys(registry).join(", ") || "none"})`
+    );
+  }
+  const now = options.now ?? Date.now;
+  const signal = options.signal ?? new AbortController().signal;
+  const start = now();
+  try {
+    const output = await runner(signal);
+    return { mode, ok: true, output, durationMs: now() - start };
+  } catch (err) {
+    return {
+      mode,
+      ok: false,
+      error: err instanceof Error ? err.message : String(err),
+      durationMs: now() - start
+    };
+  }
+}
+function coderLoopRunner(options) {
+  const delegate = createDefaultCoderDelegate({
+    sandboxClient: options.sandboxClient,
+    ...options.reviewer ? { reviewer: options.reviewer } : {},
+    ...options.winnerSelection ? { winnerSelection: options.winnerSelection } : {},
+    ...options.fanoutHarnesses ? { fanoutHarnesses: options.fanoutHarnesses } : {}
+  });
+  return async (signal) => {
+    const ctx = { signal, report: () => {
+    } };
+    return delegate(options.args, ctx);
+  };
+}
+function reviewLoopRunner(options) {
+  return coderLoopRunner(options);
+}
+function dynamicLoopRunner(o) {
+  return async (signal) => runLoop({
+    driver: createDynamicDriver({
+      planner: o.planner,
+      ...o.maxIterations !== void 0 ? { maxIterations: o.maxIterations } : {},
+      ...o.maxFanout !== void 0 ? { maxFanout: o.maxFanout } : {}
+    }),
+    ...o.agentRun ? { agentRun: o.agentRun } : {},
+    ...o.agentRuns ? { agentRuns: o.agentRuns } : {},
+    output: o.output,
+    ...o.validator ? { validator: o.validator } : {},
+    task: o.task,
+    ctx: { sandboxClient: o.sandboxClient, signal },
+    ...o.maxIterations !== void 0 ? { maxIterations: o.maxIterations } : {}
+  });
+}
+function researchLoopRunner(o) {
+  const gate = createKbGate(o.gate);
+  const maxRounds = Math.max(1, Math.trunc(o.maxRounds ?? 1));
+  return async (signal) => {
+    const accepted = [];
+    let vetoed = [];
+    let rounds = 0;
+    for (let round = 0; round < maxRounds; round += 1) {
+      if (signal.aborted) break;
+      rounds += 1;
+      const candidates = await o.research(round, vetoed);
+      if (candidates.length === 0) break;
+      vetoed = [];
+      for (const c of candidates) {
+        const v = await gate(c);
+        if (v.accepted) accepted.push(c);
+        else vetoed.push({ candidate: c, vetoedBy: v.vetoedBy, reason: v.reason });
+      }
+      if (vetoed.length === 0) break;
+    }
+    return { accepted, vetoed, rounds };
+  };
+}
+function selfImproveLoopRunner(options) {
+  return async () => optimizePrompt(options);
+}
+function auditLoopRunner(options) {
+  return async () => runAnalystLoop(options);
+}
+
 // src/model-resolution.ts
 var DEFAULT_ROUTER_BASE_URL = "https://router.tangle.tools";
 function resolveRouterBaseUrl(env = {}) {
@@ -2729,9 +2829,11 @@ export {
   SqlConversationJournal,
   ValidationError,
   applyRunRecordDefaults,
+  auditLoopRunner,
   buildForwardHeaders,
   buildLoopOtelSpans,
   cleanModelId,
+  coderLoopRunner,
   computeBackoff,
   createConversationBackend,
   createIterableBackend,
@@ -2745,6 +2847,7 @@ export {
   defaultIsRetryable,
   defineConversation,
   deriveExecutionId,
+  dynamicLoopRunner,
   exportEvalRuns,
   getModels,
   handleChatTurn,
@@ -2755,16 +2858,20 @@ export {
   mcpToolsForRuntimeMcpSubset,
   readDepth,
   readinessServerSentEvent,
+  researchLoopRunner,
   resolveChatModel,
   resolveRouterBaseUrl,
+  reviewLoopRunner,
   runAgentTask,
   runAgentTaskStream,
   runConversation,
   runConversationStream,
+  runDelegatedLoop,
   runtimeStreamServerSentEvent,
   sanitizeAgentRuntimeEvent,
   sanitizeKnowledgeReadinessReport,
   sanitizeRuntimeStreamEvent,
+  selfImproveLoopRunner,
   sleep2 as sleep,
   slugifySpeaker,
   startRuntimeRun,