hoomanjs 1.1.0 → 1.2.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.2.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,43 @@ 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],
+  )
+  .addOption(createToolkitOption())
+  .action(
+    async (options: {
+      session?: string;
+      toolkit?: Toolkit;
+      channel?: string[];
+    }) => {
+      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 });
+      } 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/daemon/index.ts

@@ -0,0 +1,56 @@
+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[];
+};
+
+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(`notification from ${message.meta.server}:${message.meta.channel}`);
+    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}`,
+      );
+    }
+  }, 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);
+      }
+    },
+  ];
+}