@liquidmetal-ai/raindrop-code 0.0.10 → 0.0.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liquidmetal-ai/raindrop-code",
-  "version": "0.0.10",
+  "version": "0.0.12",
   "description": "AI-powered terminal coding assistant with deep code understanding, file operations, and extensible tools",
   "keywords": [
     "ai",
@@ -38,43 +38,73 @@
   "types": "types/index.d.ts",
   "exports": {
     ".": {
-      "types": "./types/index.d.ts"
+      "types": "./types/index.d.ts",
+      "import": "./stubs/index.js",
+      "default": "./stubs/index.js"
     },
     "./control": {
-      "types": "./types/control.d.ts"
+      "types": "./types/control.d.ts",
+      "import": "./stubs/control.js",
+      "default": "./stubs/control.js"
     },
     "./files": {
-      "types": "./types/files.d.ts"
+      "types": "./types/files.d.ts",
+      "import": "./stubs/files.js",
+      "default": "./stubs/files.js"
     },
     "./log": {
-      "types": "./types/log.d.ts"
+      "types": "./types/log.d.ts",
+      "import": "./stubs/log.js",
+      "default": "./stubs/log.js"
     },
     "./resumable": {
-      "types": "./types/resumable.d.ts"
+      "types": "./types/resumable.d.ts",
+      "import": "./stubs/resumable.js",
+      "default": "./stubs/resumable.js"
     },
     "./runtime": {
-      "types": "./types/runtime.d.ts"
+      "types": "./types/runtime.d.ts",
+      "import": "./stubs/runtime.js",
+      "default": "./stubs/runtime.js"
     },
     "./state": {
-      "types": "./types/state.d.ts"
+      "types": "./types/state.d.ts",
+      "import": "./stubs/state.js",
+      "default": "./stubs/state.js"
     },
     "./ui": {
-      "types": "./types/ui.d.ts"
+      "types": "./types/ui.d.ts",
+      "import": "./stubs/ui.js",
+      "default": "./stubs/ui.js"
     },
     "./bash": {
-      "types": "./types/bash.d.ts"
+      "types": "./types/bash.d.ts",
+      "import": "./stubs/bash.js",
+      "default": "./stubs/bash.js"
+    },
+    "./resources": {
+      "types": "./types/resources.d.ts",
+      "import": "./stubs/resources.js",
+      "default": "./stubs/resources.js"
     }
   },
   "files": [
     "install.js",
     "README.md",
     "bin/",
-    "types/"
+    "types/",
+    "stubs/"
   ],
+  "peerDependencies": {
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "zod": "^3.25.0"
+  },
   "optionalDependencies": {
-    "@liquidmetal-ai/raindrop-code-darwin-universal": "0.0.10",
-    "@liquidmetal-ai/raindrop-code-linux-x64": "0.0.10",
-    "@liquidmetal-ai/raindrop-code-linux-arm64": "0.0.10",
-    "@liquidmetal-ai/raindrop-code-win32-x64": "0.0.10"
+    "@liquidmetal-ai/raindrop-code-darwin-universal": "0.0.12",
+    "@liquidmetal-ai/raindrop-code-linux-arm64": "0.0.12",
+    "@liquidmetal-ai/raindrop-code-linux-x64": "0.0.12",
+    "@liquidmetal-ai/raindrop-code-win32-x64": "0.0.12"
   }
 }

package/stubs/bash.js

@@ -0,0 +1,15 @@
+/**
+ * Runtime stub for @liquidmetal-ai/raindrop-code/bash
+ * 
+ * These functions are injected by the Raindrop Code runtime when executing
+ * coordinators. This stub is provided for type checking and development only.
+ */
+
+const runtimeError = () => {
+  throw new Error(
+    '@liquidmetal-ai/raindrop-code/bash is only available when running inside the Raindrop Code coordinator runtime. ' +
+    'These functions are injected at runtime by the Go executor.'
+  );
+};
+
+export const bash = runtimeError;

package/stubs/control.js

