xcoder-dna 0.0.0-stage → 1.3.0

package/dist/agents/duplicate-detector.js

@@ -0,0 +1,65 @@
+/**
+ * Built directly from real evidence, not speculation: a production run's
+ * `code` subtask re-read the same design document 11 times across its
+ * attempts (multiple times WITHIN a single attempt, not just once per
+ * fresh retry) and repeatedly re-checked for files it hadn't created yet,
+ * leaving almost none of its 25-iteration budget for actual file writing.
+ * That pattern — the exact same (thought, action) pair recurring — is
+ * cheap to detect and, left unflagged, silently burns the entire
+ * iteration budget on zero net progress.
+ *
+ * Scope: per SubAgent.run() call (one attempt), not persisted across
+ * healing retries — a fresh attempt gets a fresh detector, since a brand
+ * new transcript legitimately has no memory of the previous attempt's
+ * actions anyway (that's `sdlc-orchestrator.ts`'s file-carryover
+ * healing hint's job, not this one's).
+ */
+/** Recursively sorts object keys before stringifying, so two structurally-identical inputs compare equal regardless of key order the model happened to emit them in. */
+function stableStringify(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(",")}]`;
+    const keys = Object.keys(value).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(value[k])}`).join(",")}}`;
+}
+function normalizeThought(thought) {
+    return thought.trim().toLowerCase().replace(/\s+/g, " ");
+}
+export function actionKey(tool, input) {
+    return `${tool}::${stableStringify(input)}`;
+}
+export class DuplicateActionDetector {
+    abortAfterTotalDuplicates;
+    seen = new Map(); // "thought|||tool::input" -> iteration numbers where it occurred
+    totalDuplicates = 0;
+    /**
+     * @param abortAfterTotalDuplicates total duplicate incidents (not
+     *   necessarily of the same action — any repeats, summed) across the
+     *   whole attempt before it's treated as a stuck loop. 5 is deliberately
+     *   generous: a couple of legitimate re-checks shouldn't trip this, but
+     *   the 11-repeat pattern that motivated this class would trip it early
+     *   instead of running to the full 25-iteration cap.
+     */
+    constructor(abortAfterTotalDuplicates = 5) {
+        this.abortAfterTotalDuplicates = abortAfterTotalDuplicates;
+    }
+    check(thought, tool, input, iteration) {
+        const key = `${normalizeThought(thought)}|||${actionKey(tool, input)}`;
+        const prior = this.seen.get(key) ?? [];
+        const isDuplicate = prior.length > 0;
+        if (isDuplicate)
+            this.totalDuplicates++;
+        this.seen.set(key, [...prior, iteration]);
+        const stuck = this.totalDuplicates >= this.abortAfterTotalDuplicates;
+        const warning = isDuplicate
+            ? `duplicate detected: this exact reasoning + action ("${tool}") was already tried at iteration ${prior.at(-1)}` +
+                `${prior.length > 1 ? ` (and ${prior.length - 1} time(s) before that)` : ""} — it produced no new information ` +
+                `last time. Try a genuinely different approach instead of repeating it.`
+            : null;
+        return { isDuplicate, priorIterations: prior, stuck, warning };
+    }
+    get duplicateCount() {
+        return this.totalDuplicates;
+    }
+}

package/dist/agents/genesis-agent.d.ts

@@ -0,0 +1,61 @@
+import { EventEmitter } from 'events';
+export interface GenesisOrchestratorOptions {
+    /** One or more skill labels injected into the system prompt. */
+    skills?: string[];
+    /** Agent identity string — used as `agentName` in the prompt. */
+    agentName?: string;
+    /** The high-level directive / role description block. */
+    directive?: string;
+    /** LLM client configuration (unchanged semantics). */
+    llmOptions?: {
+        model?: string;
+        maxTokens?: number;
+    };
+    /** If true, enable record_lesson tool and inject .xcoder/lesson.md context. */
+    lessonLearned?: boolean;
+    /** Pre-loaded lesson content (avoids re-reading .xcoder/lesson.md). */
+    lessonContext?: string;
+}
+export type OrchestratorState = 'IDLE' | 'THINKING' | 'EXECUTING_TOOL' | 'PAUSED' | 'COMPLETED' | 'FAILED';
+export declare class GenesisReActOrchestrator extends EventEmitter {
+    private llm;
+    private opts;
+    private state;
+    private transcript;
+    private workspaceRoot;
+    private currentAbortController;
+    private interruptPending;
+    private cachedSystemPrompt?;
+    constructor(opts?: GenesisOrchestratorOptions);
+    getState(): OrchestratorState;
+    /**
+     * Triggers a non-blocking interrupt request. Aborts running operations immediately.
+     */
+    triggerInterrupt(): void;
+    /**
+     * Injects manual user steering into the transcript and resumes execution.
+     */
+    injectUserInput(userInput: string): void;
+    /**
+     * Builds the system prompt once, on first run call. Uses shared
+     * infrastructure: workspace index, project detection, environment info,
+     * tool manifest, and optionally external skills.
+     */
+    private buildSystemPrompt;
+    /**
+     * Runs the ReAct Orchestration Loop
+     */
+    run(initialTask: string): Promise<string>;
+    private performReasoningStep;
+    private handleInterruptPause;
+    private setState;
+}
+export declare class XcoderCLIController {
+    private orchestrator;
+    constructor(orchestrator: GenesisReActOrchestrator);
+    private setupEvents;
+    private setupKeypressHandler;
+    private disableRawMode;
+    private promptForInput;
+    start(task: string): Promise<void>;
+}

package/dist/agents/genesis-agent.js

@@ -0,0 +1,340 @@
+// xcoder:version 2 | xcoder:task task-c49600 | xcoder:updated 2026-08-13T13:52:23.536Z | xcoder:subtask code-st-6d79ef
+import * as readline from 'readline';
+import { EventEmitter } from 'events';
+import { createLlmClient } from "../llm/factory.js";
+import { buildAgentSystemPrompt, parseReactMessage } from "../protocol/react-contract.js";
+import { buildToolManifest, dispatchTool } from "../tools/tool-registry.js";
+import { getOrBuildIndex } from "../tools/workspace-index.js";
+import { detectProjectCommands } from "../tools/project-detect.js";
+import { getEnvironmentInfo } from "../util/env-info.js";
+import { isExternalSkillsEnabled, getExternalSkills } from "../skills/externalSkillLoader.js";
+import { confirmInterrupt } from "../util/confirm-interrupt.js";
+import { FooterManager } from "../util/footer-manager.js";
+// ============================================================================
+// ReAct Orchestrator Engine using LlmClient
+// ============================================================================
+export class GenesisReActOrchestrator extends EventEmitter {
+    llm;
+    opts;
+    state = 'IDLE';
+    transcript = [];
+    workspaceRoot;
+    currentAbortController = null;
+    interruptPending = false;
+    cachedSystemPrompt;
+    constructor(opts = {}) {
+        super();
+        this.opts = {
+            skills: [],
+            agentName: 'repl-agent',
+            directive: '',
+            lessonLearned: false,
+            ...opts,
+            llmOptions: opts.llmOptions ?? {},
+        };
+        this.llm = createLlmClient("orchestrator", this.opts.llmOptions);
+        this.workspaceRoot = process.cwd();
+    }
+    getState() {
+        return this.state;
+    }
+    /**
+     * Triggers a non-blocking interrupt request. Aborts running operations immediately.
+     */
+    triggerInterrupt() {
+        if (this.state === 'IDLE' || this.state === 'COMPLETED' || this.state === 'PAUSED') {
+            return;
+        }
+        this.interruptPending = true;
+        this.emit('interrupt:requested');
+        if (this.currentAbortController) {
+            this.currentAbortController.abort();
+        }
+    }
+    /**
+     * Injects manual user steering into the transcript and resumes execution.
+     */
+    injectUserInput(userInput) {
+        this.transcript.push({
+            role: 'user',
+            content: `[USER MANUAL INTERRUPT]: The user paused execution and provided this guidance: "${userInput}". Adjust your strategy accordingly.`,
+        });
+        this.interruptPending = false;
+        this.emit('input:injected', userInput);
+    }
+    /**
+     * Builds the system prompt once, on first run call. Uses shared
+     * infrastructure: workspace index, project detection, environment info,
+     * tool manifest, and optionally external skills.
+     */
+    async buildSystemPrompt() {
+        if (this.cachedSystemPrompt)
+            return this.cachedSystemPrompt;
+        const index = await getOrBuildIndex(this.workspaceRoot);
+        const detectedCommands = await detectProjectCommands(this.workspaceRoot, index);
+        const environment = getEnvironmentInfo();
+        let skills = this.opts.skills ?? [];
+        if (isExternalSkillsEnabled()) {
+            skills = [...skills, ...getExternalSkills()];
+        }
+        this.cachedSystemPrompt = buildAgentSystemPrompt({
+            agentName: this.opts.agentName ?? 'repl-agent',
+            roleDescription: this.opts.directive ?? '',
+            directive: this.opts.directive ?? '',
+            skills,
+            tools: buildToolManifest({ lessonLearned: this.opts.lessonLearned ?? false }),
+            environment,
+            detectedCommands,
+            goal: '(ad-hoc interactive task)',
+            lessonContext: this.opts.lessonContext,
+            isStandalone: true,
+        });
+        return this.cachedSystemPrompt;
+    }
+    /**
+     * Runs the ReAct Orchestration Loop
+     */
+    async run(initialTask) {
+        // Build system prompt before entering the loop.
+        try {
+            await this.buildSystemPrompt();
+        }
+        catch (err) {
+            this.setState('FAILED');
+            throw new Error(`Failed to build system prompt: ${err.message}`);
+        }
+        this.transcript.push({ role: 'user', content: initialTask });
+        while (this.state !== 'COMPLETED' && this.state !== 'FAILED') {
+            // 1. Check for manual interrupt
+            if (this.interruptPending) {
+                await this.handleInterruptPause();
+            }
+            // 2. THINKING PHASE (LLM Completion Call)
+            this.setState('THINKING');
+            this.currentAbortController = new AbortController();
+            let step;
+            try {
+                step = await this.performReasoningStep(this.currentAbortController.signal);
+            }
+            catch (err) {
+                if (err.name === 'AbortError' || this.interruptPending) {
+                    await this.handleInterruptPause();
+                    continue;
+                }
+                this.setState('FAILED');
+                throw err;
+            }
+            finally {
+                this.currentAbortController = null;
+            }
+            this.emit('thought', step.thought);
+            if (step.final_answer) {
+                this.setState('COMPLETED');
+                this.transcript.push({ role: 'assistant', content: step.final_answer.summary });
+                return step.final_answer.summary;
+            }
+            // 3. EXECUTING TOOL PHASE
+            if (step.action) {
+                const toolName = step.action.tool;
+                const toolInput = step.action.input;
+                // Append Assistant's intended action to transcript
+                this.transcript.push({
+                    role: 'assistant',
+                    content: `Thought: ${step.thought}\nAction: ${JSON.stringify(step.action)}`,
+                });
+                this.setState('EXECUTING_TOOL');
+                this.emit('action:start', step.action);
+                this.currentAbortController = new AbortController();
+                let observation;
+                try {
+                    const result = await Promise.race([
+                        dispatchTool(this.workspaceRoot, toolName, toolInput),
+                        new Promise((_, reject) => {
+                            this.currentAbortController.signal.addEventListener('abort', () => {
+                                reject(new DOMException('Tool execution cancelled by user.', 'AbortError'));
+                            });
+                        }),
+                    ]);
+                    observation = result.ok
+                        ? JSON.stringify(result.output)
+                        : `Tool Error: ${typeof result.output === 'object' ? result.output?.error ?? 'unknown' : result.output}`;
+                }
+                catch (err) {
+                    if (err.name === 'AbortError' || this.interruptPending) {
+                        await this.handleInterruptPause();
+                        continue;
+                    }
+                    observation = `Tool Error: ${err.message}`;
+                }
+                finally {
+                    this.currentAbortController = null;
+                }
+                this.emit('action:end', toolName, observation);
+                // Append tool result as observation for the LLM's next turn
+                this.transcript.push({
+                    role: 'user',
+                    content: `Observation: ${observation}`,
+                });
+            }
+        }
+        throw new Error('ReAct orchestration loop terminated unexpectedly.');
+    }
+    async performReasoningStep(signal) {
+        const completionPromise = this.llm.complete(this.cachedSystemPrompt, this.transcript);
+        const completion = await Promise.race([
+            completionPromise,
+            new Promise((_, reject) => {
+                signal.addEventListener('abort', () => {
+                    reject(new DOMException('LLM completion aborted by user interrupt.', 'AbortError'));
+                });
+            }),
+        ]);
+        const parsed = parseReactMessage(completion.text);
+        if (!parsed.ok) {
+            this.transcript.push({
+                role: 'user',
+                content: `protocol_error: ${parsed.error}`,
+            });
+            return { thought: parsed.error, action: null, final_answer: null };
+        }
+        return parsed.message;
+    }
+    async handleInterruptPause() {
+        this.setState('PAUSED');
+        this.emit('paused');
+        await new Promise((resolve) => {
+            const onInjected = () => {
+                this.removeListener('input:injected', onInjected);
+                resolve();
+            };
+            this.on('input:injected', onInjected);
+        });
+    }
+    setState(newState) {
+        this.state = newState;
+        this.emit('state:change', newState);
+    }
+}
+// ============================================================================
+// Interactive CLI Controller
+// ============================================================================
+export class XcoderCLIController {
+    orchestrator;
+    constructor(orchestrator) {
+        this.orchestrator = orchestrator;
+        this.setupEvents();
+    }
+    setupEvents() {
+        this.orchestrator.on('thought', (thought) => {
+            console.log(`\n\x1b[35m[Thought]:\x1b[0m ${thought}`);
+        });
+        this.orchestrator.on('action:start', (action) => {
+            console.log(`\x1b[33m[Action]:\x1b[0m Running ${action.tool} with args: ${JSON.stringify(action.input)}`);
+        });
+        this.orchestrator.on('action:end', (_name, observation) => {
+            console.log(`\x1b[34m[Observation]:\x1b[0m ${observation}`);
+        });
+        this.orchestrator.on('interrupt:requested', () => {
+            console.log('\n\x1b[31m[!] Interrupt received. Halting operation...\x1b[0m');
+        });
+        this.orchestrator.on('paused', async () => {
+            await this.promptForInput();
+        });
+    }
+    setupKeypressHandler() {
+        // Non-TTY environments (piped stdin, CI, Docker, SEA binary) cannot
+        // support raw-mode keypress listeners. Return a no-op cleanup.
+        if (!process.stdin.isTTY) {
+            return () => { };
+        }
+        readline.emitKeypressEvents(process.stdin);
+        process.stdin.setRawMode(true);
+        const onKeypress = async (_str, key) => {
+            if (key.ctrl && key.name === 'c') {
+                this.disableRawMode();
+                console.log('\nProcess terminated.');
+                process.exit(0);
+            }
+            if (this.orchestrator.getState() !== 'PAUSED' &&
+                this.orchestrator.getState() !== 'COMPLETED' &&
+                (key.name === 'i' || key.name === 'return')) {
+                try {
+                    // Disable raw mode so confirmInterrupt can read cooked input.
+                    this.disableRawMode();
+                    FooterManager.instance()?.hide();
+                    const confirmed = await confirmInterrupt();
+                    FooterManager.instance()?.show();
+                    if (confirmed) {
+                        this.orchestrator.triggerInterrupt();
+                    }
+                }
+                catch {
+                    // If the confirmation prompt itself fails, default to not interrupting.
+                }
+                finally {
+                    // Re-enable raw mode for subsequent keypresses.
+                    if (process.stdin.isTTY) {
+                        process.stdin.setRawMode(true);
+                    }
+                }
+            }
+        };
+        process.stdin.on('keypress', onKeypress);
+        return () => {
+            process.stdin.removeListener('keypress', onKeypress);
+            this.disableRawMode();
+        };
+    }
+    disableRawMode() {
+        if (process.stdin.isTTY) {
+            process.stdin.setRawMode(false);
+        }
+    }
+    async promptForInput() {
+        this.disableRawMode();
+        const rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+        });
+        return new Promise((resolve) => {
+            rl.question('\n\x1b[36m[XCODER INTERRUPT] Enter steering instructions:\x1b[0m ', (answer) => {
+                rl.close();
+                if (process.stdin.isTTY) {
+                    process.stdin.setRawMode(true);
+                }
+                this.orchestrator.injectUserInput(answer.trim());
+                resolve();
+            });
+        });
+    }
+    async start(task) {
+        const cleanupKeyboard = this.setupKeypressHandler();
+        console.log(`\x1b[32m=== Xcoder SDLC Agent Orchestration Active ===\x1b[0m`);
+        console.log(`\x1b[90mPress \x1b[33m'i'\x1b[90m or \x1b[33m[Enter]\x1b[90m at any time to interrupt and send input.\x1b[0m\n`);
+        try {
+            const result = await this.orchestrator.run(task);
+            console.log(`\n\x1b[32m=== Result ===\x1b[0m\n${result}`);
+        }
+        catch (err) {
+            console.error(`\n\x1b[31m[Orchestrator Execution Failed]:\x1b[0m`, err.message);
+        }
+        finally {
+            cleanupKeyboard();
+        }
+    }
+}
+// ============================================================================
+// Execution Example
+// ============================================================================
+async function main() {
+    const orchestrator = new GenesisReActOrchestrator({
+        agentName: 'repl-agent',
+        directive: 'You are the Xcoder SDLC ReAct Agent. Follow the response contract exactly.',
+        skills: [
+            'Interactive problem-solving',
+            'Tool-based exploration and execution',
+        ],
+    });
+    const cli = new XcoderCLIController(orchestrator);
+    await cli.start('Analyze repository structure and find bugs.');
+}

package/dist/agents/samurai-agent.d.ts

@@ -0,0 +1,53 @@
+import type { RaoStep, TokenUsage } from "../types.js";
+import { LlmClient } from "../llm/client.js";
+export interface SamuraiAgentOptions {
+    workspaceRoot: string;
+    llm: LlmClient;
+    maxIterations?: number;
+    model?: string;
+    /** Optional additional context injected into the system prompt (e.g. package.json contents). */
+    packageJsonContext?: string | null;
+    /** When true, writes protocol_error parse failures to protocol_error.log via logProtocolError(). Mirrors SubAgentOptions.protocolErrorLog. */
+    protocolErrorLog?: boolean;
+    /** When true, register record_lesson tool and inject lesson context. */
+    lessonLearned?: boolean;
+    /** Pre-loaded lesson content (avoid re-reading per run). */
+    lessonContext?: string;
+}
+export interface SamuraiResult {
+    summary: string;
+    deliverable: unknown;
+    filesTouched: string[];
+    raoTrace: RaoStep[];
+    tokenUsage: TokenUsage;
+    iterations: number;
+    crashed?: boolean;
+    stuckLoop?: boolean;
+}
+/**
+ * A standalone single-agent ReAct loop. Loads all registered tools, runs a
+ * conversation loop against the LLM, dispatches tool calls through the shared
+ * tool registry, and returns a result (or keeps looping in chat mode).
+ * Not coupled to SubtaskNode, TaskSpec, or the orchestrator.
+ */
+export declare class SamuraiAgent {
+    private opts;
+    constructor(opts: SamuraiAgentOptions);
+    private buildPrompt;
+    private loop;
+    /**
+     * Run a single agent invocation for a given goal. Returns when the agent
+     * calls final_answer or exhausts iterations.
+     */
+    runOnce(goal: string, opts?: {
+        onStep?: (step: RaoStep) => void;
+        onTokens?: (cumulative: TokenUsage) => void;
+    }): Promise<SamuraiResult>;
+    /**
+     * Start an interactive REPL session. Reads lines from stdin, runs the agent
+     * loop per turn, and prints the result.  The system prompt is built once
+     * and reused across turns; the transcript accumulates the full conversation
+     * (not cleared between user lines).
+     */
+    runChat(onChunk?: (text: string) => void): Promise<void>;
+}