scoutline 0.6.3 → 0.7.0

package/dist/capabilities/map.js

@@ -0,0 +1,60 @@
+/**
+ * Provider-neutral Map Capability Contract (tech-plan §2b).
+ *
+ * Declares the single Map operation (`map-fetch`), its provider-neutral
+ * request, identity, cache, and result shapes, and a total normalized
+ * cache decoder.
+ *
+ * It imports NO concrete Provider, transport, or Adapter. It does no URL
+ * validation, raw response parsing, Provider field mapping, Provider
+ * selection, retries, or presentation.
+ *
+ * Map is the simplest of the three new Tavily capabilities: the API
+ * returns URLs only (no per-page content), so there is no per-page
+ * projection or truncation concern. The handler therefore needs no
+ * `--max-chars` flag.
+ */
+// ===========================================================================
+// Total normalized cache decoder
+// ===========================================================================
+//
+// Accepts `unknown`, returns the typed result or `null`, never throws, and
+// never trusts a generic cast. Shape contract is local; the Adapter is
+// responsible for producing values that conform to `MapResult`.
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.length > 0;
+}
+/**
+ * Decode a MapResult from the cache. Returns the canonical `MapResult`
+ * on success, `null` for any malformed value.
+ */
+export function decodeMapResult(value) {
+    if (!isPlainObject(value))
+        return null;
+    if (value.schemaVersion !== 1)
+        return null;
+    if (!isNonEmptyString(value.baseUrl))
+        return null;
+    const urls = value.urls;
+    if (!Array.isArray(urls))
+        return null;
+    const decodedUrls = [];
+    for (const entry of urls) {
+        if (typeof entry !== "string" || entry.length === 0)
+            return null;
+        decodedUrls.push(entry);
+    }
+    const totalUrls = value.totalUrls;
+    if (typeof totalUrls !== "number" || !Number.isFinite(totalUrls))
+        return null;
+    return {
+        schemaVersion: 1,
+        baseUrl: value.baseUrl,
+        urls: decodedUrls,
+        totalUrls,
+    };
+}
+//# sourceMappingURL=map.js.map

package/dist/capabilities/map.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"map.js","sourceRoot":"","sources":["../../src/capabilities/map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAkFH,8EAA8E;AAC9E,iCAAiC;AACjC,8EAA8E;AAC9E,EAAE;AACF,2EAA2E;AAC3E,uEAAuE;AACvE,gEAAgE;AAEhE,SAAS,aAAa,CAAC,KAAc;IACnC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED,SAAS,gBAAgB,CAAC,KAAc;IACtC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;AACvD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAEvC,IAAI,KAAK,CAAC,aAAa,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAE3C,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,OAAO,CAAC;QAAE,OAAO,IAAI,CAAC;IAElD,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;IACxB,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAEtC,MAAM,WAAW,GAAa,EAAE,CAAC;IACjC,KAAK,MAAM,KAAK,IAAI,IAAI,EAAE,CAAC;QACzB,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QACjE,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC1B,CAAC;IAED,MAAM,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC;IAClC,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC;QAAE,OAAO,IAAI,CAAC;IAE9E,OAAO;QACL,aAAa,EAAE,CAAC;QAChB,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,IAAI,EAAE,WAAW;QACjB,SAAS;KACV,CAAC;AACJ,CAAC"}

package/dist/capabilities/quota.js

