@vietor/agent-core 0.7.0

package/dist/runtime/session.d.ts

@@ -0,0 +1,102 @@
+import type { LLMClient, LLMConfig } from "../llm/types.js";
+import type { MCPServerManager } from "../mcp/manager.js";
+import type { MCPServerConfig, MCPServerInfo } from "../mcp/types.js";
+import type { Skill } from "../skills/loader.js";
+import { type BuiltinToolsOptions, type ToolRegistry } from "../tools/registry.js";
+import type { Todo, Tool } from "../tools/types.js";
+import { type SessionEvent, type TimelineEvent } from "./events.js";
+import type { MCPClientInfo } from "../mcp/types.js";
+import { type RunStatus } from "./agent.js";
+import { type SessionMessage } from "./session-messages.js";
+export interface SessionOptions {
+    systemPrompt: string;
+    llm: LLMConfig;
+    cwd?: string;
+    tools?: Tool[];
+    skills?: Skill[];
+    mcpServers?: Record<string, MCPServerConfig>;
+    builtInTools?: BuiltinToolsOptions | false;
+    clientInfo?: MCPClientInfo;
+    sessionId?: string;
+    maxTurns?: number;
+    stallThreshold?: number;
+}
+export interface SessionDeps extends Omit<SessionOptions, "llm" | "tools" | "mcpServers"> {
+    llm: LLMClient;
+    tools: ToolRegistry;
+    mcp: MCPServerManager;
+    contextLimit: number;
+}
+export interface SessionView {
+    timeline: readonly TimelineEvent[];
+    todos: readonly Todo[];
+}
+export interface SessionState {
+    messages: SessionMessage[];
+    todos: Todo[];
+}
+export interface PromptResult {
+    status: RunStatus;
+    reply: string;
+}
+export declare class SessionBusyError extends Error {
+    constructor();
+}
+export declare class Session {
+    private agent;
+    private mcp;
+    private skillsMap;
+    private resolveSkill;
+    private timelineStore;
+    private todoStore;
+    private stream;
+    private questionQueue;
+    private runTimer;
+    private runMetrics;
+    private abortController;
+    private timer;
+    private conversation;
+    private tools;
+    readonly cwd: string;
+    readonly sessionId: string;
+    private viewCache;
+    private eventListeners;
+    subscribe: (listener: () => void) => (() => void);
+    getSnapshot: () => SessionView;
+    onEvent: (listener: (e: SessionEvent) => void) => (() => void);
+    addNotice: (text: string) => void;
+    addError: (text: string) => void;
+    runSkill: (name: string) => Promise<boolean>;
+    private emit;
+    get pendingQuestion(): Extract<TimelineEvent, {
+        type: "question";
+    }> | undefined;
+    get running(): boolean;
+    get contextTokens(): number;
+    get model(): string;
+    get thinkingEffort(): import("../llm/types.js").LLMThinkingEffort;
+    get contextLimit(): number;
+    get mcpServers(): readonly MCPServerInfo[];
+    get skills(): readonly Skill[];
+    constructor(deps: SessionDeps);
+    private start;
+    private run;
+    private clearCompletedTodos;
+    private emitRunMetrics;
+    private handleEvent;
+    private flushStreaming;
+    private flushThinking;
+    connectMCP(servers: Record<string, MCPServerConfig>): Promise<void>;
+    dispose(): void;
+    private rejectIfBusy;
+    clear(): void;
+    export(): SessionMessage[];
+    exportState(): SessionState;
+    private rebuildTimeline;
+    importState(state: SessionState): void;
+    compact(): Promise<RunStatus>;
+    abort(): void;
+    submitAnswer(id: string, answer: string): void;
+    prompt(text: string): Promise<PromptResult>;
+    private ask;
+}

package/dist/runtime/session.js

