@ellipsis-dev/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ellipsis Dev, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,40 @@
+# @ellipsis-dev/sdk
+
+TypeScript SDK for the [Ellipsis](https://www.ellipsis.dev) agents platform.
+Three subpath exports, all dependency-free at runtime:
+
+- **`@ellipsis-dev/sdk`** — generated `/v1` REST types + `EllipsisClient`, a thin
+  typed client over an injected `fetchJson`.
+- **`@ellipsis-dev/sdk/stream`** — the session stream WebSocket client
+  (`streamSession`): protocol negotiation, heartbeat liveness,
+  reconnect-with-backoff, and lossless resume via the `after_seq` record
+  cursor. Transport is an injected `openSocket`, so the same machinery runs in
+  a browser, a terminal, or a server.
+- **`@ellipsis-dev/sdk/store`** — `SessionTranscriptStore`
+  (`subscribe`/`getSnapshot`, shaped for React's `useSyncExternalStore` but
+  framework-free) plus the pure shaping helpers that turn raw session records
+  into renderable transcript items and chat turns.
+
+## Types are generated, never hand-written
+
+- `schema/frames.schema.json` — JSON Schema of the WebSocket frames, produced
+  from the server's frame models.
+- `schema/openapi.v1.json` — the OpenAPI document for the SDK's REST surface.
+
+`pnpm gen` derives `src/generated/` from those documents
+(`json-schema-to-typescript` + `openapi-typescript`). CI regenerates and
+diffs, and the server's own test suite pins the committed schema documents to
+its models, so types cannot drift from the deployed API in either direction.
+
+`test/fixtures/golden_stream.json` is a frame sequence recorded from the real
+server stream loop (ids and timestamps normalized); the store's tests replay
+it, so client behavior is validated against real emissions, not hand-written
+examples.
+
+## Protocol
+
+The stream protocol (frame taxonomy, delivery classes, resume/close-code
+contract) is documented at https://www.ellipsis.dev/docs. The compatibility
+rule clients must follow: **ignore unknown frame types and unknown
+`source`/`record_type`/`kind` values** — additive server changes are not a
+protocol break.

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+import { A as AgentSessionWire, L as ListSessionRecordsResponse, a as ListSessionTurnsResponse, S as SessionMessageWire } from './types-BRE4NMnS.js';
+export { b as AgentSessionExitStatus, c as AgentSessionPr, d as AgentSessionSource, e as AgentSessionStatus, f as AgentTurn, g as AgentTurnStatus, h as AttributionType, B as BudgetSource, D as DefaultResolution, i as DeltaFrame, j as DoneFrame, E as ErrorFrame, G as GithubAccountSnippet, k as GithubAccountType, H as Harness, l as HeartbeatFrame, M as MessagesFrame, m as ModelTokensInfo, P as ParentKind, R as RecordsAppendFrame, n as SendSessionMessageRequest, o as SessionFrame, p as SessionLiveness, q as SessionMessageStatus, r as SessionRecordWire, s as SessionState, t as SessionStreamFrame, u as SessionSurface, v as SnapshotFrame, w as StreamFrame, T as TokensInfo, x as TurnTokensInfo, y as components, z as paths } from './types-BRE4NMnS.js';
+
+type FetchJson = (path: string, init?: {
+    method?: string;
+    body?: unknown;
+}) => Promise<unknown>;
+declare class EllipsisClient {
+    private readonly fetchJson;
+    constructor(fetchJson: FetchJson);
+    getSession(sessionId: string): Promise<AgentSessionWire>;
+    getSessionRecords(sessionId: string, options?: {
+        afterSeq?: number;
+        limit?: number;
+    }): Promise<ListSessionRecordsResponse>;
+    getSessionTurns(sessionId: string): Promise<ListSessionTurnsResponse>;
+    sendSessionMessage(sessionId: string, message: string, options?: {
+        idempotencyKey?: string;
+    }): Promise<SessionMessageWire>;
+}
+
+export { AgentSessionWire, EllipsisClient, type FetchJson, ListSessionRecordsResponse, ListSessionTurnsResponse, SessionMessageWire };

package/dist/index.js

@@ -0,0 +1,53 @@
+// src/client.ts
+var EllipsisClient = class {
+  constructor(fetchJson) {
+    this.fetchJson = fetchJson;
+  }
+  fetchJson;
+  // The enriched public session (§4.1) — the same lean wire shape the
+  // stream's session frames carry.
+  async getSession(sessionId) {
+    return await this.fetchJson(
+      `/v1/sessions/${encodeURIComponent(sessionId)}`
+    );
+  }
+  // The record log + inbox messages (§4.3). Bare call = the full transcript;
+  // pass afterSeq/limit to page (limit max 1000, `has_more` signals more).
+  async getSessionRecords(sessionId, options = {}) {
+    const params = new URLSearchParams();
+    if (options.afterSeq != null)
+      params.set("after_seq", String(options.afterSeq));
+    if (options.limit != null) params.set("limit", String(options.limit));
+    const query = params.toString();
+    return await this.fetchJson(
+      `/v1/sessions/${encodeURIComponent(sessionId)}/records` + (query ? `?${query}` : "")
+    );
+  }
+  // The session's turns — the structural conversation history (message ->
+  // response exchanges with status/cost).
+  async getSessionTurns(sessionId) {
+    return await this.fetchJson(
+      `/v1/sessions/${encodeURIComponent(sessionId)}/turns`
+    );
+  }
+  // Send a message into the session's inbox (§4.2). Returns the created (or,
+  // on an idempotent retry, the original) inbox row — clients key optimistic
+  // echo chips on its id. `idempotencyKey` makes retries safe per
+  // (session, key); a closed or non-interactive session rejects with a 409
+  // (surface the server's curated copy).
+  async sendSessionMessage(sessionId, message, options = {}) {
+    return await this.fetchJson(
+      `/v1/sessions/${encodeURIComponent(sessionId)}/messages`,
+      {
+        method: "POST",
+        body: {
+          message,
+          ...options.idempotencyKey != null ? { idempotency_key: options.idempotencyKey } : {}
+        }
+      }
+    );
+  }
+};
+export {
+  EllipsisClient
+};

package/dist/store/index.d.ts

@@ -0,0 +1,145 @@
+import { r as SessionRecordWire, A as AgentSessionWire, S as SessionMessageWire, w as StreamFrame } from '../types-BRE4NMnS.js';
+
+interface ChatToolNode {
+    key: string;
+    kind: 'tool';
+    name: string;
+    input: Record<string, unknown> | null;
+    summary: string;
+    result: string | null;
+    isError: boolean;
+}
+type ChatNode = {
+    key: string;
+    kind: 'assistant';
+    text: string;
+} | {
+    key: string;
+    kind: 'thinking';
+    text: string;
+} | {
+    key: string;
+    kind: 'user';
+    text: string;
+} | {
+    key: string;
+    kind: 'lifecycle';
+    text: string;
+    recordType: string;
+    hook?: string;
+} | ChatToolNode;
+interface ChatTurn {
+    key: string;
+    role: 'assistant' | 'user' | 'lifecycle';
+    nodes: ChatNode[];
+    startedAt: string | null;
+    completedAt: string | null;
+    durationMs: number | null;
+    costUsd: number | null;
+    tokens: number | null;
+    resumed: boolean;
+}
+declare function groupRecordsToChatTurns(records: readonly SessionRecordWire[]): ChatTurn[];
+
+declare function setupOutputHook(payload: Record<string, unknown>): string;
+declare function setupOutputLine(payload: Record<string, unknown>): string | null;
+declare function lifecycleText(recordType: string, payload: Record<string, unknown>): string | null;
+
+interface CCContentBlock {
+    type?: string;
+    text?: string;
+    thinking?: string;
+    id?: string;
+    name?: string;
+    input?: Record<string, unknown>;
+    content?: unknown;
+    tool_use_id?: string;
+    is_error?: boolean;
+}
+interface CCEvent {
+    type?: string;
+    subtype?: string;
+    message?: {
+        role?: string;
+        content?: unknown;
+    };
+    result?: string;
+    duration_ms?: number;
+    total_cost_usd?: number;
+    num_turns?: number;
+    is_error?: boolean;
+    model?: string;
+    cwd?: string;
+    tools?: string[];
+    [key: string]: unknown;
+}
+type ItemKind = 'assistant' | 'thinking' | 'tool' | 'tool_result' | 'summary' | 'system' | 'user' | 'notice' | 'error';
+interface TranscriptItem {
+    key: string;
+    kind: ItemKind;
+    text: string;
+    detail?: string;
+    gutter?: string;
+    spaceBefore?: boolean;
+    isError?: boolean;
+    tool?: {
+        name: string;
+        input?: Record<string, unknown>;
+    };
+}
+declare class LineBuffer {
+    private buf;
+    push(chunk: string): string[];
+    flush(): string[];
+}
+declare function parseEventLine(line: string): CCEvent | null;
+declare function oneLine(text: string, max: number): string;
+declare function summarizeToolInput(name: string, input: unknown): string;
+declare function formatDuration(seconds: number): string;
+interface EventToItemsOptions {
+    systemInitLine?: boolean;
+}
+declare function eventToItems(event: CCEvent, keyBase: string, options?: EventToItemsOptions): TranscriptItem[];
+declare function recordToItems(record: SessionRecordWire, keyBase: string, options?: EventToItemsOptions): TranscriptItem[];
+declare function isConnectVisibleRecord(record: SessionRecordWire): boolean;
+declare function pendingToolCalls(items: TranscriptItem[]): TranscriptItem[];
+declare function collapseToolRuns(items: TranscriptItem[]): TranscriptItem[];
+declare function clampLines(text: string, maxLines: number): {
+    body: string;
+    more: number;
+};
+declare function resultCostUsd(event: CCEvent): number | null;
+declare function foldCosts(events: CCEvent[]): {
+    total: number | null;
+    lastStep: number | null;
+};
+declare function statusActivityText(status: string): string | null;
+
+declare function isConversationOver(session: AgentSessionWire): boolean;
+interface SessionTranscriptSnapshot {
+    session: AgentSessionWire | null;
+    records: readonly SessionRecordWire[];
+    messages: readonly SessionMessageWire[];
+    acknowledgedMessageIds: ReadonlySet<string>;
+    historyTruncated: boolean;
+    liveText: string;
+    liveOutputTokens: number | null;
+    lastEventAt: number | null;
+    conversationOver: boolean;
+}
+declare function emptySessionTranscriptSnapshot(): SessionTranscriptSnapshot;
+declare class SessionTranscriptStore {
+    private snapshot;
+    private listeners;
+    private acknowledged;
+    private cursorSeq;
+    private turnsFor;
+    private turnsCache;
+    get cursor(): number;
+    subscribe: (listener: () => void) => (() => void);
+    getSnapshot: () => SessionTranscriptSnapshot;
+    chatTurns: () => ChatTurn[];
+    ingest: (rawFrame: StreamFrame) => void;
+}
+
+export { type CCContentBlock, type CCEvent, type ChatNode, type ChatToolNode, type ChatTurn, type EventToItemsOptions, type ItemKind, LineBuffer, type SessionTranscriptSnapshot, SessionTranscriptStore, StreamFrame, type TranscriptItem, clampLines, collapseToolRuns, emptySessionTranscriptSnapshot, eventToItems, foldCosts, formatDuration, groupRecordsToChatTurns, isConnectVisibleRecord, isConversationOver, lifecycleText, oneLine, parseEventLine, pendingToolCalls, recordToItems, resultCostUsd, setupOutputHook, setupOutputLine, statusActivityText, summarizeToolInput };