@memnexus-ai/cli 1.7.222 → 1.7.223

package/dist/lib/renderable-retrieval.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Renderable retrieval results — retrieval health that cannot be dropped.
+ *
+ * WHY THIS MODULE EXISTS
+ *
+ * A transient retrieval failure that produces a confident-looking empty (or
+ * short) answer is worse than a sustained outage. An outage is obvious and the
+ * caller retries. A quiet partial failure is not: the agent reads "no results",
+ * records "no prior art found" as a fact, and moves on. Nobody re-runs the
+ * query, so the wrong conclusion outlives the failure that caused it.
+ *
+ * The CLI already had a degraded-retrieval warning. It had never fired once:
+ * it read `meta.degraded`, while the digest wire carries `metadata.degraded`
+ * (GH #5124). Its test constructed the fictional shape the buggy code expected,
+ * so the suite stayed green over a feature that had never worked. The root
+ * cause was not one typo — it was that every render path took the raw response
+ * as `any` and each one was free to forget the health check.
+ *
+ * THE DESIGN
+ *
+ * Health is carried structurally, not by convention:
+ *
+ *  - `RenderableSearchResult`, `RenderableDigestResult` and
+ *    `RenderableContextBriefing` have PRIVATE constructors. The
+ *    `from*Response` factories are the only way to build one.
+ *  - Those factories are the ONE place the wire-field mapping lives —
+ *    `meta.degraded` (search, build-context) vs `metadata.degraded` (digest),
+ *    the naming inconsistency that caused #5124.
+ *  - Every renderable exposes `health: DegradationState`, where `degraded` is a
+ *    required boolean and `failures` is always an array (empty when healthy).
+ *    There is no `undefined` to forget to check.
+ *  - Raw wire types are NOT exported from this module. A render path cannot
+ *    take the raw response instead, and a new output format cannot be written
+ *    without accepting a value that carries health.
+ *
+ * OUTPUT CONVENTIONS
+ *
+ *  - The warning line goes to STDERR in every format. stderr is the one channel
+ *    that survives `| jq`, `--id-only` piping and `--format json`, where stdout
+ *    must stay machine-parseable.
+ *  - Object-shaped JSON/YAML payloads additionally carry a `health` object on
+ *    stdout, and only when degraded — matching the server convention that a
+ *    healthy response gains no new fields (search.schema.ts).
+ *
+ * This module deliberately has no imports: colouring is the caller's job, and a
+ * dependency-free module keeps the type-level enforcement test cheap to run.
+ */
+/** How a branch failed. `unknown` covers wire values we do not recognise. */
+export type BranchFailureStatus = 'timeout' | 'error' | 'unknown';
+/** One retrieval branch that did not complete. */
+export interface BranchFailure {
+    readonly name: string;
+    readonly status: BranchFailureStatus;
+}
+/**
+ * Retrieval health for one response.
+ *
+ * `degraded` is never optional and `failures` is never undefined: a renderer
+ * cannot accidentally read a missing field as "healthy".
+ */
+export interface DegradationState {
+    readonly degraded: boolean;
+    readonly failures: readonly BranchFailure[];
+}
+/** A normalised search hit: `{ memory, score, matchedVia }`. */
+export interface SearchResultItem {
+    readonly memory: Record<string, any>;
+    readonly score?: number;
+    readonly matchedVia?: string[];
+}
+/** Shared marker text. Every surface uses this string so it is greppable. */
+export declare const DEGRADED_MARKER = "\u26A0 Degraded retrieval";
+/** Suffix appended to a command's headline when the response is degraded. */
+export declare const DEGRADED_HEADLINE_SUFFIX = " \u2014 INCOMPLETE (degraded retrieval)";
+/**
+ * The stderr warning line for a response, or null when the response is healthy.
+ * Plain text — the caller applies colour.
+ */
+export declare function degradationWarningLine(health: DegradationState): string | null;
+/**
+ * A one-line marker for human stdout renderers (table footer, timeline header,
+ * grouped header). Null when healthy.
+ */
+export declare function degradationSummaryLine(health: DegradationState): string | null;
+/** Headline suffix for spinners; empty string when healthy. */
+export declare function degradationHeadlineSuffix(health: DegradationState): string;
+/**
+ * A search response that has been through the health mapping.
+ *
+ * Construction is via `fromApiResponse` / `fromListResponse` only — the private
+ * constructor is what makes the health check impossible to bypass.
+ */
+export declare class RenderableSearchResult {
+    /** Normalised `{ memory, score, matchedVia }` hits. */
+    readonly results: readonly SearchResultItem[];
+    /** `meta.total` when the server sent one, else the result count. */
+    readonly total: number;
+    /** `meta.searchMethod`, when present. */
+    readonly searchMethod: string | undefined;
+    /** `meta.temporalMetadata`, when present. */
+    readonly temporalMetadata: any;
+    /** Retrieval health. Always populated. */
+    readonly health: DegradationState;
+    private readonly body;
+    private constructor();
+    /**
+     * Map a `/api/memories/search` body. Health lives at `meta.degraded` +
+     * `meta.branchFailures` (search.schema.ts SearchMeta).
+     *
+     * Callers validate the body is usable first (a 2xx without a `data` array is
+     * an unusable response, not an empty result set — see
+     * `unusableResponseError` in the search command). This factory is tolerant so
+     * that mapping never throws inside a render path.
+     */
+    static fromApiResponse(body: unknown): RenderableSearchResult;
+    /**
+     * Map a `/api/memories` list body (recap's no-query path). The list endpoint
+     * runs no search branches and carries no health signal, so the result is
+     * healthy by construction — recorded here rather than left implicit.
+     */
+    static fromListResponse(body: unknown): RenderableSearchResult;
+    /**
+     * The JSON/YAML payload: the response body with results normalised, plus a
+     * `health` object when — and only when — the response is degraded.
+     */
+    toSerializable(): Record<string, unknown>;
+}
+/**
+ * A digest / status-report response that has been through the health mapping.
+ *
+ * The digest wire puts health on `metadata`, not `meta` — the single-character
+ * difference that made the CLI's degraded warning dead code (#5124). That
+ * mapping is written once, here.
+ */
+export declare class RenderableDigestResult {
+    readonly digest: string;
+    /** DigestMetadata as sent; also carries the relevance-fallback caveats. */
+    readonly metadata: Record<string, any>;
+    readonly sources: any[];
+    readonly keyFacts: any[] | undefined;
+    readonly entities: any[] | undefined;
+    readonly effectiveStateBreakdown: any;
+    readonly health: DegradationState;
+    private readonly body;
+    private constructor();
+    /** Map a `/api/memories/digest` body. Callers validate `data.metadata` first. */
+    static fromApiResponse(body: unknown): RenderableDigestResult;
+    toSerializable(): Record<string, unknown>;
+}
+/**
+ * A build-context briefing that has been through the health mapping.
+ *
+ * The API already sends `meta.degraded` here (with `timedOutSections` /
+ * `failedSections`); the CLI dropped it silently before this type existed.
+ */
+export declare class RenderableContextBriefing {
+    /** The briefing body: activeWork, relevantFacts, gotchas, … */
+    readonly data: Record<string, any>;
+    readonly health: DegradationState;
+    private constructor();
+    static fromApiResponse(body: unknown): RenderableContextBriefing;
+    toSerializable(): Record<string, unknown>;
+}
+//# sourceMappingURL=renderable-retrieval.d.ts.map

package/dist/lib/renderable-retrieval.d.ts.map

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

package/dist/lib/renderable-retrieval.js

@@ -0,0 +1,364 @@
+"use strict";
+/**
+ * Renderable retrieval results — retrieval health that cannot be dropped.
+ *
+ * WHY THIS MODULE EXISTS
+ *
+ * A transient retrieval failure that produces a confident-looking empty (or
+ * short) answer is worse than a sustained outage. An outage is obvious and the
+ * caller retries. A quiet partial failure is not: the agent reads "no results",
+ * records "no prior art found" as a fact, and moves on. Nobody re-runs the
+ * query, so the wrong conclusion outlives the failure that caused it.
+ *
+ * The CLI already had a degraded-retrieval warning. It had never fired once:
+ * it read `meta.degraded`, while the digest wire carries `metadata.degraded`
+ * (GH #5124). Its test constructed the fictional shape the buggy code expected,
+ * so the suite stayed green over a feature that had never worked. The root
+ * cause was not one typo — it was that every render path took the raw response
+ * as `any` and each one was free to forget the health check.
+ *
+ * THE DESIGN
+ *
+ * Health is carried structurally, not by convention:
+ *
+ *  - `RenderableSearchResult`, `RenderableDigestResult` and
+ *    `RenderableContextBriefing` have PRIVATE constructors. The
+ *    `from*Response` factories are the only way to build one.
+ *  - Those factories are the ONE place the wire-field mapping lives —
+ *    `meta.degraded` (search, build-context) vs `metadata.degraded` (digest),
+ *    the naming inconsistency that caused #5124.
+ *  - Every renderable exposes `health: DegradationState`, where `degraded` is a
+ *    required boolean and `failures` is always an array (empty when healthy).
+ *    There is no `undefined` to forget to check.
+ *  - Raw wire types are NOT exported from this module. A render path cannot
+ *    take the raw response instead, and a new output format cannot be written
+ *    without accepting a value that carries health.
+ *
+ * OUTPUT CONVENTIONS
+ *
+ *  - The warning line goes to STDERR in every format. stderr is the one channel
+ *    that survives `| jq`, `--id-only` piping and `--format json`, where stdout
+ *    must stay machine-parseable.
+ *  - Object-shaped JSON/YAML payloads additionally carry a `health` object on
+ *    stdout, and only when degraded — matching the server convention that a
+ *    healthy response gains no new fields (search.schema.ts).
+ *
+ * This module deliberately has no imports: colouring is the caller's job, and a
+ * dependency-free module keeps the type-level enforcement test cheap to run.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RenderableContextBriefing = exports.RenderableDigestResult = exports.RenderableSearchResult = exports.DEGRADED_HEADLINE_SUFFIX = exports.DEGRADED_MARKER = void 0;
+exports.degradationWarningLine = degradationWarningLine;
+exports.degradationSummaryLine = degradationSummaryLine;
+exports.degradationHeadlineSuffix = degradationHeadlineSuffix;
+/** Shared marker text. Every surface uses this string so it is greppable. */
+exports.DEGRADED_MARKER = '⚠ Degraded retrieval';
+/** Suffix appended to a command's headline when the response is degraded. */
+exports.DEGRADED_HEADLINE_SUFFIX = ' — INCOMPLETE (degraded retrieval)';
+const HEALTHY = Object.freeze({
+    degraded: false,
+    failures: Object.freeze([]),
+});
+/**
+ * Branch names are server-supplied and land on stderr, which agents read.
+ * Constrain them to an identifier shape and cap the count rather than echoing
+ * arbitrary text: an unbounded string here is an injection channel into agent
+ * context (and can carry ANSI escapes from a hostile apiUrl).
+ */
+const BRANCH_NAME_PATTERN = /^[A-Za-z0-9_-]{1,32}$/;
+const MAX_BRANCH_NAMES = 8;
+function toStatus(raw) {
+    return raw === 'timeout' || raw === 'error' ? raw : 'unknown';
+}
+/**
+ * Read a wire `branchFailures` array. Accepts both shapes the API emits today:
+ * plain strings, and `{ name, status }` objects (search adds `reason`, digest
+ * adds `error`; neither is rendered).
+ */
+function readBranchFailures(raw) {
+    if (!Array.isArray(raw))
+        return HEALTHY.failures;
+    const out = [];
+    for (const entry of raw) {
+        const name = typeof entry === 'string' ? entry : (entry?.name ?? entry?.branch);
+        if (typeof name !== 'string' || !BRANCH_NAME_PATTERN.test(name))
+            continue;
+        out.push({ name, status: toStatus(entry?.status) });
+        if (out.length >= MAX_BRANCH_NAMES)
+            break;
+    }
+    return Object.freeze(out);
+}
+/**
+ * Map a container that carries the PR-3 partial-failure contract
+ * (`degraded` + `branchFailures`) into a DegradationState.
+ *
+ * This is the single place that reads those field names. Callers pass
+ * `body.meta` (search, build-context) or `body.metadata` (digest) — the
+ * difference the #5124 bug lived in.
+ */
+function readDegradation(container) {
+    const c = container;
+    if (!c || typeof c !== 'object' || c.degraded !== true)
+        return HEALTHY;
+    return Object.freeze({ degraded: true, failures: readBranchFailures(c.branchFailures) });
+}
+/**
+ * build-context reports failure per SECTION rather than per search branch
+ * (`meta.timedOutSections` / `meta.failedSections`, memories.routes.ts). Map
+ * both lists onto the same BranchFailure vocabulary so one marker renderer
+ * serves every surface.
+ */
+function readSectionDegradation(container) {
+    const c = container;
+    if (!c || typeof c !== 'object' || c.degraded !== true)
+        return HEALTHY;
+    const failures = [];
+    const collect = (raw, status) => {
+        if (!Array.isArray(raw))
+            return;
+        for (const name of raw) {
+            if (typeof name !== 'string' || !BRANCH_NAME_PATTERN.test(name))
+                continue;
+            if (failures.length >= MAX_BRANCH_NAMES)
+                return;
+            failures.push({ name, status });
+        }
+    };
+    collect(c.timedOutSections, 'timeout');
+    collect(c.failedSections, 'error');
+    return Object.freeze({ degraded: true, failures: Object.freeze(failures) });
+}
+/** Serialisable form of health, embedded in object-shaped JSON/YAML payloads. */
+function healthPayload(health) {
+    return {
+        degraded: health.degraded,
+        failures: health.failures.map((f) => ({ name: f.name, status: f.status })),
+    };
+}
+/**
+ * Replace a wire container's raw `branchFailures` with the sanitised set.
+ *
+ * Sanitising only the `health` fold is not enough: `--format json` and
+ * `--format yaml` also emit the response body, so the ORIGINAL server-supplied
+ * `meta.branchFailures` / `metadata.branchFailures` would still reach stdout
+ * unfiltered — the same injection channel the identifier-shape filter exists to
+ * close, on the one format agents parse rather than read. JSON.stringify and
+ * js-yaml both escape C0 control bytes (checked: js-yaml v4 renders ESC as
+ * `\e` inside a double-quoted scalar, so no raw escape sequence reaches a
+ * terminal), but neither touches plain-text instructions, and plain text is
+ * what an agent acts on.
+ *
+ * Replacement rather than deletion: the failed branch names survive, in their
+ * filtered form. The digest shape's free-text `error` message does not — it is
+ * unbounded server-authored prose on a channel an agent parses, and the
+ * closed-vocabulary `status` already says how the branch failed.
+ */
+function withSanitizedFailures(container, health) {
+    const c = container;
+    if (!c || typeof c !== 'object')
+        return c;
+    if (!('branchFailures' in c))
+        return c;
+    return { ...c, branchFailures: healthPayload(health).failures };
+}
+/**
+ * build-context reports failures as two lists of section names rather than a
+ * `branchFailures` array, so it needs the same treatment in its own shape.
+ */
+function withSanitizedSections(container, health) {
+    const c = container;
+    if (!c || typeof c !== 'object')
+        return c;
+    const names = (status) => health.failures.filter((f) => f.status === status).map((f) => f.name);
+    return {
+        ...c,
+        ...('timedOutSections' in c ? { timedOutSections: names('timeout') } : {}),
+        ...('failedSections' in c ? { failedSections: names('error') } : {}),
+    };
+}
+/**
+ * The stderr warning line for a response, or null when the response is healthy.
+ * Plain text — the caller applies colour.
+ */
+function degradationWarningLine(health) {
+    if (!health.degraded)
+        return null;
+    const names = health.failures.map((f) => f.name);
+    const detail = names.length
+        ? `failed branches: ${names.join(', ')}`
+        : 'one or more retrieval branches failed';
+    return (`${exports.DEGRADED_MARKER} — ${detail}. These results are incomplete; re-run before ` +
+        'treating them as a full answer.');
+}
+/**
+ * A one-line marker for human stdout renderers (table footer, timeline header,
+ * grouped header). Null when healthy.
+ */
+function degradationSummaryLine(health) {
+    if (!health.degraded)
+        return null;
+    const names = health.failures.map((f) => f.name);
+    const detail = names.length ? ` (${names.join(', ')})` : '';
+    return `${exports.DEGRADED_MARKER}${detail} — results below are INCOMPLETE.`;
+}
+/** Headline suffix for spinners; empty string when healthy. */
+function degradationHeadlineSuffix(health) {
+    return health.degraded ? exports.DEGRADED_HEADLINE_SUFFIX : '';
+}
+function normaliseResults(raw) {
+    if (!Array.isArray(raw))
+        return Object.freeze([]);
+    return Object.freeze(raw.map((r) => r && r.memory ? r : { memory: r, score: r?.score, matchedVia: r?.matchedVia }));
+}
+/**
+ * A search response that has been through the health mapping.
+ *
+ * Construction is via `fromApiResponse` / `fromListResponse` only — the private
+ * constructor is what makes the health check impossible to bypass.
+ */
+class RenderableSearchResult {
+    results;
+    total;
+    searchMethod;
+    temporalMetadata;
+    health;
+    body;
+    constructor(
+    /** Normalised `{ memory, score, matchedVia }` hits. */
+    results, 
+    /** `meta.total` when the server sent one, else the result count. */
+    total, 
+    /** `meta.searchMethod`, when present. */
+    searchMethod, 
+    /** `meta.temporalMetadata`, when present. */
+    temporalMetadata, 
+    /** Retrieval health. Always populated. */
+    health, body) {
+        this.results = results;
+        this.total = total;
+        this.searchMethod = searchMethod;
+        this.temporalMetadata = temporalMetadata;
+        this.health = health;
+        this.body = body;
+    }
+    /**
+     * Map a `/api/memories/search` body. Health lives at `meta.degraded` +
+     * `meta.branchFailures` (search.schema.ts SearchMeta).
+     *
+     * Callers validate the body is usable first (a 2xx without a `data` array is
+     * an unusable response, not an empty result set — see
+     * `unusableResponseError` in the search command). This factory is tolerant so
+     * that mapping never throws inside a render path.
+     */
+    static fromApiResponse(body) {
+        const b = (body ?? {});
+        const results = normaliseResults(b.data);
+        const meta = b.meta;
+        return new RenderableSearchResult(results, typeof meta?.total === 'number' ? meta.total : results.length, typeof meta?.searchMethod === 'string' ? meta.searchMethod : undefined, meta?.temporalMetadata, readDegradation(meta), b);
+    }
+    /**
+     * Map a `/api/memories` list body (recap's no-query path). The list endpoint
+     * runs no search branches and carries no health signal, so the result is
+     * healthy by construction — recorded here rather than left implicit.
+     */
+    static fromListResponse(body) {
+        const b = (body ?? {});
+        const results = Object.freeze((Array.isArray(b.data) ? b.data : []).map((m) => ({ memory: m })));
+        return new RenderableSearchResult(results, results.length, undefined, undefined, HEALTHY, b);
+    }
+    /**
+     * The JSON/YAML payload: the response body with results normalised, plus a
+     * `health` object when — and only when — the response is degraded.
+     */
+    toSerializable() {
+        // The `meta` overwrite keeps its original key position (object spread
+        // overwrites in place) while swapping the raw branchFailures for the
+        // filtered set.
+        return {
+            ...this.body,
+            ...(this.body.meta !== undefined
+                ? { meta: withSanitizedFailures(this.body.meta, this.health) }
+                : {}),
+            data: this.results,
+            ...(this.health.degraded ? { health: healthPayload(this.health) } : {}),
+        };
+    }
+}
+exports.RenderableSearchResult = RenderableSearchResult;
+/**
+ * A digest / status-report response that has been through the health mapping.
+ *
+ * The digest wire puts health on `metadata`, not `meta` — the single-character
+ * difference that made the CLI's degraded warning dead code (#5124). That
+ * mapping is written once, here.
+ */
+class RenderableDigestResult {
+    digest;
+    metadata;
+    sources;
+    keyFacts;
+    entities;
+    effectiveStateBreakdown;
+    health;
+    body;
+    constructor(digest, 
+    /** DigestMetadata as sent; also carries the relevance-fallback caveats. */
+    metadata, sources, keyFacts, entities, effectiveStateBreakdown, health, body) {
+        this.digest = digest;
+        this.metadata = metadata;
+        this.sources = sources;
+        this.keyFacts = keyFacts;
+        this.entities = entities;
+        this.effectiveStateBreakdown = effectiveStateBreakdown;
+        this.health = health;
+        this.body = body;
+    }
+    /** Map a `/api/memories/digest` body. Callers validate `data.metadata` first. */
+    static fromApiResponse(body) {
+        const b = (body ?? {});
+        const metadata = (b.metadata ?? {});
+        return new RenderableDigestResult(typeof b.digest === 'string' ? b.digest : '', metadata, Array.isArray(b.sources) ? b.sources : [], Array.isArray(b.keyFacts) ? b.keyFacts : undefined, Array.isArray(b.entities) ? b.entities : undefined, b.effectiveStateBreakdown, readDegradation(metadata), b);
+    }
+    toSerializable() {
+        return {
+            ...this.body,
+            ...(this.body.metadata !== undefined
+                ? { metadata: withSanitizedFailures(this.body.metadata, this.health) }
+                : {}),
+            ...(this.health.degraded ? { health: healthPayload(this.health) } : {}),
+        };
+    }
+}
+exports.RenderableDigestResult = RenderableDigestResult;
+/**
+ * A build-context briefing that has been through the health mapping.
+ *
+ * The API already sends `meta.degraded` here (with `timedOutSections` /
+ * `failedSections`); the CLI dropped it silently before this type existed.
+ */
+class RenderableContextBriefing {
+    data;
+    health;
+    constructor(
+    /** The briefing body: activeWork, relevantFacts, gotchas, … */
+    data, health) {
+        this.data = data;
+        this.health = health;
+    }
+    static fromApiResponse(body) {
+        const b = (body ?? {});
+        return new RenderableContextBriefing(b, readSectionDegradation(b.meta));
+    }
+    toSerializable() {
+        return {
+            ...this.data,
+            ...(this.data.meta !== undefined
+                ? { meta: withSanitizedSections(this.data.meta, this.health) }
+                : {}),
+            ...(this.health.degraded ? { health: healthPayload(this.health) } : {}),
+        };
+    }
+}
+exports.RenderableContextBriefing = RenderableContextBriefing;
+//# sourceMappingURL=renderable-retrieval.js.map

package/dist/lib/renderable-retrieval.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memnexus-ai/cli",
-  "version": "1.7.222",
+  "version": "1.7.223",
   "description": "Command-line interface for MemNexus Core API",
   "main": "dist/index.js",
   "bin": {
@@ -34,7 +34,7 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "@memnexus-ai/typescript-sdk": "^1.71.5",
+    "@memnexus-ai/typescript-sdk": "^1.73.2",
     "@modelcontextprotocol/sdk": "^1.27.1",
     "axios": "^1.13.6",
     "chalk": "^5.3.0",