@germanescobar/anita 0.3.0

package/dist/tools/read-file.js

@@ -0,0 +1,122 @@
+import fs from "node:fs/promises";
+export const readFileTool = {
+    name: "read_file",
+    description: "Read the contents of a file at the given path. Supports optional 1-based inclusive line ranges and max_chars bounds.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            path: { type: "string", description: "Absolute or relative file path" },
+            start_line: {
+                type: "integer",
+                minimum: 1,
+                description: "Optional 1-based first line to read",
+            },
+            end_line: {
+                type: "integer",
+                minimum: 1,
+                description: "Optional 1-based last line to read, inclusive",
+            },
+            max_chars: {
+                type: "integer",
+                minimum: 1,
+                description: "Optional maximum number of characters to return",
+            },
+        },
+        required: ["path"],
+    },
+    async execute(input) {
+        const filePath = input.path;
+        try {
+            const fullContent = await fs.readFile(filePath, "utf-8");
+            const lineCount = countLines(fullContent);
+            const startLine = readPositiveInteger(input.start_line);
+            const endLine = readPositiveInteger(input.end_line);
+            const maxChars = readPositiveInteger(input.max_chars);
+            if (startLine !== undefined && endLine !== undefined && endLine < startLine) {
+                return {
+                    content: "Error reading file: end_line must be greater than or equal to start_line.",
+                    isError: true,
+                    metadata: {
+                        path: filePath,
+                        requestedStartLine: startLine,
+                        requestedEndLine: endLine,
+                    },
+                };
+            }
+            const ranged = applyLineRange(fullContent, startLine, endLine);
+            const truncated = maxChars !== undefined && ranged.content.length > maxChars;
+            const returnedContent = truncated
+                ? ranged.content.slice(0, maxChars)
+                : ranged.content;
+            const content = truncated
+                ? `${returnedContent}\n[truncated: output exceeded ${maxChars} characters]`
+                : returnedContent;
+            const returnedRange = calculateReturnedLineRange(returnedContent, ranged.returnedLineStart);
+            return {
+                content,
+                metadata: {
+                    path: filePath,
+                    bytes: Buffer.byteLength(fullContent, "utf-8"),
+                    lineCount,
+                    returnedBytes: Buffer.byteLength(content, "utf-8"),
+                    returnedLineStart: returnedRange.start,
+                    returnedLineEnd: returnedRange.end,
+                    truncated,
+                    maxChars: maxChars ?? null,
+                },
+            };
+        }
+        catch (err) {
+            return {
+                content: `Error reading file: ${err.message}`,
+                isError: true,
+                metadata: {
+                    path: filePath,
+                },
+            };
+        }
+    },
+};
+function applyLineRange(content, startLine, endLine) {
+    if (startLine === undefined && endLine === undefined) {
+        return {
+            content,
+            returnedLineStart: content.length > 0 ? 1 : null,
+            returnedLineEnd: content.length > 0 ? countLines(content) : null,
+        };
+    }
+    const lines = content.split("\n");
+    const startIndex = (startLine ?? 1) - 1;
+    const endIndex = endLine ?? lines.length;
+    const selectedLines = lines.slice(startIndex, endIndex);
+    return {
+        content: selectedLines.join("\n"),
+        returnedLineStart: selectedLines.length > 0 ? startIndex + 1 : null,
+        returnedLineEnd: selectedLines.length > 0 ? startIndex + selectedLines.length : null,
+    };
+}
+function countLines(content) {
+    if (content.length === 0)
+        return 0;
+    return content.split("\n").length;
+}
+function calculateReturnedLineRange(content, startLine) {
+    if (content.length === 0 || startLine === null) {
+        return { start: null, end: null };
+    }
+    const returnedLineCount = content.endsWith("\n")
+        ? countLines(content) - 1
+        : countLines(content);
+    return {
+        start: startLine,
+        end: startLine + returnedLineCount - 1,
+    };
+}
+function readPositiveInteger(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Number.isInteger(value) || typeof value !== "number" || value < 1) {
+        return undefined;
+    }
+    return value;
+}

package/dist/tools/registry.d.ts

@@ -0,0 +1,9 @@
+import type { ToolDefinition, ToolExecuteOptions, ToolResult, ToolSchema } from "../types/tools.js";
+export declare class ToolRegistry {
+    private tools;
+    register(tool: ToolDefinition): void;
+    get(name: string): ToolDefinition | undefined;
+    toSchemas(): ToolSchema[];
+    execute(name: string, input: Record<string, unknown>, options?: ToolExecuteOptions): Promise<ToolResult>;
+    validateInput(name: string, input: Record<string, unknown>): ToolResult | null;
+}