@@ -0,0 +1,375 @@
+import { randomUUID } from "node:crypto";
+import { isAbortError } from "../util/async.js";
+import { toErrorMessage } from "../util/text.js";
+import { DEFAULT_MAX_TURNS, DEFAULT_STALL_THRESHOLD } from "../util/constants.js";
+import { registerBuiltinTools } from "../tools/registry.js";
+import { INITIAL_RUN_METRICS } from "./events.js";
+import { Agent } from "./agent.js";
+import { SessionMessages } from "./session-messages.js";
+import { Emitter } from "../util/emitter.js";
+import { TimelineStore, toTimelineEntries } from "./timeline.js";
+import { TodoStore } from "./todo-store.js";
+import { createSubAgentRunner } from "./sub-agent-runner.js";
+class StreamBuffer {
+    streamingText = "";
+    thinkingText = "";
+    replyStart = null;
+    lastReplyText = "";
+    get reply() {
+        return this.lastReplyText;
+    }
+    get firstReplyAt() {
+        return this.replyStart;
+    }
+    begin() {
+        this.streamingText = "";
+        this.thinkingText = "";
+        this.replyStart = null;
+        this.lastReplyText = "";
+    }
+    push(text) {
+        if (this.replyStart === null)
+            this.replyStart = Date.now();
+        this.streamingText += text;
+    }
+    pushThinking(text) {
+        this.thinkingText += text;
+    }
+    flush() {
+        const assistant = this.flushAssistant();
+        const thinkingCleared = this.flushThinking();
+        return { assistant, thinkingCleared };
+    }
+    flushForRetry() {
+        this.streamingText = "";
+        return { thinkingCleared: this.flushThinking() };
+    }
+    interrupt() {
+        this.lastReplyText = this.streamingText;
+        this.streamingText = "";
+        return this.flushThinking();
+    }
+    discardStreamedText() {
+        this.streamingText = "";
+    }
+    flushThinking() {
+        if (!this.thinkingText)
+            return false;
+        this.thinkingText = "";
+        return true;
+    }
+    flushAssistant() {
+        if (!this.streamingText)
+            return null;
+        this.lastReplyText = this.streamingText;
+        const text = this.streamingText;
+        this.streamingText = "";
+        return text;
+    }
+}
+class QuestionQueue {
+    questionSeq = 0;
+    resolvers = new Map();
+    ask() {
+        const id = `q${++this.questionSeq}`;
+        const promise = new Promise((resolve) => {
+            this.resolvers.set(id, resolve);
+        });
+        return { id, promise };
+    }
+    submit(id, answer) {
+        const resolve = this.resolvers.get(id);
+        if (resolve) {
+            this.resolvers.delete(id);
+            resolve(answer);
+        }
+    }
+    resolveAll(answer) {
+        const ids = [...this.resolvers.keys()];
+        for (const id of ids) {
+            this.submit(id, answer);
+        }
+        return ids;
+    }
+}
+class RunTimer {
+    startTime = 0;
+    begin() {
+        this.startTime = Date.now();
+    }
+    metrics(usage, firstReplyAt, running) {
+        const now = Date.now();
+        const elapsed = Math.floor((now - this.startTime) / 1000);
+        if (firstReplyAt === null) {
+            return { running, elapsed, thinkingElapsed: elapsed, replyElapsed: 0, ...usage };
+        }
+        return {
+            running,
+            elapsed,
+            thinkingElapsed: Math.floor((firstReplyAt - this.startTime) / 1000),
+            replyElapsed: Math.floor((now - firstReplyAt) / 1000),
+            ...usage,
+        };
+    }
+}
+export class SessionBusyError extends Error {
+    constructor() {
+        super("session is busy; another run is in progress");
+        this.name = "SessionBusyError";
+    }
+}
+export class Session {
+    agent;
+    mcp;
+    skillsMap = new Map();
+    resolveSkill = (name) => this.skillsMap.get(name);
+    timelineStore = new TimelineStore();
+    todoStore = new TodoStore();
+    stream = new StreamBuffer();
+    questionQueue = new QuestionQueue();
+    runTimer = new RunTimer();
+    runMetrics = INITIAL_RUN_METRICS;
+    abortController = null;
+    timer;
+    conversation;
+    tools;
+    cwd;
+    sessionId;
+    viewCache = null;
+    eventListeners = new Emitter();
+    subscribe = (listener) => {
+        const on = () => { this.viewCache = null; listener(); };
+        const unsubscribeTimeline = this.timelineStore.subscribe(on);
+        const unsubscribeTodos = this.todoStore.subscribe(on);
+        return () => { unsubscribeTimeline(); unsubscribeTodos(); };
+    };
+    getSnapshot = () => {
+        if (!this.viewCache) {
+            this.viewCache = { timeline: this.timelineStore.all, todos: this.todoStore.all };
+        }
+        return this.viewCache;
+    };
+    onEvent = (listener) => this.eventListeners.subscribe(listener);
+    addNotice = (text) => {
+        this.emit({ type: "notice", text });
+    };
+    addError = (text) => {
+        this.emit({ type: "error", text });
+    };
+    runSkill = async (name) => {
+        this.rejectIfBusy();
+        const skill = this.skillsMap.get(name);
+        if (!skill)
+            return false;
+        await this.start({ type: "skill", name: skill.name }, (signal) => this.agent.runSkill(skill, this.handleEvent, signal));
+        return true;
+    };
+    emit = (e) => {
+        this.timelineStore.applyEvent(e);
+        this.eventListeners.notify(e);
+    };
+    get pendingQuestion() {
+        return this.timelineStore.latestUnansweredQuestion;
+    }
+    get running() {
+        return this.abortController !== null;
+    }
+    get contextTokens() {
+        return this.agent.contextTokens;
+    }
+    get model() {
+        return this.agent.model;
+    }
+    get thinkingEffort() {
+        return this.agent.thinkingEffort;
+    }
+    get contextLimit() {
+        return this.agent.contextLimit;
+    }
+    get mcpServers() {
+        return this.mcp.list();
+    }
+    get skills() {
+        return [...this.skillsMap.values()];
+    }
+    constructor(deps) {
+        this.conversation = new SessionMessages(deps.systemPrompt);
+        this.tools = deps.tools;
+        this.cwd = deps.cwd ?? process.cwd();
+        this.sessionId = deps.sessionId ?? randomUUID();
+        for (const s of deps.skills ?? [])
+            this.skillsMap.set(s.name, s);
+        registerBuiltinTools(this.tools, deps.builtInTools, {
+            ask: (q, o) => this.ask(q, o),
+            setTodos: (t) => this.todoStore.set(t),
+            resolveSkill: deps.skills?.length ? this.resolveSkill : undefined,
+            subAgent: {
+                runSubAgent: (systemPrompt, task, signal) => createSubAgentRunner({
+                    llm: deps.llm,
+                    tools: this.tools,
+                    cwd: this.cwd,
+                    maxTurns: deps.maxTurns ?? DEFAULT_MAX_TURNS,
+                    stallThreshold: deps.stallThreshold ?? DEFAULT_STALL_THRESHOLD,
+                    contextLimit: deps.contextLimit,
+                })(systemPrompt, task, signal),
+            },
+        });
+        this.agent = new Agent({
+            llm: deps.llm,
+            conversation: this.conversation,
+            tools: this.tools,
+            cwd: this.cwd,
+            setTodos: (t) => this.todoStore.set(t),
+            getTodos: () => this.todoStore.all,
+            stallThreshold: deps.stallThreshold ?? DEFAULT_STALL_THRESHOLD,
+            maxTurns: deps.maxTurns ?? DEFAULT_MAX_TURNS,
+            contextLimit: deps.contextLimit,
+            resolveSkill: this.resolveSkill,
+            onCompact: () => {
+                this.stream.discardStreamedText();
+                this.rebuildTimeline();
+            },
+        });
+        this.mcp = deps.mcp;
+    }
+    start(event, runFn) {
+        this.emit(event);
+        return this.run(runFn);
+    }
+    async run(runFn) {
+        this.stream.begin();
+        this.runTimer.begin();
+        this.abortController = new AbortController();
+        this.runMetrics = { ...INITIAL_RUN_METRICS, running: true };
+        this.agent.resetUsage();
+        this.emitRunMetrics();
+        this.timer = setInterval(() => {
+            this.runMetrics = this.runTimer.metrics(this.agent.usage, this.stream.firstReplyAt, true);
+            this.emitRunMetrics();
+        }, 1000);
+        let status = "ok";
+        try {
+            status = await runFn(this.abortController.signal);
+            this.flushStreaming();
+        }
+        catch (e) {
+            status = isAbortError(e) ? "aborted" : "error";
+            this.flushStreaming();
+            if (status !== "aborted") {
+                this.emit({ type: "error", text: toErrorMessage(e) });
+            }
+        }
+        finally {
+            clearInterval(this.timer);
+            this.timer = undefined;
+            this.abortController = null;
+            this.timelineStore.markPendingToolsAborted();
+            this.runMetrics = this.runTimer.metrics(this.agent.usage, this.stream.firstReplyAt, false);
+            this.emitRunMetrics();
+            this.flushThinking();
+            this.clearCompletedTodos();
+        }
+        return { status, reply: this.stream.reply };
+    }
+    clearCompletedTodos() {
+        if (this.todoStore.all.length > 0 && this.todoStore.all.every((t) => t.status === "completed")) {
+            this.todoStore.set([]);
+        }
+    }
+    emitRunMetrics() {
+        this.emit({ type: "run_metrics", ...this.runMetrics });
+    }
+    handleEvent = (e) => {
+        switch (e.type) {
+            case "assistant_delta":
+                this.stream.push(e.text);
+                break;
+            case "thinking_delta":
+                this.stream.pushThinking(e.text);
+                break;
+            case "retry": {
+                const { thinkingCleared } = this.stream.flushForRetry();
+                if (thinkingCleared)
+                    this.emit({ type: "thinking_cleared" });
+                break;
+            }
+            case "tool_start":
+            case "error":
+                this.flushStreaming();
+                break;
+            case "interrupted":
+                if (this.stream.interrupt())
+                    this.emit({ type: "thinking_cleared" });
+                break;
+        }
+        this.emit(e);
+    };
+    flushStreaming() {
+        const { assistant, thinkingCleared } = this.stream.flush();
+        if (assistant !== null)
+            this.emit({ type: "assistant", text: assistant });
+        if (thinkingCleared)
+            this.emit({ type: "thinking_cleared" });
+    }
+    flushThinking() {
+        if (this.stream.flushThinking())
+            this.emit({ type: "thinking_cleared" });
+    }
+    async connectMCP(servers) {
+        await this.mcp.connect(servers);
+    }
+    dispose() {
+        this.abort();
+        this.mcp.kill();
+    }
+    rejectIfBusy() {
+        if (this.abortController !== null)
+            throw new SessionBusyError();
+    }
+    clear() {
+        this.rejectIfBusy();
+        this.agent.clear();
+        this.timelineStore.clear();
+        this.todoStore.set([]);
+    }
+    export() {
+        return this.agent.export();
+    }
+    exportState() {
+        return { messages: this.conversation.export(), todos: [...this.todoStore.all] };
+    }
+    rebuildTimeline() {
+        this.timelineStore.rebuild(toTimelineEntries(this.conversation.export(), (n, a) => this.tools.summarizeArgs(n, a)));
+        this.viewCache = null;
+    }
+    importState(state) {
+        this.rejectIfBusy();
+        this.conversation.import(state.messages);
+        this.todoStore.set(state.todos);
+        this.rebuildTimeline();
+    }
+    async compact() {
+        this.rejectIfBusy();
+        const { status } = await this.run((signal) => this.agent.compact(this.handleEvent, signal));
+        return status;
+    }
+    abort() {
+        this.abortController?.abort();
+        for (const id of this.questionQueue.resolveAll("")) {
+            this.timelineStore.setAnswer(id, "");
+        }
+    }
+    submitAnswer(id, answer) {
+        this.questionQueue.submit(id, answer);
+        this.timelineStore.setAnswer(id, answer);
+    }
+    async prompt(text) {
+        this.rejectIfBusy();
+        return this.start({ type: "user", text }, (signal) => this.agent.run(text, this.handleEvent, signal));
+    }
+    ask(text, options) {
+        const { id, promise } = this.questionQueue.ask();
+        this.emit({ type: "question", id, text, options, answer: null });
+        return promise;
+    }
+}

