flowviant 0.125.30 → 0.125.33

package/bin/lib/codexInput.mjs

@@ -0,0 +1,191 @@
+/** Codex's native application protocol. Keep exec's config and event readers;
+ * only conversational build turns change transport. Fenced/structured jobs
+ * retain exec rather than translate a permission profile incompletely. */
+import { randomUUID } from 'node:crypto';
+import { versionAtLeast } from './versionOrder.mjs';
+
+export function codexAppArgs(execArgs, version = null) {
+  if (version && !versionAtLeast(String(version).replace(/^codex-cli\s+/, ''), '0.166.0')) return null;
+  if (execArgs.includes('--ignore-user-config') || execArgs.includes('--output-schema')) return null;
+  const out = ['app-server', '--listen', 'stdio://'];
+  for (let i = 1; i < execArgs.length - 1; i++) {
+    const arg = execArgs[i];
+    if (arg === 'resume') {
+      if (execArgs[++i] === '--last') return null; // never guess another tab's thread
+    } else if (arg === '-c' || arg === '--config' || arg === '--enable' || arg === '--disable') {
+      out.push(arg, execArgs[++i]);
+    } else if (arg === '--model') out.push('-c', `model=${JSON.stringify(execArgs[++i])}`);
+    else if (arg === '--cd') i++;
+    else if (!['--json', '--skip-git-repo-check'].includes(arg)) return null;
+  }
+  return out;
+}
+
+const snake = s => s.replace(/[A-Z]/g, c => `_${c.toLowerCase()}`);
+export function codexAppItem(item) {
+  if (!item?.type) return null;
+  const out = Object.fromEntries(Object.entries(item).map(([key, value]) => [snake(key), value]));
+  out.type = item.type === 'collabAgentToolCall' ? 'collab_tool_call' : snake(item.type);
+  return out;
+}
+
+/** A response means the runtime accepted input, not that the model acted on
+ * it. clientUserMessageId is retained in native history for restart dedup.
+ * A completion racing a steer drains its RPC before closing stdin. */
+export function createCodexInput(child, { cwd, threadId = null, onTaken = () => {}, onThread = () => {},
+  onEvent = () => {}, onFailure = () => {}, onContext = null, rpcTimeoutMs = 30_000 } = {}) {
+  let seq = 0, ready = false, active = null, starting = false, ended = false, broken = false;
+  let usage = null, previousUsage = null, lastContext = null;
+  const requests = new Map(), queued = [], sent = new Set(), seen = new Set(), completed = new Set();
+  const write = value => {
+    if (ended || broken || child.stdin.destroyed || child.stdin.writableEnded) return false;
+    try { child.stdin.write(JSON.stringify(value) + '\n'); return true; }
+    catch { broken = true; return false; }
+  };
+  const rpc = (method, params, done) => {
+    const id = ++seq;
+    const timer = setTimeout(() => {
+      requests.delete(id);
+      fail(`Codex did not acknowledge ${method} within ${rpcTimeoutMs / 1000} seconds. Unacknowledged input remains queued.`);
+    }, rpcTimeoutMs);
+    timer.unref?.();
+    requests.set(id, { method, done, timer });
+    if (!write({ id, method, params })) { clearTimeout(timer); requests.delete(id); return false; }
+    return true;
+  };
+  const end = () => { if (!ended) {
+    ended = true;
+    for (const request of requests.values()) clearTimeout(request.timer);
+    requests.clear(); child.stdin.end();
+  } };
+  const finishUsage = () => {
+    if (usage) onEvent({ type: 'turn.completed', usage });
+    usage = null;
+  };
+  const fail = message => {
+    if (ended) return;
+    finishUsage();
+    onFailure();
+    onEvent({ type: 'turn.failed', error: { message } });
+    end();
+  };
+  const inflight = () => [...requests.values()].some(r => r.method.startsWith('turn/'));
+  const pump = () => {
+    if (!ready || ended || broken || starting || inflight()) return;
+    while (queued.length && seen.has(queued[0].id)) onTaken(queued.shift().id);
+    const next = queued.shift();
+    if (!next) return;
+    const method = active ? 'turn/steer' : 'turn/start';
+    starting = !active;
+    const expected = active;
+    const params = { threadId, input: [{ type: 'text', text: next.prompt }], clientUserMessageId: next.id,
+      ...(active ? { expectedTurnId: active } : {}) };
+    if (!rpc(method, params, response => {
+      starting = false;
+      if (response.error) {
+        // The run can finish while this RPC is in the pipe. Only a measured
+        // completed turn permits a new native turn with the same input id.
+        if (method === 'turn/steer' && active === null) queued.unshift(next);
+        else if (method === 'turn/start') { fail(response.error.message || 'Codex could not start the turn.'); return; }
+        else onEvent({ type: 'error', message: response.error.message || 'Codex could not accept the follow-up; it remains queued.' });
+      } else {
+        seen.add(next.id);
+        onTaken(next.id);
+        if (method === 'turn/start' && response.result?.turn?.status === 'inProgress' && !completed.has(response.result.turn.id)) active = response.result.turn.id;
+        // A steer response must never resurrect its completed predecessor.
+        if (method === 'turn/steer' && active && active !== expected) return;
+      }
+      pump();
+      if (!active && !starting && !queued.length && !inflight()) end();
+    })) fail('Codex could not receive the complete turn input.');
+  };
+  child.stdin.on('error', () => { broken = true; onFailure(); });
+  return {
+    start() {
+      rpc('initialize', { clientInfo: { name: 'flowviant', title: 'Flowviant', version: '1' } }, response => {
+        if (response.error) { fail(response.error.message); return; }
+        write({ method: 'initialized', params: {} });
+        rpc(threadId ? 'thread/resume' : 'thread/start', { ...(threadId ? { threadId } : {}), cwd, approvalPolicy: 'never' }, response => {
+          if (response.error) { fail(response.error.message); return; }
+          const thread = response.result?.thread;
+          if (!thread?.id) { fail('Codex returned no conversation id.'); return; }
+          threadId = thread.id;
+          for (const turn of thread.turns ?? []) for (const item of turn.items ?? [])
+            if (item.type === 'userMessage' && item.clientId) seen.add(item.clientId);
+          onThread(threadId);
+          onEvent({ type: 'thread.started', thread_id: threadId });
+          ready = true;
+          // Recovery of the initial prompt: continue its existing work rather
+          // than repeat the original request already in the native transcript.
+          if (queued[0] && seen.has(queued[0].id)) {
+            const initial = queued.shift(); onTaken(initial.id);
+            queued.unshift({ id: `recovery-${randomUUID()}`, prompt: 'Continue the request already in this conversation. Inspect work in flight before repeating commands.' });
+          }
+          pump();
+        });
+      });
+    },
+    send(id, prompt) {
+      if (ended || broken || sent.has(id)) return false;
+      sent.add(id);
+      queued.push({ id, prompt });
+      pump();
+      return true;
+    },
+    event(event) {
+      if (ended) return;
+      if ('id' in event && !event.method) {
+        const request = requests.get(event.id);
+        if (request) { clearTimeout(request.timer); requests.delete(event.id); request.done(event); }
+        return;
+      }
+      const p = event.params ?? {};
+      // Server-originated approval/tool requests cannot hang an unattended
+      // process. Return a protocol refusal, never synthesize permission.
+      if ('id' in event && event.method) {
+        write({ id: event.id, error: { code: -32601, message: 'This unattended conversation cannot answer interactive requests.' } });
+        return;
+      }
+      if (p.threadId && p.threadId !== threadId) return;
+      if (event.method === 'turn/started') {
+        active = p.turn?.id ?? active;
+        onEvent({ type: 'turn.started' });
+      }
+      if (event.method === 'item/started' || event.method === 'item/completed') {
+        const item = codexAppItem(p.item);
+        if (item) onEvent({ type: event.method.replace('/', '.'), item });
+      }
+      if (event.method === 'thread/tokenUsage/updated') {
+        const last = p.tokenUsage?.last;
+        const fingerprint = JSON.stringify(p.tokenUsage?.total);
+        if (last && (active || starting) && fingerprint !== previousUsage) {
+          previousUsage = fingerprint;
+          usage ??= { input_tokens: 0, output_tokens: 0, cached_input_tokens: 0 };
+          usage.input_tokens += last.inputTokens ?? 0;
+          usage.output_tokens += last.outputTokens ?? 0;
+          usage.cached_input_tokens += last.cachedInputTokens ?? 0;
+        }
+        const window = p.tokenUsage?.modelContextWindow;
+        // Last request occupancy, never the thread's cumulative billable spend.
+        if (onContext && last && Number.isFinite(window) && window > 0) {
+          lastContext = { usedTokens: last.inputTokens + last.outputTokens, windowTokens: window, compactAt: null, compacting: false };
+          onContext(lastContext);
+        }
+      }
+      if (p.item?.type === 'contextCompaction' && lastContext && onContext && ['item/started', 'item/completed'].includes(event.method))
+        onContext({ ...lastContext, compacting: event.method === 'item/started' });
+      if (event.method === 'error' && p.willRetry !== true) fail(p.error?.message || 'Codex reported an error.');
+      if (event.method === 'turn/completed') {
+        if (active && p.turn?.id !== active) return;
+        completed.add(p.turn?.id);
+        active = null;
+        finishUsage();
+        if (p.turn?.status === 'failed') { fail(p.turn.error?.message || 'Codex failed the turn.'); return; }
+        if (p.turn?.status === 'interrupted') { fail('Codex interrupted the turn.'); return; }
+        pump();
+        if (!starting && !queued.length && !inflight()) end();
+      }
+    },
+    close() { ended = true; for (const request of requests.values()) clearTimeout(request.timer); requests.clear(); queued.length = 0; },
+  };
+}

