@opengeni/sdk 0.29.0 → 0.32.1

package/dist/mcp-output.d.ts

@@ -0,0 +1,15 @@
+/**
+ * A transport-tolerant MCP tool result.
+ *
+ * `value` is the canonical machine-readable payload after recognized MCP/JSON
+ * envelopes are removed. `text` is the best presentation string without
+ * discarding structured data. `raw` always retains the original evidence.
+ */
+export type NormalizedMcpOutput = Readonly<{
+    raw: unknown;
+    value: unknown;
+    text: string;
+    isError: boolean;
+}>;
+/** Normalize common direct, JSON, and standard MCP result envelopes without throwing. */
+export declare function normalizeMcpOutput(output: unknown): NormalizedMcpOutput;

package/dist/preference-registry.d.ts

@@ -0,0 +1,169 @@
+export type PreferenceRegistryScope = "organization" | "workspace" | "user";
+export type PreferenceRegistryStatus = "proposed" | "active" | "inactive" | "rejected" | "superseded" | "expired";
+export type PreferenceRegistryProvenanceSource = "human" | "onboarding" | "knowledge_proposal" | "imported_document" | "slack" | "meeting_transcript" | "call_transcript";
+export type PreferenceRegistryTrust = "untrusted_proposal" | "personal" | "workspace_managed" | "organization_managed";
+export type PreferenceRegistryConflictStrategy = "override" | "merge" | "reject" | "inform";
+export declare function normalizePreferenceRegistryStableKey(value: string): string;
+export type PreferenceRegistryScopeTarget = {
+    scope: PreferenceRegistryScope;
+    workspaceId: string | null;
+    subjectId: string | null;
+};
+export type PreferenceRegistryPrecedence = {
+    tier: PreferenceRegistryScope;
+    rank: number;
+    conflictStrategy: PreferenceRegistryConflictStrategy;
+    conflictsWith: string[];
+};
+export type PreferenceRegistryRevisionSummary = {
+    id: string;
+    preferenceId: string;
+    revision: number;
+    contentHash: string;
+    title: string;
+    description: string;
+    precedence: PreferenceRegistryPrecedence;
+    provenance: {
+        source: PreferenceRegistryProvenanceSource;
+        sourceId: string | null;
+        trust: PreferenceRegistryTrust;
+    };
+    expiresAt: string | null;
+    correctsRevisionId: string | null;
+    createdBySubjectId: string;
+    createdAt: string;
+};
+export type PreferenceRegistryDescriptorProvenance = {
+    source: PreferenceRegistryProvenanceSource;
+    sourceIdHash: string | null;
+    trust: PreferenceRegistryTrust;
+};
+export type PreferenceRegistryRecord = {
+    id: string;
+    accountId: string;
+    stableKey: string;
+    target: PreferenceRegistryScopeTarget;
+    status: PreferenceRegistryStatus;
+    scopeVersion: number;
+    activationVersion: number;
+    activeRevision: PreferenceRegistryRevisionSummary | null;
+    supersededByPreferenceId: string | null;
+    createdBySubjectId: string;
+    createdAt: string;
+    updatedAt: string;
+};
+export type PreferenceRegistryEvent = {
+    id: string;
+    accountId: string;
+    preferenceId: string;
+    type: "proposal_created" | "activated" | "corrected" | "rejected" | "deactivated" | "superseded" | "scope_changed";
+    version: number;
+    oldRevisionId: string | null;
+    newRevisionId: string | null;
+    oldTarget: PreferenceRegistryScopeTarget | null;
+    newTarget: PreferenceRegistryScopeTarget | null;
+    relatedPreferenceId: string | null;
+    actorSubjectId: string;
+    reason: string;
+    createdAt: string;
+};
+export type PreferenceRegistryDescriptor = {
+    id: string;
+    stableKey: string;
+    title: string;
+    description: string;
+    scope: PreferenceRegistryScope;
+    activeVersion: number;
+    revisionId: string;
+    contentHash: string;
+    precedence: PreferenceRegistryPrecedence;
+    provenance: PreferenceRegistryDescriptorProvenance;
+    expiresAt: string | null;
+    retrievalHandle: string;
+};
+export type PreferenceRegistrySnapshot = {
+    id: string;
+    workspaceId: string;
+    sessionId: string;
+    turnId: string;
+    attemptId: string;
+    executionGeneration: number;
+    initiatingHumanSubjectId: string;
+    descriptorHash: string;
+    descriptors: PreferenceRegistryDescriptor[];
+    truncated: boolean;
+    createdAt: string;
+};
+export type PreferenceRegistryFullContent = {
+    descriptor: PreferenceRegistryDescriptor;
+    content: string;
+};
+export type CreatePreferenceRegistryProposalRequest = {
+    stableKey: string;
+    scope: PreferenceRegistryScope;
+    title: string;
+    description: string;
+    content: string;
+    precedenceRank?: number;
+    conflictStrategy?: PreferenceRegistryConflictStrategy;
+    conflictsWith?: string[];
+    expiresAt?: string | null;
+    provenanceSource?: PreferenceRegistryProvenanceSource;
+    provenanceSourceId?: string | null;
+};
+export type ActivatePreferenceRegistryRevisionRequest = {
+    revisionId: string;
+    expectedCurrentRevisionId: string | null;
+    expectedScopeVersion: number;
+    reason: string;
+};
+export type CorrectPreferenceRegistryRequest = {
+    expectedCurrentRevisionId: string;
+    expectedScopeVersion: number;
+    title: string;
+    description: string;
+    content: string;
+    precedenceRank?: number;
+    conflictStrategy?: PreferenceRegistryConflictStrategy;
+    conflictsWith?: string[];
+    expiresAt?: string | null;
+    reason: string;
+};
+export type DeactivatePreferenceRegistryRequest = {
+    expectedCurrentRevisionId: string;
+    expectedScopeVersion: number;
+    reason: string;
+};
+export type ChangePreferenceRegistryScopeRequest = {
+    scope: PreferenceRegistryScope;
+    expectedScopeVersion: number;
+    reason: string;
+};
+export type SupersedePreferenceRegistryRequest = {
+    replacementPreferenceId: string;
+    expectedCurrentRevisionId: string;
+    expectedScopeVersion: number;
+    reason: string;
+};
+export type RejectPreferenceRegistryProposalRequest = {
+    revisionId: string;
+    expectedScopeVersion: number;
+    reason: string;
+};
+export type PreferenceRegistryListOptions = {
+    scope?: PreferenceRegistryScope;
+    status?: PreferenceRegistryStatus;
+    limit?: number;
+};
+export type PreferenceRegistryListResponse = {
+    preferences: PreferenceRegistryRecord[];
+};
+export type PreferenceRegistryDetailResponse = {
+    preference: PreferenceRegistryRecord;
+    revisions: PreferenceRegistryRevisionSummary[];
+    events: PreferenceRegistryEvent[];
+};
+export type PreferenceRegistryMutationResponse = {
+    preference: PreferenceRegistryRecord;
+    event: PreferenceRegistryEvent;
+};

