@inbrowser/agent 0.1.0 → 0.2.0

package/dist/types/trace.d.ts

@@ -16,9 +16,11 @@
  * one — incur zero cost.
  *
  * Phase 1 captures `llm_request` only (the priority the playground
- * needs to ship a prompt visualizer). `llm_response` shape is
- * defined here so consumers can write against the full union from
- * day one; emit-site wiring lands in Phase 2.
+ * needs to ship a prompt visualizer). `llm_response` and
+ * `turn_dispatch_complete` complete the per-iteration wall-clock
+ * triple — request-dispatched, response-completed, tool-dispatch-
+ * completed — that the eval harness uses to split language-model
+ * time from tool-dispatch time.
  */
 import type { NormalizedMessage } from './chat.js';
 /**
@@ -36,7 +38,12 @@ export interface LlmRequestTrace {
     turnId: string;
     /** 0-indexed ReAct iteration within this turn. */
     iteration: number;
-    /** Wall-clock ms at the moment the request was about to dispatch. */
+    /** Wall-clock ms captured immediately before the strategy hands
+     *  the request to `LlmClient.chat()`. Pair with
+     *  `LlmResponseTrace.ts` (response completed) and
+     *  `TurnDispatchCompleteTrace.ts` (tool dispatch completed) to
+     *  derive the language-model vs tool-dispatch wall-clock split for
+     *  this iteration. */
     ts: number;
     /** The system-prompt string the strategy received from
      *  `StrategyRunInput.systemPrompt`. Captured verbatim. */
@@ -72,15 +79,21 @@ export interface ToolDeclarationView {
     parameters: unknown;
 }
 /**
- * Response-side snapshot. Defined now so consumers can switch on
- * `TraceEvent.kind` and handle the full union from the start. The
- * emit-site in `strategy.ts` lands in Phase 2 — strategies are free
- * to emit it earlier when the data is available.
+ * Response-side snapshot. Emitted once per ReAct iteration, paired
+ * one-to-one with `LlmRequestTrace` via `requestId`. Captures the
+ * full assistant output and the timestamp at which the chat()
+ * iterator drained — `ts - LlmRequestTrace.ts` is the iteration's
+ * language-model wall-clock segment.
  */
 export interface LlmResponseTrace {
     /** Same id as the matching `LlmRequestTrace.requestId`. */
     requestId: string;
-    /** Wall-clock ms when the chat() iterator completed. */
+    /** Wall-clock ms captured immediately after the `chat()` iterator
+     *  has yielded its terminal event for this iteration (typically
+     *  `turn_complete`, or `error` on a streaming failure). Not
+     *  emitted on mid-stream error — callers should treat a missing
+     *  `llm_response` as "language-model time unknown for this
+     *  iteration." */
     ts: number;
     /** Full assistant text emitted this iteration. */
     text: string;
@@ -102,12 +115,49 @@ export interface LlmResponseTrace {
         cachedTokens?: number;
     };
 }
