@nexus-code/remote-protocol 0.0.0-stage → 0.1.0

package/src/rpc.ts

@@ -0,0 +1,277 @@
+/**
+ * What one device asks another, sealed: JSON-RPC 2.0 requests, their
+ * answers, and the notifications a watch sends. The device that runs the
+ * sessions serves; the one that shows them asks.
+ *
+ * A session is named by the serving device's own ids: its workspace's and
+ * its tab's. The same folder has other ids on another device.
+ */
+import { z } from "zod";
+import {
+  AssistantItemSchema,
+  ChatStatusSchema,
+  ViewItemSchema,
+  ViewTaskSchema,
+  ViewToolCallSchema,
+} from "./view.js";
+
+// ---------------------------------------------------------------------------
+// JSON-RPC 2.0 shapes
+// ---------------------------------------------------------------------------
+
+export const RpcIdSchema = z.union([z.number().int(), z.string()]);
+
+export const RpcRequestSchema = z.object({
+  jsonrpc: z.literal("2.0"),
+  id: RpcIdSchema,
+  method: z.string(),
+  params: z.unknown().optional(),
+});
+export type RpcRequest = z.infer<typeof RpcRequestSchema>;
+
+export const RpcErrorSchema = z.object({
+  code: z.number().int(),
+  message: z.string(),
+  data: z.unknown().optional(),
+});
+export type RpcError = z.infer<typeof RpcErrorSchema>;
+
+// The error first: `result: z.unknown()` takes an object without one too,
+// and would strip an error answer's `error`.
+export const RpcResponseSchema = z.union([
+  z.object({ jsonrpc: z.literal("2.0"), id: RpcIdSchema, error: RpcErrorSchema }),
+  z.object({ jsonrpc: z.literal("2.0"), id: RpcIdSchema, result: z.unknown() }),
+]);
+export type RpcResponse = z.infer<typeof RpcResponseSchema>;
+
+export const RpcNotificationSchema = z.object({
+  jsonrpc: z.literal("2.0"),
+  method: z.string(),
+  params: z.unknown().optional(),
+});
+export type RpcNotification = z.infer<typeof RpcNotificationSchema>;
+
+export const RpcMessageSchema = z.union([
+  RpcRequestSchema,
+  RpcResponseSchema,
+  RpcNotificationSchema,
+]);
+export type RpcMessage = z.infer<typeof RpcMessageSchema>;
+
+/** The error codes: JSON-RPC's own, and the protocol's from 1000. */
+export const RpcErrorCode = {
+  ParseError: -32700,
+  InvalidRequest: -32600,
+  MethodNotFound: -32601,
+  InvalidParams: -32602,
+  InternalError: -32603,
+  /** No such workspace, tab or watch on the serving device. */
+  NotFound: 1001,
+  /** The serving device does not let this device do it. */
+  Forbidden: 1002,
+  /** The session cannot do it now: a chat with no request waiting, one whose program is gone. */
+  Unavailable: 1003,
+} as const;
+
+// ---------------------------------------------------------------------------
+// Sessions
+// ---------------------------------------------------------------------------
+
+/** A workspace of the serving device. */
+export const RemoteWorkspaceSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  /** Its folder, on the serving device. */
+  path: z.string(),
+});
+export type RemoteWorkspace = z.infer<typeof RemoteWorkspaceSchema>;
+
+/** Where a session stands, as the agent lists show it. */
+export const SessionStateSchema = z.enum(["needs-you", "running", "new-result", "idle", "ended"]);
+export type SessionState = z.infer<typeof SessionStateSchema>;
+
+/** An agent session or terminal of the serving device. */
+export const RemoteSessionSchema = z.object({
+  workspaceId: z.string(),
+  tabId: z.string(),
+  kind: z.enum(["claude", "codex", "terminal"]),
+  title: z.string(),
+  state: SessionStateSchema,
+  /** When it came to that state, in Unix milliseconds. */
+  since: z.number().optional(),
+  /** The last thing it said, a line. */
+  last: z.string().optional(),
+  /** The agent profile it runs with. */
+  profile: z.string().optional(),
+  /** What it waits on the user for, when it does. */
+  waiting: z
+    .object({
+      kind: z.enum(["permission", "question", "plan"]),
+      text: z.string(),
+    })
+    .optional(),
+});
+export type RemoteSession = z.infer<typeof RemoteSessionSchema>;
+
+const SessionsSchema = z.object({
+  workspaces: z.array(RemoteWorkspaceSchema),
+  sessions: z.array(RemoteSessionSchema),
+});
+
+/** A session of the serving device, by its ids there. */
+const TabRef = { workspaceId: z.string(), tabId: z.string() };
+
+// ---------------------------------------------------------------------------
+// Chats
+// ---------------------------------------------------------------------------
+
+/** Most items one chat.read gives; earlier ones come by `before`. */
+export const MAX_READ_ITEMS = 500;
+
+/**
+ * A page of a chat: its status, the items from `start` (before `total`),
+ * and the tool calls, tasks and subagents' messages they name.
+ */
+export const ChatPageSchema = z.object({
+  status: ChatStatusSchema,
+  start: z.number().int().nonnegative(),
+  total: z.number().int().nonnegative(),
+  items: z.array(ViewItemSchema),
+  tools: z.record(ViewToolCallSchema),
+  tasks: z.record(ViewTaskSchema),
+  agentItems: z.record(z.array(AssistantItemSchema)),
+});
+export type ChatPage = z.infer<typeof ChatPageSchema>;
+
+/**
+ * What changed in a watched chat since its last update (or its watch
+ * began). Items are put at their index; `total` cuts the list when it got
+ * shorter. Tool calls, tasks and subagents' messages are put by id.
+ */
+export const ChatUpdateSchema = z.object({
+  watchId: z.string(),
+  /** Counts the watch's updates from 1, so one lost shows. */
+  rev: z.number().int().positive(),
+  status: ChatStatusSchema.optional(),
+  total: z.number().int().nonnegative(),
+  items: z.array(z.object({ index: z.number().int().nonnegative(), item: ViewItemSchema })),
+  tools: z.record(ViewToolCallSchema),
+  tasks: z.record(ViewTaskSchema),
+  agentItems: z.record(z.array(AssistantItemSchema)),
+});
+export type ChatUpdate = z.infer<typeof ChatUpdateSchema>;
+
+/** The sessions' list as it is now, sent whenever it changes during a sessions.watch. */
+export const SessionsUpdateSchema = SessionsSchema.extend({ watchId: z.string() });
+export type SessionsUpdate = z.infer<typeof SessionsUpdateSchema>;
+
+const Ok = z.object({});
+
+// ---------------------------------------------------------------------------
+// The methods
+// ---------------------------------------------------------------------------
+
+/**
+ * Each method's params and result, and the capability (see ./sealed.ts)
+ * the serving device lists for it.
+ */
+export const RPC_METHODS = {
+  "sessions.list": { capability: "sessions", params: Ok, result: SessionsSchema },
+  /** The list now; then a sessions.update each time it changes, until sessions.unwatch. */
+  "sessions.watch": {
+    capability: "sessions",
+    params: Ok,
+    result: SessionsSchema.extend({ watchId: z.string() }),
+  },
+  "sessions.unwatch": {
+    capability: "sessions",
+    params: z.object({ watchId: z.string() }),
+    result: Ok,
+  },
+
+  /** The chat's last `limit` items, or those before `before`. */
+  "chat.read": {
+    capability: "chat.read",
+    params: z.object({
+      ...TabRef,
+      before: z.number().int().nonnegative().optional(),
+      limit: z.number().int().positive().max(MAX_READ_ITEMS).optional(),
+    }),
+    result: ChatPageSchema,
+  },
+  /** The chat's last page now; then a chat.update each time it changes, until chat.unwatch. */
+  "chat.watch": {
+    capability: "chat.read",
+    params: z.object({
+      ...TabRef,
+      limit: z.number().int().positive().max(MAX_READ_ITEMS).optional(),
+    }),
+    result: ChatPageSchema.extend({ watchId: z.string() }),
+  },
+  "chat.unwatch": {
+    capability: "chat.read",
+    params: z.object({ watchId: z.string() }),
+    result: Ok,
+  },
+
+  /** Sends a message, as its composer does: during a turn, the turn reads it next. */
+  "chat.send": {
+    capability: "chat.control",
+    params: z.object({ ...TabRef, text: z.string().min(1) }),
+    result: Ok,
+  },
+  /** Answers the permission request `requestId`, as its card's buttons do. */
+  "chat.answer": {
+    capability: "chat.control",
+    params: z.object({
+      ...TabRef,
+      requestId: z.string(),
+      decision: z.enum(["allow", "deny"]),
+      /** Why, for a denial: the program reads it. */
+      message: z.string().optional(),
+      /** With allow: the input the tool runs with, as the user filled it (a question's answers). */
+      updatedInput: z.record(z.unknown()).optional(),
+      /** With deny: the turn stops too, as the card's "No, and stop" does. */
+      stop: z.boolean().optional(),
+    }),
+    result: Ok,
+  },
+  "chat.interrupt": { capability: "chat.control", params: z.object(TabRef), result: Ok },
+  /** Opens a chat in one of the serving device's workspaces, sending it `prompt` if given. */
+  "chat.new": {
+    capability: "chat.control",
+    params: z.object({
+      workspaceId: z.string(),
+      agent: z.enum(["claude", "codex"]),
+      prompt: z.string().optional(),
+    }),
+    result: z.object({ tabId: z.string() }),
+  },
+  "chat.close": { capability: "chat.control", params: z.object(TabRef), result: Ok },
+
+  /** A terminal's screen and the lines above it, as text. Nothing can be typed into it. */
+  "terminal.read": {
+    capability: "terminal.read",
+    params: z.object({ ...TabRef, lines: z.number().int().positive().max(5000).optional() }),
+    result: z.object({ text: z.string() }),
+  },
+} as const;
+
+export type RpcMethod = keyof typeof RPC_METHODS;
+export type RpcParams<M extends RpcMethod> = z.infer<(typeof RPC_METHODS)[M]["params"]>;
+export type RpcResult<M extends RpcMethod> = z.infer<(typeof RPC_METHODS)[M]["result"]>;
+
+/** The notifications a serving device sends, by method. */
+export const RPC_NOTIFICATIONS = {
+  "sessions.update": SessionsUpdateSchema,
+  "chat.update": ChatUpdateSchema,
+} as const;
+
+export type RpcNotificationMethod = keyof typeof RPC_NOTIFICATIONS;
+export type RpcNotificationParams<M extends RpcNotificationMethod> = z.infer<
+  (typeof RPC_NOTIFICATIONS)[M]
+>;
+
+export function isRpcMethod(method: string): method is RpcMethod {
+  return Object.hasOwn(RPC_METHODS, method);
+}

