@getorrery/client 0.0.0-stage → 0.2.2

package/dist/transport-ws.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The WebSocket transport: the pipe listener's protocol, one frame per
+ * message (platform plan 02, "WebSocket listener: one frame per message,
+ * unchanged").
+ *
+ * The pipe frames each body with a `u32` length (`orrery-transport/src/frame.rs`);
+ * a WebSocket message already has a length, so the body *is* the message:
+ *
+ * 1. client → server: the [`Hello`], JSON text;
+ * 2. server → client: the [`HelloAck`], JSON text;
+ * 3. server → client: one AG-UI frame per message, replay first;
+ * 4. client → server: one `orrery_proto::Request` per message.
+ *
+ * Only JSON: CBOR is negotiable on the pipe, but a browser has no CBOR codec
+ * and the relay forwards bytes it never decodes (platform invariant 5).
+ *
+ * Every request is answered by a reply message (harness decision 0045):
+ * `{"t":"reply","reqId":"<request id>","ok":true,"value":…}` or
+ * `{"t":"reply","reqId":"…","ok":false,"error":"what to do"}`. Replies carry
+ * no `seq`; frames always have `seq` and never `t`. `send` resolves with the
+ * `value` or rejects with the `error`, matched on `request.id` == `reqId`;
+ * it rejects on close, and after 30 s with no reply.
+ *
+ * Browser-safe. In Node ≥ 22 the global `WebSocket` works; any other
+ * implementation (the `ws` package) can be passed as `WebSocket`.
+ */
+import { type CloseListener, type FrameListener, type Hello, type HelloAck, type Request, type Transport, type Unsubscribe } from "./transport.js";
+/** The part of the WHATWG `WebSocket` this transport uses. */
+export interface WebSocketLike {
+    readonly readyState: number;
+    binaryType: string;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    addEventListener(type: "open", listener: () => void): void;
+    addEventListener(type: "message", listener: (event: {
+        data: unknown;
+    }) => void): void;
+    addEventListener(type: "close", listener: (event: {
+        code: number;
+        reason: string;
+    }) => void): void;
+    addEventListener(type: "error", listener: (event: unknown) => void): void;
+}
+/** A `WebSocket` constructor: the global one, or `ws`'s. */
+export type WebSocketCtor = new (url: string, protocols?: string | string[]) => WebSocketLike;
+export interface WebSocketTransportOptions {
+    /** `ws(s)://host:port/path`. */
+    url: string;
+    /** Sent in the [`Hello`]: a browser cannot put a header on a WebSocket. */
+    token?: string;
+    /** The implementation; the global `WebSocket` when absent. */
+    WebSocket?: WebSocketCtor;
+}
+export declare class WebSocketTransport implements Transport {
+    readonly kind = "ws";
+    private readonly url;
+    private readonly token;
+    private readonly Ctor;
+    private socket;
+    private hub;
+    private readonly pending;
+    constructor(options: WebSocketTransportOptions);
+    connect(hello: Hello): Promise<HelloAck>;
+    subscribe(onFrame: FrameListener, onClose?: CloseListener): Unsubscribe;
+    send(request: Request): Promise<unknown>;
+    private failPending;
+    close(): Promise<void>;
+}

package/dist/transport.d.ts

@@ -0,0 +1,138 @@
+/**
+ * How a client reaches a session: a pluggable transport (platform plan 04).
+ *
+ * Every transport carries the same three things the pipe listener carries
+ * (`orrery-transport/src/listener/pipe.rs` + `frame.rs`):
+ *
+ * 1. a [`Hello`] out and a [`HelloAck`] back — always JSON, always first;
+ * 2. AG-UI [`Frame`]s in, each with its `seq`;
+ * 3. control [`Request`]s out.
+ *
+ * Two implementations ship: [`HttpSseTransport`] (`/events` as SSE, `/control`
+ * as JSON, what `orrery serve` speaks today) and [`WebSocketTransport`] (one
+ * frame per message, what the relay and the node's WebSocket listener speak).
+ * Neither imports anything from `node:`; this file is browser-safe.
+ */
+import { type Frame } from "./events.js";
+/** The AG-UI protocol version this client was built against (`orrery_agui::AGUI_PROTOCOL_VERSION`). */
+export declare const AGUI_PROTOCOL_VERSION = "1.0";
+/** A control request, as `orrery-proto` spells it. */
+export type Request = Record<string, unknown> & {
+    t: string;
+    id: string;
+};
+/**
+ * The first message on a connection. Always JSON.
+ *
+ * `format`, `protocol`, `session` and `since` are `orrery_transport::frame::Hello`
+ * verbatim. `machine`, `token`, `client` and `draws` are this SDK's additions
+ * for the relay and for a browser (which cannot set an `Authorization` header
+ * on a WebSocket); a server that does not know them ignores them, as serde
+ * does for any unknown field.
+ */
+export interface Hello {
+    format: "json";
+    protocol: string;
+    /** The session to attach to. */
+    session?: string;
+    /** The machine the session runs on, when it goes through the relay (`[machine/]session`). */
+    machine?: string;
+    /** Replay from just after this. Absent means from the start. */
+    since?: number;
+    /** A bearer token, for transports that cannot carry a header. */
+    token?: string;
+    /** What this client is, and what it draws (decision 0041 §2, 0042). */
+    client?: string;
+    draws?: string[];
+}
+/** What a server says back to a [`Hello`] (`orrery_transport::listener::pipe::HelloAck`). */
+export interface HelloAck {
+    format: "json";
+    protocol: string;
+    /** The last `seq` the session has reached. */
+    last_seq?: number;
+    /** Set when `since` was older than the replay ring: ask the session store. */
+    replay_too_old?: number;
+    /**
+     * This connection's number (harness decision 0058): a flow's question whose
+     * `requester.conn` is another is somebody else's. HTTP reads it from the
+     * `x-orrery-conn` header of `GET /events`.
+     */
+    conn?: number;
+}
+/**
+ * A control request the server refused. `message` is the server's words (what
+ * to do); `code` is the stable reason when the request has one
+ * (`workspace.*`, harness decision 0051): the reply's `code` on a WebSocket,
+ * the `x-orrery-code` header over HTTP.
+ */
+export declare class ControlError extends Error {
+    readonly code: string | undefined;
+    constructor(message: string, code?: string);
+}
+/** Called with every frame, in order. */
+export type FrameListener = (frame: Frame) => void;
+/** Called once when the stream ends: `undefined` for a clean close, the error otherwise. */
+export type CloseListener = (error?: Error) => void;
+/** Stops a subscription. */
+export type Unsubscribe = () => void;
+/**
+ * One way to reach a session. Every client draws through one of these; none
+ * knows which.
+ *
+ * The contract, checked by `test/transport.test.ts` against both
+ * implementations:
+ *
+ * - `connect` sends the [`Hello`] and resolves with the [`HelloAck`]. Frames
+ *   replayed from `since` arrive after it, through `subscribe`.
+ * - `subscribe` may be called before or after `connect`; frames that arrive
+ *   with no subscriber are buffered and handed to the first one, so none is
+ *   lost between the two calls.
+ * - `send` delivers one [`Request`]. It resolves with the server's answer
+ *   (HTTP: the `/control` body; WebSocket: the `value` of the `reply` message
+ *   whose `reqId` is `request.id`, harness decision 0045) and rejects with the
+ *   server's error text when it refuses.
+ * - `close` ends the stream; every close listener is told once.
+ */
+export interface Transport {
+    /** What this transport is called in messages: `http`, `ws`. */
+    readonly kind: string;
+    connect(hello: Hello): Promise<HelloAck>;
+    send(request: Request): Promise<unknown>;
+    subscribe(onFrame: FrameListener, onClose?: CloseListener): Unsubscribe;
+    close(): Promise<void>;
+}
+/**
+ * The frames of a transport as an async iterable: ends when the transport
+ * closes, throws when it fails.
+ */
+export declare function framesOf(transport: Transport): AsyncIterable<Frame>;
+/**
+ * Fan-out with a buffer: frames that arrive before anyone subscribes are kept
+ * for the first subscriber. Shared by both transports.
+ */
+export declare class FrameHub {
+    private readonly frames;
+    private readonly closes;
+    private pending;
+    private ended;
+    subscribe(onFrame: FrameListener, onClose?: CloseListener): Unsubscribe;
+    push(frame: Frame): void;
+    end(error?: Error): void;
+    get isEnded(): boolean;
+}
+/**
+ * Where a session lives: `[machine/]session`.
+ *
+ * A bare `session` is on the machine the transport reaches directly (the local
+ * node, or the node a URL names). `machine/session` goes through the relay,
+ * which routes by the pair (platform architecture, "A client attaches").
+ */
+export interface SessionAddress {
+    machine: string | null;
+    session: string;
+}
+/** Parse `[machine/]session`. Throws, saying the form, on anything else. */
+export declare function parseAddress(raw: string): SessionAddress;
+/** The address as text: `machine/session`, or `session`. */
+export declare function formatAddress(a: SessionAddress): string;

package/dist/workspace.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The person's own actions on a session's workspace (harness decision 0051):
+ * read a file, commit, push. Node-level requests, answered by the node that
+ * holds the session, on every transport and through the relay, like
+ * `sessions.list`. Not agent tools: no consent prompt; the node audits each
+ * as the person's.
+ *
+ * ```ts
+ * const file = await workspaceRead(transport, { session, path: "src/main.rs" });
+ * const { sha } = await workspaceCommit(transport, { session, message: "fix the build" });
+ * const { ok, output } = await workspacePush(transport, { session });
+ * ```
+ *
+ * A refusal rejects with a {@link ControlError} whose `code` is a
+ * {@link WorkspaceErrorCode} (`too_large`, `outside_workspace`,
+ * `nothing_to_commit`, `no_remote`, …) and whose message says the fix.
+ *
+ * A client with a control channel of its own (the ADE's IPC) builds the
+ * request with {@link workspaceRequest} and reads the answer as the types
+ * below.
+ */
+import type { WorkspaceCommitted, WorkspaceErrorCode, WorkspaceFile, WorkspacePushed } from "@getorrery/protocol";
+import { type Request, type Transport } from "./transport.js";
+export type { WorkspaceCommitted, WorkspaceErrorCode, WorkspaceFile, WorkspacePushed } from "@getorrery/protocol";
+/** The `t` of each request. */
+export declare const WORKSPACE_READ = "workspace.read";
+export declare const WORKSPACE_COMMIT = "workspace.commit";
+export declare const WORKSPACE_PUSH = "workspace.push";
+/** The largest file `workspace.read` answers with (`orrery_proto::workspace::READ_CAP_BYTES`). */
+export declare const WORKSPACE_READ_CAP_BYTES: number;
+/** `workspace.read`: one file's text, relative to the session's workspace. */
+export interface WorkspaceReadAsk {
+    session: string;
+    path: string;
+    /**
+     * The file as git's index holds it, not the disk: the side the live changes
+     * are measured against (harness decision 0056). Not in the index (a new
+     * file): refused with `not_found`.
+     */
+    base?: boolean;
+}
+/** `workspace.commit`: every change, or only `paths`. */
+export interface WorkspaceCommitAsk {
+    session: string;
+    message: string;
+    /** Only these paths, relative to the workspace. Absent: every change. */
+    paths?: string[];
+}
+/** `workspace.push`: the session's branch to its remote. */
+export interface WorkspacePushAsk {
+    session: string;
+}
+/** The wire form of each request, with a fresh `id`. */
+export declare const workspaceRequest: {
+    read(ask: WorkspaceReadAsk): Request;
+    commit(ask: WorkspaceCommitAsk): Request;
+    push(ask: WorkspacePushAsk): Request;
+};
+/** Read one file of the session's workspace as text. */
+export declare function workspaceRead(transport: Transport, ask: WorkspaceReadAsk): Promise<WorkspaceFile>;
+/** Commit the session's workspace; resolves with the new commit's sha. */
+export declare function workspaceCommit(transport: Transport, ask: WorkspaceCommitAsk): Promise<WorkspaceCommitted>;
+/** Push the session's branch; `ok: false` with git's words when the remote refused it. */
+export declare function workspacePush(transport: Transport, ask: WorkspacePushAsk): Promise<WorkspacePushed>;
+/** The workspace refusal's code, when `error` is one. */
+export declare function workspaceErrorCode(error: unknown): WorkspaceErrorCode | undefined;

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@getorrery/client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.2",
+  "description": "The TypeScript Orrery client SDK: an AG-UI session over a pluggable transport (HTTP+SSE, WebSocket) and a SurfaceStore. Pure data, no drawing. Browser-safe; Node-only parts in @getorrery/client/node.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "node": "./dist/node.js",
+      "default": "./dist/index.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "default": "./dist/node.js"
+    },
+    "./cloud-events": {
+      "types": "./dist/cloud-events.d.ts",
+      "default": "./dist/cloud-events.js"
+    },
+    "./browser": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kouji-dev/orrery",
+    "directory": "harness/clients/sdk-ts"
+  },
+  "dependencies": {
+    "@ag-ui/client": "^1.0.0",
+    "@ag-ui/core": "^1.0.0",
+    "@getorrery/ext": "0.2.2",
+    "@getorrery/protocol": "0.2.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "@types/ws": "^8.18.2",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.8",
+    "ws": "^8.21.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "node ../../../scripts/release/build-lib.mjs src/index.ts src/node.ts src/cloud-events.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
 }