@kynetic-ai/spec 0.1.2 → 0.3.0

package/dist/ralph/index.d.ts

@@ -3,6 +3,9 @@
  *
  * Event translation and rendering for the ralph autonomous task loop.
  */
-export { type RalphEvent, type RalphEventType, type RalphEventData, type AgentMessageData, type AgentThoughtData, type ToolStartData, type ToolUpdateData, type ToolResultData, type StatusData, type RalphTranslator, createTranslator, } from './events.js';
-export { type RalphRenderer, createCliRenderer } from './cli-renderer.js';
+export { createCliRenderer, createPrefixedRenderer, type RalphRenderer, } from "./cli-renderer.js";
+export { type AgentMessageData, type AgentThoughtData, createTranslator, type RalphEvent, type RalphEventData, type RalphEventType, type RalphTranslator, type StatusData, type ToolResultData, type ToolStartData, type ToolUpdateData, } from "./events.js";
+export { buildSubagentPrompt, DEFAULT_SUBAGENT_PREFIX, DEFAULT_SUBAGENT_TIMEOUT, RALPH_PROMPT_TIMEOUT, runSubagent, type SubagentConfig, type SubagentContext, type SubagentOptions, type SubagentResult, } from "./subagent.js";
+export { createFailureNote, getTaskFailureCount, hasTaskProgress, isIterationFailure, parseFailureCount, processFailedIteration, shouldEscalate, type TaskFailureResult, } from "./loop-errors.js";
+export { buildWrapUpContext, buildWrapUpPrompt, DEFAULT_WRAPUP_TIMEOUT, type ExitReason, isWrapUpNeeded, runWrapUpAgent, WRAPUP_AGENT_PREFIX, type WrapUpContext, type WrapUpOptions, type WrapUpResult, } from "./wrap-up.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/ralph/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ralph/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EACL,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,KAAK,aAAa,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ralph/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,KAAK,aAAa,GACnB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,gBAAgB,EAChB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,cAAc,GACpB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,mBAAmB,EACnB,uBAAuB,EACvB,wBAAwB,EACxB,oBAAoB,EACpB,WAAW,EACX,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,cAAc,GACpB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,eAAe,EACf,kBAAkB,EAClB,iBAAiB,EACjB,sBAAsB,EACtB,cAAc,EACd,KAAK,iBAAiB,GACvB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,sBAAsB,EACtB,KAAK,UAAU,EACf,cAAc,EACd,cAAc,EACd,mBAAmB,EACnB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,YAAY,GAClB,MAAM,cAAc,CAAC"}

package/dist/ralph/index.js

@@ -3,8 +3,14 @@
  *
  * Event translation and rendering for the ralph autonomous task loop.
  */
-// Event types and translator
-export { createTranslator, } from './events.js';
 // CLI renderer
-export { createCliRenderer } from './cli-renderer.js';
+export { createCliRenderer, createPrefixedRenderer, } from "./cli-renderer.js";
+// Event types and translator
+export { createTranslator, } from "./events.js";
+// Subagent spawning
+export { buildSubagentPrompt, DEFAULT_SUBAGENT_PREFIX, DEFAULT_SUBAGENT_TIMEOUT, RALPH_PROMPT_TIMEOUT, runSubagent, } from "./subagent.js";
+// Loop error handling
+export { createFailureNote, getTaskFailureCount, hasTaskProgress, isIterationFailure, parseFailureCount, processFailedIteration, shouldEscalate, } from "./loop-errors.js";
+// Wrap-up agent
+export { buildWrapUpContext, buildWrapUpPrompt, DEFAULT_WRAPUP_TIMEOUT, isWrapUpNeeded, runWrapUpAgent, WRAPUP_AGENT_PREFIX, } from "./wrap-up.js";
 //# sourceMappingURL=index.js.map

