@compilr-dev/sdk 0.3.1 → 0.4.1

package/dist/actions/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Contextual Actions — Skill invocations with context.
+ *
+ * Actions place skills where the user is (project panel, work items,
+ * documents). The ActionResolver builds the final prompt from
+ * skill + context for the agent.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   getActionsForContext,
+ *   resolveActionPrompt,
+ *   buildContextSummary,
+ * } from '@compilr-dev/sdk';
+ *
+ * // Get actions for a work item
+ * const actions = getActionsForContext('workitem');
+ *
+ * // Resolve action to a prompt
+ * const prompt = resolveActionPrompt('build', {
+ *   source: 'workitem',
+ *   project: { id: 1, name: 'hr-manager', displayName: 'Hr Manager' },
+ *   workItem: { id: 'CHR-002', title: 'Authentication System' },
+ * }, allSkills);
+ * ```
+ */
+export type { ActionContext, ActionDefinition } from './types.js';
+export { ACTION_REGISTRY, getActionsForContext, getActionById } from './registry.js';
+export { resolveActionPrompt, buildContextSummary, getSuggestedRole } from './resolver.js';

package/dist/actions/index.js

@@ -0,0 +1,30 @@
+/**
+ * Contextual Actions — Skill invocations with context.
+ *
+ * Actions place skills where the user is (project panel, work items,
+ * documents). The ActionResolver builds the final prompt from
+ * skill + context for the agent.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   getActionsForContext,
+ *   resolveActionPrompt,
+ *   buildContextSummary,
+ * } from '@compilr-dev/sdk';
+ *
+ * // Get actions for a work item
+ * const actions = getActionsForContext('workitem');
+ *
+ * // Resolve action to a prompt
+ * const prompt = resolveActionPrompt('build', {
+ *   source: 'workitem',
+ *   project: { id: 1, name: 'hr-manager', displayName: 'Hr Manager' },
+ *   workItem: { id: 'CHR-002', title: 'Authentication System' },
+ * }, allSkills);
+ * ```
+ */
+// Registry
+export { ACTION_REGISTRY, getActionsForContext, getActionById } from './registry.js';
+// Resolver
+export { resolveActionPrompt, buildContextSummary, getSuggestedRole } from './resolver.js';

package/dist/actions/registry.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Action Registry — Defines which actions are available and where.
+ *
+ * Each action maps to a skill (from platformSkills/builtinSkills)
+ * but adds UI metadata: icon, label, category, applicable contexts,
+ * and suggested agent role.
+ */
+import type { ActionDefinition } from './types.js';
+export declare const ACTION_REGISTRY: ActionDefinition[];
+/**
+ * Get actions applicable to a given context type.
+ */
+export declare function getActionsForContext(contextType: 'project' | 'workitem' | 'document'): ActionDefinition[];
+/**
+ * Get an action definition by ID.
+ */
+export declare function getActionById(id: string): ActionDefinition | undefined;

package/dist/actions/registry.js

