@mongodb-js/agent-engine-sdk 0.11.3

package/dist/index.js

@@ -0,0 +1,8 @@
+/** @mongodb-js/agent-engine-sdk — Core TypeScript protocols and models for MongoDB Agent Engine. */
+export { TextBlockSchema, ImageBlockSchema, DocumentBlockSchema, AnyContentBlockSchema, ToolDefinitionSchema, createToolDefinition, JsonValueSchema, LLMTokenUsage, LLMTokenUsageSchema, LLMToolCall, LLMToolCallSchema, LLMToolSchema, LLMToolSchemaValidator, LLMInvocationOptions, LLMInvocationOptionsSchema, LLMResponse, LLMResponseSchema, MessageSchema, serializeMessage, ToolCallChunkSchema, AgentInputSchema, AgentOutputSchema, StreamEventSchema, BranchRefSchema, EventSchema, DateFromStringSchema, SessionSummarySchema, SessionsSummaryResponseSchema, SessionMessageSchema, SessionMessagesResponseSchema, } from "./models.js";
+export { NullExecutionCallback } from "./interfaces.js";
+export { BaseApp } from "./app.js";
+export { EventResponseSchema, EventsResponseSchema } from "./api/events.js";
+export { MemorySource, MemorySourceSchema, FormatStyle, FormatStyleSchema, ModelType, ModelTypeSchema, WriteTurnResultSchema, CreateSemanticResultSchema, BulkCreateSemanticResultSchema, CreateEpisodicResultSchema, CreateTaxonomicResultSchema, CreateProceduralResultSchema, CreateUserContextResultSchema, CreateSnapshotResultSchema, PromoteSnapshotResultSchema, DeleteResultSchema, InternalStateResultSchema, ISGenerationResultSchema, MemoryChunkSchema, ContextConfigSchema, ContextMetadataSchema, ContextResponseSchema, TagScalarSchema, CustomMemorySaveResultSchema, RetrievedCustomMemorySchema, CustomMemoryRetrieveResultSchema, } from "./api/v1/memory.js";
+export { EventClient } from "./clients/events.js";
+export { MemoryClient, MemoryHttpError } from "./clients/memory.js";

package/dist/interfaces.d.ts

