@metagptx/deepflow-suite-cli 0.2.11-dev.20261020.1 → 0.3.1

package/runtime/df-agentrt/runtime.mjs

@@ -0,0 +1,358 @@
+import { readFile, lstat } from 'node:fs/promises';
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { setTimeout as delay } from 'node:timers/promises';
+import { usage } from './usage.mjs';
+import { resultView, writeResultFile } from './result.mjs';
+
+const terminal = (status) => ['succeeded', 'failed', 'cancelled'].includes(status);
+const decode = (raw) => JSON.parse(raw, (_key, value, context) => typeof value === 'number' && !Number.isSafeInteger(value) && /^-?\d+$/.test(context.source) ? BigInt(context.source) : value);
+const encode = (value) => JSON.stringify(value, (_key, item) => typeof item === 'bigint' ? JSON.rawJSON(item.toString()) : item);
+const truncate = (value = '', width) => { const chars = Array.from(String(value).trim().replaceAll('\n', ' ')); return chars.length <= width ? chars.join('') : chars.slice(0, width - 1).join('') + '…'; };
+const shortTime = (raw = '') => { const d = new Date(raw); return Number.isNaN(+d) ? raw : `${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')} ${String(d.getHours()).padStart(2, '0')}:${String(d.getMinutes()).padStart(2, '0')}:${String(d.getSeconds()).padStart(2, '0')}`; };
+const elapsed = (from, to) => { const ms = Date.parse(to) - Date.parse(from); return !from || !to || !Number.isFinite(ms) ? '—' : ms < 1000 ? `${ms}ms` : ms < 60000 ? `${(ms / 1000).toFixed(1)}s` : `${Math.floor(ms / 60000)}m${Math.floor(ms / 1000) % 60}s`; };
+const repoLine = (repo) => `${repo.url}${repo.ref ? ` @${repo.ref}` : ''}${repo.description ? `  (${truncate(repo.description, 48)})` : ''}`;
+function table(rows, out) {
+  const widths = rows[0].map((_, i) => Math.max(...rows.map((row) => Array.from(String(row[i] ?? '')).length)) + 2);
+  for (const row of rows) out.write(row.map((cell, i) => i === row.length - 1 ? String(cell ?? '') : String(cell ?? '') + ' '.repeat(Math.max(0, widths[i] - Array.from(String(cell ?? '')).length))).join('') + '\n');
+}
+class Failure extends Error { constructor(message, code = 1) { super(message); this.code = code; } }
+export function flags(args, strings = [], bools = [], repeated = []) {
+  const values = {}, positional = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--') { positional.push(...args.slice(i + 1)); break; }
+    if (!arg.startsWith('-') || arg === '-') { positional.push(arg); continue; }
+    const [key, inline] = arg.replace(/^-{1,2}/, '').split(/=(.*)/s);
+    if (bools.includes(key)) { if (inline !== undefined && !['true', 'false'].includes(inline)) throw new Failure(`invalid boolean value for -${key}`, 2); values[key] = inline !== 'false'; continue; }
+    if (!strings.includes(key) && !repeated.includes(key)) throw new Failure(`flag provided but not defined: -${key}`, 2);
+    const value = inline ?? args[++i];
+    if (value === undefined) throw new Failure(`flag needs an argument: -${key}`, 2);
+    if (repeated.includes(key)) (values[key] ||= []).push(value); else values[key] = value;
+  }
+  return { v: values, rest: positional };
+}
+const numeric = (value, name, max = 9223372036854775807n) => {
+  if (value !== undefined && (!/^\+?\d+$/.test(value) || BigInt(value) > max)) throw new Failure(`${name} must be a non-negative integer`, 2);
+};
+const query = (values) => { const pairs = Object.entries(values).filter(([, v]) => v !== undefined && v !== ''); pairs.sort(([a], [b]) => a.localeCompare(b)); const q = new URLSearchParams(pairs).toString(); return q ? '?' + q : ''; };
+function jsonObject(raw, description) { let value; try { value = JSON.parse(raw); } catch { throw new Failure(`${description} must be a JSON object`, 2); } if (!value || Array.isArray(value) || typeof value !== 'object') throw new Failure(`${description} must be a JSON object`, 2); return value; }
+
+export class RuntimeCLI {
+  constructor({ self = true, name = self ? 'df-agentrt' : 'agentrt', env = process.env, stdout = process.stdout, stderr = process.stderr } = {}) {
+    Object.assign(this, { self, name, env, stdout, stderr });
+  }
+  fail(message, code = 2) { throw new Failure(message, code); }
+  environment(message) { this.fail(`${message}${this.self ? '\nNothing is wrong with your arguments and retrying will not help.' : ''}`, 3); }
+  address() {
+    const addr = this.self ? this.env.MULTICA_SERVER_URL : this.env.AGENTRT_ADDR || 'http://127.0.0.1:8141';
+    if (!addr) this.environment('MULTICA_SERVER_URL is not set, so there is no runtime API to talk to; this command only works inside a running task');
+    return addr.replace(/\/+$/, '');
+  }
+  async request(method, route, body, { headers = {}, raw = false, stream = false, signal, responseLimit = 0, timeout = false } = {}) {
+    const addr = this.address();
+    let response;
+    try {
+      response = await fetch(addr + route, { method, headers: { ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}), ...(stream ? { Accept: 'text/event-stream' } : {}), ...headers }, body: body === undefined ? undefined : typeof body === 'string' ? body : JSON.stringify(body), signal: signal || (!stream && (this.self || timeout) ? AbortSignal.timeout(30000) : undefined) });
+    } catch (error) { throw new Failure(`cannot reach the runtime API at ${addr}: ${error.message}`); }
+    if (!response.ok) {
+      const text = (await response.text()).slice(0, 65536); let error;
+      try { error = JSON.parse(text).error; } catch { /* A proxy can return plain text. */ }
+      throw new Failure(`${error?.code ? `${error.code}: ${error.message}` : `HTTP ${response.status}: ${text.trim() || response.statusText}`}${response.headers.get('retry-after') ? ` (retry after ${response.headers.get('retry-after')}s)` : ''}`);
+    }
+    if (stream) return response.body;
+    if (method === 'DELETE') { await response.body?.cancel(); return; }
+    let text;
+    if (responseLimit) {
+      const chunks = []; let bytes = 0;
+      for await (const chunk of response.body) {
+        bytes += chunk.length;
+        if (bytes > responseLimit) throw new Failure(`response exceeds ${responseLimit} bytes`);
+        chunks.push(chunk);
+      }
+      text = Buffer.concat(chunks).toString('utf8');
+    } else text = await response.text();
+    try { const value = decode(text); return raw ? text.trim() : value; } catch (error) { throw new Failure(`decode response: ${error.message}`); }
+  }
+  async ownSession() {
+    if (this.session) return this.session;
+    if (!this.env.MULTICA_TASK_ID) this.environment('MULTICA_TASK_ID is not set, so this process cannot tell which session it belongs to; this command only works inside a running task');
+    let inv;
+    try { inv = await this.request('GET', `/v1/invocations/${encodeURIComponent(this.env.MULTICA_TASK_ID)}`); }
+    catch (error) { this.environment(`look up this task: ${error.message}`); }
+    if (!inv.session_id) this.environment(`the runtime API knows task ${this.env.MULTICA_TASK_ID} but reports no session for it`);
+    return this.session = inv.session_id;
+  }
+  async takeSession(rest, form) {
+    if (this.self) return [await this.ownSession(), rest];
+    if (!rest.length) this.fail(`usage: ${this.name} ${form}`);
+    return [rest[0], rest.slice(1)];
+  }
+  async readSession(v, rest, form) {
+    if ('session' in v) { if (!v.session.trim() || rest.length) this.fail(`usage: ${this.name} ${form}`); return encodeURIComponent(v.session); }
+    if (this.self) { if (rest.length) this.fail(`usage: ${this.name} ${form}`); return encodeURIComponent(await this.ownSession()); }
+    if (rest.length !== 1 || !rest[0].trim()) this.fail(`usage: ${this.name} ${form}`);
+    return encodeURIComponent(rest[0]);
+  }
+  async getJSON(route) { this.stdout.write(await this.request('GET', route, undefined, { raw: true }) + '\n'); }
+  async invocationCmd(command, args) {
+    const form = `usage: ${this.name} invocation result <invocation-id> [--json] [--max-bytes N] [--output-file PATH]`;
+    if (command !== 'result') this.fail(form);
+    if (args.includes('--help') || args.includes('-h')) { this.stdout.write(form + '\n'); return; }
+    const { v, rest } = flags(args, ['max-bytes', 'output-file'], ['json']);
+    numeric(v['max-bytes'], 'max-bytes', 1n << 20n);
+    const maxBytes = Number(v['max-bytes'] ?? 4096);
+    if (rest.length !== 1 || !rest[0].trim() || maxBytes < 1) this.fail(form);
+    let destination;
+    if ('output-file' in v) {
+      if (!v['output-file'].trim()) this.fail('--output-file must not be empty');
+      destination = path.resolve(v['output-file']);
+      try { await lstat(destination); this.fail(`output file already exists: ${destination}`); }
+      catch (error) { if (error.code !== 'ENOENT') this.fail(error.message); }
+    }
+    const inv = await this.request('GET', `/v1/invocations/${encodeURIComponent(rest[0])}`, undefined, { responseLimit: 64 << 20, timeout: true });
+    if (!inv || inv.id !== rest[0] || typeof inv.session_id !== 'string' || !inv.session_id || typeof inv.status !== 'string' || !inv.status) throw new Failure('invalid invocation identity or status in response');
+    const { view, output } = resultView(inv, maxBytes);
+    if (destination && view.output_present) { await writeResultFile(destination, output); view.output_file = destination; }
+    this.stdout.write(JSON.stringify(view, null, v.json ? undefined : 2) + '\n');
+  }
+  printSession(s) {
+    const rows = [['id', s.id], ['provider', s.provider], ['status', s.status]];
+    if (s.client_ref) rows.push(['client_ref', s.client_ref]);
+    rows.push(['agent_key', s.agent_key]);
+    for (const key of ['model', 'thinking_level']) if (s.config?.[key]) rows.push([key, s.config[key]]);
+    if (s.config?.skills?.length) rows.push(['skills', s.config.skills.join(', ')]);
+    (s.config?.repos || []).forEach((repo, i) => rows.push([i ? '' : 'repos', repoLine(repo)]));
+    rows.push(['workdir_state', s.workdir_state]);
+    if (s.pinned_runtime_id) rows.push(['pinned_runtime', s.pinned_runtime_id]);
+    if (s.prior_session_id || s.prior_work_dir) rows.push(['', ''], ['resume: conversation', s.prior_session_id || '(none)'], ['resume: directory', s.prior_work_dir || '(none)']);
+    if (s.resume_unavailable) rows.push(['resume: warning', 'the conversation handle is gone; the next turn keeps the files but not the history']);
+    if (s.released_at) rows.push(['released_at', shortTime(s.released_at)]);
+    rows.push(['created_at', shortTime(s.created_at)]); table(rows, this.stdout);
+  }
+  async sessionCmd(command, args) {
+    if (command === 'info') {
+      this.address(); const [id, rest] = await this.takeSession(args, 'session info <session-id>');
+      if (rest.length) this.fail(`usage: ${this.name} session info${this.self ? '' : ' <session-id>'}`);
+      this.printSession(await this.request('GET', `/v1/sessions/${encodeURIComponent(id)}`)); return;
+    }
+    if (command === 'create') {
+      const { v } = flags(args, ['provider', 'model', 'thinking-level', 'instructions', 'client-ref', 'idempotency-key', 'mcp-config', 'metadata'], [], ['skill', 'repo']);
+      if (!v.provider) this.fail('--provider is required');
+      const body = { provider: v.provider };
+      for (const [flag, key] of [['model', 'model'], ['thinking-level', 'thinking_level'], ['instructions', 'instructions'], ['client-ref', 'client_ref'], ['skill', 'skills'], ['repo', 'repos']]) if (v[flag]) body[key] = v[flag];
+      const fragments = [];
+      if (v['mcp-config']) { const raw = await readFile(v['mcp-config'], 'utf8'); try { JSON.parse(raw); } catch { throw new Failure(`${v['mcp-config']} is not valid JSON`); } fragments.push(`"mcp_config":${raw}`); }
+      if (v.metadata) { jsonObject(v.metadata, 'session create --metadata'); fragments.push(`"metadata":${v.metadata}`); }
+      const raw = JSON.stringify(body).slice(0, -1) + (fragments.length ? ',' + fragments.join(',') : '') + '}';
+      const sess = await this.request('POST', '/v1/sessions', raw, { headers: v['idempotency-key'] ? { 'Idempotency-Key': v['idempotency-key'] } : {} });
+      this.stdout.write(sess.id + '\n'); this.stderr.write(`session ready on ${sess.provider} (agent key ${sess.agent_key})\n`);
+      if (this.self) this.stderr.write('This session stays open until it is released; it will not close by itself.\n'); return;
+    }
+    if (command === 'get') {
+      const { v, rest } = flags(args, ['metadata-source', 'metadata-query-key'], ['json']);
+      if (rest.length !== 1 || !rest[0].trim()) this.fail(`usage: ${this.name} session get <session-id> [--json] [--metadata-source S] [--metadata-query-key K]`);
+      const route = `/v1/sessions/${encodeURIComponent(rest[0])}${query({ metadata_source: v['metadata-source'], metadata_query_key: v['metadata-query-key'] })}`;
+      if (v.json) return this.getJSON(route);
+      this.printSession(await this.request('GET', route)); return;
+    }
+    if (['ls', 'list'].includes(command)) {
+      const { v } = flags(args, ['status', 'limit', 'metadata-source', 'metadata-query-key']); numeric(v.limit, 'limit');
+      const page = await this.request('GET', '/v1/sessions' + query({ status: v.status, limit: v.limit && BigInt(v.limit) > 0n ? v.limit : undefined, metadata_source: v['metadata-source'], metadata_query_key: v['metadata-query-key'] }));
+      if (!page.sessions?.length) { this.stderr.write('no sessions\n'); return; }
+      table([['ID', 'PROVIDER', 'STATUS', 'WORKDIR', 'CLIENT REF', 'CREATED'], ...page.sessions.map((s) => [s.id, s.provider, s.status, s.workdir_state, truncate(s.client_ref, 24), shortTime(s.created_at)])], this.stdout);
+      this.stderr.write(`${page.sessions.length} shown, ${page.total} total\n`); return;
+    }
+    if (command === 'turns') {
+      const { v, rest } = flags(args, ['session'], ['json']);
+      const id = await this.readSession(v, rest, 'session turns [--session <session-id>] [--json]');
+      const route = `/v1/sessions/${id}/invocations`;
+      if (v.json) return this.getJSON(route);
+      const page = await this.request('GET', route);
+      if (!page.invocations?.length) { this.stderr.write('no turns yet\n'); return; }
+      table([['SEQ', 'ID', 'STATUS', 'ELAPSED', 'RUNTIME', 'CREATED', 'MESSAGE'], ...page.invocations.map((inv) => [inv.seq, inv.id, inv.status + (inv.cancel_requested && !terminal(inv.status) ? ' (cancel 已请求)' : ''), elapsed(inv.started_at || inv.claimed_at, inv.finished_at), inv.runtime_id || '—', shortTime(inv.created_at), truncate(inv.message, 48)])], this.stdout); return;
+    }
+    if (['release', 'rm', 'delete'].includes(command)) {
+      if (args.length !== 1) this.fail(`usage: ${this.name} session ${command === 'release' ? 'release' : 'rm'} <session-id>`);
+      const route = `/v1/sessions/${encodeURIComponent(args[0])}`;
+      if (command !== 'release') { await this.request('DELETE', route); this.stdout.write(`${args[0]} deleted\n`); return; }
+      const sess = await this.request('POST', route + '/release');
+      this.stdout.write(`${sess.id} released, workdir_state=${sess.workdir_state}\n`);
+      if (sess.workdir_state === 'reclaim_requested') this.stderr.write('the daemon will remove the working directory on its next GC pass; events remain readable\n'); return;
+    }
+    this.groupUsage('session', command);
+  }
+  async repoCmd(command, args) {
+    if (command === 'checkout') this.fail(`there is no \`repo checkout\` here -- \`${this.name} repo add\` checks out what it adds.${this.self ? '\nTo check out a repository this session already has, use `multica repo checkout <url>`.' : ''}`);
+    if (command === 'search') {
+      if (args.length !== 1) this.fail(`usage: ${this.name} repo search <name>`);
+      const page = await this.request('GET', '/v1/apps' + query({ name: args[0] }));
+      if (!page.apps?.length) { this.stderr.write(`nothing in the application registry matches ${JSON.stringify(args[0])}\n`); if (this.self) this.stderr.write('Try a shorter fragment of the name, or pass a clone url to `repo add` directly.\n'); return; }
+      if (this.self) for (const app of page.apps) this.stdout.write(`${app.code}\t${app.name}\t${app.repo_url}\n`);
+      else table([['CODE', 'NAME', 'REPOSITORY'], ...page.apps.map((app) => [app.code, truncate(app.name, 28), app.repo_url || '—'])], this.stdout); return;
+    }
+    if (!['ls', 'list', 'add'].includes(command)) return this.groupUsage('repo', command);
+    const { v, rest } = flags(args, command === 'add' ? ['ref'] : []);
+    this.address(); const [id, targets] = await this.takeSession(rest, `repo ${command} <session-id>`);
+    const route = `/v1/sessions/${encodeURIComponent(id)}/repos`;
+    if (command !== 'add') {
+      if (targets.length) this.fail(`usage: ${this.name} repo ls${this.self ? '' : ' <session-id>'}`);
+      const page = await this.request('GET', route);
+      if (!page.repos?.length) this.stderr.write(`no repositories; add one with \`${this.name} repo add\`\n`);
+      for (const repo of page.repos || []) this.stdout.write(repoLine(repo) + '\n'); return;
+    }
+    if (!targets.length) this.fail(`usage: ${this.name} repo add${this.self ? '' : ' <session-id>'} <url|app-code> ... [--ref REF]`);
+    const body = {};
+    for (const target of targets) { if (target.includes('://') || target.includes('@')) (body.repos ||= []).push({ url: target }); else (body.apps ||= []).push(target); }
+    if (v.ref) { if (body.repos?.length !== 1 || body.apps?.length) this.fail('--ref applies to a single repository url; add the others separately'); body.repos[0].ref = v.ref; }
+    const page = await this.request('POST', route, body);
+    if (!this.self) {
+      if (!page.added?.length) this.stderr.write('already present, nothing appended\n');
+      else { for (const repo of page.added) this.stdout.write(repoLine(repo) + '\n'); this.stderr.write(`${page.added.length} appended, ${page.repos?.length || 0} total\n`); } return;
+    }
+    let repos = page.added || [];
+    if (!repos.length) {
+      this.stderr.write('Already available to this session; checking it out.\n');
+      const wanted = new Set((body.repos || []).map((repo) => repo.url.trim().replace(/\/+$/, '')));
+      repos = (page.repos || []).filter((repo) => wanted.has(repo.url.replace(/\/+$/, '')));
+      if (!repos.length && body.apps?.length) repos = page.repos || [];
+    }
+    let failed = 0;
+    for (const repo of repos) {
+      try { await this.checkout(repo); } catch (error) { failed++; if (error.message) this.stderr.write(`${this.name}: ${error.message}\n`); }
+    }
+    if (failed) throw new Failure(`${failed} of ${repos.length} repositories could not be checked out. They remain configured for this session, so \`multica repo checkout <url>\` can be retried.`);
+  }
+  async checkout(repo) {
+    if (!this.env.MULTICA_DAEMON_PORT) this.environment('MULTICA_DAEMON_PORT is not set, so there is no daemon to check the repository out through.\nThe repository is configured for this session; only the checkout did not happen.');
+    const bin = this.env.AGENTRT_CLI_DAEMON_BIN;
+    if (!bin || !path.isAbsolute(bin)) this.environment('AGENTRT_CLI_DAEMON_BIN must name the absolute path of the pinned mcd executable. This is a deployment problem.');
+    await new Promise((resolve, reject) => {
+      const child = spawn(bin, ['repo', 'checkout', repo.url, ...(repo.ref ? ['--ref', repo.ref] : [])], { env: this.env, stdio: ['ignore', 'pipe', 'pipe'], shell: false });
+      child.stdout.pipe(this.stdout, { end: false }); child.stderr.pipe(this.stderr, { end: false });
+      child.once('error', (error) => reject(new Failure(`could not run ${bin}: ${error.message}`, 3)));
+      child.once('close', (code) => code === 0 ? resolve() : reject(new Failure('')));
+    });
+  }
+  async events(args) {
+    const form = 'events [--session <session-id>] [--after N] [--limit N] [--follow] [--raw]';
+    let v, rest;
+    try { ({ v, rest } = flags(args, ['session', 'after', 'limit'], ['raw', 'follow'])); numeric(v.after, 'after'); numeric(v.limit, 'limit'); }
+    catch { this.fail(`usage: ${this.name} ${form}`); }
+    const id = await this.readSession(v, rest, form);
+    if (v.follow) { const body = await this.request('GET', `/v1/sessions/${id}/events/stream?after_seq=${v.after || 0}`, undefined, { stream: true }); await scanSSE(body, (ev) => this.event(ev, v.raw)); return; }
+    const page = await this.request('GET', `/v1/sessions/${id}/events?after_seq=${v.after || 0}${v.limit && BigInt(v.limit) > 0n ? '&limit=' + v.limit : ''}`);
+    for (const ev of page.events || []) this.event(ev, v.raw);
+    this.stderr.write(`${page.events?.length || 0} events, next --after ${page.next_seq || 0}\n`);
+  }
+  event(ev, raw) {
+    const payload = ev.payload;
+    const summary = ev.source === 'agent' && payload && typeof payload === 'object' ? payload.content || payload.tool || payload.output : undefined;
+    this.stdout.write(`${String(ev.stream_seq).padStart(6)}  ${(ev.source || '').padEnd(6)} ${(ev.type || '').padEnd(22)} ${raw ? encode(payload) : truncate(summary || encode(payload), 100)}\n`);
+  }
+  async msg(command, args) {
+    if (command === 'cancel') {
+      this.address();
+      let id;
+      if (args.length === 1) id = args[0];
+      else if (this.self && !args.length) { id = this.env.MULTICA_TASK_ID; if (!id) this.environment('MULTICA_TASK_ID is not set, so this process cannot tell which turn it is; this command only works inside a running task'); }
+      else this.fail(`usage: ${this.name} msg cancel ${this.self ? '[<turn-id>]' : '<invocation-id>'}`);
+      const inv = await this.request('POST', `/v1/invocations/${encodeURIComponent(id)}/cancel`);
+      this.stdout.write(`${inv.id} status=${inv.status} cancel_requested=${!!inv.cancel_requested}\n`);
+      if (inv.cancel_requested && !terminal(inv.status)) this.stderr.write('the cancel is recorded; the turn stops when the daemon acknowledges it\n'); return;
+    }
+    if (command !== 'send') return this.groupUsage('msg', command);
+    const { v, rest } = flags(args, ['idempotency-key'], ['follow', 'raw']);
+    if (rest.length < 2) this.fail(`usage: ${this.name} msg send <session-id> <text> [--follow]`);
+    const id = encodeURIComponent(rest[0]);
+    const cursor = v.follow ? (await this.request('GET', `/v1/sessions/${id}/events?limit=1`)).next_seq : 0;
+    const inv = await this.request('POST', `/v1/sessions/${id}/messages`, { message: rest.slice(1).join(' ') }, { headers: v['idempotency-key'] ? { 'Idempotency-Key': v['idempotency-key'] } : {} });
+    if (!v.follow) { this.stdout.write(inv.id + '\n'); this.stderr.write(`queued turn ${inv.seq}, status ${inv.status}\n`); return; }
+    await this.follow(id, inv.id, cursor || 0, v.raw);
+  }
+  report(inv) { if (inv.result) this.stdout.write(inv.result + '\n'); this.stderr.write(`turn ${inv.id}: ${inv.status}\n`); if (inv.error) this.stderr.write(`error: ${inv.error}\n`); if (inv.status !== 'succeeded') throw new Failure(''); }
+  async follow(session, invocation, cursor, raw) {
+    const controller = new AbortController(); let detached = false, result;
+    const detach = () => { detached = true; controller.abort(); };
+    process.once('SIGINT', detach); process.once('SIGTERM', detach);
+    const poll = (async () => {
+      while (!controller.signal.aborted) {
+        try { await delay(1000, undefined, { signal: controller.signal }); } catch { break; }
+        if (controller.signal.aborted) break;
+        try {
+          const inv = await this.request('GET', `/v1/invocations/${encodeURIComponent(invocation)}`, undefined, { signal: AbortSignal.any([controller.signal, AbortSignal.timeout(30000)]) });
+          if (terminal(inv.status)) { result = inv; try { await delay(2000, undefined, { signal: controller.signal }); } catch {} controller.abort(); break; }
+        } catch { /* A failed poll is not a verdict on the turn. */ }
+      }
+    })();
+    try {
+      const body = await this.request('GET', `/v1/sessions/${session}/events/stream?after_seq=${cursor}`, undefined, { stream: true, signal: controller.signal });
+      await scanSSE(body, (ev) => this.event(ev, raw));
+    } catch (error) { if (!controller.signal.aborted) { controller.abort(); throw error; } }
+    finally { controller.abort(); await poll; process.removeListener('SIGINT', detach); process.removeListener('SIGTERM', detach); }
+    if (detached && !result) { this.stderr.write(`detached; the turn is still running (${this.name} msg cancel ${invocation} to stop it)\n`); return; }
+    result ||= await this.request('GET', `/v1/invocations/${encodeURIComponent(invocation)}`);
+    if (!terminal(result.status)) throw new Failure(`the event stream ended while the turn was still ${result.status}; re-attach with: ${this.name} events ${this.self ? '--session ' : ''}${session} --follow --after ${cursor}`);
+    this.report(result);
+  }
+  async ops(command, args) {
+    if (!['runtimes', 'orphans'].includes(command)) return this.groupUsage('ops', command);
+    const { v, rest } = flags(args, [], command === 'runtimes' ? ['json'] : ['fix']);
+    if (rest.length) this.fail(`usage: ${this.name} ops ${command}`);
+    const route = `/v1/ops/${command}`;
+    if (v.json) return this.getJSON(route);
+    const body = await this.request(v.fix ? 'POST' : 'GET', route);
+    if (command === 'runtimes') {
+      if (!body.runtimes?.length) { this.stderr.write('no runtimes have registered; session creates will fail with provider_offline\n'); return; }
+      table([['ID', 'PROVIDER', 'RECORDED', 'LIVE', 'STALE', 'DEVICE', 'LAST SEEN'], ...body.runtimes.map((rt) => [rt.id, rt.provider, rt.status, rt.live ? 'yes' : 'no', `${rt.stale_for}s`, truncate(rt.device_name, 20), shortTime(rt.last_seen_at)])], this.stdout);
+      const stale = body.runtimes.filter((rt) => !rt.live).length;
+      if (stale) this.stderr.write(`${stale} runtime(s) recorded but not heartbeating; trust the LIVE column\n`); return;
+    }
+    if (!body.workdirs?.length && !body.turns?.length) this.stderr.write('no orphans\n');
+    else {
+      if (body.workdirs?.length) { this.stdout.write('working directories:\n'); table([['  SESSION', 'KIND', 'STATE', 'WORKDIR', 'NOTE'], ...body.workdirs.map((w) => [`  ${w.session_id}`, w.kind, w.workdir_state, truncate(w.work_dir, 40), w.note])], this.stdout); }
+      if (body.turns?.length) { this.stdout.write('turns:\n'); table([['  INVOCATION', 'KIND', 'STATUS', 'RUNTIME', 'LAST SEEN', 'NOTE'], ...body.turns.map((t) => [`  ${t.invocation_id}`, t.kind, t.status, truncate(t.runtime_name, 20), shortTime(t.last_seen_at), t.note])], this.stdout); }
+      this.stderr.write(body.reconciled ? `corrected ${body.workdirs_corrected} workdir(s), failed ${body.turns_failed} turn(s)\n` : 'nothing was changed; re-run with --fix to apply\n');
+    }
+    if (body.unreadable) this.stderr.write(`warning: ${body.unreadable} working directories could not be read; this result does not cover them\n`);
+  }
+  groupUsage(group, command) { if (command) this.stderr.write(`${this.name} ${group}: unknown command ${JSON.stringify(command)}\n\n`); this.stderr.write(usage[this.self ? 'df-agentrt' : 'agentrt'][group]); throw new Failure('', 2); }
+  async run(args) {
+    try {
+      if (args[0] === '--cli-version') {
+        let version = 'workspace'; try { version = JSON.parse(await readFile(new URL('./release.json', import.meta.url), 'utf8')).version; } catch {}
+        const report = { name: this.name, version, entry: fileURLToPath(new URL(this.self ? './df-agentrt.mjs' : './agentrt.mjs', import.meta.url)) };
+        this.stdout.write((args.includes('--json') ? JSON.stringify(report) : `${this.name} ${version}`) + '\n'); return 0;
+      }
+      if (!args.length || ['--help', '-h', 'help'].includes(args[0])) { const code = !args.length && !this.self ? 2 : 0; (code ? this.stderr : this.stdout).write(usage[this.self ? 'df-agentrt' : 'agentrt']['']); return code; }
+      if (['--version', '-v', 'version'].includes(args[0])) {
+        let version = 'workspace'; try { version = JSON.parse(await readFile(new URL('./release.json', import.meta.url), 'utf8')).version; } catch { /* Source checkout. */ }
+        this.stdout.write(`${this.name} ${version} (DeepFlow Agent Runtime)\n`); return 0;
+      }
+      const [group, command, ...rest] = args;
+      if (group === 'events') await this.events(args.slice(1));
+      else if (group === 'invocation') await this.invocationCmd(command, rest);
+      else if (['session', 'repo', 'msg', 'ops'].includes(group)) {
+        if (!command) this.groupUsage(group);
+        else if (group === 'session') await this.sessionCmd(command, rest);
+        else if (group === 'repo') await this.repoCmd(command, rest);
+        else if (group === 'msg') await this.msg(command, rest);
+        else await this.ops(command, rest);
+      } else { this.stderr.write(`${this.name}: unknown command ${JSON.stringify(group)}\n\n`); this.stderr.write(usage[this.self ? 'df-agentrt' : 'agentrt']['']); return 2; }
+      return 0;
+    } catch (error) { if (error.message) this.stderr.write(`${this.name}: ${error.message}\n`); return error.code || 1; }
+  }
+}
+
+export async function scanSSE(body, emit) {
+  const decoder = new TextDecoder(); let pending = '';
+  const line = (raw) => { if (!raw.startsWith('data:')) return; try { emit(decode(raw.slice(5).trimStart())); } catch (error) { if (!(error instanceof SyntaxError)) throw error; } };
+  for await (const chunk of body) {
+    pending += typeof chunk === 'string' ? chunk : decoder.decode(chunk, { stream: true });
+    let end;
+    while ((end = pending.indexOf('\n')) >= 0) { if (end > 8 * 1024 * 1024) throw new Failure('SSE frame exceeds 8 MiB'); line(pending.slice(0, end).replace(/\r$/, '')); pending = pending.slice(end + 1); }
+    if (Buffer.byteLength(pending) > 8 * 1024 * 1024) throw new Failure('SSE frame exceeds 8 MiB');
+  }
+  pending += decoder.decode(); if (pending) line(pending);
+}

