crewly 1.11.6 → 1.12.0

package/packages/crewly-agent/src/runtime/agent-worker.ts

@@ -0,0 +1,193 @@
+/**
+ * Agent Worker Process
+ *
+ * Standalone Node.js child process that wraps AgentRunnerService for
+ * isolated agent execution. Communicates with the parent process via
+ * IPC messages (Node.js child_process.fork() protocol).
+ *
+ * This enables hot-reload of agent code without restarting the main
+ * backend process, and crash isolation so a worker failure doesn't
+ * bring down the server.
+ *
+ * @module services/agent/crewly-agent/agent-worker
+ */
+
+import { AgentRunnerService } from './agent-runner.service.js';
+import type {
+  CrewlyAgentConfig,
+  AgentRunResult,
+  StreamingEventCallbacks,
+} from './types.js';
+
+// ===== IPC Message Types =====
+
+/**
+ * Messages sent from the parent process to this worker.
+ */
+export type ParentMessage =
+  | { type: 'init'; config: CrewlyAgentConfig }
+  | { type: 'run'; message: string; conversationId?: string; metadata?: Record<string, string> }
+  | { type: 'abort' }
+  | { type: 'get-state' }
+  | { type: 'shutdown' };
+
+/**
+ * Messages sent from this worker to the parent process.
+ */
+export type WorkerMessage =
+  | { type: 'ready' }
+  | { type: 'result'; data: AgentRunResult }
+  | { type: 'error'; error: string; code?: string }
+  | { type: 'log'; level: 'debug' | 'info' | 'warn' | 'error'; message: string }
+  | { type: 'stream'; event: 'text'; data: { chunk: string } }
+  | { type: 'stream'; event: 'toolStart'; data: { toolName: string; args: Record<string, unknown> } }
+  | { type: 'stream'; event: 'toolFinish'; data: { toolName: string; args: Record<string, unknown>; result: unknown; durationMs: number } }
+  | { type: 'stream'; event: 'stepFinish'; data: { stepIndex: number; hasToolCalls: boolean } }
+  | { type: 'state'; data: { historyLength: number; isProcessing: boolean; isInitialized: boolean } };
+
+// ===== Worker State =====
+
+let runner: AgentRunnerService | null = null;
+
+/**
+ * Send a typed message to the parent process.
+ *
+ * @param msg - Worker message to send
+ */
+function send(msg: WorkerMessage): void {
+  if (process.send) {
+    process.send(msg);
+  }
+}
+
+/**
+ * Build streaming callbacks that forward events to the parent via IPC.
+ *
+ * @returns StreamingEventCallbacks that emit IPC messages
+ */
+function buildStreamingCallbacks(): StreamingEventCallbacks {
+  return {
+    onTextChunk: (chunk: string) => {
+      send({ type: 'stream', event: 'text', data: { chunk } });
+    },
+    onToolCallStart: (toolName: string, args: Record<string, unknown>) => {
+      send({ type: 'stream', event: 'toolStart', data: { toolName, args } });
+    },
+    onToolCallFinish: (toolName: string, args: Record<string, unknown>, result: unknown, durationMs: number) => {
+      send({ type: 'stream', event: 'toolFinish', data: { toolName, args, result, durationMs } });
+    },
+    onStepFinish: (stepIndex: number, hasToolCalls: boolean) => {
+      send({ type: 'stream', event: 'stepFinish', data: { stepIndex, hasToolCalls } });
+    },
+  };
+}
+
+/** AbortController for the currently executing run */
+let currentAbort: AbortController | null = null;
+
+/**
+ * Handle incoming messages from the parent process.
+ *
+ * @param msg - Parent message received via IPC
+ */
+async function handleMessage(msg: ParentMessage): Promise<void> {
+  switch (msg.type) {
+    case 'init': {
+      try {
+        runner = new AgentRunnerService(msg.config);
+        await runner.initialize();
+        send({ type: 'ready' });
+        send({ type: 'log', level: 'info', message: `Worker initialized (${msg.config.model.provider}/${msg.config.model.modelId})` });
+      } catch (err) {
+        const errMsg = err instanceof Error ? err.message : String(err);
+        send({ type: 'error', error: `Init failed: ${errMsg}`, code: 'INIT_FAILED' });
+        runner = null;
+      }
+      break;
+    }
+
+    case 'run': {
+      if (!runner || !runner.isInitialized()) {
+        send({ type: 'error', error: 'Worker not initialized', code: 'NOT_INITIALIZED' });
+        return;
+      }
+
+      currentAbort = new AbortController();
+      const streamingCallbacks = buildStreamingCallbacks();
+
+      try {
+        const result = await runner.run(msg.message, msg.conversationId, msg.metadata, {
+          abortSignal: currentAbort.signal,
+          streaming: streamingCallbacks,
+        });
+        currentAbort = null;
+        send({ type: 'result', data: result });
+      } catch (err) {
+        currentAbort = null;
+        const errMsg = err instanceof Error ? err.message : String(err);
+        send({ type: 'error', error: errMsg, code: 'RUN_FAILED' });
+      }
+      break;
+    }
+
+    case 'abort': {
+      if (currentAbort) {
+        currentAbort.abort();
+        currentAbort = null;
+        send({ type: 'log', level: 'warn', message: 'Run aborted by parent' });
+      }
+      if (runner) {
+        runner.abortCurrentRun();
+      }
+      break;
+    }
+
+    case 'get-state': {
+      send({
+        type: 'state',
+        data: {
+          historyLength: runner ? runner.getHistoryLength() : 0,
+          isProcessing: runner ? runner.isProcessing() : false,
+          isInitialized: runner ? runner.isInitialized() : false,
+        },
+      });
+      break;
+    }
+
+    case 'shutdown': {
+      send({ type: 'log', level: 'info', message: 'Worker shutting down' });
+      if (runner) {
+        await runner.shutdown();
+        runner = null;
+      }
+      // Give IPC a moment to flush, then exit
+      setTimeout(() => process.exit(0), 100);
+      break;
+    }
+  }
+}
+
+// ===== Process Setup =====
+
+// Listen for IPC messages from parent
+process.on('message', (msg: ParentMessage) => {
+  handleMessage(msg).catch((err) => {
+    const errMsg = err instanceof Error ? err.message : String(err);
+    send({ type: 'error', error: `Unhandled worker error: ${errMsg}`, code: 'UNHANDLED' });
+  });
+});
+
+// Handle uncaught exceptions — report to parent before crashing
+process.on('uncaughtException', (err) => {
+  send({ type: 'error', error: `Worker crash (uncaughtException): ${err.message}`, code: 'CRASH' });
+  setTimeout(() => process.exit(1), 100);
+});
+
+process.on('unhandledRejection', (reason) => {
+  const msg = reason instanceof Error ? reason.message : String(reason);
+  send({ type: 'error', error: `Worker crash (unhandledRejection): ${msg}`, code: 'CRASH' });
+  setTimeout(() => process.exit(1), 100);
+});
+
+// Signal ready to receive init
+send({ type: 'log', level: 'info', message: 'Agent worker process started, awaiting init' });

