@openmarket/rooms-client 0.1.0

package/src/doc-reconcile.ts

@@ -0,0 +1,160 @@
+/**
+ * The ONE client reconcile model (phase 4 P4-RECONCILE). Every pending
+ * reconcile, whatever produced it, is the same shape: three full contents
+ * (base / mine / theirs), the merge3 regions where they genuinely diverge,
+ * and the server head rev the merge was computed against. Three sources
+ * feed it:
+ *
+ * - "publish-conflict": two working copies published; the second writer's
+ *   publishDoc came back {status:"conflict"}. mine = the draft, theirs =
+ *   the server head, base = the published content at the draft's baseRev.
+ * - "disk-edit": the operator's on-disk mirror copy collided with a landed
+ *   head (the library conflict path re-pointed at this model). mine = the
+ *   local file, theirs = the server head, base = the receipt revision.
+ * - "run-revert": undoing an agent run diverged from later edits. mine =
+ *   the CURRENT head, theirs = the pre-run content the revert restores,
+ *   base = the run's final content (tharamine returns all three).
+ *
+ * Resolution always rides an expected-head fence, never a blind write:
+ * publish-conflict and run-revert resolutions publish through the one
+ * checkpoint primitive CAS'd on `headRev`; disk-edit resolutions ride the
+ * existing applyResolution path with `expectedHeadRev: headRev`. Either
+ * way a head that moved after mediation returns conflict/stale DATA and
+ * the model refreshes via `refreshDocReconcile`; nothing is overwritten
+ * and no draft is lost.
+ *
+ * Pure module (merge3 + types only), browser-safe by construction: the
+ * chat GUI builds and resolves models client-side.
+ */
+
+import { type Merge3Region, type MergeSkeletonPart, merge3 } from "./merge3.js";
+
+/** What produced a pending reconcile (labels and application route differ). */
+export type DocReconcileKind = "publish-conflict" | "disk-edit" | "run-revert";
+
+/** A per-region resolution: keep my side or take theirs. */
+export type DocRegionPick = "mine" | "theirs";
+
+export interface DocReconcileInput {
+  kind: DocReconcileKind;
+  docId: string;
+  path: string;
+  /**
+   * The shared ancestor of the two sides: the draft's baseRev content
+   * (publish-conflict), the mirror receipt revision (disk-edit), or the
+   * run's final content (run-revert). "" when unavailable: merge3 then
+   * degrades to one whole-document region, the side-by-side floor.
+   */
+  base: string;
+  /** My side: the working copy / local file, or the current head (run-revert). */
+  mine: string;
+  /** Their side: the server head, or the pre-run content (run-revert). */
+  theirs: string;
+  /** The server head rev the merge was computed against: the resolution fence. */
+  headRev: number;
+  /** Head author/note for the screen's explainer line (when known). */
+  theirsAuthor?: string | undefined;
+  theirsNote?: string | undefined;
+  /** run-revert: the run being undone. */
+  runId?: string | undefined;
+}
+
+export interface DocReconcileModel extends DocReconcileInput {
+  /** Diverging chunks (empty exactly when the merge is clean). */
+  regions: Merge3Region[];
+  /** Splice skeleton; null when the merge is clean (nothing to splice). */
+  skeleton: MergeSkeletonPart[] | null;
+  /** True when the two sides merge without mediation. */
+  clean: boolean;
+  /** The clean merge result ("" while regions exist). */
+  merged: string;
+}
+
+/**
+ * Which side of the model tracks the SERVER HEAD (the side that goes stale
+ * when the fence fails). For a run revert the head is "mine": the revert
+ * merges the pre-run content onto whatever the doc says now.
+ */
+export function docReconcileHeadSide(kind: DocReconcileKind): DocRegionPick {
+  return kind === "run-revert" ? "mine" : "theirs";
+}
+
+/** Build the model: one merge3 pass over the three contents. */
+export function buildDocReconcile(input: DocReconcileInput): DocReconcileModel {
+  const result = merge3(input.base, input.mine, input.theirs);
+  return {
+    ...input,
+    regions: result.regions,
+    skeleton: result.skeleton ?? null,
+    clean: result.clean,
+    merged: result.merged,
+  };
+}
+
+/**
+ * Turn per-region picks into the full resolved document. A clean model
+ * needs no picks (the merge IS the resolution); a diverging model requires
+ * exactly one pick per region, spliced through the merge3 skeleton so
+ * untouched text is never regenerated.
+ *
+ * The splice carries the picked LINE ARRAYS directly, never a joined
+ * string: spliceSkeleton's "" resolution means "drop the region" (a
+ * contract pinned for its other callers), so a picked side of [""] (one
+ * empty line, e.g. a separator blanked in place) would vanish through the
+ * string form. Here an empty array contributes nothing and [""] contributes
+ * exactly one empty line, so the applied document IS the picked bytes.
+ */
+export function resolveDocReconcile(model: DocReconcileModel, picks: DocRegionPick[]): string {
+  if (model.clean) return model.merged;
+  if (!model.skeleton) throw new Error("doc-reconcile: diverging model without a skeleton");
+  if (picks.length !== model.regions.length) {
+    throw new Error(
+      `doc-reconcile: ${model.regions.length} regions need ${model.regions.length} picks, got ${picks.length}`,
+    );
+  }
+  for (const [index, pick] of picks.entries()) {
+    if (pick !== "mine" && pick !== "theirs") {
+      throw new Error(`doc-reconcile: invalid pick for region ${index}`);
+    }
+  }
+  const lines: string[] = [];
+  for (const part of model.skeleton) {
+    if (part.kind === "lines") {
+      lines.push(...part.lines);
+      continue;
+    }
+    const region = model.regions[part.index];
+    const pick = picks[part.index];
+    if (!region || pick === undefined) {
+      throw new Error(`doc-reconcile: missing resolution for region ${part.index}`);
+    }
+    lines.push(...region[pick]);
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Fence failure: the server head moved after the model was built. Re-point
+ * the head-tracking side at the fresh head and re-merge; every other side
+ * (the draft, the local file, the pre-run target) is carried over verbatim,
+ * so nothing of mine is lost by a refresh.
+ */
+export function refreshDocReconcile(
+  model: DocReconcileModel,
+  head: { rev: number; content: string; authorHandle?: string; note?: string },
+): DocReconcileModel {
+  const side = docReconcileHeadSide(model.kind);
+  return buildDocReconcile({
+    kind: model.kind,
+    docId: model.docId,
+    path: model.path,
+    base: model.base,
+    mine: side === "mine" ? head.content : model.mine,
+    theirs: side === "theirs" ? head.content : model.theirs,
+    headRev: head.rev,
+    theirsAuthor:
+      side === "theirs" ? (head.authorHandle ?? model.theirsAuthor) : model.theirsAuthor,
+    theirsNote: side === "theirs" ? (head.note ?? model.theirsNote) : model.theirsNote,
+    runId: model.runId,
+  });
+}

package/src/doc-uri.ts

@@ -0,0 +1,83 @@
+import pc from "picocolors";
+
+import type { RoomDoc } from "./social-types.js";
+
+/**
+ * om://doc URIs — how docs travel through chat.
+ *
+ * A share is plain text on the wire (`om://doc/<docId>@<rev>`), so it
+ * survives every transport (rooms, DMs, copy-paste, other clients) with no
+ * protocol changes. Clients that understand the scheme render it as a pill
+ * and can annotate liveness ("head moved") from their local library cache;
+ * clients that don't still show a usable, resolvable reference.
+ */
+
+export interface DocUriRef {
+  docId: string;
+  rev?: number | undefined;
+}
+
+const DOC_URI_RE = /om:\/\/doc\/([A-Za-z0-9-]{8,64})(?:@(\d{1,9}))?/g;
+
+export function makeDocUri(docId: string, rev?: number): string {
+  return `om://doc/${docId}${rev !== undefined ? `@${rev}` : ""}`;
+}
+
+export function parseDocUris(text: string): DocUriRef[] {
+  const refs: DocUriRef[] = [];
+  for (const match of text.matchAll(DOC_URI_RE)) {
+    const docId = match[1];
+    if (!docId) continue;
+    const rev = match[2] !== undefined ? Number.parseInt(match[2], 10) : undefined;
+    refs.push({ docId, ...(rev !== undefined ? { rev } : {}) });
+  }
+  return refs;
+}
+
+export interface DocUriRenderContext {
+  /** Resolve a docId to its cached head (path + headRev), when known. */
+  lookup?: ((docId: string) => Pick<RoomDoc, "path" | "headRev"> | undefined) | undefined;
+}
+
+/**
+ * Process-wide lookup used by the tape renderers. The chat TUI registers its
+ * LibraryModel here once; every renderer (room tape, DMs, the legacy REPL)
+ * then annotates pills with live head receipts without threading the cache
+ * through a dozen render signatures. Renderers work unregistered too — pills
+ * just lose the path/receipt annotation.
+ */
+let activeLookup: DocUriRenderContext["lookup"];
+
+export function setDocUriLookup(lookup: DocUriRenderContext["lookup"]): void {
+  activeLookup = lookup;
+}
+
+export function decorateDocUrisLive(text: string): string {
+  if (!text.includes("om://doc/")) return text;
+  return decorateDocUris(text, { lookup: activeLookup });
+}
+
+/**
+ * Replace om://doc URIs with a rendered pill. With a library cache lookup the
+ * pill shows the doc's path and a head receipt (`@r3` vs `@r3→r5` when the
+ * head has moved past the shared revision); without one it stays a compact
+ * reference that is still visibly a doc link.
+ */
+export function decorateDocUris(text: string, context: DocUriRenderContext = {}): string {
+  return text.replace(DOC_URI_RE, (_raw, docId: string, revRaw: string | undefined) => {
+    const rev = revRaw !== undefined ? Number.parseInt(revRaw, 10) : undefined;
+    const known = context.lookup?.(docId);
+    if (!known) {
+      const revLabel = rev !== undefined ? pc.dim(`@r${rev}`) : "";
+      return `${pc.cyan(`⧉ doc:${docId.slice(0, 8)}`)}${revLabel}`;
+    }
+    const moved = rev !== undefined && known.headRev > rev;
+    const revLabel =
+      rev === undefined
+        ? pc.dim(`@r${known.headRev}`)
+        : moved
+          ? pc.yellow(`@r${rev}→r${known.headRev}`)
+          : pc.dim(`@r${rev}`);
+    return `${pc.cyan(`⧉ ${known.path}`)}${revLabel}`;
+  });
+}

package/src/endpoints.ts

@@ -0,0 +1,14 @@
+/**
+ * Default production endpoints, in their own module so the browser-importable
+ * client graph never touches constants.ts (which reads node:os/path for
+ * OM_HOME). Env overrides live in envString(), which no-ops in browsers.
+ */
+export const ROOMS_WS_URL = "wss://chat.kiyotaka.ai/ws/rooms";
+export const ROOM_CHAT_API_URL = "https://chat.kiyotaka.ai/chat";
+
+/** process.env reader that is safe in browsers (returns undefined). */
+export function envString(name: string): string | undefined {
+  const proc = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process;
+  const value = proc?.env?.[name];
+  return typeof value === "string" ? value : undefined;
+}

package/src/jwt.ts

@@ -0,0 +1,59 @@
+// Global crypto/atob: works in Bun, Node 18+, and browsers.
+const randomUUID = (): string => globalThis.crypto.randomUUID();
+
+import { type RoomAuthSuccessPayload, SUPPORTED_ROOM_PROTOCOL_VERSION } from "./types.js";
+
+/**
+ * Derive a room auth identity from an OM API key (a JWT) for the HTTP fallback
+ * path, where there is no server AUTH_SUCCESS frame. The claims are read
+ * best-effort; an unparseable key yields a synthesized placeholder identity
+ * rather than throwing.
+ */
+export function authFromApiKey(apiKey: string): RoomAuthSuccessPayload {
+  const payload = decodeJwtPayload(apiKey);
+  const userId =
+    stringClaim(payload, "sub") || stringClaim(payload, "id") || stringClaim(payload, "jti") || "";
+  const username =
+    stringClaim(payload, "username") ||
+    stringClaim(payload, "handle") ||
+    (userId ? `om-${userId.slice(-6)}` : "om-user");
+  return {
+    userId,
+    username,
+    handle: username,
+    connectionId: `http-${randomUUID()}`,
+    protocolVersion: SUPPORTED_ROOM_PROTOCOL_VERSION,
+  };
+}
+
+export function decodeJwtPayload(apiKey: string): Record<string, unknown> {
+  const [, payload] = apiKey.split(".");
+  if (!payload) return {};
+  try {
+    const normalized = payload.replace(/-/g, "+").replace(/_/g, "/");
+    const padded = normalized.padEnd(Math.ceil(normalized.length / 4) * 4, "=");
+    const parsed = JSON.parse(base64Utf8(padded)) as unknown;
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+      ? (parsed as Record<string, unknown>)
+      : {};
+  } catch {
+    return {};
+  }
+}
+
+export function stringClaim(payload: Record<string, unknown>, key: string): string | undefined {
+  const value = payload[key];
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function base64Utf8(value: string): string {
+  const nodeBuffer = (
+    globalThis as {
+      Buffer?: { from(data: string, encoding: string): { toString(encoding: string): string } };
+    }
+  ).Buffer;
+  if (nodeBuffer) return nodeBuffer.from(value, "base64").toString("utf8");
+  const binary = atob(value);
+  const bytes = Uint8Array.from(binary, (ch) => ch.charCodeAt(0));
+  return new TextDecoder().decode(bytes);
+}

package/src/library-publisher.ts

@@ -0,0 +1,93 @@
+/**
+ * The checkpoint publish primitive (phase 4 spine). Every surface that turns
+ * a private working copy into a shared revision (GUI editor, agent proposals,
+ * run undo, and eventually the disk mirror) publishes through `publishDoc`
+ * and nothing else.
+ *
+ * Contract (binding for the later work packages):
+ * - One write path. `publishDoc` routes through the existing `updateRoomDoc`
+ *   CAS call, which lands in tharamine's `commitContentChange` transaction.
+ *   There is no second writer here and none may be added: new publish
+ *   behavior extends this function, not the wire.
+ * - Publishing from a stale base never overwrites. A moved head comes back
+ *   as `{status: "conflict"}` DATA carrying the server's current head
+ *   (rev + content when available) so the reconcile surface can mediate;
+ *   it is never a thrown string. Non-conflict transport/HTTP failures still
+ *   throw (`RoomSocialError`), because they are errors, not outcomes.
+ * - Every publish is attributed. `source` defaults to "gui" (the working-copy
+ *   editor is the primary caller); agent, mirror, and CLI callers pass their
+ *   own source plus `credentialId`/`runId` when they have them. Absent rider
+ *   fields stay absent on the revision.
+ */
+
+import { RoomDocConflictError, updateRoomDoc } from "./social-client.js";
+import type {
+  RoomDoc,
+  RoomDocAttribution,
+  RoomDocConflictHead,
+  RoomDocRevisionSource,
+  RoomSocialConfig,
+} from "./social-types.js";
+
+export interface PublishDocInput extends RoomDocAttribution {
+  docId: string;
+  /** The published revision the working copy started from (the CAS base). */
+  baseRev: number;
+  /** The full document to land as the checkpoint. */
+  content: string;
+  /** Optional human change note (absent = server auto-derives "+A -R lines"). */
+  note?: string | undefined;
+  /** Display flag: the write was authored by an agent acting as the operator. */
+  asAgent?: boolean | undefined;
+}
+
+export type PublishDocResult =
+  | {
+      status: "published";
+      doc: RoomDoc;
+      /** The revision the checkpoint landed as. */
+      rev: number;
+      /** True when the content matched the head byte-for-byte (no revision). */
+      unchanged: boolean;
+    }
+  | {
+      status: "conflict";
+      /** The stale base the caller published from. */
+      baseRev: number;
+      /**
+       * The server's current head (content included) for the mediation
+       * surface. Null only when even the fallback head re-fetch failed.
+       */
+      head: RoomDocConflictHead | null;
+    };
+
+const DEFAULT_SOURCE: RoomDocRevisionSource = "gui";
+
+/** Publish a working copy as one attributed revision, CAS'd on `baseRev`. */
+export async function publishDoc(
+  config: RoomSocialConfig,
+  input: PublishDocInput,
+): Promise<PublishDocResult> {
+  try {
+    const result = await updateRoomDoc(config, input.docId, {
+      baseRev: input.baseRev,
+      content: input.content,
+      source: input.source ?? DEFAULT_SOURCE,
+      ...(input.note !== undefined ? { note: input.note } : {}),
+      ...(input.asAgent !== undefined ? { asAgent: input.asAgent } : {}),
+      ...(input.credentialId !== undefined ? { credentialId: input.credentialId } : {}),
+      ...(input.runId !== undefined ? { runId: input.runId } : {}),
+    });
+    return {
+      status: "published",
+      doc: result.doc,
+      rev: result.rev,
+      unchanged: result.unchanged,
+    };
+  } catch (error) {
+    if (error instanceof RoomDocConflictError) {
+      return { status: "conflict", baseRev: input.baseRev, head: error.head };
+    }
+    throw error;
+  }
+}