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

package/packages/orchestration/src/bot-data-worker.mjs

@@ -0,0 +1,228 @@
+/**
+ * The fixed data worker: a plain Node child process that owns one Bot's SQLite
+ * database and runs its statements. The engine forks THIS module path — never
+ * a path a model supplies — and it is the only place better-sqlite3 loads.
+ *
+ * Protocol (child_process IPC):
+ *  - `open { dbPath }`, then requests `{ id, op, ... }`; each replies
+ *    `{ id, ok:true, value }` or `{ id, ok:false, error }`.
+ *  - The SQL gate lives on the Host side; here a statement is a single prepared
+ *    statement (better-sqlite3 refuses multi-statement strings), extension
+ *    loading is never enabled, and every read is bounded by maxRows/maxBytes.
+ *  - The execution layer re-checks what it is asked to run: a read must be a
+ *    statement better-sqlite3 reports as a reader (`stmt.reader`), and a write
+ *    must still classify as `CREATE … AS`. A `WITH … DELETE` cannot pass either
+ *    check.
+ *  - Row and character caps alone do not bound SQLite, so `open` also sets
+ *    `max_page_count` and the soft/hard native heap limits: an oversized
+ *    allocation or database is refused by SQLite itself (SQLITE_FULL /
+ *    SQLITE_NOMEM) inside this child, never by the Host.
+ *  - A statement that never returns is cancelled by the Host SIGKILLing this
+ *    process; an unknown outcome is never replayed. SQLite recovers the file
+ *    from its WAL on the next open.
+ *
+ * The database path arrives only in the `open` message and is computed by the
+ * Host from a validated Bot id — this worker accepts no path from any model.
+ * The handler is attached only when this file is the forked entry (MB_DATA_WORKER),
+ * so the functions below can be imported and unit-tested in-process.
+ */
+
+import { createRequire } from 'node:module'
+import { DATA_ERROR_CODES, DATA_LIMITS, DataFailure, dataError, sanitizeDataMessage, quoteIdent } from './bot-data-surface.mjs'
+import { gateSql } from './bot-data-sql.mjs'
+
+const require = createRequire(import.meta.url)
+const CELL_CHARS_MAX = 4000
+
+/** Import better-sqlite3 lazily so importing this module for tests never loads the native binding. */
+let Database = null
+const loadDatabase = () => { Database ??= require('better-sqlite3'); return Database }
+
+export const cellOf = value => {
+  if (value === null || value === undefined) return null
+  if (typeof value === 'bigint') return value.toString()
+  if (Buffer.isBuffer(value)) return `<blob ${value.length} bytes>`
+  if (typeof value === 'object') return JSON.stringify(value)
+  if (typeof value === 'string' && value.length > CELL_CHARS_MAX) return `${value.slice(0, CELL_CHARS_MAX)}…`
+  return value
+}
+
+const typeName = (type, sample) => {
+  if (type) return String(type).toUpperCase()
+  if (typeof sample === 'number') return Number.isInteger(sample) ? 'INTEGER' : 'REAL'
+  if (typeof sample === 'boolean') return 'BOOLEAN'
+  if (sample === null || sample === undefined) return 'ANY'
+  return 'TEXT'
+}
+
+const columnsOf = stmt => stmt.columns().map(column => ({ name: column.name, type: String(column.type ?? 'ANY').toUpperCase() }))
+
+export const openDb = (dbPath, limits = {}) => {
+  const db = loadDatabase()(dbPath)
+  // One writer per Bot; WAL so an abrupt kill recovers; bounded busy wait.
+  db.pragma('journal_mode = WAL')
+  db.pragma('busy_timeout = 5000')
+  db.pragma('foreign_keys = OFF')
+  // Query sort/group intermediates must share the native heap ceiling instead
+  // of spilling into an unbounded temporary database on the Host disk.
+  db.pragma('temp_store = MEMORY')
+  // Native and file bounds. Row/character caps alone do not bound SQLite: one
+  // statement can allocate native memory or grow the file without returning many
+  // rows, so SQLite itself refuses (SQLITE_FULL / SQLITE_NOMEM) and the child
+  // dies alone instead of the Host.
+  const maxPageCount = Math.max(1024, Math.trunc(limits.maxPageCount ?? DATA_LIMITS.dbMaxPageCount))
+  const hardHeap = Math.max(8 * 1024 * 1024, Math.trunc(limits.hardHeapLimitBytes ?? DATA_LIMITS.dbHardHeapLimitBytes))
+  const softHeap = Math.min(hardHeap, Math.max(1024 * 1024, Math.trunc(limits.softHeapLimitBytes ?? DATA_LIMITS.dbSoftHeapLimitBytes)))
+  db.pragma(`max_page_count = ${maxPageCount}`)
+  db.pragma(`hard_heap_limit = ${hardHeap}`)
+  db.pragma(`soft_heap_limit = ${softHeap}`)
+  return db
+}
+
+/** Run a read statement, collecting up to maxRows rows and maxBytes of JSON. */
+export const runRead = (db, sql, maxRows, maxBytes) => {
+  const stmt = db.prepare(sql)
+  // A statement that returns no data is not a read, whatever the caller labelled
+  // it: better-sqlite3 exposes this per statement, so the execution layer — not a
+  // regex — decides. The gate on the Host side is the first line, this is the second.
+  if (stmt.reader !== true) throw new DataFailure(dataError('write_refused', 'Only statements that return data may run as a read.'))
+  const columns = stmt.columns().map(column => ({ name: column.name, type: String(column.type ?? 'ANY').toUpperCase() }))
+  const rows = []
+  let bytes = 2
+  let truncated = false
+  for (const raw of stmt.raw().iterate()) {
+    const row = raw.map(cellOf)
+    rows.push(row)
+    bytes += Buffer.byteLength(JSON.stringify(row)) + 1
+    if (rows.length >= maxRows) { truncated = true; break }
+    if (bytes > maxBytes) { truncated = true; break }
+  }
+  const first = rows[0]
+  if (first) columns.forEach((column, index) => { if (column.type === 'ANY') column.type = typeName(undefined, first[index]) })
+  return { columns, rows, rowCount: rows.length, truncated }
+}
+
+/** Run a non-read statement (CREATE … AS); return the affected-row count. */
+export const runWrite = (db, sql) => {
+  // The gate is re-checked where the statement is executed: a WITH … DELETE is
+  // not a CREATE, and only CREATE … AS may run here.
+  const kind = gateSql(sql, { allowCreate: true })
+  if (kind.kind !== 'create') throw new DataFailure(dataError('write_refused', `${kind.verb ?? 'That statement'} is not allowed here.`))
+  const info = db.prepare(sql).run()
+  return { changes: info.changes ?? 0 }
+}
+
+/** Describe a table/view/result relation: exact row count, columns, few samples. */
+export const describeRelation = (db, target) => {
+  const columns = columnsOf(db.prepare(`SELECT * FROM ${target} LIMIT 0`))
+  const count = db.prepare(`SELECT COUNT(*) AS n FROM ${target}`).get()
+  columns.forEach(column => {
+    const quoted = quoteIdent(column.name)
+    let sample = []
+    try { sample = db.prepare(`SELECT DISTINCT ${quoted} AS v FROM ${target} WHERE ${quoted} IS NOT NULL LIMIT 3`).all().map(row => String(row.v)) } catch { /* unorderable column */ }
+    column.sample = sample
+  })
+  return { rowCount: Number(count.n), columns }
+}
+
+/** List user tables and views with their columns (no row scan). */
+export const listTables = db => db.prepare("SELECT name FROM sqlite_master WHERE type IN ('table','view') AND name NOT LIKE 'sqlite_%' ORDER BY name").all().map(row => {
+  const quoted = quoteIdent(row.name)
+  let columns = []
+  try { columns = columnsOf(db.prepare(`SELECT * FROM ${quoted} LIMIT 0`)) } catch { /* empty view */ }
+  return { name: row.name, sqlName: quoted, columns }
+})
+
+/** A bounded page for the grid; filter uses a bound parameter, never concatenation. */
+export const pageRelation = (db, { target, offset, limit, sort, filter, filterColumn }) => {
+  const columns = columnsOf(db.prepare(`SELECT * FROM ${target} LIMIT 0`))
+  const names = columns.map(column => column.name)
+  const where = []
+  const binds = []
+  if (filter) {
+    const pattern = `%${filter.replace(/[\\%_]/g, char => `\\${char}`)}%`
+    const hit = name => `CAST(${quoteIdent(name)} AS TEXT) LIKE ? ESCAPE '\\'`
+    if (filterColumn && names.includes(filterColumn)) { where.push(hit(filterColumn)); binds.push(pattern) }
+    else { where.push(`(${names.map(hit).join(' OR ')})`); for (let i = 0; i < names.length; i++) binds.push(pattern) }
+  }
+  let orderBy = ''
+  if (sort && names.includes(sort.column) && ['asc', 'desc'].includes(sort.direction)) orderBy = ` ORDER BY ${quoteIdent(sort.column)} ${sort.direction === 'desc' ? 'DESC' : 'ASC'}`
+  const whereSql = where.length ? ` WHERE ${where.join(' AND ')}` : ''
+  const total = db.prepare(`SELECT COUNT(*) AS n FROM ${target}${whereSql}`).get(...binds)
+  const rows = db.prepare(`SELECT * FROM ${target}${whereSql}${orderBy} LIMIT ? OFFSET ?`).raw().all(...binds, limit, offset).map(raw => raw.map(cellOf))
+  return { columns, rows, rowCount: Number(total.n), offset }
+}
+
+/** Materialise a SELECT into a results table; return its columns and row count. */
+export const materialise = (db, { sql, table }) => {
+  const body = sql.trim().replace(/;+\s*$/, '')
+  // SQLite has no CREATE OR REPLACE TABLE, and DDL is transactional here: the
+  // drop, the create and the row count all happen in ONE transaction, so a
+  // CREATE … AS that hits a bound (SQLITE_FULL/SQLITE_NOMEM) or a syntax error
+  // rolls the whole replacement back and the previous table survives intact.
+  // `changes` is 0 for CREATE … AS, so count the materialised rows explicitly.
+  const replace = db.transaction(() => {
+    db.prepare(`DROP TABLE IF EXISTS ${table}`).run()
+    db.prepare(`CREATE TABLE ${table} AS ${body}`).run()
+    return Number(db.prepare(`SELECT COUNT(*) AS n FROM ${table}`).get().n)
+  })
+  const rowCount = replace()
+  return { columns: columnsOf(db.prepare(`SELECT * FROM ${table} LIMIT 0`)), rowCount }
+}
+
+/** Insert parsed rows into a freshly created table (data_load); replace drops first. */
+export const loadRows = (db, { table, columns, sqlTypes, rows }) => {
+  // One transaction for drop + create + every insert: a load that fails halfway
+  // (a bound, a type error) leaves the previous table in place instead of a
+  // half-written replacement.
+  const replace = db.transaction(() => {
+    db.prepare(`DROP TABLE IF EXISTS ${table}`).run()
+    db.prepare(`CREATE TABLE ${table} (${columns.map((name, index) => `${quoteIdent(name)} ${sqlTypes[index]}`).join(', ')})`).run()
+    const insert = db.prepare(`INSERT INTO ${table} (${columns.map(quoteIdent).join(', ')}) VALUES (${columns.map(() => '?').join(', ')})`)
+    const insertMany = db.transaction(batch => { for (const row of batch) insert.run(...row) })
+    insertMany(rows)
+    return rows.length
+  })
+  return { rowCount: replace() }
+}
+
+const buildHandlers = () => {
+  let db = null
+  let dbPath = ''
+  return {
+    open: message => { dbPath = String(message?.dbPath ?? ''); db = openDb(dbPath, message?.limits ?? {}); return {} },
+    close: () => { if (db) { db.close(); db = null } return {} },
+    run: message => (message.mode === 'write' ? runWrite(db, message.sql) : runRead(db, message.sql, message.maxRows, message.maxBytes)),
+    describe: message => describeRelation(db, message.target),
+    listTables: () => listTables(db),
+    page: message => pageRelation(db, message),
+    materialise: message => materialise(db, message),
+    load: message => loadRows(db, message),
+    // Internal bookkeeping drop: the target is always an identifier the Host
+    // quoted itself (a card/result table), never a statement from a caller.
+    drop: message => { db.prepare(`DROP TABLE IF EXISTS ${message.target}`).run(); return { dropped: true } },
+    // The database path never leaves this child except redacted out of a message.
+    secrets: () => (dbPath.length >= 3 ? [dbPath] : []),
+  }
+}
+
+/** Attach the IPC handler only when forked as the fixed worker entry. */
+if (process.env.MB_DATA_WORKER === '1' && typeof process.send === 'function') {
+  const handlers = buildHandlers()
+  process.on('message', message => {
+    const { id, op } = message
+    try {
+      const handler = handlers[op]
+      if (!handler) throw Object.assign(new Error(`Unknown op ${op}`), { code: 'invalid_input' })
+      process.send({ id, ok: true, value: handler(message) })
+    } catch (error) {
+      // The model and the panel see a bounded message: no Host paths, no stack,
+      // no credentials — only what the statement itself said.
+      const code = error?.error?.code ?? error?.code
+      process.send({ id, ok: false, error: { message: sanitizeDataMessage(error instanceof Error ? error.message : String(error), handlers.secrets()), code: DATA_ERROR_CODES.includes(code) ? code : 'sql_error' } })
+    }
+  })
+  process.on('disconnect', () => { try { handlers.close() } catch { /* already gone */ } process.exit(0) })
+}
+
+export { buildHandlers }