package/dist/proxy.d.ts

@@ -0,0 +1,64 @@
+import type { OpenGeniClient } from "./client";
+import type { StreamSessionEventsOptions } from "./stream";
+import type { SessionEvent } from "./types";
+/**
+ * Proxy-through-your-own-API helpers.
+ *
+ * The intended pattern: a customer's server consumes the OpenGeni event
+ * stream with its own API key (`client.streamEvents(...)`) and re-emits it to
+ * its browser clients over its own authenticated endpoint — the OpenGeni key
+ * never reaches the browser. The re-emitted wire format is identical to
+ * OpenGeni's own SSE stream (`id: <sequence>`, `event: <type>`,
+ * `data: <event JSON>`), so the browser side can consume it with this same
+ * SDK's streaming core (or a plain `EventSource`), including resume via
+ * `?after=` / `Last-Event-ID`.
+ */
+/** Format one event exactly as OpenGeni's API emits it over SSE. */
+export declare function formatSseEvent(event: SessionEvent): string;
+export type SseReStreamOptions = {
+    /**
+     * Emit `: ping` comment lines at this interval, keeping intermediaries from
+     * idling the connection out. Disabled when omitted.
+     */
+    heartbeatMs?: number;
+    /**
+     * Called when the downstream consumer cancels (e.g. the browser
+     * disconnected). Use it to abort the upstream OpenGeni stream — an async
+     * iterator that is mid-`await` cannot be interrupted by `return()` alone.
+     */
+    onCancel?: () => void;
+};
+/**
+ * Re-emit a stream of session events as an SSE byte stream. Pull-based, so
+ * upstream consumption follows downstream demand; cancelling the returned
+ * stream fires `onCancel` and ends the upstream iterator.
+ */
+export declare function sessionEventsToSseStream(events: AsyncIterable<SessionEvent>, options?: SseReStreamOptions): ReadableStream<Uint8Array>;
+/** Wrap an event stream in a ready-to-return SSE `Response`. */
+export declare function sessionEventsToSseResponse(events: AsyncIterable<SessionEvent>, options?: SseReStreamOptions): Response;
+/**
+ * Read the resume cursor a reconnecting SSE client sent: the `after` query
+ * parameter, or the standard `Last-Event-ID` header (the re-emitted stream
+ * sets `id:` to the sequence). Returns 0 (full replay) when absent.
+ */
+export declare function resumeSequenceFromRequest(request: Request): number;
+export type ProxySessionEventStreamOptions = Omit<StreamSessionEventsOptions, "after"> & {
+    /**
+     * Resume cursor. Pass a number, or the incoming browser `Request` to
+     * honor its `?after=` / `Last-Event-ID` automatically.
+     */
+    after?: number | Request;
+    /** See {@link SseReStreamOptions.heartbeatMs}. */
+    heartbeatMs?: number;
+};
+/**
+ * One-call proxy: consume the OpenGeni stream server-side and return an SSE
+ * `Response` for your own browser clients. Works anywhere WHATWG `Response`
+ * is the handler return type (Hono, Next.js route handlers, Bun.serve,
+ * Cloudflare Workers, ...).
+ *
+ * The upstream OpenGeni connection is torn down when the downstream client
+ * disconnects, and also when `options.signal` (e.g. the incoming request's
+ * signal) aborts.
+ */
+export declare function proxySessionEventStream(client: OpenGeniClient, workspaceId: string, sessionId: string, options?: ProxySessionEventStreamOptions): Response;