@@ -0,0 +1,111 @@
+/** Framework-neutral protocols for the Atlas Agent Engine SDK. */
+import type { AgentInput, AgentOutput, LLMResponse, LLMStreamChunk, Message, RequestContext, StreamEvent } from "./models.js";
+/**
+ * Result of an agent execution.
+ *
+ * Await for the final result, or async-iterate for streaming events.
+ *
+ * ```ts
+ * // Non-streaming
+ * const output = await agent.execute(ctx, input)
+ *
+ * // Streaming
+ * for await (const event of agent.execute(ctx, input)) {
+ *   handle(event)
+ * }
+ * ```
+ */
+export interface ExecutionResult extends PromiseLike<AgentOutput>, AsyncIterable<StreamEvent> {
+}
+/**
+ * The contract between agent code and runtimes.
+ *
+ * Agents expose a single `execute()` method that returns an `ExecutionResult`.
+ * Callers choose the execution mode:
+ * - `await agent.execute(ctx, input)` for a final result (JSON-style)
+ * - `for await (const event of agent.execute(ctx, input))` for streaming (SSE-style)
+ */
+export interface BaseAgent {
+    execute(ctx: RequestContext, input: AgentInput): ExecutionResult;
+}
+/**
+ * Framework-neutral LLM protocol.
+ *
+ * Used at runtime by the ToolPod. In Python, this protocol exposes both `invoke`
+ * (sync) and `ainvoke` (async) since Python supports both call styles. JS has no
+ * sync HTTP, so this interface has a single async `invoke` plus `stream`.
+ */
+export interface BaseLLM {
+    invoke(messages: Message[], kwargs?: Record<string, unknown>): Promise<LLMResponse>;
+    stream(messages: Message[], kwargs?: Record<string, unknown>): AsyncIterable<LLMStreamChunk>;
+}
+/**
+ * Framework-neutral callback for observability during agent execution.
+ *
+ * Replaces LangChain's `BaseCallbackHandler`. The AER injects an
+ * implementation that forwards node events to the OE for logging.
+ * Framework adapters (e.g. sdk-langgraph) bridge from the framework's
+ * native callback system to this interface.
+ *
+ * Prefer subclassing `NullExecutionCallback` over implementing this
+ * interface directly — it provides no-op defaults for all methods including
+ * optional extensions (e.g. `onNodeSuspend`) so new methods never break
+ * existing implementations.
+ */
+export interface BaseExecutionCallback {
+    onNodeStart(nodeName: string, inputs: Record<string, unknown>, opts: {
+        runId: string;
+        parentRunId?: string;
+        metadata?: Record<string, unknown>;
+    }): void;
+    onNodeEnd(nodeName: string, outputs: Record<string, unknown>, opts: {
+        runId: string;
+        parentRunId?: string;
+        durationMs?: number;
+        metadata?: Record<string, unknown>;
+    }): void;
+    onNodeError(nodeName: string, error: string, opts: {
+        runId: string;
+        parentRunId?: string;
+        metadata?: Record<string, unknown>;
+    }): void;
+}
+/**
+ * Concrete base class with no-op defaults for all `BaseExecutionCallback` methods.
+ *
+ * Subclass this instead of implementing `BaseExecutionCallback` directly so that
+ * new methods added to the interface are automatically satisfied — you only
+ * override the events you care about.
+ *
+ * ```ts
+ * class MyCallback extends NullExecutionCallback {
+ *   onNodeStart(nodeName: string, _inputs, _opts) {
+ *     console.log(`starting ${nodeName}`)
+ *   }
+ * }
+ * ```
+ */
+export declare class NullExecutionCallback implements BaseExecutionCallback {
+    onNodeStart(_nodeName: string, _inputs: Record<string, unknown>, _opts: {
+        runId: string;
+        parentRunId?: string;
+        metadata?: Record<string, unknown>;
+    }): void;
+    onNodeEnd(_nodeName: string, _outputs: Record<string, unknown>, _opts: {
+        runId: string;
+        parentRunId?: string;
+        durationMs?: number;
+        metadata?: Record<string, unknown>;
+    }): void;
+    onNodeError(_nodeName: string, _error: string, _opts: {
+        runId: string;
+        parentRunId?: string;
+        metadata?: Record<string, unknown>;
+    }): void;
+    onNodeSuspend(_nodeName: string, _opts: {
+        runId: string;
+        parentRunId?: string;
+        metadata?: Record<string, unknown>;
+    }): void;
+}
+//# sourceMappingURL=interfaces.d.ts.map

package/dist/interfaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interfaces.d.ts","sourceRoot":"","sources":["../src/interfaces.ts"],"names":[],"mappings":"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"}

package/dist/interfaces.js

@@ -0,0 +1,22 @@
+/** Framework-neutral protocols for the Atlas Agent Engine SDK. */
+/**
+ * Concrete base class with no-op defaults for all `BaseExecutionCallback` methods.
+ *
+ * Subclass this instead of implementing `BaseExecutionCallback` directly so that
+ * new methods added to the interface are automatically satisfied — you only
+ * override the events you care about.
+ *
+ * ```ts
+ * class MyCallback extends NullExecutionCallback {
+ *   onNodeStart(nodeName: string, _inputs, _opts) {
+ *     console.log(`starting ${nodeName}`)
+ *   }
+ * }
+ * ```
+ */
+export class NullExecutionCallback {
+    onNodeStart(_nodeName, _inputs, _opts) { }
+    onNodeEnd(_nodeName, _outputs, _opts) { }
+    onNodeError(_nodeName, _error, _opts) { }
+    onNodeSuspend(_nodeName, _opts) { }
+}