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

package/docs/bin-dave.md

@@ -2,61 +2,111 @@
 
 ## Introduction
 
-The Dave CLI tool is the entry point for interacting with the Hello Dave project. It is located at `bin/dave.js` and can be run globally or via npx.
+The `dave` CLI (`bin/dave.js`) is the main entry point.
 
-## Installation
+**Current model**: Bare (non-flag) first argument is treated as an agent name and delegated to `AgentLauncher`. All further arguments are forwarded.
 
-### Global Installation
+The old swarm / CodeServer / `--serve` / `--connect` / hybrid model has been abandoned.
 
-To install globally and use the `dave` command:
+## Running Agents
+
+In the direct `hello-dave` project folder, agents are available with the `dave` command from `bin/dave.js`:
 
 ```bash
-npm install -g @j-o-r/hello-dave
+dave <agent_name>                    # interactive CLI
+dave <agent_name> "one-shot message"
+echo "piped input" | dave <agent_name>
+dave <agent_name> --info
+dave <agent_name> --help
+
+# Example
+dave agent_creator --info
 ```
 
-### Local Usage with npx
+Only `*_agent.js` files are discovered.
+
+For other projects, check `package.json` for a `bin` command and prefer that project-local launcher. If no suitable bin command exists, create a temporary ESM script that imports `AgentLauncher` from `@j-o-r/hello-dave`, loads the agent, and forwards arguments.
+
+## Built-in Commands
+
+- `--help`
+- `--list-agents`
+- `--clear`
+- `--search "query"`
+- `--list`
+- `--inspect "log.ndjson"`
+- `--toolsets [filter...] [--json]`
+  - List toolsets exposed via `API.toolset`.
+  - Filters match provider (e.g. `minimax`), type (e.g. `image`, `music`), or full path (`minimax/music`).
+  - `--toolsets --help` shows detailed help for the toolsets command.
+  - Examples:
+    - `dave --toolsets`
+    - `dave --toolsets image`
+    - `dave --toolsets minimax music`
+    - `dave --toolsets --json`
+
+These do not launch an agent.
+
+## Session Management for One-Shot Calls (No Background Services)
+
+**Core principle**: Every `dave <agent> ...` invocation is an independent, short-lived process. There are **no background daemons, listeners, or persistent services**.
 
-Run without installation:
+The interactive CLI (when you just run `dave <agent>` with no message) gives you rich in-memory session continuation with keyboard shortcuts (Alt+r reset, Alt+s load session, Alt+i info, etc.).
+
+For one-shot and scripting use, the same session power is exposed via explicit flags. These operate on the existing per-agent NDJSON session storage under `.cache/@j-o-r/hello-dave/<agent>/sessions/`.
+
+### Session Flags (one-shot / scripting)
 
 ```bash
-npx @j-o-r/hello-dave [flags]
-```
+# Start a new conversation or continue the "current" session
+# (the one from the most recent successful message call for this agent)
+dave ask_agent "What's the weather in Paris?"
+
+# List all previously saved sessions for this agent
+dave ask_agent --list-sessions
 
-## Available Flags
+# Select a previous session. The *next* plain message call will continue from it.
+dave ask_agent --load-session "what_s_the_weather_in_paris_0"
+# or by recent index (most recent first)
+dave ask_agent --load-session 2
 