package/dist/sse.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Minimal incremental Server-Sent Events parser over a byte stream.
+ *
+ * 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.
+ */
+export type SseMessage = {
+    id?: string;
+    event?: string;
+    data: string;
+};
+export declare function parseSseStream(stream: ReadableStream<Uint8Array>): AsyncGenerator<SseMessage, void, void>;

package/dist/stream.d.ts

@@ -0,0 +1,48 @@
+import type { SessionEvent } from "./types";
+/**
+ * Transport boundary for the streaming core. The client implements it with
+ * `fetch`; unit tests script it directly.
+ */
+export type SessionEventStreamTransport = {
+    /** Open the SSE stream, replaying durable events after `after` first. */
+    openStream: (after: number, signal: AbortSignal | undefined) => Promise<ReadableStream<Uint8Array>>;
+    /** Replay durable events by sequence (`GET .../events?after=&limit=`). */
+    listEvents: (after: number, limit: number) => Promise<SessionEvent[]>;
+};
+export type StreamConnectionState = "connecting" | "live" | "reconnecting";
+export type StreamSessionEventsOptions = {
+    /** Resume after this sequence number (exclusive). Defaults to 0 (full replay). */
+    after?: number;
+    /** Aborting ends the stream gracefully (the generator returns). */
+    signal?: AbortSignal;
+    /** Reconnect on transient drops. Defaults to true. */
+    reconnect?: boolean;
+    /** Initial reconnect backoff. Defaults to 500ms. */
+    reconnectDelayMs?: number;
+    /** Backoff ceiling. Defaults to 10s. */
+    maxReconnectDelayMs?: number;
+    /**
+     * Give up after this many consecutive failed reconnect attempts (i.e. N
+     * reconnects = N+1 total open-stream calls). Defaults to unlimited.
+     */
+    maxReconnectAttempts?: number;
+    /** Await authoritative client reconciliation before exposing `live`. */
+    beforeLive?: (() => void | Promise<void>) | undefined;
+    onStateChange?: (state: StreamConnectionState) => void;
+};
+/**
+ * Stream a session's events with exactly-once, in-order delivery.
+ *
+ * Guarantees, anchored on the per-session contiguous `sequence`:
+ * - **No duplicates**: events at or below the cursor are dropped, so server
+ *   replay overlap and reconnect overlap never re-yield.
+ * - **No gaps**: each reconnect resumes from the last seen sequence, and a
+ *   gap observed inside one connection is backfilled from the durable replay
+ *   endpoint before the newer event is yielded (events are durable before
+ *   they are published live, so the backfill always finds them).
+ * - **Ordered**: sequences are yielded strictly ascending.
+ *
+ * The generator ends when `signal` aborts, when the server closes and
+ * `reconnect` is false, or with an error for non-retryable failures.
+ */
+export declare function streamSessionEvents(transport: SessionEventStreamTransport, options?: StreamSessionEventsOptions): AsyncGenerator<SessionEvent, void, void>;

