@vietor/agent-core 0.7.0

package/dist/runtime/agent.js

@@ -0,0 +1,253 @@
+import { isAbortError, mapWithConcurrency, withAbort } from "../util/async.js";
+import { MAX_PARALLEL_TOOL_CALLS, NOT_EXECUTED_PREFIX, SKILL_TOOL_NAME } from "../util/constants.js";
+import { summarizeText, toErrorMessage } from "../util/text.js";
+import { parseToolArgs, toText } from "../llm/messages.js";
+import { SessionMessages } from "./session-messages.js";
+import { COMPACT_PROMPT, renderTodoReminder, renderIncompleteTodoNudge } from "./prompts.js";
+import { toolError } from "../tools/types.js";
+export class Agent {
+    llm;
+    conversation;
+    tools;
+    cwd;
+    setTodos;
+    getTodos;
+    stallThreshold;
+    maxTurns;
+    contextLimit;
+    todoSnapshot = [];
+    resolveSkill;
+    onCompact;
+    inputTokens = 0;
+    outputTokens = 0;
+    constructor(opts) {
+        this.llm = opts.llm;
+        this.conversation = opts.conversation;
+        this.tools = opts.tools;
+        this.cwd = opts.cwd;
+        this.setTodos = opts.setTodos;
+        this.getTodos = opts.getTodos;
+        this.stallThreshold = opts.stallThreshold;
+        this.maxTurns = opts.maxTurns;
+        this.contextLimit = opts.contextLimit;
+        this.resolveSkill = opts.resolveSkill;
+        this.onCompact = opts.onCompact;
+    }
+    get contextTokens() {
+        return this.conversation.getEstimatedTokens();
+    }
+    get usage() {
+        return { inputTokens: this.inputTokens, outputTokens: this.outputTokens };
+    }
+    resetUsage() {
+        this.inputTokens = 0;
+        this.outputTokens = 0;
+    }
+    get model() {
+        return this.llm.model;
+    }
+    get thinkingEffort() {
+        return this.llm.thinkingEffort;
+    }
+    clear() {
+        this.conversation.clear();
+    }
+    export() {
+        return this.conversation.export();
+    }
+    async compact(onEvent, signal) {
+        const history = this.conversation.toLLM().slice(1);
+        if (history.length === 0)
+            return "ok";
+        const request = [...history];
+        const todos = this.getTodos();
+        if (todos.length) {
+            request.push({ role: "user", content: renderTodoReminder(todos) });
+        }
+        request.push({ role: "user", content: COMPACT_PROMPT });
+        const chat = await this.chatOnce({ messages: request, tools: [], thinking: false, onEvent, signal }, () => onEvent?.({ type: "interrupted" }));
+        if (!chat.ok)
+            return chat.status;
+        if (signal?.aborted)
+            return "aborted";
+        const compactText = toText(chat.message.content);
+        if (!compactText) {
+            onEvent?.({ type: "error", text: "compact failed: LLM returned no summary text" });
+            return "error";
+        }
+        this.conversation.compact(compactText);
+        this.onCompact?.();
+        return "ok";
+    }
+    async run(userInput, onEvent, signal) {
+        return this.runTurn({ role: "user", content: userInput }, onEvent, signal);
+    }
+    async runSkill(skill, onEvent, signal) {
+        return this.runTurn({ role: "skill", name: skill.name, content: skill.prompt }, onEvent, signal);
+    }
+    async runTurn(msg, onEvent, signal) {
+        this.conversation.add(msg);
+        this.conversation.createSnapshot();
+        this.todoSnapshot = this.getTodos();
+        let aborted = false;
+        const onAbort = () => {
+            if (aborted)
+                return;
+            aborted = true;
+            this.conversation.restoreFromSnapshot();
+            this.setTodos([...this.todoSnapshot]);
+            onEvent?.({ type: "interrupted" });
+        };
+        let status;
+        try {
+            status = await withAbort(this.loop(onEvent, signal), signal);
+            if (status === "aborted") {
+                onAbort();
+            }
+            return status;
+        }
+        catch (e) {
+            if (signal?.aborted || isAbortError(e)) {
+                onAbort();
+                return "aborted";
+            }
+            throw e;
+        }
+        finally {
+            this.conversation.clearSnapshot();
+            this.todoSnapshot = [];
+            this.conversation.normalizeInterruptedToolCalls();
+            this.conversation.collapseSkills();
+        }
+    }
+    async loop(onEvent, signal) {
+        let lastSig = "";
+        let stall = 0;
+        let turns = 0;
+        let textOnlyStreak = 0;
+        let pendingNudge = "";
+        while (true) {
+            if (this.conversation.getEstimatedTokens() > this.contextLimit) {
+                onEvent?.({ type: "notice", text: "auto-compacting context" });
+                const compactStatus = await this.compact((e) => { if (e.type === "error")
+                    onEvent?.(e); }, signal);
+                if (compactStatus !== "ok")
+                    return compactStatus;
+            }
+            const messages = this.conversation.toLLM();
+            const todos = this.getTodos();
+            if (todos.length) {
+                messages.push({ role: "user", content: renderTodoReminder(todos) });
+            }
+            if (pendingNudge) {
+                messages.push({ role: "user", content: pendingNudge });
+                pendingNudge = "";
+            }
+            const chat = await this.chatOnce({ messages, tools: this.tools.schemas(), onEvent, signal }, () => { });
+            if (!chat.ok)
+                return chat.status;
+            if (signal?.aborted)
+                return "aborted";
+            const msg = chat.message;
+            this.conversation.add(msg);
+            this.conversation.collapseSkills();
+            if (!msg.tool_calls?.length) {
+                if (todos.length > 0 && todos.some(t => t.status !== "completed")) {
+                    if (++textOnlyStreak >= this.stallThreshold) {
+                        onEvent?.({ type: "error", text: `agent stalled: ${textOnlyStreak} text-only responses with incomplete tasks` });
+                        return "stalled";
+                    }
+                    pendingNudge = renderIncompleteTodoNudge(todos);
+                    continue;
+                }
+                return "ok";
+            }
+            textOnlyStreak = 0;
+            const sig = msg.tool_calls
+                .map((c) => `${c.function.name}:${c.function.arguments}`)
+                .join("|");
+            stall = sig === lastSig ? stall + 1 : 1;
+            lastSig = sig;
+            if (stall >= this.stallThreshold) {
+                const reason = `stalled: repeated identical tool calls: ${summarizeText(sig, 200)}`;
+                this.resolvePendingToolCalls(msg.tool_calls, reason);
+                onEvent?.({ type: "error", text: `agent stalled: ${reason}` });
+                return "stalled";
+            }
+            if (++turns >= this.maxTurns) {
+                this.resolvePendingToolCalls(msg.tool_calls, `max turns reached (${this.maxTurns})`);
+                onEvent?.({ type: "error", text: `agent exceeded max turns (${this.maxTurns})` });
+                return "maxTurns";
+            }
+            const results = await this.runToolCalls(msg.tool_calls, onEvent, signal);
+            if (!results)
+                return "aborted";
+            for (const r of results) {
+                this.conversation.add({ role: "tool", tool_call_id: r.id, content: r.content, resultSummary: r.resultSummary, isError: r.isError });
+            }
+            for (let i = 0; i < msg.tool_calls.length; i++) {
+                const tc = msg.tool_calls[i];
+                if (tc.function.name !== SKILL_TOOL_NAME)
+                    continue;
+                const name = results[i].args.name;
+                if (typeof name !== "string" || !name)
+                    continue;
+                const skill = this.resolveSkill?.(name);
+                if (!skill)
+                    continue;
+                this.conversation.add({ role: "skill", name: skill.name, content: skill.prompt });
+                onEvent?.({ type: "skill", name: skill.name });
+            }
+        }
+    }
+    resolvePendingToolCalls(calls, reason) {
+        for (const tc of calls) {
+            this.conversation.add({ role: "tool", tool_call_id: tc.id, content: `${NOT_EXECUTED_PREFIX}${reason})`, isError: true });
+        }
+    }
+    async chatOnce(opts, onAbort) {
+        try {
+            const message = await withAbort(this.llm.chat({
+                messages: opts.messages,
+                tools: opts.tools,
+                thinking: opts.thinking,
+                onDelta: (text) => opts.onEvent?.({ type: "assistant_delta", text }),
+                onThinking: (text) => opts.onEvent?.({ type: "thinking_delta", text }),
+                onRetry: (attempt, max, error) => opts.onEvent?.({ type: "retry", attempt, max, reason: toErrorMessage(error) }),
+                onUsage: (inputTokens, outputTokens) => {
+                    this.inputTokens = inputTokens;
+                    this.outputTokens = outputTokens;
+                },
+                signal: opts.signal,
+            }), opts.signal);
+            return { ok: true, message };
+        }
+        catch (e) {
+            if (opts.signal?.aborted || isAbortError(e)) {
+                onAbort();
+                return { ok: false, status: "aborted" };
+            }
+            opts.onEvent?.({ type: "error", text: toErrorMessage(e) });
+            return { ok: false, status: "error" };
+        }
+    }
+    async runToolCalls(calls, onEvent, signal) {
+        const results = await mapWithConcurrency(calls, MAX_PARALLEL_TOOL_CALLS, (call) => this.executeToolCall(call, onEvent, signal), signal);
+        return signal?.aborted ? null : results;
+    }
+    async executeToolCall(call, onEvent, signal) {
+        const parsed = parseToolArgs(call.function.arguments);
+        const args = parsed.ok ? parsed.args : {};
+        const argsError = parsed.ok ? undefined : toolError(`invalid arguments: ${parsed.error}`);
+        const argsSummary = this.tools.summarizeArgs(call.function.name, args);
+        onEvent?.({ type: "tool_start", id: call.id, name: call.function.name, argsSummary });
+        const ctx = { signal, cwd: this.cwd };
+        const start = performance.now();
+        const result = argsError ?? await this.tools.execute(call.function.name, args, ctx);
+        const duration = performance.now() - start;
+        const resultSummary = this.tools.summarizeResult(call.function.name, result, duration);
+        if (!signal?.aborted)
+            onEvent?.({ type: "tool_end", id: call.id, result: result.content, isError: result.isError, resultSummary });
+        return { id: call.id, content: result.content, resultSummary, isError: result.isError, args };
+    }
+}