package/runtime/df-agentrt/usage.mjs

@@ -0,0 +1,16 @@
+export const usage = {
+  "df-agentrt": {
+    "": "df-agentrt -- DeepFlow Agent Runtime, from inside a task\n\nTHIS SESSION\n  df-agentrt session info                           Which session this is:\n                                                    provider, model, working\n                                                    directory, repositories,\n                                                    and whether the\n                                                    conversation history\n                                                    survived into this turn.\n  df-agentrt session turns [--session ID] [--json]  Every turn; defaults to\n                                                    this session.\n  df-agentrt events [--session ID] [--after N]      The message stream. Also\n                                                    --limit N, --raw and\n                                                    --follow.\n  df-agentrt repo list                              The repositories this\n                                                    session may check out.\n  df-agentrt repo search <name>                     Find an application and\n                                                    the repository its code\n                                                    lives in.\n  df-agentrt repo add <url|code> ...                Make another repository\n                                                    available and check it out\n                                                    now. Prints the absolute\n                                                    path of each checkout.\n  df-agentrt msg cancel [invocation-id]             Ask a turn to stop;\n                                                    defaults to the current\n                                                    turn.\n\nOTHER SESSIONS\n  df-agentrt invocation result <id> [--json]         Read a bounded final result.\n                                                    --output-file saves full text.\n  df-agentrt session ls                             Sessions on this runtime.\n  df-agentrt session get <id> [--json]              One session in full.\n  df-agentrt session create ...                     Start a new session. It\n                                                    runs an agent and costs\n                                                    money, and it does not end\n                                                    by itself.\n  df-agentrt msg send <id> <text>                   Queue a turn on another\n                                                    session. Same caveat.\n\nRUNTIME\n  df-agentrt ops runtimes [--json]                  Which execution engines\n                                                    are registered and alive.\n  df-agentrt ops orphans                            Where the records and the\n                                                    world have drifted apart.\n\nRun `df-agentrt <group>` for the flags of one group.\n",
+    "session": "df-agentrt session <command>\n\n  info                This session. Includes whether the conversation history\n                      carried over into this turn -- if it did not, you have the\n                      same files but none of what was said before.\n  turns [--session ID] [--json]\n                      Every turn; defaults to this session, oldest first.\n  ls                  Sessions on this runtime.\n  get      <id> [--json] [--metadata-source S] [--metadata-query-key K]\n                      Another session in full.\n  create   --provider P [--model M] [--thinking-level L] [--instructions S]\n           [--skill S ...] [--repo R ...] [--client-ref REF] [--mcp-config FILE]\n           [--metadata JSON]\n           [--idempotency-key KEY]\n                      Start a new session. It runs an agent and costs money, and\n                      nothing ends it for you.\n  release  <id>       Stop a session accepting turns and ask for its working\n                      directory back.\n  rm       <id>       Delete a session's record, message stream included.\n\nEverything about a session except its repository set is fixed at creation.\nFor repositories see `df-agentrt repo` -- those can be appended afterwards.\n",
+    "repo": "df-agentrt repo <command>\n\n  list                        The repositories this session may check out.\n  search  <name>              Find an application and the repository its code\n                              lives in. Use this when you know what a thing is\n                              called but not where its code is.\n  add     <url|app-code> ...  Make another repository available to this session\n          [--ref REF]         and check it out now. Prints the absolute path of\n                              each checkout on stdout; nothing else to run\n                              afterwards. --ref takes one repository only.\n\nAn argument containing \"://\" or \"@\" is treated as a clone url and stored\nverbatim; anything else is treated as an application code and looked up for\nyou. A code can never contain either, so the two cannot be confused.\n\nAppend-only: there is no remove. Removing a repository you are working inside\nwould break this turn.\n",
+    "msg": "df-agentrt msg <command>\n\n  send    <session-id> <text> [--follow] [--idempotency-key KEY] [--raw]\n          Queue a turn on another session. That session runs an agent and\n          costs money; it is not this one. --follow waits for the turn to\n          finish, which blocks you for as long as it runs.\n  cancel  [<turn-id>]\n          Ask a turn to stop. With no argument, the turn you are executing\n          right now -- you will be asked to wind down, not killed outright.\n",
+    "ops": "df-agentrt ops <command>\n\n  runtimes [--json]  Which daemons have registered, and which are still alive.\n  orphans [--fix]    Where the records and the world have drifted apart.\n                     Reports only unless --fix is given; --fix fails stranded\n                     turns on other sessions and cannot be undone.\n"
+  },
+  "agentrt": {
+    "": "agentrt -- DeepFlow Agent Runtime CLI\n\nUSAGE\n  agentrt <group> <command> [flags]\n\nGROUPS\n  session   info | create | get | ls | turns | release | rm\n  invocation result <id> [--json] [--max-bytes N] [--output-file PATH]\n  repo      ls | add | search\n  msg       send | cancel\n  events    events <session> [--after N]\n  ops       runtimes | orphans\n\nENVIRONMENT\n  AGENTRT_ADDR      Base URL of the runtime API (default http://127.0.0.1:8141)\n\nRun `agentrt <group>` for that group's commands.\n",
+    "session": "agentrt session <command>\n\n  info     <session-id>    The same view as get. Named for the agent-side CLI,\n                           where it is the command for \"which session am I in\".\n  create   --provider P [--model M] [--thinking-level L] [--instructions S]\n           [--skill S ...] [--repo R ...] [--client-ref REF] [--mcp-config FILE]\n           [--idempotency-key KEY]\n  get      <session-id> [--json] [--metadata-source S] [--metadata-query-key K]\n\t  ls       [--status active|released] [--limit N] [--metadata-source S] [--metadata-query-key K]\n  turns    <session-id> [--json] (or --session <session-id>)\n                           Every turn of one session, oldest first -- the same\n                           timeline the web UI draws, from the same endpoint.\n  release  <session-id>    Stop accepting turns; Phase 1 keeps the Worker workspace.\n                           Events and active workspace reads stay available afterwards.\n\t rm       <session-id>    Delete the record. Workspace archive is not a Phase 1 operation.\n\nEverything here except the repository set is fixed when the session is created.\nFor repositories, see `agentrt repo` -- they can be appended to afterwards.\n",
+    "repo": "agentrt repo <command>\n\n  ls      <session-id>                     Repositories this session may check out.\n  add     <session-id> <url|app-code> ...  Append repositories. Takes effect on the\n                                           next checkout, including mid-turn.\n          [--ref REF]                      Branch, tag or commit. One repository only.\n  search  <name>                           Find an application and its repository in\n                                           the registry.\n\nAn argument containing \"://\" or \"@\" is taken as a clone URL and stored\nverbatim; anything else is taken as an application code and resolved against\nthe registry. A code can never contain either, so the two cannot be confused.\n\nAppend-only: there is no remove. Removing a repository the agent is working\ninside would break the turn in flight.\n",
+    "msg": "agentrt msg <command>\n\n  send    <session-id> <text> [--follow] [--idempotency-key KEY] [--raw]\n          Queue one turn. --follow attaches to the event stream and waits for\n          the turn to finish, exiting non-zero if it failed.\n  cancel  <invocation-id>\n          Ask for a running turn to stop. Returns as soon as the request is\n          recorded, which is before the agent has actually wound down.\n",
+    "ops": "agentrt ops <command>\n\n  runtimes [--json]  Which daemons have registered, and which are still alive.\n  orphans [--fix]    Where the records and the world have drifted apart.\n                     Reports only unless --fix is given; --fix fails stranded\n                     turns on other sessions and cannot be undone.\n"
+  }
+};

