@mongodb-js/agent-engine-sdk 0.11.3

package/dist/api/v1/memory.js

@@ -0,0 +1,219 @@
+/**
+ * Canonical types for the Memory Server HTTP API.
+ *
+ * Single source of truth for result shapes returned by the memory server.
+ * Consumed by MemoryClient and by framework SDK adapters (e.g. sdk-langgraph).
+ */
+import { z } from "zod";
+import { DateFromStringSchema } from "../../models.js";
+// =============================================================================
+// Result models
+//
+// All response schemas use `z.looseObject` so unknown fields added by the
+// server are preserved on the parsed result, rather than silently dropped.
+// Request/config schemas (ContextConfigSchema) use strict object semantics.
+// =============================================================================
+export const WriteTurnResultSchema = z.looseObject({
+    id: z.string(),
+    session_id: z.string(),
+    turn_seq: z.number(),
+    acknowledged: z.boolean(),
+});
+export const CreateSemanticResultSchema = z.looseObject({
+    id: z.string(),
+    label: z.string(),
+    has_embedding: z.boolean(),
+    acknowledged: z.boolean(),
+});
+export const BulkCreateSemanticResultSchema = z.looseObject({
+    created_count: z.number(),
+    skipped_count: z.number(),
+    created_ids: z.array(z.string()),
+    skipped_labels: z.array(z.string()),
+    has_embeddings: z.boolean(),
+    acknowledged: z.boolean(),
+});
+export const CreateEpisodicResultSchema = z.looseObject({
+    id: z.string(),
+    title: z.string(),
+    has_embedding: z.boolean(),
+    acknowledged: z.boolean(),
+});
+export const CreateTaxonomicResultSchema = z.looseObject({
+    id: z.string(),
+    domain: z.string(),
+    term: z.string(),
+    has_embedding: z.boolean(),
+    acknowledged: z.boolean(),
+});
+export const CreateProceduralResultSchema = z.looseObject({
+    id: z.string(),
+    procedure: z.string(),
+    has_embedding: z.boolean(),
+    acknowledged: z.boolean(),
+});
+export const CreateUserContextResultSchema = z.looseObject({
+    id: z.string(),
+    context_key: z.string(),
+    acknowledged: z.boolean(),
+});
+export const CreateSnapshotResultSchema = z.looseObject({
+    id: z.string(),
+    session_id: z.string(),
+    message_count: z.number(),
+    has_embedding: z.boolean(),
+    embedding_strategy: z.string().optional(),
+    snapshot_reason: z.string(),
+    acknowledged: z.boolean(),
+});
+export const PromoteSnapshotResultSchema = z.looseObject({
+    snapshot_id: z.string().optional(),
+    session_id: z.string(),
+    promoted_count: z.number(),
+    reason: z.string(),
+    has_embedding: z.boolean().default(false),
+    acknowledged: z.boolean(),
+});
+export const DeleteResultSchema = z.looseObject({
+    deleted_count: z.number(),
+    acknowledged: z.boolean(),
+});
+export const InternalStateResultSchema = z.looseObject({
+    session_id: z.string(),
+    version: z.number(),
+    token_count: z.number(),
+    content_hash: z.string(),
+    previous_version: z.number().optional(),
+    was_noop: z.boolean(),
+    acknowledged: z.boolean(),
+});
+export const ISGenerationResultSchema = z.looseObject({
+    updated: z.boolean(),
+    version: z.number().optional(),
+    token_count: z.number().optional(),
+    content_hash: z.string().optional(),
+    previous_version: z.number().optional(),
+    was_noop: z.boolean(),
+    coalesced: z.boolean(),
+    skipped_reason: z.string().optional(),
+    next_update_at: z.string().optional(),
+    model_id: z.string().optional(),
+    events_hash: z.string().optional(),
+});
+export const TagScalarSchema = z.union([z.string(), z.number(), z.boolean()]);
+// Deliberate deviation from the module's looseObject convention: these
+// custom-type schemas stay strict so the server's internal similarity ranking
+// `score` never leaks into the public result shape. The trade-off is that
+// future additive server fields are dropped rather than preserved.
+export const CustomMemorySaveResultSchema = z.object({
+    id: z.string(),
+    type: z.string(),
+    tags: z.record(z.string(), TagScalarSchema),
+    has_embedding: z.boolean(),
+});
+export const RetrievedCustomMemorySchema = z.object({
+    id: z.string(),
+    type: z.string(),
+    content: z.string(),
+    tags: z.record(z.string(), TagScalarSchema),
+    contextual_metadata: z.record(z.string(), z.unknown()).nullish(),
+    user_id: z.string().nullish(),
+    agent_id: z.string().nullish(),
+});
+export const CustomMemoryRetrieveResultSchema = z.object({
+    results: z.array(RetrievedCustomMemorySchema),
+    count: z.number(),
+});
+// =============================================================================
+// Retrieval enums
+// =============================================================================
+export const MemorySourceSchema = z.enum([
+    "stm",
+    "episodic",
+    "semantic",
+    "taxonomic",
+    "procedural",
+]);
+export const MemorySource = {
+    STM: "stm",
+    EPISODIC: "episodic",
+    SEMANTIC: "semantic",
+    TAXONOMIC: "taxonomic",
+    PROCEDURAL: "procedural",
+};
+export const FormatStyleSchema = z.enum(["openai", "claude", "jinja2"]);
+export const FormatStyle = {
+    OPENAI: "openai",
+    CLAUDE: "claude",
+    JINJA2: "jinja2",
+};
+export const ModelTypeSchema = z.enum([
+    "openai",
+    "claude",
+    "anthropic",
+    "gemini",
+    "generic",
+]);
+export const ModelType = {
+    OPENAI: "openai",
+    CLAUDE: "claude",
+    ANTHROPIC: "anthropic",
+    GEMINI: "gemini",
+    GENERIC: "generic",
+};
+// =============================================================================
+// Retrieval models
+// =============================================================================
+/** Unified representation of a retrieved memory chunk across all memory types. */
+export const MemoryChunkSchema = z.looseObject({
+    id: z.string(),
+    content: z.string(),
+    source: MemorySourceSchema,
+    timestamp: DateFromStringSchema,
+    embedding: z.array(z.number()).optional(),
+    similarity_score: z.number().optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+});
+const lowerCaseStrings = (v) => typeof v === "string" ? v.toLowerCase() : v;
+const dedupSources = (arr) => Array.from(new Set(arr));
+/** Configuration for context building requests. */
+export const ContextConfigSchema = z
+    .object({
+    max_tokens: z.number().int().min(1).default(16000),
+    token_buffer: z.number().int().min(0).default(500),
+    format_style: z
+        .preprocess(lowerCaseStrings, FormatStyleSchema)
+        .default(FormatStyle.OPENAI),
+    model_type: z
+        .preprocess(lowerCaseStrings, ModelTypeSchema)
+        .default(ModelType.OPENAI),
+    similarity_threshold: z.number().min(0).max(1).default(0),
+    ranking_weights: z.record(z.string(), z.number()).default({}),
+    enabled_sources: z
+        .array(MemorySourceSchema)
+        .transform(dedupSources)
+        .default([MemorySource.EPISODIC, MemorySource.SEMANTIC]),
+    include_memories: z.boolean().default(false),
+})
+    .refine((data) => data.enabled_sources.length > 0, {
+    message: "enabled_sources cannot be empty",
+    path: ["enabled_sources"],
+});
+/** Metadata about a context build response (token counts, per-source counts, timing). */
+export const ContextMetadataSchema = z.looseObject({
+    token_count: z.number().int().min(0).default(0),
+    memory_counts: z.record(z.string(), z.number()).default({}),
+    timing: z.record(z.string(), z.number()).default({}),
+});
+/** Response from a context build request containing formatted context and retrieval metadata. */
+export const ContextResponseSchema = z.looseObject({
+    formatted_context: z.union([
+        z.string(),
+        z.array(z.record(z.string(), z.unknown())),
+    ]),
+    metadata: ContextMetadataSchema,
+    // Mirrors Python `list[MemoryChunk] | None` (default None): the server sends
+    // `null` when include_memories=False (the only path any caller uses), so accept
+    // null as well as undefined/array.
+    selected_memories: z.array(MemoryChunkSchema).nullish(),
+});

