@compilr-dev/sdk 0.9.15 → 0.9.17

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/entitlements/cache.d.ts

@@ -0,0 +1,84 @@
+/**
+ * EntitlementCache — In-memory cache for server-driven entitlements.
+ *
+ * The server is the single source of truth. This cache:
+ * 1. Fetches entitlements from the server on first access
+ * 2. Caches in memory with a configurable TTL (default: 1 hour)
+ * 3. Falls back to encrypted offline backup if server is unreachable
+ * 4. Degrades to minimal fallback limits after offline grace period expires
+ *
+ * The host app (Desktop/CLI) provides:
+ * - fetchFn: how to call the server endpoint
+ * - store (optional): encrypted persistence for offline grace (IEntitlementStore)
+ */
+import type { TierLimits, EntitlementResponse, LimitCheckResult } from './types.js';
+/**
+ * Persistence adapter for offline grace period.
+ * Desktop: Electron safeStorage. CLI: encrypted file.
+ */
+export interface IEntitlementStore {
+    /** Save encrypted entitlement data */
+    save(data: string): Promise<void>;
+    /** Load encrypted entitlement data (null if not found) */
+    load(): Promise<string | null>;
+}
+export interface EntitlementCacheConfig {
+    /** How to fetch entitlements from the server */
+    fetchFn: () => Promise<EntitlementResponse>;
+    /** Optional encrypted persistence for offline grace */
+    store?: IEntitlementStore;
+    /** Cache TTL in milliseconds (default: 1 hour) */
+    ttlMs?: number;
+    /** Offline grace period in milliseconds (default: 24 hours) */
+    offlineGraceMs?: number;
+    /** Called when entitlements are refreshed (for logging, UI updates) */
+    onRefresh?: (response: EntitlementResponse) => void;
+}
+export declare class EntitlementCache {
+    private entitlements;
+    private fetchedAtMonotonic;
+    private fetchedAtWall;
+    private readonly fetchFn;
+    private readonly store?;
+    private readonly ttlMs;
+    private readonly offlineGraceMs;
+    private readonly onRefresh?;
+    private fetchPromise;
+    constructor(config: EntitlementCacheConfig);
+    /**
+     * Get current tier limits. Fetches from server if stale, falls back to cache/store/defaults.
+     */
+    get(): Promise<TierLimits>;
+    /**
+     * Get the full entitlement response (tier, beta, features, etc.)
+     */
+    getResponse(): Promise<EntitlementResponse | null>;
+    /**
+     * Check if a numeric limit is exceeded.
+     */
+    checkLimit(field: keyof TierLimits, currentCount: number): LimitCheckResult;
+    /**
+     * Check if a feature flag is enabled for the current user.
+     */
+    isFeatureEnabled(featureSlug: string): boolean;
+    /**
+     * Whether the user is in beta mode (all features unlocked).
+     */
+    isBeta(): boolean;
+    /**
+     * Current tier name.
+     */
+    getTier(): string;
+    /**
+     * Force a refresh from the server (e.g., after login, after subscription change).
+     */
+    refresh(): Promise<TierLimits>;
+    /**
+     * Clear the cache (e.g., on logout).
+     */
+    clear(): void;
+    private isFresh;
+    private isWithinOfflineGrace;
+    private fetchAndCache;
+    private fallback;
+}

package/dist/entitlements/cache.js

