@aiderdesk/aiderdesk 0.61.0-dev → 0.61.1

package/out/resources/skills/extension-creator/references/extension-interface.md

@@ -0,0 +1,240 @@
+# Extension Interface
+
+Full TypeScript interface for AiderDesk extensions.
+
+## Extension Interface
+
+```typescript
+interface Extension {
+  // Lifecycle
+  onLoad?(context: ExtensionContext): Promise<void> | void;
+  onUnload?(context: ExtensionContext): Promise<void> | void;
+
+  // Registration
+  getCommands?(context: ExtensionContext): CommandDefinition[];
+  getTools?(context: ExtensionContext, mode: string, agentProfile: AgentProfile): ToolDefinition[];
+  getAgents?(context: ExtensionContext): AgentProfile[];
+  getModes?(context: ExtensionContext): ModeDefinition[];
+  getUIComponents?(context: ExtensionContext): UIComponentDefinition[];
+  
+  // UI Component support
+  getUIExtensionData?(componentId: string, context: ExtensionContext): Promise<unknown>;
+  executeUIExtensionAction?(componentId: string, action: string, args: unknown[], context: ExtensionContext): Promise<unknown>;
+
+  // Settings configuration (per-extension settings UI)
+  getConfigComponent?(context: ExtensionContext): string | undefined;
+  getConfigData?(context: ExtensionContext): Promise<unknown>;
+  saveConfigData?(configData: unknown, context: ExtensionContext): Promise<unknown>;
+
+  // Task Events
+  onTaskCreated?(event: TaskCreatedEvent, context: ExtensionContext): Promise<void | Partial<TaskCreatedEvent>>;
+  onTaskInitialized?(event: TaskInitializedEvent, context: ExtensionContext): Promise<void>;
+  onTaskClosed?(event: TaskClosedEvent, context: ExtensionContext): Promise<void>;
+
+  // Agent Events
+  onAgentStarted?(event: AgentStartedEvent, context: ExtensionContext): Promise<void | Partial<AgentStartedEvent>>;
+  onAgentFinished?(event: AgentFinishedEvent, context: ExtensionContext): Promise<void | Partial<AgentFinishedEvent>>;
+  onAgentStepFinished?(event: AgentStepFinishedEvent, context: ExtensionContext): Promise<void | Partial<AgentStepFinishedEvent>>;
+  onAgentProfileUpdated?(context: ExtensionContext, agentId: string, updatedProfile: AgentProfile): Promise<AgentProfile>;
+
+  // Tool Events
+  onToolApproval?(event: ToolApprovalEvent, context: ExtensionContext): Promise<void | Partial<ToolApprovalEvent>>;
+  onToolCalled?(event: ToolCalledEvent, context: ExtensionContext): Promise<void | Partial<ToolCalledEvent>>;
+  onToolFinished?(event: ToolFinishedEvent, context: ExtensionContext): Promise<void | Partial<ToolFinishedEvent>>;
+
+  // File Events
+  onFileAdded?(event: FileAddedEvent, context: ExtensionContext): Promise<void>;
+  onFileDropped?(event: FileDroppedEvent, context: ExtensionContext): Promise<void>;
+
+  // Prompt Events
+  onPromptSubmitted?(event: PromptSubmittedEvent, context: ExtensionContext): Promise<void | Partial<PromptSubmittedEvent>>;
+  onPromptStarted?(event: PromptStartedEvent, context: ExtensionContext): Promise<void>;
+  onPromptFinished?(event: PromptFinishedEvent, context: ExtensionContext): Promise<void>;
+
+  // Message Events
+  onResponseMessageProcessed?(event: ResponseMessageProcessedEvent, context: ExtensionContext): Promise<void | Partial<ResponseMessageProcessedEvent>>;
+
+  // Other Events
+  onProjectOpen?(context: ExtensionContext): Promise<void>;
+  onRuleFilesRetrieved?(context: ExtensionContext, ruleFiles: string[]): Promise<string[]>;
+  onSubagentStarted?(event: SubagentStartedEvent, context: ExtensionContext): Promise<void | Partial<SubagentStartedEvent>>;
+  onSubagentFinished?(event: SubagentFinishedEvent, context: ExtensionContext): Promise<void>;
+  onQuestionAsked?(event: QuestionAskedEvent, context: ExtensionContext): Promise<void>;
+  onQuestionAnswered?(event: QuestionAnsweredEvent, context: ExtensionContext): Promise<void>;
+  onCommandExecuted?(event: CommandExecutedEvent, context: ExtensionContext): Promise<void>;
+}
+```
+
+## ExtensionContext
+
+```typescript
+interface ExtensionContext {
+  // Logging (backend/dev console only — NOT visible to users in chat UI)
+  log(message: string, type: 'info' | 'error' | 'warn' | 'debug'): void;
+
+  // Project access
+  getProjectDir(): string;
+  getTaskContext(): TaskContext | null;
+  getProjectContext(): ProjectContext;
+
+  // Settings
+  getSetting(key: string): Promise<unknown>;
+  updateSettings(updates: Record<string, unknown>): Promise<void>;
+
+  // Models
+  getModelConfigs(): Promise<Model[]>;
+  
+  // UI updates
+  triggerUIDataRefresh(componentId?: string, taskId?: string): void;
+  triggerUIComponentsReload(): void;
+  
+  // Navigation
+  openUrl(url: string, target?: 'external' | 'window' | 'modal-overlay'): Promise<void>;
+  openPath(path: string): Promise<boolean>;
+}
+```
+
+## TaskContext
+
+```typescript
+interface TaskContext {
+  // Logging to chat (visible to users in the task's chat UI)
+  addLogMessage(level: 'info' | 'error' | 'warning', message?: string): void;
+  addLoadingMessage(message?: string, finished?: boolean): void;
+
+  // Task operations
+  updateTask(updates: Partial<TaskData>): Promise<TaskData>;
+  runPrompt(prompt: string, mode?: string): Promise<void>;
+  runCustomCommand(name: string, args?: string[], mode?: string): Promise<void>;
+  runSubagent(agentProfile: AgentProfile, prompt: string): Promise<void>;
+  interruptResponse(): Promise<void>;
+
+  // File operations
+  getRepoMap(): string;
+  getContextFiles(): ContextFile[];
+  addContextFiles(files: ContextFile[]): Promise<void>;
+
+  // Questions
+  askQuestion(text: string, options?: QuestionOptions): Promise<string>;
+}
+```
+
+## UIComponentDefinition
+
+```typescript
+interface UIComponentDefinition {
+  /** Unique component identifier */
+  id: string;
+  
+  /** Where in UI to render this component */
+  placement: UIComponentPlacement;
+  
+  /** JSX/TSX component as string to be parsed */
+  jsx: string;
+  
+  /** Optional flag to load data from extension (default: false) */
+  loadData?: boolean;
+  
+  /** Optional flag to disable data caching (default: false) */
+  noDataCache?: boolean;
+}
+
+type UIComponentPlacement =
+  | 'task-status-bar-left'
+  | 'task-status-bar-right'
+  | 'task-usage-info-bottom'
+  | 'task-messages-top'
+  | 'task-messages-bottom'
+  | 'task-input-above'
+  | 'task-input-toolbar-left'
+  | 'task-input-toolbar-right'
+  | 'tasks-sidebar-header'
+  | 'tasks-sidebar-bottom'
+  | 'task-message-above'
+  | 'task-message-below'
+  | 'task-message-bar'
+  | 'task-top-bar-left'
+  | 'task-top-bar-right'
+  | 'task-state-actions'
+  | 'task-state-actions-all'
+  | 'header-left'
+  | 'header-right'
+  | 'welcome-page';
+```
+
+## UIComponentProps
+
+Props available to UI components via the `data` prop (React is globally available, not a prop):
+
+```typescript
+interface UIComponentProps {
+  // Context data
+  projectDir?: string;
+  task?: TaskData;
+  agentProfile?: AgentProfile;
+  models: Model[];
+  providers: ProviderProfile[];
+  
+  // UI library
+  ui: UIComponents;
+  
+  // Icons library (organized by icon set)
+  icons: Record<string, Record<string, IconComponent>>;
+  
+  // Extension actions
+  executeExtensionAction: (action: string, ...args: unknown[]) => Promise<unknown>;
+  
+  // Data from getUIExtensionData() (if loadData: true)
+  data?: unknown;
+  
+  // Message-specific (for message placements)
+  message?: MessageData;
+}
+
+interface UIComponents {
+  Button: Component;
+  Checkbox: Component;
+  Input: Component;
+  Select: Component;
+  TextArea: Component;
+  IconButton: Component;
+  RadioButton: Component;
+  MultiSelect: Component;
+  Slider: Component;
+  DatePicker: Component;
+  Chip: Component;
+  ModelSelector: Component;
+  Tooltip: Component;
+  LoadingOverlay: Component;
+  ConfirmDialog: Component;
+}
+```
+
+## Metadata
+
+Metadata is defined as a **static property** on the extension class:
+
+```typescript
+export default class MyExtension implements Extension {
+  static metadata = {
+    name: 'My Extension',
+    version: '1.0.0',
+    description: 'What this extension does',
+    author: 'Author Name',
+    capabilities: ['events', 'commands'],
+  };
+}
+```
+
+**Important:** Metadata must be a `static` property on the class. Do NOT use a separate `export const metadata = { ... }` — the extension loader reads it from `ExtensionClass.metadata`.
+
+```typescript
+interface ExtensionMetadata {
+  name: string;
+  version: string;
+  description?: string;
+  author?: string;
+  capabilities?: string[];
+  iconUrl?: string;
+}
+```

