@germanescobar/anita 0.3.0

package/README.md

@@ -0,0 +1,353 @@
+# Coding Agent
+
+An intelligent AI-powered coding agent that helps you write, edit, and run code. It provides conversational interactions with AI models while having direct access to your file system and shell commands.
+
+## Features
+
+- **Conversational AI** - Chat with AI models using natural language
+- **File System Tools** - Read, write, and edit files seamlessly
+- **Command Execution** - Run shell commands safely with approval prompts
+- **Session Management** - Resume previous conversations and track history
+- **Multi-Provider Support** - Switch between local Ollama, Ollama Cloud, and OpenRouter models
+- **Event Logging** - Track all interactions and tool executions
+- **Reasoning Capture** - Preserve provider-exposed reasoning traces when available
+- **Type-Safe** - Built with TypeScript for reliability and type safety
+
+## Installation
+
+Install from npm:
+
+```bash
+npm install -g @germanescobar/anita
+```
+
+That installs the `anita` command globally, so users can run:
+
+```bash
+anita chat "Create a simple React component that displays a greeting"
+```
+
+## Local Development Install
+
+To install from a local checkout:
+
+```bash
+# Clone the repository
+git clone <repository-url>
+cd coding-agent
+
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+
+# Install the anita command globally from this checkout
+npm link
+```
+
+After that, the `anita` command will be available in your shell.
+
+`npm link` is typically a one-time setup step for a local checkout. After changing files in `src/`, run:
+
+```bash
+npm run build
+```
+
+You only need to run `npm link` again if the package's global command setup changes, such as the package name or the `bin` mapping in `package.json`.
+
+If you don't want to install it globally, you can also run it directly from the repository with:
+
+```bash
+npm run start -- <command>
+```
+
+## Usage
+
+### Basic Chat
+
+Start a new conversation:
+
+```bash
+anita chat "Create a simple React component that displays a greeting"
+```
+
+### Resume a Session
+
+Continue from a previous conversation:
+
+```bash
+anita chat "Can you explain this code?" --resume <session-id>
+```
+
+### List Past Sessions
+
+```bash
+anita sessions
+```
+
+### View Event Logs
+
+View detailed events for a specific session:
+
+```bash
+anita events <session-id>
+```
+
+### List Supported Models
+
+Show the built-in model choices grouped by provider:
+
+```bash
+anita models
+```
+
+Each listed value is a `provider/model` string that can be passed to `--model`. Local Ollama models use the `ollama/` provider, while Ollama Cloud models use `ollama-cloud/`.
+Models that support attachments are annotated with `[images]`, `[files]`, or both.
+
+### Custom Model
+
+Use a different AI model:
+
+```bash
+anita chat "Your message here" --model ollama/glm-4.7-flash:latest
+```
+
+### Additional System Prompt
+
+Add run-specific system instructions:
+
+```bash
+anita chat "Review this module" --system-prompt "Be concise and prioritize correctness issues."
+```
+
+`--system-prompt` is additive. It does not replace Anita's built-in instructions, safety rules, user instructions, or tool permission policy.
+
+Attach an image or PDF to models that support the relevant attachment type:
+
+```bash
+anita chat "Explain this screenshot" --model openrouter/moonshotai/kimi-k2.6 --attach ./screen.png
+anita chat "Summarize this brief" --model ollama-cloud/minimax-m3 --attach ./brief.pdf
+```
+
+`--attach` accepts local paths or HTTP(S) URLs and can be repeated. Supported local attachment types are `png`, `jpg`, `jpeg`, `webp`, `gif`, and `pdf`.
+
+### AGENTS.md Instructions
+
+Anita automatically includes AGENTS.md guidance in the system prompt when it builds context for a chat session.
+
+Discovery order:
+
+1. Global defaults from `~/.anita/AGENTS.md`
+2. Repository instructions from `<repo-root>/AGENTS.md`
+
+When both files exist, repository instructions are placed after global instructions and override them when they conflict.
+
+Create a global instructions file:
+
+```bash
+anita agents init --global
+```
+
+Create a repository instructions file at the Git repository root, or in the current directory when outside Git:
+
+```bash
+anita agents init
+```
+
+Use `--force` with either command to overwrite an existing file.
+
+### Context Compaction
+
+Anita tracks an approximate context budget for each session. When the model context reaches a high-water mark for the selected model's context window, Anita folds older history into a rolling summary while keeping a recent token-budgeted tail, including recent tool calls and tool results, available verbatim.
+
+By default, compaction starts around 80% of the usable model context window after reserving response tokens, preserves roughly 24,000 recent tokens, and skips compaction when the older prefix is too small to reduce context meaningfully.
+
+### Ollama Cloud
+
+Use a supported Ollama Cloud model with the `ollama-cloud/` provider. This is separate from the local `ollama/` provider, which still targets a local Ollama daemon.
+
+```bash
+export OLLAMA_API_KEY=<your-ollama-api-key>
+anita chat "Your message here" --model ollama-cloud/glm-5.2
+```
+
+Supported Ollama Cloud models:
+
+- `ollama-cloud/glm-5.2`
+- `ollama-cloud/minimax-m3` `[images, files]`
+- `ollama-cloud/deepseek-v4-pro`
+- `ollama-cloud/kimi-k2.7-code` `[images]`
+
+Ollama Cloud requests use an explicit `max_tokens` value of 8192 so the provider leaves context room for the prompt.
+
+### JSON Event Streaming
+
+Use `--stream-json` to emit one JSON event per line for machine-readable integrations:
+
+```bash
+anita chat "Add a hello world script" --stream-json
+```
+
+Example stream:
+
+```json
+{"type":"run.started","sessionId":"9e6f8a7d-7ff1-4c2c-b3d8-9c3ed5a1d4b7","model":"ollama/glm-4.7-flash:latest","workingDirectory":"/path/to/project","timestamp":"2026-04-09T15:00:00.000Z"}
+{"type":"assistant.reasoning","text":"I should inspect the project structure before changing files."}
+{"type":"assistant.text","text":"I added a hello world script."}
+{"type":"tool.call","id":"toolu_123","name":"write_file","input":{"path":"hello.js","content":"console.log(\"hello world\");\n"}}
+{"type":"tool.result","id":"toolu_123","name":"write_file","content":"File written successfully.","isError":false}
+{"type":"run.completed","sessionId":"9e6f8a7d-7ff1-4c2c-b3d8-9c3ed5a1d4b7","status":"completed","stopReason":"end_turn","timestamp":"2026-04-09T15:00:01.000Z"}
+```
+
+Without `--stream-json`, the CLI uses the normal human-readable terminal output.
+
+When using an OpenAI-compatible backend that exposes reasoning traces, Anita will also store them in the `assistant_response` event payload as `reasoning` and emit an `assistant.reasoning` stream event.
+
+## Publishing
+
+To publish the package to npm under the `@germanescobar` scope:
+
+```bash
+# Log in to npm
+npm login
+
+# Build and publish the public scoped package
+npm publish --access public
+```
+
+After publishing, users can install it with:
+
+```bash
+npm install -g @germanescobar/anita
+```
+
+## Architecture
+
+The Coding Agent is built with a modular architecture:
+
+### Core Components
+
+- **Agent Loop** - Manages the conversation cycle, including message handling and tool execution
+- **Context Builder** - Separates stable agent instructions from dynamic environment context
+- **Executor** - Executes AI-generated tool calls with safety policies
+- **Provider** - Abstracts OpenAI-compatible AI model interactions
+- **Tool Registry** - Manages available tools and their schemas
+
+### Storage Layer
+
+- **Event Store** - Persist all interactions and events
+- **Session Store** - Save and retrieve conversation sessions
+
+### Tools
+
+- **read-file** - Read file contents
+- **write-file** - Create or overwrite files
+- **edit-file** - Edit existing files with precise replacements
+- **run-command** - Execute shell commands (with approval)
+
+## Project Structure
+
+```
+coding-agent/
+├── src/
+│   ├── agent/
+│   │   ├── context-builder.ts    # Builds static prompts and dynamic context
+│   │   ├── executor.ts            # Executes tool calls safely
+│   │   ├── loop.ts                # Main conversation loop
+│   │   ├── policies.ts            # Safety and approval policies
+│   │   └── session.ts             # Session management
+│   ├── cli/
+│   │   └── index.ts               # Command-line interface
+│   ├── models/
+│   │   ├── anthropic.ts           # Anthropic Claude provider implementation
+│   │   ├── openai.ts              # OpenAI-compatible provider implementation
+│   │   ├── provider.ts            # AI provider abstraction
+│   │   └── resolve.ts             # Provider factory
+│   ├── storage/
+│   │   ├── event-store.ts         # Persistent event store
+│   │   └── session-store.ts       # Persistent session store
+│   ├── tools/
+│   │   ├── edit-file.ts           # Edit file tool
+│   │   ├── read-file.ts           # Read file tool
+│   │   ├── registry.ts            # Tool registry and schema generation
+│   │   └── run-command.ts         # Command execution tool
+│   ├── types/
+│   │   ├── agent.ts               # Agent type definitions
+│   │   ├── events.ts              # Event types
+│   │   ├── messages.ts            # Message type definitions
+│   │   └── tools.ts               # Tool type definitions
+│   ├── CLI.ts
+│   └── index.ts
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+## How It Works
+
+1. **User sends a message** via the CLI
+2. **Context is built** based on the current working directory and conversation history
+3. **AI model processes** the message and determines if tools are needed
+4. **Tool execution** happens if needed (safely with approval prompts)
+5. **Results are passed** back to the AI for further processing
+6. **Final response** is displayed to the user
+7. **Session is saved** with all messages and events
+
+## API Compatibility
+
+Available providers (provider/model format):
+
+- `ollama/<local-model>`
+- `ollama-cloud/glm-5.2`
+- `ollama-cloud/minimax-m3`
+- `ollama-cloud/deepseek-v4-pro`
+- `ollama-cloud/kimi-k2.7-code`
+- `openrouter/z-ai/glm-5.1`
+- `openrouter/minimax/minimax-m3`
+- `openrouter/deepseek/deepseek-v4-pro`
+- `openrouter/moonshotai/kimi-k2.6`
+
+`ollama/<local-model>` targets `http://localhost:11434/v1`. `ollama-cloud/<model>` targets Ollama Cloud and uses `OLLAMA_API_KEY`. `openrouter/<model>` targets OpenRouter and uses `OPENROUTER_API_KEY`.
+
+## Configuration
+
+Session data is stored in the `.anita/` directory in your working directory:
+
+```
+.anita/
+├── events/          # Individual event logs
+│   └── <session-id>/
+└── sessions/        # Session metadata
+    └── <session-id>
+```
+
+For backward compatibility, Anita falls back to the legacy `.coding-agent/` directory when it contains existing sessions and `.anita/` does not.
+
+## Development
+
+```bash
+# Run the CLI in development mode
+npm run dev -- chat "Create a simple React component that displays a greeting"
+
+# Build for production
+npm run build
+
+# Run the built CLI without installing it globally
+npm run start -- chat "Create a simple React component that displays a greeting"
+```
+
+## Safety Considerations
+
+- All shell commands require explicit approval before execution
+- Tool results are previewed before being shown to the AI
+- File modifications can be reviewed via event logs
+- Maximum iteration limit prevents infinite loops (default: 50)
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Feel free to submit issues and pull requests.

