@soleri/forge 0.0.1 → 4.0.0

package/src/templates/entry-point.ts

@@ -0,0 +1,120 @@
+import type { AgentConfig } from '../types.js';
+
+/**
+ * Generate the main index.ts entry point for the agent.
+ */
+export function generateEntryPoint(config: AgentConfig): string {
+  const facadeImports = config.domains
+    .map((d) => {
+      const fn = `create${pascalCase(d)}Facade`;
+      const file = `${d}.facade.js`;
+      return `import { ${fn} } from './facades/${file}';`;
+    })
+    .join('\n');
+
+  const facadeCreations = config.domains
+    .map((d) => `    create${pascalCase(d)}Facade(vault, brain),`)
+    .join('\n');
+
+  return `#!/usr/bin/env node
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { homedir } from 'node:os';
+
+import { Vault, Brain, Planner, KeyPool, loadKeyPoolConfig, loadIntelligenceData, registerAllFacades } from '@soleri/core';
+${facadeImports}
+import { createCoreFacade } from './facades/core.facade.js';
+import { LLMClient } from './llm/llm-client.js';
+import { PERSONA, getPersonaPrompt } from './identity/persona.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+async function main(): Promise<void> {
+  // Initialize persistent vault at ~/.${config.id}/vault.db
+  const vaultPath = join(homedir(), '.${config.id}', 'vault.db');
+  const vault = new Vault(vaultPath);
+  console.error(\`[\${PERSONA.name.toLowerCase()}] Vault: \${vaultPath}\`);
+
+  // Load and seed intelligence data
+  const dataDir = join(__dirname, 'intelligence', 'data');
+  const entries = loadIntelligenceData(dataDir);
+  if (entries.length > 0) {
+    const seeded = vault.seed(entries);
+    console.error(\`[\${PERSONA.name.toLowerCase()}] Seeded vault with \${seeded} intelligence entries\`);
+  } else {
+    console.error(\`[\${PERSONA.name.toLowerCase()}] Vault is empty — ready for knowledge capture\`);
+  }
+
+  // Initialize planner at ~/.${config.id}/plans.json
+  const plansPath = join(homedir(), '.${config.id}', 'plans.json');
+  const planner = new Planner(plansPath);
+  console.error(\`[\${PERSONA.name.toLowerCase()}] Planner: \${plansPath}\`);
+
+  // Initialize brain — intelligence layer for ranked search, auto-tagging, dedup
+  const brain = new Brain(vault);
+  console.error(\`[\${PERSONA.name.toLowerCase()}] Brain: vocabulary \${brain.getVocabularySize()} terms\`);
+
+  // Initialize LLM client (optional — works without API keys)
+  const keyPoolFiles = loadKeyPoolConfig('${config.id}');
+  const openaiKeyPool = new KeyPool(keyPoolFiles.openai);
+  const anthropicKeyPool = new KeyPool(keyPoolFiles.anthropic);
+  const llmClient = new LLMClient(openaiKeyPool, anthropicKeyPool);
+  const llmAvail = llmClient.isAvailable();
+  console.error(\`[\${PERSONA.name.toLowerCase()}] LLM: OpenAI \${llmAvail.openai ? 'available' : 'not configured'}, Anthropic \${llmAvail.anthropic ? 'available' : 'not configured'}\`);
+
+  // Create MCP server
+  const server = new McpServer({
+    name: '${config.id}-mcp',
+    version: '1.0.0',
+  });
+
+  // Register persona prompt
+  server.prompt('persona', 'Get agent persona and principles', async () => ({
+    messages: [{ role: 'assistant' as const, content: { type: 'text' as const, text: getPersonaPrompt() } }],
+  }));
+
+  // Create and register facades
+  const facades = [
+${facadeCreations}
+    createCoreFacade(vault, planner, brain, llmClient, openaiKeyPool, anthropicKeyPool),
+  ];
+
+  registerAllFacades(server, facades);
+
+  const stats = vault.stats();
+  console.error(\`[\${PERSONA.name.toLowerCase()}] \${PERSONA.name} — \${PERSONA.role}\`);
+  console.error(\`[\${PERSONA.name.toLowerCase()}] Vault: \${stats.totalEntries} entries across \${Object.keys(stats.byDomain).length} domains\`);
+  console.error(\`[\${PERSONA.name.toLowerCase()}] Registered \${facades.length} facades with \${facades.reduce((sum, f) => sum + f.ops.length, 0)} operations\`);
+
+  // Stdio transport
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error(\`[\${PERSONA.name.toLowerCase()}] Connected via stdio transport\`);
+  console.error(\`[\${PERSONA.name.toLowerCase()}] Say "Hello, \${PERSONA.name}!" to activate\`);
+
+  // Graceful shutdown
+  const shutdown = async (): Promise<void> => {
+    console.error(\`[\${PERSONA.name.toLowerCase()}] Shutting down...\`);
+    vault.close();
+    process.exit(0);
+  };
+  process.on('SIGTERM', shutdown);
+  process.on('SIGINT', shutdown);
+}
+
+main().catch((err) => {
+  console.error('[${config.id}] Fatal error:', err);
+  process.exit(1);
+});
+`;
+}
+
+function pascalCase(s: string): string {
+  return s
+    .split(/[-_\s]+/)
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join('');
+}

