@claudexor/harness-claude 3.0.4 → 3.1.1

package/dist/context-signals.d.ts

@@ -0,0 +1,52 @@
+import type { HarnessEvent } from "@claudexor/schema";
+/**
+ * D-16c: claude 2.1.165 typed context / rate-limit signal mapping, extracted
+ * from the main stream parser so each concern stays a small, testable owner.
+ * These map FIXTURE-PROVEN vendor frames onto typed HarnessEvents — no prose
+ * matching. Context signals are a sibling of the transient-retry taxonomy and
+ * NEVER enter the transient_retry loop.
+ */
+type Json = any;
+/**
+ * `system/compact_boundary` → a typed compaction context event. The boundary is
+ * the COMPLETION of a compaction; `trigger` (auto|manual) and `pre_tokens` ride
+ * through as evidence. The frame states no cause, so cause stays `unknown`.
+ */
+export declare function claudeCompactBoundaryEvents(obj: Json, sessionId: string, ts: string): HarnessEvent[];
+/**
+ * QA-015: the top-level typed `rate_limit_event` heartbeat. Always RECOGNIZED
+ * (never a dropped event). The routine `allowed` heartbeat surfaces NOTHING
+ * (arming a rate_limit signal on it would falsely trip the rotation predicate);
+ * only a limiting status arms the TYPED `rate_limit` signal the budget layer
+ * reads. Returns `[]` for the benign heartbeat.
+ */
+export declare function claudeRateLimitEvents(obj: Json, sessionId: string, ts: string): HarnessEvent[];
+/**
+ * Map the FIXTURE-PROVEN result `terminal_reason` values onto a typed
+ * context-exhaustion event (or null for `completed`/unrecognized). No prose
+ * matching — only the typed vendor enum. `prompt_too_long` is an irreducible-
+ * packet exhaustion (NOT continuation-eligible); `rapid_refill_breaker` is the
+ * SDK's repeated-refill breaker (the continuation-eligible cause).
+ */
+export declare function claudeTerminalContextEvent(terminalReason: unknown, sessionId: string, ts: string): HarnessEvent | null;
+/**
+ * D-16c side_tool: a `{work_report}`-ONLY structured_output (no `output` key) is
+ * the claude StructuredOutput-tool WorkReport envelope — the report rides the
+ * tool while the markdown final message stays the deliverable. Returns the raw
+ * work_report value, or undefined when the structured_output is a full
+ * `{work_report, output}` envelope / a plain caller-schema answer (both of
+ * which surface AS the final message).
+ */
+/**
+ * The final-message events a `result` frame emits (D-16c). Precedence:
+ * - a full `{work_report, output}` envelope / plain structured answer surfaces
+ *   AS the final message (`structured_output` finality);
+ * - otherwise the markdown `result` is the final message (side_tool rides its
+ *   WorkReport on the message payload);
+ * - a side_tool report with no deliverable text still surfaces (rare).
+ * Finality is stamped only for a success result.
+ */
+export declare function claudeResultMessageEvents(obj: Json, successResult: boolean, sessionId: string, ts: string): HarnessEvent[];
+export declare function claudeSideToolReport(structuredOutput: unknown): unknown;
+export {};
+//# sourceMappingURL=context-signals.d.ts.map

package/dist/context-signals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-signals.d.ts","sourceRoot":"","sources":["../src/context-signals.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD;;;;;;GAMG;AACH,KAAK,IAAI,GAAG,GAAG,CAAC;AAMhB;;;;GAIG;AACH,wBAAgB,2BAA2B,CACzC,GAAG,EAAE,IAAI,EACT,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,MAAM,GACT,YAAY,EAAE,CAkBhB;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,YAAY,EAAE,CAiB9F;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACxC,cAAc,EAAE,OAAO,EACvB,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,MAAM,GACT,YAAY,GAAG,IAAI,CA8BrB;AAED;;;;;;;GAOG;AACH;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,IAAI,EACT,aAAa,EAAE,OAAO,EACtB,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,MAAM,GACT,YAAY,EAAE,CAiDhB;AAED,wBAAgB,oBAAoB,CAAC,gBAAgB,EAAE,OAAO,GAAG,OAAO,CAWvE"}

package/dist/context-signals.js

