dsh-plugin-mobile-link 0.4.1 → 0.6.0

package/lib/history/probe.js

@@ -0,0 +1,195 @@
+import { HOST_CALL_TIMEOUT_MS, withTimeout, messageOf } from './shared.js'
+import { bytesOf, summarizeEvents } from './records.js'
+
+/**
+ * 只读测量（spec 007 T008/T047）：`GET /mobile-link/history-probe` 用，锁定映射之后删。
+ *
+ * 它只读、不改任何状态；`getQuery` 是个取值函数而不是服务对象本身，因为宿主注入
+ * （`ctx.inject(['sessionQuery'])`）可能在服务建好之后才发生。
+ */
+export function createProbeRunner({ getQuery, logger }) {
+  return async function probe(args = {}) {
+  const sessionId = args.sessionId
+  if (typeof sessionId !== 'string' || sessionId.length === 0) {
+    return { ok: false, error: 'sessionId is required' }
+  }
+  if (getQuery() === undefined) {
+    return { ok: false, error: 'ctx.getQuery() is not mounted in this Host' }
+  }
+  const limit = Number.isFinite(Number(args.n)) && Number(args.n) > 0 ? Number(args.n) : 60
+  const out = { ok: true, sessionId, limit }
+
+  // 1. Whole log: how many events, and is log position == seq?
+  const t0 = Date.now()
+  try {
+    const records = await withTimeout(getQuery().listEvents(sessionId), HOST_CALL_TIMEOUT_MS, 'listEvents')
+    const mismatches = []
+    records.forEach((record, index) => {
+      if (record.seq !== index && mismatches.length < 5) mismatches.push({ index, seq: record.seq })
+    })
+    out.listEvents = {
+      ...summarizeEvents(records),
+      ms: Date.now() - t0,
+      offsetEqualsSeq: mismatches.length === 0,
+      firstMismatches: mismatches,
+    }
+  } catch (error) {
+    out.listEvents = { ms: Date.now() - t0, error: messageOf(error) }
+  }
+
+  // 2. Exact window read around a seq (`readEvent`): raw events, contiguous.
+  const targetSeq = Number.isFinite(Number(args.seq)) ? Number(args.seq) : out.listEvents?.lastSeq
+  if (Number.isInteger(targetSeq) && targetSeq >= 0) {
+    const t1 = Date.now()
+    try {
+      const window = await withTimeout(
+        getQuery().readEvent({ sessionId, seq: targetSeq, before: limit, after: 0 }),
+        HOST_CALL_TIMEOUT_MS,
+        'readEvent',
+      )
+      out.readEvent = {
+        requested: { seq: targetSeq, before: limit, after: 0 },
+        ...summarizeEvents(window.events),
+        startSeq: window.startSeq ?? null,
+        endSeq: window.endSeq ?? null,
+        rawEventCount: window.events?.length ?? 0,
+        bytes: bytesOf(window.events),
+        ms: Date.now() - t1,
+      }
+    } catch (error) {
+      out.readEvent = { requested: { seq: targetSeq, before: limit }, ms: Date.now() - t1, error: messageOf(error) }
+    }
+  }
+
+  // 3. Seq-range filter (`filterEvents`): message-aligned semantic documents.
+  if (Number.isInteger(targetSeq) && targetSeq >= 0) {
+    const from = Math.max(0, targetSeq - limit + 1)
+    const t2 = Date.now()
+    try {
+      const docs = await withTimeout(
+        getQuery().filterEvents(sessionId, [{ kind: 'seq', from, to: targetSeq }]),
+        HOST_CALL_TIMEOUT_MS,
+        'filterEvents(seq)',
+      )
+      out.filterEventsSeq = {
+        requested: { from, to: targetSeq },
+        ...summarizeEvents(docs),
+        bytes: bytesOf(docs),
+        sample: docs.slice(0, 2).map((doc) => ({ seq: doc.seq, type: doc.type, textLen: doc.text?.length ?? 0 })),
+        ms: Date.now() - t2,
+      }
+    } catch (error) {
+      out.filterEventsSeq = { requested: { from, to: targetSeq }, ms: Date.now() - t2, error: messageOf(error) }
+    }
+  }
+
+  // 4. Literal text scan (`filterEvents(text)`): the fallback for search when
+  //    the full-text index is closed (base bundle ships `openAt: never`).
+  if (typeof args.text === 'string' && args.text.length > 0) {
+    const t3 = Date.now()
+    try {
+      const docs = await withTimeout(
+        getQuery().filterEvents(sessionId, [{ kind: 'text', text: args.text }]),
+        HOST_CALL_TIMEOUT_MS,
+        'filterEvents(text)',
+      )
+      out.filterEventsText = {
+        query: args.text,
+        ...summarizeEvents(docs),
+        sample: docs.slice(0, 3).map((doc) => ({
+          seq: doc.seq,
+          type: doc.type,
+          textLen: doc.text?.length ?? 0,
+          head: (doc.text ?? '').slice(0, 60),
+        })),
+        ms: Date.now() - t3,
+      }
+    } catch (error) {
+      out.filterEventsText = { query: args.text, ms: Date.now() - t3, error: messageOf(error) }
+    }
+  }
+
+  // 5. Indexed search (`searchEvents`): expected to fail while the SQLite
+  //    index is closed, which is why step 4 must be able to carry search.
+  if (typeof args.text === 'string' && args.text.length > 0) {
+    const t4 = Date.now()
+    try {
+      const page = await withTimeout(
+        getQuery().searchEvents({ sessionId, query: args.text, limit: 20 }),
+        HOST_CALL_TIMEOUT_MS,
+        'searchEvents',
+      )
+      out.searchEvents = {
+        query: args.text,
+        count: page.items?.length ?? 0,
+        hasMore: page.hasMore ?? null,
+        first: page.items?.[0] ? { seq: page.items[0].seq, type: page.items[0].type } : null,
+        ms: Date.now() - t4,
+      }
+    } catch (error) {
+      out.searchEvents = { query: args.text, ms: Date.now() - t4, error: messageOf(error) }
+    }
+  }
+
+  // 7. Chunked literal scan: `filterEvents(text)` returns every match with its
+  //    full text, so the connector must bound each call by a seq range and
+  //    stop at the requested hit count. This measures that shape.
+  if (typeof args.text === 'string' && args.text.length > 0 && Number.isInteger(out.listEvents?.lastSeq ?? null)) {
+    const chunk = Number.isFinite(Number(args.chunk)) && Number(args.chunk) > 0 ? Number(args.chunk) : 2000
+    const wanted = Number.isFinite(Number(args.hits)) && Number(args.hits) > 0 ? Number(args.hits) : 50
+    const lastSeq = out.listEvents.lastSeq
+    const t6 = Date.now()
+    const hits = []
+    let calls = 0
+    let to = lastSeq
+    try {
+      while (to >= 0 && hits.length < wanted && calls < 50) {
+        const from = Math.max(0, to - chunk + 1)
+        const docs = await withTimeout(
+          getQuery().filterEvents(sessionId, [
+            { kind: 'seq', from, to },
+            { kind: 'text', text: args.text },
+          ]),
+          HOST_CALL_TIMEOUT_MS,
+          `filterEvents(chunk ${from}-${to})`,
+        )
+        calls++
+        for (const doc of docs) {
+          if (hits.length >= wanted) break
+          hits.push({ seq: doc.seq, type: doc.type, textLen: doc.text?.length ?? 0 })
+        }
+        to = from - 1
+      }
+      out.chunkedText = {
+        query: args.text,
+        chunk,
+        calls,
+        hits: hits.length,
+        firstSeq: hits[0]?.seq ?? null,
+        lastSeq: hits[hits.length - 1]?.seq ?? null,
+        scannedFrom: to + 1,
+        ms: Date.now() - t6,
+      }
+    } catch (error) {
+      out.chunkedText = { query: args.text, calls, hits: hits.length, ms: Date.now() - t6, error: messageOf(error) }
+    }
+  }
+
+  // 6. Cold read: no Agent activation. `readSession` returns the log snapshot.
+  const t5 = Date.now()
+  try {
+    const snapshot = await withTimeout(getQuery().readSession(sessionId), HOST_CALL_TIMEOUT_MS, 'readSession')
+    out.readSession = {
+      events: snapshot.events?.length ?? null,
+      startSeq: snapshot.startSeq ?? null,
+      endSeq: snapshot.endSeq ?? null,
+      headerKeys: snapshot.session ? Object.keys(snapshot.session).slice(0, 8) : [],
+      ms: Date.now() - t5,
+    }
+  } catch (error) {
+    out.readSession = { ms: Date.now() - t5, error: messageOf(error) }
+  }
+
+  return out
+  }
+}

