fix(web): bound search provider work (round 6)

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: b9f0fcd8506afda733774868d78fe6e851b4fe2a
-README.zh.md: c57990b029b8d1e143396bb13718dbed165e2b47
+README.md: 2f062ba9b927ab62518523731d39fd7c52e07c8d
+README.zh.md: 72ff415f793b4bdb2068a8240ea42baab79984dc

packages/host/apiproxy/README.md

@@ -14,7 +14,7 @@ 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, pages 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. 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, 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. 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.
 
 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.
 

packages/host/apiproxy/README.zh.md

@@ -14,7 +14,7 @@ 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 个可见会话／snippet 对及一个前瞻项，并在返回前依据从列表推导的授权集合重新校验每个命中。将授权集合保留在宿主内存中，可在不削弱可见性或排序的前提下避开有效大型语料库的 SQLite 变量上限。载体请求信号可取消持久化列表枚举、冷会话摘要收集和每一页搜索。部署若未挂载该服务，或索引／查询操作失败，都会返回 `internal` 业务错误，以便客户端保留仅基于元数据的匹配项。
+`session.search` 是以 `session.list` 所列会话为范围的有界内容搜索投影。网关向可选的 `ctx.sessionQuery` 服务请求全局排序后的当前 surface user、assistant 和 steering（中途引导）匹配项，每页至多 20 个命中，并持续消费该结果流，直到获得至多 20 个可见会话／snippet 对及一个前瞻项；返回前仍会依据从列表推导的授权集合重新校验每个命中。宿主最多调用提供方 100 次（检查 2,000 个命中）；如果单页命中数超限、续传游标重复，或用尽该预算后结果流仍未耗尽，都会直接返回 `internal` 业务错误，不返回部分结果。将授权集合保留在宿主内存中，可在不削弱可见性或排序的前提下避开有效大型语料库的 SQLite 变量上限。载体请求信号可取消持久化列表枚举、冷会话摘要收集和每一页搜索。部署若未挂载该服务，或索引／查询操作失败，也会返回 `internal` 业务错误，以便客户端保留仅基于元数据的匹配项。
 
 `command.*` 与 `skill.*` 领域向客户端暴露宿主命令注册表和技能目录。每个方法都通过 `sessionId` 寻址一个会话的 Agent（被服务的会话必有 Agent；`command.*` 经由与 `session.*` 相同的路径恢复冷会话，而 `skill.list` 从会话头解析项目根目录，不触碰 Agent 注册表）。`command.execute` 在宿主侧运行一条斜杠命令行并返回脱耦结果；载体的请求信号可取消正在运行的处理器。`host/commands-changed` 是目录失效帧：客户端重新拉取 `command.list` 而不是做差分。
 

packages/host/apiproxy/src/api-proxy.ts

@@ -41,6 +41,9 @@ 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
+
 /** Bound cold-log stat fan-out so an aborted search stops launching new work. */
 const COLD_SUMMARY_BATCH_SIZE = 16
 