-The CLI supports various flags for configuration and launching services. Common flags include:
+# Force the next plain message call to start a completely fresh session
+dave ask_agent --reset-session
+
+# Show info about the currently selected / last active session
+dave ask_agent --session-info
+
+# Dedicated help for the session flags
+dave ask_agent --session-help
+```
 
-- `--help`: Display help information.
-- `--version`: Show the current version of the Dave CLI.
-- `--code [port] [--secret secret]`: Launch a portable CodeServer instance. Optionally specify a port (defaults to 8080 if omitted). Use `--secret` to set an access password for the server.
+**How it works (high level)**:
+- A tiny per-agent "current session pointer" file tracks which session the next plain call should continue.
+- `--load-session` updates the pointer.
+- `--reset-session` clears/marks the pointer so the next call starts fresh.
+- A plain message call pre-loads the pointed-to session (if any) into the Prompt before processing the new input, then updates the pointer afterward.
+- All real history lives in the same NDJSON files used by the interactive CLI.
 
-For detailed information on the CodeServer pattern and integration, refer to [codeserver-pattern.md](codeserver-pattern.md).
+This design gives you scriptable, "call from anywhere" session continuation with zero operational overhead.
 
-Other flags may be available depending on the version; run `dave --help` for the full list.
+See the full plan and honest assessment: `docs/plans/no-service-session-continuation.md`.
 
-## Examples
+## Handoffs
 
-### Basic Usage
+Handled inside agents via the `hand_over` / `load_agent` tools (registered from `API.toolset.generic.handoff`).
 
-- Show help (global):
-  ```bash
-  dave --help
-  ```
+See `docs/creating-agents.md` and `lib/handOffToolset.js`.
 
-- Show version (npx):
-  ```bash
-  npx @j-o-r/hello-dave --version
-  ```
+## Legacy Networking
 
-### Launching CodeServer
+Old flags and patterns (`--connect`, `--serve`, `dave code_swarm`, etc.) are no longer supported in the CLI.
 
-- Launch on default port (global):
-  ```bash
-  dave --code
-  ```
+Historical documentation is in `docs/_legacy/`.
 
-- Launch on custom port with secret (npx):
-  ```bash
-  npx @j-o-r/hello-dave --code 3000 --secret mysecretpassword
-  ```
+## References
 
+- [docs/creating-agents.md](creating-agents.md) (current standard)
+- [README.md](../README.md)
+- `lib/AgentLauncher.js`
+- `docs/plans/no-service-session-continuation.md` (primary session strategy)
+- `docs/plans/agent-file-socket-communication.md` (earlier exploration — superseded for the no-service requirement)

package/docs/cdn-ssh.md

@@ -0,0 +1,100 @@
+# CDN & SSH Publishing (SSH_EP)
+
+## Overview
+
+@j-o-r/hello-dave includes reusable modules for publishing local files (e.g., generated audio, images, documents) to a public HTTPS CDN via SSH/SCP.
+
+This is useful for music/image/video agents (Minimax, Stability, Mureka, xAI image tools) so that remote LLMs or users can access generated artifacts via direct URLs.
+
+## Requirements
+
+- Set the `SSH_EP` environment variable in the format:
+  ```
+  export SSH_EP='ssh://user@your-cdn-host.example.com:4301'
+  ```
+  or the shorter form:
+  ```
+  export SSH_EP='user@your-cdn-host.example.com:4301'
+  ```
+
+- The remote host must:
+  - Accept SSH connections on the specified port.
+  - Have a web server serving the `htdocs` directory publicly over HTTPS (the module uploads to `htdocs/aaztmp/...` by default for temp/public files).
+
+## Core Module: lib/cdn.js
+
+- `getSshConfig()`: Parses and validates `SSH_EP`.
+- `publishFile(localPath, remoteRelativePath)`: Uploads a single file and returns `{ public_url, remote_path }`.
+  - Automatically creates parent directories under `htdocs/aaztmp/`.
+  - Public URL example: `https://your-cdn-host.example.com/aaztmp/tmp/myfile.mp3`
+
+Full JSDoc and examples are in the source file.
+
+## Dedicated Toolset: lib/CdnToolset.js
+
+Exposes the `publish_file` tool for agents:
+
+```js
+import cdnTools from './CdnToolset.js';
+// or via API
+toolset.borrow(API.toolset.generic.cdn);
+```
+
+Usage in an agent (after `const toolset = agent.getToolset()`):
+```js
+await toolset.call('publish_file', {
+  localPath: '/tmp/generated.mp3',
+  remoteRelativePath: 'tmp/my-audio-123.mp3'
+});
+// Returns: { public_url: 'https://...', remote_path: '...' }
+```
+
+## Generic Tool Integration
+
+`lib/genericToolset.js` includes `execute_remote_script` which also respects `SSH_EP` as a default for remote bash execution.
+
+## Helper Scripts & Scenarios
+
+- `scenarios/_cdn-host.js`: Shared helper to derive CDN host from `SSH_EP` or `CDN_HOST` (priority: CDN_HOST > SSH_EP > fallback).
+- `scenarios/demo-publish-cdn.js`: Full demo of publishing (single + multi-file). Requires `SSH_EP`.
+
+Run the demo:
+```bash
+export SSH_EP='ssh://user@host:port'
+node scenarios/demo-publish-cdn.js
+```
+
+## Usage in Agents
+
+Creative agents (e.g., `minimax_agent.js`, `stability_agent.js`) typically borrow the CDN toolset alongside their domain toolsets:
+
+```js
+const toolset = agent.getToolset();
+if (toolset) {
+  toolset.borrow(API.toolset.generic.cdn);
+  // plus music/image/video toolsets
+}
+```
+
+After generation, call `publish_file` (or the underlying `cdn.publishFile`) to expose results publicly.
+
+## Security & Best Practices
+
+- Only relative paths under the configured remote root.
+- Temp folders (`aaztmp`) are regularly cleared on the host.
+- Use for non-sensitive, generated artifacts only.
+- Validate `SSH_EP` before operations (the module throws clear errors if missing/invalid).
+
+## TypeScript Support
+
+See `types/cdn.d.ts` for declarations of `getSshConfig` and `publishFile`.
+
+## Related Documentation
+
+- `lib/cdn.js` (source + JSDoc)
+- `lib/CdnToolset.js`
+- `lib/genericToolset.js` (remote script tool)
+- `docs/creating-agents.md` (how to borrow toolsets in new agents)
+- `docs/generic-toolset.md` (overview of generic tools)
+
+**Last updated**: June 2026 (documentation task completion for SSH_EP / CDN usage).