package/lib/history/records.js

@@ -0,0 +1,97 @@
+/**
+ * `_link/sessionWindow` / `_link/sessionFind` 共用的事件→记录件。
+ *
+ * 抽出来的理由与 `shared.js` 同一条（spec 007 T065）：窗口扫描、检索、探针三块
+ * 都要按角色归类事件、都要按字节预算裁剪，放在 `history.js` 里会把那个文件撑到
+ * 读不动，也确实漏过一次导入（`probe.js` 里 `bytesOf`/`summarizeEvents` 一直是
+ * 未定义的名字）。
+ *
+ * 这里只有纯函数：没有 IO、没有服务状态。
+ */
+
+/// Host hard cap: `readEvent` rejects `before > 50` (`before must be an integer
+/// between 0 and 50`). One chunk therefore yields at most 51 raw events.
+export const WINDOW_CHUNK = 50
+
+/// Defaults for one page. The phone may override both; the byte budget wins when
+/// they disagree (measured: 51 raw events can already be 253KB on a long session).
+export const DEFAULT_LIMIT = 60
+export const DEFAULT_MAX_BYTES = 256 * 1024
+
+/// Ceiling on how much one call reads, so a page request can never pin the
+/// connector's serial inbox (measured: ~30ms per chunk on a 2.3k session).
+export const MAX_CHUNKS_PER_CALL = 12
+
+export function bytesOf(value) {
+  try {
+    return Buffer.byteLength(JSON.stringify(value), 'utf8')
+  } catch {
+    return -1
+  }
+}
+
+export function summarizeEvents(events) {
+  if (!Array.isArray(events) || events.length === 0) {
+    return { count: 0, firstSeq: null, lastSeq: null, types: [] }
+  }
+  const types = [...new Set(events.map((event) => event?.type).filter(Boolean))].slice(0, 8)
+  return {
+    count: events.length,
+    firstSeq: events[0]?.seq ?? null,
+    lastSeq: events[events.length - 1]?.seq ?? null,
+    types,
+  }
+}
+
+export function toRecord(event) {
+  return { type: 'event', event }
+}
+
+export function bytesOfRecords(records) {
+  return bytesOf(records)
+}
+
+/// Drop the **oldest** end until the page fits. The newest edge must stay exact
+/// (it is the seq the phone's window abuts), so trimming only ever happens here.
+export function trimToBytes(records, maxBytes) {
+  let truncated = false
+  while (records.length > 1 && bytesOfRecords(records) > maxBytes) {
+    records.shift()
+    truncated = true
+  }
+  return truncated
+}
+
+/// Which of the three transcript roles one event belongs to (the phone's own
+/// `TranscriptSearchHit.Role`).
+///
+/// `user/message` only counts as **me** when the event really came from the
+/// user: measured on a real session, ~24% of `user/message` events are
+/// plugin/system injections (`data.source.kind` other than `"user"`), and
+/// agent-relayed ones carry a `data.source.rpcId` starting with `agent-`.
+/// Events with no `data.source` at all predate the marker and stay `me`
+/// (old-data compatibility). Non-`me` user messages return `undefined` —
+/// they remain visible to full-text search, they just never enter the
+/// "my questions" set (spec 009 T031).
+export function roleOf(event) {
+  const type = event?.type
+  if (type === 'user/message') {
+    const source = event?.data?.source
+    if (source !== undefined && source !== null && typeof source === 'object') {
+      if (source.kind !== undefined && source.kind !== 'user') return undefined
+      if (typeof source.rpcId === 'string' && source.rpcId.startsWith('agent-')) return undefined
+    }
+    return 'me'
+  }
+  if (type === 'assistant/message') return 'agent'
+  if (type === 'tool/call' || type === 'tool/result') return 'tool'
+  return undefined
+}
+
+/// What the search hit is *displayed* as. Injected/relayed user messages are
+/// not "me" for the curated set, but they are still user speech in full-text
+/// search (spec 009: excluded from "我的提问", not from the corpus), so an
+/// unfiltered search shows them under the user bucket.
+export function displayRoleOf(event) {
+  return roleOf(event) ?? (event?.type === 'user/message' ? 'me' : undefined)
+}

