@kuralle-agents/cli 0.13.1 → 0.15.0

package/dist/chat.js

@@ -52,21 +52,21 @@ async function runTurn(demo, input, onText, onEvent) {
     try {
         for await (const part of handle.events) {
             if (part.type === 'text-delta') {
-                text += part.delta;
+                text += part.payload.delta;
                 onText(text);
             }
             else if (part.type === 'tool-call')
-                onEvent(`⚙ tool ${part.toolName}`);
+                onEvent(`⚙ tool ${part.payload.toolName}`);
             else if (part.type === 'flow-enter')
-                onEvent(`▸ enter flow ${part.flow}`);
+                onEvent(`▸ enter flow ${part.payload.flow}`);
             else if (part.type === 'flow-end')
-                onEvent(`■ end flow ${part.flow}`);
+                onEvent(`■ end flow ${part.payload.flow}`);
             else if (part.type === 'handoff')
-                onEvent(`→ handoff ${part.targetAgent}`);
+                onEvent(`→ handoff ${part.payload.targetAgent}`);
             else if (part.type === 'paused')
-                onEvent(`⏸ paused ${part.waitingFor ?? ''}`);
+                onEvent(`⏸ paused ${part.payload.waitingFor}`);
             else if (part.type === 'error')
-                onEvent(`✖ ${part.error}`);
+                onEvent(`✖ ${part.payload.error}`);
         }
         const res = await handle;
         if (!text && typeof res.text === 'string')

package/dist/fileStore.js

@@ -6,7 +6,7 @@
  */
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
-import { reviveSession } from '@kuralle-agents/core';
+import { reviveSession, StaleWriteError } from '@kuralle-agents/core';
 export function fileSessionStore(path) {
     const readAll = () => {
         if (!existsSync(path))
@@ -28,8 +28,18 @@ export function fileSessionStore(path) {
             return map[id] ? reviveSession(map[id]) : null;
         },
         async save(session) {
+            // Compare-and-swap, matching MemoryStore. The durable journal appends through
+            // `mutateSessionWithRetry`, which retries on StaleWriteError — a store that accepts
+            // a stale write silently drops the losing append instead, and the step it wrote is
+            // then missing when finalizeStep looks for it.
             const map = readAll();
-            map[session.id] = session;
+            const existing = map[session.id];
+            const expected = session.version ?? 0;
+            const stored = existing ? (existing.version ?? 0) : 0;
+            if (stored !== expected) {
+                throw new StaleWriteError(session.id, expected, stored);
+            }
+            map[session.id] = { ...session, updatedAt: new Date(), version: expected + 1 };
             writeAll(map);
         },
         async delete(id) {

package/dist/send.js

@@ -2,9 +2,15 @@
  * send — ONE turn against a PERSISTED session for adaptive multi-turn conversations.
  *
  * Flags: --session <id> · --store <file> · --state · --reset
+ *        --approve [by] · --deny [by] · --signal <name> [--payload <json>]
+ *
+ * A `needsApproval` tool suspends the run durably. Without a way to deliver the decision the
+ * CLI could enter that pause and never leave it — every later turn re-requested approval and
+ * paused again. The runtime already accepted `signalDelivery`; only the CLI could not send one.
  */
 import { join } from 'node:path';
 import { fileSessionStore } from './fileStore.js';
+import { fileTraceStore } from './fileTraceStore.js';
 function flag(argv, name) {
     const i = argv.indexOf(name);
     return i >= 0 ? argv[i + 1] : undefined;
@@ -14,13 +20,48 @@ export async function runSend(argv, buildRuntime) {
     const storePath = flag(argv, '--store') ?? join(process.cwd(), 'runs/tui-sessions.json');
     const doReset = argv.includes('--reset');
     const doState = argv.includes('--state');
-    const reserved = new Set(['--session', sessionId, '--store', storePath]);
+    const approve = argv.includes('--approve');
+    const deny = argv.includes('--deny');
+    const signalName = flag(argv, '--signal');
+    const by = flag(argv, '--approve') ?? flag(argv, '--deny') ?? 'cli';
+    const signalDelivery = approve || deny
+        ? {
+            // A fresh id per delivery: recordSignalDelivery dedupes on it, so reusing one
+            // would make a second decision a silent no-op.
+            signalId: `cli-${Date.now()}`,
+            name: '__approval',
+            payload: { approved: approve, by },
+        }
+        : signalName
+            ? {
+                signalId: `cli-${Date.now()}`,
+                name: signalName,
+                payload: JSON.parse(flag(argv, '--payload') ?? '{}'),
+            }
+            : undefined;
+    // Every flag whose VALUE must not be mistaken for message text. Missing `--model` here
+    // meant the model id survived the filter and became the first word of every user turn —
+    // a whole live run was sent to the model with "gpt-4.1-mini " prepended to each message.
+    const consumesValue = new Set([
+        '--session',
+        '--store',
+        '--model',
+        '--signal',
+        '--payload',
+        '--approve',
+        '--deny',
+    ]);
     const message = argv
-        .filter((a, i) => !a.startsWith('--') && !(i > 0 && (argv[i - 1] === '--session' || argv[i - 1] === '--store')))
+        .filter((a, i) => !a.startsWith('--') && !(i > 0 && consumesValue.has(argv[i - 1])))
         .join(' ')
         .trim();
     const store = fileSessionStore(storePath);
-    const demo = buildRuntime(sessionId, store);
+    // Traces must be file-backed too. `send` is one turn per process, so a MemoryTraceStore
+    // (what the loader defaults to whenever a session store is supplied) is discarded on
+    // exit and `kuralle trace --store` finds nothing — the exact sidecar `chat --store`
+    // writes and the CLI guide promises for both commands.
+    const traces = fileTraceStore(storePath.replace(/\.json$/, '') + '.traces.json');
+    const demo = buildRuntime(sessionId, store, traces);
     async function readState() {
         const s = await store.get(sessionId);
         const rs = s?.durableRuns?.[sessionId]?.runState;
@@ -31,32 +72,33 @@ export async function runSend(argv, buildRuntime) {
         console.log(`reset session "${sessionId}"`);
         return;
     }
-    if (doState || !message) {
+    // A decision can arrive with no message — approving is itself the turn.
+    if (doState || (!message && !signalDelivery)) {
         console.log(await readState());
         if (!message && !doState)
             console.error('(no message — pass one to take a turn, or --state to inspect)');
         return;
     }
     const events = [];
-    const handle = demo.runtime.run({ sessionId, input: message });
+    const handle = demo.runtime.run({ sessionId, input: message, ...(signalDelivery ? { signalDelivery } : {}) });
     let text = '';
     for await (const part of handle.events) {
         if (part.type === 'text-delta') {
-            text += part.delta;
-            process.stdout.write(part.delta);
+            text += part.payload.delta;
+            process.stdout.write(part.payload.delta);
         }
         else if (part.type === 'tool-call')
-            events.push(`tool:${part.toolName}`);
+            events.push(`tool:${part.payload.toolName}`);
         else if (part.type === 'flow-enter')
-            events.push(`enter:${part.flow}`);
+            events.push(`enter:${part.payload.flow}`);
         else if (part.type === 'flow-end')
-            events.push(`end:${part.flow}`);
+            events.push(`end:${part.payload.flow}`);
         else if (part.type === 'handoff')
-            events.push(`handoff:${part.targetAgent}`);
+            events.push(`handoff:${part.payload.targetAgent}`);
         else if (part.type === 'paused')
-            events.push(`paused:${part.waitingFor ?? ''}`);
+            events.push(`paused:${part.payload.waitingFor}`);
         else if (part.type === 'error')
-            events.push(`error:${part.error}`);
+            events.push(`error:${part.payload.error}`);
     }
     const res = await handle;
     if (!text && typeof res.text === 'string')

package/dist/trace.js

@@ -4,7 +4,8 @@ import { fileSessionStore } from './fileStore.js';
 import { fileTraceStore } from './fileTraceStore.js';
 export async function runTrace(argv, buildRuntime) {
     // --store <file> points at the same file `kuralle chat --store` / `kuralle send`
-    // persist to; traces live in the `<file>.traces.json` sidecar (chat's convention).
+    // persist to; traces live in a sidecar with the extension replaced —
+    // `runs/app.json` -> `runs/app.traces.json` (JSONL, one span per line).
     // Without wiring these, buildRuntime falls back to an in-memory store that is
     // always empty in a fresh process, so no persisted trace is ever found.
     const storeIdx = argv.indexOf('--store');

package/package.json

@@ -6,7 +6,7 @@
     "url": "git+https://github.com/kuralle/kuralle-agents.git",
     "directory": "packages/cli"
   },
-  "version": "0.13.1",
+  "version": "0.15.0",
   "description": "Kuralle CLI — interactive TUI chat, adaptive send, and conversation simulation",
   "type": "module",
   "bin": {
@@ -20,18 +20,19 @@
     "ink-text-input": "^6.0.0",
     "react": "^19.2.7",
     "zod": "^4.0.0",
-    "@kuralle-agents/core": "0.13.0",
-    "@kuralle-agents/trace-ui": "0.13.0"
+    "@kuralle-agents/trace-ui": "0.14.1",
+    "@kuralle-agents/core": "0.15.0"
   },
   "peerDependencies": {
+    "@kuralle-agents/core": "0.x",
     "ai": "^6.0.0",
-    "zod": "^4.0.0",
-    "@kuralle-agents/core": "0.13.0"
+    "zod": "^4.0.0"
   },
   "devDependencies": {
     "@types/node": "^20.11.0",
     "@types/react": "^19.2.17",
-    "typescript": "^5.3.0"
+    "typescript": "^5.3.0",
+    "@kuralle-agents/fs": "0.14.1"
   },
   "publishConfig": {
     "access": "public"
@@ -44,6 +45,8 @@
     "prebuild": "rm -rf dist",
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc --noEmit -p tsconfig.json",
-    "clean": "rm -rf dist"
+    "clean": "rm -rf dist",
+    "test": "bun test ./test",
+    "typecheck:examples": "tsc --noEmit -p tsconfig.examples.json"
   }
 }