hoomanjs 1.1.0 → 1.3.0

package/README.md

@@ -20,6 +20,7 @@ It gives you:
 
 - a one-shot `exec` command for single prompts
 - a stateful `chat` interface for interactive sessions
+- a `daemon` command for processing MCP channel notifications in background
 - an Ink-powered `configure` workflow for editing app config, `instructions.md`, MCP servers, and installed skills
 - an `acp` command for running Hooman as an Agent Client Protocol (ACP) agent over stdio
 
@@ -28,6 +29,8 @@ It gives you:
 - Multiple LLM providers: `ollama`, `openai`, `anthropic`, `google`, `bedrock`
 - 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
+- MCP channel notification support through `hooman daemon --channel <name>`
 - Skill discovery / install / removal through the integrated configure flow
 - Interactive terminal UI for chat and configuration
 
@@ -132,9 +135,35 @@ Choose a toolkit size:
 hooman chat --toolkit max
 ```
 
+### `hooman daemon`
+
+Run a long-lived daemon that subscribes to one or more MCP notification channels and feeds each received notification into the agent as a queued prompt.
+
+```bash
+hooman daemon --channel hooman/channel
+```
+
+Subscribe to multiple channels:
+
+```bash
+hooman daemon --channel hooman/channel --channel alerts/channel
+```
+
+Resume or pin a session id:
+
+```bash
+hooman daemon --session my-daemon --channel hooman/channel
+```
+
+Choose a toolkit size:
+
+```bash
+hooman daemon --toolkit full --channel hoomanjs/channel
+```
+
 ### Toolkit Levels
 
-`exec`, `chat`, and `acp` support `-t, --toolkit <lite|full|max>`.
+`exec`, `chat`, `daemon`, and `acp` support `-t, --toolkit <lite|full|max>`.
 
 - `lite` - time, fetch, long-term-memory, installed skills, and configured MCP server tools
 - `full` - `lite` plus filesystem, shell, and thinking tools
@@ -359,6 +388,15 @@ Supports `region`, `clientConfig`, and optional `apiKey`, with all other values
 }
 ```
 
+## MCP Notes
+
+- MCP server `instructions` from the protocol `initialize` response are appended to Hooman's system prompt, after local `instructions.md` and session-specific prompt overrides.
+- Hooman reads these instructions automatically from connected MCP servers when building the agent.
+- `hooman daemon` can subscribe to server-published notification channels such as `hoomanjs/channel`.
+- Only MCP servers that advertise the requested channel capability are subscribed.
+- When a matching notification is received, Hooman uses `params.content` as the prompt if it is a string; otherwise it JSON-stringifies the notification params and sends that to the agent.
+- Daemon mode processes notifications sequentially, reuses the same agent session over time, and **auto-approves tool calls**.
+
 ## Skills
 
 Skills are installed under:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hoomanjs",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Bun-powered local AI agent CLI with chat, exec, ACP, MCP, and skills support.",
   "author": {
     "name": "Vaibhav Pandey",
@@ -60,6 +60,7 @@
     "chromadb": "^3.4.3",
     "cli-spinners": "^3.4.0",
     "commander": "^14.0.3",
+    "fastq": "^1.20.1",
     "gray-matter": "^4.0.3",
     "handlebars": "^4.7.9",
     "ink": "^7.0.0",

package/src/cli.ts

@@ -9,6 +9,7 @@ import { createToolApprovalHandler } from "./exec/approvals.ts";
 import { chat } from "./chat/index.tsx";
 import { configure } from "./configure/index.tsx";
 import { runAcpStdio } from "./acp/acp-agent.ts";
+import { main as daemon } from "./daemon/index.ts";
 
 async function readPackageMeta(): Promise<{
   name: string;
@@ -122,6 +123,53 @@ program
     },
   );
 
+program
+  .command("daemon")
+  .description(
+    "Run a background daemon that processes MCP channel notifications as prompts.",
+  )
+  .option("-s, --session <id>", "Session ID to use.")
+  .requiredOption(
+    "-c, --channel <name>",
+    "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 ?? [];
+      const {
+        agent,
+        mcp: { manager },
+      } = await bootstrap(
+        { sessionId, toolkit: options.toolkit ?? "full" },
+        true,
+      );
+      try {
+        await daemon({
+          agent,
+          manager,
+          channels,
+          debug: Boolean(options.debug),
+        });
+      } finally {
+        try {
+          await manager.disconnect();
+        } catch {}
+      }
+    },
+  );
+
 program
   .command("configure")
   .description("Manage app config, MCP servers, and installed skills.")