package/src/templates/inject-claude-md.ts

@@ -0,0 +1,94 @@
+import type { AgentConfig } from '../types.js';
+
+/**
+ * Generates src/activation/inject-claude-md.ts for a new agent.
+ * Provides idempotent CLAUDE.md injection — creates, appends, or updates
+ * the agent's section between HTML comment markers.
+ * Supports both project-level and global (~/.claude/CLAUDE.md) injection.
+ *
+ * Uses array-joined pattern because the generated code contains
+ * template literals (backticks) for path operations and string interpolation.
+ */
+export function generateInjectClaudeMd(config: AgentConfig): string {
+  const marker = `${config.id}:mode`;
+
+  return [
+    "import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';",
+    "import { homedir } from 'node:os';",
+    "import { join } from 'node:path';",
+    "import { getClaudeMdContent, getClaudeMdMarker } from './claude-md-content.js';",
+    '',
+    'export interface InjectResult {',
+    '  injected: boolean;',
+    '  path: string;',
+    "  action: 'created' | 'updated' | 'appended';",
+    '}',
+    '',
+    '/**',
+    ' * Inject into a specific CLAUDE.md file path.',
+    ' * Shared logic for both project-level and global injection.',
+    ' */',
+    'function injectIntoFile(filePath: string): InjectResult {',
+    '  const content = getClaudeMdContent();',
+    '  const marker = getClaudeMdMarker();',
+    `  const startMarker = '<!-- ' + marker + ' -->';`,
+    `  const endMarker = '<!-- /' + marker + ' -->';`,
+    '',
+    '  if (!existsSync(filePath)) {',
+    "    writeFileSync(filePath, content + '\\n', 'utf-8');",
+    "    return { injected: true, path: filePath, action: 'created' };",
+    '  }',
+    '',
+    "  const existing = readFileSync(filePath, 'utf-8');",
+    '',
+    '  if (existing.includes(startMarker)) {',
+    '    const startIdx = existing.indexOf(startMarker);',
+    '    const endIdx = existing.indexOf(endMarker);',
+    '    if (endIdx === -1) {',
+    "      const updated = existing.slice(0, startIdx) + content + '\\n' + existing.slice(startIdx + startMarker.length);",
+    "      writeFileSync(filePath, updated, 'utf-8');",
+    "      return { injected: true, path: filePath, action: 'updated' };",
+    '    }',
+    '    const updated = existing.slice(0, startIdx) + content + existing.slice(endIdx + endMarker.length);',
+    "    writeFileSync(filePath, updated, 'utf-8');",
+    "    return { injected: true, path: filePath, action: 'updated' };",
+    '  }',
+    '',
+    "  const separator = existing.endsWith('\\n') ? '\\n' : '\\n\\n';",
+    "  writeFileSync(filePath, existing + separator + content + '\\n', 'utf-8');",
+    "  return { injected: true, path: filePath, action: 'appended' };",
+    '}',
+    '',
+    '/**',
+    ' * Inject agent CLAUDE.md section into a project.',
+    ' * - If no CLAUDE.md exists: creates one',
+    ' * - If markers found: replaces content between them (update)',
+    ' * - If no markers: appends section to end',
+    ' */',
+    'export function injectClaudeMd(projectPath: string): InjectResult {',
+    "  return injectIntoFile(join(projectPath, 'CLAUDE.md'));",
+    '}',
+    '',
+    '/**',
+    ' * Inject agent CLAUDE.md section into the global ~/.claude/CLAUDE.md.',
+    " * Creates ~/.claude/ directory if it doesn't exist.",
+    ' * This makes the activation phrase work in any project.',
+    ' */',
+    'export function injectClaudeMdGlobal(): InjectResult {',
+    "  const claudeDir = join(homedir(), '.claude');",
+    '  if (!existsSync(claudeDir)) {',
+    '    mkdirSync(claudeDir, { recursive: true });',
+    '  }',
+    "  return injectIntoFile(join(claudeDir, 'CLAUDE.md'));",
+    '}',
+    '',
+    '/**',
+    ' * Check if the agent marker exists in a CLAUDE.md file.',
+    ' */',
+    'export function hasAgentMarker(filePath: string): boolean {',
+    '  if (!existsSync(filePath)) return false;',
+    "  const content = readFileSync(filePath, 'utf-8');",
+    `  return content.includes('<!-- ${marker} -->');`,
+    '}',
+  ].join('\n');
+}