@@ -645,8 +648,15 @@ 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
           while (authorized.length <= SESSION_SEARCH_LIMIT) {
             if (isAborted(signal)) return cancelled()
+            if (providerPageCount >= SESSION_SEARCH_PROVIDER_PAGE_LIMIT) {
+              throw new Error(
+                `session search provider exceeded the ${SESSION_SEARCH_PROVIDER_PAGE_LIMIT}-page work budget`,
+              )
+            }
+            providerPageCount++
             const page = await sessionQuery.searchSessions({
               query: request.payload.query,
               eventFilters: [
@@ -657,6 +667,11 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
               ...cursor === undefined ? {} : { cursor },
             }, { signal })
             if (isAborted(signal)) return cancelled()
+            if (page.items.length > SESSION_SEARCH_LIMIT) {
+              throw new Error(
+                `session search provider returned ${page.items.length} items; maximum is ${SESSION_SEARCH_LIMIT}`,
+              )
+            }
             // Host visibility is the authorization boundary. Consume the
             // provider's globally ranked stream rather than binding every
             // visible id into one SQLite statement, then re-check complete

packages/host/apiproxy/tests/api-proxy-search.spec.ts

@@ -225,6 +225,128 @@ 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 () => {
+    const ctx = await baseContext()
+    ctx.sessions.create(sid('visible'), { meta: header('visible') })
+    let pageNumber = 0
+    const searchSessions = vi.fn((providerRequest: SessionSearchRequest) => {
+      pageNumber++
+      expect(providerRequest.limit).toBe(20)
+      return Promise.resolve({
+        items: [],
+        nextCursor: `page-${pageNumber}`,
+      })
+    })
+    ctx.provide('sessionQuery', { searchSessions } as never)
+
+    const response = await createApiProxy(ctx, defaults).sessions.search(
+      request('endless-pages'),
+      new AbortController().signal,
+    )
+
+    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(searchSessions).toHaveBeenCalledTimes(100)
+  })
+
+  it('rejects an oversized provider page before iterating its items', async () => {
+    const ctx = await baseContext()
+    ctx.sessions.create(sid('visible'), { meta: header('visible') })
+    const oversized = new Array<SessionSearchHit>(21)
+    const iterate = vi.fn(() => oversized.values())
+    Object.defineProperty(oversized, Symbol.iterator, { value: iterate })
+    const searchSessions = vi.fn(() => Promise.resolve({ items: oversized }))
+    ctx.provide('sessionQuery', { searchSessions } as never)
+
+    const response = await createApiProxy(ctx, defaults).sessions.search(
+      request('oversized-page'),
+      new AbortController().signal,
+    )
+
+    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('returned 21 items; maximum is 20')
+    expect(iterate).not.toHaveBeenCalled()
+  })
+
+  it('fails closed when the provider repeats a continuation cursor', async () => {
+    const ctx = await baseContext()
+    ctx.sessions.create(sid('visible'), { meta: header('visible') })
+    const searchSessions = vi.fn()
+      .mockResolvedValueOnce({ items: [], nextCursor: 'repeated' })
+      .mockResolvedValueOnce({ items: [], nextCursor: 'repeated' })
+    ctx.provide('sessionQuery', { searchSessions } as never)
+
+    const response = await createApiProxy(ctx, defaults).sessions.search(
+      request('repeated-cursor'),
+      new AbortController().signal,
+    )
+
+    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('repeated a continuation cursor')
+    expect(searchSessions).toHaveBeenCalledTimes(2)
+  })
+
+  it('does not count duplicate session ids toward the result or lookahead boundary', async () => {
+    const ctx = await baseContext()
+    const items = Array.from({ length: 21 }, (_, index) => hit(`visible-${index}`, index))
+    for (const item of items) {
+      ctx.sessions.create(item.header.id, { meta: item.header })
+    }
+    const searchSessions = vi.fn()
+      .mockResolvedValueOnce({ items: items.slice(0, 20), nextCursor: 'page-2' })
+      .mockResolvedValueOnce({ items: items.slice(0, 20), nextCursor: 'page-3' })
+      .mockResolvedValueOnce({ items: items.slice(20) })
+    ctx.provide('sessionQuery', { searchSessions } as never)
+
+    const response = await createApiProxy(ctx, defaults).sessions.search(
+      request('duplicate-pages'),
+      new AbortController().signal,
+    )
+
+    expect(response.result).toMatchObject({
+      ok: true,
+      value: { hasMore: true },
+    })
+    if (!response.result.ok) throw new Error('unreachable')
+    expect(response.result.value.items.map(item => item.sessionId)).toEqual(
+      items.slice(0, 20).map(item => item.header.id),
+    )
+    expect(searchSessions).toHaveBeenCalledTimes(3)
+  })
+
+  it('cancels on a continuation page and passes the carrier signal to both calls', async () => {
+    const ctx = await baseContext()
+    ctx.sessions.create(sid('visible'), { meta: header('visible') })
+    const controller = new AbortController()
+    const searchSessions = vi.fn()
+      .mockResolvedValueOnce({ items: [], nextCursor: 'page-2' })
+      .mockImplementationOnce(() => {
+        controller.abort()
+        return Promise.resolve({ items: [] })
+      })
+    ctx.provide('sessionQuery', { searchSessions } as never)
+
+    const response = await createApiProxy(ctx, defaults).sessions.search(
+      request('cancel-continuation'),
+      controller.signal,
+    )
+
+    expect(response.result).toMatchObject({
+      ok: false,
+      error: { code: 'cancelled' },
+    })
+    expect(searchSessions).toHaveBeenCalledTimes(2)
+    for (const call of searchSessions.mock.calls) {
+      expect(call[1]).toEqual({ signal: controller.signal })
+    }
+  })
+
   it('keeps visibility sets above SQLite variable limits out of provider bindings', async () => {
     const ctx = await baseContext()
     const cold = Array.from(