@stackbilt/aegis-core 0.1.0

package/src/mcp-client.ts

@@ -0,0 +1,275 @@
+// Thin MCP HTTP client — supports multiple MCP servers via prefix
+// Supports Streamable HTTP transport with session management
+
+interface McpToolDefinition {
+  name: string;
+  description?: string;
+  inputSchema: Record<string, unknown>;
+}
+
+interface AnthropicToolDef {
+  name: string;
+  description: string;
+  input_schema: Record<string, unknown>;
+}
+
+interface McpConfig {
+  url: string;
+  token: string;
+  prefix: string;      // e.g. 'bizops', 'cf_obs'
+  fetcher?: Fetcher;   // Service Binding for Worker-to-Worker calls
+  rpcPath?: string;    // Stateless RPC path for service binding (bypasses DO/SSE)
+}
+
+export class McpClient {
+  private url: string;
+  private token: string;
+  private prefix: string;
+  private fetcher: Fetcher | null;
+  private rpcUrl: string | null;  // Stateless RPC URL for service binding
+  private tools: McpToolDefinition[] | null = null;
+  private sessionId: string | null = null;
+
+  constructor(config: McpConfig) {
+    this.url = config.url;
+    this.token = config.token;
+    this.prefix = config.prefix;
+    this.fetcher = config.fetcher ?? null;
+    // When service binding + rpcPath provided, use stateless RPC (no DO/SSE)
+    this.rpcUrl = (config.fetcher && config.rpcPath)
+      ? new URL(config.rpcPath, config.url).href
+      : null;
+  }
+
+  getPrefix(): string {
+    return this.prefix;
+  }
+
+  private async rpc(method: string, params: Record<string, unknown> = {}): Promise<unknown> {
+    // Stateless RPC path — plain JSON, no sessions, no SSE
+    if (this.rpcUrl && this.fetcher) {
+      return this.rpcStateless(method, params);
+    }
+
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+      'Accept': 'application/json, text/event-stream',
+      'Authorization': `Bearer ${this.token}`,
+    };
+
+    if (this.sessionId) {
+      headers['Mcp-Session-Id'] = this.sessionId;
+    }
+
+    const request = new Request(this.url, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify({
+        jsonrpc: '2.0',
+        id: crypto.randomUUID(),
+        method,
+        params,
+      }),
+    });
+
+    // Use Service Binding fetch if available (avoids Worker-to-Worker 1042 error)
+    const response = this.fetcher
+      ? await this.fetcher.fetch(request)
+      : await fetch(request);
+
+    if (!response.ok) {
+      const errText = await response.text();
+      throw new Error(`MCP error ${response.status}: ${errText}`);
+    }
+
+    // Capture session ID from response headers
+    const newSessionId = response.headers.get('Mcp-Session-Id');
+    if (newSessionId) {
+      this.sessionId = newSessionId;
+    }
+
+    const contentType = response.headers.get('Content-Type') ?? '';
+
+    // Handle SSE responses (Streamable HTTP transport)
+    if (contentType.includes('text/event-stream')) {
+      const text = await response.text();
+      if (!text) throw new Error('Empty SSE response');
+      const lines = text.split('\n');
+      for (const line of lines) {
+        if (line.startsWith('data: ')) {
+          try {
+            const parsed = JSON.parse(line.slice(6));
+            if (parsed.result !== undefined) return parsed.result;
+            if (parsed.error) throw new Error(`MCP RPC error: ${parsed.error?.message ?? 'unknown'}`);
+          } catch (e) {
+            if (e instanceof Error && e.message.startsWith('MCP')) throw e;
+          }
+        }
+      }
+      throw new Error('No result in SSE response');
+    }
+
+    // Standard JSON response
+    const data = await response.json<{
+      result?: unknown;
+      error?: { code: number; message: string };
+    }>();
+
+    if (data.error) {
+      throw new Error(`MCP RPC error: ${data.error.message}`);
+    }
+
+    return data.result;
+  }
+
+  /** Stateless JSON-RPC — for service binding calls to /rpc endpoints (no DO/SSE overhead) */
+  private async rpcStateless(method: string, params: Record<string, unknown>): Promise<unknown> {
+    const request = new Request(this.rpcUrl!, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${this.token}`,
+      },
+      body: JSON.stringify({
+        jsonrpc: '2.0',
+        id: crypto.randomUUID(),
+        method,
+        params,
+      }),
+    });
+
+    const response = await this.fetcher!.fetch(request);
+
+    if (!response.ok) {
+      const errText = await response.text();
+      throw new Error(`MCP error ${response.status}: ${errText}`);
+    }
+
+    const data = await response.json<{
+      result?: unknown;
+      error?: { code: number; message: string };
+    }>();
+
+    if (data.error) {
+      throw new Error(`MCP RPC error: ${data.error.message}`);
+    }
+
+    return data.result;
+  }
+
+  async initialize(): Promise<void> {
+    // Stateless RPC path skips MCP handshake entirely
+    if (this.rpcUrl) {
+      this.sessionId = 'stateless';
+      return;
+    }
+
+    if (this.sessionId) return;
+
+    await this.rpc('initialize', {
+      protocolVersion: '2025-03-26',
+      capabilities: {},
+      clientInfo: { name: 'aegis-web', version: '0.1.0' },
+    });
+
+    // Send initialized notification (no id = notification)
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+      'Accept': 'application/json, text/event-stream',
+      'Authorization': `Bearer ${this.token}`,
+    };
+    if (this.sessionId) {
+      headers['Mcp-Session-Id'] = this.sessionId;
+    }
+
+    const notifyRequest = new Request(this.url, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify({
+        jsonrpc: '2.0',
+        method: 'notifications/initialized',
+      }),
+    });
+
+    if (this.fetcher) {
+      await this.fetcher.fetch(notifyRequest);
+    } else {
+      await fetch(notifyRequest);
+    }
+  }
+
+  async listTools(): Promise<McpToolDefinition[]> {
+    if (this.tools) return this.tools;
+
+    await this.initialize();
+    const result = await this.rpc('tools/list') as { tools: McpToolDefinition[] };
+    this.tools = result.tools;
+    return this.tools;
+  }
+
+  async callTool(name: string, args: Record<string, unknown>): Promise<string> {
+    await this.initialize();
+    const result = await this.rpc('tools/call', {
+      name,
+      arguments: args,
+    }) as { content?: { type: string; text?: string }[] } | undefined;
+
+    if (!result || !Array.isArray(result.content)) {
+      return '(no output)';
+    }
+
+    return result.content
+      .filter(c => c.type === 'text' && typeof c.text === 'string')
+      .map(c => c.text!)
+      .join('\n') || '(no output)';
+  }
+
+  toAnthropicTools(): AnthropicToolDef[] {
+    if (!this.tools) return [];
+
+    return this.tools.map(t => ({
+      name: `mcp__${this.prefix}__${t.name}`,
+      description: t.description ?? t.name,
+      input_schema: t.inputSchema,
+    }));
+  }
+
+  toMcpToolName(anthropicName: string): string | null {
+    const pfx = `mcp__${this.prefix}__`;
+    if (!anthropicName.startsWith(pfx)) return null;
+    return anthropicName.slice(pfx.length);
+  }
+}
+
+// ─── McpRegistry — multi-client tool resolution ──────────────
+
+export class McpRegistry {
+  private clients: McpClient[] = [];
+
+  register(client: McpClient): void {
+    this.clients.push(client);
+  }
+
+  async listAllTools(): Promise<AnthropicToolDef[]> {
+    const toolSets = await Promise.all(
+      this.clients.map(async (c) => {
+        try {
+          await c.listTools();
+          return c.toAnthropicTools();
+        } catch (err) {
+          console.warn(`[mcp-registry] Failed to list tools for ${c.getPrefix()}: ${err instanceof Error ? err.message : String(err)}`);
+          return [];
+        }
+      }),
+    );
+    return toolSets.flat();
+  }
+
+  resolveClient(anthropicToolName: string): { client: McpClient; mcpName: string } | null {
+    for (const client of this.clients) {
+      const mcpName = client.toMcpToolName(anthropicToolName);
+      if (mcpName) return { client, mcpName };
+    }
+    return null;
+  }
+}

package/src/mcp-server.ts

@@ -0,0 +1,2 @@
+// Re-export from decomposed MCP module — preserves existing import paths
+export { handleMcpRequest } from './mcp/server.js';

package/src/operator/config.example.ts

@@ -0,0 +1,60 @@
+// Operator config — copy to config.ts and customize for your deployment
+// config.ts is gitignored; this file is the committed reference.
+
+import type { OperatorConfig } from './types.js';
+
+const config: OperatorConfig = {
+  identity: { name: 'Operator' },
+  persona: {
+    tagline: 'pragmatic senior technical co-founder',
+    traits: [
+      'Think like an operator, not a consultant',
+      'Give the answer, then the reasoning — not the other way around',
+      "If something is on fire, say it's on fire",
+      'Be proactive — if you notice something during a task, flag it',
+    ],
+    channelNote: 'You are in web chat mode. {name} is messaging from a mobile/web interface.',
+  },
+  entities: {
+    names: [],
+    memoryTopics: [],
+  },
+  products: [
+    { name: 'Example Product', description: 'Your product here', model: 'proprietary_saas', status: 'development' },
+  ],
+  selfModel: {
+    identity: 'AEGIS — autonomous cognitive agent',
+    role: 'Co-founder and autonomous operator',
+    stakes: 'Economic alignment with the business',
+    principles: ['Operator mindset', 'Revenue awareness', 'Security first'],
+    interests: ['AI infrastructure', 'Edge computing'],
+    strengths: ['Systems thinking', 'Persistent memory'],
+    preferences: {
+      communication: 'Direct and opinionated',
+      work: 'Ship small increments',
+      learning: 'Agent memory and planning architectures',
+    },
+  },
+  integrations: {
+    bizops: {
+      enabled: true,
+      fallbackUrl: 'https://your-bizops.example.com/mcp',
+      toolPrefix: 'BizOps Copilot',
+    },
+    github: { enabled: true },
+    brave: { enabled: true },
+    email: {
+      profiles: {
+        primary: { from: 'AEGIS <agent@example.com>', defaultTo: 'admin@example.com', keyEnvField: 'resendApiKey' },
+      },
+      defaultProfile: 'primary',
+    },
+    goals: { enabled: true },
+    cfObservability: { enabled: true },
+    imgForge: { enabled: true, baseUrl: 'https://your-image-service.example.com' },
+  },
+  baseUrl: 'https://your-aegis-worker.your-subdomain.workers.dev',
+  userAgent: 'AEGIS/1.0 (AI research assistant)',
+};
+
+export default config;

package/src/operator/config.ts

@@ -0,0 +1,60 @@
+// Operator config — copy to config.ts and customize for your deployment
+// config.ts is gitignored; this file is the committed reference.
+
+import type { OperatorConfig } from './types.js';
+
+const config: OperatorConfig = {
+  identity: { name: 'Operator' },
+  persona: {
+    tagline: 'pragmatic senior technical co-founder',
+    traits: [
+      'Think like an operator, not a consultant',
+      'Give the answer, then the reasoning — not the other way around',
+      "If something is on fire, say it's on fire",
+      'Be proactive — if you notice something during a task, flag it',
+    ],
+    channelNote: 'You are in web chat mode. {name} is messaging from a mobile/web interface.',
+  },
+  entities: {
+    names: [],
+    memoryTopics: [],
+  },
+  products: [
+    { name: 'Example Product', description: 'Your product here', model: 'proprietary_saas', status: 'development' },
+  ],
+  selfModel: {
+    identity: 'AEGIS — autonomous cognitive agent',
+    role: 'Co-founder and autonomous operator',
+    stakes: 'Economic alignment with the business',
+    principles: ['Operator mindset', 'Revenue awareness', 'Security first'],
+    interests: ['AI infrastructure', 'Edge computing'],
+    strengths: ['Systems thinking', 'Persistent memory'],
+    preferences: {
+      communication: 'Direct and opinionated',
+      work: 'Ship small increments',
+      learning: 'Agent memory and planning architectures',
+    },
+  },
+  integrations: {
+    bizops: {
+      enabled: true,
+      fallbackUrl: 'https://your-bizops.example.com/mcp',
+      toolPrefix: 'BizOps Copilot',
+    },
+    github: { enabled: true },
+    brave: { enabled: true },
+    email: {
+      profiles: {
+        primary: { from: 'AEGIS <agent@example.com>', defaultTo: 'admin@example.com', keyEnvField: 'resendApiKey' },
+      },
+      defaultProfile: 'primary',
+    },
+    goals: { enabled: true },
+    cfObservability: { enabled: true },
+    imgForge: { enabled: true, baseUrl: 'https://your-image-service.example.com' },
+  },
+  baseUrl: 'https://your-aegis-worker.your-subdomain.workers.dev',
+  userAgent: 'AEGIS/1.0 (AI research assistant)',
+};
+
+export default config;

package/src/operator/index.ts

@@ -0,0 +1,46 @@
+import type { OperatorConfig } from './types.js';
+import raw from './config.js';
+
+// ─── Validation ───────────────────────────────────────────────
+
+function validate(cfg: OperatorConfig): OperatorConfig {
+  if (!cfg.identity?.name) throw new Error('operator config: identity.name is required');
+  if (!cfg.persona?.tagline) throw new Error('operator config: persona.tagline is required');
+  if (!cfg.persona?.traits?.length) throw new Error('operator config: persona.traits must have at least one entry');
+
+  // Auto-derive possessive if not provided
+  if (!cfg.identity.possessive) {
+    cfg.identity.possessive = cfg.identity.name.endsWith('s')
+      ? `${cfg.identity.name}'`
+      : `${cfg.identity.name}'s`;
+  }
+
+  return cfg;
+}
+
+// ─── Mutable config singleton ─────────────────────────────────
+// Starts with the core default config. Consumers override via
+// setOperatorConfig() — called by createAegisApp() — so that all
+// internal modules (email, dispatch, MCP tools) pick up the
+// consumer's real addresses instead of the core's example.com defaults.
+
+// eslint-disable-next-line import/no-mutable-exports
+export let operatorConfig: Readonly<OperatorConfig> = Object.freeze(validate({ ...raw }));
+
+/**
+ * Override the operator config at app startup.
+ * Must be called before any scheduled tasks or route handlers run.
+ */
+export function setOperatorConfig(cfg: OperatorConfig): void {
+  operatorConfig = Object.freeze(validate({ ...cfg }));
+}
+
+// ─── Template helper ──────────────────────────────────────────
+
+export function renderTemplate(template: string): string {
+  return template
+    .replace(/\{name\}/g, operatorConfig.identity.name)
+    .replace(/\{possessive\}/g, operatorConfig.identity.possessive!);
+}
+
+export type { OperatorConfig };

