@vietor/agent-core 0.7.0

package/dist/create-session.d.ts

@@ -0,0 +1,4 @@
+import { Session } from "./runtime/session.js";
+import type { SessionOptions } from "./runtime/session.js";
+export declare const SYSTEM_PROMPT_BOUNDARY = "\n\n---\n<!-- SYSTEM_PROMPT_BOUNDARY -->\n\n";
+export declare function createSession(opts: SessionOptions): Promise<Session>;

package/dist/create-session.js

@@ -0,0 +1,51 @@
+import { createLLM } from "./llm/client.js";
+import { Session } from "./runtime/session.js";
+import { ToolRegistry } from "./tools/registry.js";
+import { MCPServerManager } from "./mcp/manager.js";
+import { TOOL_USE_PROMPT } from "./runtime/prompts.js";
+import { DEFAULT_MAX_TURNS } from "./util/constants.js";
+import { TODO_WRITE_GUIDANCE } from "./tools/todo-write.js";
+import { ASK_USER_GUIDANCE } from "./tools/ask-user.js";
+import { SUB_AGENT_GUIDANCE } from "./tools/sub-agent.js";
+export const SYSTEM_PROMPT_BOUNDARY = '\n\n---\n<!-- SYSTEM_PROMPT_BOUNDARY -->\n\n';
+function contextLimitFor(maxInputTokens) {
+    return Math.floor(maxInputTokens * 0.75);
+}
+function buildSystemPrompt(base, skills, builtInTools, maxTurns) {
+    const parts = [base];
+    const toolUseLines = [TOOL_USE_PROMPT, `- Turn budget: ${maxTurns} tool-calling turns per run.`];
+    if (typeof builtInTools === "object") {
+        if (builtInTools.todoWrite)
+            toolUseLines.push(TODO_WRITE_GUIDANCE);
+        if (builtInTools.askUser)
+            toolUseLines.push(ASK_USER_GUIDANCE);
+        if (builtInTools.subAgent)
+            toolUseLines.push(SUB_AGENT_GUIDANCE);
+    }
+    parts.push(toolUseLines.join("\n"));
+    if (skills?.length) {
+        const lines = skills.map((s) => `- \`${s.name}\`: ${s.description || "no description"}`);
+        parts.push(["Available skills (call via the Skill tool):", ...lines].join("\n"));
+    }
+    return parts.join(SYSTEM_PROMPT_BOUNDARY);
+}
+export async function createSession(opts) {
+    const llm = createLLM(opts.llm);
+    const tools = new ToolRegistry();
+    const mcp = new MCPServerManager(tools, opts.clientInfo ?? { name: "agent-core", version: "0.0.0" });
+    const session = new Session({
+        ...opts,
+        systemPrompt: buildSystemPrompt(opts.systemPrompt, opts.skills, opts.builtInTools, opts.maxTurns ?? DEFAULT_MAX_TURNS),
+        llm,
+        tools,
+        mcp,
+        contextLimit: contextLimitFor(llm.maxInputTokens),
+    });
+    if (opts.tools) {
+        tools.registerAll(opts.tools);
+    }
+    if (opts.mcpServers) {
+        await session.connectMCP(opts.mcpServers);
+    }
+    return session;
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { Session, SessionBusyError, type SessionOptions, type SessionView, type SessionState, type PromptResult } from "./runtime/session.js";
+export type { RunStatus } from "./runtime/agent.js";
+export type { SessionMessage } from "./runtime/session-messages.js";
+export { INITIAL_RUN_METRICS, type SessionEvent, type TimelineEvent, type RunMetrics } from "./runtime/events.js";
+export type { Tool, ToolContext, ToolSchema, Todo, TodoStatus, TextResult } from "./tools/types.js";
+export { toolError } from "./tools/types.js";
+export type { BuiltinToolsOptions } from "./tools/registry.js";
+export type { Skill } from "./skills/loader.js";
+export { tryLoadSkills } from "./skills/loader.js";
+export type { MCPClientInfo, MCPServerConfig, MCPServerInfo } from "./mcp/types.js";
+export type { LLMConfig, LLMThinkingEffort, LLMBackend } from "./llm/types.js";
+export { createSession, SYSTEM_PROMPT_BOUNDARY } from "./create-session.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { Session, SessionBusyError } from "./runtime/session.js";
+export { INITIAL_RUN_METRICS } from "./runtime/events.js";
+export { toolError } from "./tools/types.js";
+export { tryLoadSkills } from "./skills/loader.js";
+export { createSession, SYSTEM_PROMPT_BOUNDARY } from "./create-session.js";

package/dist/llm/anthropic.d.ts

@@ -0,0 +1,14 @@
+import Anthropic from "@anthropic-ai/sdk";
+import { type LLMAssistantMessage, type LLMMessage } from "./messages.js";
+import type { ChatOptions, LLMThinkingEffort, ResolvedLLMConfig } from "./types.js";
+import { BaseAdapter } from "./base.js";
+export declare const THINKING_BUDGET: Record<LLMThinkingEffort, number>;
+export declare class AnthropicAdapter extends BaseAdapter {
+    private client;
+    constructor(config: ResolvedLLMConfig);
+    stream(opts: ChatOptions): Promise<LLMAssistantMessage>;
+}
+export declare function toAnthropicMessages(messages: LLMMessage[], includeThinking: boolean): {
+    system: string | undefined;
+    messages: Anthropic.MessageParam[];
+};

package/dist/llm/anthropic.js

@@ -0,0 +1,200 @@
+import Anthropic from "@anthropic-ai/sdk";
+import { EmptyAssistantMessageError, parseToolArgs, toText, } from "./messages.js";
+import { BaseAdapter } from "./base.js";
+import { netFetch } from "../util/net.js";
+const CONTINUE_CUE = "Continue the work, using the prior conversation as context.";
+export const THINKING_BUDGET = {
+    high: 16000,
+    max: 32000,
+};
+export class AnthropicAdapter extends BaseAdapter {
+    client;
+    constructor(config) {
+        super(config);
+        this.client = new Anthropic({
+            apiKey: config.apiKey,
+            baseURL: config.baseUrl || undefined,
+            maxRetries: 0,
+            fetch: netFetch,
+        });
+    }
+    async stream(opts) {
+        const useThinking = opts.thinking !== false;
+        const budget = THINKING_BUDGET[this.thinkingEffort];
+        const { system, messages } = toAnthropicMessages(opts.messages, useThinking);
+        const tools = opts.tools.map(toAnthropicTool);
+        const cacheControl = { type: "ephemeral" };
+        const systemCached = system
+            ? [{ type: "text", text: system, cache_control: cacheControl }]
+            : undefined;
+        const toolsCached = tools.length > 0 && !system
+            ? [...tools.slice(0, -1), { ...tools[tools.length - 1], cache_control: cacheControl }]
+            : undefined;
+        const params = {
+            model: this.model,
+            max_tokens: this.maxOutputTokens,
+            messages,
+            ...(systemCached && { system: systemCached }),
+            ...(useThinking && {
+                thinking: { type: "enabled", budget_tokens: Math.min(budget, this.maxOutputTokens - 1) },
+                output_config: { effort: this.thinkingEffort },
+            }),
+            ...(tools.length > 0 && { tools: toolsCached ?? tools }),
+        };
+        const stream = this.client.messages.stream(params, { signal: opts.signal });
+        if (opts.onUsage)
+            stream.on("streamEvent", (e) => { if (e.type === "message_start")
+                opts.onUsage(e.message.usage.input_tokens, 0); });
+        if (opts.onDelta)
+            stream.on("text", (delta) => opts.onDelta(delta));
+        if (opts.onThinking)
+            stream.on("thinking", (delta) => opts.onThinking(delta));
+        if (opts.onToolCall)
+            stream.on("contentBlock", (block) => { if (block.type === "tool_use")
+                opts.onToolCall(); });
+        const final = await stream.finalMessage();
+        opts.onUsage?.(final.usage.input_tokens, final.usage.output_tokens);
+        const thinking = [];
+        let text = "";
+        const toolCalls = [];
+        for (const block of final.content) {
+            if (block.type === "thinking") {
+                thinking.push({ type: "thinking", thinking: block.thinking, signature: block.signature });
+            }
+            else if (block.type === "redacted_thinking") {
+                thinking.push({ type: "redacted_thinking", data: block.data });
+            }
+            else if (block.type === "text") {
+                text += block.text;
+            }
+            else if (block.type === "tool_use") {
+                toolCalls.push({
+                    id: block.id,
+                    type: "function",
+                    function: { name: block.name, arguments: JSON.stringify(block.input ?? {}) },
+                });
+            }
+        }
+        const message = {
+            role: "assistant",
+            content: text || null,
+        };
+        if (thinking.length)
+            message.thinking = thinking;
+        if (toolCalls.length)
+            message.tool_calls = toolCalls;
+        if (!text && !thinking.length && !toolCalls.length) {
+            throw new EmptyAssistantMessageError();
+        }
+        return message;
+    }
+}
+function toAnthropicTool(schema) {
+    return {
+        name: schema.function.name,
+        description: schema.function.description,
+        input_schema: schema.function.parameters,
+    };
+}
+export function toAnthropicMessages(messages, includeThinking) {
+    let system;
+    const rest = [];
+    for (const m of messages) {
+        if (m.role === "system") {
+            const text = toText(m.content);
+            system = system ? `${system}\n\n${text}` : text;
+        }
+        else {
+            rest.push(m);
+        }
+    }
+    while (rest.length > 0 &&
+        rest[0].role === "assistant" &&
+        !rest[0].tool_calls?.length) {
+        const text = toText(rest[0].content);
+        if (text)
+            system = system ? `${system}\n\n${text}` : text;
+        rest.shift();
+    }
+    const out = [];
+    for (const m of rest) {
+        const param = toMessageParam(m, includeThinking);
+        const last = out[out.length - 1];
+        if (last && last.role === param.role) {
+            const merged = mergeContent(last.content, param.content);
+            if (merged === null)
+                out.push(param);
+            else
+                last.content = merged;
+        }
+        else {
+            out.push(param);
+        }
+    }
+    if (out.length === 0 || out[0].role === "assistant") {
+        out.unshift({ role: "user", content: CONTINUE_CUE });
+    }
+    return { system, messages: out };
+}
+function toMessageParam(m, includeThinking) {
+    if (m.role === "user") {
+        return { role: "user", content: toText(m.content) };
+    }
+    if (m.role === "tool") {
+        return {
+            role: "user",
+            content: [{ type: "tool_result", tool_use_id: m.tool_call_id, content: m.content }],
+        };
+    }
+    const blocks = [];
+    const a = m;
+    if (includeThinking && a.thinking) {
+        for (const t of a.thinking)
+            blocks.push(t);
+    }
+    const text = toText(a.content);
+    if (text)
+        blocks.push({ type: "text", text });
+    if (a.tool_calls) {
+        for (const tc of a.tool_calls) {
+            const parsed = parseToolArgs(tc.function.arguments);
+            blocks.push({
+                type: "tool_use",
+                id: tc.id,
+                name: tc.function.name,
+                input: parsed.ok ? parsed.args : {},
+            });
+        }
+    }
+    return { role: "assistant", content: blocks.length ? blocks : (text || "-") };
+}
+function hasToolResult(content) {
+    return Array.isArray(content) && content.some((block) => block.type === "tool_result");
+}
+function hasText(content) {
+    return typeof content === "string" ? content.length > 0 : content.some((b) => b.type === "text");
+}
+function mergeContent(a, b) {
+    const aText = hasText(a);
+    const bText = hasText(b);
+    if ((aText || bText) && (hasToolResult(a) || hasToolResult(b)))
+        return null;
+    if (typeof a === "string" && typeof b === "string")
+        return a ? `${a}\n${b}` : b;
+    const blocks = [];
+    if (typeof a === "string") {
+        if (a)
+            blocks.push({ type: "text", text: a });
+    }
+    else {
+        blocks.push(...a);
+    }
+    if (typeof b === "string") {
+        if (b)
+            blocks.push({ type: "text", text: b });
+    }
+    else {
+        blocks.push(...b);
+    }
+    return blocks;
+}

package/dist/llm/base.d.ts

@@ -0,0 +1,10 @@
+import type { LLMAssistantMessage } from "./messages.js";
+import type { Adapter, ChatOptions, LLMThinkingEffort, ResolvedLLMConfig } from "./types.js";
+export declare abstract class BaseAdapter implements Adapter {
+    readonly model: string;
+    readonly thinkingEffort: LLMThinkingEffort;
+    readonly maxInputTokens: number;
+    readonly maxOutputTokens: number;
+    protected constructor(config: ResolvedLLMConfig);
+    abstract stream(opts: ChatOptions): Promise<LLMAssistantMessage>;
+}

package/dist/llm/base.js

@@ -0,0 +1,12 @@
+export class BaseAdapter {
+    model;
+    thinkingEffort;
+    maxInputTokens;
+    maxOutputTokens;
+    constructor(config) {
+        this.model = config.model;
+        this.thinkingEffort = config.thinkingEffort;
+        this.maxInputTokens = config.maxInputTokens;
+        this.maxOutputTokens = config.maxOutputTokens;
+    }
+}

package/dist/llm/client.d.ts

@@ -0,0 +1,4 @@
+import type { Adapter, LLMClient, LLMConfig } from "./types.js";
+export declare function isRetryableError(e: unknown, signal?: AbortSignal): boolean;
+export declare function withRetryChat(adapter: Adapter): LLMClient["chat"];
+export declare function createLLM(config: LLMConfig): LLMClient;

package/dist/llm/client.js

@@ -0,0 +1,61 @@
+import { EmptyAssistantMessageError } from "./messages.js";
+import { CompletionsAdapter } from "./completions.js";
+import { AnthropicAdapter } from "./anthropic.js";
+import { ResponsesAdapter } from "./responses.js";
+import { isAbortError, withRetry, backoffDelay } from "../util/async.js";
+import { DEFAULT_BACKEND, DEFAULT_MAX_INPUT_TOKENS, DEFAULT_MAX_OUTPUT_TOKENS, DEFAULT_THINKING_EFFORT, LLM_MAX_RETRIES } from "../util/constants.js";
+export function isRetryableError(e, signal) {
+    if (signal?.aborted || isAbortError(e))
+        return false;
+    if (e instanceof EmptyAssistantMessageError)
+        return true;
+    const name = e.name;
+    if (name === "APIConnectionError" || name === "APIConnectionTimeoutError" || name === "APITimeoutError")
+        return true;
+    const status = e.status;
+    if (status != null)
+        return status === 429 || status >= 500;
+    return false;
+}
+export function withRetryChat(adapter) {
+    return (opts) => {
+        let sawToolCall = false;
+        return withRetry(() => {
+            sawToolCall = false;
+            return adapter.stream({ ...opts, onToolCall: () => { sawToolCall = true; } });
+        }, {
+            retries: LLM_MAX_RETRIES,
+            retryable: (e) => !sawToolCall && isRetryableError(e, opts.signal),
+            backoff: backoffDelay,
+            onRetry: opts.onRetry,
+            signal: opts.signal,
+        });
+    };
+}
+export function createLLM(config) {
+    const cfg = {
+        ...config,
+        thinkingEffort: config.thinkingEffort ?? DEFAULT_THINKING_EFFORT,
+        backend: config.backend ?? DEFAULT_BACKEND,
+        maxInputTokens: config.maxInputTokens ?? DEFAULT_MAX_INPUT_TOKENS,
+        maxOutputTokens: config.maxOutputTokens ?? DEFAULT_MAX_OUTPUT_TOKENS,
+    };
+    let adapter;
+    switch (cfg.backend) {
+        case "responses":
+            adapter = new ResponsesAdapter(cfg);
+            break;
+        case "anthropic":
+            adapter = new AnthropicAdapter(cfg);
+            break;
+        default:
+            adapter = new CompletionsAdapter(cfg);
+    }
+    return {
+        model: adapter.model,
+        thinkingEffort: adapter.thinkingEffort,
+        maxInputTokens: adapter.maxInputTokens,
+        maxOutputTokens: adapter.maxOutputTokens,
+        chat: withRetryChat(adapter),
+    };
+}

package/dist/llm/completions.d.ts

@@ -0,0 +1,8 @@
+import { type LLMAssistantMessage } from "./messages.js";
+import type { ChatOptions, ResolvedLLMConfig } from "./types.js";
+import { BaseAdapter } from "./base.js";
+export declare class CompletionsAdapter extends BaseAdapter {
+    private client;
+    constructor(config: ResolvedLLMConfig);
+    stream(opts: ChatOptions): Promise<LLMAssistantMessage>;
+}

package/dist/llm/completions.js

@@ -0,0 +1,88 @@
+import OpenAI from "openai";
+import { EmptyAssistantMessageError } from "./messages.js";
+import { BaseAdapter } from "./base.js";
+import { netFetch } from "../util/net.js";
+export class CompletionsAdapter extends BaseAdapter {
+    client;
+    constructor(config) {
+        super(config);
+        this.client = new OpenAI({
+            apiKey: config.apiKey,
+            baseURL: config.baseUrl || undefined,
+            maxRetries: 0,
+            fetch: netFetch,
+        });
+    }
+    async stream(opts) {
+        const { messages, tools, onDelta, onThinking, onUsage, onToolCall, thinking, signal } = opts;
+        let content = "";
+        let refusal = "";
+        const calls = new Map();
+        const useThinking = thinking !== false;
+        const params = {
+            model: this.model,
+            max_tokens: this.maxOutputTokens,
+            messages,
+            stream: true,
+            stream_options: { include_usage: true },
+            ...(tools.length > 0 && { tools }),
+            ...(useThinking && { reasoning_effort: this.thinkingEffort })
+        };
+        const stream = await this.client.chat.completions.create(params, { signal });
+        for await (const chunk of stream) {
+            if (chunk.usage) {
+                onUsage?.(chunk.usage.prompt_tokens ?? 0, chunk.usage.completion_tokens ?? 0);
+            }
+            const delta = chunk.choices[0]?.delta;
+            if (!delta)
+                continue;
+            if (delta.content) {
+                content += delta.content;
+                onDelta?.(delta.content);
+            }
+            const thinkingDelta = delta;
+            const thinkingText = thinkingDelta.reasoning_content ?? thinkingDelta.reasoning;
+            if (thinkingText) {
+                onThinking?.(thinkingText);
+            }
+            const refusalDelta = delta;
+            if (refusalDelta.refusal) {
+                refusal += refusalDelta.refusal;
+                onDelta?.(refusalDelta.refusal);
+            }
+            if (delta.tool_calls) {
+                onToolCall?.();
+                for (const tc of delta.tool_calls) {
+                    let acc = calls.get(tc.index);
+                    if (!acc) {
+                        acc = { id: tc.id ?? "", name: "", arguments: "" };
+                        calls.set(tc.index, acc);
+                    }
+                    if (tc.id)
+                        acc.id = tc.id;
+                    if (tc.function?.name)
+                        acc.name = tc.function.name;
+                    if (tc.function?.arguments)
+                        acc.arguments += tc.function.arguments;
+                }
+            }
+        }
+        const message = {
+            role: "assistant",
+            content: content || refusal || null,
+        };
+        if (calls.size) {
+            message.tool_calls = [...calls.entries()]
+                .sort((a, b) => a[0] - b[0])
+                .map(([, acc]) => ({
+                id: acc.id,
+                type: "function",
+                function: { name: acc.name, arguments: acc.arguments },
+            }));
+        }
+        if (!content && !refusal && !calls.size) {
+            throw new EmptyAssistantMessageError();
+        }
+        return message;
+    }
+}

package/dist/llm/messages.d.ts

@@ -0,0 +1,50 @@
+export interface TextContentPart {
+    type: "text";
+    text: string;
+}
+export interface ToolCall {
+    id: string;
+    type: "function";
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+export interface ThinkingBlock {
+    type: "thinking";
+    thinking: string;
+    signature: string;
+}
+export interface RedactedThinkingBlock {
+    type: "redacted_thinking";
+    data: string;
+}
+export interface LLMAssistantMessage {
+    role: "assistant";
+    content: string | null | TextContentPart[];
+    tool_calls?: ToolCall[];
+    thinking?: Array<ThinkingBlock | RedactedThinkingBlock>;
+}
+export type LLMMessage = {
+    role: "system";
+    content: string | TextContentPart[];
+} | {
+    role: "user";
+    content: string | TextContentPart[];
+    name?: string;
+} | LLMAssistantMessage | {
+    role: "tool";
+    tool_call_id: string;
+    content: string;
+};
+export declare function toText(content: string | TextContentPart[] | null | undefined): string;
+export declare class EmptyAssistantMessageError extends Error {
+    constructor();
+}
+export declare function parseToolArgs(args: string | undefined): {
+    ok: true;
+    args: Record<string, unknown>;
+} | {
+    ok: false;
+    error: string;
+};

package/dist/llm/messages.js

@@ -0,0 +1,28 @@
+import { toErrorMessage } from "../util/text.js";
+export function toText(content) {
+    if (!content)
+        return "";
+    if (typeof content === "string")
+        return content;
+    return content.map((p) => p.text).join("");
+}
+export class EmptyAssistantMessageError extends Error {
+    constructor() {
+        super("empty assistant message: no content, refusal, thinking, or tool calls");
+        this.name = "EmptyAssistantMessageError";
+    }
+}
+export function parseToolArgs(args) {
+    if (!args)
+        return { ok: true, args: {} };
+    try {
+        const parsed = JSON.parse(args);
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+            return { ok: false, error: "arguments must be a JSON object" };
+        }
+        return { ok: true, args: parsed };
+    }
+    catch (e) {
+        return { ok: false, error: toErrorMessage(e) };
+    }
+}

package/dist/llm/responses.d.ts

@@ -0,0 +1,14 @@
+import OpenAI from "openai";
+import { type LLMAssistantMessage, type LLMMessage } from "./messages.js";
+import type { ChatOptions, ResolvedLLMConfig } from "./types.js";
+import { BaseAdapter } from "./base.js";
+import type { ToolSchema } from "../tools/types.js";
+type ResponsesInputItem = OpenAI.Responses.ResponseInputItem;
+export declare class ResponsesAdapter extends BaseAdapter {
+    private client;
+    constructor(config: ResolvedLLMConfig);
+    stream(opts: ChatOptions): Promise<LLMAssistantMessage>;
+}
+export declare function toResponsesTool(schema: ToolSchema): OpenAI.Responses.FunctionTool;
+export declare function toResponsesInput(messages: LLMMessage[]): ResponsesInputItem[];
+export {};