package/src/core/agent/index.ts

@@ -42,13 +42,14 @@ export async function create(
 ): Promise<Agent> {
   const sessionId = meta.sessionId;
   const userId = meta.userId ?? sessionId;
-  const toolkit = meta.toolkit ?? "max";
+  const toolkit = meta.toolkit ?? "full";
   const llm = await modelProviders[config.llm.provider]!();
   const stm = createShortTermMemory(sessionId);
   const ltm = config.ltm.enabled ? createLongTermMemoryStore(config) : null;
   const skills = await createSkillsPrompt(registry);
   const tools = await mcp.manager.listPrefixedTools();
-  const prompt = [system.content, meta.systemPrompt, skills.content]
+  const append = await mcp.manager.listServerInstructions();
+  const prompt = [system.content, meta.systemPrompt, ...append, skills.content]
     .filter((x) => !!x)
     .join(SECTION_BREAK);
   return new Agent({

package/src/core/mcp/index.ts

@@ -1,8 +1,8 @@
 import { Config, type NamedMcpTransport } from "./config.ts";
-import { Manager } from "./manager.ts";
+import { Manager, type ChannelMessage } from "./manager.ts";
 
 export { Config, Manager };
-export type { NamedMcpTransport };
+export type { ChannelMessage, NamedMcpTransport };
 export { createMcpTools } from "./tools.ts";
 
 export function createMcpConfig(path: string): Config {

package/src/core/mcp/manager.ts

@@ -4,9 +4,22 @@ import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js"
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
 import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import { z } from "zod";
 import { Config, type NamedMcpTransport } from "./config.ts";
 import type { McpTransport } from "./types.ts";
 
+export type ChannelMessageMeta = {
+  server: string;
+  channel: string;
+  method: string;
+  params: unknown;
+};
+
+export type ChannelMessage = {
+  prompt: string;
+  meta: ChannelMessageMeta;
+};
+
 function transportFor(spec: McpTransport): Transport {
   switch (spec.type) {
     case "stdio":
@@ -106,12 +119,118 @@ export class Manager {
     }
     const map = this.instances!;
     const batches = await Promise.all(
-      [...map.entries()].map(async ([serverKey, client]) =>
+      [...map.entries()].map(async ([server, client]) =>
         client
           .listTools()
-          .then((tools) => tools.map((t) => new PrefixedMcpTool(serverKey, t))),
+          .then((tools) => tools.map((t) => new PrefixedMcpTool(server, t))),
       ),
     );
     return batches.flat();
   }
+
+  /**
+   * Collects optional server-level instructions from each connected MCP server.
+   */
+  public async listServerInstructions(): Promise<string[]> {
+    if (this.instances === null) {
+      this.reload();
+    }
+    const map = this.instances!;
+    const rows = await Promise.all(
+      [...map.entries()].map(async ([server, client]) => {
+        await client.connect();
+        const instructions = client.client.getInstructions()?.trim();
+        if (!instructions) {
+          return "";
+        }
+
+        return [`MCP server "${server}" instructions:`, "", instructions].join(
+          "\n",
+        );
+      }),
+    );
+    return rows.filter(Boolean);
+  }
+
+  public async subscribeToChannels(
+    channels: readonly string[],
+    onMessage: (message: ChannelMessage) => void,
+  ): Promise<() => void> {
+    if (this.instances === null) {
+      this.reload();
+    }
+
+    const map = this.instances!;
+    const requested = [
+      ...new Set(channels.map((c) => c.trim()).filter(Boolean)),
+    ];
+    if (requested.length === 0) {
+      return () => {};
+    }
+
+    const unsubs: Array<() => void> = [];
+    for (const [server, client] of map.entries()) {
+      await client.connect();
+      const experimental =
+        client.client.getServerCapabilities()?.experimental ?? {};
+      for (const channel of requested) {
+        if (!Object.hasOwn(experimental, channel)) {
+          continue;
+        }
+
+        const method = `notifications/${channel}`;
+        const schema = z.object({
+          method: z.literal(method),
+          params: z.unknown().optional(),
+        });
+        const handler = (notification: {
+          method: string;
+          params?: unknown;
+        }) => {
+          const { method, params } = notification;
+          const prompt = this.toChannelPrompt(method, params);
+          if (!prompt) {
+            return;
+          }
+
+          onMessage({
+            prompt,
+            meta: {
+              server,
+              channel,
+              method,
+              params,
+            },
+          });
+        };
+        client.client.setNotificationHandler(schema, handler);
+        unsubs.push(() => {
+          client.client.setNotificationHandler(schema, () => {});
+        });
+      }
+    }
+
+    return () => {
+      for (const off of unsubs) {
+        off();
+      }
+    };
+  }
+
+  private toChannelPrompt(method: string, params?: unknown): string {
+    if (
+      params &&
+      typeof params === "object" &&
+      "content" in params &&
+      typeof params.content === "string"
+    ) {
+      return params.content.trim();
+    }
+
+    try {
+      return JSON.stringify(params).trim();
+    } catch {
+      return String(params).trim();
+    }
+  }
 }

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

@@ -0,0 +1,60 @@
+import { stderr } from "node:process";
+import { BeforeToolCallEvent, type Agent } from "@strands-agents/sdk";
+import type {
+  ChannelMessage,
+  Manager as McpManager,
+} from "../core/mcp/index.ts";
+import { createQueue } from "./queue.ts";
+
+type RunDaemonOptions = {
+  agent: Agent;
+  manager: McpManager;
+  channels: string[];
+  debug?: boolean;
+};
+
+function debug(text: string): void {
+  stderr.write(`[daemon] ${text}\n`);
+}
+
+export async function main(options: RunDaemonOptions): Promise<void> {
+  const channels = [
+    ...new Set(options.channels.map((value) => value.trim()).filter(Boolean)),
+  ];
+  if (channels.length === 0) {
+    throw new Error("At least one --channel <name> is required.");
+  }
+
+  // Daemon mode is non-interactive: approve tool calls by default.
+  options.agent.addHook(BeforeToolCallEvent, async () => {});
+
+  let fasterq: Awaited<ReturnType<typeof createQueue>>[0] | null = null;
+
+  const unsubscribe = await options.manager.subscribeToChannels(
+    channels,
+    (message) => {
+      if (fasterq != null) {
+        void fasterq.push(message);
+      }
+    },
+  );
+
+  const [queue, stop] = await createQueue(async (message: ChannelMessage) => {
+    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 → ${message.meta.server}:${message.meta.channel}: ${text}`,
+      );
+    }
+  }, unsubscribe);
+
+  fasterq = queue;
+
+  await stop();
+}

package/src/daemon/queue.ts

@@ -0,0 +1,48 @@
+import fastq from "fastq";
+import type { ChannelMessage } from "../core/mcp/index.ts";
+
+type MessageQueue = fastq.queueAsPromised<ChannelMessage, void>;
+
+export async function createQueue(
+  handler: (message: ChannelMessage) => Promise<void>,
+  cleanup: () => void,
+): Promise<[MessageQueue, () => Promise<void>]> {
+  let stopping = false;
+  let resolver: (() => void) | null = null;
+  const queue: MessageQueue = fastq.promise(async (message: ChannelMessage) => {
+    await handler(message);
+  }, 1);
+
+  const stopper = new Promise<void>((resolve) => {
+    resolver = resolve;
+  });
+
+  const shutdown = () => {
+    if (stopping) {
+      return;
+    }
+    stopping = true;
+    queue.kill();
+    resolver?.();
+  };
+
+  const onSigInt = () => shutdown();
+  const onSigTerm = () => shutdown();
+
+  process.on("SIGINT", onSigInt);
+  process.on("SIGTERM", onSigTerm);
+
+  return [
+    queue,
+    async () => {
+      try {
+        await stopper;
+      } finally {
+        cleanup();
+        await queue.drained().catch(() => {});
+        process.off("SIGINT", onSigInt);
+        process.off("SIGTERM", onSigTerm);
+      }
+    },
+  ];
+}