@opengeni/sdk 3.3.2 → 3.4.0

package/src/skills.ts

@@ -0,0 +1,69 @@
+/** Public shared Skill folder/history shapes; no runtime contracts dependency. */
+export type SkillFile = { path: string; content: string };
+export type SkillScope = "workspace" | "organization" | "user";
+export type SkillRecord = {
+  removalOperationId?: string | null;
+  activationMode: "workspace_managed" | "session_selected";
+  pendingRevisionIds: string[];
+  id: string;
+  stableKey: string;
+  scope: SkillScope;
+  scopeVersion: number;
+  status: string;
+  activeRevisionId: string | null;
+  revisionId: string | null;
+  title: string | null;
+  description: string | null;
+  contentHash: string | null;
+  files: SkillFile[];
+  source: { pluginId: string; facetKey: string; skillFacetId: string } | null;
+};
+export type SkillSummary = Omit<SkillRecord, "files">;
+export type SkillWriteReceipt = {
+  removed?: boolean | undefined;
+  operationId: string;
+  skillId: string;
+  revisionId: string;
+  outcome: "applied" | "pending" | "preserved";
+  pendingReason?: "approval" | "source_finalization" | undefined;
+  replayed: boolean;
+  decision?: "rejected" | undefined;
+  skillReview?: import("./types").SkillReviewReference | undefined;
+};
+export type SkillPublicationReceipt = SkillWriteReceipt & {
+  sourceOperationId: string;
+  activationEventId: string | null;
+};
+export type SkillSourceReleaseReceipt = {
+  skillId: string;
+  revisionId: string | null;
+  disposition: "deactivated" | "preserved" | "inactive";
+  eventId: string | null;
+  warning: string | null;
+};
+export type SaveWorkspaceSkillRequest = {
+  operationId: string;
+  skillId: string;
+  expectedRevisionId: string | null;
+  expectedScopeVersion: number;
+  scope?: SkillScope;
+  stableKey: string;
+  files: SkillFile[];
+  deletions?: string[];
+  reason: string;
+};
+export type ApplyWorkspaceSkillRevisionRequest = {
+  removalOperationId?: string;
+  operationId: string;
+  revisionId: string;
+  expectedRevisionId: string | null;
+  expectedScopeVersion: number;
+  reason: string;
+};
+
+export type RemoveWorkspaceSkillRequest = {
+  operationId: string;
+  expectedRevisionId: string | null;
+  expectedScopeVersion: number;
+  reason: string;
+};

package/src/sse.ts