@@ -0,0 +1,152 @@
+/**
+ * Action Registry — Defines which actions are available and where.
+ *
+ * Each action maps to a skill (from platformSkills/builtinSkills)
+ * but adds UI metadata: icon, label, category, applicable contexts,
+ * and suggested agent role.
+ */
+export const ACTION_REGISTRY = [
+    // ─── Project-level actions ─────────────────────────────────────────────
+    {
+        id: 'design',
+        label: 'Design App',
+        description: 'Describe an idea, get a full application design',
+        icon: 'Wand2',
+        applicableTo: ['project'],
+        category: 'design',
+        suggestedRole: 'architect',
+        needsInput: true,
+        inputPrompt: 'What would you like to design?',
+    },
+    {
+        id: 'sketch',
+        label: 'Quick Sketch',
+        description: 'Quickly sketch out an idea or concept',
+        icon: 'Pencil',
+        applicableTo: ['project'],
+        category: 'design',
+        needsInput: true,
+        inputPrompt: 'What would you like to sketch?',
+    },
+    {
+        id: 'prd',
+        label: 'Write PRD',
+        description: 'Create a product requirements document',
+        icon: 'FileText',
+        applicableTo: ['project'],
+        category: 'planning',
+        suggestedRole: 'pm',
+    },
+    {
+        id: 'architecture',
+        label: 'Architecture',
+        description: 'Design the system architecture',
+        icon: 'Network',
+        applicableTo: ['project'],
+        category: 'design',
+        suggestedRole: 'architect',
+    },
+    {
+        id: 'scaffold',
+        label: 'Scaffold',
+        description: 'Generate project code from the app model',
+        icon: 'Layers',
+        applicableTo: ['project'],
+        category: 'development',
+        suggestedRole: 'developer',
+    },
+    {
+        id: 'session-notes',
+        label: 'Session Notes',
+        description: 'Summarize what was accomplished in this session',
+        icon: 'StickyNote',
+        applicableTo: ['project'],
+        category: 'documentation',
+    },
+    // ─── Work item actions ─────────────────────────────────────────────────
+    {
+        id: 'refine',
+        label: 'Refine',
+        description: 'Break down into smaller tasks',
+        icon: 'RefreshCw',
+        applicableTo: ['project', 'workitem'],
+        category: 'planning',
+        suggestedRole: 'pm',
+    },
+    {
+        id: 'refine-item',
+        label: 'Refine Item',
+        description: 'Add detail and acceptance criteria to this item',
+        icon: 'RefreshCw',
+        applicableTo: ['workitem'],
+        category: 'planning',
+        suggestedRole: 'pm',
+    },
+    {
+        id: 'build',
+        label: 'Build',
+        description: 'Implement this work item',
+        icon: 'Hammer',
+        applicableTo: ['workitem'],
+        category: 'development',
+        suggestedRole: 'developer',
+    },
+    {
+        id: 'code-review',
+        label: 'Code Review',
+        description: 'Review code for quality and correctness',
+        icon: 'Search',
+        applicableTo: ['project', 'workitem'],
+        category: 'development',
+        suggestedRole: 'qa',
+    },
+    {
+        id: 'debug',
+        label: 'Debug',
+        description: 'Debug an issue or error',
+        icon: 'Bug',
+        applicableTo: ['project', 'workitem'],
+        category: 'development',
+        suggestedRole: 'developer',
+    },
+    // ─── Document actions ──────────────────────────────────────────────────
+    {
+        id: 'explain',
+        label: 'Explain',
+        description: 'Explain this code or document',
+        icon: 'BookOpen',
+        applicableTo: ['document', 'workitem'],
+        category: 'documentation',
+    },
+    // ─── Analysis actions ──────────────────────────────────────────────────
+    {
+        id: 'security-review',
+        label: 'Security Review',
+        description: 'Review for security vulnerabilities',
+        icon: 'Shield',
+        applicableTo: ['project'],
+        category: 'analysis',
+        suggestedRole: 'security',
+    },
+    {
+        id: 'refactor',
+        label: 'Refactor',
+        description: 'Improve code quality without changing behavior',
+        icon: 'Scissors',
+        applicableTo: ['project', 'workitem'],
+        category: 'development',
+        suggestedRole: 'developer',
+    },
+];
+/**
+ * Get actions applicable to a given context type.
+ */
+export function getActionsForContext(contextType) {
+    return ACTION_REGISTRY.filter((a) => a.applicableTo.includes(contextType));
+}
+/**
+ * Get an action definition by ID.
+ */
+export function getActionById(id) {
+    return ACTION_REGISTRY.find((a) => a.id === id);
+}

package/dist/actions/resolver.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Action Resolver — Builds the final prompt from skill + context.
+ *
+ * Given an action ID and context (project, work item, document),
+ * produces the complete prompt to send to the agent. The prompt
+ * includes a context section followed by the skill prompt.
+ *
+ * Used by both CLI and desktop to turn user actions into agent prompts.
+ */
+import type { Skill } from '@compilr-dev/agents';
+import type { ActionContext } from './types.js';
+/**
+ * Resolve an action + context into a final prompt for the agent.
+ *
+ * @param actionId - Action ID (matches skill name)
+ * @param context - Context from the UI origin
+ * @param skills - Available skills to search for the prompt
+ * @returns The full prompt string, or null if skill not found
+ */
+export declare function resolveActionPrompt(actionId: string, context: ActionContext, skills: Skill[]): string | null;
+/**
+ * Build a compact summary of the action context (for UI display).
+ * Used by the ActionCard component to show a brief description.
+ */
+export declare function buildContextSummary(context: ActionContext): string;
+/**
+ * Get the suggested agent role for an action.
+ */
+export declare function getSuggestedRole(actionId: string): string | undefined;

