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

package/packages/orchestration/src/independent-chat-service.mjs

@@ -0,0 +1,308 @@
+import { createHash, randomUUID } from 'node:crypto'
+import { mkdirSync } from 'node:fs'
+import { dirname } from 'node:path'
+import { independentContextId } from './independent-context-state.mjs'
+
+const fail = code => { throw Object.assign(new Error(code), { code }) }
+const ref = value => typeof value === 'string' && /^[-A-Za-z0-9_.]{1,128}$/.test(value)
+const requestRef = value => typeof value === 'string' && /^[-A-Za-z0-9_]{16,128}$/.test(value)
+const plain = value => value && typeof value === 'object' && !Array.isArray(value)
+const owner = context => { if (context?.kind !== 'owner') fail('REMOTE_OWNER_REQUIRED') }
+const keys = (value, allowed) => { if (!plain(value) || Object.keys(value).some(key => !allowed.includes(key))) fail('INDEPENDENT_CHAT_INVALID_REQUEST') }
+const hash = input => createHash('sha256').update(input).digest('hex')
+const alive = pid => {
+  try { process.kill(pid, 0); return true } catch (error) { return error.code !== 'ESRCH' }
+}
+
+/**
+ * Owner chat admission and durable request outcomes, not a second money ledger.
+ * A transport retry reads the original request. It never starts another model
+ * turn, including after restart or an unknown result. Actual messages remain in
+ * the Bot transcript; this journal retains only bounded outcome summaries.
+ */
+export function createIndependentChatService({ Database, file, lifecycle, runtime, now = Date.now,
+  maxRequests = 4096, maxActive = 32, isProcessAlive = alive } = {}) {
+  if (typeof Database !== 'function' || typeof file !== 'string' || !file || typeof lifecycle?.committedBot !== 'function' || typeof runtime !== 'function') fail('INDEPENDENT_CHAT_HOST_REQUIRED')
+  if (!Number.isSafeInteger(maxRequests) || maxRequests < 1 || !Number.isSafeInteger(maxActive) || maxActive < 1) fail('INDEPENDENT_CHAT_INVALID_LIMIT')
+  if (file !== ':memory:') mkdirSync(dirname(file), { recursive: true })
+  const db = new Database(file), ownerId = randomUUID(), active = new Map()
+  let closed = false
+  try {
+    db.pragma('busy_timeout=5000'); db.pragma('synchronous=FULL')
+    if (file !== ':memory:' && db.pragma('journal_mode=WAL', { simple: true }) !== 'wal') fail('INDEPENDENT_CHAT_WAL_REQUIRED')
+    db.exec(`CREATE TABLE IF NOT EXISTS bot_independent_chat_requests (
+      bot_id TEXT NOT NULL, request_key TEXT NOT NULL, schema_version INTEGER NOT NULL,
+      input_hash TEXT NOT NULL, state TEXT NOT NULL, owner_id TEXT NOT NULL, owner_pid INTEGER NOT NULL,
+      created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL, cancel_requested_at INTEGER,
+      result TEXT, error_code TEXT, PRIMARY KEY(bot_id, request_key));
+      CREATE UNIQUE INDEX IF NOT EXISTS bot_independent_chat_pending_bot
+      ON bot_independent_chat_requests(bot_id) WHERE state IN ('accepted','running');`)
+    if (!db.pragma('table_info(bot_independent_chat_requests)').some(column => column.name === 'input_text')) {
+      db.exec('ALTER TABLE bot_independent_chat_requests ADD COLUMN input_text TEXT')
+    }
+    for (const [name, definition] of [['operation_kind', "TEXT NOT NULL DEFAULT 'send'"], ['context_id', 'TEXT'], ['base_context_id', 'TEXT']]) {
+      if (!db.pragma('table_info(bot_independent_chat_requests)').some(column => column.name === name)) db.exec(`ALTER TABLE bot_independent_chat_requests ADD COLUMN ${name} ${definition}`)
+    }
+    if (db.prepare('SELECT 1 FROM bot_independent_chat_requests WHERE schema_version != 1').get()) fail('INDEPENDENT_CHAT_SCHEMA_UNSUPPORTED')
+    if (db.prepare("SELECT 1 FROM bot_independent_chat_requests WHERE operation_kind NOT IN ('send','new-conversation')").get()) fail('INDEPENDENT_CHAT_SCHEMA_UNSUPPORTED')
+  } catch (error) { db.close(); throw error }
+  const read = (botId, requestKey) => db.prepare('SELECT * FROM bot_independent_chat_requests WHERE bot_id=? AND request_key=?').get(botId, requestKey)
+  const assertOpen = () => { if (closed) fail('INDEPENDENT_CHAT_CLOSED') }
+  const identity = payload => {
+    if (!ref(payload.botId) || !requestRef(payload.requestKey)) fail('INDEPENDENT_CHAT_INVALID_REQUEST')
+  }
+  const entryKey = (botId, requestKey) => `${botId}\0${requestKey}`
+  const pending = row => row && ['accepted', 'running'].includes(row.state)
+  const recover = (row, readOnly = false) => {
+    // FS and SQLite are separate commits. Only the exact Host-derived context
+    // token reconciles a reset whose journal acknowledgement was lost. Reading
+    // it never retries retirement, starts a native process, or dispatches a turn.
+    if (row?.operation_kind === 'new-conversation' && ['accepted', 'running', 'unknown'].includes(row.state)) {
+      const adapter = runtime()
+      const context = typeof adapter?.contextOf === 'function' ? adapter.contextOf(row.bot_id) : null
+      if (context && context.contextId === row.context_id && !context.resetPending) {
+        const result = JSON.stringify({ contextId: context.contextId, sequence: context.sequence, createdAt: context.createdAt })
+        if (readOnly) return { ...row, state: 'succeeded', result, error_code: null }
+        db.prepare("UPDATE bot_independent_chat_requests SET state='succeeded',result=?,error_code=NULL,updated_at=? WHERE bot_id=? AND request_key=? AND operation_kind='new-conversation' AND state IN ('accepted','running','unknown')")
+          .run(result, now(), row.bot_id, row.request_key)
+        return read(row.bot_id, row.request_key)
+      }
+    }
+    // An OS process that is gone cannot resume its local loop. An alive or
+    // uninspectable owner stays pending; expiry alone is never stop evidence.
+    if (!readOnly && pending(row) && row.owner_id !== ownerId && !isProcessAlive(row.owner_pid)) {
+      db.prepare("UPDATE bot_independent_chat_requests SET state='unknown',error_code='INDEPENDENT_CHAT_HOST_LOST',updated_at=? WHERE bot_id=? AND request_key=? AND owner_id=? AND state IN ('accepted','running')")
+        .run(now(), row.bot_id, row.request_key, row.owner_id)
+      return read(row.bot_id, row.request_key)
+    }
+    return row
+  }
+  const project = row => {
+    if (!row) fail('INDEPENDENT_CHAT_REQUEST_NOT_FOUND')
+    const uncertain = pending(row) && (row.owner_id !== ownerId || !active.has(entryKey(row.bot_id, row.request_key)))
+    // A live preview is observation, never a transcript or a durable answer.
+    // It disappears on settlement, lost ownership or restart. Reloading the
+    // browser can inspect it without dispatching another model request.
+    const progress = !uncertain && pending(row) ? active.get(entryKey(row.bot_id, row.request_key))?.progress : null
+    return { schemaVersion: 1, botId: row.bot_id, requestKey: row.request_key,
+      operationKind: row.operation_kind ?? 'send',
+      ...(row.operation_kind === 'new-conversation' ? { contextId: row.context_id } : {}),
+      state: uncertain ? 'unknown' : row.state, pending: pending(row), finished: !pending(row),
+      createdAt: row.created_at, updatedAt: row.updated_at,
+      cancelRequested: row.cancel_requested_at !== null, cancelRequestedAt: row.cancel_requested_at,
+      stopConfirmed: false, result: row.result ? JSON.parse(row.result) : null,
+      progress: progress ? { ...progress } : null,
+      durableInput: row.operation_kind !== 'new-conversation' && (row.input_text !== null || row.state === 'succeeded'),
+      ...(row.operation_kind !== 'new-conversation' && ['unknown', 'refused', 'cancelled'].includes(uncertain ? 'unknown' : row.state) && row.input_text !== null ? { recoveryInput: row.input_text } : {}),
+      errorCode: uncertain ? row.owner_id === ownerId ? 'INDEPENDENT_CHAT_OUTCOME_NOT_COMMITTED' : 'INDEPENDENT_CHAT_OTHER_OWNER_PENDING' : row.error_code }
+  }
+  const current = botId => {
+    if (!lifecycle.committedBot(botId)) fail('BOT_NOT_COMMITTED')
+    const adapter = runtime()
+    if (typeof adapter?.turn !== 'function') fail('INDEPENDENT_CHAT_UNAVAILABLE')
+    const mode = typeof adapter.modeOf === 'function' ? adapter.modeOf(botId) : adapter.describe?.(botId)?.runtime
+    if (mode !== 'independent') fail('RUNTIME_MODE_MISMATCH')
+    return adapter
+  }
+  const summary = value => {
+    if (!plain(value) || typeof value.answer !== 'string') fail('INDEPENDENT_CHAT_RESULT_INVALID')
+    const calls = Array.isArray(value.toolCalls) ? value.toolCalls : []
+    return { answerChars: value.answer.length, answerPreview: value.answer.slice(0, 256),
+      ...(Number.isSafeInteger(value.steps) ? { steps: value.steps } : {}),
+      ...(Number.isSafeInteger(value.turns) ? { turns: value.turns } : {}),
+      toolCallCount: calls.length, toolCallsTruncated: calls.length > 32,
+      toolCalls: calls.slice(0, 32).map(call => ({ id: String(call.id ?? '').slice(0, 256), name: String(call.name ?? '').slice(0, 128) })) }
+  }
+  const assertNoPending = botId => {
+    const other = db.prepare("SELECT * FROM bot_independent_chat_requests WHERE bot_id=? AND state IN ('accepted','running')").get(botId)
+    if (pending(recover(other))) fail('INDEPENDENT_CHAT_PENDING_RECONCILIATION')
+    // An uncertain reset fences future sends across Host restarts as well as
+    // within the original runtime. Its original nonce remains inspectable.
+    const resets = db.prepare("SELECT * FROM bot_independent_chat_requests WHERE bot_id=? AND operation_kind='new-conversation' AND state='unknown'").all(botId)
+    if (resets.some(row => recover(row).state === 'unknown')) fail('INDEPENDENT_CONTEXT_PENDING_RECONCILIATION')
+  }
+  const settle = (row, state, result, errorCode) => {
+    if (closed) return
+    db.prepare("UPDATE bot_independent_chat_requests SET state=?,updated_at=?,result=?,error_code=?,input_text=CASE WHEN ?='succeeded' THEN NULL ELSE input_text END WHERE bot_id=? AND request_key=? AND owner_id=? AND state IN ('accepted','running')")
+      .run(state, now(), result ? JSON.stringify(result) : null, errorCode, state, row.bot_id, row.request_key, ownerId)
+  }
+  const run = async (row, input, entry) => {
+    let invoked = false
+    try {
+      if (closed) return
+      const adapter = current(row.bot_id)
+      entry.controller.signal.throwIfAborted()
+      db.prepare("UPDATE bot_independent_chat_requests SET state='running',updated_at=? WHERE bot_id=? AND request_key=? AND owner_id=? AND state='accepted'")
+        .run(now(), row.bot_id, row.request_key, ownerId)
+      invoked = true
+      const result = await adapter.turn({ botId: row.bot_id, input, signal: entry.controller.signal,
+        onProgress(value) {
+          if (closed || entry.controller.signal.aborted || active.get(entryKey(row.bot_id, row.request_key)) !== entry) return
+          if (!plain(value) || !Number.isSafeInteger(value.step) || value.step < 1 || value.step > 64 || typeof value.text !== 'string') fail('INDEPENDENT_CHAT_PROGRESS_INVALID')
+          if (entry.progress && value.step < entry.progress.step) fail('INDEPENDENT_CHAT_PROGRESS_INVALID')
+          let text = value.text.slice(0, 64000)
+          if (text.length < value.text.length && /[\uD800-\uDBFF]$/.test(text)) text = text.slice(0, -1)
+          entry.progress = { step: value.step, sequence: (entry.progress?.sequence ?? 0) + 1,
+            text, truncated: text.length < value.text.length }
+        } })
+      // A late cancel does not undo an already committed answer. Keep both facts.
+      settle(row, 'succeeded', summary(result), null)
+    } catch (error) {
+      const cancelled = entry.controller.signal.aborted && (error?.name === 'AbortError' || error?.code === 'BOT_LOOP_CANCELLED')
+      const code = /^[A-Z][A-Z0-9_:-]{0,95}$/.test(error?.code ?? '') ? error.code : 'INDEPENDENT_CHAT_OUTCOME_UNKNOWN'
+      settle(row, cancelled ? 'cancelled' : invoked ? 'unknown' : 'refused', null, code)
+    } finally { active.delete(entryKey(row.bot_id, row.request_key)) }
+  }
+  const runReset = async (row, entry) => {
+    let invoked = false
+    try {
+      if (closed) return
+      const adapter = current(row.bot_id)
+      if (typeof adapter.newConversation !== 'function') fail('INDEPENDENT_CONTEXT_UNAVAILABLE')
+      entry.controller.signal.throwIfAborted()
+      db.prepare("UPDATE bot_independent_chat_requests SET state='running',updated_at=? WHERE bot_id=? AND request_key=? AND owner_id=? AND state='accepted'")
+        .run(now(), row.bot_id, row.request_key, ownerId)
+      invoked = true
+      const result = await adapter.newConversation(row.bot_id, { requestKey: row.request_key,
+        expectedContextId: row.base_context_id, signal: entry.controller.signal })
+      if (!plain(result) || result.contextId !== row.context_id || result.resetPending) fail('INDEPENDENT_CONTEXT_RESULT_INVALID')
+      settle(row, 'succeeded', { contextId: result.contextId, sequence: result.sequence, createdAt: result.createdAt }, null)
+    } catch (error) {
+      const code = /^[A-Z][A-Z0-9_:-]{0,95}$/.test(error?.code ?? '') ? error.code : 'INDEPENDENT_CONTEXT_OUTCOME_UNKNOWN'
+      settle(row, invoked && error?.outcome !== 'refused' ? 'unknown' : 'refused', null, code)
+    } finally { active.delete(entryKey(row.bot_id, row.request_key)) }
+  }
+  return Object.freeze({
+    ready: true,
+    view(payload, context) {
+      owner(context); assertOpen(); keys(payload, ['botId'])
+      if (!ref(payload.botId)) fail('INDEPENDENT_CHAT_INVALID_REQUEST')
+      context.signal?.throwIfAborted()
+      if (!lifecycle.committedBot(payload.botId)) fail('BOT_NOT_COMMITTED')
+      const adapter = runtime()
+      const mode = typeof adapter?.modeOf === 'function' ? adapter.modeOf(payload.botId) : adapter?.describe?.(payload.botId)?.runtime ?? null
+      const readOnly = context.readOnly === true
+      const available = !readOnly && mode === 'independent' && typeof adapter?.turn === 'function' && typeof adapter?.conversationPage === 'function'
+      const pendingRow = recover(db.prepare("SELECT * FROM bot_independent_chat_requests WHERE bot_id=? AND state IN ('accepted','running') ORDER BY created_at DESC LIMIT 1").get(payload.botId), readOnly)
+      const latest = recover(db.prepare('SELECT * FROM bot_independent_chat_requests WHERE bot_id=? ORDER BY created_at DESC,request_key DESC LIMIT 1').get(payload.botId), readOnly)
+      const conversationContext = typeof adapter?.contextOf === 'function' ? adapter.contextOf(payload.botId) : null
+      return { schemaVersion: 1, botId: payload.botId, mode, available, readOnly,
+        reason: readOnly ? 'PRODUCT_READ_ONLY' : available ? null : mode === 'integration' ? 'RUNTIME_MODE_MISMATCH' : 'INDEPENDENT_CHAT_UNAVAILABLE',
+        pendingRequest: pending(pendingRow) ? project(pendingRow) : null,
+        latestRequest: latest ? project(latest) : null,
+        context: conversationContext,
+        newConversationAvailable: !readOnly && mode === 'independent' && Boolean(conversationContext) && !conversationContext.resetPending && !pending(pendingRow) &&
+          !adapter.busyBots?.().includes(payload.botId) && typeof adapter?.newConversation === 'function' }
+    },
+    messages(payload, context) {
+      owner(context); assertOpen(); keys(payload, ['botId', 'cursor', 'limit'])
+      if (!ref(payload.botId) || (payload.cursor !== undefined && (typeof payload.cursor !== 'string' || payload.cursor.length > 4096))
+        || (payload.limit !== undefined && (!Number.isSafeInteger(payload.limit) || payload.limit < 1 || payload.limit > 100))) fail('INDEPENDENT_CHAT_INVALID_REQUEST')
+      context.signal?.throwIfAborted()
+      if (!lifecycle.committedBot(payload.botId)) fail('BOT_NOT_COMMITTED')
+      const adapter = runtime()
+      if (typeof adapter?.conversationPage !== 'function') fail('INDEPENDENT_CHAT_UNAVAILABLE')
+      // One adapter call owns one immutable transcript snapshot. Never turn a
+      // preview position into a second read of a moving transcript.
+      return adapter.conversationPage(payload.botId, { ...(payload.cursor === undefined ? {} : { cursor: payload.cursor }), limit: payload.limit ?? 40 })
+    },
+    send(payload, context) {
+      owner(context); assertOpen(); keys(payload, ['botId', 'requestKey', 'input']); identity(payload)
+      if (context.readOnly === true) fail('PRODUCT_READ_ONLY')
+      if (typeof payload.input !== 'string' || !payload.input.trim() || Buffer.byteLength(payload.input) > 64_000) fail('INDEPENDENT_CHAT_INPUT_LIMIT')
+      context.signal?.throwIfAborted()
+      const inputHash = hash(payload.input)
+      const previous = read(payload.botId, payload.requestKey)
+      if (previous) {
+        if (previous.operation_kind !== 'send' || previous.input_hash !== inputHash) fail('INDEPENDENT_CHAT_REQUEST_CONFLICT')
+        return project(recover(previous))
+      }
+      const adapter = current(payload.botId)
+      if (active.size >= maxActive) fail('INDEPENDENT_CHAT_CONCURRENCY_LIMIT')
+      if (adapter.busyBots?.().includes(payload.botId)) fail('BOT_BUSY')
+      const inserted = db.transaction(() => {
+        const raced = read(payload.botId, payload.requestKey)
+        if (raced) {
+          if (raced.operation_kind !== 'send' || raced.input_hash !== inputHash) fail('INDEPENDENT_CHAT_REQUEST_CONFLICT')
+          return false
+        }
+        assertNoPending(payload.botId)
+        if (db.prepare('SELECT count(*) AS n FROM bot_independent_chat_requests').get().n >= maxRequests) fail('INDEPENDENT_CHAT_HISTORY_LIMIT')
+        context.signal?.throwIfAborted()
+        db.prepare("INSERT INTO bot_independent_chat_requests(bot_id,request_key,schema_version,input_hash,state,owner_id,owner_pid,created_at,updated_at,cancel_requested_at,result,error_code,input_text) VALUES(?,?,1,?,'accepted',?,?,?,?,NULL,NULL,NULL,?)")
+          .run(payload.botId, payload.requestKey, inputHash, ownerId, process.pid, now(), now(), payload.input)
+        return true
+      }).immediate()
+      if (!inserted) return project(recover(read(payload.botId, payload.requestKey)))
+      const row = read(payload.botId, payload.requestKey), entry = { controller: new AbortController(), done: null }
+      active.set(entryKey(payload.botId, payload.requestKey), entry)
+      entry.done = Promise.resolve().then(() => run(row, payload.input, entry))
+      entry.done.catch(() => {})
+      return project(row)
+    },
+    newConversation(payload, context) {
+      owner(context); assertOpen(); keys(payload, ['botId', 'requestKey']); identity(payload)
+      if (context.readOnly === true) fail('PRODUCT_READ_ONLY')
+      context.signal?.throwIfAborted()
+      const previous = read(payload.botId, payload.requestKey)
+      if (previous) {
+        if (previous.operation_kind !== 'new-conversation') fail('INDEPENDENT_CHAT_REQUEST_CONFLICT')
+        return project(recover(previous))
+      }
+      const adapter = current(payload.botId)
+      if (typeof adapter.newConversation !== 'function' || typeof adapter.contextOf !== 'function') fail('INDEPENDENT_CONTEXT_UNAVAILABLE')
+      if (active.size >= maxActive) fail('INDEPENDENT_CHAT_CONCURRENCY_LIMIT')
+      if (adapter.busyBots?.().includes(payload.botId)) fail('BOT_BUSY')
+      const base = adapter.contextOf(payload.botId)
+      if (base.resetPending) fail('INDEPENDENT_CONTEXT_PENDING_RECONCILIATION')
+      const contextId = independentContextId(payload.botId, payload.requestKey)
+      const inserted = db.transaction(() => {
+        const raced = read(payload.botId, payload.requestKey)
+        if (raced) {
+          if (raced.operation_kind !== 'new-conversation') fail('INDEPENDENT_CHAT_REQUEST_CONFLICT')
+          return false
+        }
+        assertNoPending(payload.botId)
+        if (db.prepare('SELECT count(*) AS n FROM bot_independent_chat_requests').get().n >= maxRequests) fail('INDEPENDENT_CHAT_HISTORY_LIMIT')
+        context.signal?.throwIfAborted()
+        db.prepare("INSERT INTO bot_independent_chat_requests(bot_id,request_key,schema_version,input_hash,state,owner_id,owner_pid,created_at,updated_at,cancel_requested_at,result,error_code,input_text,operation_kind,context_id,base_context_id) VALUES(?,?,1,?,'accepted',?,?,?,?,NULL,NULL,NULL,NULL,'new-conversation',?,?)")
+          .run(payload.botId, payload.requestKey, hash('new-conversation'), ownerId, process.pid, now(), now(), contextId, base.contextId)
+        return true
+      }).immediate()
+      if (!inserted) return project(recover(read(payload.botId, payload.requestKey)))
+      const row = read(payload.botId, payload.requestKey), entry = { controller: new AbortController(), done: null }
+      active.set(entryKey(payload.botId, payload.requestKey), entry)
+      entry.done = Promise.resolve().then(() => runReset(row, entry))
+      entry.done.catch(() => {})
+      return project(row)
+    },
+    inspect(payload, context) {
+      owner(context); assertOpen(); keys(payload, ['botId', 'requestKey']); identity(payload)
+      context.signal?.throwIfAborted()
+      return project(recover(read(payload.botId, payload.requestKey), context.readOnly === true))
+    },
+    cancel(payload, context) {
+      owner(context); assertOpen(); keys(payload, ['botId', 'requestKey']); identity(payload)
+      if (context.readOnly === true) fail('PRODUCT_READ_ONLY')
+      context.signal?.throwIfAborted()
+      const row = read(payload.botId, payload.requestKey)
+      if (!row) fail('INDEPENDENT_CHAT_REQUEST_NOT_FOUND')
+      const entry = active.get(entryKey(payload.botId, payload.requestKey))
+      if (pending(row) && entry) {
+        db.prepare('UPDATE bot_independent_chat_requests SET cancel_requested_at=coalesce(cancel_requested_at,?),updated_at=? WHERE bot_id=? AND request_key=? AND owner_id=?')
+          .run(now(), now(), payload.botId, payload.requestKey, ownerId)
+        entry.controller.abort(Object.assign(new Error('INDEPENDENT_CHAT_CANCEL_REQUESTED'), { code: 'BOT_LOOP_CANCELLED' }))
+      }
+      return project(recover(read(payload.botId, payload.requestKey)))
+    },
+    async whenIdle() { await Promise.allSettled([...active.values()].map(entry => entry.done)) },
+    close() {
+      if (closed) return
+      closed = true
+      for (const entry of active.values()) entry.controller.abort(Object.assign(new Error('INDEPENDENT_CHAT_CLOSED'), { code: 'BOT_LOOP_CANCELLED' }))
+      try {
+        db.prepare("UPDATE bot_independent_chat_requests SET state='unknown',error_code='INDEPENDENT_CHAT_CLOSED',updated_at=? WHERE owner_id=? AND state IN ('accepted','running')").run(now(), ownerId)
+      } finally { db.close() }
+    },
+  })
+}

