@cilow/sdk 0.2.0 → 0.3.0

package/dist/client.js

@@ -0,0 +1,653 @@
+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 {
+            const res = await this.fetchImpl(`${this.baseUrl}/health`);
+            if (!res.ok)
+                return false;
+            const body = (await res.json());
+            return body.status === "ok";
+        }
+        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;
+        }
+        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);
+}
+//# sourceMappingURL=client.js.map