xcoder-dna 0.0.0-stage → 1.3.0

package/dist/agents/samurai-agent.js

@@ -0,0 +1,279 @@
+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 { log } from "../util/logger.js";
+import { startThinking } from "../util/terminal.js";
+import { isProtocolErrorLoggingEnabled, logProtocolError } from "../util/protocol-error-logger.js";
+import { isToolErrorLoggingEnabled, logToolError } from "../util/tool-error-logger.js";
+import { DuplicateActionDetector } from "./duplicate-detector.js";
+import { recordLesson } from "../orchestrator/lesson-manager.js";
+const SAMURAI_DIRECTIVE = `Act as a general-purpose AI assistant with full access to the tool suite. Use tools when they give a better answer than guessing. Be direct and concrete. Prefer glob/grep/read_file over shell commands for file operations. Respect the shell denylist. Surface the OS platform in the first response.`.trim();
+const SAMURAI_SKILLS = [
+    "File Management: reading, writing, editing, globbing, grepping files across the workspace.",
+    "OS awareness: Windows, Linux, and macOS — adapting shell syntax and paths per platform.",
+    "Security: never passing raw secrets; using credentialRef for credential hygiene.",
+    "Directness: answering the question asked before volunteering tangential information.",
+];
+/**
+ * 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 class SamuraiAgent {
+    opts;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    // ── System prompt (built once per run to amortise index/project-detection cost) ──
+    async buildPrompt(goal) {
+        const index = await getOrBuildIndex(this.opts.workspaceRoot);
+        const detectedCommands = await detectProjectCommands(this.opts.workspaceRoot, index);
+        const environment = getEnvironmentInfo();
+        const promptOpts = {
+            agentName: "samurai",
+            roleDescription: SAMURAI_DIRECTIVE,
+            directive: SAMURAI_DIRECTIVE,
+            skills: SAMURAI_SKILLS,
+            tools: buildToolManifest({ lessonLearned: this.opts.lessonLearned ?? false }),
+            environment,
+            detectedCommands,
+            goal,
+            upstreamContext: this.opts.packageJsonContext ?? undefined,
+            isStandalone: true,
+            lessonContext: this.opts.lessonContext,
+        };
+        return buildAgentSystemPrompt(promptOpts);
+    }
+    // ── Core ReAct loop ──
+    async loop(systemPrompt, transcript, maxIterations, onStep, onTokens) {
+        const raoTrace = [];
+        const filesTouched = new Set();
+        const cumulative = { inputTokens: 0, outputTokens: 0 };
+        const hasCallbacks = !!onStep || !!onTokens;
+        const dupDetector = new DuplicateActionDetector();
+        for (let i = 0; i < maxIterations; i++) {
+            let spinner = hasCallbacks ? null : startThinking("samurai");
+            let raw;
+            let completion;
+            try {
+                completion = await this.opts.llm.complete(systemPrompt, transcript);
+                raw = completion.text;
+                cumulative.inputTokens += completion.usage.inputTokens;
+                cumulative.outputTokens += completion.usage.outputTokens;
+                onTokens?.(cumulative);
+            }
+            catch (e) {
+                const message = e.message;
+                if (spinner)
+                    spinner.fail(`llm_error: ${message}`);
+                transcript.push({ role: "user", content: `Observation: llm_error: ${message}\nTry again.` });
+                const step = { thought: "(llm call failed)", action: null, observation: `llm_error: ${message}` };
+                raoTrace.push(step);
+                onStep?.(step);
+                continue;
+            }
+            transcript.push({ role: "assistant", content: raw });
+            const parsed = parseReactMessage(raw);
+            if (!parsed.ok) {
+                if (spinner)
+                    spinner.stop("(unparseable response)");
+                const errObservation = `protocol_error: ${parsed.error}`;
+                if (this.opts.protocolErrorLog || isProtocolErrorLoggingEnabled()) {
+                    logProtocolError({
+                        ts: new Date().toISOString(),
+                        taskId: "samurai",
+                        agentId: "samurai",
+                        iteration: i,
+                        error: parsed.error,
+                        raw,
+                        model: completion.model ?? "unknown",
+                        stopReason: completion.stopReason,
+                        inputTokens: completion.usage.inputTokens,
+                        outputTokens: completion.usage.outputTokens,
+                    });
+                }
+                transcript.push({ role: "user", content: `Observation: ${errObservation}\nRe-read the contract and try again.` });
+                const step = { thought: "(unparseable response)", action: null, observation: errObservation };
+                raoTrace.push(step);
+                onStep?.(step);
+                continue;
+            }
+            const { thought, action, final_answer } = parsed.message;
+            if (spinner)
+                spinner.stop(thought);
+            if (final_answer) {
+                const step = { thought, action: null, observation: "final_answer submitted" };
+                raoTrace.push(step);
+                onStep?.(step);
+                return {
+                    summary: final_answer.summary,
+                    deliverable: final_answer.deliverable,
+                    filesTouched: [...filesTouched, ...(final_answer.files_touched ?? [])],
+                    raoTrace,
+                    tokenUsage: cumulative,
+                    iterations: i + 1,
+                };
+            }
+            // Prose-only recovery: parseReactMessage's Layer 4a/4b can return
+            // { action: null, final_answer: null } when the model sends pure
+            // reasoning prose. Treat the thought as an observation and continue.
+            if (!action) {
+                const obs = `prose_recovery: no action or final_answer in response — model sent reasoning prose only. Thought: ${thought}`;
+                const step = { thought, action: null, observation: obs };
+                raoTrace.push(step);
+                onStep?.(step);
+                transcript.push({ role: "user", content: `Observation: ${obs}\nYou must respond with either an action or a final_answer.` });
+                continue;
+            }
+            const { tool, input } = action;
+            const dup = dupDetector.check(thought, tool, input, i + 1);
+            if (dup.stuck) {
+                // Programmatic lesson recording (samurai-driven): when the agent
+                // gets stuck, record the pattern so the next run benefits.
+                if (this.opts.lessonLearned) {
+                    recordLesson(this.opts.workspaceRoot, {
+                        source: "samurai",
+                        taskId: "N/A",
+                        tags: ["stuck-loop", "samurai"],
+                        context: `Samurai agent got stuck in a repeated action loop after ${i + 1} iterations. The duplicate detector flagged ${dupDetector.duplicateCount} duplicate actions.`,
+                        lesson: `When a Samurai agent gets stuck in a loop: check the observation text for actionable hints, reduce the max iterations, and consider re-running with a clearer goal.`,
+                    }).catch(() => { });
+                }
+                return {
+                    summary: `stuck in a repeated action loop: ${dupDetector.duplicateCount} duplicate actions detected — aborted after ${i + 1} iterations instead of running to the full ${maxIterations}-iteration cap.`,
+                    deliverable: null,
+                    filesTouched: [...filesTouched],
+                    raoTrace,
+                    tokenUsage: cumulative,
+                    iterations: i + 1,
+                    stuckLoop: true,
+                };
+            }
+            let result;
+            try {
+                result = await dispatchTool(this.opts.workspaceRoot, tool, input, undefined);
+            }
+            catch (e) {
+                result = { tool, ok: false, output: { error: `unexpected tool failure: ${e.message}` } };
+            }
+            // log tool errors when --debug-tools is active
+            if (!result.ok && isToolErrorLoggingEnabled()) {
+                logToolError({
+                    ts: new Date().toISOString(),
+                    tool,
+                    error: result.output?.error ?? "unknown",
+                    ok: false,
+                    input: JSON.stringify(input),
+                    iteration: i + 1,
+                });
+            }
+            if ((tool === "write_file" || tool === "edit_file") && result.ok) {
+                const out = result.output;
+                if (out.relPath)
+                    filesTouched.add(out.relPath);
+            }
+            if (tool === "sed_tool" && result.ok) {
+                const out = result.output;
+                if (out.results) {
+                    for (const r of out.results) {
+                        if (r.matched)
+                            filesTouched.add(r.relPath);
+                    }
+                }
+            }
+            const observation = JSON.stringify(result.output).slice(0, 4000);
+            const step = { thought, action: { tool, input }, observation };
+            raoTrace.push(step);
+            onStep?.(step);
+            transcript.push({ role: "user", content: `Observation: ${observation}` });
+        }
+        return {
+            summary: `did not reach a final_answer within ${maxIterations} iterations`,
+            deliverable: null,
+            filesTouched: [...filesTouched],
+            raoTrace,
+            tokenUsage: cumulative,
+            iterations: maxIterations,
+        };
+    }
+    /**
+     * Run a single agent invocation for a given goal. Returns when the agent
+     * calls final_answer or exhausts iterations.
+     */
+    async runOnce(goal, opts) {
+        const maxIterations = this.opts.maxIterations ?? 200;
+        const systemPrompt = await this.buildPrompt(goal);
+        const transcript = [
+            { role: "user", content: "Begin. Respond with your first contract message now." },
+        ];
+        return this.loop(systemPrompt, transcript, maxIterations, opts?.onStep, opts?.onTokens);
+    }
+    /**
+     * 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).
+     */
+    async runChat(onChunk) {
+        const maxIterations = this.opts.maxIterations ?? 200;
+        const systemPrompt = await this.buildPrompt();
+        const transcript = [];
+        // Use Node.js readline for a cross-platform line-by-line interface.
+        const readline = await import("node:readline");
+        const rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+        });
+        log.ok("samurai chat — type /exit or press Ctrl+C to quit.");
+        log.dim(`workspace: ${this.opts.workspaceRoot}`);
+        log.dim(`model: ${this.opts.model ?? process.env.XCODER_MODEL ?? "deepseek-chat"}`);
+        log.raw("");
+        // Wrap readline in an async iterator so we can await each line.
+        const getLine = () => new Promise((resolve) => {
+            rl.question("samurai> ", (answer) => {
+                resolve(answer.trim());
+            });
+        });
+        process.stdout.write("samurai> ");
+        while (true) {
+            const line = await getLine();
+            if (!line) {
+                // Ctrl+C or empty on exit
+                rl.close();
+                break;
+            }
+            const trimmed = line.trim();
+            if (trimmed === "/exit" || trimmed === "/quit") {
+                rl.close();
+                break;
+            }
+            if (!trimmed) {
+                process.stdout.write("samurai> ");
+                continue;
+            }
+            // Inject user message as a goal for this turn
+            transcript.push({ role: "user", content: trimmed });
+            log.dim("thinking…");
+            const result = await this.loop(systemPrompt, transcript, maxIterations);
+            // Merge filesTouched from this run
+            if (result.summary) {
+                log.ok(result.summary);
+            }
+            if (result.deliverable !== null && result.deliverable !== undefined) {
+                log.raw(JSON.stringify(result.deliverable, null, 2));
+            }
+            log.dim(`iterations: ${result.iterations}  tokens: ${result.tokenUsage.inputTokens} in / ${result.tokenUsage.outputTokens} out`);
+            log.raw("");
+            if (onChunk) {
+                onChunk(result.summary);
+                if (result.deliverable)
+                    onChunk(JSON.stringify(result.deliverable));
+            }
+        }
+        rl.close();
+        log.ok("samurai chat ended.");
+    }
+}

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