package/src/templates/llm-client.ts

@@ -0,0 +1,301 @@
+import type { AgentConfig } from '../types.js';
+
+/**
+ * Generate the LLM client file for a new agent.
+ * Contains LLMClient (OpenAI fetch + Anthropic SDK) and ModelRouter (inlined).
+ * Uses config.id to resolve ~/.{agentId}/model-routing.json.
+ */
+export function generateLLMClient(config: AgentConfig): string {
+  return `/**
+ * LLM Client — Unified OpenAI/Anthropic caller with key pool rotation
+ * Generated by Soleri — do not edit manually.
+ */
+
+import Anthropic from '@anthropic-ai/sdk';
+import { SecretString, LLMError, CircuitBreaker, retry, parseRateLimitHeaders } from '@soleri/core';
+import type {
+  LLMCallOptions,
+  LLMCallResult,
+  RouteEntry,
+  RoutingConfig,
+  KeyPool,
+} from '@soleri/core';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { homedir } from 'node:os';
+
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+
+const OPENAI_API_URL = 'https://api.openai.com/v1/chat/completions';
+
+// =============================================================================
+// MODEL ROUTER (inlined)
+// =============================================================================
+
+function loadRoutingConfig(): RoutingConfig {
+  const defaultConfig: RoutingConfig = {
+    routes: [],
+    defaultOpenAIModel: 'gpt-4o-mini',
+    defaultAnthropicModel: 'claude-sonnet-4-20250514',
+  };
+
+  const configPath = path.join(
+    homedir(),
+    '.${config.id}',
+    'model-routing.json',
+  );
+
+  try {
+    if (fs.existsSync(configPath)) {
+      const data = JSON.parse(fs.readFileSync(configPath, 'utf-8')) as Partial<RoutingConfig>;
+      if (data.routes && Array.isArray(data.routes)) {
+        defaultConfig.routes = data.routes;
+      }
+      if (data.defaultOpenAIModel) {
+        defaultConfig.defaultOpenAIModel = data.defaultOpenAIModel;
+      }
+      if (data.defaultAnthropicModel) {
+        defaultConfig.defaultAnthropicModel = data.defaultAnthropicModel;
+      }
+    }
+  } catch {
+    // Config not available — use defaults
+  }
+
+  return defaultConfig;
+}
+
+function inferProvider(model: string): 'openai' | 'anthropic' {
+  if (model.startsWith('claude-') || model.startsWith('anthropic/')) {
+    return 'anthropic';
+  }
+  return 'openai';
+}
+
+class ModelRouter {
+  private config: RoutingConfig;
+
+  constructor(config?: RoutingConfig) {
+    this.config = config || loadRoutingConfig();
+  }
+
+  resolve(
+    caller: string,
+    task?: string,
+    originalModel?: string,
+  ): { model: string; provider: 'openai' | 'anthropic' } {
+    if (task) {
+      const exactMatch = this.config.routes.find(
+        (r) => r.caller === caller && r.task === task,
+      );
+      if (exactMatch) {
+        return { model: exactMatch.model, provider: exactMatch.provider };
+      }
+    }
+
+    const callerMatch = this.config.routes.find(
+      (r) => r.caller === caller && !r.task,
+    );
+    if (callerMatch) {
+      return { model: callerMatch.model, provider: callerMatch.provider };
+    }
+
+    if (originalModel) {
+      const provider = inferProvider(originalModel);
+      return { model: originalModel, provider };
+    }
+
+    return { model: this.config.defaultOpenAIModel, provider: 'openai' };
+  }
+
+  getRoutes(): RouteEntry[] {
+    return [...this.config.routes];
+  }
+}
+
+// =============================================================================
+// LLM CLIENT
+// =============================================================================
+
+export class LLMClient {
+  private openaiKeyPool: KeyPool;
+  private anthropicKeyPool: KeyPool;
+  private anthropicClient: Anthropic | null = null;
+  private anthropicBreaker: CircuitBreaker;
+  private anthropicKeyFingerprint: string = '';
+  private router: ModelRouter;
+
+  constructor(openaiKeyPool: KeyPool, anthropicKeyPool: KeyPool) {
+    this.openaiKeyPool = openaiKeyPool;
+    this.anthropicKeyPool = anthropicKeyPool;
+    this.anthropicBreaker = new CircuitBreaker({
+      name: 'llm-anthropic',
+      failureThreshold: 5,
+      resetTimeoutMs: 60_000,
+    });
+    this.router = new ModelRouter();
+  }
+
+  async complete(options: LLMCallOptions): Promise<LLMCallResult> {
+    const routed = this.router.resolve(
+      options.caller,
+      options.task,
+      options.model,
+    );
+    const resolvedOptions = { ...options, model: routed.model, provider: routed.provider };
+
+    return resolvedOptions.provider === 'anthropic'
+      ? this.callAnthropic(resolvedOptions)
+      : this.callOpenAI(resolvedOptions);
+  }
+
+  isAvailable(): { openai: boolean; anthropic: boolean } {
+    return {
+      openai: this.openaiKeyPool.hasKeys,
+      anthropic: this.anthropicKeyPool.hasKeys,
+    };
+  }
+
+  getRoutes(): RouteEntry[] {
+    return this.router.getRoutes();
+  }
+
+  // ===========================================================================
+  // OPENAI
+  // ===========================================================================
+
+  private async callOpenAI(options: LLMCallOptions): Promise<LLMCallResult> {
+    const keyPool = this.openaiKeyPool.hasKeys ? this.openaiKeyPool : null;
+
+    if (!keyPool) {
+      throw new LLMError('OpenAI API key not configured', { retryable: false });
+    }
+
+    const start = Date.now();
+
+    const doRequest = async (): Promise<LLMCallResult> => {
+      const apiKey = keyPool.getActiveKey().expose();
+      const keyIndex = keyPool.activeKeyIndex;
+
+      const response = await fetch(OPENAI_API_URL, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: \`Bearer \${apiKey}\`,
+        },
+        body: JSON.stringify({
+          model: options.model,
+          messages: [
+            { role: 'system', content: options.systemPrompt },
+            { role: 'user', content: options.userPrompt },
+          ],
+          temperature: options.temperature ?? 0.3,
+          max_completion_tokens: options.maxTokens ?? 500,
+        }),
+      });
+
+      if (response.headers) {
+        const rateLimits = parseRateLimitHeaders(response.headers);
+        if (rateLimits.remaining !== null) {
+          keyPool.updateQuota(keyIndex, rateLimits.remaining);
+          keyPool.rotatePreemptive();
+        }
+      }
+
+      if (!response.ok) {
+        if (response.status === 429 && keyPool.poolSize > 1) {
+          keyPool.rotateOnError();
+        }
+
+        const errorBody = await response.text();
+        throw new LLMError(
+          \`OpenAI API error: \${response.status} - \${errorBody}\`,
+          { retryable: response.status === 429 || response.status >= 500, statusCode: response.status },
+        );
+      }
+
+      const data = (await response.json()) as {
+        choices: Array<{ message: { content: string } }>;
+        usage?: { prompt_tokens?: number; completion_tokens?: number };
+      };
+
+      return {
+        text: data.choices[0]?.message?.content || '',
+        model: options.model,
+        provider: 'openai' as const,
+        inputTokens: data.usage?.prompt_tokens,
+        outputTokens: data.usage?.completion_tokens,
+        durationMs: Date.now() - start,
+      };
+    };
+
+    return retry(doRequest, { maxAttempts: 3 });
+  }
+
+  // ===========================================================================
+  // ANTHROPIC
+  // ===========================================================================
+
+  private async callAnthropic(options: LLMCallOptions): Promise<LLMCallResult> {
+    const client = this.getAnthropicClient();
+    if (!client) {
+      throw new LLMError('Anthropic API key not configured', { retryable: false });
+    }
+
+    const start = Date.now();
+
+    return this.anthropicBreaker.call(() =>
+      retry(
+        async () => {
+          const response = await client.messages.create(
+            {
+              model: options.model,
+              max_tokens: options.maxTokens ?? 1024,
+              system: options.systemPrompt,
+              messages: [{ role: 'user', content: options.userPrompt }],
+            },
+            { timeout: 60_000 },
+          );
+
+          const text = response.content
+            .filter(
+              (block): block is Anthropic.TextBlock => block.type === 'text',
+            )
+            .map((block) => block.text)
+            .join('\\n');
+
+          return {
+            text,
+            model: options.model,
+            provider: 'anthropic' as const,
+            inputTokens: response.usage?.input_tokens,
+            outputTokens: response.usage?.output_tokens,
+            durationMs: Date.now() - start,
+          };
+        },
+        { maxAttempts: 2 },
+      ),
+    );
+  }
+
+  private getAnthropicClient(): Anthropic | null {
+    if (!this.anthropicKeyPool.hasKeys) return null;
+
+    const currentKey = this.anthropicKeyPool.getActiveKey().expose();
+    const currentFingerprint = currentKey.slice(-8);
+
+    if (currentFingerprint !== this.anthropicKeyFingerprint) {
+      this.anthropicClient = null;
+      this.anthropicKeyFingerprint = currentFingerprint;
+    }
+
+    if (this.anthropicClient) return this.anthropicClient;
+
+    this.anthropicClient = new Anthropic({ apiKey: currentKey });
+    return this.anthropicClient;
+  }
+}
+`;
+}

