dsh-data-cleaning-agent 0.2.0

package/lib/engine.js

@@ -0,0 +1,290 @@
+/**
+ * 数据清洗补全引擎（纯函数，无 DSH 依赖，可在 node:test 中直接测试）。
+ *
+ * 设计约束：
+ * - 输入统一为「表头 + 行对象数组」，所有值先规范化为 string。
+ * - 清洗（clean）只会「丢弃 + 规范化」，绝不编造数据。
+ * - 补全（complete）只补「可由确定性规则推出的值」，补不出的字段留在
+ *   `_incomplete` 列表里明示，绝不编造。
+ * - 引擎层返回完整明细（供下载/入库），模型工具层只回摘要（安全边界在工具层）。
+ */
+
+/** 去掉 BOM、按 CSV/RFC4180 子集解析为 { headers, rows }。 */
+export function parseCsv(text) {
+  const src = String(text ?? '').replace(/^\uFEFF/, '');
+  const records = [];
+  let field = '';
+  let row = [];
+  let inQuotes = false;
+
+  const pushField = () => { row.push(field); field = ''; };
+  const pushRow = () => { records.push(row); row = []; };
+
+  for (let i = 0; i < src.length; i += 1) {
+    const ch = src[i];
+    if (inQuotes) {
+      if (ch === '"') {
+        if (src[i + 1] === '"') { field += '"'; i += 1; } else { inQuotes = false; }
+      } else {
+        field += ch;
+      }
+    } else if (ch === '"') {
+      inQuotes = true;
+    } else if (ch === ',') {
+      pushField();
+    } else if (ch === '\n') {
+      pushField(); pushRow();
+    } else if (ch === '\r') {
+      if (src[i + 1] === '\n') i += 1;
+      pushField(); pushRow();
+    } else {
+      field += ch;
+    }
+  }
+  // 末尾无换行时的最后一行
+  if (field !== '' || row.length > 0) { pushField(); pushRow(); }
+
+  // 去掉全空行
+  const nonEmpty = records.filter((r) => r.some((c) => c.trim() !== ''));
+  if (nonEmpty.length === 0) return { headers: [], rows: [] };
+
+  const headers = nonEmpty[0].map((h, i) => (String(h).trim() || `col_${i + 1}`));
+  const rows = nonEmpty.slice(1).map((r) => {
+    const o = {};
+    headers.forEach((h, i) => { o[h] = r[i] === undefined ? '' : String(r[i]); });
+    return o;
+  });
+  return { headers, rows };
+}
+
+/** 懒加载 xlsx：仅在真正解析 XLS/XLSX 时才 require，headless 无此依赖也不受影响。 */
+export async function parseXlsx(buffer) {
+  let XLSX;
+  try {
+    ({ default: XLSX } = await import('xlsx'));
+  } catch {
+    const err = new Error('xlsx dependency not available in this composition');
+    err.code = 'XLSX_UNAVAILABLE';
+    throw err;
+  }
+  const wb = XLSX.read(buffer, { type: 'buffer' });
+  const sheetName = wb.SheetNames[0];
+  if (!sheetName) return { headers: [], rows: [] };
+  const aoa = XLSX.utils.sheet_to_json(wb.Sheets[sheetName], { header: 1, defval: '', raw: false });
+  if (!aoa.length) return { headers: [], rows: [] };
+  const headers = aoa[0].map((h, i) => (String(h ?? '').trim() || `col_${i + 1}`));
+  const rows = aoa.slice(1).map((r) => {
+    const o = {};
+    headers.forEach((h, i) => { o[h] = r[i] === undefined || r[i] === null ? '' : String(r[i]); });
+    return o;
+  });
+  return { headers, rows };
+}
+
+export function detectFormat(filename) {
+  const name = String(filename ?? '').toLowerCase();
+  if (name.endsWith('.xlsx') || name.endsWith('.xls')) return 'xlsx';
+  if (name.endsWith('.csv') || name.endsWith('.txt')) return 'csv';
+  if (name.endsWith('.json')) return 'json';
+  return 'csv'; // 默认按 CSV 文本处理
+}
+
+export function parseJson(text) {
+  let parsed;
+  try { parsed = JSON.parse(String(text ?? '')); } catch {
+    const err = new Error('invalid JSON body'); err.code = 'BAD_JSON'; throw err;
+  }
+  const rows = Array.isArray(parsed) ? parsed : (parsed?.rows ?? []);
+  if (!rows.length) return { headers: [], rows: [] };
+  const headers = [...new Set(rows.flatMap((r) => (r && typeof r === 'object' ? Object.keys(r) : [])))];
+  const norm = rows.map((r) => {
+    const o = {};
+    headers.forEach((h) => { o[h] = r?.[h] === undefined || r?.[h] === null ? '' : String(r[h]); });
+    return o;
+  });
+  return { headers, rows: norm };
+}
+
+/** 规范化单个字符串值：trim、把 undefined/null 归一为 ''。 */
+function norm(value) {
+  if (value === undefined || value === null) return '';
+  return String(value).trim();
+}
+
+/** 规范化手机号：去空格/连字符，保留数字。 */
+export function normalizePhone(value) {
+  return norm(value).replace(/[\s-]/g, '');
+}
+
+/**
+ * 清洗一批行。opts:
+ * - required: string[]，缺失即丢弃（默认 ['name','phone']）
+ * - amountField: string（默认 'amount'）
+ * - dedupeOn: string|null，按该字段去重、保留首个（默认 'phone'）
+ * - phoneField: string|null，需要做手机号规范化的列（默认 'phone'）
+ */
+export function cleanRows(rows, opts = {}) {
+  const required = opts.required ?? ['name', 'phone'];
+  const amountField = opts.amountField ?? 'amount';
+  const dedupeOn = opts.dedupeOn === undefined ? 'phone' : opts.dedupeOn;
+  const phoneField = opts.phoneField === undefined ? 'phone' : opts.phoneField;
+
+  const input = Array.isArray(rows) ? rows : [];
+  const cleaned = [];
+  const seen = new Set();
+  let badMissing = 0;
+  let badAmount = 0;
+  let badDuplicate = 0;
+
+  for (const raw of input) {
+    const row = {};
+    for (const [k, v] of Object.entries(raw ?? {})) row[k] = norm(v);
+    if (phoneField && phoneField in row) row[phoneField] = normalizePhone(row[phoneField]);
+
+    // 1) 必填字段
+    const missing = required.filter((f) => !row[f]);
+    if (missing.length > 0) { badMissing += 1; continue; }
+
+    // 2) 金额合法（非数字或负值丢弃）
+    if (amountField in row && row[amountField] !== '') {
+      const amount = Number(row[amountField]);
+      if (!Number.isFinite(amount) || amount < 0) { badAmount += 1; continue; }
+    }
+
+    // 3) 去重
+    if (dedupeOn && row[dedupeOn]) {
+      const key = row[dedupeOn];
+      if (seen.has(key)) { badDuplicate += 1; continue; }
+      seen.add(key);
+    }
+
+    cleaned.push(row);
+  }
+
+  return {
+    total: input.length,
+    kept: cleaned.length,
+    dropped: badMissing + badAmount + badDuplicate,
+    badMissing,
+    badAmount,
+    badDuplicate,
+    cleaned,
+  };
+}
+
+/**
+ * 补全一批行（确定性规则，不编造）。
+ * - amount 空 → '0'
+ * - name 空 → placeholder（默认 '未命名'）
+ * - phone 仅做规范化；补不出真实号码的记入 `_incomplete`
+ * 返回完整明细 + 分字段补全统计。
+ */
+export function completeRows(rows, opts = {}) {
+  const amountField = opts.amountField ?? 'amount';
+  const phoneField = opts.phoneField === undefined ? 'phone' : opts.phoneField;
+  const namePlaceholder = opts.namePlaceholder ?? '未命名';
+  const fillableName = opts.fillableName === undefined ? true : opts.fillableName;
+
+  const input = Array.isArray(rows) ? rows : [];
+  const completed = [];
+  const fillStats = { name: 0, amount: 0, phoneNormalized: 0 };
+  const incomplete = [];
+
+  for (let i = 0; i < input.length; i += 1) {
+    const raw = input[i] ?? {};
+    const row = {};
+    let incompleteFields = [];
+
+    for (const [k, v] of Object.entries(raw)) {
+      const s = norm(v);
+      if (k === amountField && s === '') { row[k] = '0'; fillStats.amount += 1; }
+      else if (k === 'name' && s === '' && fillableName) { row[k] = namePlaceholder; fillStats.name += 1; }
+      else row[k] = s;
+    }
+
+    if (phoneField in row) {
+      const before = row[phoneField];
+      row[phoneField] = normalizePhone(row[phoneField]);
+      if (row[phoneField] !== before) fillStats.phoneNormalized += 1;
+      if (!row[phoneField]) incompleteFields.push(phoneField);
+    }
+    if ('name' in row && !row.name) incompleteFields.push('name');
+    if (amountField in row && row[amountField] === '') incompleteFields.push(amountField);
+
+    row._rowIndex = i;
+    if (incompleteFields.length > 0) {
+      row._incomplete = incompleteFields;
+      incomplete.push({ rowIndex: i, fields: incompleteFields });
+    }
+    completed.push(row);
+  }
+
+  return {
+    total: input.length,
+    completed: completed.length,
+    incompleteCount: incomplete.length,
+    fillStats,
+    incomplete,
+    completed,
+  };
+}
+
+/** 概览统计：列级缺失/去重 + amount 数值分布。 */
+export function profileRows(rows, opts = {}) {
+  const amountField = opts.amountField ?? 'amount';
+  const input = Array.isArray(rows) ? rows : [];
+  const columns = new Map();
+  const amounts = [];
+
+  for (const raw of input) {
+    const entries = Object.entries(raw ?? {});
+    for (const [k, v] of entries) {
+      if (!columns.has(k)) columns.set(k, { present: 0, missing: 0, distinct: new Set() });
+      const s = norm(v);
+      const col = columns.get(k);
+      if (s === '') col.missing += 1;
+      else { col.present += 1; col.distinct.add(s); }
+    }
+    if (amountField in (raw ?? {})) {
+      const n = Number(norm(raw[amountField]));
+      if (Number.isFinite(n)) amounts.push(n);
+    }
+  }
+
+  const columnStats = [...columns.entries()].map(([name, c]) => ({
+    name,
+    present: c.present,
+    missing: c.missing,
+    distinct: c.distinct.size,
+  }));
+
+  let amountStats = null;
+  if (amounts.length > 0) {
+    const sorted = [...amounts].sort((a, b) => a - b);
+    const sum = sorted.reduce((a, b) => a + b, 0);
+    amountStats = {
+      count: sorted.length,
+      min: sorted[0],
+      max: sorted[sorted.length - 1],
+      sum,
+      mean: sum / sorted.length,
+    };
+  }
+
+  return { rowCount: input.length, columnCount: columns.size, columns: columnStats, amountStats };
+}
+
+/** 明细 → CSV 文本（下载用）。 */
+export function toCsv(headers, rows) {
+  const hs = headers && headers.length ? headers : (rows[0] ? Object.keys(rows[0]) : []);
+  const escape = (v) => {
+    const s = String(v ?? '');
+    if (s.includes('"') || s.includes(',') || s.includes('\n') || s.includes('\r')) {
+      return `"${s.replace(/"/g, '""')}"`;
+    }
+    return s;
+  };
+  const lines = [hs.map(escape).join(',')];
+  for (const r of rows) lines.push(hs.map((h) => escape(r[h] ?? '')).join(','));
+  return `${lines.join('\r\n')}\r\n`;
+}

