@alexein/sdk 0.0.0-stage → 0.3.0

package/dist/openai-agents.js

@@ -0,0 +1,234 @@
+import {
+  LazyClient,
+  NOTHING_FOUND,
+  NOTHING_YET,
+  SAVED,
+  UNAVAILABLE,
+  isClient,
+  notFoundAnswer,
+  openAnswer,
+  promptBlock,
+  searchAnswer,
+  searchFor,
+  stableId
+} from "./chunk-OVDZ3D4M.js";
+import {
+  AlexeinError,
+  AuthenticationError,
+  NotFoundError,
+  PermissionDeniedError
+} from "./chunk-UNVZ22EN.js";
+
+// src/openai-agents/run.ts
+function userIdOf(context) {
+  const found = context?.userId;
+  if (!found) {
+    throw new Error(
+      'Alexein needs to know whose memory this is: run the agent with { context: { userId: "..." } }'
+    );
+  }
+  return String(found);
+}
+function sessionIdOf(context) {
+  const found = context?.sessionId;
+  return found ? String(found) : void 0;
+}
+function textOf(item2) {
+  const content = "content" in item2 ? item2.content : void 0;
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content.flatMap((part) => "text" in part && typeof part.text === "string" ? [part.text] : []).join("\n");
+}
+var saidByUser = (item2) => "role" in item2 && item2.role === "user";
+var turns = /* @__PURE__ */ new WeakMap();
+function turnOf(result) {
+  if (result.lastResponseId) return result.lastResponseId;
+  const made = turns.get(result) ?? crypto.randomUUID();
+  turns.set(result, made);
+  return made;
+}
+function answer(output) {
+  if (output === void 0 || output === null) return "";
+  return typeof output === "string" ? output : JSON.stringify(output);
+}
+async function item(said, role, turn, author) {
+  if (!said.trim()) return void 0;
+  const id = await stableId(turn, role, said);
+  return { id, role, text: said, ...author ? { author } : {} };
+}
+async function turnItems(result, session) {
+  const input = result.input ?? [];
+  const said = typeof input === "string" ? [{ role: "user", content: input }] : input;
+  const asked2 = said.findLast(saidByUser);
+  const turn = `${session ?? ""}|${turnOf(result)}`;
+  const items = [
+    await item(asked2 ? textOf(asked2) : "", "user", turn),
+    await item(answer(result.finalOutput), "assistant", turn, result.lastAgent?.name)
+  ];
+  return items.filter((i) => i !== void 0);
+}
+
+// src/openai-agents/tools.ts
+import { tool } from "@openai/agents";
+import { z } from "zod";
+function failed(strict) {
+  return (run, error) => {
+    const yours = error instanceof AuthenticationError || error instanceof PermissionDeniedError;
+    const outage = error instanceof AlexeinError && error.outage;
+    const noUser = !run.context?.userId;
+    if (yours || noUser || strict && outage) throw error;
+    if (outage) {
+      console.warn(`Alexein is unavailable: ${error.message}`);
+      return UNAVAILABLE;
+    }
+    return `That did not work: ${error instanceof Error ? error.message : String(error)}`;
+  };
+}
+function buildTools(memory, write) {
+  const errorFunction = failed(memory.strict);
+  const search = tool({
+    name: "memory_search",
+    description: "Search what you remember about this user: what they said, did and decided in earlier conversations. Ask in plain language. Ends with the refs of what it found, to read whole with memory_open.",
+    parameters: z.object({ query: z.string().describe("What to look for") }),
+    errorFunction,
+    async execute({ query }, run) {
+      const found = await searchFor(memory.userOf(run?.context), query, memory.fast);
+      return searchAnswer(found, memory.maxChars);
+    }
+  });
+  const open = tool({
+    name: "memory_open",
+    description: "Read one remembered memory whole, by a ref memory_search gave.",
+    parameters: z.object({ ref: z.string().describe("A ref memory_search gave") }),
+    errorFunction,
+    async execute({ ref }, run) {
+      try {
+        return openAnswer(await memory.userOf(run?.context).open(ref));
+      } catch (error) {
+        if (!(error instanceof NotFoundError)) throw error;
+        return notFoundAnswer(error);
+      }
+    }
+  });
+  const add = tool({
+    name: "memory_add",
+    description: "Remember something about this user for later conversations: a preference, a fact about them, a decision. Write it as one plain sentence. Never save passwords, keys or secrets.",
+    parameters: z.object({ text: z.string().describe("One plain sentence") }),
+    errorFunction,
+    async execute({ text }, run) {
+      const saved = await memory.userOf(run?.context).add(text, {
+        kind: "note",
+        session: sessionIdOf(run?.context)
+      });
+      return saved.failed ? UNAVAILABLE : SAVED;
+    }
+  });
+  return write ? [search, open, add] : [search, open];
+}
+
+// src/openai-agents/index.ts
+function asked(items) {
+  for (let i = items.length - 1; i >= 0; i--) {
+    const item2 = items[i];
+    const role = "role" in item2 ? item2.role : "";
+    if (role === "developer" || role === "system") continue;
+    return role === "user" ? textOf(item2).trim() : void 0;
+  }
+  return void 0;
+}
+var AlexeinMemory = class {
+  fast;
+  maxChars;
+  strict;
+  #client;
+  /**
+   * What `recall` found for each run - its context object - for the model calls after the first
+   * in a turn (a tool loop, a handoff), whose input no longer ends with the user's message. Per
+   * run, so two turns in flight for one user keep their own.
+   */
+  #recalled = /* @__PURE__ */ new WeakMap();
+  /** `client` defaults to one made on first use: fail-open unless strict, a 10 s timeout. */
+  constructor(client, options = {}) {
+    const given = isClient(client) ? client : void 0;
+    const settings = isClient(client) ? options : { ...client, ...options };
+    this.fast = settings.fast ?? false;
+    this.maxChars = settings.maxChars ?? 4e3;
+    this.strict = settings.strict ?? false;
+    this.#client = new LazyClient(given, "openai-agents", this.strict, settings.timeout);
+  }
+  get client() {
+    return this.#client.client;
+  }
+  /** The memory of the app user a run's context names. */
+  userOf(context) {
+    return this.client.user(userIdOf(context));
+  }
+  /**
+   * `callModelInputFilter: memory.recall`: before the model, what memory holds for the user's
+   * latest message, added to the instructions. Already using a filter? Run both:
+   * `async (args) => yours({ ...args, modelData: await memory.recall(args) })`.
+   */
+  recall = async ({
+    modelData,
+    context
+  }) => {
+    const user = this.userOf(context);
+    const run = context;
+    let question = asked(modelData.input);
+    if (question === void 0 && !this.#recalled.has(run)) {
+      const said = modelData.input.findLast(saidByUser);
+      question = said && textOf(said).trim();
+    }
+    if (question !== void 0) {
+      const found = question ? await searchFor(user, question, this.fast) : void 0;
+      this.#recalled.set(run, promptBlock(found?.context(this.maxChars) ?? ""));
+    }
+    const block = this.#recalled.get(run);
+    if (!block) return modelData;
+    const given = modelData.instructions;
+    return { ...modelData, instructions: given ? `${given}
+
+${block}` : block };
+  };
+  /**
+   * Save the turn a run answered - the user's latest message and the final output, under the
+   * agent's name - in the context's `sessionId`. Call it once the run is done (for a stream, once
+   * `completed` resolves). Saving the same result again edits rather than copies. Tool calls and
+   * their results are not saved, and a run paused for an approval saves nothing. Needs a key that
+   * writes.
+   */
+  remember = async (result) => {
+    if (result.interruptions?.length) return;
+    const context = result.runContext?.context;
+    const session = sessionIdOf(context);
+    const items = await turnItems(result, session);
+    if (items.length) await this.userOf(context).add(items, { session });
+  };
+  /**
+   * Tools the model calls when it decides to: `memory_search` and `memory_open`, and with
+   * `write`, `memory_add`. The user comes from the run's context, which a model never sees.
+   */
+  tools({ write = false } = {}) {
+    return buildTools(this, write);
+  }
+};
+var fallback;
+function defaultMemory() {
+  fallback ??= new AlexeinMemory();
+  return fallback;
+}
+var recall = (args) => defaultMemory().recall(args);
+var remember = (result) => defaultMemory().remember(result);
+var memoryTools = (options = {}) => defaultMemory().tools(options);
+export {
+  AlexeinMemory,
+  NOTHING_FOUND,
+  NOTHING_YET,
+  UNAVAILABLE,
+  defaultMemory,
+  memoryTools,
+  recall,
+  remember,
+  sessionIdOf,
+  userIdOf
+};

