@tangle-network/agent-runtime 0.105.0 → 0.106.0

package/dist/types-C9j4qg6l.d.ts

@@ -0,0 +1,500 @@
+import { ControlBudget, ControlDecision, ControlEvalResult, ControlRunResult, ControlStep, DataAcquisitionPlan, KnowledgeReadinessReport, KnowledgeRequirement, RunRecord, TraceStore, UserQuestion } from "@tangle-network/agent-eval";
+//#region src/types.d.ts
+/** @stable */
+interface AgentTaskSpec {
+  id: string;
+  intent: string;
+  /** Domain is metadata, not an architectural boundary: tax, legal, gtm, creative, blueprint, redteam, etc. */
+  domain?: string;
+  inputs?: Record<string, unknown>;
+  requiredKnowledge?: KnowledgeRequirement[];
+  budget?: Partial<ControlBudget>;
+  metadata?: Record<string, unknown>;
+}
+/** @stable */
+interface AgentKnowledgeProvider {
+  buildReadiness?(task: AgentTaskSpec): Promise<KnowledgeReadinessReport> | KnowledgeReadinessReport;
+  answerQuestions?(questions: UserQuestion[], task: AgentTaskSpec): Promise<Record<string, string>> | Record<string, string>;
+  executeAcquisitionPlans?(plans: DataAcquisitionPlan[], task: AgentTaskSpec): Promise<string[]> | string[];
+  refreshReadiness?(input: {
+    task: AgentTaskSpec;
+    previous: KnowledgeReadinessReport;
+    userAnswers: Record<string, string>;
+    acquiredEvidenceIds: string[];
+  }): Promise<KnowledgeReadinessReport> | KnowledgeReadinessReport;
+}
+/** @stable */
+interface AgentTaskContext<TState, TAction, TActionResult, TEval extends ControlEvalResult = ControlEvalResult> {
+  task: AgentTaskSpec;
+  knowledge: KnowledgeReadinessReport;
+  state: TState;
+  evals: TEval[];
+  history: ControlStep<TState, TAction, TActionResult, TEval>[];
+  budget: ControlBudget;
+  stepIndex: number;
+  wallMs: number;
+  spentCostUsd: number;
+  remainingCostUsd?: number;
+  abortSignal: AbortSignal;
+}
+/** @stable */
+interface AgentAdapter<TState, TAction, TActionResult, TEval extends ControlEvalResult = ControlEvalResult> {
+  observe(ctx: {
+    task: AgentTaskSpec;
+    knowledge: KnowledgeReadinessReport;
+    history: ControlStep<TState, TAction, TActionResult, TEval>[];
+    abortSignal: AbortSignal;
+  }): Promise<TState> | TState;
+  validate(ctx: {
+    task: AgentTaskSpec;
+    knowledge: KnowledgeReadinessReport;
+    state: TState;
+    history: ControlStep<TState, TAction, TActionResult, TEval>[];
+    abortSignal: AbortSignal;
+  }): Promise<TEval[]> | TEval[];
+  decide(ctx: AgentTaskContext<TState, TAction, TActionResult, TEval>): Promise<ControlDecision<TAction>> | ControlDecision<TAction>;
+  act(action: TAction, ctx: AgentTaskContext<TState, TAction, TActionResult, TEval>): Promise<TActionResult> | TActionResult;
+  shouldStop?(ctx: AgentTaskContext<TState, TAction, TActionResult, TEval>): Promise<{
+    stop: boolean;
+    pass: boolean;
+    reason: string;
+    score?: number;
+  }> | {
+    stop: boolean;
+    pass: boolean;
+    reason: string;
+    score?: number;
+  };
+  onKnowledgeBlocked?(ctx: {
+    task: AgentTaskSpec;
+    knowledge: KnowledgeReadinessReport;
+    questions: UserQuestion[];
+    acquisitionPlans: DataAcquisitionPlan[];
+  }): Promise<ControlDecision<TAction>> | ControlDecision<TAction>;
+  getActionCostUsd?(ctx: {
+    action: TAction;
+    result: TActionResult;
+    task: AgentTaskSpec;
+    state: TState;
+    evals: TEval[];
+    history: ControlStep<TState, TAction, TActionResult, TEval>[];
+  }): number | undefined;
+  projectRunRecords?(result: ControlRunResult<TState, TAction, TActionResult, TEval>, task: AgentTaskSpec): RunRecord[];
+}
+/** @stable */
+type AgentTaskStatus = 'completed' | 'blocked' | 'failed' | 'aborted';
+/** @stable */
+type AgentRuntimeEvent<TState = unknown, TAction = unknown, TActionResult = unknown, TEval extends ControlEvalResult = ControlEvalResult> = {
+  type: 'task_start';
+  task: AgentTaskSpec;
+} | {
+  type: 'readiness_start';
+  task: AgentTaskSpec;
+} | {
+  type: 'readiness_end';
+  task: AgentTaskSpec;
+  knowledge: KnowledgeReadinessReport;
+} | {
+  type: 'questions_start';
+  task: AgentTaskSpec;
+  questions: UserQuestion[];
+} | {
+  type: 'questions_end';
+  task: AgentTaskSpec;
+  questions: UserQuestion[];
+  userAnswers: Record<string, string>;
+} | {
+  type: 'acquisition_start';
+  task: AgentTaskSpec;
+  acquisitionPlans: DataAcquisitionPlan[];
+} | {
+  type: 'acquisition_end';
+  task: AgentTaskSpec;
+  acquisitionPlans: DataAcquisitionPlan[];
+  acquiredEvidenceIds: string[];
+} | {
+  type: 'control_start';
+  task: AgentTaskSpec;
+  knowledge: KnowledgeReadinessReport;
+} | {
+  type: 'control_step';
+  task: AgentTaskSpec;
+  step: ControlStep<TState, TAction, TActionResult, TEval>;
+} | {
+  type: 'control_end';
+  task: AgentTaskSpec;
+  control: ControlRunResult<TState, TAction, TActionResult, TEval>;
+} | {
+  type: 'task_end';
+  task: AgentTaskSpec;
+  status: AgentTaskStatus;
+  reason: string;
+};
+/** @stable */
+type AgentRuntimeEventSink<TState = unknown, TAction = unknown, TActionResult = unknown, TEval extends ControlEvalResult = ControlEvalResult> = (event: AgentRuntimeEvent<TState, TAction, TActionResult, TEval>) => Promise<void> | void;
+/**
+ *
+ * Typed transport / backend failure detail. Carried on `backend_error` and
+ * `final` events when the backend's stream throws or the upstream HTTP call
+ * returns a non-success status. Lets consumers (a) distinguish "stream
+ * completed with no text" from "stream never reached the model" and
+ * (b) reconstruct the precise upstream signal (status + truncated body) when
+ * building a `RunRecord.error`.
+ *
+ * `body` is truncated to 2 KiB by the backend so an HTML error page from a
+ * misconfigured proxy never bloats event payloads or logs. Consumers needing
+ * the full body should inspect the underlying `BackendTransportError.body`
+ * via a custom `mapEvent` or backend wrapper.
+ *
+ * @stable
+ */
+interface BackendErrorDetail {
+  /**
+   * `'transport'` — upstream HTTP / network failure with optional status code.
+   * `'backend'` — the backend's `stream()` generator threw for a non-transport
+   * reason (e.g. a custom adapter error, sandbox crash).
+   */
+  kind: 'transport' | 'backend';
+  message: string;
+  /** Upstream HTTP status when known. `0` for connection / abort errors. */
+  status?: number;
+  /** Truncated response body (≤2 KiB). Diagnostic only — never machine-parsed. */
+  body?: string;
+}
+/**
+ *
+ * OpenAI Chat Completions tool descriptor. The shape mirrors the
+ * `/v1/chat/completions` `tools[]` parameter so callers can pass tool
+ * definitions through `createOpenAICompatibleBackend({ tools })` without any
+ * runtime translation. The router proxies this shape verbatim to Anthropic
+ * (translated server-side), DeepSeek, Groq, OpenAI, and Gemini — every model
+ * that the eval surface targets.
+ *
+ * Callers that build their tool list from MCP servers should run a one-shot
+ * MCP `tools/list` at config time and project the result into this shape. The
+ * runtime intentionally does NOT depend on `@modelcontextprotocol/sdk` —
+ * keeping the backend transport thin lets domain repos own MCP plumbing.
+ *
+ * @stable
+ */
+interface OpenAIChatTool {
+  type: 'function';
+  function: {
+    name: string;
+    description?: string;
+    parameters?: Record<string, unknown>;
+  };
+}
+/**
+ *
+ * `tool_choice` parameter for OpenAI-compat chat. Same shape as the OpenAI
+ * spec: `'auto'` (default — model decides), `'none'` (disable tool calling
+ * for this turn), `'required'` (force a tool call), or a specific function
+ * pin `{ type: 'function', function: { name } }`.
+ *
+ * @stable
+ */
+type OpenAIChatToolChoice = 'auto' | 'none' | 'required' | {
+  type: 'function';
+  function: {
+    name: string;
+  };
+};
+/**
+ *
+ * `response_format` parameter for OpenAI-compatible chat endpoints. Use
+ * `json_object` when the caller needs syntactically valid JSON, or
+ * `json_schema` when the upstream provider supports schema-constrained JSON.
+ *
+ * @stable
+ */
+type OpenAIChatResponseFormat = {
+  type: 'text';
+} | {
+  type: 'json_object';
+} | {
+  type: 'json_schema';
+  json_schema: Record<string, unknown>;
+};
+/** @stable */
+type RuntimeStreamEvent = {
+  type: 'task_start';
+  task: AgentTaskSpec;
+  timestamp: string;
+} | {
+  type: 'readiness_start';
+  task: AgentTaskSpec;
+  timestamp: string;
+} | {
+  type: 'readiness_end';
+  task: AgentTaskSpec;
+  knowledge: KnowledgeReadinessReport;
+  decision: KnowledgeReadinessDecision;
+  timestamp: string;
+} | {
+  type: 'questions_start';
+  task: AgentTaskSpec;
+  questions: UserQuestion[];
+  timestamp: string;
+} | {
+  type: 'questions_end';
+  task: AgentTaskSpec;
+  questions: UserQuestion[];
+  userAnswers: Record<string, string>;
+  timestamp: string;
+} | {
+  type: 'acquisition_start';
+  task: AgentTaskSpec;
+  acquisitionPlans: DataAcquisitionPlan[];
+  timestamp: string;
+} | {
+  type: 'acquisition_end';
+  task: AgentTaskSpec;
+  acquisitionPlans: DataAcquisitionPlan[];
+  acquiredEvidenceIds: string[];
+  timestamp: string;
+} | {
+  type: 'session_created';
+  task: AgentTaskSpec;
+  session: RuntimeSession;
+  timestamp: string;
+} | {
+  type: 'session_resumed';
+  task: AgentTaskSpec;
+  session: RuntimeSession;
+  timestamp: string;
+} | {
+  type: 'backend_start';
+  task: AgentTaskSpec;
+  session: RuntimeSession;
+  backend: string;
+  timestamp: string;
+} | {
+  type: 'text_delta';
+  task?: AgentTaskSpec;
+  session?: RuntimeSession;
+  text: string;
+  timestamp?: string;
+} | {
+  type: 'reasoning_delta';
+  task?: AgentTaskSpec;
+  session?: RuntimeSession;
+  text: string;
+  timestamp?: string;
+} | {
+  type: 'tool_call';
+  task?: AgentTaskSpec;
+  session?: RuntimeSession;
+  toolName: string;
+  toolCallId?: string;
+  args?: unknown;
+  timestamp?: string;
+} | {
+  type: 'tool_result';
+  task?: AgentTaskSpec;
+  session?: RuntimeSession;
+  toolName: string;
+  toolCallId?: string;
+  result?: unknown;
+  timestamp?: string;
+} | {
+  type: 'llm_call';
+  task?: AgentTaskSpec;
+  session?: RuntimeSession;
+  model: string;
+  tokensIn?: number;
+  tokensOut?: number;
+  costUsd?: number;
+  latencyMs?: number;
+  finishReason?: string;
+  timestamp?: string;
+} | {
+  type: 'artifact';
+  task?: AgentTaskSpec;
+  session?: RuntimeSession;
+  artifactId: string;
+  name?: string;
+  mimeType?: string;
+  uri?: string;
+  content?: string;
+  metadata?: Record<string, unknown>;
+  timestamp?: string;
+} | {
+  type: 'proposal_created';
+  task?: AgentTaskSpec;
+  session?: RuntimeSession;
+  proposalId: string;
+  title: string;
+  status?: 'pending' | 'approved' | 'rejected';
+  content?: string;
+  timestamp?: string;
+} | {
+  type: 'backend_error';
+  task: AgentTaskSpec;
+  session?: RuntimeSession;
+  backend: string;
+  message: string;
+  recoverable: boolean;
+  /**
+   * Typed transport diagnostic. Present when the upstream returned a
+   * non-success HTTP status or every retry attempt threw. Consumers MUST
+   * surface this onto their `RunRecord.error` — silently treating a
+   * `backend_error` as "no output" hides credit exhaustion, auth failure,
+   * and upstream outages from operators.
+   *  - `kind: 'transport'` — HTTP / network failure with optional `status`
+   *    + truncated response `body`.
+   *  - `kind: 'backend'` — the backend's `stream()` generator threw for a
+   *    reason that isn't a recognized transport failure.
+   */
+  error?: BackendErrorDetail;
+  timestamp: string;
+} | {
+  type: 'backend_end';
+  task: AgentTaskSpec;
+  session: RuntimeSession;
+  backend: string;
+  timestamp: string;
+} | {
+  type: 'task_end';
+  task: AgentTaskSpec;
+  status: AgentTaskStatus;
+  reason: string;
+  timestamp: string;
+} | {
+  type: 'final';
+  task: AgentTaskSpec;
+  session?: RuntimeSession;
+  status: AgentTaskStatus;
+  reason: string;
+  text?: string;
+  metadata?: Record<string, unknown>;
+  /**
+   * Typed terminal-error diagnostic. Mirrors the `backend_error.error`
+   * shape so a consumer that only listens for `final` still receives a
+   * loud, structured failure when the backend never produced output. Only
+   * set when `status !== 'completed'`. Consumers building a `RunRecord`
+   * MUST map this to `RunRecord.error` rather than recording silent
+   * `error: null` with empty `finalText`.
+   */
+  error?: BackendErrorDetail;
+  timestamp: string;
+};
+/** @stable */
+interface RuntimeSession {
+  id: string;
+  backend: string;
+  status: 'active' | 'completed' | 'failed' | 'aborted';
+  resumeToken?: string;
+  createdAt: string;
+  updatedAt: string;
+  metadata?: Record<string, unknown>;
+}
+/** @stable */
+interface RuntimeSessionStore {
+  get(sessionId: string): Promise<RuntimeSession | undefined> | RuntimeSession | undefined;
+  put(session: RuntimeSession): Promise<void> | void;
+  appendEvent?(sessionId: string, event: RuntimeStreamEvent): Promise<void> | void;
+  listEvents?(sessionId: string): Promise<RuntimeStreamEvent[]> | RuntimeStreamEvent[];
+}
+/** @stable */
+interface AgentBackendInput {
+  task: AgentTaskSpec;
+  message?: string;
+  messages?: Array<{
+    role: string;
+    content: string;
+  }>;
+  inputs?: Record<string, unknown>;
+}
+/** @stable */
+interface AgentBackendContext {
+  task: AgentTaskSpec;
+  knowledge: KnowledgeReadinessReport;
+  session: RuntimeSession;
+  signal?: AbortSignal;
+  /**
+   * Conversation/run identifier when this call is part of a multi-agent run.
+   * Backends should stamp it into any trace/log emission so cross-participant
+   * events correlate. Absent when the call is a stand-alone `runAgentTask`.
+   */
+  runId?: string;
+  /**
+   * Deterministic turn id for this single call. Stable across retries of the
+   * same logical turn so a caching gateway / idempotent backend can dedupe.
+   */
+  turnId?: string;
+  /**
+   * If this call is itself nested inside a higher-order conversation
+   * (recursion via `createConversationBackend`), the enclosing turn's id.
+   * Used for trace stitching across nested orchestration.
+   */
+  parentTurnId?: string;
+  /**
+   * Headers to forward verbatim to any outbound HTTP the backend issues:
+   * `X-Tangle-Forwarded-Authorization`, `X-Tangle-Forwarded-Depth`,
+   * run/turn correlation. Backends that issue HTTP MUST merge these into
+   * the outbound request; backends that don't issue HTTP may ignore them.
+   */
+  propagatedHeaders?: Readonly<Record<string, string>>;
+}
+/** @stable */
+interface AgentExecutionBackend<TInput extends AgentBackendInput = AgentBackendInput> {
+  kind: string;
+  start?(input: TInput, context: Omit<AgentBackendContext, 'session'> & {
+    requestedSessionId?: string;
+  }): Promise<RuntimeSession> | RuntimeSession;
+  resume?(session: RuntimeSession, input: TInput, context: Omit<AgentBackendContext, 'session'>): Promise<RuntimeSession> | RuntimeSession;
+  stream(input: TInput, context: AgentBackendContext): AsyncIterable<RuntimeStreamEvent>;
+  stop?(session: RuntimeSession, reason: string): Promise<void> | void;
+}
+/** @stable */
+interface RunAgentTaskStreamOptions<TInput extends AgentBackendInput = AgentBackendInput> {
+  task: AgentTaskSpec;
+  backend: AgentExecutionBackend<TInput>;
+  input?: Omit<TInput, 'task'>;
+  knowledge?: AgentKnowledgeProvider;
+  sessionStore?: RuntimeSessionStore;
+  sessionId?: string;
+  resume?: boolean;
+  signal?: AbortSignal;
+  minimumReadinessScore?: number;
+}
+/** @stable */
+interface RunAgentTaskOptions<TState, TAction, TActionResult, TEval extends ControlEvalResult = ControlEvalResult> {
+  task: AgentTaskSpec;
+  adapter: AgentAdapter<TState, TAction, TActionResult, TEval>;
+  knowledge?: AgentKnowledgeProvider;
+  onEvent?: AgentRuntimeEventSink<TState, TAction, TActionResult, TEval>;
+  store?: TraceStore;
+  signal?: AbortSignal;
+  scenarioId?: string;
+  projectId?: string;
+  variantId?: string;
+  minimumReadinessScore?: number;
+}
+/** @stable */
+interface AgentTaskRunResult<TState, TAction, TActionResult, TEval extends ControlEvalResult = ControlEvalResult> {
+  task: AgentTaskSpec;
+  status: AgentTaskStatus;
+  knowledge: KnowledgeReadinessReport;
+  questions: UserQuestion[];
+  acquisitionPlans: DataAcquisitionPlan[];
+  userAnswers: Record<string, string>;
+  acquiredEvidenceIds: string[];
+  control: ControlRunResult<TState, TAction, TActionResult, TEval>;
+  runRecords: RunRecord[];
+}
+/** @stable */
+interface KnowledgeReadinessDecision {
+  passed: boolean;
+  status: 'ready' | 'blocked' | 'caveat';
+  reason: string;
+  readinessScore: number;
+  recommendedAction: KnowledgeReadinessReport['recommendedAction'];
+  severity: KnowledgeReadinessReport['severity'];
+  blockingGapIds: string[];
+  nonBlockingGapIds: string[];
+}
+//#endregion
+export { RunAgentTaskOptions as _, AgentKnowledgeProvider as a, RuntimeSessionStore as b, AgentTaskContext as c, AgentTaskStatus as d, BackendErrorDetail as f, OpenAIChatToolChoice as g, OpenAIChatTool as h, AgentExecutionBackend as i, AgentTaskRunResult as l, OpenAIChatResponseFormat as m, AgentBackendContext as n, AgentRuntimeEvent as o, KnowledgeReadinessDecision as p, AgentBackendInput as r, AgentRuntimeEventSink as s, AgentAdapter as t, AgentTaskSpec as u, RunAgentTaskStreamOptions as v, RuntimeStreamEvent as x, RuntimeSession as y };
+//# sourceMappingURL=types-C9j4qg6l.d.ts.map

