@compilr-dev/sdk 0.9.15 → 0.9.16

package/dist/capabilities/packs.js

@@ -53,7 +53,7 @@ export const CAPABILITY_PACKS = {
     interaction: {
         id: 'interaction',
         label: 'User Interaction',
-        tools: ['ask_user', 'ask_user_simple', 'suggest'],
+        tools: ['ask_user', 'ask_user_simple', 'propose_alternatives', 'suggest'],
         readOnly: true,
         promptModules: [],
         estimatedPromptTokens: 0,

package/dist/index.d.ts

@@ -56,8 +56,8 @@ export type { SystemPromptContext, BuildResult, SystemPromptModule, ModuleCondit
 export type { ProjectType, ProjectStatus, RepoPattern, WorkflowMode, LifecycleState, WorkItemType, WorkItemStatus, WorkItemPriority, GuidedStep, DocumentType, PlanStatus, Project, WorkItem, ProjectDocument, Plan, PlanSummary, PlanWithWorkItem, HistoryEntry, CreateProjectInput, UpdateProjectInput, ProjectListOptions, CreateWorkItemInput, UpdateWorkItemInput, QueryWorkItemsInput, CreateDocumentInput, UpdateDocumentInput, CreatePlanInput, UpdatePlanInput, ListPlansOptions, WorkItemQueryResult, ProjectListResult, BulkCreateItem, WorkItemComment, CreateCommentInput, UpdateCommentInput, IProjectRepository, IWorkItemRepository, IDocumentRepository, IPlanRepository, ICommentRepository, IAnchorService, IArtifactService, IEpisodeService, AnchorData, ArtifactType, ArtifactData, ArtifactSummaryData, WorkEpisode, ProjectWorkSummary, PlatformContext, PlatformToolsConfig, PlatformHooks, StepCriteria, } from './platform/index.js';
 export { createSQLiteRepositories, SQLiteProjectRepository, SQLiteWorkItemRepository, SQLiteDocumentRepository, SQLitePlanRepository, SQLiteCommentRepository, getDatabase, closeDatabase, closeAllDatabases, databaseExists, SCHEMA_VERSION, SCHEMA_SQL, } from './platform/index.js';
 export type { SQLiteRepositories, CreateSQLiteRepositoriesOptions, ProjectDeleteHooks, ProjectRecord, WorkItemRecord, ProjectDocumentRecord, WorkItemCommentRecord, } from './platform/index.js';
-export { createAskUserTool, createAskUserSimpleTool } from './tools/index.js';
-export type { AskUserQuestion, AskUserInput, AskUserResult, AskUserHandler, AskUserSimpleInput, AskUserSimpleResult, AskUserSimpleHandler, } from './tools/index.js';
+export { createAskUserTool, createAskUserSimpleTool, createProposeAlternativesTool } from './tools/index.js';
+export type { AskUserQuestion, AskUserInput, AskUserResult, AskUserHandler, AskUserSimpleInput, AskUserSimpleResult, AskUserSimpleHandler, Alternative, ProposeAlternativesInput, ProposeAlternativesResult, ProposeAlternativesHandler, } from './tools/index.js';
 export { detectProject, suggestProjectType, detectCommon } from './detection/index.js';
 export type { DetectProjectOptions, DetectionResult, ContentSummary } from './detection/index.js';
 export { createGuideTool, SHARED_GUIDE_ENTRIES, searchGuideEntries, topicToGuideEntry, } from './guide/index.js';

package/dist/index.js

@@ -131,7 +131,7 @@ export { createSQLiteRepositories, SQLiteProjectRepository, SQLiteWorkItemReposi
 // =============================================================================
 // User Interaction Tools (ask_user, ask_user_simple)
 // =============================================================================
-export { createAskUserTool, createAskUserSimpleTool } from './tools/index.js';
+export { createAskUserTool, createAskUserSimpleTool, createProposeAlternativesTool } from './tools/index.js';
 // =============================================================================
 // Project Detection (universal project content detection)
 // =============================================================================

package/dist/system-prompt/modules.js

@@ -140,7 +140,7 @@ IMPORTANT: Tool names are lowercase with underscores.
 - **File operations**: read_file, write_file, edit, glob, grep
 - **Shell**: bash (use run_in_background=true for long-running), bash_output, kill_shell
 - **Task management**: todo_write, todo_read
-- **User interaction**: ask_user, ask_user_simple
+- **User interaction**: ask_user, ask_user_simple, propose_alternatives (present 2-3 options for comparison)
 - **Sub-agents**: task (types: explore, code-review, plan, debug, test-runner, refactor, security-audit, general)`,
 };
 /**

package/dist/team/skill-requirements.js

@@ -51,7 +51,7 @@ export const SKILL_REQUIREMENTS = {
     },
     design: {
         required: ['ask_user', 'workitem_add'],
-        optional: ['detect_project', 'document_save', 'edit'],
+        optional: ['propose_alternatives', 'detect_project', 'document_save', 'edit'],
         reason: 'Needs to gather requirements and create backlog',
     },
     refine: {
@@ -72,7 +72,7 @@ export const SKILL_REQUIREMENTS = {
     // Documentation skills
     architecture: {
         required: ['read_file', 'write_file', 'edit'],
-        optional: ['backlog_read', 'ask_user', 'glob'],
+        optional: ['backlog_read', 'ask_user', 'propose_alternatives', 'glob'],
         reason: 'Creates architecture documents',
     },
     prd: {

package/dist/team/tool-config.js

@@ -21,6 +21,7 @@ const TOOL_NAMES = {
     // User interaction
     ASK_USER: 'ask_user',
     ASK_USER_SIMPLE: 'ask_user_simple',
+    PROPOSE_ALTERNATIVES: 'propose_alternatives',
     // Delegation
     DELEGATE: 'delegate',
     DELEGATE_BACKGROUND: 'delegate_background',
@@ -147,7 +148,7 @@ export const TOOL_GROUPS = {
     },
     interaction: {
         label: 'User Interaction',
-        tools: [TOOL_NAMES.ASK_USER, TOOL_NAMES.ASK_USER_SIMPLE, TOOL_NAMES.SUGGEST],
+        tools: [TOOL_NAMES.ASK_USER, TOOL_NAMES.ASK_USER_SIMPLE, TOOL_NAMES.PROPOSE_ALTERNATIVES, TOOL_NAMES.SUGGEST],
         readOnly: true,
         tier: 'direct',
     },

package/dist/tools/index.d.ts

@@ -5,4 +5,6 @@
  * The SDK defines schemas and types; consumers provide the UI.
  */
 export { createAskUserTool, createAskUserSimpleTool } from './ask-user-tools.js';
+export { createProposeAlternativesTool } from './propose-alternatives-tool.js';
 export type { AskUserQuestion, AskUserInput, AskUserResult, AskUserHandler, AskUserSimpleInput, AskUserSimpleResult, AskUserSimpleHandler, } from './ask-user-tools.js';
+export type { Alternative, ProposeAlternativesInput, ProposeAlternativesResult, ProposeAlternativesHandler, } from './propose-alternatives-tool.js';

package/dist/tools/index.js

@@ -5,3 +5,4 @@
  * The SDK defines schemas and types; consumers provide the UI.
  */
 export { createAskUserTool, createAskUserSimpleTool } from './ask-user-tools.js';
+export { createProposeAlternativesTool } from './propose-alternatives-tool.js';

package/dist/tools/propose-alternatives-tool.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Propose Alternatives Tool — Present 2-3 options for the user to compare and choose.
+ *
+ * Unlike ask_user (open-ended questions), this tool presents concrete alternatives
+ * with rich previews (code, markdown, mermaid) for side-by-side comparison.
+ *
+ * Factory pattern: the consumer (CLI, desktop) provides a handler callback that
+ * implements the UI. The SDK defines the tool schema and types.
+ */
+import type { Tool } from '@compilr-dev/agents';
+/** A single alternative to present */
+export interface Alternative {
+    /** Short title: "Card Layout", "REST API" */
+    title: string;
+    /** 1-2 sentence explanation */
+    description: string;
+    /** Optional rich content for preview */
+    content?: string;
+    /** Content format for rendering */
+    contentType?: 'markdown' | 'code' | 'mermaid';
+    /** Language hint for code syntax highlighting (e.g., 'typescript', 'html') */
+    language?: string;
+    /** Pros of this alternative */
+    pros?: string[];
+    /** Cons of this alternative */
+    cons?: string[];
+}
+/** Input parameters for propose_alternatives tool */
+export interface ProposeAlternativesInput {
+    /** What decision is being made */
+    question: string;
+    /** Optional context paragraph */
+    context?: string;
+    /** 2-3 alternatives to present */
+    alternatives: Alternative[];
+}
+/** Result from propose_alternatives tool */
+export interface ProposeAlternativesResult {
+    /** 0-based index of chosen alternative */
+    chosenIndex: number;
+    /** Title of chosen alternative */
+    chosenTitle: string;
+    /** Optional user notes */
+    notes?: string;
+    /** User rejected all alternatives */
+    rejected: boolean;
+}
+/**
+ * Handler callback for propose_alternatives tool.
+ * The consumer provides the UI implementation.
+ */
+export type ProposeAlternativesHandler = (input: ProposeAlternativesInput) => Promise<ProposeAlternativesResult>;
+/**
+ * Create a propose_alternatives tool with a custom UI handler.
+ *
+ * @example
+ * ```typescript
+ * const tool = createProposeAlternativesTool(async (input) => {
+ *   // Show side-by-side dialog, wait for user choice
+ *   return { chosenIndex: 0, chosenTitle: input.alternatives[0].title, rejected: false };
+ * });
+ * ```
+ */
+export declare function createProposeAlternativesTool(handler: ProposeAlternativesHandler): Tool<ProposeAlternativesInput>;

package/dist/tools/propose-alternatives-tool.js

@@ -0,0 +1,128 @@
+/**
+ * Propose Alternatives Tool — Present 2-3 options for the user to compare and choose.
+ *
+ * Unlike ask_user (open-ended questions), this tool presents concrete alternatives
+ * with rich previews (code, markdown, mermaid) for side-by-side comparison.
+ *
+ * Factory pattern: the consumer (CLI, desktop) provides a handler callback that
+ * implements the UI. The SDK defines the tool schema and types.
+ */
+import { defineTool } from '@compilr-dev/agents';
+// =============================================================================
+// Factory
+// =============================================================================
+/**
+ * Create a propose_alternatives tool with a custom UI handler.
+ *
+ * @example
+ * ```typescript
+ * const tool = createProposeAlternativesTool(async (input) => {
+ *   // Show side-by-side dialog, wait for user choice
+ *   return { chosenIndex: 0, chosenTitle: input.alternatives[0].title, rejected: false };
+ * });
+ * ```
+ */
+export function createProposeAlternativesTool(handler) {
+    return defineTool({
+        name: 'propose_alternatives',
+        description: 'Present 2-3 alternatives for the user to compare and choose from. ' +
+            'Use when there are multiple valid approaches and the user\'s preference matters. ' +
+            'Each alternative can include rich content (code, markdown, mermaid diagrams) for visual comparison. ' +
+            'Include pros and cons to help the user decide. The user picks one or provides feedback.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                question: {
+                    type: 'string',
+                    description: 'What decision is being made (e.g., "Dashboard layout approach")',
+                },
+                context: {
+                    type: 'string',
+                    description: 'Optional background context for the decision',
+                },
+                alternatives: {
+                    type: 'array',
+                    description: '2-3 alternatives to present',
+                    minItems: 2,
+                    maxItems: 3,
+                    items: {
+                        type: 'object',
+                        properties: {
+                            title: {
+                                type: 'string',
+                                description: 'Short title (e.g., "Card Grid", "Data Table")',
+                            },
+                            description: {
+                                type: 'string',
+                                description: '1-2 sentence explanation of this approach',
+                            },
+                            content: {
+                                type: 'string',
+                                description: 'Optional rich content for preview (code, markdown, or mermaid source)',
+                            },
+                            contentType: {
+                                type: 'string',
+                                enum: ['markdown', 'code', 'mermaid'],
+                                description: 'Content format for rendering',
+                            },
+                            language: {
+                                type: 'string',
+                                description: 'Language hint for code syntax highlighting (e.g., "typescript", "html")',
+                            },
+                            pros: {
+                                type: 'array',
+                                items: { type: 'string' },
+                                description: 'Advantages of this alternative',
+                            },
+                            cons: {
+                                type: 'array',
+                                items: { type: 'string' },
+                                description: 'Disadvantages of this alternative',
+                            },
+                        },
+                        required: ['title', 'description'],
+                    },
+                },
+            },
+            required: ['question', 'alternatives'],
+        },
+        execute: async (input) => {
+            try {
+                if (input.alternatives.length < 2) {
+                    return { success: false, error: 'At least 2 alternatives are required' };
+                }
+                if (input.alternatives.length > 3) {
+                    return { success: false, error: 'Maximum 3 alternatives allowed' };
+                }
+                const result = await handler(input);
+                if (result.rejected) {
+                    return {
+                        success: true,
+                        result: {
+                            chosen: null,
+                            rejected: true,
+                            feedback: result.notes ?? 'User rejected all alternatives',
+                        },
+                    };
+                }
+                return {
+                    success: true,
+                    result: {
+                        chosen: result.chosenTitle,
+                        chosenIndex: result.chosenIndex,
+                        notes: result.notes,
+                        rejected: false,
+                    },
+                };
+            }
+            catch (err) {
+                return {
+                    success: false,
+                    error: `Failed to propose alternatives: ${err instanceof Error ? err.message : String(err)}`,
+                };
+            }
+        },
+        // Not silent — show in tool call history (this is substantive, not meta)
+        silent: false,
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/sdk",
-  "version": "0.9.15",
+  "version": "0.9.16",
   "description": "Universal agent runtime for building AI-powered applications",
   "type": "module",
   "main": "dist/index.js",