@metagptx/deepflow-suite-cli 0.3.0 → 0.3.2

package/runtime/df-task/commands.mjs

@@ -2,9 +2,10 @@ 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> [--metadata-source <source>] [--metadata-query-key <key>]
-  df-task create --title <text> [--description <text>] [--message <text>] [--metadata <json>]
+  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>] [--idempotency-key <key>]
   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>
@@ -13,7 +14,7 @@ Usage:
 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>]
+  df-task handoff <task-id> --ask <text> [--assignee <who>] [--participation ensure_member] [--task-assignee <json>]
 
 Global options (before or after the command):
   --base-url <url>   Service URL (or DF_TASK_BASE_URL)
@@ -22,7 +23,7 @@ Global options (before or after the command):
 
 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_KIND   Write identity: human | bot | 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.
@@ -41,9 +42,10 @@ export const commands = {
     "writes": false
   },
   "get": {
-    "usage": "get <task-id> [--metadata-source <source>] [--metadata-query-key <key>]",
-    "description": "Read one task's identity.",
+    "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"
     ],
@@ -52,13 +54,14 @@ export const commands = {
     "writes": false
   },
   "create": {
-    "usage": "create --title <text> [--description <text>] [--message <text>] [--metadata <json>]",
+    "usage": "create --title <text> [--description <text>] [--message <text>] [--metadata <json>] [--idempotency-key <key>]",
     "description": "Create a task, optionally with its first user message in the same transaction.",
     "flags": [
       "--title",
       "--description",
       "--message",
-      "--metadata"
+      "--metadata",
+      "--idempotency-key"
     ],
     "required": [
       "--title"
@@ -67,9 +70,14 @@ export const commands = {
     "writes": true
   },
   "facts": {
-    "usage": "facts <task-id> [--after <seq>] [--types <a,b>] [--limit <n>] [--metadata-source <source>] [--metadata-query-key <key>]",
-    "description": "Read one task's facts in seq order.",
+    "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",
@@ -166,11 +174,14 @@ export const commands = {
     "writes": true
   },
   "handoff": {
-    "usage": "handoff <task-id> --ask <text> [--assignee <who>]",
+    "usage": "handoff <task-id> --ask <text> [--assignee <who>] [--participation ensure_member] [--task-assignee <json>]",
     "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"
+      "--assignee",
+      "--participation",
+      "--task-assignee",
+      "--idempotency-key"
     ],
     "required": [
       "--ask"

package/runtime/df-task/df-task.mjs

@@ -4,9 +4,10 @@ import { fileURLToPath } from 'node:url';
 import { realpathSync } from 'node:fs';
 import { help, commands } from './commands.mjs';
 import { factTypes, actorKinds } from './protocol.mjs';
+import { validateReadOptions, projectResponse, readAllFacts, readResponse } from './read.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)]);
+const valueFlags = new Set(['--base-url', ...Object.values(commands).flatMap((spec) => spec.flags).filter((flag) => flag !== '--all')]);
 export function parse(args) {
   const o = { command: '', args: [], values: {}, json: false, help: false };
   const seen = new Set();
@@ -20,6 +21,9 @@ export function parse(args) {
     if (['--help', '-h', '--json'].includes(key)) {
       if (equals >= 0) throw Error(`${key} does not take a value`);
       o[key === '--json' ? 'json' : 'help'] = true;
+    } else if (key === '--all') {
+      if (equals >= 0) throw Error(`${key} does not take a value`);
+      o.values[key] = '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);
@@ -54,9 +58,23 @@ export function validate(o, env) {
   }
   if (spec.writes) {
     if (!env.DF_TASK_ACTOR_KIND?.trim() || !env.DF_TASK_ACTOR_ID?.trim()) throw Error('writing a fact requires DF_TASK_ACTOR_KIND and DF_TASK_ACTOR_ID');
+    if (o.command === 'create') {
+      const key = o.values['--idempotency-key'] || '';
+      if (key.length > 200 || /[^\x21-\x7e]/.test(key) || (env.DF_TASK_ACTOR_KIND === 'bot' && key.length < 8)) throw Error('creation idempotency key must be at most 200 visible ASCII bytes; bot creation requires at least 8 bytes');
+    }
     if (!actorKinds.includes(env.DF_TASK_ACTOR_KIND)) throw Error(`unknown DF_TASK_ACTOR_KIND ${env.DF_TASK_ACTOR_KIND}`);
-    if (o.command === 'metadata' && env.DF_TASK_ACTOR_KIND !== 'human') throw Error('metadata requires DF_TASK_ACTOR_KIND=human');
+    if (o.command === 'metadata' && !['human','bot'].includes(env.DF_TASK_ACTOR_KIND)) throw Error('metadata requires DF_TASK_ACTOR_KIND=human or bot');
+  }
+  if (o.command === 'handoff' && ('--participation' in o.values || '--task-assignee' in o.values)) {
+    const target = o.values['--assignee'];
+    if (o.values['--participation'] !== 'ensure_member') throw Error('--participation must be ensure_member for member operations');
+    if (!target || target.trim() !== target || Buffer.byteLength(target) > 200) throw Error('member operations require a non-empty --assignee of at most 200 bytes without surrounding whitespace');
+    if ('--task-assignee' in o.values) {
+      const assignment = object(o.values['--task-assignee'], '--task-assignee must be a JSON object');
+      if (Object.keys(assignment).length !== 2 || assignment.kind !== 'human' || assignment.id !== target) throw Error('--task-assignee must identify the same human as --assignee');
+    }
   }
+  validateReadOptions(o);
 }
 function object(raw, message) {
   let value;
@@ -90,8 +108,8 @@ export async function requestFor(o) {
   let type, payload;
   if (c === 'dispatch') { type = 'dispatch_intent'; payload = { agent: v['--agent'], instruction: v['--instruction'], mode: v['--run'] ? 'message' : 'new_run', ...(v['--run'] ? { target_run_id: v['--run'] } : {}) }; }
   if (c === 'wait') { type = 'waiting_reason'; payload = { waiting_on: v['--on'], reason: v['--reason'], ...(v['--waiting-run'] ? { waiting_run_id: v['--waiting-run'] } : {}) }; }
-  if (c === 'handoff') { type = 'handoff_to_human'; payload = { ask: v['--ask'], ...(v['--assignee'] ? { assignee: v['--assignee'] } : {}) }; }
-  return post(`${path}/facts`, { type, payload });
+  if (c === 'handoff') { type = 'handoff_to_human'; payload = { ask: v['--ask'], ...(v['--assignee'] ? { assignee: v['--assignee'] } : {}), ...(v['--participation'] ? { participation: v['--participation'] } : {}), ...(v['--task-assignee'] ? { task_assignee: object(v['--task-assignee'], '--task-assignee must be a JSON object') } : {}) }; }
+  return post(`${path}/facts`, { type, payload, ...(v['--idempotency-key'] ? {idempotency_key:v['--idempotency-key']} : {}) });
 }
 function human(command, data, stdout) {
   const page = JSON.parse(data, (_key, value, context) => typeof value === 'number' && !Number.isSafeInteger(value) && /^-?\d+$/.test(context.source) ? BigInt(context.source) : value) || {};
@@ -127,7 +145,7 @@ export async function run(args, { env = process.env, stdout = process.stdout, st
     stdout.write((args.includes('--json') ? JSON.stringify(report) : `df-task ${version}`) + '\n');
     return 0;
   }
-  let o, base, req;
+  let o, base, initialRequest;
   try {
     o = parse(args);
     if (o.command === 'help' && !o.args.length) { stdout.write(help); return 0; }
@@ -139,15 +157,23 @@ export async function run(args, { env = process.env, stdout = process.stdout, st
     base = o.values['--base-url'] || env.DF_TASK_BASE_URL || 'http://127.0.0.1:8090';
     const url = new URL(base);
     if (!['http:', 'https:'].includes(url.protocol) || url.search || url.hash || url.username || url.password) throw Error('invalid base URL');
-    req = await requestFor(o);
+    initialRequest = await requestFor(o);
   } catch (error) { stderr.write(error.message + '\n'); return 2; }
-  try {
+  const request = async (options, limit = 0) => {
+    const req = options === o ? initialRequest : await requestFor(options);
     const headers = req.body ? { 'Content-Type': 'application/json' } : {};
+    if (o.command === 'create' && o.values['--idempotency-key']) headers['Idempotency-Key'] = o.values['--idempotency-key'];
     if (req.method !== 'GET') { headers['X-DF-Actor-Kind'] = env.DF_TASK_ACTOR_KIND; headers['X-DF-Actor-Id'] = env.DF_TASK_ACTOR_ID; }
     const response = await fetch(base.replace(/\/+$/, '') + req.path, { method: req.method, body: req.body, headers, signal: AbortSignal.timeout(30000) });
-    const data = await response.text();
+    const data = await readResponse(response, limit);
     if (response.status >= 400) throw Error(`HTTP ${response.status}: ${data.trim()}`);
     try { JSON.parse(data); } catch { throw Error('server returned invalid JSON'); }
+    return data;
+  };
+  if (o.values['--all']) return readAllFacts(o, base, request, stdout, stderr);
+  try {
+    let data = await request(o, '--fields' in o.values ? 64 << 20 : 0);
+    if ('--fields' in o.values) data = projectResponse(o.command, data, o.values['--fields'].split(','));
     if (o.json) stdout.write(data + '\n'); else human(o.command, data, stdout);
     return 0;
   } catch (error) { stderr.write(error.message + '\n'); return 1; }

package/runtime/df-task/protocol.mjs

@@ -1,3 +1,3 @@
 // Generated by generate-protocol.mjs from internal/model/fact.go.
 export const factTypes = ["task_lifecycle","user_message","external_result","artifact_published","summary","help_requested","run_outcome","dispatch_intent","waiting_reason","handoff_to_human","adjudication","run_terminated","invocation_started","invocation_accepted","invocation_ended","attempt_failed"];
-export const actorKinds = ["human","external","task_run","scheduler_run","driver"];
+export const actorKinds = ["human","bot","external","task_run","scheduler_run","driver"];

package/runtime/df-task/read.mjs

@@ -0,0 +1,127 @@
+import { createHash } from 'node:crypto';
+import { lstat, mkdtemp, open, link, rm } from 'node:fs/promises';
+import path from 'node:path';
+
+// Retain every numeric token verbatim, including values outside JS precision.
+export const decodeRaw = (raw) => JSON.parse(raw, (_key, value, context) => typeof value === 'number' ? JSON.rawJSON(context.source) : value);
+export const encodeRaw = (value) => JSON.stringify(value);
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value) && !JSON.isRawJSON(value);
+const seq = (value) => {
+  if (!JSON.isRawJSON(value) || !/^-?\d+$/.test(value.rawJSON)) throw Error('invalid facts sequence');
+  const n = BigInt(value.rawJSON);
+  if (n < 0n || n > 9223372036854775807n) throw Error('invalid facts sequence');
+  return n;
+};
+const rawSeq = (n) => JSON.rawJSON(BigInt(n).toString());
+
+export function validateReadOptions(o) {
+  const v = o.values;
+  if ('--fields' in v) {
+    if (!o.json) throw Error('--fields requires --json');
+    const roots = o.command === 'get' ? ['id', 'title', 'description', 'description_version', 'creator', 'metadata', 'created_at', 'updated_at'] : ['seq', 'type', 'actor_kind', 'actor_id', 'payload', 'idempotency_key', 'created_at'];
+    const paths = v['--fields'].split(',');
+    paths.forEach((field, i) => {
+      const parts = field.split('.');
+      if (!roots.includes(parts[0]) || (parts.length > 1 && !['metadata', 'payload'].includes(parts[0]))) throw Error(`unsupported field path ${JSON.stringify(field)} for ${o.command}`);
+      if (parts.some((part) => !part || part.trim() !== part || /[\[\]*\/\\\t\r\n]/.test(part))) throw Error(`invalid object field path ${JSON.stringify(field)}`);
+      if (paths.slice(0, i).some((earlier) => earlier === field || earlier.startsWith(field + '.') || field.startsWith(earlier + '.'))) throw Error('overlapping field paths');
+    });
+  }
+  const all = '--all' in v;
+  if (all && (!o.json || !v['--output-file']?.trim() || '--fields' in v)) throw Error('--all requires --json and --output-file, and cannot be combined with --fields');
+  for (const flag of ['--output-file', '--max-pages', '--max-bytes']) if (flag in v && !all) throw Error(`${flag} requires --all`);
+  for (const [flag, max] of [['--max-pages', 100], ['--max-bytes', 64 << 20]]) {
+    if (flag in v && (!/^\+?\d+$/.test(v[flag]) || BigInt(v[flag]) < 1n || BigInt(v[flag]) > BigInt(max))) throw Error(`${flag} must be between 1 and ${max}`);
+  }
+}
+
+function projectObject(source, paths) {
+  if (!isObject(source)) throw Error('expected a JSON object for field selection');
+  const selected = Object.create(null), children = new Map();
+  for (const field of paths) {
+    const [root, ...parts] = field.split('.');
+    if (parts.length) { if (!children.has(root)) children.set(root, []); children.get(root).push(parts.join('.')); }
+    else if (Object.hasOwn(source, root)) selected[root] = source[root];
+  }
+  for (const [root, subpaths] of children) {
+    if (!Object.hasOwn(source, root) || !isObject(source[root])) continue;
+    const projected = projectObject(source[root], subpaths);
+    if (Object.keys(projected).length) selected[root] = projected;
+  }
+  return selected;
+}
+export function projectResponse(command, raw, paths) {
+  const data = decodeRaw(raw);
+  if (command === 'get') return encodeRaw(projectObject(data, paths));
+  if (!isObject(data) || !Array.isArray(data.facts)) throw Error('expected facts array');
+  data.facts = data.facts.map((fact) => projectObject(fact, paths));
+  return encodeRaw(data);
+}
+const normalizedID = (id) => typeof id === 'string' ? id.toLowerCase().replace(/^urn:uuid:/, '').replace(/[{}-]/g, '') : '';
+export function validateFactPage(raw, taskID, after) {
+  const page = decodeRaw(raw);
+  if (!isObject(page) || !Array.isArray(page.facts) || !Object.hasOwn(page, 'next_after_seq')) throw Error('invalid facts page identity, facts or cursor');
+  if (!/^[0-9a-f]{32}$/.test(normalizedID(page.task_id)) || normalizedID(page.task_id) !== normalizedID(taskID)) throw Error('facts page task_id does not match query');
+  let last = after;
+  for (const fact of page.facts) {
+    if (!isObject(fact) || typeof fact.type !== 'string' || !fact.type || seq(fact.seq) <= last) throw Error(`facts page is not strictly ordered after ${after}`);
+    last = seq(fact.seq);
+  }
+  if (seq(page.next_after_seq) !== last) throw Error(`facts cursor does not match last seq ${last}`);
+  return { facts: page.facts, next: last };
+}
+export async function readResponse(response, limit = 0) {
+  if (!limit) return response.text();
+  let bytes = 0; const chunks = [];
+  for await (const chunk of response.body) {
+    bytes += chunk.length;
+    if (bytes > limit) throw Object.assign(Error('read byte budget exhausted'), { byteLimit: true });
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+export async function readAllFacts(o, baseURL, request, stdout, stderr) {
+  const output = path.resolve(o.values['--output-file']);
+  let temp;
+  try {
+    try { await lstat(output); throw Error(`output file must not exist: ${output}`); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+    temp = await mkdtemp(path.join(path.dirname(output), '.task-facts-'));
+  } catch (error) { stderr.write(error.message + '\n'); return 2; }
+  try {
+    const query = { task_id: o.args[0], base_url: baseURL, after_seq: '0', limit: '200' };
+    for (const flag of ['--after', '--types', '--limit', '--metadata-source', '--metadata-query-key']) if (flag in o.values) query[flag === '--after' ? 'after_seq' : flag.slice(2).replaceAll('-', '_')] = o.values[flag];
+    const manifest = { query, complete: false, stop_reason: 'page_limit', pages: 0, count: 0, next_after_seq: rawSeq(query.after_seq), type_counts: Object.create(null), response_bytes: 0, output_file: output };
+    const facts = [], budget = Number(o.values['--max-bytes'] || (8 << 20));
+    let cursor = BigInt(query.after_seq);
+    for (let i = 0; i < Number(o.values['--max-pages'] || 10); i++) {
+      const remaining = budget - manifest.response_bytes;
+      if (remaining <= 0) { manifest.stop_reason = 'byte_limit'; break; }
+      let raw, page;
+      try { raw = await request({ ...o, values: { ...o.values, '--after': String(cursor) } }, remaining); }
+      catch (error) { manifest.stop_reason = error.byteLimit ? 'byte_limit' : 'request_error'; stderr.write(error.message + '\n'); break; }
+      manifest.response_bytes += Buffer.byteLength(raw);
+      try { page = validateFactPage(raw, o.args[0], cursor); }
+      catch (error) { manifest.stop_reason = 'invalid_page'; stderr.write(error.message + '\n'); break; }
+      manifest.pages++;
+      if (!page.facts.length) { manifest.complete = true; manifest.stop_reason = 'empty_page'; break; }
+      for (const fact of page.facts) {
+        if (!manifest.count) manifest.first_seq = fact.seq;
+        manifest.last_seq = fact.seq;
+        manifest.type_counts[fact.type] = (manifest.type_counts[fact.type] || 0) + 1;
+        manifest.count++;
+      }
+      facts.push(...page.facts); cursor = page.next; manifest.next_after_seq = rawSeq(cursor);
+    }
+    const data = Buffer.from(encodeRaw({ query, facts, complete: manifest.complete, stop_reason: manifest.stop_reason, next_after_seq: manifest.next_after_seq }));
+    const staging = path.join(temp, 'facts.json'), file = await open(staging, 'wx', 0o600);
+    try { await file.writeFile(data); } finally { await file.close(); }
+    await link(staging, output);
+    manifest.file_bytes = data.length; manifest.file_sha256 = createHash('sha256').update(data).digest('hex');
+    stdout.write(encodeRaw(manifest) + '\n');
+    if (!manifest.complete) { stderr.write(`incomplete facts read: ${manifest.stop_reason}; next_after_seq=${cursor}\n`); return 1; }
+    return 0;
+  } catch (error) { stderr.write(error.message + '\n'); return 1; }
+  finally { await rm(temp, { recursive: true, force: true }); }
+}

package/runtime/df-task/release.json

@@ -1 +1 @@
-{"version":"0.3.0","project":"deepflow-task","sourceCommit":"3a8f5c8915cf5df74236eb4da693ac75f4c816a8","sourceDirty":false}
+{"version":"0.3.2","project":"deepflow-task","sourceCommit":"cc53e86834b19e8a4fe73f9e9a08d76853d51e51","sourceDirty":false}

package/runtime/df-taskdriver/release.json

@@ -1 +1 @@
-{"version":"0.3.0","project":"deepflow-task-driver","sourceCommit":"ab582505c8d60a99c8d2939c3d58b31803a8a229","sourceDirty":false}
+{"version":"0.3.2","project":"deepflow-task-driver","sourceCommit":"c05efdc13dfd0d7a9043007f7421dbd1ac6daab2","sourceDirty":false}