mcp-agent-foundry 1.0.0

package/dist/tasks/worker-mode.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Worker Mode
+ *
+ * Enables background task processing via Claude Code subagents.
+ * Workers claim tasks, execute them via AgentRouter, and loop until done.
+ */
+import type { Logger } from "../observability/logger.js";
+import type { WorkerConfig, WorkerState } from "../types.js";
+export declare class WorkerMode {
+    private state;
+    private config;
+    private logger;
+    private lastActivityTime;
+    constructor(config: WorkerConfig, logger: Logger);
+    /**
+     * Generate instructions for the subagent on how to claim and execute tasks.
+     * Returns markdown that tells the subagent the worker claim protocol.
+     */
+    generateClaimInstructions(): string;
+    /**
+     * Update worker state.
+     */
+    updateState(updates: Partial<WorkerState>): void;
+    /**
+     * Get current worker status.
+     */
+    getStatus(): WorkerState;
+    /**
+     * Mark that the worker is starting work on a task.
+     */
+    markTaskStarted(taskId: string): void;
+    /**
+     * Mark that the worker completed a task successfully.
+     */
+    markTaskCompleted(taskId: string): void;
+    /**
+     * Mark that the worker failed a task.
+     */
+    markTaskFailed(taskId: string, error?: Error): void;
+    /**
+     * Add a task ID to the exclusion list (e.g., after failed claim due to race).
+     */
+    excludeTask(taskId: string): void;
+    /**
+     * Record a heartbeat (keeps the worker alive).
+     */
+    heartbeat(): void;
+    /**
+     * Check if the worker should shut down due to idle timeout.
+     */
+    shouldShutdown(): boolean;
+    /**
+     * Mark the worker as shut down.
+     */
+    shutdown(): void;
+    /**
+     * Get the worker name.
+     */
+    getName(): string;
+    /**
+     * Check if the worker is currently working.
+     */
+    isWorking(): boolean;
+}
+//# sourceMappingURL=worker-mode.d.ts.map

package/dist/tasks/worker-mode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-mode.d.ts","sourceRoot":"","sources":["../../src/tasks/worker-mode.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AACzD,OAAO,KAAK,EAAa,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AASxE,qBAAa,UAAU;IACrB,OAAO,CAAC,KAAK,CAAc;IAC3B,OAAO,CAAC,MAAM,CAA2F;IACzG,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,gBAAgB,CAAS;gBAErB,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM;IA4BhD;;;OAGG;IACH,yBAAyB,IAAI,MAAM;IA+CnC;;OAEG;IACH,WAAW,CAAC,OAAO,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,IAAI;IAKhD;;OAEG;IACH,SAAS,IAAI,WAAW;IAIxB;;OAEG;IACH,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAYrC;;OAEG;IACH,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAcvC;;OAEG;IACH,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK,GAAG,IAAI;IAqBnD;;OAEG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IASjC;;OAEG;IACH,SAAS,IAAI,IAAI;IAIjB;;OAEG;IACH,cAAc,IAAI,OAAO;IAezB;;OAEG;IACH,QAAQ,IAAI,IAAI;IAShB;;OAEG;IACH,OAAO,IAAI,MAAM;IAIjB;;OAEG;IACH,SAAS,IAAI,OAAO;CAGrB"}

package/dist/tasks/worker-mode.js

