@vibefield/rosetta-protocol 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,74 @@
-# Temporary Holding Version
+# @vibefield/rosetta-protocol
 
-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.
+Install with `npm install @vibefield/rosetta-protocol`. The package ships ESM JavaScript and TypeScript declarations. Its npm version is independent of the wire protocol version.
+
+The wire types are generated from `crates/protocol` (ts-rs). Do not edit by hand — regenerate with:
+
+```sh
+TS_RS_EXPORT_DIR=$PWD/clients/ts/generated TS_RS_LARGE_INT=number \
+  cargo test -p rosetta-protocol --features ts
+```
+
+`TS_RS_LARGE_INT=number` is deliberate: every 64-bit field on the wire is a
+millisecond timestamp, ordinal, or token count — far below 2^53 — and the
+transport is plain JSON, so `JSON.parse` hands consumers `number`s.
+
+`client.ts` is the handwritten transport and subscription implementation.
+Consumers use its cancellation, reconnect, and cache APIs instead of merging
+REST pages with WebSocket state themselves. `SessionSubscription.fetchPage`
+holds history; `reveal` exposes its latest patched values; `loadEntry` adds an
+exact anchor. All three share the snapshot's generation and reset together.
+
+The client and Electron supervisor import `protocol-version.mjs`. When changing
+the wire incompatibly, bump it together with Rust's `PROTOCOL_VERSION`, regenerate
+the bindings, and refresh the wire golden. The protocol tests check that both
+languages agree. HTTP responses expose `x-rosetta-protocol-version`; WebSockets
+announce the same version in `hello`. Mismatches fail with an actionable error.
+
+## Package shape
+
+`exports` is exactly three entries, and they are the whole public surface:
+
+- `.` — the client plus the generated types. `client.ts` uses `fetch`,
+  `WebSocket`, `AbortController`, and `URLSearchParams`, so a consumer of this
+  entry needs `DOM` in its `lib`.
+- `./protocol-version` — the bare wire number and nothing else. It carries no
+  DOM dependency, so a supervisor that only checks a spawned daemon's version
+  imports it here instead of dragging the browser client into its typecheck.
+  TypeScript resolves the adjacent `protocol-version.d.mts` for the `.mjs`
+  under `moduleResolution` `Bundler` or `Node16`.
+- `./grants` — minting and verifying per-session grants (`canonicalize`,
+  `mintGrant`, `verifyGrant`, `parseGrantHeader`). Node-only: it signs with
+  `node:crypto`, so a browser bundle never imports it. `node-crypto.d.ts`
+  declares the two functions it uses, so `tsc -p clients/ts` needs no
+  `@types/node`.
+
+Everything else is encapsulated by `exports`: there are no deep
+imports of `./client` or `./generated/*`, and adding one is a change to this
+file, not to a consumer.
+
+## Credentials
+
+A daemon started with `--token-file` answers 401 to any request without a
+credential (docs/AUTH.md). Pass one as `new RosettaClient({ credential })`,
+or swap it later with `setCredential`:
+
+- `{ kind: "bearer", token }` opens every route.
+- `{ kind: "grant", grant }` opens one session's recorded history until the
+  grant's `exp` — and that session's recorded-file read (`readFileTarget`)
+  when it was minted with `SCOPE_FILES` beside `SCOPE_READ`. The daemon's
+  supervisor mints it with `@vibefield/rosetta-protocol/grants`; the client carries it
+  as an opaque string.
+
+REST requests send it as `Authorization`. WebSocket upgrades send it as the
+subprotocol pair `rosetta` + `rosetta.bearer.<base64url(token)>` or
+`rosetta.grant.<grant>`, because a browser's WebSocket cannot set headers;
+the daemon selects `rosetta`. A 401 throws `UnauthorizedError`, whose
+`reason` is the daemon's `x-rosetta-auth` header. An open socket is not
+re-checked, so a subscription outlives its grant's expiry until it
+reconnects.
+
+`npm ci` at the repository root installs the workspaces. `npm test` in this
+directory builds the SDK and runs `test/*.test.mjs` against its emitted JavaScript;
+the grant tests read the shared vectors in
+`crates/server/tests/fixtures/grants.json`.

