@synergenius/flow-weaver 0.24.3 → 0.25.0

package/dist/agent/cli-session.d.ts

@@ -22,7 +22,6 @@
 import { type ChildProcess } from 'node:child_process';
 import type { StreamEvent, CliSessionOptions } from './types.js';
 export declare class CliSession {
-    private readonly options;
     readonly sessionId: `${string}-${string}-${string}-${string}-${string}`;
     private child;
     private alive;
@@ -35,8 +34,14 @@ export declare class CliSession {
     private readonly log;
     private readonly spawnFn;
     private readonly idleTimeout;
+    private readonly opts;
     constructor(options: CliSessionOptions);
     get ready(): boolean;
+    /**
+     * Check if this session was created with equivalent CLI-relevant options.
+     * Used by the session cache to detect option drift.
+     */
+    matchesOptions(other: CliSessionOptions): boolean;
     /**
      * Inject a mock child process for testing.
      * @internal — test only
@@ -49,12 +54,22 @@ export declare class CliSession {
     /**
      * Send a user message and stream back events.
      * Auto-respawns if the process has died.
+     *
+     * Phase 1.3: Concurrent send() guard — throws if a previous turn is still active.
+     * The activeTurn lock is claimed synchronously BEFORE any async work (spawn)
+     * to prevent TOCTOU races.
      */
     send(userMessage: string, systemPromptPrefix?: string): AsyncGenerator<StreamEvent>;
     /**
      * Kill the CLI process.
      */
     kill(): void;
+    /**
+     * Compute a fingerprint of CLI-relevant options for cache comparison.
+     * Field order is significant for JSON.stringify comparison.
+     * Add new CLI-relevant fields here when they're added to CliSessionOptions.
+     */
+    private static fingerprint;
     private pushEvent;
     private completeTurn;
     private markDead;
@@ -64,6 +79,8 @@ export declare class CliSession {
 }
 /**
  * Get an existing session or create a new one.
+ * Phase 1.4: Validates that cached sessions have matching CLI-relevant options.
+ * If options changed on the same key, the old session is killed and recreated.
  */
 export declare function getOrCreateCliSession(key: string, options: CliSessionOptions): CliSession;
 /**

package/dist/agent/cli-session.js

@@ -24,7 +24,6 @@ import { spawn as nodeSpawn } from 'node:child_process';
 import { StreamJsonParser } from './streaming.js';
 const DEFAULT_IDLE_TIMEOUT_MS = 10 * 60 * 1000; // 10 minutes
 export class CliSession {
-    options;
     sessionId = randomUUID();
     child = null;
     alive = false;
@@ -37,8 +36,9 @@ export class CliSession {
     log;
     spawnFn;
     idleTimeout;
+    opts;
     constructor(options) {
-        this.options = options;
+        this.opts = options;
         this.log = options.logger;
         this.spawnFn = options.spawnFn ?? ((cmd, args, opts) => nodeSpawn(cmd, args, { ...opts, stdio: opts.stdio }));
         this.idleTimeout = options.idleTimeout ?? DEFAULT_IDLE_TIMEOUT_MS;
@@ -48,6 +48,13 @@ export class CliSession {
     get ready() {
         return this.alive;
     }
+    /**
+     * Check if this session was created with equivalent CLI-relevant options.
+     * Used by the session cache to detect option drift.
+     */
+    matchesOptions(other) {
+        return CliSession.fingerprint(this.opts) === CliSession.fingerprint(other);
+    }
     /**
      * Inject a mock child process for testing.
      * @internal — test only
@@ -67,7 +74,11 @@ export class CliSession {
      * Spawn the CLI process. Must be called before send().
      */
     async spawn() {
-        const { binPath, cwd, env, model, mcpConfigPath } = this.options;
+        // Kill existing child to prevent orphaned processes from concurrent spawn
+        if (this.child && this.alive) {
+            this.child.kill('SIGTERM');
+        }
+        const { binPath, cwd, env, model, mcpConfigPath } = this.opts;
         const args = [
             '-p',
             '--input-format',
@@ -87,6 +98,21 @@ export class CliSession {
         if (mcpConfigPath) {
             args.push('--mcp-config', mcpConfigPath, '--strict-mcp-config');
         }
+        const { disallowedTools, tools, systemPrompt, appendSystemPrompt } = this.opts;
+        if (disallowedTools && disallowedTools.length > 0) {
+            args.push('--disallowed-tools', disallowedTools.join(','));
+        }
+        // Phase 1.1: --tools flag (whitelist / disable all)
+        if (tools !== undefined) {
+            args.push('--tools', tools);
+        }
+        if (systemPrompt) {
+            args.push('--system-prompt', systemPrompt);
+        }
+        // Phase 1.2: --append-system-prompt flag
+        if (appendSystemPrompt) {
+            args.push('--append-system-prompt', appendSystemPrompt);
+        }
         const spawnResult = this.spawnFn(binPath, args, { cwd, stdio: ['pipe', 'pipe', 'pipe'], env: env ?? process.env });
         const child = 'child' in spawnResult ? spawnResult.child : spawnResult;
         const cleanup = 'cleanup' in spawnResult ? spawnResult.cleanup : undefined;
@@ -115,91 +141,104 @@ export class CliSession {
     /**
      * Send a user message and stream back events.
      * Auto-respawns if the process has died.
+     *
+     * Phase 1.3: Concurrent send() guard — throws if a previous turn is still active.
+     * The activeTurn lock is claimed synchronously BEFORE any async work (spawn)
+     * to prevent TOCTOU races.
      */
     async *send(userMessage, systemPromptPrefix) {
-        if (!this.alive) {
-            this.log?.info('CLI session dead, respawning', { sessionId: this.sessionId });
-            await this.spawn();
+        // Phase 1.3: Guard against concurrent sends
+        if (this.activeTurn) {
+            throw new Error('CliSession: concurrent send() calls are not supported. Previous turn still active.');
         }
-        this.resetIdleTimer();
-        this.parser.reset();
-        const content = systemPromptPrefix ? `${systemPromptPrefix}\n\n${userMessage}` : userMessage;
-        // Write NDJSON message to stdin
-        const ndjsonMessage = JSON.stringify({
-            type: 'user',
-            message: { role: 'user', content },
-            parent_tool_use_id: null,
-        }) + '\n';
+        // Claim the turn synchronously BEFORE any await to prevent TOCTOU race
         const turn = { resolve: () => { }, events: [], done: false };
         this.activeTurn = turn;
-        // Track whether this turn saw a 'result' event (definitive turn end)
-        let sawResult = false;
-        // Wrap pushEvent to detect result-driven message_stop as turn end
-        const originalPush = this.pushEvent.bind(this);
-        this.parser = new StreamJsonParser((event) => {
-            // The result event emits message_stop — but in session mode,
-            // we need to detect it as the turn boundary
-            if (event.type === 'message_stop' && !sawResult) {
-                // This is a stream_event message_stop (API turn), not CLI turn end.
-                // Push it but don't complete the turn.
-                originalPush(event);
-                return;
+        try {
+            if (!this.alive) {
+                this.log?.info('CLI session dead, respawning', { sessionId: this.sessionId });
+                await this.spawn();
             }
-            originalPush(event);
-        });
-        // Override parser feed to detect result events for turn completion
-        const baseFeed = this.parser.feed.bind(this.parser);
-        this.parser.feed = (line) => {
-            // Check if this line is a result event before parsing
-            try {
-                let parsed = JSON.parse(line);
-                if (parsed.type === 'stream_event' && parsed.event)
-                    parsed = parsed.event;
-                if (parsed.type === 'result') {
-                    sawResult = true;
+            this.resetIdleTimer();
+            this.parser.reset();
+            const content = systemPromptPrefix ? `${systemPromptPrefix}\n\n${userMessage}` : userMessage;
+            // Write NDJSON message to stdin
+            const ndjsonMessage = JSON.stringify({
+                type: 'user',
+                message: { role: 'user', content },
+                parent_tool_use_id: null,
+            }) + '\n';
+            // Track whether this turn saw a 'result' event (definitive turn end)
+            let sawResult = false;
+            // Wrap pushEvent to detect result-driven message_stop as turn end
+            const originalPush = this.pushEvent.bind(this);
+            this.parser = new StreamJsonParser((event) => {
+                // The result event emits message_stop — but in session mode,
+                // we need to detect it as the turn boundary
+                if (event.type === 'message_stop' && !sawResult) {
+                    // This is a stream_event message_stop (API turn), not CLI turn end.
+                    // Push it but don't complete the turn.
+                    originalPush(event);
+                    return;
                 }
+                originalPush(event);
+            });
+            // Override parser feed to detect result events for turn completion
+            const baseFeed = this.parser.feed.bind(this.parser);
+            this.parser.feed = (line) => {
+                // Check if this line is a result event before parsing
+                try {
+                    let parsed = JSON.parse(line);
+                    if (parsed.type === 'stream_event' && parsed.event)
+                        parsed = parsed.event;
+                    if (parsed.type === 'result') {
+                        sawResult = true;
+                    }
+                }
+                catch {
+                    // Not JSON, let parser handle it
+                }
+                baseFeed(line);
+                if (sawResult) {
+                    this.completeTurn();
+                }
+            };
+            try {
+                this.child.stdin.write(ndjsonMessage, (err) => {
+                    if (err) {
+                        this.log?.error('stdin write error', { sessionId: this.sessionId, err });
+                        this.markDead();
+                        turn.done = true;
+                        turn.resolve();
+                    }
+                });
             }
-            catch {
-                // Not JSON, let parser handle it
-            }
-            baseFeed(line);
-            if (sawResult) {
-                this.completeTurn();
+            catch (err) {
+                this.log?.error('stdin write exception', { sessionId: this.sessionId, err });
+                this.markDead();
+                throw new Error('CLI session stdin write failed');
             }
-        };
-        try {
-            this.child.stdin.write(ndjsonMessage, (err) => {
-                if (err) {
-                    this.log?.error('stdin write error', { sessionId: this.sessionId, err });
-                    this.markDead();
-                    turn.done = true;
-                    turn.resolve();
+            // Yield events as they arrive
+            while (!turn.done || turn.events.length > 0) {
+                if (turn.events.length > 0) {
+                    yield turn.events.shift();
+                }
+                else {
+                    await new Promise((r) => {
+                        turn.resolve = r;
+                        setTimeout(r, 50);
+                    });
                 }
-            });
-        }
-        catch (err) {
-            this.log?.error('stdin write exception', { sessionId: this.sessionId, err });
-            this.markDead();
-            throw new Error('CLI session stdin write failed');
-        }
-        // Yield events as they arrive
-        while (!turn.done || turn.events.length > 0) {
-            if (turn.events.length > 0) {
-                yield turn.events.shift();
             }
-            else {
-                await new Promise((r) => {
-                    turn.resolve = r;
-                    setTimeout(r, 50);
-                });
+            // Yield any remaining events
+            while (turn.events.length > 0) {
+                yield turn.events.shift();
             }
         }
-        // Yield any remaining events
-        while (turn.events.length > 0) {
-            yield turn.events.shift();
+        finally {
+            this.activeTurn = null;
+            this.resetIdleTimer();
         }
-        this.activeTurn = null;
-        this.resetIdleTimer();
     }
     /**
      * Kill the CLI process.
@@ -209,17 +248,34 @@ export class CliSession {
         if (this.child && this.alive) {
             this.log?.info('Killing CLI session', { sessionId: this.sessionId });
             this.child.kill('SIGTERM');
-            setTimeout(() => {
+            // Phase 1.5: unref the SIGKILL fallback timer so it doesn't keep Node alive
+            const sigkillTimer = setTimeout(() => {
                 if (this.child && !this.child.killed) {
                     this.child.kill('SIGKILL');
                 }
             }, 2000);
+            sigkillTimer.unref();
         }
         this.markDead();
     }
     // ---------------------------------------------------------------------------
     // Private
     // ---------------------------------------------------------------------------
+    /**
+     * Compute a fingerprint of CLI-relevant options for cache comparison.
+     * Field order is significant for JSON.stringify comparison.
+     * Add new CLI-relevant fields here when they're added to CliSessionOptions.
+     */
+    static fingerprint(options) {
+        return JSON.stringify({
+            model: options.model,
+            mcpConfigPath: options.mcpConfigPath,
+            disallowedTools: options.disallowedTools,
+            tools: options.tools,
+            systemPrompt: options.systemPrompt,
+            appendSystemPrompt: options.appendSystemPrompt,
+        });
+    }
     pushEvent(event) {
         if (!this.activeTurn)
             return;
@@ -233,6 +289,8 @@ export class CliSession {
         this.activeTurn.resolve();
     }
     markDead() {
+        // Phase 1.5: Clear idle timer to prevent dangling timer on process crash
+        this.clearIdleTimer();
         this.alive = false;
         this.cleanupFn?.();
         this.cleanupFn = null;
@@ -258,6 +316,8 @@ export class CliSession {
             this.log?.info('CLI session idle timeout, killing', { sessionId: this.sessionId });
             this.kill();
         }, this.idleTimeout);
+        // Phase 1.5: unref so idle timer doesn't keep Node alive on shutdown
+        this.idleTimer.unref();
     }
     clearIdleTimer() {
         if (this.idleTimer) {
@@ -272,14 +332,22 @@ export class CliSession {
 const sessions = new Map();
 /**
  * Get an existing session or create a new one.
+ * Phase 1.4: Validates that cached sessions have matching CLI-relevant options.
+ * If options changed on the same key, the old session is killed and recreated.
  */
 export function getOrCreateCliSession(key, options) {
     const existing = sessions.get(key);
     if (existing && existing.ready) {
-        return existing;
+        // Phase 1.4: Check if CLI-relevant options match
+        if (existing.matchesOptions(options)) {
+            return existing;
+        }
+        // Options changed — kill old session and recreate
+        existing.kill();
+        sessions.delete(key);
     }
-    // Kill stale session if present
-    if (existing) {
+    else if (existing) {
+        // Kill stale (dead) session
         existing.kill();
         sessions.delete(key);
     }

package/dist/agent/types.d.ts

@@ -191,6 +191,21 @@ export interface CliSessionOptions {
     mcpConfigPath?: string;
     /** Disable specific built-in tools (e.g. ['Read', 'Edit', 'Write', 'Bash'] to force MCP tools). */
     disallowedTools?: string[];
+    /**
+     * Restrict built-in tools via --tools. Empty string "" disables all. Comma-separated PascalCase names.
+     * Case-sensitive — use exact names: "Read", "Bash", "Edit" (not "read", "bash").
+     * MCP tools are unaffected by this flag.
+     */
+    tools?: string;
+    /** System prompt passed to the CLI via --system-prompt. Overrides the default Claude Code prompt. */
+    systemPrompt?: string;
+    /**
+     * Appended to the active system prompt via --append-system-prompt.
+     * Keeps Claude Code's built-in guidance and adds custom instructions.
+     * WARNING: If used with systemPrompt, appends to the custom prompt (not the default).
+     * Built-in Claude Code guidance is lost when systemPrompt is set.
+     */
+    appendSystemPrompt?: string;
     /** Custom spawn function. Defaults to child_process.spawn. */
     spawnFn?: SpawnFn;
     /** Idle timeout in milliseconds. Defaults to 600000 (10 minutes). */

package/dist/cli/flow-weaver.mjs

@@ -9886,7 +9886,7 @@ var VERSION;
 var init_generated_version = __esm({
   "src/generated-version.ts"() {
     "use strict";
-    VERSION = "0.24.3";
+    VERSION = "0.25.0";
   }
 });
 
@@ -36231,9 +36231,22 @@ var init_parser2 = __esm({
         const cacheKey = `npm:${imp.importSource}`;
         if (this.importCache.has(cacheKey)) {
           const cached2 = this.importCache.get(cacheKey);
-          const found = cached2.nodeTypes.find((nt) => nt.functionName === imp.functionName);
-          if (found) {
-            return { ...found, name: imp.name, importSource: imp.importSource };
+          const resolvedDts = resolvePackageTypesPath(imp.importSource, currentDir);
+          let cacheValid = false;
+          if (resolvedDts) {
+            try {
+              const dtsStats = fs5.statSync(resolvedDts);
+              cacheValid = cached2.mtime === dtsStats.mtimeMs;
+            } catch {
+            }
+          } else {
+            cacheValid = true;
+          }
+          if (cacheValid) {
+            const found = cached2.nodeTypes.find((nt) => nt.functionName === imp.functionName);
+            if (found) {
+              return { ...found, name: imp.name, importSource: imp.importSource };
+            }
           }
         }
         const dtsPath = resolvePackageTypesPath(imp.importSource, currentDir);
@@ -95960,7 +95973,7 @@ function parseIntStrict(value) {
 // src/cli/index.ts
 init_logger();
 init_error_utils();
-var version2 = true ? "0.24.3" : "0.0.0-dev";
+var version2 = true ? "0.25.0" : "0.0.0-dev";
 var program2 = new Command();
 program2.name("fw").description("Flow Weaver Annotations - Compile and validate workflow files").option("-v, --version", "Output the current version").option("--no-color", "Disable colors").option("--color", "Force colors").on("option:version", () => {
   logger.banner(version2);

package/dist/generated-version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.24.3";
+export declare const VERSION = "0.25.0";
 //# sourceMappingURL=generated-version.d.ts.map

package/dist/generated-version.js

@@ -1,3 +1,3 @@
 // Auto-generated by scripts/generate-version.ts — do not edit manually
-export const VERSION = '0.24.3';
+export const VERSION = '0.25.0';
 //# sourceMappingURL=generated-version.js.map

package/dist/parser.js

@@ -610,14 +610,28 @@ export class AnnotationParser {
      * Resolve an npm package @fwImport to a node type by reading .d.ts declarations.
      */
     resolveNpmImportAnnotation(imp, currentDir) {
-        // Check cache
+        // Check cache (with mtime validation — same pattern as resolveNpmImports)
         const cacheKey = `npm:${imp.importSource}`;
         if (this.importCache.has(cacheKey)) {
             const cached = this.importCache.get(cacheKey);
-            const found = cached.nodeTypes.find((nt) => nt.functionName === imp.functionName);
-            if (found) {
-                // Return a copy with the correct name from @fwImport
-                return { ...found, name: imp.name, importSource: imp.importSource };
+            const resolvedDts = resolvePackageTypesPath(imp.importSource, currentDir);
+            let cacheValid = false;
+            if (resolvedDts) {
+                try {
+                    const dtsStats = fs.statSync(resolvedDts);
+                    cacheValid = cached.mtime === dtsStats.mtimeMs;
+                }
+                catch { /* file gone — re-parse */ }
+            }
+            else {
+                // No .d.ts found — trust cache (package may have been removed)
+                cacheValid = true;
+            }
+            if (cacheValid) {
+                const found = cached.nodeTypes.find((nt) => nt.functionName === imp.functionName);
+                if (found) {
+                    return { ...found, name: imp.name, importSource: imp.importSource };
+                }
             }
         }
         // Resolve .d.ts path

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synergenius/flow-weaver",
-  "version": "0.24.3",
+  "version": "0.25.0",
   "description": "Deterministic workflow compiler for AI agents. Compiles to standalone TypeScript, no runtime dependencies.",
   "private": false,
   "type": "module",