@sqdr2/dsh-fusion 0.0.0-stage → 0.3.2

package/src/host/evidence-page.ts

@@ -0,0 +1,25 @@
+/** Lossless text decoding; binary artifacts stay available as explicit base64. */
+export function evidenceText(bytes: Uint8Array): string | undefined {
+  if (bytes.includes(0)) return undefined
+  try { return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes) }
+  catch { return undefined }
+}
+
+/** Offsets count UTF-16 code units of text, or characters of base64. */
+export function evidencePage(bytes: Uint8Array, offset = 0, limit = 24_000) {
+  if (!Number.isSafeInteger(offset) || offset < 0) throw new Error('Evidence offset must be a nonnegative safe integer')
+  if (!Number.isSafeInteger(limit) || limit < 2 || limit > 24_000) throw new Error('Evidence limit must be an integer from 2 to 24000')
+  const decoded = evidenceText(bytes)
+  const encoding = decoded === undefined ? 'base64' : 'utf-8'
+  const content = decoded ?? Buffer.from(bytes).toString('base64')
+  if (offset > content.length) throw new Error('Evidence offset exceeds the artifact text length')
+  const splitsPair = (at: number) => at > 0 && at < content.length
+    && content.charCodeAt(at - 1) >= 0xd800 && content.charCodeAt(at - 1) <= 0xdbff
+    && content.charCodeAt(at) >= 0xdc00 && content.charCodeAt(at) <= 0xdfff
+  if (splitsPair(offset)) throw new Error('Evidence offset splits a Unicode character; use the returned nextOffset')
+  let end = Math.min(content.length, offset + limit)
+  if (splitsPair(end)) end--
+  const truncated = end < content.length
+  return { bytes: bytes.byteLength, encoding, offsetUnit: 'utf-16-code-units', offset, totalCharacters: content.length,
+    text: content.slice(offset, end), truncated, nextOffset: truncated ? end : null }
+}

package/src/host/history.ts