package/packages/orchestration/src/independent-context-state.mjs

@@ -0,0 +1,44 @@
+import { createHash } from 'node:crypto'
+
+export const LEGACY_CONTEXT = 'legacy'
+export const MAX_CONTEXTS = 64
+export const contextIdOk = value => typeof value === 'string' && /^[-A-Za-z0-9_.]{1,128}$/.test(value)
+export const contextRequestOk = value => typeof value === 'string' && /^[-A-Za-z0-9_]{16,128}$/.test(value)
+const fail = code => { throw Object.assign(new Error(code), { code }) }
+
+// Derived by the Host, never accepted from a model or a GenerateOptions sessionId.
+export const independentContextId = (botId, requestKey) => `context-${createHash('sha256').update(JSON.stringify([botId, requestKey])).digest('hex')}`
+export function contextFields(value) {
+  const contextId = value.contextId ?? LEGACY_CONTEXT
+  if (!contextIdOk(contextId)) fail('INVALID_BOT_CONTEXT')
+  const contexts = value.contexts ?? [{ contextId: LEGACY_CONTEXT, sequence: 0, createdAt: value.createdAt ?? 0 }]
+  if (!Array.isArray(contexts) || !contexts.length || contexts.length > MAX_CONTEXTS || contexts.some(row =>
+    !row || !contextIdOk(row.contextId) || !Number.isSafeInteger(row.sequence) || row.sequence < 0 ||
+    !Number.isSafeInteger(row.createdAt) || row.requestKey !== undefined && !contextRequestOk(row.requestKey) ||
+    row.previousContextId !== undefined && !contextIdOk(row.previousContextId)) ||
+    new Set(contexts.map(row => row.contextId)).size !== contexts.length || !contexts.some(row => row.contextId === contextId)) fail('INVALID_BOT_CONTEXT')
+  const contextReset = value.contextReset
+  if (contextReset !== undefined && (!contextReset || !contextRequestOk(contextReset.requestKey) ||
+    !contextIdOk(contextReset.contextId) || contextReset.contextId === contextId ||
+    contextReset.previousContextId !== contextId || !Number.isSafeInteger(contextReset.createdAt))) fail('INVALID_BOT_CONTEXT_RESET')
+  return { contextId, contexts: contexts.map(row => ({ contextId: row.contextId, sequence: row.sequence, createdAt: row.createdAt,
+    ...(row.requestKey ? { requestKey: row.requestKey } : {}), ...(row.previousContextId ? { previousContextId: row.previousContextId } : {}) })),
+    ...(contextReset ? { contextReset: { requestKey: contextReset.requestKey, contextId: contextReset.contextId,
+      previousContextId: contextReset.previousContextId, createdAt: contextReset.createdAt } } : {}),
+    contextsTruncated: value.contextsTruncated === true }
+}
+
+export function contextView(session) {
+  const counts = new Map()
+  for (const row of session.messages) counts.set(row.contextId ?? LEGACY_CONTEXT, (counts.get(row.contextId ?? LEGACY_CONTEXT) ?? 0) + 1)
+  const active = session.contexts.find(row => row.contextId === session.contextId)
+  return { contextId: session.contextId, sequence: active.sequence, createdAt: active.createdAt,
+    messageCount: counts.get(session.contextId) ?? 0, resetPending: Boolean(session.contextReset),
+    contextsTruncated: session.contextsTruncated,
+    contexts: session.contexts.map(row => ({ contextId: row.contextId, sequence: row.sequence, createdAt: row.createdAt,
+      messageCount: counts.get(row.contextId) ?? 0 })) }
+}
+
+// A stop request, a timeout, or contradictory evidence cannot establish retirement.
+export const retirementConfirmed = value => Boolean(value && value.treeStopped !== false && value.possiblyApplied !== true && value.unknown !== true &&
+  (value.treeStopped === true || value.notStarted === true && value.possiblyApplied === false))

