@charming_groot/core 0.1.0

package/src/logger.ts

@@ -0,0 +1,43 @@
+import pino from 'pino';
+
+export type AgentLogger = pino.Logger;
+export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+
+const LOG_LEVEL_KEY = 'CLI_AGENT_LOG_LEVEL';
+const DEFAULT_LOG_LEVEL: LogLevel = 'info';
+
+function getLogLevel(): LogLevel {
+  const envLevel = process.env[LOG_LEVEL_KEY];
+  if (envLevel && isValidLogLevel(envLevel)) {
+    return envLevel;
+  }
+  return DEFAULT_LOG_LEVEL;
+}
+
+function isValidLogLevel(level: string): level is LogLevel {
+  return ['trace', 'debug', 'info', 'warn', 'error', 'fatal'].includes(level);
+}
+
+export function createLogger(name: string, level?: LogLevel): pino.Logger {
+  return pino({
+    name,
+    level: level ?? getLogLevel(),
+    transport:
+      process.env['NODE_ENV'] !== 'production'
+        ? { target: 'pino/file', options: { destination: 1 } }
+        : undefined,
+  });
+}
+
+let rootLogger: pino.Logger | undefined;
+
+export function getRootLogger(): pino.Logger {
+  if (!rootLogger) {
+    rootLogger = createLogger('cli-agent');
+  }
+  return rootLogger;
+}
+
+export function createChildLogger(name: string): pino.Logger {
+  return getRootLogger().child({ module: name });
+}

package/src/registry.ts

@@ -0,0 +1,62 @@
+import { RegistryError } from './errors/base-error.js';
+
+export class Registry<T> {
+  private readonly items = new Map<string, T>();
+  private readonly label: string;
+
+  constructor(label: string) {
+    this.label = label;
+  }
+
+  register(name: string, item: T): void {
+    if (this.items.has(name)) {
+      throw new RegistryError(
+        `${this.label} '${name}' is already registered`
+      );
+    }
+    this.items.set(name, item);
+  }
+
+  get(name: string): T {
+    const item = this.items.get(name);
+    if (item === undefined) {
+      throw new RegistryError(
+        `${this.label} '${name}' is not registered`
+      );
+    }
+    return item;
+  }
+
+  tryGet(name: string): T | undefined {
+    return this.items.get(name);
+  }
+
+  has(name: string): boolean {
+    return this.items.has(name);
+  }
+
+  getAll(): ReadonlyMap<string, T> {
+    return this.items;
+  }
+
+  getAllNames(): readonly string[] {
+    return [...this.items.keys()];
+  }
+
+  unregister(name: string): boolean {
+    if (!this.items.has(name)) {
+      throw new RegistryError(
+        `${this.label} '${name}' is not registered`
+      );
+    }
+    return this.items.delete(name);
+  }
+
+  clear(): void {
+    this.items.clear();
+  }
+
+  get size(): number {
+    return this.items.size;
+  }
+}

package/src/run-context.ts

@@ -0,0 +1,48 @@
+import { randomUUID } from 'node:crypto';
+import type { AgentConfig } from './config.js';
+import { EventBus } from './event-bus.js';
+import type { JsonValue } from './types/common.js';
+
+export class RunContext {
+  readonly runId: string;
+  readonly workingDirectory: string;
+  readonly eventBus: EventBus;
+  readonly config: AgentConfig;
+  readonly createdAt: Date;
+  private readonly metadata: Map<string, JsonValue>;
+  private abortController: AbortController;
+
+  constructor(config: AgentConfig, eventBus?: EventBus) {
+    this.runId = randomUUID();
+    this.workingDirectory = config.workingDirectory;
+    this.config = config;
+    this.eventBus = eventBus ?? new EventBus();
+    this.createdAt = new Date();
+    this.metadata = new Map();
+    this.abortController = new AbortController();
+  }
+
+  get signal(): AbortSignal {
+    return this.abortController.signal;
+  }
+
+  get isAborted(): boolean {
+    return this.abortController.signal.aborted;
+  }
+
+  abort(reason?: string): void {
+    this.abortController.abort(reason);
+  }
+
+  setMetadata(key: string, value: JsonValue): void {
+    this.metadata.set(key, value);
+  }
+
+  getMetadata(key: string): JsonValue | undefined {
+    return this.metadata.get(key);
+  }
+
+  getAllMetadata(): ReadonlyMap<string, JsonValue> {
+    return this.metadata;
+  }
+}

