hoomanjs 1.2.0 → 1.4.0

package/README.md

@@ -26,7 +26,7 @@ It gives you:
 
 ## Features
 
-- Multiple LLM providers: `ollama`, `openai`, `anthropic`, `google`, `bedrock`
+- Multiple LLM providers: `ollama`, `openai`, `anthropic`, `google`, `bedrock`, `xai`
 - Local configuration under `~/.hooman`
 - MCP server support via `stdio`, `streamable-http`, and `sse`
 - MCP server `instructions` support: server-provided instructions are appended to the agent system prompt
@@ -262,6 +262,7 @@ Supported `llm.provider` values:
 - `anthropic`
 - `google`
 - `bedrock`
+- `xai`
 
 ## Provider Notes
 
@@ -328,6 +329,21 @@ Uses Strands `GoogleModel` on top of `@google/genai`. Top-level options like `ap
 
 Supports `region`, `clientConfig`, and optional `apiKey`, with all other values forwarded as Bedrock model options.
 
+### xAI
+
+Uses the Vercel AI SDK xAI provider (`@ai-sdk/xai`) on top of Strands `VercelModel`. Provider-specific settings `apiKey`, `baseURL`, and `headers` are picked up; other values are forwarded into the model config (`temperature`, `maxTokens`, etc.). Defaults to `XAI_API_KEY` from the environment when no `apiKey` is supplied.
+
+```json
+{
+  "provider": "xai",
+  "model": "grok-4.20-non-reasoning",
+  "params": {
+    "apiKey": "...",
+    "temperature": 0.7
+  }
+}
+```
+
 ## MCP Configuration
 
 `mcp.json` is stored as:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hoomanjs",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Bun-powered local AI agent CLI with chat, exec, ACP, MCP, and skills support.",
   "author": {
     "name": "Vaibhav Pandey",
@@ -51,6 +51,7 @@
   "dependencies": {
     "@agentclientprotocol/sdk": "^0.18.2",
     "@ai-sdk/anthropic": "^3.0.69",
+    "@ai-sdk/xai": "^3.0.83",
     "@aws-sdk/client-bedrock-runtime": "^3.1028.0",
     "@google/genai": "^1.40.0",
     "@huggingface/transformers": "^4.0.1",

package/src/cli.ts

@@ -134,12 +134,17 @@ program
     "MCP notification channel to subscribe to (repeatable).",
     (value: string, previous?: string[]) => [...(previous ?? []), value],
   )
+  .option(
+    "--debug",
+    "Log each MCP channel notification payload to the console.",
+  )
   .addOption(createToolkitOption())
   .action(
     async (options: {
       session?: string;
       toolkit?: Toolkit;
       channel?: string[];
+      debug?: boolean;
     }) => {
       const sessionId = options.session?.trim() || crypto.randomUUID();
       const channels = options.channel ?? [];
@@ -151,7 +156,12 @@ program
         true,
       );
       try {
-        await daemon({ agent, manager, channels });
+        await daemon({
+          agent,
+          manager,
+          channels,
+          debug: Boolean(options.debug),
+        });
       } finally {
         try {
           await manager.disconnect();

package/src/core/config.ts

@@ -8,6 +8,7 @@ export enum LlmProvider {
   OpenAI = "openai",
   Ollama = "ollama",
   Bedrock = "bedrock",
+  Xai = "xai",
 }
 
 const LlmSchema = z.object({

package/src/core/models/index.ts

@@ -13,4 +13,5 @@ export const modelProviders: Record<string, () => Promise<ModelProvider>> = {
   google: () => import("./google.ts"),
   ollama: () => import("./ollama/index.ts"),
   openai: () => import("./openai.ts"),
+  xai: () => import("./xai.ts"),
 };

package/src/core/models/xai.ts

@@ -0,0 +1,47 @@
+import { createXai, xai } from "@ai-sdk/xai";
+import { VercelModel } from "@strands-agents/sdk/models/vercel";
+import type { XaiProviderSettings } from "@ai-sdk/xai";
+import type { VercelModelConfig } from "@strands-agents/sdk/models/vercel";
+import { omit, pick } from "lodash";
+
+const PROVIDER_SETTINGS_KEYS = ["apiKey", "baseURL", "headers"] as const;
+
+function pickProviderSettings(
+  params: Record<string, unknown>,
+): XaiProviderSettings {
+  const picked = pick(params, [...PROVIDER_SETTINGS_KEYS]) as Record<
+    string,
+    unknown
+  >;
+  const unset = Object.keys(picked).filter((k) => picked[k] === undefined);
+  return omit(picked, unset) as XaiProviderSettings;
+}
+
+function pickVercelModelConfig(
+  params: Record<string, unknown>,
+): Partial<VercelModelConfig> {
+  return omit(params, [
+    ...PROVIDER_SETTINGS_KEYS,
+  ]) as Partial<VercelModelConfig>;
+}
+
+/**
+ * xAI (Grok) via AI SDK + Strands {@link VercelModel}.
+ *
+ * - **`config.llm.model`**: model id passed to `xai(...)` (e.g. `grok-4.20-non-reasoning`).
+ * - **`params`**: {@link XaiProviderSettings} (`apiKey`, `baseURL`, `headers`).
+ *   If none are set, the default provider is used (`XAI_API_KEY` from env).
+ * - Any other `params` keys are forwarded as {@link VercelModelConfig} (e.g. `temperature`, `maxTokens`).
+ */
+export function create(
+  model: string,
+  params: Record<string, unknown> = {},
+): VercelModel {
+  const settings = pickProviderSettings(params);
+  const provider = Object.keys(settings).length > 0 ? createXai(settings) : xai;
+  const config = pickVercelModelConfig(params);
+  return new VercelModel({
+    provider: provider(model),
+    ...config,
+  });
+}

package/src/core/tools/filesystem.ts

@@ -2,9 +2,20 @@ import { createHash } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
 import os from "node:os";
-import { tool } from "@strands-agents/sdk";
+import {
+  DocumentBlock,
+  ImageBlock,
+  TextBlock,
+  VideoBlock,
+  tool,
+  type JSONValue,
+} from "@strands-agents/sdk";
 import { getCwd } from "../utils/cwd-context.ts";
-import type { JSONValue } from "@strands-agents/sdk";
+import {
+  detectDocumentFormat,
+  detectImageFormat,
+  detectVideoFormat,
+} from "../utils/file-formats.ts";
 import { z } from "zod";
 
 const DEFAULT_READ_LIMIT = 250;
@@ -190,7 +201,7 @@ async function readTextFile(
   const buffer = await fs.readFile(filePath);
   if (isProbablyBinary(buffer)) {
     throw new Error(
-      "File appears to be binary. Use get_file_info or read_file with as_base64 if you extend the tool for binary reads.",
+      "File appears to be binary. Call read_file again with `binary: true` — images (png/jpeg/gif/webp), videos (mp4/mov/mkv/webm/etc.), and documents (pdf/docx/csv/etc.) are returned as multimodal content blocks the provider can forward to the model; unknown binary types come back as base64.",
     );
   }
 
@@ -211,14 +222,87 @@ async function readTextFile(
   };
 }
 
-async function readBinaryFile(filePath: string): Promise<{
-  path: string;
-  encoding: "base64";
-  content: string;
-  sizeBytes: number;
-}> {
+type BinaryReadResult =
+  | Array<TextBlock | ImageBlock | VideoBlock | DocumentBlock>
+  | {
+      path: string;
+      encoding: "base64";
+      content: string;
+      sizeBytes: number;
+    };
+
+async function readBinaryFile(
+  filePath: string,
+  options?: { maxBytes?: number },
+): Promise<BinaryReadResult> {
   await ensureFile(filePath);
+  const stat = await fs.stat(filePath);
+
+  if (stat.size > (options?.maxBytes ?? DEFAULT_MAX_READ_BYTES)) {
+    throw new Error(
+      `File too large to read safely (${stat.size} bytes). Use get_file_info for metadata or process the file with another tool.`,
+    );
+  }
+
   const buffer = await fs.readFile(filePath);
+  // ImageBlock / DocumentBlock expect Uint8Array; construct a zero-copy view.
+  const bytes = new Uint8Array(
+    buffer.buffer,
+    buffer.byteOffset,
+    buffer.byteLength,
+  );
+
+  const imageFormat = detectImageFormat(filePath);
+  if (imageFormat) {
+    const metadata = new TextBlock(
+      JSON.stringify({
+        path: filePath,
+        kind: "image",
+        format: imageFormat,
+        size_bytes: stat.size,
+      }),
+    );
+    const image = new ImageBlock({
+      format: imageFormat,
+      source: { bytes },
+    });
+    return [metadata, image];
+  }
+
+  const videoFormat = detectVideoFormat(filePath);
+  if (videoFormat) {
+    const metadata = new TextBlock(
+      JSON.stringify({
+        path: filePath,
+        kind: "video",
+        format: videoFormat,
+        size_bytes: stat.size,
+      }),
+    );
+    const video = new VideoBlock({
+      format: videoFormat,
+      source: { bytes },
+    });
+    return [metadata, video];
+  }
+
+  const documentFormat = detectDocumentFormat(filePath);
+  if (documentFormat) {
+    const metadata = new TextBlock(
+      JSON.stringify({
+        path: filePath,
+        kind: "document",
+        format: documentFormat,
+        size_bytes: stat.size,
+      }),
+    );
+    const document = new DocumentBlock({
+      name: path.basename(filePath),
+      format: documentFormat,
+      source: { bytes },
+    });
+    return [metadata, document];
+  }
 
   return {
     path: filePath,
@@ -437,7 +521,9 @@ function createFilesystemSchema() {
       binary: z
         .boolean()
         .optional()
-        .describe("Return file as base64 instead of UTF-8 text."),
+        .describe(
+          "Read as binary. Images, videos, and documents are returned as multimodal content blocks (forwarded to the active provider's native media format where supported); other binary files come back as base64.",
+        ),
     }),
     readMultipleFiles: z.object({
       paths: z.array(z.string()).min(1).describe("List of file paths to read."),
@@ -519,17 +605,23 @@ export function createFilesystemTools() {
     tool({
       name: "read_file",
       description:
-        "Read a text file with optional line offset/limit. For binary files, enable the `binary` option to return base64.",
+        "Read a file. Defaults to UTF-8 text with optional line offset/limit. Pass `binary: true` for non-text files: images (jpeg/png/gif/webp), videos (mp4/mov/mkv/webm/etc.), and documents (pdf/docx/csv/etc.) are returned as multimodal content blocks — the active model provider forwards them natively where supported (Bedrock for all; Anthropic for images + docs; Google for images + docs; OpenAI for images; Ollama for images) and logs a warning for unsupported kinds. Any other binary file is returned as base64.",
       inputSchema: schema.readFile,
       callback: async (input) => {
         const filePath = normalizeUserPath(input.path);
-        const result = input.binary
-          ? await readBinaryFile(filePath)
-          : await readTextFile(filePath, {
-              offset: input.offset,
-              limit: input.limit,
-            });
 
+        if (input.binary) {
+          // Binary reads can return SDK media blocks (ImageBlock / DocumentBlock)
+          // or a plain base64 JSON object. Both are accepted by FunctionTool's
+          // result wrapping, but the callback signature is JSONValue, so cast.
+          const result = await readBinaryFile(filePath);
+          return result as unknown as JSONValue;
+        }
+
+        const result = await readTextFile(filePath, {
+          offset: input.offset,
+          limit: input.limit,
+        });
         return toJsonValue(result);
       },
     }),

package/src/core/utils/file-formats.ts

@@ -0,0 +1,60 @@
+import path from "node:path";
+import type {
+  DocumentFormat,
+  ImageFormat,
+  VideoFormat,
+} from "@strands-agents/sdk";
+
+// Extension → SDK media format. Values must match the unions the Strands SDK
+// exposes so ImageBlock / VideoBlock / DocumentBlock construct cleanly. Each
+// provider adapter (OpenAI, Anthropic, Bedrock, Google, Ollama) converts these
+// into its native shape or gracefully drops unsupported ones with a warning —
+// the paired TextBlock metadata still reaches the model either way.
+const IMAGE_EXT_FORMATS: Record<string, ImageFormat> = {
+  ".png": "png",
+  ".jpg": "jpeg",
+  ".jpeg": "jpeg",
+  ".gif": "gif",
+  ".webp": "webp",
+};
+
+const VIDEO_EXT_FORMATS: Record<string, VideoFormat> = {
+  ".mp4": "mp4",
+  ".mov": "mov",
+  ".mkv": "mkv",
+  ".webm": "webm",
+  ".flv": "flv",
+  ".mpeg": "mpeg",
+  ".mpg": "mpg",
+  ".wmv": "wmv",
+  ".3gp": "3gp",
+};
+
+const DOCUMENT_EXT_FORMATS: Record<string, DocumentFormat> = {
+  ".pdf": "pdf",
+  ".csv": "csv",
+  ".doc": "doc",
+  ".docx": "docx",
+  ".xls": "xls",
+  ".xlsx": "xlsx",
+  ".html": "html",
+  ".htm": "html",
+  ".txt": "txt",
+  ".md": "md",
+  ".json": "json",
+  ".xml": "xml",
+};
+
+export function detectImageFormat(filePath: string): ImageFormat | undefined {
+  return IMAGE_EXT_FORMATS[path.extname(filePath).toLowerCase()];
+}
+
+export function detectVideoFormat(filePath: string): VideoFormat | undefined {
+  return VIDEO_EXT_FORMATS[path.extname(filePath).toLowerCase()];
+}
+
+export function detectDocumentFormat(
+  filePath: string,
+): DocumentFormat | undefined {
+  return DOCUMENT_EXT_FORMATS[path.extname(filePath).toLowerCase()];
+}

package/src/daemon/index.ts

@@ -10,6 +10,7 @@ type RunDaemonOptions = {
   agent: Agent;
   manager: McpManager;
   channels: string[];
+  debug?: boolean;
 };
 
 function debug(text: string): void {
@@ -39,13 +40,16 @@ export async function main(options: RunDaemonOptions): Promise<void> {
   );
 
   const [queue, stop] = await createQueue(async (message: ChannelMessage) => {
-    debug(`notification from ${message.meta.server}:${message.meta.channel}`);
+    debug(`processing → ${message.meta.server}:${message.meta.channel}`);
+    if (options.debug) {
+      debug(`raw → ${JSON.stringify(message.meta)}`);
+    }
     try {
       await options.agent.invoke(message.prompt);
     } catch (error) {
       const text = error instanceof Error ? error.message : String(error);
       debug(
-        `turn failed for ${message.meta.server}:${message.meta.channel}: ${text}`,
+        `turn failed → ${message.meta.server}:${message.meta.channel}: ${text}`,
       );
     }
   }, unsubscribe);