@@ -0,0 +1,56 @@
+import type { SubtaskNode, SubtaskResult } from "../types.js";
+import type { WksProtocolMap } from "../protocol/wks-protocol-manager.js";
+import { LlmClient } from "../llm/client.js";
+import { type RoleDirective } from "../skills/directives.js";
+export interface SubAgentOptions {
+    taskId: string;
+    workspaceRoot: string;
+    llm: LlmClient;
+    maxIterations?: number;
+    /** Appended to the subtask goal on a healing retry — see orchestrator/healing.ts. */
+    healingHint?: string;
+    /** Optional per-role protocol overrides from wks_protocol.md. */
+    protocolOverrides?: WksProtocolMap;
+    /**
+     * If set, overrides the role directive and/or skills (the system prompt's
+     * "Your directive" block and "## Relevant skills" section).
+     * - A plain `string` uses it as the directive text, skills fall back to
+     *   ROLE_DIRECTIVES[subtask.role].skills (backward compat).
+     * - A `RoleDirective` object carries both `directive` and `skills`,
+     *   enabling a full override of both. If the object has no `skills`
+     *   array, skills also fall back to the role defaults.
+     * Allows the --ba path to inject a specialized directive without changing
+     * ROLE_DIRECTIVES, which existing callers (orchestrator, healing, etc.) rely on.
+     */
+    directiveOverride?: string | RoleDirective;
+    /** Enable diagnostic logging of protocol_error parse failures to protocol_error.log. */
+    protocolErrorLog?: boolean;
+    /** When true, register record_lesson tool and inject lesson context. */
+    lessonLearned?: boolean;
+    /** Pre-loaded lesson content (avoid re-reading per Sub Agent). */
+    lessonContext?: string;
+    /** When true, use SilentTerminal to suppress console output. */
+    quiet?: boolean;
+}
+/**
+ * The "Instance Agent" of the design brief, mapped 1:1 onto Xcoder SDLC's Sub
+ * Agent: role and engine are config on the subtask node (`role`, `engine`),
+ * not baked into a special-purpose class.
+ *
+ * Isolation contract: `run()` NEVER throws. Every failure mode inside the
+ * loop — an LLM API error, a tool exception that somehow escaped
+ * `dispatchTool`'s own try/catch, an unparseable response — is caught,
+ * logged to `sys.log`, surfaced to the terminal, and turned into either a
+ * recoverable observation (the loop continues) or, if truly fatal, a
+ * `crashed: true` result the Master Orchestrator can route through its
+ * normal bounded healing/escalation path. The caller in `orchestrator/
+ * swarm.ts` still wraps this in its own try/catch as defense in depth, but
+ * this class is designed not to need that safety net.
+ */
+export declare class SubAgent {
+    private opts;
+    constructor(opts: SubAgentOptions);
+    private get term();
+    run(subtask: SubtaskNode): Promise<SubtaskResult>;
+    private crashResult;
+}