package/src/types/auth.ts

@@ -0,0 +1,79 @@
+export type AuthType =
+  | 'no-auth'
+  | 'api-key'
+  | 'oauth'
+  | 'azure-ad'
+  | 'aws-iam'
+  | 'gcp-service-account'
+  | 'credential-file';
+
+export interface NoAuth {
+  readonly type: 'no-auth';
+}
+
+export interface ApiKeyAuth {
+  readonly type: 'api-key';
+  readonly apiKey: string;
+}
+
+export interface OAuthAuth {
+  readonly type: 'oauth';
+  readonly clientId: string;
+  readonly clientSecret: string;
+  readonly tokenUrl: string;
+  readonly scopes?: readonly string[];
+  readonly accessToken?: string;
+  readonly refreshToken?: string;
+}
+
+export interface AzureAdAuth {
+  readonly type: 'azure-ad';
+  readonly tenantId: string;
+  readonly clientId: string;
+  readonly clientSecret?: string;
+  readonly accessToken?: string;
+}
+
+export interface AwsIamAuth {
+  readonly type: 'aws-iam';
+  readonly accessKeyId?: string;
+  readonly secretAccessKey?: string;
+  readonly sessionToken?: string;
+  readonly region: string;
+  readonly profile?: string;
+}
+
+export interface GcpServiceAccountAuth {
+  readonly type: 'gcp-service-account';
+  readonly projectId: string;
+  readonly keyFilePath?: string;
+  readonly accessToken?: string;
+}
+
+export interface CredentialFileAuth {
+  readonly type: 'credential-file';
+  readonly filePath: string;
+  readonly profile?: string;
+}
+
+export type AuthConfig =
+  | NoAuth
+  | ApiKeyAuth
+  | OAuthAuth
+  | AzureAdAuth
+  | AwsIamAuth
+  | GcpServiceAccountAuth
+  | CredentialFileAuth;
+
+export interface IAuthStrategy {
+  readonly type: AuthType;
+  resolve(config: AuthConfig): Promise<ResolvedCredential>;
+  refresh?(config: AuthConfig): Promise<ResolvedCredential>;
+}
+
+export interface ResolvedCredential {
+  readonly type: AuthType;
+  readonly headers: Record<string, string>;
+  readonly token?: string;
+  readonly expiresAt?: Date;
+}

package/src/types/common.ts

@@ -0,0 +1,22 @@
+export type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+export type JsonObject = Record<string, JsonValue>;
+
+export interface Identifiable {
+  readonly id: string;
+}
+
+export interface Timestamped {
+  readonly createdAt: Date;
+  readonly updatedAt: Date;
+}
+
+export interface Disposable {
+  dispose(): Promise<void>;
+}

package/src/types/events.ts

@@ -0,0 +1,24 @@
+import type { Message, LlmResponse, ToolCall } from './provider.js';
+import type { ToolResult } from './tool.js';
+import type { ExecutionResult } from './sandbox.js';
+
+export interface AgentEvents {
+  'agent:start': { runId: string; model: string; startedAt: number };
+  'agent:end': { runId: string; reason: string; durationMs: number; iterations: number };
+  'agent:error': { runId: string; error: Error };
+  'llm:request': { runId: string; messages: readonly Message[] };
+  'llm:response': { runId: string; response: LlmResponse; durationMs: number; model: string };
+  'llm:stream': { runId: string; chunk: string };
+  'tool:start': { runId: string; toolCall: ToolCall; startedAt: number };
+  'tool:end': { runId: string; toolCall: ToolCall; result: ToolResult; durationMs: number };
+  'tool:permission': { runId: string; toolName: string };
+  'sandbox:execute': { runId: string; language: string };
+  'sandbox:result': { runId: string; result: ExecutionResult };
+  'mcp:connected': { server: string; toolCount: number };
+  'mcp:disconnected': { server: string };
+  'mcp:tools_changed': { server: string; tools: readonly string[] };
+  'context:assembled': { runId: string; usage: unknown; wasCompressed: boolean; toolCount: number };
+}
+
+export type EventName = keyof AgentEvents;
+export type EventPayload<K extends EventName> = AgentEvents[K];