package/lib/history/shared.js

@@ -0,0 +1,25 @@
+/**
+ * `_link/sessionWindow` / `_link/sessionFind` 共用的小工具：调用上限、超时与错误文案。
+ *
+ * 抽出来的理由：这两个助手原先在 `history.js` 里，而窗口、检索、探针三块都要用；
+ * 放在这里可以让三块各自成文件（spec 007 T065）。
+ */
+
+/// Host-side call ceiling. The connector's inbox is serial, so one slow query
+/// would otherwise hold up every other frame on the tunnel.
+export const HOST_CALL_TIMEOUT_MS = 8000
+
+/// 包一层超时：连接器的入站链是**串行**的，一次不返回的宿主调用会卡住整条链。
+export function withTimeout(promise, ms, label) {
+  let timer
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms)
+  })
+  return Promise.race([promise, timeout]).finally(() => clearTimeout(timer))
+}
+
+export function messageOf(error) {
+  if (error === undefined || error === null) return 'unknown error'
+  if (typeof error === 'string') return error
+  return error.message ?? String(error)
+}

package/lib/history/window.js

@@ -0,0 +1,90 @@
+/**
+ * `_link/sessionWindow` 的「往下扫」与「把扫描结果裁成一页」两块（spec 007 T065
+ * 的同一条理由：让 `history.js` 留得下校验、在飞锁与检索）。
+ *
+ * 唯一的 IO 是调用方给的 `readChunk`，所以这里没有服务状态、可以直接单测。
+ */
+
+import { MAX_CHUNKS_PER_CALL, bytesOfRecords, roleOf, toRecord, trimToBytes } from './records.js'
+
+/// One backward scan from `before - 1` (spec 009 T039).
+///
+/// Returns the matching events **and** `scannedFloor`: the oldest seq this call
+/// actually examined (inclusive). It is about *where the scan got to*, not about
+/// which events matched — a page whose whole stretch is filtered out still moves
+/// it, which is what lets the phone's role-filtered backfill advance. (The old
+/// cursor rule — the oldest returned record — stands still on an empty page.)
+///
+/// `exhausted` means the scan ran into the start of the log (or an empty chunk):
+/// a filtered page needs it to answer "is there more?".
+export async function scanOlder({ readChunk, sessionId, before, through, limit, maxBytes, roles }) {
+  let cursor = Math.min(before - 1, through ?? Number.MAX_SAFE_INTEGER)
+  const events = []
+  let truncatedBy = null
+  let clamped = false
+  let exhausted = false
+  let scannedFloor = null
+  for (let chunk = 0; chunk < MAX_CHUNKS_PER_CALL && cursor >= 0; chunk += 1) {
+    const { window: result, clamped: thisClamped } = await readChunk(sessionId, cursor)
+    clamped = clamped || thisClamped
+    const batch = Array.isArray(result.events) ? result.events : []
+    if (batch.length === 0) { exhausted = true; scannedFloor = 0; break }
+    const lowest = result.startSeq ?? batch[0].seq
+    scannedFloor = scannedFloor === null ? lowest : Math.min(scannedFloor, lowest)
+    for (let index = batch.length - 1; index >= 0; index -= 1) {
+      const event = batch[index]
+      if (roles !== undefined && !roles.has(roleOf(event))) continue
+      events.unshift(event)
+    }
+    if (events.length >= limit || bytesOfRecords(events.map(toRecord)) >= maxBytes) {
+      truncatedBy = events.length >= limit ? 'count' : 'bytes'
+      break
+    }
+    const next = lowest - 1
+    if (next >= cursor) { exhausted = true; break }
+    cursor = next
+    if (cursor < 0) { exhausted = true; break }
+  }
+  return { events, truncatedBy, clamped, exhausted, scannedFloor }
+}
+
+/// Shape one scan into the page the phone gets.
+///
+/// Trimming only ever drops the **oldest** end: the newest edge is the seq the
+/// phone's window abuts, so it must stay exact (one chunk is 51 events, so the
+/// page would otherwise overshoot `limit` by up to a chunk).
+///
+/// `scanBoundary` is what the caller passes as the next `before`. Normally that
+/// is `scannedFloor` — the stretch below it was never looked at. When trimming
+/// dropped records, it falls back to the oldest **returned** record instead:
+/// dropped records were not handed over, so the next page has to scan them
+/// again (re-scanning is free, losing one question is not). Without `roles` the
+/// field mirrors `startSeq`: old clients read the old fields and see no change.
+export function pageFrom(scan, { limit, maxBytes, roles }) {
+  const records = scan.events.map(toRecord)
+  let truncatedBy = scan.truncatedBy
+  let droppedOldest = false
+  if (records.length > limit) {
+    records.splice(0, records.length - limit)
+    truncatedBy = 'count'
+    droppedOldest = true
+  }
+  if (trimToBytes(records, maxBytes)) { truncatedBy = 'bytes'; droppedOldest = true }
+  if (records.length === 0) {
+    return {
+      records: [], startSeq: null, endSeq: null,
+      hasMore: roles !== undefined && !scan.exhausted,
+      truncatedBy: null, clamped: scan.clamped,
+      scanBoundary: roles === undefined ? null : scan.scannedFloor,
+    }
+  }
+  const startSeq = records[0].event.seq
+  const endSeq = records[records.length - 1].event.seq
+  // Filtered pages: "more" means older seqs remain unscanned **and** the page
+  // did not already reach the log's first event.
+  const hasMore = roles === undefined ? startSeq > 0 : (startSeq > 0 && !scan.exhausted)
+  return {
+    records, startSeq, endSeq, hasMore, truncatedBy, clamped: scan.clamped,
+    scanBoundary: roles === undefined ? startSeq : (droppedOldest ? startSeq : scan.scannedFloor),
+  }
+}