package/dist/agent/agents.d.ts

@@ -0,0 +1,16 @@
+export type AgentInstructionsScope = "global" | "repository";
+export interface AgentInstructionsFile {
+    scope: AgentInstructionsScope;
+    path: string;
+    content: string;
+}
+export interface LoadAgentInstructionsOptions {
+    cwd: string;
+    homeDir?: string;
+    repositoryRoot?: string;
+}
+export declare function getGlobalAgentsPath(homeDir?: string): string;
+export declare function getProjectAgentsPath(cwd: string): string;
+export declare function getRepositoryAgentsPath(cwd: string): string;
+export declare function loadAgentInstructions(options: LoadAgentInstructionsOptions): AgentInstructionsFile[];
+export declare function formatAgentInstructionsForPrompt(files: AgentInstructionsFile[]): string;

package/dist/agent/agents.js

@@ -0,0 +1,115 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+const AGENTS_FILE_NAME = "AGENTS.md";
+const CONFIG_DIR_NAME = ".anita";
+const LEGACY_CONFIG_DIR_NAME = ".ada";
+/* Canonical location for the global AGENTS.md. Used when writing the file. */
+export function getGlobalAgentsPath(homeDir = os.homedir()) {
+    return path.join(homeDir, CONFIG_DIR_NAME, AGENTS_FILE_NAME);
+}
+/*
+ * Resolve the global AGENTS.md for reading, preferring the canonical `.anita`
+ * directory and falling back to the legacy `.ada` directory so existing
+ * configurations keep working after the rename.
+ */
+function resolveReadableGlobalAgentsPath(homeDir) {
+    const primary = path.join(homeDir, CONFIG_DIR_NAME, AGENTS_FILE_NAME);
+    if (fs.existsSync(primary))
+        return primary;
+    const legacy = path.join(homeDir, LEGACY_CONFIG_DIR_NAME, AGENTS_FILE_NAME);
+    if (fs.existsSync(legacy))
+        return legacy;
+    return primary;
+}
+export function getProjectAgentsPath(cwd) {
+    return path.join(cwd, AGENTS_FILE_NAME);
+}
+export function getRepositoryAgentsPath(cwd) {
+    return getProjectAgentsPath(findRepositoryRoot(cwd) ?? cwd);
+}
+export function loadAgentInstructions(options) {
+    const repositoryRoot = options.repositoryRoot ?? findRepositoryRoot(options.cwd) ?? options.cwd;
+    const candidates = [
+        {
+            scope: "global",
+            path: resolveReadableGlobalAgentsPath(options.homeDir ?? os.homedir()),
+        },
+        { scope: "repository", path: getProjectAgentsPath(repositoryRoot) },
+    ];
+    const loaded = [];
+    const seenPaths = new Set();
+    for (const candidate of candidates) {
+        const file = readInstructionsFile(candidate.scope, candidate.path);
+        if (!file)
+            continue;
+        let realPath = file.path;
+        try {
+            realPath = fs.realpathSync(file.path);
+        }
+        catch {
+            realPath = file.path;
+        }
+        if (seenPaths.has(realPath))
+            continue;
+        seenPaths.add(realPath);
+        loaded.push(file);
+    }
+    return loaded;
+}
+export function formatAgentInstructionsForPrompt(files) {
+    if (files.length === 0)
+        return "";
+    const lines = [
+        "",
+        "Additional instructions from AGENTS.md files:",
+        "AGENTS.md instructions are subordinate to Anita's built-in safety rules, user instructions, and tool permission policy.",
+        "Instructions from later AGENTS.md files override earlier AGENTS.md files only when they conflict with each other.",
+    ];
+    for (const file of files) {
+        const label = file.scope === "global" ? "Global" : "Repository";
+        lines.push("");
+        lines.push(`${label} AGENTS.md (${file.path}):`);
+        lines.push(file.content.trimEnd());
+    }
+    return lines.join("\n");
+}
+function findRepositoryRoot(cwd) {
+    try {
+        const output = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+            cwd,
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 5000,
+        });
+        const root = output.trim();
+        return root.length > 0 ? root : null;
+    }
+    catch {
+        return null;
+    }
+}
+function readInstructionsFile(scope, filePath) {
+    try {
+        const stat = fs.statSync(filePath);
+        if (!stat.isFile())
+            return null;
+        return {
+            scope,
+            path: filePath,
+            content: fs.readFileSync(filePath, "utf-8"),
+        };
+    }
+    catch (err) {
+        if (isMissingPathError(err))
+            return null;
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`Failed to read ${filePath}: ${message}`);
+    }
+}
+function isMissingPathError(err) {
+    if (!(err instanceof Error))
+        return false;
+    return "code" in err && (err.code === "ENOENT" || err.code === "ENOTDIR");
+}

