scoutline 0.23.0 → 0.24.0

package/README.md

@@ -416,7 +416,7 @@ executor preflight, Provider selection, and `doctor`.
 | `search` | Yes | Yes | Yes | Yes | Yes (incl. `type: "video"`) | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Parallel (declarative semantic), Jina (neural web search) |
 | `vision.interpret-image` (analyze) | Yes | Yes | No | No | No | No | No | No | No | No | No | No | No | No | No | Provider-specific media limits; uncached |
 | `vision.ui-artifact` (ui-to-code) | Yes | Available | No | No | No | No | No | No | No | No | No | No | No | No | No | Live-attested; conformance-gated |
-| `vision.extract-text` | Yes | Pending | No | No | No | No | No | No | No | No | No | No | No | No | No | Implemented, pending live conformance |
+| `vision.extract-text` | Yes (GLM-OCR engine: PDF ≤50MB, images ≤10MB, content-hash cached; exhaustion falls back to the vision model) | Pending | No | No | No | No | No | No | No | No | No | No | No | No | No | Implemented, pending live conformance |
 | `vision.diagnose-error` | Yes | Available | No | No | No | No | No | No | No | No | No | No | No | No | No | Live-attested; conformance-gated |
 | `vision.diagram` | Yes | Pending | No | No | No | No | No | No | No | No | No | No | No | No | No | Implemented, pending live conformance |
 | `vision.chart` | Yes | Pending | No | No | No | No | No | No | No | No | No | No | No | No | No | Implemented, pending live conformance |
@@ -428,6 +428,7 @@ executor preflight, Provider selection, and `doctor`.
 | `crawl` | **No** | **No** | Yes | No | No | Yes (async) | No | No | No | No | No | Yes (sync) | No | **No** | No | Tavily sync; Firecrawl async (resumable after Ctrl-C) |
 | `map` | **No** | **No** | Yes | No | No | Yes | No | No | No | No | No | Yes | No | **No** | No | URL-set discovery; no per-page content |
 | `research` | **No** | **No** | Yes | Yes | **No** | **No** | Yes | Yes | Yes | Yes | Yes | No | No | **No** | No | Tavily, Exa, Parallel, Perplexity (Agent API `high` preset), Jina DeepSearch, You.com, and Linkup research report synthesis |
+| `investigation` (EvidencePack) | Yes | **No** (no reader) | Yes | Yes | **No** (no reader) | Yes | Yes | **No** (no reader) | Yes | Yes | Yes | Yes | **No** (no reader) | **No** (no reader) | **No** (no reader) | Provider-composed — supplied by the search+reader supplier union (Z.AI, Tavily, Exa, Firecrawl, Parallel, Jina AI, You.com, Linkup, Spider.cloud); `--synthesize` is Z.AI-only |
 | `repo search` / `repo read` / `repo tree` / `repo brief` | Yes | **No** | **No** | **No** | **No** | **No** | **No** | **No** | **No** | No | No | No | No | No | No | Participates in selection; only Z.AI supplies `repository-exploration` |
 | `tools`, `tool`, `call` (Raw tools) | Yes | No | No | No | No | No | No | No | No | No | No | No | No | No | No | Z.AI-only; accepts but ignores `--provider` |
 | `code` (Code Mode) | Yes | No | No | No | No | No | No | No | No | No | No | No | No | No | No | Z.AI-only; accepts but ignores `--provider` |
@@ -525,6 +526,53 @@ the supplier wire supports them (rejected with `UNSUPPORTED_OPTION`
 elsewhere — never silently dropped). `science get <identifier>` fetches
 one work by bare DOI, numeric PMID, or arXiv id.
 