package/docs/creating-agents.md

@@ -0,0 +1,301 @@
+# Creating Agents
+
+**Current canonical pattern (June 2026)**: Use the unified `Agent` class + `AgentLauncher`.
+
+This document is the authoritative `@j-o-r/hello-dave` framework guide for creating and improving agent definitions.
+
+## Documentation Source Rules
+
+All `hello-dave` agent documentation exists in the `@j-o-r/hello-dave` docs folder.
+
+Use this document from one of these valid locations only:
+
+1. **Direct `@j-o-r/hello-dave` checkout**
+   - When the current working directory is the checked-out `@j-o-r/hello-dave` project itself, paths are relative to CWD.
+   - Example: `docs/creating-agents.md`
+
+2. **Installed package usage**
+   - In all other projects, read this document from the installed package.
+   - Prefer local install first, then global install.
+   - Example locations:
+     - `node_modules/@j-o-r/hello-dave/docs/creating-agents.md`
+     - `$(npm root -g)/@j-o-r/hello-dave/docs/creating-agents.md`
+
+Do **not** rely on arbitrary project-local `docs/creating-agents.md` files for `hello-dave` framework guidance. Do **not** create or bootstrap this file into other projects as a framework-doc fallback.
+
+## Agent Creator Scope
+
+`agent_creator` is a helper agent dedicated to the `@j-o-r/hello-dave` module.
+
+It creates and improves `hello-dave` agent definitions while following this framework documentation. It may create or modify agent files in a user's project, but framework guidance must come from the `@j-o-r/hello-dave` docs folder only.
+
+## Quick Start — Minimal Agent
+
+```js
+import { API, Agent } from '@j-o-r/hello-dave';
+
+// call_name is derived from the filename and is the single source of truth.
+const call_name = Agent.deriveCallName(import.meta.url);
+
+/** @type {import('@j-o-r/hello-dave/types/API/x.ai/responses').XAIOptions} */
+const options = {
+  model: 'grok-4'
+};
+
+const call_description = `
+Short description of what this agent does.
+`.trim();
+
+const agent = new Agent({
+  prompt: `You are a focused helper agent.`,
+  api: API.chat.grok,
+  options,
+  toolsetMode: 'auto',
+  contextWindow: 300000,
+  call_name,
+  call_description
+});
+
+const toolset = agent.getToolset();
+if (toolset) {
+  toolset.addFrom(API.toolset.generic.bash, 'read_file');
+  toolset.addFrom(API.toolset.generic.bash, 'write_file');
+  toolset.addFrom(API.toolset.generic.bash, 'execute_bash_script');
+  toolset.borrow(API.toolset.generic.handoff);
+}
+
+export default agent;
+```
+
+## Extended Agents
+
+Use an extended agent when the system prompt is long or should be maintained separately. `Agent.loadPrompt(import.meta.url)` loads an external sibling pure Markdown prompt file named `<agent_name>.prompt.md` as UTF-8 text.
+
+```js
+import { API, Agent } from '@j-o-r/hello-dave';
+
+const call_name = Agent.deriveCallName(import.meta.url);
+const prompt = await Agent.loadPrompt(import.meta.url);
+
+/** @type {import('@j-o-r/hello-dave/types/API/x.ai/responses').XAIOptions} */
+const options = {
+  model: 'grok-4'
+};
+
+const agent = new Agent({
+  prompt,
+  api: API.chat.grok,
+  options,
+  toolsetMode: 'auto',
+  contextWindow: 300000,
+  call_name,
+  call_description: 'Creates or improves focused agent definitions.'
+});
+
+export default agent;
+```
+
+For an agent at:
+
+```text
+agents/example_agent.js
+```
+
+The sibling prompt file must be pure Markdown:
+
+```text
+agents/example_agent.prompt.md
+```
+
+## API-specific Options
+
+Agent `options` must match the selected `api`. Do not copy options between providers unless the provider type supports them.
+
+### GPT / OpenAI responses API
+
+```js
+import { API } from '@j-o-r/hello-dave';
+
+/** @type {import('@j-o-r/hello-dave/types/API/openai.com/responses').OAOptions} */
+const options = {
+  model: 'gpt-5.5',
+  reasoning: { effort: 'high', summary: 'auto' }
+};
+
+const api = API.chat.gpt;
+```
+
+### Grok / xAI responses API
+
+```js
+import { API } from '@j-o-r/hello-dave';
+
+/** @type {import('@j-o-r/hello-dave/types/API/x.ai/responses').XAIOptions} */
+const options = {
+  model: 'grok-4'
+};
+
+const api = API.chat.grok;
+```
+
+### Claude / Anthropic text API
+
+```js
+import { API } from '@j-o-r/hello-dave';
+
+/** @type {import('@j-o-r/hello-dave/types/API/anthropic.com/text').ANTHOptions} */
+const options = {
+  model: 'claude-sonnet-4-20250514'
+};
+
+const api = API.chat.claude;
+```
+
+## Accessing Agents
+
+In the direct `hello-dave` project folder, agents are accessible through the `dave` command from `bin/dave.js`:
+
+```bash
+dave agent_creator --info
+```
+
+In other projects, check that project's `package.json` for a `bin` command and use that project-local command when available. If no suitable bin command exists, create a temporary ESM launcher script that uses `lib/AgentLauncher.js` through the package export:
+
+```js
+import { AgentLauncher } from '@j-o-r/hello-dave';
+
+const launcher = new AgentLauncher({ from: import.meta.url });
+await launcher.load(process.argv[2]);
+await launcher.run(process.argv.slice(3));
+```
+
+Then run, for example:
+
+```bash
+node ./tmp/launch-agent.mjs <name> --info
+```
+
+## Toolset Discovery
+
+When creating or improving an agent that needs tools, inspect the available toolsets first using the appropriate launch command for the current project. In the direct `hello-dave` checkout this is:
+
+```bash
+dave --toolsets
+```
+
+This command lists the toolsets and tools available in the current `@j-o-r/hello-dave` installation or checkout. Use it before inventing or changing tool registrations.
+
+Recommended approach:
+
+1. Run the detected launch command with `--toolsets` (for example, `dave --toolsets` in the direct checkout).
+2. Choose only the tools the agent needs.
+3. Register tools using the current `API.toolset...` references.
+4. Keep access minimal and task-focused.
+5. If the command is not available, fall back to this framework guide and current in-repository examples.
+
+Example pattern:
+
+```js
+const toolset = agent.getToolset();
+if (toolset) {
+  toolset.addFrom(API.toolset.generic.bash, 'read_file');
+  toolset.addFrom(API.toolset.generic.bash, 'write_file');
+  toolset.addFrom(API.toolset.generic.bash, 'execute_bash_script');
+  toolset.borrow(API.toolset.generic.handoff);
+}
+```
+
+## Key Requirements
+
+- Use ESM syntax.
+- Import framework symbols with:
+  ```js
+  import { API, Agent } from '@j-o-r/hello-dave';
+  ```
+- Derive the agent name from the filename:
+  ```js
+  const call_name = Agent.deriveCallName(import.meta.url);
+  ```
+- Include `call_name` and `call_description` in the `Agent` constructor.
+- Include useful `cliIntro` for CLI-facing agents when appropriate.
+- Include JSDoc comments for important code and exported behavior.
+- Run the detected launch command with `--toolsets` before constructing or changing toolsets.
+- Register only the tools the agent needs.
+- Prefer `toolset.borrow(API.toolset.generic.handoff);` for collaboration.
+- End with:
+  ```js
+  export default agent;
+  ```
+
+## Do Not
+
+- Do not hardcode `call_name`.
+- Do not add top-level `run()` calls.
+- Do not use external npm packages for agent definitions.
+- Do not use `API.chat.xai`; use `API.chat.grok`.
+- Do not mix provider-specific option types or option shapes.
+- Do not treat another project's `docs/creating-agents.md` as framework documentation.
+
+## Validation
+
+Before running or recommending a changed JavaScript agent file, validate syntax:
+
+```bash
+node --check agents/<name>.js
+```
+
+Then test discovery/help with the detected launch command:
+
+```bash
+<detected-launch-command> <name> --help
+```
+
+## Running
+
+In the direct `hello-dave` checkout:
+
+```bash
+dave <name>
+dave <name> "message"
+echo "..." | dave <name>
+dave <name> --info
+dave <name> --help
+```
+
+For other projects, prefer the project's `package.json` `bin` command when present, or use a temporary `AgentLauncher` script as shown above. Package-based use can also be invoked with:
+
+```bash
+npx @j-o-r/hello-dave <name> "message"
+```
+
+## Handoff
+
+Use `hand_over` / `load_agent` only for clear domain shifts or deliberate fresh starts.
+
+Handoff context must be short, task-focused, and self-contained. Do not use handoff for meta questions, generic restarts, or capability questions.
+
+See `lib/handOffToolset.js` for framework implementation details.
+
+## Recommended Agent Creator Workflow
+
+1. Inspect the environment.
+2. Detect whether CWD is the direct `@j-o-r/hello-dave` checkout.
+3. Select the correct docs source:
+   - direct checkout: `docs/creating-agents.md`
+   - all other cases: `node_modules/@j-o-r/hello-dave/docs/creating-agents.md`
+4. Read the selected docs source.
+5. Run the detected launcher command with `--toolsets` before constructing or changing toolsets.
+6. Create or improve the requested agent definition.
+7. Backup before overwriting existing files.
+8. Run `node --check` on changed `.js` files.
+9. Recommend the detected launch command, such as `dave <name> --help`, as the final test.
+
+## Documentation Responsibility
+
+Maintain this file as the framework-level source of truth for `@j-o-r/hello-dave` agent creation patterns.
+
+Project-specific documentation may describe a separate project's own conventions, but it must not replace this framework guide as the source for `hello-dave` agent API behavior.
+
+---
+
+*Last updated: June 2026 (single framework-doc source model clarified)*