@j-o-r/hello-dave 0.0.2 → 0.0.3

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

@@ -0,0 +1,84 @@
+declare namespace _default {
+    export { list };
+    export { upload };
+    export { get };
+    export { getMeta };
+    export { rm };
+    export { getStorage as storage };
+}
+export default _default;
+export type fileList = {
+    data: File[];
+    pagination_token: string | null;
+};
+export type File = {
+    /**
+     * - File size in bytes.
+     */
+    bytes: number;
+    /**
+     * - Unix timestamp of creation.
+     */
+    created_at: number;
+    /**
+     * - Unix timestamp of expiration, or null.
+     */
+    expires_at: number | null;
+    /**
+     * - Path to the file.
+     */
+    filename: string;
+    /**
+     * - Unique file identifier.
+     */
+    id: string;
+    /**
+     * - Type of object, e.g., 'file'.
+     */
+    object: string;
+    /**
+     * - Purpose of the file.
+     */
+    purpose: string;
+};
+/**
+ * List Files
+ * @param {number} limit
+ * @param {'asc'|'desc'} order
+ * @param {'created_at'|'filename'| 'size'} sort_by
+ * @param {string} page (pagination_token)
+ * @retuns {Promise<fileList>}
+ */
+declare function list(limit?: number, order?: "asc" | "desc", sort_by?: "created_at" | "filename" | "size", page?: string): Promise<any>;
+/**
+ * Upload a file
+ * When content is filled this will be used as file content
+ * @param {string} filePath
+ * @param {string} [content] - optional content for a non existing file
+ * @returns {Promise<File>} file_id
+ */
+declare function upload(filePath: string, content?: string): Promise<File>;
+/**
+ * Get file content
+ * @param {string} fileId
+ * @returns {Promise<*>}
+ */
+declare function get(fileId: string): Promise<any>;
+/**
+ * Get file meta data
+ * @param {string} fileId
+ * @returns {Promise<File>}
+ */
+declare function getMeta(fileId: string): Promise<File>;
+/**
+ * Remove a file
+ * @param {string} fileId
+ * @returns {Promise<void>}
+ */
+declare function rm(fileId: string): Promise<void>;
+/**
+* Get all on-line files
+* @returns {Promise<Map<string, File>>}
+*
+*/
+declare function getStorage(page?: string): Promise<Map<string, File>>;

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

