@eagi/sdk 0.1.0

package/src/domain/types.ts

@@ -0,0 +1,112 @@
+import type { ZodType, z } from 'zod';
+import type { Identity, DomainManifest, ToolResult, HookContextMap, FilterDataMap } from '../hooks/types';
+export type { Identity, DomainManifest, ToolResult };
+import type { HookEngine } from '../hooks/engine';
+
+export interface ToolContext {
+  identity: Identity;
+  domain: DomainManifest;
+  hooks: HookEngine;
+  logger: any; // Will be AuditLogger
+  services: Record<string, any>; // Injected domain services
+  tools: {
+    call: <T = unknown>(toolName: string, input: Record<string, unknown>) => Promise<T>;
+  };
+  resources: {
+    get: <T = unknown>(uri: string) => Promise<T>;
+  };
+}
+
+export interface ResourceContext {
+  identity: Identity;
+  domain: DomainManifest;
+  hooks: HookEngine;
+  logger: any;
+  services: Record<string, any>;
+}
+
+export interface ToolDefinition<TInput extends ZodType = ZodType> {
+  name: string;
+  description: string;
+  input: TInput;
+  auth?: { roles: string[] };
+  audit?: boolean | { redactFields?: string[] };
+  approval?: {
+    required: boolean;
+    message: string | ((input: z.infer<TInput>) => string);
+    timeout?: string;
+  };
+  handler: (input: z.infer<TInput>, ctx: ToolContext) => Promise<ToolResult>;
+}
+
+type ExtractParams<T extends string> =
+  T extends `${string}{${infer Param}}${infer Rest}`
+    ? Param | ExtractParams<Rest>
+    : never;
+
+export interface ResourceDefinition<TUri extends string = string> {
+  uri: TUri;
+  name: string;
+  description: string;
+  mimeType: string;
+  auth?: { roles: string[] };
+  handler: (
+    params: Record<ExtractParams<TUri>, string>,
+    ctx: ResourceContext
+  ) => Promise<string>;
+}
+
+export interface PromptMessage {
+  role: 'user' | 'assistant';
+  content: { type: 'text'; text: string } | { type: 'image'; data: string; mimeType: string };
+}
+
+export interface PromptDefinition<TArgs extends ZodType = ZodType> {
+  name: string;
+  description: string;
+  arguments: TArgs;
+  handler: (args: z.infer<TArgs>, ctx: ResourceContext) => Promise<{ messages: PromptMessage[] }>;
+}
+
+export interface DomainConfig {
+  env: Record<string, string | undefined>;
+}
+
+type ResolvedDeps<TDeps extends readonly string[], TServiceMap> = {
+  [K in TDeps[number]]: K extends keyof TServiceMap ? TServiceMap[K] : never;
+};
+
+export interface ServiceDefinition<
+  TName extends string = string,
+  TDeps extends readonly string[] = readonly string[],
+  TInstance = any
+> {
+  name: TName;
+  deps?: TDeps;
+  factory: (config: DomainConfig, deps: ResolvedDeps<TDeps, any>) => Promise<TInstance>;
+  dispose?: (instance: TInstance) => Promise<void>;
+}
+
+export interface EagiConfig {
+  name: string;
+  version: string;
+  gateway?: {
+    port: number;
+    auth?: {
+      provider: string;
+      issuer: string;
+      audience: string;
+    };
+  };
+  audit?: {
+    hashChain?: boolean;
+    output?: 'file' | 'stdout';
+    redactInputs?: boolean;
+  };
+  hooks?: {
+    [K in keyof HookContextMap]?: (ctx: HookContextMap[K]) => Promise<void> | void;
+  } & {
+    [K in keyof FilterDataMap]?: (data: FilterDataMap[K], ctx?: any) => Promise<FilterDataMap[K]> | FilterDataMap[K];
+  };
+  domains?: Record<string, { enabled: boolean }>;
+}

package/src/hooks/engine.ts