package/src/types/index.ts

@@ -0,0 +1,54 @@
+export type {
+  JsonValue,
+  JsonObject,
+  Identifiable,
+  Timestamped,
+  Disposable,
+} from './common.js';
+
+export type {
+  ToolParameter,
+  ToolDescription,
+  ToolResult,
+  ITool,
+} from './tool.js';
+export { toolResultSchema } from './tool.js';
+
+export type {
+  MessageRole,
+  ToolCall,
+  ToolResultMessage,
+  Message,
+  StopReason,
+  LlmResponse,
+  TokenUsage,
+  StreamEvent,
+  ILlmProvider,
+} from './provider.js';
+
+export type {
+  SandboxConfig,
+  ExecutionRequest,
+  ExecutionResult,
+  ISandbox,
+} from './sandbox.js';
+
+export type {
+  AgentEvents,
+  EventName,
+  EventPayload,
+} from './events.js';
+
+export type {
+  AuthType,
+  NoAuth,
+  ApiKeyAuth,
+  OAuthAuth,
+  AzureAdAuth,
+  AwsIamAuth,
+  GcpServiceAccountAuth,
+  CredentialFileAuth,
+  AuthConfig,
+  IAuthStrategy,
+  ResolvedCredential,
+} from './auth.js';

package/src/types/provider.ts

@@ -0,0 +1,50 @@
+import type { ToolDescription } from './tool.js';
+
+export type MessageRole = 'user' | 'assistant' | 'system';
+
+export interface ToolCall {
+  readonly id: string;
+  readonly name: string;
+  readonly arguments: string;
+}
+
+export interface ToolResultMessage {
+  readonly toolCallId: string;
+  readonly content: string;
+}
+
+export interface Message {
+  readonly role: MessageRole;
+  readonly content: string;
+  readonly toolCalls?: readonly ToolCall[];
+  readonly toolResults?: readonly ToolResultMessage[];
+}
+
+export type StopReason = 'end_turn' | 'tool_use' | 'max_tokens' | 'error';
+
+export interface LlmResponse {
+  readonly content: string;
+  readonly stopReason: StopReason;
+  readonly toolCalls: readonly ToolCall[];
+  readonly usage: TokenUsage;
+}
+
+export interface TokenUsage {
+  readonly inputTokens: number;
+  readonly outputTokens: number;
+  /** Time spent in extended thinking / <think> block (ms). Only set by providers that support it. */
+  readonly thinkingMs?: number;
+}
+
+export interface StreamEvent {
+  readonly type: 'text_delta' | 'tool_call_start' | 'tool_call_delta' | 'done';
+  readonly content?: string;
+  readonly toolCall?: Partial<ToolCall>;
+  readonly response?: LlmResponse;
+}
+
+export interface ILlmProvider {
+  readonly providerId: string;
+  chat(messages: readonly Message[], tools?: readonly ToolDescription[]): Promise<LlmResponse>;
+  stream(messages: readonly Message[], tools?: readonly ToolDescription[]): AsyncIterable<StreamEvent>;
+}

package/src/types/sandbox.ts