@@ -32,7 +32,7 @@ function clampPercent(value) {
         return 0;
     if (value > 100)
         return 100;
-    return value;
+    return Math.round(value * 10) / 10;
 }
 /**
  * Validate a count set: both `used` and `limit` must be finite,

package/dist/capabilities/quota.js.map

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

package/dist/capabilities/research.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Provider-neutral Research Capability Contract (tech-plan §2c, §3).
+ *
+ * Declares the single Research operation (`research-fetch`), its
+ * provider-neutral request, identity, cache, and result shapes, and a
+ * total normalized cache decoder.
+ *
+ * Research is the most complex of the three new Tavily capabilities: it
+ * runs an asynchronous create→poll lifecycle server-side and costs 4-250
+ * credits per request. The Adapter's `invoke()` owns that full lifecycle
+ * (state-file resume, POST, poll loop, completion/failure/404 handling);
+ * shared execution wraps it with the standard cache-then-invoke pattern
+ * but forces `maxRetries: 0` so a transient POST failure never risks a
+ * double-charge (tech-plan §3, §4).
+ *
+ * It imports NO concrete Provider, transport, or Adapter. It does no
+ * query validation, raw response parsing, Provider field mapping,
+ * Provider selection, retries, or presentation.
+ */
+import type { CacheIdentity, CachedOperation } from "../lib/execution.js";
+/**
+ * The single Research Capability operation. Cache identity partitions by
+ * the composite `${capability}-${operation}` literal; the v2 partitioned
+ * key shape is
+ * `v2.research-research-fetch.<provider>.<credential-hash>.<request-hash>.json`.
+ *
+ * `--max-chars`, `--no-cache`, `--timeout` (polling), and output mode are
+ * handler-level projections/policy and do NOT participate in the cache
+ * identity.
+ */
+export type ResearchOperationKind = "research-fetch";
+/**
+ * Provider-neutral research request. `query` MUST be supplied explicitly
+ * (the handler rejects empty/whitespace queries at parse time before this
+ * request reaches the Adapter).
+ *
+ * EVERY field except `query` participates in the v2 partitioned cache
+ * identity: `model`, `outputLength`, `citationFormat`, and `domain` each
+ * alter the report the Provider produces, so two requests differing only
+ * in citation format MUST NOT share a cache entry. `--max-chars`,
+ * `--no-cache`, `--timeout`, and output mode NEVER appear here — they are
+ * projections/policy applied around the cached normalized result.
+ */
+export interface ResearchRequest {
+    readonly query: string;
+    /** Research model: mini (cheapest), pro (deepest), auto (default). */
+    readonly model?: "mini" | "pro" | "auto";
+    /** Output length: short, standard (default), long. */
+    readonly outputLength?: "short" | "standard" | "long";
+    /** Citation format: numbered (default), mla, apa, chicago. */
+    readonly citationFormat?: "numbered" | "mla" | "apa" | "chicago";
+    /** Restrict research to a single domain. */
+    readonly domain?: string;
+}
+/**
+ * A single research source. `favicon` and other Provider-only fields are
+ * dropped at the Adapter boundary.
+ */
+export interface ResearchSource {
+    readonly title: string;
+    readonly url: string;
+}
+/**
+ * Normalized research result. `schemaVersion: 1` is the breaking shape.
+ * `report` is the full report text (cache stores it untruncated;
+ * `--max-chars` is a handler projection). `model` echoes the requested
+ * model so the cached entry is self-describing.
+ */
+export interface ResearchResult {
+    readonly schemaVersion: 1;
+    readonly query: string;
+    readonly model: string;
+    readonly report: string;
+    readonly sources: readonly ResearchSource[];
+}
+/**
+ * Generic Research operation descriptor. The Adapter supplies one of
+ * these for the `research-fetch` operation it supports. The Adapter's
+ * `invoke()` owns the full create→poll→state-file lifecycle internally
+ * (tech-plan §3); shared execution wraps it with cache + zero-retry.
+ */
+export interface ResearchOperation extends CachedOperation<ResearchRequest, ResearchResult> {
+    readonly kind: ResearchOperationKind;
+}
+/**
+ * Research Capability contract. Every Adapter that supports research
+ * implements this interface and exposes it as `adapter.research`.
+ */
+export interface ResearchCapability {
+    readonly run: ResearchOperation;
+}
+/**
+ * Decode a ResearchResult from the cache. Returns the canonical
+ * `ResearchResult` on success, `null` for any malformed value.
+ */
+export declare function decodeResearchResult(value: unknown): ResearchResult | null;
+export type ResearchCacheIdentity = CacheIdentity<ResearchRequest, ResearchResult>;
+//# sourceMappingURL=research.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"research.d.ts","sourceRoot":"","sources":["../../src/capabilities/research.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAM1E;;;;;;;;;GASG;AACH,MAAM,MAAM,qBAAqB,GAAG,gBAAgB,CAAC;AAMrD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,sEAAsE;IACtE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,MAAM,CAAC;IACzC,sDAAsD;IACtD,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,GAAG,UAAU,GAAG,MAAM,CAAC;IACtD,8DAA8D;IAC9D,QAAQ,CAAC,cAAc,CAAC,EAAE,UAAU,GAAG,KAAK,GAAG,KAAK,GAAG,SAAS,CAAC;IACjE,4CAA4C;IAC5C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAMD;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,SAAS,cAAc,EAAE,CAAC;CAC7C;AAMD;;;;;GAKG;AACH,MAAM,WAAW,iBAAkB,SAAQ,eAAe,CAAC,eAAe,EAAE,cAAc,CAAC;IACzF,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;CACtC;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,GAAG,EAAE,iBAAiB,CAAC;CACjC;AAkBD;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,GAAG,IAAI,CA6B1E;AAID,MAAM,MAAM,qBAAqB,GAAG,aAAa,CAAC,eAAe,EAAE,cAAc,CAAC,CAAC"}