package/packages/crewly-agent/src/runtime/api-client.ts

@@ -0,0 +1,143 @@
+/**
+ * Crewly Agent API Client
+ *
+ * Lightweight HTTP client for calling the Crewly backend REST API.
+ * Replaces the bash curl wrapper used by orchestrator skill scripts
+ * with direct fetch() calls for in-process tool execution.
+ *
+ * @module services/agent/crewly-agent/api-client
+ */
+
+import { CREWLY_AGENT_DEFAULTS, type ApiCallResult } from './types.js';
+
+/**
+ * HTTP client for the Crewly backend REST API.
+ *
+ * Each tool in the ToolRegistry uses this client to make API calls
+ * instead of shelling out to bash scripts.
+ *
+ * @example
+ * ```typescript
+ * const client = new CrewlyApiClient('http://localhost:8787', 'crewly-orc');
+ * const result = await client.get('/teams');
+ * const result2 = await client.post('/terminal/agent-sam/deliver', { message: 'Hello' });
+ * ```
+ */
+export class CrewlyApiClient {
+  private baseUrl: string;
+  private sessionName: string;
+  private timeoutMs: number;
+
+  /**
+   * Create a new API client instance.
+   *
+   * @param baseUrl - Base URL for the Crewly API (e.g., 'http://localhost:8787')
+   * @param sessionName - Agent session name for the X-Agent-Session header
+   * @param timeoutMs - Request timeout in milliseconds
+   */
+  constructor(
+    baseUrl: string = CREWLY_AGENT_DEFAULTS.API_BASE_URL,
+    sessionName: string = 'crewly-orc',
+    timeoutMs: number = CREWLY_AGENT_DEFAULTS.API_TIMEOUT_MS,
+  ) {
+    this.baseUrl = baseUrl.replace(/\/$/, '');
+    this.sessionName = sessionName;
+    this.timeoutMs = timeoutMs;
+  }
+
+  /**
+   * Make a GET request to the Crewly API.
+   *
+   * @param endpoint - API endpoint path (e.g., '/teams')
+   * @returns API call result with parsed JSON data
+   */
+  async get<T = unknown>(endpoint: string): Promise<ApiCallResult<T>> {
+    return this.request<T>('GET', endpoint);
+  }
+
+  /**
+   * Make a POST request to the Crewly API.
+   *
+   * @param endpoint - API endpoint path (e.g., '/terminal/agent-sam/deliver')
+   * @param body - Request body to send as JSON
+   * @returns API call result with parsed JSON data
+   */
+  async post<T = unknown>(endpoint: string, body: unknown): Promise<ApiCallResult<T>> {
+    return this.request<T>('POST', endpoint, body);
+  }
+
+  /**
+   * Make a DELETE request to the Crewly API.
+   *
+   * @param endpoint - API endpoint path (e.g., '/schedule/check-123')
+   * @returns API call result with parsed JSON data
+   */
+  async delete<T = unknown>(endpoint: string): Promise<ApiCallResult<T>> {
+    return this.request<T>('DELETE', endpoint);
+  }
+
+  /**
+   * Internal request method handling fetch, timeout, and error mapping.
+   *
+   * @param method - HTTP method
+   * @param endpoint - API endpoint path
+   * @param body - Optional request body
+   * @returns Parsed API call result
+   */
+  private async request<T>(method: string, endpoint: string, body?: unknown): Promise<ApiCallResult<T>> {
+    const url = `${this.baseUrl}/api${endpoint}`;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+
+    try {
+      const headers: Record<string, string> = {
+        'Content-Type': 'application/json',
+      };
+      if (this.sessionName) {
+        headers['X-Agent-Session'] = this.sessionName;
+      }
+
+      const init: RequestInit = {
+        method,
+        headers,
+        signal: controller.signal,
+      };
+      if (body !== undefined) {
+        init.body = JSON.stringify(body);
+      }
+
+      const response = await fetch(url, init);
+      const responseBody = await response.text();
+
+      let data: T | undefined;
+      try {
+        const parsed = JSON.parse(responseBody);
+        data = parsed.data !== undefined ? parsed.data : parsed;
+      } catch {
+        data = responseBody as unknown as T;
+      }
+
+      if (response.ok) {
+        return { success: true, data, status: response.status };
+      }
+      return {
+        success: false,
+        error: typeof data === 'object' && data !== null && 'error' in data
+          ? String((data as Record<string, unknown>).error)
+          : `HTTP ${response.status}`,
+        status: response.status,
+      };
+    } catch (error) {
+      if (error instanceof Error && error.name === 'AbortError') {
+        return { success: false, error: `Request timeout after ${this.timeoutMs}ms`, status: 0 };
+      }
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : String(error),
+        status: 0,
+      };
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+}

package/packages/crewly-agent/src/runtime/approval-queue.service.ts

@@ -0,0 +1,307 @@
+/**
+ * Approval Queue Service
+ *
+ * Manages pending tool approval requests for the Crewly Agent runtime.
+ * When a tool requires approval (based on SecurityPolicy.requireApproval),
+ * execution is blocked and a PendingApproval entry is created. External
+ * callers (API, auditor) can then approve or reject the request.
+ *
+ * @module services/agent/crewly-agent/approval-queue.service
+ */
+
+import type { ToolSensitivity } from './types.js';
+
+/** Maximum number of pending approvals before oldest are auto-rejected */
+const MAX_PENDING_APPROVALS = 100;
+
+/** Default TTL for pending approvals in milliseconds (10 minutes) */
+const DEFAULT_APPROVAL_TTL_MS = 10 * 60 * 1000;
+
+/**
+ * Status of an approval request.
+ */
+export type ApprovalStatus = 'pending' | 'approved' | 'rejected' | 'expired';
+
+/**
+ * A single pending approval entry.
+ */
+export interface PendingApproval {
+  /** Unique approval ID */
+  id: string;
+  /** Agent session that requested the tool call */
+  sessionName: string;
+  /** Name of the tool awaiting approval */
+  toolName: string;
+  /** Sensitivity classification of the tool */
+  sensitivity: ToolSensitivity;
+  /** Sanitized arguments passed to the tool */
+  args: Record<string, unknown>;
+  /** Current status */
+  status: ApprovalStatus;
+  /** ISO timestamp when the approval was requested */
+  requestedAt: string;
+  /** ISO timestamp when the approval was resolved (approved/rejected/expired) */
+  resolvedAt?: string;
+  /** Who resolved the approval (e.g. 'api', 'auditor', 'auto-expire') */
+  resolvedBy?: string;
+  /** Reason for rejection (if rejected) */
+  reason?: string;
+}
+
+/**
+ * Result of resolving (approve/reject) an approval request.
+ */
+export interface ApprovalResolution {
+  /** Whether the resolution was successful */
+  success: boolean;
+  /** The resolved approval entry */
+  approval?: PendingApproval;
+  /** Error message if resolution failed */
+  error?: string;
+}
+
+/**
+ * In-memory approval queue for tool execution requests.
+ *
+ * Stores pending approvals and provides approve/reject operations.
+ * Approvals that exceed the TTL are automatically marked as expired
+ * when queried.
+ *
+ * @example
+ * ```typescript
+ * const queue = new ApprovalQueueService();
+ * const approval = queue.enqueue('session-1', 'edit_file', 'destructive', { path: '/foo' });
+ * // Later, approve it:
+ * const result = queue.approve(approval.id, 'api');
+ * ```
+ */
+export class ApprovalQueueService {
+  private static instance: ApprovalQueueService | null = null;
+  private approvals: Map<string, PendingApproval> = new Map();
+  private idCounter = 0;
+  private ttlMs: number;
+
+  /**
+   * Get the shared singleton instance.
+   * All agent-runners and API controllers share the same queue.
+   *
+   * @returns The shared ApprovalQueueService instance
+   */
+  static getInstance(): ApprovalQueueService {
+    if (!ApprovalQueueService.instance) {
+      ApprovalQueueService.instance = new ApprovalQueueService();
+    }
+    return ApprovalQueueService.instance;
+  }
+
+  /**
+   * Reset the singleton instance (for testing only).
+   */
+  static resetInstance(): void {
+    ApprovalQueueService.instance = null;
+  }
+
+  /**
+   * Create a new ApprovalQueueService.
+   *
+   * @param ttlMs - Time-to-live for pending approvals in milliseconds
+   */
+  constructor(ttlMs: number = DEFAULT_APPROVAL_TTL_MS) {
+    this.ttlMs = ttlMs;
+  }
+
+  /**
+   * Add a new approval request to the queue.
+   *
+   * @param sessionName - Agent session requesting approval
+   * @param toolName - Name of the tool
+   * @param sensitivity - Sensitivity classification
+   * @param args - Sanitized tool arguments
+   * @returns The created PendingApproval entry
+   */
+  enqueue(
+    sessionName: string,
+    toolName: string,
+    sensitivity: ToolSensitivity,
+    args: Record<string, unknown>,
+  ): PendingApproval {
+    this.expireStale();
+
+    // Enforce max pending limit — reject oldest if full
+    if (this.getPendingCount() >= MAX_PENDING_APPROVALS) {
+      const oldest = this.getOldestPending();
+      if (oldest) {
+        oldest.status = 'rejected';
+        oldest.resolvedAt = new Date().toISOString();
+        oldest.resolvedBy = 'auto-overflow';
+        oldest.reason = 'Approval queue overflow — auto-rejected oldest entry';
+      }
+    }
+
+    this.idCounter++;
+    const id = `approval-${this.idCounter}-${Date.now()}`;
+
+    const approval: PendingApproval = {
+      id,
+      sessionName,
+      toolName,
+      sensitivity,
+      args,
+      status: 'pending',
+      requestedAt: new Date().toISOString(),
+    };
+
+    this.approvals.set(id, approval);
+    return approval;
+  }
+
+  /**
+   * Approve a pending approval request.
+   *
+   * @param id - Approval ID to approve
+   * @param resolvedBy - Who is approving (e.g. 'api', 'auditor')
+   * @returns Resolution result
+   */
+  approve(id: string, resolvedBy: string = 'api'): ApprovalResolution {
+    return this.resolve(id, 'approved', resolvedBy);
+  }
+
+  /**
+   * Reject a pending approval request.
+   *
+   * @param id - Approval ID to reject
+   * @param resolvedBy - Who is rejecting
+   * @param reason - Reason for rejection
+   * @returns Resolution result
+   */
+  reject(id: string, resolvedBy: string = 'api', reason?: string): ApprovalResolution {
+    return this.resolve(id, 'rejected', resolvedBy, reason);
+  }
+
+  /**
+   * Get all pending approval requests.
+   *
+   * @param sessionName - Optional filter by session name
+   * @returns Array of pending approvals
+   */
+  getPending(sessionName?: string): PendingApproval[] {
+    this.expireStale();
+    const pending: PendingApproval[] = [];
+    for (const approval of this.approvals.values()) {
+      if (approval.status !== 'pending') continue;
+      if (sessionName && approval.sessionName !== sessionName) continue;
+      pending.push({ ...approval });
+    }
+    return pending;
+  }
+
+  /**
+   * Get a specific approval by ID.
+   *
+   * @param id - Approval ID
+   * @returns The approval entry or undefined
+   */
+  getById(id: string): PendingApproval | undefined {
+    const approval = this.approvals.get(id);
+    if (!approval) return undefined;
+    return { ...approval };
+  }
+
+  /**
+   * Get the count of currently pending approvals.
+   *
+   * @returns Number of pending approvals
+   */
+  getPendingCount(): number {
+    let count = 0;
+    for (const approval of this.approvals.values()) {
+      if (approval.status === 'pending') count++;
+    }
+    return count;
+  }
+
+  /**
+   * Clear all approvals (for testing or reset).
+   */
+  clear(): void {
+    this.approvals.clear();
+    this.idCounter = 0;
+  }
+
+  /**
+   * Resolve a pending approval with the given status.
+   *
+   * @param id - Approval ID
+   * @param status - New status
+   * @param resolvedBy - Who resolved it
+   * @param reason - Optional reason (for rejections)
+   * @returns Resolution result
+   */
+  private resolve(
+    id: string,
+    status: 'approved' | 'rejected',
+    resolvedBy: string,
+    reason?: string,
+  ): ApprovalResolution {
+    const approval = this.approvals.get(id);
+    if (!approval) {
+      return { success: false, error: `Approval '${id}' not found` };
+    }
+    if (approval.status !== 'pending') {
+      return {
+        success: false,
+        error: `Approval '${id}' is already ${approval.status}`,
+        approval: { ...approval },
+      };
+    }
+
+    approval.status = status;
+    approval.resolvedAt = new Date().toISOString();
+    approval.resolvedBy = resolvedBy;
+    if (reason) approval.reason = reason;
+
+    return { success: true, approval: { ...approval } };
+  }
+
+  /**
+   * Expire stale pending approvals that have exceeded the TTL.
+   */
+  private expireStale(): void {
+    const now = Date.now();
+    const resolvedRetentionMs = this.ttlMs * 3; // Keep resolved entries 3x TTL then prune
+
+    for (const [id, approval] of this.approvals.entries()) {
+      if (approval.status === 'pending') {
+        const requestedAt = new Date(approval.requestedAt).getTime();
+        if (now - requestedAt > this.ttlMs) {
+          approval.status = 'expired';
+          approval.resolvedAt = new Date().toISOString();
+          approval.resolvedBy = 'auto-expire';
+          approval.reason = 'Approval request expired';
+        }
+      } else if (approval.resolvedAt) {
+        // Prune resolved entries that are older than retention window
+        const resolvedAt = new Date(approval.resolvedAt).getTime();
+        if (now - resolvedAt > resolvedRetentionMs) {
+          this.approvals.delete(id);
+        }
+      }
+    }
+  }
+
+  /**
+   * Get the oldest pending approval.
+   *
+   * @returns Oldest pending approval or undefined
+   */
+  private getOldestPending(): PendingApproval | undefined {
+    let oldest: PendingApproval | undefined;
+    for (const approval of this.approvals.values()) {
+      if (approval.status !== 'pending') continue;
+      if (!oldest || approval.requestedAt < oldest.requestedAt) {
+        oldest = approval;
+      }
+    }
+    return oldest;
+  }
+}