beddel 0.2.1 → 0.2.3

package/src/runtime/index.ts

@@ -0,0 +1,31 @@
+/**
+ * Runtime Module - Server-only exports
+ *
+ * This module provides the declarative agent runtime and workflow execution.
+ * All exports in this module are server-only.
+ */
+
+// Main runtime exports
+export { DeclarativeAgentInterpreter, declarativeInterpreter } from './declarativeAgentRuntime';
+export type { YamlAgentDefinition, YamlAgentInterpreterOptions, YamlExecutionResult } from './declarativeAgentRuntime';
+
+// Workflow executor exports
+export {
+  executeWorkflowStep,
+  getAvailableStepTypes,
+  isStepTypeSupported,
+  // Individual handlers for direct use
+  executeJokeHandler,
+  executeTranslationHandler,
+  executeImageHandler,
+  executeMcpToolHandler,
+  executeVectorizeHandler,
+  executeChromaDBHandler,
+  executeGitMcpHandler,
+  executeRagHandler,
+  executeChatHandler,
+} from './workflowExecutor';
+
+// Schema compiler exports
+export { DeclarativeSchemaCompiler, DeclarativeSchemaValidationError } from './schemaCompiler';
+export type { DeclarativeSchemaPhase } from './schemaCompiler';

package/src/runtime/workflowExecutor.ts

@@ -0,0 +1,94 @@
+import 'server-only';
+
+/**
+ * Workflow Executor - Server-only workflow step execution
+ * Delegates to individual agent handlers based on step type
+ */
+
+import type { ExecutionContext } from '../types/executionContext';
+import type { WorkflowStepType } from '../shared/types/agent.types';
+
+// Import handlers from each agent
+import { executeJokeHandler } from '../agents/joker/joker.handler';
+import { executeTranslationHandler } from '../agents/translator/translator.handler';
+import { executeImageHandler } from '../agents/image/image.handler';
+import { executeMcpToolHandler } from '../agents/mcp-tool/mcp-tool.handler';
+import { executeVectorizeHandler } from '../agents/gemini-vectorize/gemini-vectorize.handler';
+import { executeChromaDBHandler } from '../agents/chromadb/chromadb.handler';
+import { executeGitMcpHandler } from '../agents/gitmcp/gitmcp.handler';
+import { executeRagHandler } from '../agents/rag/rag.handler';
+import { executeChatHandler } from '../agents/chat/chat.handler';
+
+/**
+ * Handler function type - uses any for params to allow flexible handler signatures
+ */
+type HandlerFunction = (
+  params: any,
+  props: Record<string, string>,
+  context: ExecutionContext
+) => Promise<unknown>;
+
+/**
+ * Map of workflow step types to their handlers
+ * Maps both legacy (Portuguese) and new (English) step type names
+ */
+const handlerMap: Record<string, HandlerFunction> = {
+  // English step types (preferred)
+  'joke': executeJokeHandler,
+  'translation': executeTranslationHandler,
+  'image': executeImageHandler,
+  'mcp-tool': executeMcpToolHandler,
+  'vectorize': executeVectorizeHandler,
+  'chromadb': executeChromaDBHandler,
+  'gitmcp': executeGitMcpHandler,
+  'rag': executeRagHandler,
+  'chat': executeChatHandler,
+  // Legacy step types (for backward compatibility)
+  'genkit-joke': executeJokeHandler,
+  'genkit-translation': executeTranslationHandler,
+  'genkit-image': executeImageHandler,
+  'gemini-vectorize': executeVectorizeHandler,
+};
+
+/**
+ * Execute a workflow step by delegating to the appropriate handler
+ */
+export async function executeWorkflowStep(
+  stepType: WorkflowStepType | string,
+  params: Record<string, unknown>,
+  props: Record<string, string>,
+  context: ExecutionContext
+): Promise<unknown> {
+  const handler = handlerMap[stepType];
+  if (!handler) {
+    throw new Error(`Unknown workflow step type: ${stepType}`);
+  }
+  return handler(params, props, context);
+}
+
+/**
+ * Get all available workflow step types
+ */
+export function getAvailableStepTypes(): string[] {
+  return Object.keys(handlerMap);
+}
+
+/**
+ * Check if a step type is supported
+ */
+export function isStepTypeSupported(stepType: string): boolean {
+  return stepType in handlerMap;
+}
+
+// Export individual handlers for direct use
+export {
+  executeJokeHandler,
+  executeTranslationHandler,
+  executeImageHandler,
+  executeMcpToolHandler,
+  executeVectorizeHandler,
+  executeChromaDBHandler,
+  executeGitMcpHandler,
+  executeRagHandler,
+  executeChatHandler,
+};