package/src/sealed.ts

@@ -0,0 +1,69 @@
+/**
+ * What a sealed message carries, which only the account's devices can open.
+ *
+ * Sealing (v1): XChaCha20-Poly1305 with the room key, a fresh random 24-byte
+ * nonce per message, and the frame's routing as associated data (aadOf), so
+ * the relay can neither read a message nor pass it off as another's. The
+ * room key comes from the account key (see the account key design); every
+ * device of the account holds it. The bytes sealed are the message's JSON
+ * in UTF-8.
+ */
+import { z } from "zod";
+import { type DeviceId, DeviceIdSchema } from "./relay.js";
+import { RpcMessageSchema } from "./rpc.js";
+
+/** The version of what is sealed; a device tells it in its hello. */
+export const PROTOCOL_VERSION = 1;
+
+/** The HKDF info that makes the room key from the account key. */
+export const ROOM_KEY_INFO = "nexus-remote/room-key/v1";
+
+/**
+ * The associated data a message is sealed with: its routing, as the relay
+ * delivers it. A message the relay sends on to another device, or with
+ * another seq, does not open.
+ */
+export function aadOf(frame: { from: DeviceId; to: string; seq: number; kid: number }): string {
+  return `nexus-remote/v${PROTOCOL_VERSION}|${frame.from}|${frame.to}|${frame.seq}|${frame.kid}`;
+}
+
+/**
+ * What a device can do for another, as it says in its hello. The other
+ * side asks only for what is listed; a newer device lists more.
+ */
+export const CAPABILITIES = [
+  /** sessions.list and the session events. */
+  "sessions",
+  /** chat.read and chat.watch. */
+  "chat.read",
+  /** chat.send, chat.answer, chat.interrupt, chat.new and chat.close. */
+  "chat.control",
+  /** terminal.read: a terminal's screen, as text. */
+  "terminal.read",
+] as const;
+export const CapabilitySchema = z.string();
+export type Capability = (typeof CAPABILITIES)[number];
+
+/**
+ * A device introduces itself: to all the room as it joins, and to one that
+ * just joined. What it serves of its own sessions is `serves`; a device
+ * that only watches others (a phone) serves nothing.
+ */
+export const HelloSchema = z.object({
+  type: z.literal("hello"),
+  protocol: z.number().int().positive(),
+  device: z.object({
+    id: DeviceIdSchema,
+    name: z.string(),
+    platform: z.string(),
+  }),
+  app: z.object({ name: z.string(), version: z.string() }),
+  serves: z.array(CapabilitySchema),
+  /** Whether it wants the hello of devices already there: true as it joins. */
+  reply: z.boolean(),
+});
+export type Hello = z.infer<typeof HelloSchema>;
+
+/** A sealed message's content. */
+export const SealedMessageSchema = z.union([HelloSchema, RpcMessageSchema]);
+export type SealedMessage = z.infer<typeof SealedMessageSchema>;

