scoutline 0.1.0 → 0.2.0

package/dist/lib/errors.js

@@ -1,26 +1,113 @@
 /**
- * Error types and handling for Scoutline
+ * Error types and handling for Scoutline.
+ *
+ * P1-01 introduces the normalised error contract from DESIGN.md §4:
+ *   `ScoutlineErrorCode`, `ScoutlineError`, `ValidationError`,
+ *   `UnsupportedCapabilityError`, `UnsupportedOptionError`,
+ *   `ConfigurationError`, `isRetryableError`, `getErrorExitCode`.
+ *
+ * The legacy `ZaiError` compatibility name is retained with its existing
+ * 4-arg constructor signature so current imports keep working without
+ * modification. Legacy subclasses (`AuthError`, `ApiError`,
+ * `NetworkError`, `TimeoutError`, `FileError`) continue to extend
+ * `ZaiError` for backward compatibility. The legacy 1-arg
+ * `formatErrorOutput` helper is preserved so Phase 1 command handlers
+ * keep compiling; the pure invocation-local replacement lives in
+ * `./output.js` (DESIGN.md §3) and replaces it in P1-10.
+ *
+ * P4-01 routes both the legacy and the invocation-local error
+ * formatters through `lib/redact.js` so redaction is a single source of
+ * truth.
  */
