@quickchatai/quickreview 0.0.0-stage → 1.1.0

package/dist/src/openviking/client.js

@@ -0,0 +1,821 @@
+// The OpenViking HTTP client — the one place in the daemon that
+// knows OpenViking speaks HTTP on loopback :1933.
+//
+// Everything above this file (the `MemoryStore` seam, the round's
+// `ContextAssembler`) is engine-agnostic; everything below is the server. The
+// client's whole job is to turn an HTTP surface that can be down, slow, or
+// wrong into a TOTAL function: `OvOutcome<T>` for every call, never a
+// rejection.
+//
+// Four facts about the running v0.4.15 server shape this module. They were
+// verified against it and they contradict the published docs
+// in places — do not "correct" them back:
+//
+//   1. WRITES GO THROUGH `content/batch-write`, EXCLUSIVELY. For memory-context
+//      targets, bare `content/write` appends a server-side `MEMORY_FIELDS`
+//      footer that `content/read` strips again, and no API returns the stored
+//      hash — so a read → sha256 → write cycle 409s FOREVER on any file that
+//      endpoint created. Files written by batch-write carry no footer and
+//      round-trip exactly. This client therefore has NO `content/write`
+//      wrapper at all: the footgun is removed by absence, not by a comment.
+//   2. `replace_if_hash` with a stale `base_hash` returns 409 CONFLICT and
+//      leaves the file verifiably unchanged. That is a clean, ordinary answer
+//      ("someone edited this since you read it") — `conflict: true` on the
+//      outcome, never an exception. The SAME status and code also mean "the
+//      directory was locked by another writer" (`details.conflict_type =
+//      "path_busy"`: batch-write's root lock is a zero-timeout try-lock), and
+//      that one is NOT a refusal — nothing was checked. It is told apart by
+//      `details.conflict_type` alone and retried here.
+//   3. SEARCH IS `POST /api/v1/search/search` with `mode: "context"`, and the
+//      determinism knobs are pinned OFF here rather than left to the caller:
+//      `rewrite` and `query_expansion` both invoke a server-side LLM, and the
+//      daemon has no LLM in its hot path. Note the wire spelling: `rewrite` is
+//      typed `bool | "auto"` server-side, so "off" IS `false` — sending the
+//      string "off" is a 422, i.e. a silent memory outage.
+//   4. AUTH IS THE REVIEWER USER KEY, `Authorization: Bearer <key>`, and
+//      nothing else. The server confines that key to `user/reviewer/` (403
+//      across users — a real guarantee, not a convention), the identity
+//      headers are ignored in api_key mode, and an ADMIN/ROOT key must never
+//      appear here: ADMIN grants no cross-user data access anyway and can list
+//      every user key in plaintext. The key is supplied by the caller, read
+//      lazily, and NEVER logged — `redact()` scrubs it out of every failure
+//      message at construction, before any caller can log or render one.
+import { readFileSync, statSync } from "node:fs";
+import { normalizeTag } from "../memory/store.js";
+/** Returns the FAILURE arm, not the union: a caller that builds one wants to
+ * read `conflict` off it without re-narrowing. A busy answer is never a
+ * conflict, whatever its status says. */
+export function ovFailed(status, code, message, busy = false) {
+    return {
+        ok: false,
+        status,
+        code,
+        message,
+        conflict: !busy && (status === 409 || code === "CONFLICT"),
+        busy,
+    };
+}
+/** The `details.conflict_type` the server stamps on a lock it could not take
+ * (`server/error_mapping.py`, `ResourceBusyError` / `LockAcquisitionError`). */
+export const BUSY_CONFLICT_TYPE = "path_busy";
+/**
+ * Is this error envelope the server's "directory busy, try again" answer?
+ * Keyed on `details.conflict_type`, never on the message text
+ * and never on the status alone: a hash-precondition 409 carries the same
+ * status and code, and it must stay a refusal.
+ */
+export function isBusyConflict(status, error) {
+    if (status !== 409 || !error || typeof error !== "object")
+        return false;
+    const details = error.details;
+    if (!details || typeof details !== "object")
+        return false;
+    return details.conflict_type === BUSY_CONFLICT_TYPE;
+}
+/** How hard the client retries a busy answer: at most `retries` more
+ * attempts, the n-th after a jittered `min(capMs, baseMs·2ⁿ)` wait (half to
+ * all of it), and no retry is STARTED once its wait would carry it past
+ * `budgetMs` from the first attempt — so a lock held for longer comes back as
+ * a failure the caller can see rather than a request that hangs. A retry that
+ * does start runs under the request's own timeout, so the whole call can end
+ * up to one timeout past the budget: an attempt cut short mid-write would
+ * leave its outcome unknown, which is worse than the wait. */
+export const BUSY_RETRY_DEFAULTS = Object.freeze({
+    retries: 4,
+    baseMs: 250,
+    capMs: 2000,
+    budgetMs: 10_000,
+});
+/** The wait before busy retry number `retry` (0-based): full exponential
+ * step, capped, then jittered into [½, 1] of it so writers that collided once
+ * do not collide again in lockstep. Pure — `random` is injected. */
+export function busyRetryDelay(retry, random = Math.random, opts = {}) {
+    const base = opts.baseMs ?? BUSY_RETRY_DEFAULTS.baseMs;
+    const cap = opts.capMs ?? BUSY_RETRY_DEFAULTS.capMs;
+    const step = Math.min(cap, base * 2 ** Math.max(0, retry));
+    const r = Math.min(1, Math.max(0, random()));
+    return Math.round(step * (0.5 + r / 2));
+}
+/** Server error codes that mean "this key does not authenticate here". */
+const AUTH_CODES = new Set([
+    "UNAUTHENTICATED",
+    "UNAUTHORIZED",
+    "PERMISSION_DENIED",
+    "FORBIDDEN",
+    "INVALID_API_KEY",
+]);
+/**
+ * Is this answer an authentication failure?
+ *
+ * A 401/403, an auth error code, or the message the 0.4.15 server actually
+ * sends on a bad key ("Invalid API Key"), which it has been seen to wrap in an
+ * HTTP-200 error envelope. Read as plain "memory unavailable", a refused key
+ * goes unreported; this predicate is what lets every reader call it what it
+ * is. `no_key` (nothing to send at all) is NOT this — callers
+ * that care treat it alongside, by code.
+ */
+export function isAuthFailure(status, code, message = "") {
+    if (status === 401 || status === 403)
+        return true;
+    if (AUTH_CODES.has(code.toUpperCase()))
+        return true;
+    return /invalid api key|unauthenticated|unauthori[sz]ed/i.test(message);
+}
+/**
+ * Is this answer a NOT_FOUND? The server authenticates a key
+ * before it resolves a path, so a NOT_FOUND is an authenticated ANSWER — the
+ * path is not there — never an outage. The store already reads it as "absent,
+ * known-empty" and ovsession's delete as the desired end state; the probe and
+ * the request observer read it the same way through this one predicate.
+ */
+export function isNotFound(_status, code) {
+    return code === "NOT_FOUND";
+}
+/**
+ * The quota buckets the server will accept (`CATEGORY_KEYS` in
+ * `retrieve/context_assembler/params.py`). An unknown key is a 422 for the
+ * WHOLE request, so unknown keys are dropped with a gap rather than sent.
+ */
+export const QUOTA_CATEGORIES = [
+    "events",
+    "entities",
+    "preferences",
+    "experiences",
+    "resources",
+    "skills",
+];
+/** The most exclusions one search request carries. A request-size bound, not
+ * a correctness one: past it the search can return an excluded entry, so a
+ * caller that must never see one (the round's context block) filters the
+ * result against its full list too. */
+export const EXCLUDE_URIS_CAP = 200;
+/**
+ * The exact body of a context search — pure, so the determinism guarantees are
+ * unit-testable without a server.
+ *
+ * `mode`, `rewrite` and `query_expansion` are NOT parameters. A round prompt
+ * must be reproducible from the round order, and both `rewrite: "auto"` and
+ * `query_expansion: "auto"` (the server's DEFAULT for the latter) put an LLM
+ * inside the daemon's hot path. They are pinned off here so no caller can ask
+ * for them by accident.
+ */
+export function buildContextSearchBody(query, opts = {}, onGap) {
+    const body = {
+        query,
+        mode: "context",
+        // `false`, not "off": the server types this `bool | "auto"`.
+        rewrite: false,
+        query_expansion: "off",
+    };
+    if (opts.maxTokens !== undefined)
+        body["max_tokens"] = Math.max(64, Math.min(32000, Math.floor(opts.maxTokens)));
+    if (opts.limit !== undefined)
+        body["limit"] = Math.max(1, Math.floor(opts.limit));
+    if (opts.scoreThreshold !== undefined)
+        body["score_threshold"] = opts.scoreThreshold;
+    if (opts.purpose !== undefined)
+        body["purpose"] = opts.purpose;
+    if (opts.quotas) {
+        const quotas = {};
+        for (const [key, value] of Object.entries(opts.quotas)) {
+            if (!QUOTA_CATEGORIES.includes(key)) {
+                onGap?.({
+                    op: "search",
+                    status: 0,
+                    code: "bad_quota",
+                    message: `dropped unknown quota category '${key}'`,
+                });
+                continue;
+            }
+            quotas[key] = Math.max(0, Math.floor(value));
+        }
+        if (Object.keys(quotas).length > 0)
+            body["quotas"] = quotas;
+    }
+    const tags = (opts.tags ?? []).map((tag) => normalizeTag(tag).trim()).filter((t) => t !== "");
+    if (tags.length > 0)
+        body["tags"] = [...new Set(tags)];
+    if (opts.since)
+        body["since"] = opts.since;
+    if (opts.until)
+        body["until"] = opts.until;
+    if (opts.timeField)
+        body["time_field"] = opts.timeField;
+    if (opts.excludeUris && opts.excludeUris.length > 0) {
+        body["exclude_uris"] = opts.excludeUris.slice(0, EXCLUDE_URIS_CAP);
+        if (opts.excludeUris.length > EXCLUDE_URIS_CAP)
+            onGap?.({
+                op: "search",
+                status: 0,
+                code: "exclude_truncated",
+                message: `sent ${EXCLUDE_URIS_CAP} of ${opts.excludeUris.length} exclusions; the rest are filtered from the result by the caller`,
+            });
+    }
+    return body;
+}
+/**
+ * The exact body of a `/search/find` — pure, so its determinism is testable:
+ * the query, the area(s) and the limit, and NOTHING that turns a server-side
+ * LLM on. No `session_id` (the expansion stage keys on one) and no
+ * `score_threshold` (the caller's filters decide, not a similarity floor).
+ */
+export function buildFindBody(query, opts) {
+    const target = Array.isArray(opts.targetUri) ? [...opts.targetUri] : opts.targetUri;
+    const body = { query, target_uri: target };
+    if (opts.limit !== undefined)
+        body["limit"] = Math.max(1, Math.floor(opts.limit));
+    return body;
+}
+/**
+ * The session memory policy every session this system creates MUST carry.
+ *
+ * Our deployment configures no `vlm` on purpose — memories are AUTHORED by
+ * sessions and the EOD curator, never extracted. A session created without
+ * this policy queues an extraction task on every single commit and every one
+ * of them FAILS (verified). Disabling all three at create time makes commit
+ * complete cleanly with `memories_extracted: {}` and zero LLM tokens.
+ */
+export const DISABLED_MEMORY_POLICY = Object.freeze({
+    self: { enabled: false },
+    peer: { enabled: false },
+    working_memory: { enabled: false },
+});
+/**
+ * Reads a key file and remembers the answer (including "not there"),
+ * re-checking at most every `ttlMs`.
+ *
+ * A secret that lands after boot is picked up without a restart, and a missing
+ * one does not stat the disk per request. A found key is not remembered
+ * forever: every `ttlMs` the file is re-stat'ed, and a file whose identity
+ * (inode, size or mtime) changed is re-read — so a rotated key reaches the
+ * daemon within one TTL, and a removed one stops being sent. A 401 from the
+ * server calls `invalidate()` (see `OpenVikingClient`), which makes the very
+ * next request re-read the file.
+ */
+export function keyFromFile(path, ttlMs = 60_000, now = Date.now) {
+    let cached = null;
+    let signature = null;
+    let checkedAt = -Infinity;
+    const read = () => {
+        if (now() - checkedAt < ttlMs)
+            return cached;
+        checkedAt = now();
+        let sig;
+        try {
+            const st = statSync(path);
+            sig = `${st.ino}:${st.size}:${st.mtimeMs}`;
+        }
+        catch {
+            // Gone (or unreadable): a key that is no longer on disk is no longer
+            // ours to send. A keyless client is loud (`no_key`), never silent.
+            cached = null;
+            signature = null;
+            return cached;
+        }
+        if (sig === signature && cached !== null)
+            return cached;
+        try {
+            const value = readFileSync(path, "utf8").trim();
+            cached = value === "" ? null : value;
+            signature = sig;
+        }
+        catch {
+            cached = null;
+            signature = null;
+        }
+        return cached;
+    };
+    const source = read;
+    source.invalidate = () => {
+        checkedAt = -Infinity;
+        signature = null;
+    };
+    return source;
+}
+const DEFAULT_TIMEOUT_MS = 10_000;
+export class OpenVikingClient {
+    baseUrl;
+    key;
+    /** The key source's cache-drop, when it has one (`keyFromFile`). */
+    invalidateKey;
+    user;
+    account;
+    peerId;
+    timeoutMs;
+    fetchFn;
+    log;
+    onGap;
+    onRequest;
+    clock;
+    busyRetry;
+    sleep;
+    random;
+    keyGapReported = false;
+    constructor(opts) {
+        this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+        const source = opts.apiKey;
+        this.key = typeof source === "function" ? () => source() ?? null : () => source ?? null;
+        const invalidate = typeof source === "function" ? source.invalidate : undefined;
+        this.invalidateKey = typeof invalidate === "function" ? () => invalidate() : undefined;
+        this.user = opts.user ?? "reviewer";
+        this.account = opts.account ?? "";
+        this.peerId = opts.peerId ?? "";
+        this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.fetchFn = opts.fetchFn ?? defaultFetch;
+        this.log = opts.log ?? (() => { });
+        this.onGap = opts.onGap;
+        this.onRequest = opts.onRequest;
+        this.clock = opts.clock ?? Date.now;
+        this.busyRetry = { ...BUSY_RETRY_DEFAULTS, ...(opts.busyRetry ?? {}) };
+        this.sleep = opts.sleep ?? defaultSleep;
+        this.random = opts.random ?? Math.random;
+    }
+    /** Hand one request's outcome to the observer — never throws. */
+    observe(record) {
+        try {
+            this.onRequest?.(record);
+        }
+        catch {
+            // A counter that throws must not become a memory outage.
+        }
+    }
+    /** The user tree this client's key is confined to — the root every memory
+     * URI is built under. */
+    memoriesRoot() {
+        return `viking://user/${this.user}/memories`;
+    }
+    /** Scrub the key out of a string before it can leave this class. The key is
+     * never deliberately logged; this is the belt to that braces, because server
+     * error bodies have been known to echo request material. It is applied where
+     * a failure is CONSTRUCTED (`request()`), so every consumer of an
+     * `OvFailure.message` or `OvGap.message` — the round prompt's unreadable
+     * note, the overseer anomaly, the daemon log, the `onGap` sink — receives the
+     * scrubbed text; `report()` scrubs its own line again as braces. */
+    redact(text, sent) {
+        // The key the request CARRIED, when the caller has it: the source may
+        // have rotated while the request was out, and the echo is of the old one.
+        let out = text;
+        for (const key of new Set([sent, this.key()])) {
+            if (key && key.length >= 8)
+                out = out.split(key).join("<redacted>");
+        }
+        return out;
+    }
+    report(gap) {
+        this.log(`openviking: ${gap.op} failed (${gap.status || "no answer"} ${gap.code}): ${this.redact(gap.message)}`);
+        try {
+            this.onGap?.(gap);
+        }
+        catch {
+            // An alerting sink that throws must not become a memory outage, and
+            // certainly must not propagate into a review round.
+        }
+    }
+    /**
+     * One request, total. Every failure mode — no key, connection refused,
+     * timeout, non-JSON body, `{status:"error"}` envelope, a `fetch` seam that
+     * throws synchronously — comes back as the failure arm of `OvOutcome`.
+     *
+     * A BUSY answer (`409 path_busy`, see `OvFailure`) is retried here, for
+     * every operation: the server answers busy before it checks or writes
+     * anything, so a repeat can never double a write. Each retried busy answer
+     * is observed as an answer (`conflict` — the server is up and took the
+     * key); one still busy when `BUSY_RETRY_DEFAULTS` runs out is reported as
+     * the gap it is and returned `busy: true`. A hash-precondition 409 is never
+     * retried: it is the refusal it says it is.
+     */
+    async request(op, path, init) {
+        const started = this.clock();
+        for (let retry = 0;; retry += 1) {
+            const { res, ms } = await this.attempt(op, path, init);
+            if (res.ok || !res.busy)
+                return res;
+            const delay = busyRetryDelay(retry, this.random, this.busyRetry);
+            const elapsed = this.clock() - started;
+            if (retry >= this.busyRetry.retries || elapsed + delay > this.busyRetry.budgetMs) {
+                const message = `${res.message} — still busy after ${retry} ${retry === 1 ? "retry" : "retries"} (${elapsed} ms); nothing was written`;
+                this.report({ op, status: res.status, code: BUSY_CONFLICT_TYPE, message });
+                this.observe({
+                    op,
+                    outcome: "failed",
+                    status: res.status,
+                    code: BUSY_CONFLICT_TYPE,
+                    ms,
+                    message,
+                });
+                return ovFailed(res.status, res.code, message, true);
+            }
+            this.observe({
+                op,
+                outcome: "conflict",
+                status: res.status,
+                code: BUSY_CONFLICT_TYPE,
+                ms,
+                message: res.message,
+            });
+            this.log(`openviking: ${op} answered busy (${BUSY_CONFLICT_TYPE}) — retry ${retry + 1} in ${delay} ms`);
+            await this.sleep(delay);
+        }
+    }
+    /** One attempt of `request()`. Observes and reports everything except a
+     * busy answer, which `request()` decides about (retry, or report once). */
+    async attempt(op, path, init) {
+        const key = this.key();
+        if (!key) {
+            // Reported ONCE per client: a keyless deployment is a standing condition
+            // (a dev PC with no secret), and every call would otherwise raise the
+            // same anomaly. It must still never look like success — and the
+            // observer hears EVERY one, because the health monitor counts it as an
+            // authentication failure rather than as quiet.
+            if (!this.keyGapReported) {
+                this.keyGapReported = true;
+                this.report({
+                    op,
+                    status: 0,
+                    code: "no_key",
+                    message: "no OpenViking reviewer key configured — every memory call degrades until one is",
+                });
+            }
+            this.observe({
+                op,
+                outcome: "auth",
+                status: 0,
+                code: "no_key",
+                ms: 0,
+                message: "no OpenViking key configured",
+            });
+            return { res: ovFailed(0, "no_key", "no OpenViking reviewer key configured"), ms: 0 };
+        }
+        const started = this.clock();
+        const headers = {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${key}`,
+        };
+        // Ignored in api_key mode, load-bearing in trusted mode. Harmless either
+        // way, and it keeps the identity explicit in the request we send.
+        if (this.account)
+            headers["X-OpenViking-Account"] = this.account;
+        if (this.user)
+            headers["X-OpenViking-User"] = this.user;
+        if (this.peerId)
+            headers["X-OpenViking-Actor-Peer"] = this.peerId;
+        let res;
+        let raw;
+        try {
+            const signal = timeoutSignal(init.timeoutMs ?? this.timeoutMs);
+            res = await this.fetchFn(`${this.baseUrl}${path}`, {
+                method: init.method,
+                headers,
+                ...(init.body !== undefined ? { body: JSON.stringify(init.body) } : {}),
+                ...(signal ? { signal } : {}),
+            });
+            raw = await res.text();
+        }
+        catch (err) {
+            const gap = {
+                op,
+                status: 0,
+                code: "transport",
+                message: this.redact(errText(err), key),
+            };
+            this.report(gap);
+            this.observe({
+                op,
+                outcome: "failed",
+                status: 0,
+                code: gap.code,
+                ms: this.clock() - started,
+                message: gap.message,
+            });
+            return { res: ovFailed(gap.status, gap.code, gap.message), ms: this.clock() - started };
+        }
+        const ms = this.clock() - started;
+        // Every OpenViking answer is a `{status, result, error}` envelope. Anything
+        // else — an nginx error page, a bare `null`, an empty or truncated body, an
+        // object with no `status` — is NOT an answer, and a 200 carrying one must
+        // not be read as success: that is how a write that never happened gets
+        // reported as a write that did. A 200 succeeds only on `status: "ok"`.
+        let body = null;
+        try {
+            const parsed = JSON.parse(raw);
+            if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed))
+                body = parsed;
+        }
+        catch {
+            body = null;
+        }
+        if (res.ok && body !== null && body.status !== "ok" && body.status !== "error")
+            body = null;
+        if (body === null) {
+            if (res.ok) {
+                const gap = {
+                    op,
+                    status: res.status,
+                    code: "bad_body",
+                    message: `response was not an OpenViking envelope (${raw.length} bytes)`,
+                };
+                this.report(gap);
+                this.observe({
+                    op,
+                    outcome: "failed",
+                    status: gap.status,
+                    code: gap.code,
+                    ms,
+                    message: gap.message,
+                });
+                return { res: ovFailed(gap.status, gap.code, gap.message), ms };
+            }
+            body = {};
+        }
+        if (!res.ok || body.status === "error") {
+            const code = typeof body.error?.code === "string" ? body.error.code : `http_${res.status}`;
+            const message = this.redact(typeof body.error?.message === "string" ? body.error.message : `HTTP ${res.status}`, key);
+            // The directory lock was held: nothing was checked or
+            // written. `request()` retries it — not observed or reported here.
+            if (isBusyConflict(res.status, body.error)) {
+                return { res: ovFailed(res.status, code, message, true), ms };
+            }
+            const outcome = ovFailed(res.status, code, message);
+            const auth = isAuthFailure(res.status, code, message);
+            const absent = !auth && isNotFound(res.status, code);
+            // A 409 is the precondition working as designed, and the engine's own
+            // NOT_FOUND envelope is an authenticated answer (the path is not there —
+            // the store reads it as known-empty): neither is alerted on. A bare 404
+            // with no such code — a missing route, the wrong service behind the
+            // forward — is still reported: it is the one trace that says so.
+            const answered = outcome.conflict || (absent && code === "NOT_FOUND");
+            if (!answered)
+                this.report({ op, status: res.status, code, message });
+            this.observe({
+                op,
+                outcome: outcome.conflict ? "conflict" : auth ? "auth" : absent ? "absent" : "failed",
+                status: res.status,
+                code,
+                ms,
+                message,
+            });
+            // The key we sent was refused: drop the source's cache so the NEXT
+            // request reads the file again — a rotated key must not wait out a TTL
+            // behind a 401. Last, deliberately: `report()` reads the
+            // key to redact with, and a read after the drop would re-cache the very
+            // key that was just refused for another full TTL.
+            if (auth)
+                this.invalidateKey?.();
+            return { res: outcome, ms };
+        }
+        this.observe({ op, outcome: "ok", status: res.status, code: "", ms });
+        return { res: { ok: true, status: res.status, result: (body.result ?? body) }, ms };
+    }
+    // ---- content ---------------------------------------------------------------
+    /**
+     * The ONE write path. There is deliberately no `content/write` wrapper on
+     * this class — see the header. `conflict: true` on the outcome means a
+     * precondition refused (stale `base_hash`, or `create_if_absent` on a target
+     * that already exists), and the stored file is unchanged.
+     */
+    async batchWrite(request, timeoutMs) {
+        const res = await this.request("batch_write", "/api/v1/content/batch-write", {
+            method: "POST",
+            body: request,
+            ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+        });
+        if (!res.ok)
+            return res;
+        // The three URI lists are the only proof a write landed; normalizing them
+        // here means the caller checks membership rather than trusting a 200.
+        const raw = (res.result && typeof res.result === "object" ? res.result : {});
+        return {
+            ok: true,
+            status: res.status,
+            result: {
+                root_uri: str(raw["root_uri"]),
+                created: strings(raw["created"]),
+                updated: strings(raw["updated"]),
+                unchanged: strings(raw["unchanged"]),
+            },
+        };
+    }
+    /** L2 full content. Safe as a hash source ONLY because every file this
+     * system writes was written by batch-write and so carries no `MEMORY_FIELDS`
+     * footer for `content/read` to strip. */
+    async readContent(uri) {
+        const res = await this.request("read", `/api/v1/content/read?uri=${encodeURIComponent(uri)}`, { method: "GET" });
+        if (!res.ok)
+            return res;
+        // A successful envelope whose result is not text is a malformed answer,
+        // not an empty file: an empty read would pass for a healthy empty entry.
+        if (typeof res.result !== "string") {
+            return ovFailed(res.status, "MALFORMED_RESULT", "content/read result is not a string");
+        }
+        return { ok: true, status: res.status, result: res.result };
+    }
+    async ls(uri) {
+        const res = await this.request("ls", `/api/v1/fs/ls?uri=${encodeURIComponent(uri)}`, {
+            method: "GET",
+        });
+        if (!res.ok)
+            return res;
+        // Likewise a non-array result is a malformed answer, not an empty directory.
+        if (!Array.isArray(res.result)) {
+            return ovFailed(res.status, "MALFORMED_RESULT", "fs/ls result is not a list");
+        }
+        const rows = res.result;
+        return {
+            ok: true,
+            status: res.status,
+            result: rows
+                .filter((r) => !!r && typeof r === "object")
+                .map((r) => ({
+                uri: str(r["uri"]),
+                name: str(r["name"]) || basename(str(r["uri"])),
+                isDir: r["isDir"] === true,
+                size: typeof r["size"] === "number" ? r["size"] : 0,
+                modTime: str(r["modTime"]),
+            })),
+        };
+    }
+    remove(uri, recursive = false) {
+        return this.request("delete", `/api/v1/fs?uri=${encodeURIComponent(uri)}&recursive=${recursive}`, { method: "DELETE" });
+    }
+    /**
+     * Create a directory (and its parents). A fresh server has ONLY
+     * `viking://user/default`, so the first write into `user/<us>/memories/<cat>`
+     * 404s on the missing root — nothing else provisions the tree, and making
+     * boot order responsible for it would put a network call in front of the
+     * daemon. The store calls this lazily on that failure, and eagerly from
+     * `ensureWritable`.
+     */
+    async mkdir(uri, parents = true) {
+        const res = await this.request("mkdir", "/api/v1/fs/mkdir", {
+            method: "POST",
+            body: { uri, parents },
+        });
+        // `fs/mkdir` is NOT idempotent: an existing directory comes back CONFLICT
+        // ("already exists"), verified live against 0.4.15. Every caller here wants
+        // `mkdir -p` semantics — the directory is there afterwards either way — so
+        // the conflict is a success, not a failure to report upward.
+        return res.ok || res.conflict;
+    }
+    /**
+     * Set the retrieval tag list that search's `tags` filter reads. Best-effort
+     * by contract: the tags are already in the written body's header, which is
+     * what `content/read` returns and what the store parses, so a failure here
+     * narrows retrieval — it never loses the memory or its tags.
+     */
+    async setTags(uri, tags, mode = "replace") {
+        if (tags.length === 0 && mode === "append")
+            return true;
+        const res = await this.request("set_tags", "/api/v1/fs/attrs/set_tags", {
+            method: "POST",
+            body: { uri, tags, mode },
+        });
+        return res.ok;
+    }
+    // ---- search ----------------------------------------------------------------
+    /**
+     * A budgeted context search. Returns the rendered block AND the usage stats;
+     * callers that only want a prompt block take `.rendered`, callers that need
+     * to know what the budget bought read `.stats`.
+     */
+    async searchContext(query, opts = {}) {
+        const body = buildContextSearchBody(query, opts, (gap) => this.report(gap));
+        const res = await this.request("search", "/api/v1/search/search", {
+            method: "POST",
+            body,
+            ...(opts.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}),
+        });
+        if (!res.ok)
+            return res;
+        const result = (res.result && typeof res.result === "object" ? res.result : {});
+        const rawEntries = Array.isArray(result["entries"]) ? result["entries"] : [];
+        return {
+            ok: true,
+            status: res.status,
+            result: {
+                entries: rawEntries
+                    .filter((e) => !!e && typeof e === "object")
+                    .map((e) => ({
+                    uri: str(e["uri"]),
+                    category: str(e["category"]) || "memories",
+                    score: typeof e["score"] === "number" ? e["score"] : 0,
+                    detail: str(e["detail"]),
+                    text: str(e["text"]) || str(e["content"]) || str(e["abstract"]),
+                    origin: str(e["origin"]),
+                })),
+                rendered: str(result["rendered"]).trim(),
+                digest: str(result["digest"]).trim(),
+                stats: (result["stats"] && typeof result["stats"] === "object"
+                    ? result["stats"]
+                    : {}),
+            },
+        };
+    }
+    /**
+     * A plain vector search inside one or more areas (`POST /api/v1/search/find`):
+     * the hits the server ranks by similarity under `target_uri`,
+     * never a global top K filtered afterwards. The memories bucket only; each
+     * hit's text is its abstract (the stored content itself in a deployment
+     * without a VLM), else its overview.
+     *
+     * Deterministic by construction: no `session_id` is sent, so the server
+     * runs no query expansion (that stage keys on a session), and there is no
+     * rewrite stage on this route at all.
+     */
+    async find(query, opts) {
+        const res = await this.request("find", "/api/v1/search/find", {
+            method: "POST",
+            body: buildFindBody(query, opts),
+            ...(opts.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}),
+        });
+        if (!res.ok)
+            return res;
+        const result = (res.result && typeof res.result === "object" ? res.result : {});
+        const memories = Array.isArray(result["memories"]) ? result["memories"] : [];
+        return {
+            ok: true,
+            status: res.status,
+            result: memories
+                .filter((m) => !!m && typeof m === "object")
+                .map((m) => ({
+                uri: str(m["uri"]),
+                score: typeof m["score"] === "number" && Number.isFinite(m["score"]) ? m["score"] : 0,
+                text: str(m["abstract"]) || str(m["overview"]),
+            }))
+                .filter((h) => h.uri !== ""),
+        };
+    }
+    // ---- sessions --------------------------------------------------------------
+    /** Create a per-PR session with extraction fully disabled. The policy is not
+     * a parameter: a session without it rots (see `DISABLED_MEMORY_POLICY`). */
+    createSession(sessionId) {
+        return this.request("session_create", "/api/v1/sessions", {
+            method: "POST",
+            body: { session_id: sessionId, memory_policy: DISABLED_MEMORY_POLICY },
+        });
+    }
+    /**
+     * The ids of every session the key can see — what the
+     * stale-session sweep lists. The server swallows its OWN listing failures
+     * into an empty list (`session_service.py` `sessions()`), so `[]` means "none
+     * listed", never proof that none exist.
+     */
+    async listSessions() {
+        const res = await this.request("session_list", "/api/v1/sessions", {
+            method: "GET",
+        });
+        if (!res.ok)
+            return res;
+        const rows = Array.isArray(res.result) ? res.result : [];
+        const ids = rows
+            .map((r) => r && typeof r === "object" ? str(r["session_id"]) : "")
+            .filter((id) => id !== "");
+        return { ok: true, status: res.status, result: [...new Set(ids)] };
+    }
+    /** Removes the session's messages and archives (verified: the tree is gone).
+     * Sessions are absent from the search corpus, so this frees disk, not
+     * recall. */
+    deleteSession(sessionId) {
+        return this.request("session_delete", `/api/v1/sessions/${encodeURIComponent(sessionId)}`, { method: "DELETE" });
+    }
+}
+// ---- helpers ----------------------------------------------------------------
+function str(value) {
+    return typeof value === "string" ? value : "";
+}
+function strings(value) {
+    return Array.isArray(value) ? value.filter((v) => typeof v === "string") : [];
+}
+/** Did this URI actually land? A batch-write that returns 200 without naming
+ * the target in any of its three lists did NOT write it, and reporting that as
+ * a success is how a memory silently goes missing. */
+export function batchWriteLanded(result, uri) {
+    return (result.created.includes(uri) || result.updated.includes(uri) || result.unchanged.includes(uri));
+}
+function basename(uri) {
+    const cleaned = uri.replace(/\/+$/, "");
+    const cut = cleaned.lastIndexOf("/");
+    return cut >= 0 ? cleaned.slice(cut + 1) : cleaned;
+}
+/** A thrown request error as one line: a timeout or abort is "timeout",
+ * anything else its message. Shared by every OpenViking probe. */
+export function errText(err) {
+    if (err instanceof Error)
+        return err.name === "TimeoutError" || err.name === "AbortError" ? "timeout" : err.message;
+    return String(err);
+}
+/** `AbortSignal.timeout` where the runtime has it; undefined otherwise. Tests
+ * inject their own fetch and never see it. */
+function timeoutSignal(ms) {
+    try {
+        return AbortSignal.timeout(ms);
+    }
+    catch {
+        return undefined;
+    }
+}
+const defaultFetch = (url, init) => fetch(url, init);
+const defaultSleep = (ms) => new Promise((resolve) => {
+    const t = setTimeout(resolve, ms);
+    t.unref?.();
+});
+//# sourceMappingURL=client.js.map