@@ -0,0 +1,114 @@
+import type { SqliteFusionStore } from '../task/sqlite-store.js'
+import type { TaskState } from '../task/state.js'
+import type { NativeUsageRecord } from './native-usage.js'
+import { projectLedger, restoreLedger, type Count } from '../usage/ledger.js'
+
+export interface TaskSummary {
+  id: string; sessionId: string; seq: number; createdAt: string; updatedAt: string
+  title: string; phase: string; verification: string; mode: string
+}
+export function taskSummary(state: TaskState, createdAt: string, updatedAt: string): TaskSummary {
+  return { id: state.taskId, sessionId: state.parent, seq: state.seq, createdAt, updatedAt,
+    title: state.currentWorkOrder?.goal?.slice(0, 160) || '对话任务', phase: state.phase, verification: state.verification, mode: state.control.mode }
+}
+export interface UsageSummary {
+  id: string; taskId: string; role: string; provider: string; model: string; purpose: string; startedAt: string
+  outcome: string; authority: 'none' | 'provisional' | 'final'; input: Count; output: Count
+  reasoning: Count; totalOutput: Count; cacheRead: Count
+}
+export function usageSummary(row: NativeUsageRecord): UsageSummary {
+  const projection = projectLedger(restoreLedger(row.ledger))
+  const bill = projection.bill
+  const input = bill?.uncachedInput ?? { state: 'unknown' }
+  const output = bill?.output ?? { state: 'unknown' }
+  const cacheRead = bill?.cacheRead ?? { state: 'unknown' }
+  const reasoning = bill?.reasoning?.tokens ?? { state: 'unknown' }
+
+  let totalOutput: Count = { state: 'unknown' }
+  if (output.state === 'known') {
+    if (bill?.reasoning?.kind === 'included') {
+      totalOutput = { state: 'known', tokens: output.tokens }
+    } else if (reasoning.state === 'known') {
+      totalOutput = { state: 'known', tokens: output.tokens + reasoning.tokens }
+    } else {
+      totalOutput = { state: 'unknown' }
+    }
+  }
+
+  return { id: row.nativeInvocationId, taskId: row.taskId, role: row.role, provider: row.ledger.key.provider, model: row.ledger.key.model,
+    purpose: row.purpose ?? 'conversation', startedAt: row.startedAt, outcome: row.outcome, authority: projection.authority,
+    input, output, reasoning, totalOutput, cacheRead }
+}
+
+/** Once at plugin startup; GET never writes, starts agents, or scans full task/usage snapshots. */
+export function backfillHistory(store: SqliteFusionStore) {
+  for (const id of store.listTaskIds()) {
+    if (store.readDocument(`task-index:${id}`)) continue
+    const state = store.load(id)!, events = store.events(id)
+    store.writeDocument(`task-index:${id}`, 0, taskSummary(state, events[0]!.createdAt, events.at(-1)!.createdAt))
+  }
+  for (const id of store.listDocumentIds('usage:')) {
+    const projectionId = `usage-index:${id.slice(6)}`
+    const existing = store.readDocument(projectionId)
+    if (existing && (existing.value as UsageSummary).totalOutput !== undefined) continue
+    const usageDoc = store.readDocument(id)
+    if (usageDoc) {
+      store.writeDocument(projectionId, existing?.revision ?? 0, usageSummary(usageDoc.value as NativeUsageRecord))
+    }
+  }
+}
+export interface HistoryTotals { calls: number; final: number; provisional: number; unreported: number;
+  input: { known: number; reported: number }; output: { known: number; reported: number }
+  reasoning: { known: number; reported: number }; totalOutput: { known: number; reported: number }; cacheRead: { known: number; reported: number } }
+const empty = (): HistoryTotals => ({ calls: 0, final: 0, provisional: 0, unreported: 0,
+  input: { known: 0, reported: 0 }, output: { known: 0, reported: 0 },
+  reasoning: { known: 0, reported: 0 }, totalOutput: { known: 0, reported: 0 }, cacheRead: { known: 0, reported: 0 } })
+function add(total: HistoryTotals, row: UsageSummary) {
+  total.calls++; total[row.authority === 'none' ? 'unreported' : row.authority]++
+  for (const key of ['input', 'output', 'reasoning', 'totalOutput', 'cacheRead'] as const) {
+    const count = row[key]
+    if (count && count.state === 'known') { total[key].known += count.tokens; total[key].reported++ }
+  }
+  if (!row.totalOutput && row.output && row.output.state === 'known') {
+    if (row.reasoning && row.reasoning.state === 'known') {
+      total.totalOutput.known += row.output.tokens + row.reasoning.tokens
+      total.totalOutput.reported++
+    }
+  }
+}
+/** How often the Host unlocked Lead takeover (enforced-v3), by reason. */
+export interface TakeoverTotals { total: number; tasks: number; reasons: Record<string, number> }
+export interface HistoryView {
+  observedAt: string; totalTasks: number; tasks: (TaskSummary & { usage: HistoryTotals; takeovers: number })[]; nextCursor: string | null
+  takeovers: TakeoverTotals
+  totals: HistoryTotals; groups: ({ role: string; provider: string; model: string; purpose: string } & HistoryTotals)[]
+  actualBilledUsd: null; savingsPercent: null; upstreamHttpCalls: null
+}
+export function readHistory(store: SqliteFusionStore, cursor = '', limit = 20): HistoryView {
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > 50) throw new Error('History page size must be 1–50')
+  const tasks = store.listDocumentIds('task-index:').map(id => store.readDocument(id)!.value as TaskSummary)
+    .sort((a, b) => b.createdAt.localeCompare(a.createdAt) || b.id.localeCompare(a.id))
+  const all = store.listDocumentIds('usage-index:').map(id => store.readDocument(id)!.value as UsageSummary)
+  const groups = new Map<string, HistoryView['groups'][number]>(), byTask = new Map<string, HistoryTotals>(), totals = empty()
+  for (const row of all) {
+    add(totals, row)
+    const own = byTask.get(row.taskId) ?? empty(); add(own, row); byTask.set(row.taskId, own)
+    const key = JSON.stringify([row.role, row.provider, row.model, row.purpose])
+    const group = groups.get(key) ?? { role: row.role, provider: row.provider, model: row.model, purpose: row.purpose, ...empty() }
+    add(group, row); groups.set(key, group)
+  }
+  const takeovers: TakeoverTotals = { total: 0, tasks: 0, reasons: {} }, takeoversByTask = new Map<string, number>()
+  for (const id of store.listDocumentIds('lead-takeover:')) {
+    const row = store.readDocument(id)!.value as { taskId: string; reason: string }
+    takeovers.total++; takeovers.reasons[row.reason] = (takeovers.reasons[row.reason] ?? 0) + 1
+    takeoversByTask.set(row.taskId, (takeoversByTask.get(row.taskId) ?? 0) + 1)
+  }
+  takeovers.tasks = takeoversByTask.size
+  const start = cursor ? tasks.findIndex(task => task.id === cursor) + 1 : 0
+  if (cursor && start === 0) throw new Error('History cursor is no longer available')
+  const page = tasks.slice(start, start + limit)
+  return { observedAt: new Date().toISOString(), totalTasks: tasks.length,
+    tasks: page.map(task => ({ ...task, usage: byTask.get(task.id) ?? empty(), takeovers: takeoversByTask.get(task.id) ?? 0 })),
+    nextCursor: start + limit < tasks.length ? page.at(-1)!.id : null, takeovers,
+    totals, groups: [...groups.values()].sort((a, b) => b.calls - a.calls), actualBilledUsd: null, savingsPercent: null, upstreamHttpCalls: null }
+}

