@quickchatai/quickreview 0.0.0-stage → 1.1.0

package/extensions/vendor/openviking-pi/client.ts

@@ -0,0 +1,588 @@
+import type { OVConfig } from "./config.js";
+// [QCR PATCH 6]
+import {
+  shouldRekey,
+  withBusyRetry,
+  type BusyRetryHooks,
+  type BusyRetryNote,
+} from "./qcr-honest.js";
+
+// --- OV API Response Shapes ---
+// All OV responses wrap in: { status: "ok"|"error", result: T, error?: {...}, ... }
+// This client normalizes to { ok, result } internally.
+
+export interface OVSearchResult {
+  uri: string;
+  context_type: string;   // "memory" | "resource" | "skill"
+  score: number;
+  abstract: string;
+  overview: string | null;
+  level: number;          // 0=L0, 1=L1, 2=L2
+  category: string;
+  match_reason: string;
+}
+
+export interface OVDirEntry {
+  uri: string;
+  name: string;
+  isDir: boolean;
+  size: number;
+  mode: number;
+  modTime: string;
+  abstract: string;
+}
+
+export interface OVStatInfo {
+  name: string;
+  size: number;
+  mode: number;
+  modTime: string;
+  isDir: boolean;
+  isLocked: boolean;
+  uri?: string;
+  count?: number;         // directories only
+}
+
+export interface OVSessionMeta {
+  session_id: string;
+  message_count: number;
+  total_message_count?: number;
+  commit_count: number;
+  pending_tokens?: number;
+  memories_extracted?: Record<string, number>;
+  last_commit_at?: string;
+}
+
+export interface OVSessionContext {
+  latest_archive_overview: string | null;
+  pre_archive_abstracts: any[];
+  messages: any[];
+  estimatedTokens: number;
+  stats: {
+    totalArchives: number;
+    includedArchives: number;
+    droppedArchives: number;
+    failedArchives: number;
+    activeTokens: number;
+    archiveTokens: number;
+  };
+}
+
+export interface OVCommitResult {
+  task_id?: string;
+  archive_uri?: string;
+  trace_id?: string;
+}
+
+export interface OVCommitResponse {
+  result: OVCommitResult | null;
+  traceId?: string;
+  error?: any;
+  status?: number;
+}
+
+/** [QCR PATCH 4] `content/batch-write` result envelope. */
+export interface OVBatchWriteResult {
+  root_uri: string;
+  created: string[];
+  updated: string[];
+  unchanged: string[];
+  queue_status?: Record<string, unknown>;
+}
+
+export interface OVResponse<T> {
+  ok: boolean;
+  result: T | null;
+  error?: any;
+  status?: number;
+  traceId?: string;
+}
+
+export class OVClient {
+  private baseUrl: string;
+  private apiKey: string;
+  private account: string;
+  private user: string;
+  private peerId: string;
+  connected: boolean = false;
+
+  private resolvedSpaces: Map<string, string> = new Map();
+
+  /** [QCR PATCH 6] Re-reads this client's key from its source (the
+   * ovcli.conf the daemon rewrites when its key rotates). Set by index.ts on
+   * the primary client only — an env-supplied key cannot change in-process.
+   * On an auth failure the request is retried ONCE, and only when the
+   * re-read key differs (`shouldRekey`). */
+  rekey: (() => string) | null = null;
+
+  /** [QCR PATCH 6] The busy retry's clock and sleep — real ones in pi; a
+   * test injects instant ones. */
+  retryHooks: BusyRetryHooks = {};
+
+  private static RESERVED_USER = new Set(["memories"]);
+  private static RESERVED_AGENT = new Set(["memories", "skills", "instructions", "workspaces"]);
+
+  /** Read-only access to config (for value access across modules). */
+  readonly cfg: OVConfig;
+
+  constructor(config: OVConfig) {
+    this.cfg = config;
+    this.baseUrl = config.endpoint.replace(/\/+$/, "");
+    this.apiKey = config.apiKey;
+    this.account = config.account;
+    this.user = config.user;
+    this.peerId = config.peerId;
+  }
+
+  private headers(): Record<string, string> {
+    const h: Record<string, string> = { "Content-Type": "application/json" };
+    if (this.apiKey) h["Authorization"] = `Bearer ${this.apiKey}`;
+    if (this.account) h["X-OpenViking-Account"] = this.account;
+    if (this.user) h["X-OpenViking-User"] = this.user;
+    if (this.peerId) h["X-OpenViking-Actor-Peer"] = this.peerId;
+    if (this.cfg.userAgent) h["User-Agent"] = this.cfg.userAgent;
+    return h;
+  }
+
+  /** Core fetch wrapper. Returns { ok, result } after parsing OV's { status, result } envelope. */
+  async fetchJSON<T>(path: string, init?: RequestInit, timeoutMs = 10000): Promise<OVResponse<T>> {
+    const res = await this.fetchOnce<T>(path, init, timeoutMs);
+    // [QCR PATCH 6] A refused key is re-read once from its source: the daemon
+    // rewrites the sessions' ovcli.conf the moment its key rotates, and a
+    // session that kept the key it loaded with stayed locked out until it
+    // died. Retried only when the re-read key is actually different.
+    if (!res.ok && this.rekey) {
+      let fresh = "";
+      try {
+        fresh = this.rekey() ?? "";
+      } catch {
+        fresh = "";
+      }
+      if (shouldRekey(res, this.apiKey, fresh)) {
+        this.apiKey = fresh;
+        return this.fetchOnce<T>(path, init, timeoutMs);
+      }
+    }
+    return res;
+  }
+
+  /** [QCR PATCH 6] One attempt of `fetchJSON` (the upstream body, unchanged). */
+  private async fetchOnce<T>(path: string, init?: RequestInit, timeoutMs = 10000): Promise<OVResponse<T>> {
+    try {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), timeoutMs);
+      const resp = await fetch(`${this.baseUrl}${path}`, {
+        ...init,
+        headers: { ...this.headers(), ...(init?.headers as Record<string, string> || {}) },
+        signal: controller.signal,
+      });
+      clearTimeout(timer);
+      // [QCR build conformance] `any`: this repo compiles with `strict` +
+      // `noUncheckedIndexedAccess`, under which `resp.json()` is `unknown`.
+      const body: any = await resp.json().catch(() => ({}));
+      const traceId = body?.result?.trace_id || body?.error?.trace_id || body?.trace_id || undefined;
+      if (!resp.ok || body.status === "error") {
+        return {
+          ok: false,
+          result: null,
+          status: resp.status,
+          error: body.error || { message: `HTTP ${resp.status}` },
+          traceId,
+        };
+      }
+      return { ok: true, result: (body.result ?? body) as T, traceId };
+    } catch (err: any) {
+      return { ok: false, result: null, status: 0, error: { message: err?.message || String(err) } };
+    }
+  }
+
+  // ========== Health ==========
+
+  async health(): Promise<boolean> {
+    const res = await this.fetchJSON<any>("/health", undefined, 5000);
+    this.connected = res.ok;
+    return res.ok;
+  }
+
+  // ========== Sessions ==========
+
+  // [QCR PATCH 3] `createSession()` (POST /api/v1/sessions) is DELETED and the
+  // `auto_create` query parameter is gone from getSession. This client cannot
+  // bring an OpenViking session into existence by any route.
+  //
+  // The daemon owns session lifecycle because creation carries a payload only
+  // it knows: the extraction-disabling memory_policy
+  // (`{self,peer,working_memory}.enabled = false`). A session created without
+  // it leaves a FAILED background task on every single commit, since our
+  // deployment configures no `vlm` (assets/findings.md §2.3/§2.5).
+  // An extension-created session would look identical and quietly rot.
+
+  /** GET /api/v1/sessions/{id} — session metadata. Never creates. */
+  async getSession(sessionId: string): Promise<OVSessionMeta | null> {
+    const res = await this.fetchJSON<OVSessionMeta>(
+      `/api/v1/sessions/${encodeURIComponent(sessionId)}`,
+      undefined, 5000,
+    );
+    return res.ok ? res.result : null;
+  }
+
+  /** GET /api/v1/sessions/{id}/context — assembled context with archive overview */
+  async getSessionContext(sessionId: string, tokenBudget = 128000): Promise<OVSessionContext | null> {
+    const res = await this.fetchJSON<OVSessionContext>(
+      `/api/v1/sessions/${encodeURIComponent(sessionId)}/context?token_budget=${tokenBudget}`,
+      undefined, 10000,
+    );
+    return res.ok ? res.result : null;
+  }
+
+  /** POST /api/v1/sessions/{id}/messages — add a message (simple text mode) */
+  async addMessage(sessionId: string, role: string, content: string): Promise<boolean> {
+    const res = await this.fetchJSON<any>(
+      `/api/v1/sessions/${encodeURIComponent(sessionId)}/messages`,
+      { method: "POST", body: JSON.stringify({ role, content }) },
+      10000,
+    );
+    return res.ok;
+  }
+
+  /** POST /api/v1/sessions/{id}/messages — add a message with parts */
+  async addMessageParts(sessionId: string, role: string, parts: any[]): Promise<boolean> {
+    const res = await this.fetchJSON<any>(
+      `/api/v1/sessions/${encodeURIComponent(sessionId)}/messages`,
+      { method: "POST", body: JSON.stringify({ role, parts }) },
+      10000,
+    );
+    return res.ok;
+  }
+
+  async addMessagePayload(sessionId: string, payload: any): Promise<boolean> {
+    const res = await this.fetchJSON<any>(
+      `/api/v1/sessions/${encodeURIComponent(sessionId)}/messages`,
+      { method: "POST", body: JSON.stringify(payload) },
+      10000,
+    );
+    return res.ok;
+  }
+
+  /** POST /api/v1/sessions/{id}/commit — commit session for archiving + extraction */
+  async commitSessionResponse(
+    sessionId: string,
+    keepRecentCount = this.cfg.commitKeepRecentCount,
+  ): Promise<OVCommitResponse> {
+    const res = await this.fetchJSON<OVCommitResult>(
+      `/api/v1/sessions/${encodeURIComponent(sessionId)}/commit`,
+      { method: "POST", body: JSON.stringify({ keep_recent_count: keepRecentCount }) },
+      30000,
+    );
+    if (res.ok && res.result && !res.result.trace_id && res.traceId) {
+      res.result.trace_id = res.traceId;
+    }
+    return {
+      result: res.ok ? res.result : null,
+      traceId: res.traceId,
+      error: res.error,
+      status: res.status,
+    };
+  }
+
+  async commitSession(
+    sessionId: string,
+    keepRecentCount = this.cfg.commitKeepRecentCount,
+  ): Promise<OVCommitResult | null> {
+    return (await this.commitSessionResponse(sessionId, keepRecentCount)).result;
+  }
+
+  /** DELETE /api/v1/sessions/{id} */
+  async deleteSession(sessionId: string): Promise<boolean> {
+    const res = await this.fetchJSON<any>(
+      `/api/v1/sessions/${encodeURIComponent(sessionId)}`,
+      { method: "DELETE" },
+      10000,
+    );
+    return res.ok;
+  }
+
+  // ========== Search ==========
+
+  /** POST /api/v1/search/find — basic vector search.
+   *
+   * [QCR PATCH 6] Returns the ENVELOPE, not a bare list: upstream returned
+   * `[]` for every failure, a refused key included, so `viking_search`
+   * answered "No results found." through five weeks of `Invalid API Key`. A
+   * failure is now a failure the tool can name (`failureText`). */
+  async find(
+    query: string,
+    // [QCR PATCH 11] a `target_uri` LIST too (the server takes one): a scoped
+    // session searches inside its areas, not across the tree.
+    opts?: { targetUri?: string | string[]; topK?: number; scoreThreshold?: number },
+  ): Promise<OVResponse<OVSearchResult[]>> {
+    const body: Record<string, unknown> = { query };
+    if (Array.isArray(opts?.targetUri) ? opts.targetUri.length > 0 : opts?.targetUri)
+      body.target_uri = opts!.targetUri;
+    if (opts?.topK) body.limit = opts.topK;
+    if (opts?.scoreThreshold) body.score_threshold = opts.scoreThreshold;
+
+    const res = await this.fetchJSON<any>("/api/v1/search/find", {
+      method: "POST", body: JSON.stringify(body),
+    }, 10000);
+    if (!res.ok) return { ...res, result: null };
+    if (!res.result) return { ok: true, result: [], traceId: res.traceId };
+
+    // OV returns { memories: [...], resources: [...], skills: [...], total }
+    const all: OVSearchResult[] = [];
+    for (const bucket of ["memories", "resources", "skills"]) {
+      const items = res.result[bucket];
+      if (Array.isArray(items)) {
+        for (const m of items) {
+          all.push({
+            uri: m.uri ?? "",
+            context_type: m.context_type ?? (bucket === "memories" ? "memory" : bucket === "skills" ? "skill" : "resource"),
+            score: m.score ?? 0,
+            abstract: m.abstract ?? "",
+            overview: m.overview ?? null,
+            level: m.level ?? 0,
+            category: m.category ?? "",
+            match_reason: m.match_reason ?? "",
+          });
+        }
+      }
+    }
+    return { ok: true, result: all, traceId: res.traceId };
+  }
+
+  // ========== Content ==========
+
+  /**
+   * [QCR PATCH 4] POST /api/v1/content/batch-write — the ONE durable write
+   * path. Deliberately no `content/write` wrapper: for memory targets that
+   * endpoint appends a server-side `MEMORY_FIELDS` footer which `content/read`
+   * strips again, so read → sha256 → replace_if_hash 409s forever and no API
+   * returns the stored hash. Files written through batch-write carry no footer
+   * and round-trip (assets/findings.md §3.3).
+   *
+   * Returns the whole envelope, not a boolean: a 409 CONFLICT is a real answer
+   * ("someone edited this since you read it"), not a failure to hide.
+   */
+  async batchWrite(
+    request: { root_uri: string; operations: unknown[]; wait: boolean },
+    timeoutMs = 30000,
+  ): Promise<OVResponse<OVBatchWriteResult> & BusyRetryNote> {
+    // [QCR PATCH 6] A BUSY 409 (`details.conflict_type = "path_busy"`: the
+    // directory lock was held, nothing was checked or written) is retried,
+    // jittered and bounded; a precondition 409 is returned as the refusal it
+    // is. See qcr-honest.ts.
+    return withBusyRetry(
+      () =>
+        this.fetchJSON<OVBatchWriteResult>(
+          "/api/v1/content/batch-write",
+          { method: "POST", body: JSON.stringify(request) },
+          timeoutMs,
+        ),
+      this.retryHooks,
+    );
+  }
+
+  /**
+   * [QCR PATCH 4] POST /api/v1/fs/attrs/set_tags — the retrieval tag list that
+   * search filters read. Best-effort by contract: `viking_write` already put
+   * the tags in the body text, so a failure here narrows retrieval, it never
+   * loses the memory.
+   */
+  async setTags(uri: string, tags: string[], mode: "append" | "replace" = "append"): Promise<boolean> {
+    if (tags.length === 0) return true;
+    // [QCR PATCH 6] set_tags takes the same lock family; a busy answer is
+    // retried like a write's.
+    const res = await withBusyRetry(
+      () =>
+        this.fetchJSON<any>(
+          "/api/v1/fs/attrs/set_tags",
+          { method: "POST", body: JSON.stringify({ uri, tags, mode }) },
+          10000,
+        ),
+      this.retryHooks,
+    );
+    return res.ok;
+  }
+
+  /** [QCR PATCH 6] One read at a detail level, as an ENVELOPE — `abstract`,
+   * `overview` and `readContent` below collapse every failure to null, which
+   * the tools used to render as "No content at …" for a refused key too. */
+  async readLevel(uri: string, level: "abstract" | "overview" | "full"): Promise<OVResponse<string>> {
+    const path = level === "full" ? "read" : level;
+    return this.fetchJSON<string>(
+      `/api/v1/content/${path}?uri=${encodeURIComponent(uri)}`,
+      undefined, 10000,
+    );
+  }
+
+  /** [QCR PATCH 6] `fs/ls` as an envelope (`ls()` keeps upstream's `[]`). */
+  async lsResponse(uri: string): Promise<OVResponse<OVDirEntry[]>> {
+    const res = await this.fetchJSON<any[]>(
+      `/api/v1/fs/ls?uri=${encodeURIComponent(uri)}`,
+      undefined, 10000,
+    );
+    if (!res.ok) return { ...res, result: null };
+    const rows = Array.isArray(res.result) ? res.result : [];
+    return {
+      ok: true,
+      result: rows.map(e => ({
+        uri: e.uri ?? "",
+        name: e.name ?? uriBasename(e.uri ?? ""),
+        isDir: e.isDir ?? false,
+        size: e.size ?? 0,
+        mode: e.mode ?? 0,
+        modTime: e.modTime ?? "",
+        abstract: e.abstract ?? "",
+      })),
+    };
+  }
+
+  /** [QCR PATCH 6] `fs/stat` as an envelope (`stat()` keeps upstream's null). */
+  async statResponse(uri: string): Promise<OVResponse<OVStatInfo>> {
+    return this.fetchJSON<OVStatInfo>(
+      `/api/v1/fs/stat?uri=${encodeURIComponent(uri)}`,
+      undefined, 10000,
+    );
+  }
+
+  /** GET /api/v1/content/abstract — L0 summary */
+  async abstract(uri: string): Promise<string | null> {
+    const res = await this.fetchJSON<string>(
+      `/api/v1/content/abstract?uri=${encodeURIComponent(uri)}`,
+      undefined, 10000,
+    );
+    return res.ok ? res.result : null;
+  }
+
+  /** GET /api/v1/content/overview — L1 overview (directories only) */
+  async overview(uri: string): Promise<string | null> {
+    const res = await this.fetchJSON<string>(
+      `/api/v1/content/overview?uri=${encodeURIComponent(uri)}`,
+      undefined, 10000,
+    );
+    return res.ok ? res.result : null;
+  }
+
+  /** GET /api/v1/content/read — L2 full content (files only) */
+  async readContent(uri: string): Promise<string | null> {
+    const res = await this.fetchJSON<string>(
+      `/api/v1/content/read?uri=${encodeURIComponent(uri)}`,
+      undefined, 10000,
+    );
+    return res.ok ? res.result : null;
+  }
+
+  // ========== Filesystem ==========
+
+  /** GET /api/v1/fs/ls — list directory */
+  async ls(uri: string): Promise<OVDirEntry[]> {
+    const res = await this.fetchJSON<any[]>(
+      `/api/v1/fs/ls?uri=${encodeURIComponent(uri)}`,
+      undefined, 10000,
+    );
+    if (!res.ok || !Array.isArray(res.result)) return [];
+    return res.result.map(e => ({
+      uri: e.uri ?? "",
+      name: e.name ?? uriBasename(e.uri ?? ""),
+      isDir: e.isDir ?? false,
+      size: e.size ?? 0,
+      mode: e.mode ?? 0,
+      modTime: e.modTime ?? "",
+      abstract: e.abstract ?? "",
+    }));
+  }
+
+  /** GET /api/v1/fs/stat — file/directory metadata */
+  async stat(uri: string): Promise<OVStatInfo | null> {
+    const res = await this.fetchJSON<OVStatInfo>(
+      `/api/v1/fs/stat?uri=${encodeURIComponent(uri)}`,
+      undefined, 10000,
+    );
+    return res.ok ? res.result : null;
+  }
+
+  /** DELETE /api/v1/fs — remove file or directory */
+  async delete(uri: string, recursive = false): Promise<boolean> {
+    const res = await this.fetchJSON<any>(
+      `/api/v1/fs?uri=${encodeURIComponent(uri)}&recursive=${recursive}`,
+      { method: "DELETE" },
+      10000,
+    );
+    return res.ok;
+  }
+
+  // ========== Resources ==========
+
+  /** POST /api/v1/resources — ingest a URL or file path */
+  async addResource(
+    path: string, opts?: { to?: string },
+  ): Promise<{ root_uri: string } | null> {
+    const body: Record<string, unknown> = { path };
+    if (opts?.to) body.to = opts.to;
+    const res = await this.fetchJSON<{ root_uri: string }>(
+      "/api/v1/resources",
+      { method: "POST", body: JSON.stringify(body) },
+      30000,
+    );
+    return res.ok ? res.result : null;
+  }
+
+  // ========== URI Space Resolution ==========
+
+  async resolveScopeSpace(scope: "user" | "agent"): Promise<string> {
+    const cached = this.resolvedSpaces.get(scope);
+    if (cached) return cached;
+
+    // Probe system status for user identity fallback
+    let fallbackSpace = "default";
+    const statusRes = await this.fetchJSON<any>("/api/v1/system/status", undefined, 5000);
+    if (statusRes.ok && typeof statusRes.result?.user === "string" && statusRes.result.user.trim()) {
+      fallbackSpace = statusRes.result.user.trim();
+    }
+
+    // List scope root for actual namespaces
+    const reserved = scope === "user" ? OVClient.RESERVED_USER : OVClient.RESERVED_AGENT;
+    const entries = await this.ls(`viking://${scope}/`);
+    const spaces = entries
+      .filter(e => e.isDir && !e.name.startsWith(".") && !reserved.has(e.name))
+      .map(e => e.name);
+
+    if (spaces.length > 0) {
+      // Prefer the fallback space if it exists, then "default", then first available
+      // [QCR build conformance] `?? fallbackSpace` for noUncheckedIndexedAccess
+      // (length > 0 is already checked, so the fallback is unreachable).
+      let chosen: string = spaces[0] ?? fallbackSpace;
+      if (spaces.includes(fallbackSpace)) chosen = fallbackSpace;
+      else if (spaces.includes("default")) chosen = "default";
+      this.resolvedSpaces.set(scope, chosen);
+      return chosen;
+    }
+
+    this.resolvedSpaces.set(scope, fallbackSpace);
+    return fallbackSpace;
+  }
+
+  async resolveTargetUri(targetUri: string): Promise<string> {
+    const trimmed = targetUri.trim().replace(/\/+$/, "");
+    const m = trimmed.match(/^viking:\/\/(user|agent)(?:\/(.*))?$/);
+    if (!m) return trimmed;
+    const scope = m[1] as "user" | "agent";
+    const rawRest = (m[2] ?? "").trim();
+    if (!rawRest) return trimmed;
+    const parts = rawRest.split("/").filter(Boolean);
+    if (parts.length === 0) return trimmed;
+
+    const reserved = scope === "user" ? OVClient.RESERVED_USER : OVClient.RESERVED_AGENT;
+    // [QCR build conformance] `?? ""` for noUncheckedIndexedAccess.
+    if (!reserved.has(parts[0] ?? "")) return trimmed; // already has space
+
+    const space = await this.resolveScopeSpace(scope);
+    return `viking://${scope}/${space}/${parts.join("/")}`;
+  }
+}
+
+function uriBasename(uri: string): string {
+  const cleaned = uri.replace(/\/+$/, "");
+  const last = cleaned.lastIndexOf("/");
+  return last >= 0 ? cleaned.slice(last + 1) : cleaned;
+}

