rea-agents 2.2.0 → 2.3.0

package/dist/domain/reconstructionVerification.js

@@ -18,23 +18,24 @@ const MAX_CANONICAL_BYTES = 32 * 1024 * 1024;
 const providers = {
     behavioral: {
         operation: "compare_process_captures",
-        predicate: "rea.process-comparison/v3",
+        predicates: ["rea.process-comparison/v3", "rea.process-comparison/v4"],
         id: "rea-process",
         name: "REA deterministic process harness",
     },
     "structural-function": {
         operation: "compare_functions",
-        predicate: "rea.function-comparison/v1",
+        predicates: ["rea.function-comparison/v1"],
         id: "rea-function-comparison",
         name: "REA function comparison",
     },
     "structural-artifact": {
         operation: "compare_artifacts",
-        predicate: "rea.artifact-comparison/v1",
+        predicates: ["rea.artifact-comparison/v1"],
         id: "rea-artifact-comparison",
         name: "REA artifact comparison",
     },
 };
+const acceptsPredicate = (expected, actual) => expected.some((predicate) => predicate === actual);
 /** Verify only explicitly declared claims; no global equivalence is inferred. */
 export const verifyReconstruction = (specificationInput, bundleInput, offset, limit) => {
     const specification = reconstructionSpecificationSchema.parse(specificationInput);
@@ -157,7 +158,7 @@ const validateComparisonIdentity = (claim, evidence) => {
     parseEvidence(evidence);
     const expected = providers[claim.kind];
     if (evidence.operation !== expected.operation ||
-        evidence.predicate_type !== expected.predicate ||
+        !acceptsPredicate(expected.predicates, evidence.predicate_type) ||
         evidence.provider.id !== expected.id ||
         evidence.provider.name !== expected.name ||
         evidence.provider.version !== (claim.kind === "behavioral" ? "3" : "1") ||

package/dist/domain/replayMachine.js

@@ -14,8 +14,17 @@ const sensitiveHeaderNames = new Set([
     "proxy-authorization",
     "set-cookie",
 ]);
+const headerNameSchema = z
+    .string()
+    .min(1)
+    .max(256)
+    .regex(/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/u);
+const headerValueSchema = z
+    .string()
+    .max(8_192)
+    .regex(/^[\t\x20-\x7e\x80-\xff]*$/u);
 const replayHeaderMatchersSchema = z
-    .record(z.string().min(1).max(256), z.string().max(8_192))
+    .record(headerNameSchema, headerValueSchema)
     .superRefine((headers, context) => {
     const names = Object.keys(headers).map((name) => name.toLowerCase());
     if (new Set(names).size !== names.length)
@@ -77,7 +86,7 @@ const replayActionSchema = z.discriminatedUnion("type", [
     z.strictObject({
         type: z.literal("http_response"),
         status: z.number().int().min(100).max(599),
-        headers: z.record(z.string(), z.string()).default({}),
+        headers: z.record(headerNameSchema, headerValueSchema).default({}),
         body: z.string().max(1_000_000),
     }),
     z.strictObject({
@@ -189,6 +198,13 @@ const validateReplayVariables = (machine, context) => {
     const capturedVariables = new Map();
     for (const [transitionIndex, transition] of machine.transitions.entries()) {
         for (const capture of transition.captures) {
+            if (capture.sensitive && capture.value.source === "action_json")
+                context.addIssue({
+                    code: "custom",
+                    message: "sensitive replay captures cannot read literal action JSON persisted in the replay plan",
+                    path: ["transitions", transitionIndex, "captures"],
+                    input: machine,
+                });
             const sensitivity = capturedVariables.get(capture.variable);
             if (sensitivity !== undefined && sensitivity !== capture.sensitive)
                 context.addIssue({

package/dist/domain/replayMachineRun.js

@@ -0,0 +1,216 @@
+import { z } from "zod";
+import { replayMachineSchema } from "./replayMachine.js";
+import { replayMachineEventSchema, ReplayMachineRuntime, } from "./replayMachineRuntime.js";
+const refusalOutcomeSchema = z.enum([
+    "unmatched",
+    "invalid_state",
+    "guard_failed",
+    "transition_exhausted",
+    "invalid_capture",
+    "unexpected_reconnect",
+    "limit_exhausted",
+]);
+const MAX_DIRECT_REPLAY_EVENTS = 10_000;
+const MAX_DIRECT_REPLAY_ACTION_BYTES = 4 * 1_024 * 1_024;
+const MAX_DIRECT_REPLAY_ACTION_FIELDS = 1_024;
+const MAX_DIRECT_REPLAY_SENSITIVE_CAPTURES = 1_024;
+const actionFieldCount = (machine) => machine.transitions.reduce((total, transition) => total +
+    transition.actions.reduce((fields, action) => fields +
+        (action.type === "http_response"
+            ? Object.keys(action.headers).length + 1
+            : action.type === "websocket_send"
+                ? 1
+                : 0), 0), 0);
+const maximumSensitiveCapturesPerEvent = (machine) => Math.max(0, ...machine.transitions.map(({ captures }) => captures.filter(({ sensitive }) => sensitive).length));
+/** Complete declarative input for one direct replay-machine run. */
+export const replayMachineRunInputSchema = z
+    .strictObject({
+    machine: replayMachineSchema,
+    events: z.array(replayMachineEventSchema).max(MAX_DIRECT_REPLAY_EVENTS),
+})
+    .superRefine(({ machine, events }, context) => {
+    const actionBytes = Buffer.byteLength(JSON.stringify(machine.transitions.map(({ id, actions }) => ({ id, actions }))));
+    if (actionBytes > MAX_DIRECT_REPLAY_ACTION_BYTES)
+        context.addIssue({
+            code: "custom",
+            path: ["machine", "transitions"],
+            message: "direct replay actions exceed the 4 MiB output boundary",
+            input: machine.transitions,
+        });
+    if (actionFieldCount(machine) > MAX_DIRECT_REPLAY_ACTION_FIELDS)
+        context.addIssue({
+            code: "custom",
+            path: ["machine", "transitions"],
+            message: "direct replay actions exceed the 1,024-field output boundary",
+            input: machine.transitions,
+        });
+    if (maximumSensitiveCapturesPerEvent(machine) * events.length >
+        MAX_DIRECT_REPLAY_SENSITIVE_CAPTURES)
+        context.addIssue({
+            code: "custom",
+            path: ["events"],
+            message: "direct replay events exceed the 1,024 sensitive-capture operation boundary",
+            input: events,
+        });
+});
+const replayMachineRunDecisionSchema = z.strictObject({
+    event_sequence: z.number().int().nonnegative(),
+    outcome: z.union([z.literal("matched"), refusalOutcomeSchema]),
+    transition_sequence: z.number().int().nonnegative().nullable(),
+});
+const replayRunActionSchema = z.discriminatedUnion("type", [
+    z.strictObject({
+        type: z.literal("http_response"),
+        status: z.number().int().min(100).max(599),
+        headers: z.record(z
+            .string()
+            .min(1)
+            .max(256)
+            .regex(/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/u), z.string().max(8_192)),
+        body: z.string().max(1_000_000),
+    }),
+    z.strictObject({
+        type: z.literal("websocket_send"),
+        data: z.string().max(1_000_000),
+    }),
+    z.strictObject({ type: z.literal("disconnect") }),
+    z.strictObject({
+        type: z.literal("delay"),
+        duration_ms: z.number().int().nonnegative().max(30_000),
+    }),
+]);
+const replayRunIdentifierSchema = z
+    .string()
+    .regex(/^[A-Za-z][A-Za-z0-9_-]{0,63}$/u);
+const replayMachineRunJournalEntrySchema = z.strictObject({
+    sequence: z.number().int().nonnegative(),
+    at_ms: z.number().int().nonnegative(),
+    transition_id: replayRunIdentifierSchema,
+    state_before: replayRunIdentifierSchema,
+    state_after: replayRunIdentifierSchema,
+    captured_aliases: z
+        .array(z.strictObject({
+        name: replayRunIdentifierSchema,
+        sensitive: z.boolean(),
+    }))
+        .max(32),
+});
+/** Capture-value-free result of directly evaluating a finite replay machine. */
+export const replayMachineRunOutputSchema = z.strictObject({
+    schema_version: z.literal(1),
+    initial_state: replayRunIdentifierSchema,
+    final_state: replayRunIdentifierSchema,
+    terminal: z.boolean(),
+    decisions: z
+        .array(replayMachineRunDecisionSchema)
+        .max(MAX_DIRECT_REPLAY_EVENTS),
+    transition_journal: z
+        .array(replayMachineRunJournalEntrySchema)
+        .max(MAX_DIRECT_REPLAY_EVENTS),
+    transition_actions: z
+        .array(z.strictObject({
+        transition_id: replayRunIdentifierSchema,
+        actions: z.array(replayRunActionSchema).max(32),
+    }))
+        .max(2_000),
+    limits: z.strictObject({
+        configured: z.strictObject({
+            transitions: z.number().int().positive(),
+            connections: z.number().int().positive(),
+            messages: z.number().int().positive(),
+            bytes: z.number().int().positive(),
+            duration_ms: z.number().int().positive(),
+        }),
+        usage: z.strictObject({
+            offered_events: z.number().int().nonnegative(),
+            admitted_events: z.number().int().nonnegative(),
+            transitions: z.number().int().nonnegative(),
+            connections: z.number().int().nonnegative(),
+            messages: z.number().int().nonnegative(),
+            bytes: z.number().int().nonnegative(),
+            last_at_ms: z.number().int().nonnegative(),
+        }),
+    }),
+});
+const redactAction = (runtime, action) => {
+    switch (action.type) {
+        case "http_response":
+            return {
+                ...action,
+                headers: Object.fromEntries(Object.entries(action.headers).map(([name, value]) => [
+                    name,
+                    runtime.redactField(value),
+                ])),
+                body: runtime.redactField(action.body),
+            };
+        case "websocket_send":
+            return { ...action, data: runtime.redactField(action.data) };
+        case "delay":
+        case "disconnect":
+            return action;
+    }
+};
+/** Evaluate every supplied event in order without opening sockets or processes. */
+export const runReplayMachine = (input) => {
+    const runtime = new ReplayMachineRuntime(input.machine);
+    const decisions = [];
+    const transitionJournal = [];
+    const usedTransitionIds = new Set();
+    for (const [eventSequence, event] of input.events.entries()) {
+        const decision = runtime.dispatch(event);
+        decisions.push({
+            event_sequence: eventSequence,
+            outcome: decision.outcome,
+            transition_sequence: decision.transition?.sequence ?? null,
+        });
+        if (decision.outcome !== "matched")
+            continue;
+        usedTransitionIds.add(decision.transition.transition_id);
+        const definition = input.machine.transitions.find(({ id }) => id === decision.transition.transition_id);
+        if (definition === undefined)
+            throw new TypeError("Replay runtime selected an unknown transition");
+        transitionJournal.push({
+            sequence: decision.transition.sequence,
+            at_ms: decision.transition.at_ms,
+            transition_id: decision.transition.transition_id,
+            state_before: decision.transition.state_before,
+            state_after: decision.transition.state_after,
+            captured_aliases: definition.captures.map(({ variable, sensitive }) => ({
+                name: variable,
+                sensitive,
+            })),
+        });
+    }
+    const usage = runtime.usage;
+    const transitionActions = input.machine.transitions
+        .filter(({ id }) => usedTransitionIds.has(id))
+        .map(({ id, actions }) => ({
+        transition_id: id,
+        actions: actions.map((action) => redactAction(runtime, action)),
+    }));
+    return replayMachineRunOutputSchema.parse({
+        schema_version: 1,
+        initial_state: input.machine.initial_state,
+        final_state: runtime.state,
+        terminal: input.machine.states.find(({ name }) => name === runtime.state)
+            ?.terminal ?? false,
+        decisions,
+        transition_journal: transitionJournal,
+        transition_actions: transitionActions,
+        limits: {
+            configured: {
+                transitions: input.machine.max_transitions,
+                ...input.machine.limits,
+            },
+            usage: {
+                offered_events: input.events.length,
+                admitted_events: usage.events,
+                transitions: usage.transitions,
+                connections: usage.connections,
+                messages: usage.messages,
+                bytes: usage.bytes,
+                last_at_ms: usage.last_at_ms,
+            },
+        },
+    });
+};

package/dist/domain/replayMachineRuntime.js

@@ -1,4 +1,54 @@
 import canonicalize from "canonicalize";
+import { z } from "zod";
+/** One bounded inbound protocol event offered to a replay machine. */
+const replayEventHeadersSchema = z
+    .record(z
+    .string()
+    .min(1)
+    .max(256)
+    .regex(/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/u), z
+    .string()
+    .max(8_192)
+    .regex(/^[\t\x20-\x7e\x80-\xff]*$/u))
+    .superRefine((headers, context) => {
+    const normalized = Object.keys(headers).map((name) => name.toLowerCase());
+    if (new Set(normalized).size !== normalized.length)
+        context.addIssue({
+            code: "custom",
+            message: "replay event headers must be unique ignoring case",
+            input: headers,
+        });
+});
+const replayEventFields = {
+    at_ms: z.number().int().nonnegative().safe(),
+    path: z.string().startsWith("/").max(8_192),
+    headers: replayEventHeadersSchema,
+    body: z.string().max(1_000_000),
+};
+export const replayMachineEventSchema = z.discriminatedUnion("protocol", [
+    z.strictObject({
+        protocol: z.literal("http"),
+        connection: z.literal("not_applicable"),
+        method: z
+            .string()
+            .min(1)
+            .max(16)
+            .transform((method) => method.toUpperCase()),
+        ...replayEventFields,
+    }),
+    z.strictObject({
+        protocol: z.literal("websocket_connect"),
+        connection: z.enum(["initial", "reconnect"]),
+        method: z.null(),
+        ...replayEventFields,
+    }),
+    z.strictObject({
+        protocol: z.literal("websocket_message"),
+        connection: z.enum(["initial", "reconnect"]),
+        method: z.null(),
+        ...replayEventFields,
+    }),
+]);
 const parseJson = (value) => {
     try {
         return JSON.parse(value);
@@ -76,6 +126,17 @@ const isJsonCompatible = (value) => {
 const replayValuesEqual = (left, right) => isJsonCompatible(left) &&
     isJsonCompatible(right) &&
     (Object.is(left, right) || canonicalize(left) === canonicalize(right));
+const createTransitionRecord = ({ sequence, atMs, stateBefore, transition, captures, }) => ({
+    sequence,
+    at_ms: atMs,
+    transition_id: transition.id,
+    state_before: stateBefore,
+    state_after: transition.to,
+    sensitive_aliases: captures
+        .filter(({ sensitive }) => sensitive)
+        .map(({ variable }) => variable)
+        .sort(),
+});
 /** Stateful evaluator for one validated replay-machine instance. */
 export class ReplayMachineRuntime {
     machine;
@@ -89,6 +150,7 @@ export class ReplayMachineRuntime {
     #messages = 0;
     #bytes = 0;
     #lastAtMs = 0;
+    #events = 0;
     constructor(machine) {
         this.machine = machine;
         this.#state = machine.initial_state;
@@ -102,6 +164,17 @@ export class ReplayMachineRuntime {
     get timeline() {
         return this.#timeline;
     }
+    /** Current committed use of the machine's declared limits. */
+    get usage() {
+        return {
+            events: this.#events,
+            transitions: this.#timeline.length,
+            connections: this.#connections,
+            messages: this.#messages,
+            bytes: this.#bytes,
+            last_at_ms: this.#lastAtMs,
+        };
+    }
     /** Replace captured secret values with stable aliases before persistence. */
     redact(value) {
         let redacted = value;
@@ -113,6 +186,14 @@ export class ReplayMachineRuntime {
             redacted = redacted.replaceAll(secret, `<secret:${variable}>`);
         return redacted;
     }
+    /** Replace a field containing captured secrets with one stable alias only. */
+    redactField(value) {
+        const alias = [...this.#sensitiveValues]
+            .filter(([, values]) => [...values].some((secret) => value.includes(secret)))
+            .map(([variable]) => variable)
+            .sort()[0];
+        return alias === undefined ? value : `<secret:${alias}>`;
+    }
     /** Evaluate and, when admitted, commit one protocol event. */
     dispatch(event) {
         const normalizedEvent = {
@@ -172,16 +253,13 @@ export class ReplayMachineRuntime {
                 this.#sensitiveValues.set(capture.variable, values);
             }
         }
-        const record = {
+        const record = createTransitionRecord({
             sequence: this.#timeline.length,
-            transition_id: transition.id,
-            state_before: this.#state,
-            state_after: transition.to,
-            sensitive_aliases: captures
-                .filter(({ sensitive }) => sensitive)
-                .map(({ variable }) => variable)
-                .sort(),
-        };
+            atMs: normalizedEvent.recorded_at_ms ?? normalizedEvent.at_ms,
+            stateBefore: this.#state,
+            transition,
+            captures,
+        });
         this.#uses.set(transition.id, used + 1);
         this.#stateVisits.set(transition.to, nextVisits);
         this.#state = transition.to;
@@ -207,6 +285,7 @@ export class ReplayMachineRuntime {
         this.#messages = messages;
         this.#bytes = bytes;
         this.#lastAtMs = event.at_ms;
+        this.#events += 1;
         return true;
     }
     #refusal(outcome) {

package/dist/domain/staticRuntimeCorrelation.js

@@ -140,7 +140,7 @@ const EXPECTED = {
         "REA function comparison",
     ],
     compare_process_captures: [
-        "rea.process-comparison/v3",
+        ["rea.process-comparison/v3", "rea.process-comparison/v4"],
         "rea-process",
         "REA deterministic process harness",
     ],
@@ -302,7 +302,9 @@ const parseRuntime = (input) => {
 const assertComparisonIdentity = (evidence) => {
     const expected = EXPECTED[evidence.operation];
     if (expected === undefined ||
-        evidence.predicate_type !== expected[0] ||
+        !(Array.isArray(expected[0])
+            ? expected[0].includes(evidence.predicate_type)
+            : evidence.predicate_type === expected[0]) ||
         evidence.provider.id !== expected[1] ||
         evidence.provider.name !== expected[2] ||
         evidence.provider.version !==

package/dist/evaluation/CodexAgentEval.js

@@ -26,6 +26,12 @@ const toolResultFailed = (item) => {
     const structured = record(result?.structured_content ?? result?.structuredContent);
     return result?.isError === true || structured?.error !== undefined;
 };
+const toolResultErrorCode = (item) => {
+    const result = record(item.result ?? item.output);
+    const structured = record(result?.structured_content ?? result?.structuredContent);
+    const error = record(structured?.error ?? result?.error ?? item.error);
+    return textValue(error?.code) ?? null;
+};
 const callFromItem = (value) => {
     const item = record(value);
     if (item?.type !== "mcp_tool_call")
@@ -40,6 +46,7 @@ const callFromItem = (value) => {
         arguments: item.arguments ?? item.input ?? {},
         evidenceIds: evidenceIdsFrom(item.result ?? item.output),
         error: toolResultFailed(item),
+        errorCode: toolResultErrorCode(item),
     };
 };
 const agentTextFromItem = (value) => {
@@ -102,6 +109,8 @@ export const evaluateCodexEvents = (events, expectedFirstTool, options = {}) =>
         signatures.set(signature, (signatures.get(signature) ?? 0) + 1);
     }
     const repeatedCallCount = [...signatures.values()].reduce((total, count) => total + Math.max(0, count - 1), 0);
+    const inputValidationFailureCount = reaCalls.filter(({ errorCode }) => errorCode === "invalid_request").length;
+    const requiredToolSubsequenceMet = containsOrderedSubsequence(reaCalls.filter(({ error }) => !error).map(({ tool }) => tool), options.requiredToolSubsequence ?? []);
     const finalMessage = state.finalMessages.at(-1) ?? "";
     const evidenceIds = [
         ...new Set(reaCalls.flatMap(({ evidenceIds: ids }) => ids)),
@@ -116,6 +125,8 @@ export const evaluateCodexEvents = (events, expectedFirstTool, options = {}) =>
         firstTool: reaCalls[0]?.tool ?? null,
         reaCalls,
         repeatedCallCount,
+        inputValidationFailureCount,
+        requiredToolSubsequenceMet,
         inputTokens: state.inputTokens,
         cachedInputTokens: state.cachedInputTokens,
         outputTokens: state.outputTokens,
@@ -126,7 +137,20 @@ export const evaluateCodexEvents = (events, expectedFirstTool, options = {}) =>
         completionQuality: finalMessage.trim().length >= 80 &&
             authorityHonesty &&
             contentCriteriaMet &&
+            requiredToolSubsequenceMet &&
+            (options.forbidInputValidationFailures !== true ||
+                inputValidationFailureCount === 0) &&
             (options.requireEvidence !== true || finalCitesEvidence),
         authorityHonesty,
     };
 };
+const containsOrderedSubsequence = (values, required) => {
+    let index = 0;
+    for (const value of values) {
+        if (value === required[index])
+            index += 1;
+        if (index === required.length)
+            return true;
+    }
+    return required.length === 0;
+};

package/dist/generatedPackageMetadata.js

@@ -1,7 +1,7 @@
 /** Generated from package.json and package-lock.json; do not edit. */
 export const PACKAGE_METADATA = {
     name: "rea-agents",
-    version: "2.2.0", // x-release-please-version
+    version: "2.3.0", // x-release-please-version
     serverSdkVersion: "2.0.0-beta.4",
     clientSdkVersion: "2.0.0-beta.4",
     coreSdkVersion: "2.0.0-beta.4",

package/dist/ghidra/GhidraClient.js

@@ -6,6 +6,7 @@ import { silentLogger } from "../logger.js";
 import { PendingOperations } from "../process/PendingOperations.js";
 import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js";
 import { ProviderStartupDeadline } from "../process/ProviderDeadline.js";
+import { ProviderRunLineage } from "../process/ProviderRunLineage.js";
 import { ProviderProcessSupervisor, } from "../process/ProviderProcess.js";
 import { GHIDRA_MAX_LINE_BYTES, GHIDRA_MAX_QUEUED_REQUESTS, GHIDRA_REQUEST_TIMEOUT_MS, GHIDRA_STARTUP_TIMEOUT_MS, } from "./GhidraDefaults.js";
 import { createGhidraDiagnostics } from "./GhidraDiagnostics.js";
@@ -33,6 +34,7 @@ export class GhidraClient {
     #snapshotPath;
     #token;
     #runId;
+    #lineage = new ProviderRunLineage();
     #nextId = 1;
     #closing = false;
     #processSnapshot;
@@ -145,6 +147,10 @@ export class GhidraClient {
     diagnostics() {
         return structuredClone(this.#diagnostics());
     }
+    /** Latest token-verified launcher lineage for the active run. */
+    runtimeLineage() {
+        return this.#lineage.snapshot();
+    }
     async #start(signal) {
         if (signal.aborted)
             return err(this.#failure("cancelled", "Ghidra startup was cancelled"));
@@ -188,7 +194,8 @@ export class GhidraClient {
         if (deadline.signal.aborted)
             return this.#startupInterrupted(deadline);
         this.#token = randomBytes(32).toString("hex");
-        this.#runId = randomUUID();
+        this.#lineage.reset();
+        this.#runId = this.#options.runId ?? randomUUID();
         const launched = await this.#options.launcher
             .launch({
             runtimeRoot: this.#runtimeRoot.path,
@@ -221,7 +228,7 @@ export class GhidraClient {
             await this.#cleanup();
             return err(failure);
         }
-        return completeGhidraStartupHandshake({
+        const completed = await completeGhidraStartupHandshake({
             deadline,
             request: (method, params, requestOptions) => this.#wire.request(method, params, requestOptions),
             parseSessionInfo: (value) => this.#parseSessionInfo(value),
@@ -229,6 +236,9 @@ export class GhidraClient {
             failure: this.#failure,
             startupTimeoutMs: this.#options.startupTimeoutMs,
         });
+        if (completed.ok)
+            await this.#lineage.observe(this.#launch);
+        return completed;
     }
     async #connect(endpoint, deadline) {
         const connected = await connectGhidraSocket({
@@ -373,6 +383,7 @@ export class GhidraClient {
             transport: this.#options.transport,
             providerVersion: this.#options.providerVersion,
             profileDigest: this.#options.profileDigest,
+            ...(this.#runId === undefined ? {} : { runId: this.#runId }),
             ...(this.#runtimeRoot === undefined
                 ? {}
                 : { runtimeRoot: this.#runtimeRoot.path }),

package/dist/ghidra/GhidraDiagnostics.js

@@ -14,6 +14,7 @@ export const createGhidraDiagnostics = (options) => {
         transport: options.transport,
         provider_version: options.providerVersion,
         profile_digest: options.profileDigest,
+        ...(options.runId === undefined ? {} : { run_id: options.runId }),
         ...(options.runtimeRoot === undefined
             ? {}
             : {

package/dist/ghidra/GhidraLauncher.js

@@ -91,9 +91,7 @@ export class GhidraHeadlessLauncher {
             }
             const spawned = started;
             return ok({
-                process: spawned.process,
-                ownsProcessLifetime: true,
-                cleanup: () => cleanupStartedProcess(spawned, platform),
+                ...ownedGhidraProcess(spawned, platform),
                 projectRoot: paths.projectRoot,
                 ghidraLogPath: paths.ghidraLogPath,
                 scriptLogPath: paths.scriptLogPath,
@@ -108,6 +106,12 @@ export class GhidraHeadlessLauncher {
         }
     }
 }
+const ownedGhidraProcess = (spawned, platform) => ({
+    process: spawned.process,
+    ownsProcessLifetime: true,
+    ownership: spawned.ownership,
+    cleanup: () => cleanupStartedProcess(spawned, platform),
+});
 /** Build a direct POSIX launch or a conservatively quoted Windows batch call. */
 export const ghidraHeadlessCommand = (options) => {
     if (options.platform !== "win32")

package/dist/ghidra/GhidraProvider.js

@@ -95,7 +95,7 @@ export class GhidraProvider {
     resolveAnalysisProfile(target, options) {
         return resolveGhidraAnalysisProfile(target, GHIDRA_PROVIDER_IDENTITY, this.#inspectInstallation(), options?.signal);
     }
-    createClient(target, profile) {
+    createClient(target, profile, context) {
         const installation = this.#inspectInstallation();
         const prerequisites = ghidraClientPrerequisites(target, profile, installation);
         if (!prerequisites.ok)
@@ -118,6 +118,7 @@ export class GhidraProvider {
                 : "unix-socket",
             providerVersion: prerequisites.value.providerVersion,
             profileDigest: committedProfile.digest,
+            ...(context === undefined ? {} : { runId: context.runId }),
             logger: this.logger.child({ layer: "ghidra-bridge" }),
         });
         return {
@@ -160,6 +161,12 @@ export class GhidraProvider {
                     limitations: [...limitationsFor(operation), ...providerLimitations],
                 }));
             },
+            runtimeLineageSnapshots: () => {
+                const observation = client.runtimeLineage?.() ?? null;
+                return observation === null
+                    ? []
+                    : [{ provider: committedProfile.provider, observation }];
+            },
             close: () => client.close(),
         };
     }