package/dist/terminal.d.ts

@@ -0,0 +1,49 @@
+import type { TerminalCapability } from "./types";
+/**
+ * Translate the negotiated `pty-ws` Terminal capability into the WebSocket URL
+ * the ttyd client dials. The scoped provider token is ALREADY embedded in the
+ * minted `url` (the Modal tunnel host) by `session.resolveExposedPort(7681)` —
+ * we do NOT append `cap.token` (identical posture to the desktop: the gate is the
+ * unguessable short-TTL tunnel URL + the server-recorded scoped stream token; ttyd
+ * runs `--writable` with no `-c` credential in v1). We only normalize the scheme
+ * to `ws`/`wss`; a bare host is already the ttyd websocket endpoint.
+ */
+export declare function terminalSocketUrl(cap: Pick<TerminalCapability, "url">): string;
+/** ttyd subprotocol — REQUIRED on the WebSocket handshake or ttyd refuses it. */
+export declare const TTYD_SUBPROTOCOL = "tty";
+/** Client→server command bytes (the first char of each outbound text frame). */
+export declare const TtydClientCommand: {
+    /** stdin: "0" + raw input bytes. */
+    readonly INPUT: "0";
+    /** window resize: "1" + JSON.stringify({ columns, rows }). */
+    readonly RESIZE: "1";
+    /** flow-control pause (back-pressure): "2". */
+    readonly PAUSE: "2";
+    /** flow-control resume: "3". */
+    readonly RESUME: "3";
+};
+/** Server→client command bytes (the first char of each inbound frame). */
+export declare const TtydServerCommand: {
+    /** stdout/stderr: "0" + raw output bytes (write the rest into xterm). */
+    readonly OUTPUT: "0";
+    /** set the window title: "1" + title string. */
+    readonly SET_WINDOW_TITLE: "1";
+    /** ttyd client preferences JSON: "2" + json (ignored by us). */
+    readonly SET_PREFERENCES: "2";
+};
+/**
+ * The ttyd handshake's first frame: an auth message. ttyd expects
+ * `JSON.stringify({ AuthToken })` as the FIRST text frame on the socket. We send
+ * an empty token — our gate is the tunnel URL + scoped stream token, NOT a ttyd
+ * `-c` basic-auth credential (which the box does not set in v1). Optional ttyd
+ * `columns`/`rows` can ride this frame to seed the PTY size before the first
+ * resize. Pure (string-building only) so it stays unit-testable in the SDK.
+ */
+export declare function ttydAuthFrame(opts?: {
+    columns?: number;
+    rows?: number;
+}): string;
+/** Build a client→server INPUT (stdin) frame: "0" + data. */
+export declare function ttydInputFrame(data: string): string;
+/** Build a client→server RESIZE frame: "1" + JSON.stringify({ columns, rows }). */
+export declare function ttydResizeFrame(columns: number, rows: number): string;

package/dist/transcription.d.ts