@@ -0,0 +1,29 @@
+export interface SandboxConfig {
+  readonly image: string;
+  readonly memoryLimitMb: number;
+  readonly cpuLimit: number;
+  readonly timeoutMs: number;
+  readonly workDir: string;
+}
+
+export interface ExecutionRequest {
+  readonly code: string;
+  readonly language: string;
+  readonly timeoutMs?: number;
+  readonly stdin?: string;
+}
+
+export interface ExecutionResult {
+  readonly exitCode: number;
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly timedOut: boolean;
+  readonly durationMs: number;
+}
+
+export interface ISandbox {
+  readonly containerId: string;
+  initialize(config: SandboxConfig): Promise<void>;
+  execute(request: ExecutionRequest): Promise<ExecutionResult>;
+  destroy(): Promise<void>;
+}

package/src/types/tool.ts

@@ -0,0 +1,37 @@
+import { z } from 'zod';
+import type { JsonObject } from './common.js';
+import type { RunContext } from '../run-context.js';
+
+export interface ToolParameter {
+  readonly name: string;
+  readonly type: string;
+  readonly description: string;
+  readonly required: boolean;
+}
+
+export interface ToolDescription {
+  readonly name: string;
+  readonly description: string;
+  readonly parameters: readonly ToolParameter[];
+}
+
+export interface ToolResult {
+  readonly success: boolean;
+  readonly output: string;
+  readonly error?: string;
+  readonly metadata?: JsonObject;
+}
+
+export interface ITool {
+  readonly name: string;
+  readonly requiresPermission: boolean;
+  describe(): ToolDescription;
+  execute(params: JsonObject, context: RunContext): Promise<ToolResult>;
+}
+
+export const toolResultSchema = z.object({
+  success: z.boolean(),
+  output: z.string(),
+  error: z.string().optional(),
+  metadata: z.record(z.unknown()).optional(),
+});

package/tests/config.test.ts

@@ -0,0 +1,98 @@
+import { describe, it, expect } from 'vitest';
+import {
+  parseConfig,
+  parseAgentConfig,
+  providerConfigSchema,
+  agentConfigSchema,
+} from '../src/config.js';
+import { ConfigError } from '../src/errors/base-error.js';
+
+const VALID_PROVIDER = {
+  providerId: 'claude',
+  model: 'claude-opus-4-6',
+  auth: { type: 'api-key' as const, apiKey: 'sk-test-key-123' },
+};
+
+describe('Config', () => {
+  describe('providerConfigSchema', () => {
+    it('should validate a valid provider config', () => {
+      const result = providerConfigSchema.safeParse(VALID_PROVIDER);
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.data.maxTokens).toBe(4096);
+        expect(result.data.temperature).toBe(0.7);
+      }
+    });
+
+    it('should reject empty providerId', () => {
+      const result = providerConfigSchema.safeParse({
+        ...VALID_PROVIDER,
+        providerId: '',
+      });
+      expect(result.success).toBe(false);
+    });
+
+    it('should reject invalid baseUrl', () => {
+      const result = providerConfigSchema.safeParse({
+        ...VALID_PROVIDER,
+        baseUrl: 'not-a-url',
+      });
+      expect(result.success).toBe(false);
+    });
+
+    it('should accept custom maxTokens and temperature', () => {
+      const result = providerConfigSchema.safeParse({
+        ...VALID_PROVIDER,
+        maxTokens: 8192,
+        temperature: 1.0,
+      });
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.data.maxTokens).toBe(8192);
+        expect(result.data.temperature).toBe(1.0);
+      }
+    });
+  });
+
+  describe('parseConfig', () => {
+    it('should parse valid config', () => {
+      const config = parseConfig(providerConfigSchema, VALID_PROVIDER);
+      expect(config.providerId).toBe('claude');
+    });
+
+    it('should throw ConfigError on invalid config', () => {
+      expect(() => parseConfig(providerConfigSchema, {})).toThrow(ConfigError);
+    });
+
+    it('should include field paths in error message', () => {
+      try {
+        parseConfig(providerConfigSchema, {});
+      } catch (e) {
+        expect(e).toBeInstanceOf(ConfigError);
+        expect((e as ConfigError).message).toContain('providerId');
+      }
+    });
+  });
+
+  describe('parseAgentConfig', () => {
+    it('should parse a valid agent config', () => {
+      const config = parseAgentConfig({
+        provider: VALID_PROVIDER,
+      });
+      expect(config.provider.providerId).toBe('claude');
+      expect(config.maxIterations).toBe(50);
+    });
+
+    it('should apply defaults', () => {
+      const config = parseAgentConfig({
+        provider: VALID_PROVIDER,
+      });
+      expect(config.maxIterations).toBe(50);
+      expect(config.workingDirectory).toBeTruthy();
+    });
+
+    it('should throw on missing provider', () => {
+      expect(() => parseAgentConfig({})).toThrow(ConfigError);
+    });
+  });
+});