@@ -0,0 +1,379 @@
+export type Prompt = import("../../Prompt.js").default;
+export type ToolSet = import("../../ToolSet.js").default;
+export type Includes = "code_interpreter_call.outputs" | "computer_call_output.output.image_url" | "file_search_call.results" | "message.input_image.image_url" | "message.output_text.logprobs" | "reasoning.encrypted_conten";
+export type XAIOptions = {
+    /**
+     * - Optional include parameter.
+     */
+    include?: string | null | undefined;
+    /**
+     * - Array of input objects.
+     */
+    input?: XAIInput[] | undefined;
+    /**
+     * - Instructions for the model.
+     */
+    instructions?: string | undefined;
+    /**
+     * - Maximum number of output tokens.
+     */
+    max_output_tokens?: number | undefined;
+    /**
+     * - Maximum number of tool calls allowed.
+     */
+    max_tool_calls?: number | undefined;
+    /**
+     * - Optional metadata object.
+     */
+    metadata?: Object | null | undefined;
+    /**
+     * - Model version to use.
+     */
+    model?: "grok-4-1-fast-reasoning" | "grok-4-1-fast-non-reasoning" | "grok-code-fast-1" | "grok-4-fast-reasoning" | "grok-4-fast-non-reasoning" | undefined;
+    /**
+     * - Reusable prompt string.
+     */
+    prompt?: string | null | undefined;
+    /**
+     * - Reasoning configuration.
+     */
+    reasoning?: {
+        /**
+         * - Effort level for reasoning.
+         */
+        effort: "low" | "medium" | "high" | null;
+        /**
+         * - Summary type for reasoning.
+         */
+        summary: "auto" | "concise" | "detailed";
+    } | undefined;
+    search?: "low" | "high" | "medium" | undefined;
+    /**
+     * - Service tier option, default is auto-selected.
+     */
+    service_tier?: "auto" | undefined;
+    /**
+     * - Whether to store the response or not.
+     */
+    store?: boolean | undefined;
+    /**
+     * - Whether to stream the response or not.
+     */
+    stream?: boolean | undefined;
+    /**
+     * - Sampling temperature between 0 and 2.
+     */
+    temperature?: number | undefined;
+    /**
+     * - text format
+     */
+    text?: {
+        /**
+         * - Summary type for reasoning.
+         */
+        format: "text" | "json_schema";
+    } | undefined;
+    /**
+     * - Allow parallel tool calls if true.
+     */
+    parallel_tool_calls?: boolean | undefined;
+    /**
+     * - Tool choice setting, default is auto-selected.
+     */
+    tool_choice?: "auto" | undefined;
+    /**
+     * Array of tool call objects.
+     */
+    tools?: (XSearchTool | XAIFunctionTool | MCPTool | CodeInterpreterTool | FileSearchTool | XAIWebSearchTool)[] | undefined;
+    /**
+     * -  An integer between 0 and 20 specifying the number of most likely tokens to return at each token position, each with an associated log probability.
+     */
+    top_logprobs?: number | null | undefined;
+    /**
+     * Top-p sampling value between 0 and 1.
+     */
+    top_p?: number | null | undefined;
+    /**
+     * - Needed reponse_id to validate tool calls on the next request
+     */
+    previous_response_id?: string | null | undefined;
+};
+export type XAIFunctionTool = {
+    /**
+     * - The type of the tool call, e.g., "function".
+     */
+    type: "function";
+    /**
+     * - The name of the function.
+     */
+    name: string;
+    /**
+     * - A brief description of what the function does.
+     */
+    description: string;
+    /**
+     * - The parameters required by the function.
+     */
+    parameters: {
+        type: string;
+        properties: {
+            [x: string]: ParameterProperty;
+        };
+        required?: string[] | undefined;
+    };
+};
+export type ParameterProperty = {
+    /**
+     * - The data type of the parameter, e.g., "string".
+     */
+    type: string;
+    /**
+     * - A brief description of the parameter.
+     */
+    description: string;
+};
+export type WebSearchFilters = {
+    /**
+     * - Whitelist of domains (max 5); cannot use with excluded_domains.
+     */
+    allowed_domains?: string[] | null | undefined;
+    /**
+     * - Blacklist of domains (max 5); cannot use with allowed_domains.
+     */
+    excluded_domains?: string[] | null | undefined;
+    /**
+     * - Context size; for OpenAI compatibility (reject if set).
+     */
+    search_context_size?: "low" | "high" | "medium" | null | undefined;
+    /**
+     * - User location; for OpenAI compatibility (reject if set).
+     */
+    user_location?: UserLocation | null | undefined;
+};
+export type UserLocation = {
+    /**
+     * - City of the user's location.
+     */
+    city?: string | null | undefined;
+    /**
+     * - ISO 3166-1 alpha-2 country code.
+     */
+    country?: string | null | undefined;
+    /**
+     * - Region of the user's location.
+     */
+    region?: string | null | undefined;
+    /**
+     * - IANA timezone.
+     */
+    timezone?: string | null | undefined;
+    type: "approximate";
+};
+export type XAIWebSearchTool = {
+    /**
+     * - Whitelist of domains (max 5); cannot use with excluded_domains.
+     */
+    allowed_domains?: string[] | null | undefined;
+    /**
+     * - Enable image understanding.
+     */
+    enable_image_understanding?: boolean | null | undefined;
+    /**
+     * - Blacklist of domains (max 5); cannot use with allowed_domains.
+     */
+    excluded_domains?: string[] | null | undefined;
+    /**
+     * - For OpenAI compatibility (reject if set).
+     */
+    external_web_access?: boolean | null | undefined;
+    /**
+     * - Filters; for OpenAI compatibility.
+     */
+    filters?: WebSearchFilters | null | undefined;
+    type: "web_search";
+};
+export type XSearchTool = {
+    /**
+     * - Whitelist of X handles; cannot use with excluded_x_handles.
+     */
+    allowed_x_handles?: string[] | null | undefined;
+    /**
+     * - Enable image understanding.
+     */
+    enable_image_understanding?: boolean | null | undefined;
+    /**
+     * - Enable video understanding.
+     */
+    enable_video_understanding?: boolean | null | undefined;
+    /**
+     * - Blacklist of X handles; cannot use with allowed_x_handles.
+     */
+    excluded_x_handles?: string[] | null | undefined;
+    /**
+     * - ISO-8601 date (YYYY-MM-DD).
+     */
+    from_date?: string | null | undefined;
+    /**
+     * - ISO-8601 date (YYYY-MM-DD).
+     */
+    to_date?: string | null | undefined;
+    type: "x_search";
+};
+export type FileSearchTool = {
+    /**
+     * - For OpenAI compatibility (reject if set).
+     */
+    filters: Object;
+    /**
+     * - Max results (min 1).
+     */
+    max_num_results?: number | null | undefined;
+    /**
+     * - For OpenAI compatibility (reject if set).
+     */
+    ranking_options: Object;
+    /**
+     * - List of vector store IDs.
+     */
+    vector_store_ids: string[];
+    type: "file_search";
+};
+export type CodeInterpreterTool = {
+    /**
+     * - Container ID or uploaded files object; for OpenAI compatibility (reject if set).
+     */
+    container: string | Object;
+    type: "code_interpreter";
+};
+export type MCPTool = {
+    /**
+     * - Allowed tools.
+     */
+    allowed_tools?: string[] | null | undefined;
+    /**
+     * - Authorization details.
+     */
+    authorization?: string | null | undefined;
+    /**
+     * - Connector ID.
+     */
+    connector_id?: string | null | undefined;
+    /**
+     * - Headers.
+     */
+    headers?: Object | null | undefined;
+    /**
+     * - Approval requirement.
+     */
+    require_approval?: string | null | undefined;
+    /**
+     * - Server description.
+     */
+    server_description?: string | null | undefined;
+    /**
+     * - Server label.
+     */
+    server_label: string;
+    /**
+     * - Server URL.
+     */
+    server_url: string;
+    type: "mcp";
+};
+export type XAIMessage = {
+    /**
+     * - The role of the participant (e.g., "assistant", "user").
+     */
+    role: "assistant" | "user";
+    /**
+     * - The content of the message.
+     */
+    content: Array<XAIContent>;
+};
+export type XAIInputMessage = {
+    /**
+     * - The role of the participant (e.g., "assistant", "user").
+     */
+    role: "assistant" | "user" | "system";
+    /**
+     * - The content of the message.
+     */
+    content: string;
+};
+export type XAIContent = {
+    /**
+     * - The type of content (e.g., "output_text", "input_text").
+     */
+    type: "output_text" | "input_text";
+    /**
+     * - The text content.
+     */
+    text: string;
+};
+export type XAIFunctionCall = {
+    /**
+     * - Unique identifier for the function call.
+     */
+    id: string;
+    /**
+     * - Indicates this is a function call (e.g., "function_call").
+     */
+    type: "function_call";
+    /**
+     * - Unique identifier for the specific function call instance.
+     */
+    call_id: string;
+    /**
+     * - The name of the function being called.
+     */
+    name: string;
+    /**
+     * - JSON string representing arguments passed to the function.
+     */
+    arguments: string;
+};
+export type XAIFunctionCallOutput = {
+    /**
+     * - Indicates this is a function call output (e.g., "function_call_output").
+     */
+    type: "function_call_output";
+    /**
+     * - Identifier linking to the related function call.
+     */
+    call_id: string;
+    /**
+     * - JSON string representing the output from the function call.
+     */
+    output: string;
+};
+/**
+ * Represents an OpenAI API response request INPUT structure.
+ */
+export type XAIInput = (XAIInputMessage | XAIFunctionCall | XAIFunctionCallOutput);
+/**
+* @param {Prompt} prompt
+* @param {ToolSet} [toolset]
+* @param {XAIOptions} [options]
+*/
+export function generateRequest(prompt: Prompt, toolset?: ToolSet, options?: XAIOptions): {
+    url: string;
+    headers: object;
+    body: XAIOptions;
+};
+/**
+* Parse a response
+* @param {number} duration - Fetch time in MS
+* @param {Prompt} prompt
+* @param {import('@j-o-r/apiserver/types/request.js').FetchResponseObject} res
+* @param {import('../../ToolSet.js').default} [toolset]
+*/
+export function parseResponse(duration: number, prompt: Prompt, res: import("@j-o-r/apiserver/types/request.js").FetchResponseObject, toolset?: import("../../ToolSet.js").default): Promise<void>;
+/**
+* Do a request
+* @param {Prompt} prompt
+* @param {ToolSet|null} toolset
+* @param {XAIOptions} [options]:
+* @param {number} [counter] - leave empty this counts the number of requests when doing recursive request calls
+* @return {Promise<import('../../Session.js').Message>}
+*/
+export function request(prompt: Prompt, toolset?: ToolSet | null, options?: XAIOptions, counter?: number): Promise<import("../../Session.js").Message>;

