@compilr-dev/sdk 0.2.11 → 0.2.13

package/dist/agent.js

@@ -118,6 +118,7 @@ class CompilrAgentImpl {
             provider,
             systemPrompt,
             maxIterations: config?.maxIterations ?? 50,
+            toolTimeoutMs: config?.toolTimeoutMs,
             contextManager,
             autoContextManagement: contextManager !== undefined,
             hooks: config?.hooks,

package/dist/config.d.ts

@@ -141,6 +141,8 @@ export interface CompilrAgentConfig {
     includeDefaultRules?: boolean;
     /** Guardrail configuration. Default: true */
     guardrails?: boolean | GuardrailConfig;
+    /** Tool execution timeout in milliseconds. 0 = no timeout. Default: 30000 (30s) */
+    toolTimeoutMs?: number;
     /** Lifecycle hooks */
     hooks?: HooksConfig;
     /** Context management configuration */

package/dist/index.d.ts

@@ -56,6 +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, IProjectRepository, IWorkItemRepository, IDocumentRepository, IPlanRepository, IAnchorService, IArtifactService, IEpisodeService, AnchorData, ArtifactType, ArtifactData, ArtifactSummaryData, WorkEpisode, ProjectWorkSummary, PlatformContext, PlatformToolsConfig, PlatformHooks, StepCriteria, } from './platform/index.js';
 export { createSQLiteRepositories, SQLiteProjectRepository, SQLiteWorkItemRepository, SQLiteDocumentRepository, SQLitePlanRepository, getDatabase, closeDatabase, closeAllDatabases, databaseExists, SCHEMA_VERSION, SCHEMA_SQL, } from './platform/index.js';
 export type { SQLiteRepositories, CreateSQLiteRepositoriesOptions, ProjectDeleteHooks, ProjectRecord, WorkItemRecord, ProjectDocumentRecord, } 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 { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, createAnchorTools, createArtifactTools, createEpisodeTools, ProjectAnchorStore, } from './platform/index.js';
 export type { ProjectAnchorStoreConfig } from './platform/index.js';
 export { STEP_ORDER, GUIDED_STEP_CRITERIA, getNextStep, isValidTransition, getStepCriteria, formatStepDisplay, getStepNumber, } from './platform/index.js';

package/dist/index.js

@@ -117,6 +117,10 @@ shouldIncludeModule, getEstimatedTokensForConditions, getTotalEstimatedTokens, }
 // =============================================================================
 export { createSQLiteRepositories, SQLiteProjectRepository, SQLiteWorkItemRepository, SQLiteDocumentRepository, SQLitePlanRepository, getDatabase, closeDatabase, closeAllDatabases, databaseExists, SCHEMA_VERSION, SCHEMA_SQL, } from './platform/index.js';
 // =============================================================================
+// User Interaction Tools (ask_user, ask_user_simple)
+// =============================================================================
+export { createAskUserTool, createAskUserSimpleTool, } from './tools/index.js';
+// =============================================================================
 // Platform Tools (runtime — createPlatformTools factory + individual factories)
 // =============================================================================
 export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, createAnchorTools, createArtifactTools, createEpisodeTools, ProjectAnchorStore, } from './platform/index.js';

