@geminixiang/mikan 1.0.0-beta.9 → 1.0.0-beta.91

package/dist/harness/subagent.js

@@ -0,0 +1,613 @@
+import { randomUUID } from "node:crypto";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { contentText } from "@earendil-works/pi-ai";
+import { Type } from "typebox";
+import { Value } from "typebox/value";
+import { MikanAgentSession, copyUsage, createEmptyUsage } from "./session.js";
+import { SessionStore } from "../sessions/session-store.js";
+import * as log from "../log.js";
+import { errorMessage, isRecord } from "../unknown-values.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,
+};
+export const SUBAGENT_ABORT_GRACE_MS = 100;
+const SCHEMA_STRUCTURAL_KEYS = new Set([
+    "type",
+    "properties",
+    "required",
+    "items",
+    "enum",
+    "const",
+    "anyOf",
+    "oneOf",
+    "allOf",
+]);
+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;
+}
+function isSchemaLiteral(value) {
+    return typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+}
+function hydrateObject(schema, options) {
+    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);
+}
+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(isSchemaLiteral);
+        return literals.length > 0
+            ? Type.Union(literals.map((value) => Type.Literal(value)))
+            : Type.Unknown();
+    }
+    if ("const" in schema) {
+        return isSchemaLiteral(schema.const) ? Type.Literal(schema.const) : 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":
+            return hydrateObject(schema, options);
+        case "array":
+            return Type.Array(hydrateSchema(schema.items), 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 reportSubagentActivity(session, onActivity) {
+    let characters = 0;
+    let reportedAt = 0;
+    const report = (activity) => {
+        try {
+            onActivity(activity);
+        }
+        catch (err) {
+            log.logWarning("Subagent onActivity listener failed", String(err));
+        }
+    };
+    session.subscribe((event) => {
+        switch (event.type) {
+            case "tool_execution_start": {
+                const label = isRecord(event.args) && typeof event.args.label === "string" ? event.args.label : "";
+                report(label ? `${event.toolName}: ${label}` : event.toolName);
+                return;
+            }
+            case "tool_execution_end":
+                report("thinking");
+                return;
+            case "message_start":
+                characters = 0;
+                reportedAt = 0;
+                report("thinking");
+                return;
+            case "text_delta":
+                characters += event.delta.length;
+                if (characters - reportedAt < ACTIVITY_CHARS_STEP)
+                    return;
+                reportedAt = characters;
+                report(`writing · ${characters} chars`);
+                return;
+            case "auto_retry_start":
+                report("retrying after an error");
+                return;
+            default:
+                return;
+        }
+    });
+}
+const ACTIVITY_CHARS_STEP = 250;
+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;
+}
+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: ${errorMessage(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 (!("content" in message))
+        return "";
+    return contentText(message.content, "");
+}
+function normalizedParentContext(request, entries) {
+    if (!request.parentContext || !entries)
+        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 compaction = entries.findLast((entry) => entry.type === "compaction");
+    const visible = compaction ? entries.slice(entries.indexOf(compaction) + 1) : entries;
+    const conversation = visible.flatMap((entry) => entry.type === "message" &&
+        (entry.message.role === "user" || entry.message.role === "assistant") &&
+        messageText(entry.message)
+        ? [entry.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);
+    return [
+        "<parent_reference_context>",
+        compaction ? `Earlier summary: ${compaction.summary}` : "[Earlier parent context omitted]",
+        ...recent.map((message) => `${message.role === "user" ? "User" : "Assistant"}: ${messageText(message)}`),
+        "</parent_reference_context>",
+    ].join("\n");
+}
+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");
+}
+function baseRunResult(runId, model, startedAt, stats) {
+    const usage = stats?.usage ?? createEmptyUsage();
+    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) {
+    return messages.findLast((message) => message.role === "assistant");
+}
+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?.(copyUsage(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() { }
+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 };
+    for (const field of ["maxTurns", "maxCostUsd", "maxDurationMs"]) {
+        const cap = profile[field];
+        if (cap !== undefined)
+            budget[field] = Math.min(cap, budget[field] ?? cap);
+    }
+    if (profile.maxTokens !== undefined || budget.maxTokens !== undefined) {
+        budget.maxTokens = Math.max(profile.maxTokens ?? 0, budget.maxTokens ?? 0);
+    }
+    return {
+        ...request,
+        systemPrompt: profile.systemPrompt,
+        tools: profile.tools,
+        model: profile.model || undefined,
+        thinkingLevel: profile.thinkingLevel || undefined,
+        budget: Object.keys(budget).length > 0 ? budget : undefined,
+    };
+}
+async function prepareSubagentRun(options, request, runId, startedAt) {
+    const model = request.model
+        ? options.models.resolve(request.model.provider, request.model.id)
+        : options.defaultModel;
+    const granted = selectTools(request.tools, options.availableTools);
+    const task = formatTask(request.task, request.input, normalizedParentContext(request, options.parentEntries));
+    const session = new MikanAgentSession({
+        systemPrompt: buildSystemPrompt(request.systemPrompt, request.outputSchema, granted.map((tool) => tool.name)),
+        model,
+        thinkingLevel: request.thinkingLevel ?? options.thinkingLevel,
+        tools: granted,
+        toolContext: options.toolContext,
+        models: options.models,
+        sessionStore: await SessionStore.inMemory(),
+        settings: { compaction: { enabled: false } },
+    });
+    if (options.onActivity)
+        reportSubagentActivity(session, options.onActivity);
+    return {
+        request,
+        runId,
+        startedAt,
+        modelSpec: { provider: model.provider, id: model.id },
+        session,
+        budget: resolveBudget(request.budget),
+        task,
+    };
+}
+function buildSubagentResult(run, terminalSignal, cleanupPending = false) {
+    const { session, request, budget } = run;
+    const stats = session.getLastRunStats();
+    const assistant = finalAssistant(session.lastRunMessages);
+    const text = assistant ? contentText(assistant.content, "") : "";
+    const base = {
+        ...baseRunResult(run.runId, run.modelSpec, run.startedAt, stats),
+        text: text || undefined,
+        cleanupPending: cleanupPending || undefined,
+    };
+    if (terminalSignal) {
+        return {
+            ...base,
+            status: terminalSignal,
+            error: terminalSignal === "timeout"
+                ? `Subagent exceeded its ${budget.maxDurationMs}ms duration limit`
+                : undefined,
+        };
+    }
+    if (stats.budgetExceededReason) {
+        return { ...base, status: "budget_exceeded", error: stats.budgetExceededReason };
+    }
+    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) {
+        return text
+            ? { ...base, status: "completed", output: text }
+            : { ...base, status: "failed", error: "Subagent produced no text output" };
+    }
+    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,
+    };
+}
+function buildSubagentFailure(run, terminalSignal, err) {
+    return {
+        ...baseRunResult(run.runId, run.modelSpec, run.startedAt, run.session.getLastRunStats()),
+        status: terminalSignal ?? "failed",
+        error: errorMessage(err),
+    };
+}
+async function executeSubagentPrompt(run, abortRequested, terminalSignal) {
+    if (terminalSignal())
+        return undefined;
+    const promptOutcome = subagentRunDepth
+        .run(1, () => run.session.prompt(run.task, {
+        budget: {
+            maxLlmCalls: run.budget.maxTurns,
+            maxTokens: run.budget.maxTokens,
+            maxCostUsd: run.budget.maxCostUsd,
+        },
+    }))
+        .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 outcome = await Promise.race([
+                promptOutcome.then((settledOutcome) => ({
+                    type: "settled",
+                    outcome: settledOutcome,
+                })),
+                graceExpired.then((value) => ({ type: value })),
+            ]);
+            if (graceTimer)
+                clearTimeout(graceTimer);
+            return outcome;
+        }),
+    ]);
+    if (winner.type === "expired") {
+        const cleanup = promptOutcome.then((outcome) => outcome.ok
+            ? buildSubagentResult(run, terminalSignal())
+            : buildSubagentFailure(run, terminalSignal(), outcome.error));
+        return { result: buildSubagentResult(run, terminalSignal(), true), cleanup };
+    }
+    if (!winner.outcome.ok)
+        throw winner.outcome.error;
+    return undefined;
+}
+async function executeSubagentRun(options) {
+    const request = resolveProfile(options.request, options);
+    const runId = randomUUID();
+    const startedAt = Date.now();
+    const initialModelSpec = request.model ?? {
+        provider: options.defaultModel.provider,
+        id: options.defaultModel.id,
+    };
+    let run;
+    let terminalSignal;
+    let timeout;
+    let notifyAbort = noop;
+    const abortRequested = new Promise((resolve) => {
+        notifyAbort = resolve;
+    });
+    const abort = (reason) => {
+        if (terminalSignal)
+            return;
+        terminalSignal = reason;
+        run?.session.abort(reason);
+        notifyAbort();
+    };
+    const onAbort = () => abort("cancelled");
+    try {
+        if ((subagentRunDepth.getStore() ?? 0) >= 1) {
+            throw new Error("Nested api.subagent.run calls are not allowed");
+        }
+        run = await prepareSubagentRun(options, request, runId, startedAt);
+        request.signal?.addEventListener("abort", onAbort, { once: true });
+        if (request.signal?.aborted)
+            abort("cancelled");
+        timeout = setTimeout(() => abort("timeout"), run.budget.maxDurationMs);
+        timeout.unref();
+        const earlyResult = await executeSubagentPrompt(run, abortRequested, () => terminalSignal);
+        return earlyResult ?? { result: buildSubagentResult(run, terminalSignal) };
+    }
+    catch (err) {
+        return {
+            result: run
+                ? buildSubagentFailure(run, terminalSignal, err)
+                : {
+                    ...baseRunResult(runId, initialModelSpec, startedAt),
+                    status: terminalSignal ?? "failed",
+                    error: errorMessage(err),
+                },
+        };
+    }
+    finally {
+        if (timeout)
+            clearTimeout(timeout);
+        request.signal?.removeEventListener("abort", onAbort);
+    }
+}
+function abortError() {
+    return new DOMException("The operation was aborted", "AbortError");
+}
+export const DEFAULT_GLOBAL_SUBAGENT_SLOTS = 8;
+export class SubagentSlotPool {
+    constructor(capacity) {
+        this.capacity = capacity;
+        this.held = 0;
+        this.waiters = [];
+        if (!(capacity >= 1)) {
+            throw new Error(`SubagentSlotPool capacity must be >= 1, got ${capacity}`);
+        }
+    }
+    get inFlight() {
+        return this.held;
+    }
+    async acquire(signal) {
+        if (signal?.aborted)
+            throw abortError();
+        if (this.held < this.capacity) {
+            this.held += 1;
+            return this.releaser();
+        }
+        return new Promise((resolve, reject) => {
+            const waiter = { resolve, signal };
+            waiter.onAbort = () => {
+                const index = this.waiters.indexOf(waiter);
+                if (index < 0)
+                    return;
+                this.waiters.splice(index, 1);
+                reject(abortError());
+            };
+            signal?.addEventListener("abort", waiter.onAbort, { once: true });
+            this.waiters.push(waiter);
+        });
+    }
+    releaser() {
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            const next = this.waiters.shift();
+            if (next) {
+                next.signal?.removeEventListener("abort", next.onAbort);
+                next.resolve(this.releaser());
+                return;
+            }
+            this.held -= 1;
+        };
+    }
+}
+export function unboundedSlotPool() {
+    return new SubagentSlotPool(Number.MAX_SAFE_INTEGER);
+}
+//# sourceMappingURL=subagent.js.map