hoomanjs 1.18.0 → 1.18.1

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

@@ -1,218 +0,0 @@
-import type { Where } from "chromadb";
-import type {
-  LongTermMemoryScope,
-  Memory,
-  MemorySource,
-  MemoryStatus,
-  MemoryType,
-} from "./types.ts";
-
-export const DEFAULT_HALF_LIFE_MS = 1000 * 60 * 60 * 24 * 30;
-export const DEFAULT_REINFORCEMENT_STEP = 0.1;
-export const DEFAULT_DEDUPE_THRESHOLD = 0.92;
-const DEFAULT_SEARCH_LIMIT = 5;
-const MAX_SEARCH_LIMIT = 20;
-
-export type ChromaMemoryMetadata = {
-  userId: string;
-  type: MemoryType;
-  status: MemoryStatus;
-  importance: number;
-  strength: number;
-  accessCount: number;
-  confidence: number | null;
-  createdAt: number;
-  updatedAt: number | null;
-  lastAccessedAt: number | null;
-  version: number;
-  source: MemorySource;
-  /** Omitted when empty: Chroma rejects `[]` for list metadata values. */
-  tags?: string[];
-  entities?: string[];
-  relatedTo?: string[];
-  supersededBy: string | null;
-};
-
-export function clampSearchLimit(limit?: number): number {
-  const value = Math.trunc(limit ?? DEFAULT_SEARCH_LIMIT);
-  return Math.min(Math.max(value, 1), MAX_SEARCH_LIMIT);
-}
-
-export function clampUnitInterval(value: number, fallback: number): number {
-  if (!Number.isFinite(value)) {
-    return fallback;
-  }
-  return Math.min(1, Math.max(0, value));
-}
-
-function asStringArray(value: unknown): string[] | undefined {
-  if (Array.isArray(value)) {
-    return value.filter((item): item is string => typeof item === "string");
-  }
-  if (typeof value === "string" && value.length > 0) {
-    return [value];
-  }
-  return undefined;
-}
-
-function normalizeText(text: string): string {
-  return text
-    .toLowerCase()
-    .replace(/[^\p{L}\p{N}\s]/gu, " ")
-    .replace(/\s+/g, " ")
-    .trim();
-}
-
-export function similarity(left: string, right: string): number {
-  const a = normalizeText(left);
-  const b = normalizeText(right);
-  if (!a || !b) {
-    return 0;
-  }
-  if (a === b) {
-    return 1;
-  }
-
-  const shorter = a.length <= b.length ? a : b;
-  const longer = a.length > b.length ? a : b;
-  const containment = longer.includes(shorter)
-    ? shorter.length / longer.length
-    : 0;
-
-  const tokensA = new Set(a.split(" "));
-  const tokensB = new Set(b.split(" "));
-  let intersection = 0;
-  for (const token of tokensA) {
-    if (tokensB.has(token)) {
-      intersection += 1;
-    }
-  }
-  const union = new Set([...tokensA, ...tokensB]).size;
-  const jaccard = union === 0 ? 0 : intersection / union;
-
-  return Math.max(containment, jaccard);
-}
-
-export function getEffectiveStrength(
-  metadata: Pick<
-    Memory["metadata"],
-    "createdAt" | "lastAccessedAt" | "strength"
-  >,
-  halfLifeMs: number,
-): number {
-  const reference = metadata.lastAccessedAt ?? metadata.createdAt;
-  const age = Math.max(0, Date.now() - reference);
-  return metadata.strength * Math.exp(-age / halfLifeMs);
-}
-
-export function toChromaMetadata(memory: Memory): ChromaMemoryMetadata {
-  const tags = (memory.metadata.tags ?? []).filter((t) => t.length > 0);
-  const entities = (memory.metadata.entities ?? []).filter((t) => t.length > 0);
-  const relatedTo = (memory.metadata.relatedTo ?? []).filter(
-    (t) => t.length > 0,
-  );
-
-  const meta: ChromaMemoryMetadata = {
-    userId: memory.userId,
-    type: memory.type,
-    status: memory.status,
-    importance: memory.metadata.importance,
-    strength: memory.metadata.strength,
-    accessCount: memory.metadata.accessCount,
-    confidence: memory.metadata.confidence ?? null,
-    createdAt: memory.metadata.createdAt,
-    updatedAt: memory.metadata.updatedAt ?? null,
-    lastAccessedAt: memory.metadata.lastAccessedAt ?? null,
-    version: memory.metadata.version,
-    source: memory.metadata.source,
-    supersededBy: memory.metadata.supersededBy ?? null,
-  };
-
-  if (tags.length > 0) {
-    meta.tags = tags;
-  }
-  if (entities.length > 0) {
-    meta.entities = entities;
-  }
-  if (relatedTo.length > 0) {
-    meta.relatedTo = relatedTo;
-  }
-
-  return meta;
-}
-
-export function toMemory(
-  id: string,
-  content: string,
-  metadata: ChromaMemoryMetadata | null | undefined,
-): Memory {
-  const createdAt = Number(metadata?.createdAt ?? Date.now());
-  return {
-    id,
-    userId: metadata?.userId ?? "",
-    type: (metadata?.type ?? "semantic") as MemoryType,
-    status: (metadata?.status ?? "active") as MemoryStatus,
-    content,
-    metadata: {
-      createdAt,
-      updatedAt: metadata?.updatedAt ?? undefined,
-      lastAccessedAt: metadata?.lastAccessedAt ?? undefined,
-      importance: clampUnitInterval(Number(metadata?.importance ?? 0.7), 0.7),
-      strength: Number(metadata?.strength ?? 0.5),
-      confidence:
-        metadata?.confidence == null
-          ? undefined
-          : clampUnitInterval(Number(metadata.confidence), 1),
-      accessCount: Number(metadata?.accessCount ?? 0),
-      version: Number(metadata?.version ?? 1),
-      source: (metadata?.source ?? "assistant") as MemorySource,
-      tags: asStringArray(metadata?.tags),
-      entities: asStringArray(metadata?.entities),
-      supersededBy: metadata?.supersededBy ?? undefined,
-      relatedTo: asStringArray(metadata?.relatedTo),
-    },
-  };
-}
-
-export function buildWhere(
-  scope: LongTermMemoryScope,
-  options?: {
-    status?: MemoryStatus;
-    includeArchived?: boolean;
-    types?: MemoryType[];
-  },
-): Where {
-  // Chroma v3: top-level `where` must have exactly one key (field predicate or $and/$or).
-  const parts: Where[] = [{ userId: scope.userId } as Where];
-
-  const statusFilter = options?.includeArchived
-    ? options.status
-    : (options?.status ?? "active");
-
-  if (statusFilter !== undefined) {
-    parts.push({ status: statusFilter } as Where);
-  }
-
-  if (options?.types?.length) {
-    parts.push({ type: { $in: options.types } } as Where);
-  }
-
-  if (parts.length === 1) {
-    return parts[0]!;
-  }
-
-  return { $and: parts } as Where;
-}
-
-export function chromaClientArgsFromUrl(urlString: string): {
-  host: string;
-  port?: number;
-  ssl: boolean;
-} {
-  const url = new URL(urlString);
-  return {
-    host: url.hostname,
-    port: url.port ? Number(url.port) : undefined,
-    ssl: url.protocol === "https:",
-  };
-}

