rea-agents 2.5.0 → 3.0.0

package/dist/application/EvidenceLedger.js

@@ -1,5 +1,5 @@
 import canonicalize from "canonicalize";
-import { createEvidenceBundle, parseEvidenceBundle, } from "../domain/evidenceBundle.js";
+import { createEvidenceBundle, parseEvidenceBundle, validateResidualUnknownAddition, } from "../domain/evidenceBundle.js";
 import { EvidenceIntegrityError, EvidenceLimitError, UnknownRegistryError, } from "../domain/errors.js";
 import { parseEvidence } from "../domain/evidence.js";
 import { createResidualUnknown, updateResidualUnknown, } from "../domain/residualUnknown.js";
@@ -142,26 +142,19 @@ export class EvidenceLedger {
         catch (cause) {
             return err(new UnknownRegistryError("invalid-transition", { cause }));
         }
-        const pendingRecords = new Map(this.#records);
-        pendingRecords.set(evidence.evidence_id, evidence);
         const existingUnknown = this.#unknownHeads.get(unknown.unknown_id);
         if (existingUnknown !== undefined) {
             if (existingUnknown.revision !== 1 ||
                 existingUnknown.revision_digest !== unknown.revision_digest)
                 return err(new UnknownRegistryError("already-exists"));
-            const checked = this.#validateCandidate(pendingRecords, this.#unknownRevisions);
+            const checked = this.#appendIncremental([evidence]);
             if (!checked.ok)
                 return checked;
-            this.#commit(pendingRecords, this.#unknownRevisions, checked.value);
             return ok(null);
         }
-        pendingRecords.set(mutation.evidence_id, mutation);
-        const pendingUnknowns = new Map(this.#unknownRevisions);
-        pendingUnknowns.set(unknownRevisionKey(unknown), unknown);
-        const checked = this.#validateCandidate(pendingRecords, pendingUnknowns);
+        const checked = this.#appendIncremental([evidence, mutation], unknown);
         if (!checked.ok)
             return checked;
-        this.#commit(pendingRecords, pendingUnknowns, checked.value);
         return ok(structuredClone(unknown));
     }
     /** Apply one approved full-state update using optimistic revision matching. */
@@ -218,16 +211,52 @@ export class EvidenceLedger {
                 cause,
             }));
         }
