@volter/supercode-interchange 0.1.22 → 0.1.24

package/inspection-schemas.d.ts

@@ -0,0 +1,4 @@
+/** Reads the complete typed config file layers. Never resolves credentials or runs hooks. */
+export function inspectionSchemaTier(context?: { tier?: 'full' | 'medium' | 'minimal' | null; cwd?: string; env?: Record<string, string | undefined>; diagnostic?: (text: string) => void }): 'full' | 'medium' | 'minimal';
+export function inspectionToolSchemas(tier?: 'full' | 'medium' | 'minimal'): Array<{ name: string; description: string; parameters: object }>;
+export function inspectionSchemaStats(tier: 'full' | 'medium' | 'minimal'): { tier: string; fullTokens: bigint; tierTokens: bigint; pct: bigint };

package/inspection-schemas.mjs

@@ -0,0 +1,117 @@
+// Schema cost from the same builtin declarations, without constructing tools
+// or an agent. Configuration is admitted as a whole before its tier is used.
+import { readFileSync, statSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { userInfo } from 'node:os';
+import { parseSkillToml } from './skill-toml.mjs';
+import { decodeSessionUtf8 } from './session-file.mjs';
+import { cloneNativeJson, stringifyNativeJson } from './native-json.mjs';
+import { inspectionPercentage } from './session-inspect.mjs';
+import fields from './inspection-config-fields.json' with { type: 'json' };
+import builtins from './inspection-builtin-tools.json' with { type: 'json' };
+
+const object = value => value != null && typeof value === 'object' && !Array.isArray(value) && !(value instanceof Date);
+function admit(value, schema) {
+  if (typeof schema === 'string') {
+    if (schema === 'serde_json::Value') return true;
+    if (schema === 'String') return typeof value === 'string';
+    if (schema === 'bool') return typeof value === 'boolean';
+    if (schema === 'f32' || schema === 'f64') return typeof value === 'number' || typeof value === 'bigint';
+    const bits = schema === 'usize' ? 64 : Number(schema.slice(1)), unsigned = schema[0] === 'u';
+    return typeof value === 'bigint' && value >= (unsigned ? 0n : -(1n << BigInt(bits - 1)))
+      && value <= (1n << BigInt(unsigned ? bits : bits - 1)) - 1n;
+  }
+  if (schema.array) return Array.isArray(value) && value.every(member => admit(member, schema.array));
+  if (schema.map) return object(value) && Object.values(value).every(member => admit(member, schema.map));
+  if (!object(value)) return false;
+  const definition = fields.definitions[schema.record];
+  for (const [key, field] of Object.entries(definition)) {
+    if (field.flatten) continue;
+    if (!Object.hasOwn(value, key)) { if (field.required) return false; }
+    else if (!admit(value[key], field.schema)) return false;
+  }
+  return true;
+}
+const exists = path => { try { statSync(path); return true; } catch { return false; } };
+const file = path => { try { return statSync(path).isFile(); } catch { return false; } };
+function configHome(env) {
+  if (env.SUPERCODE_HOME) return env.SUPERCODE_HOME;
+  if (env.XDG_CONFIG_HOME) return join(env.XDG_CONFIG_HOME, 'supercode');
+  let home = env.HOME || (process.platform === 'win32' && env.USERPROFILE);
+  if (!home) try { home = userInfo().homedir; } catch { home = '.'; }
+  return join(home, '.config', 'supercode');
+}
+export function inspectionSchemaTier({ tier = null, cwd = process.cwd(), env = process.env, diagnostic = () => {} } = {}) {
+  // Even an explicit tier follows the native file-reading/warning behavior.
+  const read = path => {
+    let bytes;
+    try { bytes = readFileSync(path); }
+    catch (error) { if (error.code !== 'ENOENT') diagnostic(`warning: failed to read config \`${path}\` (${error.code ?? 'filesystem error'}) — ignoring this file`); return {}; }
+    try {
+      const value = parseSkillToml(decodeSessionUtf8(bytes));
+      if (!admit(value, { record: fields.root })) throw new Error('typed configuration');
+      return value;
+    } catch { diagnostic(`warning: failed to parse config \`${path}\` (TOML syntax/schema error) — ignoring this file`); return {}; }
+  };
+  const user = read(join(configHome(env), 'config.toml')), markers = user.core?.project_root_markers ?? ['.git'];
+  let root = null, at = cwd;
+  for (;;) {
+    if (markers.some(marker => marker !== '' && exists(join(at, marker)))) { root = at; break; }
+    const parent = dirname(at); if (parent === at) break; at = parent;
+  }
+  let value = user.schema_tier;
+  for (const name of ['.supercode.toml', '.supercode.local.toml']) {
+    at = cwd;
+    for (;;) {
+      const path = join(at, name);
+      if (file(path)) { const layer = read(path); if (layer.schema_tier != null) value = layer.schema_tier; break; }
+      if (at === root) break;
+      const parent = dirname(at); if (parent === at) break; at = parent;
+    }
+  }
+  return tier ?? (['full', 'medium', 'minimal'].includes(value) ? value : 'full');
+}
+const abbreviations = ['e.g.', 'i.e.', 'etc.', 'Mr.', 'Mrs.', 'Dr.', 'vs.', 'cf.'];
+function sentences(text, maximum) {
+  let count = 0;
+  for (let at = 0; at < text.length; at++) {
+    if (!'.!?'.includes(text[at]) || at + 1 < text.length && ![' ', '\n'].includes(text[at + 1])) continue;
+    if (text[at] === '.' && abbreviations.some(value => text.slice(0, at + 1).endsWith(value))) continue;
+    if (++count === maximum) return text.slice(0, at + 1);
+  }
+  return text;
+}
+function minifyNode(node, tier) {
+  if (!object(node)) return;
+  delete node.examples; delete node.title;
+  if (typeof node.description === 'string') node.description = sentences(node.description, tier === 'minimal' ? 1 : 2);
+  const required = Array.isArray(node.required) ? node.required.filter(key => typeof key === 'string') : [];
+  if (object(node.properties)) for (const [key, child] of Object.entries(node.properties)) {
+    if (object(child)) {
+      delete child.examples; delete child.title;
+      if (tier === 'minimal' && !required.includes(key)) delete child.description;
+      else if (typeof child.description === 'string') child.description = sentences(child.description, 1);
+    }
+    minifyNode(child, tier);
+  }
+  if (Array.isArray(node.items)) node.items.forEach(child => minifyNode(child, tier));
+  else minifyNode(node.items, tier);
+  for (const key of ['anyOf', 'oneOf', 'allOf']) if (Array.isArray(node[key])) node[key].forEach(child => minifyNode(child, tier));
+  for (const key of ['if', 'then', 'else']) minifyNode(node[key], tier);
+  for (const key of ['$defs', 'definitions', 'patternProperties']) if (object(node[key])) Object.values(node[key]).forEach(child => minifyNode(child, tier));
+}
+export function inspectionToolSchemas(tier = 'full') {
+  if (!['full', 'medium', 'minimal'].includes(tier)) throw new TypeError('schema tier must be full, medium or minimal');
+  return builtins.map(schema => {
+    const full = cloneNativeJson(schema); if (tier === 'full') return full;
+    const description = sentences(full.description, tier === 'minimal' ? 1 : 2), parameters = cloneNativeJson(full.parameters);
+    minifyNode(parameters, tier);
+    const size = (description, parameters) => Buffer.byteLength(description) + Buffer.byteLength(stringifyNativeJson(parameters));
+    return size(description, parameters) >= size(full.description, full.parameters) ? full : { name: full.name, description, parameters };
+  });
+}
+export function inspectionSchemaStats(tier) {
+  const tokens = schemas => BigInt(Math.ceil(Buffer.byteLength(stringifyNativeJson(schemas)) / 4));
+  const fullTokens = tokens(inspectionToolSchemas('full')), tierTokens = tokens(inspectionToolSchemas(tier));
+  return { tier, fullTokens, tierTokens, pct: inspectionPercentage(tierTokens, fullTokens) };
+}

package/job-notepad-read.mjs

@@ -0,0 +1,97 @@
+// A job's recorded notepad. The selected store is opened read-only, after
+// the same complete job-file validation and first-id/profile choice as jobs.get.
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { isAbsolute } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { resolveHarnessHomes } from './homes.mjs';
+import { parseNativeJson } from './native-json.mjs';
+import { hermesJobRecords } from './hermes-read-validation.mjs';
+import { childPath } from './session-spend-files.mjs';
+import { profilePathJoin as join, profilePathParent as parent } from './profile-paths.mjs';
+import { nativeTrim } from './text.mjs';
+
+const jobHarnesses = ['claude-code', 'hermes', 'openclaw', 'orchestrator'];
+const object = value => value != null && typeof value === 'object' && !Array.isArray(value);
+const utf8 = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
+const compare = (a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b));
+const refuse = (message, rpcCode = -32602) => { throw Object.assign(new Error(message), { rpcCode }); };
+const directory = path => { try { return statSync(path).isDirectory(); } catch { return false; } };
+const filesystem = (path, cwd) => !path.length || isAbsolute(path) || process.platform === 'win32' && /^[A-Za-z]:/u.test(path) ? path : join(cwd, path);
+function struct(value, fields, name) {
+  if (Array.isArray(value)) {
+    if (value.length > fields.length) refuse(`${name} has too many fields`);
+    return Object.fromEntries(value.map((value, at) => [fields[at], value]));
+  }
+  if (!object(value)) refuse(`${name} must be a struct`);
+  return value;
+}
+function query(params, context) {
+  const query = struct(params, ['harness', 'id', 'key', 'value', 'profile', 'homes'], 'notepad params');
+  for (const key of ['harness', 'id']) {
+    if (Object.hasOwn(query, key) && typeof query[key] !== 'string') refuse(`${key} must be a string`);
+  }
+  for (const key of ['key', 'value', 'profile']) if (query[key] != null && typeof query[key] !== 'string') refuse(`${key} must be a string`);
+  const homes = resolveHarnessHomes(context.env);
+  if (Object.hasOwn(query, 'homes')) {
+    const supplied = struct(query.homes, Object.keys(homes), 'homes');
+    for (const key of Object.keys(homes)) if (Object.hasOwn(supplied, key)) {
+      if (typeof supplied[key] !== 'string') refuse(`homes.${key} must be a string`);
+      homes[key] = supplied[key];
+    }
+  }
+  return { ...query, harness: query.harness ?? '', id: query.id ?? '', homes };
+}
+function jobStores(root) {
+  const stores = [{ path: join(root, 'cron/jobs.json'), profile: null }], profiles = join(root, 'profiles');
+  try {
+    const named = readdirSync(profiles, { encoding: 'buffer' }).filter(name => {
+      const text = name.toString('utf8');
+      return text !== 'node_modules' && !text.startsWith('.') && directory(childPath(profiles, name));
+    }).map(name => ({ path: childPath(childPath(profiles, name), 'cron/jobs.json'), profile: name.toString('utf8') }));
+    named.sort((a, b) => compare(a.profile, b.profile)); stores.push(...named);
+  } catch { /* an unread profile directory contributes no stores */ }
+  return stores;
+}
+function requireJob(selected, root) {
+  for (const store of jobStores(root)) {
+    let jobs;
+    try { jobs = hermesJobRecords(String(store.path), parseNativeJson(utf8.decode(readFileSync(store.path)))); }
+    catch { continue; } // One invalid record invalidates that entire job file.
+    if (!jobs.has(selected.id)) continue;
+    if (store.profile === (selected.profile ?? null)) return;
+    refuse(`job \`${selected.id}\` belongs to ${store.profile == null ? 'the root home' : `profile \`${store.profile}\``}; name that profile with \`profile\``);
+  }
+  refuse(`${selected.harness} has no job \`${selected.id}\``);
+}
+function readEntries(path, id, key) {
+  let db;
+  try {
+    db = new DatabaseSync(path, { readOnly: true, allowExtension: false });
+    db.exec('PRAGMA busy_timeout=5000');
+    // Read TEXT as bytes so malformed UTF-8 is an error, as rusqlite's String
+    // conversion is. SQLite BLOB/NULL/numeric cells remain type errors.
+    const rows = db.prepare(`SELECT typeof(key) AS kt, CAST(key AS BLOB) AS kb,
+      typeof(value) AS vt, CAST(value AS BLOB) AS vb,
+      typeof(updated_at) AS ut, CAST(updated_at AS BLOB) AS ub
+      FROM cron_notepad WHERE job_id = ? AND (? IS NULL OR key = ?) ORDER BY key`).all(id, key, key);
+    return rows.map(row => {
+      const entry = {};
+      for (const [name, prefix] of [['key', 'k'], ['value', 'v'], ['updated_at', 'u']]) {
+        if (row[prefix + 't'] !== 'text') throw new Error(`${name} is not SQLite TEXT`);
+        entry[name] = utf8.decode(row[prefix + 'b']);
+      }
+      return entry;
+    });
+  } catch (error) { refuse(`${path}: ${error.message}`, -32000); }
+  finally { db?.close(); }
+}
+export function readJobNotepad(params, { env = process.env, cwd = process.cwd() } = {}) {
+  const selected = query(params, { env, cwd });
+  if (!jobHarnesses.includes(selected.harness)) refuse(`\`${selected.harness}\` has no scheduled jobs; \`jobs.notepad\` is supported for: ${jobHarnesses.join(', ')}`, -32020);
+  if (!nativeTrim(selected.id)) refuse('a notepad call needs the job id');
+  if (selected.harness !== 'hermes') refuse(`\`${selected.harness}\` keeps no job notepad; the notepad is supported for: hermes`, -32020);
+  const root = parent(selected.homes.hermes) ?? '.', actualRoot = filesystem(root, cwd);
+  requireJob(selected, actualRoot);
+  const home = selected.profile == null ? root : join(join(root, 'profiles'), selected.profile), store = join(home, 'cron/notepad.db'), path = filesystem(store, cwd);
+  return { harness: selected.harness, id: selected.id, entries: existsSync(path) ? readEntries(path, selected.id, selected.key ?? null) : [] };
+}