package/src/view.ts

@@ -0,0 +1,214 @@
+/**
+ * A chat as another device draws it: the conversation the serving device's
+ * app already made of its program's log, trimmed of what only that app
+ * uses. The shapes follow the desktop app's chat model, so its chat view can
+ * draw a remote one as it draws its own; Claude Code's and Codex's own
+ * formats stay on the serving device, which keeps up with their versions.
+ *
+ * An item or call of a kind this version does not know stays parseable
+ * (UnknownItemSchema): a newer device may send more, and an older one skips it.
+ */
+import { z } from "zod";
+
+/** An image a message or a tool result holds. Its bytes stay on the serving device in v1. */
+export const ImageRefSchema = z.object({
+  mediaType: z.string(),
+  /** How many bytes the image takes. */
+  bytes: z.number().int().nonnegative(),
+});
+export type ImageRef = z.infer<typeof ImageRefSchema>;
+
+const at = z.number().optional();
+
+export const UserItemSchema = z.object({
+  kind: z.literal("user"),
+  key: z.string(),
+  text: z.string(),
+  images: z.array(ImageRefSchema),
+  /** sent: written to the program; taken: the program read it. */
+  state: z.enum(["sent", "taken"]),
+  /** Written during a turn and not read yet: it waits above the composer. */
+  queued: z.boolean().optional(),
+  at,
+});
+
+export const AssistantBlockSchema = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("text"), text: z.string() }),
+  z.object({ type: z.literal("thinking"), text: z.string() }),
+  z.object({ type: z.literal("tool"), toolUseId: z.string() }),
+]);
+
+export const AssistantItemSchema = z.object({
+  kind: z.literal("assistant"),
+  key: z.string(),
+  messageId: z.string(),
+  blocks: z.array(AssistantBlockSchema),
+  at,
+});
+export type ViewAssistantItem = z.infer<typeof AssistantItemSchema>;
+
+export const NoticeItemSchema = z.object({
+  kind: z.literal("notice"),
+  key: z.string(),
+  /** interrupted, exited, restarted, compacted, cleared, error…: a code the app names. */
+  code: z.string(),
+  detail: z.string().optional(),
+  at,
+});
+
+/** A message the program took that the user did not write: another session's, a channel's. */
+export const ReceivedItemSchema = z.object({
+  kind: z.literal("received"),
+  key: z.string(),
+  from: z.object({
+    kind: z.string(),
+    name: z.string().optional(),
+    agent: z.string().optional(),
+  }),
+  text: z.string(),
+  at,
+});
+
+export const TaskEndItemSchema = z.object({
+  kind: z.literal("task_end"),
+  key: z.string(),
+  taskId: z.string(),
+  status: z.string(),
+  description: z.string().optional(),
+  taskType: z.string().optional(),
+  summary: z.string().optional(),
+  toolUseId: z.string().optional(),
+  wakes: z.boolean().optional(),
+  at,
+});
+
+export const ShellItemSchema = z.object({
+  kind: z.literal("shell"),
+  key: z.string(),
+  command: z.string(),
+  stdout: z.string().optional(),
+  stderr: z.string().optional(),
+  at,
+});
+
+/** The item kinds this version knows. */
+export const ITEM_KINDS: ReadonlySet<string> = new Set([
+  "user",
+  "assistant",
+  "notice",
+  "received",
+  "task_end",
+  "shell",
+]);
+
+/**
+ * An item of a kind this version does not know: kept so the list stays
+ * whole, and not drawn. A known kind that does not fit its shape is no such item.
+ */
+export const UnknownItemSchema = z
+  .object({ kind: z.string().refine((kind) => !ITEM_KINDS.has(kind)), key: z.string() })
+  .passthrough();
+
+export const ViewItemSchema = z.union([
+  UserItemSchema,
+  AssistantItemSchema,
+  NoticeItemSchema,
+  ReceivedItemSchema,
+  TaskEndItemSchema,
+  ShellItemSchema,
+  UnknownItemSchema,
+]);
+export type ViewItem = z.infer<typeof ViewItemSchema>;
+
+/** Most characters of a tool's result text sent; the rest is cut (`truncated`). */
+export const MAX_RESULT_TEXT = 64 * 1024;
+
+export const ViewToolCallSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  displayName: z.string().optional(),
+  input: z.unknown(),
+  /** streaming, running, done, error, denied, stopped. */
+  status: z.string(),
+  result: z
+    .object({
+      text: z.string(),
+      isError: z.boolean(),
+      /** The program's structured result: a run's stdout, an edit's patch. */
+      structured: z.unknown().optional(),
+      images: z.array(ImageRefSchema),
+      /** The text was longer than MAX_RESULT_TEXT and is cut there. */
+      truncated: z.boolean().optional(),
+    })
+    .optional(),
+  /** The agent call it runs under; null on the main thread. */
+  parentToolUseId: z.string().nullable(),
+});
+export type ViewToolCall = z.infer<typeof ViewToolCallSchema>;
+
+/** A tool the program asks to run, which the user allows or denies. */
+export const ViewPermissionSchema = z.object({
+  requestId: z.string(),
+  toolName: z.string(),
+  displayName: z.string().optional(),
+  input: z.record(z.unknown()),
+  description: z.string().optional(),
+  decisionReason: z.string().optional(),
+  toolUseId: z.string().optional(),
+  /** A subagent's request. */
+  agentId: z.string().optional(),
+  /** The call as the card previews it, when the input alone does not tell it. */
+  preview: ViewToolCallSchema.optional(),
+});
+export type ViewPermission = z.infer<typeof ViewPermissionSchema>;
+
+/** A task the program runs beside the turn: a background run, a subagent. */
+export const ViewTaskSchema = z.object({
+  taskId: z.string(),
+  type: z.string(),
+  description: z.string(),
+  status: z.string(),
+  toolUseId: z.string().optional(),
+  startedAt: z.number().optional(),
+  endedAt: z.number().optional(),
+  summary: z.string().optional(),
+  activity: z.string().optional(),
+});
+export type ViewTask = z.infer<typeof ViewTaskSchema>;
+
+/** The reply being written: what the program streamed of its next message so far. */
+export const ViewStreamingSchema = z.object({
+  messageId: z.string(),
+  blocks: z.array(
+    z.object({
+      type: z.enum(["text", "thinking", "tool_use"]),
+      text: z.string(),
+      toolUseId: z.string().optional(),
+    }),
+  ),
+});
+export type ViewStreaming = z.infer<typeof ViewStreamingSchema>;
+
+/** Where a chat stands, apart from its messages. */
+export const ChatStatusSchema = z.object({
+  agent: z.enum(["claude", "codex"]),
+  title: z.string(),
+  /** The model it runs, as its program names it. */
+  model: z.string().optional(),
+  effort: z.string().optional(),
+  permissionMode: z.string().optional(),
+  /** A turn is under way. */
+  running: z.boolean(),
+  process: z.enum(["none", "running", "exited"]),
+  turn: z
+    .object({
+      startedAt: z.number().optional(),
+      outputTokens: z.number(),
+      /** requesting, compacting… */
+      status: z.string().optional(),
+    })
+    .nullable(),
+  streaming: ViewStreamingSchema.nullable(),
+  permissions: z.array(ViewPermissionSchema),
+});
+export type ChatStatus = z.infer<typeof ChatStatusSchema>;

