@tangle-network/agent-runtime 0.1.0 → 0.2.0

package/README.md

@@ -55,6 +55,33 @@ If knowledge readiness fails, `runAgentTask` stops before domain actions by
 default. Adapters can override `onKnowledgeBlocked` to emit a domain action,
 such as asking a user, querying a connector, or inspecting a repo.
 
+`runAgentTask` also emits typed lifecycle events through `onEvent`:
+
+```ts
+await runAgentTask({
+  task,
+  adapter,
+  knowledge,
+  onEvent(event) {
+    console.log(event.type)
+  },
+})
+```
+
+Events cover readiness, question answering, acquisition, control-loop steps,
+and task completion. This keeps streaming UI, logs, and telemetry out of domain
+adapters while making every runtime transition observable.
+
+Knowledge providers may implement:
+
+- `buildReadiness`
+- `answerQuestions`
+- `executeAcquisitionPlans`
+- `refreshReadiness`
+
+That lets a task collect missing context before the control loop starts, then
+rerun readiness scoring against the new evidence.
+
 ## Package Boundaries
 
 - `agent-runtime` owns the reusable lifecycle and adapter contracts.

package/dist/index.d.ts

@@ -15,6 +15,12 @@ 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;
 }
 interface AgentTaskContext<TState, TAction, TActionResult, TEval extends ControlEvalResult = ControlEvalResult> {
     task: AgentTaskSpec;
@@ -72,10 +78,59 @@ interface AgentAdapter<TState, TAction, TActionResult, TEval extends ControlEval
     }): number | undefined;
     projectRunRecords?(result: ControlRunResult<TState, TAction, TActionResult, TEval>, task: AgentTaskSpec): RunRecord[];
 }
+type AgentTaskStatus = 'completed' | 'blocked' | 'failed' | 'aborted';
+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;
+};
+type AgentRuntimeEventSink<TState = unknown, TAction = unknown, TActionResult = unknown, TEval extends ControlEvalResult = ControlEvalResult> = (event: AgentRuntimeEvent<TState, TAction, TActionResult, TEval>) => Promise<void> | void;
 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;
@@ -85,12 +140,15 @@ interface RunAgentTaskOptions<TState, TAction, TActionResult, TEval extends Cont
 }
 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[];
 }
 declare function runAgentTask<TState, TAction, TActionResult, TEval extends ControlEvalResult = ControlEvalResult>(options: RunAgentTaskOptions<TState, TAction, TActionResult, TEval>): Promise<AgentTaskRunResult<TState, TAction, TActionResult, TEval>>;
 
-export { type AgentAdapter, type AgentKnowledgeProvider, type AgentTaskContext, type AgentTaskRunResult, type AgentTaskSpec, type RunAgentTaskOptions, runAgentTask };
+export { type AgentAdapter, type AgentKnowledgeProvider, type AgentRuntimeEvent, type AgentRuntimeEventSink, type AgentTaskContext, type AgentTaskRunResult, type AgentTaskSpec, type AgentTaskStatus, type RunAgentTaskOptions, runAgentTask };

package/dist/index.js

