agent-inspect 4.2.0 → 4.4.0

package/packages/core/dist/advanced.cjs

@@ -275,6 +275,9 @@ function isTraceEvent(value) {
     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";
     }
+    case "outcome_observed": {
+      return typeof value.runId === "string" && typeof value.outcomeId === "string" && typeof value.name === "string" && typeof value.expectation === "string" && (value.status === "passed" || value.status === "failed" || value.status === "unknown" || value.status === "skipped") && typeof value.observedAt === "number";
+    }
     default:
       return false;
   }
@@ -292,7 +295,8 @@ var INSPECT_KINDS = [
   "RESULT",
   "ERROR",
   "LOGIC",
-  "LOG"
+  "LOG",
+  "OUTCOME"
 ];
 var ATTRIBUTION_CONFIDENCES = [
   "explicit",
@@ -584,6 +588,32 @@ function fromLegacyStepCompleted(event) {
   if (error) out.error = error;
   return out;
 }
+function fromLegacyOutcomeObserved(event) {
+  const attrs = event.attributes ?? {};
+  const observedAtRaw = attrs.observedAt;
+  const observedAt = typeof observedAtRaw === "string" ? Date.parse(observedAtRaw) : typeof observedAtRaw === "number" && Number.isFinite(observedAtRaw) ? observedAtRaw : resolveTimes(event).timestamp;
+  const status = attrs.outcomeStatus;
+  const out = {
+    schemaVersion: "0.1",
+    event: "outcome_observed",
+    timestamp: observedAt,
+    runId: event.runId,
+    outcomeId: typeof attrs.outcomeId === "string" ? attrs.outcomeId : event.eventId,
+    name: event.name,
+    expectation: typeof attrs.expectation === "string" ? attrs.expectation : event.name,
+    status: status === "passed" || status === "failed" || status === "unknown" || status === "skipped" ? status : "unknown",
+    observedAt
+  };
+  if (event.parentId !== void 0) out.parentId = event.parentId;
+  if (typeof attrs.method === "string") out.method = attrs.method;
+  if (attrs.actual !== void 0) out.actual = attrs.actual;
+  if (event.outputSummary !== void 0) out.actual = event.outputSummary;
+  if (attrs.evidence !== void 0) out.evidence = attrs.evidence;
+  return out;
+}
+function fromNativeOutcome(event) {
+  return [fromLegacyOutcomeObserved(event)];
+}
 function fromNativeRun(event) {
   const { timestamp, startTime, endTime } = resolveTimes(event);
   const runStatus = mapPersistedStatusToRunStatus(event.status);
@@ -671,9 +701,13 @@ function persistedInspectEventToTraceEvents(event) {
   if (legacyEvent === "run_completed") return [fromLegacyRunCompleted(event)];
   if (legacyEvent === "step_started") return [fromLegacyStepStarted(event)];
   if (legacyEvent === "step_completed") return [fromLegacyStepCompleted(event)];
+  if (legacyEvent === "outcome_observed") return [fromLegacyOutcomeObserved(event)];
   if (event.kind === "RUN") {
     return fromNativeRun(event);
   }
+  if (event.kind === "OUTCOME") {
+    return fromNativeOutcome(event);
+  }
   return fromNativeStep(event);
 }
 
@@ -1012,6 +1046,9 @@ function validateEvent(event) {
     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);
     }
+    case "outcome_observed": {
+      return nonEmptyString(event.runId) && nonEmptyString(event.outcomeId) && nonEmptyString(event.name) && nonEmptyString(event.expectation) && (event.status === "passed" || event.status === "failed" || event.status === "unknown" || event.status === "skipped") && finiteNumber(event.observedAt);
+    }
     default:
       return false;
   }
@@ -1956,9 +1993,111 @@ function createInspectorRuntime(options = {}) {
   return runtime;
 }
 