package/dist/base64url.d.ts

@@ -0,0 +1,4 @@
+export declare function base64UrlEncode(bytes: Uint8Array): string;
+/** The bytes, or `null` for anything a strict decoder refuses. */
+export declare function base64UrlDecode(text: string): Uint8Array | null;
+export declare function utf8Base64UrlEncode(text: string): string;

package/dist/base64url.js

@@ -0,0 +1,48 @@
+// base64url without padding (RFC 4648 §5). Decoding is strict — the
+// alphabet only, no padding, zero trailing bits — so every byte string has
+// exactly one spelling, the rule the daemon's decoder applies to grants.
+// Browser-safe: the client encodes a bearer with it, grants.ts both ways.
+const ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+const VALUES = new Map([...ALPHABET].map((char, index) => [char, index]));
+function digit(value) {
+    return ALPHABET.charAt(value & 63);
+}
+export function base64UrlEncode(bytes) {
+    let text = "";
+    for (let at = 0; at < bytes.length; at += 3) {
+        const chunk = ((bytes[at] ?? 0) << 16) | ((bytes[at + 1] ?? 0) << 8) | (bytes[at + 2] ?? 0);
+        const width = Math.min(3, bytes.length - at);
+        text += digit(chunk >> 18) + digit(chunk >> 12);
+        if (width > 1)
+            text += digit(chunk >> 6);
+        if (width > 2)
+            text += digit(chunk);
+    }
+    return text;
+}
+/** The bytes, or `null` for anything a strict decoder refuses. */
+export function base64UrlDecode(text) {
+    if (text.length % 4 === 1)
+        return null;
+    const bytes = new Uint8Array(Math.floor((text.length * 3) / 4));
+    let buffer = 0;
+    let bits = 0;
+    let index = 0;
+    for (const char of text) {
+        const value = VALUES.get(char);
+        if (value === undefined)
+            return null;
+        buffer = (buffer << 6) | value;
+        bits += 6;
+        if (bits >= 8) {
+            bits -= 8;
+            bytes[index++] = (buffer >> bits) & 0xff;
+            buffer &= (1 << bits) - 1;
+        }
+    }
+    // Leftover bits of a canonical encoding are zero.
+    return buffer === 0 ? bytes : null;
+}
+export function utf8Base64UrlEncode(text) {
+    return base64UrlEncode(new TextEncoder().encode(text));
+}

package/dist/client.d.ts

