@j-o-r/hello-dave 0.0.9 → 0.1.0

package/agents/stability.js

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+import { AgentManager, API, CdnToolset } from '@j-o-r/hello-dave';
+import * as test from '@j-o-r/hello-dave';
+import { parseArgs } from '@j-o-r/sh';
+
+const name = 'stability';
+const api = 'xai';
+let secret = '';
+
+const args = parseArgs();
+
+let input;
+if (args._.length === 1 && typeof args._[0] === 'string' && args._[0].trim() !== '') {
+	input = args._[0].trim();
+}
+
+const help = args['help'] || false;
+const connect = args['connect'] ? args['connect'] : undefined;
+const serve = args['serve'] ? parseInt(args['serve']) : undefined;
+
+/** @type {import('lib/API/x.ai/responses.js').XAIOptions} */
+const options = { tools: [] };
+options.tools.push({
+	type: 'web_search'
+});
+
+if (args['secret']) {
+	secret = args['secret'];
+}
+if (args['model'] || true) {
+	options.model = args['model'] || 'grok-4-fast-reasoning';
+}
+if (args['temperature']) {
+	options.temperature = parseFloat(args['temperature']);
+} else {
+	options.temperature = 0.8;
+}
+if (args['tokens']) {
+	options.max_output_tokens = parseInt(args['tokens']);
+}
+if (args['top_p']) {
+	options.top_p = parseFloat(args['top_p']);
+}
+const reasoning = true;
+if (reasoning) {
+	options.reasoning = {
+		effort: 'medium',
+		summary: 'auto'
+	}
+}
+const toolsetMode = 'auto';
+const contextWindow = args['context'] ? parseInt(args['context']) : 1900000;
+
+function printHelp() {
+	console.log(`
+'${name} --help' You are looking at it.
+
+## USAGE MODES:
+
+### 1. Direct Call (One-Shot, Positional ONLY):
+./agents/${name}.js "Generate lyrics for pop song" [--options]
+
+### 2. Interactive CLI (no positional arg):
+./agents/${name}.js [--options]
+
+### 3. WS Server (no positional arg):
+./agents/${name}.js --serve 8080 [--secret mysecret] [--options]
+
+### 4. WS Client (no positional arg):
+./agents/${name}.js --connect ws://127.0.0.1:8080/ws --secret mysecret [--options]
+
+### 5. Hybrid (Server + Client, no positional arg):
+./agents/${name}.js --serve 8081 --connect ws://other:8080/ws [--secret ...] [--options]
+
+## SERVER OPTIONS EXPLAINED:
+--serve [port]: Starts WebSocket SERVER at ws://127.0.0.1:[port]/ws. Allows other agents (--connect) to connect and use this agent as a remote TOOL (e.g., 'daisy_agent'). Runs indefinitely until Ctrl+C.
+
+--connect [ws_url]: Connects as CLIENT to remote WS server at [ws_url] (e.g., ws://127.0.0.1:8080/ws). Gains access to remote agent's tools. Interactive CLI available.
+
+--secret [string]: SHARED AUTH TOKEN (min 3 chars). SERVER rejects clients without matching --secret. CLIENTS must provide server's secret to connect. Use same secret for chains.
+
+Note: Server/Client/Hybrid IGNORES positional input arg (use CLI modes instead). Hybrid: This agent serves AND uses remote tools.
+
+## OPTIONS:
+--model [grok-4-fast-reasoning|...] (default: grok-4-fast-reasoning)
+--temperature [float] (-2 to +2, default 0.8 for creativity)
+--tokens [number] (max output tokens)
+--top_p [float]
+--context [number] (default: 1900000)
+
+## SERVER TOOLS (when no input):
+Exposes as 'daisy_agent' tool for chaining.
+`);
+	process.exit();
+}
+
+if (help) {
+	printHelp();
+}
+
+const tool_call_name = 'daisy_agent';
+const tool_call_description = `
+Daisy Music Assistant:
+- "Lyrics for [theme]" → Generate lyrics.
+- "Music minimax prompt: [style]" → Optimized prompt.
+- "ffmpeg [task] on file.wav" → Bash script to run.
+- web_search: Research chords/lyrics.
+- execute_bash_script: Processes your local files safely.
+- Create music 
+`.trim();
+
+const prompt = `
+You are ${name}, a helpful music creation and editing assistant for the user's computer.
+
+Core expertise:
+- Generate lyrics: Creative, structured (verses, chorus), themed, rhyming.
+- niMAx 2.6 AI prompts: Detailed, vivid descriptions (genre, mood, instruments, structure, vocals).
+- Local audio editing: Use execute_bash_script with ffmpeg/sox commands. Provide exact bash snippets first, confirm before running. Examples:
+  * Trim: ffmpeg -i input.mp3 -ss 00:00:30 -t 00:01:00 output.mp3
+  * Concat: echo "file 'a.mp3'" > list.txt; ffmpeg -f concat -i list.txt out.mp3
+  * Sox effects: sox input.wav output.wav fade 0 3 2 norm
+  * Convert: ffmpeg -i video.mp4 audio.aac
+- Music theory: Chords, scales, BPM, EQ tips.
+- Workflows: Step-by-step for mixing, mastering, layering tracks.
+
+Behavior:
+- Be creative & enthusiastic!
+- Step-by-step: Explain, provide code, suggest files in current dir.
+- Safety: Quote bash commands; ask confirmation for destructive ops (e.g., overwrite).
+- Use web_search for inspiration/lyrics if needed.
+- Output ready-to-copy bash for ffmpeg/sox.
+- List files if unclear: Use ls *.wav *.mp3 etc. via bash.
+
+Current env: Ubuntu, ffmpeg & sox installed
+
+Respond concisely but completely. Use markdown for code/lyrics/prompts.
+`.trim();
+
+const agent = new AgentManager({ name, secret });
+agent.setup({
+	prompt,
+	api,
+	options,
+	toolsetMode,
+	contextWindow
+});
+const toolset = agent.getToolset();
+toolset?.borrow(API.stability.musicToolset);
+toolset?.borrow(CdnToolset);
+if (toolset) {
+	agent.addGenericToolcall('open_link');
+	agent.addGenericToolcall('execute_bash_script');
+	agent.addGenericToolcall('read_file');
+	agent.addGenericToolcall('write_file');
+}
+
+const cliIntro = `
+${name} ${options.model} ready! (temp: ${options.temperature}, context: ${contextWindow})
+
+Ask me to:
+- Write lyrics
+- Craft Music prompts
+- Edit audio: "fade out my track.mp3" → I'll give ffmpeg cmd
+Type /help for more.
+${tool_call_name}
+`.trim();
+
+if (input) {
+	const RES = await agent.directCall(input);
+	console.log(RES);
+} else {
+	await agent.start(serve, connect, cliIntro, tool_call_name, tool_call_description);
+}