package/src/templates/package-json.ts

@@ -0,0 +1,39 @@
+import type { AgentConfig } from '../types.js';
+
+export function generatePackageJson(config: AgentConfig): string {
+  const pkg = {
+    name: `${config.id}-mcp`,
+    version: '1.0.0',
+    description: config.description,
+    type: 'module',
+    main: 'dist/index.js',
+    bin: { [`${config.id}-mcp`]: 'dist/index.js' },
+    scripts: {
+      dev: 'tsx src/index.ts',
+      build: 'tsc && node scripts/copy-assets.js',
+      start: 'node dist/index.js',
+      typecheck: 'tsc --noEmit',
+      test: 'vitest run',
+      'test:watch': 'vitest',
+      'test:coverage': 'vitest run --coverage',
+    },
+    keywords: ['mcp', 'agent', config.id, ...config.domains.slice(0, 5)],
+    license: 'MIT',
+    engines: { node: '>=18.0.0' },
+    dependencies: {
+      '@anthropic-ai/sdk': '^0.39.0',
+      '@modelcontextprotocol/sdk': '^1.12.1',
+      '@soleri/core': '^1.0.0',
+      zod: '^3.24.2',
+    },
+    devDependencies: {
+      '@types/node': '^22.13.4',
+      '@vitest/coverage-v8': '^3.0.5',
+      tsx: '^4.19.2',
+      typescript: '^5.7.3',
+      vitest: '^3.0.5',
+    },
+  };
+
+  return JSON.stringify(pkg, null, 2);
+}