package/dist/runtime/sub-agent-runner.d.ts

@@ -0,0 +1,18 @@
+import { type SessionMessage } from "./session-messages.js";
+import { type RunStatus } from "./agent.js";
+import type { LLMClient } from "../llm/types.js";
+import { ToolRegistry } from "../tools/registry.js";
+export interface SubAgentRunOptions {
+    llm: LLMClient;
+    tools: ToolRegistry;
+    cwd: string;
+    maxTurns: number;
+    stallThreshold: number;
+    contextLimit: number;
+}
+export interface SubAgentRunResult {
+    status: RunStatus;
+    reply: string;
+    messages: SessionMessage[];
+}
+export declare function createSubAgentRunner(opts: SubAgentRunOptions): (systemPrompt: string, task: string, signal?: AbortSignal) => Promise<SubAgentRunResult>;

package/dist/runtime/sub-agent-runner.js

@@ -0,0 +1,26 @@
+import { SessionMessages, lastAssistantText } from "./session-messages.js";
+import { Agent } from "./agent.js";
+import { TOOL_USE_PROMPT } from "./prompts.js";
+import { ToolRegistry } from "../tools/registry.js";
+export function createSubAgentRunner(opts) {
+    return async (systemPrompt, task, signal) => {
+        const conversation = new SessionMessages([systemPrompt, TOOL_USE_PROMPT, `- Turn budget: ${opts.maxTurns} tool-calling turns per run.`].join("\n\n"));
+        const subTools = new ToolRegistry();
+        subTools.registerAll(opts.tools.filter((t) => t.readOnly === true));
+        const subAgent = new Agent({
+            llm: opts.llm,
+            conversation,
+            tools: subTools,
+            cwd: opts.cwd,
+            setTodos: () => { },
+            getTodos: () => [],
+            stallThreshold: opts.stallThreshold,
+            maxTurns: opts.maxTurns,
+            contextLimit: opts.contextLimit,
+        });
+        const status = await subAgent.run(task, undefined, signal);
+        const messages = conversation.export();
+        const reply = lastAssistantText(messages) || `(sub-agent produced no final text; status ${status})`;
+        return { status, reply, messages };
+    };
+}

