@meterbility/agent 0.3.1

package/LICENSE

@@ -0,0 +1,33 @@
+MIT License
+
+Copyright (c) 2026 Meterbility authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+----------------------------------------------------------------------
+
+Note: This MIT license covers everything in this repository EXCEPT the
+contents of the /ee directory (when present), which are licensed under the
+Elastic License 2.0 (ELv2) — see /ee/LICENSE.
+
+The /ee directory is reserved for Enterprise Edition modules: multi-tenant
+fleet orchestration, SSO/RBAC, audit logs, and long-retention features.
+
+Nothing under /ee today; the directory is created as a forward-compatible
+marker so the licensing boundary is visible before any /ee code lands.

package/README.md

@@ -0,0 +1,11 @@
+# @meterbility/agent
+
+Part of [Meterbility](https://github.com/HoneycombHairDevelopers/Meterbility) — the debugger for AI agents. Capture every run, inspect every decision, pause and inject live, fork from any step.
+
+TypeScript SDK for tracing custom agents: `MeterbilityTracer`, `traceAnthropic`, and Live Probe (pause / inject / resume).
+
+```bash
+npm install @meterbility/agent
+```
+
+See the [Meterbility documentation](https://github.com/HoneycombHairDevelopers/Meterbility#readme) for the full guide. MIT licensed.

package/dist/index.d.ts

@@ -0,0 +1,335 @@
+import { Store } from '@meterbility/collector';
+import { ContextComponent, Action, Outcome, TokenUsage, Step } from '@meterbility/shared';
+
+/**
+ * Public SDK types for custom TS agents. The shape is deliberately small
+ * and host-agnostic — anywhere you call a model and run tools, you can
+ * emit Steps. The collector handles the rest.
+ */
+interface TracerOptions {
+    /** Project — usually a path or stable identifier for the codebase. */
+    project: string;
+    /** Logical agent identity within the project. */
+    agent: string;
+    /** Free-form title for the run. Often the user's first message. */
+    runTitle?: string;
+    /** Free-form tags. */
+    tags?: string[];
+    /** Override METERBILITY_HOME for this tracer. */
+    meterHome?: string;
+    /** Override the source_runtime label. Defaults to "sdk-ts". */
+    sourceRuntime?: "sdk-ts" | "sdk-py" | "claude-code" | "codex-cli" | "cursor" | "fork";
+    /** Source session id (e.g. the host runtime's session uuid). */
+    sourceSessionId?: string;
+    /** Working directory associated with the run. */
+    cwd?: string;
+    /** Git branch associated with the run. */
+    gitBranch?: string;
+    /**
+     * Enable the Live Probe hook. When true, the SDK checks
+     * `$METERBILITY_HOME/probe/<run_id>.json` before each model call and:
+     *   - blocks until an operator-initiated pause is released
+     *   - prepends any queued inject message to the next user turn
+     *
+     * Defaults to false — zero overhead when the operator isn't using
+     * the probe. Turn this on when you want `meter probe` / the web
+     * probe panel to be able to graceful-pause this run.
+     */
+    probeEnabled?: boolean;
+    /**
+     * How often (ms) to poll the probe file while paused. Defaults to
+     * 250ms — fast enough to feel responsive in the operator UI, slow
+     * enough that idle pauses don't churn the filesystem.
+     */
+    probePollIntervalMs?: number;
+}
+interface StartStepOptions {
+    /** Model identity, e.g. "claude-opus-4-7". */
+    model: string;
+    /** Optional system prompt bytes — added to the context snapshot. */
+    systemPrompt?: string;
+    /** Optional tool definitions — added to the context snapshot. */
+    toolDefinitions?: unknown;
+    /** Optional retrieved docs — added to the context snapshot. */
+    retrievedDocs?: Array<{
+        source: string;
+        content: string;
+    }>;
+    /** Conversation history components (user/assistant/tool messages). */
+    history?: Array<{
+        role: "user" | "assistant" | "tool";
+        content: string;
+    }>;
+    /** Additional context components (advanced). */
+    extraComponents?: ContextComponent[];
+    /** Optional tags to apply to this step. */
+    tags?: string[];
+}
+interface RecordDecisionOptions {
+    /** Raw model output (typed unknown — caller passes whatever the SDK returned). */
+    decision: unknown;
+    /** Action representation. Use {@link helpers} or build manually. */
+    action: Action;
+}
+interface RecordOutcomeOptions {
+    outcome: Outcome;
+}
+interface RecordTokensOptions {
+    tokens: TokenUsage;
+    /** Wall-clock ms from start_step to end. Optional — tracer computes if omitted. */
+    latency_ms?: number;
+}
+/**
+ * Quick helpers for common Action shapes — keeps caller code tidy.
+ */
+declare const helpers: {
+    toolCall(name: string, input: unknown, id?: string): Action;
+    message(text: string): Action;
+    thinkingOnly(): Action;
+    subAgent(name: string): Action;
+};
+
+/**
+ * One Step builder, returned by tracer.startStep().
+ *
+ * The capture surface is imperative on purpose: most agent frameworks
+ * already have an event-loop-shaped flow ("call model, get reply, run
+ * tool, get result"), and forcing them into a different shape costs more
+ * than it earns.
+ *
+ * Internally a MeterbilityStep buffers up the context snapshot, decision,
+ * action, outcome, and tokens; persists once `end()` is called. That
+ * keeps async I/O off the agent's critical path until the step is over.
+ */
+interface StepInit {
+    tracer: MeterbilityTracer;
+    sequence: number;
+    parent_step_id?: string;
+    startedAtMs: number;
+    options: StartStepOptions;
+}
+declare class MeterbilityStep {
+    readonly step_id: string;
+    readonly sequence: number;
+    readonly parent_step_id?: string;
+    private tracer;
+    private model;
+    private startedAtMs;
+    private startedAtIso;
+    private context;
+    private decisionContent?;
+    private action;
+    private outcome;
+    private tokens;
+    private explicitLatency?;
+    private tags;
+    private ended;
+    private startOptions;
+    constructor(init: StepInit);
+    recordDecision(opts: RecordDecisionOptions): this;
+    recordAction(action: Action): this;
+    recordToolCall(name: string, input: unknown, id?: string): this;
+    recordMessage(text: string): this;
+    recordOutcome(opts: RecordOutcomeOptions): this;
+    recordToolResult(content: unknown, opts?: {
+        isError?: boolean;
+        summary?: string;
+    }): this;
+    recordTokens(opts: RecordTokensOptions): this;
+    tag(tag: string): this;
+    /**
+     * Persist the step. Idempotent on re-call. Returns the Step row.
+     */
+    end(): Promise<Step>;
+}
+
+/**
+ * SDK-side Probe hook — Track B / Turn 8 chunk 2.
+ *
+ * Runs before every model call when `tracer.probeEnabled` is true.
+ * Implements the graceful-pause + inject contract from SPEC §7.1:
+ *
+ *   1. If an operator has requested a pause, the SDK acknowledges
+ *      (confirmPaused) and blocks until the operator resumes. The
+ *      CURRENT model call (if any) is never interrupted — the check
+ *      happens at the TOP of the call wrapper, so any in-flight stream
+ *      completes naturally before we yield.
+ *
+ *   2. After the pause check (or if no pause was active), the SDK
+ *      consumes any pending inject message and appends it to the
+ *      request's `messages` array as a new user turn. This is how the
+ *      operator's "hey, the failing test is a stale fixture" nudge
+ *      reaches the model.
+ *
+ * When `probeEnabled` is false on the tracer, none of this runs and
+ * the cost is one boolean check per call.
+ *
+ * ## Testability seams
+ *
+ * - `sleep(ms)`: how long to wait between probe-state polls. Tests
+ *   inject a synchronous-ish stub that flips state on first call.
+ *   Production uses a real `setTimeout` wrapper.
+ * - `now()`: clock for timestamping pause acknowledgements. Tests pass
+ *   a counter; production uses `Date.now`.
+ *
+ * The hook is intentionally pure-functional on its arguments — it
+ * never reaches into the tracer instance for state, only for config.
+ */
+interface ProbeRuntime {
+    /** How long to wait between probe-state polls while paused. */
+    pollIntervalMs: number;
+    /** Sleep implementation (injectable for tests). */
+    sleep: (ms: number) => Promise<void>;
+    /** Clock (injectable for tests). */
+    now: () => number;
+}
+declare const DEFAULT_PROBE_RUNTIME: ProbeRuntime;
+/**
+ * The shape `applyProbeToRequest` needs from any "request with a
+ * messages array." Kept structural so it works for the Anthropic
+ * request shape AND any future provider request shape — we never
+ * import a specific SDK's types into this hook.
+ */
+interface ProbeMutableRequest {
+    messages: Array<{
+        role: "user" | "assistant";
+        content: string | Array<unknown>;
+    }>;
+}
+/**
+ * Run the probe protocol against this call.
+ *
+ * 1. Read current probe state.
+ * 2. If `pause_requested`, confirm and poll until `running`.
+ * 3. After unblocking, consume any pending inject and append it to
+ *    `req.messages` as a user turn.
+ *
+ * Returns the (possibly modified) request. Caller passes the result on
+ * to the underlying SDK call.
+ */
+declare function applyProbeToRequest<R extends ProbeMutableRequest>(runId: string, req: R, runtime?: ProbeRuntime): Promise<R>;
+
+/**
+ * Public SDK entry point.
+ *
+ * Lifecycle:
+ *
+ *   const tracer = new MeterbilityTracer({ project: "my-app", agent: "support" });
+ *   const step = tracer.startStep({ model: "claude-opus-4-7", history });
+ *   // ...call model, record outcome, record tokens...
+ *   await step.end();
+ *
+ * One tracer instance = one Run. Create a new tracer per agent invocation.
+ * The tracer is intentionally synchronous to create — capture should never
+ * block the agent's hot path — and persists asynchronously via promises
+ * returned from step.end().
+ */
+declare class MeterbilityTracer {
+    readonly run_id: string;
+    readonly project_id: string;
+    readonly agent_id: string;
+    readonly store: Store;
+    /**
+     * Whether `traceAnthropic` (or any other model-call wrapper) should
+     * run the Live Probe hook before each model call. Mirrors
+     * `TracerOptions.probeEnabled`; kept readonly so call sites can
+     * branch on `tracer.probeEnabled` without a getter.
+     */
+    readonly probeEnabled: boolean;
+    /**
+     * Runtime used by the probe hook — poll interval + injectable
+     * sleep/now seams for tests. Defaults to {@link DEFAULT_PROBE_RUNTIME}.
+     * Tests construct a custom one and assign it post-construction.
+     */
+    probeRuntime: ProbeRuntime;
+    private stepCount;
+    private prevStepId?;
+    private ended;
+    private startedAt;
+    private status;
+    constructor(opts: TracerOptions);
+    /**
+     * Begin one Step. Returns a {@link MeterbilityStep} the caller fills in
+     * imperatively: recordDecision, recordOutcome, recordTokens, end.
+     */
+    startStep(opts: StartStepOptions): MeterbilityStep;
+    /**
+     * Mark the run finished. Status is inferred from the last step's
+     * outcome unless overridden. Caller must invoke before exiting so the
+     * run row gets sealed and totals recomputed.
+     */
+    end(overrides?: {
+        status?: "ok" | "error" | "abandoned";
+    }): Promise<void>;
+    /** Internal: notify tracer of a terminal status from a step. */
+    _stepCompleted(stepStatus: "ok" | "error" | "in_progress" | "abandoned"): void;
+    /** Internal: bump totals after a step inserts. */
+    _refreshTotals(): void;
+}
+
+/**
+ * Convenience wrapper for the common "I'm calling the Anthropic SDK"
+ * case. Captures one Step per messages.create() invocation, mapping the
+ * SDK's request/response into Meterbility's data model.
+ *
+ * Usage:
+ *
+ *   import Anthropic from "@anthropic-ai/sdk";
+ *   const client = new Anthropic();
+ *   const tracer = new MeterbilityTracer({ project, agent });
+ *   const traced = traceAnthropic(tracer, (req) => client.messages.create(req));
+ *
+ *   const resp = await traced({
+ *     model: "claude-opus-4-7",
+ *     max_tokens: 1024,
+ *     system: "you are helpful",
+ *     messages: [{ role: "user", content: "hello" }],
+ *   });
+ *
+ * Returns the SDK response untouched. One captured Step per call.
+ */
+declare function traceAnthropic<Req extends AnthropicMessagesRequest, Resp extends AnthropicMessagesResponse>(tracer: MeterbilityTracer, call: (req: Req) => Promise<Resp>): (req: Req) => Promise<Resp>;
+interface AnthropicMessagesRequest {
+    model: string;
+    max_tokens: number;
+    system?: string | Array<{
+        type: string;
+        text: string;
+    }>;
+    messages: Array<{
+        role: "user" | "assistant";
+        content: string | Array<{
+            type: string;
+            text?: string;
+        } | Record<string, unknown>>;
+    }>;
+    tools?: unknown;
+}
+interface AnthropicMessagesResponse {
+    model: string;
+    usage?: {
+        input_tokens?: number;
+        output_tokens?: number;
+        cache_read_input_tokens?: number;
+        cache_creation_input_tokens?: number;
+        cache_creation?: {
+            ephemeral_5m_input_tokens?: number;
+            ephemeral_1h_input_tokens?: number;
+        };
+    };
+    content?: Array<AnthropicTextBlock | AnthropicToolUseBlock | {
+        type: string;
+    }>;
+}
+interface AnthropicTextBlock {
+    type: "text";
+    text: string;
+}
+interface AnthropicToolUseBlock {
+    type: "tool_use";
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+}
+
+export { DEFAULT_PROBE_RUNTIME, MeterbilityStep, MeterbilityTracer, type ProbeMutableRequest, type ProbeRuntime, type RecordDecisionOptions, type RecordOutcomeOptions, type RecordTokensOptions, type StartStepOptions, type StepInit, type TracerOptions, applyProbeToRequest, helpers, traceAnthropic };

package/dist/index.js

@@ -0,0 +1,415 @@
+// src/tracer.ts
+import { randomUUID as randomUUID2 } from "crypto";
+import { Store } from "@meterbility/collector";
+import {
+  insertRun,
+  setRunStatus,
+  updateRunTotals,
+  upsertAgent,
+  upsertProjectByCwd
+} from "@meterbility/collector";
+import { clearProbe } from "@meterbility/shared";
+
+// src/step.ts
+import { randomUUID } from "crypto";
+import { hashJson } from "@meterbility/shared";
+import { costCents } from "@meterbility/spec";
+import { insertStep, recordContextSnapshot } from "@meterbility/collector";
+var MeterbilityStep = class {
+  step_id = `stp_${randomUUID()}`;
+  sequence;
+  parent_step_id;
+  tracer;
+  model;
+  startedAtMs;
+  startedAtIso = (/* @__PURE__ */ new Date()).toISOString();
+  context;
+  decisionContent;
+  action = { kind: "none" };
+  outcome = { status: "pending" };
+  tokens = {
+    input: 0,
+    output: 0,
+    cached_read: 0,
+    cache_creation: 0
+  };
+  explicitLatency;
+  tags = [];
+  ended = false;
+  startOptions;
+  constructor(init) {
+    this.tracer = init.tracer;
+    this.sequence = init.sequence;
+    this.parent_step_id = init.parent_step_id;
+    this.startedAtMs = init.startedAtMs;
+    this.model = init.options.model;
+    this.startOptions = init.options;
+    this.context = [];
+    if (init.options.tags) this.tags.push(...init.options.tags);
+  }
+  recordDecision(opts) {
+    this.decisionContent = opts.decision;
+    this.action = opts.action;
+    return this;
+  }
+  recordAction(action) {
+    this.action = action;
+    return this;
+  }
+  recordToolCall(name, input, id) {
+    this.action = {
+      kind: "tool_call",
+      tool_name: name,
+      tool_use_id: id,
+      tool_input: input
+    };
+    return this;
+  }
+  recordMessage(text) {
+    this.action = { kind: "message", text };
+    return this;
+  }
+  recordOutcome(opts) {
+    this.outcome = opts.outcome;
+    return this;
+  }
+  recordToolResult(content, opts) {
+    this.outcome = {
+      status: opts?.isError ? "error" : "ok",
+      is_error: opts?.isError === true,
+      summary: opts?.summary
+    };
+    this._pendingToolResult = content;
+    return this;
+  }
+  recordTokens(opts) {
+    this.tokens = opts.tokens;
+    if (opts.latency_ms !== void 0) this.explicitLatency = opts.latency_ms;
+    return this;
+  }
+  tag(tag) {
+    if (!this.tags.includes(tag)) this.tags.push(tag);
+    return this;
+  }
+  /**
+   * Persist the step. Idempotent on re-call. Returns the Step row.
+   */
+  async end() {
+    if (this.ended) {
+      throw new Error("MeterbilityStep.end() called twice");
+    }
+    this.ended = true;
+    this.context = await buildContextComponents(
+      this.tracer.store,
+      this.startOptions
+    );
+    const snapshot = {
+      id: hashJson(this.context),
+      components: this.context
+    };
+    const snapBlobRef = await this.tracer.store.blobs.putJson(snapshot);
+    recordContextSnapshot(
+      this.tracer.store,
+      snapshot.id,
+      snapBlobRef,
+      snapshot.components.length
+    );
+    const decisionRef = await this.tracer.store.blobs.putJson(
+      this.decisionContent ?? null
+    );
+    const pending = this._pendingToolResult;
+    if (pending !== void 0) {
+      const ref = await this.tracer.store.blobs.putJson(pending);
+      this.outcome = { ...this.outcome, tool_result_ref: ref };
+    }
+    const latency_ms = this.explicitLatency !== void 0 ? this.explicitLatency : Date.now() - this.startedAtMs;
+    const { cost_cents, approx } = costCents(this.model, {
+      input: this.tokens.input,
+      output: this.tokens.output,
+      cached_read: this.tokens.cached_read,
+      cache_creation: this.tokens.cache_creation,
+      cache_creation_1h: this.tokens.cache_creation_1h
+    });
+    if (approx && !this.tags.includes("cost:approx")) {
+      this.tags.push("cost:approx");
+    }
+    const status = this.outcome.status === "error" ? "error" : this.outcome.status === "pending" ? "in_progress" : "ok";
+    const step = {
+      step_id: this.step_id,
+      run_id: this.tracer.run_id,
+      parent_step_id: this.parent_step_id,
+      sequence: this.sequence,
+      timestamp: this.startedAtIso,
+      model: this.model,
+      context_snapshot_id: snapshot.id,
+      decision_ref: decisionRef,
+      action: this.action,
+      outcome: this.outcome,
+      tokens: this.tokens,
+      latency_ms,
+      cost_cents,
+      tags: this.tags,
+      status
+    };
+    insertStep(this.tracer.store, step);
+    this.tracer._stepCompleted(status);
+    this.tracer._refreshTotals();
+    return step;
+  }
+};
+async function buildContextComponents(store, opts) {
+  const components = [];
+  if (opts.systemPrompt !== void 0) {
+    const content_ref = await store.blobs.putString(opts.systemPrompt);
+    components.push({ type: "system_prompt", content_ref });
+  }
+  if (opts.toolDefinitions !== void 0) {
+    const content_ref = await store.blobs.putJson(opts.toolDefinitions);
+    components.push({ type: "tool_definitions", content_ref });
+  }
+  if (opts.history && opts.history.length > 0) {
+    const messages = [];
+    for (const m of opts.history) {
+      messages.push({
+        role: m.role,
+        content_ref: await store.blobs.putString(m.content)
+      });
+    }
+    components.push({ type: "conversation_history", messages });
+  }
+  if (opts.retrievedDocs && opts.retrievedDocs.length > 0) {
+    const docs = [];
+    for (const d of opts.retrievedDocs) {
+      docs.push({
+        source: d.source,
+        content_ref: await store.blobs.putString(d.content)
+      });
+    }
+    components.push({ type: "retrieved_documents", docs });
+  }
+  if (opts.extraComponents) components.push(...opts.extraComponents);
+  return components;
+}
+
+// src/probe.ts
+import {
+  confirmPaused,
+  consumeInject,
+  readState
+} from "@meterbility/shared";
+var DEFAULT_PROBE_RUNTIME = {
+  pollIntervalMs: 250,
+  sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+  now: () => Date.now()
+};
+async function applyProbeToRequest(runId, req, runtime = DEFAULT_PROBE_RUNTIME) {
+  let state = readState(runId, runtime.now);
+  if (state.state === "pause_requested") {
+    state = confirmPaused(runId, runtime.now);
+    while (state.state !== "running") {
+      await runtime.sleep(runtime.pollIntervalMs);
+      state = readState(runId, runtime.now);
+    }
+  }
+  const injected = consumeInject(runId, runtime.now);
+  if (injected !== null) {
+    return {
+      ...req,
+      messages: [...req.messages, { role: "user", content: injected }]
+    };
+  }
+  return req;
+}
+
+// src/tracer.ts
+var MeterbilityTracer = class {
+  run_id;
+  project_id;
+  agent_id;
+  store;
+  /**
+   * Whether `traceAnthropic` (or any other model-call wrapper) should
+   * run the Live Probe hook before each model call. Mirrors
+   * `TracerOptions.probeEnabled`; kept readonly so call sites can
+   * branch on `tracer.probeEnabled` without a getter.
+   */
+  probeEnabled;
+  /**
+   * Runtime used by the probe hook — poll interval + injectable
+   * sleep/now seams for tests. Defaults to {@link DEFAULT_PROBE_RUNTIME}.
+   * Tests construct a custom one and assign it post-construction.
+   */
+  probeRuntime;
+  stepCount = 0;
+  prevStepId;
+  ended = false;
+  startedAt = (/* @__PURE__ */ new Date()).toISOString();
+  status = "in_progress";
+  constructor(opts) {
+    if (opts.meterHome) process.env.METERBILITY_HOME = opts.meterHome;
+    this.store = Store.open();
+    const project = upsertProjectByCwd(
+      this.store,
+      opts.cwd ?? opts.project,
+      opts.project
+    );
+    this.project_id = project.project_id;
+    const agent = upsertAgent(this.store, project.project_id, opts.agent);
+    this.agent_id = agent.agent_id;
+    this.run_id = `run_${randomUUID2()}`;
+    const run = {
+      run_id: this.run_id,
+      agent_id: this.agent_id,
+      project_id: this.project_id,
+      source_session_id: opts.sourceSessionId,
+      source_runtime: opts.sourceRuntime ?? "sdk-ts",
+      title: opts.runTitle,
+      status: "in_progress",
+      started_at: this.startedAt,
+      git_branch: opts.gitBranch,
+      cwd: opts.cwd ?? opts.project,
+      tokens_total_input: 0,
+      tokens_total_output: 0,
+      tokens_total_cached: 0,
+      cost_cents: 0,
+      step_count: 0,
+      tags: opts.tags ?? []
+    };
+    insertRun(this.store, run);
+    this.probeEnabled = opts.probeEnabled ?? false;
+    this.probeRuntime = {
+      ...DEFAULT_PROBE_RUNTIME,
+      pollIntervalMs: opts.probePollIntervalMs ?? DEFAULT_PROBE_RUNTIME.pollIntervalMs
+    };
+  }
+  /**
+   * Begin one Step. Returns a {@link MeterbilityStep} the caller fills in
+   * imperatively: recordDecision, recordOutcome, recordTokens, end.
+   */
+  startStep(opts) {
+    const sequence = this.stepCount;
+    const step = new MeterbilityStep({
+      tracer: this,
+      sequence,
+      parent_step_id: this.prevStepId,
+      startedAtMs: Date.now(),
+      options: opts
+    });
+    this.stepCount += 1;
+    this.prevStepId = step.step_id;
+    return step;
+  }
+  /**
+   * Mark the run finished. Status is inferred from the last step's
+   * outcome unless overridden. Caller must invoke before exiting so the
+   * run row gets sealed and totals recomputed.
+   */
+  async end(overrides) {
+    if (this.ended) return;
+    this.ended = true;
+    const status = overrides?.status ?? this.status;
+    setRunStatus(this.store, this.run_id, status, (/* @__PURE__ */ new Date()).toISOString());
+    updateRunTotals(this.store, this.run_id);
+    clearProbe(this.run_id);
+    this.store.close();
+  }
+  /** Internal: notify tracer of a terminal status from a step. */
+  _stepCompleted(stepStatus) {
+    if (stepStatus === "error") this.status = "error";
+    else if (stepStatus === "ok" && this.status !== "error")
+      this.status = "ok";
+  }
+  /** Internal: bump totals after a step inserts. */
+  _refreshTotals() {
+    updateRunTotals(this.store, this.run_id);
+  }
+};
+
+// src/anthropic.ts
+function traceAnthropic(tracer, call) {
+  return async (reqIn) => {
+    const req = tracer.probeEnabled ? await applyProbeToRequest(tracer.run_id, reqIn, tracer.probeRuntime) : reqIn;
+    const history = [];
+    for (const m of req.messages ?? []) {
+      const text2 = typeof m.content === "string" ? m.content : (m.content ?? []).filter(
+        (b) => b.type === "text"
+      ).map((b) => b.text).join("\n");
+      history.push({
+        role: m.role === "assistant" ? "assistant" : "user",
+        content: text2
+      });
+    }
+    const step = tracer.startStep({
+      model: req.model,
+      systemPrompt: typeof req.system === "string" ? req.system : void 0,
+      toolDefinitions: req.tools,
+      history
+    });
+    const t0 = Date.now();
+    let resp;
+    try {
+      resp = await call(req);
+    } catch (err) {
+      step.recordAction({ kind: "none" }).recordOutcome({
+        outcome: {
+          status: "error",
+          is_error: true,
+          summary: err.message?.slice(0, 200)
+        }
+      });
+      await step.end();
+      throw err;
+    }
+    const t1 = Date.now();
+    const blocks = resp.content ?? [];
+    const toolUse = blocks.find(
+      (b) => b.type === "tool_use"
+    );
+    const text = blocks.filter((b) => b.type === "text").map((b) => b.text).join("\n");
+    const action = toolUse ? {
+      kind: "tool_call",
+      tool_name: toolUse.name,
+      tool_use_id: toolUse.id,
+      tool_input: toolUse.input
+    } : text ? { kind: "message", text } : { kind: "thinking_only" };
+    const cc = resp.usage?.cache_creation;
+    const tokens5m = cc ? cc.ephemeral_5m_input_tokens ?? 0 : resp.usage?.cache_creation_input_tokens ?? 0;
+    const tokens1h = cc?.ephemeral_1h_input_tokens ?? 0;
+    step.recordDecision({ decision: resp.content, action }).recordTokens({
+      tokens: {
+        input: resp.usage?.input_tokens ?? 0,
+        output: resp.usage?.output_tokens ?? 0,
+        cached_read: resp.usage?.cache_read_input_tokens ?? 0,
+        cache_creation: tokens5m,
+        cache_creation_1h: tokens1h
+      },
+      latency_ms: t1 - t0
+    }).recordOutcome({ outcome: { status: "ok" } });
+    await step.end();
+    return resp;
+  };
+}
+
+// src/types.ts
+var helpers = {
+  toolCall(name, input, id) {
+    return { kind: "tool_call", tool_name: name, tool_use_id: id, tool_input: input };
+  },
+  message(text) {
+    return { kind: "message", text };
+  },
+  thinkingOnly() {
+    return { kind: "thinking_only" };
+  },
+  subAgent(name) {
+    return { kind: "sub_agent_dispatch", sub_agent: name };
+  }
+};
+export {
+  DEFAULT_PROBE_RUNTIME,
+  MeterbilityStep,
+  MeterbilityTracer,
+  applyProbeToRequest,
+  helpers,
+  traceAnthropic
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@meterbility/agent",
+  "version": "0.3.1",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@meterbility/shared": "^0.3.0",
+    "@meterbility/spec": "^0.3.0",
+    "@meterbility/collector": "^0.3.0"
+  },
+  "description": "TypeScript SDK for tracing custom agents with Meterbility, including Live Probe",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HoneycombHairDevelopers/Meterbility.git",
+    "directory": "packages/agent"
+  },
+  "homepage": "https://github.com/HoneycombHairDevelopers/Meterbility#readme",
+  "bugs": {
+    "url": "https://github.com/HoneycombHairDevelopers/Meterbility/issues"
+  },
+  "engines": {
+    "node": ">=20.6"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "types": "dist/index.d.ts",
+  "tsup": {
+    "entry": [
+      "src/index.ts"
+    ],
+    "format": [
+      "esm"
+    ],
+    "dts": true,
+    "clean": true
+  },
+  "scripts": {
+    "build": "tsup"
+  }
+}