@ljwei-stak/dsh-model-route-bot 0.66.3 → 0.67.0

package/packages/orchestration/src/model-accounting.mjs

@@ -4,6 +4,7 @@ import {actualCost} from '../../../.dsh-plugin/shared/run-ledger.mjs'
 import {managedModelRequest,taskModelRequest} from './model-receipt.mjs'
 import {assessFundingAdmission} from './funding-admission.mjs'
 import {taskHash} from './task-contract.mjs'
+import {planOutputBound,requestFieldAccess} from './model-request-bounds.mjs'
 
 const fail=code=>{throw Object.assign(new Error(code),{code})}
 const deferred=()=>{let resolve;const promise=new Promise(r=>{resolve=r});return {promise,resolve}}
@@ -25,7 +26,7 @@ function usageOf(value){
 }
 
 /** Every observed model call has one source receipt; only the linked run owns money. */
-export function createModelAccounting({store,authority,pricingFor,inputBoundFor,machineId,workspaceId,now=Date.now,ttlMs=120000,limits={dailyLimitUsd:1,monthlyLimitUsd:0},maxActive=16}){
+export function createModelAccounting({store,authority,pricingFor,fundingRevisionFor,inputBoundFor,modelBoundsFor,preparedFrameFor,machineId,workspaceId,now=Date.now,ttlMs=120000,limits={dailyLimitUsd:1,monthlyLimitUsd:0},maxActive=16}){
   if(store?.kind!=='sqlite-router-state'||typeof store.recordModelReceipt!=='function'||typeof pricingFor!=='function')fail('MODEL_ACCOUNTING_STORAGE_REQUIRED')
   const active=new Set();let closed=false
   const controllerSet=new Set()
@@ -37,7 +38,8 @@ export function createModelAccounting({store,authority,pricingFor,inputBoundFor,
       ...(policy.scopeId?{fundingScopeId:policy.scopeId}:{}),...(policy.projectId?{fundingProjectId:policy.projectId}:{}),
       requestHash:requestHash(options),createdAt,ownerPid:process.pid,state:'admitted',finishedAt:null,usage:null,usageComplete:false,actualModel:null,reportedCostUsd:null,finishKind:null,outcome:null}
   }
-  const callStore=(receipt,config,estimate)=>({read:()=>store.read(),update:(change,options)=>store.update(current=>{
+  const callStore=(receipt,config,estimate,assertFunding)=>({read:()=>store.read(),update:(change,options)=>store.update(current=>{
+    if (receipt.state === 'admitted' || receipt.state === 'running') assertFunding()
     if(receipt.state==='admitted'&&config.funding==='api'){
       const checked=assessFundingAdmission({store,state:current,botId:receipt.botId,scopeId:config.scopeId,projectId:config.projectId,policy:config,estimatedCostUsd:estimate,excludeRunId:receipt.runId,now:now()})
       if(!checked.accepted)return checked
@@ -65,30 +67,92 @@ export function createModelAccounting({store,authority,pricingFor,inputBoundFor,
       authority.assertTool(identity.subject,'model/infer')
       if(authority.describe(identity.subject).botId!==identity.botId)fail('MODEL_OWNER_MISMATCH')
       if(task&&(task.botId!==identity.botId||task.provider!==options.provider||task.model!==options.model))fail('MODEL_TASK_OWNER_MISMATCH')
-      const config=await pricingFor({botId:identity.botId,provider:options.provider,model:options.model,source:identity.source})
+      const fundingQuery={botId:identity.botId,provider:options.provider,model:options.model,source:identity.source}
+      const config=await pricingFor(fundingQuery)
       if(active.size>=maxActive||active.has(options))fail('MODEL_CONCURRENCY_LIMIT')
       if(!config||!['api','subscription'].includes(config.funding))fail('MODEL_FUNDING_REQUIRED')
       if(config.funding==='api'&&(!config.pricing||!['input','output'].every(k=>Number.isFinite(config.pricing[k])&&config.pricing[k]>=0)))fail('MODEL_PRICE_REQUIRED')
-      if(options.maxTokens!==undefined&&options.maxTokens!==null&&(!Number.isSafeInteger(options.maxTokens)||options.maxTokens<1))fail('MODEL_OUTPUT_BOUNDARY_REQUIRED')
+      if(options.maxTokens!==undefined&&(!Number.isSafeInteger(options.maxTokens)||options.maxTokens<1))fail('MODEL_OUTPUT_BOUNDARY_REQUIRED')
       if(config.funding==='api'&&(!Number.isSafeInteger(config.maxOutputTokens)||config.maxOutputTokens<1))fail('MODEL_ESTIMATE_REQUIRED')
-      // A declared request allowance is not a tokenizer. The trusted Host must
-      // supply an upper bound, normally the pinned model's whole context window.
-      // This also covers images and adapter framing instead of guessing from URL bytes.
+      // A declared request allowance is a price, not a capacity: the trusted
+      // input upper bound is the pinned model's own context window, resolved
+      // per admission because an adapter registration can be replaced under a
+      // live Host. That whole window already covers images, tool declarations
+      // and adapter framing, so no tokenizer and no source-length estimate
+      // stands in for it. A route whose adapter declares no window has no bound
+      // to admit, which is a required-bound failure rather than a smaller number
+      // to pretend with.
+      // A prepared call (the independent path) already bound one adapter generation and
+      // recorded its exact capacities in a Host-owned frame keyed by this request's signal.
+      // When that frame is present and names this exact route, admission uses it instead of
+      // reading the current registration: the window and default it prices are the ones the
+      // prepared dispatch will actually stream, so no metadata read can combine one
+      // generation's window with another's endpoint. A frame about another route is ignored.
+      const frame=preparedFrameFor?await preparedFrameFor(options):null
+      if (!managed && (config.fundingRevision || frame?.fundingRevision)) {
+        if (!frame || !Object.hasOwn(frame, 'fundingRevision')) fail('MODEL_FUNDING_FRAME_MISSING')
+        if (frame.fundingRevision !== (config.fundingRevision ?? null)) fail('MODEL_FUNDING_CHANGED')
+      }
+      const assertFunding=()=>{
+        if (config.fundingRevision && fundingRevisionFor?.(fundingQuery) !== config.fundingRevision) fail('MODEL_FUNDING_CHANGED')
+      }
+      assertFunding()
+      if(closed)fail('MODEL_ACCOUNTING_CLOSED')
+      if(active.size>=maxActive||active.has(options))fail('MODEL_CONCURRENCY_LIMIT')
+      options.signal?.throwIfAborted()
+      const frameBounds=frame&&frame.bounds&&frame.provider===options.provider&&frame.model===options.model?frame.bounds:null
+      let outputDefault=null
       if(config.funding==='api'){
-        const inputBound=await inputBoundFor?.({options,identity,config})
+        let inputBound
+        if(frameBounds){
+          inputBound=frameBounds.contextWindow
+          outputDefault=frameBounds.defaultMaxTokens??null
+        }else{
+          const bounds=modelBoundsFor?await modelBoundsFor({options,identity,config,signal:options.signal??null}):null
+          inputBound=bounds?.inputBound??(inputBoundFor?await inputBoundFor({options,identity,config}):null)
+          outputDefault=bounds?.outputDefault??null
+        }
         if(!Number.isSafeInteger(inputBound)||inputBound<1||!Number.isSafeInteger(config.maxInputTokens)||inputBound>config.maxInputTokens)fail('MODEL_INPUT_BOUNDARY_REQUIRED')
       }
+      // The output bound the provider will actually see. An omitted bound is not
+      // an unbounded one: the pinned adapter materializes its own per-request
+      // cap into the request before dispatch, so that declared cap — and nothing
+      // else — is what arrives. A request the Host cannot bring under the
+      // allowance, whether frozen above it or declaring no bound at all, is
+      // refused here: before a receipt, a reservation, a lease, an active slot or
+      // any provider call exists.
       const outputBound=config.maxOutputTokens
-      const effectiveOutput=Number.isSafeInteger(outputBound)&&outputBound>0?Math.min(options.maxTokens??outputBound,outputBound):options.maxTokens
-      // The SDK AgentLoop hands the adapter a frozen request that already carries the model's own
-      // output bound, so the Host cannot lower it. Such a request is admitted with the configured
-      // allowance as its estimate (decision: usability first); the daily/monthly budget stays the
-      // hard limit, and the per-call output bound is advisory where the request cannot be changed.
-      const descriptor=Object.getOwnPropertyDescriptor(options,'signal'),tokenDescriptor=Object.getOwnPropertyDescriptor(options,'maxTokens')
-      const carrier=descriptor?descriptor.writable:Object.isExtensible(options)
-      const clampable=carrier&&!(tokenDescriptor&&!tokenDescriptor.writable)&&Boolean(tokenDescriptor||Object.isExtensible(options))
+      let plan
+      if(frameBounds){
+        // The prepared config already carries the dispatched bound (clamped before it
+        // froze). Admit it as-is and only validate it against the current allowance; a
+        // second clamp here would change the dispatched config and fail the prepared call
+        // with INVALID_PREPARED_CALL, so a lowered allowance is a refusal, never a re-clamp.
+        const dispatched=options.maxTokens??null
+        if(config.funding==='api'){
+          if(!Number.isSafeInteger(dispatched)||dispatched<1)fail('MODEL_ESTIMATE_REQUIRED')
+          if(dispatched>outputBound)fail('MODEL_OUTPUT_BOUND_EXCEEDED')
+        }
+        plan={ok:true,maxTokens:options.maxTokens??undefined,source:'prepared'}
+      }else{
+        plan=Number.isSafeInteger(outputBound)&&outputBound>0
+          ?planOutputBound({requested:options.maxTokens??null,allowance:outputBound,adapterDefault:outputDefault})
+          :{ok:true,maxTokens:options.maxTokens??undefined,source:'none'}
+      }
+      if(!plan.ok)fail(plan.code)
+      // Mutability is per field and independent of every other field's: a request
+      // whose signal is read-only may still carry a writable maxTokens.
+      const tokenAccess=requestFieldAccess(options,'maxTokens'),signalAccess=requestFieldAccess(options,'signal')
+      if(plan.source==='clamp'&&!tokenAccess.canWrite)fail(plan.refusal)
+      const effectiveOutput=plan.maxTokens
+      // The bounds lookup is asynchronous, so the gates it ran past are re-run
+      // here: an accounting that closed while the adapter was being asked, or an
+      // active set another admission filled, must not gain a slot because a
+      // metadata read was slow.
+      if(closed)fail('MODEL_ACCOUNTING_CLOSED')
+      if(active.size>=maxActive||active.has(options))fail('MODEL_CONCURRENCY_LIMIT')
       const record=receiptBase(identity,{...options,...(effectiveOutput!==undefined?{maxTokens:effectiveOutput}:{})},config,managed,task)
-      let manager,accepted,binding,lease,guard,inner,estimate,previousSignal=options.signal,changedOutput=false,leaseSignal=null
+      let manager,accepted,binding,lease,guard,inner,estimate,previousSignal=options.signal,changedOutput=false,changedSignal=false,leaseSignal=null
       let started=false,exhausted=false,terminal=false,finishKind=null,observed={usage:null,complete:false},primaryError,cleanupError,propagated=false,aborted=false,consumerClosed=false
       const controller=new AbortController();controllerSet.add(controller);active.add(options)
       const build=()=>{
@@ -116,37 +180,35 @@ export function createModelAccounting({store,authority,pricingFor,inputBoundFor,
           estimate=record.funding==='subscription'?0:(input*config.pricing.input+output*config.pricing.output)/1e6
           if(!Number.isFinite(estimate))fail('MODEL_ESTIMATE_REQUIRED')
           const pending={id:record.runId,createdAt:record.createdAt,status:'running',finishedAt:null,packages:[],reviews:[],modelCall:{schemaVersion:1,id:record.id,botId:record.botId,source:record.source,...(record.fundingScopeId?{fundingScopeId:record.fundingScopeId}:{}),...(record.fundingProjectId?{fundingProjectId:record.fundingProjectId}:{})}}
-          manager=createBudgetReservations({state:callStore(record,config,estimate)})
+          manager=createBudgetReservations({state:callStore(record,config,estimate,assertFunding)})
           accepted=await manager.beginExecution({run:pending,packageEstimates:[{id:'inference',billing:record.funding,estimatedCostUsd:estimate}],...limits})
           if(!accepted.accepted)fail(accepted.reason==='subscription-call-limit'?'MODEL_SUBSCRIPTION_LIMIT':'MODEL_WAITING_BUDGET')
         }
         binding={taskId:record.taskId??record.runId,attemptId:record.attemptId,machineId,workspaceId,location:'local'}
         lease=authority.issue(identity.subject,{binding,tools:['model/infer'],ttlMs})
         // The caller request may be frozen (the SDK AgentLoop passes one). A
-        // mutable request carries the combined lease signal so the provider
-        // aborts directly; a frozen request cannot, so the lease gates the
+        // request whose signal field is writable carries the combined lease
+        // signal so the provider aborts directly; otherwise the lease gates the
         // iteration instead and cleanup still returns the provider iterator.
-        // Clamping happens when the request allows it; when it does not, the
-        // reservation above already covers the bound the provider will see.
-        const clampNeeded=effectiveOutput!==undefined&&options.maxTokens!==undefined&&options.maxTokens!==effectiveOutput
-        if(clampNeeded&&clampable){
-          options.maxTokens=effectiveOutput;changedOutput=true
-        }else if(carrier&&effectiveOutput!==undefined&&options.maxTokens===undefined&&(!tokenDescriptor||tokenDescriptor.writable)&&Object.isExtensible(options)){
-          // Adoption is best effort: the estimate above already uses the full allowance, so a
-          // sealed request without an output bound is admitted as it is instead of failing.
-          options.maxTokens=effectiveOutput;changedOutput=true
+        if(plan.source==='clamp'){
+          // Write the bound the provider will see, then read it back: a field
+          // that reports writable but does not take the value is not one the
+          // Host may claim it clamped.
+          if(!Reflect.set(options,'maxTokens',effectiveOutput)||options.maxTokens!==effectiveOutput)fail(plan.refusal)
+          changedOutput=true
         }
         guard=authority.run(lease.token,binding,'model/infer',async({signal})=>{
-          if(carrier){options.signal=AbortSignal.any([signal,...(previousSignal?[previousSignal]:[])]);options.signal.throwIfAborted()}
+          if(signalAccess.canWrite){options.signal=AbortSignal.any([signal,...(previousSignal?[previousSignal]:[])]);changedSignal=true;options.signal.throwIfAborted()}
           else{leaseSignal=signal;signal.throwIfAborted()}
           record.state='running'
           if(managed)await store.recordModelReceipt(record)
           else{
-            const value=await createBudgetReservations({state:callStore(record,config,estimate)}).checkpointExecution({reservationId:accepted.reservationId,ownerToken:accepted.ownerToken,run:{id:record.runId,createdAt:record.createdAt,status:'running',packages:[],reviews:[]},startedIds:['inference'],...limits,checkBudget:true})
+            const value=await createBudgetReservations({state:callStore(record,config,estimate,assertFunding)}).checkpointExecution({reservationId:accepted.reservationId,ownerToken:accepted.ownerToken,run:{id:record.runId,createdAt:record.createdAt,status:'running',packages:[],reviews:[]},startedIds:['inference'],...limits,checkBudget:true})
             if(value.accepted===false)fail('MODEL_WAITING_BUDGET')
           }
           authority.assertModel(identity.subject,options.provider,options.model)
-          if(carrier)options.signal.throwIfAborted();else signal.throwIfAborted()
+          assertFunding()
+          if(signalAccess.canWrite)options.signal.throwIfAborted();else signal.throwIfAborted()
           inner=next()[Symbol.asyncIterator]();started=true;ready.resolve(true)
           await done.promise
         },{signal:controller.signal})
@@ -176,15 +238,17 @@ export function createModelAccounting({store,authority,pricingFor,inputBoundFor,
         try{await inner?.return?.()}catch(e){cleanupError=e}
         done.resolve();try{await guard}catch(e){primaryError??=e}
         aborted=Boolean(options.signal?.aborted||controller.signal.aborted||previousSignal?.aborted)
-        if(descriptor)Object.defineProperty(options,'signal',descriptor);else delete options.signal
-        if(changedOutput){if(tokenDescriptor)Object.defineProperty(options,'maxTokens',tokenDescriptor);else delete options.maxTokens}
+        // Restore exactly what this call wrote, and nothing it did not: a request
+        // the Host never touched keeps its own shape, sealed or frozen alike.
+        if(changedSignal){if(signalAccess.descriptor)Object.defineProperty(options,'signal',signalAccess.descriptor);else delete options.signal}
+        if(changedOutput){if(tokenAccess.descriptor)Object.defineProperty(options,'maxTokens',tokenAccess.descriptor);else delete options.maxTokens}
         record.finishedAt=now();record.usage=observed.usage;record.usageComplete=terminal&&observed.complete;record.finishKind=finishKind
         record.state=started&&(!terminal||cleanupError)?'unknown':'settled'
         record.outcome=!started?'cancelled':!terminal||cleanupError?'unknown':aborted||finishKind==='aborted'?'cancelled':finishKind==='error'?'failed':'succeeded'
         try{
           if(managed){if(lease)await store.recordModelReceipt(record)}
           else if(accepted?.accepted){
-            const run=build();await createBudgetReservations({state:callStore(record,config,estimate)}).finishExecution({reservationId:accepted.reservationId,ownerToken:accepted.ownerToken,run})
+            const run=build();await createBudgetReservations({state:callStore(record,config,estimate,assertFunding)}).finishExecution({reservationId:accepted.reservationId,ownerToken:accepted.ownerToken,run})
           }
         }finally{
           if(lease)authority.release(lease.token);active.delete(options);controllerSet.delete(controller)

package/packages/orchestration/src/model-auxiliary-dispatch.mjs

@@ -0,0 +1,187 @@
+// The same-generation seam for the Bot's auxiliary model calls.
+//
+// DS Bot makes three model requests that are not a conversation step: the handoff note
+// (`writeNote`), the in-place checkpoint (`writeCheckpoint`) and the context steward's
+// decision (`askSteward`). All three are bare `ctx.llm.stream({purpose:'compaction'})`
+// calls, so the SDK resolves the route's current registration at dispatch — the same
+// mispricing window `model-prepared-generation.mjs` closes for the independent path and
+// `model-loop-frame.mjs` reads around for the integrated conversation. An auxiliary call
+// cannot borrow either: the session log's `request/header` fold is the conversation's own
+// metadata (experiment E3 in
+// tmp/integration/integrated-generation-study-1/experiment.mjs: an aux call read
+// generation A and dispatched generation B), and an aux request carries no loop marker.
+//
+// This module puts the auxiliary calls on the one public seam that binds metadata to its
+// own dispatch: `LlmRuntime.prepareCall(config, signal, configure)` (dsh-llm
+// lib/index.js:2220-2261). It composes the product's own prepared dispatcher, so the
+// auxiliary request is prepared once, its exact capacities are recorded in the Host-owned
+// frame store the accounting already reads, and its one-shot stream dispatches that same
+// capture through the ordinary `llm/stream` waterfall exactly once — no listener
+// re-prepares, no second waterfall, no second receipt.
+//
+// Three rules hold the trust boundary:
+//
+//   1. Identity is Host state, resolved before anything is prepared. `identityFor` is the
+//      parent's own `policy.modelIdentity`, which reads the principal directory for the
+//      request's Session. A request that names a Bot, a subject, a grant or a funding
+//      allowance of its own is refused: those are never caller inputs.
+//   2. The Host's own redactor runs before preparation. The frozen ds-bot secret listener
+//      (vendor src/host/secrets.js:505-514) rebuilds a request and re-enters
+//      `ctx.llm.stream` when it still finds a value; a prepared generation cannot survive
+//      that rebuild, and the product listener refuses it
+//      (`MODEL_PREPARED_REQUEST_REWRITTEN`) rather than price one generation and stream
+//      another. Redacting first is what makes the rewrite unnecessary, exactly as the
+//      independent path does.
+//   3. Nothing here holds money. The allowance read through `fundingFor` is only a capacity
+//      to clamp the dispatched output bound against, before the SDK freezes the config; the
+//      one accounting remains the sole authority over reservations, receipts and cost, and
+//      a missing or throwing read is treated as unpriced so it refuses in its own coded way.
+//
+// The steward's `reasoningEffort:'off'` is decided from the generation being prepared. The
+// prepared handle deliberately does not expose the model's reasoning metadata (dsh-llm
+// lib/index.js:2241-2248), and `resolveModelInfo` reads the current registration — another
+// generation — so the only public place that knows is the `configure` callback the SDK
+// itself calls with the captured `modelInfo`. `createPreparedModelDispatch` owns that
+// callback and does not expose it, so this module supplies the runtime it prepares through:
+// a Host-owned service whose `prepareCall` wraps the real one and adds the caller's control
+// selection to the SDK's own callback. No SDK file, vendor file or global is touched, the
+// wrapper is built per call (no shared state, no concurrency hazard), and an effort the
+// prepared generation does not support is never sent.
+
+import { createPreparedModelDispatch, redactPreparedModelRequest } from './model-prepared-generation.mjs'
+
+const fail = (code, detail) => { throw Object.assign(new Error(code), { code, ...detail }) }
+
+/**
+ * Request keys an auxiliary caller may never supply.
+ *
+ * Identity, authority and money are committed Host state. A request that carries any of
+ * them is refused rather than silently ignored: a caller that believes it named the Bot
+ * must not go on believing the call ran for that Bot.
+ */
+const UNTRUSTED_KEYS = Object.freeze([
+  'botId', 'subject', 'principal', 'grant', 'authority', 'identity', 'token', 'lease', 'binding',
+  'funding', 'allowance', 'maxOutputTokens', 'maxInputTokens', 'pricing', 'scopeId', 'projectId',
+])
+
+/**
+ * The steward's control selection: `reasoningEffort:'off'` when — and only when — the
+ * generation being prepared declares that effort.
+ *
+ * @param info - the prepared generation's normalized model info, exactly as the SDK passes
+ *   it to `configure` (dsh-llm lib/index.js:2228).
+ * @returns `{reasoningEffort:'off'}`, or `undefined` when the generation supports no `off`
+ *   effort or declares no reasoning at all, in which case the adapter's own default stands
+ *   — the behaviour the bare stream had.
+ */
+export function auxiliaryReasoningOff(info) {
+  const efforts = info?.reasoning?.efforts
+  if (!Array.isArray(efforts)) return undefined
+  return efforts.some(effort => effort && effort.id === 'off') ? { reasoningEffort: 'off' } : undefined
+}
+
+/**
+ * Wrap one runtime so its `prepareCall` adds the caller's control selection to the SDK's
+ * own `configure` callback.
+ *
+ * The wrapper is a Host-owned object whose prototype is the live service, so every other
+ * member of `LlmRuntime` is the real one and the real service stays `this` inside
+ * `prepareCall`. The decorated object is built per call and never escapes this module.
+ */
+function withConfiguredControls(runtime, controlsFor) {
+  if (typeof controlsFor !== 'function') return runtime
+  const decorated = Object.create(runtime)
+  Object.defineProperty(decorated, 'prepareCall', {
+    value: (config, signal, configure) => runtime.prepareCall(config, signal, (controls, info) => {
+      let selected
+      try { selected = controlsFor(info) } catch (error) {
+        fail('MODEL_AUXILIARY_CONTROLS_REJECTED', { reason: String(error?.code ?? error?.message ?? error) })
+      }
+      // Only the call-config fields matter to the SDK; anything else a control selection
+      // returns is dropped rather than forwarded into the dispatched request.
+      let next = controls
+      if (selected && typeof selected === 'object') {
+        next = { ...controls }
+        for (const [key, value] of Object.entries(selected)) if (value !== undefined) next[key] = value
+      }
+      // The dispatcher's own configure still decides the output bound and records the
+      // capacities the accounting admits on; this wrapper only adds the caller's selection.
+      return configure(next, info)
+    }),
+    writable: true, configurable: true, enumerable: false,
+  })
+  return decorated
+}
+
+/**
+ * The prepared auxiliary stream for the Bot's note, checkpoint and steward calls.
+ *
+ * @param llm - the live `llm` service, or a function returning it. A Host whose runtime
+ *   exposes no `prepareCall` is refused per call (`MODEL_PREPARED_UNAVAILABLE`), never
+ *   downgraded to the unprepared stream that re-resolves the model at dispatch.
+ * @param frames - the shared {@link createModelFrameStore} the one accounting reads. The
+ *   same store the independent path and the composition use, so an auxiliary frame is
+ *   admitted by the same authority and for exactly as long as its one dispatch.
+ * @param fundingFor - `({botId, provider, model}) => funding | null`, the Host's committed
+ *   funding read. Only its priced output allowance is used, and only as a capacity to clamp
+ *   against; a throw or a null is unpriced, and the accounting still refuses in its own way.
+ * @param identityFor - `(request) => {botId, subject, ...} | null`, the parent's trusted
+ *   Host identity read (`policy.modelIdentity`). It is the only source of the Bot and the
+ *   subject; a request that names its own is refused.
+ * @param redact - the Host's public string redactor, applied to `messages` and `system`
+ *   before preparation so the frozen secret listener has nothing to rebuild.
+ * @param carryUsageTag - optional `(from, to) => void`, the runtime's own usage-tag carry,
+ *   so a redaction rebuild keeps the DS Bot usage provenance the tag records.
+ * @returns a callable `stream(request, {controls})` — also reachable as `.stream` — that is
+ *   an async iterable of chunks, plus `reasoningOff` for the steward's decision.
+ */
+export function createAuxiliaryModelStream({
+  llm = null, frames = null, fundingFor = null, identityFor = null, redact = null, carryUsageTag = null,
+} = {}) {
+  if (!frames || typeof frames.set !== 'function' || typeof frames.read !== 'function') fail('MODEL_FRAME_STORE_REQUIRED')
+  if (typeof identityFor !== 'function') fail('MODEL_AUXILIARY_IDENTITY_REQUIRED')
+  if (typeof redact !== 'function') fail('MODEL_AUXILIARY_REDACTION_REQUIRED')
+  const service = () => (typeof llm === 'function' ? llm() : llm)
+
+  async function* stream(request, context = {}) {
+    if (!request || typeof request !== 'object' || Array.isArray(request)) fail('MODEL_AUXILIARY_REQUEST_REQUIRED')
+    for (const key of UNTRUSTED_KEYS) if (request[key] !== undefined) {
+      fail('MODEL_AUXILIARY_IDENTITY_UNTRUSTED', { reason: key })
+    }
+    if (typeof request.provider !== 'string' || request.provider === '' || typeof request.model !== 'string' || request.model === '') {
+      fail('MODEL_AUXILIARY_ROUTE_REQUIRED')
+    }
+    if (!Array.isArray(request.messages)) fail('MODEL_AUXILIARY_MESSAGES_REQUIRED')
+
+    // 1. Trusted identity, before anything is prepared: whose call this is, decided by the
+    //    Host's own directory for this request's Session — never by the request.
+    let identity = null
+    try { identity = await identityFor(request) } catch (error) {
+      fail('MODEL_AUXILIARY_IDENTITY_REQUIRED', { reason: String(error?.code ?? error?.message ?? error) })
+    }
+    const botId = identity?.botId
+    if (typeof botId !== 'string' || botId === '') fail('MODEL_AUXILIARY_IDENTITY_REQUIRED')
+
+    // 2. Host redaction, before the generation is bound. The redactor is the Host's own; a
+    //    value it finds is replaced here, so the frozen secret listener passes this request
+    //    straight through instead of rebuilding it and losing the prepared generation.
+    const redacted = redactPreparedModelRequest(request, redact)
+    if (typeof carryUsageTag === 'function') carryUsageTag(request.messages, redacted.messages)
+
+    // 3. One preparation, one dispatch, one frame. The dispatcher is built per call so the
+    //    control selection above belongs to this request alone, and the shared frame store
+    //    is what the accounting reads.
+    const runtime = service()
+    if (!runtime || typeof runtime.prepareCall !== 'function') fail('MODEL_PREPARED_UNAVAILABLE')
+    const dispatch = createPreparedModelDispatch({
+      llm: () => withConfiguredControls(runtime, typeof context.controls === 'function' ? context.controls : null),
+      frames,
+      ...(typeof fundingFor === 'function' ? { fundingFor } : {}),
+    })
+    yield* dispatch.dispatch(redacted, { botId })
+  }
+
+  stream.stream = stream
+  stream.reasoningOff = auxiliaryReasoningOff
+  return Object.freeze(stream)
+}

package/packages/orchestration/src/model-loop-frame.mjs

@@ -0,0 +1,179 @@
+// The same-generation frame for the integrated AgentLoop path, read from the session log.
+//
+// The installed SDK's `LlmRuntime.prepareCall` is the only public seam that binds one
+// adapter registration's metadata to its own dispatch (dsh-llm lib/index.js 2220-2261:
+// capture the registration at 2224, one-shot dispatch at 2249-2258). The integrated
+// AgentLoop already uses it (dsh-agent-loop lib/index.js:1201) and, BEFORE dispatch,
+// synchronously logs that exact generation into its Session: `request/header` with the
+// resolved config plus the `adapterDefaults` flags (lib/index.js:1226-1240) and
+// `request/context` with the context window (lib/index.js:1262-1271). The fold of those
+// events (`Session.requestHeader()` / `Session.requestContext()`, dsh-session
+// lib/index.js:1612/1627) therefore carries the generation the loop's frozen marked
+// request will dispatch, even when the current registration was replaced after the
+// loop's prepareCall — proven causally by experiment E1 in
+// tmp/integration/integrated-generation-study-1/experiment.mjs (dispatch A, current
+// registration read B, session-log fold A).
+//
+// The fold is the CONVERSATION's latest state, not a per-call receipt: it is not, by
+// itself, proof that it describes this one call. This module therefore derives a frame
+// only for a request that carries every public anchor the AgentLoop leaves on it, and
+// answers with a verdict the caller must act on rather than a bare frame-or-null:
+//
+//   frame            the fold describes this exact request; price and admit on it.
+//   aux              not a conversation step (no loop marker, or an aux purpose). The
+//                    caller keeps its existing path — an ordinary request, or a
+//                    caller-owned prepared call that carries its own frame.
+//   unsupportedHost  the Host could not answer at all (no session lookup wired, a
+//                    sessions service that is not a SessionStore, a throwing read).
+//                    The product refuses API funding; subscription callers may retain
+//                    their unpriced path. This verdict supplies no captured frame.
+//   missing          a loop step whose record is absent or unusable (no fold, no live
+//                    session, no materialized output bound). The caller refuses the
+//                    funded call rather than price another generation.
+//   invalid          a loop step whose record contradicts the request (route drift,
+//                    control drift, session identity mismatch). The caller refuses.
+//
+// SDK-free by construction: the loop-marker predicate and the session lookup are
+// injected, so orchestration keeps its no-direct-SDK-import shape and a request cannot
+// reach a conversation frame it did not earn from the SDK's own marker.
+
+const positive = value => Number.isSafeInteger(value) && value > 0 ? value : null
+const isId = value => typeof value === 'string' && value.length > 0 && value.length <= 512
+
+/** What one resolution found. See the module comment for what the caller owes each. */
+export const LOOP_FRAME_VERDICT = Object.freeze({
+  FRAME: 'frame', AUX: 'aux', UNSUPPORTED_HOST: 'unsupportedHost', MISSING: 'missing', INVALID: 'invalid',
+})
+
+/** The reason attached to a non-frame verdict; stable, loggable, never a message. */
+export const LOOP_FRAME_REASON = Object.freeze({
+  HOST_LOOKUP_UNWIRED: 'host-lookup-unwired',
+  HOST_LOOKUP_FAILED: 'host-lookup-failed',
+  HOST_SESSION_SERVICE_UNUSABLE: 'host-session-service-unusable',
+  HOST_SESSION_NOT_LIVE: 'host-session-not-live',
+  HOST_SESSION_IDENTITY_MISMATCH: 'host-session-identity-mismatch',
+  HOST_FOLD_UNREADABLE: 'host-fold-unreadable',
+  LOOP_SESSION_ID_MISSING: 'loop-session-id-missing',
+  LOOP_REQUEST_NOT_CANONICAL: 'loop-request-not-canonical',
+  LOOP_HEADER_FOLD_ABSENT: 'loop-header-fold-absent',
+  LOOP_CONTEXT_FOLD_ABSENT: 'loop-context-fold-absent',
+  LOOP_ROUTE_DRIFT: 'loop-route-drift',
+  LOOP_CONTROL_DRIFT: 'loop-control-drift',
+  LOOP_CONTEXT_WINDOW_UNBOUND: 'loop-context-window-unbound',
+  LOOP_OUTPUT_BOUND_UNMATERIALIZED: 'loop-output-bound-unmaterialized',
+})
+
+const verdict = (kind, reason) => Object.freeze(reason === undefined ? { kind } : { kind, reason })
+
+// The call-config fields the SDK compares for one call (`callConfigEquals`, dsh-llm
+// lib/index.js:367-371). The loop request is spread from the logged header's config, so
+// any disagreement means the fold in hand belongs to a different step of the
+// conversation — a stale fold, not this dispatch.
+const CONTROL_FIELDS = Object.freeze(['provider', 'model', 'reasoningEffort', 'temperature', 'maxTokens'])
+const controlDrift = (config, request) => {
+  for (const field of CONTROL_FIELDS) if (config[field] !== request[field]) return LOOP_FRAME_REASON.LOOP_CONTROL_DRIFT
+  if (config.stop === undefined || request.stop === undefined) {
+    if (config.stop !== request.stop) return LOOP_FRAME_REASON.LOOP_CONTROL_DRIFT
+  } else if (config.stop.length !== request.stop.length || config.stop.some((item, index) => item !== request.stop[index])) {
+    return LOOP_FRAME_REASON.LOOP_CONTROL_DRIFT
+  }
+  return null
+}
+
+/**
+ * Derive a Host-owned same-generation frame for one integrated-loop request.
+ *
+ * @param sessionFor - `(sessionId) => session | null | undefined`; in the composed
+ *   product this is `id => ctx.get('sessions')?.get?.(id)` — the Host SessionStore the
+ *   AgentLoop itself appends through (dsh-session lib/index.js:1980). Absent, throwing
+ *   or not a SessionStore is `unsupportedHost`, never an error and never a frame.
+ * @param isLoopRequest - the SDK's `isAgentLoopRequest` (re-exported through
+ *   modules/bot-runtime), so a hand-built request carrying a conversation's `sessionId`
+ *   cannot reach that conversation's frame: the marker is a process-private WeakSet the
+ *   SDK alone can add to (dsh-llm lib/index.js:377-388), and it does not survive a copy.
+ * @returns `(request) => verdict`, where a `frame` verdict carries the frozen
+ *   `{provider, model, bounds: {contextWindow, defaultMaxTokens}, request}` shape
+ *   model-accounting.mjs:89-96 consumes.
+ */
+export function createSessionLoopFrameResolver({ sessionFor = null, isLoopRequest = null, allowUnbounded = null } = {}) {
+  const lookup = typeof sessionFor === 'function' ? sessionFor : null
+  const marked = typeof isLoopRequest === 'function' ? isLoopRequest : null
+  const aux = () => verdict(LOOP_FRAME_VERDICT.AUX)
+  const unsupported = reason => verdict(LOOP_FRAME_VERDICT.UNSUPPORTED_HOST, reason)
+
+  // Without the SDK's marker predicate nothing can be told apart, so the resolver is
+  // inert. A request shaped like a loop envelope is reported as unsupported — the gap
+  // is open — while everything else keeps the path it already had. The shape is a
+  // heuristic for reporting only; it grants nothing.
+  const loopShaped = request => request && typeof request === 'object' && isId(request.sessionId)
+    && request.purpose === undefined && Object.isFrozen(request)
+    && Array.isArray(request.messages) && Object.isFrozen(request.messages)
+  if (!marked) return request => (loopShaped(request) ? unsupported(LOOP_FRAME_REASON.HOST_LOOKUP_UNWIRED) : aux())
+  // The Host did not wire the session seam at all. A loop step is reported as
+  // unsupported — the gap is open — while an ordinary or aux request keeps its path.
+  if (!lookup) return request => (request && typeof request === 'object' && marked(request) && request.purpose === undefined
+    ? unsupported(LOOP_FRAME_REASON.HOST_LOOKUP_UNWIRED)
+    : aux())
+
+  return request => {
+    if (!request || typeof request !== 'object' || !marked(request)) return aux()
+    // A marked request that names an aux purpose is not a conversation step: the
+    // conversation's frame must never price a compaction, a title or a note
+    // (experiment E3), and a caller-owned prepared aux binds its own dispatch anyway.
+    if (request.purpose !== undefined) return aux()
+    if (!isId(request.sessionId)) return verdict(LOOP_FRAME_VERDICT.INVALID, LOOP_FRAME_REASON.LOOP_SESSION_ID_MISSING)
+    // The loop freezes its request envelope and the messages it derived
+    // (dsh-agent-loop lib/index.js:1274-1288). A request that is not that envelope is
+    // not the one the fold was logged for, whatever it claims.
+    if (!Object.isFrozen(request) || !Array.isArray(request.messages) || !Object.isFrozen(request.messages)) {
+      return verdict(LOOP_FRAME_VERDICT.INVALID, LOOP_FRAME_REASON.LOOP_REQUEST_NOT_CANONICAL)
+    }
+    let session = null
+    try { session = lookup(request.sessionId) } catch { return unsupported(LOOP_FRAME_REASON.HOST_LOOKUP_FAILED) }
+    if (session === null || session === undefined) return verdict(LOOP_FRAME_VERDICT.MISSING, LOOP_FRAME_REASON.HOST_SESSION_NOT_LIVE)
+    if (typeof session.requestContext !== 'function' || typeof session.requestHeader !== 'function') {
+      return unsupported(LOOP_FRAME_REASON.HOST_SESSION_SERVICE_UNUSABLE)
+    }
+    // The lookup must answer about the session the request names, not some other one.
+    if (session.id !== request.sessionId) return verdict(LOOP_FRAME_VERDICT.INVALID, LOOP_FRAME_REASON.HOST_SESSION_IDENTITY_MISMATCH)
+    let context = null, header = null
+    try { context = session.requestContext(); header = session.requestHeader() } catch { return unsupported(LOOP_FRAME_REASON.HOST_FOLD_UNREADABLE) }
+    if (!context || typeof context !== 'object') return verdict(LOOP_FRAME_VERDICT.MISSING, LOOP_FRAME_REASON.LOOP_CONTEXT_FOLD_ABSENT)
+    if (!header || typeof header !== 'object' || !header.config || typeof header.config !== 'object') {
+      return verdict(LOOP_FRAME_VERDICT.MISSING, LOOP_FRAME_REASON.LOOP_HEADER_FOLD_ABSENT)
+    }
+    // The fold must describe this exact route on both surfaces. A conversation that
+    // moved to another route between the loop's log and this read has no frame for it,
+    // and pricing the old route's window against the new endpoint is the very mixing
+    // this module exists to prevent.
+    if (context.provider !== request.provider || context.model !== request.model
+      || header.config.provider !== request.provider || header.config.model !== request.model) {
+      return verdict(LOOP_FRAME_VERDICT.INVALID, LOOP_FRAME_REASON.LOOP_ROUTE_DRIFT)
+    }
+    const contextWindow = positive(context.contextWindow)
+    if (controlDrift(header.config, request) !== null) return verdict(LOOP_FRAME_VERDICT.INVALID, LOOP_FRAME_REASON.LOOP_CONTROL_DRIFT)
+    // Only an explicitly Host-classified subscription route may preserve unknown
+    // capacities. It still carries the same canonical prepared route and controls;
+    // accounting never receives fabricated capacity or an API estimate from it.
+    const unbounded = typeof allowUnbounded === 'function' && allowUnbounded(request) === true
+    if (contextWindow === null && !unbounded) return verdict(LOOP_FRAME_VERDICT.MISSING, LOOP_FRAME_REASON.LOOP_CONTEXT_WINDOW_UNBOUND)
+    // The dispatched output bound is already materialized into the frozen request by
+    // the SDK's own call-config resolution (dsh-llm lib/index.js:2183-2186), so the
+    // generation that streams is the one admitted. A loop step that carries no
+    // materialized bound (the NO_ADAPTER fallback at dsh-agent-loop lib/index.js:1084
+    // dispatches a bare `llm.stream`) has no same-generation frame: the caller refuses
+    // it instead of falling back to a read that can name the other generation.
+    const dispatched = positive(request.maxTokens)
+    if (dispatched === null && !unbounded) return verdict(LOOP_FRAME_VERDICT.MISSING, LOOP_FRAME_REASON.LOOP_OUTPUT_BOUND_UNMATERIALIZED)
+    // `adapterDefaults.maxTokens === true` marks that the SDK materialized the adapter's
+    // default into the logged config (dsh-llm lib/index.js:2236-2239); that value is the
+    // output default this generation dispatches. A bound the caller declared needs no
+    // default: the request already carries it.
+    const defaultMaxTokens = header.adapterDefaults?.maxTokens === true ? dispatched : null
+    const frame = Object.freeze({
+      provider: request.provider, model: request.model,
+      bounds: Object.freeze({ contextWindow, defaultMaxTokens }), request,
+    })
+    return Object.freeze({ kind: LOOP_FRAME_VERDICT.FRAME, frame })
+  }
+}