+// packages/core/src/outcomes/types.ts
+var OBSERVED_OUTCOME_STATUSES = [
+  "passed",
+  "failed",
+  "unknown",
+  "skipped"
+];
+var OBSERVED_OUTCOME_METHODS = [
+  "dom",
+  "accessibility",
+  "snapshot",
+  "network",
+  "storage",
+  "filesystem",
+  "database",
+  "queue",
+  "custom"
+];
+var OUTCOME_LEGACY_EVENT = "outcome_observed";
+
+// packages/core/src/outcomes/validate.ts
+function normalizeName(name) {
+  const trimmed = name.trim();
+  if (trimmed === "") {
+    throw new Error("observeOutcome requires a non-empty name.");
+  }
+  return trimmed.slice(0, 100);
+}
+function normalizeExpectation(value) {
+  const trimmed = value.trim();
+  if (trimmed === "") {
+    throw new Error("observeOutcome requires a non-empty expectation.");
+  }
+  return trimmed.slice(0, 500);
+}
+function parseObservedOutcomeStatus(value) {
+  const trimmed = value.trim().toLowerCase();
+  if (OBSERVED_OUTCOME_STATUSES.includes(trimmed)) {
+    return trimmed;
+  }
+  throw new Error(
+    `Unsupported observation status "${value}". Use passed, failed, unknown, or skipped.`
+  );
+}
+function parseMethod(value) {
+  if (value === void 0 || value.trim() === "") return void 0;
+  const trimmed = value.trim().toLowerCase();
+  if (OBSERVED_OUTCOME_METHODS.includes(trimmed)) {
+    return trimmed;
+  }
+  throw new Error(`Unsupported observation method "${value}".`);
+}
+function parseObservedAt(value, fallback) {
+  if (value === void 0) return fallback;
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string") {
+    const parsed = Date.parse(value);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return fallback;
+}
+function normalizeObserveOutcomeInput(name, options, nowMs = Date.now()) {
+  return {
+    name: normalizeName(name),
+    expectation: normalizeExpectation(options.expectation),
+    status: options.status,
+    ...options.method !== void 0 ? { method: parseMethod(options.method) } : {},
+    ...options.actual !== void 0 ? { actual: options.actual } : {},
+    ...options.evidence !== void 0 ? { evidence: options.evidence } : {},
+    observedAt: parseObservedAt(options.observedAt, nowMs)
+  };
+}
+
+// packages/core/src/outcomes/extract.ts
+function fromOutcomeObservedEvent(event) {
+  return {
+    outcomeId: event.outcomeId,
+    runId: event.runId,
+    ...event.parentId !== void 0 ? { parentId: event.parentId } : {},
+    name: event.name,
+    expectation: event.expectation,
+    status: event.status,
+    ...event.method !== void 0 ? { method: event.method } : {},
+    ...event.actual !== void 0 ? { actual: event.actual } : {},
+    ...event.evidence !== void 0 ? { evidence: event.evidence } : {},
+    observedAt: event.observedAt
+  };
+}
+function extractOutcomesFromTraceEvents(events) {
+  const out = [];
+  for (const event of events) {
+    if (event.event === OUTCOME_LEGACY_EVENT) {
+      out.push(fromOutcomeObservedEvent(event));
+    }
+  }
+  return out.sort((a, b) => a.observedAt - b.observedAt || a.name.localeCompare(b.name));
+}
+function parseObservationFilter(value) {
+  if (value === void 0 || value.trim() === "") return void 0;
+  return parseObservedOutcomeStatus(value);
+}
+
 // packages/core/src/inspector.ts
 var INSPECTOR_PERSISTED_SCHEMA_VERSION = "1.0";