package/src/host/http.ts

@@ -0,0 +1,30 @@
+import type { IncomingMessage, ServerResponse } from 'node:http'
+
+export function trustedRequest(req: IncomingMessage): boolean {
+  if (!['127.0.0.1', '::1', '::ffff:127.0.0.1'].includes(req.socket.remoteAddress ?? '')) return false
+  if (req.headers['sec-fetch-site'] === 'cross-site' || !req.headers.host) return false
+  try {
+    const target = new URL(`http://${req.headers.host}`)
+    if (!['localhost', '127.0.0.1', '[::1]'].includes(target.hostname)) return false
+    return !req.headers.origin || new URL(req.headers.origin).host === target.host
+  } catch { return false }
+}
+
+export function json(res: ServerResponse, status: number, body: unknown): void {
+  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store', 'x-content-type-options': 'nosniff' })
+  res.end(JSON.stringify(body))
+}
+
+export async function readJson(req: IncomingMessage): Promise<Record<string, unknown>> {
+  if (!req.headers['content-type']?.toLowerCase().startsWith('application/json')) throw new Error('JSON content type required')
+  const chunks: Buffer[] = []
+  let size = 0
+  for await (const chunk of req) {
+    size += chunk.length
+    if (size > 256 * 1024) throw new Error('Request body exceeds 256 KiB')
+    chunks.push(Buffer.from(chunk))
+  }
+  const value: unknown = JSON.parse(Buffer.concat(chunks).toString('utf8'))
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('JSON object required')
+  return value as Record<string, unknown>
+}

package/src/host/model-output.ts

@@ -0,0 +1,22 @@
+import type { Context } from '@deepseek-ai/cordis'
+import { fittedOutputReservation } from '../context/guard.js'
+
+/**
+ * Output limits come only from the public model metadata DSH discloses for the route (context window and
+ * the adapter's default max tokens). No route or model names are special-cased: route names differ between
+ * installations, and a guessed cap would be wrong for someone else's setup.
+ */
+export interface ModelOutputLimits {
+  contextWindow: number
+  defaultMaxTokens?: number
+  testedOutputCap?: number
+}
+
+/** Public model metadata only; resolving limits does not start a model turn. */
+export async function resolveModelOutputLimits(ctx: Context, provider: string, model: string): Promise<ModelOutputLimits> {
+  const info = await ctx.llm.resolveModelInfo(provider, model)
+  const contextWindow = info.context?.contextWindow
+  if (!Number.isSafeInteger(contextWindow) || Number(contextWindow) <= 0) throw new Error('The configured model does not disclose a usable context window')
+  fittedOutputReservation(Number(contextWindow))
+  return { contextWindow: Number(contextWindow), defaultMaxTokens: info.defaultMaxTokens }
+}

package/src/host/native-activity.ts