@@ -0,0 +1,17 @@
+/**
+ * Runtime stub for @liquidmetal-ai/raindrop-code/control
+ * 
+ * These functions are injected by the Raindrop Code runtime when executing
+ * coordinators. This stub is provided for type checking and development only.
+ */
+
+const runtimeError = () => {
+  throw new Error(
+    '@liquidmetal-ai/raindrop-code/control is only available when running inside the Raindrop Code coordinator runtime. ' +
+    'These functions are injected at runtime by the Go executor.'
+  );
+};
+
+export const passToAI = runtimeError;
+export const passToUser = runtimeError;
+export const passToCoordinator = runtimeError;

package/stubs/files.js

@@ -0,0 +1,19 @@
+/**
+ * Runtime stub for @liquidmetal-ai/raindrop-code/files
+ * 
+ * These functions are injected by the Raindrop Code runtime when executing
+ * coordinators. This stub is provided for type checking and development only.
+ */
+
+const runtimeError = () => {
+  throw new Error(
+    '@liquidmetal-ai/raindrop-code/files is only available when running inside the Raindrop Code coordinator runtime. ' +
+    'These functions are injected at runtime by the Go executor.'
+  );
+};
+
+export const readFile = runtimeError;
+export const writeFile = runtimeError;
+export const editFile = runtimeError;
+export const listFiles = runtimeError;
+export const fileExists = runtimeError;

package/stubs/index.js

@@ -0,0 +1,17 @@
+/**
+ * Runtime stub for @liquidmetal-ai/raindrop-code
+ * 
+ * These functions are injected by the Raindrop Code runtime when executing
+ * coordinators. This stub is provided for type checking and development only.
+ */
+
+// Re-export all modules
+export * from './control.js';
+export * from './files.js';
+export * from './bash.js';
+export * from './ui.js';
+export * from './log.js';
+export * from './state.js';
+export * from './runtime.js';
+export * from './resources.js';
+export * from './resumable.js';

package/stubs/log.js

@@ -0,0 +1,18 @@
+/**
+ * Runtime stub for @liquidmetal-ai/raindrop-code/log
+ * 
+ * These functions are injected by the Raindrop Code runtime when executing
+ * coordinators. This stub is provided for type checking and development only.
+ */
+
+const runtimeError = () => {
+  throw new Error(
+    '@liquidmetal-ai/raindrop-code/log is only available when running inside the Raindrop Code coordinator runtime. ' +
+    'These functions are injected at runtime by the Go executor.'
+  );
+};
+
+export const info = runtimeError;
+export const warn = runtimeError;
+export const error = runtimeError;
+export const debug = runtimeError;

package/stubs/resources.js

@@ -0,0 +1,18 @@
+/**
+ * Runtime stub for @liquidmetal-ai/raindrop-code/resources
+ * 
+ * These functions are injected by the Raindrop Code runtime when executing
+ * coordinators. This stub is provided for type checking and development only.
+ */
+
+const runtimeError = () => {
+  throw new Error(
+    '@liquidmetal-ai/raindrop-code/resources is only available when running inside the Raindrop Code coordinator runtime. ' +
+    'These functions are injected at runtime by the Go executor.'
+  );
+};
+
+export const listAgents = runtimeError;
+export const listCommands = runtimeError;
+export const listSkills = runtimeError;
+export const listCoordinators = runtimeError;

package/stubs/resumable.js

@@ -0,0 +1,15 @@
+/**
+ * Runtime stub for @liquidmetal-ai/raindrop-code/resumable
+ * 
+ * These functions are injected by the Raindrop Code runtime when executing
+ * coordinators. This stub is provided for type checking and development only.
+ */
+
+const runtimeError = () => {
+  throw new Error(
+    '@liquidmetal-ai/raindrop-code/resumable is only available when running inside the Raindrop Code coordinator runtime. ' +
+    'These functions are injected at runtime by the Go executor.'
+  );
+};
+
+export const createResumable = runtimeError;

package/stubs/runtime.js

