@getorrery/client 0.0.0-stage → 0.2.1

package/README.md

@@ -1,3 +1,39 @@
-# Temporary Holding Version
+# `@getorrery/client`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The TypeScript half of the client SDK: `AguiSession` (decode, `seq`, re-attach `since`,
+control RPC) and `SurfaceStore`. **Pure data, no drawing** — exactly the same two things
+[`../../core/crates/orrery-client`](../../core/crates/orrery-client) gives Rust, built on
+stock `@ag-ui/client`'s `HttpAgent` over SSE.
+
+Types come from [`@getorrery/protocol`](../../protocol), which is generated by
+`cargo xtask typegen` and must not be hand-edited.
+
+```bash
+pnpm -C harness/clients/sdk-ts test   # vitest, over ../conformance
+```
+
+It passes the shared fixtures in [`../conformance`](../conformance) — the same files
+`orrery-client` runs in Rust, asserted the same way. If the two ever disagree, one of the
+five clients is drawing something the others are not.
+
+## The session is stock `@ag-ui/client`
+
+`AguiSession` wraps `HttpAgent` and hands it back unmodified through `httpAgent()`. That
+*is* the "existing AG-UI clients work unmodified" proof: if this package had to patch the
+agent, the claim would be false. What it adds is the half AG-UI has no vocabulary for —
+`session.attach(since)`, `turn.cancel`, `intent`, `consent.answer`, `query` — over a small
+`fetch` client against `POST /control`.
+
+`run()` parses the SSE stream itself rather than going through the agent's subscriber API,
+for one reason: our frames carry a `seq` the stock agent drops, and `seq` is the whole of
+the resumption story.
+
+## 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.
+
+**Status.** Implemented and `private` until there is something to publish.
+Implementation plan: [`harness/docs/plans/08-protocol-transport.md`](../../docs/plans/08-protocol-transport.md).

