@opengeni/sdk 3.1.0 → 3.1.2

package/src/chat/types.ts

@@ -0,0 +1,219 @@
+import type { FetchLike } from "../client";
+import type { Chats } from "../chats";
+import type { WorkspaceIdResolverOptions } from "../tenant-workspaces";
+import type {
+  CreateSessionRequest,
+  AgentConfigRequest,
+  HumanInputAnswer,
+  LatencyMode,
+  ReasoningEffort,
+  SessionEvent,
+  Session,
+  SessionSkill,
+  ToolRef,
+} from "../types";
+
+/** Which other sessions the agent may reach from this one. */
+export type ChatAgentAccess = "session" | "user" | "workspace";
+
+/**
+ * Compatibility option for personal or workspace Knowledge. `false` initializes
+ * Knowledge authoring to Off; authorized retrieval remains available. Omitted
+ * follows `chats`: private with a user, or legacy reach-based defaults without one.
+ * Task notes cover temporary session-tree data.
+ */
+export type ChatMemory = "user" | "workspace" | false;
+
+export type OpenGeniOptions = {
+  /** Organization API key. Keep it on the server. */
+  apiKey: string;
+  /**
+   * The organization (account) id that owns every workspace. Optional: when
+   * omitted it is read once from the API key.
+   */
+  organizationId?: string | undefined;
+  /** Defaults to `https://app.opengeni.ai`. */
+  baseUrl?: string | undefined;
+  /**
+   * The product identity used as the external-source label for tenant
+   * workspaces and end users. Defaults to `"app"`.
+   */
+  source?: string | undefined;
+  fetch?: FetchLike | undefined;
+  /** Display name for a tenant workspace created on first use. Defaults to the tenant id. */
+  workspaceName?: ((tenant: string) => string) | undefined;
+  /**
+   * Per-user workspaces only (`{ user }` alone, or `chats: "isolated"`):
+   * permissions for the one owner the SDK adds explicitly. Tenant workspaces
+   * rely on Opengeni, which adds a user on their first request. Both default
+   * to workspace read, session create/read/control (including sending
+   * messages), file upload/read, and per-session MCP attachment; no admin
+   * permissions. Never updates an existing membership: use
+   * `client.updateExternalWorkspaceMember` for that.
+   */
+  memberPermissions?: WorkspaceIdResolverOptions["memberPermissions"];
+};
+
+/**
+ * Which workspace, in your own ids: `tenant` (one workspace per tenant),
+ * neither (the `user`'s own workspace), or an explicit `workspaceId`.
+ */
+export type ChatTarget =
+  | { tenant: string; workspaceId?: undefined }
+  | { workspaceId: string; tenant?: undefined }
+  | { user: string; tenant?: undefined; workspaceId?: undefined };
+
+/**
+ * A workspace in your own ids, for `og.workspaceId(...)`: `{ tenant }` (one
+ * workspace per tenant), `{ user }` (one workspace per user), or
+ * `{ workspaceId }`. Precedence: workspaceId, then tenant, then user.
+ */
+export type WorkspaceTarget = {
+  tenant?: string | undefined;
+  user?: string | undefined;
+  workspaceId?: string | undefined;
+};
+
+export type ChatOptions = ChatTarget & {
+  /**
+   * Host-authenticated external user; resolved through server-side asUser().
+   * Without a tenant or workspaceId, the user gets one workspace of their own.
+   */
+  user?: string | undefined;
+  /** Stable conversation id; the session id is derived from it deterministically. */
+  conversation: string;
+  /** Prefer the actual Opengeni session ID for shared or existing conversations.
+   * The acting user is independent of the conversation's identity. */
+  sessionId?: string | undefined;
+  /**
+   * Private (default with a user) uses personal Knowledge and session-only reach;
+   * shared uses workspace Knowledge/reach, isolated adds a workspace per tenant/user.
+   * Without a user, omission keeps workspace visibility, session reach and Knowledge off.
+   */
+  chats?: Chats | undefined;
+  /** Agent identity, capabilities and instructions; implicit markdown falls back on older servers. */
+  agent?: AgentConfigRequest | undefined;
+  /** Explicit agent reach overrides the `chats` default. */
+  agentAccess?: ChatAgentAccess | undefined;
+  memory?: ChatMemory | undefined;
+  model?: string | undefined;
+  instructions?: string | undefined;
+  skills?: SessionSkill[] | undefined;
+  tools?: ToolRef[] | undefined;
+  /**
+   * Raw create-request passthrough (for example `sandboxBackend: "none"` for a
+   * pure chat). Explicit values win over facade-derived ones; the message and
+   * identity/idempotency fields always come from the facade.
+   */
+  create?: Partial<CreateSessionRequest> | undefined;
+};
+
+/** A turn stopped to wait for a human decision. */
+export type ChatPending = {
+  kind: "approval" | "human_input";
+  /** The id to pass back through `chat.respond`. */
+  requestId: string;
+  /** Tool name for an approval; null for structured human input. */
+  name: string | null;
+  /** The producer's exact payload (approval entry or human-input request). */
+  payload: unknown;
+};
+
+export type ChatReplyStatus = "completed" | "pending" | "cancelled";
+
+export type ChatReply = {
+  text: string;
+  sessionId: string;
+  workspaceId: string;
+  turnId: string | null;
+  /** `pending` waits on `chat.respond`; `cancelled` carries the text produced before the cancel. */
+  status: ChatReplyStatus;
+  /** Set when the turn is waiting on `chat.respond` instead of finished. */
+  pending: ChatPending | null;
+  /** A non-destructive completion without a model-authored final answer. */
+  emptyFinalReply?: true;
+  /** Display this informational notice when emptyFinalReply is present. */
+  notice?: string;
+  /** Every event consumed while folding this turn. */
+  events: SessionEvent[];
+  toString(): string;
+};
+
+export type ChatToolStatus = "started" | "completed" | "failed";
+
+export type ChatChunk =
+  | { type: "text"; text: string }
+  | {
+      type: "tool";
+      name: string;
+      status: ChatToolStatus;
+      callId?: string | undefined;
+      input?: unknown;
+    }
+  | { type: "pending"; pending: ChatPending }
+  | { type: "done"; reply: ChatReply };
+
+export type ChatMessage = {
+  role: "user" | "assistant";
+  text: string;
+  sequence: number;
+};
+
+/** Durable text and unresolved decisions restored when a chat is reopened. */
+export type ChatSnapshot = {
+  messages: ChatMessage[];
+  pending: ChatPending[];
+  status: Session["status"] | null;
+};
+
+export type ChatRespondInput =
+  | { requestId: string; decision: "approve" | "reject"; message?: string | undefined }
+  | { requestId: string; answers: HumanInputAnswer[] }
+  | { requestId: string; skip: true };
+
+/** One earlier message from the product's own history, imported as context on the first send. */
+export type ChatImportedMessage = { role: "user" | "assistant" | "system"; text: string };
+
+export type ChatSendOptions = {
+  signal?: AbortSignal | undefined;
+  /** Supersede the current inference instead of queueing behind it. */
+  steer?: boolean | undefined;
+  /**
+   * Earlier messages the product already holds, oldest first. Used only when
+   * this send creates the session: they become the first message's
+   * `modelContext` (skipped when `create.modelContext` was supplied), trimmed
+   * from the oldest end to 30,000 characters. Never resent on later turns:
+   * after the first message Opengeni owns the history.
+   */
+  importedHistory?: ChatImportedMessage[] | undefined;
+  /** Model for this message's turn; omitted keeps the session's current policy. */
+  model?: string | undefined;
+  reasoningEffort?: ReasoningEffort | undefined;
+  latencyMode?: LatencyMode | undefined;
+  /**
+   * Model-visible application context for this one message (for example the
+   * page or record the user is looking at). Not shown in the transcript and not
+   * secret. On the creating message it is combined with imported history.
+   */
+  modelContext?: string | undefined;
+};
+
+export type ChatSessionListOptions = ChatTarget & {
+  user?: string | undefined;
+  /** Match the chat's mode; isolated lists that user's separate workspace. */
+  chats?: Chats | undefined;
+  limit?: number | undefined;
+};
+
+/** A turn ended without a usable reply, or the facade was misused. */
+export class OpenGeniChatError extends Error {
+  readonly code: string;
+  readonly event: SessionEvent | null;
+
+  constructor(code: string, message: string, event: SessionEvent | null = null) {
+    super(message);
+    this.name = "OpenGeniChatError";
+    this.code = code;
+    this.event = event;
+  }
+}

