rea-agents 3.0.0 → 3.1.0

package/dist/contracts/sessionToolSchemas.js

@@ -0,0 +1,61 @@
+import { z } from "zod";
+import { artifactComparisonInputSchema } from "../domain/artifactComparison.js";
+import { bundleComparisonInputSchema } from "../domain/bundleComparison.js";
+import { callPathInputSchema } from "../domain/callPath.js";
+import { changedBehaviorInputSchema } from "../domain/changedBehavior.js";
+import { functionComparisonInputSchema } from "../domain/functionComparison.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { processScenarioSchema } from "../domain/processCapture.js";
+import { processTraceSpecificationSchema } from "../domain/processTraceComparison.js";
+import { recordUnknownInputSchema } from "../domain/residualUnknown.js";
+import { reconstructionVerificationInputSchema } from "../domain/reconstructionVerification.js";
+import { replayMachineRunInputSchema } from "../domain/replayMachineRun.js";
+import { staticRuntimeCorrelationInputSchema } from "../domain/staticRuntimeCorrelation.js";
+import { updateUnknownInputSchema } from "../domain/residualUnknown.js";
+import { openBinaryInputSchema, closeBinaryInputSchema, } from "./sessionLifecycleInputs.js";
+import { binarySessionInputSchema } from "./sessionStatusContract.js";
+/** Retain the current canonical Evidence bundle as a session resource. */
+export const snapshotEvidenceBundleInputSchema = z.strictObject({});
+/** Release one session-retained immutable Evidence bundle. */
+export const releaseEvidenceBundleInputSchema = z.strictObject({
+    bundle_digest: z.string().regex(/^[a-f0-9]{64}$/u),
+});
+/** Optional document selection for volatile navigation context. */
+export const navigationContextInputSchema = z.strictObject({
+    document: z.string().min(1).optional(),
+});
+/** Explicit reproducible address context query. */
+export const addressContextInputSchema = z.strictObject({
+    address: z.string().min(1),
+    document: z.string().min(1).optional(),
+});
+/** Session-owned Evidence bundle import options. */
+export const importEvidenceBundleInputSchema = z.strictObject({
+    path: z.string().min(1),
+});
+/** Evidence references for deterministic process comparison. */
+export const processComparisonInputSchema = z.strictObject({
+    left_evidence_id: z.string().regex(/^ev_[a-f0-9]{64}$/u),
+    right_evidence_id: z.string().regex(/^ev_[a-f0-9]{64}$/u),
+    trace_spec: processTraceSpecificationSchema.optional(),
+    max_capture_age_ms: z.number().int().nonnegative().optional(),
+    unknown_registry_approved: z
+        .literal(true)
+        .optional()
+        .describe("Explicit approval to record capture disagreement durably"),
+});
+/** Residual-unknown list filters. */
+export const listUnknownsInputSchema = z.strictObject({
+    status: z
+        .enum(["open", "investigating", "blocked", "contradicted", "resolved"])
+        .optional(),
+    severity: z.enum(["low", "medium", "high", "critical"]).optional(),
+    domain: z.string().trim().min(1).max(100).optional(),
+    offset: z.number().int().min(0).default(0),
+    limit: z.number().int().min(1).max(500).default(100),
+});
+/** Exact residual-unknown identity to revalidate. */
+export const verifyUnknownResolutionInputSchema = z.strictObject({
+    unknown_id: z.string().regex(/^unk_[a-f0-9]{64}$/u),
+});
+export { artifactComparisonInputSchema, binarySessionInputSchema, bundleComparisonInputSchema, callPathInputSchema, changedBehaviorInputSchema, closeBinaryInputSchema, functionComparisonInputSchema, jsonValueSchema, openBinaryInputSchema, processScenarioSchema, reconstructionVerificationInputSchema, recordUnknownInputSchema, replayMachineRunInputSchema, staticRuntimeCorrelationInputSchema, updateUnknownInputSchema, };

package/dist/contracts/toolContractExamples.js