@@ -0,0 +1,199 @@
+import type { Context } from '@deepseek-ai/cordis'
+import { SessionId } from '@deepseek-ai/dsh-session'
+import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
+import type {} from '@deepseek-ai/dsh-session-query'
+import type { FusionActivity, FusionActivityPage } from '../activity.js'
+import type { SqliteFusionStore } from '../task/sqlite-store.js'
+
+interface ActivityLink {
+  parentId: string
+  childId: string
+  taskId: string
+  callId: string
+  turn: number
+  step: number
+  anchorSeq: number
+  fromSeq: number | null
+  done?: boolean
+}
+const prefix = 'activity-link:'
+const visibleTools = new Set(['bash', 'pwsh', 'read', 'write', 'edit', 'glob', 'grep', 'job_output', 'job_kill', 'str_replace_editor'])
+const parentPrefix = (parentId: string) => `activity:${encodeURIComponent(parentId)}:`
+const callPrefix = (parentId: string, callId: string) => `${parentPrefix(parentId)}${encodeURIComponent(callId)}:`
+
+/** Paginated read-only data for a plugin-owned tool view; no runtime activation. */
+export function readFusionActivity(store: SqliteFusionStore, parentId: string, callId: string, after = -1): FusionActivityPage {
+  if (!Number.isSafeInteger(after) || after < -1) throw new Error('Invalid activity cursor')
+  const rows = store.listDocumentIds(callPrefix(parentId, callId)).map(id => store.readDocument(id)!.value as FusionActivity)
+    .filter(row => row.source.seq > after).sort((a, b) => a.source.seq - b.source.seq)
+  const events = rows.slice(0, 100)
+  const links = store.listDocumentIds(prefix).map(id => store.readDocument(id)!.value as ActivityLink)
+  const link = links.find(row => row.parentId === parentId && row.callId === callId)
+  return { events, cursor: events.at(-1)?.source.seq ?? after, more: rows.length > events.length, done: !link || link.done === true }
+}
+
+/** Old conversations remain readable through the public, non-activating history
+ * API. Correlate accepted message ids, never timing guesses or model narration.
+ * This fallback neither rewrites the old log nor creates a replacement Worker.
+ */
+export async function readHistoricalFusionActivity(ctx: Context, store: SqliteFusionStore,
+  parentId: string, callId: string, after = -1): Promise<FusionActivityPage> {
+  const cached = readFusionActivity(store, parentId, callId, after)
+  const linked = store.listDocumentIds(prefix).some(id => {
+    const row = store.readDocument(id)!.value as ActivityLink
+    return row.parentId === parentId && row.callId === callId
+  })
+  if (linked || !parentId || !callId) return cached
+  const tasks = store.listTaskIds().map(id => store.load(id)!).filter(task => task.parent === parentId)
+  for (const task of tasks) {
+    if (!task.acceptedChild) continue
+    const history = store.events(task.taskId)
+    const prepared = history.find(event => event.type === 'work-order/prepared' && event.causeId === callId)
+    const delivery = store.listDocumentIds(`worker-delivery:${task.taskId}:`).map(id => store.readDocument(id)!.value as
+      { causeId: string; messageId?: string; state: string }).find(row => row.causeId === callId && row.state === 'accepted')
+    const accepted = prepared && history.find(event => event.type === 'child/accepted' && event.seq > prepared.seq)
+    const messageId = delivery?.messageId ?? (accepted?.type === 'child/accepted' ? accepted.payload.messageId : undefined)
+    if (!messageId) continue
+    const [parent, child] = await Promise.all([ctx.sessionQuery.readSession(SessionId(parentId)), ctx.sessionQuery.readSession(SessionId(task.acceptedChild))])
+    if (child.session.parentSession !== parentId) throw new Error('Fusion activity child ownership mismatch')
+    const call = parent.events.find(event => event.type === 'tool/call' && event.data.callId === callId)
+    if (!call || call.type !== 'tool/call' || !['fusion_explore', 'fusion_delegate', 'fusion_rework'].includes(call.data.name)) return cached
+    const start = child.events.find(event => event.type === 'user/message' && event.data.id === messageId)
+    if (!start) return cached
+    const acceptedIds = new Set(tasks.flatMap(item => store.events(item.taskId).flatMap(event =>
+      event.type === 'child/accepted' && event.payload.child === task.acceptedChild ? [event.payload.messageId] : [])))
+    const end = child.events.find(event => event.seq > start.seq && event.type === 'user/message' && acceptedIds.has(event.data.id))?.seq ?? Infinity
+    const calls = new Set<string>()
+    const all: FusionActivity[] = []
+    for (const source of child.events) {
+      if (source.seq <= start.seq) continue
+      if (source.type === 'tool/call' && source.seq < end && visibleTools.has(source.data.name)) calls.add(source.data.callId)
+      else if (source.type !== 'tool/result' || !calls.has(source.data.message.source.callId)) continue
+      if (source.type !== 'tool/call' && source.type !== 'tool/result') continue
+      all.push({ schemaVersion: 1, taskId: task.taskId, childSessionId: task.acceptedChild, parentCallId: callId,
+        turn: call.data.turn, step: call.data.step, anchorSeq: call.seq, source })
+    }
+    const remaining = all.filter(event => event.source.seq > after), events = remaining.slice(0, 100)
+    return { events, cursor: events.at(-1)?.source.seq ?? after, more: remaining.length > events.length,
+      done: task.control.mode === 'completed' || child.events.at(-1)?.type === 'turn/end' }
+  }
+  return cached
+}
+
+/** Copies actual Worker tool events into plugin-owned presentation storage only.
+ * Model history still contains solely the Lead's native messages and reports.
+ * Stored source coordinates make replay/HMR idempotent without executing tools.
+ */
+export class NativeFusionActivity {
+  readonly #dispose: (() => void)[] = []
+  #pending: Promise<void> = Promise.resolve()
+  readonly #seen = new WeakMap<Session, Set<string>>()
+  readonly #calls = new WeakMap<Session, Map<string, FusionActivity>>()
+  readonly errors = new Map<string, string>()
+
+  constructor(readonly ctx: Context, readonly store: SqliteFusionStore) {
+    this.#dispose.push(ctx.on('session/event', (session, event) => {
+      if (!session.header.parentSession) return
+      if (event.type === 'turn/end') { this.#enqueue(() => this.#ended(session)); return }
+      if (event.type !== 'tool/call' && event.type !== 'tool/result') return
+      this.#enqueue(() => this.#mirror(session, event, false))
+    }))
+    this.#dispose.push(ctx.on('agent/created', ({ agent }) => {
+      this.#replay(agent.session)
+      for (const child of ctx.sessions.list()) if (child.header.parentSession === agent.id) this.#replay(child)
+      return undefined
+    }))
+    for (const session of ctx.sessions.list()) this.#replay(session)
+  }
+
+  /** Called before each native delivery. No inference, dispatch or approval. */
+  link(parent: Session, childId: string, taskId: string, callId: string): void {
+    const call = parent.snapshotEvents().find(event => event.type === 'tool/call' && event.data.callId === callId)
+    if (!call || call.type !== 'tool/call') return // Direct programmatic control has no native UI call to own a row.
+    const id = `${prefix}${childId}:${call.seq}`
+    if (this.store.readDocument(id)) return
+    this.store.writeDocument(id, 0, {
+      parentId: parent.id, childId, taskId, callId, turn: call.data.turn, step: call.data.step,
+      anchorSeq: call.seq, fromSeq: this.ctx.sessions.get(SessionId(childId))?.seq ?? null,
+    } satisfies ActivityLink)
+  }
+
+  #enqueue(action: () => void): void {
+    // Session.append forbids reentry from event observers, including same-session
+    // parent callbacks. Awaited microtasks run after the native append boundary.
+    this.#pending = this.#pending.then(action).catch(error => {
+      this.errors.set('presentation', String(error))
+      this.ctx.logger.warn('Fusion activity presentation failed: %s', String(error))
+    })
+  }
+
+  #replay(session: Session): void {
+    if (!session.header.parentSession) return
+    this.#enqueue(() => {
+      for (const event of session.snapshotEvents()) {
+        if (event.type === 'tool/call' || event.type === 'tool/result') this.#mirror(session, event, true)
+        if (event.type === 'turn/end') this.#ended(session, event.seq, false)
+      }
+    })
+  }
+
+  #ended(child: Session, throughSeq: number = child.seq, live = true): void {
+    for (const id of this.store.listDocumentIds(`${prefix}${child.id}:`)) {
+      const row = this.store.readDocument(id)!, link = row.value as ActivityLink
+      if ((link.fromSeq === null ? live : link.fromSeq <= throughSeq) && !link.done) this.store.writeDocument(id, row.revision, { ...link, done: true })
+    }
+  }
+
+  #mirror(child: Session, event: SessionEvent<'tool/call'> | SessionEvent<'tool/result'>, replay: boolean): void {
+    const parent = child.header.parentSession && this.ctx.sessions.get(child.header.parentSession)
+    if (!parent) return
+    let seen = this.#seen.get(parent), calls = this.#calls.get(parent)
+    if (!seen || !calls) {
+      seen = new Set(); calls = new Map()
+      for (const id of this.store.listDocumentIds(parentPrefix(parent.id))) {
+        const activity = this.store.readDocument(id)!.value as FusionActivity
+        seen.add(`${activity.childSessionId}:${activity.source.seq}`)
+        if (activity.source.type === 'tool/call') calls.set(`${activity.childSessionId}:${activity.source.data.callId}`, activity)
+      }
+      this.#seen.set(parent, seen); this.#calls.set(parent, calls)
+    }
+    const key = `${child.id}:${event.seq}`
+    if (seen.has(key)) return
+    const sourceCallId = event.type === 'tool/call' ? event.data.callId : event.data.message.source.callId
+    const callKey = `${child.id}:${sourceCallId}`
+    let origin: Omit<FusionActivity, 'source'> | undefined = calls.get(callKey)
+    if (event.type === 'tool/call') {
+      if (!visibleTools.has(event.data.name)) return
+      const links = this.store.listDocumentIds(`${prefix}${child.id}:`).map(id => ({ id, ...this.store.readDocument(id)! }))
+        .filter(row => (row.value as ActivityLink).parentId === parent.id)
+        .sort((a, b) => (b.value as ActivityLink).anchorSeq - (a.value as ActivityLink).anchorSeq)
+      const row = links.find(row => {
+        const link = row.value as ActivityLink
+        return link.fromSeq === null ? !replay : event.seq >= link.fromSeq
+      })
+      if (!row) return // Historical, pre-feature calls are not fabricated.
+      let link = row.value as ActivityLink
+      if (link.fromSeq === null) {
+        link = { ...link, fromSeq: event.seq }
+        this.store.writeDocument(row.id, row.revision, link)
+      }
+      origin = { schemaVersion: 1, taskId: link.taskId, childSessionId: child.id,
+        parentCallId: link.callId, turn: link.turn, step: link.step,
+        // Place all calls below the owning delivery, in original source order.
+        anchorSeq: link.anchorSeq + 0.5 - 0.5 / (event.seq + 2) }
+    }
+    if (!origin) return // Results never acquire an invented call head.
+    const activity = { ...origin, source: event } satisfies FusionActivity
+    const id = `${callPrefix(parent.id, origin.parentCallId)}${String(event.seq).padStart(12, '0')}`
+    if (!this.store.readDocument(id)) this.store.writeDocument(id, 0, activity)
+    seen.add(key)
+    if (event.type === 'tool/call') calls.set(callKey, activity)
+  }
+
+  async flush(): Promise<void> { await this.#pending }
+
+  async close(): Promise<void> {
+    for (const dispose of this.#dispose.splice(0).reverse()) dispose()
+    await this.flush()
+  }
+}

package/src/host/native-approvals.ts

@@ -0,0 +1,196 @@
+import type { Context } from '@deepseek-ai/cordis'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import { SessionId as NativeSessionId } from '@deepseek-ai/dsh-session'
+import type { ToolExecution } from '@deepseek-ai/dsh-tools'
+import type { ApprovalOutcome } from '@deepseek-ai/dsh-user-approval'
+import type { ArtifactRef, LogicalApproval, Role, TaskId } from '../contracts.js'
+import { OperationId, SessionId } from '../contracts.js'
+import { digestOf } from '../digest.js'
+import type { SqliteFusionStore } from '../task/sqlite-store.js'
+import type { TaskState } from '../task/state.js'
+import type { SessionBinding } from './bindings.js'
+import { snapshotWorkspace } from './workspace.js'
+
+type Owner = { binding: SessionBinding; role: Role }
+interface Callbacks {
+  owner(agent: Agent): Owner | undefined
+  state(id: TaskId): TaskState
+  pending(id: TaskId, approval: LogicalApproval): void
+  answered(id: TaskId, approvalId: string, state: 'approved' | 'rejected' | 'withdrawn'): void
+  failed(agent: Agent, error: unknown): void
+}
+interface ApprovalRecord {
+  schemaVersion: 1
+  logical: LogicalApproval
+  agentId: string
+  role: Role
+  toolName: string
+  callId: string
+  rootCallId: string
+  askedSeq: number
+  askedAt: string
+  processId: number
+  scopeDigest: string
+  evidence: ArtifactRef
+  state: 'pending' | 'decided' | 'withdrawn-after-inspection'
+  nativeOutcome?: ApprovalOutcome
+  decidedSeq?: number
+  scopeRejection?: string
+  effect?: 'settled' | 'failed'
+  inspectionEvidence?: string
+  reissuedAs?: string
+  previousRequest?: string
+}
+
+/** Observe native decisions; never answer on the user's behalf or replay a grant. */
+export class NativeApprovals {
+  readonly #calls = new Map<Agent, Map<string, Readonly<ToolExecution>>>()
+  readonly #requests = new Map<string, string>()
+  constructor(readonly ctx: Context, readonly store: SqliteFusionStore, readonly callbacks: Callbacks) {}
+
+  install(): () => void {
+    const disposers = [
+      this.ctx.on('tools/pre-execute', async (exec, next) => {
+        if (exec.agent && this.callbacks.owner(exec.agent)) {
+          let calls = this.#calls.get(exec.agent)
+          if (!calls) this.#calls.set(exec.agent, calls = new Map())
+          calls.set(exec.callId, exec)
+        }
+        return next()
+      }, { prepend: true }),
+      this.ctx.on('session/event', (session, event) => {
+        if (event.type !== 'approval/asked' && event.type !== 'approval/decided') return
+        const agent = this.ctx.agents.get(NativeSessionId(session.id)), owner = agent && this.callbacks.owner(agent)
+        if (!agent || !owner) return
+        try {
+          if (event.type === 'approval/asked') this.#asked(agent, owner, event.data, event.seq)
+          else this.#decided(owner, event.data.id, event.data.outcome, event.seq)
+        } catch (error) { this.callbacks.failed(agent, error) }
+      }),
+      this.ctx.on('approval/request', async (request, next) => {
+        const owner = this.callbacks.owner(request.agent)
+        if (!owner) return next()
+        // This is deny-only middleware around the native answerer. The audit
+        // event already exists; a missing projection must not permit execution.
+        const key = this.#requests.get(this.#callKey(request.agent.id, request.callId ?? ''))
+        if (!key) return 'unavailable'
+        const outcome = await next() // deliberately no timer around human input
+        if (outcome !== 'allowed-once') return outcome
+        try {
+          const row = this.#read(key), exec = this.#calls.get(request.agent)?.get(row.callId)
+          const current = this.callbacks.state(owner.binding.taskId)
+          const control = current.control
+          if (!exec || request.signal?.aborted || control.mode !== 'running' || control.recovering
+            || control.outcomeUnknown || control.budgetBlocked
+            || row.scopeDigest !== this.#scope(request.agent, owner, exec).digest) {
+            this.#write(key, { ...row, scopeRejection: 'The action, workspace, policy or task control changed while approval was pending' })
+            return 'rejected'
+          }
+          return outcome
+        } catch (error) { this.callbacks.failed(request.agent, error); return 'unavailable' }
+      }, { prepend: true }),
+      this.ctx.on('tools/result', (exec, result) => {
+        if (!exec.agent) return
+        const key = this.#requests.get(this.#callKey(exec.agent.id, exec.callId))
+        if (key) {
+          try {
+            const row = this.#read(key)
+            this.#write(key, { ...row,
+              logical: row.nativeOutcome === 'allowed-once' ? { ...row.logical, state: 'consumed' } : row.logical,
+              effect: result.isError ? 'failed' : 'settled' })
+          }
+          catch (error) { this.callbacks.failed(exec.agent, error) }
+          this.#requests.delete(this.#callKey(exec.agent.id, exec.callId))
+        }
+        this.#calls.get(exec.agent)?.delete(exec.callId)
+      }),
+    ]
+    return () => { for (const dispose of disposers.reverse()) dispose(); this.#calls.clear(); this.#requests.clear() }
+  }
+
+  /** Caller must first stop/release both native Agents and inspect uncertain effects. */
+  reconcile(taskId: TaskId, evidence: string): void {
+    if (!evidence) throw new Error('Approval recovery requires inspection evidence')
+    for (const key of this.store.listDocumentIds(`native-approval:${taskId}:`)) {
+      const row = this.#read(key)
+      if (row.state !== 'pending') continue
+      const agent = this.ctx.agents.get(NativeSessionId(row.agentId))
+      if (agent && agent.status !== 'idle' || [...this.#requests.values()].includes(key)) {
+        throw new Error('The native approval is still live; settle it before recovery')
+      }
+      if (row.processId !== process.pid) {
+        try { process.kill(row.processId, 0); throw new Error('The recorded approval process is still live') }
+        catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ESRCH') throw error }
+      }
+      // This withdraws the plugin's logical wait after explicit inspection.
+      // It does not fabricate a native decision or execute the interrupted call.
+      if (this.callbacks.state(taskId).pendingApprovalIds.includes(row.logical.id)) {
+        this.callbacks.answered(taskId, row.logical.id, 'withdrawn')
+      }
+      this.#write(key, { ...row, logical: { ...row.logical, state: 'withdrawn' }, state: 'withdrawn-after-inspection', inspectionEvidence: evidence })
+    }
+  }
+
+  #asked(agent: Agent, owner: Owner, asked: { id: string; toolName: string; callId?: string; reason?: string }, seq: number): void {
+    const exec = asked.callId && this.#calls.get(agent)?.get(asked.callId)
+    if (!exec || exec.name !== asked.toolName) throw new Error('Native approval has no matching immutable tool execution')
+    const key = `native-approval:${owner.binding.taskId}:${asked.id}`
+    if (this.store.readDocument(key)) throw new Error('Native approval identity was reused')
+    const scope = this.#scope(agent, owner, exec), state = this.callbacks.state(owner.binding.taskId)
+    const previousRequest = this.store.listDocumentIds(`native-approval:${owner.binding.taskId}:`).find(id => {
+      const prior = this.#read(id)
+      return prior.state === 'withdrawn-after-inspection' && !prior.reissuedAs && prior.scopeDigest === scope.digest
+    })
+    const prior = previousRequest && this.#read(previousRequest)
+    const logical: LogicalApproval = {
+      id: prior ? prior.logical.id : `native:${asked.id}`, taskId: owner.binding.taskId, revision: state.revision,
+      operationId: prior ? prior.logical.operationId : state.currentWorkOrder?.operationId ?? OperationId(`native-tool:${agent.id}:${exec.callId}`),
+      nativeRequestId: asked.id, argsDigest: scope.argsDigest, snapshot: scope.snapshot.id,
+      permissionPolicyDigest: scope.policyDigest, state: 'pending',
+      requestingAgent: SessionId(agent.id), toolName: exec.name, callId: exec.callId, role: owner.role,
+      ...(asked.reason ? { reason: asked.reason } : {}),
+    }
+    const evidence = this.store.putArtifact(owner.binding.taskId, Buffer.from(JSON.stringify({
+      nativeRequestId: asked.id, toolName: exec.name, arguments: exec.arguments,
+      snapshot: scope.snapshot, policy: scope.policy,
+    })), 'application/vnd.dsh-fusion.approval-scope+json')
+    this.store.writeDocument(key, 0, { schemaVersion: 1, logical, agentId: agent.id, role: owner.role,
+      toolName: exec.name, callId: exec.callId, rootCallId: exec.rootCallId, askedSeq: seq,
+      askedAt: new Date().toISOString(), processId: process.pid, scopeDigest: scope.digest,
+      evidence, state: 'pending', ...(previousRequest ? { previousRequest } : {}) } satisfies ApprovalRecord)
+    this.callbacks.pending(owner.binding.taskId, logical)
+    if (prior && previousRequest) this.#write(previousRequest, { ...prior, reissuedAs: key })
+    this.#requests.set(this.#callKey(agent.id, exec.callId), key)
+  }
+
+  #decided(owner: Owner, nativeId: string, outcome: ApprovalOutcome, seq: number): void {
+    const key = `native-approval:${owner.binding.taskId}:${nativeId}`, row = this.#read(key)
+    if (row.state !== 'pending') throw new Error('Native approval already settled')
+    // Audit outcomes do not identify a human vs. automated answerer. Leave
+    // decisionBy unknown rather than attributing an auto-review to the user.
+    const state = outcome === 'allowed-once' ? 'approved' : outcome === 'cancelled' ? 'withdrawn' : 'rejected'
+    this.callbacks.answered(owner.binding.taskId, row.logical.id, state)
+    this.#write(key, { ...row, logical: { ...row.logical, state }, state: 'decided', nativeOutcome: outcome, decidedSeq: seq })
+  }
+
+  #scope(agent: Agent, owner: Owner, exec: Readonly<ToolExecution>) {
+    const state = this.callbacks.state(owner.binding.taskId), service = agent.ctx.get('approval') ?? this.ctx.get('approval')
+    if (!service || !agent.session.header.cwd) throw new Error('Native approval policy or workspace is unavailable')
+    const snapshot = snapshotWorkspace(agent.session.header.cwd)
+    const policy = { scope: 'native-approval-and-frozen-fusion-policy',
+      nativeApproval: service.overrideOf(agent.session) ?? service.config.policy ?? 'ask',
+      profileDigest: owner.binding.profile.digest, allowedPaths: state.currentWorkOrder?.allowedPaths ?? null }
+    const argsDigest = digestOf({ tool: exec.name, arguments: exec.arguments }), policyDigest = digestOf(policy)
+    return { snapshot, policy, argsDigest, policyDigest,
+      digest: digestOf({ taskId: state.taskId, revision: state.revision, agentId: agent.id,
+        role: owner.role, argsDigest, snapshot: snapshot.id, policyDigest }) }
+  }
+
+  #callKey(agent: string, call: string): string { return JSON.stringify([agent, call]) }
+  #read(key: string): ApprovalRecord {
+    const row = this.store.readDocument(key)?.value as ApprovalRecord | undefined
+    if (!row || row.schemaVersion !== 1 || !row.logical || !row.scopeDigest) throw new Error('Native approval journal requires reconciliation')
+    return row
+  }
+  #write(key: string, row: ApprovalRecord): void { this.store.writeDocument(key, this.store.readDocument(key)!.revision, row) }
+}

package/src/host/native-auxiliary.ts

@@ -0,0 +1,19 @@
+import type { GenerateOptions } from '@deepseek-ai/dsh-llm'
+import type { Digest, Role, TaskId } from '../contracts.js'
+
+export interface AuxiliaryRequest {
+  purpose: 'cache-keepalive'
+  taskId: TaskId
+  sessionId: string
+  profileDigest: Digest
+  role: Role
+  seriesId: string
+  iteration: number
+}
+
+/** Plugin-local identity: do not widen or misuse the Host's purpose enum. */
+export class NativeAuxiliaryRequests {
+  readonly #requests = new WeakMap<GenerateOptions, Readonly<AuxiliaryRequest>>()
+  tag(request: GenerateOptions, metadata: AuxiliaryRequest): void { this.#requests.set(request, Object.freeze(metadata)) }
+  get(request: GenerateOptions): Readonly<AuxiliaryRequest> | undefined { return this.#requests.get(request) }
+}