@@ -0,0 +1,185 @@
+/**
+ * EntitlementCache — In-memory cache for server-driven entitlements.
+ *
+ * The server is the single source of truth. This cache:
+ * 1. Fetches entitlements from the server on first access
+ * 2. Caches in memory with a configurable TTL (default: 1 hour)
+ * 3. Falls back to encrypted offline backup if server is unreachable
+ * 4. Degrades to minimal fallback limits after offline grace period expires
+ *
+ * The host app (Desktop/CLI) provides:
+ * - fetchFn: how to call the server endpoint
+ * - store (optional): encrypted persistence for offline grace (IEntitlementStore)
+ */
+import { UNLIMITED, OFFLINE_FALLBACK_LIMITS } from './types.js';
+// =============================================================================
+// Cache Implementation
+// =============================================================================
+const DEFAULT_TTL_MS = 60 * 60 * 1000; // 1 hour
+const DEFAULT_OFFLINE_GRACE_MS = 24 * 60 * 60 * 1000; // 24 hours
+export class EntitlementCache {
+    entitlements = null;
+    fetchedAtMonotonic = 0n; // process.hrtime.bigint() — monotonic, not clockable
+    fetchedAtWall = 0; // Date.now() — for serialization only
+    fetchFn;
+    store;
+    ttlMs;
+    offlineGraceMs;
+    onRefresh;
+    fetchPromise = null; // Dedup concurrent fetches
+    constructor(config) {
+        this.fetchFn = config.fetchFn;
+        this.store = config.store;
+        this.ttlMs = config.ttlMs ?? DEFAULT_TTL_MS;
+        this.offlineGraceMs = config.offlineGraceMs ?? DEFAULT_OFFLINE_GRACE_MS;
+        this.onRefresh = config.onRefresh;
+    }
+    /**
+     * Get current tier limits. Fetches from server if stale, falls back to cache/store/defaults.
+     */
+    async get() {
+        // Fresh cache → return immediately
+        if (this.entitlements && this.isFresh()) {
+            return this.entitlements.limits;
+        }
+        // Dedup concurrent fetch calls
+        if (this.fetchPromise)
+            return this.fetchPromise;
+        this.fetchPromise = this.fetchAndCache();
+        try {
+            return await this.fetchPromise;
+        }
+        finally {
+            this.fetchPromise = null;
+        }
+    }
+    /**
+     * Get the full entitlement response (tier, beta, features, etc.)
+     */
+    async getResponse() {
+        await this.get(); // Ensure cache is populated
+        return this.entitlements;
+    }
+    /**
+     * Check if a numeric limit is exceeded.
+     */
+    checkLimit(field, currentCount) {
+        if (!this.entitlements) {
+            return { allowed: true }; // No entitlements loaded yet — allow (fail open during init)
+        }
+        const limit = this.entitlements.limits[field];
+        // Unlimited
+        if (limit === UNLIMITED) {
+            return { allowed: true };
+        }
+        if (currentCount >= limit) {
+            return {
+                allowed: false,
+                reason: `Limit reached (${String(currentCount)}/${String(limit)})`,
+                upgradeHint: this.entitlements.beta
+                    ? undefined // No upgrade prompt during beta
+                    : 'Upgrade to Pro for unlimited access',
+                current: currentCount,
+                limit,
+            };
+        }
+        return { allowed: true, current: currentCount, limit };
+    }
+    /**
+     * Check if a feature flag is enabled for the current user.
+     */
+    isFeatureEnabled(featureSlug) {
+        if (!this.entitlements)
+            return true; // Fail open during init
+        return featureSlug in this.entitlements.features
+            ? this.entitlements.features[featureSlug]
+            : true; // Default: enabled if not explicitly listed
+    }
+    /**
+     * Whether the user is in beta mode (all features unlocked).
+     */
+    isBeta() {
+        return this.entitlements?.beta ?? false;
+    }
+    /**
+     * Current tier name.
+     */
+    getTier() {
+        return this.entitlements?.tier ?? 'free';
+    }
+    /**
+     * Force a refresh from the server (e.g., after login, after subscription change).
+     */
+    async refresh() {
+        this.fetchPromise = null; // Clear any pending dedup
+        return this.fetchAndCache();
+    }
+    /**
+     * Clear the cache (e.g., on logout).
+     */
+    clear() {
+        this.entitlements = null;
+        this.fetchedAtMonotonic = 0n;
+        this.fetchedAtWall = 0;
+        this.fetchPromise = null;
+    }
+    // ─── Private ───────────────────────────────────────────────────────────────
+    isFresh() {
+        if (this.fetchedAtMonotonic === 0n)
+            return false;
+        const elapsed = process.hrtime.bigint() - this.fetchedAtMonotonic;
+        return elapsed < BigInt(this.ttlMs) * 1000000n; // Convert ms to ns
+    }
+    isWithinOfflineGrace() {
+        if (this.fetchedAtMonotonic === 0n)
+            return false;
+        const elapsed = process.hrtime.bigint() - this.fetchedAtMonotonic;
+        return elapsed < BigInt(this.offlineGraceMs) * 1000000n;
+    }
+    async fetchAndCache() {
+        try {
+            const response = await this.fetchFn();
+            this.entitlements = response;
+            this.fetchedAtMonotonic = process.hrtime.bigint();
+            this.fetchedAtWall = Date.now();
+            // Persist encrypted for offline grace
+            if (this.store) {
+                const serialized = JSON.stringify({ response, fetchedAtWall: this.fetchedAtWall });
+                await this.store.save(serialized).catch(() => { }); // Best effort
+            }
+            this.onRefresh?.(response);
+            return response.limits;
+        }
+        catch {
+            // Server unreachable — try fallbacks
+            return this.fallback();
+        }
+    }
+    async fallback() {
+        // 1. Stale in-memory cache within offline grace
+        if (this.entitlements && this.isWithinOfflineGrace()) {
+            return this.entitlements.limits;
+        }
+        // 2. Encrypted store backup
+        if (this.store) {
+            try {
+                const stored = await this.store.load();
+                if (stored) {
+                    const parsed = JSON.parse(stored);
+                    const age = Date.now() - parsed.fetchedAtWall;
+                    if (age < this.offlineGraceMs) {
+                        this.entitlements = parsed.response;
+                        this.fetchedAtMonotonic = process.hrtime.bigint(); // Reset monotonic to now
+                        this.fetchedAtWall = parsed.fetchedAtWall;
+                        return this.entitlements.limits;
+                    }
+                }
+            }
+            catch {
+                // Corrupted store — fall through to defaults
+            }
+        }
+        // 3. Offline grace expired or no store — degrade to minimal fallback
+        return OFFLINE_FALLBACK_LIMITS;
+    }
+}