package/lib/index.js

@@ -0,0 +1,73 @@
+/**
+ * 数据清洗补全智能体 · MVP · host 半区。
+ *
+ * 组成（全部为 Spike #1–#6 已实测同构的 seam）：
+ *  1. ctx.tools  —— 注册 data_clean_rows / data_complete_rows / data_profile
+ *  2. ctx.skills —— 注册内嵌 Skill `data-cleaning`（正文指引模型调上述工具）
+ *  3. webServer/webRuntime —— 挂载上传/解析/同步清洗补全/异步任务/UI 路由
+ *  4. ctx.jobs + ctx.storageDomain —— 异步任务状态机（web 组合内可用）
+ *
+ * headless 组合无 webServer/webRuntime：用 ctx.get() 存在性守卫跳过 web 半区，
+ * 工具与 Skill 照常注册（端到端真实模型路径依赖它们）。
+ */
+import { mountWebRoutes } from './web.js';
+import { registerTools, TOOL_CLEAN } from './tools.js';
+import { registerSkill, SKILL_NAME } from './skill.js';
+
+export const name = 'data-cleaning-agent';
+export const inject = [];
+
+export function apply(ctx, config) {
+  const report = {
+    tools: 'not-checked',
+    skills: 'not-checked',
+    toolRegistered: false,
+    skillRegistered: false,
+    webMounted: false,
+    webSkipped: false,
+  };
+  const disposers = [];
+
+  // 1. 模型工具
+  try {
+    ctx.inject(['tools'], (tctx) => {
+      report.tools = 'present';
+      report.toolRegister = typeof tctx.tools?.register === 'function' ? 'ok' : String(typeof tctx.tools?.register);
+      disposers.push(...registerTools(tctx.tools));
+      report.toolRegistered = true;
+    });
+  } catch (error) {
+    report.tools = `absent: ${error instanceof Error ? error.message : String(error)}`;
+  }
+
+  // 2. 内嵌 Skill
+  try {
+    ctx.inject(['skills'], (sctx) => {
+      report.skills = 'present';
+      report.skillRegister = typeof sctx.skills?.register === 'function' ? 'ok' : String(typeof sctx.skills?.register);
+      disposers.push(registerSkill(sctx.skills));
+      report.skillRegistered = true;
+    });
+  } catch (error) {
+    report.skills = `absent: ${error instanceof Error ? error.message : String(error)}`;
+  }
+
+  // 3. web 半区（仅 web 组合存在；headless 组合无 webServer/webRuntime，inject 会失败）
+  try {
+    ctx.inject(['webServer', 'webRuntime', 'tools', 'skills', 'jobs', 'storageDomain'], (wctx) => {
+      const dispose = mountWebRoutes(wctx, { logger: ctx.logger, report, TOOL_NAME: TOOL_CLEAN, SKILL_NAME });
+      if (typeof dispose === 'function' && typeof ctx.effect === 'function') {
+        ctx.effect(() => () => dispose(), 'data-cleaning-agent: web routes');
+      }
+      report.webMounted = true;
+    });
+  } catch (error) {
+    report.webSkipped = true;
+    console.warn(`[dc-agent] web half not mounted (headless?): ${error instanceof Error ? error.message : String(error)}`);
+  }
+
+  // eslint-disable-next-line no-console
+  console.log('[dc-agent] host apply() ran');
+  ctx.__DC_MVP_REPORT__ = report;
+  ctx.__DC_MVP_DISPOSERS__ = disposers;
+}

