@claudexor/core 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 joi-lab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,7 @@
+# @claudexor/core
+
+Internal package of [Claudexor](https://github.com/razzant/claudexor) — HarnessAdapter contract, process helpers, typed errors, and low-level execution utilities.
+
+Published as part of the Claudexor toolchain; it follows the monorepo's
+lockstep version and has no separate semver contract. Use the `claudexor`
+CLI (or `@claudexor/cli`) as the supported entry point.

package/dist/adapter.d.ts

@@ -0,0 +1,56 @@
+import type { AuthPreference, ConformanceReport, HarnessEvent, HarnessManifest, HarnessModel, HarnessRunSpec, InteractionAnswerSet, InteractionRequest } from "@claudexor/schema";
+export interface DoctorSpec {
+    cwd: string;
+    /** Optional scoped env for probes that must mirror a concrete run route. */
+    env?: Record<string, string | null | undefined>;
+    /** Optional auth route preference for probes that must mirror a concrete run route. */
+    authPreference?: AuthPreference;
+}
+/**
+ * The contract every harness adapter implements. Adapters translate a native
+ * harness's I/O into typed Claudexor events — they never contain orchestration
+ * logic. External adapters may implement this as an in-tree HarnessAdapter implementation (the out-of-tree JSON-RPC bridge package was removed in v0.9).
+ */
+export interface HarnessAdapter {
+    readonly id: string;
+    /** Detect installation/version/auth and declare capabilities. */
+    discover(): Promise<HarnessManifest>;
+    /** Probe capabilities and report which intents this adapter may play. */
+    doctor(spec: DoctorSpec): Promise<ConformanceReport>;
+    /** Run a task, streaming normalized events. */
+    run(spec: HarnessRunSpec): AsyncIterable<HarnessEvent>;
+    /** Optional dedicated review path (defaults to run with intent=review). */
+    review?(spec: HarnessRunSpec): AsyncIterable<HarnessEvent>;
+    /**
+     * Optional model enumeration. Only adapters that can HONESTLY list models
+     * implement this (e.g. raw-api via OpenAI-compatible `GET /v1/models`);
+     * native-CLI adapters that cannot enumerate simply omit it. Must fail soft
+     * (return [] on network/auth error) — never throw into a picker/consumer.
+     */
+    models?(spec?: DoctorSpec): Promise<HarnessModel[]>;
+    /** Optional cancellation. */
+    cancel?(sessionId: string): Promise<void>;
+}
+/** A registry of available adapters keyed by harness id. */
+export type AdapterRegistry = Map<string, HarnessAdapter>;
+/**
+ * Imperative answer channel for interactive harness sessions.
+ *
+ * The adapter calls `request()` when its native session raises a user
+ * question (e.g. Claude's AskUserQuestion via the stream-json control
+ * protocol) and BLOCKS that tool until the promise resolves:
+ * - resolved with answers -> the adapter delivers them into the live session;
+ * - resolved with null (timeout / decline / no listener) -> the adapter
+ *   declines benignly and the model continues with assumptions.
+ *
+ * The channel is smuggled through `spec.extra` (duck-typed, same pattern as
+ * the abort signal) because HarnessRunSpec is a serializable schema shape.
+ */
+export interface InteractionChannel {
+    request(req: InteractionRequest): Promise<InteractionAnswerSet | null>;
+    /** Number of questions currently awaiting an answer. Lets stream watchdogs
+     * treat waiting-on-user as legitimate silence instead of a wedged harness. */
+    pendingCount?(): number;
+}
+export declare function interactionChannelFromSpec(spec: HarnessRunSpec): InteractionChannel | undefined;
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,iBAAiB,EACjB,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,cAAc,EACd,oBAAoB,EACpB,kBAAkB,EACnB,MAAM,mBAAmB,CAAC;AAE3B,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,4EAA4E;IAC5E,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IAChD,uFAAuF;IACvF,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB,iEAAiE;IACjE,QAAQ,IAAI,OAAO,CAAC,eAAe,CAAC,CAAC;IAErC,yEAAyE;IACzE,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAErD,+CAA+C;IAC/C,GAAG,CAAC,IAAI,EAAE,cAAc,GAAG,aAAa,CAAC,YAAY,CAAC,CAAC;IAEvD,2EAA2E;IAC3E,MAAM,CAAC,CAAC,IAAI,EAAE,cAAc,GAAG,aAAa,CAAC,YAAY,CAAC,CAAC;IAE3D;;;;;OAKG;IACH,MAAM,CAAC,CAAC,IAAI,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IAEpD,6BAA6B;IAC7B,MAAM,CAAC,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3C;AAED,4DAA4D;AAC5D,MAAM,MAAM,eAAe,GAAG,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;AAE1D;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,kBAAkB;IACjC,OAAO,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAAC;IACvE;kFAC8E;IAC9E,YAAY,CAAC,IAAI,MAAM,CAAC;CACzB;AAED,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,cAAc,GAAG,kBAAkB,GAAG,SAAS,CAK/F"}

package/dist/adapter.js

@@ -0,0 +1,8 @@
+export function interactionChannelFromSpec(spec) {
+    const channel = spec.extra?.["interactionChannel"];
+    if (!channel || typeof channel !== "object")
+        return undefined;
+    const candidate = channel;
+    return typeof candidate.request === "function" ? channel : undefined;
+}
+//# sourceMappingURL=adapter.js.map

package/dist/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AA0EA,MAAM,UAAU,0BAA0B,CAAC,IAAoB;IAC7D,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC,oBAAoB,CAAC,CAAC;IACnD,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAC9D,MAAM,SAAS,GAAG,OAAsC,CAAC;IACzD,OAAO,OAAO,SAAS,CAAC,OAAO,KAAK,UAAU,CAAC,CAAC,CAAE,OAA8B,CAAC,CAAC,CAAC,SAAS,CAAC;AAC/F,CAAC"}

package/dist/browser-mcp.d.ts

@@ -0,0 +1,18 @@
+import type { BrowserToolSpec } from "@claudexor/schema";
+/**
+ * Resolve a usable `npx` for spawning the Playwright browser MCP. Prefer the
+ * bundled node's npx (the daemon runs under the notarized node, so `npx` sits
+ * alongside `node`), fall back to PATH `npx`; an explicit env override wins for
+ * unusual layouts. Centralized so every adapter's browser injection agrees.
+ */
+export declare function resolveNpxBin(): string;
+/**
+ * The argv (after `npx`) that launches the Playwright MCP server for a run's
+ * BrowserToolSpec: an isolated profile, core+pdf capabilities, headed by default
+ * (a real visible window the user watches), and an output dir pointed at the run
+ * artifact tree so captures surface in the Canvas gallery. Adapters wrap this in
+ * their own MCP-injection flag (codex `-c mcp_servers.*` overrides, claude
+ * `--mcp-config` inline JSON).
+ */
+export declare function playwrightMcpArgs(browser: BrowserToolSpec): string[];
+//# sourceMappingURL=browser-mcp.d.ts.map

package/dist/browser-mcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-mcp.d.ts","sourceRoot":"","sources":["../src/browser-mcp.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEzD;;;;;GAKG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAKtC;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,EAAE,CAKpE"}

package/dist/browser-mcp.js

@@ -0,0 +1,32 @@
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+/**
+ * Resolve a usable `npx` for spawning the Playwright browser MCP. Prefer the
+ * bundled node's npx (the daemon runs under the notarized node, so `npx` sits
+ * alongside `node`), fall back to PATH `npx`; an explicit env override wins for
+ * unusual layouts. Centralized so every adapter's browser injection agrees.
+ */
+export function resolveNpxBin() {
+    const override = process.env.CLAUDEXOR_NPX_BIN;
+    if (override)
+        return override;
+    const bundled = join(dirname(process.execPath), "npx");
+    return existsSync(bundled) ? bundled : "npx";
+}
+/**
+ * The argv (after `npx`) that launches the Playwright MCP server for a run's
+ * BrowserToolSpec: an isolated profile, core+pdf capabilities, headed by default
+ * (a real visible window the user watches), and an output dir pointed at the run
+ * artifact tree so captures surface in the Canvas gallery. Adapters wrap this in
+ * their own MCP-injection flag (codex `-c mcp_servers.*` overrides, claude
+ * `--mcp-config` inline JSON).
+ */
+export function playwrightMcpArgs(browser) {
+    const args = ["-y", "@playwright/mcp@latest", "--isolated", "--caps=core,pdf"];
+    if (browser.headless)
+        args.push("--headless");
+    if (browser.output_dir)
+        args.push(`--output-dir=${browser.output_dir}`);
+    return args;
+}
+//# sourceMappingURL=browser-mcp.js.map

package/dist/browser-mcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-mcp.js","sourceRoot":"","sources":["../src/browser-mcp.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAG1C;;;;;GAKG;AACH,MAAM,UAAU,aAAa;IAC3B,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC;IAC/C,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAC9B,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC,CAAC;IACvD,OAAO,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC;AAC/C,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAwB;IACxD,MAAM,IAAI,GAAG,CAAC,IAAI,EAAE,wBAAwB,EAAE,YAAY,EAAE,iBAAiB,CAAC,CAAC;IAC/E,IAAI,OAAO,CAAC,QAAQ;QAAE,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IAC9C,IAAI,OAAO,CAAC,UAAU;QAAE,IAAI,CAAC,IAAI,CAAC,gBAAgB,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;IACxE,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/capabilities.d.ts

@@ -0,0 +1,4 @@
+import type { HarnessCapabilityProfile } from "@claudexor/schema";
+export declare function needsScopedHomeKeychainBridge(profile: HarnessCapabilityProfile): boolean;
+export declare function readonlyMechanism(profile: HarnessCapabilityProfile): string;
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAElE,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAKxF;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,MAAM,CAE3E"}

package/dist/capabilities.js

@@ -0,0 +1,8 @@
+export function needsScopedHomeKeychainBridge(profile) {
+    return (profile.isolation.supported_containment.includes("scoped_home_keychain_bridge") &&
+        profile.auth.credential_transports.some((t) => t.kind === "os_keychain" && t.relocatable_by.includes("HOME")));
+}
+export function readonlyMechanism(profile) {
+    return profile.access_control.readonly_mechanism;
+}
+//# sourceMappingURL=capabilities.js.map

package/dist/capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,6BAA6B,CAAC,OAAiC;IAC7E,OAAO,CACL,OAAO,CAAC,SAAS,CAAC,qBAAqB,CAAC,QAAQ,CAAC,6BAA6B,CAAC;QAC/E,OAAO,CAAC,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,aAAa,IAAI,CAAC,CAAC,cAAc,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAC9G,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,OAAiC;IACjE,OAAO,OAAO,CAAC,cAAc,CAAC,kBAAkB,CAAC;AACnD,CAAC"}

package/dist/conformance.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Typed-event conformance stats for one parsed adapter stream. Shared by the
+ * per-adapter fixture parity tests: every adapter must emit schema-valid
+ * events, tool_results MUST carry a status (a statusless result is treated as
+ * dropped/diagnostic by the engine, never as ok), and streams that perform
+ * tool work must surface typed tool_call/tool_result pairs.
+ */
+export interface StreamConformanceStats {
+    total: number;
+    started: number;
+    messages: number;
+    toolCalls: number;
+    toolResults: number;
+    statuslessToolResults: number;
+    errorToolResults: number;
+    deniedToolResults: number;
+    cancelledToolResults: number;
+    fileChanges: number;
+    usageEvents: number;
+    errors: number;
+    completed: number;
+}
+/** Validate every event against the HarnessEvent schema and aggregate stats. */
+export declare function validateTypedStream(events: unknown[]): StreamConformanceStats;
+//# sourceMappingURL=conformance.d.ts.map

package/dist/conformance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conformance.d.ts","sourceRoot":"","sources":["../src/conformance.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,gBAAgB,EAAE,MAAM,CAAC;IACzB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,oBAAoB,EAAE,MAAM,CAAC;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,gFAAgF;AAChF,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,sBAAsB,CAsC7E"}

package/dist/conformance.js

@@ -0,0 +1,60 @@
+import { HarnessEvent } from "@claudexor/schema";
+/** Validate every event against the HarnessEvent schema and aggregate stats. */
+export function validateTypedStream(events) {
+    const stats = {
+        total: 0,
+        started: 0,
+        messages: 0,
+        toolCalls: 0,
+        toolResults: 0,
+        statuslessToolResults: 0,
+        errorToolResults: 0,
+        deniedToolResults: 0,
+        cancelledToolResults: 0,
+        fileChanges: 0,
+        usageEvents: 0,
+        errors: 0,
+        completed: 0,
+    };
+    for (const raw of events) {
+        const ev = HarnessEvent.parse(raw); // throws loudly on contract violations
+        stats.total += 1;
+        switch (ev.type) {
+            case "started":
+                stats.started += 1;
+                break;
+            case "message":
+                stats.messages += 1;
+                break;
+            case "tool_call":
+                stats.toolCalls += 1;
+                break;
+            case "tool_result":
+                stats.toolResults += 1;
+                if (!ev.tool?.status)
+                    stats.statuslessToolResults += 1;
+                if (ev.tool?.status === "error")
+                    stats.errorToolResults += 1;
+                if (ev.tool?.status === "denied")
+                    stats.deniedToolResults += 1;
+                if (ev.tool?.status === "cancelled")
+                    stats.cancelledToolResults += 1;
+                break;
+            case "file_change":
+                stats.fileChanges += 1;
+                break;
+            case "usage":
+                stats.usageEvents += 1;
+                break;
+            case "error":
+                stats.errors += 1;
+                break;
+            case "completed":
+                stats.completed += 1;
+                break;
+            default: break;
+        }
+    }
+    return stats;
+}
+//# sourceMappingURL=conformance.js.map

package/dist/conformance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conformance.js","sourceRoot":"","sources":["../src/conformance.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAyBjD,gFAAgF;AAChF,MAAM,UAAU,mBAAmB,CAAC,MAAiB;IACnD,MAAM,KAAK,GAA2B;QACpC,KAAK,EAAE,CAAC;QACR,OAAO,EAAE,CAAC;QACV,QAAQ,EAAE,CAAC;QACX,SAAS,EAAE,CAAC;QACZ,WAAW,EAAE,CAAC;QACd,qBAAqB,EAAE,CAAC;QACxB,gBAAgB,EAAE,CAAC;QACnB,iBAAiB,EAAE,CAAC;QACpB,oBAAoB,EAAE,CAAC;QACvB,WAAW,EAAE,CAAC;QACd,WAAW,EAAE,CAAC;QACd,MAAM,EAAE,CAAC;QACT,SAAS,EAAE,CAAC;KACb,CAAC;IACF,KAAK,MAAM,GAAG,IAAI,MAAM,EAAE,CAAC;QACzB,MAAM,EAAE,GAAG,YAAY,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,uCAAuC;QAC3E,KAAK,CAAC,KAAK,IAAI,CAAC,CAAC;QACjB,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC;YAChB,KAAK,SAAS;gBAAE,KAAK,CAAC,OAAO,IAAI,CAAC,CAAC;gBAAC,MAAM;YAC1C,KAAK,SAAS;gBAAE,KAAK,CAAC,QAAQ,IAAI,CAAC,CAAC;gBAAC,MAAM;YAC3C,KAAK,WAAW;gBAAE,KAAK,CAAC,SAAS,IAAI,CAAC,CAAC;gBAAC,MAAM;YAC9C,KAAK,aAAa;gBAChB,KAAK,CAAC,WAAW,IAAI,CAAC,CAAC;gBACvB,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM;oBAAE,KAAK,CAAC,qBAAqB,IAAI,CAAC,CAAC;gBACvD,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO;oBAAE,KAAK,CAAC,gBAAgB,IAAI,CAAC,CAAC;gBAC7D,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,QAAQ;oBAAE,KAAK,CAAC,iBAAiB,IAAI,CAAC,CAAC;gBAC/D,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,WAAW;oBAAE,KAAK,CAAC,oBAAoB,IAAI,CAAC,CAAC;gBACrE,MAAM;YACR,KAAK,aAAa;gBAAE,KAAK,CAAC,WAAW,IAAI,CAAC,CAAC;gBAAC,MAAM;YAClD,KAAK,OAAO;gBAAE,KAAK,CAAC,WAAW,IAAI,CAAC,CAAC;gBAAC,MAAM;YAC5C,KAAK,OAAO;gBAAE,KAAK,CAAC,MAAM,IAAI,CAAC,CAAC;gBAAC,MAAM;YACvC,KAAK,WAAW;gBAAE,KAAK,CAAC,SAAS,IAAI,CAAC,CAAC;gBAAC,MAAM;YAC9C,OAAO,CAAC,CAAC,MAAM;QACjB,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/diff.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The ONE quote-aware unified-diff header parser. Three divergent parsers
+ * used to read patches: a regex in the orchestrator's diffStats that
+ * missed git-quoted headers (non-ASCII/spaces → protected-path and
+ * NEEDS_HUMAN gates silently skipped those files), a line-scan in the
+ * delivery gate that read `--- `-prefixed CONTENT lines as paths (SQL
+ * comments → false apply refusals), and a header tokenizer in
+ * context/evidence that never decoded octal escapes. All three rebase here.
+ *
+ * Structural rules, not regex governance: file metadata (`---`/`+++`,
+ * `rename from/to`, `new/deleted file mode`, binary markers) is honored only
+ * in HEADER position — between a `diff --git` line and that file's first
+ * `@@` hunk — so patch CONTENT can never masquerade as structure.
+ *
+ * PLAIN unified diffs (GNU `diff -ruN`, the workspace's non-git in-place
+ * fallback) have no `diff --git` anchors, so a document that opens with a
+ * plain file header is parsed in PLAIN mode: a file entry opens only on the
+ * full structural triple — a `--- ` line immediately followed by a `+++ `
+ * line and an `@@` hunk header — which keeps deleted `-- sql` content lines
+ * from masquerading as file boundaries. Without this mode every non-git
+ * in-place diff summarized to zero files, silently blinding diffstat and
+ * protected-path/risk gating for that whole run class. Inside a git-anchored
+ * document the git rules above apply unchanged (never mixed per document).
+ * Plain-mode entries default to modified (GNU diff marks absent files with
+ * epoch timestamps, not `/dev/null`, so added/deleted classification is
+ * honored only for explicit `/dev/null` headers) — conservative for gating:
+ * every touched path is visible to policy.
+ */
+export interface DiffFileEntry {
+    /** Pre-image path (null when the file is newly added). */
+    oldPath: string | null;
+    /** Post-image path (null when the file is deleted). */
+    newPath: string | null;
+    added: boolean;
+    deleted: boolean;
+    renamed: boolean;
+    /** Binary change (GIT binary patch payload or a bare "Binary files" stub). */
+    binary: boolean;
+    /** True when the binary change carries NO applyable payload (stub). */
+    binaryStub: boolean;
+}
+export interface UnifiedDiffSummary {
+    files: DiffFileEntry[];
+    additions: number;
+    deletions: number;
+    hunks: number;
+}
+/**
+ * Decode one git C-quoted path token: strips surrounding quotes and decodes
+ * `\ooo` octal byte escapes plus the standard single-char escapes, yielding
+ * the real on-disk path (utf8).
+ */
+export declare function cUnquoteGitPath(raw: string): string;
+export declare function parseUnifiedDiff(diff: string): UnifiedDiffSummary;
+export interface DiffPathSummary {
+    paths: string[];
+    addedPaths: string[];
+    modifiedPaths: string[];
+    existingPaths: string[];
+    additions: number;
+    deletions: number;
+}
+/**
+ * Path-oriented projection of a unified diff for policy/risk gating and
+ * diffstat honesty: which files the patch touches, which are NEW vs
+ * pre-existing, and the +/- counts. Quote-aware via parseUnifiedDiff — a
+ * git-quoted header (non-ASCII, spaces) must never silently DROP a file
+ * from protected-path/NEEDS_HUMAN classification.
+ */
+export declare function summarizeDiffPaths(diff: string): DiffPathSummary;
+//# sourceMappingURL=diff.d.ts.map

package/dist/diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.d.ts","sourceRoot":"","sources":["../src/diff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,MAAM,WAAW,aAAa;IAC5B,0DAA0D;IAC1D,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,uDAAuD;IACvD,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,8EAA8E;IAC9E,MAAM,EAAE,OAAO,CAAC;IAChB,uEAAuE;IACvE,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CA+BnD;AAmDD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,CA6JjE;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CA0BhE"}