@@ -0,0 +1,167 @@
+function numberOrNull(v) {
+    return typeof v === "number" ? v : null;
+}
+/**
+ * `system/compact_boundary` → a typed compaction context event. The boundary is
+ * the COMPLETION of a compaction; `trigger` (auto|manual) and `pre_tokens` ride
+ * through as evidence. The frame states no cause, so cause stays `unknown`.
+ */
+export function claudeCompactBoundaryEvents(obj, sessionId, ts) {
+    const meta = obj.compact_metadata && typeof obj.compact_metadata === "object" ? obj.compact_metadata : {};
+    const trigger = meta.trigger;
+    return [
+        {
+            type: "context",
+            session_id: sessionId,
+            ts,
+            context: {
+                kind: "compaction_completed",
+                cause: "unknown",
+                native_code: null,
+                trigger: trigger === "manual" || trigger === "auto" ? trigger : null,
+                pre_tokens: numberOrNull(meta.pre_tokens),
+            },
+        },
+    ];
+}
+/**
+ * QA-015: the top-level typed `rate_limit_event` heartbeat. Always RECOGNIZED
+ * (never a dropped event). The routine `allowed` heartbeat surfaces NOTHING
+ * (arming a rate_limit signal on it would falsely trip the rotation predicate);
+ * only a limiting status arms the TYPED `rate_limit` signal the budget layer
+ * reads. Returns `[]` for the benign heartbeat.
+ */
+export function claudeRateLimitEvents(obj, sessionId, ts) {
+    const info = obj.rate_limit_info && typeof obj.rate_limit_info === "object" ? obj.rate_limit_info : null;
+    const status = info ? info.status : undefined;
+    if (status !== "allowed_warning" && status !== "rejected" && status !== "blocked")
+        return [];
+    const resetsRaw = info ? info.resetsAt : undefined;
+    const resetsAt = typeof resetsRaw === "number" ? new Date(resetsRaw * 1000).toISOString() : null;
+    return [
+        {
+            type: "status",
+            session_id: sessionId,
+            ts,
+            text: `rate_limit_event: ${String(status)}`,
+            rate_limit: { resets_at: resetsAt, retry_delay_ms: null },
+            payload: { rate_limit_event: true },
+        },
+    ];
+}
+/**
+ * Map the FIXTURE-PROVEN result `terminal_reason` values onto a typed
+ * context-exhaustion event (or null for `completed`/unrecognized). No prose
+ * matching — only the typed vendor enum. `prompt_too_long` is an irreducible-
+ * packet exhaustion (NOT continuation-eligible); `rapid_refill_breaker` is the
+ * SDK's repeated-refill breaker (the continuation-eligible cause).
+ */
+export function claudeTerminalContextEvent(terminalReason, sessionId, ts) {
+    if (terminalReason === "prompt_too_long") {
+        return {
+            type: "context",
+            session_id: sessionId,
+            ts,
+            context: {
+                kind: "capacity_exhausted",
+                cause: "prompt_too_long",
+                native_code: "prompt_too_long",
+                trigger: null,
+                pre_tokens: null,
+            },
+        };
+    }
+    if (terminalReason === "rapid_refill_breaker") {
+        return {
+            type: "context",
+            session_id: sessionId,
+            ts,
+            context: {
+                kind: "capacity_exhausted",
+                cause: "repeated_refill",
+                native_code: "rapid_refill_breaker",
+                trigger: null,
+                pre_tokens: null,
+            },
+        };
+    }
+    return null;
+}
+/**
+ * D-16c side_tool: a `{work_report}`-ONLY structured_output (no `output` key) is
+ * the claude StructuredOutput-tool WorkReport envelope — the report rides the
+ * tool while the markdown final message stays the deliverable. Returns the raw
+ * work_report value, or undefined when the structured_output is a full
+ * `{work_report, output}` envelope / a plain caller-schema answer (both of
+ * which surface AS the final message).
+ */
+/**
+ * The final-message events a `result` frame emits (D-16c). Precedence:
+ * - a full `{work_report, output}` envelope / plain structured answer surfaces
+ *   AS the final message (`structured_output` finality);
+ * - otherwise the markdown `result` is the final message (side_tool rides its
+ *   WorkReport on the message payload);
+ * - a side_tool report with no deliverable text still surfaces (rare).
+ * Finality is stamped only for a success result.
+ */
+export function claudeResultMessageEvents(obj, successResult, sessionId, ts) {
+    const so = obj.structured_output;
+    const sideToolReport = claudeSideToolReport(so);
+    if (so !== undefined && so !== null && sideToolReport === undefined) {
+        return [
+            {
+                type: "message",
+                session_id: sessionId,
+                ts,
+                text: JSON.stringify(so),
+                ...(successResult ? { final: true } : {}),
+                payload: {
+                    structured_output: true,
+                    ...(successResult ? { final_source: "structured_output" } : {}),
+                },
+            },
+        ];
+    }
+    if (typeof obj.result === "string" && obj.result.trim()) {
+        return [
+            {
+                type: "message",
+                session_id: sessionId,
+                ts,
+                text: obj.result,
+                ...(successResult ? { final: true } : {}),
+                ...(successResult || sideToolReport !== undefined
+                    ? {
+                        payload: {
+                            ...(successResult ? { final_source: "result" } : {}),
+                            ...(sideToolReport !== undefined ? { work_report_side_tool: sideToolReport } : {}),
+                        },
+                    }
+                    : {}),
+            },
+        ];
+    }
+    if (sideToolReport !== undefined) {
+        return [
+            {
+                type: "status",
+                session_id: sessionId,
+                ts,
+                text: "work_report (side_tool, no deliverable text)",
+                payload: { work_report_side_tool: sideToolReport },
+            },
+        ];
+    }
+    return [];
+}
+export function claudeSideToolReport(structuredOutput) {
+    if (structuredOutput &&
+        typeof structuredOutput === "object" &&
+        !Array.isArray(structuredOutput) &&
+        "work_report" in structuredOutput &&
+        !("output" in structuredOutput)) {
+        return structuredOutput.work_report;
+    }
+    return undefined;
+}
+//# sourceMappingURL=context-signals.js.map