package/dist/tools/ask-user-tools.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Ask User Tools — Agent tools for gathering user input
+ *
+ * Two tools:
+ *   - ask_user: Structured multi-question batches (1-5 questions)
+ *   - ask_user_simple: Single question with flat schema (easier for small models)
+ *
+ * Both use a factory pattern: the consumer (CLI, desktop app) provides a handler
+ * callback that implements the actual UI. The SDK defines the tool schemas and
+ * types as the single source of truth.
+ */
+import type { Tool } from '@compilr-dev/agents';
+/** A single question in an ask_user batch */
+export interface AskUserQuestion {
+    /** Unique identifier for the question (e.g., "app_type", "target_users") */
+    id: string;
+    /** Short label for tab/step display (e.g., "App Type") — max 12 chars */
+    header: string;
+    /** The question text */
+    question: string;
+    /** Predefined options (optional — if omitted, free-text only) */
+    options?: string[];
+    /** Allow free-text input (default: true) */
+    allowCustom?: boolean;
+    /** Allow multiple selections (default: false) */
+    multiSelect?: boolean;
+}
+/** Input parameters for ask_user tool */
+export interface AskUserInput {
+    /** 1-5 questions to ask */
+    questions: AskUserQuestion[];
+    /** Optional context shown above questions */
+    context?: string;
+}
+/** Result from ask_user tool */
+export interface AskUserResult {
+    /** Answers keyed by question ID */
+    answers: Record<string, string | string[]>;
+    /** Question IDs that were skipped */
+    skipped: string[];
+}
+/**
+ * Handler callback for ask_user tool.
+ * The consumer provides the UI implementation.
+ */
+export type AskUserHandler = (input: AskUserInput) => Promise<AskUserResult>;
+/** Input parameters for ask_user_simple tool */
+export interface AskUserSimpleInput {
+    /** The question text */
+    question: string;
+    /** Predefined options (optional, max 5) */
+    options?: string[];
+    /** Allow free-text input (default: true) */
+    allowCustom?: boolean;
+}
+/** Result from ask_user_simple tool */
+export interface AskUserSimpleResult {
+    /** User's answer */
+    answer: string;
+    /** True if user skipped the question */
+    skipped: boolean;
+}
+/**
+ * Handler callback for ask_user_simple tool.
+ * The consumer provides the UI implementation.
+ */
+export type AskUserSimpleHandler = (input: AskUserSimpleInput) => Promise<AskUserSimpleResult>;
+/**
+ * Create an ask_user tool with a custom UI handler.
+ *
+ * @example
+ * ```typescript
+ * // CLI: show terminal overlay
+ * const askUser = createAskUserTool(async (input) => {
+ *   const overlay = new AskUserOverlay(input);
+ *   return await ui.showOverlay(overlay);
+ * });
+ *
+ * // Desktop: send IPC to renderer
+ * const askUser = createAskUserTool(async (input) => {
+ *   return await sendToRenderer('ask-user', input);
+ * });
+ * ```
+ */
+export declare function createAskUserTool(handler: AskUserHandler): Tool<AskUserInput>;
+/**
+ * Create an ask_user_simple tool with a custom UI handler.
+ *
+ * @example
+ * ```typescript
+ * const askSimple = createAskUserSimpleTool(async (input) => {
+ *   const overlay = new AskUserSimpleOverlay(input);
+ *   return await ui.showOverlay(overlay);
+ * });
+ * ```
+ */
+export declare function createAskUserSimpleTool(handler: AskUserSimpleHandler): Tool<AskUserSimpleInput>;

package/dist/tools/ask-user-tools.js