@@ -0,0 +1,208 @@
+/**
+ * Worker Mode
+ *
+ * Enables background task processing via Claude Code subagents.
+ * Workers claim tasks, execute them via AgentRouter, and loop until done.
+ */
+/** Default worker configuration values */
+const DEFAULTS = {
+    maxConcurrent: 1,
+    heartbeatMs: 30000,
+    idleTimeoutMs: 300000,
+};
+export class WorkerMode {
+    state;
+    config;
+    logger;
+    lastActivityTime;
+    constructor(config, logger) {
+        this.config = {
+            name: config.name,
+            allowedRoles: config.allowedRoles ?? undefined,
+            maxConcurrent: config.maxConcurrent ?? DEFAULTS.maxConcurrent,
+            heartbeatMs: config.heartbeatMs ?? DEFAULTS.heartbeatMs,
+            idleTimeoutMs: config.idleTimeoutMs ?? DEFAULTS.idleTimeoutMs,
+        };
+        this.state = {
+            name: config.name,
+            status: "idle",
+            completedCount: 0,
+            failedCount: 0,
+            lastHeartbeat: Date.now(),
+            excludeTaskIds: [],
+        };
+        this.lastActivityTime = Date.now();
+        this.logger = logger;
+        this.logger.info("Worker mode initialized", {
+            name: config.name,
+            allowedRoles: config.allowedRoles,
+            maxConcurrent: this.config.maxConcurrent,
+        });
+    }
+    /**
+     * Generate instructions for the subagent on how to claim and execute tasks.
+     * Returns markdown that tells the subagent the worker claim protocol.
+     */
+    generateClaimInstructions() {
+        const roleFilter = this.config.allowedRoles?.length
+            ? `metadata.role IN [${this.config.allowedRoles.map(r => `"${r}"`).join(", ")}]`
+            : "any role";
+        const excludeClause = this.state.excludeTaskIds?.length
+            ? `   - id NOT IN [${this.state.excludeTaskIds.join(", ")}]`
+            : "";
+        return `
+## Worker Task Claim Protocol
+
+**Worker:** ${this.state.name}
+**Allowed Roles:** ${this.config.allowedRoles?.join(", ") ?? "any"}
+**Status:** ${this.state.status}
+**Completed:** ${this.state.completedCount} | **Failed:** ${this.state.failedCount}
+
+### Instructions
+
+1. **Get current tasks:**
+   \`TaskList()\`
+
+2. **Find a task matching:**
+   - status = "pending"
+   - owner = null (unclaimed)
+   - blockedBy is empty OR all blockers completed
+   - ${roleFilter}
+${excludeClause}
+
+3. **If found, claim it:**
+   \`TaskUpdate({ taskId: <found_id>, status: "in_progress", owner: "${this.state.name}" })\`
+
+4. **Execute via AgentRouter:**
+   \`execute_task({ taskId: <found_id> })\`
+
+5. **On completion, loop back to step 1.**
+
+6. **If no tasks match, worker can exit:**
+   \`Teammate({ operation: "requestShutdown" })\`
+
+### Notes
+- If a claim fails (another worker claimed first), add the taskId to excludeTaskIds and retry
+- The execute_task tool automatically marks tasks complete on success
+- If execution fails, the task is released for retry
+`;
+    }
+    /**
+     * Update worker state.
+     */
+    updateState(updates) {
+        Object.assign(this.state, updates);
+        this.state.lastHeartbeat = Date.now();
+    }
+    /**
+     * Get current worker status.
+     */
+    getStatus() {
+        return { ...this.state };
+    }
+    /**
+     * Mark that the worker is starting work on a task.
+     */
+    markTaskStarted(taskId) {
+        this.state.status = "working";
+        this.state.currentTask = taskId;
+        this.lastActivityTime = Date.now();
+        this.state.lastHeartbeat = Date.now();
+        this.logger.debug("Worker starting task", {
+            worker: this.state.name,
+            taskId,
+        });
+    }
+    /**
+     * Mark that the worker completed a task successfully.
+     */
+    markTaskCompleted(taskId) {
+        this.state.status = "idle";
+        delete this.state.currentTask;
+        this.state.completedCount++;
+        this.lastActivityTime = Date.now();
+        this.state.lastHeartbeat = Date.now();
+        this.logger.info("Worker completed task", {
+            worker: this.state.name,
+            taskId,
+            completedCount: this.state.completedCount,
+        });
+    }
+    /**
+     * Mark that the worker failed a task.
+     */
+    markTaskFailed(taskId, error) {
+        this.state.status = "idle";
+        delete this.state.currentTask;
+        this.state.failedCount++;
+        this.lastActivityTime = Date.now();
+        this.state.lastHeartbeat = Date.now();
+        // Add to exclude list to avoid retrying immediately
+        if (!this.state.excludeTaskIds) {
+            this.state.excludeTaskIds = [];
+        }
+        this.state.excludeTaskIds.push(taskId);
+        this.logger.warn("Worker failed task", {
+            worker: this.state.name,
+            taskId,
+            failedCount: this.state.failedCount,
+            error: error?.message,
+        });
+    }
+    /**
+     * Add a task ID to the exclusion list (e.g., after failed claim due to race).
+     */
+    excludeTask(taskId) {
+        if (!this.state.excludeTaskIds) {
+            this.state.excludeTaskIds = [];
+        }
+        if (!this.state.excludeTaskIds.includes(taskId)) {
+            this.state.excludeTaskIds.push(taskId);
+        }
+    }
+    /**
+     * Record a heartbeat (keeps the worker alive).
+     */
+    heartbeat() {
+        this.state.lastHeartbeat = Date.now();
+    }
+    /**
+     * Check if the worker should shut down due to idle timeout.
+     */
+    shouldShutdown() {
+        const idleTime = Date.now() - this.lastActivityTime;
+        const shouldStop = idleTime > this.config.idleTimeoutMs;
+        if (shouldStop) {
+            this.logger.info("Worker idle timeout reached", {
+                worker: this.state.name,
+                idleTimeMs: idleTime,
+                idleTimeoutMs: this.config.idleTimeoutMs,
+            });
+        }
+        return shouldStop;
+    }
+    /**
+     * Mark the worker as shut down.
+     */
+    shutdown() {
+        this.state.status = "shutdown";
+        this.logger.info("Worker shutdown", {
+            worker: this.state.name,
+            completedCount: this.state.completedCount,
+            failedCount: this.state.failedCount,
+        });
+    }
+    /**
+     * Get the worker name.
+     */
+    getName() {
+        return this.state.name;
+    }
+    /**
+     * Check if the worker is currently working.
+     */
+    isWorking() {
+        return this.state.status === "working";
+    }
+}
+//# sourceMappingURL=worker-mode.js.map

