@charming_groot/agent 0.1.0

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@charming_groot/agent",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "ReAct agent loop with sub-agent support, token counting, and message compression for CLI Agent",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@charming_groot/core": "workspace:*",
+    "@charming_groot/providers": "workspace:*",
+    "js-tiktoken": "^1.0.21"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0"
+  },
+  "keywords": ["agent", "cli", "llm", "react", "sub-agent", "parallel"],
+  "license": "MIT"
+}

package/src/agent-loop.ts

@@ -0,0 +1,210 @@
+import type {
+  ILlmProvider,
+  ITool,
+  AgentConfig,
+  ToolDescription,
+  LlmResponse,
+  Message,
+  AgentLogger,
+} from '@charming_groot/core';
+import {
+  Registry,
+  RunContext,
+  EventBus,
+  AbortError,
+  createChildLogger,
+} from '@charming_groot/core';
+import { MessageManager } from './message-manager.js';
+import { ToolDispatcher } from './tool-dispatcher.js';
+import { PermissionManager, type PermissionHandler } from './permission.js';
+
+/**
+ * Callback that builds/rebuilds the system prompt dynamically.
+ * Called before each LLM iteration so the prompt can reflect
+ * current state (open files, cwd, etc.) without a hard dependency
+ * on @core/context-engine.
+ */
+export type SystemPromptBuilder = (context: RunContext) => string | Promise<string>;
+
+export interface AgentLoopOptions {
+  provider: ILlmProvider;
+  toolRegistry: Registry<ITool>;
+  config: AgentConfig;
+  permissionHandler?: PermissionHandler;
+  eventBus?: EventBus;
+  streaming?: boolean;
+  /** Dynamic system prompt builder — takes precedence over config.systemPrompt */
+  systemPromptBuilder?: SystemPromptBuilder;
+}
+
+export interface AgentResult {
+  readonly content: string;
+  readonly runId: string;
+  readonly iterations: number;
+  readonly aborted: boolean;
+}
+
+export class AgentLoop {
+  private readonly provider: ILlmProvider;
+  private readonly toolDispatcher: ToolDispatcher;
+  private readonly messageManager: MessageManager;
+  private readonly context: RunContext;
+  private readonly maxIterations: number;
+  private readonly logger: AgentLogger;
+  private readonly streaming: boolean;
+  private readonly systemPromptBuilder?: SystemPromptBuilder;
+  private iterations = 0;
+
+  constructor(options: AgentLoopOptions) {
+    const eventBus = options.eventBus ?? new EventBus();
+    this.context = new RunContext(options.config, eventBus);
+    this.provider = options.provider;
+    this.messageManager = new MessageManager();
+    this.maxIterations = options.config.maxIterations;
+    this.logger = createChildLogger('agent-loop');
+    this.streaming = options.streaming ?? false;
+    this.systemPromptBuilder = options.systemPromptBuilder;
+
+    const permissionManager = new PermissionManager(options.permissionHandler);
+    this.toolDispatcher = new ToolDispatcher(options.toolRegistry, permissionManager);
+
+    // Static system prompt used only when no dynamic builder is provided
+    if (!this.systemPromptBuilder && options.config.systemPrompt) {
+      this.messageManager.addSystemMessage(options.config.systemPrompt);
+    }
+  }
+
+  get runId(): string {
+    return this.context.runId;
+  }
+
+  get eventBus(): EventBus {
+    return this.context.eventBus;
+  }
+
+  async run(userMessage: string): Promise<AgentResult> {
+    this.messageManager.addUserMessage(userMessage);
+    const agentStartedAt = Date.now();
+    this.context.eventBus.emit('agent:start', {
+      runId: this.context.runId,
+      model: this.context.config.provider.model,
+      startedAt: agentStartedAt,
+    });
+    this.iterations = 0;
+
+    try {
+      let lastContent = '';
+
+      while (this.iterations < this.maxIterations) {
+        if (this.context.isAborted) {
+          throw new AbortError('Agent loop aborted');
+        }
+
+        this.iterations++;
+        this.logger.debug({ iteration: this.iterations }, 'Starting iteration');
+
+        // Rebuild system prompt dynamically if builder is provided
+        if (this.systemPromptBuilder) {
+          const prompt = await this.systemPromptBuilder(this.context);
+          this.messageManager.setSystemMessage(prompt);
+        }
+
+        const compressed = this.messageManager.compressIfNeeded();
+        if (compressed > 0) {
+          this.logger.info({ compressed }, 'History compressed');
+        }
+
+        const toolDescriptions = this.getToolDescriptions();
+        const messages = this.messageManager.getMessages();
+
+        this.context.eventBus.emit('llm:request', {
+          runId: this.context.runId,
+          messages,
+        });
+
+        const llmStartedAt = Date.now();
+        const response = this.streaming
+          ? await this.streamResponse(messages, toolDescriptions)
+          : await this.provider.chat(messages, toolDescriptions);
+
+        this.context.eventBus.emit('llm:response', {
+          runId: this.context.runId,
+          response,
+          durationMs: Date.now() - llmStartedAt,
+          model: this.context.config.provider.model,
+        });
+
+        lastContent = response.content;
+
+        if (response.stopReason === 'end_turn' || response.toolCalls.length === 0) {
+          this.messageManager.addAssistantMessage(response.content);
+          break;
+        }
+
+        // Tool use flow
+        this.messageManager.addAssistantMessage(response.content, response.toolCalls);
+        const results = await this.toolDispatcher.dispatchAll(
+          response.toolCalls,
+          this.context
+        );
+        this.messageManager.addToolResults(results);
+      }
+
+      const aborted = this.context.isAborted;
+      this.context.eventBus.emit('agent:end', {
+        runId: this.context.runId,
+        reason: aborted ? 'aborted' : 'complete',
+        durationMs: Date.now() - agentStartedAt,
+        iterations: this.iterations,
+      });
+
+      return {
+        content: lastContent,
+        runId: this.context.runId,
+        iterations: this.iterations,
+        aborted,
+      };
+    } catch (error) {
+      this.context.eventBus.emit('agent:error', {
+        runId: this.context.runId,
+        error: error instanceof Error ? error : new Error(String(error)),
+      });
+      throw error;
+    }
+  }
+
+  abort(reason?: string): void {
+    this.context.abort(reason);
+  }
+
+  getContext(): RunContext {
+    return this.context;
+  }
+
+  private async streamResponse(
+    messages: readonly Message[],
+    tools: ToolDescription[]
+  ): Promise<LlmResponse> {
+    let finalResponse: LlmResponse | undefined;
+
+    for await (const event of this.provider.stream(messages, tools)) {
+      if (event.type === 'text_delta' && event.content) {
+        this.context.eventBus.emit('llm:stream', {
+          runId: this.context.runId,
+          chunk: event.content,
+        });
+      } else if (event.type === 'done' && event.response) {
+        finalResponse = event.response;
+      }
+    }
+
+    if (!finalResponse) {
+      throw new Error('Stream ended without a final response');
+    }
+    return finalResponse;
+  }
+
+  private getToolDescriptions(): ToolDescription[] {
+    return this.toolDispatcher.getToolDescriptions();
+  }
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+export { AgentLoop } from './agent-loop.js';
+export type { AgentLoopOptions, AgentResult, SystemPromptBuilder } from './agent-loop.js';
+export { MessageManager } from './message-manager.js';
+export type { CompressionConfig } from './message-manager.js';
+export { countTextTokens, countMessageTokens, countHistoryTokens } from './token-counter.js';
+export { ToolDispatcher } from './tool-dispatcher.js';
+export { PermissionManager } from './permission.js';
+export type {
+  PermissionHandler,
+  PermissionDecision,
+  ApprovalLevel,
+  PersistApprovalCallback,
+} from './permission.js';
+export { SubAgentTool } from './sub-agent-tool.js';
+export type { SubAgentToolConfig } from './sub-agent-tool.js';
+export { SkillTool } from './skill-tool.js';
+export type { SkillEntry, SkillProvider } from './skill-tool.js';
+export { SessionManager } from './session-manager.js';
+export type { SessionMeta } from './session-manager.js';

package/src/message-manager.ts

@@ -0,0 +1,184 @@
+import type { Message, ToolCall, ToolResult } from '@charming_groot/core';
+import { countHistoryTokens } from './token-counter.js';
+
+export interface CompressionConfig {
+  /** Maximum tokens in history before compression triggers (default: 100_000) */
+  maxHistoryTokens?: number;
+  /** Number of recent non-system messages to keep intact (default: 10) */
+  keepRecentMessages?: number;
+  /** Truncate individual message content to this length in summary (default: 300) */
+  summaryContentLength?: number;
+}
+
+export class MessageManager {
+  private readonly messages: Message[] = [];
+  private readonly maxHistoryTokens: number;
+  private readonly keepRecentMessages: number;
+  private readonly summaryContentLength: number;
+
+  constructor(config: CompressionConfig = {}) {
+    this.maxHistoryTokens     = config.maxHistoryTokens     ?? 100_000;
+    this.keepRecentMessages   = config.keepRecentMessages   ?? 10;
+    this.summaryContentLength = config.summaryContentLength ?? 300;
+  }
+
+  addSystemMessage(content: string): void {
+    this.messages.push({ role: 'system', content });
+  }
+
+  setSystemMessage(content: string): void {
+    const idx = this.messages.findIndex(m => m.role === 'system');
+    if (idx >= 0) {
+      this.messages[idx] = { role: 'system', content };
+    } else {
+      this.messages.unshift({ role: 'system', content });
+    }
+  }
+
+  addUserMessage(content: string): void {
+    this.messages.push({ role: 'user', content });
+  }
+
+  addAssistantMessage(content: string, toolCalls?: readonly ToolCall[]): void {
+    this.messages.push({
+      role: 'assistant',
+      content,
+      toolCalls: toolCalls ? [...toolCalls] : undefined,
+    });
+  }
+
+  addToolResults(results: ReadonlyMap<string, ToolResult>): void {
+    const toolResults = [...results.entries()].map(([toolCallId, result]) => ({
+      toolCallId,
+      content: result.success
+        ? result.output
+        : `Error: ${result.error ?? 'Unknown error'}`,
+    }));
+    this.messages.push({ role: 'user', content: '', toolResults });
+  }
+
+  getMessages(): readonly Message[] {
+    return [...this.messages];
+  }
+
+  getLastMessage(): Message | undefined {
+    return this.messages[this.messages.length - 1];
+  }
+
+  get messageCount(): number {
+    return this.messages.length;
+  }
+
+  /** Exact token count using js-tiktoken. */
+  get totalTokens(): number {
+    return countHistoryTokens(this.messages);
+  }
+
+  clear(): void {
+    this.messages.length = 0;
+  }
+
+  serialize(): string {
+    return JSON.stringify(this.messages);
+  }
+
+  restore(json: string): void {
+    const parsed: unknown = JSON.parse(json);
+    if (!Array.isArray(parsed)) {
+      throw new Error('Invalid serialized messages: expected an array');
+    }
+    this.messages.length = 0;
+    for (const item of parsed) {
+      if (
+        typeof item === 'object' && item !== null &&
+        'role' in item && 'content' in item &&
+        typeof (item as Message).role === 'string' &&
+        typeof (item as Message).content === 'string'
+      ) {
+        this.messages.push(item as Message);
+      }
+    }
+  }
+
+  /**
+   * Compress history if it exceeds the token budget.
+   *
+   * Strategy:
+   * 1. Always keep all system messages.
+   * 2. Keep the last `keepRecentMessages` non-system messages intact.
+   * 3. Summarize older messages into a structured digest that preserves:
+   *    - what the user asked
+   *    - what tools were called and whether they succeeded
+   *    - key assistant conclusions
+   *
+   * Returns the number of messages compressed (0 = no compression needed).
+   */
+  compressIfNeeded(): number {
+    if (this.totalTokens <= this.maxHistoryTokens) return 0;
+
+    const system: Message[] = [];
+    const rest: Message[]   = [];
+
+    for (const msg of this.messages) {
+      if (msg.role === 'system') system.push(msg);
+      else rest.push(msg);
+    }
+
+    const keepCount   = Math.min(this.keepRecentMessages, rest.length);
+    const toSummarize = rest.slice(0, rest.length - keepCount);
+    const toKeep      = rest.slice(rest.length - keepCount);
+
+    if (toSummarize.length === 0) return 0;
+
+    const summaryMessage: Message = {
+      role: 'user',
+      content: this.buildDigest(toSummarize),
+    };
+
+    this.messages.length = 0;
+    this.messages.push(...system, summaryMessage, ...toKeep);
+    return toSummarize.length;
+  }
+
+  private buildDigest(messages: Message[]): string {
+    const maxLen = this.summaryContentLength;
+    const lines: string[] = [
+      `[Context summary — ${messages.length} earlier messages compressed]`,
+      '',
+    ];
+
+    for (const msg of messages) {
+      if (msg.role === 'user' && !msg.toolResults) {
+        const text = truncate(msg.content, maxLen);
+        if (text) lines.push(`User: ${text}`);
+      }
+
+      if (msg.role === 'assistant') {
+        if (msg.content) {
+          lines.push(`Assistant: ${truncate(msg.content, maxLen)}`);
+        }
+        if (msg.toolCalls?.length) {
+          for (const tc of msg.toolCalls) {
+            lines.push(`  → ${tc.name}(${truncate(tc.arguments, 120)})`);
+          }
+        }
+      }
+
+      if (msg.toolResults?.length) {
+        for (const tr of msg.toolResults) {
+          lines.push(`  ← result: ${truncate(tr.content, 120)}`);
+        }
+      }
+    }
+
+    lines.push('', '[End of summary — conversation continues below]');
+    return lines.join('\n');
+  }
+}
+
+function truncate(text: string, maxLen: number): string {
+  if (!text) return '';
+  return text.length <= maxLen ? text : text.slice(0, maxLen) + '…';
+}
+
+export { countMessageTokens, countHistoryTokens } from './token-counter.js';

package/src/permission.ts

@@ -0,0 +1,104 @@
+import type { ITool, JsonObject } from '@charming_groot/core';
+
+/**
+ * Approval level returned by PermissionHandler.
+ *
+ * - 'once'    — allow this single invocation only
+ * - 'session' — allow for the rest of this session (cached in allowedTools)
+ * - 'always'  — allow permanently (caller is responsible for persistence)
+ * - 'deny'    — block this invocation
+ */
+export type ApprovalLevel = 'once' | 'session' | 'always' | 'deny';
+
+/**
+ * Decision returned by PermissionHandler.
+ * Can be a simple boolean (backward-compatible) or an ApprovalLevel.
+ */
+export type PermissionDecision = boolean | ApprovalLevel;
+
+/**
+ * Callback that decides whether a tool invocation is allowed.
+ * Receives the tool name and the parsed parameters so the handler
+ * can make context-aware decisions (e.g., block `rm -rf /`).
+ */
+export type PermissionHandler = (
+  toolName: string,
+  params: JsonObject,
+) => Promise<PermissionDecision>;
+
+/** Callback invoked when a tool is approved with 'always' level */
+export type PersistApprovalCallback = (toolName: string) => void;
+
+const AUTO_APPROVE: PermissionHandler = async () => true;
+
+function normalizeDecision(decision: PermissionDecision): ApprovalLevel {
+  if (decision === true) return 'session';
+  if (decision === false) return 'deny';
+  return decision;
+}
+
+export class PermissionManager {
+  private readonly handler: PermissionHandler;
+  private readonly sessionAllowed = new Set<string>();
+  private readonly alwaysAllowed = new Set<string>();
+  private readonly onPersist: PersistApprovalCallback | undefined;
+
+  constructor(
+    handler?: PermissionHandler,
+    onPersist?: PersistApprovalCallback,
+  ) {
+    this.handler = handler ?? AUTO_APPROVE;
+    this.onPersist = onPersist;
+  }
+
+  async checkPermission(tool: ITool, params: JsonObject = {}): Promise<boolean> {
+    if (!tool.requiresPermission) {
+      return true;
+    }
+
+    if (this.alwaysAllowed.has(tool.name) || this.sessionAllowed.has(tool.name)) {
+      return true;
+    }
+
+    const raw = await this.handler(tool.name, params);
+    const level = normalizeDecision(raw);
+
+    if (level === 'deny') return false;
+
+    if (level === 'session') {
+      this.sessionAllowed.add(tool.name);
+    } else if (level === 'always') {
+      this.alwaysAllowed.add(tool.name);
+      this.onPersist?.(tool.name);
+    }
+    // 'once' — no caching, just allow this time
+
+    return true;
+  }
+
+  allowTool(toolName: string, level: 'session' | 'always' = 'session'): void {
+    if (level === 'always') {
+      this.alwaysAllowed.add(toolName);
+    } else {
+      this.sessionAllowed.add(toolName);
+    }
+  }
+
+  revokeTool(toolName: string): void {
+    this.sessionAllowed.delete(toolName);
+    this.alwaysAllowed.delete(toolName);
+  }
+
+  isAllowed(toolName: string): boolean {
+    return this.sessionAllowed.has(toolName) || this.alwaysAllowed.has(toolName);
+  }
+
+  clearSession(): void {
+    this.sessionAllowed.clear();
+  }
+
+  clearAll(): void {
+    this.sessionAllowed.clear();
+    this.alwaysAllowed.clear();
+  }
+}

package/src/session-manager.ts

@@ -0,0 +1,121 @@
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import type { AgentLogger } from '@charming_groot/core';
+import { createChildLogger } from '@charming_groot/core';
+import { MessageManager } from './message-manager.js';
+
+/** Metadata stored alongside the conversation messages */
+export interface SessionMeta {
+  readonly sessionId: string;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+}
+
+/** On-disk JSON shape */
+interface SessionFile {
+  meta: SessionMeta;
+  messages: string; // MessageManager.serialize() output
+}
+
+/**
+ * Persists and restores agent conversations to/from disk.
+ *
+ * Usage:
+ *   const sm = new SessionManager('/path/to/sessions');
+ *   await sm.save(sessionId, messageManager);
+ *   await sm.load(sessionId, messageManager);
+ */
+export class SessionManager {
+  private readonly sessionsDir: string;
+  private readonly logger: AgentLogger;
+
+  constructor(sessionsDir: string) {
+    this.sessionsDir = sessionsDir;
+    this.logger = createChildLogger('session-manager');
+  }
+
+  /** Save the current conversation to disk. */
+  async save(sessionId: string, manager: MessageManager): Promise<void> {
+    const filePath = this.sessionPath(sessionId);
+    await mkdir(dirname(filePath), { recursive: true });
+
+    let meta: SessionMeta;
+    try {
+      const existing = await this.readSessionFile(filePath);
+      meta = {
+        sessionId,
+        createdAt: existing.meta.createdAt,
+        updatedAt: new Date().toISOString(),
+      };
+    } catch {
+      meta = {
+        sessionId,
+        createdAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+      };
+    }
+
+    const data: SessionFile = {
+      meta,
+      messages: manager.serialize(),
+    };
+
+    await writeFile(filePath, JSON.stringify(data, null, 2), 'utf-8');
+    this.logger.info({ sessionId, messages: manager.messageCount }, 'Session saved');
+  }
+
+  /** Restore a conversation from disk into the given MessageManager. */
+  async load(sessionId: string, manager: MessageManager): Promise<SessionMeta> {
+    const filePath = this.sessionPath(sessionId);
+    const data = await this.readSessionFile(filePath);
+    manager.restore(data.messages);
+    this.logger.info({ sessionId, messages: manager.messageCount }, 'Session loaded');
+    return data.meta;
+  }
+
+  /** Check if a session file exists. */
+  async exists(sessionId: string): Promise<boolean> {
+    try {
+      await this.readSessionFile(this.sessionPath(sessionId));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /** List all session IDs in the sessions directory. */
+  async list(): Promise<SessionMeta[]> {
+    const { readdir } = await import('node:fs/promises');
+    try {
+      const entries = await readdir(this.sessionsDir);
+      const metas: SessionMeta[] = [];
+      for (const entry of entries) {
+        if (!entry.endsWith('.session.json')) continue;
+        try {
+          const data = await this.readSessionFile(join(this.sessionsDir, entry));
+          metas.push(data.meta);
+        } catch {
+          // skip corrupt files
+        }
+      }
+      return metas.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+    } catch {
+      return [];
+    }
+  }
+
+  private sessionPath(sessionId: string): string {
+    // Sanitize sessionId to prevent path traversal
+    const safe = sessionId.replace(/[^a-zA-Z0-9_-]/g, '_');
+    return join(this.sessionsDir, `${safe}.session.json`);
+  }
+
+  private async readSessionFile(filePath: string): Promise<SessionFile> {
+    const content = await readFile(filePath, 'utf-8');
+    const parsed = JSON.parse(content) as SessionFile;
+    if (!parsed.meta || !parsed.messages) {
+      throw new Error('Invalid session file format');
+    }
+    return parsed;
+  }
+}