@charming_groot/agent 0.1.0

package/src/skill-tool.ts

@@ -0,0 +1,155 @@
+import type {
+  ITool,
+  ToolDescription,
+  ToolResult,
+  JsonObject,
+  AgentLogger,
+} from '@charming_groot/core';
+import type { RunContext } from '@charming_groot/core';
+import { createChildLogger } from '@charming_groot/core';
+
+/** Minimal skill shape — avoids hard dependency on @core/types */
+export interface SkillEntry {
+  readonly name: string;
+  readonly description: string;
+  readonly tools: readonly string[];
+  readonly prompt: string;
+  readonly rules: readonly string[];
+}
+
+/** Minimal registry interface — compatible with @core/skill SkillRegistry */
+export interface SkillProvider {
+  get(name: string): SkillEntry | undefined;
+  getAll(): readonly SkillEntry[];
+}
+
+/**
+ * An ITool that exposes the skill registry to the agent.
+ *
+ * Actions:
+ *   - "list"  → returns all available skill names and descriptions
+ *   - "invoke" → returns the skill's prompt, tools, and rules so the
+ *                 agent can adopt that behavior for the current task
+ *
+ * This enables CLI-style `/skill` invocation: the agent discovers
+ * available skills and activates one by reading its prompt guidance.
+ */
+export class SkillTool implements ITool {
+  readonly name = 'skill';
+  readonly requiresPermission = false;
+
+  private readonly registry: SkillProvider;
+  private readonly logger: AgentLogger;
+
+  constructor(registry: SkillProvider) {
+    this.registry = registry;
+    this.logger = createChildLogger('skill-tool');
+  }
+
+  describe(): ToolDescription {
+    return {
+      name: this.name,
+      description:
+        'List or invoke predefined skills. ' +
+        'Use action="list" to see available skills, ' +
+        'or action="invoke" with name="<skill>" to activate a skill.',
+      parameters: [
+        {
+          name: 'action',
+          type: 'string',
+          description: 'Action to perform: "list" or "invoke"',
+          required: true,
+        },
+        {
+          name: 'name',
+          type: 'string',
+          description: 'Skill name (required for "invoke")',
+          required: false,
+        },
+        {
+          name: 'input',
+          type: 'string',
+          description: 'Optional context/input to pass to the skill',
+          required: false,
+        },
+      ],
+    };
+  }
+
+  async execute(params: JsonObject, _context: RunContext): Promise<ToolResult> {
+    const action = params['action'];
+
+    if (action === 'list') {
+      return this.listSkills();
+    }
+
+    if (action === 'invoke') {
+      const name = params['name'];
+      if (typeof name !== 'string' || name.trim().length === 0) {
+        return { success: false, output: '', error: 'Missing "name" parameter for invoke action' };
+      }
+      const input = typeof params['input'] === 'string' ? params['input'] : undefined;
+      return this.invokeSkill(name, input);
+    }
+
+    return {
+      success: false,
+      output: '',
+      error: `Unknown action: "${String(action)}". Use "list" or "invoke".`,
+    };
+  }
+
+  private listSkills(): ToolResult {
+    const skills = this.registry.getAll();
+    if (skills.length === 0) {
+      return { success: true, output: 'No skills available.' };
+    }
+
+    const lines = skills.map(
+      (s) => `- ${s.name}: ${s.description} [tools: ${s.tools.join(', ')}]`
+    );
+
+    this.logger.debug({ count: skills.length }, 'Listed skills');
+    return { success: true, output: `Available skills:\n${lines.join('\n')}` };
+  }
+
+  private invokeSkill(name: string, input?: string): ToolResult {
+    const skill = this.registry.get(name);
+    if (!skill) {
+      return { success: false, output: '', error: `Skill "${name}" not found` };
+    }
+
+    this.logger.info({ skill: name }, 'Skill invoked');
+
+    const sections: string[] = [
+      `## Skill: ${skill.name}`,
+      '',
+      skill.description,
+      '',
+      '### Prompt',
+      skill.prompt,
+    ];
+
+    if (skill.tools.length > 0) {
+      sections.push('', `### Available tools: ${skill.tools.join(', ')}`);
+    }
+
+    if (skill.rules.length > 0) {
+      sections.push('', `### Rules: ${skill.rules.join(', ')}`);
+    }
+
+    if (input) {
+      sections.push('', `### User input`, input);
+    }
+
+    return {
+      success: true,
+      output: sections.join('\n'),
+      metadata: {
+        skillName: skill.name,
+        tools: [...skill.tools],
+        rules: [...skill.rules],
+      },
+    };
+  }
+}