@@ -1,7 +1,7 @@
 /**
  * Minimal incremental Server-Sent Events parser over a byte stream.
  *
- * Implements the parts of the SSE wire format OpenGeni uses: `id`, `event`,
+ * Implements the parts of the SSE wire format Opengeni uses: `id`, `event`,
  * and `data` fields, multi-line data, comment lines, and both LF and CRLF
  * line endings. Messages without any `data` (comments, id-only blocks) are
  * not emitted.
@@ -87,7 +87,13 @@ export async function* parseSseStream(
     // still pending at end-of-stream came from a truncated connection and is
     // discarded — the streaming layer replays from its cursor on reconnect.
   } finally {
-    await reader.cancel().catch(() => {});
-    reader.releaseLock();
+    // Never await cancel(): some fetch bodies settle it only once their request
+    // aborts, which would deadlock the consumer's unwinding.
+    void reader.cancel().catch(() => {});
+    try {
+      reader.releaseLock();
+    } catch {
+      // A pending read (older stream implementations) keeps the lock; cancel releases it.
+    }
   }
 }

package/src/stream.ts

@@ -2,6 +2,10 @@ import { isAbortError, isRetryableStreamError, OpenGeniStreamError } from "./err
 import { parseSseStream } from "./sse";
 import type { SessionEvent } from "./types";
 
+const SESSION_EVENT_STREAM_COVERAGE = Symbol.for(
+  "@opengeni/sdk/session-event-stream-covered-through",
+);
+
 /**
  * Transport boundary for the streaming core. The client implements it with
  * `fetch`; unit tests script it directly.
@@ -111,7 +115,8 @@ export async function* streamSessionEvents(
         if (!event) {
           continue;
         }
-        const coveredSequence = eventResumeSequence(event);
+        const coveredSequence = trustedSseSequence(message.id, event.sequence);
+        markSessionEventStreamCoverage(event, coveredSequence);
         if (coveredSequence <= cursor) continue;
         if (event.sequence > cursor + 1) {
           for await (const missed of backfillEvents(transport, cursor, event.sequence - 1)) {
@@ -224,8 +229,10 @@ export function withStreamInactivityTimeout(
         if (signal && abortListener) signal.removeEventListener("abort", abortListener);
       }
     },
-    cancel: async (reason) => {
-      await reader.cancel(reason);
+    cancel: (reason) => {
+      // Do not wait for the underlying body: it may settle cancel() only after
+      // its request aborts (see parseSseStream).
+      void reader.cancel(reason).catch(() => {});
     },
   });
 }
@@ -283,13 +290,29 @@ function parseSessionEvent(data: string): SessionEvent | null {
   return parsed as SessionEvent;
 }
 
-/** Raw durable cursor covered by a compact SSE event. */
-function eventResumeSequence(event: SessionEvent): number {
-  if (!event.payload || typeof event.payload !== "object" || Array.isArray(event.payload)) {
-    return event.sequence;
-  }
-  const covered = Number((event.payload as Record<string, unknown>).coalescedUntil);
-  return Math.max(event.sequence, Number.isFinite(covered) ? Math.floor(covered) : event.sequence);
+/** Trusted SSE coverage attached non-enumerably to a streamed event. */
+export function sessionEventStreamCoveredThrough(event: SessionEvent): number | null {
+  const covered = (event as SessionEvent & { [SESSION_EVENT_STREAM_COVERAGE]?: unknown })[
+    SESSION_EVENT_STREAM_COVERAGE
+  ];
+  return typeof covered === "number" && Number.isSafeInteger(covered) && covered >= event.sequence
+    ? covered
+    : null;
+}
+
+function trustedSseSequence(id: string | undefined, sequence: number): number {
+  if (id === undefined || !/^\d+$/.test(id)) return sequence;
+  const covered = Number(id);
+  return Number.isSafeInteger(covered) && covered >= sequence ? covered : sequence;
+}
+
+function markSessionEventStreamCoverage(event: SessionEvent, covered: number): void {
+  Object.defineProperty(event, SESSION_EVENT_STREAM_COVERAGE, {
+    value: covered,
+    enumerable: false,
+    configurable: false,
+    writable: false,
+  });
 }
 
 async function sleep(delayMs: number, signal: AbortSignal | undefined): Promise<void> {

package/src/tenant-workspaces.ts

@@ -0,0 +1,148 @@
+import type { OpenGeniEmbeddingClient } from "./embedding-client";
+import type { Permission } from "./types";
+import { OpenGeniApiError } from "./errors";
+import { uuidV5 } from "./chat/ids";
+
+const ISOLATION_NAMESPACE = "fc398712-b4db-5b0b-8842-57cb4f2a65f9";
+/**
+ * Conversation-only member permissions. The API grants exactly this set when
+ * an organization key first acts as a user on a workspace (keep equal to
+ * `EXTERNAL_FIRST_USE_MEMBER_PERMISSIONS` in `packages/core/src/access`).
+ */
+const CONVERSATION_PERMISSIONS = [
+  "workspace:read",
+  "sessions:create",
+  "sessions:read",
+  "sessions:control",
+  "files:upload",
+  "files:read",
+  "mcp_servers:attach",
+] as const;
+
+export type WorkspaceIdTarget = {
+  /**
+   * Your tenant id. With user isolation and no tenant, the user gets one
+   * workspace of their own, independent of any tenant.
+   */
+  tenant?: string | undefined;
+  user?: string | undefined;
+  /** External user identity source; defaults to the resolver's source. */
+  source?: string | undefined;
+};
+
+export type WorkspaceIdOptions = {
+  /**
+   * `tenant`: one workspace per tenant. `user`: a separate workspace for the
+   * user (per tenant when a tenant is given, otherwise one per user).
+   */
+  isolation: "tenant" | "user";
+};
+
+export type WorkspaceIdResolverOptions = {
+  /** The organization id, or a lazy lookup (for example derived from the API key). */
+  organizationId: string | (() => Promise<string>);
+  source: string;
+  /** Workspace display name; receives the tenant id, or the user id for a per-user workspace. */
+  workspaceName?: ((tenant: string) => string) | undefined;
+  /**
+   * Per-user workspaces only (user isolation): permissions for the one member
+   * this resolver adds explicitly, its owner. Replaces the defaults: workspace
+   * read, session create/read/control (including sending messages), file
+   * upload/read, and attaching the host's per-session MCP servers. No admin
+   * permissions are granted by default. Tenant workspaces rely on the API,
+   * which adds a missing member with those defaults on their first request.
+   * Existing grants are never changed here; change them with
+   * `updateExternalWorkspaceMember`. The organization API key must also allow
+   * the selected permissions.
+   */
+  memberPermissions?: readonly Permission[] | undefined;
+};
+
+/**
+ * Server-only workspace resolution using external workspace provisioning.
+ * Workspaces are created on first use and cached. A tenant workspace's members
+ * are added by the API on their first `asUser` request (the organization key
+ * needs `members:manage`). A per-user workspace stays single-user: the API
+ * never auto-admits anyone there, and this resolver adds its owner with a
+ * stable onboarding key, so retries never restore a revoked grant.
+ */
+export function createWorkspaceIdResolver(
+  client: Pick<OpenGeniEmbeddingClient, "ensureWorkspace" | "addExternalWorkspaceMember">,
+  options: WorkspaceIdResolverOptions,
+): (target: WorkspaceIdTarget, resolution: WorkspaceIdOptions) => Promise<string> {
+  const memberPermissions = [...(options.memberPermissions ?? CONVERSATION_PERMISSIONS)];
+  const cache = new Map<string, Promise<string>>();
+  const organizationId = async () =>
+    typeof options.organizationId === "function"
+      ? await options.organizationId()
+      : options.organizationId;
+  return async (target, resolution) => {
+    const isolated = resolution.isolation === "user";
+    if (!isolated && !target.tenant) throw new TypeError("workspaceIdFor requires a tenant.");
+    if (isolated && !target.user) {
+      throw new TypeError("User isolation requires an authenticated product user.");
+    }
+    const source = target.source ?? options.source;
+    // A per-user workspace without a tenant has its own key shape, so it can
+    // never alias a tenant-scoped isolated workspace.
+    const key = target.tenant
+      ? JSON.stringify([
+          resolution.isolation,
+          options.source,
+          source,
+          target.tenant,
+          isolated ? target.user : null,
+        ])
+      : JSON.stringify(["user", options.source, source, target.user]);
+    let pending = cache.get(key);
+    if (!pending) {
+      pending = (async () => {
+        const productSource = options.source.trim();
+        const isolatedSource = `opengeni-sdk:user-isolation:${await uuidV5(productSource, ISOLATION_NAMESPACE)}`;
+        const label = target.tenant ?? target.user!;
+        const { workspace } = await client.ensureWorkspace({
+          accountId: await organizationId(),
+          externalSource: isolated
+            ? isolatedSource === productSource
+              ? `${isolatedSource}:user`
+              : isolatedSource
+            : options.source,
+          externalId: isolated ? await uuidV5(key, ISOLATION_NAMESPACE) : target.tenant!,
+          name: options.workspaceName?.(label) ?? label,
+        });
+        if (isolated) {
+          try {
+            await client.addExternalWorkspaceMember(workspace.id, {
+              identity: { source, externalId: target.user! },
+              permissions: [...memberPermissions],
+              operationId: await uuidV5(
+                JSON.stringify(["member", workspace.id, source, target.user]),
+                ISOLATION_NAMESPACE,
+              ),
+            });
+          } catch (error) {
+            // Defaults/custom permissions may have changed since this stable
+            // onboarding key committed, or the grant may have been cancelled.
+            // A definitive conflict must never mint a new key or update access.
+            // Return only the address: every asUser operation still checks the
+            // live membership, including reduced or withdrawn permissions.
+            if (
+              !(error instanceof OpenGeniApiError) ||
+              error.status !== 409 ||
+              error.code !== "conflict" ||
+              error.outcomeUnknown
+            )
+              throw error;
+          }
+        }
+        return workspace.id;
+      })();
+      pending.catch(() => {
+        if (cache.get(key) === pending) cache.delete(key);
+      });
+      if (cache.size >= 1_000) cache.delete(cache.keys().next().value!);
+      cache.set(key, pending);
+    }
+    return await pending;
+  };
+}

package/src/tool-auth.ts

@@ -0,0 +1,301 @@
+/**
+ * Per-user credentials for a product's own MCP tool server.
+ *
+ * `createSessionProxyHandler({ toolServer })` mints a short-lived token for the
+ * user its `resolve` hook authenticated, attaches it to each session it creates,
+ * and refreshes it on every message, approval, and answer. The product's MCP
+ * endpoint calls {@link verifyToolRequest} on every request and scopes all data
+ * access to the returned identity, never to ids the model supplied.
+ *
+ * Wire format (for non-Node verifiers): an HS256 JWT in `Authorization: Bearer`,
+ * signed with the hex key from {@link deriveToolTokenKey} (`HMAC-SHA256(key =
+ * secret, message = "opengeni-tool-token:v1")`, where `secret` is
+ * `OPENGENI_API_KEY` unless configured). Give a non-Node verifier that derived
+ * key, never the organization key. Claims: `iss` = `"opengeni-session-proxy"`,
+ * `aud` = the tool server URL, `sub` = the external user id, `workspace_id`,
+ * `source`, optional `tenant`, `iat`, `exp`.
+ */
+
+/** `iss` of every tool token. */
+export const TOOL_TOKEN_ISSUER = "opengeni-session-proxy";
+/** HMAC message used to derive the signing key from the secret. */
+export const TOOL_TOKEN_KEY_LABEL = "opengeni-tool-token:v1";
+/** Default token lifetime: 24 hours, refreshed on every message, approval, and answer. */
+export const TOOL_TOKEN_DEFAULT_TTL_SECONDS = 24 * 60 * 60;
+const MAX_TTL_SECONDS = 7 * 24 * 60 * 60;
+/** Opengeni's per-value limit for session MCP credential headers. */
+const MAX_HEADER_VALUE_LENGTH = 4096;
+/** Default `toolServer.url` and `verifyToolRequest` audience. */
+export const TOOL_SERVER_URL_ENV = "OPENGENI_TOOL_SERVER_URL";
+const CLOCK_SKEW_SECONDS = 60;
+
+/** The user a verified tool request acts for. */
+export type ToolRequestIdentity = {
+  /** External user id the session proxy's `resolve` hook authenticated. */
+  user: string;
+  /** Tenant from `resolve`, when it returned one. */
+  tenant?: string | undefined;
+  workspaceId: string;
+  /** External identity source (same as the proxy's `asUser` source). */
+  source: string;
+  expiresAt: Date;
+};
+
+export type VerifyToolRequestOptions = {
+  /** Signing secret. Defaults to `OPENGENI_API_KEY`; must match the proxy's. */
+  secret?: string | undefined;
+  /**
+   * Exact tool server URL the token must be issued for (the proxy's
+   * `toolServer.url`). Defaults to `OPENGENI_TOOL_SERVER_URL`.
+   */
+  audience?: string | undefined;
+};
+
+/** A Web `Request`, or a Node/Express request (`headers` plus `originalUrl`/`url`). */
+export type ToolRequestLike =
+  | Request
+  | {
+      headers: Record<string, string | string[] | undefined>;
+      originalUrl?: string | undefined;
+      url?: string | undefined;
+    };
+
+/** Missing, expired, forged, or misdirected tool token. Respond with `status` (401). */
+export class ToolRequestError extends Error {
+  readonly status = 401;
+  constructor(readonly code: string) {
+    super("Tool request is not authorized.");
+    this.name = "ToolRequestError";
+  }
+  /** A ready 401 response with a `WWW-Authenticate: Bearer` challenge. */
+  toResponse(): Response {
+    return new Response(JSON.stringify({ error: { code: this.code, message: this.message } }), {
+      status: 401,
+      headers: {
+        "Content-Type": "application/json; charset=utf-8",
+        "WWW-Authenticate": 'Bearer error="invalid_token"',
+      },
+    });
+  }
+}
+
+/**
+ * Verify the tool token on one MCP request and return who it acts for.
+ * Throws {@link ToolRequestError} (401) for every invalid token. Call it on
+ * every request, before any tool runs.
+ *
+ * ```ts
+ * const user = await verifyToolRequest(request); // { user, tenant, workspaceId }
+ * ```
+ */
+export async function verifyToolRequest(
+  request: ToolRequestLike,
+  options: VerifyToolRequestOptions = {},
+): Promise<ToolRequestIdentity> {
+  const key = await signingKey(resolveToolTokenSecret(options.secret));
+  const audience = options.audience ?? environment(TOOL_SERVER_URL_ENV);
+  if (!audience) {
+    throw new TypeError(
+      `verifyToolRequest needs the tool server URL: pass { audience } or set ${TOOL_SERVER_URL_ENV}.`,
+    );
+  }
+  const authorization = requestAuthorization(request);
+  const match = /^Bearer[ ]+([A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+)$/i.exec(
+    authorization?.trim() ?? "",
+  );
+  if (!match) throw new ToolRequestError("token_missing");
+  const [header, payload, signature] = match[1]!.split(".") as [string, string, string];
+  let protectedHeader: unknown;
+  let claims: Record<string, unknown>;
+  let signatureBytes: Uint8Array<ArrayBuffer>;
+  try {
+    signatureBytes = base64UrlDecode(signature);
+    protectedHeader = JSON.parse(utf8(base64UrlDecode(header)));
+    claims = JSON.parse(utf8(base64UrlDecode(payload)));
+  } catch {
+    throw new ToolRequestError("token_malformed");
+  }
+  if (
+    !protectedHeader ||
+    typeof protectedHeader !== "object" ||
+    (protectedHeader as { alg?: unknown }).alg !== "HS256" ||
+    !claims ||
+    typeof claims !== "object" ||
+    Array.isArray(claims)
+  ) {
+    throw new ToolRequestError("token_malformed");
+  }
+  const valid = await crypto.subtle.verify(
+    "HMAC",
+    key,
+    signatureBytes,
+    new TextEncoder().encode(`${header}.${payload}`),
+  );
+  if (!valid) throw new ToolRequestError("token_invalid");
+  const now = Math.floor(Date.now() / 1000);
+  const { iss, aud, sub, exp, iat, workspace_id, source, tenant } = claims;
+  if (iss !== TOOL_TOKEN_ISSUER) throw new ToolRequestError("token_invalid");
+  if (typeof exp !== "number" || exp <= now) throw new ToolRequestError("token_expired");
+  if (typeof iat !== "number" || iat > now + CLOCK_SKEW_SECONDS) {
+    throw new ToolRequestError("token_invalid");
+  }
+  if (aud !== audience) {
+    throw new ToolRequestError("token_audience");
+  }
+  if (
+    typeof sub !== "string" ||
+    !sub ||
+    typeof workspace_id !== "string" ||
+    !workspace_id ||
+    typeof source !== "string" ||
+    (tenant !== undefined && typeof tenant !== "string")
+  ) {
+    throw new ToolRequestError("token_invalid");
+  }
+  return {
+    user: sub,
+    ...(tenant !== undefined ? { tenant } : {}),
+    workspaceId: workspace_id,
+    source,
+    expiresAt: new Date(exp * 1000),
+  };
+}
+
+/** Mint one tool token. The session proxy calls this; products rarely need to. */
+export async function mintToolToken(input: {
+  /** Tool server URL; becomes `aud`. */
+  audience: string;
+  user: string;
+  tenant?: string | undefined;
+  workspaceId: string;
+  source: string;
+  secret?: string | undefined;
+  ttlSeconds?: number | undefined;
+}): Promise<string> {
+  const ttl = input.ttlSeconds ?? TOOL_TOKEN_DEFAULT_TTL_SECONDS;
+  if (!Number.isSafeInteger(ttl) || ttl < 1 || ttl > MAX_TTL_SECONDS) {
+    throw new TypeError(`ttlSeconds must be an integer from 1 to ${MAX_TTL_SECONDS}.`);
+  }
+  const key = await signingKey(resolveToolTokenSecret(input.secret));
+  const now = Math.floor(Date.now() / 1000);
+  const header = base64UrlJson({ alg: "HS256", typ: "JWT" });
+  const payload = base64UrlJson({
+    iss: TOOL_TOKEN_ISSUER,
+    aud: input.audience,
+    sub: input.user,
+    workspace_id: input.workspaceId,
+    source: input.source,
+    ...(input.tenant !== undefined ? { tenant: input.tenant } : {}),
+    iat: now,
+    exp: now + ttl,
+  });
+  const signature = await crypto.subtle.sign(
+    "HMAC",
+    key,
+    new TextEncoder().encode(`${header}.${payload}`),
+  );
+  const token = `${header}.${payload}.${base64UrlEncode(new Uint8Array(signature))}`;
+  if (`Bearer ${token}`.length > MAX_HEADER_VALUE_LENGTH) {
+    throw new TypeError(
+      `Tool token exceeds Opengeni's ${MAX_HEADER_VALUE_LENGTH}-character header limit; shorten the user, tenant, or URL.`,
+    );
+  }
+  return token;
+}
+
+/**
+ * The hex HS256 key tool tokens are signed with. Give this (not the
+ * organization key) to a tool server written in Python, Ruby, Go, and so on.
+ */
+export async function deriveToolTokenKey(secret?: string): Promise<string> {
+  return [...(await derivedKeyBytes(resolveToolTokenSecret(secret)))]
+    .map((byte) => byte.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+/** The configured secret, else `OPENGENI_API_KEY`. Throws when neither is set. */
+export function resolveToolTokenSecret(secret: string | undefined): string {
+  const resolved = secret ?? environment("OPENGENI_API_KEY");
+  if (!resolved) {
+    throw new TypeError(
+      "Tool tokens need a signing secret: set OPENGENI_API_KEY, or pass the same `secret` to the session proxy's toolServer and verifyToolRequest.",
+    );
+  }
+  return resolved;
+}
+
+function environment(name: string): string | undefined {
+  return (
+    (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env?.[
+      name
+    ] || undefined
+  );
+}
+
+async function derivedKeyBytes(secret: string): Promise<Uint8Array<ArrayBuffer>> {
+  const root = await crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+  return new Uint8Array(
+    await crypto.subtle.sign("HMAC", root, new TextEncoder().encode(TOOL_TOKEN_KEY_LABEL)),
+  );
+}
+
+const keys = new Map<string, Promise<CryptoKey>>();
+
+/** HS256 key derived from the secret, so the raw secret never signs tokens itself. */
+function signingKey(secret: string): Promise<CryptoKey> {
+  let key = keys.get(secret);
+  if (!key) {
+    key = (async () =>
+      await crypto.subtle.importKey(
+        "raw",
+        await derivedKeyBytes(secret),
+        { name: "HMAC", hash: "SHA-256" },
+        false,
+        ["sign", "verify"],
+      ))();
+    key.catch(() => keys.delete(secret));
+    if (keys.size >= 16) keys.delete(keys.keys().next().value!);
+    keys.set(secret, key);
+  }
+  return key;
+}
+
+function requestAuthorization(request: ToolRequestLike): string | undefined {
+  if (typeof Request !== "undefined" && request instanceof Request) {
+    return request.headers.get("authorization") ?? undefined;
+  }
+  const headers = (request as Exclude<ToolRequestLike, Request>).headers as unknown;
+  const raw =
+    headers && typeof (headers as Headers).get === "function"
+      ? ((headers as Headers).get("authorization") ?? undefined)
+      : (headers as Record<string, string | string[] | undefined>)?.authorization;
+  return Array.isArray(raw) ? undefined : raw;
+}
+
+function base64UrlJson(value: unknown): string {
+  return base64UrlEncode(new TextEncoder().encode(JSON.stringify(value)));
+}
+
+function base64UrlEncode(bytes: Uint8Array): string {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+function base64UrlDecode(value: string): Uint8Array<ArrayBuffer> {
+  const base64 = value.replace(/-/g, "+").replace(/_/g, "/");
+  const binary = atob(base64 + "=".repeat((4 - (base64.length % 4)) % 4));
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0; index < binary.length; index += 1) bytes[index] = binary.charCodeAt(index);
+  return bytes;
+}
+
+function utf8(bytes: Uint8Array): string {
+  return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+}

package/src/tool-display-metadata.ts

@@ -0,0 +1,27 @@
+import type { ToolDisplayMetadata } from "@opengeni/contracts";
+
+/** Browser/native-safe event projection; do not import server schema runtimes. */
+export function parseToolDisplayMetadata(value: unknown): ToolDisplayMetadata | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const item = value as Record<string, unknown>;
+  if (
+    Object.keys(item).some(
+      (key) => !["toolName", "title", "accountLabel", "connector", "providerDomain"].includes(key),
+    )
+  )
+    return undefined;
+  const text = (v: unknown, max: number): v is string =>
+    typeof v === "string" && v.length > 0 && v.length <= max;
+  if (!text(item.toolName, 512) || /[\u0000-\u001f\u007f]/u.test(item.toolName)) return undefined;
+  if (item.title !== undefined && !text(item.title, 512)) return undefined;
+  if (item.accountLabel !== undefined && !text(item.accountLabel, 1024)) return undefined;
+  if (item.connector !== undefined && !text(item.connector, 512)) return undefined;
+  if (item.providerDomain !== undefined && !text(item.providerDomain, 253)) return undefined;
+  return {
+    toolName: item.toolName,
+    ...(item.title !== undefined ? { title: item.title as string } : {}),
+    ...(item.accountLabel !== undefined ? { accountLabel: item.accountLabel as string } : {}),
+    ...(item.connector !== undefined ? { connector: item.connector as string } : {}),
+    ...(item.providerDomain !== undefined ? { providerDomain: item.providerDomain as string } : {}),
+  };
+}