@@ -8,12 +8,27 @@ import {
 } from "@tangle-network/agent-eval";
 async function runAgentTask(options) {
   const task = options.task;
-  const knowledge = await buildReadiness(task, options.knowledge);
+  await emit(options.onEvent, { type: "task_start", task });
+  await emit(options.onEvent, { type: "readiness_start", task });
+  let knowledge = await buildReadiness(task, options.knowledge);
+  await emit(options.onEvent, { type: "readiness_end", task, knowledge });
   const questions = userQuestionsForKnowledgeGaps(knowledge.blockingMissingRequirements);
   const acquisitionPlans = acquisitionPlansForKnowledgeGaps([
     ...knowledge.blockingMissingRequirements,
     ...knowledge.nonBlockingGaps
   ]);
+  const preflight = await runKnowledgePreflight(task, questions, acquisitionPlans, options.knowledge, options.onEvent);
+  if (options.knowledge?.refreshReadiness && (Object.keys(preflight.userAnswers).length > 0 || preflight.acquiredEvidenceIds.length > 0)) {
+    await emit(options.onEvent, { type: "readiness_start", task });
+    knowledge = await options.knowledge.refreshReadiness({
+      task,
+      previous: knowledge,
+      userAnswers: preflight.userAnswers,
+      acquiredEvidenceIds: preflight.acquiredEvidenceIds
+    });
+    await emit(options.onEvent, { type: "readiness_end", task, knowledge });
+  }
+  await emit(options.onEvent, { type: "control_start", task, knowledge });
   const control = await runAgentControlLoop({
     intent: task.intent,
     budget: task.budget,
@@ -41,17 +56,39 @@ async function runAgentTask(options) {
     },
     act: (action, ctx) => options.adapter.act(action, toAgentContext(task, knowledge, ctx)),
     shouldStop: options.adapter.shouldStop ? (ctx) => options.adapter.shouldStop(toAgentContext(task, knowledge, ctx)) : void 0,
-    getActionCostUsd: options.adapter.getActionCostUsd ? ({ action, result, state, evals, history }) => options.adapter.getActionCostUsd({ action, result, task, state, evals, history }) : void 0
+    getActionCostUsd: options.adapter.getActionCostUsd ? ({ action, result, state, evals, history }) => options.adapter.getActionCostUsd({ action, result, task, state, evals, history }) : void 0,
+    onStep: (step) => emit(options.onEvent, { type: "control_step", task, step })
   });
+  await emit(options.onEvent, { type: "control_end", task, control });
+  const status = statusFromControl(control);
+  await emit(options.onEvent, { type: "task_end", task, status, reason: control.reason });
   return {
     task,
+    status,
     knowledge,
     questions,
     acquisitionPlans,
+    userAnswers: preflight.userAnswers,
+    acquiredEvidenceIds: preflight.acquiredEvidenceIds,
     control,
     runRecords: options.adapter.projectRunRecords?.(control, task) ?? []
   };
 }
