rea-agents 3.0.0 → 3.2.0

package/dist/domain/conformanceTrustGate.js

@@ -6,19 +6,28 @@ export const dimensionResultSchema = z.strictObject({
     message: z.string().default(""),
     evidence_ids: z.array(z.string()).default([]),
 });
-/** Result of evaluating a trust gate for one scenario. */
-export const trustGateResultSchema = z.strictObject({
+const trustGateResultShape = {
     scenario_id: z.string().min(1),
-    verdict: z.enum(["pass", "fail", "unknown"]),
     dimension_results: z.array(dimensionResultSchema),
-    first_divergence: z
-        .strictObject({
-        dimension: z.string().min(1),
-        evidence_id: z.string().min(1),
-        message: z.string(),
-    })
-        .nullable(),
+};
+const divergenceSchema = z.strictObject({
+    dimension: z.string().min(1),
+    evidence_id: z.string().min(1),
+    message: z.string(),
 });
+/** Result of evaluating a trust gate for one scenario. */
+export const trustGateResultSchema = z.union([
+    z.strictObject({
+        ...trustGateResultShape,
+        verdict: z.enum(["pass", "unknown"]),
+        first_divergence: z.null(),
+    }),
+    z.strictObject({
+        ...trustGateResultShape,
+        verdict: z.literal("fail"),
+        first_divergence: divergenceSchema.nullable(),
+    }),
+]);
 /** Dimension that is volatile due to timing or normalization. */
 const VOLATILE_DIMENSIONS = new Set([
     "timing",
@@ -35,11 +44,130 @@ const SEMANTIC_DIMENSIONS = new Set([
     "stdout",
     "stderr",
     "filesystem",
+    "process",
     "process_tree",
     "shim_events",
     "protocol_events",
     "event_journal",
 ]);
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const uniqueStrings = (values) => [
+    ...new Set(values.filter((value) => value.length > 0)),
+];
+const stringValues = (value) => {
+    if (typeof value === "string")
+        return value.length > 0 ? [value] : [];
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((item) => typeof item === "string" && item.length > 0);
+};
+const evidenceIds = (record) => uniqueStrings([
+    ...stringValues(record["evidence_id"]),
+    ...stringValues(record["evidence_ids"]),
+    ...stringValues(record["evidence_links"]),
+]);
+const incompleteStatus = (value) => {
+    if (!isRecord(value))
+        return null;
+    const record = value;
+    if (record["truncated"] === true)
+        return "truncated";
+    const status = record["status"];
+    if (status === "truncated")
+        return "truncated";
+    if (status === "unknown" ||
+        status === "unavailable" ||
+        status === "partial" ||
+        status === "incomplete" ||
+        status === "unverifiable" ||
+        status === "failed" ||
+        status === "not_approved")
+        return "unknown";
+    for (const key of ["coverage", "completeness"]) {
+        const nested = record[key];
+        if (!isRecord(nested))
+            continue;
+        const nestedStatus = incompleteStatus(nested);
+        if (nestedStatus !== null)
+            return nestedStatus;
+    }
+    return null;
+};
+const hasResidualUnknowns = (value) => isRecord(value) &&
+    Array.isArray(value["residual_unknowns"]) &&
+    value["residual_unknowns"].length > 0;
+const unknownScopes = (record) => {
+    const residualUnknowns = record["residual_unknowns"];
+    if (!Array.isArray(residualUnknowns))
+        return [];
+    return residualUnknowns.flatMap((item) => {
+        if (!isRecord(item) || typeof item["scope"] !== "string")
+            return [];
+        return [item["scope"]];
+    });
+};
+const evidenceView = (input) => {
+    if (!isRecord(input))
+        return {
+            values: {},
+            evidence_ids: [],
+            status: null,
+            unknown_scopes: [],
+        };
+    const normalized = input["normalized_result"];
+    const values = isRecord(normalized) ? normalized : input;
+    const normalizedStatus = isRecord(normalized)
+        ? incompleteStatus(normalized)
+        : null;
+    return {
+        values,
+        evidence_ids: evidenceIds(input),
+        status: incompleteStatus(input) ?? normalizedStatus,
+        unknown_scopes: uniqueStrings([
+            ...unknownScopes(input),
+            ...(isRecord(normalized) ? unknownScopes(normalized) : []),
+        ]),
+    };
+};
+const dimensionScope = (dimensionName) => {
+    if (dimensionName === "exit_code" || dimensionName === "exit")
+        return "exit";
+    if (dimensionName === "process" ||
+        dimensionName === "process_tree" ||
+        dimensionName === "event_journal")
+        return "process";
+    if (dimensionName === "stdout" || dimensionName === "stderr")
+        return "terminal";
+    if (dimensionName === "filesystem")
+        return "filesystem";
+    if (dimensionName === "shim_events")
+        return "shim";
+    if (dimensionName === "protocol_events")
+        return "protocol";
+    return null;
+};
+const statusForDimension = (view, dimensionName) => {
+    const valueStatus = incompleteStatus(view.values[dimensionName]);
+    if (valueStatus !== null)
+        return valueStatus;
+    if (hasResidualUnknowns(view.values[dimensionName]))
+        return "unknown";
+    const scope = dimensionScope(dimensionName);
+    return scope !== null && view.unknown_scopes.includes(scope)
+        ? "unknown"
+        : view.status;
+};
+const comparisonIncompleteStatus = (expected, actual, options) => {
+    const expectedStatus = options.expected_status ?? incompleteStatus(expected);
+    const actualStatus = options.actual_status ?? incompleteStatus(actual);
+    if (options.truncated)
+        return "truncated";
+    if (expectedStatus === "truncated" || actualStatus === "truncated")
+        return "truncated";
+    if (expectedStatus === "unknown" || actualStatus === "unknown")
+        return "unknown";
+    return null;
+};
 /** Check if a dimension name is volatile (timing/normalization noise). */
 export function isVolatileDimension(name) {
     return VOLATILE_DIMENSIONS.has(name);
@@ -63,15 +191,19 @@ export function compareDimension(dimensionName, expected, actual, options = {})
             name: dimensionName,
             status: "match",
             message: "volatile dimension ignored",
-            evidence_ids: [],
+            evidence_ids: uniqueStrings(options.evidence_ids ?? []),
         };
     }
-    if (options.truncated) {
+    const status = comparisonIncompleteStatus(expected, actual, options);
+    const resultEvidenceIds = uniqueStrings(options.evidence_ids ?? []);
+    if (status !== null) {
         return {
             name: dimensionName,
-            status: "truncated",
-            message: "evidence was truncated",
-            evidence_ids: [],
+            status,
+            message: status === "truncated"
+                ? "evidence was truncated"
+                : "evidence completeness is unknown",
+            evidence_ids: resultEvidenceIds,
         };
     }
     if (expected === undefined && actual === undefined) {
@@ -79,15 +211,15 @@ export function compareDimension(dimensionName, expected, actual, options = {})
             name: dimensionName,
             status: "unknown",
             message: "both expected and actual are undefined",
-            evidence_ids: [],
+            evidence_ids: resultEvidenceIds,
         };
     }
     if (expected === undefined || actual === undefined) {
         return {
             name: dimensionName,
-            status: "mismatch",
-            message: `expected ${expected === undefined ? "present" : "absent"}, actual ${actual === undefined ? "absent" : "present"}`,
-            evidence_ids: [],
+            status: "unknown",
+            message: "one side has no observed value",
+            evidence_ids: resultEvidenceIds,
         };
     }
     // Semantic comparison for structured objects
@@ -99,14 +231,14 @@ export function compareDimension(dimensionName, expected, actual, options = {})
                 name: dimensionName,
                 status: "match",
                 message: "",
-                evidence_ids: [],
+                evidence_ids: resultEvidenceIds,
             };
         }
         return {
             name: dimensionName,
             status: "mismatch",
             message: "semantic content differs",
-            evidence_ids: [],
+            evidence_ids: resultEvidenceIds,
         };
     }
     // Primitive comparison