package/dist/capabilities/research.js

@@ -0,0 +1,71 @@
+/**
+ * Provider-neutral Research Capability Contract (tech-plan §2c, §3).
+ *
+ * Declares the single Research operation (`research-fetch`), its
+ * provider-neutral request, identity, cache, and result shapes, and a
+ * total normalized cache decoder.
+ *
+ * Research is the most complex of the three new Tavily capabilities: it
+ * runs an asynchronous create→poll lifecycle server-side and costs 4-250
+ * credits per request. The Adapter's `invoke()` owns that full lifecycle
+ * (state-file resume, POST, poll loop, completion/failure/404 handling);
+ * shared execution wraps it with the standard cache-then-invoke pattern
+ * but forces `maxRetries: 0` so a transient POST failure never risks a
+ * double-charge (tech-plan §3, §4).
+ *
+ * It imports NO concrete Provider, transport, or Adapter. It does no
+ * query validation, raw response parsing, Provider field mapping,
+ * Provider selection, retries, or presentation.
+ */
+// ===========================================================================
+// Total normalized cache decoder
+// ===========================================================================
+//
+// Accepts `unknown`, returns the typed result or `null`, never throws, and
+// never trusts a generic cast. Shape contract is local; the Adapter is
+// responsible for producing values that conform to `ResearchResult`.
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.length > 0;
+}
+/**
+ * Decode a ResearchResult from the cache. Returns the canonical
+ * `ResearchResult` on success, `null` for any malformed value.
+ */
+export function decodeResearchResult(value) {
+    if (!isPlainObject(value))
+        return null;
+    if (value.schemaVersion !== 1)
+        return null;
+    if (!isNonEmptyString(value.query))
+        return null;
+    if (!isNonEmptyString(value.model))
+        return null;
+    // `report` may legitimately be empty for a failed-but-completed run, but
+    // it must be a string. Require the field; do not require non-empty.
+    if (typeof value.report !== "string")
+        return null;
+    const sources = value.sources;
+    if (!Array.isArray(sources))
+        return null;
+    const decodedSources = [];
+    for (const entry of sources) {
+        if (!isPlainObject(entry))
+            return null;
+        if (!isNonEmptyString(entry.title))
+            return null;
+        if (!isNonEmptyString(entry.url))
+            return null;
+        decodedSources.push({ title: entry.title, url: entry.url });
+    }
+    return {
+        schemaVersion: 1,
+        query: value.query,
+        model: value.model,
+        report: value.report,
+        sources: decodedSources,
+    };
+}
+//# sourceMappingURL=research.js.map

package/dist/capabilities/research.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"research.js","sourceRoot":"","sources":["../../src/capabilities/research.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAiGH,8EAA8E;AAC9E,iCAAiC;AACjC,8EAA8E;AAC9E,EAAE;AACF,2EAA2E;AAC3E,uEAAuE;AACvE,qEAAqE;AAErE,SAAS,aAAa,CAAC,KAAc;IACnC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED,SAAS,gBAAgB,CAAC,KAAc;IACtC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;AACvD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAc;IACjD,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAEvC,IAAI,KAAK,CAAC,aAAa,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAE3C,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAChD,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAChD,yEAAyE;IACzE,oEAAoE;IACpE,IAAI,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAElD,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;IAC9B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC;QAAE,OAAO,IAAI,CAAC;IAEzC,MAAM,cAAc,GAAqB,EAAE,CAAC;IAC5C,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QACvC,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QAChD,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC;QAC9C,cAAc,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC;IAC9D,CAAC;IAED,OAAO;QACL,aAAa,EAAE,CAAC;QAChB,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,OAAO,EAAE,cAAc;KACxB,CAAC;AACJ,CAAC"}