package/dist/app.d.ts

@@ -0,0 +1,27 @@
+/** Base application class for framework-specific SDK integrations. */
+import type { ToolDefinition } from "./models.js";
+/**
+ * Abstract base class for framework-specific SDK integrations.
+ *
+ * Each framework SDK (LangGraph, CrewAI, etc.) subclasses `BaseApp`
+ * and implements the abstract methods using framework-native constructs.
+ *
+ * The platform runtime sets `toolWrapper` and `llmWrapper` on the
+ * instance before calling `entrypoint()` so that tools and LLMs are
+ * routed through the secure execution layer.
+ */
+export declare abstract class BaseApp {
+    readonly name: string;
+    toolWrapper: unknown;
+    llmWrapper: unknown;
+    constructor(name: string);
+    /** Returns all registered tool definitions. Used by the OE to obtain tool execution information. */
+    abstract getToolDefinitions(): ToolDefinition[];
+    /** Returns a list of wrapped, framework-specific tools. */
+    abstract tools(): unknown[];
+    /** Decorator that registers a tool on this app. */
+    abstract tool(...args: unknown[]): unknown;
+    /** Decorator that registers the agent builder function. Called by runtimes to obtain a BaseAgent. */
+    abstract entrypoint(fn: unknown): unknown;
+}
+//# sourceMappingURL=app.d.ts.map

package/dist/app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAEtE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD;;;;;;;;;GASG;AACH,8BAAsB,OAAO;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,OAAO,CAAQ;IAC5B,UAAU,EAAE,OAAO,CAAQ;gBAEf,IAAI,EAAE,MAAM;IAIxB,oGAAoG;IACpG,QAAQ,CAAC,kBAAkB,IAAI,cAAc,EAAE;IAE/C,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,IAAI,OAAO,EAAE;IAE3B,mDAAmD;IACnD,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO;IAE1C,qGAAqG;IACrG,QAAQ,CAAC,UAAU,CAAC,EAAE,EAAE,OAAO,GAAG,OAAO;CAC1C"}

