@j-o-r/hello-dave 0.1.1 → 0.1.5

package/types/API/x.ai/image.d.ts

@@ -1,48 +1,107 @@
 /**
- * Generates one or more images from a text prompt using Grok Imagine.
+ * Generates one or more images from a text prompt using Grok Imagine models.
+ *
+ * **Supported models** (current):
+ * - `grok-imagine-image-quality` — Recommended primary model.
+ * - `grok-imagine-image` — Alternative image model.
+ *
+ * Default: `grok-imagine-image-quality`.
+ *
+ * Supported features:
+ * - Up to 10 images per request (`n`)
+ * - Custom aspect ratios (see `image.to.generation.md` for the full table)
+ * - Resolutions: `1k` or `2k`
+ * - Response formats: `url` (temporary public URL) or `b64_json` (base64)
+ *
+ * All generated images are automatically saved to the local `.cache/xai/` directory.
+ * The function returns both the local path and the original API response data.
  *
  * @async
  * @function generateImage
- * @param {string} prompt - Detailed text prompt describing the desired image.
+ * @param {string} prompt - Detailed text prompt describing the desired image(s). Required.
  * @param {Object} [options={}] - Optional generation parameters.
- * @param {string} [options.model='grok-imagine-image-quality'] - Model to use.
- * @param {number} [options.n=1] - Number of images to generate (1–10).
- * @param {string} [options.response_format='url'] - `'url'` or `'b64_json'`.
- * @returns {Promise<Object>} Result containing `local_path`, `url` (or `base64`), and metadata.
- * @throws {Error} On missing prompt or API errors.
+ * @param {string} [options.model='grok-imagine-image-quality'] - Model identifier. Supported values: `grok-imagine-image-quality` (recommended) or `grok-imagine-image`.
+ * @param {number} [options.n=1] - Number of images to generate. Range: 1–10. Default: 1.
+ * @param {string} [options.response_format='url'] - `'url'` (default) or `'b64_json'`.
+ * @param {string} [options.aspect_ratio] - Desired aspect ratio (e.g. `'16:9'`, `'1:1'`, `'auto'`).
+ * @param {string} [options.resolution] - Output resolution (`'1k'` or `'2k'`).
+ * @returns {Promise<Object>} Result object containing:
+ *   - `local_path` (string) – absolute path to the saved file
+ *   - `url` (string, if response_format=url) – temporary public URL
+ *   - `base64` (string, if response_format=b64_json)
+ *   - `revised_prompt` (string) – model-revised version of the prompt (if provided)
+ *   - `raw` (Object) – full original API response
+ * @throws {Error} If `prompt` is missing/invalid, or on any API/network error.
  *
  * @example
+ * // Basic usage (uses recommended model)
  * const result = await generateImage("A futuristic city at night");
  * console.log(result.local_path);
+ *
+ * @example
+ * // Multiple images with custom aspect ratio and resolution
+ * const results = await generateImage("Mountain landscape at sunrise", {
+ *   n: 4,
+ *   aspect_ratio: "16:9",
+ *   resolution: "2k"
+ * });
+ *
+ * @example
+ * // Using the alternative model
+ * const result = await generateImage("...", { model: "grok-imagine-image" });
  */
 export function generateImage(prompt: string, options?: {
     model?: string | undefined;
     n?: number | undefined;
     response_format?: string | undefined;
+    aspect_ratio?: string | undefined;
+    resolution?: string | undefined;
 }): Promise<Object>;
 /**
  * Edits one or more images using a natural language prompt.
- * Supports up to 3 reference images for compositing, style transfer, or multi-subject scenes.
+ *
+ * Supports up to 3 reference images for advanced compositing, style transfer,
+ * multi-subject scenes, or object insertion/removal.
+ *
+ * The model analyzes the provided image(s) and applies the edits described in the prompt.
+ *
+ * **Official API payload (per current xAI Inference API spec)**:
+ * - Single image: `"image": { "url": "...", "type": "image_url" }`
+ * - Multiple images (up to 3): `"images": [ { "url": "...", "type": "image_url" }, ... ]`
+ *   (array of objects — **not** `image_urls`)
+ *
+ * When using multiple images, refer to them in the prompt as <IMAGE_0>, <IMAGE_1>, <IMAGE_2>, etc.
+ *
+ * **Supported models** (same as generation):
+ * - `grok-imagine-image-quality` (recommended)
+ * - `grok-imagine-image`
+ *
+ * All output images are automatically saved locally.
  *
  * @async
  * @function editImage
- * @param {string} prompt - Description of the desired edit.
- * @param {string|Buffer|Blob|Array<string|Buffer|Blob>} imageInputs - One or more images (URL, path, base64, Buffer, or Blob).
+ * @param {string} prompt - Natural language description of the desired edit(s). Required.
+ * @param {string|Buffer|Blob|Array<string|Buffer|Blob>} imageInputs - One or more reference images.
+ *        Accepts URLs, local paths, base64, Buffers, or Blobs. **Maximum: 3 images**.
  * @param {Object} [options={}] - Optional parameters.
- * @param {string} [options.model='grok-imagine-image-quality']
- * @param {number} [options.n=1]
- * @param {string} [options.response_format='url']
- * @returns {Promise<Object>} Result with edited image.
- * @throws {Error} If more than 3 images are provided or on API error.
+ * @param {string} [options.model='grok-imagine-image-quality'] - Model identifier. Supported values: `grok-imagine-image-quality` (recommended) or `grok-imagine-image`.
+ * @param {number} [options.n=1] - Number of output images. Range: 1–10. Default: 1.
+ * @param {string} [options.response_format='url'] - `'url'` or `'b64_json'`.
+ * @param {string} [options.aspect_ratio] - Desired aspect ratio for output.
+ * @param {string} [options.resolution] - Output resolution (`'1k'` or `'2k'`).
+ * @returns {Promise<Object>} Result object (same shape as `generateImage`):
+ *   - `local_path`, `url`/`base64`, `revised_prompt`, `raw`
+ * @throws {Error} If prompt or imageInputs are missing, more than 3 images are supplied,
+ *                 or on API/network error.
  *
  * @example
- * // Single image edit
+ * // Single-image edit (recommended model)
  * const result = await editImage("Make this a pencil sketch", "./photo.png");
  *
  * @example
  * // Multi-image editing (up to 3)
  * const result = await editImage(
- *   "Combine these two people into one scene",
+ *   "Combine <IMAGE_0> and <IMAGE_1> into one scene with a city background",
  *   ["./person1.png", "./person2.png"]
  * );
  */
