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

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

@@ -0,0 +1,186 @@
+/**
+ * Bounded data import/export for the Bot data tools.
+ *
+ * Import parses CSV/TSV or JSON/NDJSON text — the text already came from a
+ * bounded controlled read (BotLibrary) or bounded inline content, never from
+ * an OS path or URL. It infers a light column kind so SQLite can hold numbers
+ * as numbers, and it enforces row/column/byte caps so one file cannot exhaust
+ * memory. Export writes CSV that neutralises spreadsheet formula injection.
+ */
+
+import { DATA_LIMITS, DataFailure, dataError } from './bot-data-surface.mjs'
+
+const fail = (code, message, extra = {}) => { throw new DataFailure(dataError(code, message, extra)) }
+
+/** Column kind inferred from parsed values; SQLite affinity is chosen from it. */
+const SQLITE_TYPE = { integer: 'INTEGER', real: 'REAL', boolean: 'INTEGER', text: 'TEXT', null: 'TEXT' }
+
+const normalizeHeader = (raw, index, seen) => {
+  let name = String(raw ?? '').trim()
+  if (name === '') name = `column_${index + 1}`
+  let unique = name
+  for (let n = 2; seen.has(unique.toLowerCase()); n++) unique = `${name}_${n}`
+  seen.add(unique.toLowerCase())
+  return unique
+}
+
+/**
+ * Parse RFC-4180-ish delimited text. Handles quoted fields with embedded
+ * delimiters, newlines and doubled quotes. Returns { columns, rows }.
+ */
+export function parseDelimited(text, { delimiter = ',', header = true } = {}) {
+  const rows = []
+  let field = ''
+  let row = []
+  let inQuotes = false
+  let i = 0
+  const n = text.length
+  const pushField = () => { row.push(field); field = '' }
+  const pushRow = () => { pushField(); if (row.length !== 1 || row[0] !== '') rows.push(row); row = [] }
+  while (i < n) {
+    const ch = text[i]
+    if (inQuotes) {
+      if (ch === '"') { if (text[i + 1] === '"') { field += '"'; i += 2; continue } inQuotes = false; i++; continue }
+      field += ch; i++; continue
+    }
+    if (ch === '"') { inQuotes = true; i++; continue }
+    if (ch === delimiter) { pushField(); i++; continue }
+    if (ch === '\r') { if (text[i + 1] === '\n') i++; pushRow(); i++; continue }
+    if (ch === '\n') { pushRow(); i++; continue }
+    field += ch; i++
+  }
+  pushRow()
+  if (inQuotes) fail('import_failed', 'Unterminated quoted field in the input.')
+  if (!rows.length) fail('import_failed', 'The input has no rows.')
+
+  const seen = new Set()
+  let columns
+  let dataRows
+  if (header) {
+    columns = rows[0].map((cell, index) => normalizeHeader(cell, index, seen))
+    dataRows = rows.slice(1)
+  } else {
+    const width = rows[0].length
+    columns = Array.from({ length: width }, (_, index) => normalizeHeader(`column_${index + 1}`, index, seen))
+    dataRows = rows
+  }
+  return finish(columns, dataRows, delimiter)
+}
+
+/** Parse JSON (array of objects, single object) or NDJSON (one object per line). */
+export function parseJsonText(text) {
+  const trimmed = text.trim()
+  let records
+  let whole = null
+  if (trimmed.startsWith('[') || trimmed.startsWith('{')) {
+    try { whole = JSON.parse(text) } catch { whole = null }
+  }
+  if (whole !== null) {
+    records = Array.isArray(whole) ? whole : [whole]
+    if (Array.isArray(whole) && whole.length && whole.every(item => typeof item !== 'object' || item === null || Array.isArray(item))) {
+      // An array of scalars: one column named "value".
+      return finish(['value'], whole.map(item => [coerce(item)]))
+    }
+  } else {
+    // NDJSON: one JSON value per line.
+    records = []
+    for (const [index, line] of text.split(/\r?\n/).entries()) {
+      const t = line.trim()
+      if (t === '') continue
+      try { records.push(JSON.parse(t)) } catch (error) { fail('import_failed', `NDJSON line ${index + 1} parse failed: ${error.message}`) }
+    }
+  }
+  if (!records.length) fail('import_failed', 'The input has no records.')
+  const objects = records.filter(record => record !== null && typeof record === 'object' && !Array.isArray(record))
+  if (!objects.length) fail('import_failed', 'The input has no JSON objects.')
+  const seen = new Set()
+  // column order = first-seen key order; original key kept for lookup, lower for dedupe.
+  const columnKeys = []
+  const columnLower = new Set()
+  for (const object of objects) {
+    for (const key of Object.keys(object)) {
+      const lower = key.toLowerCase()
+      if (columnLower.has(lower)) continue
+      columnLower.add(lower)
+      columnKeys.push({ key, name: normalizeHeader(key, columnKeys.length, seen) })
+    }
+  }
+  const columns = columnKeys.map(entry => entry.name)
+  const dataRows = objects.map(object => columnKeys.map(entry => (object[entry.key] === undefined ? null : normalizeCell(object[entry.key]))))
+  return finish(columns, dataRows)
+}
+
+const coerce = value => (value === null || value === undefined ? null : typeof value === 'object' ? JSON.stringify(value) : value)
+
+const normalizeCell = value => (value === undefined ? null : coerce(value))
+
+/** Infer each column's final kind across all rows, then convert every cell to it. */
+function finish(columns, dataRows, delimiter) {
+  if (columns.length > DATA_LIMITS.loadMaxCols) fail('source_unsupported', `More than ${DATA_LIMITS.loadMaxCols} columns.`, { hint: 'Select fewer columns before loading.' })
+  if (dataRows.length > DATA_LIMITS.loadMaxRows) fail('source_unsupported', `More than ${DATA_LIMITS.loadMaxRows} rows.`, { hint: 'Filter or sample the data before loading.' })
+
+  // Pass 1: classify each raw value and widen the column kind.
+  const kinds = new Array(columns.length).fill('null')
+  const cellKinds = dataRows.map(row => row.map(raw => {
+    let kind
+    if (raw === '' || raw === null || raw === undefined) kind = 'null'
+    else if (typeof raw === 'boolean') kind = 'boolean'
+    else if (typeof raw === 'number') kind = Number.isInteger(raw) ? 'integer' : 'real'
+    else if (typeof raw === 'string' && /^\s*-?\d+\s*$/.test(raw)) kind = 'integer'
+    else if (typeof raw === 'string' && /^\s*-?(\d+\.\d*|\.\d+|\d+)([eE][+-]?\d+)?\s*$/.test(raw)) kind = 'real'
+    else kind = 'text'
+    return kind
+  }))
+  for (const row of cellKinds) row.forEach((kind, c) => { kinds[c] = widen(kinds[c], kind) })
+
+  // Pass 2: convert each raw cell to its column's final kind.
+  const rows = dataRows.map((row, r) => row.map((raw, c) => {
+    const kind = kinds[c]
+    if (raw === '' || raw === null || raw === undefined) return null
+    if (kind === 'integer') { if (typeof raw === 'boolean') return raw ? 1 : 0; return typeof raw === 'number' ? raw : Number(String(raw).trim()) }
+    if (kind === 'real') return typeof raw === 'number' ? raw : Number(String(raw).trim())
+    if (kind === 'boolean') return raw ? 1 : 0
+    return typeof raw === 'object' ? JSON.stringify(raw) : String(raw)
+  }))
+  return { columns, rows, kinds, sqlTypes: kinds.map(kind => SQLITE_TYPE[kind]) }
+}
+
+/** Widen a column kind as more values arrive: null < integer < real < text. */
+const RANK = { null: 0, boolean: 1, integer: 1, real: 2, text: 3 }
+const widen = (a, b) => {
+  if (a === b) return a
+  if (a === 'null') return b === 'boolean' ? 'integer' : b
+  if (b === 'null') return a
+  if ((a === 'integer' && b === 'boolean') || (a === 'boolean' && b === 'integer')) return 'integer'
+  if (RANK[a] >= RANK[b]) return a === 'integer' && b === 'real' ? 'real' : a
+  return b === 'integer' && a === 'real' ? 'real' : b
+}
+
+/**
+ * Encode one CSV field: neutralise spreadsheet formula injection, then quote
+ * when the value contains a delimiter, quote, newline or edge whitespace.
+ * A leading `-` is only neutralised when the value is not a plain number.
+ */
+export function csvField(value) {
+  let s = value === null || value === undefined ? '' : String(value)
+  const dangerous = /^[=+@\t\r]/.test(s) || (/^-/.test(s) && !/^\s*-?\d+(\.\d+)?([eE][+-]?\d+)?\s*$/.test(s))
+  if (dangerous) s = `'${s}`
+  if (/[",\n\r]/.test(s) || s !== s.trim()) s = `"${s.replace(/"/g, '""')}"`
+  return s
+}
+
+/** Encode rows (array of cell arrays) to CSV text with a header row. */
+export function toCsv(columns, rows) {
+  const lines = [columns.map(column => csvField(column.name ?? column)).join(',')]
+  for (const row of rows) lines.push(row.map(cell => csvField(cell)).join(','))
+  return `${lines.join('\r\n')}\r\n`
+}
+
+/** Strip NUL and cap bytes of an exported payload; never fabricate content. */
+export function boundExport(text, maxBytes = DATA_LIMITS.exportMaxBytes) {
+  const bytes = Buffer.byteLength(text)
+  if (bytes <= maxBytes) return { text, bytes, truncated: false }
+  // Cut on a UTF-8-safe boundary.
+  const buffer = Buffer.from(text, 'utf8').subarray(0, maxBytes)
+  return { text: buffer.toString('utf8'), bytes: buffer.length, truncated: true }
+}

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

@@ -0,0 +1,195 @@
+/**
+ * The SQL gate: what a Bot may run against its own database.
+ *
+ * This is a tokenizer-based statement classifier, NOT a keyword regex. It walks
+ * the statement once, masking string literals, comments and quoted identifiers
+ * so a keyword inside a string can never change the verdict, and it reads the
+ * verb after a WITH clause so a `WITH … DELETE` never passes as a read. The
+ * defence-in-depth (extension loading disabled, no readfile/writefile, ATTACH
+ * refused here) is proven by execution in tests/security-negative, not asserted.
+ *
+ * Only SELECT-like reads, and — when the caller allows it — `CREATE … AS`
+ * (TABLE|VIEW), run. Everything else (INSERT/UPDATE/DELETE/DROP/ALTER/ATTACH/
+ * DETACH/PRAGMA/VACUUM/BEGIN/…) is refused. One statement per call.
+ *
+ * Ported and narrowed from OpenMausBot server/data/tools.ts (commit 1bc4749)
+ * for SQLite: no dollar-quoting, no non-nesting block comments, no E-strings.
+ */
+
+import { DataFailure, dataError } from './bot-data-surface.mjs'
+
+const fail = (code, message, extra = {}) => { throw new DataFailure(dataError(code, message, extra)) }
+
+const READ_VERBS = new Set(['SELECT', 'WITH', 'VALUES', 'EXPLAIN'])
+const MATERIALISABLE = new Set(['SELECT', 'WITH', 'VALUES'])
+
+/** A token: word (upper-cased text), ident (quoted), block (parenthesised), punct. */
+const tokenize = sql => {
+  const tokens = []
+  let statements = 1
+  let ended = false
+  let depth = 0
+  let i = 0
+  const n = sql.length
+  const push = (kind, raw, text = raw) => { if (depth === 0) tokens.push({ kind, raw, text }) }
+  while (i < n) {
+    const ch = sql[i]
+    const next = sql[i + 1]
+    if (ch === '-' && next === '-') { const end = sql.slice(i).search(/[\n\r]/); i = end === -1 ? n : i + end + 1; continue }
+    if (ch === '/' && next === '*') { i = blockCommentEnd(sql, i); continue }
+    if (ch === ';') { ended = true; i++; continue }
+    if (ended && /\S/.test(ch)) { statements++; ended = false }
+    if (ch === "'") { push('word', "'…'"); i = literalEnd(sql, i); continue }
+    if (ch === '"' || ch === '`') { const j = quotedEnd(sql, i, ch); push('ident', sql.slice(i, j)); i = j; continue }
+    if (ch === '[') { const j = bracketEnd(sql, i); push('ident', sql.slice(i, j)); i = j; continue }
+    if (ch === '(') { push('block', '(…)'); depth++; i++; continue }
+    if (ch === ')') { depth = Math.max(0, depth - 1); i++; continue }
+    if (/[A-Za-z_]/.test(ch)) { let j = i + 1; while (j < n && /[A-Za-z0-9_$]/.test(sql[j])) j++; push('word', sql.slice(i, j), sql.slice(i, j).toUpperCase()); i = j; continue }
+    if (ch === ',') { push('punct', ','); i++; continue }
+    i++
+  }
+  return { tokens, statements }
+}
+
+/** SQLite block comments do not nest. */
+const blockCommentEnd = (sql, start) => {
+  const end = sql.indexOf('*/', start + 2)
+  if (end === -1) fail('invalid_input', 'Unterminated comment.')
+  return end + 2
+}
+
+/** A single-quoted literal: '' escapes a quote. */
+const literalEnd = (sql, quote) => {
+  for (let j = quote + 1; j < sql.length; j++) {
+    if (sql[j] !== "'") continue
+    if (sql[j + 1] === "'") { j++; continue }
+    return j + 1
+  }
+  fail('invalid_input', 'Unterminated string literal.')
+}
+
+/** A double-quoted or backtick identifier; the quote character doubles to escape. */
+const quotedEnd = (sql, start, quote) => {
+  for (let j = start + 1; j < sql.length; j++) {
+    if (sql[j] !== quote) continue
+    if (sql[j + 1] === quote) { j++; continue }
+    return j + 1
+  }
+  fail('invalid_input', 'Unterminated quoted identifier.')
+}
+
+/** A [bracketed] identifier (SQLite/MSSQL style); ]] escapes a bracket. */
+const bracketEnd = (sql, start) => {
+  for (let j = start + 1; j < sql.length; j++) {
+    if (sql[j] === ']') { if (sql[j + 1] === ']') { j++; continue } return j + 1 }
+  }
+  fail('invalid_input', 'Unterminated bracketed identifier.')
+}
+
+export const classifySql = sql => {
+  if (typeof sql !== 'string' || sql.trim() === '') fail('invalid_input', 'The statement is empty.')
+  const { tokens, statements } = tokenize(sql)
+  if (statements > 1) fail('invalid_input', 'One statement per call.', { hint: 'Send each statement in its own data_sql call.' })
+  if (!tokens.length || tokens[0].kind !== 'word') fail('invalid_input', 'The statement is empty.')
+  return classifyTokens(tokens)
+}
+
+const classifyTokens = tokens => {
+  let i = 0
+  let verb = tokens[0].text
+  const withClause = verb === 'WITH'
+  if (withClause) {
+    // WITH [RECURSIVE] name [(cols)] AS (body) [, …] <verb>
+    i = 1
+    if (tokens[i]?.text === 'RECURSIVE') i++
+    for (;;) {
+      while (i < tokens.length && tokens[i].kind !== 'block') i++
+      i++
+      if (tokens[i]?.text === 'AS') { while (i < tokens.length && tokens[i].kind !== 'block') i++; i++ }
+      if (tokens[i]?.kind === 'punct') { i++; continue }
+      break
+    }
+    verb = tokens[i]?.kind === 'word' ? tokens[i].text : ''
+    if (!verb) fail('invalid_input', 'A WITH clause needs a statement after it.')
+    if (verb === 'WITH') return { kind: 'refused', verb }
+  }
+  if (verb === 'EXPLAIN') {
+    // EXPLAIN shows the plan; EXPLAIN QUERY PLAN too. Neither runs the statement.
+    return { kind: 'read', materialisable: false }
+  }
+  if (READ_VERBS.has(verb)) return { kind: 'read', materialisable: withClause || MATERIALISABLE.has(verb) }
+  if (verb === 'CREATE') {
+    let j = i + 1
+    if (tokens[j]?.text === 'TEMP' || tokens[j]?.text === 'TEMPORARY') j++
+    // CREATE [TEMP] [OR REPLACE] TABLE|VIEW [IF NOT EXISTS] name AS select
+    const orReplace = tokens[j]?.text === 'OR' && tokens[j + 1]?.text === 'REPLACE'
+    if (orReplace) j += 2
+    const object = tokens[j]?.text
+    if (object !== 'TABLE' && object !== 'VIEW') return { kind: 'refused', verb: `CREATE ${object ?? ''}`.trim() }
+    j++
+    if (tokens[j]?.text === 'IF' && tokens[j + 1]?.text === 'NOT' && tokens[j + 2]?.text === 'EXISTS') j += 3
+    const nameParts = []
+    while (j < tokens.length && tokens[j].kind !== 'block' && tokens[j].text !== 'AS') { nameParts.push(tokens[j].raw.replace(/\.$/, '')); j++ }
+    if (tokens[j]?.kind === 'block') j++
+    if (tokens[j]?.text !== 'AS' || !nameParts.length) return { kind: 'refused', verb: `CREATE ${object}` }
+    return { kind: 'create', target: nameParts.join('.'), object: object.toLowerCase(), orReplace }
+  }
+  return { kind: 'refused', verb }
+}
+
+/** Throws write_refused for anything but a read (and, when allowed, a CREATE … AS). */
+export const gateSql = (sql, { allowCreate = false } = {}) => {
+  const kind = classifySql(sql)
+  if (kind.kind === 'refused') {
+    throw new DataFailure(dataError('write_refused', `${kind.verb} is not allowed here.`, {
+      sql,
+      hint: allowCreate
+        ? 'Only SELECT-like statements and CREATE [OR REPLACE] TABLE|VIEW … AS … run here. Load data with data_load; export with data_export.'
+        : 'Only SELECT-like statements run here.',
+    }))
+  }
+  if (kind.kind === 'create' && !allowCreate) {
+    throw new DataFailure(dataError('write_refused', 'CREATE is not allowed here.', { sql, hint: 'Run CREATE TABLE … AS with data_sql, then show or export the table.' }))
+  }
+  return kind
+}
+
+const CELL_CHARS_MAX = 4000
+
+/** Trim a cell's text and bound the result by rows and bytes. */
+export function boundRows(rows, maxRows, maxBytes) {
+  let truncated = rows.length > maxRows
+  let kept = rows.slice(0, maxRows).map(row => row.map(cell => (typeof cell === 'string' && cell.length > CELL_CHARS_MAX ? `${cell.slice(0, CELL_CHARS_MAX)}…` : cell)))
+  while (kept.length && Buffer.byteLength(JSON.stringify(kept)) > maxBytes) {
+    kept = kept.slice(0, Math.max(0, kept.length - Math.max(1, Math.ceil(kept.length / 10))))
+    truncated = true
+  }
+  return { rows: kept, truncated }
+}
+
+const trimSample = sample => sample?.slice(0, 3).map(value => (value.length > 60 ? `${value.slice(0, 60)}…` : value))
+
+/** Bound a column list by count and bytes, degrading to name+type under pressure. */
+export function boundColumns(columns, maxBytes, columnsMax = 100) {
+  let truncated = columns.length > columnsMax
+  let kept = truncated
+    ? columns.map(({ name, type }) => ({ name, type }))
+    : columns.map(column => ({ ...column, ...(column.sample ? { sample: trimSample(column.sample) } : {}) }))
+  const size = () => Buffer.byteLength(JSON.stringify(kept))
+  if (size() > maxBytes) { kept = kept.map(({ sample: _sample, ...rest }) => rest); truncated = true }
+  if (size() > maxBytes) kept = kept.map(({ min: _min, max: _max, ...rest }) => rest)
+  if (size() > maxBytes) kept = kept.map(({ name, type }) => ({ name, type }))
+  while (kept.length && size() > maxBytes) kept = kept.slice(0, Math.max(0, kept.length - Math.max(1, Math.ceil(kept.length / 10))))
+  return { columns: kept, truncated }
+}
+
+/** Map an engine error to a structured DataError; a killed child reads as cancelled/timeout. */
+export function toDataError(error, sql, { aborted = false } = {}) {
+  if (error instanceof DataFailure) return { ...error.error, ...(sql && !error.error.sql ? { sql } : {}) }
+  const message = error instanceof Error ? error.message : String(error)
+  if (aborted) return { code: 'cancelled', message: 'The statement was cancelled.', ...(sql ? { sql } : {}) }
+  if (/timed out|timeout|SIGKILL|killed/i.test(message)) return { code: 'timeout', message, retryable: true, ...(sql ? { sql } : {}) }
+  if (/interrupt/i.test(message)) return { code: 'cancelled', message: 'The statement was cancelled.', ...(sql ? { sql } : {}) }
+  const line = /\bLINE (\d+):/.exec(message)
+  return { code: 'sql_error', message, ...(sql ? { sql } : {}), ...(line ? { line: Number(line[1]) } : {}) }
+}

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

@@ -0,0 +1,144 @@
+/**
+ * The Data surface for the model-router Bot runtime: what the tools, the
+ * engine, the fixed worker and the panel agree on. One SQLite database per
+ * Bot, addressed only by a validated Bot id the Host derives from committed
+ * state — never from a model argument.
+ *
+ * This mirrors OpenMausBot's `shared/data-surface.ts` shape (commit 1bc4749)
+ * so the parent session can later swap the SQLite engine for DuckDB without
+ * changing the tool contract. It is intentionally smaller: no DuckDB-only
+ * readers, no external files/URLs — data enters only through a bounded
+ * controlled read or bounded inline content.
+ */
+
+/** The five tools a Bot gets. */
+export const DATA_TOOL_NAMES = Object.freeze(['data_load', 'data_describe', 'data_sql', 'data_show', 'data_export'])
+
+/** Bounds. Every result is capped by rows AND bytes; the cap is the contract, not a plan. */
+export const DATA_LIMITS = Object.freeze({
+  /** data_sql rows returned to the model by default, and at most. */
+  sqlRowsDefault: 100,
+  sqlRowsMax: 1000,
+  /** Bytes of rows data_sql returns to the model. */
+  sqlBytesMax: 256 * 1024,
+  /** data_describe result bytes; beyond describeColumnsMax columns, types only. */
+  describeBytesMax: 32 * 1024,
+  describeColumnsMax: 100,
+  /** Sample values per column, each at most sampleChars characters. */
+  sampleValues: 3,
+  sampleChars: 60,
+  /** Rows per page the panel's grid asks for. */
+  pageSize: 200,
+  pageLimitMax: 2000,
+  /** Marks a chart may render after its SQL reduction. */
+  chartMaxMarks: 5000,
+  /** Rows data_show kind:"table" keeps for the panel. */
+  showTableRowsMax: 100_000,
+  /** One statement's wall clock before the child is killed. */
+  sqlTimeoutMs: 30_000,
+  /** Cards a sheet holds; the oldest unpinned card goes first. */
+  sheetCardsMax: 100,
+  /** Inline content / library read byte cap for a single data_load. */
+  loadMaxBytes: 8 * 1024 * 1024,
+  /** Rows a single data_load may materialise. */
+  loadMaxRows: 200_000,
+  /** Columns a single data_load may materialise. */
+  loadMaxCols: 512,
+  /** A single cell's text length before it is truncated for display. */
+  cellCharsMax: 4000,
+  /** Exported CSV/JSON byte cap. */
+  exportMaxBytes: 16 * 1024 * 1024,
+  /**
+   * Native/database bounds enforced INSIDE the fixed worker. Row/character caps
+   * alone do not bound SQLite: a single statement can allocate native memory or
+   * grow the database file without returning many rows, so the worker sets these
+   * at open time and SQLite itself refuses (SQLITE_FULL / SQLITE_NOMEM) instead
+   * of the Host growing without limit.
+   */
+  /** Pages one Bot's database file may hold (SQLITE_FULL beyond it). */
+  dbMaxPageCount: 32_768,
+  /** Native heap SQLite refuses to exceed (SQLITE_NOMEM beyond it). */
+  dbHardHeapLimitBytes: 96 * 1024 * 1024,
+  /** Native heap SQLite starts reclaiming at. */
+  dbSoftHeapLimitBytes: 48 * 1024 * 1024,
+  /** The worker child's V8 old space; a runaway JS allocation dies, not the Host. */
+  workerHeapMb: 256,
+  /** Bot databases resident at once; the least recently used worker is closed. */
+  activeWorkersMax: 4,
+  /** How long close() waits for a child's real exit before reporting it. */
+  workerExitTimeoutMs: 10_000,
+  /** Wall clock for opening a database in a fresh child. */
+  openTimeoutMs: 15_000,
+})
+
+/** Where materialised card results live inside a Bot's database. */
+export const DATA_RESULTS_SCHEMA = 'mb_data_results'
+
+export const DATA_ERROR_CODES = Object.freeze([
+  'invalid_input', 'source_not_found', 'source_unsupported', 'sql_error', 'write_refused',
+  'table_not_found', 'spec_invalid', 'card_not_found', 'output_too_large', 'timeout', 'cancelled',
+  'engine_unavailable', 'import_failed', 'dataset_conflict', 'unauthorized',
+])
+
+/**
+ * Bound an engine/worker message so a failure never leaks the Host's layout or
+ * secrets: absolute paths are collapsed, stack frames are dropped and the text
+ * is capped. `secrets` are literal strings (a data directory, a temp directory)
+ * that must never reach the model or the panel.
+ */
+export function sanitizeDataMessage(message, secrets = [], maxChars = 400) {
+  let text = String(message ?? '')
+  text = text.replace(/(?:\r?\n)+\s*at\s+[^\r\n]*/g, '')      // stack frames
+  text = text.replace(/[A-Za-z]:[\\/][^\s'"`,;)]*/g, '<path>')  // Windows absolute paths
+  text = text.replace(/(^|[\s'"=(,])\/(?:[^\s'"`,;)]{2,})/g, '$1<path>') // POSIX absolute paths
+  for (const secret of secrets) {
+    if (typeof secret !== 'string' || secret.length < 3) continue
+    text = text.split(secret).join('<redacted>')
+  }
+  text = text.replace(/[\r\n]+/g, ' ').replace(/\s{2,}/g, ' ').trim()
+  return text.length > maxChars ? `${text.slice(0, maxChars)}…` : text
+}
+
+/** A structured failure every tool and route returns. `message` is the engine's own text. */
+export function dataError(code, message, extra = {}) {
+  if (!DATA_ERROR_CODES.includes(code)) throw new RangeError(`unknown data error code: ${code}`)
+  return { code, message, ...extra }
+}
+
+/** The throwable failure used inside the pure modules. */
+export class DataFailure extends Error {
+  constructor(error) {
+    super(error.message)
+    this.name = 'DataFailure'
+    this.error = error
+  }
+}
+
+/** A table name accepted as a load target / result name. */
+export const IDENT = /^[A-Za-z_][A-Za-z0-9_]{0,62}$/
+/** A Bot id, matching the Host's principal directory rules. */
+export const BOT_ID = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/
+
+/** Quote a SQL identifier for SQLite. */
+export const quoteIdent = name => `"${String(name).replace(/"/g, '""')}"`
+/** Quote a SQL string literal for SQLite. */
+export const quoteLiteral = value => `'${String(value).replace(/'/g, "''")}'`
+
+/**
+ * Derive a safe table name from an arbitrary stem (file name, dataset label).
+ * Always returns a plain identifier safe to embed as a quoted SQL identifier.
+ */
+export function tableNameFrom(stem) {
+  let name = String(stem ?? '').toLowerCase().replace(/[^a-z0-9_]+/g, '_').replace(/^_+|_+$/g, '').slice(0, 63)
+  if (!name) name = 'data'
+  if (!/^[a-z_]/.test(name)) name = `t_${name}`.slice(0, 63)
+  return name
+}
+
+/** Validate a Bot id, throwing a DataFailure otherwise. */
+export function assertBotId(botId) {
+  if (typeof botId !== 'string' || !BOT_ID.test(botId) || /[. ]$/.test(botId)) {
+    throw new DataFailure(dataError('invalid_input', 'A valid Bot id is required; it comes from the Host, never from an argument.'))
+  }
+  return botId
+}

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

@@ -0,0 +1,68 @@
+/**
+ * The five data tools a Bot can call: data_load, data_describe, data_sql,
+ * data_show, data_export. They are the model-facing half of the loop; the
+ * panel's owner actions (bot-data-actions.mjs) are the other half.
+ *
+ * Authority: the calling Bot's id comes from the live session through the
+ * injected `botIdFor(exec)` — never from an argument. A Bot only ever reaches
+ * its own database; it cannot name another Bot, an OS path, a program, a
+ * database file or a URL. Data enters only from a bounded controlled library
+ * read or bounded inline content. Every failure is a structured DataError the
+ * model can read, never a silent success.
+ *
+ * `botIdFor` is the Host's grant check (see data-product-access.mjs): a Bot
+ * without the `tool/data` grant, or one whose configuration is not committed,
+ * gets `unauthorized` with the Host's own reason instead of a vague refusal.
+ *
+ * Names, descriptions, the SDK parameter map and the business projection all
+ * come from the shared contract (data-tool-contract.mjs), which the native MCP
+ * door (native-data-tools.mjs) reads too: the two doors cannot drift apart, and
+ * a model-supplied `botId` is projected away rather than accepted as authority.
+ */
+
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { DataFailure, sanitizeDataMessage } from './bot-data-surface.mjs'
+import { DATA_TOOL_ENTRIES, invokeDataTool } from './data-tool-contract.mjs'
+
+const JSON_OUTPUT = {
+  schema: { type: 'json' },
+  render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }],
+}
+
+const errorOf = error => (error instanceof DataFailure ? error.error : { code: 'engine_unavailable', message: String(error?.message ?? error) })
+
+/**
+ * @param {object} ctx Host tool registry ({ tools: { register } }).
+ * @param {{ engine: object, botIdFor: (exec: object) => string | null }} source
+ * @returns {() => void} release
+ */
+export function registerDataTools(ctx, { engine, botIdFor } = {}) {
+  if (!engine || typeof engine.forBot !== 'function') throw new TypeError('DATA_TOOLS_REQUIRE_ENGINE')
+  if (typeof botIdFor !== 'function') throw new TypeError('DATA_TOOLS_REQUIRE_BOT_ID_FOR')
+  if (!ctx || typeof ctx.tools?.register !== 'function') throw new TypeError('DATA_TOOLS_REQUIRE_CTX')
+
+  const asBot = async (exec, run) => {
+    let botId = null
+    // A Bot without the data grant, or one whose configuration is not committed
+    // yet, is refused HERE with the Host's own reason — not as a vague
+    // "unknown subject".
+    try { botId = botIdFor(exec) ?? null } catch (error) {
+      return { error: { code: 'unauthorized', message: sanitizeDataMessage(error?.message ?? error) } }
+    }
+    if (typeof botId !== 'string' || botId === '') return { error: { code: 'unknown_subject', message: 'The calling Bot could not be identified from the live session.' } }
+    try { return await run(engine.forBot(botId), botId) } catch (error) { return { error: errorOf(error) } }
+  }
+
+  const tools = DATA_TOOL_ENTRIES.map(entry => defineTool({
+    name: entry.name,
+    description: entry.description,
+    parameters: entry.parameters,
+    output: JSON_OUTPUT,
+    // Business arguments only: the projection drops anything the model added,
+    // including a botId, so it can never be read as authority.
+    execute: (args, exec) => asBot(exec, (bot, botId) => invokeDataTool(bot, entry.name, args)),
+  }))
+
+  const releases = tools.map(tool => ctx.tools.register(tool))
+  return () => { for (const release of releases.reverse()) release() }
+}