@pennyfarthing/core 10.1.0 → 10.2.0

package/packages/core/dist/workflow/tool-watch.js

@@ -0,0 +1,166 @@
+/**
+ * Tool-watch Observation Scope for Story 95-5
+ *
+ * Delivers tool call information (name, params, results) from primary agent
+ * to backseat observer within one tool-use cycle. Truncates large results
+ * to configurable max size. Non-blocking to primary.
+ *
+ * Hook side: processToolCall() appends JSONL to transport file (synchronous, fast).
+ * Backseat side: startToolWatcher() polls JSONL and writes observations.
+ */
+import { appendFileSync, readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { appendObservation } from './observation-writer.js';
+// =============================================================================
+// Internal state
+// =============================================================================
+const DEFAULT_MAX_RESULT_SIZE = 500;
+const DEFAULT_POLL_MS = 1000;
+const timers = new WeakMap();
+const lastReadLines = new WeakMap();
+// =============================================================================
+// Implementations
+// =============================================================================
+/**
+ * Truncate a tool result string to maxSize characters.
+ * Appends `[truncated from N chars]` indicator when truncated.
+ */
+export function truncateResult(result, maxSize) {
+    if (result.length <= maxSize) {
+        return result;
+    }
+    return result.slice(0, maxSize) + ` [truncated from ${result.length} chars]`;
+}
+/**
+ * Record a tool call to the JSONL transport file.
+ * Called from the PostToolUse hook — must be synchronous and fast.
+ */
+export function processToolCall(params) {
+    try {
+        const { sessionDir, storyId, toolName, params: toolParams, toolResult } = params;
+        const maxResultSize = params.maxResultSize ?? DEFAULT_MAX_RESULT_SIZE;
+        if (!existsSync(sessionDir)) {
+            return { success: false, error: `Session directory does not exist: ${sessionDir}` };
+        }
+        const filePath = join(sessionDir, `${storyId}-tandem-toolcalls.jsonl`);
+        const entry = {
+            timestamp: new Date().toISOString(),
+            toolName,
+            params: toolParams,
+            resultPreview: truncateResult(toolResult, maxResultSize),
+            resultSize: toolResult.length,
+        };
+        appendFileSync(filePath, JSON.stringify(entry) + '\n', 'utf-8');
+        return { success: true };
+    }
+    catch (err) {
+        return { success: false, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+/**
+ * Read tool call entries from a JSONL transport file.
+ * Skips malformed lines gracefully.
+ */
+export function readToolCalls(filePath) {
+    try {
+        if (!existsSync(filePath)) {
+            return { success: false, error: `File not found: ${filePath}` };
+        }
+        const content = readFileSync(filePath, 'utf-8');
+        const lines = content.split('\n').filter(line => line.trim().length > 0);
+        const entries = [];
+        for (const line of lines) {
+            try {
+                const parsed = JSON.parse(line);
+                entries.push(parsed);
+            }
+            catch {
+                // Skip malformed lines
+            }
+        }
+        return { success: true, data: entries };
+    }
+    catch (err) {
+        return { success: false, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+/**
+ * Start a polling tool watcher that reads JSONL entries and writes observations.
+ */
+export async function startToolWatcher(config) {
+    try {
+        const pollIntervalMs = config.pollIntervalMs ?? DEFAULT_POLL_MS;
+        const toolCallsPath = join(config.sessionDir, `${config.storyId}-tandem-toolcalls.jsonl`);
+        const handle = {
+            running: true,
+            pollIntervalMs,
+        };
+        // Start from line 0 — process all existing and future entries
+        lastReadLines.set(handle, 0);
+        const timer = setInterval(() => {
+            if (!handle.running)
+                return;
+            try {
+                if (!existsSync(toolCallsPath))
+                    return;
+                const content = readFileSync(toolCallsPath, 'utf-8');
+                const lines = content.split('\n').filter(l => l.trim().length > 0);
+                const prevCount = lastReadLines.get(handle) ?? 0;
+                if (lines.length <= prevCount)
+                    return;
+                // Process only new lines
+                const newLines = lines.slice(prevCount);
+                lastReadLines.set(handle, lines.length);
+                if (!config.observationFilePath)
+                    return;
+                for (const line of newLines) {
+                    try {
+                        const entry = JSON.parse(line);
+                        // Build a param summary for the trigger detail
+                        const paramKeys = Object.keys(entry.params);
+                        const paramSummary = paramKeys.length > 0
+                            ? ` (${paramKeys.map(k => `${k}: ${String(entry.params[k]).slice(0, 50)}`).join(', ')})`
+                            : '';
+                        const triggerDetail = `${entry.toolName}${paramSummary}`;
+                        // Build enriched observation text (not just raw result replay)
+                        const observation = `Tool: ${entry.toolName}${paramSummary}\nResult (${entry.resultSize} chars): ${entry.resultPreview}`;
+                        appendObservation(config.observationFilePath, {
+                            triggerType: 'tool-watch',
+                            triggerDetail,
+                            observation,
+                        });
+                    }
+                    catch {
+                        // Skip malformed lines, continue polling
+                    }
+                }
+            }
+            catch {
+                // Error resilience — continue polling
+            }
+        }, pollIntervalMs);
+        timers.set(handle, timer);
+        return { success: true, data: handle };
+    }
+    catch (err) {
+        return { success: false, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+/**
+ * Stop a running tool watcher. Idempotent — safe to call multiple times.
+ */
+export async function stopToolWatcher(handle) {
+    try {
+        handle.running = false;
+        const timer = timers.get(handle);
+        if (timer) {
+            clearInterval(timer);
+            timers.delete(handle);
+        }
+        return { success: true };
+    }
+    catch (err) {
+        return { success: false, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+//# sourceMappingURL=tool-watch.js.map

package/packages/core/dist/workflow/tool-watch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-watch.js","sourceRoot":"","sources":["../../src/workflow/tool-watch.ts"],"names":[],"mappings":"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"}

package/packages/core/dist/workflow/tool-watch.test.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Tests for Story 95-5: Tool-watch Observation Scope
+ *
+ * RED state tests for tool call observation in the backseat agent.
+ * These tests cover all acceptance criteria:
+ *
+ * AC1: Backseat receives tool call data (name, params, result) from primary agent
+ * AC2: Data delivered within one tool-use cycle (processToolCall returns promptly)
+ * AC3: Large results truncated to configurable max size
+ * AC4: Truncation indicator included when results are truncated
+ * AC5: Non-blocking to primary agent (hook execution remains fast)
+ * AC6: Observations include analysis, not just raw tool call replay
+ * AC7: Context accumulates across tool calls
+ *
+ * Run with: npm test
+ */
+export {};
+//# sourceMappingURL=tool-watch.test.d.ts.map

package/packages/core/dist/workflow/tool-watch.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-watch.test.d.ts","sourceRoot":"","sources":["../../src/workflow/tool-watch.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG"}