package/dist/anim.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Animation definitions (decision 0043, plan 38).
+ *
+ * The host sends each one once, at attach, as the AG-UI `CUSTOM` event
+ * `orrery.ui.anim` at `seq` 0 (outside the session's order, which starts at 1).
+ * `SurfaceStore` keeps them by id; a drawer (`@getorrery/anim`) draws any of them.
+ * The type is generated from `orrery-proto`; this file adds the name and a
+ * parser that fails loudly, naming the field.
+ */
+import type { AnimDef } from "@getorrery/protocol";
+export type { AnimDef, AnimGlyphs, AnimPixel, AnimPixelState, AnimSize, AnimState, AnimTheme, } from "@getorrery/protocol";
+/** The `Custom` name an animation definition rides under. */
+export declare const ANIM = "orrery.ui.anim";
+/** The `seq` of a frame outside the session's order: the definition, at attach. */
+export declare const OUT_OF_ORDER = 0;
+/**
+ * A definition from the wire.
+ *
+ * Throws an `Error` naming the field that is wrong and what it must match:
+ * every state has its frames in every theme, each as wide as `slots`, and the
+ * template names no slot it lacks. A drawer catches it and uses its glyphs.
+ */
+export declare function parseAnim(value: unknown): AnimDef;

package/dist/channel.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `orrery-client/1` from TypeScript (plan 36 task 10, decision 0038).
+ *
+ * A client the host started reads `ORRERY_ENDPOINT` (`pipe:<name>` with the
+ * `tty` grant — a named pipe on Windows, a Unix socket elsewhere, decision
+ * 0066 §4 — `stdio` without) and `ORRERY_TOKEN`, attaches, and then gets
+ * `client/frames` and sends `control/*`. The channel itself is `@getorrery/ext`'s
+ * `connect` — one implementation of the wire for every Node client — and this
+ * file gives it the AG-UI [`Frame`] type.
+ */
+import { CLIENT_PROTOCOL, type Client, type ConnectOptions } from "@getorrery/ext";
+import { type Frame } from "./events.js";
+export { CLIENT_PROTOCOL };
+/** The channel to the host, with frames typed as this package's [`Frame`]. */
+export interface ClientChannel extends Omit<Client, "frames"> {
+    frames(): AsyncIterable<Frame>;
+}
+/**
+ * The socket a `pipe:<name>` endpoint names: `\\.\pipe\<name>` on Windows,
+ * the socket's path elsewhere; `undefined` for any other endpoint.
+ */
+export declare function pipePath(endpoint: string, platform?: string): string | undefined;
+/** Attach over `ORRERY_ENDPOINT` + `ORRERY_TOKEN`, or the `input` / `output` given. */
+export declare function connectClient(options?: ConnectOptions): Promise<ClientChannel>;

package/dist/chunk-P3UGNLD6.js

@@ -0,0 +1,135 @@
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/cloud-events.ts
+var SseParser = class {
+  /** The last `id:` seen: what `Last-Event-ID` sends back. */
+  lastEventId;
+  buffer = "";
+  event = "";
+  data = [];
+  id;
+  /** Feed text; get the events it completed. */
+  push(text) {
+    this.buffer += text;
+    const out = [];
+    let start = 0;
+    for (let i = 0; i < this.buffer.length; i += 1) {
+      const c = this.buffer[i];
+      if (c !== "\n" && c !== "\r") continue;
+      if (c === "\r" && i === this.buffer.length - 1) break;
+      this.line(this.buffer.slice(start, i), out);
+      if (c === "\r" && this.buffer[i + 1] === "\n") i += 1;
+      start = i + 1;
+    }
+    this.buffer = this.buffer.slice(start);
+    return out;
+  }
+  line(line, out) {
+    if (line === "") {
+      if (this.data.length > 0 || this.event) {
+        out.push({ ...this.id !== void 0 ? { id: this.id } : {}, event: this.event || "message", data: this.data.join("\n") });
+      }
+      this.event = "";
+      this.data = [];
+      this.id = void 0;
+      return;
+    }
+    if (line.startsWith(":")) return;
+    const at = line.indexOf(":");
+    const field = at < 0 ? line : line.slice(0, at);
+    let value = at < 0 ? "" : line.slice(at + 1);
+    if (value.startsWith(" ")) value = value.slice(1);
+    switch (field) {
+      case "event":
+        this.event = value;
+        break;
+      case "data":
+        this.data.push(value);
+        break;
+      case "id":
+        if (!value.includes("\0")) {
+          this.id = value;
+          this.lastEventId = value;
+        }
+        break;
+      default:
+        break;
+    }
+  }
+};
+function cloudEventOf(e) {
+  let v = {};
+  try {
+    const parsed = e.data ? JSON.parse(e.data) : {};
+    if (parsed && typeof parsed === "object") v = parsed;
+  } catch {
+    if (e.event !== "reset") return null;
+  }
+  const str = (k) => typeof v[k] === "string" ? v[k] : void 0;
+  switch (e.event) {
+    case "reset":
+      return { kind: "reset" };
+    case "machine":
+      return str("machine_id") ? { ...v, kind: "machine" } : null;
+    case "host":
+      return str("host_id") ? { ...v, kind: "host" } : null;
+    case "session":
+      return str("session_id") && str("machine_id") ? { ...v, kind: "session" } : null;
+    case "lease":
+      return str("session_id") && typeof v["epoch"] === "number" ? { ...v, kind: "lease" } : null;
+    case "config":
+      return Array.isArray(v["keys"]) ? { ...v, kind: "config" } : null;
+    default:
+      return null;
+  }
+}
+function backoffMs(attempt, firstMs = 1e3, maxMs = 3e4) {
+  return Math.min(maxMs, firstMs * 2 ** Math.max(0, Math.min(attempt, 30)));
+}
+var CloudEventsError = class extends Error {
+  constructor(message, status) {
+    super(message);
+    this.status = status;
+    this.name = "CloudEventsError";
+  }
+};
+async function* cloudEvents(options) {
+  const f = options.fetch ?? fetch;
+  const response = await f(options.url, {
+    headers: {
+      accept: "text/event-stream",
+      Authorization: `Bearer ${options.token}`,
+      ...options.lastEventId ? { "Last-Event-ID": options.lastEventId } : {}
+    },
+    ...options.signal ? { signal: options.signal } : {}
+  });
+  if (!response.ok || !response.body) {
+    const why = await response.text().catch(() => "");
+    throw new CloudEventsError(`GET /events: ${response.status}${why ? ` ${why}` : ""}`, response.status);
+  }
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  const parser = new SseParser();
+  try {
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) return;
+      for (const e of parser.push(decoder.decode(value, { stream: true }))) yield e;
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+export {
+  __export,
+  SseParser,
+  cloudEventOf,
+  backoffMs,
+  CloudEventsError,
+  cloudEvents
+};