package/jobs-control.mjs

@@ -0,0 +1,250 @@
+// Scheduled-job writes belong to each harness's own command/operator. The
+// existing observed reader, never a command's echo, establishes the outcome.
+import { readFileSync } from 'node:fs';
+import { isAbsolute } from 'node:path';
+import { resolveHarnessHomes } from './homes.mjs';
+import { listJobs, jobFloat, JOB_HARNESSES } from './jobs-read.mjs';
+import { readJobNotepad } from './job-notepad-read.mjs';
+import { profilePathJoin as join, profilePathParent as parent } from './profile-paths.mjs';
+import { nativeTrim } from './text.mjs';
+import { nativeInteger, nativeNumberKind, parseNativeJson, setNativeFloat, stringifyNativeJsonMember } from './native-json.mjs';
+import { supportRegistryReport } from './support-report.mjs';
+import { callProfileOrchestrator } from './profile-orchestrator-door.mjs';
+import { profileCommandFailure as failed, profileShellQuote as quote, runProfileCommand, requireProfileCommandSuccess } from './profile-command.mjs';
+
+export const CONTROLLED_JOB_HARNESSES = Object.freeze(['hermes', 'openclaw', 'orchestrator']);
+const verbs = ['create', 'update', 'pause', 'resume', 'run', 'delete'];
+const invalid = message => { throw Object.assign(new Error(message), { rpcCode: -32602 }); };
+const unsupported = message => { throw Object.assign(new Error(message), { rpcCode: -32020 }); };
+const display = path => Buffer.isBuffer(path) ? path.toString('utf8') : path;
+const utf8 = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
+const compare = (a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b));
+const mutationFields = ['harness', 'id', 'name', 'schedule', 'payload', 'session_target', 'deliver', 'profile', 'skills', 'workdir', 'model', 'provider', 'repeat', 'homes'];
+function struct(value, fields, name, strict = false) {
+  if (Array.isArray(value)) {
+    if (value.length > fields.length) invalid(`${name} has too many fields`);
+    return parseNativeJson(`{${value.map((_, at) => `${JSON.stringify(fields[at])}:${stringifyNativeJsonMember(value, String(at))}`).join(',')}}`);
+  }
+  if (value == null || typeof value !== 'object') invalid(`${name} must be a struct`);
+  if (strict) for (const key of Object.keys(value)) if (!fields.includes(key)) invalid(`unknown field \`${key}\` in ${name}`);
+  return value;
+}
+function strings(value, keys, name) {
+  for (const key of keys) if (value[key] != null && typeof value[key] !== 'string') invalid(`${name}${key} must be a string`);
+}
+function selectedHomes(value, context) {
+  const homes = Object.fromEntries(Object.entries(resolveHarnessHomes(context.env)).map(([key, path]) => [key, display(path)]));
+  if (Object.hasOwn(value, 'homes')) {
+    const supplied = struct(value.homes, Object.keys(homes), 'homes');
+    for (const key of Object.keys(homes)) if (Object.hasOwn(supplied, key)) {
+      if (typeof supplied[key] !== 'string') invalid(`homes.${key} must be a string`);
+      homes[key] = supplied[key];
+    }
+  }
+  return homes;
+}
+function params(value, context, notepad = false) {
+  const fields = notepad ? ['harness', 'id', 'key', 'value', 'profile', 'homes'] : mutationFields;
+  value = struct(value, fields, notepad ? 'notepad mutation' : 'job mutation');
+  if (Object.hasOwn(value, 'harness') && typeof value.harness !== 'string') invalid('harness must be a string');
+  if (notepad && Object.hasOwn(value, 'id') && typeof value.id !== 'string') invalid('id must be a string');
+  strings(value, notepad ? ['key', 'value', 'profile'] : ['id', 'name', 'session_target', 'profile', 'workdir', 'model', 'provider'], '');
+  const result = { ...value, harness: value.harness ?? '', id: value.id ?? (notepad ? '' : null) };
+  if (!notepad) {
+    for (const [name, fields, strict] of [['schedule', ['kind', 'minutes', 'expr', 'run_at'], true], ['payload', ['kind', 'text'], false], ['deliver', ['target', 'chat_id'], true]]) {
+      if (value[name] == null) continue;
+      const item = struct(value[name], fields, name, strict);
+      if (name !== 'deliver' && Object.hasOwn(item, 'kind') && typeof item.kind !== 'string') invalid(`${name}.kind must be a string`);
+      strings(item, name === 'schedule' ? ['expr', 'run_at'] : name === 'payload' ? ['text'] : fields, `${name}.`);
+      if (name === 'schedule' && item.minutes != null && typeof item.minutes !== 'number') invalid('schedule.minutes must be a number');
+      result[name] = { ...item, ...(name === 'deliver' ? {} : { kind: item.kind ?? '' }) };
+    }
+    if (value.skills != null && (!Array.isArray(value.skills) || value.skills.some(skill => typeof skill !== 'string'))) invalid('skills must be an array of strings');
+    if (value.repeat != null) {
+      const count = nativeInteger(value, 'repeat') ?? (nativeNumberKind(value, 'repeat') == null && Number.isInteger(value.repeat) && value.repeat >= 0 ? BigInt(value.repeat) : null);
+      if (count == null || count > 0xffffffffn) invalid('repeat must be an unsigned 32-bit integer');
+      result.repeat = Number(count);
+    }
+  }
+  result.homes = selectedHomes(value, context);
+  return result;
+}
+function requireJobHarness(harness, method) {
+  if (!JOB_HARNESSES.includes(harness)) unsupported(`\`${harness}\` has no scheduled jobs; \`${method}\` is supported for: ${JOB_HARNESSES.join(', ')}`);
+}
+function harnessProgram(harness, context) {
+  const override = nativeTrim(context.env[harness === 'hermes' ? 'SUPERCODE_HERMES_BIN' : 'SUPERCODE_OPENCLAW_BIN'] ?? '');
+  if (override) return override;
+  const program = supportRegistryReport(context).harnesses.find(row => row.id === harness)?.runtime?.default_launch?.program;
+  if (program == null) unsupported(`the registry has no launch for \`${harness}\`, so its CLI cannot be located`);
+  return program.replace(/-acp$/u, '');
+}
+const hermesHome = mutation => mutation.profile == null ? parent(mutation.homes.hermes) ?? '.' : join(join(parent(mutation.homes.hermes) ?? '.', 'profiles'), mutation.profile);
+function command(harness, mutation, context) {
+  const program = harnessProgram(harness, context), env = { ...context.env }, args = [], rendered = [];
+  if (harness === 'hermes') env.HERMES_HOME = hermesHome(mutation);
+  else { env.OPENCLAW_STATE_DIR = mutation.homes.openclaw; env.OPENCLAW_CONFIG_PATH = join(mutation.homes.openclaw, 'openclaw.json'); }
+  const add = (...values) => { args.push(...values); rendered.push(...values.map(quote)); };
+  const secret = value => { args.push(value); rendered.push('<redacted>'); };
+  return { add, secret, request: () => ({ program, args, env, owner: 'job', ran: [quote(program), ...rendered].join(' ') }) };
+}
+function gateway(homes, context) {
+  const descriptor = supportRegistryReport(context).harnesses.find(row => row.id === 'openclaw');
+  if (!descriptor) unsupported('the registry has no openclaw descriptor');
+  const connect = descriptor.runtime?.connect_launch;
+  if (!connect) unsupported('openclaw has no registered connect-mode launch, so its gateway cannot be located');
+  let path = join(homes.openclaw, 'openclaw.json');
+  if (path.startsWith('~/')) path = join('/', path.slice(2));
+  const actual = !path.length || isAbsolute(path) || process.platform === 'win32' && /^[A-Za-z]:/u.test(path) ? path : join(context.cwd, path);
+  let text, config = {};
+  try { text = utf8.decode(readFileSync(actual)); } catch { /* Native read failures use the declared default endpoint. */ }
+  if (text !== undefined) try { config = parseNativeJson(text); }
+  catch { unsupported(`openclaw's gateway endpoint could not be resolved from its own config: connect-mode config ${path} is not valid JSON`); }
+  const pointer = name => {
+    let value = config, owner, key;
+    for (const part of name?.slice(1).split('/') ?? []) { owner = value; key = part.replaceAll('~1', '/').replaceAll('~0', '~'); value = value != null && typeof value === 'object' ? value[key] : undefined; }
+    return { value, owner, key };
+  };
+  const explicit = pointer(connect.address_pointer).value, port = pointer(connect.port_pointer);
+  const integer = nativeInteger(port.owner, port.key), scheme = connect.default_address?.split('://')[0] ?? 'ws';
+  let address = typeof explicit === 'string' && nativeTrim(explicit) ? nativeTrim(explicit) : integer != null ? `${scheme}://127.0.0.1:${integer}` : connect.default_address;
+  if (address == null) unsupported(`openclaw's gateway endpoint could not be resolved from its own config: connect-mode address pointer \`${connect.address_pointer}\` does not name a non-empty string in ${path}`);
+  address = address.replace(/\/+$/u, ''); if (!address.includes('://')) address = `${scheme}://${address}`;
+  const supplied = pointer(connect.auth_pointer).value;
+  const token = typeof supplied === 'string' && nativeTrim(supplied) ? nativeTrim(supplied) : null;
+  if (connect.auth_pointer != null && token == null && connect.default_address == null) unsupported(`openclaw's gateway endpoint could not be resolved from its own config: connect-mode auth pointer \`${connect.auth_pointer}\` does not name a non-empty string in ${path}`);
+  return { address, token };
+}
+function schedule(schedule, typed = false) {
+  const field = { interval: 'minutes', cron: 'expr', once: 'run_at' }[schedule.kind];
+  if (!field) invalid(`unknown schedule kind \`${schedule.kind}\`; use interval, cron, or once`);
+  if (schedule[field] == null) invalid(`a${schedule.kind === 'interval' ? 'n' : ''} ${schedule.kind} schedule needs \`${field}\``);
+  if (typed) { const value = { kind: schedule.kind, [field]: schedule[field] }; if (field === 'minutes') setNativeFloat(value, field, schedule[field]); return value; }
+  return field === 'minutes' ? `every ${jobFloat(schedule.minutes, true)}m` : schedule[field];
+}
+const payloadKind = payload => nativeTrim(payload.kind) || 'prompt';
+function payloadText(payload) { if (payload.text == null || !nativeTrim(payload.text)) invalid(`a \`${payloadKind(payload)}\` payload needs its text`); return payload.text; }
+function deliverWord(deliver) {
+  if (deliver.target == null) return null;
+  const target = nativeTrim(deliver.target), chat = deliver.chat_id;
+  return chat != null && !target.includes(':') && nativeTrim(chat) ? `${target}:${nativeTrim(chat)}` : target;
+}
+function hermesCommand(verb, mutation, context) {
+  if (mutation.deliver != null && !nativeTrim(mutation.deliver.target ?? '') && mutation.deliver.chat_id != null) invalid('a delivery needs a target; a chat id alone names no destination, so supercode refuses rather than dropping it');
+  if (mutation.session_target != null) unsupported('hermes cron fires always open their own `platform=cron` session; hermes has no session-target verb, so Volter Harness refuses rather than dropping the field');
+  const c = command('hermes', mutation, context), add = c.add;
+  add('cron', { create: 'create', update: 'edit', pause: 'pause', resume: 'resume', run: 'run', delete: 'remove' }[verb]);
+  if (verb !== 'create') add(mutation.id);
+  const definitions = () => {
+    if (mutation.skills != null) { if (!mutation.skills.length && verb === 'update') add('--clear-skills'); for (const skill of mutation.skills) add('--skill', skill); }
+    for (const field of ['workdir', 'model', 'provider', 'repeat']) if (mutation[field] != null) add(`--${field}`, String(mutation[field]));
+  };
+  const payload = () => {
+    if (mutation.payload == null) return;
+    const kind = payloadKind(mutation.payload);
+    if (!['prompt', 'script'].includes(kind)) unsupported(`hermes cron carries a \`prompt\` or a \`--script\` payload; it has no verb for a \`${kind}\` payload`);
+    const text = payloadText(mutation.payload); kind === 'script' ? add('--script', text) : verb === 'update' ? add('--prompt', text) : add(text);
+  };
+  if (verb === 'create' || verb === 'update') {
+    if (verb === 'update' && mutation.schedule != null) add('--schedule', schedule(mutation.schedule));
+    if (mutation.name != null) add('--name', mutation.name);
+    if (mutation.deliver != null) { const word = deliverWord(mutation.deliver); if (word != null) add('--deliver', word); }
+    if (verb === 'create' && mutation.payload != null && payloadKind(mutation.payload) === 'script') add('--script', payloadText(mutation.payload));
+    definitions();
+    if (verb === 'create') add(schedule(mutation.schedule));
+    if (!(verb === 'create' && mutation.payload != null && payloadKind(mutation.payload) === 'script')) payload();
+  }
+  return c.request();
+}
+function openclawCommand(verb, mutation, context) {
+  const connection = gateway(mutation.homes, context), c = command('openclaw', mutation, context), add = c.add;
+  add('cron', { create: 'add', update: 'edit', pause: 'disable', resume: 'enable', run: 'run', delete: 'rm' }[verb]);
+  if (verb !== 'create') add(mutation.id);
+  add('--url', connection.address); if (connection.token != null) { add('--token'); c.secret(connection.token); }
+  if (verb === 'create' || verb === 'update') {
+    if (mutation.name != null) add('--name', mutation.name);
+    if (mutation.schedule != null) { const value = schedule(mutation.schedule); add({ interval: '--every', cron: '--cron', once: '--at' }[mutation.schedule.kind], mutation.schedule.kind === 'interval' ? value.slice(6) : value); }
+    if (mutation.payload != null) {
+      const kind = payloadKind(mutation.payload), flag = { prompt: '--message', system_event: '--system-event', command: '--command' }[kind];
+      if (!flag) unsupported(`openclaw cron carries \`message\`, \`system-event\` or \`command\` payloads; it has no verb for a \`${kind}\` payload`);
+      add(flag, payloadText(mutation.payload));
+    }
+    if (mutation.session_target != null) add('--session', mutation.session_target);
+    if (mutation.profile != null) add('--agent', mutation.profile);
+    if (mutation.deliver != null) {
+      const target = mutation.deliver.target == null ? null : nativeTrim(mutation.deliver.target), chat = mutation.deliver.chat_id;
+      if (target == null) { if (chat != null) add('--to', chat); }
+      else if (target === 'announce') { add('--announce'); if (chat != null) add('--to', chat); }
+      else if (target === 'webhook') { if (chat == null) invalid('an openclaw `webhook` delivery needs the URL in `chat_id`'); add('--webhook', chat); }
+      else if (target === 'none') add('--no-deliver');
+      else unsupported(`openclaw delivers \`announce\`, \`webhook\`, or \`none\`; it has no \`${target}\` delivery mode`);
+    }
+    if (verb === 'create') add('--json');
+  } else if (['profile', 'session_target', 'deliver', 'name', 'schedule', 'payload'].some(field => mutation[field] != null)) invalid(`\`jobs.${verb}\` changes no fields; pass definition fields to \`jobs.update\``);
+  return c.request();
+}
+function orchestratorArgs(verb, mutation) {
+  const args = {}; if (nativeTrim(mutation.id ?? '')) args.id = nativeTrim(mutation.id);
+  if (verb === 'create' || verb === 'update') {
+    if (mutation.session_target != null) unsupported('an orchestrator cron fire opens its own binding on the job\'s origin surface (`docs/ORCHESTRATOR-IR.md` §4.3); the model has no session-target field, so Volter Harness refuses rather than dropping it');
+    if (mutation.name != null) args.name = mutation.name;
+    if (mutation.schedule != null) args.schedule = schedule(mutation.schedule, true);
+    if (mutation.payload != null) { const kind = payloadKind(mutation.payload); if (kind !== 'prompt') unsupported(`an orchestrator job carries a \`prompt\` — the fire opens a worker session and sends it (§4.3); there is no \`${kind}\` payload, so supercode refuses rather than inventing one`); args.prompt = payloadText(mutation.payload); }
+    if (mutation.deliver != null) { const word = deliverWord(mutation.deliver); if (word != null) args.deliver = word; }
+  } else if (['name', 'schedule', 'payload', 'deliver', 'session_target'].some(field => mutation[field] != null)) invalid(`\`jobs.${verb}\` changes no fields; pass definition fields to \`jobs.update\``);
+  return args;
+}
+async function rows(mutation, context) { return (await listJobs({ harness: mutation.harness, homes: mutation.homes }, context)).jobs; }
+async function ids(mutation, context) { try { return new Set((await rows(mutation, context)).map(job => job.id)); } catch { return new Set(); } }
+async function createdId(mutation, before, stdout, ran, context) {
+  const after = await ids(mutation, context), fresh = [...after].filter(id => !before.has(id)).sort(compare);
+  if (fresh.length === 1) return fresh[0];
+  const named = fresh.find(id => stdout.includes(id)); if (named !== undefined) return named;
+  let value; try { value = parseNativeJson(nativeTrim(stdout)); } catch { /* no JSON id hint */ }
+  for (const id of [value?.id, value?.job?.id, value?.jobId, value?.job_id, value?.result?.id]) if (typeof id === 'string') { if (after.has(id)) return id; break; }
+  const said = nativeTrim(stdout);
+  failed(`\`${ran}\` reported success but ${mutation.harness} gained ${fresh.length} job(s), so the new job cannot be identified${said ? `; ${mutation.harness} said: ${said}` : ''}`);
+}
+export async function mutateJob(verb, value, { env = process.env, cwd = process.cwd(), signal } = {}) {
+  const context = { env, cwd, signal }, mutation = params(value, context); requireJobHarness(mutation.harness, `jobs.${verb}`);
+  if (!verbs.includes(verb)) invalid(`unknown job mutation: ${verb}`);
+  if (!CONTROLLED_JOB_HARNESSES.includes(mutation.harness)) unsupported('claude-code scheduled jobs are session-scoped runtime state: they are created by the model inside a session (`CronCreate`) and restored on resume. Claude Code publishes no harness verb a client can call, so Volter Harness refuses rather than inventing one');
+  if (verb !== 'create' && !nativeTrim(mutation.id ?? '')) invalid(`\`jobs.${verb}\` needs the job id to act on`);
+  if (verb === 'create' && mutation.schedule == null) invalid('`jobs.create` needs a schedule (interval, cron, or once)');
+  if (mutation.harness !== 'hermes') { const field = ['skills', 'workdir', 'model', 'provider', 'repeat'].find(field => mutation[field] != null); if (field) unsupported(`${mutation.harness} has no job verb that sets \`${field}\`, so Volter Harness refuses rather than dropping it`); }
+  let ran, id = mutation.id;
+  if (mutation.harness === 'orchestrator') {
+    const args = orchestratorArgs(verb, mutation), profile = nativeTrim(mutation.profile ?? '') || 'default';
+    const answer = await callProfileOrchestrator(mutation.homes.orchestrator, `jobs.${verb}`, args, { ...context, owner: 'job' }, profile); ran = `${answer.ran} [${answer.door}]`;
+    id = typeof answer.result?.job_id === 'string' ? answer.result.job_id : mutation.id;
+    if (id == null) failed(`\`${ran}\` succeeded but named no job id`);
+  } else {
+    const request = mutation.harness === 'hermes' ? hermesCommand(verb, mutation, context) : openclawCommand(verb, mutation, context);
+    const before = verb === 'create' ? await ids(mutation, context) : null, output = await runProfileCommand(request, context); requireProfileCommandSuccess(request, output); ran = request.ran;
+    if (mutation.harness === 'hermes') { const said = output.stdout.split(/\r?\n/u).map(nativeTrim).find(line => line.startsWith('Failed to ') || line.startsWith('Job not found')); if (said !== undefined) failed(`\`${ran}\` exited 0 but hermes said: ${said}`); }
+    if (verb === 'create') id = await createdId(mutation, before, output.stdout, ran, context);
+  }
+  let job; try { job = (await rows(mutation, context)).find(job => job.id === id); } catch (error) { failed(`\`${ran}\` succeeded but the job store could not be re-read: ${error.message}`); }
+  if (verb === 'delete') {
+    if (job) failed(`\`${ran}\` reported success but \`${id}\` is still in ${mutation.harness === 'orchestrator' ? 'the orchestrator\'s' : `${mutation.harness}'s`} job store`);
+    return { harness: mutation.harness, verb, ran, id, deleted: true };
+  }
+  if (!job) failed(`\`${ran}\` reported success but ${mutation.harness === 'orchestrator' ? 'the orchestrator' : `\`${mutation.harness}\``} has no job \`${id}\` afterwards`);
+  return { harness: mutation.harness, verb, ran, id, job };
+}
+export async function mutateJobNotepad(verb, value, { env = process.env, cwd = process.cwd(), signal } = {}) {
+  if (!['set', 'delete'].includes(verb)) invalid(`unknown notepad mutation: ${verb}`);
+  const context = { env, cwd, signal }, mutation = params(value, context, true); requireJobHarness(mutation.harness, 'jobs.notepad');
+  if (!nativeTrim(mutation.id)) invalid('a notepad call needs the job id');
+  if (mutation.harness !== 'hermes') unsupported(`\`${mutation.harness}\` keeps no job notepad; the notepad is supported for: hermes`);
+  if (verb === 'set' ? mutation.key == null || mutation.value == null : mutation.key == null) invalid(verb === 'set' ? '`notepad set` needs a key and a value' : '`notepad delete` needs a key');
+  const job = (await rows(mutation, context)).find(job => job.id === mutation.id);
+  if (!job) invalid(`${mutation.harness} has no job \`${mutation.id}\``);
+  if (job.profile !== (mutation.profile ?? null)) invalid(`job \`${mutation.id}\` belongs to ${job.profile == null ? 'the root home' : `profile \`${job.profile}\``}; name that profile with \`profile\``);
+  const c = command('hermes', mutation, context); c.add('cron', 'notepad', mutation.id, verb, '--', mutation.key); if (verb === 'set') c.add(mutation.value);
+  const request = c.request(), output = await runProfileCommand(request, context); requireProfileCommandSuccess(request, output);
+  const read = readJobNotepad(mutation, context);
+  if (verb === 'set' && !(read.entries.length === 1 && read.entries[0].value === mutation.value)) failed(`\`${request.ran}\` exited 0 but the store does not hold \`${mutation.key}\` = the value sent afterwards`);
+  if (verb === 'delete' && read.entries.length) failed(`\`${request.ran}\` exited 0 but the store still holds \`${mutation.key}\``);
+  return { ...read, ran: request.ran };
+}