@@ -0,0 +1,17 @@
+/**
+ * Runtime stub for @liquidmetal-ai/raindrop-code/runtime
+ * 
+ * These functions are injected by the Raindrop Code runtime when executing
+ * coordinators. This stub is provided for type checking and development only.
+ */
+
+const runtimeError = () => {
+  throw new Error(
+    '@liquidmetal-ai/raindrop-code/runtime is only available when running inside the Raindrop Code coordinator runtime. ' +
+    'These functions are injected at runtime by the Go executor.'
+  );
+};
+
+export const getCwd = runtimeError;
+export const getVersion = runtimeError;
+export const getSessionId = runtimeError;

package/stubs/state.js

@@ -0,0 +1,18 @@
+/**
+ * Runtime stub for @liquidmetal-ai/raindrop-code/state
+ * 
+ * These functions are injected by the Raindrop Code runtime when executing
+ * coordinators. This stub is provided for type checking and development only.
+ */
+
+const runtimeError = () => {
+  throw new Error(
+    '@liquidmetal-ai/raindrop-code/state is only available when running inside the Raindrop Code coordinator runtime. ' +
+    'These functions are injected at runtime by the Go executor.'
+  );
+};
+
+export const getState = runtimeError;
+export const setState = runtimeError;
+export const deleteState = runtimeError;
+export const clearState = runtimeError;

package/stubs/ui.js

@@ -0,0 +1,20 @@
+/**
+ * Runtime stub for @liquidmetal-ai/raindrop-code/ui
+ * 
+ * These functions are injected by the Raindrop Code runtime when executing
+ * coordinators. This stub is provided for type checking and development only.
+ */
+
+const runtimeError = () => {
+  throw new Error(
+    '@liquidmetal-ai/raindrop-code/ui is only available when running inside the Raindrop Code coordinator runtime. ' +
+    'These functions are injected at runtime by the Go executor.'
+  );
+};
+
+export const showStatus = runtimeError;
+export const showProgress = runtimeError;
+export const showSuccess = runtimeError;
+export const showError = runtimeError;
+export const showWarning = runtimeError;
+export const showInfo = runtimeError;

package/types/control.d.ts