-function normalizeName(name, fallback) {
+function normalizeName2(name, fallback) {
   if (typeof name !== "string" || name.trim() === "") return fallback;
   return truncateName(name.trim(), 100);
 }
@@ -2059,7 +2198,7 @@ function createInspector(options = {}) {
     if (options.enabled === false) {
       return Promise.resolve(fn());
     }
-    const runName = normalizeName(name, "unnamed-run");
+    const runName = normalizeName2(name, "unnamed-run");
     const runId = runOptions.runId ?? createRunId();
     const traceDir = runOptions.traceDir ?? options.traceDir ?? getDefaultTraceDir();
     const metadata = mergeMetadata(options.metadata, runOptions.metadata);
@@ -2139,7 +2278,7 @@ function createInspector(options = {}) {
       return Promise.resolve(fn());
     }
     const context = runtime.getCurrentContext();
-    const stepName = normalizeName(name, "unnamed-step");
+    const stepName = normalizeName2(name, "unnamed-step");
     const stepId = createStepId();
     const parentId = runtime.getCurrentStepId();
     const stepType = stepOptions.type ?? "logic";
@@ -2219,7 +2358,7 @@ function createInspector(options = {}) {
     run,
     step,
     tool(name, fn, toolOptions) {
-      const toolName = normalizeName(name, "unknown-tool");
+      const toolName = normalizeName2(name, "unknown-tool");
       return step(`tool:${toolName}`, fn, {
         ...toolOptions,
         type: "tool",
@@ -2230,7 +2369,7 @@ function createInspector(options = {}) {
       });
     },
     llm(name, fn, llmOptions) {
-      const model = normalizeName(name, "unknown-model");
+      const model = normalizeName2(name, "unknown-model");
       return step(`llm:${model}`, fn, {
         ...llmOptions,
         type: "llm",
@@ -2243,6 +2382,41 @@ function createInspector(options = {}) {
     observe(name, fn, observeOptions) {
       return async (...args) => step(name, () => Promise.resolve(fn(...args)), observeOptions);
     },
+    async observeOutcome(name, outcomeOptions) {
+      const ctx = runtime.getCurrentContext();
+      if (!ctx) return;
+      let normalized;
+      try {
+        normalized = normalizeObserveOutcomeInput(name, outcomeOptions);
+      } catch {
+        return;
+      }
+      const outcomeId = createStepId();
+      const parentId = runtime.getCurrentStepId();
+      await write({
+        schemaVersion: INSPECTOR_PERSISTED_SCHEMA_VERSION,
+        eventId: outcomeId,
+        runId: ctx.runId,
+        ...parentId !== void 0 ? { parentId } : {},
+        kind: "OUTCOME",
+        name: normalized.name,
+        status: normalized.status === "failed" ? "error" : "ok",
+        timestamp: new Date(normalized.observedAt).toISOString(),
+        confidence: "explicit",
+        source: { type: "manual", name: "createInspector" },
+        attributes: {
+          legacyEvent: "outcome_observed",
+          outcomeId,
+          outcomeStatus: normalized.status,
+          expectation: normalized.expectation,
+          ...normalized.method !== void 0 ? { method: normalized.method } : {},
+          ...normalized.actual !== void 0 ? { actual: normalized.actual } : {},
+          ...normalized.evidence !== void 0 ? { evidence: normalized.evidence } : {},
+          observedAt: new Date(normalized.observedAt).toISOString()
+        },
+        ...normalized.actual !== void 0 ? { outputSummary: normalized.actual } : {}
+      });
+    },
     getDiagnostics() {
       return runtime.getDiagnostics();
     },
@@ -3867,8 +4041,9 @@ async function searchTraces(metas, options) {
   }
   const limit = options.limit ?? 50;
   const sessionId = options.session?.trim();
+  const observationStatus = parseObservationFilter(options.observation);
   const hasContentFilter = Boolean(
-    options.status || stepTypeFilter || nameQuery || toolQuery || durationFilter
+    options.status || stepTypeFilter || nameQuery || toolQuery || durationFilter || observationStatus
   );
   const results = [];
   const sessionLabel = sessionId && sessionId !== "" ? sessionId : void 0;
@@ -3913,6 +4088,22 @@ async function searchTraces(metas, options) {
       statusFilter: options.status
     });
     results.push(...stepMatches);
+    if (observationStatus) {
+      const outcomes = extractOutcomesFromTraceEvents(events);
+      const matched = outcomes.filter((outcome) => outcome.status === observationStatus);
+      for (const outcome of matched) {
+        results.push({
+          runId: m.runId,
+          runName: m.name,
+          runStatus: m.status,
+          stepName: outcome.name,
+          timestamp: outcome.observedAt,
+          matchReason: `observation status=${outcome.status}`,
+          matchedFields: ["outcome.status", "outcome.name"],
+          filePath: m.filePath
+        });
+      }
+    }
   }
   results.sort((a, b) => {
     const ta = a.timestamp ?? 0;
@@ -4301,9 +4492,10 @@ function buildActivitySummary(index, options = {}) {
     entries
   };
 }
-function renderActivitySummaryHuman(summary) {
+function renderActivitySummaryHuman(summary, options) {
   const lines = [];
-  const todayStart = /* @__PURE__ */ new Date();
+  const nowMs = options?.nowMs ?? Date.now();
+  const todayStart = new Date(nowMs);
   todayStart.setHours(0, 0, 0, 0);
   const todayMs = todayStart.getTime();
   const today = summary.entries.filter(
@@ -4734,12 +4926,12 @@ function buildCriticalPath(runs, handoffs) {
     handoffs.filter((edge) => edge.confidence === "explicit").map((edge) => edge.from)
   );
   const ordered = [...runs].sort(compareRuns);
-  const path5 = [];
+  const path6 = [];
   const visited = /* @__PURE__ */ new Set();
   const pushRun = (run, confidence, source) => {
     if (visited.has(run.runId)) return;
     visited.add(run.runId);
-    path5.push({
+    path6.push({
       runId: run.runId,
       name: run.name,
       startedAt: run.startedAt,
@@ -4764,7 +4956,7 @@ function buildCriticalPath(runs, handoffs) {
     const confidence = explicitTargets.has(run.runId) || explicitSources.has(run.runId) ? "explicit" : "correlated";
     pushRun(run, confidence, confidence === "explicit" ? "manual" : "inferred");
   }
-  return path5;
+  return path6;
 }
 function metaRunIdMatches(run, token, runById) {
   const meta = extractSessionWorkflowMetadata(run.metadata);
@@ -4884,6 +5076,190 @@ async function isAgentInspectTrace(filePath) {
   }
 }
 
+// packages/core/src/bundle/resolve.ts
+function parseSinceCutoff(since) {
+  const trimmed = since.trim();
+  if (trimmed === "") {
+    throw new Error("--since requires a non-empty duration (e.g. 24h, 7d).");
+  }
+  return Date.now() - parseDuration(trimmed);
+}
+function runActivityMs(run) {
+  if (run.startedAt !== void 0 && Number.isFinite(run.startedAt)) return run.startedAt;
+  if (run.endedAt !== void 0 && Number.isFinite(run.endedAt)) return run.endedAt;
+  return void 0;
+}
+function runsInSinceWindow(runs, since) {
+  const cutoff = parseSinceCutoff(since);
+  const ids = [];
+  for (const run of runs) {
+    const activity = runActivityMs(run);
+    if (activity !== void 0 && activity >= cutoff) {
+      ids.push(run.runId);
+    }
+  }
+  return ids.sort((a, b) => a.localeCompare(b));
+}
+function findSession(index, sessionId) {
+  return index.sessions.find((session) => session.sessionId === sessionId);
+}
+function resolveBundleRunIds(index, runs, options) {
+  const runId = options.runId?.trim();
+  const sessionId = options.sessionId?.trim();
+  const since = options.since?.trim();
+  const modes = [runId ? 1 : 0, sessionId ? 1 : 0, since ? 1 : 0].reduce((a, b) => a + b, 0);
+  if (modes === 0) {
+    throw new Error(
+      "bundle requires a run id, --session <sessionId>, or --since <duration>."
+    );
+  }
+  if (modes > 1) {
+    throw new Error(
+      "bundle accepts only one target: a run id, --session, or --since (not combined)."
+    );
+  }
+  if (runId) {
+    const known = runs.some((run) => run.runId === runId);
+    if (!known) {
+      throw new Error(`Run "${runId}" was not found in the trace directory.`);
+    }
+    return { runIds: [runId] };
+  }
+  if (sessionId) {
+    const session = findSession(index, sessionId);
+    if (!session) {
+      throw new Error(`Session "${sessionId}" was not found.`);
+    }
+    if (session.runIds.length === 0) {
+      throw new Error(`Session "${sessionId}" has no runs to bundle.`);
+    }
+    return {
+      runIds: [...session.runIds].sort((a, b) => a.localeCompare(b)),
+      sessionId
+    };
+  }
+  const runIds = runsInSinceWindow(runs, since);
+  if (runIds.length === 0) {
+    throw new Error(`No runs matched --since ${since}.`);
+  }
+  return { runIds, since };
+}
+
+// packages/core/src/bundle/safety-status.ts
+function aggregateBundleSafeStatus(statuses) {
+  if (statuses.length === 0) return "UNKNOWN";
+  if (statuses.some((status) => status === "UNSAFE")) return "UNSAFE";
+  if (statuses.some((status) => status === "UNKNOWN")) return "UNKNOWN";
+  if (statuses.some((status) => status === "SAFE WITH WARNINGS")) return "SAFE WITH WARNINGS";
+  return "SAFE";
+}
+function toMetadataSafeStatus(status) {
+  if (status === "SAFE WITH WARNINGS") return "SAFE_WITH_WARNINGS";
+  return status;
+}
+function bundleFailsOnSafety(status, allowUnsafe) {
+  if (allowUnsafe) return false;
+  return status === "UNSAFE" || status === "UNKNOWN";
+}
+
+// packages/core/src/bundle/manifest.ts
+var BUNDLE_NOTE = "Generated locally by AgentInspect. Bundles are derived copies for review \u2014 not compliance or security certification. Review before sharing.";
+var PLACEHOLDER_NOTE = "No eval or performance artifacts were requested for this bundle.";
+function buildBundleMetadata(parts) {
+  const aggregate = aggregateBundleSafeStatus(
+    parts.checks.runs.map((run) => run.status)
+  );
+  return {
+    createdAt: parts.createdAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+    agentInspectVersion: parts.agentInspectVersion,
+    redactionProfile: parts.profile,
+    sourceTraceCount: parts.resolve.runIds.length,
+    runIds: [...parts.resolve.runIds],
+    safeStatus: toMetadataSafeStatus(aggregate),
+    files: [...parts.files].sort((a, b) => a.localeCompare(b)),
+    note: BUNDLE_NOTE,
+    ...parts.resolve.sessionId !== void 0 ? { sessionId: parts.resolve.sessionId } : {},
+    ...parts.resolve.since !== void 0 ? { since: parts.resolve.since } : {}
+  };
+}
+function buildPlaceholderArtifact() {
+  return {
+    status: "not_requested",
+    note: PLACEHOLDER_NOTE
+  };
+}
+
+// packages/core/src/bundle/summary.ts
+function markdownTable(rows) {
+  const lines = ["| Field | Value |", "| --- | --- |"];
+  for (const [key, value] of rows) {
+    lines.push(`| ${key} | ${value ?? "unknown"} |`);
+  }
+  return lines.join("\n");
+}
+function buildBundleSummaryMarkdown(parts) {
+  const { metadata, checks, redaction } = parts;
+  const lines = [
+    "# AgentInspect trace bundle",
+    "",
+    metadata.note,
+    "",
+    "## Overview",
+    "",
+    markdownTable([
+      ["Created", metadata.createdAt],
+      ["AgentInspect", metadata.agentInspectVersion],
+      ["Redaction profile", metadata.redactionProfile],
+      ["Safe status", metadata.safeStatus],
+      ["Source traces", metadata.sourceTraceCount],
+      ["Runs", metadata.runIds.join(", ")],
+      ...metadata.sessionId ? [["Session", metadata.sessionId]] : [],
+      ...metadata.since ? [["Since", metadata.since]] : []
+    ]),
+    "",
+    "## Safety checks",
+    "",
+    `Aggregate: **${checks.aggregateStatus}**`,
+    ""
+  ];
+  for (const run of checks.runs) {
+    lines.push(
+      `- \`${run.runId}\`: ${run.status} (${run.findings} finding(s), ${run.errors} error(s), ${run.warnings} warning(s))`
+    );
+  }
+  lines.push("", "## Redaction", "", `Total findings: ${redaction.totalFindings}`, "");
+  for (const run of redaction.runs) {
+    const detectors = run.detectors.length > 0 ? run.detectors.join(", ") : "none";
+    lines.push(`- \`${run.runId}\`: ${run.findings} finding(s); detectors: ${detectors}`);
+  }
+  lines.push(
+    "",
+    "## Files",
+    "",
+    ...metadata.files.map((file) => `- \`${file}\``),
+    "",
+    "_Review every generated artifact before sharing outside your team._",
+    ""
+  );
+  return lines.join("\n");
+}
+function normalizeBundleOutputPath(out) {
+  const trimmed = out.trim();
+  if (trimmed === "") {
+    throw new Error("--out requires a non-empty path.");
+  }
+  const resolved = path__default.default.resolve(trimmed);
+  if (resolved.toLowerCase().endsWith(".zip")) {
+    return resolved.slice(0, -4);
+  }
+  return resolved;
+}
+function defaultBundleOutputPath(runIds) {
+  const label = runIds.length === 1 ? runIds[0] : `multi-${runIds.length}`;
+  const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+  return path__default.default.resolve(`agent-inspect-bundle-${label}-${stamp}`);
+}
+
 // packages/core/src/inspect-run.ts
 function normalizeRunName(name) {
   if (typeof name !== "string" || name.trim() === "") {
@@ -5026,18 +5402,24 @@ exports.RUNS_DIR_NAME = RUNS_DIR_NAME;
 exports.SESSION_WORKFLOW_KEYS = SESSION_WORKFLOW_KEYS;
 exports.TERMINAL_INDENT = TERMINAL_INDENT;
 exports.TraceDirectory = TraceDirectory;
+exports.aggregateBundleSafeStatus = aggregateBundleSafeStatus;
 exports.aggregateSessionCheckResults = aggregateSessionCheckResults;
 exports.buildActivitySummary = buildActivitySummary;
+exports.buildBundleMetadata = buildBundleMetadata;
+exports.buildBundleSummaryMarkdown = buildBundleSummaryMarkdown;
 exports.buildLocalExplanation = buildLocalExplanation;
+exports.buildPlaceholderArtifact = buildPlaceholderArtifact;
 exports.buildRunSummary = buildRunSummary;
 exports.buildRunTimeline = buildRunTimeline;
 exports.buildRunWhatSummary = buildRunWhatSummary;
 exports.buildSessionIndex = buildSessionIndex;
 exports.buildTraceStats = buildTraceStats;
+exports.bundleFailsOnSafety = bundleFailsOnSafety;
 exports.createInspector = createInspector;
 exports.createInspectorRuntime = createInspectorRuntime;
 exports.createRunId = createRunId;
 exports.createStepId = createStepId;
+exports.defaultBundleOutputPath = defaultBundleOutputPath;
 exports.deriveSessionStatus = deriveSessionStatus;
 exports.enrichSessionRunRecord = enrichSessionRunRecord;
 exports.enrichSessionSummary = enrichSessionSummary;
@@ -5076,6 +5458,7 @@ exports.listTraceFiles = listTraceFiles;
 exports.loadSessionRunRecords = loadSessionRunRecords;
 exports.loadTraceMetadataList = loadTraceMetadataList;
 exports.maybeInspectRun = maybeInspectRun;
+exports.normalizeBundleOutputPath = normalizeBundleOutputPath;
 exports.parseDuration = parseDuration;
 exports.parseDurationFilter = parseDurationFilter;
 exports.parseTraceJsonl = parseTraceJsonl;
@@ -5096,6 +5479,7 @@ exports.renderRunWhat = renderRunWhat;
 exports.renderStepLine = renderStepLine;
 exports.renderTimeline = renderTimeline;
 exports.renderTraceStats = renderTraceStats;
+exports.resolveBundleRunIds = resolveBundleRunIds;
 exports.resolveRedactionProfile = resolveRedactionProfile;
 exports.resolveTraceDir = resolveTraceDir;
 exports.resolveTraceSafetyOptions = resolveTraceSafetyOptions;
@@ -5104,6 +5488,7 @@ exports.runWithStepContext = runWithStepContext;
 exports.searchTraces = searchTraces;
 exports.serializeEvent = serializeEvent;
 exports.sessionKeyForRun = sessionKeyForRun;
+exports.toMetadataSafeStatus = toMetadataSafeStatus;
 exports.traceMetasToSessionRunRecords = traceMetasToSessionRunRecords;
 exports.truncateName = truncateName;
 exports.unknownTraceFormatMessage = unknownTraceFormatMessage;