package/runtime/df-task/commands.mjs

@@ -0,0 +1,188 @@
+export const help = `df-task — DeepFlow Task fact log CLI
+
+Usage:
+  df-task ls [--limit <n>] [--metadata-source <source>] [--metadata-query-key <key>]
+  df-task get <task-id> [--fields <paths> --json] [--metadata-source <source>] [--metadata-query-key <key>]
+  df-task create --title <text> [--description <text>] [--message <text>] [--metadata <json>]
+  df-task facts <task-id> [--after <seq>] [--types <a,b>] [--limit <n>] [--metadata-source <source>] [--metadata-query-key <key>]
+  df-task facts <task-id> --all --output-file <path> --json [--max-pages <n>] [--max-bytes <n>]
+  df-task append <task-id> --type <type> --file payload.json [--idempotency-key <k>]
+  df-task stream [--after <seq>] [--types <a,b>] [--limit <n>] [--metadata-source <source>] [--metadata-query-key <key>]
+  df-task title <task-id> --title <text>
+  df-task metadata <task-id> --metadata <json> [--metadata-source <source>] [--metadata-query-key <key>]
+
+Scheduling shorthands (each one is a wrapper around append):
+  df-task dispatch <task-id> --agent <name> --instruction <text> [--run <run-id>]
+  df-task wait <task-id> --on <what> --reason <text> [--waiting-run <run-id>]
+  df-task handoff <task-id> --ask <text> [--assignee <who>]
+
+Global options (before or after the command):
+  --base-url <url>   Service URL (or DF_TASK_BASE_URL)
+  --json             Machine-readable JSON output
+  help [command]     Show general or command help (-h / --help also supported)
+
+Environment:
+  DF_TASK_BASE_URL     Service URL, default http://127.0.0.1:8090
+  DF_TASK_ACTOR_KIND   Write identity: human | external | task_run | scheduler_run | driver
+  DF_TASK_ACTOR_ID     Write identity id, e.g. the current run id
+
+Facts are append-only. The API has no way to change or remove a fact, so neither does this CLI.
+`;
+export const commands = {
+  "ls": {
+    "usage": "ls [--limit <n>] [--metadata-source <source>] [--metadata-query-key <key>]",
+    "description": "List tasks, newest first.",
+    "flags": [
+      "--limit",
+      "--metadata-source",
+      "--metadata-query-key"
+    ],
+    "required": [],
+    "needsID": false,
+    "writes": false
+  },
+  "get": {
+    "usage": "get <task-id> [--fields <paths> --json] [--metadata-source <source>] [--metadata-query-key <key>]",
+    "description": "Read one task's identity. --fields selects known fields and object paths; absent paths are omitted.",
+    "flags": [
+      "--fields",
+      "--metadata-source",
+      "--metadata-query-key"
+    ],
+    "required": [],
+    "needsID": true,
+    "writes": false
+  },
+  "create": {
+    "usage": "create --title <text> [--description <text>] [--message <text>] [--metadata <json>]",
+    "description": "Create a task, optionally with its first user message in the same transaction.",
+    "flags": [
+      "--title",
+      "--description",
+      "--message",
+      "--metadata"
+    ],
+    "required": [
+      "--title"
+    ],
+    "needsID": false,
+    "writes": true
+  },
+  "facts": {
+    "usage": "facts <task-id> [--after <seq>] [--types <a,b>] [--limit <n>] [--fields <paths> --json | --all --output-file <path> --json [--max-pages <n>] [--max-bytes <n>]] [--metadata-source <source>] [--metadata-query-key <key>]",
+    "description": "Read facts in seq order. --fields selects fields per fact, retaining pagination. --all writes complete raw pages to a private file and prints a manifest; limits default to 10 pages / 8 MiB. Only an observed empty page marks complete. Partial reads exit 1.",
+    "flags": [
+      "--fields",
+      "--all",
+      "--output-file",
+      "--max-pages",
+      "--max-bytes",
+      "--after",
+      "--types",
+      "--limit",
+      "--metadata-source",
+      "--metadata-query-key"
+    ],
+    "required": [],
+    "needsID": true,
+    "writes": false
+  },
+  "append": {
+    "usage": "append <task-id> --type <type> --file payload.json [--idempotency-key <k>]",
+    "description": "Append one fact from a JSON payload file.",
+    "flags": [
+      "--type",
+      "--file",
+      "--idempotency-key"
+    ],
+    "required": [
+      "--type",
+      "--file"
+    ],
+    "needsID": true,
+    "writes": true
+  },
+  "stream": {
+    "usage": "stream [--after <seq>] [--types <a,b>] [--limit <n>] [--metadata-source <source>] [--metadata-query-key <key>]",
+    "description": "Read facts across all tasks from a cursor. One-shot pull, not a long connection.",
+    "flags": [
+      "--after",
+      "--types",
+      "--limit",
+      "--metadata-source",
+      "--metadata-query-key"
+    ],
+    "required": [],
+    "needsID": false,
+    "writes": false
+  },
+  "title": {
+    "usage": "title <task-id> --title <text>",
+    "description": "Change a task's title. Writes no fact.",
+    "flags": [
+      "--title"
+    ],
+    "required": [
+      "--title"
+    ],
+    "needsID": true,
+    "writes": true
+  },
+  "metadata": {
+    "usage": "metadata <task-id> --metadata <json> [--metadata-source <source>] [--metadata-query-key <key>]",
+    "description": "Replace a task's metadata as human. Writes no fact.",
+    "flags": [
+      "--metadata",
+      "--metadata-source",
+      "--metadata-query-key"
+    ],
+    "required": [
+      "--metadata"
+    ],
+    "needsID": true,
+    "writes": true
+  },
+  "dispatch": {
+    "usage": "dispatch <task-id> --agent <name> --instruction <text> [--run <run-id>]",
+    "description": "Append a dispatch intent. Without --run it asks for a new run; with --run it posts a message to that run.",
+    "flags": [
+      "--agent",
+      "--instruction",
+      "--run"
+    ],
+    "required": [
+      "--agent",
+      "--instruction"
+    ],
+    "needsID": true,
+    "writes": true
+  },
+  "wait": {
+    "usage": "wait <task-id> --on <what> --reason <text> [--waiting-run <run-id>]",
+    "description": "Append a waiting reason. It is context for humans and the next scheduling run, not a gate for the driver.",
+    "flags": [
+      "--on",
+      "--reason",
+      "--waiting-run"
+    ],
+    "required": [
+      "--on",
+      "--reason"
+    ],
+    "needsID": true,
+    "writes": true
+  },
+  "handoff": {
+    "usage": "handoff <task-id> --ask <text> [--assignee <who>]",
+    "description": "Append a handoff to a human. Handing the ball back and asking a human to do a step are the same fact.",
+    "flags": [
+      "--ask",
+      "--assignee"
+    ],
+    "required": [
+      "--ask"
+    ],
+    "needsID": true,
+    "writes": true
+  }
+};