package/dist/runtime/events.d.ts

@@ -0,0 +1,69 @@
+export interface RunMetrics {
+    running: boolean;
+    elapsed: number;
+    thinkingElapsed: number;
+    replyElapsed: number;
+    inputTokens: number;
+    outputTokens: number;
+}
+export declare const INITIAL_RUN_METRICS: RunMetrics;
+export type TimelineEvent = {
+    type: "user";
+    text: string;
+} | {
+    type: "skill";
+    name: string;
+} | {
+    type: "assistant";
+    text: string;
+} | {
+    type: "tool";
+    id: string;
+    name: string;
+    argsSummary: string;
+    result: string | null;
+    isError?: boolean;
+    resultSummary?: string;
+} | {
+    type: "retry";
+    attempt: number;
+    max: number;
+    reason: string;
+} | {
+    type: "error";
+    text: string;
+} | {
+    type: "interrupted";
+} | {
+    type: "question";
+    id: string;
+    text: string;
+    options: string[];
+    answer: string | null;
+} | {
+    type: "notice";
+    text: string;
+};
+export type StreamEvent = {
+    type: "assistant_delta";
+    text: string;
+} | {
+    type: "thinking_delta";
+    text: string;
+} | {
+    type: "thinking_cleared";
+} | {
+    type: "tool_start";
+    id: string;
+    name: string;
+    argsSummary: string;
+} | {
+    type: "tool_end";
+    id: string;
+    result: string;
+    isError?: boolean;
+    resultSummary?: string;
+} | ({
+    type: "run_metrics";
+} & RunMetrics);
+export type SessionEvent = TimelineEvent | StreamEvent;

