@getorrery/client 0.0.0-stage → 0.2.2

package/dist/cloud-events.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Orrery Cloud's event stream (platform decision 0024, plan 14 "Events"):
+ * `GET /api/v1/events` as Server-Sent Events, account-scoped. Each event names
+ * what changed (ids and a version, never content); a client re-reads it
+ * through the routes it already uses. `reset` means refresh everything.
+ *
+ * - [`SseParser`]: `text/event-stream` text in, events out, chunk by chunk
+ *   (the ADE feeds it what its Rust side reads; a browser feeds it `fetch`'s body).
+ * - [`cloudEvents`]: the `fetch`-streaming client (headers, so not `EventSource`):
+ *   the token in `Authorization`, never the query, and `Last-Event-ID` to resume.
+ * - [`backoffMs`]: the reconnect delay, 1 s doubling to 30 s.
+ *
+ * Browser-safe: `fetch`, `ReadableStream` and `TextDecoder` only.
+ */
+/** One server-sent event. `event` is `message` when the block named none. */
+export interface SseEvent {
+    id?: string;
+    event: string;
+    data: string;
+}
+/**
+ * An incremental `text/event-stream` parser (the WHATWG rules that matter
+ * here): `\n`, `\r\n` or `\r` end a line, a blank line ends an event, `:` lines
+ * are comments (Cloud's `: ping`), `data:` lines join with `\n`, `id:` is kept
+ * as [`lastEventId`] for the reconnect.
+ */
+export declare class SseParser {
+    /** The last `id:` seen: what `Last-Event-ID` sends back. */
+    lastEventId: string | undefined;
+    private buffer;
+    private event;
+    private data;
+    private id;
+    /** Feed text; get the events it completed. */
+    push(text: string): SseEvent[];
+    private line;
+}
+/** What a Cloud event names (plan 14 "Events"). Unknown kinds are dropped by [`cloudEventOf`]. */
+export type CloudEvent = {
+    kind: "machine";
+    machine_id: string;
+    host_id?: string;
+    version?: number;
+} | {
+    kind: "host";
+    host_id: string;
+    version?: number;
+} | {
+    kind: "session";
+    session_id: string;
+    machine_id: string;
+    change: "started" | "state" | "title" | "ended" | "deleted" | string;
+    version?: number;
+} | {
+    kind: "lease";
+    session_id: string;
+    machine_id: string;
+    epoch: number;
+    handoff_id?: string;
+    version?: number;
+} | {
+    kind: "config";
+    keys: string[];
+    machine_id?: string;
+    version?: number;
+} | {
+    kind: "reset";
+};
+/** An SSE event as a [`CloudEvent`], or `null` for a kind or body this client does not know. */
+export declare function cloudEventOf(e: SseEvent): CloudEvent | null;
+/** The wait before reconnect attempt `attempt` (0-based): 1 s, 2 s, 4 s … at most 30 s. */
+export declare function backoffMs(attempt: number, firstMs?: number, maxMs?: number): number;
+/** `GET /events` refused: `status` 401 means sign in again. */
+export declare class CloudEventsError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+export interface CloudEventsOptions {
+    /** `https://cloud/api/v1/events`. */
+    url: string;
+    /** A person or client token: sent as `Authorization: Bearer`. */
+    token: string;
+    /** Resume after this event (`Last-Event-ID`). */
+    lastEventId?: string;
+    signal?: AbortSignal;
+    /** `fetch` (the global one when absent). */
+    fetch?: typeof fetch;
+}
+/**
+ * Read Cloud's event stream until it ends, the signal aborts, or it breaks
+ * (thrown). Every event carries the `id` to resume from. A refusal throws a
+ * [`CloudEventsError`] with the status.
+ */
+export declare function cloudEvents(options: CloudEventsOptions): AsyncGenerator<SseEvent>;

package/dist/cloud-events.js

@@ -0,0 +1,14 @@
+import {
+  CloudEventsError,
+  SseParser,
+  backoffMs,
+  cloudEventOf,
+  cloudEvents
+} from "./chunk-P3UGNLD6.js";
+export {
+  CloudEventsError,
+  SseParser,
+  backoffMs,
+  cloudEventOf,
+  cloudEvents
+};

package/dist/conformance-node.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The fixture runner's disk half: Node only, exported from `@getorrery/client/node`.
+ */
+import { type Scenario } from "./conformance.js";
+export * from "./conformance.js";
+/** Where the fixtures live, relative to this package. */
+export declare function fixturesDir(): string;
+/** Load one scenario file. Throws naming the file and the line. */
+export declare function load(path: string): Scenario;
+/** Load every `*.jsonl` scenario in a directory, sorted by name. */
+export declare function loadAll(dir?: string): Scenario[];

package/dist/conformance.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The fixture runner, shared by every TypeScript client.
+ *
+ * Browser-safe: this half parses a scenario from its text and replays it.
+ * Reading the fixtures from disk (`load`, `loadAll`, `fixturesDir`) is in
+ * `@getorrery/client/node`; a browser bundles the files' text instead.
+ *
+ * `sdk-ts` runs these and so does Ink (plan 09c). The **same files** the Rust
+ * SDK runs: a scenario only one language checks is a scenario that has stopped
+ * being a contract.
+ */
+import { type Frame } from "./events.js";
+import { type StoreState, SurfaceStore } from "./store.js";
+/** One line of a scenario. */
+export type Step = {
+    kind: "event";
+    frame: Frame;
+}
+/** A frame this build cannot even parse. It still consumes its `seq`. */
+ | {
+    kind: "unknown";
+    seq: number;
+    what: string;
+} | {
+    kind: "expect";
+    state: StoreState;
+};
+/** One fixture file. */
+export interface Scenario {
+    name: string;
+    path: string;
+    steps: Step[];
+}
+/** Parse one scenario from its text. Throws naming the file and the line. */
+export declare function parse(text: string, name: string, path?: string): Scenario;
+/** The frames of a scenario, in order: what a fixture-backed fake connection plays. */
+export declare function framesOf(scenario: Scenario): Frame[];
+/**
+ * How many scenarios there are — the whole set, exactly.
+ *
+ * The twin of `orrery_client::conformance::SCENARIO_COUNT`. Every client
+ * asserts this number rather than a floor of its own; two floors is how
+ * fixtures get deleted and only one suite notices.
+ *
+ * It counts the `*.jsonl` files in `clients/conformance` and nothing below it:
+ * `conformance/streams/` holds `ModelEvent` scripts for the fixture provider,
+ * not AG-UI scenarios for a renderer, and `loadAll` is deliberately not
+ * recursive.
+ */
+export declare const SCENARIO_COUNT = 68;
+/** Every checkpoint in a scenario, with the store as it stood at each. */
+export declare function checkpoints(scenario: Scenario): Array<{
+    index: number;
+    actual: StoreState;
+    expected: StoreState;
+}>;
+/** Replay a scenario and hand back the store it produced. */
+export declare function replay(scenario: Scenario): SurfaceStore;

package/dist/events.d.ts

@@ -0,0 +1,173 @@
+/**
+ * The AG-UI events this client understands, and the frame that carries our seq.
+ *
+ * The tags come from `@ag-ui/core`'s own `EventType`, not from a list retyped
+ * here: that is what makes "an existing AG-UI client works unmodified" checkable
+ * rather than asserted. The surface half comes from `@getorrery/protocol`, which is
+ * generated from `orrery-proto`. Nothing in this file is a hand-written frame
+ * type.
+ */
+import { EventType } from "@ag-ui/core";
+import type { Outcome, SurfaceKind } from "@getorrery/protocol";
+/** The `Custom` name a consent prompt rides under. */
+export declare const CONSENT_REQUEST = "orrery.consent.request";
+/** The `Custom` name a consent resolution rides under. */
+export declare const CONSENT_RESOLVED = "orrery.consent.resolved";
+/** The `Custom` name a turn's cancellation rides under. */
+export declare const TURN_CANCELLED = "orrery.turn.cancelled";
+/**
+ * The `Custom` name a placement rides under (decisions 0086, 0088): the
+ * `Placed` fields, its `surface`, and `text`, its text form, for a client that
+ * draws no panes. The store does not keep it; the UI document holds the same.
+ */
+export declare const PLACED = "orrery.placed";
+/** The `Custom` name a placement's removal rides under: `{id, owner}`. */
+export declare const UNPLACED = "orrery.unplaced";
+/**
+ * One RFC 6902 op, and nothing else (harness decision 0072): a stock AG-UI
+ * client drops a delta holding an op it does not know. Streamed text is an
+ * `add` onto `…/kind/chunks`, which the store folds into `kind.value`.
+ */
+export type PatchOp = {
+    op: "replace";
+    path: string;
+    value: unknown;
+} | {
+    op: "add";
+    path: string;
+    value: unknown;
+} | {
+    op: "remove";
+    path: string;
+};
+/** An AG-UI event, as `orrery-agui` encodes it. */
+export type AguiEvent = {
+    type: typeof EventType.RUN_STARTED;
+    threadId: string;
+    runId: string;
+} | {
+    type: typeof EventType.RUN_FINISHED;
+    threadId: string;
+    runId: string;
+    result?: unknown;
+    outcome?: {
+        type: string;
+    };
+    usage?: unknown[];
+} | {
+    type: typeof EventType.RUN_ERROR;
+    message: string;
+    code?: string | null;
+    result?: unknown;
+    usage?: unknown[];
+} | {
+    type: typeof EventType.STEP_STARTED;
+    stepName: string;
+} | {
+    type: typeof EventType.STEP_FINISHED;
+    stepName: string;
+} | {
+    type: typeof EventType.TEXT_MESSAGE_START;
+    messageId: string;
+    role: string;
+    /** The extension segment this message belongs to (decision 0076 §3). */
+    subagentRunId?: string;
+} | {
+    type: typeof EventType.TEXT_MESSAGE_CONTENT;
+    messageId: string;
+    delta: string;
+} | {
+    type: typeof EventType.TEXT_MESSAGE_END;
+    messageId: string;
+} | {
+    type: typeof EventType.TOOL_CALL_START;
+    toolCallId: string;
+    toolCallName: string;
+    parentMessageId?: string;
+    subagentRunId?: string;
+} | {
+    type: typeof EventType.TOOL_CALL_ARGS;
+    toolCallId: string;
+    delta: string;
+} | {
+    type: typeof EventType.TOOL_CALL_END;
+    toolCallId: string;
+} | {
+    type: typeof EventType.TOOL_CALL_RESULT;
+    messageId: string;
+    toolCallId: string;
+    content: string;
+    outcome?: Outcome;
+} | {
+    type: typeof EventType.REASONING_START;
+    messageId: string;
+    timestamp?: number;
+} | {
+    type: typeof EventType.REASONING_MESSAGE_START;
+    messageId: string;
+    role: string;
+} | {
+    type: typeof EventType.REASONING_MESSAGE_CONTENT;
+    messageId: string;
+    delta: string;
+} | {
+    type: typeof EventType.REASONING_MESSAGE_END;
+    messageId: string;
+} | {
+    type: typeof EventType.REASONING_END;
+    messageId: string;
+    timestamp?: number;
+} | {
+    type: typeof EventType.SUBAGENT_STARTED;
+    subagentRunId: string;
+    /** `<ext>.model` or `<ext>.agent`. */
+    name: string;
+    description?: string;
+    parentToolCallId?: string;
+} | {
+    type: typeof EventType.SUBAGENT_FINISHED;
+    subagentRunId: string;
+    result?: unknown;
+    outcome?: {
+        type: string;
+    };
+} | {
+    type: typeof EventType.SUBAGENT_ERROR;
+    subagentRunId: string;
+    message: string;
+    code?: string | null;
+} | {
+    type: typeof EventType.STATE_SNAPSHOT;
+    snapshot: unknown;
+} | {
+    type: typeof EventType.STATE_DELTA;
+    delta: PatchOp[];
+} | {
+    type: typeof EventType.CUSTOM;
+    name: string;
+    value: Record<string, unknown>;
+};
+/**
+ * An AG-UI event with our `seq` on it.
+ *
+ * `seq` is assigned once, per session, at the differ's output — never per
+ * connection — so it is on the frame rather than implied by the order a socket
+ * happened to deliver things in. `mergedFrom` is the first seq a coalesced
+ * frame stands for, without which a merge and a lost frame look the same.
+ */
+export type Frame = AguiEvent & {
+    seq: number;
+    merged_from?: number;
+};
+/**
+ * A frame as it arrives, made a [`Frame`]: Orrery's extras ride in AG-UI's
+ * `metadata.orrery` on the wire (`seq`, `merged_from`, a tool result's
+ * `outcome`, a failed run's `result`) and sit beside the event here. A frame
+ * recorded with them beside the event already passes through. `null` when it
+ * carries no `seq`, so is not a frame.
+ */
+export declare function frameOf(raw: unknown): Frame | null;
+/** The first sequence number a frame accounts for. */
+export declare function firstSeq(frame: Frame): number;
+/** A surface kind we can still name after a patch has been applied to it. */
+export type Kind = SurfaceKind;

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `@getorrery/client` — an AG-UI session and a `SurfaceStore`. Pure data, no drawing.
+ *
+ * The same two types as `clients/sdk-rs`, against the same conformance fixtures.
+ * The session half sits on stock `@ag-ui/client`, which is what makes "existing
+ * AG-UI clients work unmodified" a thing this repo checks rather than claims.
+ *
+ * ## Browser-safe
+ *
+ * This entry imports nothing from `node:` (checked by `test/entry.test.ts`), so
+ * a web page, the ADE's webview and a phone bundle it as is. What needs Node —
+ * the `orrery-client/1` channel over `ORRERY_ENDPOINT`, and reading the
+ * conformance fixtures from disk — is `@getorrery/client/node`.
+ *
+ * ## Transports
+ *
+ * `AguiSession` runs over a [`Transport`]: HTTP + SSE (`orrery serve` today)
+ * or WebSocket (the node's listener and the relay, one frame per message).
+ *
+ * ## A client never writes state
+ *
+ * AG-UI's shared state is bidirectional by design; ours is not. `StateSnapshot`
+ * and `StateDelta` flow outward only, and an edit a person makes arrives back as
+ * an `intent` the kernel validates. Anyone porting a component that expects to
+ * write state directly needs to know that.
+ *
+ * Implementation plan: `harness/docs/plans/08-protocol-transport.md`
+ */
+export * from "./events.js";
+export * from "./anim.js";
+export * from "./store.js";
+export * from "./transport.js";
+export { HttpSseTransport, type HttpTransportOptions, sse } from "./transport-http.js";
+export { WebSocketTransport, type WebSocketCtor, type WebSocketLike, type WebSocketTransportOptions, } from "./transport-ws.js";
+export * from "./session.js";
+export * from "./workspace.js";
+export * from "./kept.js";
+export * from "./cloud-events.js";
+export * as conformance from "./conformance.js";

package/dist/index.js

@@ -0,0 +1,112 @@
+import {
+  AGUI_PROTOCOL_VERSION,
+  ANIM,
+  AguiSession,
+  CONSENT_REQUEST,
+  CONSENT_RESOLVED,
+  ControlError,
+  DETACHED_TURN,
+  FrameHub,
+  HttpSseTransport,
+  MAX_FILE_BYTES,
+  MAX_MESSAGE_BYTES,
+  MOVED,
+  NOTICES,
+  OUT_OF_ORDER,
+  PLACED,
+  SESSION_CHANGES,
+  STATE_CHANGED,
+  SurfaceStore,
+  TURN_CANCELLED,
+  UNPLACED,
+  USER_MESSAGE,
+  WORKSPACE_COMMIT,
+  WORKSPACE_PUSH,
+  WORKSPACE_READ,
+  WORKSPACE_READ_CAP_BYTES,
+  WebSocketTransport,
+  afterOf,
+  choosingLine,
+  conformance_exports,
+  filePart,
+  firstSeq,
+  formatAddress,
+  frameOf,
+  framesOf,
+  keptTranscript,
+  movedOf,
+  parseAddress,
+  parseAnim,
+  parseEndpoint,
+  readKept,
+  resumeFrom,
+  sse,
+  thoughtMs,
+  workspaceCommit,
+  workspaceErrorCode,
+  workspacePush,
+  workspaceRead,
+  workspaceRequest
+} from "./chunk-RQUTHT7N.js";
+import {
+  CloudEventsError,
+  SseParser,
+  backoffMs,
+  cloudEventOf,
+  cloudEvents
+} from "./chunk-P3UGNLD6.js";
+export {
+  AGUI_PROTOCOL_VERSION,
+  ANIM,
+  AguiSession,
+  CONSENT_REQUEST,
+  CONSENT_RESOLVED,
+  CloudEventsError,
+  ControlError,
+  DETACHED_TURN,
+  FrameHub,
+  HttpSseTransport,
+  MAX_FILE_BYTES,
+  MAX_MESSAGE_BYTES,
+  MOVED,
+  NOTICES,
+  OUT_OF_ORDER,
+  PLACED,
+  SESSION_CHANGES,
+  STATE_CHANGED,
+  SseParser,
+  SurfaceStore,
+  TURN_CANCELLED,
+  UNPLACED,
+  USER_MESSAGE,
+  WORKSPACE_COMMIT,
+  WORKSPACE_PUSH,
+  WORKSPACE_READ,
+  WORKSPACE_READ_CAP_BYTES,
+  WebSocketTransport,
+  afterOf,
+  backoffMs,
+  choosingLine,
+  cloudEventOf,
+  cloudEvents,
+  conformance_exports as conformance,
+  filePart,
+  firstSeq,
+  formatAddress,
+  frameOf,
+  framesOf,
+  keptTranscript,
+  movedOf,
+  parseAddress,
+  parseAnim,
+  parseEndpoint,
+  readKept,
+  resumeFrom,
+  sse,
+  thoughtMs,
+  workspaceCommit,
+  workspaceErrorCode,
+  workspacePush,
+  workspaceRead,
+  workspaceRequest
+};

package/dist/kept.d.ts

@@ -0,0 +1,82 @@
+/**
+ * A session kept in Orrery Cloud (platform decision 0013, plan 12 step 2):
+ * the client's three-part cursor, reading the kept log a page at a time, and
+ * what the log reads as while its machine is offline.
+ *
+ * The wire is `GET /api/v1/sessions/:id/log?after=<epoch>,<seq>` (plan 12,
+ * "Wire"). Pure data: the caller fetches pages, this decides what to ask for
+ * and what is new.
+ */
+/** Where a client is in a session's history (decision 0013 §6). */
+export interface SessionCursor {
+    /** The lease epoch the frames were read under (Cloud's `epoch`). */
+    epoch?: number;
+    /** The last kept entry read from Cloud, `(epoch, seq)` with `epoch` above. */
+    entrySeq?: number;
+    /** The last live frame's `seq`, from the node's ring. */
+    frameSeq?: number;
+}
+/** One kept entry, decrypted: a row of the node's `sessions.db`. */
+export interface KeptEntry {
+    epoch: number;
+    seq: number;
+    /** `branch`, `turn`, `entry` or `event`. */
+    kind: string;
+    /** `<kind>:<id or seq>`. */
+    key: string;
+    hash: string;
+    at: number;
+    body: unknown;
+}
+/** One page of `GET /sessions/:id/log`. */
+export interface KeptPage {
+    session_id: string;
+    machine_id: string;
+    epoch: number;
+    lease: "held" | "expired";
+    entries: KeptEntry[];
+    next: {
+        epoch: number;
+        seq: number;
+    } | null;
+}
+/**
+ * How to (re)attach. Within one epoch, resume from the node's ring after
+ * `frameSeq`. When the epoch moved (a handoff, a node that restarted or was
+ * replaced), the frames held are partial: drop them and read the history
+ * again (decision 0013 §6).
+ */
+export declare function resumeFrom(cursor: SessionCursor, epoch: number | undefined): {
+    since?: number;
+    replay: boolean;
+};
+/** The `after=` of a cursor: `<epoch>,<entry_seq>`, or nothing to read from the start. */
+export declare function afterOf(cursor: SessionCursor): string | undefined;
+/**
+ * Read the kept log after `cursor` until `next` is null. An entry already in
+ * `seen` (by `(epoch, seq)`) is skipped, so pages, polls and a re-read never
+ * draw one twice. Returns the new entries and the cursor past them.
+ */
+export declare function readKept(page: (after: string | undefined) => Promise<KeptPage>, cursor: SessionCursor, seen: Set<string>): Promise<{
+    entries: KeptEntry[];
+    cursor: SessionCursor;
+    page: KeptPage | null;
+}>;
+/** What a kept log reads as: one item per message, reasoning or tool call. */
+export type KeptItem = {
+    role: "user" | "assistant" | "thinking";
+    text: string;
+    key: string;
+} | {
+    role: "tool";
+    name: string;
+    call: string;
+    ok: boolean | null;
+    key: string;
+};
+/**
+ * The transcript of kept `turn` entries, the way `orrery replay` reads the
+ * same rows: the person's words, the model's prose and reasoning, each tool
+ * call and how it settled. Runs, settings and events are not drawn.
+ */
+export declare function keptTranscript(entries: readonly KeptEntry[]): KeptItem[];

package/dist/node.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `@getorrery/client/node` — everything in `@getorrery/client`, plus what only runs
+ * in Node:
+ *
+ * - [`connectClient`]: `orrery-client/1` over `ORRERY_ENDPOINT` (a local pipe
+ *   or stdio, through `@getorrery/ext`), for a client the host spawned;
+ * - `conformance.load` / `loadAll` / `fixturesDir`: the fixtures, from disk.
+ */
+export * from "./index.js";
+export * from "./channel.js";
+export * as conformance from "./conformance-node.js";