+async function runKnowledgePreflight(task, questions, acquisitionPlans, provider, onEvent) {
+  let userAnswers = {};
+  let acquiredEvidenceIds = [];
+  if (questions.length > 0 && provider?.answerQuestions) {
+    await emit(onEvent, { type: "questions_start", task, questions });
+    userAnswers = await provider.answerQuestions(questions, task);
+    await emit(onEvent, { type: "questions_end", task, questions, userAnswers });
+  }
+  if (acquisitionPlans.length > 0 && provider?.executeAcquisitionPlans) {
+    await emit(onEvent, { type: "acquisition_start", task, acquisitionPlans });
+    acquiredEvidenceIds = await provider.executeAcquisitionPlans(acquisitionPlans, task);
+    await emit(onEvent, { type: "acquisition_end", task, acquisitionPlans, acquiredEvidenceIds });
+  }
+  return { userAnswers, acquiredEvidenceIds };
+}
 function buildReadiness(task, provider) {
   if (provider?.buildReadiness) return provider.buildReadiness(task);
   return scoreKnowledgeReadiness({
@@ -63,6 +100,15 @@ function buildReadiness(task, provider) {
 function isKnowledgeBlocked(evals) {
   return evals.some((evalResult) => evalResult.id === "knowledge-ready" && !evalResult.passed);
 }
+function statusFromControl(control) {
+  if (control.stoppedBy === "abort") return "aborted";
+  if (control.reason.includes("knowledge readiness blocked")) return "blocked";
+  if (control.pass) return "completed";
+  return "failed";
+}
+async function emit(sink, event) {
+  await sink?.(event);
+}
 function toAgentContext(task, knowledge, ctx) {
   return {
     task,

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import {\n  acquisitionPlansForKnowledgeGaps,\n  blockingKnowledgeEval,\n  runAgentControlLoop,\n  scoreKnowledgeReadiness,\n  userQuestionsForKnowledgeGaps,\n  type ControlBudget,\n  type ControlContext,\n  type ControlDecision,\n  type ControlEvalResult,\n  type ControlRunResult,\n  type ControlStep,\n  type DataAcquisitionPlan,\n  type KnowledgeReadinessReport,\n  type KnowledgeRequirement,\n  type RunRecord,\n  type TraceStore,\n  type UserQuestion,\n} from '@tangle-network/agent-eval'\n\nexport interface AgentTaskSpec {\n  id: string\n  intent: string\n  /** Domain is metadata, not an architectural boundary: tax, legal, gtm, creative, blueprint, redteam, etc. */\n  domain?: string\n  inputs?: Record<string, unknown>\n  requiredKnowledge?: KnowledgeRequirement[]\n  budget?: Partial<ControlBudget>\n  metadata?: Record<string, unknown>\n}\n\nexport interface AgentKnowledgeProvider {\n  buildReadiness?(task: AgentTaskSpec): Promise<KnowledgeReadinessReport> | KnowledgeReadinessReport\n  answerQuestions?(questions: UserQuestion[], task: AgentTaskSpec): Promise<Record<string, string>> | Record<string, string>\n  executeAcquisitionPlans?(plans: DataAcquisitionPlan[], task: AgentTaskSpec): Promise<string[]> | string[]\n}\n\nexport interface AgentTaskContext<TState, TAction, TActionResult, TEval extends ControlEvalResult = ControlEvalResult> {\n  task: AgentTaskSpec\n  knowledge: KnowledgeReadinessReport\n  state: TState\n  evals: TEval[]\n  history: ControlStep<TState, TAction, TActionResult, TEval>[]\n  budget: ControlBudget\n  stepIndex: number\n  wallMs: number\n  spentCostUsd: number\n  remainingCostUsd?: number\n  abortSignal: AbortSignal\n}\n\nexport interface AgentAdapter<TState, TAction, TActionResult, TEval extends ControlEvalResult = ControlEvalResult> {\n  observe(ctx: {\n    task: AgentTaskSpec\n    knowledge: KnowledgeReadinessReport\n    history: ControlStep<TState, TAction, TActionResult, TEval>[]\n    abortSignal: AbortSignal\n  }): Promise<TState> | TState\n\n  validate(ctx: {\n    task: AgentTaskSpec\n    knowledge: KnowledgeReadinessReport\n    state: TState\n    history: ControlStep<TState, TAction, TActionResult, TEval>[]\n    abortSignal: AbortSignal\n  }): Promise<TEval[]> | TEval[]\n\n  decide(ctx: AgentTaskContext<TState, TAction, TActionResult, TEval>): Promise<ControlDecision<TAction>> | ControlDecision<TAction>\n\n  act(action: TAction, ctx: AgentTaskContext<TState, TAction, TActionResult, TEval>): Promise<TActionResult> | TActionResult\n\n  shouldStop?(ctx: AgentTaskContext<TState, TAction, TActionResult, TEval>): Promise<{\n    stop: boolean\n    pass: boolean\n    reason: string\n    score?: number\n  }> | {\n    stop: boolean\n    pass: boolean\n    reason: string\n    score?: number\n  }\n\n  onKnowledgeBlocked?(ctx: {\n    task: AgentTaskSpec\n    knowledge: KnowledgeReadinessReport\n    questions: UserQuestion[]\n    acquisitionPlans: DataAcquisitionPlan[]\n  }): Promise<ControlDecision<TAction>> | ControlDecision<TAction>\n\n  getActionCostUsd?(ctx: {\n    action: TAction\n    result: TActionResult\n    task: AgentTaskSpec\n    state: TState\n    evals: TEval[]\n    history: ControlStep<TState, TAction, TActionResult, TEval>[]\n  }): number | undefined\n\n  projectRunRecords?(result: ControlRunResult<TState, TAction, TActionResult, TEval>, task: AgentTaskSpec): RunRecord[]\n}\n\nexport interface RunAgentTaskOptions<TState, TAction, TActionResult, TEval extends ControlEvalResult = ControlEvalResult> {\n  task: AgentTaskSpec\n  adapter: AgentAdapter<TState, TAction, TActionResult, TEval>\n  knowledge?: AgentKnowledgeProvider\n  store?: TraceStore\n  signal?: AbortSignal\n  scenarioId?: string\n  projectId?: string\n  variantId?: string\n  minimumReadinessScore?: number\n}\n\nexport interface AgentTaskRunResult<TState, TAction, TActionResult, TEval extends ControlEvalResult = ControlEvalResult> {\n  task: AgentTaskSpec\n  knowledge: KnowledgeReadinessReport\n  questions: UserQuestion[]\n  acquisitionPlans: DataAcquisitionPlan[]\n  control: ControlRunResult<TState, TAction, TActionResult, TEval>\n  runRecords: RunRecord[]\n}\n\nexport async function runAgentTask<TState, TAction, TActionResult, TEval extends ControlEvalResult = ControlEvalResult>(\n  options: RunAgentTaskOptions<TState, TAction, TActionResult, TEval>,\n): Promise<AgentTaskRunResult<TState, TAction, TActionResult, TEval>> {\n  const task = options.task\n  const knowledge = await buildReadiness(task, options.knowledge)\n  const questions = userQuestionsForKnowledgeGaps(knowledge.blockingMissingRequirements)\n  const acquisitionPlans = acquisitionPlansForKnowledgeGaps([\n    ...knowledge.blockingMissingRequirements,\n    ...knowledge.nonBlockingGaps,\n  ])\n\n  const control = await runAgentControlLoop<TState, TAction, TActionResult, TEval>({\n    intent: task.intent,\n    budget: task.budget,\n    signal: options.signal,\n    store: options.store,\n    scenarioId: options.scenarioId ?? task.id,\n    projectId: options.projectId,\n    variantId: options.variantId,\n    observe: ({ history, abortSignal }) => options.adapter.observe({ task, knowledge, history, abortSignal }),\n    validate: async ({ state, history, abortSignal }) => {\n      const readinessEval = blockingKnowledgeEval(knowledge, { minimumScore: options.minimumReadinessScore })\n      const evals = await options.adapter.validate({ task, knowledge, state, history, abortSignal })\n      return [readinessEval as TEval, ...evals]\n    },\n    decide: (ctx) => {\n      if (isKnowledgeBlocked(ctx.evals)) {\n        return options.adapter.onKnowledgeBlocked?.({ task, knowledge, questions, acquisitionPlans }) ?? {\n          type: 'stop',\n          pass: false,\n          score: knowledge.readinessScore,\n          reason: `knowledge readiness blocked: ${knowledge.reason}`,\n        }\n      }\n      return options.adapter.decide(toAgentContext(task, knowledge, ctx))\n    },\n    act: (action, ctx) => options.adapter.act(action, toAgentContext(task, knowledge, ctx)),\n    shouldStop: options.adapter.shouldStop\n      ? (ctx) => options.adapter.shouldStop!(toAgentContext(task, knowledge, ctx))\n      : undefined,\n    getActionCostUsd: options.adapter.getActionCostUsd\n      ? ({ action, result, state, evals, history }) => options.adapter.getActionCostUsd!({ action, result, task, state, evals, history })\n      : undefined,\n  })\n\n  return {\n    task,\n    knowledge,\n    questions,\n    acquisitionPlans,\n    control,\n    runRecords: options.adapter.projectRunRecords?.(control, task) ?? [],\n  }\n}\n\nfunction buildReadiness(\n  task: AgentTaskSpec,\n  provider: AgentKnowledgeProvider | undefined,\n): Promise<KnowledgeReadinessReport> | KnowledgeReadinessReport {\n  if (provider?.buildReadiness) return provider.buildReadiness(task)\n  return scoreKnowledgeReadiness({\n    taskId: task.id,\n    requirements: task.requiredKnowledge ?? [],\n    metadata: { domain: task.domain, ...task.metadata },\n  })\n}\n\nfunction isKnowledgeBlocked(evals: ControlEvalResult[]): boolean {\n  return evals.some((evalResult) => evalResult.id === 'knowledge-ready' && !evalResult.passed)\n}\n\nfunction toAgentContext<TState, TAction, TActionResult, TEval extends ControlEvalResult>(\n  task: AgentTaskSpec,\n  knowledge: KnowledgeReadinessReport,\n  ctx: ControlContext<TState, TAction, TActionResult, TEval>,\n): AgentTaskContext<TState, TAction, TActionResult, TEval> {\n  return {\n    task,\n    knowledge,\n    state: ctx.state,\n    evals: ctx.evals,\n    history: ctx.history,\n    budget: ctx.budget,\n    stepIndex: ctx.stepIndex,\n    wallMs: ctx.wallMs,\n    spentCostUsd: ctx.spentCostUsd,\n    remainingCostUsd: ctx.remainingCostUsd,\n    abortSignal: ctx.abortSignal,\n  }\n}\n\nexport type {\n  ControlBudget,\n  ControlDecision,\n  ControlEvalResult,\n  ControlRunResult,\n  ControlStep,\n  DataAcquisitionPlan,\n  KnowledgeReadinessReport,\n  KnowledgeRequirement,\n  RunRecord,\n  UserQuestion,\n} from '@tangle-network/agent-eval'\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import {\n  acquisitionPlansForKnowledgeGaps,\n  blockingKnowledgeEval,\n  runAgentControlLoop,\n  scoreKnowledgeReadiness,\n  userQuestionsForKnowledgeGaps,\n  type ControlBudget,\n  type ControlContext,\n  type ControlDecision,\n  type ControlEvalResult,\n  type ControlRunResult,\n  type ControlStep,\n  type DataAcquisitionPlan,\n  type KnowledgeReadinessReport,\n  type KnowledgeRequirement,\n  type RunRecord,\n  type TraceStore,\n  type UserQuestion,\n} from '@tangle-network/agent-eval'\n\nexport interface AgentTaskSpec {\n  id: string\n  intent: string\n  /** Domain is metadata, not an architectural boundary: tax, legal, gtm, creative, blueprint, redteam, etc. */\n  domain?: string\n  inputs?: Record<string, unknown>\n  requiredKnowledge?: KnowledgeRequirement[]\n  budget?: Partial<ControlBudget>\n  metadata?: Record<string, unknown>\n}\n\nexport interface AgentKnowledgeProvider {\n  buildReadiness?(task: AgentTaskSpec): Promise<KnowledgeReadinessReport> | KnowledgeReadinessReport\n  answerQuestions?(questions: UserQuestion[], task: AgentTaskSpec): Promise<Record<string, string>> | Record<string, string>\n  executeAcquisitionPlans?(plans: DataAcquisitionPlan[], task: AgentTaskSpec): Promise<string[]> | string[]\n  refreshReadiness?(input: {\n    task: AgentTaskSpec\n    previous: KnowledgeReadinessReport\n    userAnswers: Record<string, string>\n    acquiredEvidenceIds: string[]\n  }): Promise<KnowledgeReadinessReport> | KnowledgeReadinessReport\n}\n\nexport interface AgentTaskContext<TState, TAction, TActionResult, TEval extends ControlEvalResult = ControlEvalResult> {\n  task: AgentTaskSpec\n  knowledge: KnowledgeReadinessReport\n  state: TState\n  evals: TEval[]\n  history: ControlStep<TState, TAction, TActionResult, TEval>[]\n  budget: ControlBudget\n  stepIndex: number\n  wallMs: number\n  spentCostUsd: number\n  remainingCostUsd?: number\n  abortSignal: AbortSignal\n}\n\nexport interface AgentAdapter<TState, TAction, TActionResult, TEval extends ControlEvalResult = ControlEvalResult> {\n  observe(ctx: {\n    task: AgentTaskSpec\n    knowledge: KnowledgeReadinessReport\n    history: ControlStep<TState, TAction, TActionResult, TEval>[]\n    abortSignal: AbortSignal\n  }): Promise<TState> | TState\n\n  validate(ctx: {\n    task: AgentTaskSpec\n    knowledge: KnowledgeReadinessReport\n    state: TState\n    history: ControlStep<TState, TAction, TActionResult, TEval>[]\n    abortSignal: AbortSignal\n  }): Promise<TEval[]> | TEval[]\n\n  decide(ctx: AgentTaskContext<TState, TAction, TActionResult, TEval>): Promise<ControlDecision<TAction>> | ControlDecision<TAction>\n\n  act(action: TAction, ctx: AgentTaskContext<TState, TAction, TActionResult, TEval>): Promise<TActionResult> | TActionResult\n\n  shouldStop?(ctx: AgentTaskContext<TState, TAction, TActionResult, TEval>): Promise<{\n    stop: boolean\n    pass: boolean\n    reason: string\n    score?: number\n  }> | {\n    stop: boolean\n    pass: boolean\n    reason: string\n    score?: number\n  }\n\n  onKnowledgeBlocked?(ctx: {\n    task: AgentTaskSpec\n    knowledge: KnowledgeReadinessReport\n    questions: UserQuestion[]\n    acquisitionPlans: DataAcquisitionPlan[]\n  }): Promise<ControlDecision<TAction>> | ControlDecision<TAction>\n\n  getActionCostUsd?(ctx: {\n    action: TAction\n    result: TActionResult\n    task: AgentTaskSpec\n    state: TState\n    evals: TEval[]\n    history: ControlStep<TState, TAction, TActionResult, TEval>[]\n  }): number | undefined\n\n  projectRunRecords?(result: ControlRunResult<TState, TAction, TActionResult, TEval>, task: AgentTaskSpec): RunRecord[]\n}\n\nexport type AgentTaskStatus =\n  | 'completed'\n  | 'blocked'\n  | 'failed'\n  | 'aborted'\n\nexport type AgentRuntimeEvent<TState = unknown, TAction = unknown, TActionResult = unknown, TEval extends ControlEvalResult = ControlEvalResult> =\n  | { type: 'task_start'; task: AgentTaskSpec }\n  | { type: 'readiness_start'; task: AgentTaskSpec }\n  | { type: 'readiness_end'; task: AgentTaskSpec; knowledge: KnowledgeReadinessReport }\n  | { type: 'questions_start'; task: AgentTaskSpec; questions: UserQuestion[] }\n  | { type: 'questions_end'; task: AgentTaskSpec; questions: UserQuestion[]; userAnswers: Record<string, string> }\n  | { type: 'acquisition_start'; task: AgentTaskSpec; acquisitionPlans: DataAcquisitionPlan[] }\n  | { type: 'acquisition_end'; task: AgentTaskSpec; acquisitionPlans: DataAcquisitionPlan[]; acquiredEvidenceIds: string[] }\n  | { type: 'control_start'; task: AgentTaskSpec; knowledge: KnowledgeReadinessReport }\n  | { type: 'control_step'; task: AgentTaskSpec; step: ControlStep<TState, TAction, TActionResult, TEval> }\n  | { type: 'control_end'; task: AgentTaskSpec; control: ControlRunResult<TState, TAction, TActionResult, TEval> }\n  | { type: 'task_end'; task: AgentTaskSpec; status: AgentTaskStatus; reason: string }\n\nexport type AgentRuntimeEventSink<TState = unknown, TAction = unknown, TActionResult = unknown, TEval extends ControlEvalResult = ControlEvalResult> = (\n  event: AgentRuntimeEvent<TState, TAction, TActionResult, TEval>,\n) => Promise<void> | void\n\nexport interface RunAgentTaskOptions<TState, TAction, TActionResult, TEval extends ControlEvalResult = ControlEvalResult> {\n  task: AgentTaskSpec\n  adapter: AgentAdapter<TState, TAction, TActionResult, TEval>\n  knowledge?: AgentKnowledgeProvider\n  onEvent?: AgentRuntimeEventSink<TState, TAction, TActionResult, TEval>\n  store?: TraceStore\n  signal?: AbortSignal\n  scenarioId?: string\n  projectId?: string\n  variantId?: string\n  minimumReadinessScore?: number\n}\n\nexport interface AgentTaskRunResult<TState, TAction, TActionResult, TEval extends ControlEvalResult = ControlEvalResult> {\n  task: AgentTaskSpec\n  status: AgentTaskStatus\n  knowledge: KnowledgeReadinessReport\n  questions: UserQuestion[]\n  acquisitionPlans: DataAcquisitionPlan[]\n  userAnswers: Record<string, string>\n  acquiredEvidenceIds: string[]\n  control: ControlRunResult<TState, TAction, TActionResult, TEval>\n  runRecords: RunRecord[]\n}\n\nexport async function runAgentTask<TState, TAction, TActionResult, TEval extends ControlEvalResult = ControlEvalResult>(\n  options: RunAgentTaskOptions<TState, TAction, TActionResult, TEval>,\n): Promise<AgentTaskRunResult<TState, TAction, TActionResult, TEval>> {\n  const task = options.task\n  await emit(options.onEvent, { type: 'task_start', task })\n  await emit(options.onEvent, { type: 'readiness_start', task })\n  let knowledge = await buildReadiness(task, options.knowledge)\n  await emit(options.onEvent, { type: 'readiness_end', task, knowledge })\n  const questions = userQuestionsForKnowledgeGaps(knowledge.blockingMissingRequirements)\n  const acquisitionPlans = acquisitionPlansForKnowledgeGaps([\n    ...knowledge.blockingMissingRequirements,\n    ...knowledge.nonBlockingGaps,\n  ])\n  const preflight = await runKnowledgePreflight(task, questions, acquisitionPlans, options.knowledge, options.onEvent)\n  if (options.knowledge?.refreshReadiness && (Object.keys(preflight.userAnswers).length > 0 || preflight.acquiredEvidenceIds.length > 0)) {\n    await emit(options.onEvent, { type: 'readiness_start', task })\n    knowledge = await options.knowledge.refreshReadiness({\n      task,\n      previous: knowledge,\n      userAnswers: preflight.userAnswers,\n      acquiredEvidenceIds: preflight.acquiredEvidenceIds,\n    })\n    await emit(options.onEvent, { type: 'readiness_end', task, knowledge })\n  }\n\n  await emit(options.onEvent, { type: 'control_start', task, knowledge })\n  const control = await runAgentControlLoop<TState, TAction, TActionResult, TEval>({\n    intent: task.intent,\n    budget: task.budget,\n    signal: options.signal,\n    store: options.store,\n    scenarioId: options.scenarioId ?? task.id,\n    projectId: options.projectId,\n    variantId: options.variantId,\n    observe: ({ history, abortSignal }) => options.adapter.observe({ task, knowledge, history, abortSignal }),\n    validate: async ({ state, history, abortSignal }) => {\n      const readinessEval = blockingKnowledgeEval(knowledge, { minimumScore: options.minimumReadinessScore })\n      const evals = await options.adapter.validate({ task, knowledge, state, history, abortSignal })\n      return [readinessEval as TEval, ...evals]\n    },\n    decide: (ctx) => {\n      if (isKnowledgeBlocked(ctx.evals)) {\n        return options.adapter.onKnowledgeBlocked?.({ task, knowledge, questions, acquisitionPlans }) ?? {\n          type: 'stop',\n          pass: false,\n          score: knowledge.readinessScore,\n          reason: `knowledge readiness blocked: ${knowledge.reason}`,\n        }\n      }\n      return options.adapter.decide(toAgentContext(task, knowledge, ctx))\n    },\n    act: (action, ctx) => options.adapter.act(action, toAgentContext(task, knowledge, ctx)),\n    shouldStop: options.adapter.shouldStop\n      ? (ctx) => options.adapter.shouldStop!(toAgentContext(task, knowledge, ctx))\n      : undefined,\n    getActionCostUsd: options.adapter.getActionCostUsd\n      ? ({ action, result, state, evals, history }) => options.adapter.getActionCostUsd!({ action, result, task, state, evals, history })\n      : undefined,\n    onStep: (step) => emit(options.onEvent, { type: 'control_step', task, step }),\n  })\n  await emit(options.onEvent, { type: 'control_end', task, control })\n  const status = statusFromControl(control)\n  await emit(options.onEvent, { type: 'task_end', task, status, reason: control.reason })\n\n  return {\n    task,\n    status,\n    knowledge,\n    questions,\n    acquisitionPlans,\n    userAnswers: preflight.userAnswers,\n    acquiredEvidenceIds: preflight.acquiredEvidenceIds,\n    control,\n    runRecords: options.adapter.projectRunRecords?.(control, task) ?? [],\n  }\n}\n\nasync function runKnowledgePreflight<TState, TAction, TActionResult, TEval extends ControlEvalResult>(\n  task: AgentTaskSpec,\n  questions: UserQuestion[],\n  acquisitionPlans: DataAcquisitionPlan[],\n  provider: AgentKnowledgeProvider | undefined,\n  onEvent: AgentRuntimeEventSink<TState, TAction, TActionResult, TEval> | undefined,\n): Promise<{ userAnswers: Record<string, string>; acquiredEvidenceIds: string[] }> {\n  let userAnswers: Record<string, string> = {}\n  let acquiredEvidenceIds: string[] = []\n  if (questions.length > 0 && provider?.answerQuestions) {\n    await emit(onEvent, { type: 'questions_start', task, questions })\n    userAnswers = await provider.answerQuestions(questions, task)\n    await emit(onEvent, { type: 'questions_end', task, questions, userAnswers })\n  }\n  if (acquisitionPlans.length > 0 && provider?.executeAcquisitionPlans) {\n    await emit(onEvent, { type: 'acquisition_start', task, acquisitionPlans })\n    acquiredEvidenceIds = await provider.executeAcquisitionPlans(acquisitionPlans, task)\n    await emit(onEvent, { type: 'acquisition_end', task, acquisitionPlans, acquiredEvidenceIds })\n  }\n  return { userAnswers, acquiredEvidenceIds }\n}\n\nfunction buildReadiness(\n  task: AgentTaskSpec,\n  provider: AgentKnowledgeProvider | undefined,\n): Promise<KnowledgeReadinessReport> | KnowledgeReadinessReport {\n  if (provider?.buildReadiness) return provider.buildReadiness(task)\n  return scoreKnowledgeReadiness({\n    taskId: task.id,\n    requirements: task.requiredKnowledge ?? [],\n    metadata: { domain: task.domain, ...task.metadata },\n  })\n}\n\nfunction isKnowledgeBlocked(evals: ControlEvalResult[]): boolean {\n  return evals.some((evalResult) => evalResult.id === 'knowledge-ready' && !evalResult.passed)\n}\n\nfunction statusFromControl(control: ControlRunResult<unknown, unknown, unknown, ControlEvalResult>): AgentTaskStatus {\n  if (control.stoppedBy === 'abort') return 'aborted'\n  if (control.reason.includes('knowledge readiness blocked')) return 'blocked'\n  if (control.pass) return 'completed'\n  return 'failed'\n}\n\nasync function emit<TState, TAction, TActionResult, TEval extends ControlEvalResult>(\n  sink: AgentRuntimeEventSink<TState, TAction, TActionResult, TEval> | undefined,\n  event: AgentRuntimeEvent<TState, TAction, TActionResult, TEval>,\n): Promise<void> {\n  await sink?.(event)\n}\n\nfunction toAgentContext<TState, TAction, TActionResult, TEval extends ControlEvalResult>(\n  task: AgentTaskSpec,\n  knowledge: KnowledgeReadinessReport,\n  ctx: ControlContext<TState, TAction, TActionResult, TEval>,\n): AgentTaskContext<TState, TAction, TActionResult, TEval> {\n  return {\n    task,\n    knowledge,\n    state: ctx.state,\n    evals: ctx.evals,\n    history: ctx.history,\n    budget: ctx.budget,\n    stepIndex: ctx.stepIndex,\n    wallMs: ctx.wallMs,\n    spentCostUsd: ctx.spentCostUsd,\n    remainingCostUsd: ctx.remainingCostUsd,\n    abortSignal: ctx.abortSignal,\n  }\n}\n\nexport type {\n  ControlBudget,\n  ControlDecision,\n  ControlEvalResult,\n  ControlRunResult,\n  ControlStep,\n  DataAcquisitionPlan,\n  KnowledgeReadinessReport,\n  KnowledgeRequirement,\n  RunRecord,\n  UserQuestion,\n} from '@tangle-network/agent-eval'\n"],"mappings":"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","names":[]}

package/package.json

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