package/dist/ralph/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ralph/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,6BAA6B;AAC7B,OAAO,EAWL,gBAAgB,GACjB,MAAM,aAAa,CAAC;AAErB,eAAe;AACf,OAAO,EAAsB,iBAAiB,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ralph/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,eAAe;AACf,OAAO,EACL,iBAAiB,EACjB,sBAAsB,GAEvB,MAAM,mBAAmB,CAAC;AAC3B,6BAA6B;AAC7B,OAAO,EAGL,gBAAgB,GASjB,MAAM,aAAa,CAAC;AACrB,oBAAoB;AACpB,OAAO,EACL,mBAAmB,EACnB,uBAAuB,EACvB,wBAAwB,EACxB,oBAAoB,EACpB,WAAW,GAKZ,MAAM,eAAe,CAAC;AACvB,sBAAsB;AACtB,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,eAAe,EACf,kBAAkB,EAClB,iBAAiB,EACjB,sBAAsB,EACtB,cAAc,GAEf,MAAM,kBAAkB,CAAC;AAC1B,gBAAgB;AAChB,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,sBAAsB,EAEtB,cAAc,EACd,cAAc,EACd,mBAAmB,GAIpB,MAAM,cAAc,CAAC"}

package/dist/ralph/loop-errors.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Loop mode error handling utilities.
+ *
+ * Tracks per-task failures with [LOOP-FAIL:N] prefix in notes.
+ * Escalates to automation:needs_review after 3 failures.
+ */
+import type { Task } from "../schema/task.js";
+/**
+ * Parse the failure count from a [LOOP-FAIL:N] prefixed note.
+ * Returns 0 if no match found.
+ *
+ * AC: @loop-mode-error-handling ac-4
+ */
+export declare function parseFailureCount(noteContent: string): number;
+/**
+ * Get the current failure count for a task by examining its notes.
+ * Returns the highest failure count found, or 0 if no failures recorded.
+ *
+ * AC: @loop-mode-error-handling ac-4
+ */
+export declare function getTaskFailureCount(task: Task): number;
+/**
+ * Create a failure note with [LOOP-FAIL:N] prefix.
+ * Increments N based on prior failure count.
+ *
+ * AC: @loop-mode-error-handling ac-1, ac-3, ac-4
+ */
+export declare function createFailureNote(taskRef: string, errorDescription: string, priorFailureCount: number): string;
+/**
+ * Check if failure count has reached the escalation threshold.
+ * Threshold is 3 failures.
+ *
+ * AC: @loop-mode-error-handling ac-5
+ */
+export declare function shouldEscalate(failureCount: number): boolean;
+/**
+ * Determine if an iteration result represents a failure.
+ *
+ * Failures include:
+ * - Tests fail
+ * - PR blocked
+ * - Exception thrown
+ * - Agent reports cannot complete
+ *
+ * AC: @loop-mode-error-handling ac-7
+ */
+export declare function isIterationFailure(result: {
+    succeeded?: boolean;
+    error?: Error;
+    stopReason?: string;
+}): boolean;
+/**
+ * Check if an in_progress task has made progress in this iteration.
+ * Progress is indicated by new notes added after the startTime.
+ *
+ * AC: @loop-mode-error-handling ac-8
+ */
+export declare function hasTaskProgress(task: Task, iterationStartTime: Date): boolean;
+/**
+ * Result of processing a failed iteration for a task.
+ */
+export interface TaskFailureResult {
+    taskRef: string;
+    failureCount: number;
+    escalated: boolean;
+    noteAdded: boolean;
+}
+/**
+ * Process failed iteration for tasks that were in progress.
+ * Adds LOOP-FAIL notes for tasks without progress and escalates at threshold.
+ *
+ * This function should be called after an iteration fails to track per-task failures.
+ *
+ * AC: @loop-mode-error-handling ac-1, ac-2, ac-3, ac-4, ac-5, ac-8
+ *
+ * @param tasksInProgress - Tasks that were in_progress at iteration start
+ * @param currentTasks - Current state of all tasks (after iteration)
+ * @param iterationStartTime - When the iteration started
+ * @param errorDescription - Description of what went wrong
+ * @returns Array of results for each processed task
+ */
+export declare function processFailedIteration(tasksInProgress: Task[], currentTasks: Task[], iterationStartTime: Date, errorDescription: string): TaskFailureResult[];
+//# sourceMappingURL=loop-errors.d.ts.map