package/dist/tools/registry.js

@@ -0,0 +1,122 @@
+const SUPPORTED_PROPERTY_TYPES = new Set([
+    "string",
+    "number",
+    "integer",
+    "boolean",
+    "object",
+    "array",
+]);
+export class ToolRegistry {
+    tools = new Map();
+    register(tool) {
+        this.tools.set(tool.name, tool);
+    }
+    get(name) {
+        return this.tools.get(name);
+    }
+    toSchemas() {
+        return Array.from(this.tools.values())
+            .sort((a, b) => a.name.localeCompare(b.name))
+            .map((tool) => ({
+            name: tool.name,
+            description: tool.description,
+            parameters: tool.inputSchema,
+        }));
+    }
+    async execute(name, input, options) {
+        const tool = this.tools.get(name);
+        if (!tool) {
+            return { content: `Unknown tool: ${name}`, isError: true };
+        }
+        const validationError = this.validateInput(name, input);
+        if (validationError)
+            return validationError;
+        return tool.execute(input, options);
+    }
+    validateInput(name, input) {
+        const tool = this.tools.get(name);
+        if (!tool)
+            return null;
+        const errors = validateAgainstSchema(tool.inputSchema, input);
+        if (errors.length === 0)
+            return null;
+        return {
+            content: `Invalid input for tool "${name}": ${errors.join(" ")}`,
+            isError: true,
+            metadata: {
+                validationErrors: errors,
+            },
+        };
+    }
+}
+function validateAgainstSchema(schema, input) {
+    const errors = [];
+    const required = readRequiredFields(schema.required);
+    for (const field of required) {
+        if (!Object.prototype.hasOwnProperty.call(input, field) ||
+            input[field] === undefined) {
+            errors.push(`missing required field "${field}".`);
+        }
+    }
+    const properties = readProperties(schema.properties);
+    for (const [field, propertySchema] of Object.entries(properties)) {
+        if (!Object.prototype.hasOwnProperty.call(input, field) ||
+            input[field] === undefined) {
+            continue;
+        }
+        const expectedType = readExpectedType(propertySchema);
+        if (!expectedType)
+            continue;
+        const value = input[field];
+        if (!matchesType(value, expectedType)) {
+            errors.push(`field "${field}" must be ${formatExpectedType(expectedType)}.`);
+        }
+    }
+    return errors;
+}
+function readRequiredFields(required) {
+    if (!Array.isArray(required))
+        return [];
+    return required.filter((field) => typeof field === "string");
+}
+function readProperties(properties) {
+    if (!isPlainObject(properties))
+        return {};
+    const result = {};
+    for (const [field, propertySchema] of Object.entries(properties)) {
+        if (isPlainObject(propertySchema)) {
+            result[field] = propertySchema;
+        }
+    }
+    return result;
+}
+function readExpectedType(schema) {
+    const type = schema.type;
+    if (typeof type !== "string")
+        return null;
+    return SUPPORTED_PROPERTY_TYPES.has(type) ? type : null;
+}
+function matchesType(value, expectedType) {
+    switch (expectedType) {
+        case "array":
+            return Array.isArray(value);
+        case "boolean":
+            return typeof value === "boolean";
+        case "integer":
+            return Number.isInteger(value);
+        case "number":
+            return typeof value === "number" && Number.isFinite(value);
+        case "object":
+            return isPlainObject(value);
+        case "string":
+            return typeof value === "string";
+        default:
+            return true;
+    }
+}
+function formatExpectedType(expectedType) {
+    return expectedType === "integer" ? "an integer" : `a ${expectedType}`;
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/tools/run-command.d.ts

@@ -0,0 +1,2 @@
+import type { ToolDefinition } from "../types/tools.js";
+export declare const runCommandTool: ToolDefinition;

package/dist/tools/run-command.js

@@ -0,0 +1,103 @@
+import { exec } from "node:child_process";
+import process from "node:process";
+const DEFAULT_TIMEOUT = 30_000; // 30 seconds
+const MAX_OUTPUT_CHARS = 10_000;
+export const runCommandTool = {
+    name: "run_command",
+    description: "Run a shell command and return stdout/stderr. Has a 30 second timeout.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            command: { type: "string", description: "The shell command to run" },
+        },
+        required: ["command"],
+    },
+    async execute(input, options) {
+        const command = input.command;
+        const signal = options?.signal;
+        if (signal?.aborted) {
+            return abortedResult(command);
+        }
+        return new Promise((resolve) => {
+            exec(command, { timeout: DEFAULT_TIMEOUT, signal }, (error, stdout, stderr) => {
+                const aborted = Boolean(signal?.aborted);
+                const timedOut = Boolean(error?.killed) && !aborted;
+                const parts = [];
+                if (stdout)
+                    parts.push(stdout);
+                if (stderr)
+                    parts.push(`[stderr]\n${stderr}`);
+                if (aborted) {
+                    parts.push("[cancelled] Command was cancelled before completion");
+                }
+                else if (timedOut) {
+                    parts.push(`[timeout] Command timed out after ${DEFAULT_TIMEOUT}ms`);
+                }
+                else if (error && error.signal) {
+                    parts.push(`[signal: ${error.signal}]`);
+                }
+                else if (error) {
+                    parts.push(`[exit code: ${error.code}]`);
+                }
+                const rawContent = parts.join("\n") || "(no output)";
+                let content = rawContent;
+                const truncated = content.length > MAX_OUTPUT_CHARS;
+                if (content.length > MAX_OUTPUT_CHARS) {
+                    content = content.slice(0, MAX_OUTPUT_CHARS) + `\n[truncated: output exceeded ${MAX_OUTPUT_CHARS} characters]`;
+                }
+                resolve({
+                    content,
+                    isError: !!error,
+                    metadata: {
+                        command,
+                        cwd: process.cwd(),
+                        exitCode: getExitCode(error),
+                        signal: error?.signal ?? null,
+                        timedOut,
+                        aborted,
+                        truncated,
+                        bytes: Buffer.byteLength(rawContent, "utf-8"),
+                        lineCount: countLines(rawContent),
+                        stdoutBytes: Buffer.byteLength(stdout, "utf-8"),
+                        stderrBytes: Buffer.byteLength(stderr, "utf-8"),
+                        timeoutMs: DEFAULT_TIMEOUT,
+                        maxOutputChars: MAX_OUTPUT_CHARS,
+                    },
+                });
+            });
+        });
+    },
+};
+function abortedResult(command) {
+    const content = "[cancelled] Command was cancelled before completion";
+    return {
+        content,
+        isError: true,
+        metadata: {
+            command,
+            cwd: process.cwd(),
+            exitCode: null,
+            signal: null,
+            timedOut: false,
+            aborted: true,
+            truncated: false,
+            bytes: Buffer.byteLength(content, "utf-8"),
+            lineCount: countLines(content),
+            stdoutBytes: 0,
+            stderrBytes: 0,
+            timeoutMs: DEFAULT_TIMEOUT,
+            maxOutputChars: MAX_OUTPUT_CHARS,
+        },
+    };
+}
+function countLines(content) {
+    if (content.length === 0)
+        return 0;
+    return content.split("\n").length;
+}
+function getExitCode(error) {
+    if (!error)
+        return 0;
+    const maybeCode = error;
+    return typeof maybeCode.code === "number" ? maybeCode.code : null;
+}