package/src/sub-agent-tool.ts

@@ -0,0 +1,122 @@
+import type {
+  ITool,
+  ILlmProvider,
+  ToolDescription,
+  ToolResult,
+  JsonObject,
+  AgentLogger,
+} from '@charming_groot/core';
+import { Registry, RunContext, createChildLogger } from '@charming_groot/core';
+import { AgentLoop } from './agent-loop.js';
+import type { SystemPromptBuilder } from './agent-loop.js';
+import type { PermissionHandler } from './permission.js';
+
+/** Configuration for creating a sub-agent tool. */
+export interface SubAgentToolConfig {
+  /** Display name for this sub-agent tool */
+  readonly name: string;
+  /** Description shown to the parent agent */
+  readonly description: string;
+  /** LLM provider the sub-agent will use */
+  readonly provider: ILlmProvider;
+  /** Tools available to the sub-agent */
+  readonly toolRegistry: Registry<ITool>;
+  /** System prompt or dynamic builder for the sub-agent */
+  readonly systemPrompt?: string;
+  readonly systemPromptBuilder?: SystemPromptBuilder;
+  /** Max iterations for the sub-agent (default: 25) */
+  readonly maxIterations?: number;
+  /** Permission handler for the sub-agent's tools */
+  readonly permissionHandler?: PermissionHandler;
+}
+
+const DEFAULT_MAX_ITERATIONS = 25;
+
+/**
+ * Wraps an AgentLoop as an ITool so a parent agent can delegate
+ * sub-tasks to a child agent via tool calls.
+ *
+ * The parent sends a "task" parameter; the sub-agent runs autonomously
+ * and returns the final result as tool output.
+ */
+export class SubAgentTool implements ITool {
+  readonly name: string;
+  readonly requiresPermission = false;
+
+  private readonly config: SubAgentToolConfig;
+  private readonly logger: AgentLogger;
+
+  constructor(config: SubAgentToolConfig) {
+    this.name = config.name;
+    this.config = config;
+    this.logger = createChildLogger(`sub-agent:${config.name}`);
+  }
+
+  describe(): ToolDescription {
+    return {
+      name: this.name,
+      description: this.config.description,
+      parameters: [
+        {
+          name: 'task',
+          type: 'string',
+          description: 'The task to delegate to the sub-agent',
+          required: true,
+        },
+      ],
+    };
+  }
+
+  async execute(params: JsonObject, context: RunContext): Promise<ToolResult> {
+    const task = params['task'];
+    if (typeof task !== 'string' || task.trim().length === 0) {
+      return { success: false, output: '', error: 'Missing or empty "task" parameter' };
+    }
+
+    this.logger.info({ task: task.slice(0, 200) }, 'Sub-agent starting');
+
+    const childLoop = new AgentLoop({
+      provider: this.config.provider,
+      toolRegistry: this.config.toolRegistry,
+      config: {
+        provider: {
+          providerId: this.config.provider.providerId,
+          model: 'sub-agent',
+          auth: { type: 'api-key' as const, apiKey: '' },
+          maxTokens: 4096,
+          temperature: 0.7,
+        },
+        maxIterations: this.config.maxIterations ?? DEFAULT_MAX_ITERATIONS,
+        workingDirectory: context.workingDirectory,
+        systemPrompt: this.config.systemPrompt,
+      },
+      permissionHandler: this.config.permissionHandler,
+      systemPromptBuilder: this.config.systemPromptBuilder,
+    });
+
+    // Propagate abort from parent context to child via AbortSignal
+    const onAbort = () => childLoop.abort('Parent aborted');
+    context.signal.addEventListener('abort', onAbort, { once: true });
+
+    try {
+      const result = await childLoop.run(task);
+
+      this.logger.info(
+        { iterations: result.iterations, aborted: result.aborted },
+        'Sub-agent completed',
+      );
+
+      if (result.aborted) {
+        return { success: false, output: result.content, error: 'Sub-agent was aborted' };
+      }
+
+      return { success: true, output: result.content };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      this.logger.warn({ error: message }, 'Sub-agent failed');
+      return { success: false, output: '', error: `Sub-agent error: ${message}` };
+    } finally {
+      context.signal.removeEventListener('abort', onAbort);
+    }
+  }
+}