@@ -0,0 +1,38 @@
+import type { ActionHandler, FilterHandler, HookContextMap, FilterDataMap } from './types';
+
+export class HookEngine {
+  private actions: Map<string, Array<{ handler: ActionHandler<any>; priority: number }>> = new Map();
+  private filters: Map<string, Array<{ handler: FilterHandler<any>; priority: number }>> = new Map();
+
+  addAction<K extends keyof HookContextMap>(hookName: K, handler: ActionHandler<K>, priority: number = 10): void {
+    if (!this.actions.has(hookName)) {
+      this.actions.set(hookName, []);
+    }
+    this.actions.get(hookName)!.push({ handler, priority });
+    this.actions.get(hookName)!.sort((a, b) => a.priority - b.priority);
+  }
+
+  addFilter<K extends keyof FilterDataMap>(hookName: K, handler: FilterHandler<K>, priority: number = 10): void {
+    if (!this.filters.has(hookName)) {
+      this.filters.set(hookName, []);
+    }
+    this.filters.get(hookName)!.push({ handler, priority });
+    this.filters.get(hookName)!.sort((a, b) => a.priority - b.priority);
+  }
+
+  async doAction<K extends keyof HookContextMap>(hookName: K, context: HookContextMap[K]): Promise<void> {
+    const handlers = this.actions.get(hookName) || [];
+    for (const { handler } of handlers) {
+      await handler(context);
+    }
+  }
+
+  async applyFilters<K extends keyof FilterDataMap>(hookName: K, data: FilterDataMap[K], context?: any): Promise<FilterDataMap[K]> {
+    let result = data;
+    const handlers = this.filters.get(hookName) || [];
+    for (const { handler } of handlers) {
+      result = await handler(result, context);
+    }
+    return result;
+  }
+}

package/src/hooks/index.ts

@@ -0,0 +1,2 @@
+export * from './types';
+export * from './engine';

package/src/hooks/types.ts

@@ -0,0 +1,45 @@
+export interface Identity {
+  userId: string;
+  role: string;
+  email?: string;
+  claims: Record<string, unknown>;
+}
+
+export interface DomainManifest {
+  name: string;
+  version: string;
+  description?: string;
+  dependencies?: string[];
+  roles?: Record<string, { description?: string; includes?: string[] }>;
+  triggers?: any[];
+}
+
+export interface ToolResult {
+  content: Array<{ type: 'text'; text: string } | { type: 'image'; data: string; mimeType: string }>;
+  isError?: boolean;
+}
+
+export interface HookContextMap {
+  'before:tool:call': { toolName: string; input: unknown; identity: Identity; domain: DomainManifest };
+  'after:tool:call': { toolName: string; input: unknown; output: ToolResult; identity: Identity; duration: number };
+  'on:tool:error': { toolName: string; input: unknown; error: Error; identity: Identity };
+  'before:resource:read': { uri: string; identity: Identity };
+  'after:resource:read': { uri: string; data: string; identity: Identity };
+  'on:server:start': { config: any; domains: DomainManifest[] };
+  'on:server:stop': { uptime: number; requestCount: number };
+  'on:domain:load': { domain: DomainManifest };
+}
+
+export interface FilterDataMap {
+  'filter:tool:input': unknown;
+  'filter:tool:output': ToolResult;
+  'filter:resource:data': string;
+  'filter:tools:list': any[]; // Will be ToolDefinition[]
+  'filter:audit:entry': any; // Will be AuditEntry
+}
+
+export type ActionHandler<K extends keyof HookContextMap> = (ctx: HookContextMap[K]) => Promise<void> | void;
+export type FilterHandler<K extends keyof FilterDataMap> = (
+  data: FilterDataMap[K],
+  ctx?: any
+) => Promise<FilterDataMap[K]> | FilterDataMap[K];

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './hooks';
+export * from './domain';
+export * from './define';
+export * from './server';
+export * from './middleware';