package/dist/tools/write-file.d.ts

@@ -0,0 +1,2 @@
+import type { ToolDefinition } from "../types/tools.js";
+export declare const writeFileTool: ToolDefinition;

package/dist/tools/write-file.js

@@ -0,0 +1,29 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+export const writeFileTool = {
+    name: "write_file",
+    description: "Write content to a file. Creates the file and any parent directories if they don't exist. Overwrites existing content.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            path: { type: "string", description: "Absolute or relative file path" },
+            content: { type: "string", description: "Content to write to the file" },
+        },
+        required: ["path", "content"],
+    },
+    async execute(input) {
+        const filePath = input.path;
+        const content = input.content;
+        try {
+            await fs.mkdir(path.dirname(filePath), { recursive: true });
+            await fs.writeFile(filePath, content);
+            return { content: `File written: ${filePath}` };
+        }
+        catch (err) {
+            return {
+                content: `Error writing file: ${err.message}`,
+                isError: true,
+            };
+        }
+    },
+};

package/dist/types/agent.d.ts

@@ -0,0 +1,44 @@
+import type { ConversationItem, ConversationReasoningItem } from "./conversation.js";
+import type { Message, ContentBlock } from "./messages.js";
+export type SessionStatus = "active" | "paused" | "completed" | "archived";
+export interface SessionState {
+    id: string;
+    title?: string;
+    workingDirectory: string;
+    model: string;
+    conversationItems: ConversationItem[];
+    messages: Message[];
+    contextBudget?: SessionContextBudget;
+    createdAt: string;
+    lastActiveAt: string;
+    status: SessionStatus;
+}
+export interface SessionContextBudget {
+    approximateTokens: number;
+    thresholdTokens: number;
+    compactAtRatio: number;
+    reservedResponseTokens: number;
+    keepRecentTokens: number;
+    minSummarizableTokens: number;
+    targetSummaryTokens: number;
+    preservedRecentTokens?: number;
+    summaryTokens?: number;
+    compactionSummary?: string;
+    summarizedItemCount?: number;
+    compactedAt?: string;
+    lastProviderUsage?: ModelUsage;
+}
+export type StopReason = "end_turn" | "tool_use" | "max_tokens" | "error";
+export interface ModelResponse {
+    stopReason: StopReason;
+    content: ContentBlock[];
+    reasoning?: string;
+    reasoningItems?: ConversationReasoningItem[];
+    usage?: ModelUsage;
+}
+export interface ModelUsage {
+    inputTokens: number;
+    outputTokens: number;
+    cachedTokens?: number;
+    cacheWriteTokens?: number;
+}