package/dist/app.js

@@ -0,0 +1,19 @@
+/** Base application class for framework-specific SDK integrations. */
+/**
+ * Abstract base class for framework-specific SDK integrations.
+ *
+ * Each framework SDK (LangGraph, CrewAI, etc.) subclasses `BaseApp`
+ * and implements the abstract methods using framework-native constructs.
+ *
+ * The platform runtime sets `toolWrapper` and `llmWrapper` on the
+ * instance before calling `entrypoint()` so that tools and LLMs are
+ * routed through the secure execution layer.
+ */
+export class BaseApp {
+    name;
+    toolWrapper = null;
+    llmWrapper = null;
+    constructor(name) {
+        this.name = name;
+    }
+}

package/dist/clients/events.d.ts

@@ -0,0 +1,11 @@
+/** HTTP client for the platform event API. */
+import type { BranchRef, Event } from "../models.js";
+export declare class EventClient {
+    private readonly oeUrl;
+    private readonly timeout;
+    constructor(oeUrl: string, timeout?: number);
+    appendEvent(sessionId: string, actorId: string, payload: Record<string, unknown>, parentEventId?: string, metadata?: Record<string, unknown>, branch?: BranchRef): Promise<Event>;
+    listEvents(sessionId: string, branch?: string, metadataFilters?: Record<string, string>): Promise<Event[]>;
+    getEvent(sessionId: string, eventId: string): Promise<Event | null>;
+}
+//# sourceMappingURL=events.d.ts.map

package/dist/clients/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/clients/events.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAE9C,OAAO,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAgBrD,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,KAAK,EAAE,MAAM,EAAE,OAAO,SAAK;IAKjC,WAAW,CACf,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,aAAa,CAAC,EAAE,MAAM,EACtB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClC,MAAM,CAAC,EAAE,SAAS,GACjB,OAAO,CAAC,KAAK,CAAC;IAmBX,UAAU,CACd,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,MAAM,EACf,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACvC,OAAO,CAAC,KAAK,EAAE,CAAC;IAmBb,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC;CAW1E"}

package/dist/clients/events.js

@@ -0,0 +1,67 @@
+/** HTTP client for the platform event API. */
+import { EventResponseSchema, EventsResponseSchema } from "../api/events.js";
+/**
+ * Percent-encode an id for use as a single URL path segment, refusing bare
+ * dot segments: encodeURIComponent leaves '.'/'..' untouched, and the URL
+ * parser would collapse them into a parent-path rewrite of this authenticated
+ * request.
+ */
+function encodeIdSegment(id) {
+    if (id === "." || id === "..") {
+        throw new Error(`Invalid id: bare dot segment ${JSON.stringify(id)}`);
+    }
+    return encodeURIComponent(id);
+}
+export class EventClient {
+    oeUrl;
+    timeout;
+    constructor(oeUrl, timeout = 30) {
+        this.oeUrl = oeUrl.replace(/\/$/, "");
+        this.timeout = timeout;
+    }
+    async appendEvent(sessionId, actorId, payload, parentEventId, metadata, branch) {
+        const body = { actor_id: actorId, payload };
+        if (parentEventId !== undefined)
+            body["parent_event_id"] = parentEventId;
+        if (metadata !== undefined)
+            body["metadata"] = metadata;
+        if (branch !== undefined)
+            body["branch"] = branch;
+        const resp = await fetch(`${this.oeUrl}/v1/sessions/${encodeIdSegment(sessionId)}/events`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(this.timeout * 1000),
+        });
+        if (!resp.ok)
+            throw new Error(`HTTP ${resp.status}: ${await resp.text()}`);
+        return EventResponseSchema.parse(await resp.json()).event;
+    }
+    async listEvents(sessionId, branch, metadataFilters) {
+        const params = new URLSearchParams();
+        if (branch !== undefined)
+            params.set("branch", branch);
+        if (metadataFilters !== undefined) {
+            for (const [key, val] of Object.entries(metadataFilters)) {
+                params.set(`metadata.${key}`, val);
+            }
+        }
+        const qs = params.size > 0 ? `?${params.toString()}` : "";
+        const resp = await fetch(`${this.oeUrl}/v1/sessions/${encodeIdSegment(sessionId)}/events${qs}`, {
+            signal: AbortSignal.timeout(this.timeout * 1000),
+        });
+        if (!resp.ok)
+            throw new Error(`HTTP ${resp.status}: ${await resp.text()}`);
+        return EventsResponseSchema.parse(await resp.json()).events;
+    }
+    async getEvent(sessionId, eventId) {
+        const resp = await fetch(`${this.oeUrl}/v1/sessions/${encodeIdSegment(sessionId)}/events/${encodeIdSegment(eventId)}`, {
+            signal: AbortSignal.timeout(this.timeout * 1000),
+        });
+        if (resp.status === 404)
+            return null;
+        if (!resp.ok)
+            throw new Error(`HTTP ${resp.status}: ${await resp.text()}`);
+        return EventResponseSchema.parse(await resp.json()).event;
+    }
+}