hoomanjs 1.0.0

package/src/core/config.ts

@@ -0,0 +1,157 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { z } from "zod";
+
+/** LLM backend; extend as you add providers. */
+export enum LlmProvider {
+  Anthropic = "anthropic",
+  Google = "google",
+  OpenAI = "openai",
+  Ollama = "ollama",
+  Bedrock = "bedrock",
+}
+
+const LlmSchema = z.object({
+  provider: z.nativeEnum(LlmProvider),
+  model: z.string().min(1),
+  params: z.record(z.string(), z.any()).default({}),
+});
+
+/** Partial compaction overrides from JSON; missing fields use defaults below. */
+const CompactionPartialSchema = z.object({
+  /** Fraction of context to target after compaction (e.g. 0.75 = keep ~75% budget). */
+  ratio: z.number().min(0).max(1).optional(),
+  /** Minimum number of recent turns / message groups to preserve verbatim when compacting. */
+  keep: z.number().int().nonnegative().optional(),
+});
+
+const DEFAULT_COMPACTION = { ratio: 0.75, keep: 5 } as const;
+
+const DEFAULT_CHROMA = {
+  url: "http://127.0.0.1:8000",
+  collection: { memory: "memory" },
+} as const;
+
+const ChromaPartialSchema = z.object({
+  url: z.string().min(1).optional(),
+  collection: z
+    .object({
+      memory: z.string().min(1).optional(),
+    })
+    .optional(),
+});
+
+const LtmPartialSchema = z.object({
+  enabled: z.boolean().optional(),
+  chroma: ChromaPartialSchema.optional(),
+});
+
+const ToolsPartialSchema = z.object({
+  allowed: z.array(z.string().min(1)).default([]),
+});
+
+const ConfigSchema = z.object({
+  name: z.string().min(1),
+  llm: LlmSchema,
+  tools: ToolsPartialSchema.default({ allowed: [] }),
+  ltm: LtmPartialSchema.nullish().transform((ltm) => ({
+    enabled: ltm?.enabled ?? false,
+    chroma: {
+      url: ltm?.chroma?.url ?? DEFAULT_CHROMA.url,
+      collection: {
+        memory:
+          ltm?.chroma?.collection?.memory ?? DEFAULT_CHROMA.collection.memory,
+      },
+    },
+  })),
+  compaction: CompactionPartialSchema.nullish().transform((c) => ({
+    ratio: c?.ratio ?? DEFAULT_COMPACTION.ratio,
+    keep: c?.keep ?? DEFAULT_COMPACTION.keep,
+  })),
+});
+
+export type ConfigData = z.infer<typeof ConfigSchema>;
+export type LlmConfig = z.infer<typeof LlmSchema>;
+export type CompactionConfig = ConfigData["compaction"];
+export type LtmConfig = ConfigData["ltm"];
+export type ToolsConfig = ConfigData["tools"];
+
+const defaultConfigData = (): ConfigData => ({
+  name: "Hooman",
+  llm: {
+    provider: LlmProvider.Ollama,
+    model: "gemma4:e4b",
+    params: {},
+  },
+  tools: {
+    allowed: [],
+  },
+  ltm: {
+    enabled: false,
+    chroma: {
+      url: "http://127.0.0.1:8000",
+      collection: { memory: "memory" },
+    },
+  },
+  compaction: {
+    ratio: 0.75,
+    keep: 5,
+  },
+});
+
+export class Config {
+  private data!: ConfigData;
+  private readonly path: string;
+
+  public constructor(path: string) {
+    this.path = path;
+    this.reload();
+  }
+
+  get name(): string {
+    return this.data.name;
+  }
+
+  get llm(): LlmConfig {
+    return this.data.llm;
+  }
+
+  get tools(): ToolsConfig {
+    return {
+      ...this.data.tools,
+      allowed: [...this.data.tools.allowed],
+    };
+  }
+
+  get compaction(): CompactionConfig {
+    return this.data.compaction;
+  }
+
+  get ltm(): LtmConfig {
+    return this.data.ltm;
+  }
+
+  private readJson(): unknown {
+    if (!existsSync(this.path)) {
+      return defaultConfigData();
+    }
+    return JSON.parse(readFileSync(this.path, "utf8"));
+  }
+
+  public reload(): void {
+    const wasMissing = !existsSync(this.path);
+    this.data = ConfigSchema.parse(this.readJson());
+    if (wasMissing) {
+      this.persist();
+    }
+  }
+
+  public persist(): void {
+    writeFileSync(this.path, JSON.stringify(this.data, null, 2), "utf8");
+  }
+
+  public update(partial: Partial<ConfigData>): void {
+    const updated = { ...this.data, ...partial };
+    this.data = ConfigSchema.parse(updated);
+    this.persist();
+  }
+}