package/dist/types/agent.js

@@ -0,0 +1 @@
+export {};

package/dist/types/conversation.d.ts

@@ -0,0 +1,43 @@
+import type { ToolResultMetadata } from "./tools.js";
+import type { AttachmentContentBlock, ContentBlock, Message, MessageRole } from "./messages.js";
+export type ConversationItem = ConversationMessageItem | ConversationAttachmentItem | ConversationReasoningItem | ConversationFunctionCallItem | ConversationFunctionOutputItem | ConversationCompactionSummaryItem;
+export interface ConversationMessageItem {
+    type: "message";
+    role: MessageRole;
+    content: string;
+    contentFormat?: "string" | "block";
+}
+export interface ConversationAttachmentItem {
+    type: "attachment";
+    role: "user";
+    attachment: AttachmentContentBlock;
+}
+export interface ConversationReasoningItem {
+    type: "reasoning";
+    id?: string;
+    summary: string;
+    encryptedContent?: string;
+}
+export interface ConversationFunctionCallItem {
+    type: "function_call";
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+}
+export interface ConversationFunctionOutputItem {
+    type: "function_output";
+    callId: string;
+    name?: string;
+    content: string;
+    isError?: boolean;
+    metadata?: Record<string, ToolResultMetadata>;
+}
+export interface ConversationCompactionSummaryItem {
+    type: "compaction_summary";
+    summary: string;
+}
+export declare function messagesToConversationItems(messages: Message[]): ConversationItem[];
+export declare function conversationItemsToMessages(items: ConversationItem[]): Message[];
+export declare function contentBlocksToConversationItems(content: ContentBlock[], reasoning?: string, reasoningItems?: ConversationReasoningItem[]): ConversationItem[];
+export declare function conversationItemsToText(items: ConversationItem[]): string;
+export declare function conversationItemToText(item: ConversationItem): string;

package/dist/types/conversation.js