@@ -0,0 +1,324 @@
+export { PROTOCOL_VERSION } from "./protocol-version.mjs";
+import type { TimelineEntryResponse } from "./generated/TimelineEntryResponse.js";
+import type { ApiError } from "./generated/ApiError.js";
+import type { ImageVariant } from "./generated/ImageVariant.js";
+import type { AssetRef } from "./generated/AssetRef.js";
+import type { BoostResponse } from "./generated/BoostResponse.js";
+import type { ContributionResponse } from "./generated/ContributionResponse.js";
+import type { CommandResponse } from "./generated/CommandResponse.js";
+import type { CollaborationTimeline } from "./generated/CollaborationTimeline.js";
+import type { DiscoveriesResponse } from "./generated/DiscoveriesResponse.js";
+import type { EnableResponse } from "./generated/EnableResponse.js";
+import type { ErrorCode } from "./generated/ErrorCode.js";
+import type { HeatmapResponse } from "./generated/HeatmapResponse.js";
+import type { ProjectRow } from "./generated/ProjectRow.js";
+import type { ProjectsResponse } from "./generated/ProjectsResponse.js";
+import type { RuntimeRow } from "./generated/RuntimeRow.js";
+import type { RuntimesResponse } from "./generated/RuntimesResponse.js";
+import type { SearchRequest } from "./generated/SearchRequest.js";
+import type { SearchResponse } from "./generated/SearchResponse.js";
+import type { ServerFrame } from "./generated/ServerFrame.js";
+import type { SessionResponse } from "./generated/SessionResponse.js";
+import type { SessionRow } from "./generated/SessionRow.js";
+import type { SessionsResponse } from "./generated/SessionsResponse.js";
+import type { Stamp } from "./generated/Stamp.js";
+import type { StatusResponse } from "./generated/StatusResponse.js";
+import type { TimelinePage } from "./generated/TimelinePage.js";
+import type { TimelineEntry } from "./generated/TimelineEntry.js";
+import type { TimelineMeta } from "./generated/TimelineMeta.js";
+import type { TimelineMetaPlanSource } from "./generated/TimelineMetaPlanSource.js";
+import type { PricingResponse } from "./generated/PricingResponse.js";
+import type { UsageResponse } from "./generated/UsageResponse.js";
+import type { ActivityResponse } from "./generated/ActivityResponse.js";
+import type { DayUsageResponse } from "./generated/DayUsageResponse.js";
+export declare const DEFAULT_BASE_URL = "http://127.0.0.1:4640";
+/**
+ * How a client proves itself to a daemon started with `--token-file`
+ * (docs/AUTH.md). A bearer opens every route; a grant opens one session's
+ * recorded history until its `exp`. The client only carries a grant, as an
+ * opaque string: minting needs the key (`@vibefield/rosetta-protocol/grants`).
+ */
+export type RosettaCredential = {
+    readonly kind: "bearer";
+    readonly token: string;
+} | {
+    readonly kind: "grant";
+    readonly grant: string;
+};
+/** Why a daemon refused a request: the `x-rosetta-auth` header of its 401. */
+export type AuthRefusal = "missing" | "bad-token" | "malformed" | "bad-signature" | "expired" | "wrong-session" | "wrong-scope" | "wrong-route" | "grants-disabled";
+export declare const AUTH_REFUSALS: readonly AuthRefusal[];
+export declare const AUTH_REASON_HEADER = "x-rosetta-auth";
+/** The subprotocol a daemon selects for a credentialed WebSocket upgrade. */
+export declare const AUTH_WS_PROTOCOL = "rosetta";
+/** The `Authorization` value that presents `credential`. */
+export declare function authorizationHeader(credential: RosettaCredential): string;
+/**
+ * A browser's WebSocket cannot set `Authorization`, so the credential rides
+ * the subprotocol list beside the marker the daemon selects. The daemon
+ * never echoes the credential entry.
+ */
+export declare function webSocketProtocols(credential: RosettaCredential): string[];
+export interface RosettaClientOptions {
+    baseUrl?: string;
+    /** Injectable for Node or test environments. */
+    fetchFn?: typeof fetch;
+    WebSocketImpl?: typeof WebSocket;
+    requestTimeoutMs?: number;
+    notificationIntervalMs?: number;
+    /** Presented on every request and upgrade; see {@link RosettaCredential}. */
+    credential?: RosettaCredential;
+}
+export declare class ApiRequestError extends Error {
+    readonly status: number;
+    readonly code: ErrorCode | null;
+    constructor(status: number, code: ErrorCode | null, message: string);
+}
+/** The bound watermark no longer matches: refetch from the head. */
+export declare class CursorExpiredError extends ApiRequestError {
+    constructor(message: string);
+}
+/** A 401: the daemon wants a credential this client did not present, or
+ * refused the one it did. `reason` is null only from a daemon that named
+ * none. */
+export declare class UnauthorizedError extends ApiRequestError {
+    readonly reason: AuthRefusal | null;
+    constructor(reason: AuthRefusal | null, message: string);
+}
+export type SubscriptionStatus = "connecting" | "syncing" | "live" | "resyncing" | "closed";
+export interface SessionSubscriptionHandlers {
+    /** Every replacement invalidates all loaded history, anchors, and in-flight reads. */
+    onReset?: () => void;
+    onSnapshot?: (page: TimelinePage) => void;
+    /** The full ordered visible timeline after each coalesced change. */
+    onChange?: (entries: TimelineEntry[]) => void;
+    /** The complete light work index. Bodies remain behind lazy references. */
+    onTimelineMetaChange?: (timelineMeta: TimelineMeta) => void;
+    onStatus?: (status: SubscriptionStatus) => void;
+    onError?: (error: ApiError) => void;
+}
+export interface MetaState {
+    runtimes: RuntimeRow[];
+    projects: ProjectRow[];
+    sessions: SessionRow[];
+}
+export interface MetaSubscriptionHandlers {
+    /** Snapshots establish a baseline; only mutations describe subsequent changes. */
+    onChange?: (state: MetaState, source: "snapshot" | "mutation") => void;
+    onStatus?: (status: SubscriptionStatus) => void;
+    onError?: (error: ApiError) => void;
+}
+export declare class RosettaClient {
+    private origin;
+    get baseUrl(): string;
+    private connection;
+    private readonly connectionListeners;
+    private readonly subscriptions;
+    private readonly requestTimeoutMs;
+    private readonly notificationIntervalMs;
+    private readonly fetchFn;
+    private readonly WebSocketImpl;
+    private credential;
+    constructor(options?: RosettaClientOptions);
+    /**
+     * Replace the credential (a refreshed grant, a rotated bearer), or drop
+     * it. Later requests and every later (re)connect present it. An open
+     * socket is left alone: the daemon checks a credential at the upgrade, so
+     * a grant that expires under a live subscription ends only with its
+     * socket, and the reconnect then needs a fresh one.
+     */
+    setCredential(credential: RosettaCredential | null): void;
+    private response;
+    private request;
+    status(signal?: AbortSignal): Promise<StatusResponse>;
+    /** The roll call's census — what discovery found, content-free. */
+    discoveries(signal?: AbortSignal): Promise<DiscoveriesResponse>;
+    /** Consent: enroll the chosen agent kinds. Grantable exactly once, while
+     * the daemon is awaiting consent. */
+    enableRuntimes(kinds: string[], signal?: AbortSignal): Promise<EnableResponse>;
+    /** Attention-directed ingestion: the reader opened a still-queued
+     * session — ask the daemon to read it next. Advisory; safe to fire on
+     * every selection of a pending session. */
+    boost(sessionId: string, signal?: AbortSignal): Promise<BoostResponse>;
+    runtimes(signal?: AbortSignal): Promise<RuntimesResponse>;
+    projects(signal?: AbortSignal): Promise<ProjectsResponse>;
+    sessions(options?: {
+        project?: string;
+        limit?: number;
+        native_session_id?: string;
+    }, signal?: AbortSignal): Promise<SessionsResponse>;
+    /** Resolve canonical rows for provider-native session ids; children come
+     * back too, and `root_session_id` names the navigable thread. */
+    sessionsByNativeId(nativeSessionIds: readonly string[], signal?: AbortSignal): Promise<SessionsResponse>;
+    session(id: string, signal?: AbortSignal): Promise<SessionResponse>;
+    /**
+     * One backward page. Pass the previous page's `cursor` to continue; a
+     * rewrite underneath throws {@link CursorExpiredError} — refetch from the
+     * head (no cursor).
+     */
+    timeline(sessionId: string, options?: {
+        limit?: number;
+        cursor?: string;
+    }, signal?: AbortSignal): Promise<TimelinePage>;
+    /** Complete delivered collaboration history for one team member. The
+     * response deliberately excludes private prose and tool rows. */
+    collaborationTimeline(sessionId: string, signal?: AbortSignal): Promise<CollaborationTimeline>;
+    /** An exact row and the generation it belongs to. */
+    timelineEntryResponse(sessionId: string, timelineId: string, signal?: AbortSignal): Promise<TimelineEntryResponse>;
+    timelineEntry(sessionId: string, timelineId: string, signal?: AbortSignal): Promise<TimelineEntry>;
+    reportWork(sessionId: string, timelineId: string, signal?: AbortSignal): Promise<TimelineEntry[]>;
+    /** Recover one deliberately omitted command body from its raw-ledger
+     * record. Nothing is fetched until the reader opens the disclosure. */
+    command(sessionId: string, timelineId: string, signal?: AbortSignal): Promise<CommandResponse>;
+    /** Read the live file named by one canonical file-bearing target. The caller
+     * supplies identities and an index, never a path; the daemon resolves the
+     * exact path already stored on that timeline row. */
+    /** Direct image URLs let the browser share compressed and decoded resources.
+     * Recipes are finite, versioned and enforced by the daemon. */
+    imageAssetUrl(asset: AssetRef, variant: ImageVariant): string;
+    imageFileTargetUrl(sessionId: string, timelineId: string, targetIndex: number, variant: ImageVariant): string;
+    readFileTarget(sessionId: string, timelineId: string, targetIndex: number, signal?: AbortSignal): Promise<Uint8Array>;
+    /** Resolve a canonical oversized-text member only when its disclosure is
+     * opened. Asset references are daemon-owned and may not redirect this
+     * authenticated/local client to another origin. */
+    readTextAsset(asset: AssetRef, signal?: AbortSignal): Promise<string>;
+    readAsset(asset: AssetRef, signal?: AbortSignal): Promise<Uint8Array>;
+    /** Read one exact plan document selected from timeline_meta. */
+    readPlan(sessionId: string, source: TimelineMetaPlanSource, signal?: AbortSignal): Promise<Uint8Array>;
+    search(request: SearchRequest, signal?: AbortSignal): Promise<SearchResponse>;
+    heatmap(projectId: string, options?: {
+        sinceMs?: number;
+        offsetMinutes?: number;
+    }, signal?: AbortSignal): Promise<HeatmapResponse>;
+    contribution(projectId: string, signal?: AbortSignal): Promise<ContributionResponse>;
+    /** The heatmap figure's decomposition over the same window: per-model days
+     * (they sum back to the heatmap exactly) plus an hour-of-day profile. */
+    usage(projectId: string, options?: {
+        sinceMs?: number;
+        offsetMinutes?: number;
+    }, signal?: AbortSignal): Promise<UsageResponse>;
+    /** Hourly model tokens for one date, using the heatmap's timezone offset. */
+    dayUsage(projectId: string, day: string, offsetMinutes?: number, signal?: AbortSignal): Promise<DayUsageResponse>;
+    /** Which top-level sessions were active in a window of at most seven days,
+     * newest recorded activity first, each with its tree's turns and the gaps
+     * inside them longer than `gapMs` (15 minutes unless asked). It spans
+     * sessions, so it needs the bearer. */
+    activity(window: {
+        sinceMs: number;
+        untilMs?: number;
+        sessions?: readonly string[];
+        gapMs?: number;
+        limit?: number;
+    }, signal?: AbortSignal): Promise<ActivityResponse>;
+    /** The price catalog behind every cost figure: its basis (list-price
+     * equivalent), version, sources, and the catalog the projection's rollup
+     * was priced with. */
+    pricing(signal?: AbortSignal): Promise<PricingResponse>;
+    /** A restarted app-owned daemon may bind another port. Abort old requests
+     * and reconnect existing consumers without losing the reader's selection. */
+    setBaseUrl(baseUrl: string): void;
+    onConnectionChange(listener: () => void): () => void;
+    private transport;
+    subscribeSession(sessionId: string, handlers: SessionSubscriptionHandlers): SessionSubscription;
+    subscribeMeta(handlers: MetaSubscriptionHandlers): MetaSubscription;
+    subscribeCollaboration(sessionId: string, handlers: CollaborationSubscriptionHandlers): CollaborationSubscription;
+}
+interface SubscriptionTransport {
+    url: () => string;
+    /** The credential's subprotocol pair, read at every (re)connect. */
+    protocols: () => string[] | undefined;
+    socket: typeof WebSocket;
+    interval: number;
+    onClose: (sub: BaseSubscription) => void;
+}
+declare abstract class BaseSubscription {
+    protected stamp: Stamp | null;
+    protected closed: boolean;
+    private readonly transport;
+    private socket;
+    private attempts;
+    private status;
+    private reconnectTimer;
+    private deadline;
+    private changeTimer;
+    constructor(transport: SubscriptionTransport);
+    protected start(): void;
+    private connect;
+    private retry;
+    private clearDeadline;
+    protected live(): void;
+    protected setStatus(status: SubscriptionStatus): void;
+    protected changed(immediate?: boolean): void;
+    protected cancelChange(): void;
+    /** Drop a generation and request an authoritative snapshot. */
+    restart(): void;
+    close(): void;
+    protected abstract invalidate(): void;
+    protected abstract handleFrame(frame: ServerFrame): void;
+    protected abstract flushChanges(): void;
+    protected abstract onStatus(status: SubscriptionStatus): void;
+    protected abstract onError(error: ApiError): void;
+    protected dispose(): void;
+}
+export declare class SessionSubscription extends BaseSubscription {
+    private readonly handlers;
+    private readonly client;
+    private readonly sessionId;
+    private readonly rows;
+    private readonly visible;
+    private timelineMeta;
+    private generation;
+    private watermark;
+    private readonly pending;
+    private rowsDirty;
+    private metaDirty;
+    constructor(transport: SubscriptionTransport, handlers: SessionSubscriptionHandlers, client: RosettaClient, sessionId: string);
+    entries(): TimelineEntry[];
+    protected dispose(): void;
+    protected invalidate(): void;
+    protected handleFrame(frame: ServerFrame): void;
+    private apply;
+    /** Hold a page in this cache without displaying it until the reader pulls. */
+    fetchPage(cursor: string, limit?: number, signal?: AbortSignal): Promise<TimelinePage>;
+    /** Reveal cached identities using their latest patched values. */
+    reveal(entries: readonly TimelineEntry[]): void;
+    loadEntry(timelineId: string, signal?: AbortSignal): Promise<boolean>;
+    private read;
+    protected flushChanges(): void;
+    protected onStatus(status: SubscriptionStatus): void;
+    protected onError(error: ApiError): void;
+}
+export declare class MetaSubscription extends BaseSubscription {
+    private readonly handlers;
+    private readonly runtimes;
+    private readonly projects;
+    private readonly sessions;
+    private dirty;
+    private source;
+    constructor(transport: SubscriptionTransport, handlers: MetaSubscriptionHandlers);
+    state(): MetaState;
+    protected invalidate(): void;
+    protected handleFrame(frame: ServerFrame): void;
+    protected flushChanges(): void;
+    protected onStatus(status: SubscriptionStatus): void;
+    protected onError(error: ApiError): void;
+}
+export interface CollaborationSubscriptionHandlers {
+    onChange?: (state: CollaborationTimeline) => void;
+    onReset?: () => void;
+    onStatus?: (status: SubscriptionStatus) => void;
+    onError?: (error: ApiError) => void;
+}
+export declare class CollaborationSubscription extends BaseSubscription {
+    private readonly handlers;
+    private readonly rows;
+    private readonly observations;
+    private dirty;
+    constructor(transport: SubscriptionTransport, handlers: CollaborationSubscriptionHandlers);
+    private observe;
+    protected invalidate(): void;
+    protected handleFrame(frame: ServerFrame): void;
+    protected flushChanges(): void;
+    protected onStatus(status: SubscriptionStatus): void;
+    protected onError(error: ApiError): void;
+}