@@ -115,14 +247,14 @@ export function compareDimension(dimensionName, expected, actual, options = {})
             name: dimensionName,
             status: "match",
             message: "",
-            evidence_ids: [],
+            evidence_ids: resultEvidenceIds,
         };
     }
     return {
         name: dimensionName,
         status: "mismatch",
         message: `expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`,
-        evidence_ids: [],
+        evidence_ids: resultEvidenceIds,
     };
 }
 /** Recursively sort object keys for deterministic comparison. */
@@ -131,6 +263,8 @@ function sortKeys(value) {
         return value;
     if (Array.isArray(value))
         return value.map(sortKeys);
+    if (!isRecord(value))
+        return value;
     const sorted = {};
     for (const key of Object.keys(value).sort()) {
         sorted[key] = sortKeys(value[key]);
@@ -144,12 +278,22 @@ function sortKeys(value) {
 export function evaluateTrustGate(contract, expectedEvidence, actualEvidence, options = {}) {
     const dimensionResults = [];
     let firstDivergence = null;
+    const expectedView = evidenceView(expectedEvidence);
+    const actualView = evidenceView(actualEvidence);
     for (const dim of contract.dimensions) {
         if (!dim.required)
             continue;
-        const expectedValue = expectedEvidence[dim.name];
-        const actualValue = actualEvidence[dim.name];
-        const result = compareDimension(dim.name, expectedValue, actualValue, options);
+        const expectedValue = expectedView.values[dim.name];
+        const actualValue = actualView.values[dim.name];
+        const result = compareDimension(dim.name, expectedValue, actualValue, {
+            ...options,
+            expected_status: statusForDimension(expectedView, dim.name),
+            actual_status: statusForDimension(actualView, dim.name),
+            evidence_ids: uniqueStrings([
+                ...actualView.evidence_ids,
+                ...expectedView.evidence_ids,
+            ]),
+        });
         dimensionResults.push(result);
         if (result.status === "mismatch" && firstDivergence === null) {
             firstDivergence = {
@@ -166,12 +310,12 @@ export function evaluateTrustGate(contract, expectedEvidence, actualEvidence, op
         : hasUnknown
             ? "unknown"
             : "pass";
-    return {
+    return trustGateResultSchema.parse({
         scenario_id: contract.scenario_id,
         verdict,
         dimension_results: dimensionResults,
         first_divergence: firstDivergence,
-    };
+    });
 }
 /**
  * Evaluate trust gates for all scenarios in a conformance package.
@@ -182,8 +326,8 @@ export function evaluatePackageTrustGates(pkg, actualEvidence, options = {}) {
     const results = [];
     for (const contract of pkg.verifier_contracts) {
         const expected = pkg.expected_evidence.find((e) => e.scenario_id === contract.scenario_id);
-        if (!expected)
-            continue;
+        if (expected === undefined)
+            throw new TypeError(`Parsed conformance package is missing expected evidence for ${contract.scenario_id}`);
         const expectedEvidence = expected.envelopes[0] ?? {};
         const actual = actualEvidence[contract.scenario_id] ?? {};
         const result = evaluateTrustGate(contract, expectedEvidence, actual, options);

package/dist/domain/customProtocolCapture.js

@@ -85,7 +85,7 @@ export const customProtocolCaptureSchema = z.strictObject({
     /** Transport type for this session. */
     transport: transportTypeSchema,
     /** Captured frames in order. */
-    frames: z.array(protocolFrameSchema).min(0).max(100_000),
+    frames: z.array(protocolFrameSchema),
     /** Authentication flow events. */
     auth_events: z.array(authFlowEventSchema).default([]),
     /** Whether any frame was truncated. */
@@ -129,9 +129,9 @@ export function failedAuthEvents(events) {
 }
 /** Compute the duration of an authentication flow in milliseconds. */
 export function authFlowDuration(events) {
-    if (events.length === 0)
+    const first = events.at(0);
+    const last = events.at(-1);
+    if (first === undefined || last === undefined)
         return null;
-    const first = events[0];
-    const last = events[events.length - 1];
     return last.at_ms - first.at_ms;
 }

package/dist/domain/electronActiveObservation.js

@@ -0,0 +1,244 @@
+import { isAbsolute } from "node:path";
+import { z } from "zod";
+const absolutePathSchema = z
+    .string()
+    .min(1)
+    .refine(isAbsolute, "path must be absolute");
+const windowIndexSchema = z.number().int().min(0);
+const deepLinkUrlSchema = z
+    .string()
+    .min(1)
+    .refine((value) => {
+    try {
+        return new URL(value).protocol.length > 0;
+    }
+    catch {
+        return false;
+    }
+}, "deep-link url must be an absolute URL");
+const actionSchema = z.discriminatedUnion("kind", [
+    z.strictObject({
+        step_id: z.string().min(1),
+        kind: z.literal("click"),
+        selector: z.string().min(1),
+        window_index: windowIndexSchema.default(0),
+    }),
+    z.strictObject({
+        step_id: z.string().min(1),
+        kind: z.literal("wait"),
+        duration_ms: z.number().int().min(0),
+        window_index: windowIndexSchema.optional(),
+    }),
+    z.strictObject({
+        step_id: z.string().min(1),
+        kind: z.literal("renderer-reload"),
+        window_index: windowIndexSchema.default(0),
+    }),
+    z.strictObject({
+        step_id: z.string().min(1),
+        kind: z.literal("renderer-crash"),
+        window_index: windowIndexSchema.default(0),
+    }),
+    z.strictObject({
+        step_id: z.string().min(1),
+        kind: z.literal("deep-link"),
+        delivery: z.enum(["open-url", "second-instance"]),
+        url: deepLinkUrlSchema,
+    }),
+]);
+/** Input for one explicit, provider-owned Electron runtime experiment. */
+export const electronActiveObservationInputSchema = z.strictObject({
+    executable_path: absolutePathSchema,
+    application_path: absolutePathSchema,
+    application_root: absolutePathSchema,
+    args: z.array(z.string()).default([]),
+    actions: z.array(actionSchema).default([]),
+});
+const ipcEventSchema = z.strictObject({
+    sequence: z.number().int().min(1),
+    correlation_id: z.string().nullable().default(null),
+    kind: z.enum([
+        "main-handler-invocation",
+        "main-event-invocation",
+        "utility-process-fork",
+        "utility-process-message",
+        "ipc-main-to-renderer",
+        "ipc-utility-to-main",
+        "ipc-renderer-send",
+        "ipc-renderer-invoke",
+        "ipc-renderer-post-message",
+    ]),
+    event: z.string().nullable().optional(),
+    phase: z
+        .enum(["attempted", "completed", "blocked", "failed", "observed"])
+        .nullable()
+        .optional(),
+    channel: z.string().nullable(),
+    direction: z
+        .enum([
+        "renderer-to-main",
+        "main-to-renderer",
+        "main-to-utility",
+        "utility-to-main",
+    ])
+        .nullable()
+        .optional(),
+    sender: z.string().nullable().optional(),
+    receiver: z.string().nullable().optional(),
+    frame: z.string().nullable().default(null),
+    target: z.string().nullable().optional(),
+    argument_shapes: z.array(z.string()),
+    result_shape: z.string().nullable(),
+    process_type: z.string().nullable(),
+    source: z.string().default("electron-active-hook"),
+    capture_method: z
+        .enum(["api-wrapper", "event-emitter", "process-hook"])
+        .default("api-wrapper"),
+    artifact_path: z.string().nullable().default(null),
+    artifact_sha256: z
+        .string()
+        .regex(/^[a-f0-9]{64}$/u)
+        .nullable()
+        .default(null),
+    error: z.boolean(),
+});
+const timelineEventSchema = z.strictObject({
+    sequence: z.number().int().min(1),
+    correlation_id: z.string().nullable().default(null),
+    kind: z.enum([
+        "main-handler-invocation",
+        "main-event-invocation",
+        "utility-process-fork",
+        "utility-process-message",
+        "ipc-main-to-renderer",
+        "ipc-utility-to-main",
+        "ipc-renderer-send",
+        "ipc-renderer-invoke",
+        "ipc-renderer-post-message",
+        "app-lifecycle",
+        "window-lifecycle",
+        "web-contents-lifecycle",
+        "navigation",
+        "shell-attempt",
+        "process-lifecycle",
+        "permission",
+        "popup-attempt",
+        "download",
+        "protocol",
+        "preload",
+        "native-addon",
+        "updater",
+        "error",
+    ]),
+    event: z.string().nullable(),
+    phase: z.enum(["attempted", "completed", "blocked", "failed", "observed"]),
+    channel: z.string().nullable(),
+    direction: z
+        .enum([
+        "renderer-to-main",
+        "main-to-renderer",
+        "main-to-utility",
+        "utility-to-main",
+    ])
+        .nullable(),
+    sender: z.string().nullable(),
+    receiver: z.string().nullable(),
+    frame: z.string().nullable(),
+    target: z.string().nullable(),
+    argument_shapes: z.array(z.string()),
+    result_shape: z.string().nullable(),
+    process_type: z.string().nullable(),
+    source: z.string(),
+    capture_method: z.enum(["api-wrapper", "event-emitter", "process-hook"]),
+    artifact_path: z.string().nullable(),
+    artifact_sha256: z
+        .string()
+        .regex(/^[a-f0-9]{64}$/u)
+        .nullable(),
+    error: z.boolean(),
+});
+const processMetricSchema = z.strictObject({
+    pid: z.number().int().min(1),
+    type: z.string().min(1),
+    name: z.string().nullable(),
+    service_name: z.string().nullable(),
+});
+const windowResultSchema = z.strictObject({
+    window_id: z.string(),
+    web_contents_id: z.string(),
+    url: z.string(),
+    title: z.string(),
+    visible: z.boolean().nullable(),
+    destroyed: z.boolean(),
+});
+const coverageSchema = z.strictObject({
+    status: z.enum([
+        "complete",
+        "partial_attach",
+        "hook_conflict",
+        "target_exited",
+        "cleanup_failed",
+    ]),
+    observed_event_families: z.array(z.string()),
+    unavailable_event_families: z.array(z.string()),
+    observed_roles: z.array(z.string()),
+    pre_capture_activity: z.literal("unavailable"),
+});
+const actionResultContextShape = {
+    step_id: z.string().min(1),
+    kind: z.enum([
+        "click",
+        "wait",
+        "renderer-reload",
+        "renderer-crash",
+        "deep-link",
+    ]),
+    window_index: windowIndexSchema.nullable(),
+    target: z.string().nullable(),
+    elapsed_ms: z.number().int().min(0),
+};
+const actionResultSchema = z.discriminatedUnion("status", [
+    z.strictObject({
+        ...actionResultContextShape,
+        status: z.literal("completed"),
+        error: z.null(),
+    }),
+    z.strictObject({
+        ...actionResultContextShape,
+        status: z.enum(["failed", "cancelled"]),
+        error: z.string(),
+    }),
+]);
+/** Result of a provider-owned Electron runtime experiment. */
+export const electronActiveObservationResultSchema = z.strictObject({
+    application: z.strictObject({
+        executable_path: absolutePathSchema,
+        application_path: absolutePathSchema,
+        electron_version: z.string().min(1),
+        process_ownership: z.literal("provider-owned"),
+        cleanup: z.literal("terminated-owned-process"),
+    }),
+    actions: z.array(actionResultSchema),
+    windows: z.array(windowResultSchema),
+    processes: z.strictObject({
+        items: z.array(processMetricSchema),
+    }),
+    ipc: z.strictObject({
+        events: z.array(ipcEventSchema),
+        observed: z.number().int().min(0),
+    }),
+    timeline: z
+        .strictObject({
+        events: z.array(timelineEventSchema),
+        observed: z.number().int().min(0),
+    })
+        .default({ events: [], observed: 0 }),
+    coverage: coverageSchema.default({
+        status: "partial_attach",
+        observed_event_families: [],
+        unavailable_event_families: [],
+        observed_roles: [],
+        pre_capture_activity: "unavailable",
+    }),
+    limitations: z.array(z.string()),
+});