package/dist/actions/resolver.js

@@ -0,0 +1,107 @@
+/**
+ * Action Resolver — Builds the final prompt from skill + context.
+ *
+ * Given an action ID and context (project, work item, document),
+ * produces the complete prompt to send to the agent. The prompt
+ * includes a context section followed by the skill prompt.
+ *
+ * Used by both CLI and desktop to turn user actions into agent prompts.
+ */
+import { getActionById } from './registry.js';
+/**
+ * Resolve an action + context into a final prompt for the agent.
+ *
+ * @param actionId - Action ID (matches skill name)
+ * @param context - Context from the UI origin
+ * @param skills - Available skills to search for the prompt
+ * @returns The full prompt string, or null if skill not found
+ */
+export function resolveActionPrompt(actionId, context, skills) {
+    // Find the skill prompt
+    const skill = skills.find((s) => s.name === actionId);
+    if (!skill)
+        return null;
+    // Build context section
+    const contextSection = buildContextSection(context);
+    // Combine: context + skill prompt + user input
+    const parts = [];
+    if (contextSection) {
+        parts.push(contextSection);
+        parts.push('---');
+    }
+    parts.push(skill.prompt);
+    if (context.userInput) {
+        parts.push('---');
+        parts.push(`## User Request\n\n${context.userInput}`);
+    }
+    return parts.join('\n\n');
+}
+/**
+ * Build a context section from the action context.
+ * This gives the agent structured information about what it's working on.
+ */
+function buildContextSection(context) {
+    const lines = [];
+    if (context.project) {
+        lines.push(`## Action Context`);
+        lines.push(`- **Project:** ${context.project.displayName} (\`${context.project.name}\`)`);
+        if (context.project.path) {
+            lines.push(`- **Path:** \`${context.project.path}\``);
+        }
+    }
+    if (context.workItem) {
+        if (lines.length === 0)
+            lines.push('## Action Context');
+        lines.push(`- **Work Item:** ${context.workItem.id} — ${context.workItem.title}`);
+        if (context.workItem.priority) {
+            lines.push(`- **Priority:** ${context.workItem.priority}`);
+        }
+        if (context.workItem.status) {
+            lines.push(`- **Status:** ${context.workItem.status}`);
+        }
+        if (context.workItem.type) {
+            lines.push(`- **Type:** ${context.workItem.type}`);
+        }
+        if (context.workItem.description) {
+            lines.push('');
+            lines.push('**Description:**');
+            lines.push(context.workItem.description);
+        }
+    }
+    if (context.document) {
+        if (lines.length === 0)
+            lines.push('## Action Context');
+        lines.push(`- **Document:** ${context.document.title}`);
+        if (context.document.type) {
+            lines.push(`- **Type:** ${context.document.type}`);
+        }
+        if (context.document.contentPreview) {
+            lines.push('');
+            lines.push('**Content Preview:**');
+            lines.push(context.document.contentPreview);
+        }
+    }
+    return lines.length > 0 ? lines.join('\n') : null;
+}
+/**
+ * Build a compact summary of the action context (for UI display).
+ * Used by the ActionCard component to show a brief description.
+ */
+export function buildContextSummary(context) {
+    if (context.workItem) {
+        return `${context.workItem.id}: ${context.workItem.title}`;
+    }
+    if (context.document) {
+        return context.document.title;
+    }
+    if (context.project) {
+        return context.project.displayName;
+    }
+    return '';
+}
+/**
+ * Get the suggested agent role for an action.
+ */
+export function getSuggestedRole(actionId) {
+    return getActionById(actionId)?.suggestedRole;
+}

