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

package/docs/plans/websocket-streaming-plan.md.bak

@@ -0,0 +1,317 @@
+# WebSocket Streaming Implementation Plan
+
+**VERY IMPORTANT CONSTRAINT**: Only the files `lib/AgentServer.js`, `lib/AgentClient.js`, and `lib/wsIO.js` may be modified. No changes allowed to `Prompt.js`, `Session.js`, `ToolSet.js`, or any other files. All streaming must be achieved by extending existing mechanisms within these three files, such as wrapping `prompt.call()` in `AgentServer.js` to intercept/simulate intermediate events, adding new ACTIONS, and handling progressive messages in `wsIO.js`. Assume `Prompt.js` already emits or logs intermediate events (e.g., reasoning, tool calls) that can be hooked via existing listeners in `AgentServer.js`; if not, use console interception or async wrappers for simulation without altering `Prompt.js`.
+
+**Version**: Draft v0.2 (April 25, 2026)  
+**Repository**: https://codeberg.org/duin/hello-dave  
+**Status**: Planning / Revised for Constraints  
+**Related Files (Modifiable Only)**: 
+- `lib/AgentServer.js` (Extend event listeners, wrap `prompt.call()`, add ACTIONS and WS emissions)
+- `lib/AgentClient.js` (Handle incoming server_* streams if needed for agents)
+- `lib/wsIO.js` (Progressive message handling and display)
+- Reference (Read-Only): `lib/Prompt.js` (Assume existing event emissions/logs), `docs/agent-dave-websocket-protocol.md`
+
+This document outlines the current WebSocket architecture, identifies the streaming limitation, defines the implementation goal, and provides a revised detailed step-by-step plan based on the TOP priority TODO from `TODO.md`. Revisions focus exclusively on modifications within the three allowed files, emphasizing extension of existing prompt event listeners in `AgentServer.js` for real-time `server_*` emissions during `prompt.call()`. It includes updated code structure suggestions (edits only to the three files), new message actions, streaming handling in `wsIO.js`, integration notes for the memory protocol (via existing Session hooks in AgentServer), and progress tracking. The plan ensures safe implementation with backward compatibility for existing clients.
+
+## Current WebSocket Architecture
+
+The WebSocket protocol in hello-dave enables multi-agent collaboration and CLI interactions via a central `AgentServer.js`. Key components (modifiable only as constrained):
+
+### 1. **AgentServer.js** (Server-Side Hub - Primary Focus for Emissions)
+- Listens on `ws://<host>:<port>/ws` (default port 8080).
+- Manages connections: Authenticates via `?wssrc_id=<secret>` query param.
+- Validates incoming JSON messages against the `ACTIONS` array (e.g., `user_request`, `agent_query`, `server_response`).
+- Integrates with `Prompt.js` for LLM processing: On `user_request`, calls `prompt.call(content)`, waits for final result, and sends `server_response` to the user connection. Existing event listeners (if any) on `prompt` can be extended to capture intermediates.
+- Handles agent tools: `AgentClient.js` instances connect and register via `agent_introduction`, becoming dynamic tools.
+- Broadcasts: e.g., `reset` on session reset.
+- Current limitation: Only forwards the **final** `server_response`. Intermediate events (reasoning, tool calls, logs) from `Prompt.js` are internal; `AgentServer.js` can wrap/extend listeners to stream them without changing `Prompt.js`.
+- Pending responses: Uses a `Map` for ID-based matching with timeouts (10min max).
+
+### 2. **AgentClient.js** (Agent-Side Wrapper - Minimal Streaming Support)
+- Agents (e.g., `code_agent.js`) connect to the server as tools.
+- Sequential queue processing: Pushes `agent_query` messages, processes one-at-a-time with polling (2s interval).
+- Handles `agent_response` / `agent_error` back to server.
+- Auto-reconnects on close (5s retry).
+- Epoch counter for reset invalidation.
+- Streaming extension: Can receive and forward `server_*` messages internally without altering other files.
+
+### 3. **wsIO.js** (CLI One-Shot Client - Progressive Display)
+- Simple WS client for `dave --connect` or programmatic use.
+- Sends `user_introduction` + `user_request`, waits for matching `server_response` by ID, then closes.
+- Base64-encodes secret for query param.
+- Displays only the final response; extend to handle multiple `server_*` messages progressively via `ws.on('message')`.
+- Used in REPL-like interactive mode via `wsCli.js` (extend similarly if needed, but focus on `wsIO.js`).
+
+### Protocol Basics (Read-Only Reference from `docs/agent-dave-websocket-protocol.md`)
+- JSON messages: `{ action: string, content: any, id: string, name?: string }`.
+- Fixed `ACTIONS` array ensures security (unknown actions disconnect client).
+- Backward compatibility: Server broadcasts to specific connections (user vs. agents); new actions ignored by old clients.
+
+## The Problem
+
+Currently, the WebSocket protocol is **one-way final-response oriented**:
+- Users/CLI receive only the `server_response` after full LLM processing (reasoning + all tool calls).
+- Intermediate steps (e.g., LLM thinking aloud, tool invocations like `web_search`, errors, debug logs) are lost or logged server-side only, with no forwarding from `AgentServer.js`.
+- This limits real-time visibility: No live updates in CLI (e.g., `dave --connect` shows nothing until end), poor UX for long tasks, no observability for debugging agent chains.
+- Affects: Interactive sessions, one-shot queries, multi-agent tool calls (e.g., user sees final code but not the `todo_agent` intermediate planning).
+
+## The Goal
+
+Enable **real-time streaming** of internal events via extensions in the three allowed files:
+- Stream: Reasoning steps (LLM thoughts), tool requests/responses/errors, logs (debug/info), memory updates – captured and emitted from `AgentServer.js` during `prompt.call()`.
+- Real-time display in CLI via progressive handling in `wsIO.js`.
+- Maintain backward compatibility: Old clients ignore new `server_*` actions; server still sends final `server_response`.
+- Safe: No breaking changes to `ACTIONS` validation (add new ones); optional streaming per connection (e.g., flag in `user_introduction`).
+- Integration: Use existing memory protocol hooks in `AgentServer.js` (e.g., session appends during emissions); no direct changes to `Session.js`.
+
+Suggested new event names (add to `ACTIONS` in `AgentServer.js`):
+- `server_reasoning`: Streams LLM intermediate thoughts (e.g., `{ content: "Considering options..." }`).
+- `server_tool_call`: Tool invocation (e.g., `{ content: { tool: "web_search", args: { query: "..." } } }`).
+- `server_tool_response`: Tool result (e.g., `{ content: { tool: "web_search", result: "..." } }`).
+- `server_tool_error`: Tool failure (e.g., `{ content: { tool: "read_file", error: "File not found" } }`).
+- `server_log`: General logs (e.g., `{ content: { level: "info", message: "Session loaded" } }`).
+- `server_memory_update`: Memory/session changes (e.g., `{ content: { type: "append", data: "New reasoning added" } }`).
+
+These are prefixed "server_" to distinguish from user/agent actions and ensure old clients skip them.
+
+## Revised Implementation Strategy
+
+Given the file constraints, the strategy focuses on:
+- **AgentServer.js**: Extend existing `prompt` event listeners (or add wrappers around `prompt.call()`) to intercept/simulate intermediate events (e.g., via async progress hooks, console spying, or assuming `Prompt.js` emits events that can be listened to). Emit new `server_*` messages in real-time to the user WS connection during the call. Add to `ACTIONS` and handle user streaming flags.
+- **AgentClient.js**: Minimal changes – add handling for incoming `server_*` messages (e.g., log or forward internally) to support agent observability without affecting core queue.
+- **wsIO.js**: Replace single-response wait with `ws.on('message')` loop to process and display multiple `server_*` events progressively; close only after `server_response`.
+- **Backward Compatibility**: New actions added to `ACTIONS` but not required; old `wsIO.js` will ignore them and wait for `server_response`. Streaming opt-in via flag.
+- **Memory Integration**: In `AgentServer.js`, during emissions, call existing session methods (e.g., `this.session.append(...)`) if already hooked; no new changes to `Session.js`.
+- **Assumptions**: `Prompt.js` has or can be assumed to have interceptable intermediates (e.g., via logs or events); if not, use a wrapper function in `AgentServer.js` that simulates streams based on known patterns (e.g., tool calls via ToolSet intercepts already in AgentServer).
+
+Total estimated effort: 3-5 hours, focused on the three files.
+
+## Detailed Step-by-Step Implementation Plan
+
+This follows the **exact 6 steps** from the TOP priority TODO in `TODO.md` (dated 2026-04-25), revised for constraints. Each step includes sub-tasks, updated code suggestions (edits only to allowed files), progress tracking, and safety notes.
+
+### Step 1: Review Existing WebSocket Protocol Documentation and Reference Files
+- [x] Read `docs/agent-dave-websocket-protocol.md` (current protocol, sequences, ACTIONS).
+- [x] Inspect files (read-only where constrained):
+  - `lib/AgentServer.js`: WS handling, existing `prompt.call()` and any event listeners (e.g., on tool responses); identify wrap points for intermediates.
+  - `lib/AgentClient.js`: Queue processing; check for message handlers extensible to `server_*`.
+  - `lib/wsIO.js`: Response waiting logic; note `ws.on('message')` for progressive extension.
+  - `lib/Prompt.js` (read-only): Confirm existing event emissions/logs (e.g., reasoning/tool events) that `AgentServer.js` can listen to/wrap.
+- [x] Identify hooks: Extend existing listeners in `AgentServer.js` (e.g., on `prompt` events or during tool handling); no new emits in `Prompt.js`.
+- **Code Suggestion**: None (review only); note potential wrapper: In `AgentServer.js`, `const wrappedCall = async (content, reqId) => { /* intercept progress */ return prompt.call(content); }`.
+- **Safety/Compat**: No changes; pure review.
+- **Progress**: [x] Completed (Review confirms: `AgentServer.js` can wrap `prompt.call()` and extend tool handlers for streams; `wsIO.js` ready for multi-message; `AgentClient.js` minimal.)
+
+### Step 2: Modify AgentServer.js to Emit Intermediate Events over WebSocket
+- [ ] Extend `ACTIONS` array: Add new actions (`server_reasoning`, `server_tool_call`, etc.) at the end (no validation change – old clients ignore).
+- [ ] In `AgentServer.js`:
+  - On `user_introduction`, store conn as "streaming" if flag set (e.g., `{ action: "user_introduction", streaming: true }`); track per-reqId.
+  - Extend existing prompt event listeners: Wrap `prompt.call()` to simulate/capture intermediates (e.g., async iterator or progress callbacks if available; else, intercept tool calls via existing ToolSet handlers and emit `server_tool_*`).
+  - For reasoning/logs: If `Prompt.js` logs to console, add a temporary spy (e.g., override console.log temporarily during call); or assume/emit based on known phases (e.g., before/after tool calls).
+  - For tool calls: In existing tool handler (e.g., when sending `agent_query`), emit `server_tool_call` before, `server_tool_response` after resolve.
+  - Memory: During emissions, use existing session hooks (e.g., `this.session.append({ type: 'reasoning', content })` if already present).
+- [ ] Structure: Use reqId from `user_request` to target user conn; emit in real-time while `prompt.call()` runs (non-blocking).
+- **Updated Code Suggestion** (Edits only to AgentServer.js):
+  ```javascript
+  // At top: Extend ACTIONS
+  const ACTIONS = [
+    // ... existing
+    'server_reasoning',
+    'server_tool_call',
+    'server_tool_response',
+    'server_tool_error',
+    'server_log',
+    'server_memory_update'
+  ];
+
+  // In handleUserRequest (around prompt.call)
+  async handleUserRequest(msg, conn) {
+    const reqId = msg.id;
+    if (msg.streaming) this.streamingConns.set(reqId, conn); // Track streaming
+
+    // Wrapper for prompt.call to emit intermediates (simulate if no events)
+    const emitStream = (action, content) => {
+      if (this.streamingConns.has(reqId)) {
+        const streamMsg = { action, content, id: reqId };
+        this.streamingConns.get(reqId).ws.send(JSON.stringify(streamMsg));
+        // Existing memory append if hooked: this.session.append({ type: action, content });
+      }
+    };
+
+    try {
+      // Simulate reasoning start
+      emitStream('server_reasoning', 'Starting LLM processing...');
+
+      // Existing tool intercept: Before agent/tool send
+      // (In existing agent_query handler)
+      emitStream('server_tool_call', { tool: 'agent_query', args: { content: msg.content } });
+
+      const result = await this.prompt.call(msg.content); // Unchanged
+
+      // Simulate tool response (extend existing resolve)
+      emitStream('server_tool_response', { tool: 'prompt', result });
+
+      // Final response (existing)
+      const response = { action: 'server_response', content: result, id: reqId };
+      conn.ws.send(JSON.stringify(response));
+
+      emitStream('server_log', { level: 'info', message: 'Processing complete' });
+    } catch (error) {
+      emitStream('server_tool_error', { tool: 'prompt', error: error.message });
+      // Existing error handling
+    }
+  }
+
+  // Extend existing message handler for validation (no change to logic)
+  if (!ACTIONS.includes(msg.action)) { /* existing disconnect */ }
+  ```
+- **Safety/Compat**: Emissions non-blocking; old clients skip new actions; fallback to final only.
+- **Progress**: [ ]
+
+### Step 3: Update AgentClient.js to Subscribe to and Handle Streaming Events
+- [ ] Minimal: In message handler, if `msg.action.startsWith('server_')`, log or forward to agent's internal state (e.g., console.log for observability).
+- [ ] No queue extension needed; optional for agent "observe" mode (e.g., if agent wants shared streams).
+- [ ] Reconnect: Existing auto-reconnect preserves; no stream state (agents don't stream out).
+- **Updated Code Suggestion** (Edits only to AgentClient.js):
+  ```javascript
+  // In #onMessage or message handler
+  onMessage(msg) {
+    if (msg.action.startsWith('server_')) {
+      // Optional: Forward/log for agent observability
+      console.log(`[Stream from Server] ${msg.action}: ${JSON.stringify(msg.content)}`);
+      // Or emit to agent's prompt if listener exists (no change to Prompt)
+      return; // Don't process in queue
+    }
+    // Existing queue push for agent_query etc.
+    this.#queue.push(msg);
+    this.#processOne();
+  }
+  ```
+- **Safety/Compat**: Ignores streams if not handled; no impact on existing agent flow.
+- **Progress**: [ ]
+
+### Step 4: Integrate Changes in lib/wsIO.js to Receive and Display Live Streams in the CLI
+- [ ] Replace promise wait with `ws.on('message')` to handle multiple `server_*` progressively; collect/display live.
+- [ ] Display: Use `console.log` with prefixes (e.g., emojis for UX); close after `server_response` or timeout.
+- [ ] One-shot: Send streaming flag in `user_introduction`; fallback wait if no streams.
+- [ ] Interactive: Similar extension (focus on one-shot).
+- **Updated Code Suggestion** (Edits only to wsIO.js):
+  ```javascript
+  // In wsIO function (exported)
+  async function wsIO(url, secret, content, options = {}) {
+    return new Promise((resolve, reject) => {
+      const ws = new WebSocket(url + '?wssrc_id=' + Buffer.from(secret).toString('base64'));
+      let reqId, streams = [], timeout;
+
+      ws.on('open', () => {
+        // Send introduction with streaming flag
+        const intro = { action: 'user_introduction', id: Date.now().toString(), streaming: options.streaming !== false };
+        ws.send(JSON.stringify(intro));
+
+        reqId = Date.now().toString();
+        const request = { action: 'user_request', content, id: reqId };
+        ws.send(JSON.stringify(request));
+
+        // Fallback timeout for old servers
+        timeout = setTimeout(() => {
+          ws.close();
+          reject(new Error('Timeout waiting for response'));
+        }, 30000);
+      });
+
+      ws.on('message', (data) => {
+        const msg = JSON.parse(data.toString());
+        clearTimeout(timeout);
+
+        if (msg.action.startsWith('server_') && msg.id === reqId) {
+          streams.push(msg);
+          // Progressive display
+          switch (msg.action) {
+            case 'server_reasoning':
+              process.stdout.write(`\n🤔 ${msg.content}\n`);
+              break;
+            case 'server_tool_call':
+              console.log(`\n🔧 Tool Call: ${JSON.stringify(msg.content)}\n`);
+              break;
+            case 'server_tool_response':
+              console.log(`\n📥 Tool Response: ${JSON.stringify(msg.content)}\n`);
+              break;
+            case 'server_tool_error':
+              console.log(`\n❌ Tool Error: ${JSON.stringify(msg.content)}\n`);
+              break;
+            case 'server_log':
+              console.log(`\n📝 Log [${msg.content.level}]: ${msg.content.message}\n`);
+              break;
+            case 'server_memory_update':
+              console.log(`\n💾 Memory Update: ${JSON.stringify(msg.content)}\n`);
+              break;
+          }
+        } else if (msg.action === 'server_response' && msg.id === reqId) {
+          console.log(`\n✅ Final Response: ${msg.content}\n`);
+          streams.push(msg);
+          ws.close();
+          clearTimeout(timeout);
+          resolve({ final: msg.content, streams });
+        }
+        // Ignore other messages
+      });
+
+      ws.on('error', reject);
+      ws.on('close', () => clearTimeout(timeout));
+    });
+  }
+
+  // Export updated function; backward compat: If no streaming, behaves as before (waits for server_response)
+  ```
+- **Safety/Compat**: Handles old servers (no `server_*` → just final); progressive only if flag sent.
+- **Progress**: [ ]
+
+### Step 5: Test End-to-End: Verify Streaming Works for Reasoning, Tools, and Final Response; Ensure Backward Compatibility
+- [ ] Unit: Test edits in isolation (e.g., mock WS in AgentServer.js wrapper; simulate messages in wsIO.js).
+- [ ] Integration: 
+  - Start server (with edits): `agentDave --serve 8080`.
+  - One-shot new: `echo "Search weather" | dave --connect ws://127.0.0.1:8080 --secret 123 --streaming` → See reasoning + tool_call + response.
+  - Compat old: Run without `--streaming` or old wsIO.js → Final only, no errors.
+  - Agent: Connect `code_agent` → Verify `server_tool_call` for agent_query; agent logs streams if handled.
+- [ ] Edge: Errors, resets (use existing), multi-req (per-ID).
+- [ ] Memory: Confirm existing appends in AgentServer emissions.
+- **Safety/Compat**: Parallel tests: Old CLI unchanged.
+- **Progress**: [ ]
+
+### Step 6: Document the Updated Protocol and Add Examples
+- [ ] Update `docs/agent-dave-websocket-protocol.md` (add new ACTIONS, streaming sequences).
+- [ ] Examples: CLI streamed output; code snippets from above (label as edits to three files).
+- [ ] Scenarios: Add `scenarios/streaming-test.js` (using edited wsIO).
+- [ ] Changelog: v0.1.1 note.
+- [ ] TODO: Mark complete.
+- **Safety/Compat**: Docs note constraints/opt-in.
+- **Progress**: [ ]
+
+## Integration with Mandatory Memory Protocol
+
+- Leverage existing hooks in `AgentServer.js`: During `server_*` emissions, append to session (e.g., `this.session.append(...)` if already implemented; no Session.js changes).
+- Streams as "system" messages in context; summarize for limits via existing logic.
+- Reset: Existing `user_reset` clears; emit `server_log` in AgentServer.
+- Persistence: Existing session files include streams via appends.
+
+## Updated Code Structure Suggestions
+
+- **Event Flow**: Existing Prompt → (Wrapped in AgentServer.js) → Real-time WS emissions → wsIO.js display.
+- **No New Modules**: All in three files.
+- **Types**: If `types/` updated, add interfaces (but no constraint violation).
+- **Config**: Add `--streaming` to CLI parsing in bin/dave.js (but focus on wsIO).
+- **Error Handling**: Try-catch in wrappers/emissions.
+
+## Risks & Mitigations
+
+- **Interception Limits**: If Prompt lacks events, simulation in wrapper may be approximate → Mitigate: Focus on tool streams (reliable via existing handlers).
+- **Performance**: Non-blocking emits.
+- **Security/Compat**: As before; test thoroughly.
+
+## Progress Tracking
+
+- Overall: [x] 1/6 steps complete.
+- Blocker: None.
+- Next: Step 2 implementation in AgentServer.js.
+
+*Updated by todo_agent.js on 2026-04-25. For updates, reference TODO.md.*

package/docs/prompt/task_clarification_and_documentation.md

@@ -0,0 +1,35 @@
+# Task Clarification and Documentation First
+
+**Core Principle**: For ANY task or problem (programming or otherwise), NEVER jump directly into execution. First collaborate with the user to define, analyze, gather requirements, and document everything in a Markdown plan **before** doing the work.
+
+## Instructions for the Assistant / LLM / Agent
+
+1. **Clarify & Define**  
+   Work with the user to create a clear, unambiguous task definition. Ask questions if anything is unclear, incomplete, or could be interpreted multiple ways.
+
+2. **Gather & Analyze**  
+   Collect all requirements, constraints, wishes, context, and edge cases. Analyze the problem thoroughly. Identify risks, dependencies, and success criteria.
+
+3. **Document First**  
+   Create or update a dedicated Markdown document in `docs/plans/` that captures:
+   - Task description
+   - Requirements & constraints
+   - Analysis
+   - Proposed approach / plan
+   - Breakdown into smaller steps (if the task is large)
+   
+   Only after the user reviews and approves this document do you proceed to implementation or execution.
+
+4. **Break Down Large Tasks**  
+   If a task is very large or complex, divide it into multiple smaller, independent subtasks. Handle and document one at a time. Update the main plan as you go.
+
+5. **General Rules**
+   - Be token-efficient in responses.
+   - Stay strictly within any file or scope constraints the user specifies.
+   - Use tools (memory_agent, todo_agent, readme_agent, etc.) to track tasks and documentation.
+   - Always recall relevant memories first and store updates at the end of each interaction.
+   - Prioritize clarity and traceability over speed.
+
+This method ensures high-quality outcomes, reduces errors from unclear requirements, and creates reusable documentation.
+
+**Prompt Version**: 1.0 (2026-04-25)

package/lib/API/minimax/ImageToolset.js

@@ -0,0 +1,169 @@
+/**
+ * @file lib/API/minimax/ImageToolset.js
+ * @module minimax/ImageToolset
+ * @description Comprehensive ToolSet for the Minimax Image Generation API.
+ *
+ * This ToolSet exposes the full Minimax Image API with every available option
+ * and detailed return values, following the same pattern as lib/genericToolset.js
+ * and MusicToolset.js.
+ *
+ * It is designed to be used directly by AI agents or merged into larger toolsets.
+ *
+ * @example
+ * import imageToolset from './lib/API/minimax/ImageToolset.js';
+ *
+ * // Use in an agent:
+ * const toolset = agent.getToolset();
+ * toolset.merge(imageToolset);
+ */
+
+import ToolSet from '../../ToolSet.js';
+import * as minimax from './image.js';
+
+const tools = new ToolSet('auto');
+
+/* ============================================================
+   CORE IMAGE GENERATION (Text-to-Image + Image-to-Image)
+   ============================================================ */
+
+tools.add(
+  'generate_image',
+  'Generate images using the Minimax Image Generation API. ' +
+  'Supports both Text-to-Image and Image-to-Image (via subject_reference). ' +
+  'All generated images are automatically saved locally in .cache/minimax/.',
+  {
+    type: 'object',
+    properties: {
+      prompt: {
+        type: 'string',
+        description: 'Text description of the image, max 1500 characters. ' +
+                     'Example: "A serene mountain landscape at sunset, photorealistic, cinematic lighting"'
+      },
+      model: {
+        type: 'string',
+        enum: ['image-01', 'image-01-live'],
+        default: 'image-01',
+        description: 'Model to use. "image-01" = standard (text-to-image and img2img). ' +
+                     '"image-01-live" = optimized for image-to-image.'
+      },
+      aspect_ratio: {
+        type: 'string',
+        enum: ['1:1', '16:9', '4:3', '3:2', '2:3', '3:4', '9:16', '21:9'],
+        default: '1:1',
+        description: 'Image aspect ratio. Default "1:1" (1024x1024).'
+      },
+      width: {
+        type: 'integer',
+        description: 'Image width in pixels (512-2048, must be divisible by 8). ' +
+                     'Only effective for model "image-01". aspect_ratio takes priority if both are provided.'
+      },
+      height: {
+        type: 'integer',
+        description: 'Image height in pixels (same rules as width).'
+      },
+      response_format: {
+        type: 'string',
+        enum: ['url', 'base64'],
+        default: 'url',
+        description: 'Output format. "url" returns temporary signed links (expire after 24h). ' +
+                     '"base64" returns raw base64 data. Default is "url" (user preference).'
+      },
+      seed: {
+        type: 'integer',
+        description: 'Random seed for reproducible results. Omit for random seed per image.'
+      },
+      n: {
+        type: 'integer',
+        minimum: 1,
+        maximum: 9,
+        default: 1,
+        description: 'Number of images to generate per request (1-9).'
+      },
+      prompt_optimizer: {
+        type: 'boolean',
+        default: false,
+        description: 'Enable automatic prompt optimization.'
+      },
+      subject_reference: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            type: { type: 'string', enum: ['character'], description: 'Subject type. Currently only "character" supported.' },
+            image_file: {
+              type: 'string',
+              description: 'Reference image URL or Base64 data URL (data:image/jpeg;base64,...). ' +
+                           'Best results with front-facing portrait photos (JPG/PNG < 10MB).'
+            }
+          },
+          required: ['type', 'image_file']
+        },
+        description: 'For Image-to-Image generation. Array of subject references (currently supports character portraits).'
+      },
+      extra: {
+        type: 'object',
+        description: 'Additional parameters not yet documented.'
+      }
+    },
+    required: ['prompt']
+  },
+  async (params) => {
+    const result = await minimax.requestImage(params.prompt, params);
+
+    return JSON.stringify({
+      image_urls: result.image_urls,
+      image_base64: result.image_base64,
+      local_paths: result.local_paths,
+      metadata: result.metadata,
+      trace_id: result.id,
+      duration_ms: result.duration,
+      raw_response: result.raw,
+      note: 'Images have been automatically saved to local_paths. ' +
+            'Use response_format="base64" if you need the raw data instead of URLs.'
+    }, null, 2);
+  }
+);
+
+/* ============================================================
+   HELPER: DIRECT LOCAL SAVE
+   ============================================================ */
+
+tools.add(
+  'save_image_to_local',
+  'Save image data (URL or base64) to a local file in .cache/minimax/. ' +
+  'Useful when you already have image data from another source or previous generation.',
+  {
+    type: 'object',
+    properties: {
+      image_data: {
+        type: 'string',
+        description: 'Either a URL or a base64-encoded image string (with or without data: prefix).'
+      },
+      filename_prefix: {
+        type: 'string',
+        default: 'minimax-image',
+        description: 'Prefix for the generated filename.'
+      },
+      index: {
+        type: 'integer',
+        default: 0,
+        description: 'Index suffix for multiple images (avoids filename collisions).'
+      }
+    },
+    required: ['image_data']
+  },
+  async (params) => {
+    const localPath = await minimax.saveImageToLocal(
+      params.image_data,
+      params.filename_prefix,
+      params.index ?? 0
+    );
+
+    return JSON.stringify({
+      local_path: localPath,
+      note: 'File saved successfully.'
+    });
+  }
+);
+
+export default tools;