@geminixiang/mikan 1.0.0-beta.4 → 1.0.0-beta.40

package/dist/harness/subagent-runner.js

@@ -0,0 +1,617 @@
+import { randomUUID } from "node:crypto";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { Kind, Type } from "@sinclair/typebox";
+import { Value } from "@sinclair/typebox/value";
+import * as log from "../log.js";
+import { MikanAgentSession } from "./runner.js";
+import { SessionStore } from "./session-store.js";
+import { copySubagentUsage, createEmptySubagentUsage } from "./usage.js";
+import { unboundedSlotPool } from "../tools/subagent-slots.js";
+const subagentRunDepth = new AsyncLocalStorage();
+const DEFAULT_SYSTEM_PROMPT = "You are a focused subagent. Complete only the assigned task and return the result directly.";
+export const DEFAULT_SUBAGENT_BUDGET = {
+    maxTurns: 100,
+    maxCostUsd: 10,
+    maxDurationMs: 10 * 60 * 1000,
+};
+/** Time allowed for an aborted subagent to settle before detached cleanup. */
+export const SUBAGENT_ABORT_GRACE_MS = 100;
+const SCHEMA_STRUCTURAL_KEYS = new Set([
+    "type",
+    "properties",
+    "required",
+    "items",
+    "enum",
+    "const",
+    "anyOf",
+    "oneOf",
+    "allOf",
+]);
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function schemaOptions(node) {
+    const options = {};
+    for (const [key, value] of Object.entries(node)) {
+        if (!SCHEMA_STRUCTURAL_KEYS.has(key))
+            options[key] = value;
+    }
+    if (isRecord(options.additionalProperties)) {
+        options.additionalProperties = hydrateSchema(options.additionalProperties);
+    }
+    return options;
+}
+/**
+ * outputSchema arrives over the subagent tool as plain JSON (tool-call
+ * arguments never carry TypeBox's Kind symbol), but Value.Check dispatches
+ * purely on schema[Kind] and throws ValueCheckUnknownTypeError for anything
+ * without it. Hydrate plain JSON Schema into real TypeBox schema nodes so
+ * validation runs instead of throwing; schemas built with TypeBox already
+ * carry Kind and pass through untouched.
+ *
+ * Unsupported keywords ($ref, not, patternProperties, if/then/else) degrade to
+ * a permissive Unknown — fail-open by design: outputSchema is advisory output
+ * validation, not a security boundary.
+ */
+function hydrateSchema(schema) {
+    if (isRecord(schema) && Kind in schema)
+        return schema;
+    if (!isRecord(schema))
+        return Type.Unknown();
+    if (Array.isArray(schema.enum)) {
+        const literals = schema.enum.filter((value) => typeof value === "string" || typeof value === "number" || typeof value === "boolean");
+        return literals.length > 0
+            ? Type.Union(literals.map((value) => Type.Literal(value)))
+            : Type.Unknown();
+    }
+    if ("const" in schema) {
+        const value = schema.const;
+        return typeof value === "string" || typeof value === "number" || typeof value === "boolean"
+            ? Type.Literal(value)
+            : Type.Unknown();
+    }
+    if (Array.isArray(schema.anyOf))
+        return Type.Union(schema.anyOf.map(hydrateSchema));
+    if (Array.isArray(schema.oneOf))
+        return Type.Union(schema.oneOf.map(hydrateSchema));
+    if (Array.isArray(schema.allOf))
+        return Type.Intersect(schema.allOf.map(hydrateSchema));
+    const type = Array.isArray(schema.type)
+        ? schema.type
+        : (schema.type ?? (schema.properties ? "object" : schema.items ? "array" : undefined));
+    if (Array.isArray(type)) {
+        return Type.Union(type.map((variant) => hydrateSchema({ ...schema, type: variant })));
+    }
+    const options = schemaOptions(schema);
+    switch (type) {
+        case "object": {
+            const properties = isRecord(schema.properties) ? schema.properties : {};
+            const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+            const props = {};
+            for (const [key, value] of Object.entries(properties)) {
+                const hydrated = hydrateSchema(value);
+                props[key] = required.has(key) ? hydrated : Type.Optional(hydrated);
+            }
+            return Type.Object(props, options);
+        }
+        case "array":
+            return Type.Array(schema.items !== undefined ? hydrateSchema(schema.items) : Type.Unknown(), options);
+        case "string":
+            return Type.String(options);
+        case "number":
+            return Type.Number(options);
+        case "integer":
+            return Type.Integer(options);
+        case "boolean":
+            return Type.Boolean(options);
+        case "null":
+            return Type.Null(options);
+        default:
+            return Type.Unknown(options);
+    }
+}
+function resolveBudget(budget) {
+    const resolved = { ...DEFAULT_SUBAGENT_BUDGET, ...budget };
+    const positiveIntegerFields = [
+        ["maxTurns", resolved.maxTurns],
+        ["maxTokens", resolved.maxTokens],
+        ["maxDurationMs", resolved.maxDurationMs],
+    ];
+    for (const [name, value] of positiveIntegerFields) {
+        if (value !== undefined && (!Number.isInteger(value) || value <= 0)) {
+            throw new Error(`api.subagent.run budget.${name} must be a positive integer`);
+        }
+    }
+    if (!Number.isFinite(resolved.maxCostUsd) || resolved.maxCostUsd < 0) {
+        throw new Error("api.subagent.run budget.maxCostUsd must be a non-negative number");
+    }
+    return resolved;
+}
+function selectTools(requested, available) {
+    if (!requested || requested.length === 0)
+        return [];
+    const byName = new Map();
+    for (const tool of available) {
+        if (!byName.has(tool.name))
+            byName.set(tool.name, tool);
+    }
+    const selected = [];
+    for (const name of new Set(requested)) {
+        const tool = byName.get(name);
+        if (!tool)
+            throw new Error(`Unknown or unavailable subagent tool: ${name}`);
+        selected.push(tool);
+    }
+    return selected;
+}
+/**
+ * Wrap a tool so the run can prove it was actually reached. Fields are listed
+ * explicitly rather than spread: `AgentTool` is a plain interface, and a
+ * structural copy would silently drop anything added to it later.
+ */
+function witnessToolUse(tool, invoked) {
+    return {
+        name: tool.name,
+        label: tool.label,
+        description: tool.description,
+        parameters: tool.parameters,
+        ...(tool.constrainedSampling !== undefined
+            ? { constrainedSampling: tool.constrainedSampling }
+            : {}),
+        ...(tool.prepareArguments ? { prepareArguments: tool.prepareArguments.bind(tool) } : {}),
+        ...(tool.executionMode ? { executionMode: tool.executionMode } : {}),
+        execute: (...args) => {
+            invoked.add(tool.name);
+            return tool.execute(...args);
+        },
+    };
+}
+function formatTask(task, input, parentContext) {
+    const trimmed = task.trim();
+    if (!trimmed)
+        throw new Error("api.subagent.run requires a non-empty task");
+    let formatted = trimmed;
+    if (input !== undefined) {
+        let serialized;
+        try {
+            serialized = JSON.stringify(input, null, 2);
+        }
+        catch (err) {
+            throw new Error(`api.subagent.run input must be JSON-serializable: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+        }
+        if (serialized === undefined)
+            throw new Error("api.subagent.run input must be JSON-serializable");
+        formatted = `${trimmed}\n\nInput:\n${serialized}`;
+    }
+    return parentContext ? `${parentContext}\n\n${formatted}` : formatted;
+}
+function messageText(message) {
+    if (message.role === "compactionSummary" || message.role === "branchSummary") {
+        return message.summary;
+    }
+    if (!("content" in message))
+        return "";
+    if (typeof message.content === "string")
+        return message.content;
+    if (!Array.isArray(message.content))
+        return "";
+    return message.content
+        .filter((part) => typeof part === "object" && part !== null && part.type === "text")
+        .map((part) => part.text)
+        .join("");
+}
+function normalizedParentContext(request, messages) {
+    if (!request.parentContext || !messages)
+        return undefined;
+    const recentTurns = request.parentContext.recentTurns ?? 3;
+    if (!Number.isInteger(recentTurns) || recentTurns < 1 || recentTurns > 8) {
+        throw new Error("api.subagent.run parentContext.recentTurns must be an integer from 1 to 8");
+    }
+    const conversation = messages.filter((message) => (message.role === "user" || message.role === "assistant") && messageText(message));
+    let first = conversation.length;
+    let users = 0;
+    while (first > 0 && users < recentTurns) {
+        first -= 1;
+        if (conversation[first]?.role === "user")
+            users += 1;
+    }
+    const recent = conversation.slice(first);
+    const recentStart = recent[0] ? messages.indexOf(recent[0]) : messages.length;
+    let summary;
+    for (let index = recentStart - 1; index >= 0; index--) {
+        const message = messages[index];
+        if (message?.role === "compactionSummary" || message?.role === "branchSummary") {
+            summary = message;
+            break;
+        }
+    }
+    return [
+        "<parent_reference_context>",
+        summary ? `Earlier summary: ${messageText(summary)}` : "[Earlier parent context omitted]",
+        ...recent.map((message) => `${message.role === "user" ? "User" : "Assistant"}: ${messageText(message)}`),
+        "</parent_reference_context>",
+    ].join("\n");
+}
+/**
+ * The evidence policy has to name the actual grant. Told to "use granted
+ * tools" while holding none, a model will write a tool call as prose and
+ * hand that text back as its answer — which then flows to dependent DAG
+ * nodes as if it were a finding.
+ */
+function groundingPolicy(toolNames) {
+    if (toolNames.length === 0) {
+        return [
+            "Evidence policy:",
+            "- You have NO tools in this run. Do not emit tool calls or tool-call syntax; they will not execute.",
+            "- Answer only from the task text and any structured input supplied to you.",
+            "- Never claim to have read a file, run a command, or reached a repository or URL.",
+            "- If the task cannot be done without a tool, say so plainly and stop.",
+        ].join("\n");
+    }
+    return [
+        "Evidence policy:",
+        `- Your tools this run: ${toolNames.join(", ")}. Nothing else will execute.`,
+        "- Use them for any claim about files, commands, repositories, or external state.",
+        "- Never simulate tool output or claim a tool was used when it was not.",
+        "- If the task requires a tool you were not granted, state that you cannot verify it instead of guessing.",
+    ].join("\n");
+}
+function buildSystemPrompt(base, outputSchema, toolNames) {
+    const prompt = [base?.trim() || DEFAULT_SYSTEM_PROMPT, groundingPolicy(toolNames)].join("\n\n");
+    if (!outputSchema)
+        return prompt;
+    return [
+        prompt,
+        "",
+        "Return only one JSON value matching this JSON Schema. Do not use Markdown or code fences.",
+        JSON.stringify(outputSchema),
+    ].join("\n");
+}
+/**
+ * Every SubagentRunResult's metric fields are born here — one derivation from
+ * the session's run stats, so adding a metric is one edit and no terminal
+ * site can drift (the abort branch once shipped without toolCallCounts). The
+ * terminal sites state only what differs: status, error, text.
+ */
+function baseRunResult(runId, model, startedAt, stats) {
+    const usage = stats?.usage ?? createEmptySubagentUsage();
+    return {
+        runId,
+        model,
+        turns: stats?.llmCalls ?? 0,
+        toolCalls: stats?.toolCalls ?? 0,
+        toolCallCounts: stats?.toolCallCounts ?? {},
+        usage,
+        tokens: usage.totalTokens,
+        costUsd: usage.cost.total,
+        durationMs: Date.now() - startedAt,
+    };
+}
+function finalAssistant(messages) {
+    for (let index = messages.length - 1; index >= 0; index--) {
+        const message = messages[index];
+        if (message?.role === "assistant")
+            return message;
+    }
+    return undefined;
+}
+function assistantText(message) {
+    if (!message)
+        return "";
+    return message.content
+        .filter((part) => part.type === "text")
+        .map((part) => part.text)
+        .join("");
+}
+/**
+ * Execute one non-recursive, fresh subagent run. Never rejects: every
+ * failure — including request validation — is a result with a terminal
+ * status, so batch callers (`tasks` / `dag`) can never orphan in-flight
+ * sibling runs on one bad request. Usage is reported once, after the
+ * underlying run settles; an aborted run may report it from detached cleanup.
+ */
+export async function runSubagent(options) {
+    const execution = await executeBoundedSubagentRun(options);
+    if (execution.cleanup) {
+        void execution.cleanup
+            .then(async (result) => {
+            await reportSubagentUsage(options.onUsage, result.usage);
+        })
+            .catch((err) => {
+            log.logWarning("Subagent detached cleanup failed", String(err));
+        });
+        return execution.result;
+    }
+    await reportSubagentUsage(options.onUsage, execution.result.usage);
+    return execution.result;
+}
+async function reportSubagentUsage(onUsage, usage) {
+    try {
+        await onUsage?.(copySubagentUsage(usage));
+    }
+    catch (err) {
+        log.logWarning("Subagent onUsage listener failed", String(err));
+    }
+}
+async function executeBoundedSubagentRun(options) {
+    const startedAt = Date.now();
+    let release;
+    try {
+        release = await (options.slots ?? unboundedSlotPool()).acquire(options.request.signal);
+    }
+    catch (err) {
+        if (err instanceof Error && err.name === "AbortError") {
+            const model = options.request.model ?? {
+                provider: options.defaultModel.provider,
+                id: options.defaultModel.id,
+            };
+            return {
+                result: { ...baseRunResult(randomUUID(), model, startedAt), status: "cancelled" },
+            };
+        }
+        throw err;
+    }
+    if (!release)
+        throw new Error("Subagent slot acquisition returned no release handle");
+    try {
+        const execution = await executeSubagentRun(options);
+        if (!execution.cleanup) {
+            release();
+            release = undefined;
+            return execution;
+        }
+        const cleanup = execution.cleanup;
+        const heldRelease = release;
+        void cleanup
+            .then(() => heldRelease(), (err) => {
+            log.logWarning("Subagent detached cleanup failed", String(err));
+            heldRelease();
+        })
+            .catch((err) => {
+            log.logWarning("Subagent detached release failed", String(err));
+            heldRelease();
+        });
+        release = undefined;
+        return execution;
+    }
+    catch (err) {
+        release?.();
+        release = undefined;
+        throw err;
+    }
+}
+function noop() { }
+/**
+ * Expand `request.profile` into the concrete capability set it names. Most
+ * profile budgets are caps that callers may only tighten. Token budgets are
+ * different: the effective allowance is the larger of the profile default and
+ * the caller's request.
+ */
+function resolveProfile(request, options) {
+    if (!request.profile)
+        return request;
+    const profile = options.profiles?.get(request.profile);
+    if (!profile) {
+        const known = [...(options.profiles?.keys() ?? [])].join(", ");
+        throw new Error(`Unknown subagent profile: ${request.profile}${known ? ` (available: ${known})` : ""}`);
+    }
+    if (request.tools || request.model || request.systemPrompt || request.thinkingLevel) {
+        throw new Error(`Subagent profile ${request.profile} cannot be combined with tools, model, systemPrompt, or thinkingLevel`);
+    }
+    const budget = {
+        ...request.budget,
+        ...(profile.maxTurns !== undefined
+            ? { maxTurns: Math.min(profile.maxTurns, request.budget?.maxTurns ?? profile.maxTurns) }
+            : {}),
+        ...(profile.maxTokens !== undefined || request.budget?.maxTokens !== undefined
+            ? { maxTokens: Math.max(profile.maxTokens ?? 0, request.budget?.maxTokens ?? 0) }
+            : {}),
+        ...(profile.maxCostUsd !== undefined
+            ? {
+                maxCostUsd: Math.min(profile.maxCostUsd, request.budget?.maxCostUsd ?? profile.maxCostUsd),
+            }
+            : {}),
+        ...(profile.maxDurationMs !== undefined
+            ? {
+                maxDurationMs: Math.min(profile.maxDurationMs, request.budget?.maxDurationMs ?? profile.maxDurationMs),
+            }
+            : {}),
+    };
+    return {
+        ...request,
+        systemPrompt: profile.systemPrompt,
+        tools: profile.tools,
+        requiredTools: profile.requiredTools,
+        ...(profile.model ? { model: profile.model } : {}),
+        ...(profile.thinkingLevel ? { thinkingLevel: profile.thinkingLevel } : {}),
+        ...(Object.keys(budget).length > 0 ? { budget } : {}),
+    };
+}
+async function executeSubagentRun(options) {
+    const request = resolveProfile(options.request, options);
+    const runId = randomUUID();
+    const startedAt = Date.now();
+    let modelSpec = request.model ?? {
+        provider: options.defaultModel.provider,
+        id: options.defaultModel.id,
+    };
+    let sessionRef;
+    let terminalSignal;
+    let timeout;
+    let notifyAbort = noop;
+    const abortRequested = new Promise((resolve) => {
+        notifyAbort = resolve;
+    });
+    const abort = (reason) => {
+        if (terminalSignal)
+            return;
+        terminalSignal = reason;
+        sessionRef?.abort();
+        notifyAbort();
+    };
+    const onAbort = () => abort("cancelled");
+    try {
+        if ((subagentRunDepth.getStore() ?? 0) >= 1) {
+            throw new Error("Nested api.subagent.run calls are not allowed");
+        }
+        const model = request.model
+            ? options.models.resolve(request.model.provider, request.model.id)
+            : options.defaultModel;
+        modelSpec = { provider: model.provider, id: model.id };
+        const invokedTools = new Set();
+        const granted = selectTools(request.tools, options.availableTools);
+        const missingRequiredTools = (request.requiredTools ?? []).filter((name) => !granted.some((tool) => tool.name === name));
+        if (missingRequiredTools.length > 0) {
+            throw new Error(`Required subagent tools were not granted: ${missingRequiredTools.join(", ")}`);
+        }
+        const tools = granted.map((tool) => witnessToolUse(tool, invokedTools));
+        const task = formatTask(request.task, request.input, normalizedParentContext(request, options.parentMessages));
+        const budget = resolveBudget(request.budget);
+        const session = new MikanAgentSession({
+            systemPrompt: buildSystemPrompt(request.systemPrompt, request.outputSchema, granted.map((tool) => tool.name)),
+            model,
+            thinkingLevel: request.thinkingLevel ?? options.thinkingLevel,
+            tools,
+            models: options.models,
+            sessionStore: SessionStore.inMemory(options.workspaceDir),
+            settings: { compaction: { enabled: false } },
+        });
+        sessionRef = session;
+        request.signal?.addEventListener("abort", onAbort, { once: true });
+        if (request.signal?.aborted)
+            abort("cancelled");
+        timeout = setTimeout(() => abort("timeout"), budget.maxDurationMs);
+        timeout.unref();
+        const buildResult = (cleanupPending = false) => {
+            const stats = session.getLastRunStats();
+            const assistant = finalAssistant(session.messages);
+            const text = assistantText(assistant);
+            const base = {
+                ...baseRunResult(runId, modelSpec, startedAt, stats),
+                ...(text ? { text } : {}),
+                ...(cleanupPending ? { cleanupPending: true } : {}),
+            };
+            if (terminalSignal) {
+                return {
+                    ...base,
+                    status: terminalSignal,
+                    ...(terminalSignal === "timeout"
+                        ? { error: `Subagent exceeded its ${budget.maxDurationMs}ms duration limit` }
+                        : {}),
+                };
+            }
+            if (stats.budgetExceededReason) {
+                return {
+                    ...base,
+                    status: "budget_exceeded",
+                    error: stats.budgetExceededReason,
+                };
+            }
+            const unusedRequiredTools = (request.requiredTools ?? []).filter((name) => !invokedTools.has(name));
+            if (unusedRequiredTools.length > 0) {
+                return {
+                    ...base,
+                    status: "failed",
+                    error: `Required tool not used: ${unusedRequiredTools.join(", ")}`,
+                };
+            }
+            if (assistant?.stopReason === "error") {
+                return {
+                    ...base,
+                    status: "failed",
+                    error: assistant.errorMessage || "Subagent failed",
+                };
+            }
+            if (!assistant) {
+                return { ...base, status: "failed", error: "Subagent produced no assistant response" };
+            }
+            if (request.outputSchema) {
+                let parsed;
+                try {
+                    parsed = JSON.parse(text);
+                }
+                catch {
+                    return { ...base, status: "invalid_output", error: "Subagent output is not valid JSON" };
+                }
+                if (!Value.Check(hydrateSchema(request.outputSchema), parsed)) {
+                    return {
+                        ...base,
+                        status: "invalid_output",
+                        error: "Subagent output does not match the requested schema",
+                    };
+                }
+                return {
+                    ...base,
+                    status: "completed",
+                    output: parsed,
+                };
+            }
+            if (!text) {
+                return { ...base, status: "failed", error: "Subagent produced no text output" };
+            }
+            return {
+                ...base,
+                status: "completed",
+                output: text,
+            };
+        };
+        const buildFailureResult = (err) => ({
+            ...baseRunResult(runId, modelSpec, startedAt, session.getLastRunStats()),
+            status: terminalSignal ?? "failed",
+            error: err instanceof Error ? err.message : String(err),
+        });
+        if (!terminalSignal) {
+            const promptOutcome = subagentRunDepth
+                .run(1, () => session.prompt(task, {
+                budget: {
+                    maxLlmCalls: budget.maxTurns,
+                    maxTokens: budget.maxTokens,
+                    maxCostUsd: budget.maxCostUsd,
+                    maxDurationMs: budget.maxDurationMs,
+                },
+            }))
+                .then(() => ({ ok: true }), (error) => ({ ok: false, error }));
+            const winner = await Promise.race([
+                promptOutcome.then((outcome) => ({ type: "settled", outcome })),
+                abortRequested.then(async () => {
+                    let graceTimer;
+                    const graceExpired = new Promise((resolve) => {
+                        graceTimer = setTimeout(() => resolve("expired"), SUBAGENT_ABORT_GRACE_MS);
+                    });
+                    const graceOutcome = await Promise.race([
+                        promptOutcome.then((settledOutcome) => ({
+                            type: "settled",
+                            outcome: settledOutcome,
+                        })),
+                        graceExpired.then((value) => ({ type: value })),
+                    ]);
+                    if (graceTimer)
+                        clearTimeout(graceTimer);
+                    return graceOutcome;
+                }),
+            ]);
+            if (winner.type === "expired") {
+                const cleanup = promptOutcome.then((settledOutcome) => settledOutcome.ok ? buildResult() : buildFailureResult(settledOutcome.error));
+                return { result: buildResult(true), cleanup };
+            }
+            if (!winner.outcome.ok)
+                throw winner.outcome.error;
+        }
+        return { result: buildResult() };
+    }
+    catch (err) {
+        return {
+            result: {
+                ...baseRunResult(runId, modelSpec, startedAt, sessionRef?.getLastRunStats()),
+                status: terminalSignal ?? "failed",
+                error: err instanceof Error ? err.message : String(err),
+            },
+        };
+    }
+    finally {
+        if (timeout)
+            clearTimeout(timeout);
+        request.signal?.removeEventListener("abort", onAbort);
+    }
+}
+//# sourceMappingURL=subagent-runner.js.map