package/dist/context-signals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-signals.js","sourceRoot":"","sources":["../src/context-signals.ts"],"names":[],"mappings":"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"}

package/dist/effort-probe.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Effort discovery for the INSTALLED claude CLI.
+ *
+ * Claude Code's effort ladder is a property of the binary on this machine, not
+ * of Claudexor: 2.1.89 advertises `low, medium, high, max` while 2.1.165
+ * advertises `low, medium, high, xhigh, max`. Hardcoding either one means one
+ * installed version gets silently clamped, which is exactly the defect this
+ * replaces. So we read the ladder out of the binary's own `--help`.
+ *
+ * The help line looks like:
+ *   --effort <level>   Effort level for the current session (low, medium, high, xhigh, max)
+ * with the parenthesized list possibly wrapped onto following lines — and HOW FAR
+ * it wraps depends on the terminal width, so the parse reads the flag's whole
+ * block rather than a fixed number of lines.
+ *
+ * On a missing binary, an unparseable help text, or a `--help` that stops
+ * documenting the values, the recorded snapshot fills in and the run proceeds.
+ */
+import type { HarnessEvent, HarnessRunSpec } from "@claudexor/schema";
+import { EffortHint } from "@claudexor/schema";
+export declare const BIN: string;
+/**
+ * Recorded fallback, captured from `claude --help` on the CLI version stamped
+ * below. Used ONLY when the live parse cannot answer.
+ */
+export declare const CLAUDE_EFFORT_SNAPSHOT: readonly EffortHint[];
+/** Vendor CLI version `CLAUDE_EFFORT_SNAPSHOT` was captured from. */
+export declare const CLAUDE_EFFORT_SNAPSHOT_VERIFIED_AGAINST = "2.1.165";
+/**
+ * Whether the recorded snapshot may be TRUSTED for arg emission against the
+ * installed binary (INV-105). The snapshot is another `--help`'s recorded
+ * answer, so it is only that binary's truth on the exact CLI version it was
+ * captured from: 2.1.165 advertises `xhigh`, 2.1.89 rejects it, and a 2.1.89
+ * install whose live parse failed used to be handed the 2.1.165 ladder anyway
+ * — `--effort xhigh` then went to a CLI that refuses the flag.
+ *
+ * The installed version string is whatever `claude --version` printed
+ * (e.g. `2.1.165 (Claude Code)`), so the comparison extracts the full dotted
+ * numeric token and requires it to EQUAL the snapshot stamp exactly. An
+ * unknown or unparseable version can never vouch for the snapshot.
+ */
+export declare function claudeSnapshotTrustedForVersion(installedVersion: string | null): boolean;
+/**
+ * The effort ladder the RUN may resolve `--effort` against, version-gating
+ * snapshot trust (INV-105):
+ *
+ * - a LIVE parse is the installed binary's own answer — trusted on any version;
+ * - the snapshot FALLBACK is trusted only when the installed version equals
+ *   `CLAUDE_EFFORT_SNAPSHOT_VERIFIED_AGAINST` (same binary, same ladder);
+ * - a fallback on ANY OTHER version (mismatch, unknown, unparseable) yields an
+ *   EMPTY ladder: the normalizer then sends no `--effort` flag at all, and the
+ *   existing drop seam (`claudeEffortIgnoredEvent`) discloses it — the run
+ *   proceeds at the vendor default rather than forwarding a level another
+ *   version's snapshot advertises to a binary that may reject it.
+ */
+export declare function claudeAdvertisedEffortsForRun(efforts: {
+    levels: readonly EffortHint[];
+    live: boolean;
+}, installedVersion: string | null): readonly EffortHint[];
+/**
+ * The RUN's whole INV-105 effort seam in one place: probe the installed
+ * binary's ladder, version-gate snapshot-fallback trust
+ * (`claudeAdvertisedEffortsForRun`), and derive the DROP/CLAMP disclosure on
+ * the SAME advertised list the arg builder will resolve against — so the flag
+ * sent and the disclosure emitted can never disagree. The `--version` spawn
+ * happens only when it can matter (fallback ladder AND an effort actually
+ * requested); a live parse or a hint-less run never pays for it.
+ */
+export declare function claudeRunEffortResolution(spec: Pick<HarnessRunSpec, "session_id" | "effort_hint">, deps: {
+    probeEffortLevels: typeof probeClaudeEffortLevels;
+    detectVersion: (abortSignal?: AbortSignal) => Promise<string | null>;
+}, abortSignal?: AbortSignal): Promise<{
+    advertised: readonly EffortHint[];
+    disclosure: HarnessEvent | null;
+}>;
+/**
+ * Pull the advertised levels out of `claude --help` text, or null when the
+ * `--effort` line is absent or documents no values.
+ *
+ * Pure and separately testable: the spawn lives in the adapter's runtime deps so
+ * a test can feed recorded help text for any CLI version.
+ */
+export declare function parseClaudeEffortHelp(help: string): EffortHint[] | null;
+type ClaudeHelpProbe = {
+    ok: true;
+    help: string;
+    code: number | null;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * The shared capture, with the caller's cancellation bounding only the CALLER'S
+ * OWN wait. An abandoned caller reads a probe failure — its run is going away
+ * anyway, and the ladder falls back to the snapshot for that one run — while the
+ * capture keeps running for everybody else.
+ */
+export declare function probeClaudeHelp(abortSignal?: AbortSignal): Promise<ClaudeHelpProbe>;
+/**
+ * The effort ladder the INSTALLED claude binary advertises, falling back to the
+ * recorded snapshot when `--help` cannot be read or no longer documents the
+ * values. A probe failure costs freshness, never the run.
+ */
+export declare function probeClaudeEffortLevels(abortSignal?: AbortSignal): Promise<{
+    levels: readonly EffortHint[];
+    live: boolean;
+}>;
+/**
+ * The INV-105 disclosure for an effort the RUN itself could not honor, or null
+ * when nothing was dropped. Preflight validates against the manifest ladder,
+ * but the arg builder resolves against what the INSTALLED binary advertises at
+ * run time (an older CLI's `--help` can be narrower than the discovered
+ * manifest), and its normalizer answers "send no flag" — which without this
+ * event was a silent vendor-default run. The payload rides the same
+ * `ignored_settings` channel governance uses (QA-070 timeline warning).
+ */
+export declare function claudeEffortIgnoredEvent(spec: Pick<HarnessRunSpec, "session_id" | "effort_hint">, advertised: readonly EffortHint[]): HarnessEvent | null;
+/**
+ * The INV-105 disclosure for an effort the resolution CLAMPED, or null when the
+ * level rode through verbatim (or was dropped — `claudeEffortIgnoredEvent`'s
+ * shape; the two are mutually exclusive: a drop sends no flag, a clamp sends a
+ * different one). Mirrors the codex clamp seam so a moved level is disclosed
+ * the same way on both adapters, and takes the SAME (advertised, ladder)
+ * inputs the arg builder's normalizer takes so the disclosure can never
+ * disagree with the flag actually sent.
+ *
+ * Reachability today: the arg builder resolves with the installed binary's own
+ * list as both advertised set and rank ladder (`normalizeEffort`'s two-arg
+ * form), and against one's own ladder every miss is a DROP, never a clamp —
+ * so with current call sites this event only fires if a rank ladder broader
+ * than the binary's list is ever threaded through (the codex-shaped future,
+ * e.g. `ultra` ranking above a max-capped binary and clamping onto `max`).
+ * The seam exists precisely so that future cannot be silent.
+ */
+/**
+ * The one INV-105 seam the run yields: the DROP disclosure or the CLAMP
+ * disclosure, whichever applies (they are mutually exclusive by construction —
+ * a drop sends no flag, a clamp sends a different one), or null when the
+ * requested level rode through verbatim or nothing was requested.
+ */
+export declare function claudeEffortDisclosureEvent(spec: Pick<HarnessRunSpec, "session_id" | "effort_hint">, advertised: readonly EffortHint[]): HarnessEvent | null;
+export declare function claudeEffortClampedEvent(spec: Pick<HarnessRunSpec, "session_id" | "effort_hint">, advertised: readonly EffortHint[], ladder?: readonly EffortHint[]): HarnessEvent | null;
+export {};
+//# sourceMappingURL=effort-probe.d.ts.map

package/dist/effort-probe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effort-probe.d.ts","sourceRoot":"","sources":["../src/effort-probe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACtE,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAI/C,eAAO,MAAM,GAAG,QAA+C,CAAC;AAEhE;;;GAGG;AACH,eAAO,MAAM,sBAAsB,EAAE,SAAS,UAAU,EAMvD,CAAC;AAEF,qEAAqE;AACrE,eAAO,MAAM,uCAAuC,YAAY,CAAC;AAEjE;;;;;;;;;;;;GAYG;AACH,wBAAgB,+BAA+B,CAAC,gBAAgB,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAIxF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE;IAAE,MAAM,EAAE,SAAS,UAAU,EAAE,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,EACzD,gBAAgB,EAAE,MAAM,GAAG,IAAI,GAC9B,SAAS,UAAU,EAAE,CAGvB;AAED;;;;;;;;GAQG;AACH,wBAAsB,yBAAyB,CAC7C,IAAI,EAAE,IAAI,CAAC,cAAc,EAAE,YAAY,GAAG,aAAa,CAAC,EACxD,IAAI,EAAE;IACJ,iBAAiB,EAAE,OAAO,uBAAuB,CAAC;IAClD,aAAa,EAAE,CAAC,WAAW,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CACtE,EACD,WAAW,CAAC,EAAE,WAAW,GACxB,OAAO,CAAC;IAAE,UAAU,EAAE,SAAS,UAAU,EAAE,CAAC;IAAC,UAAU,EAAE,YAAY,GAAG,IAAI,CAAA;CAAE,CAAC,CAOjF;AAUD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,EAAE,GAAG,IAAI,CA2CvE;AAqCD,KAAK,eAAe,GAClB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAoEjF;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,WAAW,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC,CAYnF;AAED;;;;GAIG;AACH,wBAAsB,uBAAuB,CAC3C,WAAW,CAAC,EAAE,WAAW,GACxB,OAAO,CAAC;IAAE,MAAM,EAAE,SAAS,UAAU,EAAE,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC,CAI3D;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,IAAI,CAAC,cAAc,EAAE,YAAY,GAAG,aAAa,CAAC,EACxD,UAAU,EAAE,SAAS,UAAU,EAAE,GAChC,YAAY,GAAG,IAAI,CAsBrB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH;;;;;GAKG;AACH,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,IAAI,CAAC,cAAc,EAAE,YAAY,GAAG,aAAa,CAAC,EACxD,UAAU,EAAE,SAAS,UAAU,EAAE,GAChC,YAAY,GAAG,IAAI,CAErB;AAED,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,IAAI,CAAC,cAAc,EAAE,YAAY,GAAG,aAAa,CAAC,EACxD,UAAU,EAAE,SAAS,UAAU,EAAE,EACjC,MAAM,GAAE,SAAS,UAAU,EAAe,GACzC,YAAY,GAAG,IAAI,CAerB"}