@@ -50,33 +109,86 @@ export function editImage(prompt: string, imageInputs: string | Buffer | Blob |
     model?: string | undefined;
     n?: number | undefined;
     response_format?: string | undefined;
+    aspect_ratio?: string | undefined;
+    resolution?: string | undefined;
 }): Promise<Object>;
 /**
- * Generates a video from a still image and text prompt.
- * This function is fully automatic — it submits the request and polls internally
- * until the video is ready before returning.
+ * Generates a video from a still image + text motion prompt.
+ *
+ * This function is **fully automatic**: it posts to `/videos/generations` and then
+ * internally calls `pollVideoResult()` until the video is ready.
+ *
+ * **Supported model**: Only `grok-imagine-video` (the sole model for image-to-video generation).
+ *
+ * The provided image becomes the first frame; the prompt describes the desired motion/animation.
+ * Supports public URLs or base64 data URIs for the source image.
+ *
+ * Video parameters (from official docs):
+ * - `duration`: 1–15 seconds (affects pricing)
+ * - `aspect_ratio`, `resolution`
+ *
+ * **Important**: Video generation can take a long time and is prone to polling timeouts.
+ * Use the exported `pollVideoResult()` directly with higher `intervalMs`/`maxAttempts`
+ * if you encounter frequent timeouts.
  *
  * @async
  * @function generateVideo
- * @param {string} prompt - Description of the desired motion or animation.
- * @param {string|Buffer|Blob} imageInput - Source image (URL, path, base64, Buffer, or Blob).
+ * @param {string} prompt - Description of the desired motion or animation. Required.
+ * @param {string|Buffer|Blob} imageInput - Source image (URL, local path, base64, Buffer, or Blob). Required.
  * @param {Object} [options={}] - Optional video parameters.
- * @param {number} [options.duration=8] - Video duration in seconds.
- * @param {string} [options.aspect_ratio='16:9'] - Aspect ratio.
+ * @param {string} [options.model='grok-imagine-video'] - Model identifier (only `grok-imagine-video` is supported).
+ * @param {number} [options.duration=8] - Video length in seconds (1–15). Default: 8.
+ * @param {string} [options.aspect_ratio='16:9'] - Aspect ratio for the video.
  * @param {string} [options.resolution='720p'] - Output resolution.
- * @returns {Promise<Object>} Result containing `local_path` and `url` of the generated video.
- * @throws {Error} On missing inputs or generation failure.
+ * @returns {Promise<Object>} Result containing `local_path`, `url`, `status: 'done'`, and `raw`.
+ * @throws {Error} If prompt or imageInput is missing, or on generation failure/timeout.
  *
  * @example
+ * // Basic usage with public image URL
  * const result = await generateVideo(
  *   "Make the water crash down and slowly pan out",
  *   "https://example.com/waterfall.png",
  *   { duration: 12 }
  * );
  * console.log(result.local_path);
+ *
+ * @example
+ * // Using a local file with custom aspect ratio
+ * const result = await generateVideo(
+ *   "Animate the character walking forward",
+ *   "./character.png",
+ *   { duration: 10, aspect_ratio: "9:16" }
+ * );
  */
 export function generateVideo(prompt: string, imageInput: string | Buffer | Blob, options?: {
+    model?: string | undefined;
     duration?: number | undefined;
     aspect_ratio?: string | undefined;
     resolution?: string | undefined;
 }): Promise<Object>;
