refactor(web): publish transient model request capacity (round 1)

packages/llm/llm/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/llm/llm/README.md
-README.md: 2328188e420df6de60f024982a31d37a858a303e
-README.zh.md: 586767a9e790fa68d27673836700fd789ce6a180
+README.md: d28a5632a3fbdbf11c7dba2ee0c57a704f2ba6f4
+README.zh.md: fd93fa43d5bfabd6e8751d4efbad229096ced08d

packages/llm/llm/README.md

@@ -16,7 +16,7 @@ An adapter registry plus a single streaming call surface, interceptable via a wa
 - `ctx.llm.listModels(provider: string): Promise<LlmModelInfo[]>` Discover the models one registered provider currently advertises.
 - `ctx.llm.resolveModelInfo(provider: string, model: string, signal?: AbortSignal): Promise<LlmResolvedModelInfo>` Resolve validated exact-model identity plus available context and reasoning metadata from the owning adapter, with optional cancellation for asynchronous adapters.
 - `ctx.llm.resolveCallConfig(config: LlmCallConfig, signal?: AbortSignal): Promise<LlmCallConfig>` Validate an explicit effort and materialize an adapter-configured default without clamping.
-- `ctx.llm.prepareCall(config: LlmCallConfig, signal?: AbortSignal): Promise<PreparedLlmCall>` Resolve a config and capture its current adapter registration as one cancellable, one-shot call.
+- `ctx.llm.prepareCall(config: LlmCallConfig, signal?: AbortSignal): Promise<PreparedLlmCall>` Resolve a config plus available context metadata in one exact-model lookup and capture its current adapter registration as one cancellable, one-shot call.
 - `ctx.llm.stream(options: GenerateOptions): AsyncIterable<StreamChunk>` Stream one model call as raw chunks (token-level deltas). Consumers assemble the chunks into blocks/messages with `BlockAssembler`.
 
 `LlmService` preserves errors from final adapter selection, synchronous dispatch, iterator construction, and iteration, and binds their provenance to the exact stream handle returned for that model call. `isLlmAdapterFailure(stream, value)` reports only errors from that call's final adapter boundary; `llmFailureOf(stream, value)` returns the adjacent immutable `LlmFailure`; `llmRetryPolicyOf(stream)` returns the immutable policy of the exact registration selected at that boundary, even if the route is later disposed or replaced. A call that never reaches a final adapter has no serving policy. Nested model calls, `llm/stream` middleware, and downstream consumer failures remain unclassified for the outer call. Classification never replaces or mutates the adapter's original coded `Error`.