package/dist/agent/context-budget.d.ts

@@ -0,0 +1,7 @@
+export interface ContextBudgetOptions {
+    thresholdTokens: number;
+    preserveRecentMessages: number;
+    summaryMaxCharacters?: number;
+}
+export declare const DEFAULT_CONTEXT_BUDGET: ContextBudgetOptions;
+export declare function getDefaultContextBudget(modelString: string): ContextBudgetOptions;

package/dist/agent/context-budget.js

@@ -0,0 +1,17 @@
+export const DEFAULT_CONTEXT_BUDGET = {
+    thresholdTokens: 120_000,
+    preserveRecentMessages: 8,
+    summaryMaxCharacters: 6_000,
+};
+const KIMI_CLOUD_CONTEXT_BUDGET = {
+    ...DEFAULT_CONTEXT_BUDGET,
+    thresholdTokens: 48_000,
+};
+export function getDefaultContextBudget(modelString) {
+    const normalizedModel = modelString.toLowerCase();
+    if (normalizedModel.startsWith("ollama-cloud/") &&
+        normalizedModel.includes("kimi")) {
+        return KIMI_CLOUD_CONTEXT_BUDGET;
+    }
+    return DEFAULT_CONTEXT_BUDGET;
+}

package/dist/agent/context-builder.d.ts