package/src/token-counter.ts

@@ -0,0 +1,79 @@
+import { getEncoding, type Tiktoken } from 'js-tiktoken';
+import type { Message } from '@charming_groot/core';
+
+// cl100k_base: Claude, GPT-4, GPT-3.5-turbo
+// o200k_base:  GPT-4o, o1, o3
+const MODEL_ENCODING: Record<string, string> = {
+  'claude': 'cl100k_base',
+  'gpt-4': 'cl100k_base',
+  'gpt-3.5': 'cl100k_base',
+  'gpt-4o': 'o200k_base',
+  'o1': 'o200k_base',
+  'o3': 'o200k_base',
+};
+
+const MESSAGE_OVERHEAD = 4;   // role + formatting tokens per message
+const REPLY_OVERHEAD  = 3;   // assistant reply priming tokens
+
+let enc: Tiktoken | null = null;
+
+function getEncoder(): Tiktoken {
+  if (!enc) {
+    // cl100k_base works well enough for Claude and most OpenAI models.
+    // For o200k_base models the count differs by ~3% — acceptable for budget tracking.
+    enc = getEncoding('cl100k_base');
+  }
+  return enc;
+}
+
+export function resolveEncoding(modelId: string): string {
+  const key = Object.keys(MODEL_ENCODING).find(k => modelId.toLowerCase().includes(k));
+  return key ? MODEL_ENCODING[key] : 'cl100k_base';
+}
+
+/**
+ * Count tokens in a plain text string.
+ */
+export function countTextTokens(text: string): number {
+  if (!text) return 0;
+  try {
+    return getEncoder().encode(text).length;
+  } catch {
+    // Fallback: character estimate
+    return Math.ceil(text.length / 4);
+  }
+}
+
+/**
+ * Count tokens for a single Message (content + tool calls + tool results).
+ * Mirrors OpenAI's message token counting spec closely enough for Claude too.
+ */
+export function countMessageTokens(msg: Message): number {
+  let tokens = MESSAGE_OVERHEAD;
+
+  tokens += countTextTokens(msg.content);
+
+  if (msg.toolCalls) {
+    for (const tc of msg.toolCalls) {
+      tokens += countTextTokens(tc.name);
+      tokens += countTextTokens(tc.arguments);
+      tokens += 3; // function_call framing
+    }
+  }
+
+  if (msg.toolResults) {
+    for (const tr of msg.toolResults) {
+      tokens += countTextTokens(tr.content);
+      tokens += 3; // tool result framing
+    }
+  }
+
+  return tokens;
+}
+
+/**
+ * Count total tokens across a message history.
+ */
+export function countHistoryTokens(messages: readonly Message[]): number {
+  return messages.reduce((sum, m) => sum + countMessageTokens(m), REPLY_OVERHEAD);
+}

package/src/tool-dispatcher.ts

