@kuralle-agents/cli 0.14.0 → 0.16.0

package/dist/cli.js

@@ -4,11 +4,13 @@
  *
  *   kuralle chat [--trace] [--store <file>] [--session <id>] [--auto "msg1|msg2"] [--agent <path.ts>]
  *   kuralle send --session <id> [--store <file>] [--state|--reset] "<message>"
+ *   kuralle resume <session> [--store <file>] [--summary <text>]
  *   kuralle sim --goal "<goal>" [--turns N] [--profile "<who>"] [--agent <path.ts>]
  *   kuralle trace <session> [--last] [--json] [--web] [--port N]
  */
 import { resolveBuildRuntime } from './agentLoader.js';
 import { runChat } from './chat.js';
+import { runResume } from './resume.js';
 import { runSend } from './send.js';
 import { runSim } from './sim.js';
 import { runTrace } from './trace.js';
@@ -17,6 +19,7 @@ const HELP = `kuralle — Kuralle agent CLI
 Usage:
   kuralle chat [--trace] [--store <file>] [--session <id>] [--auto "msg1|msg2"] [--agent <path.ts>]
   kuralle send --session <id> [--store <file>] [--state|--reset] "<message>"
+  kuralle resume <session> [--store <file>] [--summary <text>]
   kuralle sim --goal "<goal>" [--turns N] [--profile "<who>"] [--agent <path.ts>]
   kuralle trace <session> [--last] [--json] [--web] [--port N]
 
@@ -27,6 +30,7 @@ Options:
   --trace             Live trace side panel — the built-in AgentTrace of each turn (chat only)
   --store <file>      Persist the session + traces to JSON files so chat survives across launches (chat only)
   --session <id>      Session id to resume with --store (default: "default")
+  --summary <text>    Resolution note appended on resume (seen by the agent post-resume)
 `;
 function flag(argv, name) {
     const i = argv.indexOf(name);
@@ -65,6 +69,9 @@ async function main() {
         case 'send':
             await runSend(subArgv, buildRuntime);
             break;
+        case 'resume':
+            await runResume(subArgv, buildRuntime);
+            break;
         case 'sim':
             await runSim(subArgv, buildRuntime);
             break;

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/resume.d.ts

@@ -0,0 +1,2 @@
+import type { BuildRuntime } from './agentRuntime.js';
+export declare function runResume(argv: string[], buildRuntime: BuildRuntime): Promise<void>;

package/dist/resume.js

@@ -0,0 +1,35 @@
+/**
+ * resume — hand a held-over session back to the bot after a human resolved an escalation.
+ *
+ * Usage: kuralle resume <session> [--store <path>] [--summary <text>]
+ *
+ * A terminal-handoff escalation parks the run (`status = 'paused'`, no `waitingFor`); every
+ * later turn is held with "a colleague is handling this" until this command runs.
+ * `runtime.resumeFromEscalation` appends the resolution note, clears the parked flow /
+ * escalation state, and marks the run runnable — the next `run()` continues with context.
+ */
+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;
+}
+export async function runResume(argv, buildRuntime) {
+    const storePath = flag(argv, '--store') ?? join(process.cwd(), 'runs/tui-sessions.json');
+    const summary = flag(argv, '--summary');
+    // Every flag whose VALUE must not be mistaken for the session id positional. Missing one
+    // here would let the value survive the filter and become the session id (see send.ts).
+    const consumesValue = new Set(['--store', '--summary']);
+    const positional = argv.filter((a, i) => !a.startsWith('--') && !(i > 0 && consumesValue.has(argv[i - 1])));
+    const sessionId = positional[0];
+    if (!sessionId) {
+        console.error('usage: kuralle resume <session> [--store <path>] [--summary <text>]');
+        process.exit(2);
+    }
+    const store = fileSessionStore(storePath);
+    const traces = fileTraceStore(storePath.replace(/\.json$/, '') + '.traces.json');
+    const demo = buildRuntime(sessionId, store, traces);
+    await demo.runtime.resumeFromEscalation(sessionId, summary !== undefined ? { resolutionSummary: summary } : undefined);
+    console.log(`resumed session "${sessionId}"${summary ? ` (${summary})` : ''}`);
+}

package/dist/send.js

@@ -2,6 +2,11 @@
  * 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';
@@ -15,9 +20,39 @@ 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);
@@ -37,14 +72,15 @@ 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') {

package/package.json

@@ -6,7 +6,7 @@
     "url": "git+https://github.com/kuralle/kuralle-agents.git",
     "directory": "packages/cli"
   },
-  "version": "0.14.0",
+  "version": "0.16.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.14.0",
-    "@kuralle-agents/trace-ui": "0.14.0"
+    "@kuralle-agents/trace-ui": "0.14.2",
+    "@kuralle-agents/core": "0.16.0"
   },
   "peerDependencies": {
+    "@kuralle-agents/core": "0.x",
     "ai": "^6.0.0",
-    "zod": "^4.0.0",
-    "@kuralle-agents/core": "0.14.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.2"
   },
   "publishConfig": {
     "access": "public"
@@ -45,6 +46,7 @@
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "clean": "rm -rf dist",
-    "test": "bun test ./test"
+    "test": "bun test ./test",
+    "typecheck:examples": "tsc --noEmit -p tsconfig.examples.json"
   }
 }