fix(web): converge search runtime boundaries (round 8)

2026-07-27 14:02:35 +08:00
parent 40b68cd8d5
commit ba2925c704
21 changed files with 469 additions and 54 deletions
--- a/packages/host/apiproxy/README.i18n.yaml
+++ b/packages/host/apiproxy/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/host/apiproxy/README.md
-README.md: 2f062ba9b927ab62518523731d39fd7c52e07c8d
-README.zh.md: 72ff415f793b4bdb2068a8240ea42baab79984dc
+README.md: e61de41a14294b8c1601e5be8cab19fdf780916d
+README.zh.md: 7e49ad49aaa9356412f90b37237b06ce65776e1c
--- a/packages/host/apiproxy/README.md
+++ b/packages/host/apiproxy/README.md
@@ -14,7 +14,9 @@ The mux stream projects the latest log-backed title as a validated `session/titl

 Workspace and Session lists are separate reconnect baselines. `workspace.create` creates a unique name or adopts an existing directory, `session.create` accepts an optional preallocated Session id, and `host/workspace-changed` plus `host/session-added` carry committed increments in either arrival order. `SessionSummary.blank` and the `host/session-added` frame carry the derived zero-events bit: clients hide blank sessions and reuse them per workspace, flip blank on the first `host/session-status(running:true)`, and treat `session.list` as the reconnect authority; cold summaries are never blank because lazy persistence keeps never-appended sessions out of `list()`.

-`session.search` is a bounded content-search projection over the sessions visible through `session.list`. The gateway asks the optional `ctx.sessionQuery` service for globally ranked current-surface user, assistant, and steering matches in pages capped at 20 hits, consumes that stream until it has at most 20 visible session/snippet pairs plus one lookahead, and revalidates every hit against the list-derived authorization set before returning it. It makes at most 100 provider calls (2,000 inspected hits); an oversized page, a repeated continuation cursor, or a still-unexhausted stream at that budget fails closed as an `internal` business error. Keeping the authorization set in Host memory avoids SQLite's variable ceiling for large valid corpora without weakening visibility or ranking. The carrier request signal cancels persistence listing, cold-summary collection, and every search page. A deployment without the service, or a failed index/query operation, also returns an `internal` business error so clients can retain metadata-only matches.
+`session.search` is a bounded content-search projection over the sessions visible through `session.list`. The gateway asks the optional `ctx.sessionQuery` service for globally ranked current-surface user, assistant, and steering matches in pages capped at 20 hits, consumes that stream until it has at most 20 visible session/snippet pairs plus one lookahead, and revalidates every hit against the list-derived authorization set before returning it. Returned snippets contain at most 240 Unicode code points; a malformed non-string provider snippet fails closed instead of crossing the RPC boundary. Keeping the authorization set in Host memory avoids SQLite's variable ceiling for large valid corpora without weakening visibility or ranking.
+
+A stale continuation discards every partial result, deduplication entry, and cursor from that provider attempt, then restarts at the first page against the original list-derived visibility snapshot. Stale retries share the same limit of at most 100 provider calls (and therefore at most 2,000 inspected hits); an oversized page, a repeated continuation cursor, or a still-unexhausted stream at that call budget fails closed as an `internal` business error. The carrier request signal cancels persistence listing, cold-summary collection, and every search call, including a stale rejection observed concurrently with cancellation. A deployment without the service, or any unrecovered index/query failure, also returns an `internal` business error so clients can retain metadata-only matches.

 The `command.*` and `skill.*` domains expose the host command registry and skill catalog to clients. Every method addresses one session's agent by `sessionId` (a served session always has an Agent; `command.*` resumes cold sessions through the same path as `session.*`, while `skill.list` resolves the project root from the session header without touching the Agent registry). `command.execute` runs a slash-command line host-side and returns a detached result; the carrier's request signal cancels the running handler. `host/commands-changed` is the catalog invalidation frame: clients refetch `command.list` instead of diffing.

--- a/packages/host/apiproxy/README.zh.md
+++ b/packages/host/apiproxy/README.zh.md
@@ -14,7 +14,9 @@ mux 流会在每个已附加会话的订阅基线之后，以及对应的实时

 Workspace 列表与 Session 列表是相互独立的重连基线。`workspace.create` 会创建唯一名称或接纳现有目录，`session.create` 接受可选的预分配 Session id，`host/workspace-changed` 与 `host/session-added` 则以任意到达顺序携带已提交的增量。`SessionSummary.blank` 与 `host/session-added` 帧携带派生的零事件位：客户端隐藏空白会话并按 workspace 复用它们，在首个 `host/session-status(running:true)` 时翻转 blank，并以 `session.list` 作为重连权威；冷会话摘要永远不是空白——惰性持久化让从未追加过事件的会话根本不出现在 `list()` 中。

-`session.search` 是以 `session.list` 所列会话为范围的有界内容搜索投影。网关向可选的 `ctx.sessionQuery` 服务请求全局排序后的当前 surface user、assistant 和 steering（中途引导）匹配项，每页至多 20 个命中，并持续消费该结果流，直到获得至多 20 个可见会话／snippet 对及一个前瞻项；返回前仍会依据从列表推导的授权集合重新校验每个命中。宿主最多调用提供方 100 次（检查 2,000 个命中）；如果单页命中数超限、续传游标重复，或用尽该预算后结果流仍未耗尽，都会直接返回 `internal` 业务错误，不返回部分结果。将授权集合保留在宿主内存中，可在不削弱可见性或排序的前提下避开有效大型语料库的 SQLite 变量上限。载体请求信号可取消持久化列表枚举、冷会话摘要收集和每一页搜索。部署若未挂载该服务，或索引／查询操作失败，也会返回 `internal` 业务错误，以便客户端保留仅基于元数据的匹配项。
+`session.search` 是以 `session.list` 所列会话为范围的有界内容搜索投影。网关向可选的 `ctx.sessionQuery` 服务请求全局排序后的当前 surface user、assistant 和 steering（中途引导）匹配项，每页至多 20 个命中，并持续消费该结果流，直到获得至多 20 个可见会话／snippet 对及一个前瞻项；返回前仍会依据从列表推导的授权集合重新校验每个命中。返回的 snippet 最多包含 240 个 Unicode 码点；如果提供方返回格式错误的非字符串 snippet，系统会直接失败，而不会让它越过 RPC 边界。将授权集合保留在宿主内存中，可在不削弱可见性或排序的前提下避开有效大型语料库的 SQLite 变量上限。
+
+陈旧的续传会丢弃该提供方尝试中的所有部分结果、去重条目和游标，然后依据最初从列表推导的可见性快照从第一页重新开始。陈旧重试共用最多 100 次提供方调用的限制（因此最多检查 2,000 个命中）；如果单页命中数超限、续传游标重复，或用尽该调用预算后结果流仍未耗尽，都会直接返回 `internal` 业务错误，不返回部分结果。载体请求信号可取消持久化列表枚举、冷会话摘要收集和每一次搜索调用；即使同时收到陈旧拒绝，也以取消为准。部署若未挂载该服务，或索引／查询故障无法恢复，也会返回 `internal` 业务错误，以便客户端保留仅基于元数据的匹配项。

 `command.*` 与 `skill.*` 领域向客户端暴露宿主命令注册表和技能目录。每个方法都通过 `sessionId` 寻址一个会话的 Agent（被服务的会话必有 Agent；`command.*` 经由与 `session.*` 相同的路径恢复冷会话，而 `skill.list` 从会话头解析项目根目录，不触碰 Agent 注册表）。`command.execute` 在宿主侧运行一条斜杠命令行并返回脱耦结果；载体的请求信号可取消正在运行的处理器。`host/commands-changed` 是目录失效帧：客户端重新拉取 `command.list` 而不是做差分。

--- a/packages/host/apiproxy/src/api-proxy.ts
+++ b/packages/host/apiproxy/src/api-proxy.ts
@@ -41,8 +41,11 @@ const DEFAULT_MAX_MESSAGES = 50
 /** Product contract: sidebar search returns one bounded page and no cursor. */
 const SESSION_SEARCH_LIMIT = 20

-/** Provider work budget: at most 100 pages × 20 hits = 2,000 inspected hits. */
-const SESSION_SEARCH_PROVIDER_PAGE_LIMIT = 100
+/** Provider work budget: at most 100 calls and 2,000 inspected hits. */
+const SESSION_SEARCH_PROVIDER_CALL_LIMIT = 100
+
+/** Product contract: snippets contain at most 240 Unicode code points. */
+const SESSION_SEARCH_SNIPPET_CODE_POINT_LIMIT = 240

 /** Bound cold-log stat fan-out so an aborted search stops launching new work. */
 const COLD_SUMMARY_BATCH_SIZE = 16
@@ -55,6 +58,28 @@ function isAborted(signal: AbortSignal): boolean {
  return signal.aborted
 }

+/** Copy at most the product-visible code-point prefix without splitting a surrogate pair. */
+function boundedSessionSearchSnippet(value: unknown): string {
+  if (typeof value !== 'string') {
+    throw new Error('session search provider returned a non-string snippet')
+  }
+  let end = 0
+  for (
+    let count = 0;
+    count < SESSION_SEARCH_SNIPPET_CODE_POINT_LIMIT && end < value.length;
+    count++
+  ) {
+    const first = value.charCodeAt(end)
+    const hasSurrogatePair = first >= 0xD800
+      && first <= 0xDBFF
+      && end + 1 < value.length
+      && value.charCodeAt(end + 1) >= 0xDC00
+      && value.charCodeAt(end + 1) <= 0xDFFF
+    end += hasSurrogatePair ? 2 : 1
+  }
+  return end === value.length ? value : value.slice(0, end)
+}
+
 /**
 * Message-boundary pagination: count maxMessages surface messages backwards from
 * the window tail; the cut is the starting seq of the oldest message group
@@ -648,24 +673,42 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
          const acceptedIds = new Set<SessionId>()
          const seenCursors = new Set<SessionSearchCursor>()
          let cursor: SessionSearchCursor | undefined
-          let providerPageCount = 0
+          let providerCallCount = 0
          while (authorized.length <= SESSION_SEARCH_LIMIT) {
            if (isAborted(signal)) return cancelled()
-            if (providerPageCount >= SESSION_SEARCH_PROVIDER_PAGE_LIMIT) {
+            if (providerCallCount >= SESSION_SEARCH_PROVIDER_CALL_LIMIT) {
              throw new Error(
-                `session search provider exceeded the ${SESSION_SEARCH_PROVIDER_PAGE_LIMIT}-page work budget`,
+                `session search provider exceeded the ${SESSION_SEARCH_PROVIDER_CALL_LIMIT}-call work budget`,
              )
            }
-            providerPageCount++
-            const page = await sessionQuery.searchSessions({
-              query: request.payload.query,
-              eventFilters: [
-                { kind: 'type', values: ['user/message', 'assistant/message', 'steering/message'] },
-                { kind: 'surface', values: ['current'] },
-              ],
-              limit: SESSION_SEARCH_LIMIT,
-              ...cursor === undefined ? {} : { cursor },
-            }, { signal })
+            providerCallCount++
+            const requestedCursor = cursor
+            let page
+            try {
+              page = await sessionQuery.searchSessions({
+                query: request.payload.query,
+                eventFilters: [
+                  { kind: 'type', values: ['user/message', 'assistant/message', 'steering/message'] },
+                  { kind: 'surface', values: ['current'] },
+                ],
+                limit: SESSION_SEARCH_LIMIT,
+                ...requestedCursor === undefined ? {} : { cursor: requestedCursor },
+              }, { signal })
+            } catch (error: unknown) {
+              if (isAborted(signal)) return cancelled()
+              if (
+                requestedCursor !== undefined
+                && error instanceof SessionQueryError
+                && error.code === 'SESSION_QUERY_STALE_CURSOR'
+              ) {
+                authorized.length = 0
+                acceptedIds.clear()
+                seenCursors.clear()
+                cursor = undefined
+                continue
+              }
+              throw error
+            }
            if (isAborted(signal)) return cancelled()
            const providerItemCount = page.items.length
            if (providerItemCount > SESSION_SEARCH_LIMIT) {
@@ -691,10 +734,11 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
                || !MESSAGE_TYPES.has(hit.bestMatch.type)
                || acceptedIds.has(hit.header.id)
              ) continue
+              const snippet = boundedSessionSearchSnippet(hit.bestMatch.snippet)
              acceptedIds.add(hit.header.id)
              authorized.push({
                sessionId: hit.header.id,
-                snippet: hit.bestMatch.snippet,
+                snippet,
              })
            }
            const nextCursor = page.nextCursor
--- a/packages/host/apiproxy/tests/api-proxy-search.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-search.spec.ts
@@ -225,7 +225,7 @@ describe('session.search', () => {
    expect(searchSessions.mock.calls[1]?.[0]).toMatchObject({ cursor: 'page-2' })
  })

-  it('fails closed after 100 provider pages with distinct continuation cursors', async () => {
+  it('fails closed after 100 provider calls with distinct continuation cursors', async () => {
    const ctx = await baseContext()
    ctx.sessions.create(sid('visible'), { meta: header('visible') })
    let pageNumber = 0
@@ -247,10 +247,153 @@ describe('session.search', () => {
    expect(response.result.ok).toBe(false)
    if (response.result.ok) throw new Error('unreachable')
    expect(response.result.error).toMatchObject({ code: 'internal' })
-    expect(response.result.error.message).toContain('100-page work budget')
+    expect(response.result.error.message).toContain('100-call work budget')
    expect(searchSessions).toHaveBeenCalledTimes(100)
  })

+  it('restarts a stale continuation from one fresh generation and keeps the visibility snapshot', async () => {
+    const ctx = await baseContext()
+    const oldOnly = hit('old-only', 0)
+    const shared = hit('shared', 1)
+    const freshFirst = hit('fresh-first', 2)
+    const freshLast = hit('fresh-last', 3)
+    for (const item of [oldOnly, shared, freshFirst, freshLast]) {
+      ctx.sessions.create(item.header.id, { meta: item.header })
+    }
+    const late = hit('late-visible', 4)
+    const stale = new SessionQueryError(
+      'provider generation changed',
+      'SESSION_QUERY_STALE_CURSOR',
+    )
+    const searchSessions = vi.fn((providerRequest: SessionSearchRequest) => {
+      switch (searchSessions.mock.calls.length) {
+        case 1:
+          expect(providerRequest).not.toHaveProperty('cursor')
+          return Promise.resolve({
+            items: [oldOnly, shared],
+            nextCursor: 'old-cursor',
+          })
+        case 2:
+          expect(providerRequest.cursor).toBe('old-cursor')
+          ctx.sessions.create(late.header.id, { meta: late.header })
+          return Promise.reject(stale)
+        case 3:
+          expect(providerRequest).not.toHaveProperty('cursor')
+          return Promise.resolve({
+            items: [freshFirst, shared],
+            nextCursor: 'old-cursor',
+          })
+        case 4:
+          expect(providerRequest.cursor).toBe('old-cursor')
+          return Promise.resolve({ items: [freshLast, late] })
+        default:
+          return Promise.reject(new Error('unexpected provider call'))
+      }
+    })
+    ctx.provide('sessionQuery', { searchSessions } as never)
+
+    const response = await createApiProxy(ctx, defaults).sessions.search(
+      request('stale-restart'),
+      new AbortController().signal,
+    )
+
+    expect(response.result).toEqual({
+      ok: true,
+      value: {
+        items: [
+          { sessionId: 'fresh-first', snippet: 'match 2' },
+          { sessionId: 'shared', snippet: 'match 1' },
+          { sessionId: 'fresh-last', snippet: 'match 3' },
+        ],
+        hasMore: false,
+      },
+    })
+    expect(searchSessions).toHaveBeenCalledTimes(4)
+  })
+
+  it('counts continuous stale restarts against the 100-call budget', async () => {
+    const ctx = await baseContext()
+    const partial = hit('partial')
+    ctx.sessions.create(partial.header.id, { meta: partial.header })
+    const stale = new SessionQueryError(
+      'provider generation changed',
+      'SESSION_QUERY_STALE_CURSOR',
+    )
+    const searchSessions = vi.fn((providerRequest: SessionSearchRequest) => {
+      if (searchSessions.mock.calls.length > 100) {
+        return Promise.reject(new Error('provider was called after the shared budget'))
+      }
+      if (providerRequest.cursor !== undefined) return Promise.reject(stale)
+      return Promise.resolve({
+        items: [partial],
+        nextCursor: `cursor-${searchSessions.mock.calls.length}`,
+      })
+    })
+    ctx.provide('sessionQuery', { searchSessions } as never)
+
+    const response = await createApiProxy(ctx, defaults).sessions.search(
+      request('stale-churn'),
+      new AbortController().signal,
+    )
+
+    expect(response.result.ok).toBe(false)
+    if (response.result.ok) throw new Error('unreachable')
+    expect(response.result.error.code).toBe('internal')
+    expect(response.result.error.message).toContain('100-call work budget')
+    expect(response.result).not.toHaveProperty('value')
+    expect(searchSessions).toHaveBeenCalledTimes(100)
+  })
+
+  it('gives abort priority over a coincident stale continuation failure', async () => {
+    const ctx = await baseContext()
+    ctx.sessions.create(sid('visible'), { meta: header('visible') })
+    const controller = new AbortController()
+    const stale = new SessionQueryError(
+      'provider generation changed',
+      'SESSION_QUERY_STALE_CURSOR',
+    )
+    const searchSessions = vi.fn()
+      .mockResolvedValueOnce({ items: [], nextCursor: 'stale-cursor' })
+      .mockImplementationOnce(() => {
+        controller.abort()
+        return Promise.reject(stale)
+      })
+    ctx.provide('sessionQuery', { searchSessions } as never)
+
+    const response = await createApiProxy(ctx, defaults).sessions.search(
+      request('abort-stale'),
+      controller.signal,
+    )
+
+    expect(response.result).toMatchObject({
+      ok: false,
+      error: { code: 'cancelled' },
+    })
+    expect(searchSessions).toHaveBeenCalledTimes(2)
+  })
+
+  it('does not retry a stale first-page failure', async () => {
+    const ctx = await baseContext()
+    ctx.sessions.create(sid('visible'), { meta: header('visible') })
+    const searchSessions = vi.fn(() => Promise.reject(new SessionQueryError(
+      'provider generation changed before paging',
+      'SESSION_QUERY_STALE_CURSOR',
+    )))
+    ctx.provide('sessionQuery', { searchSessions } as never)
+
+    const response = await createApiProxy(ctx, defaults).sessions.search(
+      request('first-page-stale'),
+      new AbortController().signal,
+    )
+
+    expect(response.result).toMatchObject({
+      ok: false,
+      error: { code: 'internal' },
+    })
+    expect(response.result).not.toHaveProperty('value')
+    expect(searchSessions).toHaveBeenCalledOnce()
+  })
+
  it('rejects an oversized provider page before iterating its items', async () => {
    const ctx = await baseContext()
    ctx.sessions.create(sid('visible'), { meta: header('visible') })
@@ -272,6 +415,61 @@ describe('session.search', () => {
    expect(iterate).not.toHaveBeenCalled()
  })

+  it('bounds provider snippets to 240 Unicode code points without splitting astral text', async () => {
+    const ctx = await baseContext()
+    const visible = hit('visible')
+    ctx.sessions.create(visible.header.id, { meta: visible.header })
+    const expected = `${'x'.repeat(239)}😀`
+    const overlong = {
+      ...visible,
+      bestMatch: {
+        ...visible.bestMatch,
+        snippet: `${expected}${'y'.repeat(10_000)}`,
+      },
+    }
+    ctx.provide('sessionQuery', {
+      searchSessions: () => Promise.resolve({ items: [overlong] }),
+    } as never)
+
+    const response = await createApiProxy(ctx, defaults).sessions.search(
+      request('bounded-snippet'),
+      new AbortController().signal,
+    )
+
+    expect(response.result).toEqual({
+      ok: true,
+      value: {
+        items: [{ sessionId: 'visible', snippet: expected }],
+        hasMore: false,
+      },
+    })
+  })
+
+  it('fails closed when the provider returns a non-string snippet', async () => {
+    const ctx = await baseContext()
+    const visible = hit('visible')
+    ctx.sessions.create(visible.header.id, { meta: visible.header })
+    ctx.provide('sessionQuery', {
+      searchSessions: () => Promise.resolve({
+        items: [{
+          ...visible,
+          bestMatch: { ...visible.bestMatch, snippet: 42 },
+        }],
+      }),
+    } as never)
+
+    const response = await createApiProxy(ctx, defaults).sessions.search(
+      request('malformed-snippet'),
+      new AbortController().signal,
+    )
+
+    expect(response.result.ok).toBe(false)
+    if (response.result.ok) throw new Error('unreachable')
+    expect(response.result.error.code).toBe('internal')
+    expect(response.result.error.message).toContain('non-string snippet')
+    expect(response.result).not.toHaveProperty('value')
+  })
+
  it('inspects only numerically stored items when a compliant page overrides iteration', async () => {
    const ctx = await baseContext()
    const visible = Array.from({ length: 21 }, (_, index) => hit(`visible-${index}`, index))