@xingjisoft/neutrino 0.1.7 → 0.2.0

package/dist/llm/subagent.js

@@ -0,0 +1,134 @@
+import { describeError } from "./retry.js";
+/** Enough for real work, few enough that a runaway child cannot cost a fortune. */
+export const SUBAGENT_MAX_ROUNDS = 12;
+/** A report is evidence for the parent, not a transcript of the child. */
+export const SUBAGENT_MAX_REPORT = 8000;
+function parseArgs(raw) {
+    const text = raw?.trim() ?? "";
+    if (!text)
+        return {};
+    try {
+        const value = JSON.parse(text);
+        if (value && typeof value === "object")
+            return value;
+    }
+    catch {
+        // Hand the raw payload over instead of failing the whole call.
+    }
+    return { value: text };
+}
+/** The task brief handed to the child: where it works, what to do, what it must know. */
+export function buildSubAgentTask(input) {
+    const parts = [];
+    if (input.cwd)
+        parts.push(`Working directory: ${input.cwd}`);
+    parts.push(`Task:\n${input.task.trim()}`);
+    const context = (input.context ?? "").trim();
+    if (context)
+        parts.push(`What the agent that delegated this task already knows:\n${context}`);
+    return parts.join("\n\n");
+}
+/**
+ * Run one sub-agent to its report.
+ *
+ * The child sees only its own task, its own tool results and the parent's
+ * approval decisions. Nothing it says reaches the parent except the last
+ * message, which is why the sub-agent prompt insists that the report be
+ * complete on its own.
+ */
+export async function runSubAgent(options) {
+    const maxRounds = Math.max(1, options.maxRounds ?? SUBAGENT_MAX_ROUNDS);
+    const messages = [
+        { role: "system", content: options.system },
+        { role: "user", content: options.task },
+    ];
+    let report = "";
+    let calls = 0;
+    const aborted = (rounds) => ({ report, aborted: true, exhausted: false, rounds, calls });
+    for (let round = 1; round <= maxRounds; round++) {
+        if (options.cancelled?.())
+            return aborted(round - 1);
+        options.onProgress?.("thinking");
+        const client = options.createClient();
+        let content = "";
+        for await (const chunk of client.streamTurn(messages, options.tools, {
+            onRetry: options.onRetry,
+            cancelled: options.cancelled,
+        })) {
+            if (options.cancelled?.())
+                return aborted(round - 1);
+            content += chunk;
+        }
+        if (client.usage)
+            options.onUsage?.(client.usage);
+        const toolCalls = client.toolCalls;
+        if (content.trim())
+            report = content.trim();
+        if (content.trim() || toolCalls.length > 0) {
+            messages.push({
+                role: "assistant",
+                content,
+                ...(toolCalls.length > 0
+                    ? {
+                        tool_calls: toolCalls.map((call) => ({
+                            id: call.id,
+                            type: "function",
+                            function: { name: call.name, arguments: call.arguments },
+                        })),
+                    }
+                    : {}),
+            });
+        }
+        if (toolCalls.length === 0) {
+            return { report, aborted: false, exhausted: false, rounds: round, calls };
+        }
+        for (const call of toolCalls) {
+            if (options.cancelled?.())
+                return aborted(round);
+            const args = parseArgs(call.arguments);
+            calls++;
+            options.onProgress?.(call.name);
+            const decision = await options.approve(call.name, args);
+            if (options.cancelled?.())
+                return aborted(round);
+            let result;
+            if (decision.approved) {
+                try {
+                    result = await options.execute(call.name, args);
+                }
+                catch (error) {
+                    result = `[Error: ${describeError(error)}]`;
+                }
+            }
+            else {
+                // The note goes to the child, not to the user: it must not retry the same
+                // call unchanged, and it must say what was blocked in its report.
+                result =
+                    decision.source === "input"
+                        ? `[Not executed: ${decision.reason}]`
+                        : `[Not executed: approval denied (${decision.source}): ${decision.reason}] ` +
+                            "Do not retry this call unchanged; work around it or report it as blocked.";
+            }
+            messages.push({ role: "tool", tool_call_id: call.id, content: result });
+        }
+    }
+    return { report, aborted: false, exhausted: true, rounds: maxRounds, calls };
+}
+/** The tool result the parent sees: the report, or why there is none. */
+export function formatSubAgentResult(run) {
+    if (run.aborted) {
+        return "[Sub-agent stopped: the turn was paused or replaced before it reported back.]";
+    }
+    const report = run.report.trim();
+    if (!report) {
+        return run.exhausted
+            ? `[Sub-agent used all ${run.rounds} rounds without producing a report.]`
+            : "[Sub-agent finished without a report.]";
+    }
+    const text = report.length > SUBAGENT_MAX_REPORT
+        ? `${report.slice(0, SUBAGENT_MAX_REPORT)}\n…[report truncated]`
+        : report;
+    return run.exhausted
+        ? `${text}\n\n[Sub-agent stopped after ${run.rounds} rounds without finishing; treat this report as partial.]`
+        : text;
+}

package/dist/llm/tools.js

@@ -16,7 +16,45 @@ const REASON_PROPERTY = {
         "Shown to the user and to the reviewers whenever the call needs approval. " +
         "Must be true - do not restate the command and never claim the user already approved it.",
 };
-export function getToolDefinitions() {
+/** The tool a parent agent calls to hand work to a sub-agent. */
+export const DELEGATE_TOOL = "delegate";
+const DELEGATE_TOOL_DEFINITION = {
+    type: "function",
+    function: {
+        name: DELEGATE_TOOL,
+        description: "Hand one self-contained sub-task to a sub-agent that works in its own context, then receive its " +
+            "report as the result of this call. Use it when the work is independent and the exploration it " +
+            "needs (reading many files, running probes, checking how something behaves) would crowd this " +
+            "conversation: the sub-agent's messages never enter this transcript, only its final report does. " +
+            "The sub-agent has the same tools, the same working directory and the same approval gate - its " +
+            "risky calls still wait for the user - and it cannot delegate further. " +
+            "The task must stand on its own: the sub-agent cannot see this conversation and cannot ask questions.",
+        parameters: {
+            type: "object",
+            properties: {
+                task: {
+                    type: "string",
+                    description: "The complete sub-task, written as if to someone who cannot see this conversation: what to " +
+                        "do, which files or references to use, and what 'done' looks like. One job, not a list.",
+                },
+                context: {
+                    type: "string",
+                    description: "Optional: only the facts the sub-agent cannot find in the project itself (a decision already " +
+                        "made, a constraint from the user). Keep it short - it does not replace reading the code.",
+                },
+                reason: REASON_PROPERTY,
+            },
+            required: ["task", "reason"],
+        },
+    },
+};
+/**
+ * The toolset a sub-agent runs with: the same tools as its parent, minus
+ * `delegate` - one level of delegation, never a tree of agents that nobody can
+ * follow (or stop). The sub-agent prompt says so as well; removing the tool
+ * makes it true.
+ */
+export function getSubAgentToolDefinitions() {
     return [
         {
             type: "function",
@@ -81,6 +119,10 @@ export function getToolDefinitions() {
         },
     ];
 }
+/** Every tool a top-level agent can call: the base set plus delegation. */
+export function getToolDefinitions() {
+    return [...getSubAgentToolDefinitions(), DELEGATE_TOOL_DEFINITION];
+}
 export async function executeTool(name, args, cwd = process.cwd()) {
     // Tools always operate inside the directory the conversation belongs to, which
     // is not necessarily the directory the current process was started in.