package/src/core/index.ts

@@ -0,0 +1,54 @@
+import type { Agent } from "@strands-agents/sdk";
+import { Config } from "./config.ts";
+import { create as createAgent } from "./agent/index.ts";
+import {
+  createMcpConfig,
+  createMcpManager,
+  type Config as McpServersConfig,
+  type Manager as McpConnectionManager,
+} from "./mcp/index.ts";
+import { createSkillsRegistry } from "./skills/index.ts";
+import type { Registry } from "./skills/index.ts";
+import { system as createSystemPrompt } from "./prompts/index.ts";
+import type { Toolkit } from "./toolkit.ts";
+import {
+  basePath,
+  configJsonPath,
+  instructionsMdPath,
+  mcpJsonPath,
+} from "./utils/paths.ts";
+
+export async function bootstrap(
+  meta: {
+    userId?: string;
+    sessionId: string;
+    systemPrompt?: string;
+    toolkit?: Toolkit;
+  },
+  print: boolean = false,
+): Promise<{
+  config: Config;
+  agent: Agent;
+  mcp: { config: McpServersConfig; manager: McpConnectionManager };
+  registry: Registry;
+}> {
+  const config = new Config(configJsonPath());
+  const mcpConfig = createMcpConfig(mcpJsonPath());
+  const mcpManager = createMcpManager(mcpConfig);
+  const mcp = { config: mcpConfig, manager: mcpManager };
+  const registry = createSkillsRegistry(basePath());
+  const toolkit = meta.toolkit ?? "max";
+  const system = await createSystemPrompt(
+    instructionsMdPath(),
+    config,
+    toolkit,
+  );
+  const sessionId = meta?.sessionId ?? crypto.randomUUID();
+  const agent = await createAgent(config, system, registry, mcp, print, {
+    userId: meta?.userId ?? sessionId,
+    sessionId,
+    systemPrompt: meta?.systemPrompt,
+    toolkit,
+  });
+  return { config, agent, mcp, registry };
+}

package/src/core/mcp/config.ts

@@ -0,0 +1,80 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { z } from "zod";
+import { McpTransportSchema, type McpTransport } from "./types.ts";
+
+const McpServersFileSchema = z.object({
+  mcpServers: z.record(z.string().min(1), McpTransportSchema).default({}),
+});
+
+export type McpServersFile = z.infer<typeof McpServersFileSchema>;
+
+/** One named MCP transport from the config file. */
+export type NamedMcpTransport = { name: string; transport: McpTransport };
+
+/**
+ * Read/write `{"mcpServers": { "<name>": <transport> }}` on disk.
+ */
+export class Config {
+  private readonly path: string;
+  private servers: Record<string, McpTransport>;
+
+  public constructor(path: string) {
+    this.path = path;
+    this.servers = {};
+    this.reload();
+  }
+
+  private readJson(): McpServersFile {
+    if (!existsSync(this.path)) {
+      return { mcpServers: {} };
+    }
+    const raw = readFileSync(this.path, "utf8");
+    return JSON.parse(raw) as McpServersFile;
+  }
+
+  /** Reload servers from disk (overwrites unsaved in-memory changes). */
+  public reload(): void {
+    const parsed = McpServersFileSchema.parse(this.readJson());
+    this.servers = { ...parsed.mcpServers };
+  }
+
+  private persist(): void {
+    const payload: McpServersFile = { mcpServers: { ...this.servers } };
+    writeFileSync(this.path, JSON.stringify(payload, null, 2), "utf8");
+  }
+
+  /** All configured servers, stable sort by name. */
+  public list(): NamedMcpTransport[] {
+    return Object.entries(this.servers)
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([name, transport]) => ({ name, transport }));
+  }
+
+  public get(name: string): McpTransport | undefined {
+    return this.servers[name];
+  }
+
+  public add(name: string, transport: McpTransport): void {
+    if (Object.hasOwn(this.servers, name)) {
+      throw new Error(`MCP server "${name}" already exists`);
+    }
+    this.servers[name] = transport;
+    this.persist();
+  }
+
+  public update(name: string, transport: McpTransport): void {
+    if (!Object.hasOwn(this.servers, name)) {
+      throw new Error(`MCP server "${name}" not found`);
+    }
+    this.servers[name] = transport;
+    this.persist();
+  }
+
+  public remove(name: string): void {
+    if (!Object.hasOwn(this.servers, name)) {
+      throw new Error(`MCP server "${name}" not found`);
+    }
+    delete this.servers[name];
+    this.persist();
+  }
+}