@@ -0,0 +1,34 @@
+import type { ApprovalMode, PolicyContext } from "./policies.js";
+import type { ConversationItem } from "../types/conversation.js";
+import type { Message } from "../types/messages.js";
+import type { Skill } from "../skills/skills.js";
+export type NetworkAccess = "available" | "unavailable" | "unknown";
+export interface RuntimeContextOptions {
+    shell?: string;
+    approvalMode?: ApprovalMode;
+    networkAccess?: NetworkAccess;
+    writeScope?: string;
+    policyContext?: PolicyContext;
+    skills?: Skill[];
+    agentsHomeDir?: string;
+    agentsRepositoryRoot?: string;
+    systemPrompt?: string;
+}
+export declare class ContextBuilder {
+    private workingDirectory;
+    private runtimeContext;
+    constructor(workingDirectory: string, runtimeContext?: RuntimeContextOptions);
+    buildSystemPrompt(): string;
+    private buildUserSystemPromptSection;
+    private buildEnvironmentFooter;
+    buildDynamicContext(): Promise<string>;
+    buildMessagesWithDynamicContext(messages: Message[]): Promise<Message[]>;
+    buildItemsWithDynamicContext(items: ConversationItem[]): Promise<ConversationItem[]>;
+    private buildEnvironmentContext;
+    private buildPolicyContext;
+    private describeApprovalMode;
+    private describeNetworkAccess;
+    private describeDecision;
+    private getGitContext;
+    private runQuiet;
+}