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

package/runtime/df-agentctrl/commands.mjs

@@ -0,0 +1,93 @@
+export const help = `df-agentctrl — Agent control plane CLI
+
+Usage:
+  df-agentctrl list [--include-disabled] [--metadata-source <source>] [--metadata-query-key <key>] [--json]
+  df-agentctrl get <agent-id> [--version <n>] [--metadata-source <source>] [--metadata-query-key <key>] [--json]
+  df-agentctrl create --file agent.json [--json]
+  df-agentctrl save <agent-id> --file agent.json [--change-note <text>] [--json]
+  df-agentctrl versions <agent-id> [--json]
+  df-agentctrl diff <agent-id> --from <n> --to <n> [--json]
+  df-agentctrl enable <agent-id> [--json]
+  df-agentctrl disable <agent-id> [--json]
+  df-agentctrl rollback <agent-id> --version <n> [--change-note <text>] [--json]
+
+Global options (before or after the command):
+  --base-url <url>   Service URL (or DF_AGENTCTRL_BASE_URL)
+  --json             Machine-readable JSON output
+  help [command]     Show general or command help (-h / --help also supported)
+`;
+export const commands = {
+  "list": {
+    "usage": "list [--include-disabled] [--metadata-source <source>] [--metadata-query-key <key>]",
+    "description": "List enabled agents and their default version summaries.",
+    "flags": [
+      "--include-disabled",
+      "--metadata-source",
+      "--metadata-query-key"
+    ],
+    "needsID": false
+  },
+  "get": {
+    "usage": "get <agent-id> [--version <n>] [--metadata-source <source>] [--metadata-query-key <key>]",
+    "description": "Read metadata and a complete definition; omit --version for the current default.",
+    "flags": [
+      "--version",
+      "--metadata-source",
+      "--metadata-query-key"
+    ],
+    "needsID": true
+  },
+  "create": {
+    "usage": "create --file agent.json",
+    "description": "Create an agent and version 1 from a complete JSON snapshot.",
+    "flags": [
+      "--file"
+    ],
+    "needsID": false
+  },
+  "save": {
+    "usage": "save <agent-id> --file agent.json [--change-note <text>]",
+    "description": "Save a complete snapshot as a new immutable default version.",
+    "flags": [
+      "--file",
+      "--change-note"
+    ],
+    "needsID": true
+  },
+  "versions": {
+    "usage": "versions <agent-id>",
+    "description": "List immutable versions, newest first.",
+    "flags": [],
+    "needsID": true
+  },
+  "diff": {
+    "usage": "diff <agent-id> --from <n> --to <n>",
+    "description": "Compare two versions of the same agent as file diffs.",
+    "flags": [
+      "--from",
+      "--to"
+    ],
+    "needsID": true
+  },
+  "enable": {
+    "usage": "enable <agent-id>",
+    "description": "Include an agent in the default directory.",
+    "flags": [],
+    "needsID": true
+  },
+  "disable": {
+    "usage": "disable <agent-id>",
+    "description": "Exclude an agent from the default directory; preserve its history.",
+    "flags": [],
+    "needsID": true
+  },
+  "rollback": {
+    "usage": "rollback <agent-id> --version <n> [--change-note <text>]",
+    "description": "Copy a historical definition into a new default version; preserve name and enabled state.",
+    "flags": [
+      "--version",
+      "--change-note"
+    ],
+    "needsID": true
+  }
+};