+/**
+ * End-of-iteration tool-dispatch marker. Emitted once per ReAct
+ * iteration that actually ran tool calls, immediately after the
+ * per-turn dispatch loop drained. Paired one-to-one with
+ * `LlmResponseTrace` via `requestId`. NOT emitted for the final
+ * assistant turn (no tool calls → no dispatch segment to close).
+ *
+ * `ts - LlmResponseTrace.ts` is the iteration's tool-dispatch
+ * wall-clock segment; `ts - LlmRequestTrace.ts` is the iteration's
+ * total wall-clock from request dispatch through tool-result append.
+ *
+ * Only the aggregate is captured. Per-tool wall-clock can be added
+ * later — the existing `tool_call`/`tool_result` events on the
+ * strategy event stream are the right place for that, not the
+ * trace.
+ */
+export interface TurnDispatchCompleteTrace {
+    /** Same id as the matching `LlmRequestTrace.requestId`. */
+    requestId: string;
+    /** Mirror of `LlmRequestTrace.turnId`, carried for grouping
+     *  consumers that key by turn rather than by iteration. */
+    turnId: string;
+    /** 0-indexed ReAct iteration within the turn. Mirrors
+     *  `LlmRequestTrace.iteration`. */
+    iteration: number;
+    /** Wall-clock ms captured immediately after the last tool result
+     *  for this iteration was appended to the messages array, before
+     *  the loop steps to the next iteration. */
+    ts: number;
+    /** Number of tool calls executed in this iteration. Always >= 1
+     *  in practice (an iteration with zero tool calls does not emit
+     *  this event). */
+    toolCallCount: number;
+}
 export type TraceEvent = {
     kind: 'llm_request';
     data: LlmRequestTrace;
 } | {
     kind: 'llm_response';
     data: LlmResponseTrace;
+} | {
+    kind: 'turn_dispatch_complete';
+    data: TurnDispatchCompleteTrace;
 };
 /**
  * Pluggable trace sink. Hosts implement `emit()` to push events to a

package/dist/types/trace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"trace.d.ts","sourceRoot":"","sources":["../../src/types/trace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B;;+CAE2C;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,MAAM,EAAE,MAAM,CAAC;IACf,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,EAAE,EAAE,MAAM,CAAC;IACX;8DAC0D;IAC1D,YAAY,EAAE,MAAM,CAAC;IACrB;;;mCAG+B;IAC/B,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B;;;iDAG6C;IAC7C,KAAK,EAAE,mBAAmB,EAAE,CAAC;IAC7B;;;oBAGgB;IAChB,GAAG,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,OAAO,CAAA;KAAE,CAAC;CAC7C;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,2DAA2D;IAC3D,SAAS,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,EAAE,EAAE,MAAM,CAAC;IACX,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;IACb;gCAC4B;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,SAAS,EAAE;QACT,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,OAAO,CAAC;QACd,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,EAAE,CAAC;IACJ;kDAC8C;IAC9C,KAAK,CAAC,EAAE;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC/E;AAED,MAAM,MAAM,UAAU,GAClB;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,IAAI,EAAE,eAAe,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,IAAI,EAAE,gBAAgB,CAAA;CAAE,CAAC;AAErD;;;;;;;;;GASG;AACH,MAAM,WAAW,MAAM;IACrB,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;CAC/B"}
+{"version":3,"file":"trace.d.ts","sourceRoot":"","sources":["../../src/types/trace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B;;+CAE2C;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,MAAM,EAAE,MAAM,CAAC;IACf,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;0BAKsB;IACtB,EAAE,EAAE,MAAM,CAAC;IACX;8DAC0D;IAC1D,YAAY,EAAE,MAAM,CAAC;IACrB;;;mCAG+B;IAC/B,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B;;;iDAG6C;IAC7C,KAAK,EAAE,mBAAmB,EAAE,CAAC;IAC7B;;;oBAGgB;IAChB,GAAG,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,OAAO,CAAA;KAAE,CAAC;CAC7C;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,2DAA2D;IAC3D,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;sBAKkB;IAClB,EAAE,EAAE,MAAM,CAAC;IACX,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;IACb;gCAC4B;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,SAAS,EAAE;QACT,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,OAAO,CAAC;QACd,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,EAAE,CAAC;IACJ;kDAC8C;IAC9C,KAAK,CAAC,EAAE;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC/E;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,yBAAyB;IACxC,2DAA2D;IAC3D,SAAS,EAAE,MAAM,CAAC;IAClB;+DAC2D;IAC3D,MAAM,EAAE,MAAM,CAAC;IACf;uCACmC;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB;;gDAE4C;IAC5C,EAAE,EAAE,MAAM,CAAC;IACX;;uBAEmB;IACnB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,UAAU,GAClB;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,IAAI,EAAE,eAAe,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,IAAI,EAAE,gBAAgB,CAAA;CAAE,GAChD;IAAE,IAAI,EAAE,wBAAwB,CAAC;IAAC,IAAI,EAAE,yBAAyB,CAAA;CAAE,CAAC;AAExE;;;;;;;;;GASG;AACH,MAAM,WAAW,MAAM;IACrB,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;CAC/B"}

package/dist/types/trace.js

@@ -16,9 +16,11 @@
  * one — incur zero cost.
  *
  * Phase 1 captures `llm_request` only (the priority the playground
- * needs to ship a prompt visualizer). `llm_response` shape is
- * defined here so consumers can write against the full union from
- * day one; emit-site wiring lands in Phase 2.
+ * needs to ship a prompt visualizer). `llm_response` and
+ * `turn_dispatch_complete` complete the per-iteration wall-clock
+ * triple — request-dispatched, response-completed, tool-dispatch-
+ * completed — that the eval harness uses to split language-model
+ * time from tool-dispatch time.
  */
 export {};
 //# sourceMappingURL=trace.js.map

package/dist/types/trace.js.map

@@ -1 +1 @@
-{"version":3,"file":"trace.js","sourceRoot":"","sources":["../../src/types/trace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG"}
+{"version":3,"file":"trace.js","sourceRoot":"","sources":["../../src/types/trace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inbrowser/agent",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Agent runtime + CLI. Library exports AgentSession, AgentStrategy, ToolRegistry, LlmClient, MetricsCollector, SandboxObserver. Ships an `agent` binary with NDJSON output, --json stdin, --dry-run, schema introspection, and inverse-mode MCP serve. Domain-agnostic — hosts wire their own AgentDefinitions.",
   "type": "module",
   "main": "./dist/index.js",