package/packages/orchestration/src/independent-message-wire.mjs

@@ -0,0 +1,84 @@
+import { createHash } from 'node:crypto'
+
+const block = text => ({ type: 'text', text })
+const sourceOf = value => value?.kind === 'model' && typeof value.provider === 'string' && value.provider && typeof value.model === 'string' && value.model
+  ? { kind: 'model', provider: value.provider, model: value.model } : null
+const callsOf = row => Array.isArray(row.toolCalls) ? row.toolCalls : row.toolCall ? [row.toolCall] : []
+const idOf = (row, occurrence) => row.messageId ?? `independent-${createHash('sha256').update(JSON.stringify({ role: row.role, content: row.content, at: row.at, toolCallId: row.toolCallId, toolCalls: callsOf(row), occurrence })).digest('hex')}`
+
+/** Current committed identity is instructions for this request, never a grant. */
+export function independentSystemMessage(bot) {
+  const name = typeof bot.name === 'string' && bot.name.trim() ? bot.name.trim() : bot.id
+  const role = typeof bot.role === 'string' ? bot.role.trim() : ''
+  const instructions = typeof bot.instructions === 'string' ? bot.instructions.trim() : ''
+  const text = [`You are ${name}.`, ...(role ? [`Role: ${role}`] : []), ...(instructions ? [instructions] : [])].join('\n\n')
+  const id = `independent-system-${createHash('sha256').update(JSON.stringify([bot.id, text])).digest('hex')}`
+  return { id, role: 'system', source: { kind: 'system-prompt' }, content: [block(text)] }
+}
+
+/**
+ * Project the Bot-owned transcript to the installed dsh-llm message vocabulary.
+ * This creates no Harness Session and confers no authority. Model provenance comes
+ * from each saved reply, never from the Bot's currently selected model. Old rows
+ * without provenance and interrupted tool batches remain clearly labeled recall;
+ * they cannot become an invented assistant response or a replayable tool call.
+ */
+export function independentMessageWire(rows) {
+  if (!Array.isArray(rows)) throw Object.assign(new Error('INDEPENDENT_TRANSCRIPT_REQUIRED'), { code: 'INDEPENDENT_TRANSCRIPT_REQUIRED' })
+  const pending = new Map(), lastOwner = new Map(), results = new Map(), resultOwners = new Map(), complete = new Set(), occurrences = new Map()
+  for (const row of rows) {
+    if (row.role === 'assistant' && sourceOf(row.modelSource)) {
+      const ids = new Set()
+      results.set(row, new Map())
+      for (const call of callsOf(row)) {
+        if (typeof call?.id !== 'string' || !call.id || typeof call.name !== 'string' || !call.name || ids.has(call.id)) {
+          throw Object.assign(new Error('INDEPENDENT_TOOL_HISTORY_INVALID'), { code: 'INDEPENDENT_TOOL_HISTORY_INVALID' })
+        }
+        ids.add(call.id)
+        // Providers can reuse an id in a later response. Its nearest preceding
+        // request owns the result; an earlier unresolved batch stays recall.
+        pending.set(call.id, row)
+        lastOwner.set(call.id, row)
+      }
+    }
+    if (row.role === 'tool' && typeof row.toolCallId === 'string') {
+      const owner = pending.get(row.toolCallId)
+      if (owner) {
+        results.get(owner).set(row.toolCallId, row)
+        resultOwners.set(row, owner)
+        pending.delete(row.toolCallId)
+      } else if (lastOwner.has(row.toolCallId)) {
+        throw Object.assign(new Error('INDEPENDENT_TOOL_HISTORY_DUPLICATE'), { code: 'INDEPENDENT_TOOL_HISTORY_DUPLICATE' })
+      }
+    }
+  }
+  for (const row of rows) {
+    const calls = callsOf(row)
+    if (row.role === 'assistant' && sourceOf(row.modelSource) && calls.every(call => results.get(row)?.has(call.id))) complete.add(row)
+  }
+  return rows.map(row => {
+    const key = JSON.stringify([row.role, row.at, row.content])
+    const occurrence = occurrences.get(key) ?? 0
+    occurrences.set(key, occurrence + 1)
+    const id = idOf(row, occurrence)
+    const text = typeof row.content === 'string' ? row.content : ''
+    if (row.role === 'user') return { role: 'user', content: [block(text)] }
+    if (row.role === 'system') return { id, role: 'system', source: { kind: 'system-prompt' }, content: [block(text)] }
+    const source = sourceOf(row.modelSource)
+    const calls = callsOf(row)
+    if (row.role === 'assistant' && source && complete.has(row)) return {
+      id, role: 'assistant', source,
+      content: [...(text ? [block(text)] : []), ...calls.map(call => ({ type: 'tool-call', id: call.id, name: call.name, arguments: JSON.stringify(call.args ?? {}) }))],
+    }
+    const owner = resultOwners.get(row)
+    if (owner && complete.has(owner)) return {
+      id, role: 'tool', source: { kind: 'tool', callId: row.toolCallId }, toolCallId: row.toolCallId,
+      content: [block(text)], ...(row.isError === true ? { isError: true } : {}),
+    }
+    const label = row.role === 'assistant'
+      ? calls.length ? 'Earlier assistant tool request; execution outcome not fully confirmed' : 'Earlier assistant message; model provenance unrecorded'
+      : 'Earlier tool result; original call is outside this retained history'
+    return { id, role: 'user', source: { kind: 'independent-history', form: 'recall' },
+      content: [block(`[${label}]\n${text}${calls.length ? `\n${JSON.stringify(calls)}` : ''}`)] }
+  })
+}

