@compilr-dev/sdk 0.13.0 → 0.15.0

package/dist/actions/registry.js

@@ -14,7 +14,11 @@ export const ACTION_REGISTRY = [
         icon: 'Wand2',
         applicableTo: ['project'],
         category: 'design',
-        suggestedRole: 'architect',
+        // BA owns requirements: the 'ba' role (analyst profile) has both
+        // backlog_write and documents, so it can complete the full /design action
+        // (create work items + write the PRD). The architect profile lacks
+        // backlog_write and cannot create the backlog.
+        suggestedRole: 'ba',
         needsInput: true,
         inputPrompt: 'What would you like to design?',
     },
@@ -34,8 +38,13 @@ export const ACTION_REGISTRY = [
         description: 'Create a product requirements document',
         icon: 'FileText',
         applicableTo: ['project'],
-        category: 'planning',
-        suggestedRole: 'pm',
+        // PRD is artifact-authoring (requirements), grouped with design/architecture
+        // rather than backlog-breakdown 'planning' (refine/refine-item).
+        category: 'design',
+        // Requirements work → Business Analyst, not PM. The 'ba' role (analyst
+        // profile) is purpose-built for requirements gathering and has the
+        // documents tools needed to author the PRD.
+        suggestedRole: 'ba',
     },
     {
         id: 'architecture',

package/dist/errors/classify.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Agent-error classification.
+ *
+ * Provider/agent failures surface to hosts in two shapes:
+ *  - as a thrown `ProviderError` instance (in-process — e.g. the CLI), or
+ *  - as a stringified message after crossing an IPC/serialization boundary
+ *    (e.g. the Desktop app's `agent.chat` IPC returns `error: string`).
+ *
+ * Hosts were string-matching the message independently to detect the common
+ * first-run failure (a missing/invalid API key → 401), which is duplicated and
+ * fragile. This centralizes the classification so every host shares one
+ * implementation; the *remediation copy* stays host-specific (the CLI tells the
+ * user to run /config or set an env var; Desktop points to Settings).
+ */
+export type AgentErrorCategory = 'auth' | 'rate_limit' | 'overloaded' | 'server' | 'connection' | 'unknown';
+export interface AgentErrorInfo {
+    category: AgentErrorCategory;
+    /** HTTP status code if one could be determined. */
+    statusCode?: number;
+    /** The original message text (for logging / fallback display). */
+    raw: string;
+}
+/**
+ * Classify an agent/provider error into a stable category. Accepts a thrown
+ * `ProviderError` instance (read by duck-typing its `statusCode`), any `Error`,
+ * or a stringified message (post-IPC).
+ */
+export declare function classifyAgentError(err: unknown): AgentErrorInfo;
+/** Convenience: true when the failure is a missing/invalid API key. */
+export declare function isApiKeyError(err: unknown): boolean;

package/dist/errors/classify.js

@@ -0,0 +1,80 @@
+/**
+ * Agent-error classification.
+ *
+ * Provider/agent failures surface to hosts in two shapes:
+ *  - as a thrown `ProviderError` instance (in-process — e.g. the CLI), or
+ *  - as a stringified message after crossing an IPC/serialization boundary
+ *    (e.g. the Desktop app's `agent.chat` IPC returns `error: string`).
+ *
+ * Hosts were string-matching the message independently to detect the common
+ * first-run failure (a missing/invalid API key → 401), which is duplicated and
+ * fragile. This centralizes the classification so every host shares one
+ * implementation; the *remediation copy* stays host-specific (the CLI tells the
+ * user to run /config or set an env var; Desktop points to Settings).
+ */
+/** Pull a usable message string out of any thrown value. */
+function messageOf(err) {
+    if (typeof err === 'string')
+        return err;
+    if (err instanceof Error)
+        return err.message;
+    if (err && typeof err === 'object' && 'message' in err) {
+        return String(err.message);
+    }
+    return String(err);
+}
+/**
+ * First HTTP status code in the text, if any (e.g. "ProviderError: 401 ...").
+ * Uses a curated set of codes providers actually return, so a port number or IP
+ * octet isn't misread as a status (e.g. `ECONNREFUSED 127.0.0.1:443` must not
+ * read as 443 — that would mask a connection error as an HTTP one).
+ */
+function statusFromText(text) {
+    const m = text.match(/\b(400|401|403|404|408|409|413|422|429|500|502|503|504|529)\b/);
+    return m ? Number(m[1]) : undefined;
+}
+function categorize(statusCode, text) {
+    const lower = text.toLowerCase();
+    // Auth: key issues. Match on status OR the provider's textual markers, since a
+    // stringified error may not preserve the numeric code.
+    if (statusCode === 401 ||
+        statusCode === 403 ||
+        /authentication_error|invalid x-api-key|invalid api key|no api key|x-api-key|permission_error|unauthorized/.test(lower)) {
+        return 'auth';
+    }
+    if (statusCode === 429 || /rate.?limit|too many requests/.test(lower))
+        return 'rate_limit';
+    if (statusCode === 529 || /overloaded/.test(lower))
+        return 'overloaded';
+    if ((statusCode !== undefined && statusCode >= 500 && statusCode < 600) ||
+        /internal server error/.test(lower)) {
+        return 'server';
+    }
+    if (statusCode === undefined &&
+        /econnrefused|econnreset|etimedout|enotfound|network|socket|dns|connection/.test(lower)) {
+        return 'connection';
+    }
+    return 'unknown';
+}
+/**
+ * Classify an agent/provider error into a stable category. Accepts a thrown
+ * `ProviderError` instance (read by duck-typing its `statusCode`), any `Error`,
+ * or a stringified message (post-IPC).
+ */
+export function classifyAgentError(err) {
+    const raw = messageOf(err);
+    // A thrown ProviderError carries a numeric `statusCode`; prefer it. Fall back
+    // to parsing a status out of the message text (the stringified/IPC case).
+    let statusCode;
+    if (err && typeof err === 'object' && 'statusCode' in err && typeof err.statusCode === 'number') {
+        statusCode = err.statusCode;
+    }
+    else {
+        statusCode = statusFromText(raw);
+    }
+    return { category: categorize(statusCode, raw), statusCode, raw };
+}
+/** Convenience: true when the failure is a missing/invalid API key. */
+export function isApiKeyError(err) {
+    return classifyAgentError(err).category === 'auth';
+}

package/dist/index.d.ts

@@ -78,6 +78,8 @@ export { PROJECT_TYPES, getProjectTypeConfig, getEnrichedProjectTypeConfig, getP
 export type { ActionMeta, SkillMeta } from './project-types/index.js';
 export type { ProjectTypeConfig, ProjectPhase, SuggestedAgent, DocumentTemplate, } from './project-types/index.js';
 export { defineTool, createSuccessResult, createErrorResult, mergeHooks, createLoggingHooks, createClaudeProvider, createOpenAIProvider, createGeminiNativeProvider, createOllamaProvider, createTogetherProvider, createGroqProvider, createFireworksProvider, createPerplexityProvider, createOpenRouterProvider, createMockProvider, MockProvider, Agent, ContextManager, DEFAULT_CONTEXT_CONFIG, createTaskTool, createSuggestTool, defaultAgentTypes, TOOL_SETS, BUILTIN_GUARDRAILS, TOOL_NAMES, getDefaultShellManager, builtinSkills, AnchorManager, MCPManager, AgentError, ProviderError, ToolError, ToolTimeoutError, MaxIterationsError, AbortError, } from '@compilr-dev/agents';
+export { classifyAgentError, isApiKeyError } from './errors/classify.js';
+export type { AgentErrorCategory, AgentErrorInfo } from './errors/classify.js';
 export type { Tool, HooksConfig, AgentEvent, Message, LLMProvider, AnchorInput, ToolExecutionResult, AgentRunResult, PermissionHandler, PermissionHandlerResponse, ToolPermission, AgentTypeConfig, GuardrailTriggeredHandler, BeforeLLMHookResult, BeforeToolHook, BeforeToolHookResult, AfterToolHook, AgentState, AgentConfig, SessionInfo, Anchor, AnchorScope, AnchorClearOptions, AnchorPriority, AnchorQueryOptions, FileAccessType, FileAccess, GuardrailResult, GuardrailContext, MCPClient, MCPToolDefinition, } from '@compilr-dev/agents';
 export { DEFAULT_PERMISSION_RULES, WRITE_TOOLS, findMatchingRule, permissionModeLabel, permissionLevelLabel, } from './permissions.js';
 export type { PermissionRule, PermissionMode, PermissionLevel } from './permissions.js';

package/dist/index.js

@@ -193,6 +193,9 @@ AnchorManager,
 MCPManager, 
 // Error types
 AgentError, ProviderError, ToolError, ToolTimeoutError, MaxIterationsError, AbortError, } from '@compilr-dev/agents';
+// Error classification — shared by hosts to map provider/agent failures
+// (esp. missing/invalid API key) into stable categories + host-specific copy.
+export { classifyAgentError, isApiKeyError } from './errors/classify.js';
 // =============================================================================
 // Shared Permission Defaults & Utilities
 // =============================================================================

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/sdk",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Universal agent runtime for building AI-powered applications",
   "type": "module",
   "main": "dist/index.js",
@@ -17,6 +17,10 @@
     "./flow-runner": {
       "types": "./dist/flow-runner/index.d.ts",
       "import": "./dist/flow-runner/index.js"
+    },
+    "./errors": {
+      "types": "./dist/errors/classify.d.ts",
+      "import": "./dist/errors/classify.js"
     }
   },
   "files": [
@@ -64,7 +68,7 @@
     "node": ">=20.0.0"
   },
   "dependencies": {
-    "@compilr-dev/agents": "^0.5.9",
+    "@compilr-dev/agents": "^0.6.0",
     "@compilr-dev/logger": "^0.1.0",
     "ajv": "^6.14.0",
     "yaml": "^2.8.4"