package/dist/types-Cja5OTGh.d.ts

@@ -0,0 +1,190 @@
+import { AnalystFinding, AnalystRunEvent, AnalystRunInputs, AnalystRunResult, FindingsDiff } from "@tangle-network/agent-eval";
+//#region src/analyst-loop/types.d.ts
+/** Knowledge-side bridge — consumers wire `proposeFromFindings` from agent-knowledge. */
+interface KnowledgeProposalSource<TProposal = unknown> {
+  /**
+   * Convert a findings batch into proposals. Returns the partitioned
+   * result so the loop can report malformed
+   * findings. Implementations SHOULD honour the convention "non-
+   * knowledge subjects return null and are counted in `skipped`."
+   */
+  proposeFromFindings(findings: ReadonlyArray<AnalystFinding>): Promise<KnowledgeProposalBatch<TProposal>> | KnowledgeProposalBatch<TProposal>;
+}
+interface KnowledgeProposalBatch<TProposal = unknown> {
+  proposals: TProposal[];
+  skipped: number;
+  errors: Array<{
+    findingId: string;
+    subject: string;
+    message: string;
+  }>;
+}
+/** Agent-surface bridge — proposes prompt, skill, tool, and scaffolding edits. */
+interface ImprovementProposalSource<TEdit = unknown> {
+  proposeFromFindings(findings: ReadonlyArray<AnalystFinding>): Promise<ImprovementEditBatch<TEdit>> | ImprovementEditBatch<TEdit>;
+}
+interface ImprovementEditBatch<TEdit = unknown> {
+  edits: TEdit[];
+  skipped: number;
+  errors: Array<{
+    findingId: string;
+    subject: string;
+    message: string;
+  }>;
+}
+interface RunAnalystLoopOpts {
+  /** The run id of the work being analysed. */
+  runId: string;
+  /** The registry — pre-populated with the analyst kinds the consumer wants. */
+  registry: AnalystRegistryLike;
+  /** Inputs forwarded to `registry.run` — typically `{ traceStore }`. */
+  inputs: AnalystRunInputs;
+  /**
+   * Findings ledger. The loop appends the new run + diffs against the
+   * baseline run before running adapters. Pass `null` to skip
+   * persistence (useful for one-shot analyses).
+   */
+  findingsStore: FindingsStoreLike | null;
+  /**
+   * Prior run id whose findings the loop reads + provides to analysts
+   * as `priorFindings` AND diffs against. When omitted, the loop picks
+   * the most recent run in the store (excluding `runId` itself); pass
+   * `null` to explicitly start with an empty baseline.
+   */
+  baselineRunId?: string | null;
+  /** Strategy for forwarding prior findings into `ctx.priorFindings`. */
+  priorFindingsStrategy?: 'per-kind' | 'wildcard' | 'none';
+  /** Knowledge-side bridge — usually `agent-knowledge`'s `proposeFromFindings`. */
+  knowledgeProposalSource?: KnowledgeProposalSource;
+  /** Agent-surface bridge — usually a prompt, skill, or tool diff producer. */
+  improvementProposalSource?: ImprovementProposalSource;
+  /** Optional logger. Defaults to `console.log` for `[analyst-loop]` lines. */
+  log?: (msg: string, fields?: Record<string, unknown>) => void;
+  /**
+   * Event sink for live progress. Called for every phase of the loop:
+   * baseline resolution, registry events forwarded from `runStream`,
+   * ledger persistence, diff, knowledge / improvement proposals, and
+   * the terminal `loop-completed`. Awaited so
+   * slow sinks (SSE write, JSONL append) apply backpressure.
+   *
+   * The callback MUST NOT throw — exceptions propagate and abort the
+   * loop. Catch + swallow internally if your sink is unreliable.
+   */
+  onEvent?: (event: AnalystLoopEvent) => void | Promise<void>;
+}
+interface RunAnalystLoopResult<TProposal = unknown, TEdit = unknown> {
+  runId: string;
+  baselineRunId: string | null;
+  analystResult: AnalystRunResult;
+  diff: FindingsDiff | null;
+  knowledge: KnowledgeReport<TProposal> | null;
+  improvement: ImprovementReport<TEdit> | null;
+}
+interface KnowledgeReport<TProposal = unknown> {
+  proposals: TProposal[];
+  skipped: number;
+  errors: Array<{
+    findingId: string;
+    subject: string;
+    message: string;
+  }>;
+}
+interface ImprovementReport<TEdit = unknown> {
+  edits: TEdit[];
+  skipped: number;
+  errors: Array<{
+    findingId: string;
+    subject: string;
+    message: string;
+  }>;
+}
+/**
+ * Narrowed shape we accept for `AnalystRegistry` so the orchestrator
+ * remains testable without instantiating the real class. The real
+ * class satisfies this trivially.
+ */
+interface AnalystRegistryLike {
+  list(): ReadonlyArray<{
+    id: string;
+  }>;
+  run(runId: string, inputs: AnalystRunInputs, opts?: {
+    priorFindings?: ReadonlyArray<AnalystFinding> | Record<string, ReadonlyArray<AnalystFinding>>;
+    [k: string]: unknown;
+  }): Promise<AnalystRunResult>;
+}
+/** Narrowed shape we accept for `FindingsStore`. */
+interface FindingsStoreLike {
+  loadAll(): ReadonlyArray<AnalystFinding & {
+    run_id: string;
+  }>;
+  loadRun(runId: string): ReadonlyArray<AnalystFinding & {
+    run_id: string;
+  }>;
+  append(runId: string, findings: ReadonlyArray<AnalystFinding>): Promise<void>;
+}
+/**
+ * Narrow the `AnalystRegistryLike` further when we need streaming: the
+ * loop checks if the registry exposes `runStream` and uses it when
+ * present, falling back to `run()` otherwise. This keeps the type
+ * surface backwards-compatible — older registry shims that only
+ * implement `run` still work; they just don't forward per-analyst
+ * events.
+ */
+interface AnalystRegistryStreamingLike extends AnalystRegistryLike {
+  runStream?(runId: string, inputs: AnalystRunInputs, opts?: {
+    priorFindings?: ReadonlyArray<AnalystFinding> | Record<string, ReadonlyArray<AnalystFinding>>;
+    [k: string]: unknown;
+  }): AsyncIterable<AnalystRunEvent>;
+}
+/**
+ * Events emitted by `runAnalystLoop` via `opts.onEvent`. UIs and
+ * JSONL tail-sinks consume this stream. The loop awaits each
+ * callback so a slow sink applies backpressure to the loop's phases
+ * (e.g. an SSE write that takes 200ms delays the next phase by
+ * 200ms — the loop never out-paces its observer).
+ *
+ * Forwards registry events verbatim via `analyst` so consumers don't
+ * have to wire two streams.
+ */
+type AnalystLoopEvent = {
+  type: 'baseline-resolved';
+  runId: string;
+  baselineRunId: string | null;
+  priorFindingCount: number;
+} | {
+  type: 'analyst';
+  runId: string;
+  /** Forwarded verbatim from `AnalystRegistry.runStream`. */
+  event: AnalystRunEvent;
+} | {
+  type: 'findings-persisted';
+  runId: string;
+  count: number;
+} | {
+  type: 'diff-computed';
+  runId: string;
+  baselineRunId: string;
+  appeared: number;
+  disappeared: number;
+  persisted: number;
+  changed: number;
+} | {
+  type: 'knowledge-proposed';
+  runId: string;
+  proposalCount: number;
+  skipped: number;
+  errors: number;
+} | {
+  type: 'improvement-proposed';
+  runId: string;
+  editCount: number;
+  skipped: number;
+  errors: number;
+} | {
+  type: 'loop-completed';
+  runId: string;
+  durationMs: number;
+};
+//#endregion
+export { ImprovementEditBatch as a, KnowledgeProposalBatch as c, RunAnalystLoopOpts as d, RunAnalystLoopResult as f, FindingsStoreLike as i, KnowledgeProposalSource as l, AnalystRegistryLike as n, ImprovementProposalSource as o, AnalystRegistryStreamingLike as r, ImprovementReport as s, AnalystLoopEvent as t, KnowledgeReport as u };
+//# sourceMappingURL=types-Cja5OTGh.d.ts.map