package/lib/jobs.js

@@ -0,0 +1,144 @@
+/**
+ * Job / Storage 状态机（Spike #4 实测同构）。
+ *  - `ctx.jobs`：后台任务生命周期（start/wait/read/kill/list），host bundle 需先
+ *    `attachController()`（无主 job 否则抛 "no job controller serves this agent"）。
+ *  - `ctx.storageDomain`：schema 校验的持久 KV，落盘 `DSH_HOME/storages/<domain>.json`。
+ *
+ * 任务记录持久化到 domain `dc_tasks_v1`（table `jobs`），状态机：
+ *   queued → running → completed | failed | killed
+ */
+import { cleanRows, completeRows, profileRows } from './engine.js';
+
+const DOMAIN_NAME = 'dc_tasks_v1';
+const DOMAIN_VERSION = 1;
+const permissiveSchema = {
+  parse: (v) => v,
+  safeParse: (v) => ({ success: true, data: v }),
+};
+
+const domainSpec = () => ({
+  name: DOMAIN_NAME,
+  version: DOMAIN_VERSION,
+  tables: { jobs: { valueSchema: permissiveSchema } },
+});
+
+function now() {
+  return new Date().toISOString();
+}
+
+/** 同步执行一次清洗/补全/概览，返回完整明细（供下载）与摘要。 */
+export function runSync(kind, rows, opts = {}) {
+  switch (kind) {
+    case 'clean': {
+      const r = cleanRows(rows, opts);
+      return { kind, summary: { total: r.total, kept: r.kept, dropped: r.dropped, badMissing: r.badMissing, badAmount: r.badAmount, badDuplicate: r.badDuplicate }, rows: r.cleaned, headers: opts.headers ?? [] };
+    }
+    case 'complete': {
+      const r = completeRows(rows, opts);
+      return { kind, summary: { total: r.total, completed: r.completed, incompleteCount: r.incompleteCount, name: r.fillStats.name, amount: r.fillStats.amount, phoneNormalized: r.fillStats.phoneNormalized }, rows: r.completed, headers: opts.headers ?? [] };
+    }
+    case 'profile': {
+      const r = profileRows(rows, opts);
+      return { kind, summary: { rowCount: r.rowCount, columnCount: r.columnCount, columns: r.columns, amountStats: r.amountStats }, rows: [], headers: opts.headers ?? [] };
+    }
+    default:
+      throw new Error(`unknown kind: ${kind}`);
+  }
+}
+
+export class DataCleaningJobs {
+  constructor({ jobs, storageDomain, logger }) {
+    this.jobs = jobs;
+    this.storageDomain = storageDomain;
+    this.logger = logger ?? console;
+    this.access = null;
+    this.detachController = null;
+  }
+
+  async init() {
+    if (!this.jobs) throw new Error('jobs service unavailable');
+    if (!this.storageDomain) throw new Error('storageDomain service unavailable');
+    // host bundle 提供自己的后台执行器
+    this.detachController = this.jobs.attachController('data-cleaning-agent-mvp');
+    this.access = await this.storageDomain.open(domainSpec());
+    this.logger.info('[dc-agent] jobs/storage state machine ready');
+    return this;
+  }
+
+  table() {
+    if (!this.access) throw new Error('state machine not initialized');
+    return this.access.table('jobs');
+  }
+
+  async start({ kind, rows, headers, opts = {} }) {
+    const id = `task-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const record = {
+      id,
+      kind,
+      state: 'queued',
+      rowsIn: Array.isArray(rows) ? rows.length : 0,
+      summary: null,
+      rowsOut: 0,
+      error: null,
+      createdAt: now(),
+      startedAt: null,
+      finishedAt: null,
+    };
+    await this.table().put(id, record);
+
+    // 将明细暂存在内存闭包，任务完成时写回摘要（不把原始行写进持久 KV，避免膨胀）。
+    const taskRows = Array.isArray(rows) ? rows : [];
+
+    this.jobs.start({
+      kind: `dc-${kind}`,
+      label: `data-cleaning ${kind} (${record.rowsIn} rows)`,
+      run: () => {
+        let resolveDone;
+        const done = new Promise((res) => { resolveDone = res; });
+        const finish = async (patch) => {
+          try {
+            await this.table().update(id, (rec) => ({ ...rec, ...patch, finishedAt: now() }));
+          } catch (e) {
+            this.logger.warn(`[dc-agent] update failed for ${id}: ${e?.message ?? e}`);
+          }
+        };
+        // 同步执行（MVP 体量直接跑；大文件异步化留给产品阶段）
+        queueMicrotask(async () => {
+          try {
+            await this.table().update(id, (rec) => ({ ...rec, state: 'running', startedAt: now() }));
+            const result = runSync(kind, taskRows, { ...opts, headers });
+            await finish({ state: 'completed', summary: result.summary, rowsOut: result.rows.length });
+            resolveDone({ status: 'completed', output: result });
+          } catch (error) {
+            await finish({ state: 'failed', error: error instanceof Error ? error.message : String(error) });
+            resolveDone({ status: 'failed', detail: error instanceof Error ? error.message : String(error) });
+          }
+        });
+        return {
+          done,
+          readOutput: () => '',
+          cancel: (reason) => {
+            finish({ state: 'killed', error: String(reason ?? 'cancelled') }).catch(() => {});
+            resolveDone({ status: 'killed', detail: String(reason ?? 'cancelled') });
+          },
+        };
+      },
+    });
+
+    return id;
+  }
+
+  async list() {
+    const entries = this.table().entries();
+    return [...entries].map(([, rec]) => rec).sort((a, b) => String(b.createdAt).localeCompare(String(a.createdAt)));
+  }
+
+  async get(id) {
+    return this.table().get(id) ?? null;
+  }
+
+  async dispose() {
+    if (this.access) { try { await this.access.close(); } catch {} this.access = null; }
+    if (this.detachController) { try { this.detachController(); } catch {} this.detachController = null; }
+  }
+}

package/lib/skill.js

@@ -0,0 +1,32 @@
+/**
+ * 内嵌 Skill：`data-cleaning`。
+ * 正文只描述工作流，把「工具选择」交给模型；安全约束：绝不回传原始行、绝不编造数据。
+ */
+import { TOOL_CLEAN, TOOL_COMPLETE, TOOL_PROFILE } from './tools.js';
+
+export const SKILL_NAME = 'data-cleaning';
+
+export function registerSkill(skills) {
+  return skills.register({
+    name: SKILL_NAME,
+    description:
+      'Clean, complete, and profile a batch of raw tabular data rows (name / phone / amount and similar columns).',
+    whenToUse:
+      'When the user asks to clean, complete, validate, de-duplicate, or summarize a batch of raw data rows, CSV records, or table-like data.',
+    source: 'dsh-data-cleaning-agent',
+    content: [
+      'You are a data cleaning and completion assistant. Work only on the rows the user actually provided; never invent, pad, or fabricate extra rows.',
+      '',
+      'Workflow:',
+      `1. (Optional) Run \`${TOOL_PROFILE}\` on the batch to understand columns and amount distribution.`,
+      `2. Run \`${TOOL_CLEAN}\` to trim, normalize phone, drop rows with missing required fields, drop non-numeric/negative amounts, and de-duplicate.`,
+      `3. If the user also asks to fill gaps, run \`${TOOL_COMPLETE}\` on the kept rows: it fills empty amount with 0 and empty name with a placeholder, and reports anything it cannot deterministically complete.`,
+      '4. Report only the returned summaries (total / kept / dropped / incomplete). Never echo raw rows or full detail rows back to the user.',
+      '',
+      'Safety rules:',
+      '- Never return raw input rows or the full cleaned/completed rows in your reply — summaries only.',
+      '- Never invent a phone number, name, or amount. If a value cannot be derived deterministically, say it is incomplete.',
+      '',
+    ].join('\n'),
+  });
+}