package/extensions/vendor/openviking-pi/config.json

@@ -0,0 +1,28 @@
+{
+  "enabled": true,
+  "syncTurns": true,
+  "recallTokenBudget": 2000,
+  "recallMaxContentChars": 500,
+  "recallPreferAbstract": true,
+  "scoreThreshold": 0.35,
+  "minQueryLength": 3,
+  "profileTokenBudget": 10000,
+  "resumeContextBudget": 32000,
+  "recallQueryExpansion": "off",
+  "_qcr_fork": "Vendored + patched fork of the OpenViking pi extension; see README.md. takeover.enabled below and recallQueryExpansion above are belt-and-braces only — config.ts forces takeover off (PATCH 1) and query expansion off (PATCH 7) in code. There is no commitTokenThreshold: nothing commits a session (PATCH 7).",
+  "takeover": {
+    "enabled": false,
+    "tokenThreshold": 30000,
+    "keepRecentTurns": 3,
+    "overviewBudget": 3000,
+    "overviewPollMs": 2000,
+    "overviewPollMax": 15
+  },
+  "captureToolResults": false,
+  "captureMode": "semantic",
+  "captureMaxLength": 24000,
+  "captureToolMaxChars": 1000000,
+  "captureAssistantTurns": true,
+  "bypassPatterns": [],
+  "logLevel": "error"
+}