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

package/packages/orchestration/src/bot-session-store.mjs

@@ -13,8 +13,10 @@
  * - Versioned: a store written by a newer schema is refused instead of guessed at.
  */
 
-import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { mkdirSync, readFileSync, renameSync, writeFileSync, openSync, closeSync, fsyncSync, unlinkSync } from 'node:fs'
 import { dirname, join } from 'node:path'
+import { createHash, randomUUID } from 'node:crypto'
+import { LEGACY_CONTEXT, MAX_CONTEXTS, contextIdOk, contextRequestOk, contextFields, contextView } from './independent-context-state.mjs'
 
 export const BOT_SESSION_SCHEMA = 1
 export const MAX_MESSAGES = 2_000
@@ -28,17 +30,33 @@ const text = value => (typeof value === 'string' ? value : '')
 const idOk = value => typeof value === 'string' && /^[A-Za-z0-9_.-]{1,128}$/.test(value)
 
 function emptySession(botId, now) {
-  return { schemaVersion: BOT_SESSION_SCHEMA, botId, createdAt: now, updatedAt: now, turns: 0, messages: [], truncated: false }
+  return { schemaVersion: BOT_SESSION_SCHEMA, botId, createdAt: now, updatedAt: now, turns: 0, messages: [], truncated: false,
+    ...contextFields({ createdAt: 0 }) }
 }
 
 function bounded(message) {
   const content = text(message.content)
+  const model = message.modelSource
+  if (model !== undefined && (!model || model.kind !== 'model' ||
+    ![model.provider, model.model].every(value => typeof value === 'string' && value.length > 0 && value.length <= 256 && !/[\x00-\x1f]/.test(value)))) fail('INVALID_BOT_MESSAGE_SOURCE')
+  if (message.toolCallId !== undefined && (typeof message.toolCallId !== 'string' || !message.toolCallId || message.toolCallId.length > 256)) fail('INVALID_BOT_TOOL_CALL_ID')
+  const calls = message.toolCalls
+  if (calls !== undefined && (!Array.isArray(calls) || calls.length > 8 || calls.some(call =>
+    !call || typeof call.id !== 'string' || !call.id || call.id.length > 256 || typeof call.name !== 'string' || !call.name || call.name.length > 128 ||
+    !call.args || typeof call.args !== 'object' || Array.isArray(call.args) || JSON.stringify(call.args).length > MAX_MESSAGE_CHARS) ||
+    new Set(calls.map(call => call.id)).size !== calls.length)) fail('INVALID_BOT_TOOL_CALLS')
   return {
+    contextId: message.contextId ?? LEGACY_CONTEXT,
     role: ROLES.includes(message.role) ? message.role : 'user',
     content: content.length > MAX_MESSAGE_CHARS ? `${content.slice(0, MAX_MESSAGE_CHARS)}\n[truncated]` : content,
     at: Number.isSafeInteger(message.at) ? message.at : 0,
     ...(typeof message.name === 'string' && message.name ? { name: message.name.slice(0, 128) } : {}),
     ...(message.toolCall ? { toolCall: message.toolCall } : {}),
+    ...(typeof message.messageId === 'string' && message.messageId ? { messageId: message.messageId.slice(0, 256) } : {}),
+    ...(model ? { modelSource: { kind: 'model', provider: model.provider, model: model.model } } : {}),
+    ...(calls ? { toolCalls: structuredClone(calls) } : {}),
+    ...(message.toolCallId ? { toolCallId: message.toolCallId } : {}),
+    ...(message.isError === true ? { isError: true } : {}),
   }
 }
 