package/dist/capabilities/search.d.ts

@@ -20,16 +20,24 @@
 import type { ProviderId } from "../providers/types.js";
 /** Recency filter accepted by Z.AI; MiniMax rejects it. */
 export type SearchRecency = "oneDay" | "oneWeek" | "oneMonth" | "oneYear" | "noLimit";
+/**
+ * Topic hint accepted by all Search Providers. Each Adapter maps it
+ * differently: Tavily passes it natively; Z.AI and MiniMax append a
+ * keyword to the query inside `invoke()`.
+ */
+export type SearchTopic = "general" | "news" | "finance";
 /**
  * Provider controls accepted by the Search Capability. Every field is
  * optional. MiniMax rejects `domain`, `recency`, `contentSize`, and
- * `location` with `UNSUPPORTED_OPTION` before any SDK access.
+ * `location` with `UNSUPPORTED_OPTION` before any SDK access. `topic`
+ * is accepted by all adapters.
  */
 export interface SearchControls {
     domain?: string;
     recency?: SearchRecency;
     contentSize?: "medium" | "high";
     location?: "cn" | "us";
+    topic?: SearchTopic;
 }
 /**
  * A Search request. `query` must contain at least one non-whitespace

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

@@ -1 +1 @@
-{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/capabilities/search.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAMxD,2DAA2D;AAC3D,MAAM,MAAM,aAAa,GACrB,QAAQ,GACR,SAAS,GACT,UAAU,GACV,SAAS,GACT,SAAS,CAAC;AAEd;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,WAAW,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;IAChC,QAAQ,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC;CACrC;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAMD;;;;;GAKG;AACH,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,YAAY,EAAE,GAAG,IAAI,CAAC;CACxD;AAED;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC;IAC9B,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,aAAa,CAAC,CAAC;IAC1C,QAAQ,CAAC,gBAAgB,CAAC,EAAE,SAAS,0BAA0B,EAAE,CAAC;CACnE;AAMD;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,CAAC;IAEvC;;;;;OAKG;IACH,aAAa,CACX,OAAO,EAAE,aAAa,EACtB,aAAa,CAAC,EAAE;QAAE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,GAChD,mBAAmB,CAAC;IAEvB;;;;OAIG;IACH,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,SAAS,YAAY,EAAE,CAAC,CAAC;CAClE"}
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/capabilities/search.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAMxD,2DAA2D;AAC3D,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,GAAG,SAAS,CAAC;AAEtF;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC;AAEzD;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,WAAW,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;IAChC,QAAQ,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IACvB,KAAK,CAAC,EAAE,WAAW,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC;CACrC;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAMD;;;;;GAKG;AACH,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,YAAY,EAAE,GAAG,IAAI,CAAC;CACxD;AAED;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC;IAC9B,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,aAAa,CAAC,CAAC;IAC1C,QAAQ,CAAC,gBAAgB,CAAC,EAAE,SAAS,0BAA0B,EAAE,CAAC;CACnE;AAMD;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,CAAC;IAEvC;;;;;OAKG;IACH,aAAa,CACX,OAAO,EAAE,aAAa,EACtB,aAAa,CAAC,EAAE;QAAE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,GAChD,mBAAmB,CAAC;IAEvB;;;;OAIG;IACH,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,SAAS,YAAY,EAAE,CAAC,CAAC;CAClE"}

package/dist/commands/crawl.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Crawl command — thin handler over the Crawl Capability
+ * (tech-plan §2a, §8).
+ *
+ * The handler applies parse-level validation (URL scheme), delegates to
+ * `capability.fetch(request)` through the generic shared execution
+ * wrapper (`executeCachedOperation`), then projects the normalized
+ * `CrawlResult` into the public envelope. The Adapter owns URL
+ * validation, credentials, transport, raw response parsing, cache
+ * identity, and error normalization; the handler owns projection
+ * (`--max-chars` per-page truncation) and output-mode presentation.
+ *
+ * Provider selection, capability support, configuration, Adapter
+ * construction, and adapter.crawl agreement live in `src/index.ts`.
+ *
+ * Cache stores full content; `truncated` and `originalContentLength`
+ * are handler projections (mirrors reader).
+ */
+import type { CommandContext, CommandResult } from "../command-invocation.js";
+import type { CrawlCapability } from "../capabilities/crawl.js";
+import type { ExecutionDependencies } from "../lib/execution.js";
+export interface CrawlOptions {
+    readonly depth?: number;
+    readonly breadth?: number;
+    readonly limit?: number;
+    readonly selectPaths?: string;
+    readonly excludePaths?: string;
+    readonly instructions?: string;
+    readonly format?: "markdown" | "text";
+    readonly contentSize?: "medium" | "high";
+    readonly timeout?: number;
+    readonly noCache?: boolean;
+    readonly maxChars?: number;
+}
+/**
+ * Dependencies injected by `src/index.ts` after Provider selection,
+ * capability support check, configuration check, Adapter construction,
+ * and adapter.crawl agreement.
+ */
+export interface CrawlHandlerDependencies {
+    readonly capability: CrawlCapability;
+    readonly execution: ExecutionDependencies;
+}
+export declare function crawl(url: string, options: CrawlOptions | undefined, deps: CrawlHandlerDependencies, _context?: CommandContext): Promise<CommandResult>;
+export declare const CRAWL_HELP: string;
+//# sourceMappingURL=crawl.d.ts.map