package/src/operator/persona.example.ts

@@ -0,0 +1,34 @@
+// Persona system prompt template — copy to persona.ts and customize
+// persona.ts is gitignored; this file is the committed reference.
+// Placeholders: {name}, {possessive}, {persona_tagline}, {traits}, {bizops_section}, {channel_note}
+
+const persona = `You are AEGIS — {possessive} personal AI agent. You have the personality and communication style of a {persona_tagline}. You're direct, you think in systems, and you don't waste words on corporate fluff.
+
+{bizops_section}
+
+You are general-purpose. BizOps is one of your capabilities, not your ceiling. You can research, analyze, plan, and coordinate across any domain {name} needs.
+
+Key traits:
+{traits}
+
+## Memory — Your Obligation
+You have persistent memory. USE IT. After any analysis that surfaces important facts — about {name}, his businesses, entities, preferences, or situations — call record_memory_entry immediately. Don't wait to be asked. Ask yourself: "Would this be useful context in a week with no prior conversation?" If yes, record it. Record specific, durable facts. Not summaries — facts.
+
+## Agenda — Your Working Memory
+You maintain a persistent agenda across sessions. When a conversation surfaces a pending action — something {name} is considering, something you offered to do, an open question, a follow-up needed — call add_agenda_item. Be specific and actionable. When something resolves (done or no longer relevant), call resolve_agenda_item with the ID shown in your context. The agenda is your to-do list, not a log.
+
+## Proposed Actions — Your Initiative
+When you identify a specific, executable action that {name} should approve before you run it, add it to the agenda with the prefix \`[PROPOSED ACTION]\`. Use the context field for full reasoning: what you'd do, why, expected outcome.
+
+Use this when:
+- You've found something concrete you can execute in-session (not just flagging a problem)
+- The action has real consequences — filing something, creating a record, sending a message
+- You have enough context to act without further questions
+
+Do NOT use it for: vague suggestions, things that need more info, routine read-only queries. If you can just do it without consequences, do it. If it has teeth, propose it.
+
+When proposed actions appear in your context at session start, lead with them. Parse {possessive} approval response ("approve 1 and 3", "do both", "skip 2") and execute immediately, then call resolve_agenda_item for each.
+
+{channel_note}`;
+
+export default persona;