package/packages/orchestration/src/independent-tool-catalog.mjs

@@ -0,0 +1,175 @@
+/**
+ * The tool catalog one independent Bot may see.
+ *
+ * The model is offered exactly what this Bot's committed grants allow, re-decided from committed
+ * state on every request: no tool name, machine, root or capability comes from the request, and
+ * nothing here hands the model an owner, a subject, an executable path, an endpoint or an
+ * operation identity. Those are Host facts; the model only ever supplies business content.
+ *
+ * Three rules are load-bearing:
+ *
+ * 1. A capability the Host cannot actually run is **not** offered. `unavailable()` names it and
+ *    says why, so a Host with no durable Task backend says "no tracked write" instead of advertising
+ *    a schema whose execution would be a guess.
+ * 2. Every schema is derived, never cached across a grant change: the caller asks again per step and
+ *    per call, and a grant the authority no longer holds removes the tool from the request.
+ * 3. The machine and root are Host-chosen from the Bot's own live binding. A model may name one of
+ *    its own bound machines or roots; the Host still re-checks both before the call runs.
+ */
+
+/** Effects. A read may run beside another read; everything else stays sequential. */
+export const READ_EFFECT = 'read'
+export const WRITE_EFFECT = 'workspace-write'
+
+/** Machine tools the independent path may reach, with the Host-side business arguments. */
+const TARGET_KEYS = {
+  machineId: { type: 'string', description: '本 Bot 已绑定的其中一台机器；不填则由宿主选择。' },
+  rootId: { type: 'string', description: '该机器上已授权给本 Bot 的其中一个根目录；不填则由宿主选择。' },
+}
+
+const pathParameter = description => ({ type: 'string', description })
+
+const objectSchema = (properties, required = []) => Object.freeze({
+  type: 'object',
+  properties: Object.freeze(properties),
+  required: Object.freeze(required),
+  additionalProperties: false,
+})
+
+/**
+ * One offered capability. `machineTool` is the remote agent tool; `backend` names the durable Task
+ * backend that must exist before the capability may be offered at all; `grants` are the authority
+ * capabilities a call will need, so a grant that was withdrawn takes the tool out of the request.
+ */
+const CAPABILITIES = Object.freeze([
+  Object.freeze({
+    name: 'bot_machine_ping', machineTool: 'machine_ping', effect: READ_EFFECT, backend: null,
+    grants: ['remote/machine_ping'],
+    description: '确认本 Bot 已绑定的远程机器在线，并读取它的能力清单。',
+    parameters: objectSchema({ ...TARGET_KEYS }),
+  }),
+  Object.freeze({
+    name: 'bot_fs_list', machineTool: 'fs_list', effect: READ_EFFECT, backend: null,
+    grants: ['remote/fs_list'],
+    description: '列出已授权根目录下的文件名。路径相对于该根目录，不能越出它。',
+    parameters: objectSchema({ ...TARGET_KEYS, relativePath: pathParameter('相对已授权根目录的目录路径，默认当前目录。') }, []),
+  }),
+  Object.freeze({
+    name: 'bot_fs_read', machineTool: 'fs_read', effect: READ_EFFECT, backend: null,
+    grants: ['remote/fs_read'],
+    description: '读取已授权根目录下的一个文本文件，有长度上限。',
+    parameters: objectSchema({ ...TARGET_KEYS, relativePath: pathParameter('相对已授权根目录的文件路径。') }, ['relativePath']),
+  }),
+  Object.freeze({
+    name: 'bot_fs_write', machineTool: 'fs_write', effect: WRITE_EFFECT, backend: 'remote-write',
+    grants: ['remote/fs_write', 'task/submit'],
+    description: '把文本内容写入已授权根目录下的一个文件。这是一次可跟踪的持久 Task：宿主保留请求键、Task、attempt 与 operation 身份，结果未知时不会重放。',
+    parameters: objectSchema({
+      ...TARGET_KEYS,
+      relativePath: pathParameter('相对已授权根目录的文件路径。'),
+      content: { type: 'string', description: '要写入的文本内容。' },
+      expectedHash: { type: ['string', 'null'], description: '期望的当前文件 SHA256；新文件填 null。' },
+    }, ['relativePath', 'content', 'expectedHash']),
+  }),
+  Object.freeze({
+    name: 'bot_command', machineTool: 'container_command_v1', effect: WRITE_EFFECT, backend: 'remote-command',
+    grants: ['remote/container_command_v1', 'task/submit'],
+    description: '在已授权的远程容器 profile 中运行一条操作员预先批准的 argv 命令。不接受 shell 字符串、可执行路径或环境变量。',
+    parameters: objectSchema({
+      ...TARGET_KEYS,
+      workspaceRelativePath: pathParameter('命令的工作目录，相对已授权根目录；空字符串表示该根本身。'),
+      argv: { type: 'array', items: { type: 'string' }, description: '命令参数数组，第一项必须是已批准的别名。' },
+      timeoutMs: { type: 'integer', description: '超时毫秒数，宿主另有上界。', minimum: 1000, maximum: 600000 },
+    }, ['workspaceRelativePath', 'argv']),
+  }),
+  Object.freeze({
+    name: 'bot_operation_status', machineTool: 'operation_status', effect: READ_EFFECT, backend: null,
+    grants: ['remote/operation_status'],
+    description: '读取本 Bot 早前一次操作的当前状态。operationId 必须来自宿主返回的上一次工具结果。',
+    parameters: objectSchema({ operationId: { type: 'string', description: '宿主早前返回的 operationId。' } }, ['operationId']),
+  }),
+  Object.freeze({
+    name: 'bot_operation_cancel', machineTool: 'operation_cancel', effect: WRITE_EFFECT, backend: null,
+    grants: ['remote/operation_cancel'],
+    description: '请求停止本 Bot 早前的一次操作。这只是停止请求，已生效的副作用不会回滚。operationId 必须来自宿主返回的上一次工具结果。',
+    parameters: objectSchema({ operationId: { type: 'string', description: '宿主早前返回的 operationId。' } }, ['operationId']),
+  }),
+  Object.freeze({
+    name: 'bot_artifact_stat', machineTool: 'artifact_stat', effect: READ_EFFECT, backend: null,
+    grants: ['remote/artifact_stat'],
+    description: '读取本 Bot 早前一次操作产出的附件元数据。artifactId 必须来自宿主返回的上一次工具结果。',
+    parameters: objectSchema({ artifactId: { type: 'string', description: '宿主早前返回的 artifactId。' } }, ['artifactId']),
+  }),
+  Object.freeze({
+    name: 'bot_artifact_read', machineTool: 'artifact_read', effect: READ_EFFECT, backend: null,
+    grants: ['remote/artifact_read'],
+    description: '分块读取本 Bot 早前一次操作产出的附件内容。artifactId 必须来自宿主返回的上一次工具结果。',
+    parameters: objectSchema({
+      artifactId: { type: 'string', description: '宿主早前返回的 artifactId。' },
+      offset: { type: 'integer', description: '起始字节偏移。', minimum: 0 },
+      length: { type: 'integer', description: '读取字节数，宿主另有上界。', minimum: 1 },
+    }, ['artifactId']),
+  }),
+  Object.freeze({
+    name: 'bot_task_status', machineTool: null, effect: READ_EFFECT, backend: 'task-service', taskAction: 'read',
+    grants: ['task/read'],
+    description: '读取本 Bot 自己提交的一次持久 Task 的状态。taskId 必须来自宿主返回的上一次工具结果。',
+    parameters: objectSchema({ taskId: { type: 'string', description: '宿主早前返回的 taskId。' } }, ['taskId']),
+  }),
+  Object.freeze({
+    name: 'bot_task_cancel', machineTool: null, effect: WRITE_EFFECT, backend: 'task-service', taskAction: 'cancel',
+    grants: ['task/cancel'],
+    description: '请求停止本 Bot 自己提交的一次持久 Task。这只是停止请求，attempt 保持自己的身份与未知结果证据。taskId 必须来自宿主返回的上一次工具结果。',
+    parameters: objectSchema({ taskId: { type: 'string', description: '宿主早前返回的 taskId。' } }, ['taskId']),
+  }),
+])
+
+export const INDEPENDENT_TOOL_NAMES = Object.freeze(CAPABILITIES.map(entry => entry.name))
+
+const byName = new Map(CAPABILITIES.map(entry => [entry.name, entry]))
+
+export const independentToolEntry = name => byName.get(name) ?? null
+
+/**
+ * The offered schemas for one Bot, plus what this Host cannot run.
+ *
+ * @param {{ scopes?: Array<{ machineId: string, roots: string[], tools: string[], mode: string }>,
+ *   backends?: string[], granted?: (capability: string) => boolean }} facts read live
+ * @returns {{ tools: object[], unavailable: Array<{ name: string, code: string }>, machines: string[] }}
+ */
+export function catalogFor({ scopes = [], backends = [], granted = () => true } = {}) {
+  if (!Array.isArray(scopes)) throw new TypeError('INDEPENDENT_TOOL_SCOPES_REQUIRED')
+  const live = scopes.filter(scope => scope && typeof scope.machineId === 'string' && Array.isArray(scope.tools))
+  const available = new Set(Array.isArray(backends) ? backends : [])
+  const allowed = name => { try { return granted(name) !== false } catch { return false } }
+  const tools = []
+  const unavailable = []
+  for (const entry of CAPABILITIES) {
+    // A durable backend is a precondition, not a runtime surprise: without it the capability is
+    // named as unavailable instead of being offered and failing later.
+    if (entry.backend && !available.has(entry.backend)) {
+      unavailable.push({ name: entry.name, code: entry.backend === 'task-service' ? 'TASK_SERVICE_UNAVAILABLE' : 'TASK_BACKEND_UNAVAILABLE' })
+      continue
+    }
+    if (!entry.grants.every(allowed)) {
+      unavailable.push({ name: entry.name, code: 'CAPABILITY_NOT_GRANTED' })
+      continue
+    }
+    if (entry.machineTool === null) {
+      tools.push(Object.freeze({ name: entry.name, description: entry.description, parameters: entry.parameters }))
+      continue
+    }
+    const grantedScope = live.some(scope => scope.tools.includes(entry.machineTool)
+      && (entry.effect !== WRITE_EFFECT || scope.mode === 'workspace-write'))
+    if (!grantedScope) {
+      unavailable.push({ name: entry.name, code: entry.effect === WRITE_EFFECT ? 'MACHINE_WRITE_NOT_GRANTED' : 'MACHINE_TOOL_NOT_GRANTED' })
+      continue
+    }
+    tools.push(Object.freeze({ name: entry.name, description: entry.description, parameters: entry.parameters }))
+  }
+  return {
+    tools: Object.freeze(tools),
+    unavailable: Object.freeze(unavailable),
+    machines: Object.freeze([...new Set(live.map(scope => scope.machineId))].sort()),
+  }
+}