@@ -48,6 +66,7 @@ export function parseSession(value, botId) {
   if (value.schemaVersion !== BOT_SESSION_SCHEMA) fail(value.schemaVersion > BOT_SESSION_SCHEMA ? 'BOT_SESSION_SCHEMA_NEWER' : 'INVALID_BOT_SESSION')
   if (value.botId !== botId) fail('BOT_SESSION_MISMATCH')
   if (!Array.isArray(value.messages)) fail('INVALID_BOT_SESSION')
+  if (value.messages.some(message => message.contextId !== undefined && !contextIdOk(message.contextId))) fail('INVALID_BOT_CONTEXT')
   return {
     schemaVersion: BOT_SESSION_SCHEMA,
     botId,
@@ -55,7 +74,9 @@ export function parseSession(value, botId) {
     updatedAt: Number.isSafeInteger(value.updatedAt) ? value.updatedAt : 0,
     turns: Number.isSafeInteger(value.turns) && value.turns >= 0 ? value.turns : 0,
     truncated: value.truncated === true,
-    messages: value.messages.map(bounded),
+    ...contextFields(value),
+    messages: value.messages.map((message, index) => bounded({ ...message,
+      messageId: message.messageId ?? `legacy-${createHash('sha256').update(JSON.stringify([botId, index, message])).digest('hex')}` })),
   }
 }
 
@@ -79,10 +100,32 @@ export function openBotSessionStore({ dir, now = Date.now, maxMessages = MAX_MES
   const write = session => {
     mkdirSync(dirname(fileOf(session.botId)), { recursive: true })
     const target = fileOf(session.botId)
-    const temp = `${target}.${process.pid}.tmp`
-    writeFileSync(temp, JSON.stringify(session))
-    renameSync(temp, target)
-    return session
+    const temp = `${target}.${process.pid}.${randomUUID()}.tmp`
+    let descriptor, renamed = false
+    try {
+      descriptor = openSync(temp, 'wx', 0o600)
+      writeFileSync(descriptor, JSON.stringify(session)); fsyncSync(descriptor)
+      closeSync(descriptor); descriptor = undefined
+      renameSync(temp, target); renamed = true
+      const verified = read(session.botId)
+      if (JSON.stringify(verified) !== JSON.stringify(parseSession(session, session.botId))) fail('BOT_SESSION_WRITE_NOT_CONFIRMED')
+      return verified
+    } catch (error) {
+      // Do not overwrite a possibly committed file with an old snapshot.
+      error.outcome = renamed ? 'unknown' : 'refused'
+      throw error
+    } finally { if (descriptor !== undefined) closeSync(descriptor) }
+  }
+  // Exclusive filesystem admission covers the read-modify-rename in every process.
+  // A stale lock is refused; guessing that its owner died could overwrite a live writer.
+  const mutate = (botId, change) => {
+    const target = fileOf(botId)
+    mkdirSync(dirname(target), { recursive: true })
+    let lock
+    try { lock = openSync(`${target}.lock`, 'wx', 0o600) }
+    catch (error) { if (error.code === 'EEXIST') fail('BOT_SESSION_WRITE_BUSY'); throw error }
+    try { return change(read(botId)) }
+    finally { closeSync(lock); unlinkSync(`${target}.lock`) }
   }
 
   return Object.freeze({
@@ -93,8 +136,12 @@ export function openBotSessionStore({ dir, now = Date.now, maxMessages = MAX_MES
     /** Append messages and advance the turn counter atomically. */
     append(botId, messages, { turn = false } = {}) {
       if (!Array.isArray(messages) || messages.length === 0) fail('INVALID_BOT_SESSION_APPEND')
-      const session = read(botId)
-      for (const message of messages) session.messages.push(bounded({ ...message, at: Number.isSafeInteger(message.at) ? message.at : now() }))
+      return mutate(botId, session => {
+      if (session.contextReset) fail('INDEPENDENT_CONTEXT_PENDING_RECONCILIATION')
+      for (const message of messages) session.messages.push(bounded({ ...message,
+        contextId: session.contextId,
+        ...(!message.messageId ? { messageId: randomUUID() } : {}),
+        at: Number.isSafeInteger(message.at) ? message.at : now() }))
       if (session.messages.length > maxMessages) {
         session.messages.splice(0, session.messages.length - maxMessages)
         session.truncated = true
@@ -102,6 +149,55 @@ export function openBotSessionStore({ dir, now = Date.now, maxMessages = MAX_MES
       if (turn) session.turns += 1
       session.updatedAt = now()
       return write(session)
+      })
+    },
+    contextOf: botId => contextView(read(botId)),
+    beginContext(botId, { requestKey, contextId, expectedContextId } = {}) {
+      if (!contextRequestOk(requestKey) || !contextIdOk(contextId)) fail('INVALID_BOT_CONTEXT_RESET')
+      return mutate(botId, session => {
+        const existing = session.contexts.find(row => row.requestKey === requestKey)
+        if (existing) {
+          if (existing.contextId !== contextId) fail('INDEPENDENT_CONTEXT_REQUEST_CONFLICT')
+          return session
+        }
+        if (session.contextReset) fail('INDEPENDENT_CONTEXT_PENDING_RECONCILIATION')
+        if (contextId === session.contextId || session.messages.some(row => row.contextId === contextId)) fail('INDEPENDENT_CONTEXT_REQUEST_CONFLICT')
+        if (expectedContextId !== undefined && session.contextId !== expectedContextId) fail('INDEPENDENT_CONTEXT_STALE')
+        session.contextReset = { requestKey, contextId, previousContextId: session.contextId, createdAt: now() }
+        session.updatedAt = now()
+        return write(session)
+      })
+    },
+    commitContext(botId, { requestKey, contextId } = {}) {
+      return mutate(botId, session => {
+        const existing = session.contexts.find(row => row.requestKey === requestKey)
+        if (existing) {
+          if (existing.contextId !== contextId) fail('INDEPENDENT_CONTEXT_REQUEST_CONFLICT')
+          return session
+        }
+        const intent = session.contextReset
+        if (!intent || intent.requestKey !== requestKey || intent.contextId !== contextId) fail('INDEPENDENT_CONTEXT_REQUEST_CONFLICT')
+        const sequence = Math.max(...session.contexts.map(row => row.sequence)) + 1
+        if (!Number.isSafeInteger(sequence)) fail('INDEPENDENT_CONTEXT_HISTORY_LIMIT')
+        session.contexts.push({ ...intent, sequence, createdAt: now() })
+        if (session.contexts.length > MAX_CONTEXTS) { session.contexts = session.contexts.slice(-MAX_CONTEXTS); session.contextsTruncated = true }
+        session.contextId = contextId
+        delete session.contextReset
+        session.updatedAt = now()
+        return write(session)
+      })
+    },
+    abortContext(botId, { requestKey, contextId } = {}) {
+      return mutate(botId, session => {
+        if (!session.contextReset || session.contextReset.requestKey !== requestKey || session.contextReset.contextId !== contextId) fail('INDEPENDENT_CONTEXT_REQUEST_CONFLICT')
+        delete session.contextReset
+        session.updatedAt = now()
+        return write(session)
+      })
+    },
+    contextCommitted(botId, requestKey, contextId) {
+      const session = read(botId)
+      return session.contexts.some(row => row.requestKey === requestKey && row.contextId === contextId)
     },
     /** Forget one Bot's transcript (used when a Bot is deleted, never on a transient error). */
     remove(botId) {

package/packages/orchestration/src/bot-settings.mjs

@@ -2,6 +2,7 @@ import { createHash } from 'node:crypto'
 import { mkdirSync } from 'node:fs'
 import { dirname, resolve } from 'node:path'
 import { OFFICIAL_TOOLS } from '../../../.dsh-plugin/shared/official-tool-registry.mjs'
+import { fundingForMainRoute, materializeMainRouteDefault, normalizeMainModelRoutes, preserveMainModelRoutes } from './main-model-routes.mjs'
 
 export const BOT_SETTINGS_SCHEMA = 1
 export const BOT_EXECUTION_MODES = Object.freeze(['read-only', 'workspace-write', 'cli-native'])
@@ -36,7 +37,7 @@ export function defaultBotSettings() {
 
 /** Closed stored schema. No executable paths, installer URLs, credentials or arbitrary roots. */
 export function normalizeBotSettings(input) {
-  keys(input, ['schemaVersion', 'enabled', 'model', 'officialTools', 'machineGrants', 'capabilities', 'workspaceRef', 'funding', 'maxConcurrentTasks', 'routing'], 'settings')
+  keys(input, ['schemaVersion', 'enabled', 'model', 'officialTools', 'machineGrants', 'capabilities', 'workspaceRef', 'funding', 'maxConcurrentTasks', 'routing', 'mainRoutes'], 'settings')
   const value = { ...defaultBotSettings(), ...input }
   if (value.schemaVersion !== 1) fail('BOT_SETTINGS_VERSION_UNSUPPORTED', 'Bot 绑定版本不受支持，请升级宿主。')
   if (typeof value.enabled !== 'boolean') fail('BOT_SETTINGS_INVALID', 'enabled 必须是布尔值。', { field: 'enabled' })
@@ -82,8 +83,16 @@ export function normalizeBotSettings(input) {
     if (!['local', 'remote'].includes(value.workspaceRef.kind) || !ref(value.workspaceRef.machineId) || !ref(value.workspaceRef.rootId)) fail('BOT_SETTINGS_INVALID', '工作区必须引用已登记机器和根目录。', { field: 'workspaceRef' })
     value.workspaceRef = { kind: value.workspaceRef.kind, machineId: value.workspaceRef.machineId, rootId: value.workspaceRef.rootId }
   }
-  keys(value.funding, ['mode', 'scopeId', 'pricing', 'request', 'dailyBudgetUsd', 'monthlyBudgetUsd', 'subscription'], 'funding')
-  const funding = { ...defaultBotSettings().funding, ...value.funding }
+  value.funding = normalizeFunding(value.funding)
+  if (Object.hasOwn(input, 'mainRoutes')) value.mainRoutes = normalizeMainModelRoutes(input.mainRoutes, { normalizeFunding })
+  if (!Number.isSafeInteger(value.maxConcurrentTasks) || value.maxConcurrentTasks < 1 || value.maxConcurrentTasks > 32) fail('BOT_SETTINGS_INVALID', '最大并发任务数必须为 1 至 32。', { field: 'maxConcurrentTasks' })
+  json(value)
+  return clone(value)
+}
+
+function normalizeFunding(input) {
+  keys(input, ['mode', 'scopeId', 'pricing', 'request', 'dailyBudgetUsd', 'monthlyBudgetUsd', 'subscription'], 'funding')
+  const funding = { ...defaultBotSettings().funding, ...input }
   if (!['api', 'subscription'].includes(funding.mode) || (funding.scopeId !== null && !ref(funding.scopeId))) fail('BOT_SETTINGS_INVALID', '请选择目录中的 API 或订阅资金范围。', { field: 'funding' })
   if (funding.pricing !== null) {
     keys(funding.pricing, ['input', 'output', 'cacheRead', 'cacheWrite'], 'funding.pricing')
@@ -101,17 +110,18 @@ export function normalizeBotSettings(input) {
     funding.subscription = { dailyCalls: count(funding.subscription.dailyCalls, 'funding.subscription.dailyCalls'), monthlyCalls: count(funding.subscription.monthlyCalls, 'funding.subscription.monthlyCalls') }
   }
   if (funding.mode === 'api' && funding.subscription !== null) fail('BOT_SETTINGS_INVALID', 'API 资金不能携带订阅次数；不会隐式切换执行渠道。', { field: 'funding.subscription' })
-  value.funding = funding
-  if (!Number.isSafeInteger(value.maxConcurrentTasks) || value.maxConcurrentTasks < 1 || value.maxConcurrentTasks > 32) fail('BOT_SETTINGS_INVALID', '最大并发任务数必须为 1 至 32。', { field: 'maxConcurrentTasks' })
-  json(value)
-  return clone(value)
+  return funding
 }
 
 function catalogOf(input) {
   if (!plain(input)) fail('BOT_SETTINGS_CATALOG_UNAVAILABLE', '宿主尚未提供可信模型、机器和资金目录。')
   const models = list(input.models ?? [], 4096, 'catalog.models').map(item => {
     if (!token(item.provider) || !token(item.model)) fail('BOT_SETTINGS_CATALOG_INVALID', '宿主模型目录无效。')
+    if (item.fundingModes !== undefined && (!Array.isArray(item.fundingModes) || !item.fundingModes.length || item.fundingModes.length > 2
+      || item.fundingModes.some(mode => !['api', 'subscription'].includes(mode)) || new Set(item.fundingModes).size !== item.fundingModes.length)) fail('BOT_SETTINGS_CATALOG_INVALID', '宿主模型资金渠道目录无效。')
     return { provider: item.provider, model: item.model, label: String(item.label ?? item.model).slice(0, 256),
+      ...(item.fundingModes === undefined ? {} : { fundingModes: [...item.fundingModes] }),
+      ...(item.pricing === undefined ? {} : { pricing: normalizeFunding({ pricing: item.pricing }).pricing }),
       cliModels: (item.cliModels ?? []).filter(mapping => registry.has(mapping.toolId) && token(mapping.model)).map(mapping => ({ toolId: mapping.toolId, model: mapping.model })) }
   })
   unique(models.map(routeRef), 'catalog.models')
@@ -152,6 +162,7 @@ export function validateBotSettings(input, catalogInput) {
   const denied = (message, field) => fail('BOT_SETTINGS_SCOPE_DENIED', message, { field })
   const model = settings.model && catalog.models.find(item => routeRef(item) === routeRef(settings.model))
   if (settings.model && !model) denied('此准确模型已不在宿主目录，请刷新后重新选择。', 'model')
+  if (model?.fundingModes && !model.fundingModes.includes(settings.funding.mode)) denied('此模型不支持所选资金渠道，请选择宿主列出的渠道。', 'funding.mode')
   for (const tool of settings.officialTools) {
     const entry = catalog.tools.find(item => item.toolId === tool.toolId)
     if (!entry?.modes.includes(tool.mode)) denied(`${tool.toolId} 尚未获准使用该执行模式。`, 'officialTools')
@@ -187,10 +198,20 @@ function compiledGrant(settings, catalog) {
   return { tools: [...new Set(tools)].sort(), modelRoutes: [{ ...settings.model }] }
 }
 
+export function checkMainRouteFunding(route, funding, catalog) {
+  const model = catalog.models.find(item => item.provider === route.provider && item.model === route.model)
+  const scope = catalog.fundingScopes.find(item => item.id === funding?.scopeId)
+  if (!funding || !model || (model.fundingModes && !model.fundingModes.includes(funding.mode))
+    || !scope?.modes.includes(funding.mode) || (scope.models && !scope.models.some(item => item.provider === route.provider && item.model === route.model))) {
+    fail('MAIN_ROUTE_FUNDING_UNAVAILABLE', '此路线缺少可用模型、资金范围、渠道或完整限额。', { field: 'mainRoutes', route: routeRef(route) })
+  }
+  return funding
+}
+
 /** Isolated component tables, safe to colocate with other SQLite components. */
-export function openBotSettings({ Database, file, catalogFor = () => ({}), botExists = () => false, onCommitted = () => {}, onSuspended = () => {}, now = Date.now }) {
+export function openBotSettings({ Database, file, catalogFor = () => ({}), botExists = () => false, isMainBot = () => false, onCommitted = () => {}, onSuspended = () => {}, now = Date.now }) {
   if (typeof Database !== 'function' || typeof file !== 'string' || !file) throw new TypeError('Database constructor and explicit file are required')
-  for (const [name, callback] of Object.entries({ catalogFor, botExists, onCommitted, onSuspended })) if (typeof callback !== 'function') throw new TypeError(`${name} must be a function`)
+  for (const [name, callback] of Object.entries({ catalogFor, botExists, isMainBot, onCommitted, onSuspended })) if (typeof callback !== 'function') throw new TypeError(`${name} must be a function`)
   if (file !== ':memory:') { file = resolve(file); mkdirSync(dirname(file), { recursive: true }) }
   const db = new Database(file)
   try {
@@ -288,8 +309,26 @@ export function openBotSettings({ Database, file, catalogFor = () => ({}), botEx
       const botId = botIdOf(request.botId)
       if (!Number.isSafeInteger(request.expectedRevision) || request.expectedRevision < 0) fail('BOT_SETTINGS_INVALID', 'expectedRevision 必须是当前绑定修订号。')
       if (!sync(botExists(botId), 'botExists')) fail('BOT_SETTINGS_UNKNOWN_BOT', '此 Bot 不在已提交的宿主目录。')
-      const normalized=normalizeBotSettings(request.settings)
-      const settings=normalized.enabled?validateBotSettings(normalized,sync(catalogFor(botId),'catalogFor')).settings:normalized
+      const previous = load(botId).settings
+      const incoming = normalizeBotSettings(request.settings)
+      const main = sync(isMainBot(botId), 'isMainBot') === true
+      if (!main && Object.hasOwn(incoming, 'mainRoutes') && json(incoming.mainRoutes) !== json(previous.mainRoutes ?? null)) {
+        fail('MAIN_ROUTES_ROLE_REQUIRED', '只有已提交的 Main Bot 可以修改多路线配置。')
+      }
+      let normalized = main ? preserveMainModelRoutes(incoming, previous) : incoming
+      if (!main && Object.hasOwn(previous, 'mainRoutes')) normalized.mainRoutes = previous.mainRoutes
+      const needsCatalog = normalized.enabled || (main && normalized.mainRoutes)
+      const hostCatalog = needsCatalog ? sync(catalogFor(botId), 'catalogFor') : null
+      if (main && normalized.mainRoutes) {
+        const catalog = catalogOf(hostCatalog)
+        for (const route of normalized.mainRoutes.routes) {
+          const known = catalog.models.find(item => item.provider === route.provider && item.model === route.model)
+          if (route.funding.mode === 'api' && route.funding.pricing === null && known?.pricing) route.funding.pricing = clone(known.pricing)
+          if (route.enabled) checkMainRouteFunding(route, fundingForMainRoute(normalized.mainRoutes, route), catalog)
+        }
+        normalized = materializeMainRouteDefault(normalized, { normalizeFunding })
+      }
+      const settings = normalized.enabled ? validateBotSettings(normalized, hostCatalog).settings : normalized
       return commit(botId, request.expectedRevision, settings)
     },
     refresh() {

package/packages/orchestration/src/bot-thread-admission.mjs

@@ -0,0 +1,84 @@
+/**
+ * Which model calls belong to a Bot thread, decided before anything else runs.
+ *
+ * The runtime's live owner index is a fast answer that goes stale the moment a thread is
+ * archived, a Bot is suspended or deleted, or a Bot is moved to the other runtime: an archived
+ * thread's Session leaves `chatOwners`, so the ordinary Harness bypass would answer for it as if
+ * it were the user's own chat — unguarded, unpoliced and unaccounted. The thread catalog is the
+ * record that survives all of that, and its gate is the one the send path already uses.
+ *
+ * So this guard asks the catalog first, for the exact Bot/thread/session triple, and only then
+ * the frozen runtime. Three outcomes, and only three:
+ *
+ * - `thread`: a committed Bot thread. The gate has just re-confirmed the Bot is committed and
+ *   healthy, its grant still stands, the thread is open, and the Host still owns the Session.
+ * - `unbound`: nothing claims this Session. An ordinary Harness session — the user's own chat,
+ *   another plugin — stays exactly as unguarded as it was.
+ * - a refusal: the Session is claimed but the claim does not stand. Nothing is replayed, and no
+ *   identity is invented: a doubt about a thread never becomes Main, the owner, or a default
+ *   Session.
+ *
+ * A Session the frozen runtime reports as a live thread while the catalog has no record for it
+ * is a refusal too. The catalog is the record; the runtime's index is the hint.
+ */
+
+const fail = (code, message) => {
+  const error = new Error(message ?? code)
+  error.code = code
+  error.outcome = 'refused'
+  throw error
+}
+
+const safe = work => { try { return work() } catch { return null } }
+
+/**
+ * @param {{
+ *   threads?: object | (() => object | null) | null,
+ *   nativeThreadOf?: ((sessionId: string) => { botId: string, threadId: string } | null | undefined) | null,
+ * }} options
+ */
+export function createBotThreadAdmission({ threads = null, nativeThreadOf = null } = {}) {
+  // The thread host is built after the product runtime, so the resolver is allowed to be lazy:
+  // the guard asks for it on every call rather than capturing a half-composed Host.
+  const host = () => {
+    const value = typeof threads === 'function' ? safe(() => threads()) : threads
+    // Either the thread host itself or its catalog: both are the same committed record.
+    const catalog = value?.service && typeof value.service === 'object' ? value.service : value
+    return catalog && typeof catalog.threadBySession === 'function' && typeof catalog.assertSendable === 'function' ? catalog : null
+  }
+  const nativeThread = sessionId => (typeof nativeThreadOf === 'function' ? safe(() => nativeThreadOf(sessionId)) : null) ?? null
+
+  /**
+   * @param {string | undefined | null} sessionId
+   * @returns {{ kind: 'absent' | 'unbound' } | { kind: 'thread', botId: string, threadId: string, sessionId: string }}
+   */
+  const admit = sessionId => {
+    if (typeof sessionId !== 'string' || sessionId === '') return { kind: 'absent' }
+    const service = host()
+    const live = nativeThread(sessionId)
+    if (!service) {
+      // No catalog to ask. A Session the runtime still calls a live Bot thread is refused rather
+      // than handed to the ordinary bypass, which would answer for a Bot with no Bot policy.
+      if (live) fail('BOT_THREAD_ADMISSION_UNAVAILABLE', '线程会话服务未就绪，宿主无法确认该会话归属，本次请求被拒绝。')
+      return { kind: 'unbound' }
+    }
+    // A catalog that cannot be read is a doubt, not an answer: it may hold the very tombstoned
+    // identity this call belongs to, so the failure propagates instead of reading as "unbound".
+    const found = service.threadBySession(sessionId) ?? null
+    if (found && typeof found.botId === 'string' && typeof found.threadId === 'string') {
+      // The exact triple, re-confirmed now: archive, revocation, a deleted Bot, a moved runtime
+      // and a Session the Host no longer owns all refuse here.
+      const gate = service.assertSendable({ botId: found.botId, threadId: found.threadId })
+      // And the Session the gate answered for is the one that was asked about: a record that
+      // resolved to some other Session is a refusal, never a silent substitution.
+      if (gate?.sessionId !== sessionId) {
+        fail('THREAD_SESSION_CONFLICT', '该线程会话与请求的会话不一致，本次请求被拒绝。')
+      }
+      return { kind: 'thread', botId: found.botId, threadId: found.threadId, sessionId, grantVerified: gate?.grantVerified === true }
+    }
+    if (live) fail('BOT_THREAD_UNVERIFIED', '该会话是一条 Bot 线程会话，但线程目录没有它的记录，本次请求被拒绝。')
+    return { kind: 'unbound' }
+  }
+
+  return Object.freeze({ admit })
+}

package/packages/orchestration/src/bot-thread-host.mjs

@@ -0,0 +1,187 @@
+import { createBotThreads } from './bot-threads.mjs'
+
+// The seam between the thread catalog and the real Host. Everything the catalog
+// needs to know about authority is asked here, of services the product already
+// owns: the frozen runtime's thread records, the lifecycle's committed Bots, the
+// principal directory and the capability authority. Nothing is reimplemented,
+// and nothing the Host does not confirm is treated as confirmed.
+//
+// The adapter also reports which Host hooks exist. A Host that has not applied
+// the thread records (an older overlay, or a build without them) says so here,
+// so the composition can surface `blocked` with the missing hook instead of a
+// surface that looks wired and is not.
+
+/**
+ * @param {{
+ *   rt: object,                 // the product runtime (createBotProduct().rt)
+ *   lifecycle: object,          // attachDsLifecycle()
+ *   authority: object,          // capability-broker authority
+ *   directory: object,          // principal directory (principals.mjs)
+ *   file: string,               // where the catalog lives, beside the Host's own state
+ *   runtimeMode?: (botId: string) => string | null,
+ *   now?: () => number,
+ * }} options
+ */
+export function createBotThreadHost({ rt, lifecycle, authority, directory, file, runtimeMode = null, now = Date.now } = {}) {
+  if (!rt || typeof rt !== 'object') throw new TypeError('BOT_THREAD_HOST_RUNTIME_REQUIRED')
+  if (!lifecycle || typeof lifecycle !== 'object') throw new TypeError('BOT_THREAD_HOST_LIFECYCLE_REQUIRED')
+  if (!authority || typeof authority !== 'object') throw new TypeError('BOT_THREAD_HOST_AUTHORITY_REQUIRED')
+  if (!directory || typeof directory !== 'object') throw new TypeError('BOT_THREAD_HOST_DIRECTORY_REQUIRED')
+  if (typeof file !== 'string' || file === '') throw new TypeError('BOT_THREAD_HOST_FILE_REQUIRED')
+
+  // Which trusted hooks this Host actually has. `ready` is the honest gate for
+  // offering a send at all: without the runtime record and the ownership
+  // lookup, a thread Session could be made but never authorized.
+  const hooks = Object.freeze({
+    createSession: typeof rt.createSession === 'function',
+    addThreadSession: typeof rt.addThreadSession === 'function',
+    setThreadArchived: typeof rt.setThreadArchived === 'function',
+    renameThread: typeof rt.renameThread === 'function',
+    threadOf: typeof rt.threadOf === 'function',
+    threadsOf: typeof rt.threadsOf === 'function',
+    committedBot: typeof lifecycle.committedBot === 'function',
+    lifecycleStatus: typeof lifecycle.status === 'function',
+    forSession: typeof directory.forSession === 'function',
+    forBot: typeof directory.forBot === 'function',
+    describe: typeof authority.describe === 'function',
+    assertTool: typeof authority.assertTool === 'function',
+  })
+  const ready = hooks.createSession && hooks.addThreadSession && hooks.committedBot && hooks.forSession && hooks.describe
+
+  const committedBot = botId => (hooks.committedBot ? lifecycle.committedBot(botId) ?? null : null)
+  const lifecycleStatus = () => (hooks.lifecycleStatus ? lifecycle.status() ?? null : null)
+
+  // The Host's own record of a Bot's threads: identity and archive, read back
+  // from committed state. This is what a restart settles an interrupted create
+  // against, so it is read from the lifecycle, never from this process.
+  const committedThreads = botId => {
+    const bot = committedBot(botId)
+    if (!Array.isArray(bot?.threads)) return []
+    return bot.threads
+      .filter(thread => thread && typeof thread.threadId === 'string' && typeof thread.sessionId === 'string')
+      .map(thread => ({ threadId: thread.threadId, sessionId: thread.sessionId, archivedAt: thread.archivedAt ?? null }))
+  }
+
+  // The principal directory is the Host's persistent confirmation of who a
+  // Session belongs to. It is asked before any policy runs, every time.
+  const ownsSession = (botId, sessionId) => {
+    if (!hooks.forSession || !hooks.describe) return false
+    try { return authority.describe(directory.forSession(sessionId)).botId === botId } catch { return false }
+  }
+
+  // A suspended or disabled Bot has an empty committed grant. The authority
+  // says so through the one assertion a send always needs; a doubt is reported
+  // as unanswerable rather than assumed.
+  const botAuthorized = botId => {
+    if (!hooks.forBot || !hooks.assertTool) return null
+    try {
+      const subject = directory.forBot(botId)
+      authority.assertTool(subject, 'model/infer')
+      return true
+    } catch (error) {
+      return error?.code === 'TOOL_DENIED' || error?.code === 'SUBJECT_REVOKED' ? false : null
+    }
+  }
+
+  // Makes a thread's Session through the same factory every own chat uses, and
+  // records it in the Bot's committed state in one save — the write that makes
+  // the lifecycle compile the Session into this Bot's ownership. A refusal the
+  // Host names before any Session exists is reported as such, so the catalog
+  // does not keep a create intent for an operation that never started.
+  const createSession = async ({ botId, threadId, title, dir }) => {
+    if (!hooks.createSession) {
+      throw Object.assign(new Error('宿主运行时未提供会话工厂。'), { code: 'SESSION_FACTORY_REQUIRED', outcome: 'refused' })
+    }
+    const readOnly = typeof rt.readOnly === 'function' ? rt.readOnly() : undefined
+    if (readOnly !== undefined) throw Object.assign(new Error(readOnly), { code: 'PRODUCT_READ_ONLY', outcome: 'refused' })
+    const sessionId = await rt.createSession(title, { dir })
+    if (!hooks.addThreadSession) {
+      throw Object.assign(new Error('宿主运行时未提供线程会话记录（rt.addThreadSession）。'), { code: 'SESSION_HOST_HOOK_MISSING', outcome: 'refused' })
+    }
+    await rt.addThreadSession(botId, threadId, sessionId, { name: title })
+    return sessionId
+  }
+
+  // Archive is the Host's fact: dropping a thread's authority happens in the
+  // committed state, and only then in the catalog.
+  const setThreadArchived = async ({ botId, threadId, archivedAt }) => {
+    if (!hooks.setThreadArchived) return null
+    return rt.setThreadArchived(botId, threadId, archivedAt)
+  }
+
+  // A thread's title is the Host's too: the rename lands in the committed state
+  // and answers with the record it wrote, which the catalog checks before it
+  // believes the rename happened.
+  const renameThread = async ({ botId, threadId, name }) => {
+    if (!hooks.renameThread) return null
+    return rt.renameThread(botId, threadId, name)
+  }
+
+  const service = createBotThreads({
+    file,
+    committedBot,
+    lifecycleStatus,
+    botAuthorized,
+    ownsSession,
+    committedThreads,
+    createSession,
+    setThreadArchived,
+    renameThread,
+    // No public Host session-inspect exists yet: reconcile then reports every
+    // unowned Session as 'unbound' rather than 'missing'.
+    inspectSession: null,
+    runtimeMode: typeof runtimeMode === 'function' ? runtimeMode : null,
+    now,
+  })
+
+  // The owner-console handlers. Each takes the RPC payload as a closed field
+  // set (the catalog refuses anything else) and returns JSON-safe state; the
+  // composition wraps every one of them in ownerOnly.
+  const actions = Object.freeze({
+    'threads.readModel': payload => service.readModel(payload ?? {}),
+    'threads.list': payload => service.list(payload?.botId),
+    'threads.create': payload => service.create(payload ?? {}),
+    'threads.rename': payload => service.rename(payload ?? {}),
+    'threads.switch': payload => service.switchThread(payload ?? {}),
+    'threads.open': payload => service.openThread(payload ?? {}),
+    'threads.archive': payload => service.archive(payload ?? {}),
+    'threads.unarchive': payload => service.unarchive(payload ?? {}),
+    'threads.ensure': payload => service.ensureSession(payload ?? {}),
+    'threads.recover': payload => service.recover(payload ?? {}),
+    'threads.reconcile': () => service.reconcile(),
+  })
+
+  /**
+   * The gate a real send runs under, before any model or tool call. It answers
+   * with the Session the turn must use, or refuses with the reason.
+   *
+   * `create` defaults to false: dispatching a model request is not a request to
+   * make a Session. A caller that means "write in this thread" says so, and
+   * only a thread that has never had a Session — no id, no durable create
+   * intent, no outcome the Host failed to confirm — is given one, exactly once,
+   * through the same single-flight ensure every other path uses. Every other
+   * refusal is handed back untouched: an unknown, unbound, revoked, archived,
+   * foreign or moved-away thread is never quietly given a fresh identity.
+   */
+  const sendGate = async ({ botId, threadId, create = false } = {}) => {
+    const gate = service.probeSendable({ botId, threadId })
+    if (gate.ok) return gate
+    if (create !== true) return gate
+    // The one path that may make a Session: never created, and never attempted.
+    if (gate.code !== 'SESSION_MISSING' || gate.sessionState !== 'none') return gate
+    await service.ensureSession({ botId, threadId })
+    return service.probeSendable({ botId, threadId })
+  }
+
+  return Object.freeze({
+    service,
+    actions,
+    hooks,
+    ready,
+    sendGate,
+    ownsSession,
+    committedThreads,
+    botAuthorized,
+    close: () => service.close(),
+  })
+}