@@ -1,186 +1,198 @@
 declare module '@liquidmetal-ai/raindrop-code/control' {
-  /**
-   * Schema definition for AI response validation.
-   * Must be a Zod schema object (use z.object()).
-   */
-  export interface ResponseSchema {
-    /** Parse and validate data against the schema (required) */
-    parse: (data: any) => any;
-    /** Get the schema shape for field extraction (required) */
-    shape: () => Record<string, SchemaField>;
-    /** Internal definition metadata */
-    _def?: {
-      shape?: () => Record<string, SchemaField>;
-    };
-  }
+	// Import Zod types for proper type inference
+	import type { z } from 'zod';
 
-  /**
-   * Schema field definition
-   */
-  export interface SchemaField {
-    /** Field type information */
-    _def?: {
-      typeName?: string;
-      description?: string;
-      innerType?: SchemaField;
-    };
-    /** Check if field is optional */
-    isOptional?: () => boolean;
-  }
+	/**
+	 * Schema definition for AI response validation.
+	 * Must be a Zod schema object (use z.object()).
+	 */
+	export interface ResponseSchema {
+		/** Parse and validate data against the schema (required) */
+		parse: (data: any) => any;
+		/** Shape property containing field schemas (Zod 3 structure) */
+		shape: Record<string, SchemaField>;
+	}
 
-  /**
-   * Options for passing control to AI
-   */
-  export interface PassToAIOptions {
-    /** The prompt to send to the AI */
-    prompt: string;
-    /**
-     * REQUIRED: Zod schema defining the expected response structure.
-     * Use z.object() with .describe() on fields for better AI instructions.
-     * 
-     * Automatically:
-     * - Generates unique signal name
-     * - Appends instructions with example to prompt
-     * - Validates AI response against schema
-     * - Returns typed data
-     * 
-     * @example
-     * z.object({
-     *   result: z.string().describe('The result of the operation'),
-     *   success: z.boolean().describe('Whether it succeeded')
-     * })
-     */
-    responseSchema: ResponseSchema;
-    /**
-     * REQUIRED: Example object showing realistic response values.
-     * Must contain at least one field. Used to generate clear instructions.
-     * 
-     * @example
-     * {
-     *   result: 'Successfully completed the task',
-     *   success: true
-     * }
-     */
-    example: Record<string, any>;
-    /** Timeout in seconds (default: 3600) */
-    timeout?: number;
-    /** Optional: Specific tools to enable for this AI session */
-    tools?: string[];
-    /** Optional: Specific skills to enable for this AI session */
-    skills?: string[];
-  }
+	/**
+	 * Schema field definition matching Zod 3 structure
+	 */
+	export interface SchemaField {
+		/** Internal Zod definition with type metadata */
+		_def: {
+			/** Zod type name (e.g., 'ZodString', 'ZodNumber', 'ZodArray') */
+			typeName: string;
+			/** Optional description set via .describe() */
+			description?: string;
+			/** Validation checks */
+			checks?: any[];
+			/** Whether coercion is enabled */
+			coerce?: boolean;
+			/** For ZodArray: inner type */
+			innerType?: SchemaField;
+		};
+		/** Check if field is optional */
+		isOptional?: () => boolean;
+	}
 
-  /**
-   * Data returned from AI via session_control signal
-   */
-  export type SignalData = Record<string, any>;
+	/**
+	 * Options for passing control to AI
+	 */
+	export interface PassToAIOptions<TSchema extends z.ZodObject<any>> {
+		/** The prompt to send to the AI */
+		prompt: string;
+		/**
+		 * REQUIRED: Zod object schema defining the expected response structure.
+		 * Must use z.object() - primitive schemas are not supported.
+		 * Use .describe() on fields for better AI instructions.
+		 * 
+		 * For primitive values, wrap them in an object:
+		 * - Instead of: z.string()
+		 * - Use: z.object({ result: z.string() })
+		 * 
+		 * Automatically:
+		 * - Generates unique signal name
+		 * - Appends instructions with example to prompt
+		 * - Validates AI response against schema
+		 * - Returns typed data
+		 * 
+		 * @example
+		 * z.object({
+		 *   result: z.string().describe('The result of the operation'),
+		 *   success: z.boolean().describe('Whether it succeeded')
+		 * })
+		 */
+		responseSchema: TSchema;
+		/**
+		 * REQUIRED: Example object showing realistic response values.
+		 * Must be an object matching the schema's output type.
+		 * Used to generate clear instructions for the AI.
+		 * 
+		 * @example
+		 * {
+		 *   result: 'Successfully completed the task',
+		 *   success: true
+		 * }
+		 */
+		example: z.infer<TSchema>;
+		/** Timeout in seconds (default: 3600) */
+		timeout?: number;
+		/** Optional: Specific tools to enable for this AI session */
+		tools?: string[];
+		/** Optional: Specific skills to enable for this AI session */
+		skills?: string[];
+	}
 
-  /**
-   * Options for passing control to user
-   */
-  export interface PassToUserOptions {
-    /** Message to display to the user */
-    message: string;
-    /** Type of user input: "choice" (default) or "text" */
-    type?: 'choice' | 'text';
-    /** Available actions for the user to choose from (for type="choice") */
-    actions?: string[];
-    /** Placeholder text for text input (for type="text") */
-    placeholder?: string;
-  }
+	/**
+	 * Data returned from AI via session_control signal
+	 */
+	export type SignalData = Record<string, any>;
 
-  /**
-   * Options for passing control to another coordinator
-   */
-  export interface PassToCoordinatorOptions {
-    /** Name of the coordinator to execute */
-    coordinator: string;
-    /** Input data to pass to the coordinator */
-    input: Record<string, any>;
-  }
+	/**
+	 * Options for passing control to user
+	 */
+	export interface PassToUserOptions {
+		/** Message to display to the user */
+		message: string;
+		/** Type of user input: "choice" (default) or "text" */
+		type?: 'choice' | 'text';
+		/** Available actions for the user to choose from (for type="choice") */
+		actions?: string[];
+		/** Placeholder text for text input (for type="text") */
+		placeholder?: string;
+	}
 
-  /**
-   * Pass control to AI by sending a prompt and waiting for a signal.
-   * 
-   * Uses Zod schema to automatically generate instructions and validate responses.
-   * The AI receives clear examples and the response is type-checked.
-   * 
-   * @param opts - Options for the AI session
-   * @returns Promise resolving to the validated signal data
-   * 
-   * @example
-   * ```typescript
-   * import { z } from 'zod';
-   * 
-   * const result = await passToAI({
-   *   prompt: 'Analyze this code and find potential bugs',
-   *   responseSchema: z.object({
-   *     bugs: z.array(z.string()).describe('List of bugs found'),
-   *     severity: z.enum(['low', 'medium', 'high']).describe('Overall severity'),
-   *     summary: z.string().describe('Brief analysis summary')
-   *   }),
-   *   example: {
-   *     bugs: ['Memory leak in loop', 'Unhandled error case'],
-   *     severity: 'high',
-   *     summary: 'Found 2 critical issues'
-   *   },
-   *   timeout: 300
-   * });
-   * 
-   * console.log(result.bugs);      // string[] - typed and validated!
-   * console.log(result.severity);  // 'low' | 'medium' | 'high'
-   * ```
-   */
-  export function passToAI(opts: PassToAIOptions): Promise<SignalData>;
+	/**
+	 * Options for passing control to another coordinator
+	 */
+	export interface PassToCoordinatorOptions {
+		/** Name of the coordinator to execute */
+		coordinator: string;
+		/** Input data to pass to the coordinator */
+		input: Record<string, any>;
+	}
 
-  /**
-   * Pass control to the user for manual input/decision.
-   * 
-   * @param opts - Options for user interaction
-   * @returns Promise resolving to the user's selected action or entered text
-   * 
-   * @example
-   * ```typescript
-   * // Choice selection (default)
-   * const choice = await passToUser({
-   *   message: 'How should we proceed?',
-   *   type: 'choice',
-   *   actions: ['Continue', 'Skip', 'Abort']
-   * });
-   * if (choice === 'Abort') {
-   *   return { success: false };
-   * }
-   * 
-   * // Freeform text input
-   * const name = await passToUser({
-   *   message: 'What is your project name?',
-   *   type: 'text',
-   *   placeholder: 'my-project'
-   * });
-   * ```
-   */
-  export function passToUser(opts: PassToUserOptions): Promise<string>;
+	/**
+	 * Pass control to AI by sending a prompt and waiting for a signal.
+	 * 
+	 * Uses Zod schema to automatically generate instructions and validate responses.
+	 * The AI receives clear examples and the response is type-checked.
+	 * 
+	 * @param opts - Options for the AI session
+	 * @returns Promise resolving to the validated signal data
+	 * 
+	 * @example
+	 * ```typescript
+	 * import { z } from 'zod';
+	 * 
+	 * const result = await passToAI({
+	 *   prompt: 'Analyze this code and find potential bugs',
+	 *   responseSchema: z.object({
+	 *     bugs: z.array(z.string()).describe('List of bugs found'),
+	 *     severity: z.enum(['low', 'medium', 'high']).describe('Overall severity'),
+	 *     summary: z.string().describe('Brief analysis summary')
+	 *   }),
+	 *   example: {
+	 *     bugs: ['Memory leak in loop', 'Unhandled error case'],
+	 *     severity: 'high',
+	 *     summary: 'Found 2 critical issues'
+	 *   },
+	 *   timeout: 300
+	 * });
+	 * 
+	 * console.log(result.bugs);      // string[] - typed and validated!
+	 * console.log(result.severity);  // 'low' | 'medium' | 'high'
+	 * ```
+	 */
+	export function passToAI<T extends z.ZodObject<any>>(opts: PassToAIOptions<T>): Promise<z.infer<T>>;
 
-  /**
-   * Pass control to another coordinator.
-   * 
-   * @param opts - Options for coordinator execution
-   * @returns Promise resolving to the coordinator's result
-   * 
-   * @example
-   * ```typescript
-   * const result = await passToCoordinator({
-   *   coordinator: 'helper-coordinator',
-   *   input: { task: 'process data' }
-   * });
-   * ```
-   */
-  export function passToCoordinator(opts: PassToCoordinatorOptions): Promise<Record<string, any>>;
+	/**
+	 * Pass control to the user for manual input/decision.
+	 * 
+	 * @param opts - Options for user interaction
+	 * @returns Promise resolving to the user's selected action or entered text
+	 * 
+	 * @example
+	 * ```typescript
+	 * // Choice selection (default)
+	 * const choice = await passToUser({
+	 *   message: 'How should we proceed?',
+	 *   type: 'choice',
+	 *   actions: ['Continue', 'Skip', 'Abort']
+	 * });
+	 * if (choice === 'Abort') {
+	 *   return { success: false };
+	 * }
+	 * 
+	 * // Freeform text input
+	 * const name = await passToUser({
+	 *   message: 'What is your project name?',
+	 *   type: 'text',
+	 *   placeholder: 'my-project'
+	 * });
+	 * ```
+	 */
+	export function passToUser(opts: PassToUserOptions): Promise<string>;
 
-  /**
-   * Get the current control state.
-   * 
-   * @returns The current state ('coordinator', 'ai', or 'user')
-   */
-  export function current(): string;
+	/**
+	 * Pass control to another coordinator.
+	 * 
+	 * @param opts - Options for coordinator execution
+	 * @returns Promise resolving to the coordinator's result
+	 * 
+	 * @example
+	 * ```typescript
+	 * const result = await passToCoordinator({
+	 *   coordinator: 'helper-coordinator',
+	 *   input: { task: 'process data' }
+	 * });
+	 * ```
+	 */
+	export function passToCoordinator(opts: PassToCoordinatorOptions): Promise<Record<string, any>>;
+
+	/**
+	 * Get the current control state.
+	 * 
+	 * @returns The current state ('coordinator', 'ai', or 'user')
+	 */
+	export function current(): string;
 }