package/dist/runtime/events.js

@@ -0,0 +1 @@
+export const INITIAL_RUN_METRICS = { running: false, elapsed: 0, thinkingElapsed: 0, replyElapsed: 0, inputTokens: 0, outputTokens: 0 };

package/dist/runtime/prompts.d.ts

@@ -0,0 +1,5 @@
+import type { Todo } from "../tools/types.js";
+export declare const TOOL_USE_PROMPT: string;
+export declare const COMPACT_PROMPT: string;
+export declare function renderTodoReminder(todos: readonly Todo[]): string;
+export declare function renderIncompleteTodoNudge(todos: readonly Todo[]): string;

package/dist/runtime/prompts.js

@@ -0,0 +1,45 @@
+export const TOOL_USE_PROMPT = [
+    "Tool-Use Guidelines:",
+    "The user's instructions in the preceding sections take precedence over these defaults.",
+    "",
+    "- Prefer emitting independent tool calls together in one turn so they run concurrently (2-8 calls per turn is normal); do not batch calls that depend on a prior result or that modify the same file or resource.",
+    "- Scale planning: when a task involves many independent items (queries, reads, searches), estimate the count up front and pick a strategy: a few — do them directly; more — spread over a few turns with several calls per turn.",
+    "- A run has a limited budget of tool-calling turns. If a task needs far more turns than the budget, do not work item-by-item in the main loop — narrow the scope.",
+    "- For file operations (read/write/edit/glob/grep) and fetching URLs, use the dedicated tool. Fall back to Shell only when no dedicated tool covers the task and Shell is available. A runtime error does not make Shell the fallback; do not retry that same operation through Shell.",
+    "- If a tool call fails, read the error, adjust the arguments or approach, and continue; do not repeat the identical call and do not abandon the task over a single failure.",
+].join("\n");
+export const COMPACT_PROMPT = [
+    "Summarize the conversation above for context continuation. Preserve:\n",
+    "1. Primary goal, sub-goals, constraints, acceptance criteria.\n",
+    "2. Decisions and rationale (including rejected approaches).\n",
+    "3. Files (paths, signatures, config values, key code snippets).\n",
+    "4. Tool calls and relevant results (commands, search hits, test output).\n",
+    "5. Errors/failures and how they were resolved.\n",
+    "6. Current progress: what is done, verified, and in-progress state.\n",
+    "7. Pending tasks, open questions, concrete next step.\n",
+    "Discard: completed small talk, verbose tool outputs already absorbed, resolved dead ends. The full conversation will be replaced by this summary, so anything omitted is lost — keep only what the next turn needs to continue without re-reading history.\n",
+    "Concise but thorough; keep technical specifics; use the conversation language. Aim for roughly 500-1000 tokens — under 1% of the original length, never a generic recap; technical specifics over prose. ",
+    "Start with \"Summary of conversation so far\":",
+].join("");
+const STATUS_GLYPHS = {
+    pending: "○",
+    inProgress: "◐",
+    completed: "✓",
+};
+export function renderTodoReminder(todos) {
+    const items = todos.map((t) => {
+        return `${STATUS_GLYPHS[t.status]} ${t.content}`;
+    });
+    const focus = todos.find((t) => t.status === "inProgress");
+    const focusLine = focus ? ` Current focus: ${focus.content}` : "";
+    const incomplete = todos.filter(t => t.status !== "completed");
+    const warning = incomplete.length > 0
+        ? ` ${incomplete.length} incomplete. You MUST complete EVERY task before your final text-only response — update status via TodoWrite after each task finishes.`
+        : "";
+    return `<system-reminder>Tasks: ${items.join(" | ")}${focusLine}${warning}</system-reminder>`;
+}
+export function renderIncompleteTodoNudge(todos) {
+    const incomplete = todos.filter(t => t.status !== "completed");
+    const names = incomplete.map(t => `"${t.content}"`).join(", ");
+    return `<system-reminder>STOP! You have ${incomplete.length} incomplete task(s): ${names}. Use tools to complete them. Call TodoWrite to mark each one completed before your final text response.</system-reminder>`;
+}