package/tests/errors.test.ts

@@ -0,0 +1,87 @@
+import { describe, it, expect } from 'vitest';
+import {
+  AgentError,
+  RegistryError,
+  ConfigError,
+  ProviderError,
+  ToolExecutionError,
+  SandboxError,
+  PermissionDeniedError,
+  AbortError,
+} from '../src/errors/base-error.js';
+
+describe('Errors', () => {
+  it('should create AgentError with code', () => {
+    const err = new AgentError('test', 'TEST_CODE');
+    expect(err.message).toBe('test');
+    expect(err.code).toBe('TEST_CODE');
+    expect(err.name).toBe('AgentError');
+    expect(err).toBeInstanceOf(Error);
+  });
+
+  it('should chain cause', () => {
+    const cause = new Error('original');
+    const err = new AgentError('wrapped', 'WRAP', cause);
+    expect(err.cause).toBe(cause);
+  });
+
+  it('should create RegistryError', () => {
+    const err = new RegistryError('not found');
+    expect(err.code).toBe('REGISTRY_ERROR');
+    expect(err.name).toBe('RegistryError');
+    expect(err).toBeInstanceOf(AgentError);
+  });
+
+  it('should create ConfigError', () => {
+    const err = new ConfigError('bad config');
+    expect(err.code).toBe('CONFIG_ERROR');
+    expect(err.name).toBe('ConfigError');
+  });
+
+  it('should create ProviderError', () => {
+    const err = new ProviderError('api failed');
+    expect(err.code).toBe('PROVIDER_ERROR');
+    expect(err.name).toBe('ProviderError');
+  });
+
+  it('should create ToolExecutionError with toolName', () => {
+    const err = new ToolExecutionError('file-read', 'read failed');
+    expect(err.toolName).toBe('file-read');
+    expect(err.code).toBe('TOOL_EXECUTION_ERROR');
+    expect(err.name).toBe('ToolExecutionError');
+  });
+
+  it('should create SandboxError', () => {
+    const err = new SandboxError('container failed');
+    expect(err.code).toBe('SANDBOX_ERROR');
+    expect(err.name).toBe('SandboxError');
+  });
+
+  it('should create PermissionDeniedError', () => {
+    const err = new PermissionDeniedError('shell-exec');
+    expect(err.toolName).toBe('shell-exec');
+    expect(err.code).toBe('PERMISSION_DENIED');
+    expect(err.message).toContain('shell-exec');
+  });
+
+  it('should create AbortError with default message', () => {
+    const err = new AbortError();
+    expect(err.message).toBe('Operation aborted');
+    expect(err.code).toBe('ABORT_ERROR');
+  });
+
+  it('should create AbortError with custom message', () => {
+    const err = new AbortError('user cancelled');
+    expect(err.message).toBe('user cancelled');
+  });
+
+  it('should be catchable as Error', () => {
+    try {
+      throw new RegistryError('test');
+    } catch (e) {
+      expect(e).toBeInstanceOf(Error);
+      expect(e).toBeInstanceOf(AgentError);
+      expect(e).toBeInstanceOf(RegistryError);
+    }
+  });
+});