hoomanjs 1.0.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
@@ -174,7 +203,7 @@ hooman acp --toolkit max
 ACP notes:
 
 - ACP sessions are stored under `~/.hooman/acp-sessions`
-- ACP uses Hooman's local `mcp.json`; client-provided MCP servers and client workspace tools are not exposed
+- ACP loads MCP servers passed on `session/new` and `session/load`, in addition to Hooman's local `mcp.json`
 - ACP `session/new` and `session/load` support `_meta.userId` and `_meta.systemPrompt`
 - when `_meta.systemPrompt` is provided, it is appended to the agent system prompt with a section break
 
@@ -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.0.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/acp/acp-agent.ts

@@ -42,6 +42,7 @@ import { extractAcpClientUserId } from "./meta/user-id.ts";
 import { deriveSessionTitleFromEcho } from "./sessions/title.ts";
 import { acpPromptEchoText, acpPromptToInvokeArgs } from "./prompt-invoke.ts";
 import type { Config } from "../core/config.ts";
+import { normalizeAcpSessionMcpServers } from "./mcp-servers.ts";
 import {
   listStoredSessionIds,
   loadSessionMessages,
@@ -206,6 +207,10 @@ export class AcpAgent implements AgentContract {
       authMethods: [],
       agentCapabilities: {
         loadSession: true,
+        mcpCapabilities: {
+          http: true,
+          sse: true,
+        },
         promptCapabilities: {
           embeddedContext: true,
           image: true,
@@ -315,6 +320,7 @@ export class AcpAgent implements AgentContract {
     const clientSystemPrompt =
       extractAcpClientSystemPrompt(params._meta) ?? null;
     const bootstrapUserId = clientUserId ?? sessionId;
+    const mcpServers = normalizeAcpSessionMcpServers(params.mcpServers);
 
     const now = new Date().toISOString();
     const meta: SessionMetaFile = {
@@ -324,6 +330,7 @@ export class AcpAgent implements AgentContract {
       title: null,
       userId: clientUserId,
       systemPrompt: clientSystemPrompt,
+      mcpServers,
     };
     await writeSessionMeta(this.#acpRoot, sessionId, meta);
 
@@ -336,6 +343,7 @@ export class AcpAgent implements AgentContract {
         userId: bootstrapUserId,
         sessionId,
         toolkit: this.#toolkit,
+        mcpServers,
         ...(clientSystemPrompt ? { systemPrompt: clientSystemPrompt } : {}),
       },
       false,
@@ -419,6 +427,10 @@ export class AcpAgent implements AgentContract {
         ? requestedSystemPrompt
         : storedSystemPrompt;
     const bootstrapUserId = clientUserId ?? params.sessionId;
+    const mcpServers =
+      params.mcpServers.length > 0
+        ? normalizeAcpSessionMcpServers(params.mcpServers)
+        : (existing.mcpServers ?? []);
 
     const {
       config,
@@ -429,6 +441,7 @@ export class AcpAgent implements AgentContract {
         userId: bootstrapUserId,
         sessionId: params.sessionId,
         toolkit: this.#toolkit,
+        mcpServers,
         ...(clientSystemPrompt ? { systemPrompt: clientSystemPrompt } : {}),
       },
       false,
@@ -487,6 +500,7 @@ export class AcpAgent implements AgentContract {
       ...(requestedSystemPrompt !== undefined
         ? { systemPrompt: requestedSystemPrompt || null }
         : {}),
+      mcpServers,
     });
 
     return {

package/src/acp/mcp-servers.ts

@@ -0,0 +1,64 @@
+import { RequestError, type McpServer } from "@agentclientprotocol/sdk";
+import type { NamedMcpTransport } from "../core/mcp/index.ts";
+
+function pairsToRecord(
+  pairs: ReadonlyArray<{ name: string; value: string }>,
+): Record<string, string> | undefined {
+  if (pairs.length === 0) {
+    return undefined;
+  }
+  return Object.fromEntries(pairs.map((pair) => [pair.name, pair.value]));
+}
+
+function toNamedTransport(server: McpServer): NamedMcpTransport {
+  if ("command" in server) {
+    return {
+      name: server.name,
+      transport: {
+        type: "stdio",
+        command: server.command,
+        args: server.args,
+        env: pairsToRecord(server.env),
+      },
+    };
+  }
+  if (server.type === "http") {
+    return {
+      name: server.name,
+      transport: {
+        type: "streamable-http",
+        url: server.url,
+        headers: pairsToRecord(server.headers),
+      },
+    };
+  }
+  return {
+    name: server.name,
+    transport: {
+      type: "sse",
+      url: server.url,
+      headers: pairsToRecord(server.headers),
+    },
+  };
+}
+
+/**
+ * Convert ACP session MCP server definitions into the transport shape used by
+ * Hooman's MCP manager.
+ */
+export function normalizeAcpSessionMcpServers(
+  servers: readonly McpServer[] | null | undefined,
+): NamedMcpTransport[] {
+  const normalized = (servers ?? []).map(toNamedTransport);
+  const seen = new Set<string>();
+  for (const { name } of normalized) {
+    if (seen.has(name)) {
+      throw RequestError.invalidParams({
+        mcpServers: servers,
+        message: `Duplicate ACP MCP server name "${name}" in session request`,
+      });
+    }
+    seen.add(name);
+  }
+  return normalized;
+}

package/src/acp/sessions/store.ts

@@ -2,6 +2,7 @@ import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import type { SessionInfo } from "@agentclientprotocol/sdk";
 import type { MessageData } from "@strands-agents/sdk";
+import type { NamedMcpTransport } from "../../core/mcp/config.ts";
 
 export type SessionMetaFile = {
   cwd: string;
@@ -12,6 +13,8 @@ export type SessionMetaFile = {
   userId?: string | null;
   /** Session-level system prompt from ACP client `_meta`. */
   systemPrompt?: string | null;
+  /** Session-scoped MCP servers requested by the ACP client. */
+  mcpServers?: NamedMcpTransport[];
 };
 
 const META = "meta.json";

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/index.ts

@@ -6,6 +6,7 @@ import {
   createMcpManager,
   type Config as McpServersConfig,
   type Manager as McpConnectionManager,
+  type NamedMcpTransport,
 } from "./mcp/index.ts";
 import { createSkillsRegistry } from "./skills/index.ts";
 import type { Registry } from "./skills/index.ts";
@@ -23,6 +24,7 @@ export async function bootstrap(
     userId?: string;
     sessionId: string;
     systemPrompt?: string;
+    mcpServers?: NamedMcpTransport[];
     toolkit?: Toolkit;
   },
   print: boolean = false,
@@ -34,7 +36,7 @@ export async function bootstrap(
 }> {
   const config = new Config(configJsonPath());
   const mcpConfig = createMcpConfig(mcpJsonPath());
-  const mcpManager = createMcpManager(mcpConfig);
+  const mcpManager = createMcpManager(mcpConfig, meta.mcpServers ?? []);
   const mcp = { config: mcpConfig, manager: mcpManager };
   const registry = createSkillsRegistry(basePath());
   const toolkit = meta.toolkit ?? "max";

package/src/core/mcp/index.ts

@@ -1,13 +1,17 @@
-import { Config } from "./config.ts";
-import { Manager } from "./manager.ts";
+import { Config, type NamedMcpTransport } from "./config.ts";
+import { Manager, type ChannelMessage } from "./manager.ts";
 
 export { Config, Manager };
+export type { ChannelMessage, NamedMcpTransport };
 export { createMcpTools } from "./tools.ts";
 
 export function createMcpConfig(path: string): Config {
   return new Config(path);
 }
 
-export function createMcpManager(config: Config): Manager {
-  return new Manager(config);
+export function createMcpManager(
+  config: Config,
+  mcpServers: readonly NamedMcpTransport[] = [],
+): Manager {
+  return new Manager(config, mcpServers);
 }

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 { Config } from "./config.ts";
+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":
@@ -43,7 +56,10 @@ function transportFor(spec: McpTransport): Transport {
 export class Manager {
   private instances: Map<string, McpClient> | null = null;
 
-  public constructor(private readonly config: Config) {}
+  public constructor(
+    private readonly config: Config,
+    private readonly mcpServers: readonly NamedMcpTransport[] = [],
+  ) {}
 
   /** Lazily builds clients from the current in-memory config (reloads file first). */
   get clients(): ReadonlyMap<string, McpClient> {
@@ -61,7 +77,12 @@ export class Manager {
     this.config.reload();
     const previous = this.instances;
     const next = new Map<string, McpClient>();
-    for (const { name, transport } of this.config.list()) {
+    const transports = [
+      ...this.config.list(),
+      // Session-scoped ACP servers intentionally override local config names.
+      ...this.mcpServers,
+    ];
+    for (const { name, transport } of transports) {
       next.set(
         name,
         new McpClient({
@@ -98,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);
+      }
+    },
+  ];
+}