package/bin/lib/codexSubagentEvents.mjs

@@ -27,7 +27,9 @@ export function codexCollabUpdates(item) {
     const receiver = item.receiver_agents?.find(a => a.thread_id === id);
     const status = statusOf(state?.status ?? state);
     const message = state?.message ?? (typeof state?.completed === 'string' ? state.completed : null);
-    return [{ id, ...(tool === 'spawn_agent' ? { ...(item.id ? { callId: item.id } : {}), ...(typeof item.prompt === 'string' ? { brief: item.prompt } : {}),
+    // The spawning thread is the child's parent; the reader names the lead's 'lead'.
+    const parent = tool === 'spawn_agent' && CODEX_CHILD_THREAD_RE.test(item.sender_thread_id ?? '') ? { parent: item.sender_thread_id } : {};
+    return [{ id, ...parent, ...(tool === 'spawn_agent' ? { ...(item.id ? { callId: item.id } : {}), ...(typeof item.prompt === 'string' ? { brief: item.prompt } : {}),
         ...(receiver?.agent_path || receiver?.agent_nickname || item.title ? { title: receiver?.agent_path ?? receiver?.agent_nickname ?? item.title } : {}),
         ...(receiver?.agent_role || item.agent_type ? { kind: receiver?.agent_role ?? item.agent_type } : {}),
       } : {}),

package/bin/lib/codexSubagents.mjs

@@ -4,6 +4,14 @@
  * rust-v0.160.0: exec_events.rs CollabToolCallItem; core/agent/child_config.rs
  * reapplies the live turn's approval and permission profile after role config.
  * V2 rollout shapes measured on codex-cli 0.163.0 (codexSubagents.test.mjs).
+ *
+ * A child's own rollout says what it ran on (2026-11-06, S4.1): its newest
+ * `turn_context` names the model and effort that turn resolved, never what
+ * the spawn asked for; `session_meta`'s thread_spawn names the thread that
+ * spawned it (the lead, or another child: nesting); `task_complete` carries
+ * its final message, the result. `knownTargets` are a resumed agent's
+ * children from earlier turns (workAgentResume.mjs), name → thread, so a
+ * follow-up by task path reaches the record it continues.
  */
 import { open } from 'node:fs/promises';
 import { codexRolloutFile } from './runtimeLimits.mjs';
@@ -13,6 +21,9 @@ import { codexCollabUpdates, codexSpawnResult, statusOf } from './codexSubagentE
 import { NATIVE_AGENT_TOOLS } from './nativeAgentTools.mjs';
 import { isSealedMessage } from './orchestratorNative.mjs';
 import { SUBAGENT_CAP } from './subagentBounds.mjs';
+import { turnModelOf } from './turnModel.mjs';
+
+const EFFORT_RE = /^[a-z]{1,24}$/;
 
 const CODEX = NATIVE_AGENT_TOOLS.codex;
 // A rollout shows a superset of what the gate sees: send_message and the
@@ -22,7 +33,7 @@ const COLLAB_CALLS = [...CODEX.spawn, ...CODEX.followup, ...CODEX.message, ...CO
 const RECEIPT_CALLS = [...CODEX.spawn, ...CODEX.followup];
 
 export function createCodexSubagentReader({ since = Date.now(), env = process.env, onSubagent, onActivity, onToolEvent, onSpawnResult,
-  findFile = codexRolloutFile } = {}) {
+  findFile = codexRolloutFile, knownTargets = null } = {}) {
   const readers = new Map();
   const calls = new Map();
   const targets = new Map();
@@ -33,11 +44,12 @@ export function createCodexSubagentReader({ since = Date.now(), env = process.en
   let chain = Promise.resolve();
   const report = update => {
     if (!update?.id || !CODEX_CHILD_THREAD_RE.test(update.id)) return;
-    // The root thread plus the run's children.
-    if (!readers.has(update.id) && readers.size >= SUBAGENT_CAP + 1) return;
-    if (!readers.has(update.id))
+    // The root thread plus the run's children are followed. A child past the
+    // cap is still reported, unfollowed: the relay counts it as not recorded.
+    if (!readers.has(update.id) && readers.size < SUBAGENT_CAP + 1)
       readers.set(update.id, { offset: null, rest: Buffer.alloc(0), seen: new Set(), live: false });
     const { message, ...record } = update;
+    if (record.parent && record.parent === root) record.parent = 'lead';
     onSubagent?.(record);
   };
   const rememberTarget = (path, id) => {
@@ -45,6 +57,7 @@ export function createCodexSubagentReader({ since = Date.now(), env = process.en
     if (targets.size > 128) targets.delete(targets.keys().next().value);
   };
   const targetId = value => targets.get(value) ?? (CODEX_CHILD_THREAD_RE.test(value ?? '') ? value : null);
+  if (knownTargets) for (const [name, id] of knownTargets) if (CODEX_CHILD_THREAD_RE.test(id ?? '')) rememberTarget(name, id);
 
   function observe(ev, owner) {
     const at = Date.parse(ev?.timestamp ?? '');
@@ -65,10 +78,18 @@ export function createCodexSubagentReader({ since = Date.now(), env = process.en
       if (src) {
         const title = src.agent_path ?? src.agent_nickname;
         if (src.agent_path) rememberTarget(src.agent_path, owner);
-        report({ id: owner, ...(title ? { title } : {}), ...(src.agent_role ? { kind: src.agent_role } : {}) });
+        const parent = CODEX_CHILD_THREAD_RE.test(src.parent_thread_id ?? '') ? { parent: src.parent_thread_id } : {};
+        report({ id: owner, ...(title ? { title } : {}), ...(src.agent_role ? { kind: src.agent_role } : {}), ...parent });
       }
       return;
     }
+    if (ev.type === 'turn_context' && owner !== root) {
+      const model = turnModelOf(p.model);
+      const effort = p.effort ?? p.collaboration_mode?.settings?.reasoning_effort;
+      const brain = { ...(model ? { model } : {}), ...(typeof effort === 'string' && EFFORT_RE.test(effort) ? { effort } : {}) };
+      if (Object.keys(brain).length) report({ id: owner, ...brain });
+      return;
+    }
     if (ev.type === 'response_item' && p.type === 'function_call') {
       const name = String(p.name ?? '').split('.').at(-1);
       if (owner !== root && ['exec_command', 'shell_command', 'shell'].includes(name)) {
@@ -126,7 +147,7 @@ export function createCodexSubagentReader({ since = Date.now(), env = process.en
       // A V2 message is ciphertext (orchestratorNative.mjs `isSealedMessage`):
       // its words are unknown, so the child carries no brief rather than that.
       const sealed = isSealedMessage(call.namespace ? `${call.namespace}.${call.name}` : call.name, args.message);
-      report({ id, kind: args.agent_type ?? '', title, ...(sealed ? {} : { brief: args.message ?? '' }), status: 'running', now: '' });
+      report({ id, kind: args.agent_type ?? '', title, ...(sealed ? {} : { brief: args.message ?? '' }), status: 'running', now: '', parent: owner });
       return;
     }
     if (owner !== root && ev.type === 'response_item' && p.type === 'custom_tool_call') {
@@ -167,7 +188,7 @@ export function createCodexSubagentReader({ since = Date.now(), env = process.en
       return;
     }
     if (p.type === 'collab_agent_spawn_end' && p.new_thread_id) {
-      report({ id: p.new_thread_id, brief: p.prompt ?? '', kind: p.new_agent_role ?? '', title: p.new_agent_nickname ?? '',
+      report({ id: p.new_thread_id, brief: p.prompt ?? '', kind: p.new_agent_role ?? '', title: p.new_agent_nickname ?? '', parent: owner,
         status: statusOf(typeof p.status === 'object' ? Object.keys(p.status)[0]?.toLowerCase() : p.status) ?? 'running' });
     }
     if (owner === root) return;
@@ -181,7 +202,7 @@ export function createCodexSubagentReader({ since = Date.now(), env = process.en
         onToolEvent?.('Write', { file_path: path, content: change?.add?.content ?? '' }, { agentId: owner, id: p.call_id });
     }
     if (p.type === 'task_started' || p.type === 'turn_started') report({ id: owner, status: 'running' });
-    if (p.type === 'task_complete' || p.type === 'turn_complete') report({ id: owner, status: 'done', ...(p.last_agent_message ? { now: p.last_agent_message } : {}) });
+    if (p.type === 'task_complete' || p.type === 'turn_complete') report({ id: owner, status: 'done', ...(p.last_agent_message ? { now: p.last_agent_message, result: p.last_agent_message } : {}) });
     if (p.type === 'turn_aborted') report({ id: owner, status: 'stopped' });
   }
 
@@ -199,7 +220,7 @@ export function createCodexSubagentReader({ since = Date.now(), env = process.en
         try {
           const ev = JSON.parse(line);
           if (initial && id !== root) initialEvents.push(ev);
-          else if (id === root || state.live || ev.type === 'session_meta') observe(ev, id);
+          else if (id === root || state.live || ev.type === 'session_meta' || ev.type === 'turn_context') observe(ev, id);
           else if (ev.type === 'event_msg' && ['task_started', 'turn_started'].includes(ev.payload?.type)) {
             state.live = true; observe(ev, id);
           }
@@ -210,6 +231,10 @@ export function createCodexSubagentReader({ since = Date.now(), env = process.en
         // native turn belongs to this card; inherited history is never replayed.
         for (const ev of initialEvents) if (ev.type === 'session_meta') observe(ev, id);
         const start = initialEvents.findLastIndex(ev => ev.type === 'event_msg' && ['task_started', 'turn_started'].includes(ev.payload?.type));
+        // The newest context is this turn's, wherever the CLI wrote it; an
+        // older turn's is refused by `since`.
+        const context = initialEvents.findLastIndex(ev => ev.type === 'turn_context');
+        if (context >= 0 && (start < 0 || context < start)) observe(initialEvents[context], id);
         if (start >= 0) {
           state.live = true;
           for (const ev of initialEvents.slice(start)) observe(ev, id);

package/bin/lib/conversationOutput.mjs

@@ -0,0 +1,14 @@
+/** One output vocabulary for Terminal, capture and agent conversations. */
+export const CONVERSATION_OUTPUT = `CONVERSATION OUTPUT: both Terminal and agent chats render Markdown tables, highlighted code and LaTeX (use $$ delimiters for math; shell/console blocks use the reading font, source code uses monospace).
+Printed source fences have Copy and Download; add file=script.py after the language to name the downloaded code file.
+For a diagram, use a mermaid fence. For an illustration or an interactive view, use a flowviant-svg or flowviant-html fence. Those explicit fences render in an opaque sandbox: inline CSS/JS and data: images work; network requests, external scripts, forms, popups and access to the app do not. Ordinary html/svg/js fences remain printed source code. Keep inline visuals under 100,000 characters. Prefer retained artifacts for large, downloadable or reusable outputs.
+For a native data card, use a flowviant-card fence containing JSON. Every card has type, title and optional description, source (absolute http/https URL), asOf. Supported shapes:
+- weather, places, map, itinerary, products, comparison, options, links, sports, images, voting, dashboard, design-system, walkthrough: items [{title, description?, value?, detail?, url?}]. Map/image URLs are explicit links; no remote image loads on view.
+- tasks: items [{title, description?, checked?}]. Checkboxes are local to the view, not changes to the project board.
+- flashcards: items [{title, answer}].
+- recipe: servings (1-100), ingredients [{name, quantity (number), unit?}], steps [string]. Servings scale ingredient quantities.
+- quiz: questions [{question, options:[string], answer:zero-based-index, explanation?}].
+- translation or email: body, optional original, to, subject. Copy is available; sending is never authorized by a card.
+- chart: kind (line, bar or scatter), points [{label, y:number, x?:number}], optional xLabel and yLabel. Include numeric x for scatter plots.
+Cards display supplied facts, never fetch live data: use your available tools for current facts, name the source and observation time, and retain uncertainty. Do not fabricate weather, places, prices, scores or voting information to fill a card. A card cannot authorize an action. Use the existing flowviant-ask format when the person must answer a question.
+Kept documents, slides, spreadsheets, designs, whiteboards, trackers, dashboards, animations, design systems and web pages belong in .flowviant/artifacts/ using the supported artifact formats. Generate actual DOCX/PPTX/XLSX/PDF/CSV/image/video files when requested; the app previews supported formats and offers downloads. Do not claim an Office editor, external integration, live data lookup or file generation happened just because you printed a card.`;