package/dist/shared-Btg8LbKC.d.cts

@@ -0,0 +1,23 @@
+/**
+ * What the framework integrations share: a client made on first use, the tools' answers in words
+ * a model reads, and the ids that make saving a turn twice an edit rather than a copy. Built on
+ * the client alone; never HTTP.
+ */
+
+/** What the model is told when memory is down, unless the integration is strict. */
+declare const UNAVAILABLE = "Memory is unavailable right now; carry on without it.";
+declare const NOTHING_FOUND = "Nothing remembered about that.";
+declare const NOTHING_YET = "Nothing has been remembered for this user yet.";
+/** What an integration's entry point takes besides its client. */
+interface IntegrationOptions {
+    /** Skip search's relevance check: free and quicker, a little less precise. */
+    fast?: boolean;
+    /** How much of what memory holds goes into a prompt or a tool's answer, in characters. */
+    maxChars?: number;
+    /** Throw on an outage instead of carrying on without memory. */
+    strict?: boolean;
+    /** Milliseconds each attempt may take, for the client made on first use. Default 10 s. */
+    timeout?: number;
+}
+
+export { type IntegrationOptions as I, NOTHING_FOUND as N, UNAVAILABLE as U, NOTHING_YET as a };

package/dist/shared-Btg8LbKC.d.ts