package/src/templates/persona.ts

@@ -0,0 +1,45 @@
+import type { AgentConfig } from '../types.js';
+
+export function generatePersona(config: AgentConfig): string {
+  const principleLines = config.principles.map((p) => `    '${escapeQuotes(p)}',`).join('\n');
+
+  return `export interface AgentPersona {
+  name: string;
+  role: string;
+  description: string;
+  principles: string[];
+  greeting: string;
+}
+
+export const PERSONA: AgentPersona = {
+  name: '${escapeQuotes(config.name)}',
+  role: '${escapeQuotes(config.role)}',
+  description: '${escapeQuotes(config.description)}',
+  principles: [
+${principleLines}
+  ],
+  greeting: '${escapeQuotes(config.greeting)}',
+};
+
+export function getPersonaPrompt(): string {
+  return [
+    \`You are \${PERSONA.name}, a \${PERSONA.role}.\`,
+    '',
+    PERSONA.description,
+    '',
+    'Core principles:',
+    ...PERSONA.principles.map((p) => \`- \${p}\`),
+    '',
+    'When advising:',
+    '- Reference specific patterns from the knowledge vault',
+    '- Provide concrete examples, not just theory',
+    '- Flag anti-patterns with severity level',
+    '- Suggest the simplest approach that solves the problem',
+  ].join('\\n');
+}
+`;
+}
+
+function escapeQuotes(s: string): string {
+  return s.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+}