package/dist/commands/crawl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crawl.d.ts","sourceRoot":"","sources":["../../src/commands/crawl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAC9E,OAAO,KAAK,EACV,eAAe,EAIhB,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AASjE,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,MAAM,CAAC;IACtC,QAAQ,CAAC,WAAW,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;IACzC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;IACrC,QAAQ,CAAC,SAAS,EAAE,qBAAqB,CAAC;CAC3C;AA0FD,wBAAsB,KAAK,CACzB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,YAAY,YAAK,EAC1B,IAAI,EAAE,wBAAwB,EAC9B,QAAQ,CAAC,EAAE,cAAc,GACxB,OAAO,CAAC,aAAa,CAAC,CAwBxB;AAQD,eAAO,MAAM,UAAU,QAuDf,CAAC"}

package/dist/commands/crawl.js

@@ -0,0 +1,170 @@
+/**
+ * Crawl command — thin handler over the Crawl Capability
+ * (tech-plan §2a, §8).
+ *
+ * The handler applies parse-level validation (URL scheme), delegates to
+ * `capability.fetch(request)` through the generic shared execution
+ * wrapper (`executeCachedOperation`), then projects the normalized
+ * `CrawlResult` into the public envelope. The Adapter owns URL
+ * validation, credentials, transport, raw response parsing, cache
+ * identity, and error normalization; the handler owns projection
+ * (`--max-chars` per-page truncation) and output-mode presentation.
+ *
+ * Provider selection, capability support, configuration, Adapter
+ * construction, and adapter.crawl agreement live in `src/index.ts`.
+ *
+ * Cache stores full content; `truncated` and `originalContentLength`
+ * are handler projections (mirrors reader).
+ */
+import { executeCachedOperation } from "../lib/execution.js";
+import { OUTPUT_MODES } from "../lib/output.js";
+import { ValidationError } from "../lib/errors.js";
+// ---------------------------------------------------------------------------
+// Parse-level validation
+// ---------------------------------------------------------------------------
+function validateUrl(url) {
+    if (!url.startsWith("http://") && !url.startsWith("https://")) {
+        throw new ValidationError("URL must start with http:// or https://");
+    }
+}
+// ---------------------------------------------------------------------------
+// Projection helpers
+// ---------------------------------------------------------------------------
+/**
+ * Apply `--max-chars` truncation to a single page's content. Mirrors the
+ * reader's truncation contract: slice to `max - 1`, trim trailing
+ * whitespace, append `…`.
+ */
+function truncateContent(content, max) {
+    const originalLen = content.length;
+    if (!max || max <= 0 || originalLen <= max) {
+        return { text: content, originalLen, truncated: false };
+    }
+    return { text: content.slice(0, max - 1).trimEnd() + "…", originalLen, truncated: true };
+}
+/**
+ * Build the Provider-neutral CrawlRequest from CrawlOptions. Only fields
+ * that affect the Provider request or the cache identity appear here;
+ * `--max-chars`, `--no-cache`, and output mode never enter the request.
+ */
+function buildCrawlRequest(url, options) {
+    const request = { url };
+    if (options.depth !== undefined)
+        request.depth = options.depth;
+    if (options.breadth !== undefined)
+        request.breadth = options.breadth;
+    if (options.limit !== undefined)
+        request.limit = options.limit;
+    if (options.selectPaths !== undefined)
+        request.selectPaths = options.selectPaths;
+    if (options.excludePaths !== undefined)
+        request.excludePaths = options.excludePaths;
+    if (options.instructions !== undefined)
+        request.instructions = options.instructions;
+    if (options.format !== undefined)
+        request.format = options.format;
+    if (options.contentSize !== undefined)
+        request.contentSize = options.contentSize;
+    if (options.timeout !== undefined)
+        request.timeout = options.timeout;
+    return request;
+}
+function projectPage(page, maxChars) {
+    if (!maxChars || maxChars <= 0) {
+        return { url: page.url, content: page.content, contentFormat: page.contentFormat };
+    }
+    const { text, originalLen, truncated } = truncateContent(page.content, maxChars);
+    return {
+        url: page.url,
+        content: text,
+        contentFormat: page.contentFormat,
+        truncated,
+        originalContentLength: originalLen,
+    };
+}
+function buildCrawlPresentations(pages) {
+    const urls = pages.map((p) => p.url);
+    const compact = urls.join("\n");
+    const refs = urls.map((u, i) => `[${i + 1}] ${u}`).join("\n");
+    const markdown = pages.map((p) => `## ${p.url}\n\n${p.content}`).join("\n\n---\n\n");
+    return { compact, markdown, refs, tty: markdown };
+}
+// ---------------------------------------------------------------------------
+// Handler
+// ---------------------------------------------------------------------------
+export async function crawl(url, options = {}, deps, _context) {
+    validateUrl(url);
+    const request = buildCrawlRequest(url, options);
+    const result = await executeCachedOperation(deps.capability.fetch, request, { noCache: options.noCache === true }, deps.execution);
+    // Projection: apply --max-chars per page. The cache stores full content;
+    // truncation state is recomputed on every read.
+    const projectedPages = result.pages.map((page) => projectPage(page, options.maxChars));
+    const envelope = {
+        schemaVersion: 1,
+        baseUrl: result.baseUrl,
+        pages: projectedPages,
+        totalPages: result.totalPages,
+    };
+    return { kind: "data", data: envelope, presentations: buildCrawlPresentations(projectedPages) };
+}
+// ---------------------------------------------------------------------------
+// Help
+// ---------------------------------------------------------------------------
+const OUTPUT_MODE_LIST = OUTPUT_MODES.join(" | ");
+export const CRAWL_HELP = `
+Crawl Command - Crawl a website starting from a URL (Provider Capability)
+
+Usage: scoutline crawl <url> [options]
+
+Crawls pages starting from <url>, following links up to the configured
+depth and breadth. Returns a structured result with an array of pages.
+
+Provider selection (precedence: --provider, then SCOUTLINE_PROVIDER,
+then the configured default):
+  - Tavily advertises the crawl Capability and supplies the Adapter.
+  - Z.AI and MiniMax do NOT advertise crawl. Selecting them returns
+    UNSUPPORTED_CAPABILITY with no fallback.
+
+Options:
+  --depth <n>          Crawl depth, 1-5 (default: 1)
+  --breadth <n>        Max links to follow per page, 1-500 (default: 20)
+  --limit <n>          Total pages to process (default: 50)
+  --select-paths <rx>  Comma-separated regex patterns to select URL paths
+  --exclude-paths <rx> Comma-separated regex patterns to exclude URL paths
+  --instructions <t>   Natural language instructions for page selection
+  --format <f>         Output format: markdown (default), text
+  --content-size <s>   Extraction depth: medium (default), high
+  --timeout <s>        Request timeout in seconds (default: 150)
+  --max-chars <n>      Truncate each page's content to <n> chars
+                       (projection only; cache stores full content)
+  --no-cache           Bypass the response cache for this invocation
+
+Common Options:
+  --provider <id>            Override the active Provider (zai | minimax | tavily)
+  --output-format <mode>     One of: ${OUTPUT_MODE_LIST} (default: data)
+  -O <mode>                  Alias for --output-format
+
+Output format (schema-version-1):
+  {
+    "schemaVersion": 1,
+    "baseUrl":         "<the URL you passed>",
+    "pages": [
+      {
+        "url":            "<page URL>",
+        "content":        "<page body as markdown/text>",
+        "contentFormat":  "markdown" | "text",
+        "truncated":      false,          // present when --max-chars is set
+        "originalContentLength": <number>  // present when --max-chars is set
+      }
+    ],
+    "totalPages": <number>
+  }
+
+Examples:
+  scoutline crawl https://docs.example.com --depth 1
+  scoutline crawl https://example.com --depth 2 --breadth 10 --limit 20
+  scoutline crawl https://docs.example.com --select-paths "/api/.*,/guide/.*"
+  scoutline crawl https://example.com --format text --max-chars 2000
+  scoutline --provider tavily crawl https://example.com --depth 3
+`.trim();
+//# sourceMappingURL=crawl.js.map