package/types/index.d.ts

@@ -16,4 +16,5 @@ export * from '@liquidmetal-ai/raindrop-code/ui';
 export * from '@liquidmetal-ai/raindrop-code/log';
 export * from '@liquidmetal-ai/raindrop-code/state';
 export * from '@liquidmetal-ai/raindrop-code/runtime';
+export * from '@liquidmetal-ai/raindrop-code/resources';
 export * from '@liquidmetal-ai/raindrop-code/resumable';

package/types/resources.d.ts

@@ -0,0 +1,164 @@
+declare module '@liquidmetal-ai/raindrop-code/resources' {
+  /**
+   * Information about an agent
+   */
+  export interface AgentInfo {
+    /** Agent name */
+    name: string;
+    /** Description of when and why to use this agent */
+    description: string;
+    /** Allowed tool names (empty array = all tools allowed) */
+    tools: string[];
+    /** Model to use (empty = inherit from parent) */
+    model: string;
+    /** Temperature setting (0.0-1.0, undefined = default) */
+    temperature?: number;
+    /** Expected context - keys are context names, values are descriptions */
+    contextNeeds: Record<string, string>;
+  }
+
+  /**
+   * Information about a command
+   */
+  export interface CommandInfo {
+    /** Command name */
+    name: string;
+    /** Description for help text */
+    description: string;
+    /** Whether this command starts an excursion */
+    isExcursion: boolean;
+    /** Title for the excursion box */
+    excursionTitle: string;
+  }
+
+  /**
+   * Information about a skill
+   */
+  export interface SkillInfo {
+    /** Skill name */
+    name: string;
+    /** Description of what the skill does */
+    description: string;
+    /** Path to skill directory */
+    path: string;
+    /** Path to SKILL.md file */
+    mdPath: string;
+    /** License name or reference */
+    license: string;
+    /** Environment requirements */
+    compatibility: string;
+    /** True if references/ directory exists */
+    hasReferences: boolean;
+    /** True if scripts/ directory exists */
+    hasScripts: boolean;
+    /** True if assets/ directory exists */
+    hasAssets: boolean;
+  }
+
+  /**
+   * Information about a coordinator
+   */
+  export interface CoordinatorInfo {
+    /** Coordinator name */
+    name: string;
+    /** Description of what the coordinator does */
+    description: string;
+    /** Estimated execution time */
+    estimatedTime: string;
+    /** Whether the coordinator requires user approval */
+    requiresApproval: boolean;
+    /** Path to the coordinator source file */
+    sourcePath: string;
+    /** Type of source (e.g., "typescript", "javascript") */
+    sourceType: string;
+  }
+
+  /**
+   * List all available agents with detailed metadata.
+   * Agents are specialized AI sessions with custom prompts and tool configurations.
+   * 
+   * @returns Promise resolving to a map of agent name to agent information
+   * 
+   * @example
+   * ```typescript
+   * const agents = await listAgents();
+   * 
+   * // Direct access by name
+   * const reviewAgent = agents['code-reviewer'];
+   * console.log(`${reviewAgent.name}: ${reviewAgent.description}`);
+   * console.log(`Tools: ${reviewAgent.tools.join(', ')}`);
+   * 
+   * // Iterate over all agents
+   * for (const [name, agent] of Object.entries(agents)) {
+   *   console.log(`${name}: ${agent.description}`);
+   * }
+   * ```
+   */
+  export function listAgents(): Promise<Record<string, AgentInfo>>;
+
+  /**
+   * List all available commands with detailed metadata.
+   * Commands are reusable tools that can be invoked by AI or coordinators.
+   * 
+   * @returns Promise resolving to a map of command name to command information
+   * 
+   * @example
+   * ```typescript
+   * const commands = await listCommands();
+   * 
+   * // Direct access by name
+   * const prCmd = commands['create-pr'];
+   * console.log(`${prCmd.name}: ${prCmd.description}`);
+   * if (prCmd.isExcursion) {
+   *   console.log(`Excursion: ${prCmd.excursionTitle}`);
+   * }
+   * 
+   * // Iterate over all commands
+   * for (const [name, cmd] of Object.entries(commands)) {
+   *   console.log(`${name}: ${cmd.description}`);
+   * }
+   * ```
+   */
+  export function listCommands(): Promise<Record<string, CommandInfo>>;
+
+  /**
+   * List all available skills with detailed metadata including location.
+   * Skills are structured workflows that guide AI through complex tasks.
+   * 
+   * @returns Promise resolving to a map of skill name to skill information
+   * 
+   * @example
+   * ```typescript
+   * const skills = await listSkills();
+   * 
+   * // Direct access by name
+   * const prdSkill = skills['prd-writer'];
+   * console.log(`${prdSkill.name}: ${prdSkill.description}`);
+   * console.log(`Location: ${prdSkill.path}`);
+   * 
+   * // Iterate over all skills
+   * for (const [name, skill] of Object.entries(skills)) {
+   *   console.log(`${name}: ${skill.description}`);
+   * }
+   * ```
+   */
+  export function listSkills(): Promise<Record<string, SkillInfo>>;
+
+  /**
+   * List all available coordinators with detailed metadata.
+   * Coordinators are multi-session orchestration scripts that can be composed.
+   * 
+   * @returns Promise resolving to an array of coordinator information
+   * 
+   * @example
+   * ```typescript
+   * const coordinators = await listCoordinators();
+   * console.log('Available coordinators:');
+   * for (const coord of coordinators) {
+   *   console.log(`  ${coord.name}: ${coord.description}`);
+   *   console.log(`    Estimated time: ${coord.estimatedTime}`);
+   * }
+   * ```
+   */
+  export function listCoordinators(): Promise<CoordinatorInfo[]>;
+}