package/lib/tools.js

@@ -0,0 +1,144 @@
+/**
+ * 模型工具定义：`data_clean_rows` / `data_complete_rows` / `data_profile`。
+ * 安全边界：模型工具只回摘要，绝不回传原始行或明细行；明细仅通过 web 下载链路暴露。
+ * 手写 definition 与 Spike #5 结论一致：`parameters`/`output.schema` 用对象级
+ * `required: [...]`，不得把 `required:true` 写进 property 内部。
+ */
+import { cleanRows, completeRows, profileRows } from './engine.js';
+
+export const TOOL_CLEAN = 'data_clean_rows';
+export const TOOL_COMPLETE = 'data_complete_rows';
+export const TOOL_PROFILE = 'data_profile';
+
+function rowsProperty() {
+  return {
+    type: 'array',
+    items: { type: 'object', additionalProperties: true },
+  };
+}
+
+function summarySchema(extraProps = {}) {
+  return {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+      total: { type: 'integer' },
+      kept: { type: 'integer' },
+      dropped: { type: 'integer' },
+      badMissing: { type: 'integer' },
+      badAmount: { type: 'integer' },
+      badDuplicate: { type: 'integer' },
+      ...extraProps,
+    },
+    required: ['total', 'kept', 'dropped', 'badMissing', 'badAmount', 'badDuplicate'],
+  };
+}
+
+export function registerTools(tools) {
+  const disposers = [];
+
+  disposers.push(tools.register({
+    name: TOOL_CLEAN,
+    description:
+      'Clean one batch of raw data rows: trim values, normalize phone numbers, drop rows missing a required field, drop rows with non-numeric or negative amount, and de-duplicate. Returns a summary only (never raw rows).',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: { rows: rowsProperty() },
+      required: ['rows'],
+    },
+    output: {
+      schema: summarySchema(),
+      render: (_args, value) => [{
+        type: 'text',
+        text: `cleaned ${value.total} rows: kept ${value.kept}, dropped ${value.dropped} (missing ${value.badMissing}, bad-amount ${value.badAmount}, duplicate ${value.badDuplicate})`,
+      }],
+    },
+    async execute(args) {
+      const r = cleanRows(Array.isArray(args.rows) ? args.rows : []);
+      return {
+        total: r.total,
+        kept: r.kept,
+        dropped: r.dropped,
+        badMissing: r.badMissing,
+        badAmount: r.badAmount,
+        badDuplicate: r.badDuplicate,
+      };
+    },
+  }));
+
+  disposers.push(tools.register({
+    name: TOOL_COMPLETE,
+    description:
+      'Complete one batch of raw data rows with deterministic rules only: fill empty amount with 0, fill empty name with a placeholder, normalize phone numbers. Fields that cannot be deterministically completed are reported as incomplete (by row index + field). Returns a summary only, never raw rows.',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: { rows: rowsProperty() },
+      required: ['rows'],
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          total: { type: 'integer' },
+          completed: { type: 'integer' },
+          incompleteCount: { type: 'integer' },
+          name: { type: 'integer' },
+          amount: { type: 'integer' },
+          phoneNormalized: { type: 'integer' },
+        },
+        required: ['total', 'completed', 'incompleteCount', 'name', 'amount', 'phoneNormalized'],
+      },
+      render: (_args, value) => [{
+        type: 'text',
+        text: `completed ${value.total} rows: ${value.completed} done, ${value.incompleteCount} still incomplete (filled name ${value.name}, amount ${value.amount}, normalized phone ${value.phoneNormalized})`,
+      }],
+    },
+    async execute(args) {
+      const r = completeRows(Array.isArray(args.rows) ? args.rows : []);
+      return {
+        total: r.total,
+        completed: r.completed,
+        incompleteCount: r.incompleteCount,
+        name: r.fillStats.name,
+        amount: r.fillStats.amount,
+        phoneNormalized: r.fillStats.phoneNormalized,
+      };
+    },
+  }));
+
+  disposers.push(tools.register({
+    name: TOOL_PROFILE,
+    description:
+      'Profile one batch of raw data rows: column presence/missing/distinct counts and amount distribution. Returns a summary only.',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: { rows: rowsProperty() },
+      required: ['rows'],
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          rowCount: { type: 'integer' },
+          columnCount: { type: 'integer' },
+        },
+        required: ['rowCount', 'columnCount'],
+      },
+      render: (_args, value) => [{
+        type: 'text',
+        text: `profiled ${value.rowCount} rows across ${value.columnCount} columns`,
+      }],
+    },
+    async execute(args) {
+      const r = profileRows(Array.isArray(args.rows) ? args.rows : []);
+      return { rowCount: r.rowCount, columnCount: r.columnCount };
+    },
+  }));
+
+  return disposers;
+}