@@ -0,0 +1,124 @@
+import type { ITool, ToolCall, ToolResult, ToolDescription, JsonObject } from '@charming_groot/core';
+import {
+  Registry,
+  PermissionDeniedError,
+  createChildLogger,
+} from '@charming_groot/core';
+import type { RunContext, AgentLogger } from '@charming_groot/core';
+import { PermissionManager } from './permission.js';
+
+/** Maximum characters in a single tool result output */
+const MAX_OUTPUT_CHARS = 80_000;
+const TRUNCATION_NOTICE = '\n\n... [output truncated — exceeded 80,000 characters]';
+
+export class ToolDispatcher {
+  private readonly toolRegistry: Registry<ITool>;
+  private readonly permissionManager: PermissionManager;
+  private readonly logger: AgentLogger;
+
+  constructor(toolRegistry: Registry<ITool>, permissionManager: PermissionManager) {
+    this.toolRegistry = toolRegistry;
+    this.permissionManager = permissionManager;
+    this.logger = createChildLogger('tool-dispatcher');
+  }
+
+  async dispatch(
+    toolCall: ToolCall,
+    context: RunContext
+  ): Promise<ToolResult> {
+    const tool = this.toolRegistry.tryGet(toolCall.name);
+    if (!tool) {
+      this.logger.warn({ toolName: toolCall.name }, 'Unknown tool');
+      return {
+        success: false,
+        output: '',
+        error: `Unknown tool: ${toolCall.name}`,
+      };
+    }
+
+    let params: JsonObject;
+    try {
+      params = JSON.parse(toolCall.arguments) as JsonObject;
+    } catch {
+      this.logger.warn(
+        { toolName: toolCall.name, arguments: toolCall.arguments.slice(0, 200) },
+        'Invalid JSON in tool arguments',
+      );
+      return {
+        success: false,
+        output: '',
+        error: `Invalid tool arguments for "${toolCall.name}": ${toolCall.arguments.slice(0, 100)}`,
+      };
+    }
+
+    const permitted = await this.permissionManager.checkPermission(tool, params);
+    if (!permitted) {
+      this.logger.info({ toolName: toolCall.name }, 'Permission denied');
+      throw new PermissionDeniedError(toolCall.name);
+    }
+
+    const toolStartedAt = Date.now();
+    context.eventBus.emit('tool:start', { runId: context.runId, toolCall, startedAt: toolStartedAt });
+
+    let result: ToolResult;
+    try {
+      result = await tool.execute(params, context);
+    } catch (error) {
+      if (error instanceof PermissionDeniedError) throw error;
+      const message = error instanceof Error ? error.message : String(error);
+      result = { success: false, output: '', error: message };
+    }
+
+    const truncated = this.truncateResult(result);
+    context.eventBus.emit('tool:end', {
+      runId: context.runId,
+      toolCall,
+      result: truncated,
+      durationMs: Date.now() - toolStartedAt,
+    });
+    return truncated;
+  }
+
+  async dispatchAll(
+    toolCalls: readonly ToolCall[],
+    context: RunContext
+  ): Promise<ReadonlyMap<string, ToolResult>> {
+    const abortedResult: ToolResult = {
+      success: false,
+      output: '',
+      error: 'Operation aborted',
+    };
+
+    const entries = await Promise.all(
+      toolCalls.map(async (toolCall): Promise<[string, ToolResult]> => {
+        if (context.isAborted) {
+          return [toolCall.id, abortedResult];
+        }
+        const result = await this.dispatch(toolCall, context);
+        return [toolCall.id, result];
+      })
+    );
+
+    return new Map(entries);
+  }
+
+  private truncateResult(result: ToolResult): ToolResult {
+    if (result.output.length <= MAX_OUTPUT_CHARS) return result;
+    this.logger.info(
+      { originalLength: result.output.length, limit: MAX_OUTPUT_CHARS },
+      'Tool output truncated',
+    );
+    return {
+      ...result,
+      output: result.output.slice(0, MAX_OUTPUT_CHARS) + TRUNCATION_NOTICE,
+    };
+  }
+
+  getToolDescriptions(): ToolDescription[] {
+    const descriptions: ToolDescription[] = [];
+    for (const [, tool] of this.toolRegistry.getAll()) {
+      descriptions.push(tool.describe());
+    }
+    return descriptions;
+  }
+}