package/dist/actions/types.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Action Types — Context and definition types for contextual actions.
+ *
+ * Actions are skill invocations that carry context from their origin
+ * (project panel, work item, document). The ActionResolver uses these
+ * to build the final prompt sent to the agent.
+ */
+/**
+ * Context attached to an action invocation.
+ * Carries information from the UI origin so the agent
+ * understands what it's working on.
+ */
+export interface ActionContext {
+    /** Where the action was triggered from */
+    source: 'project' | 'workitem' | 'document' | 'chat';
+    /** Active project info */
+    project?: {
+        id: number;
+        name: string;
+        displayName: string;
+        path?: string;
+    };
+    /** Work item context (when action triggered from a work item) */
+    workItem?: {
+        id: string;
+        title: string;
+        description?: string;
+        status?: string;
+        priority?: string;
+        type?: string;
+    };
+    /** Document context (when action triggered from a document) */
+    document?: {
+        id: number;
+        title: string;
+        type?: string;
+        contentPreview?: string;
+    };
+    /** Free-form user input (e.g., "Make it use JWT with refresh tokens") */
+    userInput?: string;
+}
+/**
+ * Defines an action that can be triggered from the UI.
+ * Maps to a skill but adds UI metadata and context requirements.
+ */
+export interface ActionDefinition {
+    /** Unique ID (matches skill name) */
+    id: string;
+    /** Display label */
+    label: string;
+    /** Short description */
+    description: string;
+    /** Lucide icon name */
+    icon: string;
+    /** Which context types this action applies to */
+    applicableTo: Array<'project' | 'workitem' | 'document'>;
+    /** Category for grouping in menus */
+    category: 'design' | 'development' | 'planning' | 'documentation' | 'analysis';
+    /** Suggested agent role (hint for auto-selection) */
+    suggestedRole?: string;
+    /** Whether to prompt for user input before executing */
+    needsInput?: boolean;
+    /** Prompt label when needsInput is true */
+    inputPrompt?: string;
+}

package/dist/actions/types.js

@@ -0,0 +1,8 @@
+/**
+ * Action Types — Context and definition types for contextual actions.
+ *
+ * Actions are skill invocations that carry context from their origin
+ * (project panel, work item, document). The ActionResolver uses these
+ * to build the final prompt sent to the agent.
+ */
+export {};

package/dist/index.d.ts

@@ -62,6 +62,8 @@ export { createPlatformTools, createProjectTools, createWorkItemTools, createDoc
 export type { ProjectAnchorStoreConfig } from './platform/index.js';
 export { STEP_ORDER, GUIDED_STEP_CRITERIA, getNextStep, isValidTransition, getStepCriteria, formatStepDisplay, getStepNumber, } from './platform/index.js';
 export { platformSkills, designSkill, sketchSkill, prdSkill, refineSkill, refineItemSkill, architectureSkill, sessionNotesSkill, buildSkill, scaffoldSkill, } from './skills/index.js';
+export { ACTION_REGISTRY, getActionsForContext, getActionById, resolveActionPrompt, buildContextSummary, getSuggestedRole, } from './actions/index.js';
+export type { ActionContext, ActionDefinition } from './actions/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 type { Tool, HooksConfig, AgentEvent, Message, LLMProvider, AnchorInput, ToolExecutionResult, AgentRunResult, PermissionHandler, 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, findMatchingRule, permissionModeLabel, permissionLevelLabel, } from './permissions.js';

package/dist/index.js

@@ -141,6 +141,10 @@ export { STEP_ORDER, GUIDED_STEP_CRITERIA, getNextStep, isValidTransition, getSt
 // =============================================================================
 export { platformSkills, designSkill, sketchSkill, prdSkill, refineSkill, refineItemSkill, architectureSkill, sessionNotesSkill, buildSkill, scaffoldSkill, } from './skills/index.js';
 // =============================================================================
+// Contextual Actions (skill invocations with context)
+// =============================================================================
+export { ACTION_REGISTRY, getActionsForContext, getActionById, resolveActionPrompt, buildContextSummary, getSuggestedRole, } from './actions/index.js';
+// =============================================================================
 // Re-exports from @compilr-dev/agents (convenience — no need to install separately)
 // =============================================================================
 export { 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/sdk",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "Universal agent runtime for building AI-powered applications",
   "type": "module",
   "main": "dist/index.js",
@@ -67,7 +67,7 @@
   },
   "devDependencies": {
     "@anthropic-ai/sdk": "^0.78.0",
-    "@compilr-dev/agents": "^0.3.26",
+    "@compilr-dev/agents": "^0.3.27",
     "@compilr-dev/agents-coding": "^1.0.2",
     "@eslint/js": "^9.39.1",
     "@opentelemetry/api": "^1.9.0",