@compilr-dev/sdk 0.9.14 → 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/compressors/index.js

@@ -43,7 +43,8 @@ export function createCompressorHook(config) {
             if (compressed !== null && compressed.length < stdout.length) {
                 const saved = stdout.length - compressed.length;
                 const pct = Math.round((saved / stdout.length) * 100);
-                console.log(`[compressor] bash "${command.slice(0, 40)}" ${String(stdout.length)} → ${String(compressed.length)} chars (${String(pct)}% saved)`); // eslint-disable-line no-console
+                // eslint-disable-next-line no-console
+                console.log(`[compressor] bash "${command.slice(0, 40)}" ${String(stdout.length)} → ${String(compressed.length)} chars (${String(pct)}% saved)`);
                 return {
                     result: {
                         ...ctx.result,

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/platform/tools/plan-tools.js

@@ -105,6 +105,12 @@ export function createPlanTools(config, planModeCallbacks) {
         },
         execute: async (input) => {
             try {
+                // Guard: prevent agent from self-approving plans during plan mode
+                if (input.status === 'approved' &&
+                    planModeCallbacks?.isPlanModeActive?.()) {
+                    return createErrorResult('Cannot set status to "approved" directly during plan mode. ' +
+                        'Use plan_submit to submit your plan for user approval instead.');
+                }
                 const updateInput = {};
                 if (input.content !== undefined) {
                     updateInput.content = input.content;
@@ -363,7 +369,8 @@ export function createPlanTools(config, planModeCallbacks) {
     // ---------------------------------------------------------------------------
     // plan_submit (requires callback from host app)
     // ---------------------------------------------------------------------------
-    const planSubmitTool = planModeCallbacks
+    const onPlanSubmitFn = planModeCallbacks?.onPlanSubmit;
+    const planSubmitTool = onPlanSubmitFn
         ? defineTool({
             name: 'plan_submit',
             description: 'Submit a plan for user approval. Call this when your plan is ready for review. ' +
@@ -390,7 +397,7 @@ export function createPlanTools(config, planModeCallbacks) {
                     return createErrorResult(`Plan ${String(input.plan_id)} not found`);
                 }
                 // Call host app's approval UI
-                const result = await planModeCallbacks.onPlanSubmit({
+                const result = await onPlanSubmitFn({
                     planId: input.plan_id,
                     summary: input.summary,
                 });
@@ -414,7 +421,8 @@ export function createPlanTools(config, planModeCallbacks) {
     // ---------------------------------------------------------------------------
     // plan_mode_exit (requires callback from host app)
     // ---------------------------------------------------------------------------
-    const planModeExitTool = planModeCallbacks
+    const onPlanModeExitFn = planModeCallbacks?.onPlanModeExit;
+    const planModeExitTool = onPlanModeExitFn
         ? defineTool({
             name: 'plan_mode_exit',
             description: 'Exit plan mode without submitting a plan. Use this when the task is simple enough ' +
@@ -430,7 +438,7 @@ export function createPlanTools(config, planModeCallbacks) {
                 required: ['reason'],
             },
             execute: async (input) => {
-                await planModeCallbacks.onPlanModeExit({ reason: input.reason });
+                await onPlanModeExitFn({ reason: input.reason });
                 return createSuccessResult({
                     message: `Exited plan mode: ${input.reason}. Full tools now available.`,
                 });

package/dist/project-types/configs.js

@@ -112,10 +112,10 @@ Suggest delegation when a task would benefit from focused expertise.`,
 // =============================================================================
 export const generalConfig = {
     id: 'general',
-    label: 'General',
-    description: 'Blank project — define your own workflow',
+    label: 'General Purpose',
+    description: 'Any project — define your own workflow',
     icon: 'FolderOpen',
-    category: 'software',
+    category: 'general',
     phases: [],
     suggestedAgents: [],
     documentTemplates: [

package/dist/project-types/types.d.ts

@@ -76,7 +76,7 @@ export interface ProjectTypeConfig {
     /** Lucide icon name */
     icon: string;
     /** Category for grouping in type selector */
-    category: 'software' | 'writing' | 'business' | 'education';
+    category: 'general' | 'software' | 'writing' | 'business' | 'education';
     /** Workflow phases (shown in project panel lifecycle) */
     phases: ProjectPhase[];
     /** Suggested agent roles (shown first in "Add Agent" dialog) */

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/plan-mode.d.ts

@@ -38,9 +38,11 @@ export interface PlanModeExitInfo {
  */
 export interface PlanModeCallbacks {
     /** Called when agent submits a plan for approval (shows approval UI) */
-    onPlanSubmit: (info: PlanSubmitInfo) => Promise<PlanSubmitResult>;
+    onPlanSubmit?: (info: PlanSubmitInfo) => Promise<PlanSubmitResult>;
     /** Called when agent wants to exit plan mode without a plan */
-    onPlanModeExit: (info: PlanModeExitInfo) => Promise<void>;
+    onPlanModeExit?: (info: PlanModeExitInfo) => Promise<void>;
+    /** Check if plan mode is currently active (used to guard plan_update from self-approval) */
+    isPlanModeActive?: () => boolean;
 }
 /**
  * System prompt section injected when plan mode is active.

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.14",
+  "version": "0.9.16",
   "description": "Universal agent runtime for building AI-powered applications",
   "type": "module",
   "main": "dist/index.js",
@@ -62,6 +62,9 @@
     "better-sqlite3": "^11.0.0 || ^12.0.0"
   },
   "peerDependenciesMeta": {
+    "@compilr-dev/agents-coding": {
+      "optional": true
+    },
     "better-sqlite3": {
       "optional": true
     }