package/dist/commands/crawl.js.map

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

package/dist/commands/doctor.d.ts

@@ -38,14 +38,13 @@ export interface DoctorDiagnosticsDependencies {
     readonly cacheSummary?: string;
 }
 /**
- * Build a schema-version-1 {@link DiagnosticsReport}. Inventory
- * (`sharedCapabilities`, `zaiOnlyCapabilities`) is derived purely from
- * `deps.descriptors` — no descriptor.create(), no transport, no
- * production registry import. Under `--no-tools` the command returns
- * after metadata + configured-state evaluation. Otherwise each
- * configured Provider is probed through shared execution with settled
- * collection, preserving registry order and normalized redacted
- * failures.
+ * Build a schema-version-2 {@link DiagnosticsReport}. Inventory
+ * (`capabilityMatrix`) is derived purely from `deps.descriptors` — no
+ * descriptor.create(), no transport, no production registry import.
+ * Under `--no-tools` the command returns after metadata +
+ * configured-state evaluation. Otherwise each configured Provider is
+ * probed through shared execution with settled collection, preserving
+ * registry order and normalized redacted failures.
  */
 export declare function buildDiagnosticsReport(deps: DoctorDiagnosticsDependencies): Promise<DiagnosticsReport>;
 /**

package/dist/commands/doctor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,KAAK,EAEV,iBAAiB,EAElB,MAAM,gCAAgC,CAAC;AASxC,OAAO,KAAK,EAAE,kBAAkB,EAAE,UAAU,EAAsB,MAAM,uBAAuB,CAAC;AAMhG,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,iBAAiB,EAAE,UAAU,CAAC;IACvC,QAAQ,CAAC,WAAW,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACpD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,QAAQ,CAAC,MAAM,EAAE,MAAM,MAAM,CAAC;IAC9B;;;;;;;OAOG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AA6CD;;;;;;;;;GASG;AACH,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,6BAA6B,GAClC,OAAO,CAAC,iBAAiB,CAAC,CAkC5B;AA4CD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAKhE;AAMD,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,WAAW,EAAE,MAAM,OAAO,CAAC,iBAAiB,CAAC,CAAC;CACxD;AAED;;;;GAIG;AACH,wBAAsB,MAAM,CAC1B,IAAI,EAAE,yBAAyB,GAC9B,OAAO,CAAC,aAAa,CAAC,iBAAiB,CAAC,CAAC,CAO3C;AAED,eAAO,MAAM,WAAW,QAuDhB,CAAC"}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,KAAK,EAEV,iBAAiB,EAElB,MAAM,gCAAgC,CAAC;AAKxC,OAAO,KAAK,EAAE,kBAAkB,EAAE,UAAU,EAAsB,MAAM,uBAAuB,CAAC;AAMhG,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,iBAAiB,EAAE,UAAU,CAAC;IACvC,QAAQ,CAAC,WAAW,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACpD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,QAAQ,CAAC,MAAM,EAAE,MAAM,MAAM,CAAC;IAC9B;;;;;;;OAOG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AA6CD;;;;;;;;GAQG;AACH,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,6BAA6B,GAClC,OAAO,CAAC,iBAAiB,CAAC,CAiC5B;AA4CD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAKhE;AAMD,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,WAAW,EAAE,MAAM,OAAO,CAAC,iBAAiB,CAAC,CAAC;CACxD;AAED;;;;GAIG;AACH,wBAAsB,MAAM,CAC1B,IAAI,EAAE,yBAAyB,GAC9B,OAAO,CAAC,aAAa,CAAC,iBAAiB,CAAC,CAAC,CAO3C;AAED,eAAO,MAAM,WAAW,QA4DhB,CAAC"}