package/bin/codeDave

@@ -52,7 +52,7 @@ pm2 start "${PROJECT_DIR}/agents/npm_agent.js"    --name "${FOLDER}_npm_${PORT}"
 pm2 start "${PROJECT_DIR}/agents/docs_agent.js"   --name "${FOLDER}_docs_${PORT}"   -- --connect "ws://127.0.0.1:${PORT}/ws" --secret "${SECRET}"
 pm2 start "${PROJECT_DIR}/agents/test_agent.js"   --name "${FOLDER}_test_${PORT}"   -- --connect "ws://127.0.0.1:${PORT}/ws" --secret "${SECRET}"
 pm2 start "${PROJECT_DIR}/agents/memory_agent.js" --name "${FOLDER}_memory_${PORT}" -- --connect "ws://127.0.0.1:${PORT}/ws" --secret "${SECRET}"
-pm2 start "${PROJECT_DIR}/agents/spawn_agent.js"  --name "${FOLDER}_spawn_${PORT}"    -- --connect "ws://127.0.0.1:${PORT}/ws" --secret "${SECRET}"
+# pm2 start "${PROJECT_DIR}/agents/spawn_agent.js"  --name "${FOLDER}_spawn_${PORT}"    -- --connect "ws://127.0.0.1:${PORT}/ws" --secret "${SECRET}"
 
 echo "codeDave processes spawned with prefix '${FOLDER}_' and suffix _${PORT}. Check with: pm2 list | grep '${FOLDER}_${PORT}'"
 echo "dave --connect ws://127.0.0.1:${PORT}/ws --secret '$SECRET'"

package/bin/dave.js