package/src/voice.ts

@@ -0,0 +1,67 @@
+/**
+ * The voice socket: what a device says goes to the server as audio and
+ * comes back as text while it speaks (streaming speech to text).
+ *
+ * GET /voice?v=1&lang=<language> upgrades to a WebSocket, signed in as
+ * /relay is (a Bearer header, or ?ticket= from POST /relay/ticket). Then:
+ * - server: `ready`, naming the audio format and sample rate to send, and
+ *   the most seconds this session may take;
+ * - client: binary frames of audio in that format, about 100 ms each, then
+ *   `end` when the user stops;
+ * - server, as they come: `partial` (the words so far of the segment being
+ *   spoken; each replaces the last) and `final` (a finished segment, to
+ *   append; it clears the partial). Every partial and final after the
+ *   session's first final starts with the space its language puts between
+ *   segments (none for ja or zh): the text is the finals joined as they
+ *   came, then the partial, with nothing trimmed or added between;
+ * - server: `limit` if the audio ran past what the session or the
+ *   account's quota allows (audio past it is dropped; finals still come);
+ * - server: `done` with the seconds counted, once every final is out; then
+ *   it closes (1000). An `error` ends the session; it closes after.
+ */
+import { z } from "zod";
+
+export const VOICE_VERSION = 1;
+
+/** Most bytes in one audio frame (2 s of 16 kHz 16-bit mono); an even count. */
+export const MAX_AUDIO_FRAME_BYTES = 64 * 1024;
+
+/** The language to hear, BCP 47-ish: "ko", "en", "en-US", or "multi" to detect it. */
+export const VoiceLanguageSchema = z.string().regex(/^([a-z]{2,3}(-[A-Z]{2})?|multi)$/);
+
+/** What a device sends besides audio: that the user stopped speaking. */
+export const VoiceClientMessageSchema = z.object({ t: z.literal("end") });
+export type VoiceClientMessage = z.infer<typeof VoiceClientMessageSchema>;
+
+export const VoiceReadySchema = z.object({
+  t: z.literal("ready"),
+  format: z.literal("pcm_s16le"),
+  /** The rate to send at; it may change with the provider, so it is not to be assumed. */
+  sampleRate: z.number().int().positive(),
+  /** The fewer of the session's limit and what is left of the month's quota. */
+  maxSeconds: z.number().nonnegative(),
+});
+
+export const VoiceServerMessageSchema = z.discriminatedUnion("t", [
+  VoiceReadySchema,
+  z.object({ t: z.literal("partial"), text: z.string() }),
+  z.object({ t: z.literal("final"), text: z.string() }),
+  z.object({ t: z.literal("limit"), reason: z.enum(["session", "quota"]) }),
+  z.object({ t: z.literal("done"), seconds: z.number().nonnegative() }),
+  z.object({
+    t: z.literal("error"),
+    /** unauthorized: the device's sign-in ended (the socket closes 4001 after it). */
+    code: z.enum(["bad-frame", "provider-error", "unauthorized"]),
+    message: z.string(),
+  }),
+]);
+export type VoiceServerMessage = z.infer<typeof VoiceServerMessageSchema>;
+
+/** GET /voice/usage: this month's seconds, used and allowed. */
+export const VoiceUsageSchema = z.object({
+  /** The month, as YYYY-MM. */
+  period: z.string(),
+  usedSeconds: z.number().nonnegative(),
+  limitSeconds: z.number().nonnegative(),
+});
+export type VoiceUsage = z.infer<typeof VoiceUsageSchema>;