@@ -0,0 +1,201 @@
+export function messagesToConversationItems(messages) {
+    const items = [];
+    for (const message of messages) {
+        if (typeof message.content === "string") {
+            items.push({
+                type: "message",
+                role: message.role,
+                content: message.content,
+                contentFormat: "string",
+            });
+            continue;
+        }
+        for (const block of message.content) {
+            switch (block.type) {
+                case "text":
+                    items.push({
+                        type: "message",
+                        role: message.role,
+                        content: block.text,
+                        contentFormat: "block",
+                    });
+                    break;
+                case "image":
+                case "file":
+                    items.push({
+                        type: "attachment",
+                        role: "user",
+                        attachment: block,
+                    });
+                    break;
+                case "tool_use":
+                    items.push({
+                        type: "function_call",
+                        id: block.id,
+                        name: block.name,
+                        input: block.input,
+                    });
+                    break;
+                case "tool_result":
+                    items.push({
+                        type: "function_output",
+                        callId: block.toolUseId,
+                        content: block.content,
+                        ...(block.isError !== undefined ? { isError: block.isError } : {}),
+                        ...(block.metadata !== undefined ? { metadata: block.metadata } : {}),
+                    });
+                    break;
+            }
+        }
+    }
+    return items;
+}
+export function conversationItemsToMessages(items) {
+    const messages = [];
+    let pendingAssistantBlocks = [];
+    let pendingUserBlocks = [];
+    const flushAssistantBlocks = () => {
+        if (pendingAssistantBlocks.length === 0)
+            return;
+        messages.push({ role: "assistant", content: pendingAssistantBlocks });
+        pendingAssistantBlocks = [];
+    };
+    const flushUserBlocks = () => {
+        if (pendingUserBlocks.length === 0)
+            return;
+        messages.push({ role: "user", content: pendingUserBlocks });
+        pendingUserBlocks = [];
+    };
+    for (const item of items) {
+        switch (item.type) {
+            case "message":
+                if (item.contentFormat === "block") {
+                    if (item.role === "assistant") {
+                        flushUserBlocks();
+                        pendingAssistantBlocks.push({ type: "text", text: item.content });
+                    }
+                    else {
+                        flushAssistantBlocks();
+                        pendingUserBlocks.push({ type: "text", text: item.content });
+                    }
+                    break;
+                }
+                flushAssistantBlocks();
+                flushUserBlocks();
+                messages.push({
+                    role: item.role,
+                    content: item.content,
+                });
+                break;
+            case "attachment":
+                flushAssistantBlocks();
+                pendingUserBlocks.push(item.attachment);
+                break;
+            case "reasoning":
+                break;
+            case "function_call":
+                flushUserBlocks();
+                pendingAssistantBlocks.push({
+                    type: "tool_use",
+                    id: item.id,
+                    name: item.name,
+                    input: item.input,
+                });
+                break;
+            case "function_output":
+                flushAssistantBlocks();
+                pendingUserBlocks.push({
+                    type: "tool_result",
+                    toolUseId: item.callId,
+                    content: item.content,
+                    ...(item.isError !== undefined ? { isError: item.isError } : {}),
+                    ...(item.metadata !== undefined ? { metadata: item.metadata } : {}),
+                });
+                break;
+            case "compaction_summary":
+                flushAssistantBlocks();
+                flushUserBlocks();
+                messages.push({
+                    role: "user",
+                    content: [{ type: "text", text: item.summary }],
+                });
+                break;
+        }
+    }
+    flushAssistantBlocks();
+    flushUserBlocks();
+    return messages;
+}
+export function contentBlocksToConversationItems(content, reasoning, reasoningItems) {
+    const items = [];
+    if (reasoningItems && reasoningItems.length > 0) {
+        items.push(...reasoningItems);
+    }
+    else if (reasoning) {
+        items.push({ type: "reasoning", summary: reasoning });
+    }
+    for (const block of content) {
+        switch (block.type) {
+            case "text":
+                items.push({
+                    type: "message",
+                    role: "assistant",
+                    content: block.text,
+                    contentFormat: "block",
+                });
+                break;
+            case "image":
+            case "file":
+                items.push({
+                    type: "attachment",
+                    role: "user",
+                    attachment: block,
+                });
+                break;
+            case "tool_use":
+                items.push({
+                    type: "function_call",
+                    id: block.id,
+                    name: block.name,
+                    input: block.input,
+                });
+                break;
+            case "tool_result":
+                items.push({
+                    type: "function_output",
+                    callId: block.toolUseId,
+                    content: block.content,
+                    ...(block.isError !== undefined ? { isError: block.isError } : {}),
+                    ...(block.metadata !== undefined ? { metadata: block.metadata } : {}),
+                });
+                break;
+        }
+    }
+    return items;
+}
+export function conversationItemsToText(items) {
+    return items.map(conversationItemToText).join("\n");
+}
+export function conversationItemToText(item) {
+    switch (item.type) {
+        case "message":
+            return item.content;
+        case "attachment":
+            return `${item.attachment.type} attachment ${formatAttachmentName(item.attachment)}`;
+        case "reasoning":
+            return `reasoning ${item.summary}`;
+        case "function_call":
+            return `function_call ${item.id} ${item.name} ${JSON.stringify(item.input)}`;
+        case "function_output":
+            return `function_output ${item.callId} ${item.isError ? "error" : "ok"} ${item.content} ${JSON.stringify(item.metadata ?? {})}`;
+        case "compaction_summary":
+            return item.summary;
+    }
+}
+function formatAttachmentName(attachment) {
+    const name = attachment.name ? `${attachment.name} ` : "";
+    if (attachment.source.type === "url") {
+        return `${name}${attachment.source.url}`;
+    }
+    return `${name}${attachment.source.mediaType}`;
+}