package/dist/entitlements/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Entitlements — Server-driven tier management for pricing.
+ */
+export type { TierLimits, EntitlementResponse, LimitCheckResult, } from './types.js';
+export { UNLIMITED, OFFLINE_FALLBACK_LIMITS, } from './types.js';
+export type { IEntitlementStore, EntitlementCacheConfig, } from './cache.js';
+export { EntitlementCache } from './cache.js';

package/dist/entitlements/index.js

@@ -0,0 +1,5 @@
+/**
+ * Entitlements — Server-driven tier management for pricing.
+ */
+export { UNLIMITED, OFFLINE_FALLBACK_LIMITS, } from './types.js';
+export { EntitlementCache } from './cache.js';

package/dist/entitlements/types.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Entitlement Types — Shared between server, SDK, Desktop, and CLI.
+ *
+ * TierLimits values: -1 = unlimited, 0+ = actual limit.
+ */
+/** Numeric limits for a tier. All values server-driven — never hardcoded in app logic. */
+export interface TierLimits {
+    maxProjects: number;
+    maxTeamAgents: number;
+    maxCustomAgents: number;
+    maxTemplates: number;
+    maxBackgroundTasks: number;
+    maxMcpServers: number;
+    maxKnowledgeDocs: number;
+    maxConversationsPerDay: number;
+    maxAgentMessagesPerDay: number;
+    maxScaffoldToolkits: number;
+}
+/** Response from the cli-entitlements endpoint */
+export interface EntitlementResponse {
+    tier: string;
+    beta: boolean;
+    limits: TierLimits;
+    pendingPayment: boolean;
+    trialEndsAt: string | null;
+    features: Record<string, boolean>;
+    issuedAt: string;
+    userId: string;
+    signature: string;
+}
+/** Result of checking a limit */
+export interface LimitCheckResult {
+    allowed: boolean;
+    reason?: string;
+    upgradeHint?: string;
+    current?: number;
+    limit?: number;
+}
+/** Sentinel value for unlimited */
+export declare const UNLIMITED = -1;
+/**
+ * Minimal fallback limits when server is unreachable AND no cached entitlements exist.
+ * Intentionally restrictive to push the user to connect.
+ */
+export declare const OFFLINE_FALLBACK_LIMITS: TierLimits;

package/dist/entitlements/types.js

@@ -0,0 +1,23 @@
+/**
+ * Entitlement Types — Shared between server, SDK, Desktop, and CLI.
+ *
+ * TierLimits values: -1 = unlimited, 0+ = actual limit.
+ */
+/** Sentinel value for unlimited */
+export const UNLIMITED = -1;
+/**
+ * Minimal fallback limits when server is unreachable AND no cached entitlements exist.
+ * Intentionally restrictive to push the user to connect.
+ */
+export const OFFLINE_FALLBACK_LIMITS = {
+    maxProjects: 1,
+    maxTeamAgents: 1,
+    maxCustomAgents: 0,
+    maxTemplates: 0,
+    maxBackgroundTasks: 0,
+    maxMcpServers: 0,
+    maxKnowledgeDocs: 0,
+    maxConversationsPerDay: 5,
+    maxAgentMessagesPerDay: 20,
+    maxScaffoldToolkits: 0,
+};

package/dist/index.d.ts

@@ -56,8 +56,10 @@ 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 { EntitlementCache, UNLIMITED, OFFLINE_FALLBACK_LIMITS } from './entitlements/index.js';
+export type { TierLimits, EntitlementResponse, LimitCheckResult, IEntitlementStore, EntitlementCacheConfig, } from './entitlements/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,11 @@ 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';
+// =============================================================================
+// Entitlements (server-driven tier management)
+// =============================================================================
+export { EntitlementCache, UNLIMITED, OFFLINE_FALLBACK_LIMITS } from './entitlements/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.17",
   "description": "Universal agent runtime for building AI-powered applications",
   "type": "module",
   "main": "dist/index.js",