+/**
+ * Polls the xAI video status endpoint until generation completes or fails.
+ *
+ * This is an internal helper used by `generateVideo()`, but it is exported for
+ * advanced use cases where you want manual control over polling parameters.
+ *
+ * The xAI video endpoint returns `status: 'done'`, `'failed'`, or `'expired'`.
+ * On success it also provides `video.url`.
+ *
+ * **Timeout note**: Video generation can be slow. The default `intervalMs` was
+ * increased (and the function exported) to give callers more flexibility.
+ * Recommended values: `intervalMs` 15000–30000, `maxAttempts` 60+ for longer videos.
+ *
+ * @async
+ * @function pollVideoResult
+ * @param {string} requestId - The `request_id` returned from a `/videos/generations` call. Required.
+ * @param {number} [maxAttempts=60] - Maximum number of polling attempts. Default: 60.
+ * @param {number} [intervalMs=15000] - Milliseconds to wait between polls. Default: 15000.
+ * @returns {Promise<Object>} Result containing:
+ *   - `local_path` (string) – path to the saved MP4
+ *   - `url` (string) – public video URL
+ *   - `status: 'done'`
+ *   - `raw` (Object) – full response
+ * @throws {Error} On failure/expiration status, missing request_id, or polling timeout.
+ */
+export function pollVideoResult(requestId: string, maxAttempts?: number, intervalMs?: number): Promise<Object>;

package/types/API/x.ai/imageToolset.d.ts

@@ -0,0 +1,3 @@
+export default tools;
+declare const tools: ToolSet;
+import ToolSet from '../../ToolSet.js';

package/types/API/x.ai/index.d.ts

@@ -4,4 +4,4 @@ declare namespace _default {
 }
 export default _default;
 import * as image from './image.js';
-import imageToolset from './ImageToolset.js';
+import imageToolset from './imageToolset.js';

package/types/API/x.ai/responses.d.ts