package/dist/ralph/loop-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop-errors.d.ts","sourceRoot":"","sources":["../../src/ralph/loop-errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAE9C;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAG7D;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CActD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,gBAAgB,EAAE,MAAM,EACxB,iBAAiB,EAAE,MAAM,GACxB,MAAM,CAGR;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAE5D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE;IACzC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GAAG,OAAO,CAiBV;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,IAAI,EACV,kBAAkB,EAAE,IAAI,GACvB,OAAO,CAiBT;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CACpC,eAAe,EAAE,IAAI,EAAE,EACvB,YAAY,EAAE,IAAI,EAAE,EACpB,kBAAkB,EAAE,IAAI,EACxB,gBAAgB,EAAE,MAAM,GACvB,iBAAiB,EAAE,CAuCrB"}

package/dist/ralph/loop-errors.js

@@ -0,0 +1,150 @@
+/**
+ * Loop mode error handling utilities.
+ *
+ * Tracks per-task failures with [LOOP-FAIL:N] prefix in notes.
+ * Escalates to automation:needs_review after 3 failures.
+ */
+/**
+ * Parse the failure count from a [LOOP-FAIL:N] prefixed note.
+ * Returns 0 if no match found.
+ *
+ * AC: @loop-mode-error-handling ac-4
+ */
+export function parseFailureCount(noteContent) {
+    const match = noteContent.match(/^\[LOOP-FAIL:(\d+)\]/);
+    return match ? Number.parseInt(match[1], 10) : 0;
+}
+/**
+ * Get the current failure count for a task by examining its notes.
+ * Returns the highest failure count found, or 0 if no failures recorded.
+ *
+ * AC: @loop-mode-error-handling ac-4
+ */
+export function getTaskFailureCount(task) {
+    if (!task.notes || task.notes.length === 0) {
+        return 0;
+    }
+    let maxCount = 0;
+    for (const note of task.notes) {
+        const count = parseFailureCount(note.content);
+        if (count > maxCount) {
+            maxCount = count;
+        }
+    }
+    return maxCount;
+}
+/**
+ * Create a failure note with [LOOP-FAIL:N] prefix.
+ * Increments N based on prior failure count.
+ *
+ * AC: @loop-mode-error-handling ac-1, ac-3, ac-4
+ */
+export function createFailureNote(taskRef, errorDescription, priorFailureCount) {
+    const newCount = priorFailureCount + 1;
+    return `[LOOP-FAIL:${newCount}] Task ${taskRef} failed: ${errorDescription}`;
+}
+/**
+ * Check if failure count has reached the escalation threshold.
+ * Threshold is 3 failures.
+ *
+ * AC: @loop-mode-error-handling ac-5
+ */
+export function shouldEscalate(failureCount) {
+    return failureCount >= 3;
+}
+/**
+ * Determine if an iteration result represents a failure.
+ *
+ * Failures include:
+ * - Tests fail
+ * - PR blocked
+ * - Exception thrown
+ * - Agent reports cannot complete
+ *
+ * AC: @loop-mode-error-handling ac-7
+ */
+export function isIterationFailure(result) {
+    // Explicit success flag
+    if (result.succeeded === false) {
+        return true;
+    }
+    // Error was thrown
+    if (result.error) {
+        return true;
+    }
+    // Agent cancelled (stopped working)
+    if (result.stopReason === "cancelled") {
+        return true;
+    }
+    return false;
+}
+/**
+ * Check if an in_progress task has made progress in this iteration.
+ * Progress is indicated by new notes added after the startTime.
+ *
+ * AC: @loop-mode-error-handling ac-8
+ */
+export function hasTaskProgress(task, iterationStartTime) {
+    if (!task.notes || task.notes.length === 0) {
+        return false;
+    }
+    // Check if any notes were created after iteration start
+    for (const note of task.notes) {
+        const noteTime = new Date(note.created_at);
+        if (noteTime > iterationStartTime) {
+            // Exclude LOOP-FAIL notes from progress check
+            if (!note.content.startsWith("[LOOP-FAIL:")) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Process failed iteration for tasks that were in progress.
+ * Adds LOOP-FAIL notes for tasks without progress and escalates at threshold.
+ *
+ * This function should be called after an iteration fails to track per-task failures.
+ *
+ * AC: @loop-mode-error-handling ac-1, ac-2, ac-3, ac-4, ac-5, ac-8
+ *
+ * @param tasksInProgress - Tasks that were in_progress at iteration start
+ * @param currentTasks - Current state of all tasks (after iteration)
+ * @param iterationStartTime - When the iteration started
+ * @param errorDescription - Description of what went wrong
+ * @returns Array of results for each processed task
+ */
+export function processFailedIteration(tasksInProgress, currentTasks, iterationStartTime, errorDescription) {
+    const results = [];
+    // Create a map of current task state for quick lookup
+    const currentTaskMap = new Map();
+    for (const task of currentTasks) {
+        currentTaskMap.set(task._ulid, task);
+    }
+    // Process each task that was in progress
+    for (const originalTask of tasksInProgress) {
+        const currentTask = currentTaskMap.get(originalTask._ulid);
+        // Skip if task no longer exists or is no longer in_progress
+        // (it may have been completed/cancelled/submitted during the iteration)
+        if (!currentTask || currentTask.status !== "in_progress") {
+            continue;
+        }
+        // Check if task made progress
+        const madeProgress = hasTaskProgress(currentTask, iterationStartTime);
+        // AC: @loop-mode-error-handling ac-8
+        // If task is still in_progress but made no progress, count as implicit failure
+        if (!madeProgress) {
+            const priorCount = getTaskFailureCount(currentTask);
+            const newCount = priorCount + 1;
+            const escalate = shouldEscalate(newCount);
+            results.push({
+                taskRef: currentTask._ulid,
+                failureCount: newCount,
+                escalated: escalate,
+                noteAdded: true, // Note will be added by caller
+            });
+        }
+    }
+    return results;
+}
+//# sourceMappingURL=loop-errors.js.map

package/dist/ralph/loop-errors.js.map

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

package/dist/ralph/subagent.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Ralph Subagent Module
+ *
+ * Handles spawning and running subagents for dedicated tasks like PR review.
+ * Subagents run sequentially - ralph waits for completion before continuing.
+ */
+import type { AgentAdapter } from "../agents/adapters.js";
+import { type SpawnedAgent } from "../agents/spawner.js";
+/**
+ * Context provided to a subagent for its task.
+ * AC: @ralph-subagent-spawning ac-10
+ */
+export interface SubagentContext {
+    /** Task reference (e.g., @task-slug) */
+    taskRef: string;
+    /** Full task details from kspec task get */
+    taskDetails: Record<string, unknown>;
+    /** Linked spec with acceptance criteria, if spec_ref exists */
+    specWithACs: Record<string, unknown> | null;
+    /** Current git branch */
+    gitBranch: string;
+}
+/**
+ * Configuration for subagent execution.
+ */
+export interface SubagentConfig {
+    /** Timeout in milliseconds (default: 20 minutes) */
+    timeout: number;
+    /** Output prefix for distinguishing subagent output */
+    outputPrefix: string;
+}
+/**
+ * Result of running a subagent.
+ */
+export interface SubagentResult {
+    /** Whether the subagent completed successfully */
+    success: boolean;
+    /** Whether the subagent timed out */
+    timedOut: boolean;
+    /** Error message if failed */
+    error?: string;
+}
+/**
+ * Options for running a subagent.
+ */
+export interface SubagentOptions {
+    /** Whether to auto-approve tool requests */
+    yolo: boolean;
+    /** Working directory */
+    cwd: string;
+    /** Tool request handler */
+    handleRequest: (client: SpawnedAgent["client"], reqId: string | number, method: string, params: unknown) => Promise<void>;
+}
+/** Default subagent timeout: 20 minutes */
+export declare const DEFAULT_SUBAGENT_TIMEOUT: number;
+/** Default output prefix for subagent */
+export declare const DEFAULT_SUBAGENT_PREFIX = "[REVIEW SUBAGENT]";
+/**
+ * Default ACP prompt timeout for ralph agents: 30 minutes.
+ * The framing layer default (5 min) is too aggressive — API slowness,
+ * extended thinking, and large context processing can exceed it even
+ * with the keepalive mechanism (which resets on tool calls/notifications).
+ */
+export declare const RALPH_PROMPT_TIMEOUT: number;
+/**
+ * Build the prompt for a PR review subagent.
+ * AC: @ralph-subagent-spawning ac-2, ac-10, ac-12
+ */
+export declare function buildSubagentPrompt(context: SubagentContext): string;
+/**
+ * Run a subagent for a dedicated task.
+ *
+ * AC: @ralph-subagent-spawning ac-1 (spawn), ac-3 (sequential), ac-4 (output),
+ *     ac-9 (timeout), ac-11 (prefix)
+ *
+ * @param adapter - Agent adapter to use for spawning
+ * @param context - Task context for the subagent
+ * @param config - Subagent configuration (timeout, prefix)
+ * @param options - Runtime options (cwd, request handler)
+ * @returns Result indicating success/failure/timeout
+ */
+export declare function runSubagent(adapter: AgentAdapter, context: SubagentContext, config: SubagentConfig, options: SubagentOptions): Promise<SubagentResult>;
+//# sourceMappingURL=subagent.d.ts.map

package/dist/ralph/subagent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent.d.ts","sourceRoot":"","sources":["../../src/ralph/subagent.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAS7E;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,wCAAwC;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,+DAA+D;IAC/D,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC5C,yBAAyB;IACzB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,kDAAkD;IAClD,OAAO,EAAE,OAAO,CAAC;IACjB,qCAAqC;IACrC,QAAQ,EAAE,OAAO,CAAC;IAClB,8BAA8B;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,4CAA4C;IAC5C,IAAI,EAAE,OAAO,CAAC;IACd,wBAAwB;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,2BAA2B;IAC3B,aAAa,EAAE,CACb,MAAM,EAAE,YAAY,CAAC,QAAQ,CAAC,EAC9B,KAAK,EAAE,MAAM,GAAG,MAAM,EACtB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,OAAO,KACZ,OAAO,CAAC,IAAI,CAAC,CAAC;CACpB;AAMD,2CAA2C;AAC3C,eAAO,MAAM,wBAAwB,QAAiB,CAAC;AAEvD,yCAAyC;AACzC,eAAO,MAAM,uBAAuB,sBAAsB,CAAC;AAE3D;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,QAAiB,CAAC;AAMnD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,CA2DpE;AAMD;;;;;;;;;;;GAWG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,YAAY,EACrB,OAAO,EAAE,eAAe,EACxB,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,cAAc,CAAC,CAmFzB"}

package/dist/ralph/subagent.js

@@ -0,0 +1,174 @@
+/**
+ * Ralph Subagent Module
+ *
+ * Handles spawning and running subagents for dedicated tasks like PR review.
+ * Subagents run sequentially - ralph waits for completion before continuing.
+ */
+import { spawnAndInitialize } from "../agents/spawner.js";
+import { createTranslator } from "./events.js";
+import { createPrefixedRenderer } from "./cli-renderer.js";
+// ============================================================================
+// Default Configuration
+// ============================================================================
+/** Default subagent timeout: 20 minutes */
+export const DEFAULT_SUBAGENT_TIMEOUT = 20 * 60 * 1000;
+/** Default output prefix for subagent */
+export const DEFAULT_SUBAGENT_PREFIX = "[REVIEW SUBAGENT]";
+/**
+ * Default ACP prompt timeout for ralph agents: 30 minutes.
+ * The framing layer default (5 min) is too aggressive — API slowness,
+ * extended thinking, and large context processing can exceed it even
+ * with the keepalive mechanism (which resets on tool calls/notifications).
+ */
+export const RALPH_PROMPT_TIMEOUT = 30 * 60 * 1000;
+// ============================================================================
+// Prompt Builder
+// ============================================================================
+/**
+ * Build the prompt for a PR review subagent.
+ * AC: @ralph-subagent-spawning ac-2, ac-10, ac-12
+ */
+export function buildSubagentPrompt(context) {
+    const specSection = context.specWithACs
+        ? `
+## Linked Spec with Acceptance Criteria
+
+\`\`\`json
+${JSON.stringify(context.specWithACs, null, 2)}
+\`\`\`
+
+**Verify all ACs have test coverage before merging.**
+`
+        : "";
+    return `# PR Review Subagent
+
+You are a subagent spawned by ralph to REVIEW a PR and merge it only if clean.
+
+## Role Boundary
+
+You are a REVIEWER, not a fixer. Your responsibilities:
+- Review code quality, AC coverage (own + trait), spec alignment
+- Post findings as inline PR comments with severity (MUST-FIX:, SHOULD-FIX:, SUGGESTION:)
+- Merge the PR ONLY if all quality gates pass (no MUST-FIX or SHOULD-FIX items)
+- Complete the task after merge
+
+You MUST NOT:
+- Fix code issues yourself
+- Push commits to the PR branch
+- Add or modify tests
+- Make any code changes
+
+If you find issues:
+1. Post them as inline PR comments with severity prefix
+2. Transition the task to needs_work: \`kspec task needs-work ${context.taskRef} --reason "findings..."\`
+3. Exit — the worker agent will fix issues in the next iteration
+
+## Context
+
+- **Task:** \`${context.taskRef}\`
+- **Branch:** \`${context.gitBranch}\`
+
+### Task Details
+
+\`\`\`json
+${JSON.stringify(context.taskDetails, null, 2)}
+\`\`\`
+${specSection}
+## Instructions
+
+Run the PR review skill:
+
+\`\`\`
+/pr-review ${context.taskRef}
+\`\`\`
+
+The skill defines all review steps, quality gates, and merge criteria. Follow it completely.
+
+Do NOT start new work. Do NOT fix code. Your only job is reviewing this task's PR, posting findings, and merging if clean.
+`;
+}
+// ============================================================================
+// Subagent Runner
+// ============================================================================
+/**
+ * Run a subagent for a dedicated task.
+ *
+ * AC: @ralph-subagent-spawning ac-1 (spawn), ac-3 (sequential), ac-4 (output),
+ *     ac-9 (timeout), ac-11 (prefix)
+ *
+ * @param adapter - Agent adapter to use for spawning
+ * @param context - Task context for the subagent
+ * @param config - Subagent configuration (timeout, prefix)
+ * @param options - Runtime options (cwd, request handler)
+ * @returns Result indicating success/failure/timeout
+ */
+export async function runSubagent(adapter, context, config, options) {
+    const prompt = buildSubagentPrompt(context);
+    let agent = null;
+    try {
+        // AC: @ralph-subagent-spawning ac-1 - Spawn new ACP process
+        agent = await spawnAndInitialize(adapter, {
+            cwd: options.cwd,
+            clientOptions: {
+                clientInfo: {
+                    name: "kspec-ralph-subagent",
+                    version: "1.0.0",
+                },
+                methodTimeouts: {
+                    "session/prompt": RALPH_PROMPT_TIMEOUT,
+                    "session/resume": RALPH_PROMPT_TIMEOUT,
+                },
+            },
+        });
+        // AC: @ralph-subagent-spawning ac-4, ac-11 - Prefixed renderer for output
+        const translator = createTranslator();
+        const renderer = createPrefixedRenderer(config.outputPrefix);
+        // Set up streaming update handler
+        agent.client.on("update", (_sid, update) => {
+            const event = translator.translate(update);
+            if (event) {
+                renderer.render(event);
+            }
+        });
+        // Set up tool request handler
+        agent.client.on("request", (reqId, method, params) => {
+            options
+                .handleRequest(agent.client, reqId, method, params)
+                .catch((err) => {
+                agent.client.respondError(reqId, -32000, err.message);
+            });
+        });
+        // Create ACP session
+        const acpSessionId = await agent.client.newSession({
+            cwd: options.cwd,
+            mcpServers: [],
+        });
+        // AC: @ralph-subagent-spawning ac-9 - Timeout handling
+        const timeoutPromise = new Promise((_, reject) => {
+            setTimeout(() => reject(new Error("SUBAGENT_TIMEOUT")), config.timeout);
+        });
+        // AC: @ralph-subagent-spawning ac-3 - Ralph waits for completion
+        const promptPromise = agent.client.prompt({
+            sessionId: acpSessionId,
+            prompt: [{ type: "text", text: prompt }],
+        });
+        // Race between completion and timeout
+        await Promise.race([promptPromise, timeoutPromise]);
+        return { success: true, timedOut: false };
+    }
+    catch (err) {
+        const error = err;
+        // AC: @ralph-subagent-spawning ac-9 - Timeout detection
+        if (error.message === "SUBAGENT_TIMEOUT") {
+            return { success: false, timedOut: true };
+        }
+        return { success: false, timedOut: false, error: error.message };
+    }
+    finally {
+        // Always clean up the agent process
+        if (agent) {
+            agent.kill();
+        }
+    }
+}
+//# sourceMappingURL=subagent.js.map

package/dist/ralph/subagent.js.map

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