-export class ZaiError extends Error {
+import { redactCredentialString, configuredSecrets } from "./redact.js";
+export class ScoutlineError extends Error {
     code;
     statusCode;
     help;
-    constructor(message, code, statusCode, help) {
+    retryable;
+    exitCode;
+    constructor(message, code, options = {}) {
         super(message);
+        this.name = "ScoutlineError";
         this.code = code;
-        this.statusCode = statusCode;
-        this.help = help;
+        this.statusCode = options.statusCode;
+        this.help = options.help;
+        this.retryable = options.retryable ?? false;
+        this.exitCode = options.exitCode ?? 1;
+    }
+}
+/**
+ * Compatibility name for existing imports. The 4-arg constructor
+ * signature matches the legacy `ZaiError` so current call sites keep
+ * working without modification. Status codes passed here become
+ * `statusCode`; `help` becomes `help`; `retryable` and `exitCode` keep
+ * their defaults (`false` / `1`).
+ */
+export class ZaiError extends ScoutlineError {
+    constructor(message, code, statusCode, help) {
+        super(message, code, { statusCode, help });
         this.name = "ZaiError";
     }
 }
-export class AuthError extends ZaiError {
-    constructor(message) {
-        super(message, "AUTH_ERROR", 401, "Check your Z_AI_API_KEY is valid and has sufficient quota");
+export class ValidationError extends ScoutlineError {
+    constructor(message, help) {
+        super(message, "VALIDATION_ERROR", {
+            statusCode: 400,
+            help,
+            exitCode: 1,
+        });
+        this.name = "ValidationError";
     }
 }
-export class ValidationError extends ZaiError {
-    constructor(message) {
-        super(message, "VALIDATION_ERROR", 400);
+export class UnsupportedCapabilityError extends ScoutlineError {
+    constructor(provider, capability) {
+        super(`Provider "${provider}" does not support capability "${capability}"`, "UNSUPPORTED_CAPABILITY", { exitCode: 1 });
+        this.name = "UnsupportedCapabilityError";
+    }
+}
+export class UnsupportedOptionError extends ScoutlineError {
+    constructor(provider, capability, option) {
+        super(`Provider "${provider}" does not support option "${option}" for capability "${capability}"`, "UNSUPPORTED_OPTION", { exitCode: 1 });
+        this.name = "UnsupportedOptionError";
+    }
+}
+export class ConfigurationError extends ScoutlineError {
+    constructor(message, help) {
+        // Configuration failures use exit 3 to distinguish them from
+        // ordinary command failures (DESIGN.md §4, GATE-1). The public code is
+        // CONFIGURATION_ERROR; the previous "FILE_ERROR" code was semantically
+        // wrong (FILE_ERROR is reserved for file/media failures in Phase 3).
+        super(message, "CONFIGURATION_ERROR", { help, exitCode: 3 });
+        this.name = "ConfigurationError";
+    }
+}
+export function isRetryableError(error) {
+    if (error instanceof ScoutlineError) {
+        return error.retryable;
+    }
+    return false;
+}
+export function getErrorExitCode(error) {
+    if (error instanceof ScoutlineError) {
+        return error.exitCode;
+    }
+    return 1;
+}
+// ---------------------------------------------------------------------------
+// Legacy subclasses (compat). Kept for Phase 1 command handlers; the ones
+// that survive into Phase 2 are validated during that phase's migration.
+// ---------------------------------------------------------------------------
+export class AuthError extends ZaiError {
+    // Fixup C — W2: AuthError help text is Provider-neutral. The default
+    // message points at "your Provider credentials" instead of naming a
+    // specific env var, since the same AuthError surfaces for any Provider
+    // transport failure (including MiniMax). Callers that DO know which
+    // Provider failed can pass `keyName` to tighten the guidance.
+    constructor(message, keyName) {
+        const help = keyName
+            ? `Check that ${keyName} is valid and has sufficient quota for the active Provider`
+            : "Check that your Provider credentials are valid and have sufficient quota";
+        super(message, "AUTH_ERROR", 401, help);
     }
 }
 export class ApiError extends ZaiError {
@@ -34,8 +121,16 @@ export class NetworkError extends ZaiError {
     }
 }
 export class TimeoutError extends ZaiError {
+    /**
+     * The configured timeout duration that elapsed, in milliseconds. Kept as
+     * a first-class field (Fixup D) so an Adapter rewrapping a typed
+     * `TimeoutError` can preserve the original duration instead of re-reading
+     * an ambient `process.env` value that may differ from the injected env.
+     */
+    durationMs;
     constructor(timeoutMs) {
         super(`Request timed out after ${timeoutMs}ms`, "TIMEOUT_ERROR", undefined, "Try again or increase timeout with Z_AI_TIMEOUT env var");
+        this.durationMs = timeoutMs;
     }
 }
 export class FileError extends ZaiError {
@@ -43,26 +138,47 @@ export class FileError extends ZaiError {
         super(message, "FILE_ERROR", undefined, help);
     }
 }
+// ---------------------------------------------------------------------------
+// Legacy 1-arg `formatErrorOutput` (compat). Phase 1 command handlers
+// still call this with an unknown error value and rely on the legacy
+// `ZAI_OUTPUT_MODE` env var for pretty-print decisions. The pure,
+// invocation-local replacement lives in `./output.js` (DESIGN.md §3) and
+// replaces this helper in P1-10.
+//
+// P4-01: every field that reaches the public envelope is run through the
+// shared `redactCredentialString` from `./redact.js` so credential
+// material embedded in `message` or `help` is replaced with
+// `[REDACTED]` before the value reaches stdout/stderr. The configured
+// Provider credentials from the process environment are passed in as
+// extra replacement targets.
+// ---------------------------------------------------------------------------
 export function formatErrorOutput(error) {
-    const pretty = (process.env.ZAI_OUTPUT_MODE || "") === "pretty";
-    if (error instanceof ZaiError) {
-        return JSON.stringify({
+    const pretty = typeof process !== "undefined" && process.env && process.env.ZAI_OUTPUT_MODE === "pretty";
+    const secrets = configuredSecrets();
+    if (error instanceof ScoutlineError) {
+        const payload = {
             success: false,
-            error: error.message,
+            error: redactCredentialString(error.message, secrets),
             code: error.code,
-            ...(error.help && { help: error.help }),
-        }, null, pretty ? 2 : 0);
+        };
+        if (error.help) {
+            payload.help = redactCredentialString(error.help, secrets);
+        }
+        if (typeof error.statusCode === "number") {
+            payload.statusCode = error.statusCode;
+        }
+        return JSON.stringify(payload, null, pretty ? 2 : 0);
     }
     if (error instanceof Error) {
         return JSON.stringify({
             success: false,
-            error: error.message,
+            error: redactCredentialString(error.message, secrets),
             code: "UNKNOWN_ERROR",
         }, null, pretty ? 2 : 0);
     }
     return JSON.stringify({
         success: false,
-        error: String(error),
+        error: redactCredentialString(String(error), secrets),
         code: "UNKNOWN_ERROR",
     }, null, pretty ? 2 : 0);
 }

package/dist/lib/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/lib/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,OAAO,QAAS,SAAQ,KAAK;IAGxB,IAAI;IACJ,UAAU;IACV,IAAI;IAJb,YACE,OAAe,EACR,IAAY,EACZ,UAAmB,EACnB,IAAa;QAEpB,KAAK,CAAC,OAAO,CAAC,CAAC;oBAJR,IAAI;0BACJ,UAAU;oBACV,IAAI;QAGX,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;IACzB,CAAC;CACF;AAED,MAAM,OAAO,SAAU,SAAQ,QAAQ;IACrC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,EAAE,2DAA2D,CAAC,CAAC;IACjG,CAAC;CACF;AAED,MAAM,OAAO,eAAgB,SAAQ,QAAQ;IAC3C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,EAAE,kBAAkB,EAAE,GAAG,CAAC,CAAC;IAC1C,CAAC;CACF;AAED,MAAM,OAAO,QAAS,SAAQ,QAAQ;IACpC,YAAY,OAAe,EAAE,UAAkB;QAC7C,KAAK,CAAC,OAAO,EAAE,WAAW,EAAE,UAAU,CAAC,CAAC;IAC1C,CAAC;CACF;AAED,MAAM,OAAO,YAAa,SAAQ,QAAQ;IACxC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,gCAAgC,CAAC,CAAC;IAC/E,CAAC;CACF;AAED,MAAM,OAAO,YAAa,SAAQ,QAAQ;IACxC,YAAY,SAAiB;QAC3B,KAAK,CACH,2BAA2B,SAAS,IAAI,EACxC,eAAe,EACf,SAAS,EACT,yDAAyD,CAC1D,CAAC;IACJ,CAAC;CACF;AAED,MAAM,OAAO,SAAU,SAAQ,QAAQ;IACrC,YAAY,OAAe,EAAE,IAAa;QACxC,KAAK,CAAC,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC;IAChD,CAAC;CACF;AAED,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,MAAM,MAAM,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,EAAE,CAAC,KAAK,QAAQ,CAAC;IAChE,IAAI,KAAK,YAAY,QAAQ,EAAE,CAAC;QAC9B,OAAO,IAAI,CAAC,SAAS,CACnB;YACE,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,KAAK,CAAC,OAAO;YACpB,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,GAAG,CAAC,KAAK,CAAC,IAAI,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC;SACxC,EACD,IAAI,EACJ,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CACf,CAAC;IACJ,CAAC;IAED,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,OAAO,IAAI,CAAC,SAAS,CACnB;YACE,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,KAAK,CAAC,OAAO;YACpB,IAAI,EAAE,eAAe;SACtB,EACD,IAAI,EACJ,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CACf,CAAC;IACJ,CAAC;IAED,OAAO,IAAI,CAAC,SAAS,CACnB;QACE,OAAO,EAAE,KAAK;QACd,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC;QACpB,IAAI,EAAE,eAAe;KACtB,EACD,IAAI,EACJ,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CACf,CAAC;AACJ,CAAC"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/lib/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAqBxE,MAAM,OAAO,cAAe,SAAQ,KAAK;IAC9B,IAAI,CAA8B;IAClC,UAAU,CAAU;IACpB,IAAI,CAAU;IACd,SAAS,CAAU;IACnB,QAAQ,CAAS;IAE1B,YACE,OAAe,EACf,IAAiC,EACjC,OAAO,GAA0B,EAAE;QAEnC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;QACrC,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QACzB,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,KAAK,CAAC;QAC5C,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,CAAC,CAAC;IACxC,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,OAAO,QAAS,SAAQ,cAAc;IAC1C,YAAY,OAAe,EAAE,IAAY,EAAE,UAAmB,EAAE,IAAa;QAC3E,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC;QAC3C,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;IACzB,CAAC;CACF;AAED,MAAM,OAAO,eAAgB,SAAQ,cAAc;IACjD,YAAY,OAAe,EAAE,IAAa;QACxC,KAAK,CAAC,OAAO,EAAE,kBAAkB,EAAE;YACjC,UAAU,EAAE,GAAG;YACf,IAAI;YACJ,QAAQ,EAAE,CAAC;SACZ,CAAC,CAAC;QACH,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AAED,MAAM,OAAO,0BAA2B,SAAQ,cAAc;IAC5D,YAAY,QAAgB,EAAE,UAAkB;QAC9C,KAAK,CACH,aAAa,QAAQ,kCAAkC,UAAU,GAAG,EACpE,wBAAwB,EACxB,EAAE,QAAQ,EAAE,CAAC,EAAE,CAChB,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAC;IAC3C,CAAC;CACF;AAED,MAAM,OAAO,sBAAuB,SAAQ,cAAc;IACxD,YAAY,QAAgB,EAAE,UAAkB,EAAE,MAAc;QAC9D,KAAK,CACH,aAAa,QAAQ,8BAA8B,MAAM,qBAAqB,UAAU,GAAG,EAC3F,oBAAoB,EACpB,EAAE,QAAQ,EAAE,CAAC,EAAE,CAChB,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF;AAED,MAAM,OAAO,kBAAmB,SAAQ,cAAc;IACpD,YAAY,OAAe,EAAE,IAAa;QACxC,6DAA6D;QAC7D,uEAAuE;QACvE,uEAAuE;QACvE,qEAAqE;QACrE,KAAK,CAAC,OAAO,EAAE,qBAAqB,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAC;QAC7D,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AAED,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,IAAI,KAAK,YAAY,cAAc,EAAE,CAAC;QACpC,OAAO,KAAK,CAAC,SAAS,CAAC;IACzB,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,IAAI,KAAK,YAAY,cAAc,EAAE,CAAC;QACpC,OAAO,KAAK,CAAC,QAAQ,CAAC;IACxB,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED,8EAA8E;AAC9E,0EAA0E;AAC1E,yEAAyE;AACzE,8EAA8E;AAE9E,MAAM,OAAO,SAAU,SAAQ,QAAQ;IACrC,qEAAqE;IACrE,oEAAoE;IACpE,uEAAuE;IACvE,oEAAoE;IACpE,8DAA8D;IAC9D,YAAY,OAAe,EAAE,OAAgB;QAC3C,MAAM,IAAI,GAAG,OAAO;YAClB,CAAC,CAAC,cAAc,OAAO,4DAA4D;YACnF,CAAC,CAAC,0EAA0E,CAAC;QAC/E,KAAK,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;IAC1C,CAAC;CACF;AAED,MAAM,OAAO,QAAS,SAAQ,QAAQ;IACpC,YAAY,OAAe,EAAE,UAAkB;QAC7C,KAAK,CAAC,OAAO,EAAE,WAAW,EAAE,UAAU,CAAC,CAAC;IAC1C,CAAC;CACF;AAED,MAAM,OAAO,YAAa,SAAQ,QAAQ;IACxC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,gCAAgC,CAAC,CAAC;IAC/E,CAAC;CACF;AAED,MAAM,OAAO,YAAa,SAAQ,QAAQ;IACxC;;;;;OAKG;IACM,UAAU,CAAS;IAC5B,YAAY,SAAiB;QAC3B,KAAK,CACH,2BAA2B,SAAS,IAAI,EACxC,eAAe,EACf,SAAS,EACT,yDAAyD,CAC1D,CAAC;QACF,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;IAC9B,CAAC;CACF;AAED,MAAM,OAAO,SAAU,SAAQ,QAAQ;IACrC,YAAY,OAAe,EAAE,IAAa;QACxC,KAAK,CAAC,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC;IAChD,CAAC;CACF;AAED,8EAA8E;AAC9E,sEAAsE;AACtE,qEAAqE;AACrE,kEAAkE;AAClE,yEAAyE;AACzE,iCAAiC;AACjC,EAAE;AACF,yEAAyE;AACzE,mEAAmE;AACnE,4DAA4D;AAC5D,sEAAsE;AACtE,qEAAqE;AACrE,6BAA6B;AAC7B,8EAA8E;AAE9E,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,MAAM,MAAM,GACV,OAAO,OAAO,KAAK,WAAW,IAAI,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC,eAAe,KAAK,QAAQ,CAAC;IAC5F,MAAM,OAAO,GAAG,iBAAiB,EAAE,CAAC;IACpC,IAAI,KAAK,YAAY,cAAc,EAAE,CAAC;QACpC,MAAM,OAAO,GAA4B;YACvC,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,sBAAsB,CAAC,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC;YACrD,IAAI,EAAE,KAAK,CAAC,IAAI;SACjB,CAAC;QACF,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;YACf,OAAO,CAAC,IAAI,GAAG,sBAAsB,CAAC,KAAK,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAC7D,CAAC;QACD,IAAI,OAAO,KAAK,CAAC,UAAU,KAAK,QAAQ,EAAE,CAAC;YACzC,OAAO,CAAC,UAAU,GAAG,KAAK,CAAC,UAAU,CAAC;QACxC,CAAC;QACD,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACvD,CAAC;IAED,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,OAAO,IAAI,CAAC,SAAS,CACnB;YACE,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,sBAAsB,CAAC,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC;YACrD,IAAI,EAAE,eAAe;SACtB,EACD,IAAI,EACJ,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CACf,CAAC;IACJ,CAAC;IAED,OAAO,IAAI,CAAC,SAAS,CACnB;QACE,OAAO,EAAE,KAAK;QACd,KAAK,EAAE,sBAAsB,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QACrD,IAAI,EAAE,eAAe;KACtB,EACD,IAAI,EACJ,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CACf,CAAC;AACJ,CAAC"}

package/dist/lib/execution.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Shared Execution Contract (DESIGN.md §10).
+ *
+ * Owns cache lookup, legacy read-through, retry policy, and local count
+ * truncation for every Provider Capability. Capability Modules define
+ * shared meaning; Adapters perform a single transport attempt; this
+ * module is the single retry and cache-policy owner.
+ *
+ * Boundary rules (ARCHITECTURE.md §2):
+ *   - May import capability types, Provider identity types, cache, and
+ *     normalized errors.
+ *   - Must NOT import a concrete Provider Adapter, UTCP, or `mmx-cli`.
+ *   - Must NOT import command presentation or output mode modules.
+ *
+ * Order of operations for `executeSearch`:
+ *   1. `capability.validate(request)`
+ *   2. `capability.cacheIdentity(request, { legacyCount: options.count })`
+ *   3. Read the provider-partitioned cache key
+ *   4. Try and decode Adapter-supplied legacy candidates when applicable
+ *   5. Invoke through `executeProviderOperation`
+ *   6. Retry only normalized retryable failures
+ *   7. Cache the full normalized result
+ *   8. Apply local count truncation
+ */
+import type { SearchCapability, SearchRequest, SearchSource } from "../capabilities/search.js";
+import { type ResponseCache } from "./cache.js";
+/**
+ * Retry policy for a single Provider operation. Defaults are applied
+ * per-operation from {@link defaultRetryPolicy}.
+ */
+export interface RetryPolicy {
+    maxRetries: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+    jitterMs: number;
+}
+/**
+ * Dependencies shared execution requires. `sleep` and `random` are
+ * injected so retry backoff is deterministic under test.
+ */
+export interface ExecutionDependencies {
+    cache: ResponseCache;
+    sleep(ms: number): Promise<void>;
+    random(): number;
+}
+/** Provider operations that share a single retry policy table. */
+export type ProviderOperation = "search" | "vision" | "quota" | "diagnostics";
+/**
+ * Default retry policy per operation. Search, quota, and diagnostics
+ * allow one retry; Vision allows two to preserve shipped Z.AI
+ * behaviour. Base delay 500 ms, max delay 8000 ms, jitter up to 250 ms.
+ */
+export declare function defaultRetryPolicy(operation: ProviderOperation): RetryPolicy;
+/**
+ * Generic uncached retry wrapper. Performs no I/O of its own; the
+ * caller supplies the invoke thunk and the cache strategy. Each
+ * outward Provider operation has exactly one retry wrapper; Adapter
+ * transport methods perform one attempt and never retry internally.
+ */
+export declare function executeProviderOperation<T>(operation: ProviderOperation, invoke: () => Promise<T>, dependencies: Pick<ExecutionDependencies, "sleep" | "random">, retryPolicy?: RetryPolicy): Promise<T>;
+/**
+ * Execute a normalized Search through the shared pipeline:
+ * validate → cache identity → new-key read → optional legacy
+ * read-through → invoke with retry → cache the full result → apply
+ * count truncation.
+ *
+ * Count never enters the cache identity request or the Provider
+ * request; it is supplied only as `legacyCount` so the Z.AI Adapter
+ * can reconstruct old keys.
+ */
+export declare function executeSearch(capability: SearchCapability, request: SearchRequest, options: {
+    count?: number;
+    noCache?: boolean;
+    retryPolicy?: RetryPolicy;
+}, dependencies: ExecutionDependencies): Promise<readonly SearchSource[]>;
+//# sourceMappingURL=execution.d.ts.map

package/dist/lib/execution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution.d.ts","sourceRoot":"","sources":["../../src/lib/execution.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAE/F,OAAO,EAAyB,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAMvE;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,aAAa,CAAC;IACrB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,MAAM,IAAI,MAAM,CAAC;CAClB;AAED,kEAAkE;AAClE,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,aAAa,CAAC;AAM9E;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,iBAAiB,GAAG,WAAW,CAe5E;AAkCD;;;;;GAKG;AACH,wBAAsB,wBAAwB,CAAC,CAAC,EAC9C,SAAS,EAAE,iBAAiB,EAC5B,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACxB,YAAY,EAAE,IAAI,CAAC,qBAAqB,EAAE,OAAO,GAAG,QAAQ,CAAC,EAC7D,WAAW,CAAC,EAAE,WAAW,GACxB,OAAO,CAAC,CAAC,CAAC,CAeZ;AAoBD;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CACjC,UAAU,EAAE,gBAAgB,EAC5B,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,WAAW,CAAC,EAAE,WAAW,CAAA;CAAE,EACzE,YAAY,EAAE,qBAAqB,GAClC,OAAO,CAAC,SAAS,YAAY,EAAE,CAAC,CAuDlC"}

package/dist/lib/execution.js

@@ -0,0 +1,177 @@
+/**
+ * Shared Execution Contract (DESIGN.md §10).
+ *
+ * Owns cache lookup, legacy read-through, retry policy, and local count
+ * truncation for every Provider Capability. Capability Modules define
+ * shared meaning; Adapters perform a single transport attempt; this
+ * module is the single retry and cache-policy owner.
+ *
+ * Boundary rules (ARCHITECTURE.md §2):
+ *   - May import capability types, Provider identity types, cache, and
+ *     normalized errors.
+ *   - Must NOT import a concrete Provider Adapter, UTCP, or `mmx-cli`.
+ *   - Must NOT import command presentation or output mode modules.
+ *
+ * Order of operations for `executeSearch`:
+ *   1. `capability.validate(request)`
+ *   2. `capability.cacheIdentity(request, { legacyCount: options.count })`
+ *   3. Read the provider-partitioned cache key
+ *   4. Try and decode Adapter-supplied legacy candidates when applicable
+ *   5. Invoke through `executeProviderOperation`
+ *   6. Retry only normalized retryable failures
+ *   7. Cache the full normalized result
+ *   8. Apply local count truncation
+ */
+import { ScoutlineError } from "./errors.js";
+import { buildProviderCacheKey } from "./cache.js";
+const DEFAULT_BASE_DELAY_MS = 500;
+const DEFAULT_MAX_DELAY_MS = 8000;
+const DEFAULT_JITTER_MS = 250;
+/**
+ * Default retry policy per operation. Search, quota, and diagnostics
+ * allow one retry; Vision allows two to preserve shipped Z.AI
+ * behaviour. Base delay 500 ms, max delay 8000 ms, jitter up to 250 ms.
+ */
+export function defaultRetryPolicy(operation) {
+    const base = {
+        baseDelayMs: DEFAULT_BASE_DELAY_MS,
+        maxDelayMs: DEFAULT_MAX_DELAY_MS,
+        jitterMs: DEFAULT_JITTER_MS,
+    };
+    switch (operation) {
+        case "vision":
+            return { ...base, maxRetries: 2 };
+        case "search":
+        case "quota":
+        case "diagnostics":
+        default:
+            return { ...base, maxRetries: 1 };
+    }
+}
+/**
+ * Classify whether a normalized error is retryable for a Provider
+ * operation. Authentication, validation, unsupported, content-policy,
+ * and exhausted-quota failures are terminal. Normalized timeout,
+ * network, HTTP 429, 500, 502, 503, and 504 equivalents are retryable.
+ *
+ * An explicit `retryable: true` on a `ScoutlineError` wins; an explicit
+ * `retryable: false` overrides a code-based default. Non-Scoutline
+ * errors never retry — Adapters must normalize failures before they
+ * leave the Adapter boundary.
+ */
+function isOperationRetryableError(error) {
+    if (!(error instanceof ScoutlineError))
+        return false;
+    // Explicit retryable flag wins over code-based defaults.
+    if (error.retryable)
+        return true;
+    switch (error.code) {
+        case "TIMEOUT_ERROR":
+        case "NETWORK_ERROR":
+            return true;
+        case "API_ERROR":
+            return (error.statusCode === 429 ||
+                error.statusCode === 500 ||
+                error.statusCode === 502 ||
+                error.statusCode === 503 ||
+                error.statusCode === 504);
+        default:
+            return false;
+    }
+}
+/**
+ * Generic uncached retry wrapper. Performs no I/O of its own; the
+ * caller supplies the invoke thunk and the cache strategy. Each
+ * outward Provider operation has exactly one retry wrapper; Adapter
+ * transport methods perform one attempt and never retry internally.
+ */
+export async function executeProviderOperation(operation, invoke, dependencies, retryPolicy) {
+    const policy = retryPolicy ?? defaultRetryPolicy(operation);
+    let attempt = 0;
+    for (;;) {
+        try {
+            return await invoke();
+        }
+        catch (error) {
+            if (attempt >= policy.maxRetries)
+                throw error;
+            if (!isOperationRetryableError(error))
+                throw error;
+            const backoff = Math.min(policy.maxDelayMs, policy.baseDelayMs * Math.pow(2, attempt));
+            const jitter = Math.floor(dependencies.random() * policy.jitterMs);
+            await dependencies.sleep(backoff + jitter);
+            attempt += 1;
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Search execution
+// ---------------------------------------------------------------------------
+/**
+ * Apply command-level count truncation to a normalized result. Count
+ * is meaning local to the command Module: zero returns an empty list,
+ * a positive count slices, and an absent count returns everything.
+ */
+function applyCount(result, count) {
+    if (count === undefined)
+        return result;
+    if (count <= 0)
+        return [];
+    return result.slice(0, count);
+}
+/**
+ * Execute a normalized Search through the shared pipeline:
+ * validate → cache identity → new-key read → optional legacy
+ * read-through → invoke with retry → cache the full result → apply
+ * count truncation.
+ *
+ * Count never enters the cache identity request or the Provider
+ * request; it is supplied only as `legacyCount` so the Z.AI Adapter
+ * can reconstruct old keys.
+ */
+export async function executeSearch(capability, request, options, dependencies) {
+    // 1. Validate Capability request.
+    capability.validate(request);
+    // 2. Adapter-owned cache identity (after validation).
+    const identity = capability.cacheIdentity(request, {
+        legacyCount: options.count,
+    });
+    // 3. Read the provider-partitioned cache key.
+    const newKey = buildProviderCacheKey({
+        provider: identity.provider,
+        capability: identity.capability,
+        credentialFingerprint: identity.credentialFingerprint,
+        request: identity.request,
+    });
+    if (!options.noCache) {
+        const cached = await dependencies.cache.get(newKey);
+        if (cached !== null) {
+            return applyCount(cached, options.count);
+        }
+        // 4. Adapter-owned legacy candidates (Z.AI only). Invalid raw data
+        //    is a miss; a valid hit populates the new key but the legacy
+        //    file is never changed or deleted.
+        if (identity.legacyCandidates) {
+            for (const candidate of identity.legacyCandidates) {
+                const raw = await dependencies.cache.get(candidate.key);
+                if (raw === null)
+                    continue;
+                const decoded = candidate.decode(raw);
+                if (decoded !== null) {
+                    await dependencies.cache.set(newKey, decoded);
+                    return applyCount(decoded, options.count);
+                }
+            }
+        }
+    }
+    // 5 + 6. Invoke through executeProviderOperation; retryable failures
+    //        are retried with backoff driven by the injected sleep+random.
+    const result = await executeProviderOperation("search", () => capability.invoke(request), dependencies, options.retryPolicy);
+    // 7. Cache the full normalized result before count is applied.
+    if (!options.noCache) {
+        await dependencies.cache.set(newKey, result);
+    }
+    // 8. Local count truncation.
+    return applyCount(result, options.count);
+}
+//# sourceMappingURL=execution.js.map

package/dist/lib/execution.js.map

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

package/dist/lib/index.d.ts

@@ -1,8 +1,16 @@
 /**
- * Library exports for programmatic usage
+ * Library exports for programmatic usage.
+ *
+ * `formatErrorOutput` lives in `./output.js` (DESIGN.md §3, canonical
+ * invocation-local 2-arg form). `./errors.js` keeps a legacy 1-arg
+ * compat version that Phase 1 command handlers import directly until
+ * P1-10 migrates them. To avoid a duplicate-export error in this
+ * aggregator, the errors-module re-export below is explicit and omits
+ * `formatErrorOutput`; the canonical 2-arg version from `./output.js`
+ * wins through `export *` below.
  */
 export * from "./config.js";
-export * from "./errors.js";
+export { type ScoutlineErrorCode, type ScoutlineErrorOptions, ScoutlineError, ZaiError, ValidationError, ConfigurationError, UnsupportedCapabilityError, UnsupportedOptionError, AuthError, ApiError, NetworkError, TimeoutError, FileError, isRetryableError, getErrorExitCode, } from "./errors.js";
 export * from "./output.js";
 export * from "./image.js";
 export * from "./api-client.js";

package/dist/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lib/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lib/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,cAAc,aAAa,CAAC;AAC5B,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAC1B,cAAc,EACd,QAAQ,EACR,eAAe,EACf,kBAAkB,EAClB,0BAA0B,EAC1B,sBAAsB,EACtB,SAAS,EACT,QAAQ,EACR,YAAY,EACZ,YAAY,EACZ,SAAS,EACT,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AACrB,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC"}

package/dist/lib/index.js

@@ -1,8 +1,16 @@
 /**
- * Library exports for programmatic usage
+ * Library exports for programmatic usage.
+ *
+ * `formatErrorOutput` lives in `./output.js` (DESIGN.md §3, canonical
+ * invocation-local 2-arg form). `./errors.js` keeps a legacy 1-arg
+ * compat version that Phase 1 command handlers import directly until
+ * P1-10 migrates them. To avoid a duplicate-export error in this
+ * aggregator, the errors-module re-export below is explicit and omits
+ * `formatErrorOutput`; the canonical 2-arg version from `./output.js`
+ * wins through `export *` below.
  */
 export * from "./config.js";
-export * from "./errors.js";
+export { ScoutlineError, ZaiError, ValidationError, ConfigurationError, UnsupportedCapabilityError, UnsupportedOptionError, AuthError, ApiError, NetworkError, TimeoutError, FileError, isRetryableError, getErrorExitCode, } from "./errors.js";
 export * from "./output.js";
 export * from "./image.js";
 export * from "./api-client.js";

package/dist/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/lib/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/lib/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,cAAc,aAAa,CAAC;AAC5B,OAAO,EAGL,cAAc,EACd,QAAQ,EACR,eAAe,EACf,kBAAkB,EAClB,0BAA0B,EAC1B,sBAAsB,EACtB,SAAS,EACT,QAAQ,EACR,YAAY,EACZ,YAAY,EACZ,SAAS,EACT,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AACrB,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC"}

package/dist/lib/mcp-client.d.ts

@@ -7,7 +7,7 @@
  * - Web Search: Real-time web search
  * - Web Reader: Web page content extraction
  */
-import { type Tool } from "@utcp/sdk";
+import { UtcpClient, type Tool } from "@utcp/sdk";
 import "@utcp/mcp";
 export interface ZReadSearchResult {
     title: string;
@@ -24,6 +24,23 @@ export interface WebSearchResult {
     icon: string;
     publish_date?: string;
 }
+/**
+ * Constructor options for {@link ZaiMcpClient}.
+ *
+ * `utcpFactory` is a behaviour-preserving injection seam: when omitted the
+ * production path uses `UtcpClient.create()`. Tests inject a fake to avoid
+ * touching process globals.
+ *
+ * `disableRetry` (P2-03) lets the Z.AI Search Adapter hand retry policy
+ * to shared execution. When omitted, the client retains its existing
+ * direct-client retry behaviour.
+ */
+export interface ZaiMcpClientOptions {
+    enableVision?: boolean;
+    noCache?: boolean;
+    disableRetry?: boolean;
+    utcpFactory?: () => Promise<UtcpClient>;
+}
 /**
  * Unified MCP client for all Z.AI MCP services
  */
@@ -32,10 +49,7 @@ export declare class ZaiMcpClient {
     private initPromise;
     private isInitialized;
     private options;
-    constructor(options?: {
-        enableVision?: boolean;
-        noCache?: boolean;
-    });
+    constructor(options?: ZaiMcpClientOptions);
     /**
      * Initialize the UTCP client and register all MCP servers
      */
@@ -54,13 +68,37 @@ export declare class ZaiMcpClient {
     private readToolsCache;
     private writeToolsCache;
     /**
-     * List all discovered tools from registered MCP servers
+     * List all discovered tools from registered MCP servers.
+     *
+     * Returns the PUBLIC projected view: internal UTCP names (e.g.
+     * `scoutline_zai.search.web_search_prime`) are rewritten to the
+     * stable dotted form (e.g. `scoutline.zai.search.web_search_prime`).
+     * The private unprojected discovery list is retained for invocation
+     * through {@link getTool} / {@link resolveToolName}.
      */
     listTools(refresh?: boolean): Promise<Tool[]>;
     /**
-     * Find a tool by exact name or by suffix match
+     * Private unprojected discovery list. Tools keep their exact UTCP
+     * names so {@link getTool} can resolve public aliases back to the
+     * internal invocation identity.
+     */
+    private discoverTools;
+    /**
+     * Find a tool by exact internal name, public dotted name, or leaf
+     * suffix. Resolution order:
+     *   1. Exact discovered name (e.g. `scoutline_zai.search.web_search_prime`).
+     *   2. Public dotted name (e.g. `scoutline.zai.search.web_search_prime`):
+     *      derive the provider-relative suffix after the public prefix and
+     *      match exactly one discovered name ending in `.<suffix>`. Zero or
+     *      multiple matches fail.
+     *   3. Legacy short-suffix fallback: a single discovered name ending in
+     *      `.<name>` (e.g. for callers that pass only `web_search_prime`).
+     *
+     * Public names never replace the private discovered-name record — the
+     * returned {@link Tool} always carries its internal UTCP name.
      */
     getTool(toolName: string): Promise<Tool | undefined>;
+    private findToolByResolvedName;
     /**
      * Resolve a tool name, accepting full names or suffixes
      */
@@ -150,10 +188,7 @@ export declare class ZaiMcpClient {
     close(timeoutMs?: number): Promise<void>;
 }
 export declare class ZReadMcpClient extends ZaiMcpClient {
-    constructor(options?: {
-        enableVision?: boolean;
-        noCache?: boolean;
-    });
+    constructor(options?: ZaiMcpClientOptions);
     searchDoc(repo: string, query: string, language?: "zh" | "en"): Promise<string>;
     getRepoStructure(repo: string, dirPath?: string): Promise<string>;
     readFile(repo: string, path: string): Promise<string>;

package/dist/lib/mcp-client.d.ts.map

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