@@ -29,7 +29,7 @@ export type XAIOptions = {
     /**
      * - Model version to use.
      */
-    model?: "grok-4-1-fast-reasoning" | "grok-4-1-fast-non-reasoning" | "grok-code-fast-1" | "grok-4-fast-reasoning" | "grok-4-fast-non-reasoning" | undefined;
+    model?: "grok-build-0.1" | "grok-4.3" | "grok-4.20" | "grok-4.20-multi-agent" | "grok-4.20-non-reasoning" | undefined;
     /**
      * - Reusable prompt string.
      */
@@ -47,7 +47,7 @@ export type XAIOptions = {
          */
         summary: "auto" | "concise" | "detailed";
     } | undefined;
-    search?: "low" | "high" | "medium" | undefined;
+    search?: "low" | "medium" | "high" | undefined;
     /**
      * - Service tier option, default is auto-selected.
      */
@@ -94,7 +94,7 @@ export type XAIOptions = {
      */
     top_p?: number | null | undefined;
     /**
-     * - Needed reponse_id to validate tool calls on the next request
+     * - Needed response_id to validate tool calls on the next request
      */
     previous_response_id?: string | null | undefined;
 };
@@ -144,7 +144,7 @@ export type WebSearchFilters = {
     /**
      * - Context size; for OpenAI compatibility (reject if set).
      */
-    search_context_size?: "low" | "high" | "medium" | null | undefined;
+    search_context_size?: "low" | "medium" | "high" | null | undefined;
     /**
      * - User location; for OpenAI compatibility (reject if set).
      */

package/types/Agent.d.ts

@@ -0,0 +1,123 @@
+export default Agent;
+export type XAIOptions = import("./API/x.ai/responses.js").XAIOptions;
+export type OAOptions = any;
+export type ANTHOptions = import("./API/anthropic.com/text.js").ANTHOptions;
+export type AgentConfig = {
+    /**
+     * - Initial system prompt (can be loaded via Agent.loadPrompt for extended agents)
+     */
+    prompt: string;
+    /**
+     * - Chat adaptor function from API.chat.* (e.g. API.chat.xai)
+     */
+    api: Function;
+    /**
+     * - Model options
+     */
+    options?: XAIOptions | OAOptions | Object;
+    contextWindow?: number | undefined;
+    toolsetMode?: "auto" | "required" | null | undefined;
+    debug?: boolean | undefined;
+    /**
+     * - Plain text secret (will be base64 encoded internally)
+     */
+    secret?: string | undefined;
+    cachePath?: string | undefined;
+    /**
+     * - Agent/tool name (required). Must match /^[a-z0-9_]{2,}$/. Recommended: derive via Agent.deriveCallName(import.meta.url)
+     */
+    call_name: string;
+    /**
+     * - Description for the tool (required, non-empty string)
+     */
+    call_description: string;
+    /**
+     * - CLI intro message (stored for future use)
+     */
+    cliIntro?: string | undefined;
+};
+declare class Agent {
+    /**
+     * Derives the canonical `call_name` from the agent's own filename.
+     * This makes the **filename the single source of truth** for the agent name.
+     *
+     * Recommended usage in every agent:
+     *   const call_name = Agent.deriveCallName(import.meta.url);
+     *
+     * @param {string} importMetaUrl - Always pass `import.meta.url` from the agent module.
+     * @returns {string} The derived call_name (basename without extension)
+     * @throws {Error} If the derived name is invalid.
+     */
+    static deriveCallName(importMetaUrl: string): string;
+    /**
+     * Loads the external system prompt for "extended" agents.
+     *
+     * Looks for a pure Markdown sibling prompt file in the same directory as the
+     * calling agent. The filename is always `<call_name>.prompt.md`, where
+     * `call_name` is derived from the calling agent filename.
+     *
+     * Two common patterns:
+     *
+     * 1. Simple one-file agent (internal prompt):
+     *    const prompt = `You are ...`;   // define inline
+     *
+     * 2. Extended agent (external Markdown prompt):
+     *    const prompt = await Agent.loadPrompt(import.meta.url);
+     *    // Automatically loads ./<call_name>.prompt.md as UTF-8 text.
+     *
+     * @param {string} importMetaUrl - Pass `import.meta.url` from the agent module.
+     * @param {Object} [options]
+     * @param {boolean} [options.required=true] - If true, throws when no external prompt file is found.
+     * @param {string|null} [options.fallback=null] - Prompt to return if no external file is found and required=false.
+     * @returns {Promise<string>} The Markdown prompt content (trimmed).
+     * @throws {Error} When required=true and no prompt file can be found, or when the prompt file cannot be read.
+     */
+    static loadPrompt(importMetaUrl: string, options?: {
+        required?: boolean | undefined;
+        fallback?: string | null | undefined;
+    }): Promise<string>;
+    /**
+     * Creates a new Agent instance.
+     * Minimal core skeleton (no run(), no CLI parsing, no server/client logic).
+     * All configuration is passed via the constructor.
+     * Designed to be used by AgentLauncher and for clean handoff support.
+     *
+     * @param {AgentConfig} config
+     */
+    constructor(config?: AgentConfig);
+    /**
+     * @returns {string}
+     */
+    info(): string;
+    /**
+     * Direct synchronous call to the underlying Prompt.
+     * @param {string} input - User input.
+     * @returns {Promise<string>} Response.
+     */
+    directCall(input: string): Promise<string>;
+    /** @returns {Prompt} Underlying Prompt instance. */
+    getPrompt(): Prompt;
+    /** @returns {Session} Underlying Session instance (for CLI and handoff support). */
+    getSession(): Session;
+    /** @returns {ToolSet|null} Toolset if configured. */
+    getToolset(): ToolSet | null;
+    /** @returns {string} Agent name (from call_name). */
+    get name(): string;
+    /** @returns {string} Agent description. */
+    get description(): string;
+    /** @returns {string} CLI intro (if provided). */
+    get cliIntro(): string;
+    /** @returns {string} Base64-encoded secret (if provided). */
+    get secret(): string;
+    /** @returns {string} Cache path. */
+    get cachePath(): string;
+    /** @returns {number} Context window size. */
+    get contextWindow(): number;
+    /** @returns {string} Model name (if set via options). */
+    get model(): string;
+    destructor(): void;
+    #private;
+}
+import Prompt from './Prompt.js';
+import Session from './Session.js';
+import ToolSet from './ToolSet.js';

package/types/AgentLauncher.d.ts

@@ -0,0 +1,250 @@
+export default AgentLauncher;
+/**
+ * @module AgentLauncher
+ *
+ * AgentLauncher provides a clean, reusable way to discover, load, run, and
+ * hand-off between "clean" Agent instances (those built with the unified
+ * Agent class and exported via `export default agent;`).
+ *
+ * Primary responsibilities:
+ *   - Discovery: `list()` returns all agents found in the standard locations
+ *     without importing them (now includes a short `desc`).
+ *   - Loading: `load(name)` resolves, imports, and validates a clean Agent.
+ *   - Execution: `run()` handles CLI argument parsing, one-shot calls,
+ *     --help/--info, and interactive CLI startup.
+ *   - In-process handoff: Listens for the 'agent:handoff' event on the active
+ *     Prompt and seamlessly swaps the active agent (including rebinding the
+ *     single long-lived Cli instance when in interactive mode).
+ *
+ * Design highlights:
+ *   - A single Cli instance is kept for the lifetime of the launcher in
+ *     interactive mode. On handoff we call `cli.rebind(...)` instead of
+ *     creating a new Cli (which would duplicate global key handlers).
+ *   - Handoffs are always "fresh": the new agent starts with only its own
+ *     system prompt + the provided context. No conversation history is copied.
+ *   - Same-name "handoff" (self-reset) is supported as a deliberate fresh-start
+ *     / token-reduction mechanism. The current agent is fully replaced with a
+ *     newly loaded instance of itself + the new focused context.
+ *   - Old agents are cleaned up via `destructor()` (removes listeners, aids GC).
+ *   - Works for both interactive CLI and non-interactive / one-shot usage.
+ *
+ * Typical usage (from user code or a thin launcher script):
+ *   ```js
+ *   import { AgentLauncher } from '@j-o-r/hello-dave';
+ *
+ *   const launcher = new AgentLauncher();
+ *   const agents = await launcher.list();
+ *   await launcher.load('code_agent');
+ *   await launcher.run();   // handles argv, one-shot, or interactive CLI
+ *   ```
+ *
+ * Thin launcher example (agents/code_launcher.js style):
+ *   ```js
+ *   import AgentLauncher from '../lib/AgentLauncher.js';
+ *   const launcher = new AgentLauncher();
+ *   await launcher.load('code_agent');
+ *   await launcher.run();
+ *   ```
+ *
+ * Handoff support is automatic once an agent registers the hand_over / load_agent
+ * tools (see lib/handOffToolset.js and agents that call
+ * `toolset.addFrom(API.toolset.generic.handoff, 'hand_over')`).
+ *
+ * @see Agent
+ * @see agentLoader
+ * @see handOffToolset
+ */
+/**
+ * The main launcher for clean Agent-based agents.
+ *
+ * @class AgentLauncher
+ */
+declare class AgentLauncher {
+    /**
+     * Creates a new AgentLauncher.
+     *
+     * Pass `{ from: import.meta.url }` from the consuming project to resolve
+     * project-local agents relative to that project's nearest package.json.
+     *
+     * @constructor
+     * @param {import('./agentLoader.js').AgentLoaderOptions} [options={}] - Loader options.
+     *
+     * @example
+     * const launcher = new AgentLauncher({ from: import.meta.url });
+     * await launcher.load('weather_agent');
+     * await launcher.run();
+     */
+    constructor(options?: import("./agentLoader.js").AgentLoaderOptions);
+    /**
+     * List all discoverable agents without loading or executing any of them.
+     *
+     * Performs a lightweight filesystem scan of the configured agent directory.
+     * For each agent it attempts a safe import to extract
+     * a short description (`desc`). Incompatible agents or agents that throw
+     * on import (side effects, top-level `await agent.run()`, missing exports, etc.)
+     * receive `desc: '[ERROR]'`.
+     *
+     * Search location when constructed with `{ from: import.meta.url }`:
+     *   1. <nearest-package-root-from-from>/agents/
+     *
+     * Only files whose basename matches the valid agent name pattern are returned.
+     * See `lib/agentLoader.js` for the exact regex (`validAgentNameRegex`).
+     *
+     * @async
+     * @returns {Promise<Array<{name: string, path: string, desc: string}>>}
+     *   Array of discovered agents. Each object contains:
+     *   - `name`: the agent identifier (basename without `.js`)
+     *   - `path`: absolute path to the agent module on disk
+     *   - `desc`: short description (from the agent's `description` / `call_description`),
+     *             or the literal string `'[ERROR]'` when the agent is incompatible or fails to load
+     *
+     * @example
+     * const launcher = new AgentLauncher();
+     * const list = await launcher.list();
+     * console.log(list);
+     * // [
+     * //   { name: 'code_agent', path: '/.../agents/code_agent.js', desc: 'Main coding expert. Handles implementation...' },
+     * //   { name: 'weather_agent', path: '/.../agents/weather_agent.js', desc: 'Weather Agent: Specialized in current weather...' },
+     * //   { name: 'test_agent', path: '/.../agents/test_agent.js', desc: '[ERROR]' },
+     * //   ...
+     * // ]
+     *
+     * @example
+     * // Just the names + descriptions
+     * const summary = (await launcher.list()).map(a => `${a.name}: ${a.desc}`);
+     *
+     * @see module:agentLoader#listAgents
+     */
+    list(): Promise<Array<{
+        name: string;
+        path: string;
+        desc: string;
+    }>>;
+    /**
+     * Load a clean Agent by name and make it the active agent.
+     *
+     * If `agentName` is omitted, it is read from the first non-flag positional
+     * argument in `process.argv` (after the script name).
+     *
+     * Internally delegates to `loadAgent()` from the agent loader, which:
+     *   - Resolves the module path (same configured directory as `list()`)
+     *   - Dynamically imports the module
+     *   - Extracts the default export (or factory function)
+     *   - Validates that the result is a proper Agent instance
+     *
+     * After successful load, the previous active agent (if any) is cleaned up
+     * via its `destructor()` method, and the new agent's 'agent:handoff' listener
+     * is attached.
+     *
+     * @async
+     * @param {string} [agentName] - Name of the agent to load (e.g. "code_agent").
+     *   Must be a valid agent name (see agentLoader.js for the pattern).
+     *   If omitted, read from process.argv.
+     * @param {Array<any>} [extraArgs=[]] - Optional arguments passed through to
+     *   the agent module if it exports a factory function instead of an instance.
+     * @returns {Promise<AgentLauncher>} Returns `this` for chaining.
+     * @throws {Error} If no agent name can be determined, or if loading/validation fails.
+     *
+     * @example
+     * const launcher = new AgentLauncher();
+     * await launcher.load('code_agent');
+     *
+     * @example
+     * // Load from argv (typical when used from a thin launcher script)
+     * await launcher.load();   // reads first positional from process.argv
+     *
+     * @example
+     * // With extra args for a factory-style agent
+     * await launcher.load('my_agent', ['--debug']);
+     *
+     * @see module:agentLoader#loadAgent
+     * @see #_setActiveAgent
+     */
+    load(agentName?: string, extraArgs?: Array<any>): Promise<AgentLauncher>;
+    /**
+     * Main entry point. Orchestrates argument parsing and execution mode.
+     *
+     * Behavior (checked in this order):
+     *   1. `--help`   → Print usage and return.
+     *   2. `--info`   → Print agent.info() (or raw agent) and return.
+     *   3. If no active agent → automatically call `load()` (reads from argv).
+     *   4. One-shot mode: if a second positional argument exists after the agent
+     *      name, treat the rest of the line as a message and call
+     *      `activeAgent.directCall(message)`.
+     *   5. Default: start interactive CLI via `#startCli()`.
+     *
+     * @async
+     * @returns {Promise<any>} In one-shot mode, returns the result of directCall.
+     *   In other modes, returns undefined.
+     *
+     * @example
+     * // From a thin launcher script that already called load()
+     * await launcher.run();
+     *
+     * @example
+     * // One-shot usage (message after agent name)
+     * // node ... code_agent "Refactor the Session class"
+     * const result = await launcher.run();
+     *
+     * @see #load
+     * @see #_startCli
+     */
+    run(): Promise<any>;
+    /**
+     * Returns the currently active Agent instance (or null if none loaded).
+     *
+     * @returns {Agent|null}
+     */
+    getActiveAgent(): Agent | null;
+    /**
+     * Directly assign an already-created Agent instance as the active agent.
+     *
+     * This is the programmatic alternative to `load()`. Use it when the caller
+     * has constructed an agent manually, or when testing an agent module that is
+     * outside the configured agent loader search paths.
+     *
+     * The previous active agent, if any, is cleaned up via `destructor()`. The new
+     * agent becomes the launcher's active agent and has the launcher's
+     * `agent:handoff` listener attached to its Prompt, just like agents loaded via
+     * `load()`.
+     *
+     * The supplied agent is assumed to be a valid `Agent` instance. Unlike
+     * `load()`, this method does not resolve, import, or validate an agent module
+     * through the configured agent loader.
+     *
+     * @param {Agent} newAgent - Existing Agent instance to make active.
+     * @returns {AgentLauncher} Returns `this` for chaining.
+     *
+     * @example
+     * const launcher = new AgentLauncher();
+     * launcher.setActiveAgent(agent);
+     * await launcher.run();
+     *
+     * @see #load
+     * @see #getActiveAgent
+     */
+    setActiveAgent(newAgent: Agent): AgentLauncher;
+    /**
+     * Returns the Prompt belonging to the active agent (or null).
+     *
+     * Useful for advanced scenarios where you need direct access to the
+     * underlying prompt (e.g. to listen to events manually).
+     *
+     * @returns {import('./Prompt.js').default|null}
+     */
+    getPrompt(): import("./Prompt.js").default | null;
+    /**
+     * Returns the Session belonging to the active agent (or null).
+     *
+     * @returns {import('./Session.js').default|null}
+     */
+    getSession(): import("./Session.js").default | null;
+    /**
+     * The name of the currently active agent (or 'no_name' if none loaded).
+     *
+     * @type {string}
+     */
+    get name(): string;
+    #private;
+}
+import Agent from './Agent.js';