@@ -0,0 +1,189 @@
+/**
+ * Framework- and transport-agnostic speech-to-text capability contract.
+ *
+ * Audio transport, microphone access, credentials, and provider SDKs belong to
+ * host-supplied adapters. This module deliberately contains no browser globals
+ * and no provider implementation.
+ */
+export type TranscriptionCredentialMode = "managed" | "byok";
+export type WorkspaceTranscriptionTarget = {
+    provider: string;
+    model: string | null;
+    credentialMode: TranscriptionCredentialMode;
+    /** Workspace-scoped connection reference. This is never a secret. */
+    credentialConnectionId: string | null;
+    region: string | null;
+};
+export type WorkspaceTranscriptionPolicy = {
+    enabled: boolean;
+    /** Exact admin-accepted policy identity; required whenever enabled. */
+    acceptanceId: string | null;
+    primary: WorkspaceTranscriptionTarget | null;
+    /** Explicit language preference. Required when automatic detection is not accepted. */
+    language: string | null;
+    /** Whether the accepted adapter may automatically detect the spoken language. */
+    autoDetectLanguage: boolean;
+    /** Whether the accepted adapter may identify distinct speakers. */
+    diarization: {
+        enabled: boolean;
+        maxSpeakers: number | null;
+    };
+    retention: {
+        mode: "none" | "provider-policy";
+        maxDays: number | null;
+    };
+    privacy: {
+        allowProviderLogging: boolean;
+        allowProviderTraining: boolean;
+    };
+    fallback: {
+        mode: "disabled" | "explicit";
+        targets: WorkspaceTranscriptionTarget[];
+    };
+    cost: {
+        currency: "USD";
+        maxPerHour: number | null;
+        maxPerMonth: number | null;
+    };
+};
+export declare const DEFAULT_WORKSPACE_TRANSCRIPTION_POLICY: WorkspaceTranscriptionPolicy;
+export type TranscriptionAdapterDescriptor = {
+    provider: string;
+    model: string | null;
+    credentialMode: TranscriptionCredentialMode;
+    region: string | null;
+};
+export type TranscriptionTargetSelection = {
+    kind: "primary";
+} | {
+    kind: "fallback";
+    index: number;
+};
+export type TranscriptionPolicyBlockReason = "disabled" | "unaccepted" | "target_missing" | "fallback_disabled" | "fallback_unaccepted" | "provider_mismatch" | "model_mismatch" | "credential_mode_mismatch" | "region_mismatch";
+export type TranscriptionAuthorization = {
+    authorized: true;
+    acceptanceId: string;
+    target: WorkspaceTranscriptionTarget;
+    selection: TranscriptionTargetSelection;
+} | {
+    authorized: false;
+    reason: TranscriptionPolicyBlockReason;
+};
+export type TranscriptionLifecycleStatus = "idle" | "requesting-permission" | "listening" | "reconnecting" | "cancelling" | "closed" | "error";
+export type TranscriptionErrorCode = "permission_denied" | "not_supported" | "network" | "provider" | "policy_blocked" | "timeout" | "cancelled" | "unavailable" | "too_large" | "invalid_audio" | "unknown";
+/** Native browser voice input defaults to the configured deployment capability. */
+export declare function resolveWorkspaceVoiceInputEnabled(settings: unknown): boolean | null;
+export type TranscriptionTimeSpan = {
+    startMilliseconds: number;
+    endMilliseconds: number;
+};
+export type TranscriptionSpeaker = {
+    /** Provider-neutral identity stable within the local transcription session. */
+    id: string;
+    label?: string | undefined;
+};
+export type TranscriptionWord = {
+    text: string;
+    span: TranscriptionTimeSpan;
+    confidence?: number | undefined;
+    speaker?: TranscriptionSpeaker | undefined;
+};
+/** Optional result detail; adapters omit fields their provider cannot supply. */
+export type TranscriptionResultMetadata = {
+    detectedLanguage?: string | undefined;
+    span?: TranscriptionTimeSpan | undefined;
+    confidence?: number | undefined;
+    speaker?: TranscriptionSpeaker | undefined;
+    words?: TranscriptionWord[] | undefined;
+};
+export type TranscriptionDiagnostic = {
+    operation: "start" | "session" | "cancel" | "close";
+    code: TranscriptionErrorCode;
+    /** Diagnostic-only detail. React sanitizes and bounds this before forwarding it. */
+    detail: string;
+};
+type TranscriptionEventBase = {
+    /** Stable across reconnects and explicitly accepted fallback attempts. */
+    localSessionId: string;
+    /** Adapter-monotonic across the entire local session, including replay. */
+    sequence: number;
+    occurredAt: string;
+};
+export type TranscriptionEvent = (TranscriptionEventBase & {
+    type: "permission.requested";
+}) | (TranscriptionEventBase & {
+    type: "session.opened";
+    providerSessionId: string;
+}) | (TranscriptionEventBase & {
+    type: "transcript.partial";
+    segmentId: string;
+    text: string;
+    metadata?: TranscriptionResultMetadata | undefined;
+}) | (TranscriptionEventBase & {
+    type: "transcript.final";
+    segmentId: string;
+    text: string;
+    /** Stable provider/coordinator acceptance identity used for dedupe. */
+    providerAcceptanceId: string;
+    metadata?: TranscriptionResultMetadata | undefined;
+}) | (TranscriptionEventBase & {
+    type: "usage";
+    audioMilliseconds: number;
+    costUsd: number | null;
+}) | (TranscriptionEventBase & {
+    type: "session.reconnecting";
+    attempt: number;
+    reason: string;
+}) | (TranscriptionEventBase & {
+    type: "session.error";
+    code: TranscriptionErrorCode;
+    recoverable: boolean;
+}) | (TranscriptionEventBase & {
+    type: "session.closed";
+    reason: "completed" | "cancelled" | "error" | "replaced";
+});
+export type TranscriptionSessionRequest = {
+    localSessionId: string;
+    policyAcceptanceId: string;
+    selection: TranscriptionTargetSelection;
+    target: WorkspaceTranscriptionTarget;
+    language: string | null;
+    autoDetectLanguage: boolean;
+    diarization: WorkspaceTranscriptionPolicy["diarization"];
+    retention: WorkspaceTranscriptionPolicy["retention"];
+    privacy: WorkspaceTranscriptionPolicy["privacy"];
+    cost: WorkspaceTranscriptionPolicy["cost"];
+    /** A replacement/reconnect adapter must emit events above this floor. */
+    sequenceFloor: number;
+};
+export type TranscriptionEventListener = (event: TranscriptionEvent) => void;
+export type TranscriptionAdapterStartContext = {
+    /** Aborted on local cancellation, policy replacement, timeout, or unmount. */
+    signal: AbortSignal;
+    /** Non-UI observability seam; callers receive only bounded, redacted detail. */
+    reportDiagnostic: (diagnostic: TranscriptionDiagnostic) => void;
+};
+export type TranscriptionSession = {
+    readonly localSessionId: string;
+    cancel(reason?: string): Promise<void>;
+    close(): Promise<void>;
+};
+export type TranscriptionAdapter = {
+    readonly descriptor: TranscriptionAdapterDescriptor;
+    start(request: TranscriptionSessionRequest, listener: TranscriptionEventListener, context: TranscriptionAdapterStartContext): Promise<TranscriptionSession>;
+};
+/** Invalid or absent settings always resolve to the fail-closed default. */
+export declare function resolveWorkspaceTranscriptionPolicy(settings: unknown): WorkspaceTranscriptionPolicy;
+/**
+ * Speech authorization is intentionally independent from turn model policy.
+ * Every selected adapter must match one exact admin-accepted target.
+ */
+export declare function authorizeTranscriptionAdapter(policy: WorkspaceTranscriptionPolicy, descriptor: TranscriptionAdapterDescriptor, selection?: TranscriptionTargetSelection): TranscriptionAuthorization;
+export declare function createTranscriptionSessionRequest(input: {
+    policy: WorkspaceTranscriptionPolicy;
+    adapter: TranscriptionAdapter;
+    localSessionId: string;
+    selection?: TranscriptionTargetSelection | undefined;
+    sequenceFloor?: number | undefined;
+}): TranscriptionSessionRequest | null;
+export {};