@mongodb-js/agent-engine-runner-shared 0.11.3

package/dist/workflow/memory.js

@@ -0,0 +1,184 @@
+/** Durable activity synchronization with short-term Memory. */
+import { create } from "@bufbuild/protobuf";
+import { LLMResponse } from "@mongodb-js/agent-engine-sdk";
+import { ActivityMemoryCommandSchema, MemoryWriteSchema, } from "../generated/workflow/v1/activity_pb.js";
+import { getLogger } from "../logger.js";
+import { normalizeContent } from "../utils.js";
+import { CALL_INTERRUPTED_ARTIFACT_KEY } from "../call_interrupted.js";
+const logger = getLogger("agent_engine_runner_shared.workflow.memory");
+const encoder = new TextEncoder();
+/** JSON-serialize a plain tool result, degrading to String on failure. */
+function safeJsonContent(result) {
+    try {
+        return JSON.stringify(result) ?? String(result);
+    }
+    catch {
+        return String(result);
+    }
+}
+export function validateDurableMemoryIdentity(identity, userId) {
+    const scope = identity?.tenantScope;
+    if (!userId ||
+        !identity?.executionId ||
+        !identity.sessionId ||
+        !scope?.orgId ||
+        !scope.projectId ||
+        !scope.workspaceId) {
+        throw new Error("durable Memory identity is incomplete");
+    }
+}
+class DurableMemoryProjection {
+    executionId;
+    activityId;
+    sessionId;
+    orgId;
+    projectId;
+    workspaceId;
+    userId;
+    constructor(executionId, activityId, sessionId, orgId, projectId, workspaceId, userId) {
+        this.executionId = executionId;
+        this.activityId = activityId;
+        this.sessionId = sessionId;
+        this.orgId = orgId;
+        this.projectId = projectId;
+        this.workspaceId = workspaceId;
+        this.userId = userId;
+    }
+    static fromActivity(context, userId) {
+        validateDurableMemoryIdentity(context.workflowIdentity, userId);
+        if (!context.activityId || !context.workflowIdentity || !userId) {
+            throw new Error("durable Memory identity is incomplete");
+        }
+        const scope = context.workflowIdentity.tenantScope;
+        if (!scope)
+            throw new Error("durable Memory identity is incomplete");
+        return new DurableMemoryProjection(context.workflowIdentity.executionId, context.activityId, context.workflowIdentity.sessionId, scope.orgId, scope.projectId, scope.workspaceId, userId);
+    }
+    userInput(content) {
+        const id = `workflow:${this.executionId}:input`;
+        return this.write(id, {
+            ...this.turnIdentity(id),
+            role: "user",
+            content,
+        });
+    }
+    assistant(content, toolCalls) {
+        const id = `workflow:${this.executionId}:${this.activityId}:assistant:0`;
+        return this.write(id, {
+            ...this.turnIdentity(id),
+            role: "assistant",
+            content,
+            ...(toolCalls === null ? {} : { tool_calls: toolCalls }),
+        });
+    }
+    tool(content, toolCallId, toolName) {
+        const id = `workflow:${this.executionId}:${this.activityId}:tool:0`;
+        return this.write(id, {
+            ...this.turnIdentity(id),
+            role: "tool",
+            content,
+            tool_call_id: toolCallId,
+            tool_name: toolName,
+            is_error: false,
+        });
+    }
+    turnIdentity(id) {
+        return {
+            session_id: this.sessionId,
+            org_id: this.orgId,
+            user_id: this.userId,
+            project_id: this.projectId,
+            agent_id: this.workspaceId,
+            idempotency_key: id,
+        };
+    }
+    write(id, payload) {
+        return create(MemoryWriteSchema, {
+            id,
+            payloadJson: encoder.encode(JSON.stringify(payload)),
+        });
+    }
+}
+/** Own durable Memory projection, delivery, and pending user input. */
+export class DurableMemoryState {
+    pendingUserMessage;
+    synchronization = Promise.resolve();
+    constructor(pendingUserMessage = null) {
+        this.pendingUserMessage = pendingUserMessage;
+    }
+    synchronizeLlm(client, context, result, userId) {
+        const projection = DurableMemoryProjection.fromActivity(context, userId);
+        const writes = [];
+        try {
+            if (typeof result !== "object" ||
+                result === null ||
+                Array.isArray(result)) {
+                throw new Error("LLM result must be an object");
+            }
+            const response = LLMResponse.fromRaw(result);
+            const toolCalls = response.toolCalls?.map((toolCall) => {
+                const args = toolCall.args ?? {};
+                if (typeof args !== "string" &&
+                    (typeof args !== "object" || args === null || Array.isArray(args))) {
+                    throw new Error("tool-call arguments must be an object or string");
+                }
+                return {
+                    id: toolCall.id ?? "",
+                    name: toolCall.name ?? "",
+                    arguments: args,
+                };
+            });
+            if (!response.content && !toolCalls?.length) {
+                throw new Error("assistant result has no content or tool calls");
+            }
+            writes.push(projection.assistant(response.content, toolCalls ?? null));
+        }
+        catch {
+            logger.warn({ activity_id: context.activityId }, "Skipping incompatible durable Memory LLM result");
+        }
+        return this.synchronize(client, context, projection, writes);
+    }
+    synchronizeTool(client, context, result, userId, toolCallId, toolName) {
+        const projection = DurableMemoryProjection.fromActivity(context, userId);
+        const writes = [];
+        const interrupted = typeof result === "object" &&
+            result !== null &&
+            !Array.isArray(result) &&
+            Object.keys(result).length === 1 &&
+            result[CALL_INTERRUPTED_ARTIFACT_KEY] ===
+                true;
+        if (!interrupted) {
+            // Plain structured results must survive as JSON (mirroring the
+            // ToolMessage path): normalizeContent would reduce objects to
+            // "[object Object]" and mangle arrays (multimodal concatenation),
+            // losing the result Memory must preserve.
+            const content = typeof result === "object" && result !== null
+                ? safeJsonContent(result)
+                : normalizeContent(result);
+            if (toolCallId && content) {
+                writes.push(projection.tool(content, toolCallId, toolName));
+            }
+            else if (toolCallId) {
+                logger.warn({ activity_id: context.activityId }, "Skipping incompatible durable Memory tool result");
+            }
+        }
+        return this.synchronize(client, context, projection, writes);
+    }
+    synchronize(client, context, projection, resultWrites) {
+        const operation = this.synchronization.then(async () => {
+            const writes = this.pendingUserMessage === null
+                ? resultWrites
+                : [projection.userInput(this.pendingUserMessage), ...resultWrites];
+            await client.ensureMemoryWritten(create(ActivityMemoryCommandSchema, {
+                workflowIdentity: context.workflowIdentity,
+                activityId: context.activityId,
+                attemptId: context.attemptId,
+                fencingToken: context.fencingToken,
+                memoryWrites: writes,
+            }));
+            this.pendingUserMessage = null;
+        });
+        this.synchronization = operation.catch(() => { });
+        return operation;
+    }
+}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@mongodb-js/agent-engine-runner-shared",
+  "version": "0.11.3",
+  "description": "Runner SDK - Framework-agnostic agent runtime (TypeScript)",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/10gen/agentic-platform.git",
+    "directory": "client-libraries/packages/javascript/packages/agent-engine-runner-shared"
+  },
+  "type": "module",
+  "packageManager": "npm@11.14.1",
+  "engines": {
+    "node": ">=24",
+    "npm": ">=11.10.0"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE.md"
+  ],
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "typecheck": "tsc --project tsconfig.build.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint \"src/**/*.ts\" \"tests/**/*.ts\""
+  },
+  "dependencies": {
+    "@bufbuild/protobuf": "2.12.1",
+    "@fastify/cors": "^10.0.0",
+    "@mongodb-js/agent-engine-sdk-memory": "0.11.3",
+    "@mongodb-js/agent-engine-sdk": "0.11.3",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/core": "^2.0.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.205.0",
+    "@opentelemetry/resources": "^2.0.0",
+    "@opentelemetry/sdk-trace-base": "^2.7.1",
+    "eventsource-parser": "^3.0.0",
+    "fastify": "^5.0.0",
+    "js-yaml": "^4.1.0",
+    "log4js": "^6.9.1",
+    "mongodb": "^6.0.0",
+    "proper-lockfile": "^4.1.2",
+    "undici": "^6.0.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@bufbuild/protoc-gen-es": "2.12.1",
+    "@eslint/js": "^10.0.1",
+    "@sentry/node": "^8.55.0",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.0.0",
+    "@types/proper-lockfile": "^4.1.4",
+    "eslint": "^10.4.0",
+    "typescript": "^5.5.0",
+    "typescript-eslint": "^8.59.3",
+    "vitest": "^4.1.6"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org"
+  }
+}