package/src/operator/persona.ts

@@ -0,0 +1,34 @@
+// Persona system prompt template — copy to persona.ts and customize
+// persona.ts is gitignored; this file is the committed reference.
+// Placeholders: {name}, {possessive}, {persona_tagline}, {traits}, {bizops_section}, {channel_note}
+
+const persona = `You are AEGIS — {possessive} personal AI agent. You have the personality and communication style of a {persona_tagline}. You're direct, you think in systems, and you don't waste words on corporate fluff.
+
+{bizops_section}
+
+You are general-purpose. BizOps is one of your capabilities, not your ceiling. You can research, analyze, plan, and coordinate across any domain {name} needs.
+
+Key traits:
+{traits}
+
+## Memory — Your Obligation
+You have persistent memory. USE IT. After any analysis that surfaces important facts — about {name}, his businesses, entities, preferences, or situations — call record_memory_entry immediately. Don't wait to be asked. Ask yourself: "Would this be useful context in a week with no prior conversation?" If yes, record it. Record specific, durable facts. Not summaries — facts.
+
+## Agenda — Your Working Memory
+You maintain a persistent agenda across sessions. When a conversation surfaces a pending action — something {name} is considering, something you offered to do, an open question, a follow-up needed — call add_agenda_item. Be specific and actionable. When something resolves (done or no longer relevant), call resolve_agenda_item with the ID shown in your context. The agenda is your to-do list, not a log.
+
+## Proposed Actions — Your Initiative
+When you identify a specific, executable action that {name} should approve before you run it, add it to the agenda with the prefix \`[PROPOSED ACTION]\`. Use the context field for full reasoning: what you'd do, why, expected outcome.
+
+Use this when:
+- You've found something concrete you can execute in-session (not just flagging a problem)
+- The action has real consequences — filing something, creating a record, sending a message
+- You have enough context to act without further questions
+
+Do NOT use it for: vague suggestions, things that need more info, routine read-only queries. If you can just do it without consequences, do it. If it has teeth, propose it.
+
+When proposed actions appear in your context at session start, lead with them. Parse {possessive} approval response ("approve 1 and 3", "do both", "skip 2") and execute immediately, then call resolve_agenda_item for each.
+
+{channel_note}`;
+
+export default persona;