hoomanjs 1.18.0 → 1.18.1

package/src/core/mcp/manager.ts

@@ -1,491 +0,0 @@
-import { McpClient, type Tool } from "@strands-agents/sdk";
-import { PrefixedMcpTool } from "./prefixed-mcp-tool.ts";
-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 { get } from "lodash";
-import { z } from "zod";
-import { Config, type NamedMcpTransport } from "./config.ts";
-import type { McpTransport } from "./types.ts";
-import { normalizeAttachmentPaths } from "../utils/attachments.ts";
-
-export const HOOMAN_CHANNEL = "hooman/channel";
-export const HOOMAN_CHANNEL_PERMISSION = "hooman/channel/permission";
-const HOOMAN_CHANNEL_PERMISSION_METHOD = `notifications/${HOOMAN_CHANNEL_PERMISSION}`;
-
-export type ChannelMessageMeta = {
-  subscription: ChannelSubscription;
-  source?: string;
-  user?: string;
-  session?: string;
-  thread?: string;
-};
-
-export type ChannelMessage = {
-  prompt: string;
-  attachments: string[];
-  meta: ChannelMessageMeta;
-};
-
-export type ChannelPermissionBehavior = "allow_once" | "allow_always" | "deny";
-
-export type ChannelSubscription = {
-  server: string;
-  channel: string;
-};
-
-export type ChannelSubscriptionHandle = {
-  unsubscribe: () => void;
-  subscriptions: ChannelSubscription[];
-};
-
-type ChannelPermissionRequest = {
-  requestId: string;
-  tool: string;
-  description: string;
-  preview: string;
-  source?: string;
-  user?: string;
-  session?: string;
-  thread?: string;
-};
-
-function transportFor(spec: McpTransport): Transport {
-  switch (spec.type) {
-    case "stdio":
-      return new StdioClientTransport({
-        command: spec.command,
-        args: spec.args,
-        env: spec.env,
-        cwd: spec.cwd,
-        stderr: "ignore",
-      });
-    case "streamable-http": {
-      const headers = spec.headers;
-      return new StreamableHTTPClientTransport(new URL(spec.url), {
-        requestInit: headers ? { headers } : undefined,
-      });
-    }
-    case "sse": {
-      const headers = spec.headers;
-      return new SSEClientTransport(new URL(spec.url), {
-        requestInit: headers ? { headers } : undefined,
-      });
-    }
-    default: {
-      const _exhaustive: never = spec;
-      return _exhaustive;
-    }
-  }
-}
-
-function readPathValue(
-  value: unknown,
-  path: string | undefined,
-): string | undefined {
-  const key = path?.trim();
-  if (!key) {
-    return undefined;
-  }
-
-  const current = get(value, key);
-  if (typeof current !== "string") {
-    return undefined;
-  }
-
-  const trimmed = current.trim();
-  return trimmed.length > 0 ? trimmed : undefined;
-}
-
-function readIdentityPath(
-  experimental: unknown,
-  key: "hooman/user" | "hooman/session" | "hooman/thread",
-): string | undefined {
-  const path = get(experimental, [key, "path"]);
-  return typeof path === "string" && path.trim().length > 0
-    ? path.trim()
-    : undefined;
-}
-
-function readSourceValue(value: unknown): string | undefined {
-  return readPathValue(value, "meta.source");
-}
-
-function readAttachmentsFromParams(params: unknown): string[] {
-  if (!params || typeof params !== "object") {
-    return [];
-  }
-  const topLevel = (params as { attachments?: unknown }).attachments;
-  return normalizeAttachmentPaths(topLevel);
-}
-
-/**
- * Holds one {@link McpClient} per named entry in {@link Config}. Call {@link reload}
- * after changing the file on disk (or construct and then {@link reload} once).
- */
-export class Manager {
-  private instances: Map<string, McpClient> | null = null;
-  private readonly permissions = new Map<
-    string,
-    {
-      resolve: (behavior: ChannelPermissionBehavior) => void;
-      reject: (reason: Error) => void;
-      timer: ReturnType<typeof setTimeout>;
-    }
-  >();
-
-  public constructor(
-    private readonly config: Config,
-    private readonly acp = false,
-    private readonly servers: readonly NamedMcpTransport[] = [],
-  ) {}
-
-  /** Lazily builds clients from the current in-memory config (reloads file first). */
-  get clients(): ReadonlyMap<string, McpClient> {
-    if (this.instances === null) {
-      this.reload();
-    }
-    return this.instances!;
-  }
-
-  /**
-   * Rereads the config file, replaces all clients, and best-effort disconnects
-   * previous clients (stdio subprocesses, HTTP sessions).
-   */
-  public reload(): void {
-    if (!this.acp) {
-      this.config.reload();
-    }
-    const previous = this.instances;
-    const next = new Map<string, McpClient>();
-    const transports = [
-      ...(this.acp ? [] : this.config.list()),
-      // Session-scoped servers override local config entries on name conflicts.
-      ...this.servers,
-    ];
-    for (const { name, transport } of transports) {
-      next.set(
-        name,
-        new McpClient({
-          transport: transportFor(transport),
-        }),
-      );
-    }
-    this.instances = next;
-    if (previous?.size) {
-      for (const client of previous.values()) {
-        void client.disconnect().catch(() => {});
-      }
-    }
-  }
-
-  public async disconnect(): Promise<void> {
-    for (const [key, pending] of this.permissions.entries()) {
-      clearTimeout(pending.timer);
-      pending.reject(new Error(`Pending permission "${key}" cancelled.`));
-    }
-    this.permissions.clear();
-    const toClose = this.instances;
-    this.instances = null;
-    if (!toClose?.size) {
-      return;
-    }
-    await Promise.all(
-      [...toClose.values()].map((c) => c.disconnect().catch(() => undefined)),
-    );
-  }
-
-  /**
-   * Lists tools from every configured MCP client with names prefixed by a
-   * slugified server config key (see {@link PrefixedMcpTool}).
-   */
-  public async listPrefixedTools(): Promise<Tool[]> {
-    if (this.instances === null) {
-      this.reload();
-    }
-    const map = this.instances!;
-    const batches = await Promise.all(
-      [...map.entries()].map(async ([server, client]) =>
-        client
-          .listTools()
-          .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<ChannelSubscriptionHandle> {
-    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 { unsubscribe: () => {}, subscriptions: [] };
-    }
-
-    const unsubs: Array<() => void> = [];
-    const subscriptions: ChannelSubscription[] = [];
-    for (const [server, client] of map.entries()) {
-      await client.connect();
-      const experimental =
-        client.client.getServerCapabilities()?.experimental ?? {};
-      const user = readIdentityPath(experimental, "hooman/user");
-      const session = readIdentityPath(experimental, "hooman/session");
-      const thread = readIdentityPath(experimental, "hooman/thread");
-      const supportsPermission =
-        Boolean(get(experimental, [HOOMAN_CHANNEL_PERMISSION])) &&
-        typeof (client.client as { setNotificationHandler?: unknown })
-          .setNotificationHandler === "function";
-
-      if (supportsPermission) {
-        const schema = z.object({
-          method: z.literal(HOOMAN_CHANNEL_PERMISSION_METHOD),
-          params: z.object({
-            request_id: z.string().min(1),
-            behavior: z.enum(["allow_once", "allow_always", "deny"]),
-          }),
-        });
-        const handler = (notification: {
-          params?: {
-            request_id?: string;
-            behavior?: ChannelPermissionBehavior;
-          };
-        }) => {
-          const requestId = notification.params?.request_id?.trim();
-          const behavior = notification.params?.behavior;
-          if (!requestId || !behavior) {
-            return;
-          }
-          const key = `${server}:${requestId}`;
-          const pending = this.permissions.get(key);
-          if (!pending) {
-            return;
-          }
-          this.permissions.delete(key);
-          clearTimeout(pending.timer);
-          pending.resolve(behavior);
-        };
-        client.client.setNotificationHandler(schema, handler);
-        unsubs.push(() => {
-          client.client.setNotificationHandler(schema, () => {});
-        });
-      }
-
-      for (const channel of requested) {
-        if (!Object.hasOwn(experimental, channel)) {
-          continue;
-        }
-
-        subscriptions.push({ server, channel });
-
-        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(params);
-          if (!prompt) {
-            return;
-          }
-          const attachments = readAttachmentsFromParams(params);
-
-          onMessage({
-            prompt,
-            attachments,
-            meta: {
-              subscription: { server, channel },
-              source: readSourceValue(params),
-              user: readPathValue(params, user),
-              session: readPathValue(params, session),
-              thread: readPathValue(params, thread),
-            },
-          });
-        };
-        client.client.setNotificationHandler(schema, handler);
-        unsubs.push(() => {
-          client.client.setNotificationHandler(schema, () => {});
-        });
-      }
-    }
-
-    return {
-      subscriptions,
-      unsubscribe: () => {
-        for (const off of unsubs) {
-          off();
-        }
-      },
-    };
-  }
-
-  public async supportsChannelPermission(server: string): Promise<boolean> {
-    if (this.instances === null) {
-      this.reload();
-    }
-    const client = this.instances!.get(server);
-    if (!client) {
-      return false;
-    }
-    await client.connect();
-    const experimental =
-      client.client.getServerCapabilities()?.experimental ?? {};
-    return Boolean(get(experimental, [HOOMAN_CHANNEL_PERMISSION]));
-  }
-
-  public async requestChannelPermission(
-    server: string,
-    request: ChannelPermissionRequest,
-    timeoutMs = 120_000,
-  ): Promise<ChannelPermissionBehavior> {
-    if (this.instances === null) {
-      this.reload();
-    }
-    const client = this.instances!.get(server);
-    if (!client) {
-      throw new Error(`MCP server "${server}" is not connected.`);
-    }
-    await client.connect();
-    const experimental =
-      client.client.getServerCapabilities()?.experimental ?? {};
-    if (!Object.hasOwn(experimental, HOOMAN_CHANNEL_PERMISSION)) {
-      throw new Error(
-        `MCP server "${server}" does not support ${HOOMAN_CHANNEL_PERMISSION}.`,
-      );
-    }
-
-    const requestId = request.requestId.trim();
-    if (!requestId) {
-      throw new Error("requestId is required.");
-    }
-    const key = `${server}:${requestId}`;
-    if (this.permissions.has(key)) {
-      throw new Error(`Permission request "${requestId}" is already pending.`);
-    }
-
-    const response = new Promise<ChannelPermissionBehavior>(
-      (resolve, reject) => {
-        const timer = setTimeout(() => {
-          this.permissions.delete(key);
-          reject(
-            new Error(
-              `Permission request "${requestId}" timed out after ${timeoutMs}ms.`,
-            ),
-          );
-        }, timeoutMs);
-        this.permissions.set(key, { resolve, reject, timer });
-      },
-    );
-
-    try {
-      const sender = client.client as {
-        notification?: (payload: unknown) => Promise<void>;
-      };
-      if (typeof sender.notification !== "function") {
-        throw new Error(
-          `MCP client for "${server}" cannot send notifications.`,
-        );
-      }
-      await sender.notification({
-        method: "notifications/hooman/channel/permission_request",
-        params: {
-          request_id: requestId,
-          tool_name: request.tool,
-          description: request.description,
-          input_preview: request.preview,
-          options: [
-            { id: "allow_once", label: "Allow once" },
-            { id: "allow_always", label: "Always allow" },
-            { id: "deny", label: "Deny" },
-          ],
-          meta: {
-            ...(request.source ? { source: request.source } : {}),
-            ...(request.user ? { user: request.user } : {}),
-            ...(request.session ? { session: request.session } : {}),
-            ...(request.thread ? { thread: request.thread } : {}),
-          },
-        },
-      });
-      return await response;
-    } catch (error) {
-      const pending = this.permissions.get(key);
-      if (pending) {
-        clearTimeout(pending.timer);
-        this.permissions.delete(key);
-      }
-      throw error;
-    }
-  }
-
-  private toChannelPrompt(params?: unknown): string {
-    const parts = [];
-
-    if (
-      params &&
-      typeof params === "object" &&
-      "content" in params &&
-      typeof params.content === "string"
-    ) {
-      parts.push(params.content.trim());
-    }
-
-    if (
-      params &&
-      typeof params === "object" &&
-      "attachments" in params &&
-      Array.isArray(params.attachments) &&
-      params.attachments.length > 0
-    ) {
-      parts.push("User sent attachments.");
-    }
-
-    if (
-      params &&
-      typeof params === "object" &&
-      "event" in params &&
-      typeof params.event === "object"
-    ) {
-      parts.push(
-        "Raw event data:\n```json\n" + JSON.stringify(params.event) + "\n```",
-      );
-    }
-
-    return parts.filter(Boolean).join("\n").trim();
-  }
-}

package/src/core/mcp/prefixed-mcp-tool.ts

@@ -1,45 +0,0 @@
-import {
-  Tool,
-  type ToolContext,
-  type ToolSpec,
-  type ToolStreamGenerator,
-} from "@strands-agents/sdk";
-import slugify from "slugify";
-
-function mcpServerPrefix(serverKey: string): string {
-  const slug = slugify(serverKey, {
-    replacement: "_",
-    lower: true,
-    strict: true,
-  });
-  return slug.length > 0 ? slug : "mcp";
-}
-
-/**
- * Exposes MCP server tools to the model as `slugifiedServerKey__originalName`
- * while delegating execution to the stock SDK tool (correct wire name).
- */
-export class PrefixedMcpTool extends Tool {
-  name: string;
-  description: string;
-  toolSpec: ToolSpec;
-
-  public constructor(
-    private readonly serverKey: string,
-    private readonly inner: Tool,
-  ) {
-    super();
-    const prefix = mcpServerPrefix(serverKey);
-    this.name = `${prefix}__${inner.name}`;
-    this.description = `${inner.description} (MCP server: ${serverKey})`;
-    this.toolSpec = {
-      ...inner.toolSpec,
-      name: this.name,
-      description: this.description,
-    };
-  }
-
-  stream(toolContext: ToolContext): ToolStreamGenerator {
-    return this.inner.stream(toolContext);
-  }
-}

package/src/core/mcp/tools.ts

@@ -1,92 +0,0 @@
-import { tool } from "@strands-agents/sdk";
-import type { JSONValue } from "@strands-agents/sdk";
-import { z } from "zod";
-import type { Config } from "./config.ts";
-import { McpTransportSchema } from "./types.ts";
-
-function toJsonValue(value: unknown): JSONValue {
-  return JSON.parse(JSON.stringify(value)) as JSONValue;
-}
-
-const NamedTransportSchema = z.object({
-  name: z.string().min(1).describe("Unique MCP server name."),
-  transport: McpTransportSchema.describe(
-    "Transport configuration for the MCP server.",
-  ),
-});
-
-export function createMcpTools(config: Config) {
-  return [
-    tool({
-      name: "list_mcp_servers",
-      description:
-        "List configured MCP servers from the local MCP config file.",
-      inputSchema: z.object({}),
-      callback: async () => {
-        const servers = config.list();
-        return toJsonValue({
-          count: servers.length,
-          servers,
-        });
-      },
-    }),
-    tool({
-      name: "get_mcp_server",
-      description: "Get a configured MCP server by name.",
-      inputSchema: z.object({
-        name: z.string().min(1).describe("MCP server name."),
-      }),
-      callback: async (input) => {
-        const transport = config.get(input.name);
-        return toJsonValue({
-          name: input.name,
-          found: transport !== undefined,
-          transport: transport ?? null,
-        });
-      },
-    }),
-    tool({
-      name: "add_mcp_server",
-      description:
-        "Add a new MCP server configuration to the local MCP config file.",
-      inputSchema: NamedTransportSchema,
-      callback: async (input) => {
-        config.add(input.name, input.transport);
-        return toJsonValue({
-          added: true,
-          name: input.name,
-          transport: input.transport,
-        });
-      },
-    }),
-    tool({
-      name: "update_mcp_server",
-      description:
-        "Update an existing MCP server configuration in the local MCP config file.",
-      inputSchema: NamedTransportSchema,
-      callback: async (input) => {
-        config.update(input.name, input.transport);
-        return toJsonValue({
-          updated: true,
-          name: input.name,
-          transport: input.transport,
-        });
-      },
-    }),
-    tool({
-      name: "delete_mcp_server",
-      description:
-        "Delete an MCP server configuration from the local MCP config file.",
-      inputSchema: z.object({
-        name: z.string().min(1).describe("MCP server name to remove."),
-      }),
-      callback: async (input) => {
-        config.remove(input.name);
-        return toJsonValue({
-          deleted: true,
-          name: input.name,
-        });
-      },
-    }),
-  ];
-}

package/src/core/mcp/types.ts

@@ -1,37 +0,0 @@
-import { z } from "zod";
-
-const headersOrEnvVarsSchema = z.record(z.string(), z.string()).optional();
-
-/** MCP stdio server: subprocess with JSON-RPC over stdin/stdout. */
-export const StdioSchema = z.object({
-  type: z.literal("stdio"),
-  command: z.string().min(1),
-  args: z.array(z.string()).optional(),
-  env: headersOrEnvVarsSchema,
-  cwd: z.string().optional(),
-});
-
-/** MCP remote server over streamable HTTP (preferred over legacy SSE). */
-export const StreamableHttpSchema = z.object({
-  type: z.literal("streamable-http"),
-  url: z.url(),
-  headers: headersOrEnvVarsSchema,
-});
-
-/** MCP remote server over SSE + POST messages (legacy transport). */
-export const SseSchema = z.object({
-  type: z.literal("sse"),
-  url: z.url(),
-  headers: headersOrEnvVarsSchema,
-});
-
-export const McpTransportSchema = z.discriminatedUnion("type", [
-  StdioSchema,
-  StreamableHttpSchema,
-  SseSchema,
-]);
-
-export type Stdio = z.infer<typeof StdioSchema>;
-export type StreamableHttp = z.infer<typeof StreamableHttpSchema>;
-export type Sse = z.infer<typeof SseSchema>;
-export type McpTransport = z.infer<typeof McpTransportSchema>;

package/src/core/memory/index.ts

@@ -1,17 +0,0 @@
-export { create as createShortTermMemory } from "./stm";
-export {
-  createLongTermMemoryStore,
-  createLongTermMemoryTools,
-  LongTermMemoryStore,
-} from "./ltm";
-export type {
-  ArchiveMemoryInput,
-  LongTermMemoryOptions,
-  LongTermMemoryScope,
-  MemorySource,
-  SearchMemoryInput,
-  SearchMemoryResult,
-  StoreMemoryInput,
-  StoreMemoryResult,
-  UpdateMemoryInput,
-} from "./ltm";