@cilow/sdk 0.2.1 → 0.3.0

package/dist/client.js

@@ -1,509 +1,653 @@
-'use strict';
-
-// src/client.ts
-async function fetchWithRetry(url, options, config) {
-  const controller = new AbortController();
-  const timeoutId = setTimeout(() => controller.abort(), config.timeout);
-  let lastError = null;
-  for (let attempt = 0; attempt <= config.retries; attempt++) {
-    try {
-      const response = await fetch(url, {
-        ...options,
-        signal: controller.signal
-      });
-      clearTimeout(timeoutId);
-      if (!response.ok) {
-        const errorBody = await response.text();
-        let apiError;
+import { CilowError } from "./errors.js";
+import { canonicalJson, sha256Hex } from "./hash.js";
+/** Current wall clock as epoch MICROSECONDS — the unit every Cilow time field uses. */
+export function nowMicros() {
+    return Date.now() * 1000;
+}
+/**
+ * The idempotency key `ingest` sends when you pass no `sourceId`: a sha256 CONTENT HASH.
+ * The wire requires `source_id` (`RememberRequest.source_id` / `IngestAnyRequest.source_id` are
+ * non-optional) and a timestamp would make every retry a fresh write; hashing the content makes a
+ * retry of the same payload an idempotent no-op (the engine dedups under the tenant on this key).
+ * Pre-image: `"<form>:<content>"`, facts as canonical JSON (sorted keys, compact). The Python SDK's
+ * `ingest_source_id` computes the identical key.
+ */
+export function ingestSourceId(content) {
+    const pre = "facts" in content
+        ? `facts:${canonicalJson(content.facts)}`
+        : "text" in content
+            ? `text:${content.text}`
+            : "url" in content
+                ? `text:${content.url}`
+                : `bytes:${content.contentBase64}`;
+    return `sdk-ingest-${sha256Hex(pre).slice(0, 32)}`;
+}
+let rpcSeq = 0;
+/**
+ * A thin, typed client for a running cilow-serve. One instance, five verbs:
+ *
+ * ```ts
+ * const cilow = new CilowClient({ baseUrl: "http://localhost:8080", token: "demo" });
+ * await cilow.remember([{ subject: "Maya", predicate: "employer", object: "Acme" }]);
+ * const r = await cilow.recall("where does Maya work", { anchor: "Maya", attribute: "employer" });
+ * if (r.abstained) console.log("engine doesn't know:", r.reason);
+ * else console.log(r.claims[0].value); // "Acme"
+ * ```
+ *
+ * Handles the JSON-RPC 2.0 envelope, bearer auth, and error mapping. The abstention
+ * contract is surfaced as a plain `abstained` boolean on `recall`/`answer` — never an
+ * exception. CilowError is thrown only for protocol / transport / auth failures.
+ */
+export class CilowClient {
+    baseUrl;
+    token;
+    scope;
+    fetchImpl;
+    timeoutMs;
+    /** The friendly id-based memories surface: `client.memories.add(...)` etc. */
+    memories;
+    constructor(opts) {
+        if (!opts.baseUrl)
+            throw new CilowError("CilowClient requires a baseUrl");
+        if (!opts.token)
+            throw new CilowError("CilowClient requires a bearer token");
+        this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+        this.token = opts.token;
+        this.scope = opts.scope ?? {};
+        const f = opts.fetch ?? globalThis.fetch;
+        if (typeof f !== "function") {
+            throw new CilowError("no fetch available — pass `fetch` in CilowClientOptions (Node <18) or use Node 18+");
+        }
+        this.fetchImpl = f;
+        this.timeoutMs = opts.timeoutMs ?? 30_000;
+        // The memories sub-API — arrow methods so they close over `this` (and reach the private transport).
+        this.memories = {
+            add: (content, opts = {}) => this.callRest("add", {
+                content,
+                ...(opts.contentBase64 !== undefined ? { content_base64: opts.contentBase64 } : {}),
+                ...(opts.mime !== undefined ? { mime: opts.mime } : {}),
+                ...(opts.subjectHint !== undefined ? { subject_hint: opts.subjectHint } : {}),
+                ...(opts.customId !== undefined ? { custom_id: opts.customId } : {}),
+                ...(opts.observedAt !== undefined ? { observed_at: opts.observedAt } : {}),
+                ...(opts.metadata !== undefined ? { metadata: opts.metadata } : {}),
+            }),
+            search: (query, opts = {}) => this.callRest("search", {
+                query,
+                ...(opts.anchor !== undefined ? { anchor: opts.anchor } : {}),
+                ...(opts.attribute !== undefined ? { attribute: opts.attribute } : {}),
+                ...(opts.mode !== undefined ? { mode: opts.mode } : {}),
+            }),
+            get: (id) => this.callRest("get", { id }, { allow404: true }),
+            list: (opts = {}) => this.callRest("list", {
+                offset: opts.offset ?? 0,
+                active_only: opts.activeOnly ?? false,
+                ...(opts.limit !== undefined ? { limit: opts.limit } : {}),
+            }),
+            update: (id, value, opts = {}) => this.callRest("update", {
+                id,
+                value,
+                ...(opts.observedAt !== undefined ? { observed_at: opts.observedAt } : {}),
+            }),
+            delete: (id, opts = {}) => this.callRest("delete", {
+                id,
+                ...(opts.at !== undefined ? { at: opts.at } : {}),
+            }),
+            batchAdd: (items) => this.callRest("batch", {
+                items: items.map((it) => ({
+                    content: it.content,
+                    ...(it.subjectHint !== undefined ? { subject_hint: it.subjectHint } : {}),
+                    ...(it.customId !== undefined ? { custom_id: it.customId } : {}),
+                    ...(it.observedAt !== undefined ? { observed_at: it.observedAt } : {}),
+                    ...(it.metadata !== undefined ? { metadata: it.metadata } : {}),
+                })),
+            }),
+        };
+    }
+    /** Liveness probe — `GET /health`, no auth. Returns true iff the server is up. */
+    async health() {
         try {
-          apiError = JSON.parse(errorBody);
-        } catch {
-          apiError = {
-            code: `HTTP_${response.status}`,
-            message: errorBody || response.statusText
-          };
+            const res = await this.fetchImpl(`${this.baseUrl}/health`);
+            if (!res.ok)
+                return false;
+            const body = (await res.json());
+            return body.status === "ok";
         }
-        throw new CilowApiError(apiError.message, apiError.code, response.status, apiError.details);
-      }
-      return response;
-    } catch (error) {
-      lastError = error;
-      if (error instanceof CilowApiError) {
-        throw error;
-      }
-      if (config.debug) {
-        console.warn(`Cilow API request failed (attempt ${attempt + 1}/${config.retries + 1}):`, error);
-      }
-      if (attempt < config.retries) {
-        await new Promise((resolve) => setTimeout(resolve, Math.pow(2, attempt) * 100));
-      }
-    }
-  }
-  clearTimeout(timeoutId);
-  throw lastError || new Error("Request failed");
-}
-var CilowApiError = class extends Error {
-  constructor(message, code, statusCode, details) {
-    super(message);
-    this.code = code;
-    this.statusCode = statusCode;
-    this.details = details;
-    this.name = "CilowApiError";
-  }
-};
-var CilowClient = class {
-  constructor(config) {
-    this.baseUrl = config.apiUrl.replace(/\/$/, "");
-    this.apiKey = config.apiKey;
-    this.timeout = config.timeout ?? 3e4;
-    this.retries = config.retries ?? 3;
-    this.debug = config.debug ?? false;
-    const authHeaders = this.apiKey.startsWith("cilow_") ? { "X-API-Key": this.apiKey } : { Authorization: `Bearer ${this.apiKey}` };
-    this.headers = {
-      "Content-Type": "application/json",
-      ...authHeaders,
-      ...config.headers
-    };
-  }
-  /**
-   * Make an API request
-   */
-  async request(method, path, body, queryParams) {
-    let url = `${this.baseUrl}${path}`;
-    if (queryParams) {
-      const params = new URLSearchParams();
-      for (const [key, value] of Object.entries(queryParams)) {
-        if (value !== void 0) {
-          params.append(key, String(value));
+        catch {
+            return false;
+        }
+    }
+    /** Ingest `(subject, predicate, object)` facts as bitemporal claims. Returns the write receipt. */
+    async remember(facts, opts = {}) {
+        const now = opts.observedAt ?? nowMicros();
+        return this.call("remember", {
+            facts,
+            scope: this.mergeScope(opts.scope),
+            source: opts.source ?? "operator",
+            source_id: opts.sourceId ?? `sdk-${Date.now()}-${rpcSeq}`,
+            observed_at: now,
+            ...(opts.rawContext !== undefined ? { raw_context: opts.rawContext } : {}),
+            ...(opts.branch !== undefined ? { branch: opts.branch } : {}),
+        });
+    }
+    /**
+     * Retrieve claims as-of a valid-time T, OR a calibrated abstain. Check `abstained`
+     * first. When true, `claims` is empty; use the caller's fallback or safe-deferral policy.
+     */
+    async recall(query, opts = {}) {
+        const now = opts.now ?? nowMicros();
+        return this.call("recall", {
+            query,
+            scope: this.mergeScope(opts.scope),
+            as_of: opts.asOf ?? now,
+            now,
+            ...(opts.anchor !== undefined ? { anchor: opts.anchor } : {}),
+            ...(opts.attribute !== undefined ? { attribute: opts.attribute } : {}),
+            ...(opts.branch !== undefined ? { branch: opts.branch } : {}),
+        });
+    }
+    /**
+     * Present-time synthesized answer with citations, OR a calibrated abstain. When
+     * `abstained` is true, `text` is the honored abstain message and `citations` is empty.
+     */
+    async answer(query, opts = {}) {
+        return this.call("answer", {
+            query,
+            scope: this.mergeScope(opts.scope),
+            now: opts.now ?? nowMicros(),
+            ...(opts.anchor !== undefined ? { anchor: opts.anchor } : {}),
+            ...(opts.attribute !== undefined ? { attribute: opts.attribute } : {}),
+            ...(opts.branch !== undefined ? { branch: opts.branch } : {}),
+        });
+    }
+    /**
+     * Track A1 — create a git-style BRANCH of this tenant's memory (O(1), copies nothing). Write/
+     * supersede facts on the branch (`remember(facts, { branch: name })`) and they stay ISOLATED from
+     * `main` and other branches; an anchored `recall(q, { branch: name })` inherits main's value as of
+     * the fork for keys the branch never wrote. Check `ok`: false ⇒ rejected (see `error`).
+     */
+    async fork(name, opts = {}) {
+        return this.call("fork", {
+            name,
+            scope: this.mergeScope(opts.scope),
+            now: opts.now ?? nowMicros(),
+            ...(opts.from !== undefined ? { from: opts.from } : {}),
+        });
+    }
+    /** Track A1 — list this tenant's git-style branches (`main` first, then forks in name order). */
+    async branchList(opts = {}) {
+        const res = await this.call("branch_list", {
+            scope: this.mergeScope(opts.scope),
+        });
+        return res.branches ?? [];
+    }
+    /** The as-of-T bitemporal history of an entity's claims, ascending by `valid_from`. */
+    async timeline(entity, opts = {}) {
+        const res = await this.call("timeline", {
+            entity,
+            scope: this.mergeScope(opts.scope),
+            at: opts.at ?? nowMicros(),
+            ...(opts.from !== undefined ? { t_from: opts.from } : {}),
+            ...(opts.to !== undefined ? { t_to: opts.to } : {}),
+        });
+        return res.entries;
+    }
+    /** Register / resolve an entity name to its canonical id + alias class as-of `at`. */
+    async trackEntity(name, opts = {}) {
+        return this.call("track_entity", {
+            name,
+            scope: this.mergeScope(opts.scope),
+            at: opts.at ?? nowMicros(),
+        });
+    }
+    /**
+     * Report the outcome of a prior `recall` (by its `traceId`) so memory LEARNS — the
+     * outcome-feedback loop. A `"positive"` outcome reinforces the cited claims; `"negative"`
+     * down-weights them; either way the calibrated abstain gate's q̂ self-tunes. This is
+     * in-context learning at the memory layer — no model retraining.
+     *
+     * Check `.applied`: when FALSE the feedback was rejected (`.error` is `"unknown_trace"` or
+     * `"cross_tenant"`) and nothing was mutated. A cross-tenant attempt does NOT consume the
+     * owner's trace.
+     */
+    async feedback(traceId, outcome, opts = {}) {
+        return this.call("feedback", {
+            trace_id: traceId,
+            outcome,
+            scope: this.mergeScope(opts.scope),
+        });
+    }
+    /**
+     * Run the idle-time episodic→semantic pass for this tenant: promote corroborated claims,
+     * collapse supersession chains into queryable transitions, and decay stale never-recalled
+     * claims. Retire-not-delete — as-of-T history is preserved. Returns the counts.
+     */
+    async consolidate(opts = {}) {
+        return this.call("consolidate", {
+            scope: this.mergeScope(opts.scope),
+            now: opts.now ?? nowMicros(),
+        });
+    }
+    /**
+     * "Just add text": ingest free PROSE. A language model extracts (subject, predicate, object) facts,
+     * written as calibrated bitemporal claims — no hand-structuring. `subjectHint` is the default subject
+     * for a fact the text does not name. Check `.ok`: false ⇒ the text couldn't be read (`.error` says why).
+     */
+    async rememberText(text, subjectHint, opts = {}) {
+        return this.call("remember_text", {
+            text,
+            subject_hint: subjectHint,
+            scope: this.mergeScope(opts.scope),
+            source_id: opts.sourceId ?? `sdk-${Date.now()}-${++rpcSeq}`,
+            observed_at: opts.observedAt ?? nowMicros(),
+        });
+    }
+    /**
+     * Make an image part of memory: a vision model reads it into a caption + facts, written as claims —
+     * so the image is recallable by an ordinary TEXT query. `imageBase64` is the raw base64 (no data: prefix).
+     * Check `.ok`: false ⇒ the image couldn't be read (`.error`).
+     */
+    async ingestImage(imageBase64, mime, subjectHint, opts = {}) {
+        return this.call("ingest_image", {
+            image_base64: imageBase64,
+            mime,
+            subject_hint: subjectHint,
+            scope: this.mergeScope(opts.scope),
+            source_id: opts.sourceId ?? `sdk-img-${Date.now()}-${++rpcSeq}`,
+            observed_at: opts.observedAt ?? nowMicros(),
+        });
+    }
+    /**
+     * Make an audio clip part of memory: it's transcribed, then the transcript is written as a claim AND
+     * run through the same text→facts extraction prose uses — so the audio is recallable by an ordinary
+     * TEXT query. `audioBase64` is the raw base64 (no data: prefix). Check `.ok`: false ⇒ couldn't read (`.error`).
+     */
+    async ingestAudio(audioBase64, mime, subjectHint, opts = {}) {
+        return this.call("ingest_audio", {
+            audio_base64: audioBase64,
+            mime,
+            subject_hint: subjectHint,
+            scope: this.mergeScope(opts.scope),
+            source_id: opts.sourceId ?? `sdk-aud-${Date.now()}-${++rpcSeq}`,
+            observed_at: opts.observedAt ?? nowMicros(),
+        });
+    }
+    /**
+     * Make a PDF part of memory via the hybrid path: the text layer is extracted AND each page is rendered
+     * to an image read by a VLM, both written as claims — so a document (text-based or scanned) is
+     * recallable by an ordinary TEXT query. `pdfBase64` is the raw base64 (no data: prefix). Check `.ok`.
+     */
+    async ingestPdf(pdfBase64, subjectHint, opts = {}) {
+        return this.call("ingest_pdf", {
+            pdf_base64: pdfBase64,
+            subject_hint: subjectHint,
+            scope: this.mergeScope(opts.scope),
+            source_id: opts.sourceId ?? `sdk-pdf-${Date.now()}-${++rpcSeq}`,
+            observed_at: opts.observedAt ?? nowMicros(),
+        });
+    }
+    /**
+     * Ingest clean CSV or JSON DIRECTLY into claims — no LLM, no hallucination, no token cost. Each row is
+     * an entity, each column/key a predicate, each value an object. `format` is "csv" or "json";
+     * `subjectField` names the column/key that is the entity (omit ⇒ subjectHint + row index).
+     */
+    async ingestStructured(data, format, subjectHint, opts = {}) {
+        return this.call("ingest_structured", {
+            data,
+            format,
+            ...(opts.subjectField !== undefined ? { subject_field: opts.subjectField } : {}),
+            subject_hint: subjectHint,
+            scope: this.mergeScope(opts.scope),
+            source_id: opts.sourceId ?? `sdk-str-${Date.now()}-${++rpcSeq}`,
+            observed_at: opts.observedAt ?? nowMicros(),
+        });
+    }
+    /**
+     * Primary universal save API: hand Cilow literally any data. Pass exactly one of
+     * `contentBase64` (any bytes) or `text` (prose / CSV / JSON / a bare URL) in `content`. The data is
+     * sniffed, the ORIGINAL retained durably (`raw_id`/`blob_id`), a document entity + metadata claims
+     * written (so even unknown bytes are findable), and the matching typed reader runs when one exists.
+     * Reader/provider failures are surfaced in-band as `status: "degraded"` + `reader_error`, not as a
+     * calibrated "memory does not know" read abstain.
+     */
+    async save(content, opts = {}) {
+        return this.call("save", {
+            ...("contentBase64" in content
+                ? { content_base64: content.contentBase64 }
+                : { text: content.text }),
+            ...(opts.mime !== undefined ? { mime: opts.mime } : {}),
+            subject_hint: opts.subjectHint ?? "",
+            ...(opts.metadata !== undefined ? { metadata: opts.metadata } : {}),
+            scope: this.mergeScope(opts.scope),
+            source_id: opts.sourceId ?? `sdk-save-${Date.now()}-${++rpcSeq}`,
+            observed_at: opts.observedAt ?? nowMicros(),
+        });
+    }
+    /**
+     * Legacy alias for `save`: the universal NEVER-REJECT ingest. Pass exactly one of
+     * `contentBase64` (any bytes) or `text` (prose / CSV / JSON / a bare URL) in `content`. The data is
+     * sniffed, the ORIGINAL retained durably (`blob_id`), a document entity + metadata claims written
+     * (so even unknown bytes are findable), and the matching typed reader runs when one exists (a URL
+     * is fetched + snapshotted; replay never re-fetches). `ok` is false only for malformed ARGUMENTS;
+     * unknown types and reader failures are `ok: true` with `routed` absent + `reader_error` set.
+     */
+    async ingestAny(content, opts = {}) {
+        return this.call("ingest_any", {
+            ...("contentBase64" in content
+                ? { content_base64: content.contentBase64 }
+                : { text: content.text }),
+            ...(opts.mime !== undefined ? { mime: opts.mime } : {}),
+            subject_hint: opts.subjectHint ?? "",
+            ...(opts.metadata !== undefined ? { metadata: opts.metadata } : {}),
+            scope: this.mergeScope(opts.scope),
+            source_id: opts.sourceId ?? `sdk-any-${Date.now()}-${++rpcSeq}`,
+            observed_at: opts.observedAt ?? nowMicros(),
+        });
+    }
+    /**
+     * Retire memory (retire-not-delete), or destroy it when `erase: true` (OF1).
+     *
+     * Retire: omit `attribute` to forget the whole entity, set it to forget one attribute, add
+     * `value` to forget one value. As-of-T history before `at` is preserved.
+     *
+     * Erase: whole-entity destruction; counters on the receipt. Not complete Art.17.
+     */
+    async forget(entity, opts = {}) {
+        const erase = opts.erase === true;
+        return this.call("forget", {
+            entity,
+            ...(erase
+                ? { erase: true }
+                : {
+                    ...(opts.attribute !== undefined ? { attribute: opts.attribute } : {}),
+                    ...(opts.value !== undefined ? { value: opts.value } : {}),
+                }),
+            scope: this.mergeScope(opts.scope),
+            at: opts.at ?? nowMicros(),
+        });
+    }
+    /** Destructive right-to-be-forgotten path — `forget(entity, { erase: true })`. */
+    async erase(entity, opts = {}) {
+        return this.forget(entity, { erase: true, scope: opts.scope, at: opts.at });
+    }
+    /**
+     * Curated injectible pack + citations + trunk/suffix — no free-form synthesis (D2).
+     * When session trunk is on and `session != 0`, `trunk` is the stable multi-turn prefix.
+     */
+    async contextPack(query, opts = {}) {
+        return this.call("context_pack", {
+            query,
+            scope: this.mergeScope(opts.scope),
+            now: opts.now ?? nowMicros(),
+            ...(opts.asOf !== undefined ? { as_of: opts.asOf } : {}),
+            ...(opts.anchor !== undefined ? { anchor: opts.anchor } : {}),
+            ...(opts.attribute !== undefined ? { attribute: opts.attribute } : {}),
+        });
+    }
+    // ── The four core verbs: ingest / contextPack / forget / explain ─────────
+    // `contextPack` and `forget` are above; `ingest` and `explain` complete the set.
+    /**
+     * The ONE write door (core verb #1): store `{ facts }` | `{ text }` | `{ url }` | `{ contentBase64 }`.
+     *
+     * - `facts` — `[{ subject, predicate, object, multi? }]`. Rides the `remember` path. A new value for
+     *   an exclusive attribute SUPERSEDES the old one (history stays queryable via `contextPack({ asOf })`);
+     *   `multi: true` on a fact lets values coexist. `source` / `rawContext` / `branch` apply here.
+     * - `text` (prose / CSV / JSON), `url` (a bare URL — sent as `text`; the server fetches + snapshots
+     *   it), `contentBase64` (+ `mime` hint) — ride the never-reject `ingest_any` path: the original is
+     *   retained durably (`content.blob_id`), a document entity + `metadata` claims are written, and the
+     *   matching typed reader runs when one exists. `subjectHint` / `metadata` apply here.
+     *
+     * `sourceId` defaults to a CONTENT HASH (`ingestSourceId`) so a retry of the same payload is an
+     * idempotent no-op; the key actually sent is echoed on `source_id`. Never throws for content —
+     * only for a transport / auth failure.
+     */
+    async ingest(content, opts = {}) {
+        const sourceId = opts.sourceId ?? ingestSourceId(content);
+        const common = {
+            scope: this.mergeScope(opts.scope),
+            source_id: sourceId,
+            observed_at: opts.observedAt ?? nowMicros(),
+        };
+        if ("facts" in content) {
+            const wire = await this.call("ingest", {
+                facts: content.facts,
+                source: opts.source ?? "operator",
+                ...(opts.rawContext !== undefined ? { raw_context: opts.rawContext } : {}),
+                ...(opts.branch !== undefined ? { branch: opts.branch } : {}),
+                ...common,
+            });
+            return {
+                kind: "facts",
+                source_id: sourceId,
+                ok: wire.ok ?? true,
+                facts_ingested: wire.claims_emitted ?? 0,
+                deduped: wire.deduped ?? false,
+                remember: wire,
+                ...(wire.error !== undefined ? { error: wire.error } : {}),
+            };
+        }
+        const payload = "contentBase64" in content
+            ? { content_base64: content.contentBase64, ...(content.mime !== undefined ? { mime: content.mime } : {}) }
+            : { text: "url" in content ? content.url : content.text };
+        const wire = await this.call("ingest", {
+            ...payload,
+            subject_hint: opts.subjectHint ?? "",
+            ...(opts.metadata !== undefined ? { metadata: opts.metadata } : {}),
+            ...common,
+        });
+        return {
+            kind: "content",
+            source_id: sourceId,
+            ok: wire.ok,
+            facts_ingested: wire.facts_ingested ?? 0,
+            deduped: wire.deduped ?? false,
+            remember: wire.remember,
+            content: wire,
+            ...(wire.trace_id !== undefined ? { trace_id: wire.trace_id } : {}),
+            ...(wire.error !== undefined ? { error: wire.error } : {}),
+        };
+    }
+    /**
+     * Why did a pack / recall surface what it surfaced? (core verb #4) Pass the `trace_id` from a
+     * `contextPack` / `recall` response. The report carries the cited claims (labels resolved, each with
+     * its inclusion probability), the read's `best_nonconformity` vs the tenant's grounding threshold
+     * `q_hat`, and whether the read was grounded (`isGrounded(r)`) or a gap. Read-only: explaining never
+     * consumes the feedback trace. `found: false` + `error` (`unknown_trace` / `cross_tenant`) is in-band.
+     */
+    async explain(traceId, opts = {}) {
+        return this.call("explain", {
+            trace_id: traceId,
+            scope: this.mergeScope(opts.scope),
+        });
+    }
+    // ── Retained blobs (the lossless raw lane) ───────────────────────────────
+    /**
+     * Read a retained original back by its hex `blob_id` (from an ingest receipt or `blobList`).
+     * Full sha256-verified read by default; pass `offset`/`length` for a chunk-indexed RANGE read
+     * of a large blob (EOF-clamped; `total_len` in the response lets you paginate; `byte_len` is
+     * the returned window). `found:false` with no `error` is an ordinary miss; `error` in
+     * {invalid_id, invalid_range, storage, corrupt} means the range read FAILED — never treat it
+     * as absence. Bytes ride back in `data_base64`.
+     */
+    async blobGet(blobId, opts = {}) {
+        return this.call("blob_get", {
+            blob_id: blobId,
+            ...(opts.offset !== undefined ? { offset: opts.offset } : {}),
+            ...(opts.length !== undefined ? { length: opts.length } : {}),
+            scope: this.mergeScope(opts.scope),
+        });
+    }
+    /**
+     * One retained blob's METADATA (mime, byte length, provenance, metadata pairs, chunk count) by
+     * hex `blob_id` — no bytes. `found:false` ⇒ this tenant retains no such blob.
+     */
+    async blobMeta(blobId, scope) {
+        return this.call("blob_meta", { blob_id: blobId, scope: this.mergeScope(scope) });
+    }
+    /** Enumerate this tenant's retained original blobs with metadata (no bytes), deterministically ordered. */
+    async blobList(scope) {
+        return this.call("blob_list", { scope: this.mergeScope(scope) });
+    }
+    // ── Verified Context Runtime ───────────────────────────────────────────
+    async createContextWorkspace(name, scope) {
+        return this.call("context_workspace_create", { name, scope: this.mergeScope(scope), now: nowMicros() });
+    }
+    async ingestEvidence(input) {
+        return this.call("evidence_ingest", { workspace_id: input.workspaceId, source_id: input.sourceId, source_revision: input.sourceRevision, text: input.text, mime: input.mime ?? "text/plain", metadata: input.metadata ?? {}, coordinates: input.coordinates ?? [], trust: input.trust ?? "user_provided", acl_principals: input.aclPrincipals ?? [], scope: this.mergeScope(input.scope), observed_at: nowMicros() });
+    }
+    async investigate(workspaceId, query, opts = {}) {
+        return this.call("context_investigate", { workspace_id: workspaceId, query, token_budget: opts.tokenBudget ?? 2000, scope: this.mergeScope(opts.scope), now: nowMicros() });
+    }
+    async compileContext(workspaceId, query, opts) {
+        return this.call("context_compile", {
+            workspace_id: workspaceId,
+            query,
+            model_id: opts.modelId,
+            tokenizer_id: opts.tokenizerId,
+            model_context_token_budget: opts.modelContextTokenBudget ?? 1024,
+            audit_payload_byte_budget: opts.auditPayloadByteBudget ?? 256 * 1024,
+            prompt_template_id: opts.promptTemplateId ?? "cilow/context/plain/v1",
+            as_of: opts.asOf ?? nowMicros(),
+            scope: this.mergeScope(opts.scope),
+        });
+    }
+    async getCompiledContext(receiptId, scope) {
+        return this.call("context_program_get", {
+            receipt_id: receiptId,
+            scope: this.mergeScope(scope),
+        });
+    }
+    async getContextTrace(traceId, scope) {
+        return this.call("context_trace_get", { trace_id: traceId, scope: this.mergeScope(scope) });
+    }
+    async recordAgentEpisode(workspaceId, summary, evidenceIds, scope) {
+        return this.call("agent_episode_record", { workspace_id: workspaceId, summary, evidence_ids: evidenceIds, scope: this.mergeScope(scope), occurred_at: nowMicros() });
+    }
+    async proposeMemory(input) {
+        return this.call("memory_propose", { workspace_id: input.workspaceId, episode_id: input.episodeId, subject: input.subject, predicate: input.predicate, value: input.value, evidence_ids: input.evidenceIds, scope: this.mergeScope(input.scope), now: nowMicros() });
+    }
+    async verifyMemory(proposalId, accept, reason, scope) {
+        return this.call("memory_verify", { proposal_id: proposalId, accept, reason, scope: this.mergeScope(scope), now: nowMicros() });
+    }
+    // ── internals ───────────────────────────────────────────────────────────
+    mergeScope(override) {
+        return { ...this.scope, ...(override ?? {}) };
+    }
+    /**
+     * Issue one JSON-RPC `tools/call` and return the engine's `structuredContent`.
+     * Maps every failure mode (transport, HTTP, JSON-RPC error, malformed body) to a CilowError.
+     */
+    async call(name, args) {
+        const id = ++rpcSeq;
+        const envelope = {
+            jsonrpc: "2.0",
+            id,
+            method: "tools/call",
+            params: { name, arguments: args },
+        };
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        let res;
+        try {
+            res = await this.fetchImpl(`${this.baseUrl}/rpc`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${this.token}`,
+                },
+                body: JSON.stringify(envelope),
+                signal: controller.signal,
+            });
+        }
+        catch (cause) {
+            throw new CilowError(`request to ${this.baseUrl}/rpc failed: ${describe(cause)}`, { cause });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        let body;
+        const text = await res.text();
+        try {
+            body = text ? JSON.parse(text) : undefined;
         }
-      }
-      const queryString = params.toString();
-      if (queryString) {
-        url += `?${queryString}`;
-      }
-    }
-    if (this.debug) {
-      console.log(`Cilow API: ${method} ${url}`);
-    }
-    const response = await fetchWithRetry(
-      url,
-      {
-        method,
-        headers: this.headers,
-        body: body ? JSON.stringify(body) : void 0
-      },
-      { timeout: this.timeout, retries: this.retries, debug: this.debug }
-    );
-    const text = await response.text();
-    if (!text) {
-      return void 0;
-    }
-    return JSON.parse(text);
-  }
-  // ===========================================================================
-  // Simple API (remember, recall, forget)
-  // ===========================================================================
-  /**
-   * Store a memory (simple API)
-   *
-   * @param content - The content to remember
-   * @param options - Optional configuration
-   * @returns The created memory ID
-   *
-   * @example
-   * ```typescript
-   * await cilow.remember("User prefers dark mode", {
-   *   tags: ["preference"],
-   *   userId: "user-123"
-   * });
-   * ```
-   */
-  async remember(content, options) {
-    const response = await this.request("POST", "/api/v1/memory/add", {
-      content,
-      tags: options?.tags ?? [],
-      user_id: options?.userId,
-      session_id: options?.sessionId,
-      metadata: options?.metadata,
-      type: options?.tier
-    });
-    return response.memory_id || response.id || "";
-  }
-  /**
-   * Search memories (simple API)
-   *
-   * @param query - Search query text
-   * @param options - Search options
-   * @returns Array of search results
-   *
-   * @example
-   * ```typescript
-   * const memories = await cilow.recall("user preferences", {
-   *   limit: 10,
-   *   tags: ["preference"]
-   * });
-   * ```
-   */
-  async recall(query, options) {
-    const response = await this.request("POST", "/api/v1/memory/search", {
-      query,
-      limit: options?.limit ?? 10,
-      min_score: options?.minRelevance ?? 0.3,
-      tags: options?.tags,
-      user_id: options?.userId
-    });
-    return (response.results ?? []).map((r) => ({
-      memory: {
-        id: r.memory_id,
-        content: r.content,
-        tags: r.tags ?? [],
-        tier: "hot",
-        status: "active",
-        accessCount: 0,
-        tokenCount: Math.ceil(r.content.length / 4),
-        metadata: {},
-        createdAt: r.created_at ?? (/* @__PURE__ */ new Date()).toISOString(),
-        updatedAt: r.created_at ?? (/* @__PURE__ */ new Date()).toISOString(),
-        lastAccessedAt: (/* @__PURE__ */ new Date()).toISOString()
-      },
-      score: r.similarity,
-      highlights: []
-    }));
-  }
-  /**
-   * Delete memories (simple API)
-   *
-   * @param filter - Filter criteria for deletion
-   * @returns Number of memories deleted
-   *
-   * @example
-   * ```typescript
-   * // Delete by tags
-   * await cilow.forget({ tags: ["temporary"] });
-   *
-   * // Delete by user
-   * await cilow.forget({ userId: "user-123" });
-   *
-   * // Delete specific memory
-   * await cilow.forget({ memoryId: "mem-abc" });
-   * ```
-   */
-  async forget(filter) {
-    if (filter.memoryId) {
-      await this.deleteMemory(filter.memoryId);
-      return 1;
-    }
-    const response = await this.request("DELETE", "/api/v1/memories/bulk", {
-      filter_tags: filter.tags,
-      user_id: filter.userId,
-      session_id: filter.sessionId,
-      older_than: filter.olderThan
-    });
-    return response.deleted ?? 0;
-  }
-  // ===========================================================================
-  // Memory CRUD Operations
-  // ===========================================================================
-  /**
-   * Create a new memory
-   */
-  async createMemory(content, options) {
-    return this.request("POST", "/api/v1/memories", {
-      content,
-      tags: options?.tags ?? [],
-      user_id: options?.userId,
-      session_id: options?.sessionId,
-      metadata: options?.metadata,
-      tier: options?.tier
-    });
-  }
-  /**
-   * Get a memory by ID
-   */
-  async getMemory(memoryId) {
-    return this.request("GET", `/api/v1/memories/${memoryId}`);
-  }
-  /**
-   * Update a memory
-   */
-  async updateMemory(memoryId, updates) {
-    return this.request("PATCH", `/api/v1/memories/${memoryId}`, {
-      content: updates.content,
-      tags: updates.tags,
-      metadata: updates.metadata,
-      tier: updates.tier
-    });
-  }
-  /**
-   * Delete a memory
-   */
-  async deleteMemory(memoryId) {
-    await this.request("DELETE", `/api/v1/memories/${memoryId}`);
-  }
-  /**
-   * List memories with pagination
-   */
-  async listMemories(options) {
-    const response = await this.request(
-      "GET",
-      "/api/v1/memory/list",
-      void 0,
-      {
-        limit: options?.limit ?? 20,
-        offset: options?.offset ?? 0,
-        user_id: options?.userId,
-        session_id: options?.sessionId,
-        tags: options?.tags?.join(","),
-        type: options?.tier
-      }
-    );
-    const items = (response.memories ?? []).map((m) => ({
-      id: m.memory_id || m.id || "",
-      content: m.content,
-      tags: m.tags ?? [],
-      createdAt: m.created_at ?? (/* @__PURE__ */ new Date()).toISOString(),
-      tier: m.type || "hot"
-    }));
-    const limit = options?.limit ?? 20;
-    const offset = options?.offset ?? 0;
-    const total = response.total ?? items.length;
-    return {
-      items,
-      total,
-      limit,
-      offset,
-      hasMore: offset + items.length < total
-    };
-  }
-  // ===========================================================================
-  // Search Operations
-  // ===========================================================================
-  /**
-   * Search memories with full options
-   */
-  async searchMemories(query) {
-    const response = await this.request("POST", "/api/v1/memories/search", {
-      text: query.text,
-      limit: query.limit ?? 10,
-      min_relevance: query.minRelevance ?? 0.3,
-      filter_tags: query.tags,
-      user_id: query.userId,
-      session_id: query.sessionId,
-      tier: query.tier,
-      created_after: query.createdAfter,
-      created_before: query.createdBefore,
-      include_archived: query.includeArchived,
-      mode: query.mode ?? "hybrid"
-    });
-    return response.results ?? [];
-  }
-  /**
-   * Advanced search with reranking and boosts
-   */
-  async advancedSearch(query) {
-    const response = await this.request("POST", "/api/v1/memories/search/advanced", {
-      text: query.text,
-      limit: query.limit ?? 10,
-      min_relevance: query.minRelevance ?? 0.3,
-      filter_tags: query.tags,
-      required_tags: query.requiredTags,
-      excluded_tags: query.excludedTags,
-      user_id: query.userId,
-      session_id: query.sessionId,
-      recency_boost: query.recencyBoost,
-      frequency_boost: query.frequencyBoost,
-      metadata_filters: query.metadataFilters,
-      reranker: query.reranker
-    });
-    return response.results ?? [];
-  }
-  /**
-   * Get context for AI applications
-   */
-  async getContext(query, options) {
-    const maxTokens = options?.maxTokens ?? 4e3;
-    const tokensPerChar = 0.25;
-    const results = await this.searchMemories({
-      text: query,
-      limit: 30,
-      minRelevance: 0.3,
-      userId: options?.userId,
-      tags: options?.tags
-    });
-    let context = "";
-    let estimatedTokens = 0;
-    const memoryIds = [];
-    const scores = [];
-    for (const result of results) {
-      const memoryText = `[Relevance: ${(result.score * 100).toFixed(0)}%]
-${result.memory.content}
-
-`;
-      const memoryTokens = Math.ceil(memoryText.length * tokensPerChar);
-      if (estimatedTokens + memoryTokens > maxTokens) break;
-      context += memoryText;
-      estimatedTokens += memoryTokens;
-      memoryIds.push(result.memory.id);
-      scores.push(result.score);
-    }
-    return {
-      context: context.trim(),
-      memoriesUsed: memoryIds.length,
-      estimatedTokens,
-      memoryIds,
-      scores
-    };
-  }
-  // ===========================================================================
-  // Conversation Operations
-  // ===========================================================================
-  /**
-   * Store a conversation turn
-   */
-  async storeConversation(turn) {
-    const content = `User: ${turn.userMessage}
-
-Assistant: ${turn.assistantResponse}`;
-    const tags = ["conversation"];
-    if (turn.sessionId) {
-      tags.push(`session:${turn.sessionId}`);
-    }
-    return this.remember(content, {
-      tags,
-      userId: turn.userId,
-      sessionId: turn.sessionId,
-      metadata: {
-        type: "conversation",
-        ...turn.metadata
-      }
-    });
-  }
-  /**
-   * Get conversation history for a session
-   */
-  async getConversationHistory(sessionId, options) {
-    const response = await this.listMemories({
-      sessionId,
-      tags: ["conversation"],
-      limit: options?.limit ?? 50,
-      offset: options?.offset ?? 0
-    });
-    return response.items;
-  }
-  // ===========================================================================
-  // Graph Operations
-  // ===========================================================================
-  /**
-   * Get a graph node
-   */
-  async getGraphNode(nodeId) {
-    return this.request("GET", `/api/v1/graph/nodes/${nodeId}`);
-  }
-  /**
-   * Create a graph node
-   */
-  async createGraphNode(type, name, properties) {
-    return this.request("POST", "/api/v1/graph/nodes", {
-      type,
-      name,
-      properties: properties ?? {}
-    });
-  }
-  /**
-   * Create a graph edge
-   */
-  async createGraphEdge(sourceId, targetId, type, properties) {
-    return this.request("POST", "/api/v1/graph/edges", {
-      source_id: sourceId,
-      target_id: targetId,
-      type,
-      properties: properties ?? {}
-    });
-  }
-  /**
-   * Traverse the graph from a starting node
-   */
-  async traverseGraph(options) {
-    return this.request("POST", "/api/v1/graph/traverse", {
-      start_node_id: options.startNodeId,
-      max_depth: options.maxDepth ?? 3,
-      relationship_types: options.relationshipTypes,
-      limit: options.limit ?? 100,
-      direction: options.direction ?? "both"
-    });
-  }
-  /**
-   * Get related nodes for a memory
-   */
-  async getRelatedNodes(memoryId) {
-    const response = await this.request(
-      "GET",
-      `/api/v1/memories/${memoryId}/related-nodes`
-    );
-    return response.nodes ?? [];
-  }
-  // ===========================================================================
-  // Statistics & Admin
-  // ===========================================================================
-  /**
-   * Get memory statistics
-   */
-  async getStats() {
-    return this.request("GET", "/api/v1/stats");
-  }
-  /**
-   * Get all tags with counts
-   */
-  async getTags() {
-    const response = await this.request("GET", "/api/v1/tags");
-    return response.tags ?? [];
-  }
-  /**
-   * Get user statistics
-   */
-  async getUserStats(userId) {
-    return this.request("GET", `/api/v1/users/${userId}/stats`);
-  }
-  /**
-   * Health check
-   */
-  async healthCheck() {
-    return this.request("GET", "/health");
-  }
-  // ===========================================================================
-  // Batch Operations
-  // ===========================================================================
-  /**
-   * Batch create memories
-   */
-  async batchCreate(items) {
-    const response = await this.request("POST", "/api/v1/memories/batch", {
-      memories: items.map((item) => ({
-        content: item.content,
-        tags: item.options?.tags ?? [],
-        user_id: item.options?.userId,
-        session_id: item.options?.sessionId,
-        metadata: item.options?.metadata
-      }))
-    });
-    return response.ids ?? [];
-  }
-  /**
-   * Batch delete memories
-   */
-  async batchDelete(memoryIds) {
-    const response = await this.request("DELETE", "/api/v1/memories/batch", {
-      ids: memoryIds
-    });
-    return response.deleted ?? 0;
-  }
-};
-function createClient(config) {
-  return new CilowClient(config);
+        catch (cause) {
+            throw new CilowError(`malformed JSON response (HTTP ${res.status}): ${text.slice(0, 200)}`, {
+                httpStatus: res.status,
+                cause,
+            });
+        }
+        const frame = body;
+        // A JSON-RPC error envelope (auth, parse, method-not-found, bad-args) — even on a 200.
+        if (frame?.error) {
+            throw new CilowError(frame.error.message ?? "Cilow JSON-RPC error", {
+                code: frame.error.code,
+                httpStatus: res.status,
+                data: frame.error.data,
+            });
+        }
+        if (!res.ok) {
+            throw new CilowError(`Cilow HTTP ${res.status}: ${text.slice(0, 200)}`, {
+                httpStatus: res.status,
+            });
+        }
+        // The MCP `tools/call` result carries the typed payload under `result.structuredContent`.
+        const result = frame?.result;
+        if (!result || result.structuredContent === undefined) {
+            throw new CilowError(`Cilow response missing result.structuredContent: ${text.slice(0, 200)}`, { httpStatus: res.status });
+        }
+        return result.structuredContent;
+    }
+    /**
+     * POST to `/v1/memories/<verb>` and return the parsed JSON body (plain REST, not JSON-RPC). With
+     * `allow404`, a 404 resolves to `null` (used by `memories.get`). Other 4xx/5xx throw a CilowError
+     * carrying the body's `error` string.
+     */
+    async callRest(verb, payload, opts = {}) {
+        const url = `${this.baseUrl}/v1/memories/${verb}`;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        let res;
+        try {
+            res = await this.fetchImpl(url, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${this.token}`,
+                },
+                body: JSON.stringify(payload),
+                signal: controller.signal,
+            });
+        }
+        catch (cause) {
+            throw new CilowError(`request to ${url} failed: ${describe(cause)}`, { cause });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (opts.allow404 && res.status === 404)
+            return null;
+        const text = await res.text();
+        let body;
+        try {
+            body = text ? JSON.parse(text) : undefined;
+        }
+        catch (cause) {
+            throw new CilowError(`malformed JSON response (HTTP ${res.status}): ${text.slice(0, 200)}`, {
+                httpStatus: res.status,
+                cause,
+            });
+        }
+        if (!res.ok) {
+            const err = body?.error;
+            throw new CilowError(err ?? `Cilow HTTP ${res.status}: ${text.slice(0, 200)}`, {
+                httpStatus: res.status,
+            });
+        }
+        return body;
+    }
+}
+function describe(e) {
+    if (e instanceof Error)
+        return e.message;
+    return String(e);
 }
-
-exports.CilowApiError = CilowApiError;
-exports.CilowClient = CilowClient;
-exports.createClient = createClient;
-//# sourceMappingURL=client.js.map
 //# sourceMappingURL=client.js.map