package/runtime/df-agentctrl/df-agentctrl.mjs

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+import { readFile } from 'node:fs/promises';
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { help, commands } from './commands.mjs';
+
+const uuid = /^(?:urn:uuid:)?(?:[0-9a-f]{32}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|\{[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\})$/i;
+const valueFlags = new Set(['--base-url', ...Object.values(commands).flatMap((spec) => spec.flags)]);
+export function parse(args) {
+  const o = { command: '', args: [], values: {}, json: false, help: false, includeDisabled: false };
+  const seen = new Set();
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (!arg.startsWith('-')) { if (!o.command) o.command = arg; else o.args.push(arg); continue; }
+    const equals = arg.indexOf('=');
+    const key = equals < 0 ? arg : arg.slice(0, equals);
+    if (seen.has(key)) throw Error(`duplicate option ${key}`);
+    seen.add(key);
+    if (['--help', '-h', '--json', '--include-disabled'].includes(key)) {
+      if (equals >= 0) throw Error(`${key} does not take a value`);
+      o[key === '--json' ? 'json' : key === '--include-disabled' ? 'includeDisabled' : 'help'] = true;
+    } else if (valueFlags.has(key)) {
+      if (equals < 0 && (i + 1 === args.length || args[i + 1].startsWith('--'))) throw Error(`${key} requires a value`);
+      o.values[key] = equals < 0 ? args[++i] : arg.slice(equals + 1);
+    } else throw Error(`unknown option ${key}`);
+  }
+  o.command ||= 'help';
+  if (o.command === 'help' && o.args.length === 1) { o.command = o.args.pop(); o.help = true; }
+  return o;
+}
+function query(values) {
+  const pairs = Object.entries(values).filter(([, value]) => value !== undefined && value !== '');
+  pairs.sort(([a], [b]) => a.localeCompare(b));
+  const value = new URLSearchParams(pairs).toString();
+  return value ? `?${value}` : '';
+}
+export async function requestFor(o) {
+  const spec = Object.hasOwn(commands, o.command) ? commands[o.command] : undefined, v = o.values;
+  if (!spec) throw Error(`unknown command ${o.command}`);
+  for (const key of Object.keys(v)) if (key !== '--base-url' && !spec.flags.includes(key)) throw Error(`${key} is not supported by ${o.command}`);
+  if (o.includeDisabled && !spec.flags.includes('--include-disabled')) throw Error('--include-disabled is only supported by list');
+  if (spec.needsID) {
+    if (o.args.length !== 1) throw Error(`${o.command} requires exactly one agent-id`);
+    if (!uuid.test(o.args[0])) throw Error('agent-id must be a UUID');
+  } else if (o.args.length) throw Error(`${o.command} does not accept positional arguments`);
+  for (const key of ['--version', '--from', '--to']) if (key in v) {
+    if (!/^\+?\d+$/.test(v[key]) || BigInt(v[key]) < 1n || BigInt(v[key]) > 2147483647n) throw Error(`${key} must be a positive 32-bit integer`);
+  }
+  const metadata = { metadata_source: v['--metadata-source'], metadata_query_key: v['--metadata-query-key'] };
+  let path = '/api/v1/agents';
+  if (o.command === 'list') return { method: 'GET', path: path + query({ ...metadata, ...(o.includeDisabled ? { include_disabled: 'true' } : {}) }) };
+  if (spec.needsID) path += `/${encodeURIComponent(o.args[0])}`;
+  if (['create', 'save'].includes(o.command)) {
+    if (!v['--file']) throw Error('--file is required');
+    const raw = await readFile(v['--file'], 'utf8');
+    let obj;
+    try { obj = JSON.parse(raw); } catch (error) { throw Error(`invalid JSON: ${error.message}`); }
+    if (!obj || Array.isArray(obj) || typeof obj !== 'object') throw Error('snapshot must be a JSON object');
+    // Inject the note without rounding numbers or discarding unknown snapshot fields.
+    const trimmed = raw.trim();
+    const body = '--change-note' in v ? trimmed.slice(0, -1) + (Object.keys(obj).length ? ',' : '') + `"change_note":${JSON.stringify(v['--change-note'])}}` : raw;
+    return { method: 'POST', path: path + (o.command === 'save' ? '/versions' : ''), body };
+  }
+  if (o.command === 'get') return { method: 'GET', path: path + (v['--version'] ? `/versions/${encodeURIComponent(v['--version'])}` : '') + query(metadata) };
+  if (o.command === 'versions') return { method: 'GET', path: `${path}/versions` };
+  if (['enable', 'disable'].includes(o.command)) return { method: 'POST', path: `${path}/${o.command}` };
+  if (o.command === 'diff') {
+    if (!v['--from'] || !v['--to']) throw Error('--from and --to are required');
+    return { method: 'GET', path: `${path}/versions/${encodeURIComponent(v['--to'])}/diff${query({ against: v['--from'] })}` };
+  }
+  if (!v['--version']) throw Error('--version is required');
+  return { method: 'POST', path: `${path}/versions/${encodeURIComponent(v['--version'])}/rollback`, body: JSON.stringify({ change_note: v['--change-note'] || '' }) };
+}
+function pretty(raw) {
+  const tokens = raw.match(/"(?:\\.|[^"\\])*"|[{}\[\],:]|[^\s{}\[\],:]+/g) || [];
+  let level = 0, out = '';
+  const newline = () => '\n' + '  '.repeat(level);
+  tokens.forEach((token, i) => {
+    if (token === '{' || token === '[') { out += token; level++; if (tokens[i + 1] !== (token === '{' ? '}' : ']')) out += newline(); }
+    else if (token === '}' || token === ']') { level--; if (tokens[i - 1] !== (token === '}' ? '{' : '[')) out += newline(); out += token; }
+    else out += token === ',' ? ',' + newline() : token === ':' ? ': ' : token;
+  });
+  return out;
+}
+export async function run(args, { env = process.env, stdout = process.stdout, stderr = process.stderr } = {}) {
+  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: 'df-agentctrl', version, entry: fileURLToPath(import.meta.url) };
+    stdout.write((args.includes('--json') ? JSON.stringify(report) : `df-agentctrl ${version}`) + '\n');
+    return 0;
+  }
+  let o, base, req;
+  try {
+    o = parse(args);
+    if (o.command === 'help' && !o.args.length) { stdout.write(help); return 0; }
+    if (o.help) {
+      const spec = Object.hasOwn(commands, o.command) ? commands[o.command] : undefined; if (!spec) throw Error(`unknown command ${o.command}`);
+      stdout.write(`df-agentctrl ${spec.usage} [--base-url <url>] [--json]\n\n${spec.description}\n`); return 0;
+    }
+    req = await requestFor(o);
+    base = o.values['--base-url'] || env.DF_AGENTCTRL_BASE_URL || 'http://127.0.0.1:8080';
+    const url = new URL(base);
+    if (!['http:', 'https:'].includes(url.protocol) || url.search || url.hash || url.username || url.password) throw Error('invalid base URL');
+  } catch (error) { stderr.write(error.message + '\n'); return 2; }
+  try {
+    const response = await fetch(base.replace(/\/+$/, '') + req.path, { method: req.method, body: req.body, headers: req.body ? { 'Content-Type': 'application/json' } : {}, signal: AbortSignal.timeout(30000) });
+    const data = await response.text();
+    if (response.status >= 400) throw Error(`HTTP ${response.status}: ${data.trim()}`);
+    let value; try { value = JSON.parse(data); } catch { throw Error('server returned invalid JSON'); }
+    if (o.json) stdout.write(data + '\n');
+    else if (o.command === 'diff' && (value === null || (typeof value === 'object' && !Array.isArray(value) && (value.files == null || Array.isArray(value.files))))) {
+      for (const file of value?.files || []) stdout.write(`${file.path} (+${file.additions} -${file.deletions})\n${file.patch}`);
+      if (!value?.files?.length) stdout.write('No differences.\n');
+    } else stdout.write(pretty(data) + '\n');
+    return 0;
+  } catch (error) { stderr.write(error.message + '\n'); return 1; }
+}
+if (process.argv[1] && fileURLToPath(import.meta.url) === realpathSync(process.argv[1])) process.exitCode = await run(process.argv.slice(2));