package/packages/orchestration/src/bot-independent-execution.mjs

@@ -0,0 +1,195 @@
+/**
+ * The trusted frame an independent Bot turn runs in.
+ *
+ * The independent loop owns a transcript, not an identity. Before it may ask a provider for
+ * anything, a Host — and only a Host — has to say which committed Bot this turn is, which model
+ * that Bot has saved, and that the Bot is still committed, unrevoked and on the independent
+ * runtime. This module is that say: the Bot product composes it from its own directory,
+ * lifecycle, policy and serving admission, publishes it once, and the loop asks it per step.
+ *
+ * Three rules are load-bearing:
+ *
+ * 1. Nothing here accepts an identity from a request. The Bot comes from the argument the
+ *    dispatch already validated, the subject from the principal directory, the model from the
+ *    Bot's own committed record, and the runtime from the committed switch. A caller that names
+ *    a route the Bot has not saved is refused, so a step that started under one model cannot be
+ *    finished under another.
+ * 2. This module holds no money. The stream it returns is the Host's own `llm/stream` entry, so
+ *    the product's model listener — the same one an integrated turn goes through — applies the
+ *    Bot policy, re-decides the route per chunk and records the one receipt. A second ledger, or
+ *    a token-estimated "actual" bill, would be a second authority; there is none here.
+ * 3. An outcome the provider did not state is not an answer. A stream that ends without a
+ *    finish, or with an error, throws: the loop then writes no assistant message and the
+ *    transcript keeps the honest state instead of a confident-looking reply.
+ */
+
+import { collectAnswer } from './bot-independent-stream.mjs'
+import { independentSystemMessage } from './independent-message-wire.mjs'
+
+const idOk = value => typeof value === 'string' && /^[A-Za-z0-9_.-]{1,128}$/.test(value)
+const fail = (code, message) => { const error = new Error(message ?? code); error.code = code; throw error }
+
+/**
+ * `provider/model`, or null when the Bot has not committed to a route at all.
+ *
+ * The split is at the **first** slash only: a Host catalog legitimately serves refs whose model
+ * remainder carries a namespace of its own (`openrouter/anthropic/claude-3`), and dropping that
+ * remainder would ask for a model nobody committed to.
+ */
+export const routeOf = value => {
+  if (typeof value !== 'string') return null
+  const at = value.indexOf('/')
+  if (at <= 0 || at === value.length - 1) return null
+  const provider = value.slice(0, at)
+  const model = value.slice(at + 1)
+  return provider && model ? { provider, model } : null
+}
+
+/** What the operator is told when a stream cannot be turned into an answer. */
+const REPLY_REFUSAL = Object.freeze({
+  MODEL_STREAM_UNFINISHED: '模型没有给出结束状态，这一轮不写入回答。',
+  MODEL_STREAM_ERROR: '模型调用失败，这一轮不写入回答。',
+  MODEL_STREAM_ABORTED: '模型调用被中止，这一轮不写入回答。',
+  MODEL_STREAM_TRUNCATED: '模型回答被上界截断，未当作完整回答写入。',
+  MODEL_STREAM_REASON_UNKNOWN: '模型结束状态无法识别，这一轮不写入回答。',
+  MODEL_TOOL_CALL_ID_MISSING: '模型请求的工具没有调用编号，已拒绝。',
+  MODEL_TOOL_CALL_NAME_MISSING: '模型请求了一个没有名称的工具，已拒绝。',
+  MODEL_TOOL_CALL_ARGS_INVALID: '模型请求的工具参数不是合法 JSON，已拒绝。',
+})
+
+/** The closed request shape: nothing here names a session, a runtime or an identity. `conversationId` is the one trusted Host-supplied work-thread correlation the dispatch boundary injects; it is never a model field. */
+const REQUEST_FIELDS = Object.freeze(['botId', 'provider', 'model', 'messages', 'signal', 'system', 'tools', 'maxTokens', 'reasoningEffort', 'onText', 'conversationId'])
+
+/**
+ * @param {{
+ *   policy: { modelContext: Function },
+ *   directory: { forBot: (botId: string) => object },
+ *   lifecycle: { committedBot: (botId: string) => object | null },
+ *   serving: { assertMode: (botId: string, mode: string) => string },
+ *   authority: { assertModel: Function, assertTool: Function },
+ *   stream: (options: object, context: { botId: string, subject: object }) => AsyncIterable<object>,
+ *   readyFor?: (botId: string) => boolean,
+ * }} options
+ */
+export function createBotIndependentExecution({ policy, directory, lifecycle, serving, authority, stream, readyFor = () => true } = {}) {
+  if (!policy || typeof policy.modelContext !== 'function') throw new TypeError('INDEPENDENT_EXECUTION_REQUIRES_POLICY')
+  if (!directory || typeof directory.forBot !== 'function') throw new TypeError('INDEPENDENT_EXECUTION_REQUIRES_DIRECTORY')
+  if (!lifecycle || typeof lifecycle.committedBot !== 'function') throw new TypeError('INDEPENDENT_EXECUTION_REQUIRES_LIFECYCLE')
+  if (!serving || typeof serving.assertMode !== 'function') throw new TypeError('INDEPENDENT_EXECUTION_REQUIRES_SERVING')
+  if (!authority || typeof authority.assertModel !== 'function' || typeof authority.assertTool !== 'function') {
+    throw new TypeError('INDEPENDENT_EXECUTION_REQUIRES_AUTHORITY')
+  }
+  if (typeof stream !== 'function') throw new TypeError('INDEPENDENT_EXECUTION_REQUIRES_STREAM')
+  if (typeof readyFor !== 'function') throw new TypeError('INDEPENDENT_EXECUTION_REQUIRES_READINESS')
+
+  /**
+   * The committed Bot, or a refusal. A deleted Bot, a suspended lifecycle and an unhealthy Host
+   * are all "nobody can say", and none of them is the integration path.
+   */
+  const committed = botId => {
+    if (!idOk(botId)) fail('INVALID_BOT_ID')
+    const bot = lifecycle.committedBot(botId)
+    if (!bot) fail('BOT_NOT_COMMITTED', `无法确认 ${botId} 的已提交状态，本次请求被拒绝。`)
+    return bot
+  }
+
+  return Object.freeze({
+    /**
+     * The route this turn may ask for, read from the Bot's own committed record. A Bot with no
+     * saved model has no route: nothing here falls back to a global provider or a default model,
+     * and a Host whose model service cannot be reached refuses rather than guessing.
+     */
+    routeFor(botId) {
+      const bot = committed(botId)
+      const route = routeOf(bot.model)
+      if (!route) fail('BOT_MODEL_UNCOMMITTED', `无法确认 ${botId} 已保存的模型，本次请求被拒绝。`)
+      return route
+    },
+
+    /**
+     * Re-decide one independent turn before it writes anything: the committed runtime, the
+     * committed Bot, a live subject and the Bot's own grant for the model it saved. The loop calls
+     * this before every transcript write, every provider step and every tool call, so a Bot that
+     * was moved, deleted, revoked or stripped of its grant stops at the next checkpoint instead of
+     * finishing — or even writing a user message — on a state that no longer stands.
+     */
+    assertTurn(botId) {
+      serving.assertMode(botId, 'independent')
+      const bot = committed(botId)
+      const route = routeOf(bot.model)
+      if (!route) fail('BOT_MODEL_UNCOMMITTED', `无法确认 ${botId} 已保存的模型，本次请求被拒绝。`)
+      const subject = directory.forBot(botId)
+      // The grant is re-asserted here, not only when the model call later enters its own frame: an
+      // emptied grant must refuse before anything is written to the transcript.
+      authority.assertModel(subject, route.provider, route.model)
+      authority.assertTool(subject, 'model/infer')
+      if(readyFor(botId, route)!==true)fail('BOT_BINDING_UNAVAILABLE','此 Bot 尚未配置可用的默认执行绑定。')
+      return true
+    },
+
+    /**
+     * One model call for one independent turn, inside the Bot's own frame.
+     *
+     * The caller passes the route it resolved; this re-reads the committed record and refuses a
+     * mismatch, so the saved route identity of one request is never swapped mid-turn. The request
+     * shape is closed: a caller cannot open a new path to a session, a runtime or an identity
+     * through this trusted facade.
+     *
+     * @param {{ botId: string, provider: string, model: string, messages: object[], signal?: AbortSignal,
+     *   system?: unknown, tools?: unknown, maxTokens?: number, reasoningEffort?: string }} request
+     * @returns {Promise<{ text: string, toolCalls: object[], source: object }>}
+     */
+    async complete(request = {}) {
+      const { botId, provider, model, messages, signal, system, tools, maxTokens, reasoningEffort, onText, conversationId } = request
+      const extra = Object.keys(request).filter(key => !REQUEST_FIELDS.includes(key))
+      if (extra.length) fail('INDEPENDENT_REQUEST_UNKNOWN_FIELD', `本次请求带有不受支持的字段：${extra.join(', ')}`)
+      if (onText !== undefined && typeof onText !== 'function') fail('INDEPENDENT_PROGRESS_INVALID')
+      this.assertTurn(botId)
+      const bot = committed(botId)
+      const saved = routeOf(bot.model)
+      if (!saved || saved.provider !== provider || saved.model !== model) {
+        fail('BOT_MODEL_MISMATCH', `已保存模型与本次请求不一致：${botId} 当前为 ${bot.model ?? '未知'}，本次 ${provider}/${model} 被拒绝。`)
+      }
+      // The thinking level belongs to the same committed Bot choice as its
+      // route. Omitting it here used to silently select the adapter default,
+      // even when the owner had saved another level in the Bot's settings.
+      // The actual prepared SDK generation validates capability support; a
+      // stale level is refused before provider I/O, never silently replaced.
+      const effort = bot.effort
+      if (effort !== undefined && (typeof effort !== 'string' || !effort.trim())) fail('BOT_MODEL_EFFORT_INVALID')
+      if (reasoningEffort !== undefined && reasoningEffort !== effort) {
+        fail('BOT_MODEL_EFFORT_MISMATCH', '本次思考强度与 Bot 已保存的选择不一致，请先在 Bot 设置中保存。')
+      }
+      if (!Array.isArray(messages)) fail('BOT_TURN_MESSAGES_REQUIRED')
+      for (const message of messages) {
+        if (!message || !Array.isArray(message.content)) fail('BOT_TURN_MESSAGE_BLOCKS_REQUIRED')
+        if (message.role === 'assistant' && (message.source?.kind !== 'model' ||
+          typeof message.source.provider !== 'string' || !message.source.provider ||
+          typeof message.source.model !== 'string' || !message.source.model)) fail('BOT_TURN_MESSAGE_PROVENANCE_REQUIRED')
+      }
+      if (signal?.aborted) fail('BOT_LOOP_CANCELLED')
+      const subject = directory.forBot(botId)
+      const options = {
+        provider, model, messages: [independentSystemMessage(bot), ...messages],
+        ...(signal ? { signal } : {}),
+        ...(system === undefined ? {} : { system }),
+        ...(tools === undefined ? {} : { tools }),
+        ...(maxTokens === undefined ? {} : { maxTokens }),
+        ...(effort === undefined ? {} : { reasoningEffort: effort }),
+      }
+      // The whole call runs inside the frame, so the product's own model listener sees the
+      // committed Bot subject and the turn's cancel — one policy decision, one receipt. The
+      // turn's committed Bot and subject travel with the call so a Host-prepared stream can
+      // bind the exact adapter generation and admit against it; a plain stream ignores them.
+      return policy.modelContext(subject, signal, async () => {
+        const reply = await collectAnswer(stream(options, { botId, subject }), { onText })
+        // A stream that never finished, failed or asked for something unusable is not an answer:
+        // the loop writes nothing, and the receipt keeps the unknown outcome.
+        if (reply.failed) fail(reply.failed, REPLY_REFUSAL[reply.failed] ?? reply.failed)
+        // The route that produced this answer travels with it, so the next turn's request is a
+        // conversation the Host's own model service recognises and can replay.
+        return { text: reply.text, toolCalls: reply.toolCalls, source: { kind: 'model', provider, model } }
+      }, { botId, ...(typeof conversationId === 'string' ? { conversationId } : {}) })
+    },
+  })
+}

