new-erp-mcp 0.2.2 → 0.3.0

package/scripts/mcp-artifacts.js

@@ -0,0 +1,106 @@
+const fs = require('node:fs/promises');
+const path = require('node:path');
+
+const JSON_BUDGET = 10000;
+const PREVIEW_BUDGET = 2200;
+const isPrimitive = value => value === null || ['string', 'boolean', 'number'].includes(typeof value);
+const clipped = (value, bytes) => Buffer.from(value).subarray(0, bytes).toString('utf8');
+
+class StreamFailure extends Error {
+  constructor(partialResult, cause) {
+    super('Page stream did not finish.', { cause });
+    this.partialResult = partialResult;
+  }
+}
+
+function preview(value) {
+  const rows = Array.isArray(value) ? value : Array.isArray(value?.list) ? value.list : [value];
+  const list = [];
+  for (const row of rows.slice(0, 3)) {
+    const fields = [];
+    function visit(item, prefix = '', depth = 0) {
+      if (!item || typeof item !== 'object' || depth > 3) return;
+      for (const [key, val] of Object.entries(item)) {
+        const name = prefix ? `${prefix}.${key}` : key;
+        if (/^rawJson$/i.test(key)) continue;
+        if (isPrimitive(val)) fields.push([name, typeof val === 'string' && !/(?:url|asin|sku)$/i.test(key) ? clipped(val, 180) : val]);
+        else if (!Array.isArray(val)) visit(val, name, depth + 1);
+      }
+    }
+    if (isPrimitive(row)) fields.push(['value', typeof row === 'string' ? clipped(row, 180) : row]);
+    else visit(row);
+    const identity = [];
+    for (const pattern of [/(^|\.)asin$/i, /(^|\.)sku$/i, /(^|\.)image.?url$/i]) {
+      const field = fields.find(([key]) => pattern.test(key));
+      if (field) identity.push(field);
+    }
+    const ordered = [...identity, ...fields.filter(field => !identity.includes(field))];
+    const item = {};
+    for (const [key, val] of ordered) {
+      item[key] = val;
+      if (Buffer.byteLength(JSON.stringify([...list, item])) > PREVIEW_BUDGET) delete item[key];
+    }
+    if (Object.keys(item).length) list.push(item);
+  }
+  return list;
+}
+
+async function metadata(file, mediaType, extra = {}) {
+  const stat = await fs.stat(file);
+  await fs.chmod(file, 0o600);
+  return { path: file, mediaType, bytes: stat.size, complete: true, ...extra };
+}
+
+async function exclusive(file, value, mediaType, extra) {
+  await fs.writeFile(file, value, { flag: 'wx', mode: 0o600 });
+  return metadata(file, mediaType, extra);
+}
+
+async function adaptResult(value, { dir, outputPath }) {
+  if (Buffer.isBuffer(value) || Buffer.isBuffer(value?.file)) {
+    const buffer = Buffer.isBuffer(value) ? value : value.file;
+    const artifact = await exclusive(path.join(dir, 'export.xlsx'), buffer, 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet');
+    return { artifact, ...(typeof value?.taskId === 'string' ? { taskId: value.taskId } : {}), ...(Number.isFinite(value?.boxes) ? { boxes: value.boxes } : {}) };
+  }
+  const output = Array.isArray(value) && value.length === 1 ? value[0] : value;
+  if (output?.output && output.output === outputPath) {
+    const artifact = await metadata(outputPath, outputPath.endsWith('.csv') ? 'text/csv' : 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet');
+    return { artifact, ...(typeof output.taskId === 'string' ? { taskId: output.taskId } : {}), ...(Number.isFinite(output.boxes) ? { boxes: output.boxes } : {}), ...(output.encoding ? { encoding: output.encoding } : {}) };
+  }
+  const data = Array.isArray(value) ? { list: value } : value;
+  const json = JSON.stringify(data ?? null);
+  if (Buffer.byteLength(json) <= JSON_BUDGET) return { data: data ?? null };
+  const artifact = await exclusive(path.join(dir, 'result.json'), json, 'application/json');
+  const result = { artifact, preview: preview(data) };
+  if (Array.isArray(data?.list)) result.rowCount = data.list.length;
+  for (const field of ['page', 'pageSize', 'totalCount', 'fetchedCount', 'complete']) {
+    if (isPrimitive(data?.[field]) && data[field] !== undefined) result[field] = data[field];
+  }
+  return result;
+}
+
+async function consumePages(iterator, { dir, active }) {
+  const file = path.join(dir, 'pages.ndjson');
+  const handle = await fs.open(file, 'wx', 0o600);
+  let pageCount = 0; let rowCount = 0; let last = {};
+  let error;
+  try {
+    for await (const page of iterator) {
+      if (!active()) throw new Error('Job stopped');
+      await handle.writeFile(`${JSON.stringify(page)}\n`);
+      pageCount += 1;
+      rowCount += Array.isArray(page?.list) ? page.list.length : 0;
+      last = page;
+    }
+  } catch (cause) { error = cause; }
+  finally { await handle.close(); }
+  const artifact = await metadata(file, 'application/x-ndjson', { complete: !error, pageCount, rowCount });
+  const result = { artifact, pageCount, rowCount };
+  for (const field of ['page', 'pageSize', 'totalCount', 'fetchedCount', 'complete']) {
+    if (isPrimitive(last?.[field]) && last[field] !== undefined) result[field] = last[field];
+  }
+  if (error) { delete result.complete; throw new StreamFailure(result, error); }
+  return result;
+}
+
+module.exports = { adaptResult, consumePages, StreamFailure };

package/scripts/mcp-auth.js

@@ -0,0 +1,86 @@
+const { readSession, removeSession, sessionExpired } = require('./local-session.js');
+const { getBaseUrl, normalizeBaseUrl } = require('./shared.js');
+const { runBrowserLogin } = require('./login-browser.js');
+
+function loginRequired() {
+  return Object.assign(new Error('ERP 尚未登录或会话已失效'), { code: 'LOGIN_REQUIRED' });
+}
+
+function createAuth({ openBrowser, browserTimeoutMs = 300_000 } = {}) {
+  let pending;
+  let closed = false;
+  let lastMessage;
+
+  function requireSession() {
+    let session;
+    try { session = readSession(); } catch { throw loginRequired(); }
+    if (!session || sessionExpired(session)) throw loginRequired();
+    try { normalizeBaseUrl(session.baseUrl); } catch { throw loginRequired(); }
+    return session;
+  }
+
+  function status() {
+    let session;
+    try { session = requireSession(); } catch {}
+    return {
+      state: pending ? 'login_pending' : session ? 'authenticated' : 'login_required',
+      loggedIn: Boolean(session),
+      ...(session ? { baseUrl: session.baseUrl, username: session.username, expireTime: session.expireTime } : {}),
+      ...(pending?.url ? { url: pending.url } : {}),
+      ...(lastMessage ? { message: lastMessage } : {}),
+    };
+  }
+
+  async function login() {
+    if (closed) throw Object.assign(new Error('MCP 登录服务已关闭'), { code: 'SERVICE_CLOSED' });
+    if (pending) return pending.ready;
+    let baseUrl = '', username = '';
+    try { baseUrl = getBaseUrl(); } catch {}
+    try { username = readSession()?.username || ''; } catch {}
+    const controller = new AbortController();
+    let resolveReady, rejectReady;
+    const ready = new Promise((resolve, reject) => { resolveReady = resolve; rejectReady = reject; });
+    const attempt = { controller, ready, url: undefined, done: undefined };
+    pending = attempt;
+    lastMessage = undefined;
+    attempt.done = runBrowserLogin({ defaults: { baseUrl, username }, signal: controller.signal,
+      timeoutMs: browserTimeoutMs, ...(openBrowser === undefined ? {} : { openBrowser }),
+      onReady(url) {
+        attempt.url = url;
+        resolveReady({ state: 'login_pending', url, expiresInSeconds: Math.ceil(browserTimeoutMs / 1000) });
+      },
+    }).then(() => {
+      lastMessage = undefined;
+    }, () => {
+      lastMessage = '网页登录未完成；可重新启动登录。';
+      rejectReady(Object.assign(new Error('无法完成本机网页登录，请重试'), { code: 'LOGIN_INCOMPLETE' }));
+    }).finally(() => {
+      if (pending === attempt) pending = undefined;
+    });
+    return ready;
+  }
+
+  async function stopPending() {
+    const attempt = pending;
+    if (attempt) {
+      attempt.controller.abort();
+      await attempt.done;
+    }
+  }
+
+  async function logout() {
+    await stopPending();
+    removeSession();
+    lastMessage = undefined;
+    return status();
+  }
+
+  async function close() {
+    closed = true;
+    await stopPending();
+  }
+
+  return { login, status, logout, requireSession, close };
+}
+
+module.exports = { createAuth };

package/scripts/mcp-catalog.js

@@ -0,0 +1,124 @@
+const { z } = require('zod');
+const { commands } = require('./new-erp.js');
+
+const hiddenArgs = new Set(['username', 'password', 'token', 'output']);
+const registry = new Map();
+for (const [cliName, command] of Object.entries(commands)) {
+  if (!['read', 'export', 'stream', 'local'].includes(command.kind)) {
+    throw new Error(`Command must declare a supported kind: ${cliName}`);
+  }
+  if (command.kind === 'local') continue;
+  const name = cliName === 'options' ? 'erp_options' : cliName.replaceAll('-', '_');
+  registry.set(name, { name, description: command.description, effect: command.kind, script: command.script });
+}
+
+registry.set('export_game_products', {
+  name: 'export_game_products', description: '导出在用或停用商品 XLSX', effect: 'export',
+  api: 'exportGameProducts',
+  schema: z.strictObject({
+    fields: z.array(z.string().trim().min(1)).min(1)
+      .refine((fields) => new Set(fields).size === fields.length, 'fields must be unique')
+      .default(['sku', 'name_cn', 'price']).describe('ERP 导出字段名；非空且不重复'),
+    disused: z.boolean().default(false).describe('导出停用商品'),
+  }),
+});
+registry.set('export_outer_packages', {
+  name: 'export_outer_packages', description: '导出外包装规格 XLSX', effect: 'export',
+  api: 'exportOuterPackages',
+  schema: z.strictObject({
+    flowStatus: z.union([z.enum(['1', '2', '3', '4', '5']), z.number().int().min(1).max(5)])
+      .describe('外包装流程状态，1–5'),
+  }),
+});
+
+function summary(entry) {
+  return { name: entry.name, description: entry.description, effect: entry.effect };
+}
+
+function listOperations(query = '') {
+  if (typeof query !== 'string') throw new TypeError('query must be a string');
+  const words = query.trim().toLowerCase().split(/\s+/).filter(Boolean);
+  return [...registry.values()].filter((entry) =>
+    words.every((word) => `${entry.name} ${entry.description}`.toLowerCase().includes(word))).map(summary);
+}
+
+function entryFor(name) {
+  const entry = registry.get(name);
+  if (!entry) throw new Error('Unknown ERP operation');
+  return entry;
+}
+
+function metadata(entry) {
+  if (entry.api) return { schema: entry.schema, args: [] };
+  const implementation = require(`./${entry.script}`);
+  const args = implementation.args.filter((arg) => !hiddenArgs.has(arg.name));
+  const shape = {};
+  for (const arg of args) {
+    let field;
+    if (arg.type === 'string') field = z.string();
+    else if (arg.type === 'int') field = z.number().int();
+    else if (arg.type === 'bool') field = z.boolean();
+    else throw new Error(`Unsupported argument type: ${arg.type}`);
+    field = arg.default === undefined ? field.optional() : field.default(arg.default);
+    shape[arg.name] = field.describe(arg.help);
+  }
+  return { schema: z.strictObject(shape), args };
+}
+
+function requirementsFor(entry, args) {
+  const requirements = ['Requires a fresh saved personal ERP login. Business validators enforce required filters and valid values.'];
+  if (entry.effect === 'export') requirements.push('Requires a stable requestId. Files are saved to a server-managed private artifact.');
+  for (const arg of args.filter((field) => field.choices)) {
+    requirements.push(`${arg.name}: ${arg.choices.join(', ')} (runtime aliases may also be accepted)`);
+  }
+  if (entry.name.startsWith('packing_order_')) {
+    requirements.push('Supply packingNo alone, or all of project, warehouses, startDate, endDate. Supplying any historical field requires all four.');
+  }
+  if (entry.name === 'packing_detail_export') {
+    requirements.push('project, warehouses, startDate, endDate are always required. taskId resumes only a matching existing ERP export.');
+  }
+  if (entry.name === 'export_game_products') requirements.push('fields accepts nonempty unique ERP field names; the three defaults are examples, not an allowlist.');
+  const scope = {
+    game_product_list: 'ERP 搜索可能模糊匹配，需核对返回 SKU；结果仅为当前页。',
+    game_product_batch: 'found 表示 ERP 搜索有返回，不保证精确 SKU；每个 SKU 只查一页，结合 querySku 和 totalCount 判断范围。',
+    product_detail: 'id 与 asin 必须二选一。ASIN 保留全部精确 SKU 和店铺匹配；imageUrl 是 ERP 原始路径，不保证有完整图库。',
+    inventory_list: '预计可用不代表实际签收；保留不同批次、BOM，不自动合并为单一版本。',
+    supply_evidence: '计划不是完成凭证；数组不带分页完整性元数据，不推断全量。需要完整范围时显式使用 fetchAll。',
+    stocking_assembly_inbound: '仅统计精确 SKU 关联的备货拼装实际入库凭证，不以计划量或预测库存代替。',
+    packing_detail: '保留全部 SKU、BOM、包装版本和原始单位，不自动选择首个版本或猜测单位。',
+    outer_package_list: '保留不同包装规格及 BOM 版本，不自动选择首条或把未知数量补零。',
+    product_declaration_list: 'SKU 筛选可能模糊匹配，需核对返回的 SKU 与国家。',
+  };
+  if (scope[entry.name]) requirements.push(scope[entry.name]);
+  return requirements;
+}
+
+function describeOperation(name) {
+  const entry = entryFor(name);
+  const { schema, args } = metadata(entry);
+  const inputSchema = z.toJSONSchema(schema, { io: 'input', unrepresentable: 'any' });
+  return { ...summary(entry), inputSchema, requirements: requirementsFor(entry, args), execution: 'job' };
+}
+
+function getOperation(name) {
+  const entry = entryFor(name);
+  const { schema } = metadata(entry);
+  return {
+    ...summary(entry), schema,
+    invoke(params = {}, hooks = {}) {
+      const options = schema.parse(params);
+      if (entry.api) return import('../index.mjs').then((api) => api[entry.api](options));
+      const implementation = require(`./${entry.script}`);
+      if (entry.effect === 'export') {
+        if (typeof hooks.outputPath !== 'string' || !hooks.outputPath.trim()) {
+          throw new TypeError('Export requires a server-owned outputPath');
+        }
+        options.output = hooks.outputPath;
+        if (entry.name === 'packing_detail_export') options.onProgress = hooks.onProgress;
+      }
+      return implementation[entry.effect === 'stream' ? 'pages' : 'main'](options);
+    },
+  };
+}
+
+module.exports = { listOperations, describeOperation, getOperation };

package/scripts/mcp-job-store.js

@@ -0,0 +1,65 @@
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const os = require('node:os');
+const crypto = require('node:crypto');
+
+function digest(value) {
+  return crypto.createHash('sha256').update(value).digest('hex');
+}
+
+function canonical(value) {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
+  if (value && typeof value === 'object') return `{${Object.keys(value).filter(key => value[key] !== undefined).sort().map(key => `${JSON.stringify(key)}:${canonical(value[key])}`).join(',')}}`;
+  return JSON.stringify(value);
+}
+
+function ownerOf(session) {
+  if (!session?.baseUrl || (session.userId == null && !session.username)) throw failure('AUTH_REQUIRED', 'A personal ERP session is required.');
+  const url = new URL(session.baseUrl);
+  url.hash = ''; url.search = '';
+  if (url.username || url.password) throw failure('AUTH_REQUIRED', 'A personal ERP session is required.');
+  return digest(canonical([url.toString().replace(/\/+$/, ''), session.userId != null ? ['id', String(session.userId)] : ['name', session.username]]));
+}
+
+function failure(code, message) {
+  return Object.assign(new Error(message), { code });
+}
+
+function alive(pid) {
+  if (!Number.isSafeInteger(pid) || pid < 1) return true;
+  try { process.kill(pid, 0); return true; } catch (error) { return error.code !== 'ESRCH'; }
+}
+
+function createStore(rootDir) {
+  const root = path.resolve(rootDir || process.env.NEW_ERP_EXPORT_DIR || path.join(os.homedir(), 'Downloads', 'new-erp'));
+  const jobsDir = path.join(root, '.mcp-jobs');
+  async function privateDir(dir) {
+    await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+    await fs.chmod(dir, 0o700);
+  }
+  async function init() {
+    await fs.mkdir(root, { recursive: true, mode: 0o700 });
+    await privateDir(jobsDir);
+    await privateDir(path.join(jobsDir, 'requests'));
+    await privateDir(path.join(jobsDir, 'exports'));
+  }
+  function jobDir(id) {
+    if (!/^[0-9a-f-]{36}$/.test(id)) throw failure('NOT_FOUND', 'Job not found.');
+    return path.join(jobsDir, id);
+  }
+  async function read(id) {
+    try { return JSON.parse(await fs.readFile(path.join(jobDir(id), 'job.json'), 'utf8')); }
+    catch (error) { if (error.code === 'ENOENT') throw failure('NOT_FOUND', 'Job not found.'); throw error; }
+  }
+  async function write(record) {
+    const dir = jobDir(record.jobId);
+    const temp = path.join(dir, `${crypto.randomUUID()}.tmp`);
+    try {
+      await fs.writeFile(temp, JSON.stringify(record), { flag: 'wx', mode: 0o600 });
+      await fs.rename(temp, path.join(dir, 'job.json'));
+    } finally { await fs.rm(temp, { force: true }); }
+  }
+  return { root, jobsDir, init, jobDir, read, write, privateDir };
+}
+
+module.exports = { createStore, ownerOf, canonical, digest, failure, alive };

package/scripts/mcp-jobs.js

@@ -0,0 +1,277 @@
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { withErpContext, AuthRequiredError, redactSensitiveText } = require('./shared.js');
+const { createStore, ownerOf, canonical, digest, failure, alive } = require('./mcp-job-store.js');
+const { adaptResult, consumePages, StreamFailure } = require('./mcp-artifacts.js');
+
+const ACTIVE = new Set(['queued', 'running']);
+const pause = ms => new Promise(resolve => setTimeout(resolve, ms));
+
+function createJobs({ rootDir, getOperation, waitMs = 750 } = {}) {
+  if (typeof getOperation !== 'function') throw new TypeError('getOperation is required');
+  if (!Number.isFinite(waitMs) || waitMs < 0 || waitMs > 5000) throw new TypeError('waitMs must be between 0 and 5000');
+  const store = createStore(rootDir);
+  const instance = crypto.randomUUID();
+  const local = new Map();
+  const admissions = new Set();
+  let closed = false;
+
+  function receipt(record, note) {
+    const result = {};
+    for (const key of ['jobId', 'operation', 'state', 'createdAt', 'updatedAt', 'progress', 'result', 'error']) {
+      if (record[key] !== undefined) result[key] = record[key];
+    }
+    if (ACTIVE.has(record.state)) result.pollAfterMs = 1000;
+    if (note) result.error = note;
+    return structuredClone(result);
+  }
+
+  async function owned(jobId, session) {
+    const owner = ownerOf(session);
+    const record = await store.read(jobId);
+    if (record.owner !== owner) throw failure('NOT_FOUND', 'Job not found.');
+    return record;
+  }
+
+  function persist(entry) {
+    const copy = structuredClone(entry.record);
+    const next = entry.writes.catch(() => {}).then(() => store.write(copy));
+    entry.writes = next;
+    return next;
+  }
+
+  async function status(jobId, session) {
+    const record = await owned(jobId, session);
+    const entry = local.get(jobId);
+    if (entry) return receipt(entry.record);
+    if (ACTIVE.has(record.state)) {
+      if (!alive(record.process?.pid)) {
+        record.state = 'interrupted';
+        record.updatedAt = new Date().toISOString();
+        record.error = { code: 'PROCESS_INTERRUPTED', message: 'The local worker stopped. No automatic retry was made.' };
+        await store.write(record);
+      } else return receipt(record, { code: 'STATE_UNCERTAIN', message: 'Another local worker owns this job; its last saved state is shown.' });
+    }
+    return receipt(record);
+  }
+
+  async function list(session, { limit = 20 } = {}) {
+    session = { ...session };
+    const owner = ownerOf(session);
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100) throw failure('INVALID_INPUT', 'limit must be an integer between 1 and 100.');
+    let entries;
+    try { entries = await fs.readdir(store.jobsDir, { withFileTypes: true }); }
+    catch (error) { if (error.code === 'ENOENT') return { jobs: [] }; throw error; }
+    const records = [];
+    for (const entry of entries) {
+      if (!entry.isDirectory() || !/^[0-9a-f-]{36}$/.test(entry.name)) continue;
+      try {
+        const record = await store.read(entry.name);
+        if (record.owner === owner) records.push(record);
+      } catch (error) { if (error.code !== 'NOT_FOUND') throw error; }
+    }
+    records.sort((a, b) => b.createdAt.localeCompare(a.createdAt) || b.jobId.localeCompare(a.jobId));
+    const jobs = [];
+    for (const record of records.slice(0, limit)) {
+      const { result, ...summary } = await status(record.jobId, session);
+      jobs.push({ ...summary, hasResult: Boolean(result), ...(result?.artifact ? { artifact: result.artifact } : {}) });
+    }
+    return { jobs };
+  }
+
+  async function exportLock(entry) {
+    const lock = path.join(store.jobsDir, 'exports', entry.record.owner);
+    const reaper = `${lock}.reaping`;
+    const identity = { pid: process.pid, instance, jobId: entry.record.jobId };
+    let uncertain = 0;
+    const incomplete = () => failure('EXPORT_LOCK_UNCERTAIN', 'Export coordination is incomplete. No new ERP request was made; inspect the local task history before retrying.');
+    function waitForPublication() { if (++uncertain >= 10) throw incomplete(); }
+    while (!closed && entry.record.state === 'queued') {
+      try { await fs.access(reaper); waitForPublication(); await pause(20); continue; }
+      catch (error) { if (error.code !== 'ENOENT') throw error; }
+      try {
+        await fs.mkdir(lock, { mode: 0o700 });
+        await fs.writeFile(path.join(lock, 'owner.json'), JSON.stringify(identity), { flag: 'wx', mode: 0o600 });
+        return async () => {
+          const current = JSON.parse(await fs.readFile(path.join(lock, 'owner.json'), 'utf8'));
+          if (current.instance === instance && current.jobId === identity.jobId) await fs.rm(lock, { recursive: true, force: true });
+        };
+      } catch (error) { if (error.code !== 'EEXIST') throw error; }
+      let holder;
+      try { holder = JSON.parse(await fs.readFile(path.join(lock, 'owner.json'), 'utf8')); }
+      catch (error) { if (error.code !== 'ENOENT') throw error; }
+      if (!holder) waitForPublication();
+      else {
+        if (!Number.isSafeInteger(holder.pid) || holder.pid < 1 || typeof holder.instance !== 'string' || typeof holder.jobId !== 'string') throw incomplete();
+        uncertain = 0;
+      }
+      if (holder && !alive(holder.pid)) {
+        try {
+          await fs.mkdir(reaper, { mode: 0o700 });
+        } catch (error) { if (error.code === 'EEXIST') { await pause(20); continue; } throw error; }
+        try {
+          const current = JSON.parse(await fs.readFile(path.join(lock, 'owner.json'), 'utf8'));
+          if (current.instance === holder.instance && !alive(current.pid)) await fs.rm(lock, { recursive: true, force: true });
+        } catch (error) { if (error.code !== 'ENOENT') throw error; }
+        finally { await fs.rmdir(reaper); }
+      }
+      await pause(20);
+    }
+    return null;
+  }
+
+  async function run(entry, definition, session) {
+    let release;
+    const active = () => !closed && ACTIVE.has(entry.record.state);
+    try {
+      if (definition.effect === 'export') release = await exportLock(entry);
+      if (!active()) return;
+      entry.record.state = 'running';
+      entry.record.updatedAt = new Date().toISOString();
+      await persist(entry);
+      if (!active()) return;
+      const dir = store.jobDir(entry.record.jobId);
+      const outputPath = path.join(dir, entry.record.operation === 'sales_volume_export' ? 'export.csv' : 'export.xlsx');
+      const result = await withErpContext(session, async () => {
+        const value = await definition.invoke(structuredClone(entry.record.params), {
+          outputPath,
+          onProgress: async progress => {
+            if (!active()) throw failure('JOB_INTERRUPTED', 'The local worker stopped.');
+            const saved = {};
+            for (const key of ['taskId', 'stage', 'status', 'phase', 'boxes']) {
+              if (typeof progress?.[key] === 'string') saved[key] = progress[key].slice(0, 200);
+              else if (typeof progress?.[key] === 'number' && Number.isFinite(progress[key])) saved[key] = progress[key];
+            }
+            if (entry.record.operation === 'packing_detail_export' && typeof progress?.taskId === 'string' && progress.taskId) entry.record.checkpoint = { taskId: progress.taskId };
+            entry.record.progress = saved;
+            entry.record.updatedAt = new Date().toISOString();
+            await persist(entry);
+            if (!active()) throw failure('JOB_INTERRUPTED', 'The local worker stopped.');
+          },
+        });
+        if (!active()) return;
+        if (value && typeof value[Symbol.asyncIterator] === 'function') return consumePages(value, { dir, active });
+        return adaptResult(value, { dir, outputPath });
+      });
+      if (!active()) return;
+      entry.record.state = 'succeeded';
+      entry.record.result = result;
+      entry.record.updatedAt = new Date().toISOString();
+      await persist(entry);
+    } catch (error) {
+      if (!active()) return;
+      entry.record.state = 'failed';
+      entry.record.updatedAt = new Date().toISOString();
+      const cause = error instanceof StreamFailure ? error.cause : error;
+      entry.record.error = cause instanceof AuthRequiredError || cause?.code === 'LOGIN_REQUIRED'
+        ? { code: 'LOGIN_REQUIRED', message: 'The ERP session needs browser login.' }
+        : { code: 'EXECUTION_FAILED', message: redactSensitiveText(cause?.message || 'ERP execution failed.', [session.token, session.username]).slice(0, 1200) };
+      if (error instanceof StreamFailure) entry.record.result = error.partialResult;
+      await persist(entry);
+    } finally {
+      if (release) await release();
+    }
+  }
+
+  async function admit(operation, params, session, { requestId } = {}) {
+    if (closed) throw failure('JOBS_CLOSED', 'The local worker is closed.');
+    session = { ...session };
+    const owner = ownerOf(session);
+    const definition = getOperation(operation);
+    if (!definition) throw failure('UNKNOWN_OPERATION', 'Unknown ERP operation.');
+    const parsed = definition.schema.parse(params);
+    if (definition.effect === 'export' && requestId === undefined) throw failure('REQUEST_ID_REQUIRED', 'Exports require a stable requestId.');
+    if (requestId !== undefined && (typeof requestId !== 'string' || !requestId.trim() || requestId.length > 200)) throw failure('INVALID_INPUT', 'requestId must be a nonempty string of at most 200 characters.');
+    await store.init();
+    if (closed) throw failure('JOBS_CLOSED', 'The local worker is closed.');
+    const fingerprint = digest(canonical({ operation, params: parsed }));
+    let claim;
+    if (requestId !== undefined) {
+      claim = path.join(store.jobsDir, 'requests', digest(canonical([owner, requestId])));
+      try { await fs.mkdir(claim, { mode: 0o700 }); }
+      catch (error) {
+        if (error.code !== 'EEXIST') throw error;
+        let saved;
+        for (let attempt = 0; attempt < 10; attempt += 1) {
+          try { saved = JSON.parse(await fs.readFile(path.join(claim, 'claim.json'), 'utf8')); break; }
+          catch (readError) { if (readError.code !== 'ENOENT') throw failure('REQUEST_UNCERTAIN', 'The saved request admission is uncertain; it will not be replayed.'); await pause(10); }
+        }
+        if (!saved) throw failure('REQUEST_UNCERTAIN', 'The saved request admission is uncertain; it will not be replayed.');
+        if (saved.fingerprint !== fingerprint) throw failure('REQUEST_CONFLICT', 'requestId was already used for a different call.');
+        return status(saved.jobId, session);
+      }
+    }
+    const jobId = crypto.randomUUID();
+    const now = new Date().toISOString();
+    const record = { jobId, operation, state: 'queued', createdAt: now, updatedAt: now, owner, params: parsed, fingerprint, process: { pid: process.pid, instance } };
+    if (operation === 'packing_detail_export' && parsed.taskId) record.checkpoint = { taskId: parsed.taskId };
+    const entry = { record, writes: Promise.resolve() };
+    await fs.mkdir(store.jobDir(jobId), { mode: 0o700 });
+    await persist(entry);
+    if (claim) {
+      const temporary = path.join(claim, `${crypto.randomUUID()}.tmp`);
+      await fs.writeFile(temporary, JSON.stringify({ jobId, fingerprint }), { flag: 'wx', mode: 0o600 });
+      await fs.rename(temporary, path.join(claim, 'claim.json'));
+    }
+    local.set(jobId, entry);
+    if (closed) {
+      record.state = 'interrupted';
+      record.error = { code: 'PROCESS_INTERRUPTED', message: 'The local worker stopped. No automatic retry was made.' };
+      await persist(entry);
+    } else {
+      entry.done = run(entry, definition, { ...session }).catch(() => {});
+      if (waitMs) {
+        let timer;
+        await Promise.race([entry.done, new Promise(resolve => { timer = setTimeout(resolve, waitMs); })]);
+        clearTimeout(timer);
+      }
+    }
+    return receipt(record);
+  }
+
+  function start(...args) {
+    const pending = admit(...args);
+    admissions.add(pending);
+    pending.finally(() => admissions.delete(pending)).catch(() => {});
+    return pending;
+  }
+
+  async function resume(jobId, session, { requestId } = {}) {
+    session = { ...session };
+    const record = await owned(jobId, session);
+    if (ACTIVE.has(record.state) && alive(record.process?.pid)) throw failure('RESUME_UNSUPPORTED', 'This job may still be running.');
+    if (record.operation !== 'packing_detail_export' || !record.checkpoint?.taskId) throw failure('RESUME_UNSUPPORTED', 'Only packing jobs with a saved task ID support explicit resume.');
+    if (!requestId) throw failure('REQUEST_ID_REQUIRED', 'Resume requires a stable requestId.');
+    return start(record.operation, { ...record.params, taskId: record.checkpoint.taskId }, session, { requestId });
+  }
+
+  async function cancel(jobId, session) {
+    const record = await owned(jobId, session);
+    const entry = local.get(jobId);
+    if (record.state === 'queued' && entry?.record.state === 'queued') {
+      entry.record.state = 'cancelled';
+      entry.record.updatedAt = new Date().toISOString();
+      await persist(entry);
+      return receipt(entry.record);
+    }
+    if (ACTIVE.has(record.state)) return receipt(entry?.record || record, { code: 'CANCELLATION_UNSUPPORTED', message: 'Running ERP work cannot be cancelled end to end.' });
+    return receipt(entry?.record || record);
+  }
+
+  async function close() {
+    closed = true;
+    await Promise.allSettled([...admissions]);
+    for (const entry of local.values()) {
+      if (!ACTIVE.has(entry.record.state)) continue;
+      entry.record.state = 'interrupted';
+      entry.record.updatedAt = new Date().toISOString();
+      entry.record.error = { code: 'PROCESS_INTERRUPTED', message: 'The local worker stopped. ERP work was not cancelled.' };
+      await persist(entry);
+    }
+  }
+
+  return { start, status, list, resume, cancel, close };
+}
+
+module.exports = { createJobs };