package/src/middleware/approval.ts

@@ -0,0 +1,30 @@
+import type { ToolDefinition, ToolContext } from '../domain/types';
+
+export class ApprovalRequiredError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ApprovalRequiredError';
+  }
+}
+
+export async function approvalMiddleware(
+  tool: ToolDefinition,
+  input: any,
+  ctx: ToolContext
+): Promise<void> {
+  if (!tool.approval || !tool.approval.required) return;
+
+  // In a real MRTR (Multi Round-Trip Request) implementation, we would check for an approval token in the request.
+  // For now, if the token is missing, we throw an ApprovalRequiredError which the proxy/gateway converts
+  // to the appropriate MCP MRTR response.
+
+  const hasApprovalToken = false; // Mock
+
+  if (!hasApprovalToken) {
+    const message = typeof tool.approval.message === 'function' 
+      ? tool.approval.message(input)
+      : tool.approval.message;
+
+    throw new ApprovalRequiredError(message);
+  }
+}

package/src/middleware/audit.ts

@@ -0,0 +1,36 @@
+import type { ToolDefinition, ToolContext, ToolResult } from '../domain/types';
+
+export async function auditMiddleware(
+  tool: ToolDefinition,
+  input: any,
+  output: ToolResult,
+  ctx: ToolContext
+): Promise<void> {
+  if (!tool.audit) return;
+
+  // Redaction logic based on tool.audit config
+  let auditedInput = { ...input };
+  if (typeof tool.audit === 'object' && tool.audit.redactFields) {
+    for (const field of tool.audit.redactFields) {
+      if (field in auditedInput) {
+        auditedInput[field] = '[REDACTED]';
+      }
+    }
+  }
+
+  const entry = {
+    timestamp: new Date().toISOString(),
+    tool: tool.name,
+    identity: ctx.identity.userId,
+    role: ctx.identity.role,
+    input: auditedInput,
+    success: !output.isError
+  };
+
+  const finalEntry = await ctx.hooks.applyFilters('filter:audit:entry', entry, ctx);
+  
+  // Log it using the injected logger (which could be the gateway stream or local file)
+  if (ctx.logger) {
+    ctx.logger.info('AUDIT', finalEntry);
+  }
+}

package/src/middleware/auth.ts

@@ -0,0 +1,30 @@
+import type { ToolDefinition, ToolContext } from '../domain/types';
+
+export class AuthError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'AuthError';
+  }
+}
+
+export async function authMiddleware(tool: ToolDefinition, ctx: ToolContext): Promise<void> {
+  if (!tool.auth || !tool.auth.roles) return;
+  
+  const userRole = ctx.identity.role;
+  const domainRoles = ctx.domain.roles || {};
+  
+  const allowedRoles = new Set(tool.auth.roles);
+  
+  // Basic RBAC checking
+  if (allowedRoles.has(userRole)) return;
+
+  // Check if user role includes any allowed role
+  const userRoleDef = domainRoles[userRole];
+  if (userRoleDef && userRoleDef.includes) {
+    for (const included of userRoleDef.includes) {
+      if (allowedRoles.has(included)) return;
+    }
+  }
+
+  throw new AuthError(`User role '${userRole}' is not authorized to execute tool '${tool.name}'`);
+}

package/src/middleware/index.ts

@@ -0,0 +1,3 @@
+export * from './auth';
+export * from './audit';
+export * from './approval';

package/src/server/builder.ts