package/dist/runtime/session-messages.d.ts

@@ -0,0 +1,43 @@
+import { type LLMAssistantMessage, type LLMMessage } from "../llm/messages.js";
+export type SessionMessage = {
+    role: "system";
+    content: string;
+} | {
+    role: "user";
+    content: string;
+} | {
+    role: "skill";
+    name: string;
+    content: string;
+} | LLMAssistantMessage | {
+    role: "tool";
+    tool_call_id: string;
+    content: string;
+    resultSummary?: string;
+    isError?: boolean;
+};
+export declare function lastAssistantText(messages: SessionMessage[]): string;
+export declare class SessionMessages {
+    private system;
+    private readonly systemEstimateTokens;
+    private messages;
+    private estimatedTokens;
+    private collapsedCount;
+    private snapshot?;
+    private llmCache;
+    constructor(system: string);
+    getEstimatedTokens(): number;
+    add(msg: SessionMessage): void;
+    toLLM(): LLMMessage[];
+    export(): SessionMessage[];
+    import(messages: SessionMessage[]): void;
+    normalizeInterruptedToolCalls(): void;
+    clear(): void;
+    compact(summary: string): void;
+    private resetMessages;
+    collapseSkills(): void;
+    private collapseOne;
+    createSnapshot(): void;
+    restoreFromSnapshot(): void;
+    clearSnapshot(): void;
+}