@@ -39,6 +39,7 @@ export const TOOL_EXAMPLE_OVERRIDES = {
     export_evidence_bundle: { path: "/tmp/evidence.json" },
     inspect_address_context: { address: "0x1000" },
     import_evidence_bundle: { path: "evidence.json" },
+    release_evidence_bundle: { bundle_digest: "a".repeat(64) },
     capture_process_scenario: {
         approved: true,
         executable: "/usr/bin/true",

package/dist/contracts/toolContractHelpers.js

@@ -0,0 +1,23 @@
+import { z } from "zod";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { TOOL_EXAMPLE_OVERRIDES } from "./toolContractExamples.js";
+export const document = z.string().optional().describe("The document name");
+export const address = z
+    .string()
+    .describe("A provider-normalized address; default memory uses 0x-prefixed hexadecimal");
+export const optionalAddress = address.optional();
+export const procedure = z.string().describe("The procedure name or address");
+export const pagination = {
+    offset: z.number().int().min(0).default(0),
+    limit: z.number().int().min(1).max(500).default(100),
+};
+const exampleInputSchema = z.record(z.string(), jsonValueSchema);
+export const examplesFor = (name, inputSchema) => {
+    const parsed = inputSchema.parse(TOOL_EXAMPLE_OVERRIDES[name] ?? {});
+    return [
+        {
+            title: `Example ${name.replaceAll("_", " ")} request`,
+            input: exampleInputSchema.parse(parsed),
+        },
+    ];
+};

package/dist/contracts/toolContracts.js

@@ -1,19 +1,6 @@
 import { z } from "zod";
-import { jsonValueSchema } from "../domain/jsonValue.js";
-import { processScenarioSchema } from "../domain/processCapture.js";
-import { recordUnknownInputSchema, updateUnknownInputSchema, } from "../domain/residualUnknown.js";
-import { artifactComparisonInputSchema } from "../domain/artifactComparison.js";
-import { functionComparisonInputSchema } from "../domain/functionComparison.js";
-import { bundleComparisonInputSchema } from "../domain/bundleComparison.js";
-import { changedBehaviorInputSchema } from "../domain/changedBehavior.js";
-import { callPathInputSchema } from "../domain/callPath.js";
-import { staticRuntimeCorrelationInputSchema } from "../domain/staticRuntimeCorrelation.js";
-import { reconstructionVerificationInputSchema } from "../domain/reconstructionVerification.js";
-import { replayMachineRunInputSchema } from "../domain/replayMachineRun.js";
-import { processTraceSpecificationSchema } from "../domain/processTraceComparison.js";
 import { enhancedInputSchemas } from "./enhancedInputs.js";
 import { enhancedOutputSchemas, officialOutputSchemas, requireOutputSchema, sessionOutputSchemas, } from "./toolOutputSchemas.js";
-import { TOOL_EXAMPLE_OVERRIDES } from "./toolContractExamples.js";
 import { NATIVE_TOOL_CONTRACTS } from "./nativeToolContracts.js";
 import { ARTIFACT_TOOL_CONTRACTS } from "./artifactToolContracts.js";
 import { MANAGED_TOOL_CONTRACTS } from "./managedToolContracts.js";
@@ -22,34 +9,14 @@ import { BROWSER_PROVIDER_TOOL_CONTRACTS } from "./browserProviderToolContracts.
 import { ELECTRON_TOOL_CONTRACTS } from "./electronToolContracts.js";
 import { JAVASCRIPT_RUNTIME_OBSERVATION_TOOL_CONTRACTS } from "./javascriptRuntimeObservationToolContracts.js";
 import { APPLICATION_TOOL_CONTRACTS } from "./applicationToolContracts.js";
-import { closeBinaryInputSchema, openBinaryInputSchema, } from "./sessionLifecycleInputs.js";
+import { addressContextInputSchema, artifactComparisonInputSchema, binarySessionInputSchema, bundleComparisonInputSchema, callPathInputSchema, changedBehaviorInputSchema, closeBinaryInputSchema, functionComparisonInputSchema, importEvidenceBundleInputSchema, listUnknownsInputSchema, navigationContextInputSchema, openBinaryInputSchema, processComparisonInputSchema, processScenarioSchema, reconstructionVerificationInputSchema, recordUnknownInputSchema, releaseEvidenceBundleInputSchema, replayMachineRunInputSchema, snapshotEvidenceBundleInputSchema, staticRuntimeCorrelationInputSchema, updateUnknownInputSchema, verifyUnknownResolutionInputSchema, } from "./sessionToolSchemas.js";
+import { address, document, examplesFor, optionalAddress, pagination, procedure, } from "./toolContractHelpers.js";
 import { toolContractMetadata } from "./toolEffects.js";
-import { binarySessionInputSchema } from "./sessionStatusContract.js";
 import { functionInstructionInputSchema } from "./functionInstructionContract.js";
 import { HOPPER_MEMORY_TOOL_DEFINITIONS } from "./hopperMemoryContracts.js";
 import { analysisSearchInput } from "./analysisSearchContract.js";
 import { FUNCTION_WORKFLOW_TOOL_CONTRACTS } from "./functionWorkflowToolContracts.js";
-export { binarySessionInputSchema } from "./sessionStatusContract.js";
-const document = z.string().optional().describe("The document name");
-const address = z
-    .string()
-    .describe("A provider-normalized address; default memory uses 0x-prefixed hexadecimal");
-const optionalAddress = address.optional();
-const procedure = z.string().describe("The procedure name or address");
-const pagination = {
-    offset: z.number().int().min(0).default(0),
-    limit: z.number().int().min(1).max(500).default(100),
-};
-const exampleInputSchema = z.record(z.string(), jsonValueSchema);
-const examplesFor = (name, inputSchema) => {
-    const parsed = inputSchema.parse(TOOL_EXAMPLE_OVERRIDES[name] ?? {});
-    return [
-        {
-            title: `Example ${name.replaceAll("_", " ")} request`,
-            input: exampleInputSchema.parse(parsed),
-        },
-    ];
-};
+export { addressContextInputSchema, binarySessionInputSchema, importEvidenceBundleInputSchema, listUnknownsInputSchema, navigationContextInputSchema, processComparisonInputSchema, releaseEvidenceBundleInputSchema, snapshotEvidenceBundleInputSchema, verifyUnknownResolutionInputSchema, } from "./sessionToolSchemas.js";
 const official = (name, description, inputSchema) => {
     const trackedInputSchema = inputSchema.extend({
         unknown_registry_approved: z
@@ -150,46 +117,6 @@ export const exportEvidenceBundleInputSchema = z.strictObject({
     path: z.string().min(1),
     overwrite: z.boolean().default(false),
 });
-/** Retain the current canonical Evidence bundle as a session resource. */
-export const snapshotEvidenceBundleInputSchema = z.strictObject({});
-/** Optional document selection for volatile navigation context. */
-export const navigationContextInputSchema = z.strictObject({
-    document: z.string().min(1).optional(),
-});
-/** Explicit reproducible address context query. */
-export const addressContextInputSchema = z.strictObject({
-    address: z.string().min(1),
-    document: z.string().min(1).optional(),
-});
-/** Session-owned Evidence bundle import options. */
-export const importEvidenceBundleInputSchema = z.strictObject({
-    path: z.string().min(1),
-});
-/** Evidence references for deterministic process comparison. */
-export const processComparisonInputSchema = z.strictObject({
-    left_evidence_id: z.string().regex(/^ev_[a-f0-9]{64}$/u),
-    right_evidence_id: z.string().regex(/^ev_[a-f0-9]{64}$/u),
-    trace_spec: processTraceSpecificationSchema.optional(),
-    max_capture_age_ms: z.number().int().nonnegative().optional(),
-    unknown_registry_approved: z
-        .literal(true)
-        .optional()
-        .describe("Explicit approval to record capture disagreement durably"),
-});
-/** Residual-unknown list filters. */
-export const listUnknownsInputSchema = z.strictObject({
-    status: z
-        .enum(["open", "investigating", "blocked", "contradicted", "resolved"])
-        .optional(),
-    severity: z.enum(["low", "medium", "high", "critical"]).optional(),
-    domain: z.string().trim().min(1).max(100).optional(),
-    offset: z.number().int().min(0).default(0),
-    limit: z.number().int().min(1).max(500).default(100),
-});
-/** Exact residual-unknown identity to revalidate. */
-export const verifyUnknownResolutionInputSchema = z.strictObject({
-    unknown_id: z.string().regex(/^unk_[a-f0-9]{64}$/u),
-});
 /** Target lifecycle tools available only on the long-lived MCP adapter. */
 export const SESSION_TOOL_CONTRACTS = [
     session("open_binary", "Open a local executable, application bundle, archive, JavaScript, source map, plist, or analysis database after validation. provider_id selects one deep provider or deterministic auto selection; the binding remains stable until close or an explicit switch, with no failure fallback. An optional snapshot v2 is imported atomically and must match the binary identity, concrete provider, and canonical analysis profile exactly.", openBinaryInputSchema),
@@ -212,7 +139,8 @@ export const SESSION_TOOL_CONTRACTS = [
     session("verify_unknown_resolution", "Revalidate the current residual-unknown head against live bundled evidence, exact authority/confidence/environment requirements, and revision integrity. Withdrawn and out-of-scope dispositions are not truth claims.", verifyUnknownResolutionInputSchema),
     session("run_replay_machine", "Evaluate ordered HTTP and WebSocket events directly against one validated finite replay machine without opening sockets or launching a target. Returns every decision, a capture-value-free transition journal, one redacted action table entry per used transition, captured aliases, final state, and exact configured and consumed limits.", replayMachineRunInputSchema),
     session("snapshot_evidence_bundle", "Retain the current canonical Evidence v2 bundle as an immutable session resource. Returns a compact digest summary and exact opaque URI; copy that URI unchanged and call MCP resources/read (Codex: read_mcp_resource) for the full bundle. Repeating an unchanged snapshot is idempotent.", snapshotEvidenceBundleInputSchema),
-    session("get_navigation_context", "Return the selected document, current address, and containing/current procedure in one coherent provider-neutral request. A cursor outside any procedure returns procedure: null. Scalar navigation getters remain available for evaluation and compatibility.", navigationContextInputSchema),
+    session("release_evidence_bundle", "Release one immutable session-retained Evidence v2 bundle by exact digest. This is the recovery operation when bounded bundle retention is exhausted; releasing an unknown digest is idempotent and reports released: false.", releaseEvidenceBundleInputSchema),
+    session("get_navigation_context", "Compose the selected document, current address, and containing/current procedure into one provider-neutral result. The result reflects sequential provider observations, not an atomic cursor snapshot; a cursor outside any procedure returns procedure: null. Scalar navigation getters remain available for evaluation and compatibility.", navigationContextInputSchema),
     session("inspect_address_context", "Inspect one explicit reproducible address for its analyzed name, containing procedure, regular and inline comments, and matching bookmarks. Each unsupported facet returns a typed unavailable outcome; xrefs, assembly, and pseudocode remain separate bounded follow-ups.", addressContextInputSchema),
 ];
 /** Complete ordered public inventory used by registration and verification. */

package/dist/contracts/toolEffects.js

@@ -107,6 +107,16 @@ export const TOOL_EFFECTS = {
     }),
     list_electron_targets: browserEvidence,
     inspect_electron_page: browserEvidence,
+    capture_electron_scenario: effects({
+        mutatesTarget: true,
+        mutatesSession: true,
+        writesFilesystem: true,
+        launchesProcess: true,
+        accessesNetwork: true,
+        changesUiState: true,
+        mayDiscardData: true,
+        idempotent: false,
+    }),
     list_javascript_runtime_targets: browserEvidence,
     observe_javascript_runtime: browserEvidence,
     analyze_javascript_application: evidence,
@@ -151,6 +161,10 @@ export const TOOL_EFFECTS = {
         mayDiscardData: true,
     }),
     snapshot_evidence_bundle: effects({ mutatesSession: true }),
+    release_evidence_bundle: effects({
+        mutatesSession: true,
+        mayDiscardData: true,
+    }),
     get_navigation_context: effects({ mutatesSession: true }),
     inspect_address_context: effects({ mutatesSession: true }),
     import_evidence_bundle: effects({ mutatesSession: true }),
@@ -158,6 +172,7 @@ export const TOOL_EFFECTS = {
         mutatesSession: true,
         writesFilesystem: true,
         launchesProcess: true,
+        accessesNetwork: true,
         idempotent: false,
     }),
     compare_process_captures: sessionEvidence,

package/dist/contracts/toolOutputSchemaGroups.js

@@ -22,7 +22,7 @@ import { staticRuntimeCorrelationResultSchema } from "../domain/staticRuntimeCor
 import { reconstructionVerificationResultSchema } from "../domain/reconstructionVerification.js";
 import { replayMachineRunOutputSchema } from "../domain/replayMachineRun.js";
 import { analysisErrorProjectionSchema } from "./errorSchemas.js";
-import { addressList, analysisActivity, addressedEntry, bounded, containingProcedureResolution, clientFeatureAvailabilitySchema, functionDossierOutput, graphNode, lifecycleResultOf, nullableText, pageOutput, procedureIdentity, procedureInfoOutput, evidenceResultOf as resultOf, searchPageOutput, segmentOutput, sessionProvider, providerIdentity, toolAvailability, symbolDiscoveryOutput, targetFormatSchema, targetKindSchema, } from "./toolOutputSchemaPrimitives.js";
+import { addressList, addressedEntry, analysisActivity, bounded, containingProcedureResolution, clientFeatureAvailabilitySchema, functionDossierOutput, graphNode, lifecycleResultOf, nullableText, pageOutput, procedureIdentity, procedureInfoOutput, evidenceResultOf as resultOf, searchPageOutput, segmentOutput, sessionProvider, providerIdentity, toolAvailability, symbolDiscoveryOutput, targetFormatSchema, targetKindSchema, } from "./toolOutputSchemaPrimitives.js";
 const contextFacetSchema = z.discriminatedUnion("state", [
     z.object({ state: z.literal("available"), value: jsonValueSchema }),
     z.object({
@@ -31,6 +31,14 @@ const contextFacetSchema = z.discriminatedUnion("state", [
         remediation: z.string(),
     }),
 ]);
+const bookmarkFacetSchema = z.discriminatedUnion("state", [
+    z.object({ state: z.literal("available"), value: z.array(addressedEntry) }),
+    z.object({
+        state: z.literal("unavailable"),
+        reason: z.string(),
+        remediation: z.string(),
+    }),
+]);
 /** Exact structured-content schemas shared by direct analysis providers. */
 export const officialOutputSchemas = {
     address_name: resultOf(nullableText),
@@ -315,8 +323,14 @@ export const sessionOutputSchemas = {
         bytes: z.number().int().min(0),
         records: z.number().int().min(0),
         unknowns: z.number().int().min(0),
+        scope: z.literal("session"),
+        survives_session: z.literal(false),
         bundle_uri: z.string().regex(/^rea:\/\/evidence-bundle\/[a-f0-9]{64}$/u),
     })),
+    release_evidence_bundle: lifecycleResultOf(z.object({
+        bundle_digest: z.string().regex(/^[a-f0-9]{64}$/u),
+        released: z.boolean(),
+    })),
     get_navigation_context: lifecycleResultOf(z.object({
         document: z.string(),
         address: z.string(),
@@ -329,10 +343,11 @@ export const sessionOutputSchemas = {
         procedure: contextFacetSchema,
         comment: contextFacetSchema,
         inline_comment: contextFacetSchema,
-        bookmarks: contextFacetSchema,
+        bookmarks: bookmarkFacetSchema,
     })),
     import_evidence_bundle: lifecycleResultOf(z.object({
         imported: z.number().int().min(0),
+        unknowns_added: z.number().int().min(0),
         total: z.number().int().min(0),
     })),
     capture_process_scenario: resultOf(processCaptureSchema),

package/dist/contracts/toolOutputSchemaPrimitives.js

@@ -42,11 +42,8 @@ export const targetKindSchema = z.enum([
     "archive",
     "artifact",
 ]);
-const providerCapability = z.object({
+const providerCapabilityFacts = {
     operation: z.string(),
-    available: z.boolean(),
-    reason: z.string().nullable(),
-    availability_code: z.enum(PROVIDER_REJECTION_CODES).nullable(),
     input_contract_version: z.number().int().min(1),
     output_contract_version: z.number().int().min(1),
     pagination: z.enum(["none", "offset", "cursor"]),
@@ -66,7 +63,21 @@ const providerCapability = z.object({
         timeout_ms: z.number().int().min(0).nullable(),
     }),
     limitations: z.array(z.string()),
-});
+};
+export const providerCapability = z.discriminatedUnion("available", [
+    z.object({
+        ...providerCapabilityFacts,
+        available: z.literal(true),
+        reason: z.null(),
+        availability_code: z.null(),
+    }),
+    z.object({
+        ...providerCapabilityFacts,
+        available: z.literal(false),
+        reason: z.string().nullable(),
+        availability_code: z.enum(PROVIDER_REJECTION_CODES).nullable(),
+    }),
+]);
 export const providerIdentity = z.object({
     id: z.string(),
     name: z.string(),
@@ -182,21 +193,25 @@ export const clientFeatureAvailabilitySchema = z.object({
     roots: z.boolean(),
     sampling: z.boolean(),
 });
-export const toolAvailability = z.object({
+const toolAvailabilityMode = z.discriminatedUnion("available", [
+    z.object({
+        name: z.string(),
+        available: z.literal(true),
+        missing_operations: z.array(z.string()).max(0),
+        remediation: z.null(),
+    }),
+    z.object({
+        name: z.string(),
+        available: z.literal(false),
+        missing_operations: z.array(z.string()).min(1),
+        remediation: z.string().nullable(),
+    }),
+]);
+const toolAvailabilityFacts = {
     name: z.string(),
     surface: z.string(),
-    available: z.boolean(),
-    reason: z.enum([
-        "available",
-        "client_capability_missing",
-        "target_required",
-        "provider_missing",
-        "provider_unavailable",
-        "target_unsupported",
-        "unsupported_host",
-        "policy_disabled",
-    ]),
-    remediation: z.string().nullable(),
+    default_mode_available: z.boolean().optional(),
+    modes: z.array(toolAvailabilityMode).optional(),
     client_requirements: z.object({
         required: z.array(clientFeatureNameSchema),
         optional: z.array(clientFeatureNameSchema),
@@ -219,7 +234,30 @@ export const toolAvailability = z.object({
         idempotent: z.boolean(),
         open_world: z.boolean(),
     }),
-});
+};
+export const toolUnavailabilityReason = z.enum([
+    "client_capability_missing",
+    "target_required",
+    "provider_missing",
+    "provider_unavailable",
+    "target_unsupported",
+    "unsupported_host",
+    "policy_disabled",
+]);
+export const toolAvailability = z.discriminatedUnion("available", [
+    z.object({
+        ...toolAvailabilityFacts,
+        available: z.literal(true),
+        reason: z.literal("available"),
+        remediation: z.null(),
+    }),
+    z.object({
+        ...toolAvailabilityFacts,
+        available: z.literal(false),
+        reason: toolUnavailabilityReason,
+        remediation: z.string().nullable(),
+    }),
+]);
 export const sessionProvider = z.object({
     provider: providerIdentity,
     providers: z.array(providerIdentity),
@@ -315,13 +353,25 @@ const availableMemoryPermissions = z.object({
     available: z.literal(true),
     source: z.literal("ghidra-memory-block"),
 });
-export const bounded = (item) => z.object({
-    items: z.array(item),
-    total: z.number().int().min(0).nullable(),
-    returned: z.number().int().min(0),
-    truncated: z.boolean(),
-    next_offset: z.number().int().min(0).nullable(),
-});
+export const bounded = (item) => {
+    const facts = {
+        items: z.array(item),
+        total: z.number().int().min(0).nullable(),
+        returned: z.number().int().min(0),
+    };
+    return z.discriminatedUnion("truncated", [
+        z.object({
+            ...facts,
+            truncated: z.literal(false),
+            next_offset: z.null(),
+        }),
+        z.object({
+            ...facts,
+            truncated: z.literal(true),
+            next_offset: z.number().int().min(0).nullable(),
+        }),
+    ]);
+};
 const addressedValue = z.object({
     address: z.string(),
     value: z.string(),

package/dist/contracts/toolSchemaMetadata.js

@@ -0,0 +1,128 @@
+import { z } from "zod";
+const PROPERTY_DESCRIPTIONS = {
+    addresses: "Ordered provider-normalized procedure addresses to analyze.",
+    approved: "Explicit operator approval to perform this operation.",
+    after: "The later or right-hand observation to compare.",
+    before: "The earlier or left-hand observation to compare.",
+    boundary_id: "Exact reconstruction boundary identifier to evaluate.",
+    case_sensitive: "Whether text matching distinguishes uppercase and lowercase.",
+    cdp_endpoint: "Approved literal loopback Chrome DevTools Protocol endpoint.",
+    comment: "Exact analyst comment text to write.",
+    comparisons: "Validated comparison Evidence records to aggregate.",
+    coverage: "Exact reconstruction-coverage commitment to verify.",
+    detail: "Requested response detail level.",
+    direction: "Direction in which to traverse or compare relationships.",
+    document: "Exact provider document or program identity.",
+    error: "Structured, caller-actionable error when the operation fails.",
+    evidence: "Evidence v2 record produced by this operation.",
+    evidence_id: "Stable identifier of the recorded Evidence v2 observation.",
+    evidence_uri: "Session resource URI for the recorded Evidence v2 observation.",
+    executable: "Approved absolute path of the executable to run.",
+    format: "Declared input artifact format.",
+    name: "Exact name used by this operation.",
+    pattern: "Text or bounded pattern used to filter matching results.",
+    phase: "Current plan or execution phase of the operation.",
+    plan: "Content-bound execution plan and its approval commitment.",
+    query: "Non-empty feature or text query to investigate.",
+    question: "Concrete unresolved question to retain for later investigation.",
+    result: "Primary structured result returned by this operation.",
+    left: "Left-hand input used for comparison or differential execution.",
+    limit: "Maximum number of results to return in this page.",
+    limits: "Bounded resource-consumption and result-size limits for this operation.",
+    mode: "Operation mode that selects the requested behavior.",
+    offset: "Zero-based index of the first result to return.",
+    overwrite: "Whether an existing destination may be replaced.",
+    path: "Local filesystem path used by this operation.",
+    provider_id: "Exact deep-analysis provider ID, or automatic selection when omitted.",
+    right: "Right-hand input used for comparison or differential execution.",
+    schema_version: "Version of this structured result schema.",
+    source_evidence: "Evidence records supporting the prepared source transformation.",
+    status: "Current lifecycle or verification status.",
+    summary: "Concise evidence-backed summary of the result.",
+    symbols: "Ordered bounded Swift symbols to demangle.",
+    target_id: "Exact authorized CDP target identifier.",
+    unknown_id: "Exact residual-unknown identifier.",
+    unknown_registry_approved: "Explicit approval to record bounded residual uncertainty in the session registry.",
+    workspace_path: "Approved local path of the persistent investigation workspace.",
+};
+/** Attach caller guidance to a canonical schema for the SDK wire projection. */
+export const toolInputSchemaWithMetadata = (contract) => {
+    const schema = contract.inputSchema.meta(z.globalRegistry.get(contract.inputSchema) ?? {});
+    const standard = schema["~standard"];
+    const inputJsonSchema = standard.jsonSchema?.input;
+    if (inputJsonSchema === undefined)
+        throw new TypeError("Tool input schema does not expose Standard JSON Schema");
+    // Zod's input projection drops root metadata when a descendant transforms.
+    // Preserve the parser and let the SDK own conversion of everything else.
+    Object.defineProperty(schema, "~standard", {
+        value: {
+            ...standard,
+            jsonSchema: {
+                ...standard.jsonSchema,
+                input: (options) => ({
+                    ...describeProperties(inputJsonSchema(options)),
+                    examples: contract.examples.map(({ input }) => input),
+                }),
+            },
+        },
+    });
+    return schema;
+};
+const describeProperties = (value) => Object.fromEntries(Object.entries(value).map(([key, child]) => {
+    if (key !== "properties" || !isObject(child))
+        return [key, describeValue(child)];
+    return [
+        key,
+        Object.fromEntries(Object.entries(child).map(([property, propertySchema]) => [
+            property,
+            isObject(propertySchema) &&
+                typeof propertySchema.description !== "string"
+                ? {
+                    ...describeProperties(propertySchema),
+                    description: fallbackPropertyDescription(property),
+                }
+                : describeValue(propertySchema),
+        ])),
+    ];
+}));
+const describeValue = (value) => {
+    if (Array.isArray(value))
+        return value.map(describeValue);
+    return isObject(value) ? describeProperties(value) : value;
+};
+const fallbackPropertyDescription = (property) => {
+    const explicit = PROPERTY_DESCRIPTIONS[property];
+    if (explicit !== undefined)
+        return explicit;
+    const words = property.replaceAll("_", " ");
+    if (property.endsWith("_approved"))
+        return `Explicit operator approval for ${words.slice(0, -9)}.`;
+    if (property.endsWith("_offset"))
+        return `Zero-based index of the first ${words.slice(0, -7)} to return.`;
+    if (property.endsWith("_limit"))
+        return `Maximum number of ${words.slice(0, -6)} entries to return.`;
+    if (property.startsWith("max_"))
+        return `Maximum permitted ${words.slice(4)} for this operation.`;
+    if (property.startsWith("include_"))
+        return `Whether to include ${words.slice(8)} in the result.`;
+    if (property.startsWith("expected_"))
+        return `Expected ${words.slice(9)} used to reject stale or mismatched input.`;
+    if (property.endsWith("_sha256"))
+        return `Exact SHA-256 digest of ${words.slice(0, -7)}.`;
+    if (property.endsWith("_evidence_id"))
+        return `Exact Evidence v2 identifier for the ${words.slice(0, -12)} observation.`;
+    if (property.endsWith("_evidence_ids"))
+        return `Ordered Evidence v2 identifiers for the ${words.slice(0, -13)} observations.`;
+    if (property.endsWith("_path"))
+        return `Local filesystem path for ${words.slice(0, -5)}.`;
+    if (property.endsWith("_uri"))
+        return `Canonical URI for ${words.slice(0, -4)}.`;
+    if (property.endsWith("_bytes"))
+        return `Bounded byte count for ${words.slice(0, -6)}.`;
+    if (property.endsWith("_root") || property.endsWith("_roots"))
+        return `Approved canonical filesystem ${words}.`;
+    if (property.startsWith("is_") || property.startsWith("has_"))
+        return `Whether ${words}.`;
+    return `Value for ${words}.`;
+};
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);

package/dist/doctorRuntime.js

@@ -58,7 +58,7 @@ const inspectJavaScriptReplay = async () => {
             detail: config.error.message,
             remediation: "Fix the reported REA_JAVASCRIPT_REPLAY_* configuration.",
         };
-    if (!config.value.javascriptReplayPolicy.enabled)
+    if (config.value.javascriptReplayPolicy.status === "disabled")
         return {
             name: "javascript-replay",
             ok: true,

package/dist/domain/androidApplication.js

@@ -146,6 +146,8 @@ const classify = (all) => ({
 });
 const retain = (groups, maximum) => {
     let remaining = maximum;
+    // SAFETY: the projection preserves every key from Groups and replaces only
+    // each readonly Component array with a bounded mutable Component array.
     return Object.fromEntries(Object.entries(groups).map(([key, values]) => {
         const selected = [...values]
             .sort((left, right) => compare(left.path, right.path))

package/dist/domain/appleApplication.js

@@ -140,6 +140,8 @@ const classifyComponents = (all, roots) => {
 };
 const retainComponents = (groups, maximum) => {
     let remaining = maximum;
+    // SAFETY: the projection preserves every key from Groups and replaces only
+    // each readonly Component array with a bounded mutable Component array.
     return Object.fromEntries(Object.entries(groups).map(([key, values]) => {
         const retained = [...values]
             .sort((left, right) => compare(left.path, right.path))

package/dist/domain/binaryTarget.js

@@ -36,14 +36,16 @@ export const parseBinaryTarget = async (input, cwd = process.cwd(), hostArchitec
                     format: "analysis-database",
                 });
             const artifactFormat = await detectArtifactFormat(path, handle);
-            if (artifactFormat !== undefined)
-                return ok({
+            if (artifactFormat !== undefined) {
+                const identity = {
                     path,
                     sourcePath: canonical,
                     sha256: await sha256Handle(handle),
-                    kind: isArchiveFormat(artifactFormat) ? "archive" : "artifact",
-                    format: artifactFormat,
-                });
+                };
+                return isArchiveFormat(artifactFormat)
+                    ? ok({ ...identity, kind: "archive", format: artifactFormat })
+                    : ok({ ...identity, kind: "artifact", format: artifactFormat });
+            }
             const detected = await readExecutableMetadata(handle, hostArchitecture);
             if (!detected.ok)
                 return err(new BinaryTargetError(path, detected.error));

package/dist/domain/binaryTargetTypes.js

@@ -0,0 +1 @@
+export {};