package/runtime/df-agentctrl/release.json

@@ -0,0 +1 @@
+{"version":"0.3.1","project":"deepflow-agent-ctrl","sourceCommit":"10e745773559f4712b04ab61915a018995e30630","sourceDirty":false}

package/runtime/df-agentrt/agentrt.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { RuntimeCLI } from './runtime.mjs';
+process.exitCode = await new RuntimeCLI({ self: false }).run(process.argv.slice(2));

package/runtime/df-agentrt/df-agentrt.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { RuntimeCLI } from './runtime.mjs';
+process.exitCode = await new RuntimeCLI({ self: true }).run(process.argv.slice(2));

package/runtime/df-agentrt/release.json

@@ -0,0 +1 @@
+{"version":"0.3.1","project":"deepflow-agent-runtime","sourceCommit":"420ebb91ed4cf92ca81eb8c295cc111f94b9da2c","sourceDirty":false}

package/runtime/df-agentrt/result.mjs

@@ -0,0 +1,44 @@
+import { createHash } from 'node:crypto';
+import { mkdtemp, open, link, rm } from 'node:fs/promises';
+import path from 'node:path';
+
+const terminal = (status) => ['succeeded', 'failed', 'cancelled'].includes(status);
+const statuses = ['pending', 'waiting_for_runtime', 'claimed', 'running', 'succeeded', 'failed', 'cancelled'];
+export function resultView(inv, maxBytes) {
+  const view = { invocation_id: inv.id, session_id: inv.session_id, status: inv.status, terminal: terminal(inv.status), result_state: terminal(inv.status) ? 'missing' : 'pending', output_present: false, output: '', output_bytes: 0, output_returned_bytes: 0, output_truncated: false };
+  if (inv.finished_at) view.finished_at = inv.finished_at;
+  if (inv.error) view.error = inv.error;
+  const invalid = (message) => { view.result_state = 'invalid'; view.format_error = message; return { view, output: '' }; };
+  if (!statuses.includes(inv.status)) { view.result_state = 'invalid'; view.format_error = 'unknown invocation status'; }
+  if (!inv.result) return { view, output: '' };
+  let result;
+  try { result = JSON.parse(inv.result); } catch { return invalid('result is not a JSON object'); }
+  if (!result || typeof result !== 'object' || Array.isArray(result)) return invalid('result is not a JSON object');
+  for (const [field, target] of [['error', 'result_error'], ['failure_reason', 'failure_reason']]) {
+    if (!Object.hasOwn(result, field) || result[field] === null) continue;
+    if (typeof result[field] !== 'string') return invalid(`${field} is not a string`);
+    if (result[field]) view[target] = result[field];
+  }
+  if (!Object.hasOwn(result, 'output') || result.output === null) return { view, output: '' };
+  if (typeof result.output !== 'string') return invalid('output is not a string');
+  const bytes = Buffer.from(result.output);
+  view.output_present = true; view.output_bytes = bytes.length;
+  if (view.terminal) view.result_state = 'available';
+  view.output_sha256 = createHash('sha256').update(bytes).digest('hex');
+  let end = Math.min(maxBytes, bytes.length);
+  if (end < bytes.length) while (end > 0 && (bytes[end] & 0xc0) === 0x80) end--;
+  view.output = bytes.subarray(0, end).toString('utf8');
+  view.output_truncated = bytes.length > maxBytes;
+  view.output_returned_bytes = end;
+  return { view, output: result.output };
+}
+
+// Publish a private file atomically without replacing a concurrent destination.
+export async function writeResultFile(destination, data) {
+  const directory = await mkdtemp(path.join(path.dirname(destination), '.invocation-result-'));
+  try {
+    const staging = path.join(directory, 'output'), file = await open(staging, 'wx', 0o600);
+    try { await file.writeFile(data); } finally { await file.close(); }
+    await link(staging, destination);
+  } finally { await rm(directory, { recursive: true, force: true }); }
+}