@@ -0,0 +1,23 @@
+/**
+ * What the framework integrations share: a client made on first use, the tools' answers in words
+ * a model reads, and the ids that make saving a turn twice an edit rather than a copy. Built on
+ * the client alone; never HTTP.
+ */
+
+/** What the model is told when memory is down, unless the integration is strict. */
+declare const UNAVAILABLE = "Memory is unavailable right now; carry on without it.";
+declare const NOTHING_FOUND = "Nothing remembered about that.";
+declare const NOTHING_YET = "Nothing has been remembered for this user yet.";
+/** What an integration's entry point takes besides its client. */
+interface IntegrationOptions {
+    /** Skip search's relevance check: free and quicker, a little less precise. */
+    fast?: boolean;
+    /** How much of what memory holds goes into a prompt or a tool's answer, in characters. */
+    maxChars?: number;
+    /** Throw on an outage instead of carrying on without memory. */
+    strict?: boolean;
+    /** Milliseconds each attempt may take, for the client made on first use. Default 10 s. */
+    timeout?: number;
+}
+
+export { type IntegrationOptions as I, NOTHING_FOUND as N, UNAVAILABLE as U, NOTHING_YET as a };

package/package.json

@@ -1,6 +1,129 @@
 {
   "name": "@alexein/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "JavaScript and TypeScript client for Alexein: long-term memory for your users and agents, with LangGraph.js and OpenAI Agents SDK integrations.",
+  "license": "MIT",
+  "author": "Alexein AI",
+  "homepage": "https://docs.alexein.ai/sdks/typescript",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Alexein-AI/sdk.git",
+    "directory": "typescript"
+  },
+  "bugs": {
+    "url": "https://github.com/Alexein-AI/sdk/issues"
+  },
+  "keywords": [
+    "alexein",
+    "memory",
+    "long-term-memory",
+    "agents",
+    "ai-agents",
+    "langgraph",
+    "openai-agents"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./langgraph": {
+      "import": {
+        "types": "./dist/langgraph.d.ts",
+        "default": "./dist/langgraph.js"
+      },
+      "require": {
+        "types": "./dist/langgraph.d.cts",
+        "default": "./dist/langgraph.cjs"
+      }
+    },
+    "./openai-agents": {
+      "import": {
+        "types": "./dist/openai-agents.d.ts",
+        "default": "./dist/openai-agents.js"
+      },
+      "require": {
+        "types": "./dist/openai-agents.d.cts",
+        "default": "./dist/openai-agents.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "typesVersions": {
+    "*": {
+      "langgraph": [
+        "./dist/langgraph.d.ts"
+      ],
+      "openai-agents": [
+        "./dist/openai-agents.d.ts"
+      ]
+    }
+  },
+  "files": [
+    "dist/*.js",
+    "dist/*.cjs",
+    "dist/*.d.ts",
+    "dist/*.d.cts",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "lint": "prettier --check .",
+    "check": "tsc --noEmit && prettier --check . && vitest run",
+    "test": "vitest run",
+    "format": "prettier --write .",
+    "prepublishOnly": "npm run check && npm run build"
+  },
+  "peerDependencies": {
+    "@langchain/core": ">=1.0.0 <2.0.0",
+    "@langchain/langgraph": ">=1.0.0 <2.0.0",
+    "@openai/agents": ">=0.21.0 <1.0.0",
+    "zod": "^3.25.0 || ^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@langchain/core": {
+      "optional": true
+    },
+    "@langchain/langgraph": {
+      "optional": true
+    },
+    "@openai/agents": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@langchain/core": "^1.3.0",
+    "@langchain/langgraph": "^1.6.0",
+    "@openai/agents": "^0.21.0",
+    "@types/node": "^22.10.0",
+    "langchain": "^1.6.0",
+    "prettier": "^3.4.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0",
+    "zod": "^4.0.0"
+  }
+}