dsh-hypatia-auto-memory 0.3.0 → 0.5.0

package/src/memory-status.js

@@ -0,0 +1,167 @@
+/**
+ * Flattening the two state tables into what the conversation's Memory tab reads.
+ *
+ * Why this exists. Everything the background pipeline knows about a session —
+ * how far it has been logged, how far it has been consolidated, how many tokens
+ * are still waiting, whether the `session-<id>` node exists, which tasks are
+ * stuck — lives in the state domain, on disk, readable only by stopping DSH and
+ * opening a JSON file. The checklist in the README tells a user to confirm
+ * logging with a hand-typed `hypatia knowledge-get msg-<sessionId>-<n>`. That is
+ * the gap this closes: a conversation tab that answers "did this session get
+ * remembered, and is anything stuck" without leaving the browser.
+ *
+ * Pure, so it is tested without a storage domain, a cordis context or hypatia.
+ * The route that serves it lives in memory-api.js.
+ *
+ * @module dsh-hypatia-auto-memory/memory-status
+ */
+
+import { EMPTY_PROGRESS } from './progress.js'
+
+/** How many failed tasks the shared failure list carries. */
+export const FAILED_LIMIT = 20
+
+/** How long a task `error` may be in the payload. */
+export const ERROR_MAX = 200
+
+/**
+ * Bound a task error the way every other diagnostic path in this plugin does.
+ * @param {unknown} value - a task's stored `error` field.
+ * @returns {string} the message, capped, or '' when it is not a string.
+ */
+export function boundedError(value) {
+  if (typeof value !== 'string') return ''
+  return value.length > ERROR_MAX ? `${value.slice(0, ERROR_MAX)}…` : value
+}
+
+/** A session row with no progress of its own — a session known only from a task. */
+function emptyEntry(id) {
+  return {
+    id,
+    logged: EMPTY_PROGRESS.lastLoggedSeq,
+    consolidated: EMPTY_PROGRESS.lastConsolidatedSeq,
+    checkTurn: EMPTY_PROGRESS.lastCheckTurn,
+    pendingTokens: EMPTY_PROGRESS.pendingTokens,
+    sessionNode: EMPTY_PROGRESS.hasSessionNode === 1,
+    belongTo: EMPTY_PROGRESS.lastBelongToIndex,
+    deferred: 0,
+    failed: 0,
+    error: '',
+  }
+}
+
+/**
+ * Fold the two state tables into per-session rows plus a shared failure list.
+ *
+ * Sessions come from `progress` (one row per session the shelf has seen) and are
+ * topped up from `tasks`, so a session whose only trace is a stuck task still
+ * appears with a reason rather than looking untouched. Task counts are folded
+ * onto their session; the failure list carries bounded error text, and
+ * `deferred` only counts, since a deferred task is waiting on a load, not on a
+ * person.
+ *
+ * With `sessionId` the fold covers that one session: the failure cap then
+ * bounds only its failures, so other sessions' backlog cannot crowd them out,
+ * and a per-request read does not build a row for every session on the shelf.
+ *
+ * @param {{
+ *   progressEntries: Iterable<[string, any]>,
+ *   taskEntries: Iterable<[string, any]>,
+ *   sessionId?: string,
+ * }} deps - raw table entries for the shelf in use, and optionally the one
+ *   session to keep.
+ * @returns {{sessions: object[], failed: object[], total: number}}
+ */
+export function buildStatus({ progressEntries, taskEntries, sessionId: only }) {
+  const bySession = new Map()
+  for (const [key, row] of progressEntries) {
+    if (only !== undefined && key !== only) continue
+    const current = { ...EMPTY_PROGRESS, ...(row ?? {}) }
+    bySession.set(key, {
+      id: key,
+      logged: current.lastLoggedSeq,
+      consolidated: current.lastConsolidatedSeq,
+      checkTurn: current.lastCheckTurn,
+      pendingTokens: current.pendingTokens,
+      sessionNode: current.hasSessionNode === 1,
+      belongTo: current.lastBelongToIndex,
+      deferred: 0,
+      failed: 0,
+      error: '',
+    })
+  }
+
+  const failed = []
+  for (const [id, record] of taskEntries) {
+    const sessionId = String(record?.sessionId ?? '')
+    if (sessionId === '') continue
+    if (only !== undefined && sessionId !== only) continue
+    const entry = bySession.get(sessionId) ?? emptyEntry(sessionId)
+    const status = String(record?.status ?? '')
+    if (status === 'deferred') entry.deferred += 1
+    if (status === 'failed') {
+      entry.failed += 1
+      if (entry.error === '') entry.error = boundedError(record?.error)
+      failed.push({
+        kind: String(record?.kind ?? ''),
+        sessionId,
+        attempts: Number(record?.attempts ?? 0),
+        error: boundedError(record?.error),
+      })
+    }
+    bySession.set(sessionId, entry)
+  }
+
+  // The tasks table is keyed `<kind>:<sessionId>`, so insertion order is kind-major
+  // and not a recency order. Truncating is therefore arbitrary rather than
+  // "newest"; it is a bound on the payload, not a ranking.
+  return { sessions: [...bySession.values()], failed: failed.slice(0, FAILED_LIMIT), total: bySession.size }
+}
+
+/**
+ * Collapse the fold to the one session the tab is bound to.
+ *
+ * The derived flags are computed here rather than in the browser so there is one
+ * definition of "caught up" and one place to change it.
+ *
+ * @param {{sessions: object[], failed: object[]}} built - the output of {@link buildStatus}.
+ * @param {string} sessionId - the session the tab is showing.
+ * @returns {object} the session view; `known` is false for a session with no trace yet.
+ */
+export function sessionView(built, sessionId) {
+  const row = built.sessions.find((session) => session.id === sessionId)
+  const failedTasks = built.failed.filter((task) => task.sessionId === sessionId)
+  if (row === undefined) {
+    return {
+      sessionId,
+      known: false,
+      loggedSeq: 0,
+      consolidatedSeq: 0,
+      // Nothing logged and nothing consolidated is not a backlog.
+      caughtUp: true,
+      pendingTokens: 0,
+      sessionNode: false,
+      belongTo: 0,
+      deferred: 0,
+      failed: 0,
+      failedTasks,
+      error: '',
+    }
+  }
+  return {
+    sessionId,
+    known: true,
+    loggedSeq: row.logged,
+    consolidatedSeq: row.consolidated,
+    // Both watermarks start at 0, so an unlogged session reads as caught up
+    // rather than as behind — `known` separates "nothing to do" from "nothing done".
+    caughtUp: row.consolidated >= row.logged,
+    pendingTokens: row.pendingTokens,
+    sessionNode: row.sessionNode,
+    belongTo: row.belongTo,
+    deferred: row.deferred,
+    failed: row.failed,
+    failedTasks,
+    error: row.error,
+  }
+}