package/src/chat/vercel.ts

@@ -0,0 +1,204 @@
+import { asRecord } from "./fold";
+import {
+  chatErrorSummary,
+  clientConversation,
+  errorResponse,
+  importedHistoryBefore,
+  lastUserMessageText,
+  openResolvedChat,
+  readJsonObject,
+  resolveChatRequest,
+  sseByteStream,
+  sseHeaders,
+  sseLine,
+  type ChatResolve,
+} from "./http";
+import type { Opengeni } from "./opengeni";
+import type { ChatChunk, ChatPending } from "./types";
+
+/**
+ * Vercel AI SDK UI message stream (protocol v1, as consumed by `useChat` with
+ * the default transport in AI SDK 5, 6, and 7; approval requests need 6+).
+ * Parts are `data: <json>` SSE
+ * lines terminated by `data: [DONE]`, under the
+ * `x-vercel-ai-ui-message-stream: v1` header.
+ */
+
+export const UI_MESSAGE_STREAM_HEADER = "x-vercel-ai-ui-message-stream";
+export const UI_MESSAGE_STREAM_VERSION = "v1";
+
+export type UIMessageStreamOptions = {
+  /** Assistant message id announced in the `start` part. Defaults to a random UUID. */
+  messageId?: string | undefined;
+  /**
+   * Emit Opengeni's own tool activity as tool parts. Off by default: those
+   * tools are not in the app's typed tool set. When on, parts are marked
+   * `dynamic` and `providerExecuted`, so `useChat` renders them as
+   * `dynamic-tool` parts and never tries to execute them. Approval requests
+   * are always emitted (as dynamic tool parts) because answering them is part
+   * of the conversation.
+   */
+  toolParts?: boolean | undefined;
+  /**
+   * Emit the `start` / `start-step` / `finish-step` / `finish` framing. Set to
+   * false when writing into an existing AI SDK stream that owns its framing
+   * (for example `createUIMessageStream({ execute: ({ writer }) => ... })`).
+   * Defaults to true.
+   */
+  framing?: boolean | undefined;
+};
+
+/** Protocol parts for one reply, in order. */
+export async function* uiMessageStreamParts(
+  chunks: AsyncIterable<ChatChunk>,
+  options: UIMessageStreamOptions = {},
+): AsyncGenerator<Record<string, unknown>, void, void> {
+  const messageId = options.messageId ?? crypto.randomUUID();
+  const textId = `text_${messageId}`;
+  let textOpen = false;
+  const closeText = (): Record<string, unknown>[] => {
+    if (!textOpen) return [];
+    textOpen = false;
+    return [{ type: "text-end", id: textId }];
+  };
+  const framing = options.framing ?? true;
+  if (framing) {
+    yield { type: "start", messageId };
+    yield { type: "start-step" };
+  }
+  try {
+    for await (const chunk of chunks) {
+      switch (chunk.type) {
+        case "text":
+          if (!textOpen) {
+            textOpen = true;
+            yield { type: "text-start", id: textId };
+          }
+          yield { type: "text-delta", id: textId, delta: chunk.text };
+          break;
+        case "tool": {
+          if (!options.toolParts) break;
+          yield* closeText();
+          const toolCallId = chunk.callId ?? `call_${crypto.randomUUID()}`;
+          const tool = { toolCallId, dynamic: true, providerExecuted: true };
+          if (chunk.status === "started") {
+            yield { type: "tool-input-start", ...tool, toolName: chunk.name };
+            yield {
+              type: "tool-input-available",
+              ...tool,
+              toolName: chunk.name,
+              input: chunk.input ?? {},
+            };
+          } else if (chunk.status === "failed") {
+            yield { type: "tool-output-error", ...tool, errorText: "The tool call failed." };
+          } else {
+            yield { type: "tool-output-available", ...tool, output: { status: chunk.status } };
+          }
+          break;
+        }
+        case "pending":
+          yield* closeText();
+          yield* pendingParts(chunk.pending);
+          break;
+        case "done":
+          yield* closeText();
+          break;
+      }
+    }
+    yield* closeText();
+    if (framing) {
+      yield { type: "finish-step" };
+      yield { type: "finish" };
+    }
+  } catch (error) {
+    yield* closeText();
+    yield { type: "error", errorText: chatErrorSummary(error).message };
+  }
+}
+
+function* pendingParts(pending: ChatPending): Generator<Record<string, unknown>> {
+  if (pending.kind === "approval") {
+    const raw = asRecord(pending.payload);
+    const rawItem = asRecord(raw.rawItem);
+    yield {
+      type: "tool-input-available",
+      toolCallId: pending.requestId,
+      toolName: pending.name ?? "tool",
+      dynamic: true,
+      providerExecuted: true,
+      input: raw.arguments ?? rawItem.arguments ?? {},
+    };
+    yield {
+      type: "tool-approval-request",
+      toolCallId: pending.requestId,
+      approvalId: pending.requestId,
+    };
+    return;
+  }
+  yield { type: "data-opengeni-pending", data: pending };
+}
+
+export async function* uiMessageStreamBlocks(
+  chunks: AsyncIterable<ChatChunk>,
+  options: UIMessageStreamOptions = {},
+): AsyncGenerator<string, void, void> {
+  for await (const part of uiMessageStreamParts(chunks, options)) {
+    yield sseLine(JSON.stringify(part));
+  }
+  yield sseLine("[DONE]");
+}
+
+export function chatChunksToUIMessageStream(
+  chunks: AsyncIterable<ChatChunk>,
+  options: UIMessageStreamOptions & { onCancel?: (() => void) | undefined } = {},
+): ReadableStream<Uint8Array> {
+  return sseByteStream(uiMessageStreamBlocks(chunks, options), options.onCancel);
+}
+
+export function uiMessageStreamResponse(
+  chunks: AsyncIterable<ChatChunk>,
+  options: UIMessageStreamOptions = {},
+): Response {
+  return new Response(chatChunksToUIMessageStream(chunks, options), {
+    headers: sseHeaders({ [UI_MESSAGE_STREAM_HEADER]: UI_MESSAGE_STREAM_VERSION }),
+  });
+}
+
+/** Text of the last user `UIMessage` (`parts` of type `text`, joined). */
+export function lastUIMessageText(messages: unknown): string | null {
+  return lastUserMessageText(messages, ["text"], "parts");
+}
+
+/**
+ * `useChat` request handler: body `{ id, messages, trigger, messageId }`.
+ * Conversation: the host's `resolve`, else the `x-opengeni-conversation`
+ * header, else the chat `id`. Only the last user message is sent; the
+ * messages before it are imported once as context when this request creates
+ * the session. `regenerate-message` steers instead of queueing.
+ */
+export async function handleVercelChatRequest(
+  og: Opengeni,
+  request: Request,
+  resolve: ChatResolve,
+  options: Pick<UIMessageStreamOptions, "toolParts"> = {},
+): Promise<Response> {
+  const body = await readJsonObject(request);
+  const prompt = lastUIMessageText(body?.messages)?.trim() ?? "";
+  if (!prompt) {
+    return errorResponse(400, "The last user message has no text.", "message_required");
+  }
+  const resolved = await resolveChatRequest(request, resolve);
+  if (resolved.response) return resolved.response;
+  const opened = await openResolvedChat(
+    og,
+    resolved.resolution,
+    clientConversation(request, body?.id),
+  );
+  if (opened.response) return opened.response;
+  const steer = body?.trigger === "regenerate-message";
+  const importedHistory = importedHistoryBefore(body?.messages, ["text"], "parts");
+  return uiMessageStreamResponse(
+    opened.chat.stream(prompt, { signal: request.signal, steer, importedHistory }),
+    options.toolParts ? { toolParts: true } : {},
+  );
+}

package/src/chats.ts

@@ -0,0 +1,16 @@
+import type { CreateSessionRequest } from "./types";
+
+/**
+ * Private chats use personal Knowledge and session-only agent reach; shared chats
+ * use workspace Knowledge and reach. Isolated adds a separate workspace per user.
+ */
+export type Chats = "private" | "shared" | "isolated";
+
+/** SDK defaults only: the API still authorizes visibility, agent reach and Knowledge separately. */
+export function chatDefaults(
+  chats: Chats,
+): Required<Pick<CreateSessionRequest, "visibility" | "agentAccess" | "memoryScope">> {
+  return chats === "shared"
+    ? { visibility: "workspace", agentAccess: "workspace", memoryScope: "workspace" }
+    : { visibility: "private", agentAccess: "session", memoryScope: "user" };
+}