+### Investigation (`investigate`)
+
+`scoutline investigate <question>` runs a local, transparent,
+cache-resumable pipeline ([ADR-0013](https://github.com/vikasagarwal101/scoutline/blob/main/docs/adr/0013-local-investigation-pipeline.md)):
+plan sub-queries → fan-out search → Fusion merge → read the top
+`--sources` (default 5) → deterministic passage extraction → an
+EvidencePack (`schemaVersion` 1). No provider-side job runs — distinct
+from Research, an opaque billed provider job. The pack is data, not
+prose: agents consume it directly and text output modes fall back to
+JSON (agent-synthesis is the default; you write the prose). Warm re-runs
+replay the response cache (`coverage.cacheHits` reflects it).
+
+```bash
+scoutline investigate "rust async runtime benchmarks"
+scoutline investigate "rust async | rust tokio"    # pipes split explicit sub-queries
+scoutline investigate "topic" --provider tavily,exa --sources 8
+scoutline investigate "topic" --max-chars 20000 --synthesize
+```
+
+Sub-query planning precedence: explicit pipes (the `--merge` grammar) >
+`--context <path>` (a local notes file — it never leaves the machine,
+only the derived sub-query strings are searched) > deterministic
+templates of the bare question (original, key terms,
+overview/evidence/criticism; deduped, capped at 5). Provider selection
+reuses search's fan-out activation tiers verbatim (comma-list/`all`
+fan-out, single pin, `config set fanout true`). Cost is stated in one
+stderr notice before any billable work: N sub-queries × M arms billable
+searches + up to K reads.
+
+Controls: `--sources <n>`, `--max-chars <n>` (passages trim first, late
+sources drop; the full untrimmed pack is saved and recoverable via
+`scoutline history show <ref>`), `--no-cache`, `--no-journal`, `--save`,
+`--isolated`. Sources surfaced but unread land in `coverage.unread` with
+a reason code — never silently dropped. `--synthesize` attaches an
+additive `brief` via Z.AI chat (Z.AI-only; absent by default; a
+synthesis failure is the run's terminal error, never a degraded pack).
+`--depth`, `--arms`, and `--budget-tokens` are rejected with
+`VALIDATION_ERROR` by design.
+
+`--verify` turns the positional into a statement: sentence-claims
+(≤ 8, fail-loud) are searched verbatim and matched to the extracted
+passages; the pack gains an additive `verify` block — per claim, a
+verdict (`corroborated` / `contradicted` / `unresolved`), evidence
+pointers, and a negation-cue count. `contradicted` is a disclosed
+negation-cue heuristic (hint-grade), not semantic judgment;
+`--context` + `--verify` is a mode-conflict VALIDATION_ERROR.
+
 ## Usage
 
 The CLI is self-documenting. Use `--help` at any level:

package/dist/capabilities/investigation.d.ts

@@ -0,0 +1,134 @@
+/**
+ * EvidencePack schema + total decoder (T1, docs/plans/investigate-pipeline
+ * PRD AC-6; ADR-0013 §7).
+ *
+ * The EvidencePack is the self-contained deliverable of an Investigation
+ * (CONTEXT.md glossary): question, sub-queries, sources with per-source
+ * content hashes and extracted passages, and a coverage block. The pack is
+ * data, not prose — agent-synthesis is the contract; `--synthesize` (T7)
+ * attaches a `brief` additively and is not part of this schema.
+ *
+ * This module declares the pack type, its total decoder, and the
+ * contentSha256 shape predicate. It imports NOTHING from other src modules
+ * (self-contained by ticket contract; hashing itself lands in T5 — this
+ * module only validates hash *shape*).
+ *
+ * Decoder discipline mirrors capabilities/reader.ts exactly:
+ *   - accepts `unknown`, returns the pack or `null`, never throws,
+ *     never trusts a generic cast;
+ *   - reject primitives and arrays at the top level;
+ *   - `schemaVersion` MUST be the literal number 1 (rejects "1", 1.5,
+ *     bigints, any future version);
+ *   - `title: null` is a valid decoded value (reader parity);
+ *   - optional fields preserved verbatim when present.
+ */
+/** `[start, end)` character offsets into the source `content` string. */
+export type CharRange = readonly [number, number];
+/**
+ * One extracted passage. `quote` is pinned to the content by `charRange`:
+ * `content.slice(...charRange) === quote` for every passage (D4). The pin
+ * is enforced where content is available (assembly in T5, extraction in
+ * T3); the decoder enforces the shape so a decoded pack is at least
+ * structurally sound.
+ */
+export interface EvidencePassage {
+    readonly quote: string;
+    readonly charRange: CharRange;
+}
+/** One read source: reader-envelope fields + passages. */
+export interface EvidenceSource {
+    readonly url: string;
+    /** The URL the Reader actually fetched (provider rewrite possible). */
+    readonly finalUrl: string;
+    /** Page title if the provider returned one; `null` if absent (reader parity). */
+    readonly title: string | null;
+    /** ISO-8601 UTC Z timestamp captured when the read resolved (D5). */
+    readonly fetchedAt: string;
+    /** Provider id that surfaced the source (search-arm winner). */
+    readonly provider: string;
+    /** Mirrors the read `format`; `"markdown"` or `"text"`. */
+    readonly contentFormat: "markdown" | "text";
+    /** Lowercase hex SHA-256 of the UTF-8 normalized content string (D5). */
+    readonly contentSha256: string;
+    readonly passages: readonly EvidencePassage[];
+}
+/** Coverage block: how much of the planned grid actually produced evidence. */
+export interface EvidenceCoverage {
+    /** Number of planned sub-queries. */
+    readonly subQueries: number;
+    /** Number of search arms actually used. */
+    readonly armsUsed: number;
+    /** Number of post-cluster candidate sources surfaced. */
+    readonly sourcesConsidered: number;
+    /** Number of sources whose read resolved successfully. */
+    readonly sourcesRead: number;
+    /** Count of search arms + reads served warm from cache (D5). */
+    readonly cacheHits: number;
+    /**
+     * Sources surfaced but not read, each with a reason code only —
+     * redacted, no error prose crossing the interface (house rule, D5).
+     */
+    readonly unread: readonly {
+        readonly url: string;
+        readonly reason: string;
+    }[];
+}
+/** The self-contained Investigation deliverable (PRD AC-6). */
+export interface EvidencePack {
+    readonly schemaVersion: 1;
+    readonly question: string;
+    readonly subQueries: readonly string[];
+    readonly sources: readonly EvidenceSource[];
+    readonly coverage: EvidenceCoverage;
+    /**
+     * investigate-verify lane T2 (PRD AC-6): the additive claim-
+     * corroboration block. ABSENT on question-mode packs (byte-identity
+     * pin); present only when `investigate --verify` assembled the pack.
+     */
+    readonly verify?: VerifyBlock;
+}
+/** The deterministic verdict vocabulary (cue heuristic, PRD AC-5). */
+export type ClaimVerdict = "corroborated" | "contradicted" | "unresolved";
+/** One evidence pointer into the pack's own `sources` array. */
+export interface ClaimEvidencePointer {
+    readonly sourceIndex: number;
+    readonly passageIndex: number;
+}
+/**
+ * One claim row: the claim text, its verdict, the count of cue-bearing
+ * matching passages (agent re-judgment input — the cue heuristic is
+ * DISCLOSED hint-grade), and first-encounter evidence pointers.
+ */
+export interface ClaimRow {
+    readonly text: string;
+    readonly verdict: ClaimVerdict;
+    readonly negationCues: number;
+    readonly evidence: readonly ClaimEvidencePointer[];
+}
+/** The additive verify block: the statement plus one row per claim. */
+export interface VerifyBlock {
+    readonly statement: string;
+    readonly claims: readonly ClaimRow[];
+}
+/**
+ * `contentSha256` validity: a 64-character lowercase hex string —
+ * the exact shape of `createHash("sha256")…digest("hex")` output.
+ * Ruling (ticket T1): hex-shape is enforced at decode, so an
+ * uppercased, truncated, or non-hex string fails closed. Full
+ * recompute-vs-content binding belongs to assembly (T5), which is the
+ * only place the paired content string exists.
+ */
+export declare function isValidContentSha256(value: unknown): value is string;
+/**
+ * Decode an `unknown` value into a canonical `EvidencePack`. Returns the
+ * typed pack on success, `null` for any malformed value. NEVER throws,
+ * NEVER trusts a generic cast.
+ *
+ * `title: null` is valid (reader parity). `sources` and `passages` may be
+ * empty arrays (a pack whose every read failed is still a valid, sad pack).
+ * `brief` (T7) is additive: unknown keys are NOT rejected — a decoded pack
+ * carries exactly the AC-6 keys, and an input carrying extra keys decodes
+ * to the canonical subset.
+ */
+export declare function decodeInvestigationPack(value: unknown): EvidencePack | null;
+//# sourceMappingURL=investigation.d.ts.map

package/dist/capabilities/investigation.d.ts.map

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

package/dist/capabilities/investigation.js

@@ -0,0 +1,278 @@
+/**
+ * EvidencePack schema + total decoder (T1, docs/plans/investigate-pipeline
+ * PRD AC-6; ADR-0013 §7).
+ *
+ * The EvidencePack is the self-contained deliverable of an Investigation
+ * (CONTEXT.md glossary): question, sub-queries, sources with per-source
+ * content hashes and extracted passages, and a coverage block. The pack is
+ * data, not prose — agent-synthesis is the contract; `--synthesize` (T7)
+ * attaches a `brief` additively and is not part of this schema.
+ *
+ * This module declares the pack type, its total decoder, and the
+ * contentSha256 shape predicate. It imports NOTHING from other src modules
+ * (self-contained by ticket contract; hashing itself lands in T5 — this
+ * module only validates hash *shape*).
+ *
+ * Decoder discipline mirrors capabilities/reader.ts exactly:
+ *   - accepts `unknown`, returns the pack or `null`, never throws,
+ *     never trusts a generic cast;
+ *   - reject primitives and arrays at the top level;
+ *   - `schemaVersion` MUST be the literal number 1 (rejects "1", 1.5,
+ *     bigints, any future version);
+ *   - `title: null` is a valid decoded value (reader parity);
+ *   - optional fields preserved verbatim when present.
+ */
+// ---------------------------------------------------------------------------
+// Field predicates
+// ---------------------------------------------------------------------------
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.length > 0;
+}
+function isFiniteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value);
+}
+/**
+ * `contentSha256` validity: a 64-character lowercase hex string —
+ * the exact shape of `createHash("sha256")…digest("hex")` output.
+ * Ruling (ticket T1): hex-shape is enforced at decode, so an
+ * uppercased, truncated, or non-hex string fails closed. Full
+ * recompute-vs-content binding belongs to assembly (T5), which is the
+ * only place the paired content string exists.
+ */
+export function isValidContentSha256(value) {
+    if (typeof value !== "string" || value.length !== 64)
+        return false;
+    for (const ch of value) {
+        const code = ch.charCodeAt(0);
+        const isDigit = code >= 48 && code <= 57;
+        const isLowerHex = (code >= 97 && code <= 102) || isDigit;
+        if (!isLowerHex)
+            return false;
+    }
+    return true;
+}
+// ---------------------------------------------------------------------------
+// Total decoder
+// ---------------------------------------------------------------------------
+function decodeCharRange(value) {
+    // PR #264 F2: the documented `[start, end)` invariant, enforced at
+    // decode — safe integers, non-negative start, strictly increasing
+    // (an empty range cannot quote a non-empty passage).
+    return (Array.isArray(value) &&
+        value.length === 2 &&
+        Number.isSafeInteger(value[0]) &&
+        Number.isSafeInteger(value[1]) &&
+        value[0] >= 0 &&
+        value[1] > value[0]);
+}
+function decodePassage(value) {
+    if (!isPlainObject(value))
+        return null;
+    if (!isNonEmptyString(value.quote))
+        return null;
+    if (!decodeCharRange(value.charRange))
+        return null;
+    return { quote: value.quote, charRange: [value.charRange[0], value.charRange[1]] };
+}
+function decodeSource(value) {
+    if (!isPlainObject(value))
+        return null;
+    if (!isNonEmptyString(value.url))
+        return null;
+    if (!isNonEmptyString(value.finalUrl))
+        return null;
+    const title = value.title;
+    if (title !== null && typeof title !== "string")
+        return null;
+    if (!isNonEmptyString(value.fetchedAt))
+        return null;
+    if (!isNonEmptyString(value.provider))
+        return null;
+    if (value.contentFormat !== "markdown" && value.contentFormat !== "text")
+        return null;
+    if (!isValidContentSha256(value.contentSha256))
+        return null;
+    if (!Array.isArray(value.passages))
+        return null;
+    const passages = [];
+    for (const raw of value.passages) {
+        const passage = decodePassage(raw);
+        if (passage === null)
+            return null;
+        passages.push(passage);
+    }
+    return {
+        url: value.url,
+        finalUrl: value.finalUrl,
+        title: title,
+        fetchedAt: value.fetchedAt,
+        provider: value.provider,
+        contentFormat: value.contentFormat,
+        contentSha256: value.contentSha256,
+        passages,
+    };
+}
+function decodeCoverage(value) {
+    if (!isPlainObject(value))
+        return null;
+    if (!isFiniteNumber(value.subQueries))
+        return null;
+    if (!isFiniteNumber(value.armsUsed))
+        return null;
+    if (!isFiniteNumber(value.sourcesConsidered))
+        return null;
+    if (!isFiniteNumber(value.sourcesRead))
+        return null;
+    if (!isFiniteNumber(value.cacheHits))
+        return null;
+    if (!Array.isArray(value.unread))
+        return null;
+    const unread = [];
+    for (const raw of value.unread) {
+        if (!isPlainObject(raw))
+            return null;
+        if (!isNonEmptyString(raw.url))
+            return null;
+        if (!isNonEmptyString(raw.reason))
+            return null;
+        unread.push({ url: raw.url, reason: raw.reason });
+    }
+    return {
+        subQueries: value.subQueries,
+        armsUsed: value.armsUsed,
+        sourcesConsidered: value.sourcesConsidered,
+        sourcesRead: value.sourcesRead,
+        cacheHits: value.cacheHits,
+        unread,
+    };
+}
+/**
+ * Decode an `unknown` value into a canonical `EvidencePack`. Returns the
+ * typed pack on success, `null` for any malformed value. NEVER throws,
+ * NEVER trusts a generic cast.
+ *
+ * `title: null` is valid (reader parity). `sources` and `passages` may be
+ * empty arrays (a pack whose every read failed is still a valid, sad pack).
+ * `brief` (T7) is additive: unknown keys are NOT rejected — a decoded pack
+ * carries exactly the AC-6 keys, and an input carrying extra keys decodes
+ * to the canonical subset.
+ */
+export function decodeInvestigationPack(value) {
+    // PR #264 F1: total containment for the never-throws contract — a
+    // throwing getter or Proxy trap on untrusted input must surface as
+    // a fail-closed null, never as an exception out of the decoder.
+    try {
+        return decodeInvestigationPackInner(value);
+    }
+    catch {
+        return null;
+    }
+}
+function decodeInvestigationPackInner(value) {
+    if (!isPlainObject(value))
+        return null;
+    if (value.schemaVersion !== 1)
+        return null;
+    if (!isNonEmptyString(value.question))
+        return null;
+    if (!Array.isArray(value.subQueries))
+        return null;
+    for (const q of value.subQueries) {
+        if (!isNonEmptyString(q))
+            return null;
+    }
+    if (!Array.isArray(value.sources))
+        return null;
+    const sources = [];
+    for (const raw of value.sources) {
+        const source = decodeSource(raw);
+        if (source === null)
+            return null;
+        sources.push(source);
+    }
+    const coverage = decodeCoverage(value.coverage);
+    if (coverage === null)
+        return null;
+    // investigate-verify lane T2 (D4): additive-optional `verify` — absent
+    // keeps the canonical subset (question-mode byte identity); present is
+    // validated row-by-row and fails closed on any malformed row.
+    const verify = decodeVerifyBlock(value.verify, sources.length, (sourceIndex) => sources[sourceIndex] === undefined ? 0 : sources[sourceIndex].passages.length);
+    if (verify === undefined)
+        return null;
+    return {
+        schemaVersion: 1,
+        question: value.question,
+        subQueries: [...value.subQueries],
+        sources,
+        coverage,
+        ...(verify !== null ? { verify } : {}),
+    };
+}
+const CLAIM_VERDICTS = ["corroborated", "contradicted", "unresolved"];
+/**
+ * Decode the additive verify block. `undefined` = malformed (the caller
+ * fails closed); `null` = absent (the canonical subset stands); the
+ * decoded block = present + valid.
+ *
+ * PR #270 babysit: pointer RANGE is cross-checked against the decoded
+ * sources of the SAME pack (sourceIndex < sourceCount; passageIndex <
+ * that source's passage count) — a shape-safe but out-of-range pointer
+ * is malformed, INCLUDING any pointer into a zero-source pack (it can
+ * never dereference; assembly emits empty evidence there by
+ * construction, so only hand-built input reaches that arm).
+ */
+function decodeVerifyBlock(value, sourceCount, passageCountAt) {
+    if (value === undefined)
+        return null;
+    if (!isPlainObject(value))
+        return undefined;
+    if (!isNonEmptyString(value.statement))
+        return undefined;
+    if (!Array.isArray(value.claims))
+        return undefined;
+    const claims = [];
+    for (const raw of value.claims) {
+        if (!isPlainObject(raw))
+            return undefined;
+        if (!isNonEmptyString(raw.text))
+            return undefined;
+        if (typeof raw.verdict !== "string" || !CLAIM_VERDICTS.includes(raw.verdict)) {
+            return undefined;
+        }
+        if (typeof raw.negationCues !== "number" ||
+            !Number.isSafeInteger(raw.negationCues) ||
+            raw.negationCues < 0) {
+            return undefined;
+        }
+        if (!Array.isArray(raw.evidence))
+            return undefined;
+        const evidence = [];
+        for (const pointer of raw.evidence) {
+            if (!isPlainObject(pointer))
+                return undefined;
+            if (!isSafeIndex(pointer.sourceIndex) || !isSafeIndex(pointer.passageIndex)) {
+                return undefined;
+            }
+            if (pointer.sourceIndex >= sourceCount ||
+                pointer.passageIndex >= passageCountAt(pointer.sourceIndex)) {
+                return undefined;
+            }
+            evidence.push({ sourceIndex: pointer.sourceIndex, passageIndex: pointer.passageIndex });
+        }
+        claims.push({
+            text: raw.text,
+            verdict: raw.verdict,
+            negationCues: raw.negationCues,
+            evidence,
+        });
+    }
+    return { statement: value.statement, claims };
+}
+/** Finite, safe, non-negative integer index (evidence pointer guard). */
+function isSafeIndex(value) {
+    return (typeof value === "number" && Number.isSafeInteger(value) && value >= 0);
+}
+//# sourceMappingURL=investigation.js.map

package/dist/capabilities/investigation.js.map

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