@@ -0,0 +1,169 @@
+/**
+ * Ask User Tools — Agent tools for gathering user input
+ *
+ * Two tools:
+ *   - ask_user: Structured multi-question batches (1-5 questions)
+ *   - ask_user_simple: Single question with flat schema (easier for small models)
+ *
+ * Both use a factory pattern: the consumer (CLI, desktop app) provides a handler
+ * callback that implements the actual UI. The SDK defines the tool schemas and
+ * types as the single source of truth.
+ */
+import { defineTool } from '@compilr-dev/agents';
+// =============================================================================
+// Factory — ask_user
+// =============================================================================
+/**
+ * Create an ask_user tool with a custom UI handler.
+ *
+ * @example
+ * ```typescript
+ * // CLI: show terminal overlay
+ * const askUser = createAskUserTool(async (input) => {
+ *   const overlay = new AskUserOverlay(input);
+ *   return await ui.showOverlay(overlay);
+ * });
+ *
+ * // Desktop: send IPC to renderer
+ * const askUser = createAskUserTool(async (input) => {
+ *   return await sendToRenderer('ask-user', input);
+ * });
+ * ```
+ */
+export function createAskUserTool(handler) {
+    return defineTool({
+        name: 'ask_user',
+        description: 'Ask the user structured questions. ' +
+            'Present 1-5 questions with optional predefined answers. ' +
+            'Each question can have options to choose from or allow free-text input. ' +
+            'Use this during design/refine phases to gather requirements efficiently.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                questions: {
+                    type: 'array',
+                    description: 'Questions to ask the user (1-5 questions)',
+                    minItems: 1,
+                    maxItems: 5,
+                    items: {
+                        type: 'object',
+                        properties: {
+                            id: {
+                                type: 'string',
+                                description: 'Unique identifier for the question',
+                            },
+                            header: {
+                                type: 'string',
+                                description: 'Short label for tab/step display (max 12 chars)',
+                            },
+                            question: {
+                                type: 'string',
+                                description: 'The question text',
+                            },
+                            options: {
+                                type: 'array',
+                                description: 'Predefined options (optional)',
+                                items: { type: 'string' },
+                            },
+                            allowCustom: {
+                                type: 'boolean',
+                                description: 'Allow free-text input (default: true)',
+                            },
+                            multiSelect: {
+                                type: 'boolean',
+                                description: 'Allow multiple selections (default: false)',
+                            },
+                        },
+                        required: ['id', 'header', 'question'],
+                    },
+                },
+                context: {
+                    type: 'string',
+                    description: 'Optional context shown above questions',
+                },
+            },
+            required: ['questions'],
+        },
+        execute: async (input) => {
+            try {
+                if (input.questions.length === 0) {
+                    return { success: false, error: 'At least one question is required' };
+                }
+                if (input.questions.length > 5) {
+                    return { success: false, error: 'Maximum 5 questions allowed' };
+                }
+                const result = await handler(input);
+                return { success: true, result };
+            }
+            catch (err) {
+                return {
+                    success: false,
+                    error: `Failed to ask user: ${err instanceof Error ? err.message : String(err)}`,
+                };
+            }
+        },
+        silent: true,
+    });
+}
+// =============================================================================
+// Factory — ask_user_simple
+// =============================================================================
+/**
+ * Create an ask_user_simple tool with a custom UI handler.
+ *
+ * @example
+ * ```typescript
+ * const askSimple = createAskUserSimpleTool(async (input) => {
+ *   const overlay = new AskUserSimpleOverlay(input);
+ *   return await ui.showOverlay(overlay);
+ * });
+ * ```
+ */
+export function createAskUserSimpleTool(handler) {
+    return defineTool({
+        name: 'ask_user_simple',
+        description: 'Ask the user a single question. ' +
+            'Provide optional predefined choices or allow free-text input. ' +
+            'Use this for simple question flows — one question at a time. ' +
+            'Preferred over ask_user for single questions and smaller models.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                question: {
+                    type: 'string',
+                    description: 'The question to ask the user',
+                },
+                options: {
+                    type: 'array',
+                    description: 'Predefined options for the user to choose from (max 5)',
+                    items: { type: 'string' },
+                    maxItems: 5,
+                },
+                allowCustom: {
+                    type: 'boolean',
+                    description: 'Allow free-text input in addition to options (default: true)',
+                },
+            },
+            required: ['question'],
+        },
+        execute: async (input) => {
+            try {
+                if (!input.question || input.question.trim().length === 0) {
+                    return { success: false, error: 'Question text is required' };
+                }
+                if (input.options && input.options.length > 5) {
+                    return { success: false, error: 'Maximum 5 options allowed' };
+                }
+                const result = await handler(input);
+                return { success: true, result };
+            }
+            catch (err) {
+                return {
+                    success: false,
+                    error: `Failed to ask user: ${err instanceof Error ? err.message : String(err)}`,
+                };
+            }
+        },
+        silent: true,
+    });
+}

package/dist/tools/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Tools — Reusable tool factories for CLI and desktop consumers.
+ *
+ * These tools require a UI handler callback from the consumer.
+ * The SDK defines schemas and types; consumers provide the UI.
+ */
+export { createAskUserTool, createAskUserSimpleTool, } from './ask-user-tools.js';
+export type { AskUserQuestion, AskUserInput, AskUserResult, AskUserHandler, AskUserSimpleInput, AskUserSimpleResult, AskUserSimpleHandler, } from './ask-user-tools.js';

package/dist/tools/index.js

@@ -0,0 +1,7 @@
+/**
+ * Tools — Reusable tool factories for CLI and desktop consumers.
+ *
+ * These tools require a UI handler callback from the consumer.
+ * The SDK defines schemas and types; consumers provide the UI.
+ */
+export { createAskUserTool, createAskUserSimpleTool, } from './ask-user-tools.js';

package/package.json

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