package/src/core/memory/stm/flat-file-storage.ts

@@ -1,89 +0,0 @@
-import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
-import { join } from "node:path";
-import type {
-  Snapshot,
-  SnapshotLocation,
-  SnapshotManifest,
-  SnapshotStorage,
-} from "@strands-agents/sdk";
-
-/**
- * Snapshot storage with a flat per-session layout:
- * `<baseDir>/<sessionId>/snapshot_latest.json`.
- */
-export class FlatFileStorage implements SnapshotStorage {
-  constructor(private readonly baseDir: string) {}
-
-  async saveSnapshot(params: {
-    location: SnapshotLocation;
-    snapshotId: string;
-    isLatest: boolean;
-    snapshot: Snapshot;
-  }): Promise<void> {
-    const path = this.snapshotPath(params.location, params.snapshotId);
-    await mkdir(join(this.sessionDir(params.location.sessionId)), {
-      recursive: true,
-    });
-    await writeFile(path, JSON.stringify(params.snapshot, null, 2), "utf8");
-  }
-
-  async loadSnapshot(params: {
-    location: SnapshotLocation;
-    snapshotId?: string;
-  }): Promise<Snapshot | null> {
-    const path = this.snapshotPath(params.location, params.snapshotId);
-    try {
-      const raw = await readFile(path, "utf8");
-      return JSON.parse(raw) as Snapshot;
-    } catch (error) {
-      if (
-        error instanceof Error &&
-        "code" in error &&
-        error.code === "ENOENT"
-      ) {
-        return null;
-      }
-      throw error;
-    }
-  }
-
-  async listSnapshotIds(): Promise<string[]> {
-    // Flat storage only tracks one mutable snapshot.
-    return [];
-  }
-
-  async deleteSession(params: { sessionId: string }): Promise<void> {
-    await rm(this.sessionDir(params.sessionId), {
-      recursive: true,
-      force: true,
-    });
-  }
-
-  async loadManifest(): Promise<SnapshotManifest> {
-    return {
-      schemaVersion: "1.0",
-      updatedAt: new Date().toISOString(),
-    };
-  }
-
-  async saveManifest(): Promise<void> {
-    // No-op: flat storage doesn't persist manifest metadata.
-  }
-
-  private sessionDir(sessionId: string): string {
-    return join(this.baseDir, sessionId);
-  }
-
-  private snapshotPath(
-    location: SnapshotLocation,
-    snapshotId?: string,
-  ): string {
-    if (snapshotId && snapshotId !== "latest") {
-      return join(
-        this.sessionDir(location.sessionId),
-        `snapshot_${snapshotId}.json`,
-      );
-    }
-    return join(this.sessionDir(location.sessionId), "snapshot_latest.json");
-  }
-}

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

