hoomanjs 1.4.0 → 1.6.0

package/README.md

@@ -26,7 +26,7 @@ It gives you:
 
 ## Features
 
-- Multiple LLM providers: `ollama`, `openai`, `anthropic`, `google`, `bedrock`, `xai`
+- Multiple LLM providers: `ollama`, `openai`, `anthropic`, `google`, `bedrock`, `groq`, `xai`
 - 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
@@ -262,6 +262,7 @@ Supported `llm.provider` values:
 - `anthropic`
 - `google`
 - `bedrock`
+- `groq`
 - `xai`
 
 ## Provider Notes
@@ -329,6 +330,21 @@ Uses Strands `GoogleModel` on top of `@google/genai`. Top-level options like `ap
 
 Supports `region`, `clientConfig`, and optional `apiKey`, with all other values forwarded as Bedrock model options.
 
+### Groq
+
+Uses the Vercel AI SDK Groq provider (`@ai-sdk/groq`) on top of Strands `VercelModel`. Provider-specific settings `apiKey`, `baseURL`, and `headers` are picked up; other values are forwarded into the model config (`temperature`, `maxTokens`, etc.). Defaults to `GROQ_API_KEY` from the environment when no `apiKey` is supplied.
+
+```json
+{
+  "provider": "groq",
+  "model": "gemma2-9b-it",
+  "params": {
+    "apiKey": "...",
+    "temperature": 0.7
+  }
+}
+```
+
 ### xAI
 
 Uses the Vercel AI SDK xAI provider (`@ai-sdk/xai`) on top of Strands `VercelModel`. Provider-specific settings `apiKey`, `baseURL`, and `headers` are picked up; other values are forwarded into the model config (`temperature`, `maxTokens`, etc.). Defaults to `XAI_API_KEY` from the environment when no `apiKey` is supplied.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hoomanjs",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "Bun-powered local AI agent CLI with chat, exec, ACP, MCP, and skills support.",
   "author": {
     "name": "Vaibhav Pandey",
@@ -51,6 +51,7 @@
   "dependencies": {
     "@agentclientprotocol/sdk": "^0.18.2",
     "@ai-sdk/anthropic": "^3.0.69",
+    "@ai-sdk/groq": "^3.0.35",
     "@ai-sdk/xai": "^3.0.83",
     "@aws-sdk/client-bedrock-runtime": "^3.1028.0",
     "@google/genai": "^1.40.0",

package/src/cli.ts

@@ -146,20 +146,27 @@ program
       channel?: string[];
       debug?: boolean;
     }) => {
-      const sessionId = options.session?.trim() || crypto.randomUUID();
+      const session = options.session?.trim();
       const channels = options.channel ?? [];
       const {
         agent,
         mcp: { manager },
       } = await bootstrap(
-        { sessionId, toolkit: options.toolkit ?? "full" },
+        {
+          sessionId: session,
+          userId: session,
+          toolkit: options.toolkit ?? "full",
+        },
         true,
       );
+      // Daemon mode is non-interactive: approve tool calls by default.
+      agent.addHook(BeforeToolCallEvent, async () => {});
       try {
         await daemon({
           agent,
           manager,
           channels,
+          session,
           debug: Boolean(options.debug),
         });
       } finally {

package/src/core/agent/index.ts

@@ -35,7 +35,7 @@ export async function create(
   print: boolean = false,
   meta: {
     userId?: string;
-    sessionId: string;
+    sessionId?: string;
     systemPrompt?: string;
     toolkit?: Toolkit;
   },
@@ -57,8 +57,8 @@ export async function create(
     systemPrompt: prompt,
     model: llm.create(config.llm.model, config.llm.params),
     appState: {
-      userId,
-      sessionId,
+      ...(userId ? { userId } : {}),
+      ...(sessionId ? { sessionId } : {}),
     },
     tools: [
       ...createTimeTools(),

package/src/core/config.ts

@@ -5,6 +5,7 @@ import { z } from "zod";
 export enum LlmProvider {
   Anthropic = "anthropic",
   Google = "google",
+  Groq = "groq",
   OpenAI = "openai",
   Ollama = "ollama",
   Bedrock = "bedrock",

package/src/core/index.ts

@@ -22,7 +22,7 @@ import {
 export async function bootstrap(
   meta: {
     userId?: string;
-    sessionId: string;
+    sessionId?: string;
     systemPrompt?: string;
     mcpServers?: NamedMcpTransport[];
     toolkit?: Toolkit;
@@ -45,10 +45,9 @@ export async function bootstrap(
     config,
     toolkit,
   );
-  const sessionId = meta?.sessionId ?? crypto.randomUUID();
   const agent = await createAgent(config, system, registry, mcp, print, {
-    userId: meta?.userId ?? sessionId,
-    sessionId,
+    userId: meta?.userId ?? meta?.sessionId,
+    sessionId: meta?.sessionId,
     systemPrompt: meta?.systemPrompt,
     toolkit,
   });

package/src/core/mcp/manager.ts

@@ -4,6 +4,7 @@ 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";
@@ -13,6 +14,10 @@ export type ChannelMessageMeta = {
   channel: string;
   method: string;
   params: unknown;
+  identity: {
+    user?: string;
+    session?: string;
+  };
 };
 
 export type ChannelMessage = {
@@ -49,6 +54,34 @@ function transportFor(spec: McpTransport): Transport {
   }
 }
 
+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: "identity/user" | "identity/session",
+): string | undefined {
+  const path = get(experimental, [key, "path"]);
+  return typeof path === "string" && path.trim().length > 0
+    ? path.trim()
+    : undefined;
+}
+
 /**
  * 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).
@@ -173,6 +206,8 @@ export class Manager {
       await client.connect();
       const experimental =
         client.client.getServerCapabilities()?.experimental ?? {};
+      const user = readIdentityPath(experimental, "identity/user");
+      const session = readIdentityPath(experimental, "identity/session");
       for (const channel of requested) {
         if (!Object.hasOwn(experimental, channel)) {
           continue;
@@ -200,6 +235,10 @@ export class Manager {
               channel,
               method,
               params,
+              identity: {
+                user: readPathValue(params, user),
+                session: readPathValue(params, session),
+              },
             },
           });
         };

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

@@ -1,17 +1,32 @@
-import { Agent, SummarizingConversationManager } from "@strands-agents/sdk";
-import { SessionManager, FileStorage } from "@strands-agents/sdk";
+import {
+  FileStorage,
+  SessionManager,
+  SummarizingConversationManager,
+} from "@strands-agents/sdk";
 import { sessionsPath } from "../../utils/paths";
+import { LazySessionManager } from "./lazy-session-manager";
 
-export function create(sessionId: string) {
-  const sessionManager = new SessionManager({
-    sessionId,
-    storage: { snapshot: new FileStorage(sessionsPath()) },
-  });
-
+export function create(sessionId?: string) {
   const conversationManager = new SummarizingConversationManager({
     summaryRatio: 0.5,
     preserveRecentMessages: 5,
   });
+  const storage = new FileStorage(sessionsPath());
+
+  if (!sessionId) {
+    return {
+      plugins: [new LazySessionManager({ storage })],
+      conversationManager,
+    };
+  }
+
+  const sessionManager = new SessionManager({
+    sessionId,
+    storage: { snapshot: storage },
+  });
 
   return { sessionManager, conversationManager };
 }
+
+export { LazySessionManager } from "./lazy-session-manager";
+export type { LazySessionManagerConfig } from "./lazy-session-manager";

package/src/core/memory/stm/lazy-session-manager.ts

@@ -0,0 +1,122 @@
+import {
+  AfterInvocationEvent,
+  BeforeInvocationEvent,
+  Message,
+  type LocalAgent,
+  type MessageData,
+  type Plugin,
+  type Snapshot,
+  type SnapshotLocation,
+  type SnapshotStorage,
+} from "@strands-agents/sdk";
+
+const DEFAULT_SESSION_ID = "default-session";
+const DEFAULT_APP_STATE_KEY = "sessionId";
+const DEFAULT_SCOPE_ID = "agent";
+const SCHEMA_VERSION = "1.0";
+// `FileStorage` (and any backend that follows its convention) validates ids
+// against `[a-z0-9_-]+`, so coerce anything else (e.g. `919599960600@c.us`).
+const UNSAFE_CHARS = /[^a-z0-9_-]+/g;
+
+export type LazySessionManagerConfig = {
+  /** Pluggable snapshot backend (e.g. `FileStorage`). */
+  storage: SnapshotStorage;
+  /** Fallback session id when `appState` does not provide one. Defaults to `"default-session"`. */
+  defaultSessionId?: string;
+  /** `appState` key used to derive the active session id. Defaults to `"sessionId"`. */
+  appStateKey?: string;
+  /** Scope id passed through to the storage backend. Defaults to `"agent"`. */
+  scopeId?: string;
+};
+
+/**
+ * Short-term memory plugin that resolves the active session id at invocation
+ * time from `agent.appState` instead of binding it once at construction.
+ *
+ * Designed for long-lived agents that fan out to many independent
+ * conversations (e.g. a daemon routing notifications from multiple chat
+ * channels). Persistence is delegated to a `SnapshotStorage` so any backend
+ * (filesystem, S3, custom) works.
+ */
+export class LazySessionManager implements Plugin {
+  private readonly storage: SnapshotStorage;
+  private readonly defaultSessionId: string;
+  private readonly appStateKey: string;
+  private readonly scopeId: string;
+
+  constructor(config: LazySessionManagerConfig) {
+    this.storage = config.storage;
+    this.defaultSessionId = sanitize(
+      config.defaultSessionId ?? DEFAULT_SESSION_ID,
+    );
+    this.appStateKey = config.appStateKey ?? DEFAULT_APP_STATE_KEY;
+    this.scopeId = sanitize(config.scopeId ?? DEFAULT_SCOPE_ID);
+  }
+
+  get name(): string {
+    return "hooman:lazy-session-manager";
+  }
+
+  initAgent(agent: LocalAgent): void {
+    agent.addHook(BeforeInvocationEvent, async (event) => {
+      await this.restore(event.agent);
+    });
+    agent.addHook(AfterInvocationEvent, async (event) => {
+      await this.save(event.agent);
+    });
+  }
+
+  /** Removes the persisted history for the given session, if present. */
+  async deleteSession(sessionId: string): Promise<void> {
+    await this.storage.deleteSession({ sessionId: sanitize(sessionId) });
+  }
+
+  private location(agent: LocalAgent): SnapshotLocation {
+    return {
+      sessionId: sanitize(this.resolveSessionId(agent)),
+      scope: "agent",
+      scopeId: this.scopeId,
+    };
+  }
+
+  private resolveSessionId(agent: LocalAgent): string {
+    const raw = agent.appState.get(this.appStateKey);
+    const candidate = typeof raw === "string" ? raw.trim() : "";
+    return candidate.length > 0 ? candidate : this.defaultSessionId;
+  }
+
+  private async restore(agent: LocalAgent): Promise<void> {
+    const snapshot = await this.storage.loadSnapshot({
+      location: this.location(agent),
+    });
+    agent.messages.length = 0;
+    if (!snapshot) return;
+    const raw = snapshot.data.messages;
+    if (!Array.isArray(raw)) return;
+    for (const md of raw as unknown as MessageData[]) {
+      agent.messages.push(Message.fromJSON(md));
+    }
+  }
+
+  private async save(agent: LocalAgent): Promise<void> {
+    const messages = agent.messages.map((m) => m.toJSON());
+    const snapshot: Snapshot = {
+      scope: "agent",
+      schemaVersion: SCHEMA_VERSION,
+      createdAt: new Date().toISOString(),
+      data: { messages: messages as unknown as Snapshot["data"]["messages"] },
+      appData: {},
+    };
+    await this.storage.saveSnapshot({
+      location: this.location(agent),
+      snapshotId: "latest",
+      isLatest: true,
+      snapshot,
+    });
+  }
+}
+
+function sanitize(value: string): string {
+  const trimmed = value.trim().toLowerCase().replace(UNSAFE_CHARS, "_");
+  return trimmed.length > 0 ? trimmed : DEFAULT_SESSION_ID;
+}

package/src/core/models/groq.ts

@@ -0,0 +1,48 @@
+import { createGroq, groq } from "@ai-sdk/groq";
+import { VercelModel } from "@strands-agents/sdk/models/vercel";
+import type { GroqProviderSettings } from "@ai-sdk/groq";
+import type { VercelModelConfig } from "@strands-agents/sdk/models/vercel";
+import { omit, pick } from "lodash";
+
+const PROVIDER_SETTINGS_KEYS = ["apiKey", "baseURL", "headers"] as const;
+
+function pickProviderSettings(
+  params: Record<string, unknown>,
+): GroqProviderSettings {
+  const picked = pick(params, [...PROVIDER_SETTINGS_KEYS]) as Record<
+    string,
+    unknown
+  >;
+  const unset = Object.keys(picked).filter((k) => picked[k] === undefined);
+  return omit(picked, unset) as GroqProviderSettings;
+}
+
+function pickVercelModelConfig(
+  params: Record<string, unknown>,
+): Partial<VercelModelConfig> {
+  return omit(params, [
+    ...PROVIDER_SETTINGS_KEYS,
+  ]) as Partial<VercelModelConfig>;
+}
+
+/**
+ * Groq via AI SDK + Strands {@link VercelModel}.
+ *
+ * - **`config.llm.model`**: model id passed to `groq(...)` (e.g. `gemma2-9b-it`).
+ * - **`params`**: {@link GroqProviderSettings} (`apiKey`, `baseURL`, `headers`).
+ *   If none are set, the default provider is used (`GROQ_API_KEY` from env).
+ * - Any other `params` keys are forwarded as {@link VercelModelConfig} (e.g. `temperature`, `maxTokens`).
+ */
+export function create(
+  model: string,
+  params: Record<string, unknown> = {},
+): VercelModel {
+  const settings = pickProviderSettings(params);
+  const provider =
+    Object.keys(settings).length > 0 ? createGroq(settings) : groq;
+  const config = pickVercelModelConfig(params);
+  return new VercelModel({
+    provider: provider(model),
+    ...config,
+  });
+}

package/src/core/models/index.ts

@@ -11,6 +11,7 @@ export const modelProviders: Record<string, () => Promise<ModelProvider>> = {
   anthropic: () => import("./anthropic.ts"),
   bedrock: () => import("./bedrock.ts"),
   google: () => import("./google.ts"),
+  groq: () => import("./groq.ts"),
   ollama: () => import("./ollama/index.ts"),
   openai: () => import("./openai.ts"),
   xai: () => import("./xai.ts"),

package/src/daemon/index.ts

@@ -1,5 +1,5 @@
 import { stderr } from "node:process";
-import { BeforeToolCallEvent, type Agent } from "@strands-agents/sdk";
+import type { Agent } from "@strands-agents/sdk";
 import type {
   ChannelMessage,
   Manager as McpManager,
@@ -9,6 +9,7 @@ import { createQueue } from "./queue.ts";
 type RunDaemonOptions = {
   agent: Agent;
   manager: McpManager;
+  session?: string;
   channels: string[];
   debug?: boolean;
 };
@@ -17,6 +18,29 @@ function debug(text: string): void {
   stderr.write(`[daemon] ${text}\n`);
 }
 
+function resolveSessionId(
+  message: ChannelMessage,
+  fallback?: string,
+): string | undefined {
+  const raw = message.meta.identity.session?.trim() || fallback;
+  if (!raw) return undefined;
+  // Namespace per `server:channel` so the same chat id coming from two
+  // different MCP servers (or two channels on the same server) never collide.
+  return `${message.meta.server}:${message.meta.channel}:${raw}`;
+}
+
+function resolveUserId(
+  message: ChannelMessage,
+  session?: string,
+): string | undefined {
+  const raw = message.meta.identity.user?.trim();
+  if (!raw) return session;
+  // Same user id across different servers is not the same human, so scope
+  // user ids by server. Channel is intentionally omitted so long-term memory
+  // can stay consistent for a user across rooms within one server.
+  return `${message.meta.server}:${raw}`;
+}
+
 export async function main(options: RunDaemonOptions): Promise<void> {
   const channels = [
     ...new Set(options.channels.map((value) => value.trim()).filter(Boolean)),
@@ -24,37 +48,49 @@ export async function main(options: RunDaemonOptions): Promise<void> {
   if (channels.length === 0) {
     throw new Error("At least one --channel <name> is required.");
   }
+  debug(`starting daemon for channels: ${channels.join(", ")}`);
 
-  // Daemon mode is non-interactive: approve tool calls by default.
-  options.agent.addHook(BeforeToolCallEvent, async () => {});
+  let unsubscribe = () => {};
 
-  let fasterq: Awaited<ReturnType<typeof createQueue>>[0] | null = null;
+  const [queue, stop] = await createQueue(
+    async (message: ChannelMessage) => {
+      const tag = `${message.meta.server}:${message.meta.channel}`;
+      const session = resolveSessionId(message, options.session);
+      const user = resolveUserId(message, session);
 
-  const unsubscribe = await options.manager.subscribeToChannels(
-    channels,
-    (message) => {
-      if (fasterq != null) {
-        void fasterq.push(message);
+      debug(`dequeued → ${tag} session=${session} user=${user}`);
+      if (options.debug) {
+        debug(`raw → ${JSON.stringify(message.meta)}`);
+      }
+
+      options.agent.appState.set("userId", user);
+      options.agent.appState.set("sessionId", session);
+
+      try {
+        await options.agent.invoke(message.prompt);
+        debug(`completed → ${tag} session=${session} user=${user}`);
+      } catch (error) {
+        const text = error instanceof Error ? error.message : String(error);
+        debug(`turn failed → ${tag} session=${session} user=${user}: ${text}`);
       }
     },
+    () => unsubscribe(),
   );
 
-  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);
+  unsubscribe = await options.manager.subscribeToChannels(
+    channels,
+    (message) => {
       debug(
-        `turn failed → ${message.meta.server}:${message.meta.channel}: ${text}`,
+        `received notification → ${message.meta.server}:${message.meta.channel}`,
       );
-    }
-  }, unsubscribe);
-
-  fasterq = queue;
+      void queue.push(message);
+    },
+  );
+  debug(`subscribed to ${channels.length} channel(s)`);
 
-  await stop();
+  try {
+    await stop();
+  } finally {
+    debug("stopping daemon");
+  }
 }