agent-inspect 4.2.0 → 4.4.0

package/packages/core/dist/index.cjs

@@ -257,7 +257,8 @@ var INSPECT_KINDS = [
   "RESULT",
   "ERROR",
   "LOGIC",
-  "LOG"
+  "LOG",
+  "OUTCOME"
 ];
 var ATTRIBUTION_CONFIDENCES = [
   "explicit",
@@ -585,6 +586,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;
   }
@@ -1316,9 +1320,100 @@ function createInspectorRuntime(options = {}) {
   return runtime;
 }
 
+// packages/core/src/outcomes/types.ts
+var OBSERVED_OUTCOME_METHODS = [
+  "dom",
+  "accessibility",
+  "snapshot",
+  "network",
+  "storage",
+  "filesystem",
+  "database",
+  "queue",
+  "custom"
+];
+
+// packages/core/src/outcomes/validate.ts
+function isRecord5(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+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 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)
+  };
+}
+function boundPayload(value, opts) {
+  if (value === void 0) return void 0;
+  if (!isRecord5(value) && !Array.isArray(value)) {
+    if (typeof value === "string") {
+      return value.length > opts.maxMetadataValueLength ? `${value.slice(0, opts.maxMetadataValueLength)}\u2026` : value;
+    }
+    return value;
+  }
+  return prepareMetadataForDisk(
+    isRecord5(value) ? value : { items: value },
+    opts
+  );
+}
+function prepareOutcomeEventForDisk(event, opts) {
+  const actual = boundPayload(event.actual, opts);
+  const evidence = boundPayload(event.evidence, opts);
+  const next = {
+    ...event,
+    ...actual !== void 0 ? { actual } : {},
+    ...evidence !== void 0 ? { evidence } : {}
+  };
+  if ("actual" in event && actual === void 0) {
+    const { actual: _a, ...rest } = next;
+    return rest;
+  }
+  if ("evidence" in event && evidence === void 0) {
+    const { evidence: _e, ...rest } = next;
+    return rest;
+  }
+  return next;
+}
+
 // 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);
 }
@@ -1419,7 +1514,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);
@@ -1499,7 +1594,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";
@@ -1579,7 +1674,7 @@ function createInspector(options = {}) {
     run,
     step: step2,
     tool(name, fn, toolOptions) {
-      const toolName = normalizeName(name, "unknown-tool");
+      const toolName = normalizeName2(name, "unknown-tool");
       return step2(`tool:${toolName}`, fn, {
         ...toolOptions,
         type: "tool",
@@ -1590,7 +1685,7 @@ function createInspector(options = {}) {
       });
     },
     llm(name, fn, llmOptions) {
-      const model = normalizeName(name, "unknown-model");
+      const model = normalizeName2(name, "unknown-model");
       return step2(`llm:${model}`, fn, {
         ...llmOptions,
         type: "llm",
@@ -1603,6 +1698,41 @@ function createInspector(options = {}) {
     observe(name, fn, observeOptions) {
       return async (...args) => step2(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();
     },
@@ -2692,11 +2822,56 @@ function observe(agent, options) {
   }
 }
 
+// packages/core/src/observe-outcome.ts
+async function safeWrite(label, op) {
+  try {
+    await op();
+  } catch (error) {
+    warn(`observeOutcome: ${label}`, error);
+  }
+}
+async function observeOutcome(name, options) {
+  const context = getCurrentContext();
+  if (!context) {
+    warn("observeOutcome() called outside inspectRun(); skipping");
+    return;
+  }
+  let normalized;
+  try {
+    normalized = normalizeObserveOutcomeInput(name, options);
+  } catch (error) {
+    warn("observeOutcome() invalid arguments", error);
+    return;
+  }
+  const traceSafety = getTraceSafetyFromContext();
+  const parentId = getParentStepId();
+  const event = {
+    schemaVersion: "0.1",
+    event: "outcome_observed",
+    timestamp: normalized.observedAt,
+    runId: context.runId,
+    outcomeId: createStepId(),
+    ...parentId !== void 0 ? { parentId } : {},
+    name: normalized.name,
+    expectation: normalized.expectation,
+    status: normalized.status,
+    ...normalized.method !== void 0 ? { method: normalized.method } : {},
+    ...normalized.actual !== void 0 ? { actual: normalized.actual } : {},
+    ...normalized.evidence !== void 0 ? { evidence: normalized.evidence } : {},
+    observedAt: normalized.observedAt
+  };
+  const prepared = traceSafety !== void 0 ? prepareOutcomeEventForDisk(event, traceSafety) : event;
+  await safeWrite("writeTraceEvent", async () => {
+    await writeTraceEvent(prepared, context.traceDir);
+  });
+}
+
 exports.createInspector = createInspector;
 exports.getCurrentCorrelationMetadata = getCurrentCorrelationMetadata;
 exports.inspectRun = inspectRun;
 exports.maybeInspectRun = maybeInspectRun;
 exports.observe = observe;
+exports.observeOutcome = observeOutcome;
 exports.step = step;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map