@@ -1,32 +0,0 @@
-import {
-  SessionManager,
-  SummarizingConversationManager,
-} from "@strands-agents/sdk";
-import { sessionsPath } from "../../utils/paths";
-import { FlatFileStorage } from "./flat-file-storage";
-import { LazySessionManager } from "./lazy-session-manager";
-
-export function create(sessionId?: string) {
-  const conversationManager = new SummarizingConversationManager({
-    summaryRatio: 0.5,
-    preserveRecentMessages: 5,
-  });
-  const storage = new FlatFileStorage(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

@@ -1,220 +0,0 @@
-import {
-  AfterInvocationEvent,
-  BeforeInvocationEvent,
-  Message,
-  contentBlockFromData,
-  type LocalAgent,
-  type MessageData,
-  type Plugin,
-  type SystemPrompt,
-  type SystemPromptData,
-  type Snapshot,
-  type SnapshotLocation,
-  type SnapshotStorage,
-} from "@strands-agents/sdk";
-import type { JSONValue } from "@strands-agents/sdk";
-
-const DEFAULT_SESSION_ID = "default-session";
-const DEFAULT_APP_STATE_KEY = "sessionId";
-const DEFAULT_SCOPE_ID = "agent";
-const SNAPSHOT_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;
-const RUNTIME_OWNED_KEYS = ["userId", "origin"] as const;
-
-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 runtimeState = this.captureRuntimeState(agent);
-    const snapshot = await this.storage.loadSnapshot({
-      location: this.location(agent),
-    });
-    agent.messages.length = 0;
-    if (!snapshot) {
-      this.restoreRuntimeState(agent, runtimeState);
-      return;
-    }
-    loadSnapshot(agent, snapshot);
-    this.restoreRuntimeState(agent, runtimeState);
-  }
-
-  private async save(agent: LocalAgent): Promise<void> {
-    const snapshot = takeSnapshot(agent);
-    await this.storage.saveSnapshot({
-      location: this.location(agent),
-      snapshotId: "latest",
-      isLatest: true,
-      snapshot,
-    });
-  }
-
-  private captureRuntimeState(agent: LocalAgent): Map<string, unknown> {
-    const state = new Map<string, unknown>();
-    const keys = [this.appStateKey, ...RUNTIME_OWNED_KEYS];
-    for (const key of keys) {
-      state.set(key, agent.appState.get(key));
-    }
-    return state;
-  }
-
-  private restoreRuntimeState(
-    agent: LocalAgent,
-    runtimeState: Map<string, unknown>,
-  ): void {
-    for (const [key, value] of runtimeState.entries()) {
-      if (value === undefined) {
-        agent.appState.delete(key);
-        continue;
-      }
-      agent.appState.set(key, value);
-    }
-  }
-}
-
-function sanitize(value: string): string {
-  const trimmed = value.trim().toLowerCase().replace(UNSAFE_CHARS, "_");
-  return trimmed.length > 0 ? trimmed : DEFAULT_SESSION_ID;
-}
-
-function takeSnapshot(agent: LocalAgent): Snapshot {
-  const data: Record<string, JSONValue> = {
-    messages: agent.messages.map((message) =>
-      message.toJSON(),
-    ) as unknown as JSONValue,
-    state: agent.appState.getAll() as JSONValue,
-    systemPrompt:
-      agent.systemPrompt !== undefined
-        ? (systemPromptToData(agent.systemPrompt) as JSONValue)
-        : null,
-  };
-
-  return {
-    scope: "agent",
-    schemaVersion: SNAPSHOT_SCHEMA_VERSION,
-    createdAt: new Date().toISOString(),
-    data,
-    appData: {},
-  };
-}
-
-function loadSnapshot(agent: LocalAgent, snapshot: Snapshot): void {
-  if (snapshot.scope !== "agent") {
-    throw new Error(`Expected snapshot scope 'agent', got '${snapshot.scope}'`);
-  }
-  if (snapshot.schemaVersion !== SNAPSHOT_SCHEMA_VERSION) {
-    throw new Error(
-      `Unsupported snapshot schema version: ${snapshot.schemaVersion}. Current version: ${SNAPSHOT_SCHEMA_VERSION}`,
-    );
-  }
-
-  if ("messages" in snapshot.data) {
-    const messages = snapshot.data.messages;
-    agent.messages.length = 0;
-    for (const msgData of messages as unknown as MessageData[]) {
-      agent.messages.push(Message.fromJSON(msgData));
-    }
-  }
-
-  if ("state" in snapshot.data) {
-    const state = snapshot.data.state;
-    const nextState =
-      state && typeof state === "object" && !Array.isArray(state)
-        ? (state as Record<string, JSONValue>)
-        : {};
-    agent.appState.clear();
-    for (const [key, value] of Object.entries(nextState)) {
-      agent.appState.set(key, value);
-    }
-  }
-
-  if ("systemPrompt" in snapshot.data) {
-    const systemPrompt = snapshot.data.systemPrompt;
-    if (systemPrompt !== null) {
-      agent.systemPrompt = systemPromptFromData(
-        systemPrompt as SystemPromptData,
-      );
-    } else {
-      delete agent.systemPrompt;
-    }
-  }
-}
-
-function systemPromptToData(prompt: SystemPrompt): SystemPromptData {
-  if (typeof prompt === "string") {
-    return prompt;
-  }
-  return prompt.map((block) => block.toJSON()) as SystemPromptData;
-}
-
-function systemPromptFromData(data: SystemPromptData): SystemPrompt {
-  if (typeof data === "string") {
-    return data;
-  }
-  return data.map((block) => contentBlockFromData(block)) as SystemPrompt;
-}