-        const pendingRecords = new Map(this.#records);
-        pendingRecords.set(mutationEvidence.evidence_id, mutationEvidence);
-        const pendingUnknowns = new Map(this.#unknownRevisions);
-        pendingUnknowns.set(unknownRevisionKey(unknown), unknown);
-        const checked = this.#validateCandidate(pendingRecords, pendingUnknowns);
+        const checked = this.#appendIncremental([mutationEvidence], unknown);
         if (!checked.ok)
             return checked;
-        this.#commit(pendingRecords, pendingUnknowns, checked.value);
         return ok(structuredClone(unknown));
     }
+    #appendIncremental(records, unknown) {
+        const additions = new Map();
+        let addedBytes = 0;
+        for (const evidence of records) {
+            const existing = additions.get(evidence.evidence_id) ??
+                this.#records.get(evidence.evidence_id);
+            if (existing !== undefined) {
+                if (!recordsAgree(existing, evidence))
+                    return err(new EvidenceIntegrityError("Conflicting evidence record"));
+                continue;
+            }
+            additions.set(evidence.evidence_id, evidence);
+            addedBytes += serializedBytes(evidence);
+        }
+        const unknownKey = unknown === undefined ? undefined : unknownRevisionKey(unknown);
+        if (unknownKey !== undefined && this.#unknownRevisions.has(unknownKey))
+            return err(new UnknownRegistryError("integrity"));
+        const unknownBytes = unknown === undefined ? 0 : serializedBytes(unknown);
+        if (this.#exceedsRecordLimit(this.#records.size + additions.size, this.#unknownRevisions.size + (unknown === undefined ? 0 : 1)))
+            return err(new EvidenceLimitError("records", this.limits.maxRecords));
+        if (this.#bytes + addedBytes + unknownBytes > this.limits.maxBytes)
+            return err(new EvidenceLimitError("bytes", this.limits.maxBytes));
+        if (unknown !== undefined)
+            try {
+                validateResidualUnknownAddition(unknown, {
+                    get: (id) => additions.get(id) ?? this.#records.get(id),
+                    has: (id) => additions.has(id) || this.#records.has(id),
+                }, this.#unknownHeads);
+            }
+            catch (cause) {
+                return err(new UnknownRegistryError("integrity", { cause }));
+            }
+        for (const [id, evidence] of additions)
+            this.#records.set(id, evidence);
+        if (unknown !== undefined && unknownKey !== undefined) {
+            this.#unknownRevisions.set(unknownKey, unknown);
+            this.#unknownHeads.set(unknown.unknown_id, unknown);
+        }
+        this.#bytes += addedBytes + unknownBytes;
+        return ok(undefined);
+    }
     #validateCandidate(records, unknowns) {
         if (this.#exceedsRecordLimit(records.size, unknowns.size))
             return err(new EvidenceLimitError("records", this.limits.maxRecords));

package/dist/application/JavaScriptArtifactAnalysis.js

@@ -1,7 +1,9 @@
 import { createHash } from "node:crypto";
-import { analyzeJavaScriptStaticSource } from "../domain/javascriptStaticAnalysis.js";
-import { analyzeJavaScriptSemantics } from "../domain/javascriptSemanticAnalysis.js";
+import { analyzeParsedJavaScriptStaticSource } from "../domain/javascriptStaticAnalysis.js";
+import { analyzeParsedJavaScriptSemantics } from "../domain/javascriptSemanticAnalysis.js";
 import { DEFAULT_JAVASCRIPT_SEMANTIC_LIMITS, } from "../domain/javascriptSemanticIr.js";
+import { parseJavaScriptSource } from "../domain/javascriptSourceParser.js";
+import { failedJavaScriptStaticAnalysis } from "../domain/javascriptStaticAnalysisHelpers.js";
 import { analyzeJavaScriptJsonModule } from "./JavaScriptJsonModules.js";
 /** Analyze selected text files under one shared AST, finding, module, and time budget. */
 export const analyzeJavaScriptArtifactFiles = (fileSet, input, now) => {
@@ -70,7 +72,14 @@ const analyzeArtifactFile = (file, context) => {
         state.truncatedScopes += 1;
         return;
     }
-    const analysis = analyzeJavaScriptStaticSource(file.text.value, {
+    const parsed = parseJavaScriptSource(file.text.value);
+    if (parsed === null) {
+        const analysis = failedJavaScriptStaticAnalysis();
+        state.files.push({ file, javascript: analysis, semantic: null });
+        state.parseFailures += 1;
+        return;
+    }
+    const analysis = analyzeParsedJavaScriptStaticSource(file.text.value, parsed, {
         maxAstNodes: remainingNodes,
         maxFindings: remainingFindings,
         maxModules: remainingModules,
@@ -88,7 +97,7 @@ const analyzeArtifactFile = (file, context) => {
         maxModuleLinks: semanticFindingBudget,
     };
     const semantics = analysis.parse_status === "complete" || analysis.parse_status === "partial"
-        ? analyzeJavaScriptSemantics(file.text.value, semanticLimits)
+        ? analyzeParsedJavaScriptSemantics(parsed, semanticLimits)
         : null;
     state.files.push({
         file,

package/dist/application/LazyAnalysisProvider.js

@@ -0,0 +1,77 @@
+/**
+ * Preserve synchronous provider discovery while loading implementation modules
+ * only when a target-bound client first executes.
+ */
+export class LazyAnalysisProvider {
+    #providerIdentity;
+    #capabilityDescriptors;
+    #loadProvider;
+    #provider;
+    constructor(options) {
+        this.#providerIdentity = options.identity;
+        this.#capabilityDescriptors = options.capabilities;
+        this.#loadProvider = options.load;
+    }
+    /** Return generated provider identity without loading its implementation. */
+    identity() {
+        return this.#providerIdentity;
+    }
+    /** Return generated capability metadata without loading its implementation. */
+    capabilities() {
+        return this.#capabilityDescriptors;
+    }
+    /** Create a client whose implementation is loaded on first execution. */
+    createClient(target, profile, context) {
+        return new LazyAnalysisClient(async () => {
+            const provider = await this.#load();
+            return provider.createClient(target, profile, context);
+        });
+    }
+    async #load() {
+        this.#provider ??= this.#loadProvider().catch((cause) => {
+            this.#provider = undefined;
+            throw cause;
+        });
+        return this.#provider;
+    }
+}
+class LazyAnalysisClient {
+    #loadClient;
+    #client;
+    #loading;
+    #closed = false;
+    constructor(loadClient) {
+        this.#loadClient = loadClient;
+    }
+    execute = async (operation, parameters, options) => {
+        const client = await this.#load();
+        return client.execute(operation, parameters, options);
+    };
+    runtimeLineageSnapshots() {
+        return this.#client?.runtimeLineageSnapshots?.() ?? [];
+    }
+    requestActivitySnapshots() {
+        return this.#client?.requestActivitySnapshots?.() ?? [];
+    }
+    async close() {
+        this.#closed = true;
+        if (this.#loading === undefined)
+            return;
+        const client = await this.#loading;
+        await client.close();
+    }
+    async #load() {
+        if (this.#closed)
+            throw new Error("Lazy analysis client is closed");
+        this.#loading ??= this.#loadClient()
+            .then((client) => {
+            this.#client = client;
+            return client;
+        })
+            .catch((cause) => {
+            this.#loading = undefined;
+            throw cause;
+        });
+        return this.#loading;
+    }
+}

package/dist/application/LoopbackReplay.js

@@ -374,11 +374,11 @@ export const startLoopbackReplay = async (scenario, recordEvent = () => undefine
         async close() {
             closePromise ??= (async () => {
                 recorder.stopMachineAdmission();
+                await recorder.drainMachine();
                 for (const client of websocket.clients)
                     client.terminate();
                 await new Promise((resolveClose) => websocket.close(() => resolveClose()));
                 await closeReplayServer(server);
-                await recorder.drainMachine();
             })();
             await closePromise;
         },

package/dist/application/NativeApiInspection.js

@@ -0,0 +1,80 @@
+import { nativeApiInspectionResultSchema, } from "../domain/nativeApiBoundary.js";
+const unavailableBoundary = () => ({
+    available: false,
+    reason: "The selected provider did not expose a structured native API boundary model.",
+    residual_unknowns: [
+        "What are the function's return and parameter boundary types?",
+        "Does this function dispatch through a jump table with recoverable data addresses?",
+    ],
+});
+/** Project one analyzed-function dossier into inspectable native API substeps. */
+export const projectNativeApiInspection = (dossier) => {
+    const boundary = dossier.native_api ?? unavailableBoundary();
+    const unsupportedBranches = boundary.available
+        ? []
+        : ["structured-boundary-types", "jump-table-data-mapping"];
+    const residualUnknowns = boundary.available
+        ? availableResidualUnknowns(boundary)
+        : boundary.residual_unknowns;
+    return nativeApiInspectionResultSchema.parse({
+        schema_version: 1,
+        procedure: {
+            address: dossier.procedure.address,
+            name: dossier.procedure.name,
+        },
+        boundary,
+        substeps: [
+            {
+                operation: "analyze_function",
+                status: "completed",
+                observations: [
+                    "provider function dossier",
+                    "provider pseudocode classification",
+                    "provider control-flow observations",
+                ],
+            },
+            {
+                operation: "project_native_api_boundary",
+                status: boundary.available ? "completed" : "unsupported",
+                observations: boundary.available
+                    ? [
+                        "return and parameter boundary types",
+                        "confidence and inference evidence",
+                        "jump-table dispatch, data, and target addresses",
+                    ]
+                    : [boundary.reason],
+            },
+            {
+                operation: "preserve_residual_unknowns",
+                status: "completed",
+                observations: residualUnknowns.length === 0
+                    ? ["no additional structured-boundary unknowns"]
+                    : residualUnknowns,
+            },
+        ],
+        unsupported_branches: unsupportedBranches,
+        residual_unknowns: residualUnknowns,
+    });
+};
+const availableResidualUnknowns = (boundary) => {
+    const unknowns = [];
+    if (boundary.parameters_truncated)
+        unknowns.push("Which additional parameters were omitted by the native API boundary limit?");
+    if (boundary.jump_tables_truncated)
+        unknowns.push("Which additional jump tables were omitted by the native API boundary limit?");
+    for (const table of boundary.jump_tables) {
+        if (table.data_sources_truncated || table.mappings_truncated)
+            unknowns.push(`Which additional data sources or targets were omitted for the jump table dispatched at ${table.dispatch_address}?`);
+        if (table.data_sources.length === 0)
+            unknowns.push(`What backing data address produced the jump table dispatched at ${table.dispatch_address}?`);
+        if (table.data_sources.some(({ entry_count: count, entry_size_bytes: size }) => count === null || size === null))
+            unknowns.push(`What are the exact entry size and count for candidate jump-table data dispatched at ${table.dispatch_address}?`);
+        if (table.mappings.some(({ case_value: value }) => value === null))
+            unknowns.push(`Which source-level case values correspond to every target dispatched at ${table.dispatch_address}?`);
+    }
+    for (const value of [boundary.return_type, ...boundary.parameters]) {
+        if (value.confidence === "low")
+            unknowns.push(`Can the inferred ${value.role} type ${value.data_type} be confirmed with imported metadata or an ABI probe?`);
+    }
+    return [...new Set(unknowns)];
+};

package/dist/application/SessionProviderRouter.js

@@ -26,7 +26,7 @@ export class SessionProviderRouter {
                 : (target, resolutionOptions) => provider.resolveAnalysisProfile?.(target, resolutionOptions) ??
                     Promise.resolve(ok({ profile: null, compatibility: {} })));
         return new SessionProviderRouter({
-            kind: "legacy",
+            kind: "single",
             provider,
             identity,
             capabilities,
@@ -61,7 +61,7 @@ export class SessionProviderRouter {
     }
     /** Provider identities exposed through the flat 1.x compatibility field. */
     providerIdentities(route) {
-        if (this.runtime.kind === "legacy") {
+        if (this.runtime.kind === "single") {
             if (route.capabilities === undefined)
                 return [route.identity];
             return uniqueProviderIdentities([...route.capabilities.values()].map(({ provider }) => provider));
@@ -86,7 +86,7 @@ export class SessionProviderRouter {
             compatibility: {},
             binding: null,
             selection: undefined,
-            createClient: (target, context) => createLegacyClient(runtime, target, undefined, context),
+            createClient: (target, context) => createSingleProviderClient(runtime, target, undefined, context),
         };
     }
     /** Resolve target routes before any provider client is created. */
@@ -122,12 +122,12 @@ export class SessionProviderRouter {
             compatibility: normalized.value.compatibility,
             binding: null,
             selection: undefined,
-            createClient: (openedTarget, context) => createLegacyClient(runtime, openedTarget, normalized.value.profile ?? undefined, context),
+            createClient: (openedTarget, context) => createSingleProviderClient(runtime, openedTarget, normalized.value.profile ?? undefined, context),
         });
     }
     /** Candidate status authoritative for the active or target-free route. */
     candidateStatuses(route) {
-        if (this.runtime.kind === "legacy")
+        if (this.runtime.kind === "single")
             return [];
         return route.selection?.candidates ?? this.runtime.registry.candidates();
     }
@@ -160,7 +160,7 @@ const selectableRoute = (auxiliaryProviders, selection) => {
             emptyClient(identity),
     };
 };
-const createLegacyClient = (runtime, target, profile, context) => typeof runtime.provider === "function"
+const createSingleProviderClient = (runtime, target, profile, context) => typeof runtime.provider === "function"
     ? runtime.provider(target, profile, context)
     : runtime.provider.createClient(target, profile, context);
 const emptyClient = (identity) => ({

package/dist/application/SetupClientConfiguration.js

@@ -5,6 +5,7 @@ import { z } from "zod";
 import writeFileAtomic from "write-file-atomic";
 import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
 import { PRODUCT_IDENTITY } from "../identity.js";
+import { MCP_STARTUP_POLICY } from "../mcpStartupPolicy.js";
 import { resolveClientConfigTransactionPath } from "./ClientConfigPath.js";
 const defaultCommand = () => [
     "npx",
@@ -12,7 +13,6 @@ const defaultCommand = () => [
     PRODUCT_IDENTITY.registrationPackageSpecifier,
     "mcp",
 ];
-const CODEX_STARTUP_TIMEOUT_SECONDS = 30;
 /** Back up, atomically update, and semantically read back one JSON MCP configuration. */
 export const configureJsonClient = async (client, environment = {}, command = defaultCommand()) => {
     const transactionPath = await resolveClientConfigTransactionPath(client.configPath);
@@ -214,7 +214,9 @@ const clientConfigurationDesired = (client, providerEnvironment, command) => {
         command: command[0] ?? PRODUCT_IDENTITY.cliBinary,
         args: command.slice(1),
         ...(client.name === "codex"
-            ? { startup_timeout_sec: CODEX_STARTUP_TIMEOUT_SECONDS }
+            ? {
+                startup_timeout_sec: MCP_STARTUP_POLICY.codexStartupTimeoutSeconds,
+            }
             : {}),
         ...(Object.keys(environment).length === 0 ? {} : { env: environment }),
     };

package/dist/application/runtime.js

@@ -1,12 +1,10 @@
-import { BinarySession } from "./BinarySession.js";
 import { HopperProvider } from "../hopper/HopperProvider.js";
 import { GhidraProvider } from "../ghidra/GhidraProvider.js";
-import { NativeMacOSProvider } from "../native/NativeMacOSProvider.js";
-import { ArtifactProvider } from "../artifacts/ArtifactProvider.js";
-import { ManagedStaticProvider } from "../dotnet/ManagedStaticProvider.js";
 import { silentLogger } from "../logger.js";
+import { GENERATED_AUXILIARY_PROVIDERS } from "../generatedMcpToolCatalog.js";
 import { AnalysisProviderRegistry } from "./AnalysisProviderRegistry.js";
-import { SessionProviderRouter } from "./SessionProviderRouter.js";
+import { composeBinarySession } from "./BinarySessionComposition.js";
+import { LazyAnalysisProvider } from "./LazyAnalysisProvider.js";
 /**
  * Compose the target-switching runtime shared directly by CLI and MCP adapters.
  * This is the sole production wiring point, so both adapters share identical
@@ -15,9 +13,28 @@ import { SessionProviderRouter } from "./SessionProviderRouter.js";
 export const createBinarySession = (config, logger = silentLogger) => {
     const hopper = new HopperProvider(config, logger);
     const ghidra = new GhidraProvider(config, logger);
-    return new BinarySession(SessionProviderRouter.selectable(new AnalysisProviderRegistry([hopper, ghidra], config.analysisProvider), [
-        new ArtifactProvider(config.artifactNativeMountEnabled, config.artifactIntegrityContinueEnabled),
-        new NativeMacOSProvider(),
-        new ManagedStaticProvider(),
+    const auxiliary = new Map(GENERATED_AUXILIARY_PROVIDERS.map((provider) => [
+        provider.identity.id,
+        provider,
     ]));
+    const lazyProvider = (id, load) => {
+        const generated = auxiliary.get(id);
+        if (generated === undefined)
+            throw new TypeError(`Missing generated provider metadata for ${id}`);
+        return new LazyAnalysisProvider({ ...generated, load });
+    };
+    return composeBinarySession(new AnalysisProviderRegistry([hopper, ghidra], config.analysisProvider), [
+        lazyProvider("rea-artifact-graph", async () => {
+            const { ArtifactProvider } = await import("../artifacts/ArtifactProvider.js");
+            return new ArtifactProvider(config.artifactNativeMountEnabled, config.artifactIntegrityContinueEnabled);
+        }),
+        lazyProvider("native-macos", async () => {
+            const { NativeMacOSProvider } = await import("../native/NativeMacOSProvider.js");
+            return new NativeMacOSProvider();
+        }),
+        lazyProvider("rea-dotnet-static", async () => {
+            const { ManagedStaticProvider } = await import("../dotnet/ManagedStaticProvider.js");
+            return new ManagedStaticProvider();
+        }),
+    ]);
 };

package/dist/browser/PlaywrightBrowserScenarioProvider.js

@@ -3,8 +3,14 @@ import { browserScenarioCaptureSchema, browserScenarioCompletenessSchema, browse
 import { AnalysisError, BrowserObservationError, ProviderAdapterError, } from "../domain/errors.js";
 import { err, ok } from "../domain/result.js";
 import { BrowserScenarioCaptureBudget } from "./PlaywrightScenarioArtifacts.js";
-import { PlaywrightScenarioSessionFactory } from "./PlaywrightScenarioSession.js";
 const OPERATION = "capture_browser_scenario";
+let defaultFactory;
+const lazyPlaywrightFactory = {
+    async open(scenario, options) {
+        defaultFactory ??= import("./PlaywrightScenarioSession.js").then(({ PlaywrightScenarioSessionFactory }) => new PlaywrightScenarioSessionFactory());
+        return (await defaultFactory).open(scenario, options);
+    },
+};
 export const PLAYWRIGHT_BROWSER_SCENARIO_PROVIDER_IDENTITY = Object.freeze({
     id: "rea-playwright-browser-scenario",
     name: "REA Playwright browser scenario capture provider",
@@ -234,7 +240,7 @@ const runScenario = async (factory, scenario, options) => {
 /** Controlled Playwright/CDP scenario driver with exact process ownership. */
 export class PlaywrightBrowserScenarioProvider {
     factory;
-    constructor(factory = new PlaywrightScenarioSessionFactory()) {
+    constructor(factory = lazyPlaywrightFactory) {
         this.factory = factory;
     }
     identity() {

package/dist/catalogIdentity.js

@@ -29,7 +29,7 @@ const promptCatalog = PROMPT_CONTRACTS.map((contract) => ({
 /** Canonical fixed resources exposed by every target-free MCP session. */
 export const MCP_RESOURCE_CATALOG = [
     { name: "server-identity", uri: "rea://server/identity" },
-    { name: "active-residual-unknowns", uri: "rea://unknowns/active" },
+    { name: "analysis-snapshot", uri: "rea://snapshot/current" },
 ];
 /** Canonical resource templates exposed by every target-free MCP session. */
 export const MCP_RESOURCE_TEMPLATE_CATALOG = [
@@ -40,8 +40,8 @@ export const MCP_RESOURCE_TEMPLATE_CATALOG = [
     },
     { name: "residual-unknown", uri_template: "rea://unknown/{unknownId}" },
     {
-        name: "analysis-snapshot",
-        uri_template: "rea://snapshot/{snapshotDigest}",
+        name: "evidence-bundle",
+        uri_template: "rea://evidence-bundle/{bundleDigest}",
     },
     {
         name: "artifact-page",

package/dist/cli/artifactCommands.js

@@ -73,17 +73,19 @@ const registerExtractionCommand = (cli, logger) => {
         args: z.object({
             path: z.string().describe("Application or package path"),
             outputRoot: z.string().describe("Absent absolute output root"),
+        }),
+        options: z.object({
             occurrenceIds: z
                 .array(z.string().regex(/^occ_[a-f0-9]{64}$/u))
                 .min(1)
                 .max(500)
                 .describe("Exact artifact occurrence IDs selected for extraction"),
         }),
-        alias: { outputRoot: "output-root", occurrenceIds: "occurrence-ids" },
-        run: ({ args }) => logCliCommand(logger, "extract-artifact", () => runProviderAnalysis(args.path, "extract_artifact", {
+        alias: { occurrenceIds: "occurrence-ids" },
+        run: ({ args, options }) => logCliCommand(logger, "extract-artifact", () => runProviderAnalysis(args.path, "extract_artifact", {
             approved: true,
             output_root: args.outputRoot,
-            occurrence_ids: args.occurrenceIds,
+            occurrence_ids: options.occurrenceIds,
         }, logger)),
     });
 };

package/dist/cli/coreAnalysisCommands.js

@@ -9,6 +9,7 @@ import { runCliJavaScriptApplicationAnalysis } from "./javascriptApplicationAnal
 export const registerCoreAnalysisCommands = (cli, logger) => {
     registerCoreCommands(cli, logger);
     registerFunctionCommand(cli, logger);
+    registerNativeApiCommand(cli, logger);
     registerInstructionsCommand(cli, logger);
     registerSearchCommand(cli, logger);
     registerXrefsCommand(cli, logger);
@@ -213,6 +214,46 @@ const registerFunctionCommand = (cli, logger) => {
         }, directAnalysisOptions(logger, options.snapshot, options.provider))),
     });
 };
+const registerNativeApiCommand = (cli, logger) => {
+    cli.command(CLI_COMMANDS.inspectNativeApi, {
+        description: "Reconstruct one native function API boundary with evidence",
+        args: z.object({
+            path: z.string().describe("App or program path"),
+            address: z.string().describe("Procedure name or address"),
+        }),
+        options: z.object({
+            maxPseudocodeChars: z
+                .number()
+                .int()
+                .min(1)
+                .max(100_000)
+                .default(20_000)
+                .describe("Maximum pseudocode characters to inspect"),
+            maxInstructions: z
+                .number()
+                .int()
+                .min(1)
+                .max(5_000)
+                .default(500)
+                .describe("Maximum assembly instructions to inspect"),
+            snapshot: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Load and update a local analysis snapshot"),
+            provider: providerSelectionOption,
+        }),
+        alias: {
+            maxPseudocodeChars: "max-pseudocode-chars",
+            maxInstructions: "max-instructions",
+        },
+        run: ({ args, options }) => logCliCommand(logger, "inspect-native-api", () => runDirectAnalysis(args.path, "inspect_native_api", {
+            procedure: args.address,
+            max_pseudocode_chars: options.maxPseudocodeChars,
+            max_instructions: options.maxInstructions,
+        }, directAnalysisOptions(logger, options.snapshot, options.provider))),
+    });
+};
 const registerInstructionsCommand = (cli, logger) => {
     cli.command(CLI_COMMANDS.instructions, {
         description: "Read one bounded raw-instruction window without decompiling",

package/dist/cliCommandNames.js

@@ -12,6 +12,7 @@ export const CLI_COMMANDS = Object.freeze({
     capabilities: "capabilities",
     providers: "providers",
     function: "function",
+    inspectNativeApi: "inspect-native-api",
     instructions: "instructions",
     search: "search",
     importReferenceSource: "import-reference-source",

package/dist/contracts/artifactToolContracts.js

@@ -1,3 +1,4 @@
+import { isAbsolute } from "node:path";
 import { z } from "zod";
 import { artifactOutputSchemas } from "./toolOutputSchemas.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
@@ -51,7 +52,11 @@ export const artifactInventoryInputSchema = z
 /** Exact caller boundary for approved artifact extraction. */
 export const artifactExtractionInputSchema = z.object({
     approved: z.literal(true),
-    output_root: z.string().min(1).max(4_096),
+    output_root: z
+        .string()
+        .min(1)
+        .max(4_096)
+        .refine(isAbsolute, "Extraction output root must be absolute"),
     occurrence_ids: z
         .array(z.string().regex(/^occ_[a-f0-9]{64}$/u))
         .min(1)
@@ -110,7 +115,7 @@ const artifact = (name, description, inputSchema) => {
 };
 /** Artifact-graph inventory and explicitly approved safe extraction contracts. */
 export const ARTIFACT_TOOL_CONTRACTS = [
-    artifact("inventory_artifact", "Inventory the active application or package as a deterministic, content-addressed artifact graph. Returns bounded node and edge pages without extracting or mounting by default.", artifactInventoryInputSchema),
-    artifact("inspect_artifact", "Inspect the active artifact through one bounded, cancellable inventory substep. Returns the full substep Evidence and its ID, observations, derived relationships, hypotheses, contradictions, unexplored branches, limitations, and format-specific next probes. Any substep failure fails the whole call.", artifactInspectionInputSchema),
+    artifact("inventory_artifact", "After open_binary binds a local archive, application package, or other artifact—or when one is already active—inventory it as a deterministic, content-addressed artifact graph. This tool accepts no path; in a target-free session open the target first. Returns bounded node and edge pages without extracting or mounting by default.", artifactInventoryInputSchema),
+    artifact("inspect_artifact", "After open_binary binds a local archive, application package, or other artifact—or when one is already active—inspect it through one bounded, cancellable inventory substep. This tool accepts no path; in a target-free session open the target first. Returns the full substep Evidence and its ID, observations, derived relationships, hypotheses, contradictions, unexplored branches, limitations, and format-specific next probes. Any substep failure fails the whole call.", artifactInspectionInputSchema),
     artifact("extract_artifact", "Extract selected graph artifacts beneath an explicit output root. Requires approval, rejects traversal and symlink escapes, never overwrites, enforces bomb limits, and verifies cleanup.", artifactExtractionInputSchema),
 ];

package/dist/contracts/enhancedInputs.js

@@ -61,6 +61,15 @@ export const enhancedInputSchemas = {
             basic_blocks: 0,
         }),
     }),
+    inspect_native_api: z.object({
+        procedure: z.string().describe("A procedure name or address"),
+        max_pseudocode_chars: z.number().int().min(1).max(100_000).default(20_000),
+        max_instructions: z.number().int().min(1).max(5_000).default(500),
+        unknown_registry_approved: z
+            .literal(true)
+            .optional()
+            .describe("Explicit approval to record unsupported native API branches durably"),
+    }),
     trace_feature: traceLiteralInputSchema,
     find_code_for_string: traceLiteralInputSchema,
     trace_call_path: z.object({
@@ -90,6 +99,7 @@ export const enhancedToolNameSchema = z.enum([
     "find_xrefs_to_name",
     "binary_overview",
     "analyze_function",
+    "inspect_native_api",
     "trace_feature",
     "find_code_for_string",
     "trace_call_path",

package/dist/contracts/functionWorkflowToolContracts.js

@@ -0,0 +1,30 @@
+import { jsonObjectSchema } from "../domain/jsonValue.js";
+import { enhancedInputSchemas } from "./enhancedInputs.js";
+import { TOOL_EXAMPLE_OVERRIDES } from "./toolContractExamples.js";
+import { toolContractMetadata } from "./toolEffects.js";
+import { enhancedOutputSchemas } from "./toolOutputSchemas.js";
+const functionWorkflow = (name, description) => {
+    const inputSchema = enhancedInputSchemas[name];
+    const outputSchema = enhancedOutputSchemas[name];
+    if (outputSchema === undefined)
+        throw new Error(`Missing function workflow output schema for ${name}`);
+    return {
+        name,
+        ...toolContractMetadata(name),
+        description,
+        kind: "enhanced",
+        inputSchema,
+        outputSchema,
+        examples: [
+            {
+                title: `Example ${name.replaceAll("_", " ")} request`,
+                input: jsonObjectSchema.parse(inputSchema.parse(TOOL_EXAMPLE_OVERRIDES[name] ?? {})),
+            },
+        ],
+    };
+};
+/** Function dossier and native API reconstruction workflow contracts. */
+export const FUNCTION_WORKFLOW_TOOL_CONTRACTS = [
+    functionWorkflow("analyze_function", "Preferred bounded analysis for one procedure symbol or address. Returns identity, provider-specific pseudocode, optional assembly, comments, calls, typed-or-explicitly-unavailable references, referenced strings/names, and local CFG blocks with exact truncation metadata. Providers with a structured decompiler model also expose native API boundary types, confidence, evidence, jump-table data/target addresses, and explicit decompiler-artifact labels."),
+    functionWorkflow("inspect_native_api", "Reconstruct one native function boundary through inspectable substeps. Returns structured inferred return/parameter types with confidence and evidence, jump-table dispatch/data/target mappings, explicit decompiler-artifact labels, unsupported branches, and residual unknowns."),
+];