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

package/types/Cli.d.ts

@@ -1,9 +1,9 @@
 export default Cli;
-export type OARequest = typeof import("./API/openai.com/reponses/text.js").request;
-export type XRequest = typeof import("./API/x.ai/text.js").request;
+export type OARequest = any;
+export type XRequest = any;
 export type ANTHRequest = typeof import("./API/anthropic.com/text.js").request;
-export type XOptions = import("./API/x.ai/text.js").XOptions;
-export type OAOptions = import("./API/openai.com/reponses/text.js").OAOptions;
+export type XOptions = any;
+export type OAOptions = any;
 export type ANTHOptions = import("./API/anthropic.com/text.js").ANTHOptions;
 export type Prompt = import("./Prompt.js").default;
 export type Session = import("./Session.js").default;
@@ -44,6 +44,8 @@ export type CLIOptions = {
  * - Event-driven updates from Prompt (messages, truncated, finished).
  * - Built-in help, reset, load session, copy last message (Alt+m).
  * - Customizable intro/help via options.
+ * - Supports rebinding to a new Prompt/Session (for in-process agent handoff) without creating a new CLI instance.
+ *   Use rebind() then start(initialContext) for clean handoff.
  *
  * @example
  * const cli = new Cli({ prompt: myPrompt, session: mySession });
@@ -61,6 +63,23 @@ declare class Cli {
      * @throws {Error} If required prompt or session is missing.
      */
     constructor(options: CLIOptions);
+    /**
+     * Rebind this CLI instance to a new Prompt and Session (used for in-process agent handoff).
+     *
+     * - Unbinds listeners from the old prompt.
+     * - Updates internal prompt/session references.
+     * - Updates the assistant role prefix to the new agent's name.
+     * - Re-attaches prompt event listeners to the *new* prompt.
+     * - Optionally updates the description shown on next start().
+     *
+     * Does **not** re-register global key mappings or inputHandler (prevents duplication and double-typing).
+     * Does **not** call start(). Caller should call start() (optionally with initial context) afterwards.
+     *
+     * @param {Prompt} newPrompt
+     * @param {Session} newSession
+     * @param {string} [newDescription] - Optional new description/intro (banner + agent info). If omitted, keeps previous.
+     */
+    rebind(newPrompt: Prompt, newSession: Session, newDescription?: string): void;
     /**
      * Prints detailed info about current session and prompt, plus description.
      * Triggered by Alt+i.
@@ -68,11 +87,12 @@ declare class Cli {
     printInfo(): void;
     /**
      * Starts the CLI: Shows intro/description, focuses user input, optionally processes initial message.
-     * @param {string} [s] - Optional initial user message to process.
+     *
+     * When called with a string `s` (e.g. handoff context), the context is shown as a user message
+     * and then processed. This makes the injected handoff context visible in the terminal.
+     *
+     * @param {string} [s] - Optional initial user message / handoff context to process.
      * @returns {Promise<void>}
-     * @example
-     * await cli.start(); // Interactive mode
-     * await cli.start('What is the weather?'); // Start with query
      */
     start(s?: string): Promise<void>;
     /**

package/types/Prompt.d.ts

@@ -1,11 +1,11 @@
 export default Prompt;
-export type OARequest = typeof import("./API/openai.com/reponses/text.js").request;
-export type XRequest = typeof import("./API/x.ai/text.js").request;
+export type OARequest = any;
+export type XRequest = any;
 export type XAIRequest = typeof import("./API/x.ai/responses.js").request;
 export type ANTHRequest = typeof import("./API/anthropic.com/text.js").request;
-export type XOptions = import("./API/x.ai/text.js").XOptions;
+export type XOptions = any;
 export type XAIOptions = import("./API/x.ai/responses.js").XAIOptions;
-export type OAOptions = import("./API/openai.com/reponses/text.js").OAOptions;
+export type OAOptions = any;
 export type ANTHOptions = import("./API/anthropic.com/text.js").ANTHOptions;
 export type ToolSet = import("./ToolSet.js").default;
 /**
@@ -176,7 +176,7 @@ export type Message = {
 * @fires Prompt#http_request - HTTP tool request starts
 * @fires Prompt#http_response - HTTP tool response received
 */
-declare class Prompt {
+declare class Prompt extends EventEmitter<any> {
     /**
     * Constructs a new Prompt instance.
     * If contextWindow = 0 (defaut) the prompt will have no context building up (ONE_SHOT)
@@ -261,6 +261,23 @@ declare class Prompt {
     * @param returns {number}
     */
     countTokens(str?: string): number;
+    /**
+     * Prune resolved function-call I/O from the prompt history, keeping only the
+     * most recent complete function request/response pair.
+     *
+     * A resolved function call is an assistant `function_request` that has a
+     * matching tool `function_response` by `call_id` (or `id` fallback). Older
+     * resolved pairs are removed from their messages; empty assistant/tool
+     * messages are removed entirely. Unresolved function calls and normal
+     * user/assistant text messages are preserved.
+     *
+     * This is useful before serializing history for providers such as the OpenAI
+     * Responses API, where repeatedly sending all historical tool transcripts can
+     * pollute context and waste tokens.
+     *
+     * @returns {boolean} True when the prompt history was changed.
+     */
+    pruneResolvedFunctionCallsExceptLast(): boolean;
     /**
     * reduce the prompt length to fit in the contextWindow
     * or simply reset when there is no contextWindow
@@ -330,3 +347,4 @@ declare class Prompt {
     info(): string;
     #private;
 }
+import { EventEmitter } from 'node:events';

package/types/Session.d.ts

@@ -11,7 +11,7 @@ declare class Session {
     *
     * @param {string} name - The name of the prompt.
     * @param {Prompt} prompt - The Prompt instance.
-    * @param {string} [storage] - The base storage folder; defaults to process.cwd()/.cache/hello-dave.
+    * @param {string} [storage] - The base storage folder; defaults to process.cwd()/.cache/@j-o-r/hello-dave.
     */
     constructor(name: string, prompt: Prompt, storage?: string);
     /** @type {string} Sanitized prompt name (public readonly). */

package/types/ToolSet.d.ts

@@ -96,6 +96,16 @@ declare class ToolSet {
      * @returns {ToolSet} Returns this instance to allow chaining
      */
     borrow(sourceToolSet: ToolSet): ToolSet;
+    /**
+     * Copies ONE tool from another ToolSet into this one.
+     * Optionally renames it to avoid name conflicts.
+     *
+     * @param {ToolSet} sourceToolSet - The source ToolSet
+     * @param {string} sourceName - Name of the tool in the source ToolSet
+     * @param {string} [newName] - Optional new name for the tool in this ToolSet
+     * @returns {ToolSet} Returns this instance for chaining
+     */
+    addFrom(sourceToolSet: ToolSet, sourceName: string, newName?: string): ToolSet;
     /**
      * Getter for the current tool choice setting.
      * @returns {string} The tool choice: 'auto', 'none', or 'required'

package/types/agentLoader.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Find the nearest package root by walking upward until package.json is found.
+ *
+ * @param {string|URL} from - Starting file path, directory path, or file URL.
+ * @returns {Promise<string|null>} Package root path, or null.
+ */
+export function findNearestPackageRoot(from: string | URL): Promise<string | null>;
+/**
+ * Build ordered agent directory candidates.
+ *
+ * When `options.from` is supplied, discovery is intentionally strict: the only
+ * directory searched is the `agents` directory under the nearest package root
+ * found from that caller module URL/path.
+ *
+ * @param {AgentLoaderOptions} [options={}] - Loader options.
+ * @returns {Promise<string[]>} Absolute agent directory candidates.
+ */
+export function getAgentDirs(options?: AgentLoaderOptions): Promise<string[]>;
+/**
+ * Discover all available agents by performing a lightweight filesystem scan.
+ *
+ * @param {AgentLoaderOptions} [options={}] - Loader options.
+ * @returns {Promise<Array<{name: string, path: string, desc: string}>>}
+ *   Array of discovered agents.
+ */
+export function listAgents(options?: AgentLoaderOptions): Promise<Array<{
+    name: string;
+    path: string;
+    desc: string;
+}>>;
+/**
+ * Resolve the absolute path to an agent module by name.
+ *
+ * @param {string} agentName - The agent identifier or safe direct path.
+ * @param {AgentLoaderOptions} [options={}] - Loader options.
+ * @returns {Promise<string>} Absolute path to the matching .js file.
+ */
+export function resolveAgentPath(agentName: string, options?: AgentLoaderOptions): Promise<string>;
+/**
+ * Load (import + validate) a clean Agent instance by name.
+ *
+ * @param {string} agentName - Agent identifier to load.
+ * @param {Array<any>} [extraArgs=[]] - Optional factory arguments.
+ * @param {AgentLoaderOptions} [options={}] - Loader options.
+ * @returns {Promise<import('./Agent.js').default>} Loaded Agent instance.
+ */
+export function loadAgent(agentName: string, extraArgs?: Array<any>, options?: AgentLoaderOptions): Promise<import("./Agent.js").default>;
+/**
+ * Create an isolated agent loader bound to a caller/project context.
+ *
+ * @param {AgentLoaderOptions} [options={}] - Loader options.
+ * @returns {{
+ *   getAgentDirs: () => Promise<string[]>,
+ *   listAgents: () => Promise<Array<{name: string, path: string, desc: string}>>,
+ *   resolveAgentPath: (agentName: string) => Promise<string>,
+ *   loadAgent: (agentName: string, extraArgs?: Array<any>) => Promise<import('./Agent.js').default>
+ * }} Configured loader API.
+ */
+export function createAgentLoader(options?: AgentLoaderOptions): {
+    getAgentDirs: () => Promise<string[]>;
+    listAgents: () => Promise<Array<{
+        name: string;
+        path: string;
+        desc: string;
+    }>>;
+    resolveAgentPath: (agentName: string) => Promise<string>;
+    loadAgent: (agentName: string, extraArgs?: Array<any>) => Promise<import("./Agent.js").default>;
+};
+export type AgentLoaderOptions = {
+    /**
+     * - Caller module URL/path, usually caller import.meta.url.
+     */
+    from?: string | URL | undefined;
+    /**
+     * - Explicit agent directories. Used only when `from` is not supplied.
+     */
+    agentDirs?: (string | URL)[] | undefined;
+};

package/types/cdn.d.ts

@@ -1,11 +1,7 @@
 declare namespace _default {
     export { getSshConfig };
-    export { ensureRemoteDir };
-    export { ensureProjectStructure };
-    export { listProjects };
-    export { deleteProject };
     export { publishFile };
-    export { publishToProject };
+    export { unpublishFile };
 }
 export default _default;
 /**
@@ -20,7 +16,7 @@ export default _default;
  *
  * @example
  * // Required environment variable:
- * // export SSH_EP='ssh://jorrit@drive.duin.xyz:4301'
+ * // export SSH_EP='ssh://user@your-cdn.example.com:4301'
  */
 export function getSshConfig(): {
     user: string;
@@ -29,61 +25,8 @@ export function getSshConfig(): {
     raw: string;
 };
 /**
- * Ensure a remote directory exists under `htdocs/`.
- * Creates all parent directories as needed (`mkdir -p`).
- *
- * @param {string} remoteRelativeDir - Relative path under htdocs (e.g. "tmp/cdn-demo-123" or "projects/my-project")
- * @returns {Promise<string>} The full remote directory path (e.g. "htdocs/tmp/cdn-demo-123")
- */
-export function ensureRemoteDir(remoteRelativeDir: string): Promise<string>;
-/**
- * Ensure the remote project directory structure exists.
- * Creates `htdocs/projects/<slug>` (and the `generated` subfolder).
- *
- * @param {string} projectSlug - Project identifier (will be sanitized)
- * @returns {Promise<string>} The remote directory path under htdocs
- */
-export function ensureProjectStructure(projectSlug: string): Promise<string>;
-/**
- * List all existing projects on the remote server.
- *
- * Scans the `htdocs/projects/` directory and returns metadata for each project.
- * Useful when starting without prior context about what has already been published.
- *
- * @returns {Promise<Array<{slug: string, url: string, fileCount: number, created?: string}>>}
- *          Array of project objects.
- *
- * @throws {Error} If the SSH connection or directory listing fails.
- *
- * @example
- * const projects = await cdn.listProjects();
- * console.log(projects[0].url); // https://drive.duin.xyz/projects/my-project/
- */
-export function listProjects(): Promise<Array<{
-    slug: string;
-    url: string;
-    fileCount: number;
-    created?: string;
-}>>;
-/**
- * Delete an entire project folder from the remote server.
- *
- * Permanently removes `htdocs/projects/<slug>` and all its contents.
- * Use with caution — this operation cannot be undone.
- *
- * @param {string} projectSlug - Project identifier (will be sanitized to kebab-case)
- * @returns {Promise<{deleted: boolean, project: string}>}
- *
- * @example
- * await cdn.deleteProject('my-old-project');
- */
-export function deleteProject(projectSlug: string): Promise<{
-    deleted: boolean;
-    project: string;
-}>;
-/**
- * Publish a single local file to an arbitrary location on the public CDN.
- *
+ * Publish a single local file to an arbitrary temp location on the public CDN.
+ * this folder is cleared regulary.
  * Automatically creates any missing parent directories.
  * Returns a direct public HTTPS URL.
  *
@@ -104,38 +47,20 @@ export function publishFile(localPath: string, remoteRelativePath: string): Prom
     remote_path: string;
 }>;
 /**
- * Publish one or more local files into an organized project folder on the public CDN.
- *
- * Supports both single file (string) and multiple files (array).
- * Automatically creates the project directory and generates `meta.json`.
- * Optional `description.md` and `plan.md` files can be created.
+ * Delete a previously published file from the public CDN temp folder.
  *
- * @param {string|string[]} localPaths - Single path or array of local file paths
- * @param {string} projectSlug - Project identifier (sanitized to kebab-case)
- * @param {Object} [options]
- * @param {string} [options.description] - Human-readable project description
- * @param {string} [options.plan] - Planning notes or step-by-step evolution
- * @param {string} [options.filename] - Custom filename (only used when uploading a single file)
+ * The target path is resolved relative to `htdocs/aaztmp/`. Missing files are
+ * treated as already unpublished because `rm -f` is used.
  *
- * @returns {Promise<{public_urls: string[], project_folder: string, meta: object}>}
+ * @param {string} remoteRelativePath - File path under htdocs/aaztmp (e.g. "tmp/quick-reference.mp3")
+ * @returns {Promise<{public_url: string, remote_path: string, unpublished: boolean}>}
  *
  * @example
- * // Multiple files
- * const result = await cdn.publishToProject(
- *   ['audio.mp3', 'cover.jpg'],
- *   'my-project',
- *   { description: 'Music cover project' }
- * );
- *
- * // Single file with custom name
- * await cdn.publishToProject('/tmp/file.mp3', 'my-project', { filename: 'final.mp3' });
+ * const result = await cdn.unpublishFile('tmp/quick-reference.mp3');
+ * console.log(result.unpublished);
  */
-export function publishToProject(localPaths: string | string[], projectSlug: string, options?: {
-    description?: string | undefined;
-    plan?: string | undefined;
-    filename?: string | undefined;
-}): Promise<{
-    public_urls: string[];
-    project_folder: string;
-    meta: object;
+export function unpublishFile(remoteRelativePath: string): Promise<{
+    public_url: string;
+    remote_path: string;
+    unpublished: boolean;
 }>;

package/types/defaultToolsets.d.ts

@@ -0,0 +1,9 @@
+export { createHandOffToolset };
+export default defaultToolsets;
+import { createHandOffToolset } from './handOffToolset.js';
+/**
+ * Default framework-owned toolset tree exposed as API.toolset.
+ *
+ * @type {Record<string, Record<string, any>>}
+ */
+declare const defaultToolsets: Record<string, Record<string, any>>;

package/types/fafs.d.ts

@@ -68,7 +68,7 @@ import { jsType } from '@j-o-r/sh';
 export const GLOBAL: Object;
 /**
  * Gathers comprehensive environment information: user name, fresh system details, IP-based geolocation,
- * and normalized current working directory. Results are cached in ~/.cache/hello-dave/env for 31 days,
+ * and normalized current working directory. Results are cached in ~/.cache/@j-o-r/hello-dave/env for 31 days,
  * refreshed on expiry. On cache hit, updates with fresh system info and cwd.
  *
  * @returns {Promise<EnvironmentInfo>} The environment information object.

package/types/genericToolset.d.ts

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

package/types/handOffToolset.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Configure the singleton handoff toolset used by API.toolset.generic.handoff.
+ *
+ * This keeps existing agent code working while allowing AgentLauncher instances
+ * created with `{ from: import.meta.url }` to make `list_agents` use the same
+ * project-aware loader as handoff loading.
+ *
+ * @param {HandOffToolsetOptions} options - Handoff toolset options.
+ * @returns {void}
+ */
+export function configureDefaultHandOffToolset(options?: HandOffToolsetOptions): void;
+/**
+ * Create a handoff toolset using the provided agent discovery function.
+ *
+ * @param {HandOffToolsetOptions} [options={}] - Toolset options.
+ * @returns {ToolSet} Configured ToolSet instance.
+ */
+export function createHandOffToolset(options?: HandOffToolsetOptions): ToolSet;
+export default handoffTools;
+export type HandOffToolsetOptions = {
+    listAgents?: (() => Promise<Array<{
+        name: string;
+        path: string;
+        desc: string;
+    }>>) | undefined;
+};
+import ToolSet from './ToolSet.js';
+declare const handoffTools: ToolSet;

package/types/index.d.ts

@@ -1,33 +1,35 @@
-export { default as CdnToolset } from "./CdnToolset.js";
-import AgentManager from './AgentManager.js';
-import AgentServer from './AgentServer.js';
-import AgentClient from './AgentClient.js';
+import Agent from './Agent.js';
+import AgentLauncher from './AgentLauncher.js';
 import Prompt from './Prompt.js';
 import ToolSet from './ToolSet.js';
 import Session from './Session.js';
 export namespace API {
-    export namespace text {
+    export namespace chat {
         export { gpt };
-        export { xai };
+        export { grok };
         export { claude };
     }
     export namespace search {
         export { brave };
     }
-    export { minimax };
-    export { stability };
-    export { xaitools };
+    export { defaultToolsets as toolset };
 }
 import Cli from './Cli.js';
 import { env } from './fafs.js';
 import { GLOBAL } from './fafs.js';
-import wsCli from '../lib/wsCli.js';
-import wsIO from '../lib/wsIO.js';
-import { request as gpt } from './API/openai.com/reponses/text.js';
-import { request as xai } from './API/x.ai/responses.js';
+import { createAgentLoader } from './agentLoader.js';
+import { createHandOffToolset } from './defaultToolsets.js';
+import { findNearestPackageRoot } from './agentLoader.js';
+import { getAgentDirs } from './agentLoader.js';
+import { listToolsets } from './toolsetLoader.js';
+import { matchesToolsetFilter } from './toolsetLoader.js';
+import { parseToolsetArgs } from './toolsetLoader.js';
+import { renderToolsetList } from './toolsetLoader.js';
+import { renderToolsetsHelp } from './toolsetLoader.js';
+import { shortDescription } from './toolsetLoader.js';
+import { request as gpt } from './API/openai.com/responses.js';
+import { request as grok } from './API/x.ai/responses.js';
 import { request as claude } from './API/anthropic.com/text.js';
 import { request as brave } from './API/brave.com/search.js';
-import minimax from './API/minimax/index.js';
-import stability from './API/stability.ai/index.js';
-import xaitools from './API/x.ai/index.js';
-export { AgentManager, AgentServer, AgentClient, Prompt, ToolSet, Session, Cli, env, GLOBAL, wsCli, wsIO };
+import defaultToolsets from './defaultToolsets.js';
+export { Agent, AgentLauncher, Prompt, ToolSet, Session, Cli, env, GLOBAL, createAgentLoader, createHandOffToolset, findNearestPackageRoot, getAgentDirs, listToolsets, matchesToolsetFilter, parseToolsetArgs, renderToolsetList, renderToolsetsHelp, shortDescription };

package/types/toolsetLoader.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Shorten a description for compact CLI display.
+ *
+ * @param {unknown} desc - Description value.
+ * @param {number} [maxLen=140] - Maximum length.
+ * @returns {string} Shortened description.
+ */
+export function shortDescription(desc: unknown, maxLen?: number): string;
+/**
+ * Parse toolset CLI arguments.
+ *
+ * @param {string[]} [argv=process.argv.slice(2)] - Arguments without node/script prefix.
+ * @returns {ParsedToolsetArgs} Parsed toolset arguments.
+ */
+export function parseToolsetArgs(argv?: string[]): ParsedToolsetArgs;
+/**
+ * Check if a display name matches any provided filters.
+ *
+ * @param {string} displayName - Toolset display name, for example "minimax/music".
+ * @param {string[]} [filters=[]] - Filters to apply.
+ * @returns {boolean} Whether the display name matches.
+ */
+export function matchesToolsetFilter(displayName: string, filters?: string[]): boolean;
+/**
+ * List framework/default toolsets directly in the current process.
+ *
+ * @param {ToolsetListOptions} [options={}] - Listing options.
+ * @returns {ToolsetListResult} Structured toolset listing.
+ */
+export function listToolsets(options?: ToolsetListOptions): ToolsetListResult;
+/**
+ * Render toolset help text.
+ *
+ * @param {string} [command='dave --toolsets'] - Command shown in examples.
+ * @returns {string} Help text.
+ */
+export function renderToolsetsHelp(command?: string): string;
+/**
+ * Render a human-readable toolset listing.
+ *
+ * @param {ToolsetListResult} result - Structured toolset listing.
+ * @returns {string} Human-readable output.
+ */
+export function renderToolsetList(result: ToolsetListResult): string;
+export type ListedTool = {
+    /**
+     * - Tool name.
+     */
+    name: string;
+    /**
+     * - Shortened tool description.
+     */
+    description: string;
+};
+export type ListedToolset = {
+    /**
+     * - Display name, for example "minimax/music".
+     */
+    name: string;
+    /**
+     * - Number of tools in this toolset.
+     */
+    toolCount: number;
+    /**
+     * - Listed tool metadata.
+     */
+    tools: ListedTool[];
+    /**
+     * - Optional note when the value is not a ToolSet instance.
+     */
+    note?: string | undefined;
+};
+export type ToolsetListResult = {
+    /**
+     * - Public import reference.
+     */
+    reference: string;
+    /**
+     * - Matching toolsets.
+     */
+    toolsets: ListedToolset[];
+    /**
+     * - Number of matching toolsets.
+     */
+    totalToolsets: number;
+    /**
+     * - Number of matching tools.
+     */
+    totalTools: number;
+};
+export type ToolsetListOptions = {
+    /**
+     * - Optional provider/type/name filters.
+     */
+    filters?: string[] | undefined;
+    /**
+     * - Optional toolset tree. Defaults to framework toolsets.
+     */
+    toolsets?: Record<string, Record<string, any>> | undefined;
+};
+export type ParsedToolsetArgs = {
+    /**
+     * - Positional filters.
+     */
+    filters: string[];
+    /**
+     * - Whether JSON output was requested.
+     */
+    json: boolean;
+    /**
+     * - Whether help output was requested.
+     */
+    help: boolean;
+};