package/packages/orchestration/src/bot-independent-stream.mjs

@@ -0,0 +1,74 @@
+/**
+ * Read one Host model stream into the small reply shape the independent loop expects.
+ *
+ * The chunk vocabulary is the Host's own (`text-delta`, `tool-call-delta`, `usage`, `finish`), so
+ * an independent turn sees exactly what an integrated one sees. Two older spellings are accepted
+ * as well because a fixture or a narrow adapter may emit them; nothing else is invented.
+ *
+ * The outcome is read, not assumed: a stream that ends without a finish, or with an error or an
+ * abort, is reported as failed so the caller writes no answer. Usage is deliberately not read
+ * here — the one money authority observes it on the same stream.
+ */
+
+/**
+ * The Host's finish vocabulary. It is merge-extensible, so a kind this module has not been taught
+ * is a refusal rather than an answer: an outcome that cannot be read is not a completed turn.
+ */
+const FINISH_KINDS = Object.freeze({
+  stop: null,
+  'tool-calls': null,
+  'max-tokens': 'MODEL_STREAM_TRUNCATED',
+  aborted: 'MODEL_STREAM_ABORTED',
+  error: 'MODEL_STREAM_ERROR',
+})
+
+const finishFailed = reason => {
+  const kind = reason?.kind
+  if (typeof kind !== 'string' || !Object.hasOwn(FINISH_KINDS, kind)) return 'MODEL_STREAM_REASON_UNKNOWN'
+  return FINISH_KINDS[kind]
+}
+
+/**
+ * @param {AsyncIterable<object> | Iterable<object>} stream
+ * @returns {Promise<{ text: string, toolCalls: object[], failed: string | null }>}
+ */
+export async function collectAnswer(stream, { onText } = {}) {
+  let text = ''
+  const calls = new Map()
+  let finished = false
+  let failed = null
+  for await (const chunk of stream) {
+    if (typeof chunk === 'string') { text += chunk; if (onText) await onText(text); continue }
+    if (!chunk || typeof chunk !== 'object') continue
+    if (chunk.type === 'text-delta' || chunk.type === 'text' || chunk.type === 'delta') {
+      if (typeof chunk.text === 'string') { text += chunk.text; if (onText) await onText(text) }
+      continue
+    }
+    if (chunk.type === 'tool-call-delta') {
+      const id = typeof chunk.id === 'string' && chunk.id ? chunk.id : null
+      if (!id) { failed ??= 'MODEL_TOOL_CALL_ID_MISSING'; continue }
+      const call = calls.get(id) ?? { id, name: '', args: '' }
+      if (typeof chunk.name === 'string' && chunk.name) call.name = chunk.name
+      if (typeof chunk.argumentsDelta === 'string') call.args += chunk.argumentsDelta
+      calls.set(id, call)
+      continue
+    }
+    if (chunk.type === 'usage') continue
+    if (chunk.type === 'finish') {
+      finished = true
+      failed ??= finishFailed(chunk.reason)
+    }
+  }
+  if (!finished && failed === null) failed = 'MODEL_STREAM_UNFINISHED'
+  const toolCalls = []
+  for (const call of calls.values()) {
+    if (failed === null && !call.name) failed = 'MODEL_TOOL_CALL_NAME_MISSING'
+    let args = {}
+    if (call.args) {
+      try { args = JSON.parse(call.args) } catch { if (failed === null) failed = 'MODEL_TOOL_CALL_ARGS_INVALID' }
+    }
+    if (!args || typeof args !== 'object' || Array.isArray(args)) { if (failed === null) failed = 'MODEL_TOOL_CALL_ARGS_INVALID'; args = {} }
+    toolCalls.push({ id: call.id, name: call.name, args })
+  }
+  return { text, toolCalls, failed }
+}