package/dist/tasks/worker-mode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-mode.js","sourceRoot":"","sources":["../../src/tasks/worker-mode.ts"],"names":[],"mappings":"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"}

package/dist/translation/errors.d.ts

@@ -0,0 +1,203 @@
+/**
+ * Error Translation Layer
+ *
+ * Normalizes error formats from different LLM providers (Anthropic, OpenAI, Gemini)
+ * into AgentRouter's standardized error types. This allows consistent error handling
+ * regardless of which provider produced the error.
+ *
+ * Provider error format differences:
+ * - Anthropic: { type: "error", error: { type, message } }
+ * - OpenAI: { error: { message, type, code } }
+ * - Gemini: { error: { message, status, code } }
+ *
+ * All errors are mapped to the appropriate AgentRouterError subclass with the
+ * original error preserved in the `cause` property for debugging.
+ */
+import { AgentRouterError } from '../types.js';
+/**
+ * Anthropic API error structure.
+ * Format: { type: "error", error: { type: string, message: string } }
+ */
+export interface AnthropicError {
+    type?: 'error';
+    error?: {
+        type?: string;
+        message?: string;
+    };
+    status?: number;
+    statusCode?: number;
+    message?: string;
+}
+/**
+ * OpenAI API error structure.
+ * Format: { error: { message: string, type: string, code: string } }
+ */
+export interface OpenAIError {
+    error?: {
+        message?: string;
+        type?: string;
+        code?: string | null;
+        param?: string | null;
+    };
+    status?: number;
+    statusCode?: number;
+    message?: string;
+}
+/**
+ * Google Gemini API error structure.
+ * Format: { error: { message: string, status: string, code: number } }
+ */
+export interface GeminiError {
+    error?: {
+        message?: string;
+        status?: string;
+        code?: number;
+        details?: {
+            '@type'?: string;
+            reason?: string;
+            domain?: string;
+            metadata?: Record<string, string>;
+        }[];
+    };
+    status?: number;
+    statusCode?: number;
+    message?: string;
+}
+/**
+ * Generic error with HTTP-like properties (for errors from fetch, SDK wrappers, etc.)
+ */
+export interface HttpError extends Error {
+    status?: number;
+    statusCode?: number;
+    code?: string;
+    response?: {
+        status?: number;
+        data?: unknown;
+    };
+}
+/**
+ * Translate an Anthropic API error to an AgentRouterError.
+ *
+ * Anthropic error format:
+ * ```json
+ * {
+ *   "type": "error",
+ *   "error": {
+ *     "type": "invalid_request_error" | "authentication_error" | "rate_limit_error" | ...,
+ *     "message": "Human-readable error message"
+ *   }
+ * }
+ * ```
+ *
+ * Error types from Anthropic:
+ * - invalid_request_error: Bad request parameters (400)
+ * - authentication_error: Invalid API key (401)
+ * - permission_error: Forbidden (403)
+ * - not_found_error: Resource not found (404)
+ * - rate_limit_error: Rate limited (429)
+ * - api_error: Internal server error (500)
+ * - overloaded_error: Overloaded (529)
+ *
+ * @param error - The raw Anthropic error
+ * @returns Normalized AgentRouterError
+ */
+export declare function translateAnthropicError(error: AnthropicError): AgentRouterError;
+/**
+ * Translate an OpenAI API error to an AgentRouterError.
+ *
+ * OpenAI error format:
+ * ```json
+ * {
+ *   "error": {
+ *     "message": "Human-readable error message",
+ *     "type": "invalid_request_error" | "authentication_error" | "rate_limit_error" | ...,
+ *     "code": "specific_error_code" | null,
+ *     "param": "parameter_name" | null
+ *   }
+ * }
+ * ```
+ *
+ * Common error types from OpenAI:
+ * - invalid_request_error: Bad request (400)
+ * - invalid_api_key: Invalid API key (401)
+ * - insufficient_quota: Quota exceeded (429)
+ * - rate_limit_exceeded: Rate limited (429)
+ * - server_error: Internal error (500)
+ * - engine_overloaded: Overloaded (503)
+ *
+ * @param error - The raw OpenAI error
+ * @returns Normalized AgentRouterError
+ */
+export declare function translateOpenAIError(error: OpenAIError): AgentRouterError;
+/**
+ * Translate a Google Gemini API error to an AgentRouterError.
+ *
+ * Gemini error format:
+ * ```json
+ * {
+ *   "error": {
+ *     "code": 400,
+ *     "message": "Human-readable error message",
+ *     "status": "INVALID_ARGUMENT" | "UNAUTHENTICATED" | "RESOURCE_EXHAUSTED" | ...,
+ *     "details": [...]
+ *   }
+ * }
+ * ```
+ *
+ * Common status values from Gemini:
+ * - INVALID_ARGUMENT: Bad request (400)
+ * - UNAUTHENTICATED: Invalid API key (401)
+ * - PERMISSION_DENIED: Forbidden (403)
+ * - NOT_FOUND: Resource not found (404)
+ * - RESOURCE_EXHAUSTED: Rate limited or quota exceeded (429)
+ * - INTERNAL: Internal server error (500)
+ * - UNAVAILABLE: Service unavailable (503)
+ *
+ * @param error - The raw Gemini error
+ * @returns Normalized AgentRouterError
+ */
+export declare function translateGeminiError(error: GeminiError): AgentRouterError;
+/**
+ * Translate any error into an AgentRouterError.
+ * Used when the provider is unknown or for generic error handling.
+ *
+ * @param error - Any error object
+ * @param provider - Provider name for error context
+ * @returns Normalized AgentRouterError
+ */
+export declare function translateGenericError(error: unknown, provider: string): AgentRouterError;
+/**
+ * Translate an error from a specific provider.
+ * Routes to the appropriate provider-specific translator.
+ *
+ * @param error - The raw error from the provider
+ * @param provider - Provider name ('anthropic', 'openai', 'google', etc.)
+ * @returns Normalized AgentRouterError
+ */
+export declare function translateProviderError(error: unknown, provider: string): AgentRouterError;
+/**
+ * Wrap an async function to translate provider errors.
+ * Useful for wrapping provider calls to ensure consistent error handling.
+ *
+ * @param fn - Async function to wrap
+ * @param provider - Provider name for error context
+ * @returns Wrapped function that translates errors
+ */
+export declare function withErrorTranslation<T extends unknown[], R>(fn: (...args: T) => Promise<R>, provider: string): (...args: T) => Promise<R>;
+/**
+ * Check if an error is retryable (transient error that may succeed on retry).
+ *
+ * @param error - The error to check
+ * @returns True if the error is retryable
+ */
+export declare function isRetryableError(error: unknown): boolean;
+/**
+ * Get recommended retry delay for an error.
+ *
+ * @param error - The error to get retry delay for
+ * @param attempt - Current attempt number (1-based)
+ * @param baseDelayMs - Base delay in milliseconds (default: 1000)
+ * @returns Recommended delay in milliseconds, or undefined if not retryable
+ */
+export declare function getRetryDelay(error: unknown, attempt: number, baseDelayMs?: number): number | undefined;
+//# sourceMappingURL=errors.d.ts.map

package/dist/translation/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/translation/errors.ts"],"names":[],"mappings":"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"}