package/dist/runtime/timeline.d.ts

@@ -0,0 +1,21 @@
+import type { SessionMessage } from "./session-messages.js";
+import type { SessionEvent, TimelineEvent } from "./events.js";
+export declare class TimelineStore {
+    private listeners;
+    private entries;
+    private pendingTools;
+    private pendingQuestions;
+    get all(): readonly TimelineEvent[];
+    subscribe(listener: () => void): () => void;
+    applyEvent(e: SessionEvent): void;
+    private append;
+    setResult(id: string, result: string, isError?: boolean, resultSummary?: string): void;
+    setAnswer(id: string, answer: string): void;
+    get latestUnansweredQuestion(): Extract<TimelineEvent, {
+        type: "question";
+    }> | undefined;
+    markPendingToolsAborted(): void;
+    clear(): void;
+    rebuild(entries: TimelineEvent[]): void;
+}
+export declare function toTimelineEntries(messages: SessionMessage[], summarizeArgs: (name: string, args: Record<string, unknown>) => string): TimelineEvent[];

package/dist/runtime/timeline.js

@@ -0,0 +1,146 @@
+import { parseToolArgs, toText } from "../llm/messages.js";
+import { Emitter } from "../util/emitter.js";
+export class TimelineStore {
+    listeners = new Emitter();
+    entries = [];
+    pendingTools = new Map();
+    pendingQuestions = new Map();
+    get all() {
+        return this.entries;
+    }
+    subscribe(listener) {
+        return this.listeners.subscribe(listener);
+    }
+    applyEvent(e) {
+        switch (e.type) {
+            case "tool_start":
+                this.append({ type: "tool", id: e.id, name: e.name, argsSummary: e.argsSummary, result: null });
+                break;
+            case "tool_end":
+                this.setResult(e.id, e.result, e.isError, e.resultSummary);
+                break;
+            case "question":
+                this.pendingQuestions.set(e.id, this.entries.length);
+                this.append(e);
+                break;
+            case "assistant_delta":
+            case "thinking_delta":
+            case "thinking_cleared":
+            case "run_metrics":
+                break;
+            default:
+                this.append(e);
+        }
+    }
+    append(entry) {
+        this.entries.push(entry);
+        if (entry.type === "tool" && entry.result === null) {
+            this.pendingTools.set(entry.id, this.entries.length - 1);
+        }
+        this.listeners.notify();
+    }
+    setResult(id, result, isError, resultSummary) {
+        const idx = this.pendingTools.get(id);
+        if (idx === undefined)
+            return;
+        this.pendingTools.delete(id);
+        const entry = this.entries[idx];
+        if (entry.type !== "tool" || entry.result !== null)
+            return;
+        this.entries[idx] = { ...entry, result, isError, resultSummary };
+        this.listeners.notify();
+    }
+    setAnswer(id, answer) {
+        const index = this.pendingQuestions.get(id);
+        if (index === undefined)
+            return;
+        this.pendingQuestions.delete(id);
+        const entry = this.entries[index];
+        if (entry.type !== "question" || entry.answer !== null)
+            return;
+        this.entries[index] = { ...entry, answer };
+        this.listeners.notify();
+    }
+    get latestUnansweredQuestion() {
+        for (let i = this.entries.length - 1; i >= 0; i--) {
+            const e = this.entries[i];
+            if (e.type === "question" && e.answer === null)
+                return e;
+        }
+        return undefined;
+    }
+    markPendingToolsAborted() {
+        for (const [, idx] of this.pendingTools) {
+            const entry = this.entries[idx];
+            if (entry.type === "tool" && entry.result === null) {
+                this.entries[idx] = { ...entry, result: "aborted", isError: true, resultSummary: "aborted" };
+            }
+        }
+        this.pendingTools.clear();
+        this.listeners.notify();
+    }
+    clear() {
+        this.entries = [];
+        this.pendingTools.clear();
+        this.pendingQuestions.clear();
+        this.listeners.notify();
+    }
+    rebuild(entries) {
+        this.entries = entries;
+        this.pendingTools.clear();
+        this.pendingQuestions.clear();
+        entries.forEach((entry, i) => {
+            if (entry.type === "tool" && entry.result === null) {
+                this.pendingTools.set(entry.id, i);
+            }
+        });
+        this.listeners.notify();
+    }
+}
+export function toTimelineEntries(messages, summarizeArgs) {
+    const toolResults = new Map();
+    for (const m of messages) {
+        if (m.role === "tool") {
+            const result = { content: m.content };
+            if (m.resultSummary !== undefined || m.isError !== undefined) {
+                result.resultSummary = m.resultSummary;
+                result.isError = m.isError;
+            }
+            toolResults.set(m.tool_call_id, result);
+        }
+    }
+    const entries = [];
+    for (const m of messages) {
+        if (m.role === "user") {
+            entries.push({ type: "user", text: m.content });
+        }
+        else if (m.role === "skill") {
+            entries.push({ type: "skill", name: m.name });
+        }
+        else if (m.role === "assistant") {
+            const text = toText(m.content);
+            if (text)
+                entries.push({ type: "assistant", text });
+            if (m.tool_calls) {
+                for (const tc of m.tool_calls) {
+                    const parsed = parseToolArgs(tc.function.arguments);
+                    const entry = {
+                        type: "tool",
+                        id: tc.id,
+                        name: tc.function.name,
+                        argsSummary: summarizeArgs(tc.function.name, parsed.ok ? parsed.args : {}),
+                        result: null,
+                    };
+                    const result = toolResults.get(tc.id);
+                    if (result) {
+                        entries.push({ ...entry, result: result.content, isError: result.isError, resultSummary: result.resultSummary });
+                    }
+                    else {
+                        entries.push(entry);
+                    }
+                }
+            }
+        }
+    }
+    return entries;
+}

package/dist/runtime/todo-store.d.ts

@@ -0,0 +1,8 @@
+import type { Todo } from "../tools/types.js";
+export declare class TodoStore {
+    private listeners;
+    private items;
+    get all(): readonly Todo[];
+    subscribe(listener: () => void): () => void;
+    set(todos: Todo[]): void;
+}