package/dist/runtime/session-messages.js

@@ -0,0 +1,174 @@
+import { toText } from "../llm/messages.js";
+import { INTERRUPTED_TOOL_CONTENT } from "../util/constants.js";
+function estimateTokens(text) {
+    if (!text)
+        return 0;
+    let tokens = 0;
+    for (let i = 0; i < text.length; i++) {
+        tokens += text.charCodeAt(i) < 0x80 ? 1 : 4;
+    }
+    return Math.round(tokens / 4);
+}
+export function lastAssistantText(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const m = messages[i];
+        if (m.role !== "assistant")
+            continue;
+        const text = toText(m.content);
+        if (text)
+            return text;
+    }
+    return "";
+}
+function messageText(msg) {
+    const parts = [];
+    const t = toText(msg.content);
+    if (t)
+        parts.push(t);
+    if ("tool_calls" in msg && msg.tool_calls) {
+        for (const tc of msg.tool_calls) {
+            if (tc.function?.name)
+                parts.push(tc.function.name);
+            if (tc.function?.arguments)
+                parts.push(tc.function.arguments);
+        }
+    }
+    if ("thinking" in msg && msg.thinking) {
+        for (const t of msg.thinking) {
+            if (t.type === "thinking")
+                parts.push(t.thinking);
+        }
+    }
+    return parts.join(" ");
+}
+function toLLMMessage(m) {
+    if (m.role === "tool")
+        return { role: "tool", tool_call_id: m.tool_call_id, content: m.content };
+    if (m.role === "skill")
+        return { role: "user", name: m.name, content: m.content };
+    return m;
+}
+export class SessionMessages {
+    system;
+    systemEstimateTokens;
+    messages = [];
+    estimatedTokens = 0;
+    collapsedCount = 0;
+    snapshot;
+    llmCache = null;
+    constructor(system) {
+        this.system = system;
+        this.systemEstimateTokens = estimateTokens(system);
+        this.estimatedTokens = this.systemEstimateTokens;
+    }
+    getEstimatedTokens() {
+        return this.estimatedTokens;
+    }
+    add(msg) {
+        this.messages.push(msg);
+        this.estimatedTokens += estimateTokens(messageText(msg));
+        if (this.llmCache) {
+            this.llmCache.push(toLLMMessage(msg));
+        }
+    }
+    toLLM() {
+        if (this.llmCache) {
+            return this.llmCache.slice();
+        }
+        const result = new Array(this.messages.length + 1);
+        result[0] = { role: "system", content: this.system };
+        for (let i = 0; i < this.messages.length; i++) {
+            result[i + 1] = toLLMMessage(this.messages[i]);
+        }
+        this.llmCache = result;
+        return result.slice();
+    }
+    export() {
+        return this.messages.slice();
+    }
+    import(messages) {
+        this.resetMessages(messages.slice(), messages.reduce((sum, m) => sum + estimateTokens(messageText(m)), 0));
+        this.normalizeInterruptedToolCalls();
+    }
+    normalizeInterruptedToolCalls() {
+        const out = [];
+        let changed = false;
+        let addedTokens = 0;
+        for (let i = 0; i < this.messages.length; i++) {
+            const m = this.messages[i];
+            out.push(m);
+            if (m.role !== "assistant" || !m.tool_calls?.length)
+                continue;
+            const satisfied = new Set();
+            while (i + 1 < this.messages.length) {
+                const next = this.messages[i + 1];
+                if (next.role !== "tool")
+                    break;
+                i++;
+                out.push(next);
+                satisfied.add(next.tool_call_id);
+            }
+            for (const tc of m.tool_calls) {
+                if (satisfied.has(tc.id))
+                    continue;
+                out.push({ role: "tool", tool_call_id: tc.id, content: INTERRUPTED_TOOL_CONTENT });
+                changed = true;
+                addedTokens += estimateTokens(INTERRUPTED_TOOL_CONTENT);
+            }
+        }
+        if (changed) {
+            this.messages = out;
+            this.estimatedTokens += addedTokens;
+            this.llmCache = null;
+        }
+    }
+    clear() {
+        this.resetMessages([], 0);
+    }
+    compact(summary) {
+        this.resetMessages([{ role: "assistant", content: summary }], estimateTokens(summary), true);
+    }
+    resetMessages(messages, extraTokens, keepSnapshot = false) {
+        this.messages = messages;
+        this.estimatedTokens = this.systemEstimateTokens + extraTokens;
+        this.collapsedCount = 0;
+        if (!keepSnapshot)
+            this.clearSnapshot();
+        this.llmCache = null;
+    }
+    collapseSkills() {
+        for (let i = this.collapsedCount; i < this.messages.length; i++) {
+            const m = this.messages[i];
+            if (m.role === "skill")
+                this.collapseOne(i, m);
+        }
+        this.collapsedCount = this.messages.length;
+    }
+    collapseOne(index, m) {
+        const before = estimateTokens(messageText(m));
+        const collapsed = `<skill "${m.name}" invoked - its instructions were followed above>`;
+        this.messages[index] = { ...m, content: collapsed };
+        this.estimatedTokens += estimateTokens(collapsed) - before;
+        this.llmCache = null;
+    }
+    createSnapshot() {
+        this.snapshot = {
+            messages: this.messages.slice(),
+            estimatedTokens: this.estimatedTokens,
+            collapsedCount: this.collapsedCount,
+        };
+    }
+    restoreFromSnapshot() {
+        const snap = this.snapshot;
+        if (snap) {
+            this.messages = snap.messages.slice();
+            this.estimatedTokens = snap.estimatedTokens;
+            this.collapsedCount = snap.collapsedCount;
+            this.clearSnapshot();
+            this.llmCache = null;
+        }
+    }
+    clearSnapshot() {
+        this.snapshot = undefined;
+    }
+}