@@ -0,0 +1,185 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import {
+  ListToolsRequestSchema,
+  CallToolRequestSchema,
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema,
+  ListPromptsRequestSchema,
+  GetPromptRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import type { EagiConfig, DomainRegistry, HookEngine } from '../index';
+import { authMiddleware } from '../middleware/auth';
+import { auditMiddleware } from '../middleware/audit';
+import { approvalMiddleware } from '../middleware/approval';
+
+export class EagiServerBuilder {
+  constructor(
+    private config: EagiConfig,
+    private registry: DomainRegistry,
+    private hooks: HookEngine,
+    private servicesMap: Record<string, any>
+  ) {}
+
+  build(): Server {
+    const server = new Server(
+      { name: this.config.name, version: this.config.version },
+      { capabilities: { tools: {}, resources: {}, prompts: {} } }
+    );
+
+    this.registerTools(server);
+    this.registerResources(server);
+    this.registerPrompts(server);
+
+    return server;
+  }
+
+  private registerTools(server: Server) {
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+      // Identity projection happens at the gateway level, or here via middleware if local.
+      // For now, we return all tools.
+      const tools = this.registry.getAllTools().map(t => ({
+        name: t.name,
+        description: t.description,
+        inputSchema: zodToJsonSchema(t.input) as any,
+      }));
+      return { tools };
+    });
+
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+      const { name, arguments: args } = request.params;
+      const tool = this.registry.getAllTools().find(t => t.name === name);
+      
+      if (!tool) {
+        throw new Error(`Tool not found: ${name}`);
+      }
+
+      // Mock identity for now, normally extracted from request context (HTTP header via proxy)
+      const identity = { userId: 'system', role: 'admin', claims: {} };
+      const domain = this.registry.getAll().find(d => d.tools.includes(tool))!.manifest;
+
+      const ctx = {
+        identity,
+        domain,
+        hooks: this.hooks,
+        logger: console, // Temporary logger
+        services: this.servicesMap,
+        tools: {
+          call: async (toolName: string, input: any) => {
+            // Internal call logic
+            return null as any;
+          }
+        },
+        resources: {
+          get: async (uri: string) => {
+            return null as any;
+          }
+        }
+      };
+
+      let input = await this.hooks.applyFilters('filter:tool:input', args, ctx);
+      
+      // Validation
+      const parsedInput = tool.input.parse(input);
+
+      await this.hooks.doAction('before:tool:call', { toolName: name, input: parsedInput, identity, domain });
+
+      if (tool.auth) await authMiddleware(tool, ctx);
+      if (tool.approval) await approvalMiddleware(tool, parsedInput, ctx);
+
+      const startTime = Date.now();
+      let output = await tool.handler(parsedInput, ctx);
+      const duration = Date.now() - startTime;
+
+      output = await this.hooks.applyFilters('filter:tool:output', output, ctx);
+
+      await this.hooks.doAction('after:tool:call', { toolName: name, input: parsedInput, output, identity, duration });
+
+      if (tool.audit) await auditMiddleware(tool, parsedInput, output, ctx);
+
+      return output as any;
+    });
+  }
+
+  private registerResources(server: Server) {
+    server.setRequestHandler(ListResourcesRequestSchema, async () => {
+      const resources = this.registry.getAllResources().map(r => ({
+        uri: r.uri,
+        name: r.name,
+        description: r.description,
+        mimeType: r.mimeType,
+      }));
+      return { resources };
+    });
+
+    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+      const { uri } = request.params;
+      const resource = this.registry.getAllResources().find(r => r.uri === uri); // Naive matching for now
+
+      if (!resource) {
+        throw new Error(`Resource not found: ${uri}`);
+      }
+
+      const identity = { userId: 'system', role: 'admin', claims: {} };
+      const domain = this.registry.getAll().find(d => d.resources.includes(resource))!.manifest;
+      
+      const ctx = {
+        identity,
+        domain,
+        hooks: this.hooks,
+        logger: console,
+        services: this.servicesMap,
+      };
+
+      await this.hooks.doAction('before:resource:read', { uri, identity });
+      
+      let data = await resource.handler({} as any, ctx); // Naive param extraction
+      data = await this.hooks.applyFilters('filter:resource:data', data, ctx);
+
+      await this.hooks.doAction('after:resource:read', { uri, data, identity });
+
+      return {
+        contents: [{ uri, mimeType: resource.mimeType, text: data }]
+      };
+    });
+  }
+
+  private registerPrompts(server: Server) {
+    server.setRequestHandler(ListPromptsRequestSchema, async () => {
+      const prompts = this.registry.getAllPrompts().map(p => ({
+        name: p.name,
+        description: p.description,
+        arguments: [] // Should extract from Zod schema
+      }));
+      return { prompts };
+    });
+
+    server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+      const { name, arguments: args } = request.params;
+      const prompt = this.registry.getAllPrompts().find(p => p.name === name);
+
+      if (!prompt) {
+        throw new Error(`Prompt not found: ${name}`);
+      }
+
+      const identity = { userId: 'system', role: 'admin', claims: {} };
+      const domain = this.registry.getAll().find(d => d.prompts.includes(prompt))!.manifest;
+      
+      const ctx = {
+        identity,
+        domain,
+        hooks: this.hooks,
+        logger: console,
+        services: this.servicesMap,
+      };
+
+      const parsedArgs = prompt.arguments.parse(args);
+      const result = await prompt.handler(parsedArgs, ctx);
+
+      return {
+        description: prompt.description,
+        messages: result.messages as any
+      };
+    });
+  }
+}