package/src/model-log.js

@@ -0,0 +1,246 @@
+/**
+ * Durable, bounded record of the model attempts the background pipeline makes.
+ *
+ * Why this exists. The route one consolidation attempt runs on is chosen by a
+ * process-local round-robin cursor (`createConsolidationRouteSelector`) and,
+ * before this, was dropped the moment the call was made. "Which model actually
+ * summarised that span?" was then unanswerable from outside the process: the
+ * settings card shows the configured route LIST, the host logger goes to a
+ * terminal that scrolls away, and the usage ledger only folds agent turns — it
+ * cannot see a plugin's direct `llm.stream` call at all (see
+ * `@linxin666/dsh-usage` `usage-service.ts`, which folds `assistant/message`).
+ *
+ * The record is written at SELECTION time and updated when the attempt settles,
+ * so a row left at `pending` is itself evidence: the process died, or the
+ * attempt is still in flight. That distinguishes the three states the cursor
+ * alone cannot — selected, completed, and consumed-but-produced-nothing.
+ *
+ * It lives in its OWN storage domain rather than in the one holding watermarks
+ * and queued tasks. In that domain a record failing its schema rejects the whole
+ * open and silently disables the plugin (see the note on `taskTable` in
+ * state.js); diagnostics must never be able to take the authoritative data down
+ * with them. Here the blast radius is one bounded table nobody's correctness
+ * depends on. `openModelLog` therefore degrades to a logger-only log when the
+ * domain will not open, and callers keep working.
+ *
+ * @module dsh-hypatia-auto-memory/model-log
+ */
+
+import { defineDomain, domainTable } from '@deepseek-ai/dsh-storage-domain'
+import { z } from 'zod'
+
+/** How many attempts to keep. A ring large enough to answer "the last run(s)". */
+export const MODEL_CALL_LIMIT = 100
+
+/**
+ * One model attempt. `outcome` is the state that matters:
+ *
+ * - `pending`  — selected, not settled (in flight, or the process died).
+ * - `ok`       — the call settled AND produced a usable result.
+ * - `incomplete` — settled without one: output cap, abort, refusal, a reply
+ *   that did not parse, or one that parsed into nothing usable. The cursor WAS
+ *   consumed and nothing was stored. This is a deliberate catch-all: from
+ *   outside, every one of those looks the same, and a caller that reported `ok`
+ *   for a stop that yielded no summary would make the table lie.
+ * - `error`    — the call itself threw (provider/transport failure).
+ *
+ * `detail` carries a finish kind, a fixed label, or a provider error message —
+ * never message content and never model output. The plugin's whole log path is
+ * built to keep conversation text out of places a later reader can stumble
+ * into, and a `JSON.parse` failure is exactly where that leaks by accident:
+ * Node quotes the offending input in the message (`Unexpected token 'H', "Here
+ * is th"...`). Parse sites therefore record a fixed label, and `finish` caps
+ * whatever it is handed, because a provider `failure.message` can carry a whole
+ * HTTP body.
+ */
+export const modelCallTable = domainTable(z.object({
+  /** Monotonic within the process; recovered from the stored rows on open. */
+  seq: z.number().step(1).min(1),
+  /** Epoch milliseconds at selection. */
+  at: z.number().default(0),
+  /** The `purpose` the call was made with ('memory-consolidation', …). */
+  purpose: z.string().default(''),
+  provider: z.string().default(''),
+  model: z.string().default(''),
+  outcome: z.string().default('pending'),
+  /** Wall time from selection to settle; 0 while pending. */
+  ms: z.number().min(0).default(0),
+  detail: z.string().default(''),
+}))
+
+/** Upper bound on `detail`; see the table doc. Applied on every write. */
+export const DETAIL_MAX = 200
+
+/**
+ * Diagnostics domain. Separate from `hypatia_auto_memory` on purpose (module
+ * doc); its own version line, so the authoritative domain's format never has to
+ * move for a table only a human reads.
+ */
+export const diagnosticsSpec = defineDomain({
+  name: 'hypatia_auto_memory_diag',
+  version: 1,
+  // Table names must match /^[a-z][a-z0-9_]*$/ — the module-load guard rejects
+  // camelCase before any medium is touched.
+  tables: { model_calls: modelCallTable },
+})
+
+/**
+ * Fixed-width key so lexicographic order equals sequence order. A bare numeric
+ * key would be re-ordered by the JSON object it is stored in (integer-like keys
+ * sort first, numerically), which is why ordering is carried by the padded key
+ * AND by the `seq` field the reader sorts on.
+ * @param {number} seq
+ */
+function keyOf(seq) {
+  return String(seq).padStart(12, '0')
+}
+
+/**
+ * The log a caller gets when none was injected (unit tests, a composition
+ * without storage). Call sites default to it, so none of them branches on
+ * observability being available.
+ */
+export const NULL_MODEL_LOG = Object.freeze({
+  begin: () => ({ finish: async () => {} }),
+  recent: () => [],
+})
+
+/**
+ * @param {{
+ *   table?: any,
+ *   status: import('./status.js').StatusLog,
+ *   limit?: number,
+ *   now?: () => number,
+ * }} deps - `table` absent (or the domain failed to open) means: log lines
+ * still happen, nothing is stored, and no caller has to branch.
+ */
+export function createModelLog({ table, status, limit = MODEL_CALL_LIMIT, now = Date.now }) {
+  let counter = 0
+  if (table !== undefined) {
+    // Every stored row passed the schema at open, so `seq` is always the number
+    // the padded key was derived from.
+    for (const [, row] of table.entries()) {
+      if (row.seq > counter) counter = row.seq
+    }
+  }
+
+  function onWriteError(error) {
+    status.warn(`model-call log write failed: ${String(error)}`)
+  }
+
+  /** Keep the newest `limit` rows; drop the rest oldest-first. */
+  async function prune() {
+    while (table.size > limit) {
+      let oldest
+      for (const [key, row] of table.entries()) {
+        if (oldest === undefined || row.seq < oldest.row.seq) oldest = { key, row }
+      }
+      if (oldest === undefined) return
+      await table.delete(oldest.key)
+    }
+  }
+
+  async function write(key, record) {
+    try {
+      await table.put(key, record)
+      await prune()
+    } catch (error) {
+      onWriteError(error)
+    }
+  }
+
+  /**
+   * Record one attempt as it is selected, before the call is made.
+   *
+   * @param {string} purpose - The same string handed to `llm.stream`.
+   * @param {{provider: string, model: string}} route
+   * @returns {{seq: number, finish: (outcome: string, detail?: string) => Promise<void>}}
+   */
+  function begin(purpose, route) {
+    counter += 1
+    const seq = counter
+    const at = now()
+    const key = keyOf(seq)
+    const record = {
+      seq,
+      at,
+      purpose,
+      provider: String(route?.provider ?? ''),
+      model: String(route?.model ?? ''),
+      outcome: 'pending',
+      ms: 0,
+      detail: '',
+    }
+    // Durable before the call runs, so an attempt that never settles still
+    // leaves a row. Awaited by `finish`, never by the caller.
+    const stored = table === undefined ? Promise.resolve() : write(key, record)
+    return {
+      seq,
+      async finish(outcome, detail = '') {
+        // Never rejects, and callers do not await it: every one of them calls
+        // this from a `finally`, where a throw here would replace the error the
+        // queue was going to see, and a storage stall would hold the queue task
+        // open after its own timeout has already been cleared.
+        try {
+          await stored
+          const ms = Math.max(0, now() - at)
+          const bounded = String(detail).slice(0, DETAIL_MAX)
+          if (table !== undefined) {
+            await write(key, { ...record, outcome, ms, detail: bounded })
+          }
+          const suffix = bounded === '' ? '' : ` (${bounded})`
+          status.info(`model call: ${purpose} ${record.provider}/${record.model} ${outcome} ${ms}ms${suffix}`)
+        } catch (error) {
+          onWriteError(error)
+        }
+      },
+    }
+  }
+
+  /** Newest-first snapshot, for a human reading the state file or a card. */
+  function recent(count = 20) {
+    if (table === undefined) return []
+    return [...table.entries()]
+      .map(([, row]) => row)
+      .sort((a, b) => Number(b?.seq) - Number(a?.seq))
+      .slice(0, count)
+  }
+
+  return { begin, recent }
+}
+
+/**
+ * Open the diagnostics domain and build the log. Never throws: a domain that
+ * will not open costs the stored history, not the memory pipeline.
+ *
+ * @param {import('@deepseek-ai/cordis').Context} ctx - context injecting `storageDomain`.
+ * @param {{status: import('./status.js').StatusLog, limit?: number, now?: () => number}} deps
+ * @returns {Promise<{modelLog: ReturnType<typeof createModelLog>, domain?: any}>}
+ * `domain` is the open handle when there is one, so a caller that finds itself
+ * disposed can close it (mirrors `openState`).
+ */
+export async function openModelLog(ctx, { status, limit, now }) {
+  let domain
+  try {
+    domain = await ctx.storageDomain.open(diagnosticsSpec)
+  } catch (error) {
+    status.warn(`model-call log unavailable, attempts will only be logged: ${String(error)}`)
+    return { modelLog: createModelLog({ status, limit, now }) }
+  }
+  try {
+    ctx.effect(() => () => {
+      void domain.close().catch(() => {
+        // Closing during teardown must never take the fiber down.
+      })
+    }, 'hypatia-auto-memory: close diagnostics domain')
+  } catch {
+    // The fiber went away while the domain was opening, so no disposer will
+    // ever run for it — closing here is the only thing that prevents a leak.
+    // Deliberately silent: the plugin is being torn down, and a warning about
+    // an unavailable log would be noise at exactly the moment nothing can act
+    // on it.
+    await domain.close().catch(() => {})
+    return { modelLog: createModelLog({ status, limit, now }) }
+  }
+  return { modelLog: createModelLog({ table: domain.table('model_calls'), status, limit, now }), domain }
+}