package/src/server/api/graphql.ts

@@ -2,7 +2,9 @@
  * GraphQL helpers used by the /api/graphql route.
  */
 
-import { agentRegistry } from "../../agents/agentRegistry";
+import { GraphQLError, GraphQLScalarType, Kind, type ValueNode } from "graphql";
+import { createSchema, createYoga } from "graphql-yoga";
+import { agentRegistry } from "../../agents/registry";
 import {
   getClientByApiKey,
   getEndpointByName,
@@ -39,6 +41,39 @@ export function getGraphQLSchema(): string {
   return schema;
 }
 
+const parseJsonLiteral = (ast: ValueNode): unknown => {
+  switch (ast.kind) {
+    case Kind.STRING:
+    case Kind.BOOLEAN:
+      return ast.value;
+    case Kind.INT:
+      return parseInt(ast.value, 10);
+    case Kind.FLOAT:
+      return parseFloat(ast.value);
+    case Kind.OBJECT: {
+      const value: Record<string, any> = {};
+      for (const field of ast.fields) {
+        value[field.name.value] = parseJsonLiteral(field.value);
+      }
+      return value;
+    }
+    case Kind.LIST:
+      return ast.values.map(parseJsonLiteral);
+    case Kind.NULL:
+      return null;
+    default:
+      return null;
+  }
+};
+
+const jsonScalar = new GraphQLScalarType({
+  name: "JSON",
+  description: "Arbitrary JSON value",
+  serialize: (value: unknown) => value,
+  parseValue: (value: unknown) => value,
+  parseLiteral: (ast: ValueNode) => parseJsonLiteral(ast),
+});
+
 export async function executeRegisteredMethod(
   input: ExecuteMethodInput,
   clientId: string
@@ -164,86 +199,86 @@ export async function executeRegisteredMethod(
   }
 }
 
-export async function handleGraphQLPost(request: Request) {
-  try {
-    let clientId: string;
-    const authHeader = request.headers.get("authorization");
+async function resolveClientId(request: Request): Promise<string> {
+  const authHeader = request.headers.get("authorization");
 
-    if (authHeader && authHeader.startsWith("Bearer ")) {
-      const apiKey = authHeader.substring(7);
-      if (!isValidApiKey(apiKey)) {
-        throw new AuthenticationError("Invalid API key format");
-      }
-      const client = await getClientByApiKey(apiKey);
-      if (!client) throw new AuthenticationError("Invalid API key");
-      const rateLimitOk = await checkRateLimit(client.id, client.rateLimit);
-      if (!rateLimitOk) throw new RateLimitError("Rate limit exceeded.");
-      clientId = client.id;
-    } else if (request.headers.get("x-admin-tenant") === "true") {
-      clientId = "admin_tenant";
-    } else {
-      throw new AuthenticationError(
-        "Missing or invalid authorization header"
-      );
+  if (authHeader && authHeader.startsWith("Bearer ")) {
+    const apiKey = authHeader.substring(7);
+    if (!isValidApiKey(apiKey)) {
+      throw new AuthenticationError("Invalid API key format");
     }
+    const client = await getClientByApiKey(apiKey);
+    if (!client) throw new AuthenticationError("Invalid API key");
+    const rateLimitOk = await checkRateLimit(client.id, client.rateLimit);
+    if (!rateLimitOk) throw new RateLimitError("Rate limit exceeded.");
+    return client.id;
+  }
 
-    const body = await request.json();
-    if (!body.query) {
-      throw new ValidationError("Missing query in request body");
-    }
+  if (request.headers.get("x-admin-tenant") === "true") {
+    return "admin_tenant";
+  }
 
-    if (body.query && body.query.includes("executeMethod")) {
-      if (!body.variables || !body.variables.methodName) {
-        throw new ValidationError(
-          "Missing 'variables' or 'methodName' in request body"
-        );
-      }
+  throw new AuthenticationError("Missing or invalid authorization header");
+}
 
-      const result = await executeRegisteredMethod(
-        {
-          methodName: body.variables.methodName,
-          params: body.variables.params || {},
-          props: body.variables.props || {},
-        },
-        clientId
-      );
-      return Response.json({ data: { executeMethod: result } });
-    }
+function toGraphQLError(error: unknown): GraphQLError {
+  const message = error instanceof Error ? error.message : "Internal server error";
+  let code = "INTERNAL_SERVER_ERROR";
 
-    return Response.json(
-      { errors: [{ message: "Unsupported operation" }] },
-      { status: 400 }
-    );
-  } catch (error) {
-    const status =
-      error instanceof AuthenticationError
-        ? 401
-        : error instanceof RateLimitError
-        ? 429
-        : error instanceof ValidationError
-        ? 400
-        : error instanceof NotFoundError
-        ? 404
-        : 500;
-    return Response.json(
-      {
-        errors: [
-          {
-            message:
-              error instanceof Error ? error.message : "Internal server error",
-          },
-        ],
-      },
-      { status }
-    );
+  if (error instanceof AuthenticationError) {
+    code = "UNAUTHENTICATED";
+  } else if (error instanceof RateLimitError) {
+    code = "RATE_LIMITED";
+  } else if (error instanceof ValidationError) {
+    code = "BAD_USER_INPUT";
+  } else if (error instanceof NotFoundError) {
+    code = "NOT_FOUND";
   }
+
+  return new GraphQLError(message, { extensions: { code } });
+}
+
+const yoga = createYoga({
+  schema: createSchema({
+    typeDefs: schema,
+    resolvers: {
+      JSON: jsonScalar,
+      Query: {
+        ping: () => "pong",
+      },
+      Mutation: {
+        executeMethod: async (
+          _parent: unknown,
+          args: { methodName: string; params?: Record<string, unknown>; props?: Record<string, string> },
+          context: { request: Request }
+        ) => {
+          try {
+            const clientId = await resolveClientId(context.request);
+            return await executeRegisteredMethod(
+              {
+                methodName: args.methodName,
+                params: args.params || {},
+                props: args.props || {},
+              },
+              clientId
+            );
+          } catch (error) {
+            throw toGraphQLError(error);
+          }
+        },
+      },
+    },
+  }),
+  context: ({ request }: { request: Request }) => ({ request }),
+  graphqlEndpoint: "/api/graphql",
+  graphiql: true,
+  fetchAPI: { Request, Response },
+});
+
+export async function handleGraphQLPost(request: Request) {
+  return yoga.handleRequest(request, { request });
 }
 
-export function handleGraphQLGet() {
-  return new Response(
-    `<!DOCTYPE html>
-    <html><head><title>Opal Support API - GraphQL</title><style>body{font-family:sans-serif;max-width:800px;margin:50px auto;padding:20px}code,pre{background:#f4f4f4;padding:4px 8px;border-radius:4px}</style></head>
-    <body><h1>Opal Support API</h1><p>GraphQL endpoint for executing registered methods.</p><h2>Endpoint</h2><code>POST /api/graphql</code><h2>Authentication</h2><p>Use Bearer token in Authorization header.</p><h2>Schema</h2><pre>${schema}</pre></body></html>`,
-    { headers: { "Content-Type": "text/html" } }
-  );
+export async function handleGraphQLGet(request: Request) {
+  return yoga.handleRequest(request, { request });
 }

package/src/server/index.ts

@@ -2,5 +2,5 @@ export * from "./types";
 export * from "./errors";
 export * from "./kvStore";
 export * from "./runtimeSecurity";
-export { agentRegistry } from "../agents/agentRegistry";
-export type { AgentRegistration } from "../agents/agentRegistry";
+export { agentRegistry } from "../agents/registry";
+export type { AgentRegistration } from "../agents/registry";

package/src/shared/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Shared Module - Client-safe types and utilities
+ * This module can be safely imported in both client and server environments
+ */
+
+export * from './types';
+export * from './utils';

package/src/shared/types/agent.types.ts

@@ -0,0 +1,80 @@
+/**
+ * Shared Agent Types - Safe for client and server
+ * These types contain no sensitive data and can be used in both environments
+ */
+
+/**
+ * Agent metadata - safe for client display
+ */
+export interface AgentMetadata {
+  id: string;
+  name: string;
+  description: string;
+  category: string;
+  route: string;
+  tags?: string[];
+}
+
+/**
+ * Generic agent response wrapper
+ */
+export interface AgentResponse<T = unknown> {
+  success: boolean;
+  data?: T;
+  error?: string;
+  timestamp?: string;
+}
+
+/**
+ * Execution step tracking for workflow visualization
+ */
+export interface ExecutionStep {
+  agent: string;
+  action: string;
+  status: 'running' | 'success' | 'error';
+  startTime: number;
+  endTime?: number;
+  duration?: number;
+  input?: Record<string, unknown>;
+  output?: Record<string, unknown>;
+  error?: string;
+  description?: string;
+  phase?: 'orchestration' | 'vectorization' | 'storage' | 'retrieval' | 'ingestion' | 'generation';
+}
+
+/**
+ * Workflow step types supported by the runtime
+ * Includes both English (preferred) and legacy (Portuguese) names
+ */
+export type WorkflowStepType =
+  // English step types (preferred)
+  | 'joke'
+  | 'translation'
+  | 'image'
+  | 'vectorize'
+  | 'mcp-tool'
+  | 'chromadb'
+  | 'gitmcp'
+  | 'rag'
+  | 'chat'
+  | 'output-generator'
+  | 'builtin-agent'
+  | 'custom-action'
+  // Legacy step types (backward compatibility)
+  | 'genkit-joke'
+  | 'genkit-translation'
+  | 'genkit-image'
+  | 'gemini-vectorize';
+
+/**
+ * Agent categories for organization
+ */
+export type AgentCategory =
+  | 'utility'
+  | 'translation'
+  | 'image'
+  | 'mcp'
+  | 'vectorization'
+  | 'storage'
+  | 'retrieval'
+  | 'orchestration';

package/src/shared/types/execution.types.ts

@@ -0,0 +1,45 @@
+/**
+ * Execution Types - Shared between client and server
+ * Used for tracking and displaying execution progress
+ */
+
+/**
+ * Execution result from a workflow step
+ */
+export interface ExecutionResult<T = unknown> {
+  success: boolean;
+  data?: T;
+  error?: string;
+  duration?: number;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Workflow execution status
+ */
+export type ExecutionStatus = 'pending' | 'running' | 'success' | 'error' | 'cancelled';
+
+/**
+ * Workflow execution summary
+ */
+export interface ExecutionSummary {
+  agentId: string;
+  status: ExecutionStatus;
+  startTime: number;
+  endTime?: number;
+  totalDuration?: number;
+  stepsCompleted: number;
+  totalSteps: number;
+  error?: string;
+}
+
+/**
+ * Execution log entry
+ */
+export interface ExecutionLogEntry {
+  timestamp: number;
+  level: 'info' | 'warn' | 'error' | 'debug';
+  message: string;
+  step?: string;
+  metadata?: Record<string, unknown>;
+}

package/src/shared/types/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Shared Types - Re-exports for client and server
+ */
+
+export * from './agent.types';
+export * from './execution.types';
+export * from './schema.types';

package/src/shared/types/schema.types.ts

@@ -0,0 +1,55 @@
+/**
+ * Schema Types - Shared type definitions for agent schemas
+ * Used for input/output validation on both client and server
+ */
+
+/**
+ * JSON Schema-like type definition
+ */
+export interface SchemaProperty {
+  type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+  description?: string;
+  enum?: string[];
+  items?: SchemaProperty;
+  properties?: Record<string, SchemaProperty>;
+  required?: string[];
+  default?: unknown;
+  minLength?: number;
+  maxLength?: number;
+  minimum?: number;
+  maximum?: number;
+  pattern?: string;
+}
+
+/**
+ * Agent schema definition
+ */
+export interface AgentSchemaDefinition {
+  input: {
+    type: 'object';
+    properties: Record<string, SchemaProperty>;
+    required?: string[];
+  };
+  output: {
+    type: 'object';
+    properties: Record<string, SchemaProperty>;
+    required?: string[];
+  };
+}
+
+/**
+ * Validation result
+ */
+export interface ValidationResult {
+  valid: boolean;
+  errors?: ValidationError[];
+}
+
+/**
+ * Validation error detail
+ */
+export interface ValidationError {
+  path: string;
+  message: string;
+  code: string;
+}

package/src/shared/utils/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Shared Utilities - Re-exports
+ */
+
+export * from './validation';

package/src/shared/utils/validation.ts

@@ -0,0 +1,100 @@
+/**
+ * Validation Utilities - Shared validation helpers
+ * Safe for use in both client and server environments
+ */
+
+import type { ValidationResult, ValidationError } from '../types/schema.types';
+
+/**
+ * Validate that a value is a non-empty string
+ */
+export function isNonEmptyString(value: unknown): value is string {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+/**
+ * Validate that a value is a positive number
+ */
+export function isPositiveNumber(value: unknown): value is number {
+  return typeof value === 'number' && value > 0 && !isNaN(value);
+}
+
+/**
+ * Validate that a value is a valid URL
+ */
+export function isValidUrl(value: unknown): value is string {
+  if (typeof value !== 'string') return false;
+  try {
+    new URL(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Validate resolution format (e.g., "1024x1024")
+ */
+export function isValidResolution(value: unknown): value is string {
+  if (typeof value !== 'string') return false;
+  return /^\d+x\d+$/.test(value);
+}
+
+/**
+ * Validate language code (e.g., "en", "pt", "es")
+ */
+export function isValidLanguageCode(value: unknown): value is string {
+  if (typeof value !== 'string') return false;
+  return /^[a-z]{2}(-[A-Z]{2})?$/.test(value);
+}
+
+/**
+ * Create a validation result with errors
+ */
+export function createValidationResult(errors: ValidationError[]): ValidationResult {
+  return {
+    valid: errors.length === 0,
+    errors: errors.length > 0 ? errors : undefined,
+  };
+}
+
+/**
+ * Create a validation error
+ */
+export function createValidationError(
+  path: string,
+  message: string,
+  code: string
+): ValidationError {
+  return { path, message, code };
+}
+
+/**
+ * Sanitize string input by trimming whitespace
+ */
+export function sanitizeString(value: unknown): string {
+  if (typeof value !== 'string') return '';
+  return value.trim();
+}
+
+/**
+ * Validate required fields in an object
+ */
+export function validateRequiredFields(
+  obj: Record<string, unknown>,
+  requiredFields: string[]
+): ValidationError[] {
+  const errors: ValidationError[] = [];
+  
+  for (const field of requiredFields) {
+    if (obj[field] === undefined || obj[field] === null) {
+      errors.push(createValidationError(
+        field,
+        `Missing required field: ${field}`,
+        'REQUIRED_FIELD_MISSING'
+      ));
+    }
+  }
+  
+  return errors;
+}