package/src/server/index.ts

@@ -0,0 +1,2 @@
+export * from './builder';
+export * from './lifecycle';

package/src/server/lifecycle.ts

@@ -0,0 +1,73 @@
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { EagiServerBuilder } from './builder';
+import { DomainRegistry, DomainLoader, sortServices } from '../domain';
+import { HookEngine } from '../hooks';
+import type { EagiConfig } from '../domain/types';
+
+export class EagiRunner {
+  private registry = new DomainRegistry();
+  private hooks = new HookEngine();
+  private servicesMap: Record<string, any> = {};
+
+  constructor(private config: EagiConfig) {}
+
+  async start(domainDirs: string[]) {
+    // 1. Register global hooks from config
+    if (this.config.hooks) {
+      for (const [hookName, handler] of Object.entries(this.config.hooks)) {
+        if (hookName.startsWith('filter:')) {
+          this.hooks.addFilter(hookName as any, handler as any);
+        } else {
+          this.hooks.addAction(hookName as any, handler as any);
+        }
+      }
+    }
+
+    // 2. Load domains
+    const loader = new DomainLoader();
+    for (const dir of domainDirs) {
+      const domain = await loader.load(dir);
+      this.registry.register(domain);
+      
+      // Load domain-specific hooks
+      if (domain.hooksModule && domain.hooksModule.default) {
+        const domainHooks = domain.hooksModule.default;
+        for (const [hookName, handler] of Object.entries(domainHooks)) {
+          if (hookName.startsWith('filter:')) {
+            this.hooks.addFilter(hookName as any, handler as any);
+          } else {
+            this.hooks.addAction(hookName as any, handler as any);
+          }
+        }
+      }
+
+      await this.hooks.doAction('on:domain:load', { domain: domain.manifest });
+    }
+
+    // 3. Initialize Services (Topological Sort)
+    const allServices = this.registry.getAll().flatMap(d => d.services);
+    const sortedServices = sortServices(allServices);
+
+    for (const service of sortedServices) {
+      const deps: Record<string, any> = {};
+      if (service.deps) {
+        for (const dep of service.deps) {
+          deps[dep] = this.servicesMap[dep];
+        }
+      }
+      // Initialize the service factory
+      const instance = await service.factory({ env: process.env as any }, deps);
+      this.servicesMap[service.name] = instance;
+    }
+
+    // 4. Build MCP Server
+    const builder = new EagiServerBuilder(this.config, this.registry, this.hooks, this.servicesMap);
+    const server = builder.build();
+
+    // 5. Connect Transport
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+
+    await this.hooks.doAction('on:server:start', { config: this.config, domains: this.registry.getAll().map(d => d.manifest) });
+  }
+}

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}