package/out/resources/skills/extension-creator/references/extension-types.md

@@ -0,0 +1,186 @@
+# Extension Types
+
+AiderDesk supports two types of extensions: single-file and folder extensions.
+
+## Single-File Extensions
+
+**When to use:** Simple extensions with no npm dependencies
+
+**Location:** `packages/extensions/extensions/my-extension.ts`
+
+**Structure:**
+```typescript
+import type { Extension, ExtensionContext } from '@aiderdesk/extensions';
+
+export default class MyExtension implements Extension {
+  static metadata = {
+    name: 'My Extension',
+    version: '1.0.0',
+    description: 'What this extension does',
+    author: 'Author Name',
+    capabilities: ['events', 'commands'],
+  };
+
+  async onLoad(context: ExtensionContext): Promise<void> {
+    context.log('Extension loaded', 'info');
+  }
+}
+```
+
+**Advantages:**
+- Simple structure
+- Easy to maintain
+- No build step required
+
+**Limitations:**
+- Cannot use npm dependencies
+- All code in one file
+- No separate config or logger files
+
+## Folder Extensions
+
+**When to use:** Complex extensions with npm dependencies or multiple files
+
+**Location:** `packages/extensions/extensions/my-extension/`
+
+**Structure:**
+```
+packages/extensions/extensions/my-extension/
+├── index.ts           # Main extension file (implements Extension)
+├── package.json       # npm dependencies
+├── tsconfig.json      # TypeScript config (module: ES2020+)
+├── README.md          # Documentation
+├── config.ts          # Optional: persistent config storage
+├── logger.ts          # Optional: local logger
+├── constants.ts       # Optional: extension constants
+└── resources/         # Optional: WASM, queries, assets
+```
+
+**package.json:**
+```json
+{
+  "name": "my-extension",
+  "version": "1.0.0",
+  "main": "index.ts",
+  "dependencies": {
+    // Required packages
+  }
+}
+```
+
+**tsconfig.json:**
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ES2020",
+    "moduleResolution": "node",
+    "esModuleInterop": true,
+    "strict": true
+  }
+}
+```
+
+**Advantages:**
+- Can use npm dependencies
+- Modular structure
+- Separate config and logger files
+- Can include resources (WASM, queries, assets)
+
+**Requirements:**
+- Must have package.json
+- Must have tsconfig.json with ES2020+ module
+- Must set `hasDependencies: true` in extensions.json
+
+## Choosing Extension Type
+
+**When:** Extension needs npm packages
+
+**Then:** Use folder extension
+
+**When:** Extension is simple with no dependencies
+
+**Then:** Use single-file extension
+
+**When:** Extension needs multiple files
+
+**Then:** Use folder extension
+
+**When:** Extension needs resources (WASM, queries)
+
+**Then:** Use folder extension
+
+## Common Patterns by Type
+
+### Single-File: Simple Event Handler
+
+```typescript
+import type { Extension, ExtensionContext, AgentStartedEvent } from '@aiderdesk/extensions';
+
+export default class SimpleExtension implements Extension {
+  static metadata = {
+    name: 'Simple Extension',
+    version: '1.0.0',
+    description: 'Simple event handler',
+    author: 'Author Name',
+    capabilities: ['events'],
+  };
+
+  async onLoad(context: ExtensionContext): Promise<void> {
+    context.log('Simple extension loaded', 'info');
+  }
+
+  async onAgentStarted(
+    event: AgentStartedEvent,
+    context: ExtensionContext
+  ): Promise<void | Partial<AgentStartedEvent>> {
+    context.log('Agent started', 'info');
+    return { contextMessages: [...event.contextMessages] };
+  }
+}
+```
+
+### Folder: Extension with Config and Dependencies
+
+```
+tree-sitter-repo-map/
+├── index.ts           # Main extension with getTools()
+├── package.json       # tree-sitter dependencies
+├── tsconfig.json      # ES2020 module
+├── config.ts          # Config storage
+├── logger.ts          # Extension logger
+├── constants.ts       # Extension constants
+└── resources/
+    └── queries/       # Language queries
+```
+
+## Updating extensions.json
+
+### Single-File Entry
+
+```json
+{
+  "id": "my-extension",
+  "name": "My Extension",
+  "description": "Description of what it does",
+  "file": "extensions/my-extension.ts",
+  "type": "single",
+  "capabilities": ["onLoad", "onAgentStarted"]
+}
+```
+
+### Folder Entry
+
+```json
+{
+  "id": "my-extension",
+  "name": "My Extension",
+  "description": "Description",
+  "folder": "extensions/my-extension",
+  "type": "folder",
+  "hasDependencies": true,
+  "capabilities": ["onLoad", "getCommands", "onAgentStarted"]
+}
+```
+
+**Note:** Always set `hasDependencies: true` for folder extensions, even if they don't have dependencies yet. This ensures proper loading.

package/out/resources/skills/extension-creator/references/in-repo-flow.md

@@ -0,0 +1,132 @@
+# In-Repo Installation Flow
+
+This flow covers developing extensions **inside the AiderDesk codebase** at `packages/extensions/extensions/`. These extensions ship with the application and are available to all users by default.
+
+## When to Use This Flow
+
+Only when:
+1. The current working project **is** the AiderDesk repository itself
+2. The user explicitly chooses "In-Repo" as the installation target
+3. The extension is meant to be a built-in feature, not a personal or project-specific tool
+
+## Process
+
+1. **Determine extension type** — single-file or folder
+2. **Create extension file(s)** in `packages/extensions/extensions/`
+3. **Implement Extension interface methods**
+4. **Export metadata and default class**
+5. **Update `packages/extensions/extensions.json`** — register the extension
+6. **Update `docs-site/docs/extensions/examples.md`** — document it
+7. **Verify with type checking and code-checker**
+
+## Directory Structure
+
+### Single-File In-Repo Extension
+
+```
+packages/extensions/extensions/
+└── my-extension.ts                        # Everything in one file
+```
+
+### Folder In-Repo Extension
+
+```
+packages/extensions/extensions/
+└── my-extension/
+    ├── index.ts                           # Main extension file
+    ├── package.json                       # npm dependencies (must run npm install)
+    ├── tsconfig.json                      # TypeScript config (module: ES2020+)
+    ├── README.md                          # Documentation
+    ├── config.ts                          # Optional: persistent config storage
+    ├── logger.ts                          # Optional: local logger
+    ├── constants.ts                       # Optional: extension constants
+    └── resources/                         # Optional: WASM, queries, assets
+```
+
+## Step-by-Step
+
+### Step 1: Determine type
+
+- **Single-file**: No npm dependencies, simple logic
+- **Folder**: Needs npm packages, multiple files, resources
+
+### Step 2: Create the extension
+
+Use the templates:
+- [single-file.ts.template](../assets/templates/single-file.ts.template)
+- [folder-extension/](../assets/templates/folder-extension/)
+- [folder-extension-with-config/index.ts.template](../assets/templates/folder-extension-with-config/index.ts.template)
+
+Create files in `packages/extensions/extensions/{name}/` or `packages/extensions/extensions/{name}.ts`.
+
+### Step 3: Implement interface
+
+Same as any extension — implement required methods, export metadata and class.
+
+Reference: [extension-interface.md](extension-interface.md)
+
+### Step 4: Register in extensions.json
+
+**This step is unique to In-Repo extensions.**
+
+Add an entry to `packages/extensions/extensions.json`:
+
+**Single-file entry:**
+```json
+{
+  "id": "my-extension",
+  "name": "My Extension",
+  "description": "Description of what it does",
+  "file": "extensions/my-extension.ts",
+  "type": "single",
+  "capabilities": ["onLoad", "onAgentStarted"]
+}
+```
+
+**Folder entry:**
+```json
+{
+  "id": "my-extension",
+  "name": "My Extension",
+  "description": "Description",
+  "folder": "extensions/my-extension",
+  "type": "folder",
+  "hasDependencies": true,
+  "capabilities": ["onLoad", "getCommands", "onAgentStarted"]
+}
+```
+
+**Important:** Always set `hasDependencies: true` for folder extensions, even if they don't have dependencies yet.
+
+### Step 5: Document in examples.md
+
+Add an entry to the table in `docs-site/docs/extensions/examples.md`:
+
+| Extension | Description | Capabilities | Type |
+|-----------|-------------|-------------|------|
+| My Extension | What it does | events, commands | folder |
+
+Include extension name, description, capabilities, and type.
+
+### Step 6: Install dependencies (folder extensions only)
+
+If this is a folder extension with npm dependencies:
+
+```bash
+cd packages/extensions
+npm install
+```
+
+### Step 7: Verify
+
+- Run type checking: `npm run typecheck`
+- Run tests if applicable: `npm run test`
+- Verify extension loads without errors
+- Check that extension appears in extensions list
+
+## What NOT to do (In-Repo)
+
+- Do NOT use `@/` imports in extension files — use relative imports or `@aiderdesk/extensions` package imports only
+- Do NOT forget to update `extensions.json` — the extension won't load without registration
+- Do NOT forget to update `examples.md` — users won't know about the extension
+- Do NOT place files outside `packages/extensions/extensions/` unless there's a specific reason (e.g., shared utilities should go in `packages/extensions/src/`)

package/out/resources/skills/extension-creator/references/install-targets.md

@@ -0,0 +1,96 @@
+# Installation Targets
+
+AiderDesk extensions can be installed in three locations, each with different purposes and workflows.
+
+## Target Options
+
+### 1. Current Project (`.aider-desk/extensions/`)
+
+**Use when:** The extension is specific to this project and should travel with the codebase.
+
+**Location:** `{projectDir}/.aider-desk/extensions/`
+
+**Characteristics:**
+- Project-scoped: only available when working in this project
+- Committed to version control alongside the project
+- Shared with team members via git
+- No need to update any registry or manifest files
+- Simple drop-in: just create the file/folder in the directory
+
+**Best for:** Project-specific tools, domain-specific rules, team conventions, repo-specific integrations.
+
+---
+
+### 2. Global (`~/.aider-desk/extensions/`)
+
+**Use when:** The extension is a personal utility you want available across all projects.
+
+**Location:** `~/.aider-desk/extensions/`
+
+**Characteristics:**
+- User-scoped: available in every project you work on
+- Not committed to any repository (lives in home directory)
+- Private to your environment
+- No need to update any registry or manifest files
+- Simple drop-in: just create the file/folder in the directory
+
+**Best for:** Personal productivity tools, custom commands, cross-project utilities, personal preferences.
+
+---
+
+### 3. In-Repo (`packages/extensions/`) — **Only when working inside the AiderDesk project**
+
+**Use when:** You are developing an extension that ships *with* AiderDesk itself, as part of the application.
+
+**Location:** `packages/extensions/extensions/{name}/` or `packages/extensions/extensions/{name}.ts`
+
+**Characteristics:**
+- Ships with the AiderDesk application as a built-in extension
+- Available to all users by default
+- Requires updating `packages/extensions/extensions.json` (the extension registry)
+- Requires updating documentation in `docs-site/docs/extensions/examples.md`
+- Must follow monorepo conventions (no `@/` imports, proper tsconfig/package.json)
+- Subject to the full AiderDesk development workflow (type checking, testing, etc.)
+
+**Best for:** Core features, official integrations, extensions that should be available out-of-the-box.
+
+## How to Choose
+
+Ask the user at the start of every extension creation session:
+
+> "Where should this extension be installed? **Current project** (project-scoped, shared with team), **Global** (personal, available everywhere), or **In-Repo** (ships with AiderDesk, only available when working in the aider-desk project)?"
+
+**Decision tree:**
+
+```
+Is the current project the AiderDesk codebase itself?
+├── YES → Offer all 3 options (Project, Global, In-Repo)
+│         In-Repo means: packages/extensions/ + update extensions.json + update docs
+│
+└── NO  → Offer only 2 options (Project, Global)
+          Project = .aider-desk/extensions/ in current project
+          Global  = ~/.aider-desk/extensions/
+```
+
+## Key Differences Summary
+
+| Aspect | Project | Global | In-Repo |
+|--------|---------|--------|---------|
+| Location | `.aider-desk/extensions/` | `~/.aider-desk/extensions/` | `packages/extensions/extensions/` |
+| Scope | This project only | All projects | All users (ships with app) |
+| Version controlled | Yes (with project) | No | Yes (with AiderDesk) |
+| Update extensions.json | No | No | **Yes** |
+| Update examples.md docs | No | No | **Yes** |
+| npm install needed | No | No | **Yes** (if folder extension) |
+| Available immediately | Yes | Yes | After build/restart |
+
+## Shared Rules (All Targets)
+
+Regardless of target, these rules always apply:
+
+- Implement the `Extension` interface correctly
+- Export `metadata` object with name, version, description, author, capabilities
+- Export class as `default`
+- Never use `@/` imports in extension files
+- Store config files inside the extension directory
+- Use proper TypeScript (ES2020+ modules for folder extensions)