@@ -97,7 +97,7 @@ if (args.clear) {
 
 			try {
 				const response = await wsIO(args.connect, secret, action, input);
-				console.log(response.content);
+				console.log(JSON.stringify(response.content, null, '  '));
 			} catch (e) {
 				console.error(`Error: ${e.message}`);
 				process.exit(1);

package/docs/dependencies.md

@@ -0,0 +1,7 @@
+
+
+## A linux based os with
+
+`node`
+`spellcheck`
+`msmtp`

package/docs/music-toolsets.md

@@ -0,0 +1,137 @@
+# Music Toolsets
+
+**Date:** May 22, 2026  
+**Status:** Implemented and Documented
+
+The `hello-dave` toolkit now includes two specialized **MusicToolsets** for AI-powered music generation and editing:
+
+- **Stability AI MusicToolset** (`API.stability.musicToolset`) — Powered by Stable Audio 3.
+- **Minimax MusicToolset** (`API.minimax.musicToolset`) — Powered by Minimax Music 2.6 / Cover models.
+
+These toolsets are designed for seamless integration into AI agents (via `AgentManager` and `ToolSet.borrow()`). They provide high-level, LLM-friendly tools with rich descriptions, JSON schemas, constraints, examples, and automatic async polling.
+
+## Prerequisites
+
+- **Stability AI**: Set `STABILITY_API_KEY` environment variable (obtain from [platform.stability.ai](https://platform.stability.ai)).
+- **Minimax**: Set `MINIMAX_API_KEY` environment variable.
+- Both toolsets automatically handle local file saving (to `.cache/stability` or equivalent) and support remote URLs where applicable.
+- Optional: `CdnToolset` for publishing results.
+
+## Stability AI MusicToolset
+
+**Location**: `lib/API/stability.ai/MusicToolset.js` (with underlying implementation in `lib/API/stability.ai/audio.js` and specs in `audio-3.md`).
+
+**Key Facts** (for LLMs/agents):
+- Model: `stable-audio-3` (fixed).
+- Cost: 26 credits per successful generation.
+- Max duration: 380 seconds (default ~190s).
+- Output: 44.1 kHz stereo, MP3 (default) or WAV.
+- Prompts: English only; no copyrighted material.
+- Polling: Fully automatic (no manual `fetch_result` needed).
+
+### Available Tools
+
+1. **`text_to_audio`**  
+   Generate original music/sound from a descriptive text prompt.  
+   Parameters: `prompt` (required), `duration`, `output_format`, `seed`, `steps`, `cfg_scale`.  
+   Returns: JSON with `local_path`, `finish_reason`, etc.
+
+2. **`audio_to_audio`**  
+   Transform an existing audio file using a new prompt (style transfer, genre change, etc.).  
+   Supports `audio_url` (remote) or `audio_path` (local).  
+   Parameters: `prompt` (required), `audio_url`/`audio_path`, `strength`, `duration`, etc.
+
+3. **`inpaint`**  
+   Replace a specific timed section of audio using a prompt + mask.  
+   Parameters: `prompt`, `audio_url`/`audio_path`, `mask_start`, `mask_end`, etc.
+
+**Full Documentation**: See the comprehensive JSDoc in `lib/API/stability.ai/MusicToolset.js` and `audio.js`.
+
+## Minimax MusicToolset
+
+**Location**: `lib/API/minimax/MusicToolset.js` (with underlying `lib/API/minimax/music.js`).
+
+**Key Features**:
+- Supports text-to-music, cover generation (one-step and advanced two-step with lyrics modification), analysis/preprocessing, and lyrics generation/editing.
+- Strict mutual-exclusivity guardrails for reference audio vs. `cover_feature_id`.
+- Lyrics optional for instrumental tracks; structured tags supported (`[Verse]`, `[Chorus]`, etc.).
+- Models: `music-2.6`, `music-cover`, etc.
+
+### Available Tools
+
+1. **`create_music`** — Pure text-to-music generation (no reference audio).
+2. **`change_music`** — Cover generation (direct reference or two-step via `analyze_music`).
+3. **`analyze_music`** — Preprocess reference audio to obtain `cover_feature_id` for advanced covers.
+4. **`lyrics`** — Generate, edit, or continue song lyrics (full song or snippets).
+
+**Full Documentation**: See JSDoc in `lib/API/minimax/MusicToolset.js`.
+
+## Usage in Custom Agents
+
+The dedicated example agents demonstrate best practices:
+
+- **`agents/stability.js`** — Music assistant using Stability tools + local editing (ffmpeg/sox via `execute_bash_script`).
+- **`agents/minimax.js`** — Similar assistant using Minimax tools (note: filename uses "minimaxi" internally for display).
+
+### Example Integration Pattern (from the agents)
+
+```javascript
+import { AgentManager, API, CdnToolset } from '@j-o-r/hello-dave';
+
+const agent = new AgentManager({ name: 'my-music-agent', secret: '...' });
+agent.setup({
+  prompt: `You are a music creation assistant...`,
+  api: 'xai',
+  options: { model: 'grok-4-fast-reasoning', temperature: 0.8, ... },
+  toolsetMode: 'auto',
+  contextWindow: 1900000
+});
+
+const toolset = agent.getToolset();
+toolset?.borrow(API.stability.musicToolset);  // or API.minimax.musicToolset
+toolset?.borrow(CdnToolset);
+
+if (toolset) {
+  agent.addGenericToolcall('execute_bash_script');
+  agent.addGenericToolcall('read_file');
+  agent.addGenericToolcall('write_file');
+  // ... other tools
+}
+
+await agent.start(/* serve/connect options */);
+```
+
+**Agent Prompts**: Both examples include rich system prompts covering lyrics generation, music theory, local audio editing with ffmpeg, safety confirmations, and step-by-step workflows.
+
+**CLI Usage**:
+```bash
+node agents/stability.js "Create an epic orchestral track"
+node agents/minimax.js "Generate a jazz cover of my song"
+# Or run as server/client for chaining with other agents
+```
+
+## Best Practices & Notes
+
+- **Local-First**: Generated audio is saved locally by default (never auto-CDN unless using CdnToolset explicitly).
+- **Error Handling**: Toolsets include robust validation, polling, and error messages. Stability has a known note on remote audio URL handling (MIME type detection for FormData in `audioToAudio`).
+- **Parity**: The Stability implementation was modeled directly after the Minimax one for consistency (same tool patterns, JSDoc style, demo structure).
+- **Demos**: See `scenarios/demo-stability-audio.js` (modeled after Minimax demo).
+- **Extensibility**: Borrow additional toolsets (e.g., `CdnToolset`) or generic tools as needed.
+- **LLM-Friendly**: All tool descriptions are optimized for function-calling with examples, constraints, defaults, and usage guidance.
+
+## Related Files
+
+- `lib/API/stability.ai/MusicToolset.js`
+- `lib/API/stability.ai/audio.js`
+- `lib/API/stability.ai/audio-3.md`
+- `lib/API/minimax/MusicToolset.js`
+- `lib/API/minimax/music.js`
+- `agents/stability.js`
+- `agents/minimax.js`
+- `docs/plans/minimax-music-generation.md` (historical plan)
+
+For questions or contributions, see the main project README or open an issue.
+
+---
+
+*This documentation ensures the new music capabilities are discoverable and easy to adopt.*

package/docs/plans/minimax-music-generation.md

@@ -0,0 +1,80 @@
+# Minimax Music Toolset & HTTP Wrapper Plan (Focused Version v1.4 – 2-Stage Approach)
+
+**Date:** May 20, 2026  
+**Version:** 1.4 (2-Stage Implementation Approach)  
+**Status:** Planning Phase – Stage 1 Ready for Implementation  
+**Focus:** Strictly the HTTP wrapper (`lib/API/minimax/music.js`) and the special Music Toolset (`lib/API/minimax/MusicToolset.js`).  
+**No Music Agent creation** – This plan provides everything needed to later create a music agent (using patterns from `./agents/*`).
+
+---
+
+## 1. 2-Stage Implementation Approach (Approved)
+
+**Stage 1 – HTTP Wrapper (Current Focus)**  
+- Create `lib/API/minimax/music.js` first.  
+- This will be a complete, reusable, low-level HTTP client for all Minimax music endpoints.  
+- Includes support for:  
+  - Basic music generation  
+  - Two-Step Cover (Advanced Mode with Lyrics Modification)  
+  - Local-only storage for generated results  
+  - Organized CDN publishing for references only (when explicitly requested)  
+- User will create a Minimax account and obtain an API key (`MINIMAX_API_KEY`) before testing.  
+- Once the wrapper is ready and tested (with real key), we move to Stage 2.
+
+**Stage 2 – Music Toolset (After Stage 1)**  
+- Create `lib/API/minimax/MusicToolset.js` using the wrapper from Stage 1.  
+- Expose high-level tools (including the high-priority `generate_cover_with_lyrics_modification`).  
+- Follows exact patterns from `lib/genericToolset.js`.
+
+This staged approach ensures we have a solid, tested foundation before building the tool layer.
+
+---
+
+## 2. Current Rules for Audio Handling (v1.3 + v1.4)
+
+- Generated audio → **Local storage only** (never auto-published to CDN).  
+- Reference audio for Two-Step Cover → Published to organized CDN **only when project_slug is provided**.  
+- Organized structure: `projects/<slug>/` with `meta.json`, `description.md`, `plan.md`.
+
+---
+
+## 3. Stage 1 Deliverable: `lib/API/minimax/music.js`
+
+**Purpose:** Pure HTTP wrapper (no ToolSet logic).
+
+**Required Exports (to be implemented):**
+- `getHeaders()`
+- `requestMusic(prompt, options)`
+- `preprocessCover(audioUrl, options)`
+- `generateCoverWithLyricsModification(coverFeatureId, newLyrics, prompt, options)`
+- `twoStepCoverWithLocalResult(referenceAudio, newLyrics, prompt, options)`
+- `downloadToLocal(audioUrl, targetLocalPath)`
+- `publishReferenceToOrganizedCDN(localPath, projectSlug, description, planContent)`
+- `slugify(text)`
+- Helper constants for endpoints and default audio settings.
+
+**Implementation Style:**  
+Exact mirror of `lib/API/x.ai/responses.js`:
+- Uses `import { request as doRequest } from '@j-o-r/apiserver';`
+- Uses `import { SH, sleep } from '@j-o-r/sh';`
+- Env check for `MINIMAX_API_KEY`
+- Duration tracking + clean error handling
+- All generated results downloaded locally via `downloadToLocal`
+
+**Two-Step Cover Support:** Fully included as requested.
+
+---
+
+## 4. Next Steps
+
+1. **Now (Stage 1):** Implement `lib/API/minimax/music.js`
+2. User creates Minimax account + API key
+3. Test the wrapper (with real key)
+4. **Later (Stage 2):** Implement the Music Toolset
+
+---
+
+**Plan v1.4 is now the single source of truth for the 2-stage approach.**
+
+Ready to begin **Stage 1** (create `lib/API/minimax/music.js`)?  
+Reply with **"Approved – start Stage 1: implement music.js"** and I will proceed immediately.

package/docs/plans/unified-agent-architecture.md

@@ -0,0 +1,146 @@
+# Unified Agent Architecture – Human-Readable Event-Driven Design
+
+**Date:** May 09, 2026  
+**Version:** 2.5 (Complete & Self-Contained – Includes Key Implementation Patterns)  
+**Status:** Final – This document is the single source of truth
+
+---
+
+## 1. Core Philosophy
+
+- Everything that happens is an **event**.
+- There is **no "final response"** concept.
+- The **only** way to know that an agent (or user acting as agent) has finished its turn is when it emits a **`kind: "ready"`** event.
+- **Users and agents are completely symmetric.**
+- A `function_call` sent by an Agent to a connected peer is treated exactly as a **`query`** by the receiver.
+- A `function_response` is the answer that comes back when the receiver has processed that query and emitted its own **`ready`** event.
+
+---
+
+## 2. What `lib/Agent.js` Must Do (Core Responsibilities)
+
+`lib/Agent.js` is the **single source of truth** for all agent behavior. It must be a pure core class with **zero** terminal I/O, readline, or CLI code.
+
+It must implement **all** of the following functionality in one class:
+
+### 2.1 Hybrid Server + Client Mode
+- When instantiated with `serve: port`, it acts as a WebSocket server.
+- When instantiated with `connect: url`, it acts as a WebSocket client.
+- It can do both at the same time (hybrid).
+
+### 2.2 Dynamic Tool Registration (from AgentServer + AgentClient)
+- Any peer (remote agent **or** user) that connects and sends a `kind: "introduction"` message is automatically registered as a tool in `prompt.toolset`.
+- The tool name = the peer’s `name`.
+- The tool description = the peer’s `description`.
+- The tool implementation sends a `function_call` (or `query`) to the peer and waits for a `function_response`.
+
+### 2.3 User as First-Class Expert (Two Modes)
+- **Direct mode**: Normal user input is passed directly to `prompt.call(content)`.
+- **Expert mode** (optional): If the user provides `name` + `description`, the Agent sends an `introduction` on connect and registers the user as a callable tool. The model can then issue `function_call` to the human user.
+
+### 2.4 Unified Event Protocol (Mandatory)
+All messages use this exact shape:
+
+```json
+{
+  "type": "event",
+  "kind": "query" | "reasoning" | "log" | "function_call" | "function_response" |
+          "ready" | "info" | "session_list" | "load_session" | "reset" |
+          "proceed" | "tool_start" | "tool_end" | "error" | "introduction",
+  "from": "user:cli" | "agent:main" | "agent:memory" | "human",
+  "id": "correlation-id",
+  "content": any,
+  "metadata": object | null
+}
+```
+
+Key rules:
+- `function_call` received → treated internally as a `query`.
+- `ready` is the **only** completion signal.
+- When the Prompt emits `ready`, the Agent emits a `kind: "ready"` event.
+
+### 2.5 Internal Behaviors (Must Be Implemented)
+- **Queue + Processing Flag**: Incoming queries are processed one at a time.
+- **Epoch-based Reset**: On `reset`, increment an epoch so in-flight work can be safely discarded.
+- **Auto-reconnect** (client side): If the WebSocket drops, automatically retry.
+- **Pending Response Map**: Track pending `function_call` / `query` responses with timeouts.
+- **Prompt Integration**: Wrap a `Prompt` instance and translate its events (`message`, `ready`, `tool_request`, `tool_response`, `error`) into the unified protocol.
+
+### 2.6 Key Implementation Patterns from Existing Code (Mandatory)
+
+The new `lib/Agent.js` **must preserve** the following proven patterns from `lib/AgentServer.js` and `lib/AgentClient.js`:
+
+- **Tool registration pattern** (`addClient` in AgentServer):
+  - On `introduction`, create a tool in `prompt.toolset` whose implementation sends a message to the peer and returns a Promise that resolves on `function_response` / `agent_response`.
+
+- **Pending response handling** (`pendingResponses` Map):
+  - Use a Map keyed by `conn_id:id` (or just `id` in the unified protocol) to store `{resolve, reject, timer}`.
+  - On receiving `function_response` / `agent_response`, resolve the matching promise and clear the timer.
+
+- **Queue + epoch pattern** (from AgentClient):
+  - Maintain an internal message queue and a `processing` flag.
+  - On `reset`, increment `epoch` and discard the queue.
+  - Only process one message at a time.
+
+- **Auto-reconnect** (from AgentClient):
+  - On client-side `onclose`, schedule a reconnect after 5 seconds.
+
+- **Message sending with correlation**:
+  - Every outgoing `query` / `function_call` gets a unique `id`.
+  - Responses are matched by this `id`.
+
+These patterns must be re-implemented inside the single `Agent` class using the new unified event kinds.
+
+### 2.7 Public API (High-Level)
+The class must expose at minimum:
+
+```js
+new Agent(prompt, {
+  name: 'agent:main',
+  serve: 8080,           // server mode
+  connect: 'ws://...',   // client mode
+  debug: true
+});
+
+agent.query(content);
+agent.sendFunctionCall(name, args);
+agent.on('event', fn);
+agent.on('ready', fn);
+agent.on('query', fn);
+```
+
+### 2.8 No I/O in the Core
+- `lib/Agent.js` must have **zero** dependencies on `@j-o-r/cli`, readline, stdin/stdout, or any terminal code.
+- All terminal and web interfaces are provided by separate binding modules.
+
+---
+
+## 3. Architectural Principle: Core vs Bindings
+
+- `lib/Agent.js` = pure core (event logic, registration, protocol, Prompt integration).
+- All user interfaces = separate bindings (`lib/cli/terminal-binding.js`, future web binding, etc.).
+- `wsIO.js` and `wsCli.js` remain **completely untouched**.
+
+---
+
+## 4. Requirements for the Terminal Binding (`lib/cli/terminal-binding.js`)
+
+(See separate detailed requirements in sections above – must use `@j-o-r/cli` + `@j-o-r/sh`, keep 100% command parity with `wsCli.js`, support expert registration, and use the new event protocol.)
+
+---
+
+## 5. Implementation Order (v2.5)
+
+1. Approve this plan.
+2. Implement / rewrite `lib/Agent.js` exactly according to section 2 (including the key patterns in 2.6).
+3. Implement `lib/cli/terminal-binding.js` (using `@j-o-r/cli` + `@j-o-r/sh`).
+4. Update `lib/index.js` and documentation.
+5. Do **not** modify `wsIO.js` or `wsCli.js`.
+
+---
+
+**This document is now complete, precise, and self-contained.**
+
+It contains every piece of information needed to implement `lib/Agent.js` and the terminal binding in a new session with **no prior context**.
+
+**Approved – proceed with implementation** (or requested changes): _______________________________