@codmir/agent

@codmir/agent

Core agent logic for Codmir - reusable in IDE (local) and cloud (remote) modes.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        @codmir/agent                             │
│                                                                  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐   │
│  │   Session    │  │    Tools     │  │     AI Client        │   │
│  │   Manager    │  │   Executor   │  │   (Streaming)        │   │
│  └──────────────┘  └──────────────┘  └──────────────────────┘   │
│                                                                  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐   │
│  │   Context    │  │    Tool      │  │     Approval         │   │
│  │   Provider   │  │  Definitions │  │     Handler          │   │
│  └──────────────┘  └──────────────┘  └──────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
        ┌──────────┐   ┌──────────┐   ┌──────────────┐
        │   IDE    │   │  Cloud   │   │   Claude     │
        │  (local) │   │ (remote) │   │   Code API   │
        └──────────┘   └──────────┘   └──────────────┘

Modes

Local Mode (IDE)

• Session runs on user's machine
• Connection active while IDE is open
• Session ends when IDE closes
• Faster response (no network latency for tools)

Cloud Mode (Remote)

• Session runs on Codmir servers
• User can close IDE, session persists
• Session continues in background
• Results synced when user reconnects

Usage

In IDE (Local Mode)

import { createAgent, LocalSessionManager } from '@codmir/agent';
import { FileSystemAdapter } from './adapters/filesystem';

const agent = createAgent({
  mode: 'local',
  sessionManager: new LocalSessionManager(),
  contextProvider: new FileSystemAdapter(workspaceRoot),
  aiConfig: {
    provider: 'codmir', // or 'openai', 'anthropic'
    apiKey: process.env.CODMIR_API_KEY,
  },
});

// Start a session
const session = await agent.createSession({
  prompt: 'Fix the bug in auth.ts',
});

// Listen to events
agent.on('thinking', (data) => updateUI('thinking', data));
agent.on('tool_call', (data) => showToolCall(data));
agent.on('response_chunk', (data) => appendToChat(data));
agent.on('complete', (data) => finalizeResponse(data));

// Approve tool calls
await agent.approveToolCall(session.id, toolCallId);

In Cloud (Remote Mode)

import { createAgent, CloudSessionManager } from '@codmir/agent';
import { RemoteFileAdapter } from './adapters/remote';

const agent = createAgent({
  mode: 'cloud',
  sessionManager: new CloudSessionManager({
    redis: redisClient,
    persistSessions: true,
  }),
  contextProvider: new RemoteFileAdapter(ideConnection),
  aiConfig: {
    provider: 'codmir',
    apiKey: process.env.CODMIR_API_KEY,
  },
});

// Session persists even if client disconnects
const session = await agent.resumeSession(sessionId);

Tools

Built-in tools available to the agent:

Tool	Description
read_file	Read file contents
write_file	Write/create file
edit_file	Apply targeted edits
list_directory	List files in directory
search_files	Search for text in files
run_command	Execute terminal command
git_status	Get git status
git_diff	Get git diff
ask_user	Ask user a question

Custom Tools

import { defineTool } from '@codmir/agent/tools';

const myTool = defineTool({
  name: 'my_custom_tool',
  description: 'Does something custom',
  parameters: z.object({
    input: z.string(),
  }),
  execute: async (params, context) => {
    // Your logic here
    return { result: 'done' };
  },
});

agent.registerTool(myTool);

Session Lifecycle

User Input
    │
    ▼
┌─────────────────┐
│ Create Session  │ ◄─── New conversation
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   AI Thinking   │ ◄─── Streaming response
└────────┬────────┘
         │
         ▼
┌─────────────────┐     ┌─────────────────┐
│   Tool Call?    │────►│ Execute Tool    │
└────────┬────────┘     └────────┬────────┘
         │                       │
         │◄──────────────────────┘
         ▼
┌─────────────────┐
│    Response     │ ◄─── Final answer
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Session Active  │ ◄─── Ready for next message
└─────────────────┘
         │
    Local: closes with IDE
    Cloud: persists until timeout

Events

Event	Description
session_created	New session started
thinking_started	AI is processing
response_chunk	Streaming text chunk
tool_call_created	AI wants to use a tool
tool_call_approved	User approved tool
tool_call_rejected	User rejected tool
tool_call_started	Tool execution began
tool_call_completed	Tool finished successfully
tool_call_failed	Tool execution failed
response_complete	Full response ready
session_error	Error occurred
session_ended	Session terminated