package/src/core/models/anthropic.ts

@@ -1,53 +0,0 @@
-import { anthropic, createAnthropic } from "@ai-sdk/anthropic";
-import { VercelModel } from "@strands-agents/sdk/models/vercel";
-import type { AnthropicProviderSettings } from "@ai-sdk/anthropic";
-import type { VercelModelConfig } from "@strands-agents/sdk/models/vercel";
-import { omit, pick } from "lodash";
-
-const PROVIDER_SETTINGS_KEYS = [
-  "apiKey",
-  "authToken",
-  "baseURL",
-  "headers",
-] as const;
-
-function pickProviderSettings(
-  params: Record<string, unknown>,
-): AnthropicProviderSettings {
-  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 AnthropicProviderSettings;
-}
-
-function pickVercelModelConfig(
-  params: Record<string, unknown>,
-): Partial<VercelModelConfig> {
-  return omit(params, [
-    ...PROVIDER_SETTINGS_KEYS,
-  ]) as Partial<VercelModelConfig>;
-}
-
-/**
- * Anthropic via AI SDK + Strands {@link VercelModel}.
- *
- * - **`config.llm.model`**: model id passed to `anthropic(...)` (e.g. `claude-sonnet-4-20250514`).
- * - **`params`**: Settings {@link AnthropicProviderSettings} (`apiKey`, `authToken`, `baseURL`, …).
- *   If none are set, the default provider is used (`ANTHROPIC_API_KEY` / `ANTHROPIC_AUTH_TOKEN` 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 ? createAnthropic(settings) : anthropic;
-  const config = pickVercelModelConfig(params);
-  return new VercelModel({
-    provider: provider(model),
-    ...config,
-  });
-}

package/src/core/models/bedrock.ts

@@ -1,54 +0,0 @@
-import type { BedrockRuntimeClientConfig } from "@aws-sdk/client-bedrock-runtime";
-import { BedrockModel } from "@strands-agents/sdk/models/bedrock";
-import type { BedrockModelOptions } from "@strands-agents/sdk";
-
-/**
- * Params map from `config.llm.params` into {@link BedrockModel} options.
- *
- * - **`region`**: AWS region (default `us-west-2`).
- * - **`clientConfig`**: passed to the Bedrock Runtime client (credentials, profile, etc.).
- *   See AWS SDK v3 docs for credential options.
- * - **`apiKey`**: optional Bedrock API key auth (bearer), if used instead of SigV4.
- * - Any other keys are forwarded as Bedrock model config (e.g. `maxTokens`, `temperature`,
- *   `stream`, `cacheConfig`).
- *
- * `config.llm.model` is always used as `modelId`.
- */
-export type BedrockLlmParams = Omit<
-  BedrockModelOptions,
-  "modelId" | "region" | "clientConfig" | "apiKey"
-> & {
-  region?: string;
-  clientConfig?: BedrockRuntimeClientConfig;
-  apiKey?: string;
-};
-
-const TOP_LEVEL_KEYS = new Set(["region", "clientConfig", "apiKey", "modelId"]);
-
-export function create(
-  model: string,
-  params: Record<string, unknown> = {},
-): BedrockModel {
-  const p = params as Record<string, unknown>;
-  const region =
-    typeof p.region === "string" && p.region.length > 0
-      ? p.region
-      : "us-west-2";
-  const clientConfig = p.clientConfig as BedrockRuntimeClientConfig | undefined;
-  const apiKey = typeof p.apiKey === "string" ? p.apiKey : undefined;
-
-  const modelOptions: Record<string, unknown> = {};
-  for (const [key, value] of Object.entries(p)) {
-    if (!TOP_LEVEL_KEYS.has(key)) {
-      modelOptions[key] = value;
-    }
-  }
-
-  return new BedrockModel({
-    modelId: model,
-    region,
-    ...(clientConfig ? { clientConfig } : {}),
-    ...(apiKey !== undefined ? { apiKey } : {}),
-    ...modelOptions,
-  } as BedrockModelOptions);
-}