package/types/AgentClient.d.ts

@@ -24,6 +24,10 @@ export type WSOptions = {
      * - Logical name: e.g. search, code, os, support.
      */
     name: string;
+    /**
+     * - Websocket server access secret.
+     */
+    secret: string;
     url?: string | undefined;
     /**
      * - How often to pull one message from the queue.
@@ -48,6 +52,7 @@ export type WSOptions = {
 * @property {ToolSet} [toolset] - The toolset
 * @property {string} description - Custom introduction message.
 * @property {string} name - Logical name: e.g. search, code, os, support.
+* @property {string} secret - Websocket server access secret.
 * @property {string} [url='ws://127.0.0.1:8000/ws?params=1234']
 * @property {number} [intervalMs=250] - How often to pull one message from the queue.
 */

package/types/AgentManager.d.ts

@@ -1,5 +1,6 @@
 export default AgentManager;
 export type XOptions = import("./API/x.ai/text.js").XOptions;
+export type XAIOptions = import("./API/x.ai/responses.js").XAIOptions;
 export type OAOptions = import("./API/openai.com/reponses/text.js").OAOptions;
 export type ANTHOptions = import("./API/anthropic.com/text.js").ANTHOptions;
 export type Setup = {
@@ -10,11 +11,11 @@ export type Setup = {
     /**
      * - Model options
      */
-    options: OAOptions | XOptions | ANTHOptions;
+    options: XAIOptions | OAOptions | XOptions | ANTHOptions;
     /**
      * - AI endpoint to use
      */
-    api: "gpt" | "grok" | "claude";
+    api: "gpt" | "xai" | "claude";
     /**
      * - The size in tokens for the context/session
      */
@@ -33,6 +34,10 @@ export type Options = {
      * - Agent name
      */
     name: string;
+    /**
+     * - Secret string for WS access authorisation (server and client secrets should match)
+     */
+    secret: string;
     /**
      * - path to session/record storage
      */
@@ -40,14 +45,15 @@ export type Options = {
 };
 /**
 * @typedef {import('./API/x.ai/text.js').XOptions} XOptions
+* @typedef {import('./API/x.ai/responses.js').XAIOptions} XAIOptions
 * @typedef {import('./API/openai.com/reponses/text.js').OAOptions} OAOptions
 * @typedef {import('./API/anthropic.com/text.js').ANTHOptions} ANTHOptions
 */
 /**
 * @typedef {Object} Setup
 * @property {string} prompt - Initial system prompt
-* @property {OAOptions|XOptions|ANTHOptions} options - Model options
-* @property {'gpt'|'grok'|'claude'} api - AI endpoint to use
+* @property {XAIOptions|OAOptions|XOptions|ANTHOptions} options - Model options
+* @property {'gpt'|'xai'|'claude'} api - AI endpoint to use
 * @property {number} [contextWindow] - The size in tokens for the context/session
 * @property {'auto'|'required'|void} [toolsetMode] -
 * @property {boolean} [debug] - verbose output
@@ -55,6 +61,7 @@ export type Options = {
 /**
 * @typedef {Object} Options
 * @property {string} name - Agent name
+* @property {string} secret - Secret string for WS access authorisation (server and client secrets should match)
 * @property {string} [cachePath] - path to session/record storage
 */
 declare class AgentManager {
@@ -67,29 +74,6 @@ declare class AgentManager {
     */
     setup(setup: Setup): this;
     /**
-    * Start a CLI for local usage
-    * @param {string} description - introduction message for the CLI user
-    */
-    startCli(description: string): void;
-    /**
-    * Attach a session to an AgentServer
-    * DO NOT ATTACH TO SELF, however, when in server mode
-    * An AgentServer can attach as client to another server
-    * @param {string} name - function_call name
-    * @param {string} description - function_call description
-    * @param {string} [url='ws://127.0.0.1:8000/ws'] - ws URL
-    */
-    attach(name: string, description: string, url?: string): AgentClient;
-    /**
-    * Start the Agent in server mode.
-    * A server is always started on localhost
-    * Clients can attach now and are accesible as via function_calls (toolset)
-    * @param {string} name - function_call name
-    * @param {string} description - function_call description
-    * @param {number} [port=8000] - Start the dynamic toolset server on this port
-    */
-    enableServer(name: string, description?: string, port?: number): void;
-    /**
     * Direct call to the prompt
     * @param {string} input
     * @returns {Promise<string>}
@@ -102,11 +86,20 @@ declare class AgentManager {
     /** @returns {Promise<import('./fafs.js').EnvironmentInfo>} */
     environment(): Promise<import("./fafs.js").EnvironmentInfo>;
     /**
-    * @param {string} name - the toolname
-    */
-    addGenericToolcall(name: string): void;
+     * Add (copy) a pre-defined toolcall to the function_calls
+     * @param {'read_file'|'write_file'|'get_user_env'|'execute_bash_script'|'send_email'|'open_link'|'execute_remote_script'|'history_search'|'javascript_interpreter'} name - name /^[a-z_0-9]{2,}$/ e.g. 'execute_bash_script'
+     */
+    addGenericToolcall(name: "read_file" | "write_file" | "get_user_env" | "execute_bash_script" | "send_email" | "open_link" | "execute_remote_script" | "history_search" | "javascript_interpreter"): void;
+    /**
+     * Smart launcher: Dispatches to CLI/server/attach/direct. Auto-gens cliIntro/desc if empty.
+     * @param {number} [servePort] - Server port (if no input).
+     * @param {string} [connectUrl] - WS to attach. e.g. ws://127.0.0.1:8091/ws
+     * @param {string} [cliIntro=""] - CLI intro (auto-gen if falsy).
+     * @param {string} [toolName=""] - name /^[a-z_0-9]{2,}$/ Tool name for server/attach (defaults to agent.name).
+     * @param {string} [toolDescription=""] - Tool desc (auto-gen if falsy).
+     */
+    start(servePort?: number, connectUrl?: string, cliIntro?: string, toolName?: string, toolDescription?: string): Promise<void>;
     #private;
 }
-import { AgentClient } from './index.js';
 import { Prompt } from './index.js';
 import { ToolSet } from './index.js';

package/types/AgentServer.d.ts

@@ -3,9 +3,13 @@ export type Client = import("../node_modules/@j-o-r/apiserver/types/ClientWrappe
 export type Prompt = import("./Prompt.js").default;
 export type ToolSet = import("./ToolSet.js").default;
 export type Session = import("./Session.js").default;
-export type AuthFunction = (conn: import("@j-o-r/apiserver/types/WebSocketServer.js").WebSocketConnection) => Promise<boolean>;
+export type AuthFunction = (conn: import("@j-o-r/apiserver/types/WebSocketServer.js").WebSocketConnection, req: any) => Promise<boolean>;
 export type AgentServerOptions = {
     name: string;
+    /**
+     * - server access secret
+     */
+    secret: string;
     description: string;
     prompt: Prompt;
     session: Session;

package/types/Prompt.d.ts

@@ -1,19 +1,21 @@
 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 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 XAIOptions = import("./API/x.ai/responses.js").XAIOptions;
 export type OAOptions = import("./API/openai.com/reponses/text.js").OAOptions;
 export type ANTHOptions = import("./API/anthropic.com/text.js").ANTHOptions;
 export type ToolSet = import("./ToolSet.js").default;
 /**
  * - The AI model to use for chat functionality.
  */
-export type request = OARequest | XRequest | ANTHRequest;
+export type request = OARequest | XRequest | ANTHRequest | XAIRequest;
 /**
  * - Model options
  */
-export type options = OAOptions | XOptions | ANTHOptions;
+export type options = OAOptions | XOptions | ANTHOptions | XAIOptions;
 export type Roles = "system" | "assistant" | "user" | "tool" | "log" | "reasoning";
 export type Record = {
     /**

package/types/ToolSet.d.ts

@@ -83,6 +83,7 @@ declare class ToolSet {
     * Execute a method
     * @param {string} name
     * @param {object} params
+    * @returns {Promise<*>}
     */
     call(name: string, params: object): Promise<any>;
     /**

package/types/index.d.ts

@@ -1,3 +1,4 @@
+import AgentManager from './AgentManager.js';
 import AgentServer from './AgentServer.js';
 import AgentClient from './AgentClient.js';
 import Prompt from './Prompt.js';
@@ -6,7 +7,7 @@ import Session from './Session.js';
 export namespace API {
     namespace text {
         export { gpt };
-        export { grok };
+        export { xai };
         export { claude };
     }
     namespace search {
@@ -17,7 +18,7 @@ import Cli from './Cli.js';
 import { env } from './fafs.js';
 import { GLOBAL } from './fafs.js';
 import { request as gpt } from './API/openai.com/reponses/text.js';
-import { request as grok } from './API/x.ai/text.js';
+import { request as xai } 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';
-export { AgentServer, AgentClient, Prompt, ToolSet, Session, Cli, env, GLOBAL };
+export { AgentManager, AgentServer, AgentClient, Prompt, ToolSet, Session, Cli, env, GLOBAL };

package/types/wsCli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env -S node
+declare function _default(connectUrl: string, secret?: string): void;
+export default _default;