@soleri/forge 5.11.0 → 5.12.0

package/src/scaffolder.ts

@@ -22,14 +22,37 @@ import { generateInjectClaudeMd } from './templates/inject-claude-md.js';
 import { generateActivate } from './templates/activate.js';
 import { generateReadme } from './templates/readme.js';
 import { generateSetupScript } from './templates/setup-script.js';
+import { generateAgentsMd } from './templates/agents-md.js';
 import { generateSkills } from './templates/skills.js';
 import { generateExtensionsIndex, generateExampleOp } from './templates/extensions.js';
+import { generateTelegramBot } from './templates/telegram-bot.js';
+import { generateTelegramConfig } from './templates/telegram-config.js';
+import { generateTelegramAgent } from './templates/telegram-agent.js';
+import { generateTelegramSupervisor } from './templates/telegram-supervisor.js';
+
+function getSetupTarget(config: AgentConfig): 'claude' | 'codex' | 'both' {
+  return config.setupTarget ?? 'claude';
+}
+
+function includesClaudeSetup(config: AgentConfig): boolean {
+  const target = getSetupTarget(config);
+  return target === 'claude' || target === 'both';
+}
+
+function includesCodexSetup(config: AgentConfig): boolean {
+  const target = getSetupTarget(config);
+  return target === 'codex' || target === 'both';
+}
 
 /**
  * Preview what scaffold will create without writing anything.
  */
 export function previewScaffold(config: AgentConfig): ScaffoldPreview {
   const agentDir = join(config.outputDir, config.id);
+  const claudeSetup = includesClaudeSetup(config);
+  const codexSetup = includesCodexSetup(config);
+  const setupLabel =
+    claudeSetup && codexSetup ? 'Claude Code + Codex' : claudeSetup ? 'Claude Code' : 'Codex';
 
   const files = [
     { path: 'package.json', description: 'NPM package with MCP SDK, SQLite, Zod dependencies' },
@@ -80,7 +103,7 @@ export function previewScaffold(config: AgentConfig): ScaffoldPreview {
     },
     {
       path: 'scripts/setup.sh',
-      description: 'Automated setup — Node.js check, build, Claude Code MCP registration',
+      description: `Automated setup — Node.js check, build, ${setupLabel} MCP registration`,
     },
     {
       path: 'skills/',
@@ -90,13 +113,35 @@ export function previewScaffold(config: AgentConfig): ScaffoldPreview {
     },
   ];
 
-  if (config.hookPacks?.length) {
+  if (codexSetup) {
+    files.push({
+      path: 'AGENTS.md',
+      description: 'Codex project instructions and activation workflow',
+    });
+  }
+
+  if (claudeSetup && config.hookPacks?.length) {
     files.push({
       path: '.claude/',
       description: `Hook pack files (${config.hookPacks.join(', ')})`,
     });
   }
 
+  if (config.telegram) {
+    files.push(
+      {
+        path: 'src/telegram-bot.ts',
+        description: 'Telegram bot entry point with Grammy middleware',
+      },
+      { path: 'src/telegram-config.ts', description: 'Telegram config loading (env + file)' },
+      { path: 'src/telegram-agent.ts', description: 'Agent loop wired to MCP tools' },
+      {
+        path: 'src/telegram-supervisor.ts',
+        description: 'Process supervisor with restart and logging',
+      },
+    );
+  }
+
   const facades = [
     ...config.domains.map((d) => ({
       name: `${config.id}_${d.replace(/-/g, '_')}`,
@@ -208,6 +253,8 @@ export function scaffold(config: AgentConfig): ScaffoldResult {
       greeting: `Hello! I'm ${config.name}, your AI assistant for ${config.role}.`,
     };
   }
+  const claudeSetup = includesClaudeSetup(config);
+  const codexSetup = includesCodexSetup(config);
   const agentDir = join(config.outputDir, config.id);
   const filesCreated: string[] = [];
 
@@ -238,7 +285,7 @@ export function scaffold(config: AgentConfig): ScaffoldResult {
     'src/extensions/middleware',
   ];
 
-  if (config.hookPacks?.length) {
+  if (claudeSetup && config.hookPacks?.length) {
     dirs.push('.claude');
   }
 
@@ -265,6 +312,10 @@ export function scaffold(config: AgentConfig): ScaffoldResult {
     ['scripts/setup.sh', generateSetupScript(config)],
   ];
 
+  if (codexSetup) {
+    projectFiles.push(['AGENTS.md', generateAgentsMd(config)]);
+  }
+
   for (const [path, content] of projectFiles) {
     writeFileSync(join(agentDir, path), content, 'utf-8');
     filesCreated.push(path);
@@ -285,6 +336,16 @@ export function scaffold(config: AgentConfig): ScaffoldResult {
     ['src/extensions/ops/example.ts', generateExampleOp(config)],
   ];
 
+  // Telegram transport files (optional)
+  if (config.telegram) {
+    sourceFiles.push(
+      ['src/telegram-bot.ts', generateTelegramBot(config)],
+      ['src/telegram-config.ts', generateTelegramConfig(config)],
+      ['src/telegram-agent.ts', generateTelegramAgent(config)],
+      ['src/telegram-supervisor.ts', generateTelegramSupervisor(config)],
+    );
+  }
+
   // Empty intelligence data bundles (domain facades come from @soleri/core at runtime)
   for (const domain of config.domains) {
     sourceFiles.push([`src/intelligence/data/${domain}.json`, generateEmptyBundle(domain)]);
@@ -325,16 +386,41 @@ export function scaffold(config: AgentConfig): ScaffoldResult {
     buildError = err instanceof Error ? err.message : String(err);
   }
 
-  // Register the agent as an MCP server in ~/.claude.json (only if build succeeded)
-  let mcpReg: { registered: boolean; path: string; error?: string };
-  if (buildSuccess) {
-    mcpReg = registerMcpServer(config.id, agentDir);
-  } else {
-    mcpReg = {
-      registered: false,
-      path: join(homedir(), '.claude.json'),
-      error: 'Skipped — build failed',
-    };
+  // Register the agent as an MCP server in selected host configs (only if build succeeded)
+  const mcpRegistrations: Array<{ host: 'Claude Code' | 'Codex'; result: RegistrationResult }> = [];
+  if (claudeSetup) {
+    if (buildSuccess) {
+      mcpRegistrations.push({
+        host: 'Claude Code',
+        result: registerClaudeMcpServer(config.id, agentDir),
+      });
+    } else {
+      mcpRegistrations.push({
+        host: 'Claude Code',
+        result: {
+          registered: false,
+          path: join(homedir(), '.claude.json'),
+          error: 'Skipped — build failed',
+        },
+      });
+    }
+  }
+  if (codexSetup) {
+    if (buildSuccess) {
+      mcpRegistrations.push({
+        host: 'Codex',
+        result: registerCodexMcpServer(config.id, agentDir),
+      });
+    } else {
+      mcpRegistrations.push({
+        host: 'Codex',
+        result: {
+          registered: false,
+          path: join(homedir(), '.codex', 'config.toml'),
+          error: 'Skipped — build failed',
+        },
+      });
+    }
   }
 
   const summaryLines = [
@@ -354,22 +440,31 @@ export function scaffold(config: AgentConfig): ScaffoldResult {
     summaryLines.push(`  Run manually: cd ${agentDir} && npm install && npm run build`);
   }
 
-  if (config.hookPacks?.length) {
+  if (claudeSetup && config.hookPacks?.length) {
     summaryLines.push(`${config.hookPacks.length} hook pack(s) bundled in .claude/`);
   }
 
-  if (mcpReg.registered) {
-    summaryLines.push(`MCP server registered in ${mcpReg.path}`);
-  } else {
-    summaryLines.push(`Warning: Failed to register MCP server in ${mcpReg.path}: ${mcpReg.error}`);
+  for (const registration of mcpRegistrations) {
+    if (registration.result.registered) {
+      summaryLines.push(
+        `${registration.host} MCP server registered in ${registration.result.path}`,
+      );
+    } else {
+      summaryLines.push(
+        `Warning: Failed to register ${registration.host} MCP server in ${registration.result.path}: ${registration.result.error}`,
+      );
+    }
   }
 
-  summaryLines.push(
-    '',
-    'Next steps:',
-    '  Restart Claude Code',
-    `  Say "Hello, ${config.name}!" to activate the persona`,
-  );
+  const nextSteps = ['', 'Next steps:'];
+  if (claudeSetup) {
+    nextSteps.push('  Restart Claude Code');
+  }
+  if (codexSetup) {
+    nextSteps.push('  Restart Codex');
+  }
+  nextSteps.push(`  Say "Hello, ${config.name}!" to activate the persona`);
+  summaryLines.push(...nextSteps);
 
   return {
     success: true,
@@ -432,14 +527,20 @@ export function listAgents(parentDir: string): AgentInfo[] {
   return agents;
 }
 
+/**
+ * Registration result for host config updates.
+ */
+interface RegistrationResult {
+  registered: boolean;
+  path: string;
+  error?: string;
+}
+
 /**
  * Register the agent as an MCP server in ~/.claude.json (User MCPs).
  * Idempotent — updates existing entry if present.
  */
-function registerMcpServer(
-  agentId: string,
-  agentDir: string,
-): { registered: boolean; path: string; error?: string } {
+function registerClaudeMcpServer(agentId: string, agentDir: string): RegistrationResult {
   const claudeJsonPath = join(homedir(), '.claude.json');
 
   try {
@@ -472,6 +573,47 @@ function registerMcpServer(
   }
 }
 
+/**
+ * Register the agent as an MCP server in ~/.codex/config.toml.
+ * Idempotent — updates existing section if present.
+ */
+function registerCodexMcpServer(agentId: string, agentDir: string): RegistrationResult {
+  const codexDir = join(homedir(), '.codex');
+  const codexConfigPath = join(codexDir, 'config.toml');
+  const sectionHeader = `[mcp_servers.${agentId}]`;
+  const sectionBlock = `${sectionHeader}
+command = "node"
+args = ["${join(agentDir, 'dist', 'index.js')}"]
+`;
+
+  try {
+    mkdirSync(codexDir, { recursive: true });
+
+    let content = existsSync(codexConfigPath) ? readFileSync(codexConfigPath, 'utf-8') : '';
+    const start = content.indexOf(sectionHeader);
+
+    if (start === -1) {
+      const trimmed = content.trimEnd();
+      content = trimmed.length === 0 ? `${sectionBlock}\n` : `${trimmed}\n\n${sectionBlock}\n`;
+    } else {
+      const afterHeader = start + sectionHeader.length;
+      const tail = content.slice(afterHeader);
+      const nextSectionOffset = tail.search(/\n\[[^\]]+\]/);
+      const end = nextSectionOffset === -1 ? content.length : afterHeader + nextSectionOffset;
+      content = `${content.slice(0, start).trimEnd()}\n\n${sectionBlock}\n${content.slice(end).trimStart()}`;
+    }
+
+    writeFileSync(codexConfigPath, content.replace(/\n{3,}/g, '\n\n'), 'utf-8');
+    return { registered: true, path: codexConfigPath };
+  } catch (err) {
+    return {
+      registered: false,
+      path: codexConfigPath,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
 function generateEmptyBundle(domain: string): string {
   return JSON.stringify(
     {

package/src/templates/agents-md.ts

@@ -0,0 +1,35 @@
+import type { AgentConfig } from '../types.js';
+
+/**
+ * Generate AGENTS.md content for Codex sessions.
+ */
+export function generateAgentsMd(config: AgentConfig): string {
+  const principles = config.principles.map((p) => `- ${p}`).join('\n');
+  const domains = config.domains.map((d) => `- ${d}`).join('\n');
+
+  return `# AGENTS.md instructions for this project
+
+## Agent Identity
+- Name: ${config.name}
+- Role: ${config.role}
+- Agent MCP prefix: \`${config.id}\`
+
+## Activation
+- Say "Hello, ${config.name}!" to activate persona behavior via \`${config.id}_core\`.
+- Say "Goodbye, ${config.name}!" to deactivate.
+
+## Domains
+${domains}
+
+## Principles
+${principles}
+
+## Skills
+- Local skills live in \`skills/<skill>/SKILL.md\`.
+- If a user explicitly names a skill, open that \`SKILL.md\` and follow it for that turn.
+
+## Setup Notes
+- This repository was scaffolded with Codex support.
+- Session model/reasoning is selected at session start and does not auto-switch per prompt.
+`;
+}

package/src/templates/entry-point.ts

@@ -257,10 +257,23 @@ async function main(): Promise<void> {
     messages: [{ role: 'assistant' as const, content: { type: 'text' as const, text: getPersonaPrompt() } }],
   }));
 
-  registerAllFacades(server, allFacades);
+  // Hot ops — promoted to standalone MCP tools with full schema discovery
+  const hotOps = new Set([
+    'search_intelligent',
+    'capture_knowledge',
+    'orchestrate_plan',
+    'orchestrate_execute',
+    'orchestrate_complete',
+  ]);
+
+  registerAllFacades(server, allFacades, {
+    agentId: '${config.id}',
+    hotOps,
+    authPolicy: () => runtime.authPolicy,
+  });
 
   console.error(\`[\${tag}] \${PERSONA.name} — \${PERSONA.role}\`);
-  console.error(\`[\${tag}] Registered \${allFacades.length} facades with \${allFacades.reduce((sum, f) => sum + f.ops.length, 0)} operations\`);
+  console.error(\`[\${tag}] Registered \${allFacades.length} facades with \${allFacades.reduce((sum, f) => sum + f.ops.length, 0)} operations (\${hotOps.size} hot)\`);
 
   // ─── Transport + shutdown ──────────────────────────────────────
   const transport = new StdioServerTransport();

package/src/templates/package-json.ts

@@ -16,6 +16,12 @@ export function generatePackageJson(config: AgentConfig): string {
       test: 'vitest run',
       'test:watch': 'vitest',
       'test:coverage': 'vitest run --coverage',
+      ...(config.telegram
+        ? {
+            'telegram:start': 'node dist/telegram-supervisor.js',
+            'telegram:dev': 'tsx src/telegram-bot.ts',
+          }
+        : {}),
     },
     keywords: ['mcp', 'agent', config.id, ...config.domains.slice(0, 5)],
     license: 'MIT',
@@ -24,6 +30,7 @@ export function generatePackageJson(config: AgentConfig): string {
       '@modelcontextprotocol/sdk': '^1.12.1',
       '@soleri/core': '^2.0.0',
       zod: '^3.24.2',
+      ...(config.telegram ? { grammy: '^1.35.0' } : {}),
     },
     optionalDependencies: {
       '@anthropic-ai/sdk': '^0.39.0',

package/src/templates/readme.ts

@@ -4,12 +4,92 @@ import type { AgentConfig } from '../types.js';
  * Generate a README.md for the scaffolded agent.
  */
 export function generateReadme(config: AgentConfig): string {
+  const setupTarget = config.setupTarget ?? 'claude';
+  const claudeSetup = setupTarget === 'claude' || setupTarget === 'both';
+  const codexSetup = setupTarget === 'codex' || setupTarget === 'both';
   const domainRows = config.domains
     .map((d) => `| ${d} | *Ready for knowledge capture* |`)
     .join('\n');
 
   const principleLines = config.principles.map((p) => `- ${p}`).join('\n');
 
+  const quickStartSession =
+    claudeSetup && codexSetup
+      ? 'Start a new Claude Code or Codex session, then say:'
+      : claudeSetup
+        ? 'Start a new Claude Code session, then say:'
+        : 'Start a new Codex session, then say:';
+
+  const prerequisites = [
+    '- **Node.js 18+** — `node --version` to check',
+    ...(claudeSetup ? ['- **Claude Code** — Anthropic CLI (`claude` command)'] : []),
+    ...(codexSetup ? ['- **Codex** — desktop/CLI with `~/.codex/config.toml`'] : []),
+  ].join('\n');
+
+  const helloFlow = [
+    `- ${config.name} returns its persona, principles, and tool recommendations`,
+    ...(claudeSetup ? [`- Claude can adopt the ${config.name} persona for the session`] : []),
+    ...(claudeSetup
+      ? [`- ${config.name} can inject/check CLAUDE.md integration when requested`]
+      : []),
+    ...(codexSetup
+      ? ['- Codex uses project-level AGENTS.md guidance and local skills for routing']
+      : []),
+  ].join('\n');
+
+  const manualSetupBlocks = [
+    ...(claudeSetup
+      ? [
+          [
+            '### Claude Code',
+            '',
+            'Add this to `~/.claude/settings.json` under `mcpServers`:',
+            '',
+            '```json',
+            '{',
+            '  "mcpServers": {',
+            `    "${config.id}": {`,
+            '      "command": "node",',
+            '      "args": ["dist/index.js"],',
+            `      "cwd": "/absolute/path/to/${config.id}"`,
+            '    }',
+            '  }',
+            '}',
+            '```',
+          ].join('\n'),
+        ]
+      : []),
+    ...(codexSetup
+      ? [
+          [
+            '### Codex',
+            '',
+            'Add this to `~/.codex/config.toml`:',
+            '',
+            '```toml',
+            `[mcp_servers.${config.id}]`,
+            'command = "node"',
+            `args = ["/absolute/path/to/${config.id}/dist/index.js"]`,
+            '```',
+          ].join('\n'),
+        ]
+      : []),
+  ].join('\n\n');
+
+  const skillsLead =
+    claudeSetup && codexSetup
+      ? `${config.name} ships with 17 structured workflow skills. In Claude Code they are invocable via \`/<skill-name>\`; in Codex they are available via generated AGENTS.md + local skill files.`
+      : claudeSetup
+        ? `${config.name} ships with 17 structured workflow skills, invocable via \`/<skill-name>\` in Claude Code:`
+        : `${config.name} ships with 17 structured workflow skills, available via generated AGENTS.md + local skill files in Codex:`;
+
+  const skillsInstallNote =
+    claudeSetup && codexSetup
+      ? 'Skills are installed to `~/.claude/commands/` and `~/.codex/skills/` during setup. Run `./scripts/setup.sh` to install or reinstall.'
+      : claudeSetup
+        ? 'Skills are installed to `~/.claude/commands/` during setup. Run `./scripts/setup.sh` to install or reinstall.'
+        : 'Skills are installed to `~/.codex/skills/` during setup. Run `./scripts/setup.sh` to install or reinstall.';
+
   return `# ${config.name} — ${config.role}
 
 ${config.description}
@@ -35,10 +115,10 @@ cd ${config.id}
 npm install
 npm run build
 
-# 2. Add to Claude Code
+# 2. Run setup
 ./scripts/setup.sh
 
-# 3. Start a new Claude Code session, then say:
+# 3. ${quickStartSession}
 #    "Hello, ${config.name}!"
 \`\`\`
 
@@ -46,33 +126,15 @@ That's it. ${config.name} will activate, check your setup, and offer to configur
 
 ## Prerequisites
 
-- **Node.js 18+** — \`node --version\` to check
-- **Claude Code** — Anthropic's CLI for Claude (\`claude\` command)
+${prerequisites}
 
 ## What Happens When You Say "Hello, ${config.name}!"
 
-1. ${config.name} returns its persona, principles, and tool recommendations
-2. Claude adopts the ${config.name} persona for the rest of the session
-3. ${config.name} checks if your project has CLAUDE.md integration
-4. If not, it offers to inject its configuration (facades table, intent detection, knowledge protocol)
+${helloFlow}
 
 ## Manual Setup (if setup.sh doesn't work)
 
-Add this to \`~/.claude/settings.json\` under \`mcpServers\`:
-
-\`\`\`json
-{
-  "mcpServers": {
-    "${config.id}": {
-      "command": "node",
-      "args": ["dist/index.js"],
-      "cwd": "/absolute/path/to/${config.id}"
-    }
-  }
-}
-\`\`\`
-
-Then restart Claude Code.
+${manualSetupBlocks}
 
 ## Domains
 
@@ -86,7 +148,7 @@ ${principleLines}
 
 ## Built-in Skills
 
-${config.name} ships with 17 structured workflow skills, invocable via \`/<skill-name>\` in Claude Code:
+${skillsLead}
 
 **Development Workflows:**
 
@@ -120,7 +182,7 @@ ${config.name} ships with 17 structured workflow skills, invocable via \`/<skill
 | \`/onboard-me\` | Instant project knowledge tour for newcomers |
 | \`/health-check\` | Vault maintenance — duplicates, contradictions, stale entries |
 
-Skills are installed to \`~/.claude/commands/\` during setup. Run \`./scripts/setup.sh\` to install or reinstall.
+${skillsInstallNote}
 
 ## Features
 
@@ -176,8 +238,8 @@ Use \`llm_status\` to check provider availability and key pool health.
 
 ### Activating and Deactivating
 
-- **"Hello, ${config.name}!"** — Activate the persona. Claude adopts ${config.name}'s identity, principles, and tool access for the session.
-- **"Goodbye, ${config.name}!"** — Deactivate. Claude returns to its default behavior.
+- **"Hello, ${config.name}!"** — Activate the persona. Your active client session adopts ${config.name}'s identity, principles, and tool access.
+- **"Goodbye, ${config.name}!"** — Deactivate and return to default assistant behavior.
 
 ### Daily Workflow