@@ -25,7 +25,7 @@ Provider and model metadata is a discovery surface, not a routing whitelist. `re
 
 Exact-model metadata is a separate correctness query, not a catalog decoration or global LLM setting. `resolveModelInfo()` asks the adapter that owns the exact provider/model route once; an adapter can describe an unlisted dynamic model, and absent `context` or `reasoning` fields mean only that those capabilities are unavailable. Invalid identity, context, or reasoning metadata fails with `INVALID_MODEL_INFO`, `INVALID_MODEL_CONTEXT`, or `INVALID_MODEL_REASONING`.
 
-Reasoning identifiers are opaque adapter-owned strings rather than a core enum. An adapter publishes its ordered selectable list, including an `off` id when that model's capability API exposes one. `resolveCallConfig()` accepts only an exact advertised identifier, materializes `defaultEffort` when present, and otherwise preserves the provider default. Asynchronous model resolvers receive the caller's signal and must settle promptly after cancellation. `prepareCall()` additionally retains the exact adapter registration through header logging and terminal dispatch, so HMR cannot combine one adapter's capability result with another adapter's request; reusing its one-shot handle or changing its call-config fields fails with `INVALID_PREPARED_CALL`. An unsupported explicit or configured effort fails with `UNSUPPORTED_REASONING_EFFORT` before provider I/O.
+Reasoning identifiers are opaque adapter-owned strings rather than a core enum. An adapter publishes its ordered selectable list, including an `off` id when that model's capability API exposes one. `resolveCallConfig()` accepts only an exact advertised identifier, materializes `defaultEffort` when present, and otherwise preserves the provider default. Asynchronous model resolvers receive the caller's signal and must settle promptly after cancellation. `prepareCall()` additionally exposes the detached context metadata from that same lookup and retains the exact adapter registration through header logging and terminal dispatch, so HMR cannot combine one adapter's capability result with another adapter's request; reusing its one-shot handle or changing its call-config fields fails with `INVALID_PREPARED_CALL`. Its dispatch observer runs after a final stream handle is constructed and before adapter iteration. An unsupported explicit or configured effort fails with `UNSUPPORTED_REASONING_EFFORT` before provider I/O.
 
 ### Events
 

packages/llm/llm/README.zh.md

@@ -16,7 +16,7 @@
 - `ctx.llm.listModels(provider: string): Promise<LlmModelInfo[]>` 发现某个已注册提供方当前公布的模型。
 - `ctx.llm.resolveModelInfo(provider: string, model: string, signal?: AbortSignal): Promise<LlmResolvedModelInfo>` 从拥有精确路由的适配器解析经校验的确切模型身份、可用上下文和推理（reasoning）元数据；异步适配器可选地支持取消。
 - `ctx.llm.resolveCallConfig(config: LlmCallConfig, signal?: AbortSignal): Promise<LlmCallConfig>` 校验显式推理强度，并填入适配器配置的默认值，但不自动调整。
-- `ctx.llm.prepareCall(config: LlmCallConfig, signal?: AbortSignal): Promise<PreparedLlmCall>` 解析配置并将其当前适配器注册捕获为一次可取消、一次性调用。
+- `ctx.llm.prepareCall(config: LlmCallConfig, signal?: AbortSignal): Promise<PreparedLlmCall>` 在一次精确模型查询中解析配置与可用上下文元数据，并将其当前适配器注册捕获为一次可取消、一次性调用。
 - `ctx.llm.stream(options: GenerateOptions): AsyncIterable<StreamChunk>` 将一次模型调用流式输出为原始 chunk（token 级 delta）。消费方使用 `BlockAssembler` 将 chunk 组装为块／消息。
 
 `LlmService` 保留来自最终适配器选择、同步 dispatch、iterator 构造与迭代的错误，并将其溯源绑定到该次模型调用返回的精确流句柄。`isLlmAdapterFailure(stream, value)` 只报告该调用最终适配器边界的错误；`llmFailureOf(stream, value)` 返回相邻的不可变 `LlmFailure`；`llmRetryPolicyOf(stream)` 返回在该边界选中的确切注册所对应的不可变策略，即使之后释放或替换路由也不变。未到达最终适配器的调用没有服务策略。嵌套模型调用、`llm/stream` middleware 和下游消费方失败对外层调用仍未分类。分类绝不替换或更改适配器的原始编码 `Error`。
@@ -25,7 +25,7 @@
 
 确切模型元数据是独立的正确性查询，不是 catalog 装饰或全局 LLM 设置。`resolveModelInfo()` 会向拥有精确提供方／模型路由的适配器查询一次；适配器可以描述未列出的动态模型，缺少 `context` 或 `reasoning` 字段只表示相应能力不可用。无效的身份、上下文或推理元数据会以 `INVALID_MODEL_INFO`、`INVALID_MODEL_CONTEXT` 或 `INVALID_MODEL_REASONING` 失败。
 
-推理标识符是由适配器持有的不透明字符串，而非核心枚举。适配器会公布有序可选列表；模型能力 API 提供 `off` id 时，列表也会包含它。`resolveCallConfig()` 只接受与已公布标识符完全一致的值，在存在 `defaultEffort` 时填入它，否则保留提供方默认值。异步模型解析器会接收调用方的 signal，并且必须在取消后迅速完成结算。`prepareCall()` 还会让精确适配器注册跨越请求头记录和最终分派，因此 HMR（热模块替换）不会将一个适配器的能力结果与另一个适配器的请求混用；复用其一次性句柄或更改调用配置字段会以 `INVALID_PREPARED_CALL` 失败。不支持的显式或配置推理强度会在提供方 I/O 前以 `UNSUPPORTED_REASONING_EFFORT` 失败。
+推理标识符是由适配器持有的不透明字符串，而非核心枚举。适配器会公布有序可选列表；模型能力 API 提供 `off` id 时，列表也会包含它。`resolveCallConfig()` 只接受与已公布标识符完全一致的值，在存在 `defaultEffort` 时填入它，否则保留提供方默认值。异步模型解析器会接收调用方的 signal，并且必须在取消后迅速完成结算。`prepareCall()` 还会公开同一次查询得到的脱耦上下文元数据，并让精确适配器注册跨越请求头记录和最终分派，因此 HMR（热模块替换）不会将一个适配器的能力结果与另一个适配器的请求混用；复用其一次性句柄或更改调用配置字段会以 `INVALID_PREPARED_CALL` 失败。其分派观察器在最终流句柄构造完成后、适配器开始迭代前运行。不支持的显式或配置推理强度会在提供方 I/O 前以 `UNSUPPORTED_REASONING_EFFORT` 失败。
 
 ### 事件
 

packages/llm/llm/src/index.ts

@@ -10,6 +10,7 @@ import { Context, Service } from 'cordis'
 import type {
   GenerateOptions,
   LlmFailure,
+  LlmModelContext,
   LlmModelInfo,
   LlmResolvedModelInfo,
   LlmProviderInfo,
@@ -111,14 +112,18 @@ export class LlmError extends HarnessError {
 export interface PreparedLlmCall {
   /** Detached, deep-frozen config with any adapter-owned default materialized. */
   readonly config: LlmCallConfig
+  /** Detached context metadata resolved with the registration-bound call. */
+  readonly context?: LlmModelContext
   /**
    * Dispatch this call once through the registration captured during
    * preparation. The request's call-config fields must match {@link config};
    * reuse or mismatch fails with `INVALID_PREPARED_CALL`.
    * @param options - fully assembled request carrying the prepared config.
+   * @param onDispatched - contained Agent-loop notification hook invoked after
+   *   a stream handle is constructed and before its adapter is iterated.
    * @returns the chunk stream, including the `llm/stream` waterfall.
    */
-  stream(options: GenerateOptions): AsyncIterable<StreamChunk>
+  stream(options: GenerateOptions, onDispatched?: () => void): AsyncIterable<StreamChunk>
 }
 
 /**
@@ -392,15 +397,16 @@ export class LlmService extends Service {
    * @returns a detached config only when a default must be materialized.
    */
   async resolveCallConfig(config: LlmCallConfig, signal?: AbortSignal): Promise<LlmCallConfig> {
-    return this.resolveCallConfigFor(this.registration(config.provider), config, signal)
+    return (await this.resolveCallFor(this.registration(config.provider), config, signal)).config
   }
 
-  private async resolveCallConfigFor(
+  private async resolveCallFor(
     registration: AdapterRegistration,
     config: LlmCallConfig,
     signal?: AbortSignal,
-  ): Promise<LlmCallConfig> {
-    const reasoning = (await this.resolveModelInfoFor(registration, config.model, signal)).reasoning
+  ): Promise<{ config: LlmCallConfig; context?: LlmModelContext }> {
+    const resolved = await this.resolveModelInfoFor(registration, config.model, signal)
+    const reasoning = resolved.reasoning
     const requested = config.reasoningEffort
     if (reasoning === undefined) {
       if (requested !== undefined) {
@@ -409,17 +415,28 @@ export class LlmService extends Service {
           'UNSUPPORTED_REASONING_EFFORT',
         )
       }
-      return config
+      return {
+        config,
+        ...resolved.context === undefined ? {} : { context: resolved.context },
+      }
     }
     const effective = requested ?? reasoning.defaultEffort
-    if (effective === undefined) return config
+    if (effective === undefined) {
+      return {
+        config,
+        ...resolved.context === undefined ? {} : { context: resolved.context },
+      }
+    }
     if (!reasoning.efforts.some(effort => effort.id === effective)) {
       throw new LlmError(
         `provider "${config.provider}" model "${config.model}" does not support reasoning effort "${effective}"`,
         'UNSUPPORTED_REASONING_EFFORT',
       )
     }
-    return requested === effective ? config : { ...config, reasoningEffort: effective }
+    return {
+      config: requested === effective ? config : { ...config, reasoningEffort: effective },
+      ...resolved.context === undefined ? {} : { context: resolved.context },
+    }
   }
 
   /**
@@ -432,18 +449,25 @@ export class LlmService extends Service {
    */
   async prepareCall(config: LlmCallConfig, signal?: AbortSignal): Promise<PreparedLlmCall> {
     const registration = this.registration(config.provider)
-    const resolvedConfig = deepFreeze(structuredClone(
-      await this.resolveCallConfigFor(registration, config, signal),
-    ))
+    const resolved = await this.resolveCallFor(registration, config, signal)
+    const resolvedConfig = deepFreeze(structuredClone(resolved.config))
+    const context = resolved.context === undefined
+      ? undefined
+      : Object.freeze(structuredClone(resolved.context))
     let dispatched = false
     return Object.freeze({
       config: resolvedConfig,
-      stream: (options: GenerateOptions): AsyncIterable<StreamChunk> => {
+      ...context === undefined ? {} : { context },
+      stream: (options: GenerateOptions, onDispatched?: () => void): AsyncIterable<StreamChunk> => {
         if (dispatched) {
           throw new LlmError('a prepared LLM call can only be dispatched once', 'INVALID_PREPARED_CALL')
         }
         dispatched = true
-        return this.streamWithRegistration(options, { registration, config: resolvedConfig })
+        return this.streamWithRegistration(
+          options,
+          { registration, config: resolvedConfig },
+          onDispatched,
+        )
       },
     })
   }
@@ -478,25 +502,51 @@ export class LlmService extends Service {
    * so it cannot suppress the primary provider error. A downstream close awaits
    * adapter cleanup, whose failures remain ordinary untagged work.
    */
-  private async * adapterStream(
+  private adapterStream(
     options: GenerateOptions,
     failures: AdapterFailureScope,
     prepared?: { registration: AdapterRegistration; config: LlmCallConfig },
-  ): AsyncGenerator<StreamChunk> {
+    onDispatched?: () => void,
+  ): AsyncIterable<StreamChunk> {
+    if (prepared === undefined) {
+      return this.resolveAndStream(options, failures, onDispatched)
+    }
     let iterator: AsyncIterator<StreamChunk>
     try {
-      const registration = prepared?.registration ?? this.registration(options.provider)
+      const registration = prepared.registration
       failures.retryPolicy = registration.retryPolicy
-      const resolvedConfig = prepared === undefined
-        ? await this.resolveCallConfigFor(registration, options, options.signal)
-        : prepared.config
-      if (prepared !== undefined && !callConfigEquals(options, resolvedConfig)) {
+      const resolvedConfig = prepared.config
+      if (!callConfigEquals(options, resolvedConfig)) {
         throw new LlmError(
           'prepared LLM call config changed before adapter dispatch',
           'INVALID_PREPARED_CALL',
         )
       }
-      const resolvedOptions = prepared !== undefined || callConfigEquals(options, resolvedConfig)
+      const adapter = registration.adapter
+      const stream = adapter.stream(this.forAdapter(options, adapter))
+      iterator = stream[Symbol.asyncIterator]()
+    } catch (error: unknown) {
+      return this.failedAdapterStream(markLlmAdapterFailure(failures, error))
+    }
+    this.notifyDispatched(onDispatched)
+    return this.iterateAdapter(iterator, failures)
+  }
+
+  private async * resolveAndStream(
+    options: GenerateOptions,
+    failures: AdapterFailureScope,
+    onDispatched?: () => void,
+  ): AsyncGenerator<StreamChunk> {
+    let iterator: AsyncIterator<StreamChunk>
+    try {
+      const registration = this.registration(options.provider)
+      failures.retryPolicy = registration.retryPolicy
+      const resolvedConfig = (await this.resolveCallFor(
+        registration,
+        options,
+        options.signal,
+      )).config
+      const resolvedOptions = callConfigEquals(options, resolvedConfig)
         ? options
         : Object.isFrozen(options)
           ? deepFreeze({ ...options, ...resolvedConfig })
@@ -507,7 +557,19 @@ export class LlmService extends Service {
     } catch (error: unknown) {
       throw markLlmAdapterFailure(failures, error)
     }
+    this.notifyDispatched(onDispatched)
+    yield* this.iterateAdapter(iterator, failures)
+  }
 
+  private async * failedAdapterStream(error: Error): AsyncGenerator<StreamChunk> {
+    await Promise.resolve()
+    throw error
+  }
+
+  private async * iterateAdapter(
+    iterator: AsyncIterator<StreamChunk>,
+    failures: AdapterFailureScope,
+  ): AsyncGenerator<StreamChunk> {
     let completed = false
     let iterationFailed = false
     try {
@@ -537,6 +599,15 @@ export class LlmService extends Service {
     }
   }
 
+  private notifyDispatched(onDispatched: (() => void) | undefined): void {
+    if (onDispatched === undefined) return
+    try {
+      onDispatched()
+    } catch (error: unknown) {
+      this.ctx.logger.warn(`llm dispatch observer threw: ${String(error)}`)
+    }
+  }
+
   /**
    * Stream one model call as raw chunks (token-level deltas). Throws
    * `LlmError` with code `NO_ADAPTER` if no adapter is registered for
@@ -548,23 +619,32 @@ export class LlmService extends Service {
    * agent-loop request recovery; middleware and nested-call failures remain
    * untagged for the outer call.
    * @param options - the full request; `options.provider` selects the adapter.
+   * @param onDispatched - contained Agent-loop notification hook invoked after
+   *   a stream handle is constructed and before its adapter is iterated.
    * @returns the chunk stream, possibly wrapped by `llm/stream` listeners.
    */
-  stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
-    return this.streamWithRegistration(options)
+  stream(options: GenerateOptions, onDispatched?: () => void): AsyncIterable<StreamChunk> {
+    return this.streamWithRegistration(options, undefined, onDispatched)
   }
 
   private streamWithRegistration(
     options: GenerateOptions,
     prepared?: { registration: AdapterRegistration; config: LlmCallConfig },
+    onDispatched?: () => void,
   ): AsyncIterable<StreamChunk> {
     const failures: AdapterFailureScope = { failures: new WeakMap<Error, LlmFailure>() }
+    let terminalEntered = false
     const stream = this.ctx.waterfall(
       this,
       'llm/stream',
       options,
-      () => this.adapterStream(options, failures, prepared),
+      () => {
+        terminalEntered = true
+        return this.adapterStream(options, failures, prepared, onDispatched)
+      },
     )
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- waterfall mutates this latch.
+    if (!terminalEntered) this.notifyDispatched(onDispatched)
     return bindAdapterFailureScope(stream, failures)
   }
 }

packages/llm/llm/tests/service.spec.ts

@@ -1058,6 +1058,40 @@ describe('LlmService', () => {
     })).toThrow(expect.objectContaining({ code: 'INVALID_PREPARED_CALL' }))
   })
 
+  it('reuses one exact-model lookup for prepared config and context metadata', async () => {
+    const ctx = new Context()
+    await ctx.plugin(LlmService)
+    let resolutions = 0
+    const source = { contextWindow: 128_000 }
+    const adapter = new class extends ScriptedAdapter {
+      override resolveModel(provider: string, model: string): Promise<LlmResolvedModelInfo> {
+        resolutions += 1
+        return Promise.resolve({
+          provider,
+          id: model,
+          name: model,
+          context: source,
+          reasoning: {
+            efforts: [{ id: ReasoningEffortId('high'), name: 'High' }],
+            defaultEffort: ReasoningEffortId('high'),
+          },
+        })
+      }
+    }(SCRIPT)
+    ctx.llm.registerAdapter(['route'], adapter)
+
+    const prepared = await ctx.llm.prepareCall({ provider: 'route', model: 'model' })
+    source.contextWindow = 64_000
+    expect(prepared.config.reasoningEffort).toBe(ReasoningEffortId('high'))
+    expect(prepared.context).toEqual({ contextWindow: 128_000 })
+    expect(Object.isFrozen(prepared.context)).toBe(true)
+    for await (const _chunk of prepared.stream({
+      ...prepared.config,
+      messages: [],
+    })) { /* drain */ }
+    expect(resolutions).toBe(1)
+  })
+
   it('passes cancellation through exact-model resolution', async () => {
     const ctx = new Context()
     await ctx.plugin(LlmService)