agent-inspect 0.1.0

package/packages/core/dist/index.mjs

@@ -0,0 +1,919 @@
+import { mkdir, writeFile, readFile, readdir, stat, appendFile } from 'fs/promises';
+import os from 'os';
+import path from 'path';
+import { nanoid } from 'nanoid';
+import { AsyncLocalStorage } from 'async_hooks';
+import chalk from 'chalk';
+
+// packages/core/src/types.ts
+var STEP_TYPES = [
+  "run",
+  "llm",
+  "tool",
+  "decision",
+  "logic",
+  "state",
+  "custom"
+];
+var STEP_STATUSES = [
+  "running",
+  "success",
+  "error"
+];
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isStepType(value) {
+  return typeof value === "string" && STEP_TYPES.includes(value);
+}
+function isStepStatus(value) {
+  return typeof value === "string" && STEP_STATUSES.includes(value);
+}
+function isTraceEvent(value) {
+  if (!isRecord(value)) return false;
+  if (value.schemaVersion !== "0.1") return false;
+  if (typeof value.timestamp !== "number") return false;
+  if (typeof value.event !== "string") return false;
+  switch (value.event) {
+    case "run_started": {
+      return typeof value.runId === "string" && typeof value.name === "string" && typeof value.startTime === "number";
+    }
+    case "run_completed": {
+      return typeof value.runId === "string" && (value.status === "success" || value.status === "error") && typeof value.endTime === "number" && typeof value.durationMs === "number";
+    }
+    case "step_started": {
+      return typeof value.runId === "string" && typeof value.stepId === "string" && typeof value.name === "string" && isStepType(value.type) && typeof value.startTime === "number";
+    }
+    case "step_completed": {
+      return typeof value.runId === "string" && typeof value.stepId === "string" && (value.status === "success" || value.status === "error") && typeof value.endTime === "number" && typeof value.durationMs === "number";
+    }
+    default:
+      return false;
+  }
+}
+var DEFAULT_TRACE_DIR_NAME = ".agent-inspect";
+var RUNS_DIR_NAME = "runs";
+var FALLBACK_TRACE_DIR = path.join(
+  os.tmpdir(),
+  "agent-inspect",
+  RUNS_DIR_NAME
+);
+var MAX_NAME_LENGTH = 100;
+function createRunId() {
+  return `run_${nanoid(10)}`;
+}
+function createStepId() {
+  return `step_${nanoid(10)}`;
+}
+function formatDuration(ms) {
+  if (!Number.isFinite(ms) || ms < 0) {
+    return "0ms";
+  }
+  if (ms < 1e3) {
+    return `${Math.floor(ms)}ms`;
+  }
+  const seconds = ms / 1e3;
+  return `${(Math.round(seconds * 10) / 10).toFixed(1)}s`;
+}
+function formatTimestamp(timestamp) {
+  if (!Number.isFinite(timestamp)) {
+    return "Invalid date";
+  }
+  const d = new Date(timestamp);
+  if (Number.isNaN(d.getTime())) {
+    return "Invalid date";
+  }
+  const y = d.getFullYear();
+  const mo = String(d.getMonth() + 1).padStart(2, "0");
+  const day = String(d.getDate()).padStart(2, "0");
+  const h = String(d.getHours()).padStart(2, "0");
+  const min = String(d.getMinutes()).padStart(2, "0");
+  const s = String(d.getSeconds()).padStart(2, "0");
+  return `${y}-${mo}-${day} ${h}:${min}:${s}`;
+}
+function getDefaultTraceDir() {
+  try {
+    const home = os.homedir();
+    if (typeof home !== "string" || home.trim() === "") {
+      return FALLBACK_TRACE_DIR;
+    }
+    return path.join(home, DEFAULT_TRACE_DIR_NAME, RUNS_DIR_NAME);
+  } catch {
+    return FALLBACK_TRACE_DIR;
+  }
+}
+function getTraceFilePath(runId, traceDir) {
+  const baseDir = traceDir ?? getDefaultTraceDir();
+  let safeId = typeof runId === "string" && runId.trim() !== "" ? runId.trim() : "run_unknown";
+  safeId = path.basename(safeId);
+  if (safeId === "" || safeId === "." || safeId === "..") {
+    safeId = "run_unknown";
+  }
+  return path.join(baseDir, `${safeId}.jsonl`);
+}
+async function ensureTraceDir(traceDir) {
+  const primary = path.resolve(traceDir);
+  try {
+    await mkdir(primary, { recursive: true });
+    return primary;
+  } catch {
+    warn(`Failed to create trace directory: ${primary}`);
+    const fallback = path.resolve(FALLBACK_TRACE_DIR);
+    try {
+      await mkdir(fallback, { recursive: true });
+      return fallback;
+    } catch {
+      warn(`Failed to create fallback trace directory: ${fallback}`);
+      return primary;
+    }
+  }
+}
+function formatError(error) {
+  if (error instanceof Error) {
+    const out = { message: error.message };
+    if (typeof error.stack === "string" && error.stack.length > 0) {
+      out.stack = error.stack;
+    }
+    return out;
+  }
+  if (typeof error === "string") {
+    return { message: error };
+  }
+  if (error === null) {
+    return { message: "Unknown error: null" };
+  }
+  if (error === void 0) {
+    return { message: "Unknown error: undefined" };
+  }
+  if (typeof error === "number" || typeof error === "boolean" || typeof error === "bigint") {
+    return { message: String(error) };
+  }
+  if (typeof error === "object") {
+    try {
+      return { message: JSON.stringify(error) };
+    } catch {
+      return { message: "Unknown error" };
+    }
+  }
+  return { message: "Unknown error" };
+}
+function truncateName(name, maxLength = MAX_NAME_LENGTH) {
+  if (typeof name !== "string" || name.trim() === "") {
+    return "unnamed";
+  }
+  const trimmed = name.trim();
+  if (trimmed.length <= maxLength) {
+    return trimmed;
+  }
+  const ellipsis = "...";
+  const head = Math.max(0, maxLength - ellipsis.length);
+  return `${trimmed.slice(0, head)}${ellipsis}`;
+}
+function warn(message, error) {
+  const base = `[AgentInspect] ${message}`;
+  if (error === void 0) {
+    console.warn(base);
+    return;
+  }
+  console.warn(`${base}: ${formatError(error).message}`);
+}
+var storage = new AsyncLocalStorage();
+function toPublicContext(ctx) {
+  return {
+    runId: ctx.runId,
+    runName: ctx.runName,
+    traceDir: ctx.traceDir,
+    silent: ctx.silent,
+    metadata: ctx.metadata
+  };
+}
+function invoke(fn) {
+  return new Promise((resolve, reject) => {
+    try {
+      Promise.resolve(fn()).then(resolve, reject);
+    } catch (e) {
+      reject(e);
+    }
+  });
+}
+function getCurrentContext() {
+  try {
+    const s = storage.getStore();
+    if (!s) return void 0;
+    return toPublicContext(s);
+  } catch {
+    return void 0;
+  }
+}
+function getCurrentRunId() {
+  try {
+    return storage.getStore()?.runId;
+  } catch {
+    return void 0;
+  }
+}
+function getCurrentRunName() {
+  try {
+    return storage.getStore()?.runName;
+  } catch {
+    return void 0;
+  }
+}
+function getCurrentStepId() {
+  try {
+    return storage.getStore()?.currentStepId;
+  } catch {
+    return void 0;
+  }
+}
+function getParentStepId() {
+  return getCurrentStepId();
+}
+function getCurrentDepth() {
+  try {
+    const d = storage.getStore()?.currentDepth;
+    return typeof d === "number" && Number.isFinite(d) ? d : 0;
+  } catch {
+    return 0;
+  }
+}
+function hasActiveContext() {
+  try {
+    return storage.getStore() !== void 0;
+  } catch {
+    return false;
+  }
+}
+function getTraceDirFromContext() {
+  try {
+    return storage.getStore()?.traceDir;
+  } catch {
+    return void 0;
+  }
+}
+function isSilentContext() {
+  try {
+    const s = storage.getStore();
+    return s ? s.silent : false;
+  } catch {
+    return false;
+  }
+}
+function runWithContext(context, fn) {
+  const runtime = {
+    runId: context.runId,
+    runName: context.runName,
+    traceDir: context.traceDir,
+    silent: context.silent,
+    metadata: context.metadata,
+    currentDepth: 0
+  };
+  return new Promise((resolve, reject) => {
+    storage.run(runtime, () => {
+      try {
+        Promise.resolve(fn()).then(resolve, reject);
+      } catch (e) {
+        reject(e);
+      }
+    });
+  });
+}
+function runWithStepContext(stepId, fn) {
+  let parent;
+  try {
+    parent = storage.getStore();
+  } catch {
+    parent = void 0;
+  }
+  if (!parent) {
+    return invoke(fn);
+  }
+  const derived = {
+    runId: parent.runId,
+    runName: parent.runName,
+    traceDir: parent.traceDir,
+    silent: parent.silent,
+    metadata: parent.metadata,
+    currentStepId: stepId,
+    currentDepth: parent.currentDepth + 1
+  };
+  return new Promise((resolve, reject) => {
+    storage.run(derived, () => {
+      try {
+        Promise.resolve(fn()).then(resolve, reject);
+      } catch (e) {
+        reject(e);
+      }
+    });
+  });
+}
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function nonEmptyString(value) {
+  return typeof value === "string" && value.trim() !== "";
+}
+function finiteNumber(value) {
+  return typeof value === "number" && Number.isFinite(value);
+}
+function optionalErrorInfo(value) {
+  if (value === void 0) return true;
+  if (!isRecord2(value)) return false;
+  if (typeof value.message !== "string") return false;
+  if ("stack" in value && value.stack !== void 0) {
+    if (typeof value.stack !== "string") return false;
+  }
+  return true;
+}
+function validateEvent(event) {
+  if (!isRecord2(event)) return false;
+  if (event.schemaVersion !== "0.1") return false;
+  if (!finiteNumber(event.timestamp)) return false;
+  if (typeof event.event !== "string") return false;
+  switch (event.event) {
+    case "run_started": {
+      if (!nonEmptyString(event.runId) || !nonEmptyString(event.name) || !finiteNumber(event.startTime)) {
+        return false;
+      }
+      if (event.metadata !== void 0 && !isRecord2(event.metadata)) {
+        return false;
+      }
+      return true;
+    }
+    case "run_completed": {
+      return nonEmptyString(event.runId) && (event.status === "success" || event.status === "error") && finiteNumber(event.endTime) && finiteNumber(event.durationMs) && optionalErrorInfo(event.error);
+    }
+    case "step_started": {
+      if (!nonEmptyString(event.runId) || !nonEmptyString(event.stepId) || !nonEmptyString(event.name) || !isStepType(event.type) || !finiteNumber(event.startTime)) {
+        return false;
+      }
+      if (event.parentId !== void 0 && typeof event.parentId !== "string") {
+        return false;
+      }
+      if (event.metadata !== void 0 && !isRecord2(event.metadata)) {
+        return false;
+      }
+      return true;
+    }
+    case "step_completed": {
+      return nonEmptyString(event.runId) && nonEmptyString(event.stepId) && (event.status === "success" || event.status === "error") && finiteNumber(event.endTime) && finiteNumber(event.durationMs) && optionalErrorInfo(event.error);
+    }
+    default:
+      return false;
+  }
+}
+function serializeEvent(event) {
+  try {
+    return JSON.stringify(event);
+  } catch {
+    return "";
+  }
+}
+async function initializeTraceFile(runId, traceDir) {
+  try {
+    const usable = await ensureTraceDir(traceDir);
+    const filePath = getTraceFilePath(runId, usable);
+    await writeFile(filePath, "", "utf-8");
+    return filePath;
+  } catch (e) {
+    warn("Failed to initialize trace file", e);
+  }
+  try {
+    const usable = await ensureTraceDir(FALLBACK_TRACE_DIR);
+    const filePath = getTraceFilePath(runId, usable);
+    await writeFile(filePath, "", "utf-8");
+    return filePath;
+  } catch (e) {
+    warn("Failed to initialize trace file on fallback directory", e);
+    return void 0;
+  }
+}
+async function writeTraceEvent(event, traceDir) {
+  if (!validateEvent(event)) {
+    warn("Skipped invalid trace event (validation failed)");
+    return;
+  }
+  const line = serializeEvent(event);
+  if (line === "") {
+    warn("Skipped trace event (serialization failed)");
+    return;
+  }
+  const payload = `${line}
+`;
+  const tryAppend = async (dir) => {
+    try {
+      const usable = await ensureTraceDir(dir);
+      const filePath = getTraceFilePath(event.runId, usable);
+      await appendFile(filePath, payload, "utf-8");
+      return true;
+    } catch {
+      return false;
+    }
+  };
+  if (await tryAppend(traceDir)) {
+    return;
+  }
+  warn(`Failed to append trace event for run ${event.runId}`);
+  if (await tryAppend(FALLBACK_TRACE_DIR)) {
+    return;
+  }
+  warn("Failed to append trace event to fallback directory");
+}
+async function readTraceFile(runId, traceDir) {
+  try {
+    const filePath = getTraceFilePath(runId, traceDir);
+    return await readFile(filePath, "utf-8");
+  } catch (e) {
+    if (e && typeof e === "object" && "code" in e && e.code === "ENOENT") {
+      return void 0;
+    }
+    warn("Unexpected error reading trace file", e);
+    return void 0;
+  }
+}
+async function readTraceEvents(runId, traceDir) {
+  const out = [];
+  try {
+    const raw = await readTraceFile(runId, traceDir);
+    if (raw === void 0) {
+      return out;
+    }
+    const lines = raw.split("\n");
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (trimmed === "") continue;
+      let parsed;
+      try {
+        parsed = JSON.parse(trimmed);
+      } catch {
+        warn("Skipped invalid JSON line in trace file");
+        continue;
+      }
+      if (validateEvent(parsed)) {
+        out.push(parsed);
+      } else {
+        warn("Skipped invalid trace event line in trace file");
+      }
+    }
+  } catch (e) {
+    warn("Failed to read trace events", e);
+  }
+  return out;
+}
+async function listTraceFiles(traceDir) {
+  try {
+    const usable = path.resolve(traceDir);
+    const names = await readdir(usable);
+    const jsonl = names.filter((n) => n.endsWith(".jsonl"));
+    const withStat = await Promise.all(
+      jsonl.map(async (name) => {
+        try {
+          const st = await stat(path.join(usable, name));
+          return { name, mtime: st.mtimeMs };
+        } catch {
+          return { name, mtime: 0 };
+        }
+      })
+    );
+    withStat.sort((a, b) => {
+      if (b.mtime !== a.mtime) return b.mtime - a.mtime;
+      return a.name.localeCompare(b.name);
+    });
+    return withStat.map((x) => x.name);
+  } catch {
+    return [];
+  }
+}
+function getRunIdFromTraceFileName(fileName) {
+  try {
+    const base = path.basename(fileName);
+    if (!base.endsWith(".jsonl")) return void 0;
+    const id = base.slice(0, -".jsonl".length);
+    return id === "" ? void 0 : id;
+  } catch {
+    return void 0;
+  }
+}
+var TERMINAL_INDENT = "  ";
+var MAX_TERMINAL_NAME_LENGTH = 80;
+var MAX_TERMINAL_DEPTH = 10;
+function normalizeDepth(depth) {
+  if (!Number.isFinite(depth) || depth < 0) {
+    return 0;
+  }
+  return Math.min(Math.floor(depth), MAX_TERMINAL_DEPTH);
+}
+function safePrint(line = "") {
+  try {
+    console.log(line);
+  } catch {
+  }
+}
+function getIndent(depth) {
+  return TERMINAL_INDENT.repeat(normalizeDepth(depth));
+}
+function formatTerminalName(name) {
+  if (typeof name !== "string" || name.trim() === "") {
+    return "unnamed";
+  }
+  return truncateName(name, MAX_TERMINAL_NAME_LENGTH);
+}
+function getStatusIcon(status) {
+  if (status === "success") return chalk.green("\u2714");
+  if (status === "error") return chalk.red("\u2716");
+  return chalk.yellow("\u23F3");
+}
+function renderStepLine(name, durationMs, status, depth) {
+  try {
+    const nm = formatTerminalName(name);
+    const ind = getIndent(depth ?? 0);
+    if (status === "running" && durationMs === void 0) {
+      return `${ind}${chalk.yellow("\u23F3")} ${nm}`;
+    }
+    const hasDur = durationMs !== void 0 && Number.isFinite(durationMs);
+    const dur = hasDur ? formatDuration(durationMs) : void 0;
+    if (status === "running") {
+      return dur !== void 0 ? `${ind}${chalk.yellow("\u23F3")} ${nm} (${dur})` : `${ind}${chalk.yellow("\u23F3")} ${nm}`;
+    }
+    if (!hasDur || dur === void 0) {
+      return `${ind}${chalk.yellow("\u23F3")} ${nm}`;
+    }
+    if (status === "success") {
+      return `${ind}${getStatusIcon("success")} ${nm} (${dur})`;
+    }
+    return `${ind}${getStatusIcon("error")} ${nm} (${dur})`;
+  } catch {
+    return "";
+  }
+}
+function renderErrorLine(error, depth) {
+  try {
+    const msg = typeof error.message === "string" ? error.message : "";
+    const ind = getIndent((depth ?? 0) + 1);
+    return `${ind}Error: ${msg}`;
+  } catch {
+    return "";
+  }
+}
+function renderRunSummary(durationMs, status, traceFilePath) {
+  try {
+    const dur = Number.isFinite(durationMs) ? formatDuration(durationMs) : formatDuration(0);
+    const head = status === "error" ? `Failed in ${dur}` : `Completed in ${dur}`;
+    const lines = [head];
+    if (traceFilePath !== void 0 && traceFilePath.trim() !== "") {
+      lines.push(`Trace: ${traceFilePath}`);
+    }
+    return lines;
+  } catch {
+    return [];
+  }
+}
+function printRunStart(runId, name) {
+  if (isSilentContext()) return;
+  try {
+    safePrint("");
+    const header = `${chalk.cyan.bold("\u{1F50D} AgentInspect:")} ${formatTerminalName(name)} ${chalk.dim(`(${runId})`)}`;
+    safePrint(header);
+  } catch {
+  }
+}
+function printStepStart(name, depth = 0) {
+  if (isSilentContext()) return;
+  try {
+    safePrint(renderStepLine(name, void 0, "running", depth));
+  } catch {
+  }
+}
+function printStepComplete(name, durationMs, status, depth = 0) {
+  if (isSilentContext()) return;
+  try {
+    safePrint(renderStepLine(name, durationMs, status, depth));
+  } catch {
+  }
+}
+function printError(error, depth = 0) {
+  if (isSilentContext()) return;
+  try {
+    safePrint(renderErrorLine(error, depth));
+  } catch {
+  }
+}
+function printRunComplete(_name, _runId, durationMs, status, traceFilePath) {
+  if (isSilentContext()) return;
+  try {
+    const lines = renderRunSummary(durationMs, status, traceFilePath);
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      if (i === 0) {
+        const color = status === "error" ? chalk.red : status === "running" ? chalk.yellow : chalk.green;
+        safePrint(color(line));
+      } else {
+        safePrint(chalk.dim(line));
+      }
+    }
+  } catch {
+  }
+}
+function printFailedAt(stepName) {
+  if (isSilentContext()) return;
+  try {
+    safePrint(`Failed at: ${formatTerminalName(stepName)}`);
+  } catch {
+  }
+}
+
+// packages/core/src/inspect-run.ts
+function normalizeRunName(name) {
+  if (typeof name !== "string" || name.trim() === "") {
+    return "unnamed-run";
+  }
+  return truncateName(name.trim(), 100);
+}
+async function safeInstrumentation(label, op) {
+  try {
+    await Promise.resolve(op());
+  } catch (e) {
+    warn(`inspectRun: ${label}`, e);
+  }
+}
+async function inspectRun(name, fn, options) {
+  if (typeof fn !== "function") {
+    throw new TypeError("inspectRun requires `fn` to be a function");
+  }
+  const runName = normalizeRunName(name);
+  const runId = createRunId();
+  const traceDir = typeof options?.traceDir === "string" && options.traceDir.trim() !== "" ? options.traceDir.trim() : getDefaultTraceDir();
+  const context = {
+    runId,
+    runName,
+    traceDir,
+    silent: options?.silent ?? false,
+    metadata: options?.metadata
+  };
+  return runWithContext(context, async () => {
+    const startTime = Date.now();
+    let traceFilePath;
+    await safeInstrumentation("initializeTraceFile", async () => {
+      traceFilePath = await initializeTraceFile(runId, traceDir);
+    });
+    await safeInstrumentation("writeTraceEvent(run_started)", async () => {
+      const started = {
+        schemaVersion: "0.1",
+        event: "run_started",
+        timestamp: startTime,
+        runId,
+        name: runName,
+        startTime,
+        ...options?.metadata !== void 0 ? { metadata: options.metadata } : {}
+      };
+      await writeTraceEvent(started, traceDir);
+    });
+    await safeInstrumentation("printRunStart", () => {
+      printRunStart(runId, runName);
+    });
+    let result;
+    try {
+      result = await Promise.resolve(fn());
+    } catch (userError) {
+      const endTime2 = Date.now();
+      const durationMs2 = endTime2 - startTime;
+      const formatted = formatError(userError);
+      const printPath2 = traceFilePath ?? getTraceFilePath(runId, traceDir);
+      await safeInstrumentation("writeTraceEvent(run_completed error)", async () => {
+        const completed = {
+          schemaVersion: "0.1",
+          event: "run_completed",
+          timestamp: endTime2,
+          runId,
+          status: "error",
+          endTime: endTime2,
+          durationMs: durationMs2,
+          error: formatted
+        };
+        await writeTraceEvent(completed, traceDir);
+      });
+      await safeInstrumentation("printRunComplete(error)", () => {
+        printRunComplete(runName, runId, durationMs2, "error", printPath2);
+      });
+      throw userError;
+    }
+    const endTime = Date.now();
+    const durationMs = endTime - startTime;
+    const printPath = traceFilePath ?? getTraceFilePath(runId, traceDir);
+    await safeInstrumentation("writeTraceEvent(run_completed success)", async () => {
+      const completed = {
+        schemaVersion: "0.1",
+        event: "run_completed",
+        timestamp: endTime,
+        runId,
+        status: "success",
+        endTime,
+        durationMs
+      };
+      await writeTraceEvent(completed, traceDir);
+    });
+    await safeInstrumentation("printRunComplete(success)", () => {
+      printRunComplete(runName, runId, durationMs, "success", printPath);
+    });
+    return result;
+  });
+}
+
+// packages/core/src/step.ts
+function normalizeStepName(name) {
+  if (typeof name !== "string" || name.trim() === "") {
+    return "unnamed-step";
+  }
+  return truncateName(name.trim(), 100);
+}
+async function safeInstrumentation2(label, op) {
+  try {
+    await Promise.resolve(op());
+  } catch (e) {
+    warn(`step: ${label}`, e);
+  }
+}
+async function stepImpl(name, fn, options) {
+  if (typeof fn !== "function") {
+    throw new TypeError("step requires `fn` to be a function");
+  }
+  const stepName = normalizeStepName(name);
+  const context = getCurrentContext();
+  if (!context) {
+    warn("step() called outside inspectRun(); executing without instrumentation");
+    return Promise.resolve(fn());
+  }
+  const stepId = createStepId();
+  const renderDepth = getCurrentDepth();
+  const parentId = getParentStepId();
+  const stepType = options?.type ?? "logic";
+  const metadata = options?.metadata;
+  const startTime = Date.now();
+  await safeInstrumentation2("writeTraceEvent(step_started)", async () => {
+    const started = {
+      schemaVersion: "0.1",
+      event: "step_started",
+      timestamp: startTime,
+      runId: context.runId,
+      stepId,
+      ...typeof parentId === "string" && parentId.trim() !== "" ? { parentId } : {},
+      name: stepName,
+      type: stepType,
+      startTime,
+      ...metadata !== void 0 ? { metadata } : {}
+    };
+    await writeTraceEvent(started, context.traceDir);
+  });
+  await safeInstrumentation2("printStepStart", () => {
+    printStepStart(stepName, renderDepth);
+  });
+  let result;
+  try {
+    result = await runWithStepContext(stepId, async () => {
+      return await Promise.resolve(fn());
+    });
+  } catch (userError) {
+    const endTime2 = Date.now();
+    const durationMs2 = endTime2 - startTime;
+    const formatted = formatError(userError);
+    await safeInstrumentation2("writeTraceEvent(step_completed error)", async () => {
+      const completed = {
+        schemaVersion: "0.1",
+        event: "step_completed",
+        timestamp: endTime2,
+        runId: context.runId,
+        stepId,
+        status: "error",
+        endTime: endTime2,
+        durationMs: durationMs2,
+        error: formatted
+      };
+      await writeTraceEvent(completed, context.traceDir);
+    });
+    await safeInstrumentation2("printStepComplete(error)", () => {
+      printStepComplete(stepName, durationMs2, "error", renderDepth);
+    });
+    await safeInstrumentation2("printError", () => {
+      printError(formatted, renderDepth);
+    });
+    await safeInstrumentation2("printFailedAt", () => {
+      printFailedAt(stepName);
+    });
+    throw userError;
+  }
+  const endTime = Date.now();
+  const durationMs = endTime - startTime;
+  await safeInstrumentation2("writeTraceEvent(step_completed success)", async () => {
+    const completed = {
+      schemaVersion: "0.1",
+      event: "step_completed",
+      timestamp: endTime,
+      runId: context.runId,
+      stepId,
+      status: "success",
+      endTime,
+      durationMs
+    };
+    await writeTraceEvent(completed, context.traceDir);
+  });
+  await safeInstrumentation2("printStepComplete(success)", () => {
+    printStepComplete(stepName, durationMs, "success", renderDepth);
+  });
+  return result;
+}
+async function stepLlm(model, fn) {
+  const modelName = typeof model === "string" && model.trim() !== "" ? model.trim() : "unknown-model";
+  return stepImpl(`llm:${modelName}`, fn, {
+    type: "llm",
+    metadata: { model: modelName }
+  });
+}
+async function stepTool(toolName, fn) {
+  const normalized = typeof toolName === "string" && toolName.trim() !== "" ? toolName.trim() : "unknown-tool";
+  return stepImpl(`tool:${normalized}`, fn, {
+    type: "tool",
+    metadata: { toolName: normalized }
+  });
+}
+var step = Object.assign(stepImpl, {
+  llm: stepLlm,
+  tool: stepTool
+});
+
+// packages/core/src/observe.ts
+var INSTRUMENTABLE_METHODS = ["run", "execute", "invoke"];
+function isInstrumentableProp(prop) {
+  if (typeof prop !== "string") return false;
+  return INSTRUMENTABLE_METHODS.includes(prop);
+}
+function getAgentLabel(target) {
+  try {
+    const ctor = Reflect.get(target, "constructor");
+    const name = ctor?.name;
+    if (typeof name === "string" && name.trim() !== "" && name !== "Object") {
+      return name.trim();
+    }
+  } catch {
+  }
+  return "Agent";
+}
+function buildRunName(target, methodKey) {
+  const label = getAgentLabel(target);
+  return truncateName(`${label}.${methodKey}`, 100);
+}
+function observe(agent, options) {
+  if (agent === null || agent === void 0) {
+    warn("observe() requires an object");
+    return agent;
+  }
+  const agentType = typeof agent;
+  if (agentType !== "object" && agentType !== "function") {
+    warn("observe() requires an object");
+    return agent;
+  }
+  const target = agent;
+  const handlers = {
+    get(proxyTarget, prop, receiver) {
+      try {
+        const value = Reflect.get(proxyTarget, prop, receiver);
+        if (isInstrumentableProp(prop)) {
+          if (typeof value !== "function") {
+            return value;
+          }
+          const methodKey = prop;
+          return function observedWrapper(...args) {
+            let runName;
+            try {
+              runName = buildRunName(proxyTarget, methodKey);
+            } catch (e) {
+              warn("observe() method wrapping failed", e);
+              return value.apply(proxyTarget, args);
+            }
+            return inspectRun(runName, () => value.apply(proxyTarget, args), options);
+          };
+        }
+        if (typeof value === "function" && prop !== "constructor") {
+          return value.bind(proxyTarget);
+        }
+        return value;
+      } catch (e) {
+        warn("observe() method wrapping failed", e);
+        try {
+          return Reflect.get(proxyTarget, prop, receiver);
+        } catch {
+          return void 0;
+        }
+      }
+    }
+  };
+  try {
+    return new Proxy(target, handlers);
+  } catch (e) {
+    warn("observe() failed", e);
+    return agent;
+  }
+}
+
+export { DEFAULT_TRACE_DIR_NAME, FALLBACK_TRACE_DIR, MAX_NAME_LENGTH, MAX_TERMINAL_DEPTH, MAX_TERMINAL_NAME_LENGTH, RUNS_DIR_NAME, TERMINAL_INDENT, createRunId, createStepId, ensureTraceDir, formatDuration, formatError, formatTerminalName, formatTimestamp, getCurrentContext, getCurrentDepth, getCurrentRunId, getCurrentRunName, getCurrentStepId, getDefaultTraceDir, getIndent, getParentStepId, getRunIdFromTraceFileName, getTraceDirFromContext, getTraceFilePath, hasActiveContext, initializeTraceFile, inspectRun, isSilentContext, isStepStatus, isStepType, isTraceEvent, listTraceFiles, observe, printError, printFailedAt, printRunComplete, printRunStart, printStepComplete, printStepStart, readTraceEvents, readTraceFile, renderErrorLine, renderRunSummary, renderStepLine, runWithContext, runWithStepContext, serializeEvent, step, truncateName, validateEvent, warn, writeTraceEvent };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map