@pennyfarthing/core 10.1.0 → 10.3.0

package/packages/core/dist/workflow/tandem-lifecycle.js

@@ -0,0 +1,186 @@
+/**
+ * Tandem Backseat Agent Lifecycle for Story 95-2
+ *
+ * Manages spawn/kill lifecycle for backseat observer agents in phased workflows.
+ * When a workflow phase has a `tandem:` config block, BikeLane spawns a background
+ * subagent that observes the primary agent's work.
+ */
+import { join } from 'node:path';
+// =============================================================================
+// In-memory registries
+// =============================================================================
+/** Active backseat agents keyed by storyId */
+const activeBackseats = new Map();
+/** Cleanup handlers keyed by storyId */
+const cleanupHandlers = new Map();
+/** Counter for generating unique task IDs */
+let taskIdCounter = 0;
+/**
+ * Reset all in-memory state. For testing only.
+ */
+export function _resetForTesting() {
+    activeBackseats.clear();
+    cleanupHandlers.clear();
+    taskIdCounter = 0;
+}
+// =============================================================================
+// Implementations
+// =============================================================================
+/**
+ * Normalize scope from tandem config to a string array.
+ * Defaults to ['file-watch'] when no scope is specified.
+ */
+function normalizeScope(scope) {
+    if (scope === undefined) {
+        return ['file-watch'];
+    }
+    if (Array.isArray(scope)) {
+        return scope;
+    }
+    return [scope];
+}
+/**
+ * Spawn a backseat agent for a tandem-configured phase.
+ *
+ * If phase has no tandem config, returns success with no handle (no-op).
+ * If phase has tandem config, spawns background subagent and returns handle.
+ */
+export async function spawnBackseat(params) {
+    const { phase, storyId, sessionDir, adapter } = params;
+    // No tandem config — no-op
+    if (!phase.tandem) {
+        return { success: true };
+    }
+    const { partner, scope } = phase.tandem;
+    // Validate partner
+    if (!partner) {
+        return { success: false, error: 'Tandem partner is required and cannot be empty' };
+    }
+    const normalizedScope = normalizeScope(scope);
+    const observationFilePath = join(sessionDir, `${storyId}-tandem-${partner}.md`);
+    // Terminate existing backseat for this story if one is already running
+    const existing = activeBackseats.get(storyId);
+    if (existing) {
+        try {
+            if (adapter) {
+                await adapter.terminate(existing.taskId);
+            }
+            activeBackseats.delete(storyId);
+        }
+        catch {
+            // Swallow — old process may already be dead
+        }
+    }
+    // Spawn via adapter if provided, otherwise generate synthetic ID (test mode)
+    let taskId;
+    if (adapter) {
+        try {
+            const spawnResult = await adapter.spawn({
+                partner,
+                model: 'haiku',
+                storyId,
+                scope: normalizedScope,
+                observationFilePath,
+            });
+            taskId = spawnResult.taskId;
+        }
+        catch (err) {
+            return { success: false, error: `Failed to spawn backseat: ${err instanceof Error ? err.message : String(err)}` };
+        }
+    }
+    else {
+        taskId = `tandem-${storyId}-${partner}-${++taskIdCounter}`;
+    }
+    const handle = {
+        taskId,
+        partner,
+        model: 'haiku',
+        runInBackground: true,
+        scope: normalizedScope,
+        observationFilePath,
+        cleanupRegistered: true,
+    };
+    // Register cleanup handler at spawn time — terminates the real process
+    registerCleanupHandler({
+        storyId,
+        cleanup: async () => {
+            if (adapter) {
+                try {
+                    await adapter.terminate(handle.taskId);
+                }
+                catch {
+                    // Swallow — process may already be dead
+                }
+            }
+            activeBackseats.delete(storyId);
+        },
+    });
+    // Store in active registry
+    activeBackseats.set(storyId, handle);
+    return { success: true, data: handle };
+}
+/**
+ * Terminate a running backseat agent.
+ *
+ * Handles already-stopped tasks gracefully (no throw).
+ */
+export async function terminateBackseat(handle, adapter) {
+    // Terminate real process via adapter if provided
+    if (adapter) {
+        try {
+            await adapter.terminate(handle.taskId);
+        }
+        catch {
+            // Swallow — process may already be stopped
+        }
+    }
+    // Remove from active registry (find by taskId)
+    for (const [storyId, active] of activeBackseats) {
+        if (active.taskId === handle.taskId) {
+            activeBackseats.delete(storyId);
+            break;
+        }
+    }
+    return { success: true, data: { status: 'terminated' } };
+}
+/**
+ * Get the active backseat handle for a story, if any.
+ *
+ * Returns null if no backseat is running for this story.
+ */
+export function getActiveBackseat(storyId) {
+    return activeBackseats.get(storyId) ?? null;
+}
+/**
+ * Register a cleanup handler for tandem backseat processes.
+ *
+ * Handlers are executed on crash recovery or explicit cleanup.
+ */
+export function registerCleanupHandler(handler) {
+    const existing = cleanupHandlers.get(handler.storyId) ?? [];
+    existing.push(handler);
+    cleanupHandlers.set(handler.storyId, existing);
+}
+/**
+ * Execute all cleanup handlers for a story.
+ *
+ * Must not throw even if individual handlers fail.
+ * Clears handlers after execution (idempotent).
+ */
+export async function executeCleanupHandlers(storyId) {
+    const handlers = cleanupHandlers.get(storyId);
+    if (!handlers || handlers.length === 0) {
+        return;
+    }
+    // Clear immediately to ensure idempotency
+    cleanupHandlers.delete(storyId);
+    for (const handler of handlers) {
+        try {
+            await handler.cleanup();
+        }
+        catch {
+            // Swallow errors — primary agent must not be affected
+        }
+    }
+}
+//# sourceMappingURL=tandem-lifecycle.js.map

package/packages/core/dist/workflow/tandem-lifecycle.js.map

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

package/packages/core/dist/workflow/tandem-lifecycle.test.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Tests for Story 95-2: Backseat Agent Spawn and Lifecycle
+ *
+ * RED state tests for tandem backseat agent lifecycle in phased workflows.
+ * These tests cover all 5 acceptance criteria:
+ *
+ * AC1: BikeLane spawns backseat agent at tandem phase start
+ * AC2: BikeLane terminates backseat agent at phase end
+ * AC3: Zero orphan processes (NFR8)
+ * AC4: Primary agent continues if backseat crashes (NFR10)
+ * AC5: Backward compatible (no tandem = no change)
+ *
+ * Run with: npm test
+ */
+export {};
+//# sourceMappingURL=tandem-lifecycle.test.d.ts.map

package/packages/core/dist/workflow/tandem-lifecycle.test.d.ts.map

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