package/src/core/mcp/index.ts

@@ -0,0 +1,13 @@
+import { Config } from "./config.ts";
+import { Manager } from "./manager.ts";
+
+export { Config, Manager };
+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);
+}

package/src/core/mcp/manager.ts

@@ -0,0 +1,109 @@
+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 { Config } from "./config.ts";
+import type { McpTransport } from "./types.ts";
+
+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;
+    }
+  }
+}
+
+/**
+ * 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;
+
+  public constructor(private readonly config: Config) {}
+
+  /** 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 {
+    this.config.reload();
+    const previous = this.instances;
+    const next = new Map<string, McpClient>();
+    for (const { name, transport } of this.config.list()) {
+      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> {
+    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 ([serverKey, client]) =>
+        client
+          .listTools()
+          .then((tools) => tools.map((t) => new PrefixedMcpTool(serverKey, t))),
+      ),
+    );
+    return batches.flat();
+  }
+}

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

@@ -0,0 +1,45 @@
+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

@@ -0,0 +1,92 @@
+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

@@ -0,0 +1,37 @@
+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

@@ -0,0 +1,17 @@
+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";

package/src/core/memory/ltm/embed.ts

@@ -0,0 +1,67 @@
+import { pipeline } from "@huggingface/transformers";
+import type { FeatureExtractionPipeline } from "@huggingface/transformers";
+import type { EmbeddingFunction } from "chromadb";
+
+const DEFAULT_MODEL =
+  process.env.HF_EMBEDDING_MODEL ?? "Xenova/bge-small-en-v1.5";
+
+/**
+ * Chroma {@link EmbeddingFunction} backed by `@huggingface/transformers`
+ * `feature-extraction` (mean-pooled, L2-normalized sentence embeddings).
+ *
+ * The pipeline is loaded lazily on first {@link HFEmbedding.generate} call so
+ * constructors stay synchronous and startup stays fast.
+ */
+export class HFEmbedding implements EmbeddingFunction {
+  private readonly modelId: string;
+  private pipePromise: Promise<FeatureExtractionPipeline> | null = null;
+
+  constructor(modelId: string = DEFAULT_MODEL) {
+    this.modelId = modelId;
+  }
+
+  get name(): string {
+    return `hf-transformers:${this.modelId}`;
+  }
+
+  private async getPipeline(): Promise<FeatureExtractionPipeline> {
+    if (!this.pipePromise) {
+      this.pipePromise = pipeline(
+        "feature-extraction",
+        this.modelId,
+      ) as Promise<FeatureExtractionPipeline>;
+    }
+    return this.pipePromise;
+  }
+
+  async generate(texts: string[]): Promise<number[][]> {
+    if (texts.length === 0) {
+      return [];
+    }
+    const pipe = await this.getPipeline();
+    const tensor = await pipe(texts, {
+      pooling: "mean",
+      normalize: true,
+    });
+    const raw = tensor.tolist() as unknown;
+
+    if (texts.length === 1) {
+      if (Array.isArray(raw) && raw.every((x) => typeof x === "number")) {
+        return [raw as number[]];
+      }
+    }
+
+    if (
+      Array.isArray(raw) &&
+      raw.length > 0 &&
+      Array.isArray(raw[0]) &&
+      (raw[0] as unknown[]).every((x) => typeof x === "number")
+    ) {
+      return raw as number[][];
+    }
+
+    throw new Error(
+      "Unexpected embedding tensor shape from feature-extraction pipeline",
+    );
+  }
+}

package/src/core/memory/ltm/index.ts

@@ -0,0 +1,18 @@
+export {
+  LongTermMemoryStore,
+  create as createLongTermMemoryStore,
+} from "./store.ts";
+
+export { create as createLongTermMemoryTools } from "./tools.ts";
+
+export type {
+  ArchiveMemoryInput,
+  LongTermMemoryOptions,
+  LongTermMemoryScope,
+  MemorySource,
+  SearchMemoryInput,
+  SearchMemoryResult,
+  StoreMemoryInput,
+  StoreMemoryResult,
+  UpdateMemoryInput,
+} from "./types.ts";