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

package/src/sealed.ts

@@ -0,0 +1,99 @@
+/**
+ * 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;
+
+/**
+ * This package's version, which a device tells in its hello (`schema`):
+ * the methods a device serves are those of its version, so another can
+ * leave out what an older one does not have. Kept equal to package.json's.
+ */
+export const SCHEMA_VERSION = "0.2.0";
+
+/** 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 sessions.watch, profiles.list. */
+  "sessions",
+  /** Reading a chat: chat.read and chat.watch, its settings, commands, panel, images, tool calls; history.list. */
+  "chat.read",
+  /** Acting in a chat: sending, answering, stopping, settings, commands, opening, resuming, renaming, closing. */
+  "chat.control",
+  /** terminal.read and terminal.watch: a terminal's screen, as text. */
+  "terminal.read",
+  /** Typing into a terminal, opening, renaming and closing one. */
+  "terminal.control",
+  /** files.list and files.read, in a workspace's folders. */
+  "files",
+  /** git.status, git.diff and git.log of a workspace. */
+  "git",
+  /**
+   * Takes agents' requests (`from`: nexus on another device) to act in its
+   * chats and terminals, as the user set it (Settings › Remote: ask or
+   * allow). Without it, a request with `from` is refused, whatever
+   * chat.control and terminal.control say: those are for people.
+   */
+  "agents",
+] 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(),
+    /** The app's color theme now, by its id ("github-dark"): a phone may follow it. */
+    theme: z.string().optional(),
+  }),
+  serves: z.array(CapabilitySchema),
+  /**
+   * The protocol package's version it speaks (SCHEMA_VERSION, "0.2.0");
+   * absent before 0.2.0. A method it does not have is answered MethodNotFound.
+   */
+  schema: z.string().max(40).optional(),
+  /** 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,297 @@
+/**
+ * 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,
+});
+
+/**
+ * Where an agent that sent a message can be answered: its tab, on the
+ * device `deviceId` (absent: the device this chat runs on). `nexus chat
+ * send` takes it as it is.
+ */
+export const ReplyAddressSchema = z.object({
+  deviceId: z.string().optional(),
+  workspaceId: z.string(),
+  tabId: z.string(),
+});
+export type ReplyAddress = z.infer<typeof ReplyAddressSchema>;
+
+/** 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(),
+    /** Sent from another device of the account: which one, as it names itself. */
+    device: z.object({ id: z.string(), name: z.string() }).optional(),
+    /** Where the sender takes an answer. */
+    replyTo: ReplyAddressSchema.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(),
+  /**
+   * What "always allow" would add, one choice each, in the serving
+   * device's words ("Allow Bash(npm test:*) in this folder"): chat.answer
+   * picks them by index.
+   */
+  suggestions: z.array(z.object({ label: z.string() })).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>;
+
+/** One step of the agent's to-do list. */
+export const ViewTodoSchema = z.object({
+  content: z.string(),
+  /** pending, in_progress or completed. */
+  status: z.string(),
+});
+
+/** A subagent the turn called (an Agent tool call). */
+export const ViewAgentRowSchema = z.object({
+  toolUseId: z.string(),
+  description: z.string(),
+  /** running, completed, failed or stopped. */
+  status: z.string(),
+  startedAt: z.number().optional(),
+  endedAt: z.number().optional(),
+});
+
+/** A goal the chat works toward (/goal), and where it stands. */
+export const ViewGoalSchema = z.object({
+  condition: z.string(),
+  /** active, paused, met or failed. */
+  status: z.string(),
+  setAt: z.number().optional(),
+  /** How many checks found it unmet so far. */
+  checks: z.number().int().nonnegative(),
+  /** Once it ended: why. */
+  reason: z.string().optional(),
+});
+export type ViewGoal = z.infer<typeof ViewGoalSchema>;
+
+/**
+ * What the chat's side panel shows beside the conversation: the to-do
+ * list, the tasks and subagents, the files it changed, the context it
+ * fills, what it cost, and its goal.
+ */
+export const ChatPanelSchema = z.object({
+  todos: z.array(ViewTodoSchema),
+  /** Background runs and the like, by the program's task ids (chat.stopTask stops one). */
+  tasks: z.array(ViewTaskSchema),
+  agents: z.array(ViewAgentRowSchema),
+  changedFiles: z.array(
+    z.object({
+      /** Absolute, on the serving device, as the chat's tool calls name it. */
+      path: z.string(),
+      added: z.number().int().nonnegative().optional(),
+      removed: z.number().int().nonnegative().optional(),
+    }),
+  ),
+  /** The context window: tokens in it, and how many it takes; null before the program said. */
+  context: z
+    .object({
+      usedTokens: z.number().int().nonnegative(),
+      maxTokens: z.number().int().positive(),
+    })
+    .nullable(),
+  /** What the conversation cost so far, in US dollars, when the program tells it. */
+  costUsd: z.number().nonnegative().optional(),
+  goal: ViewGoalSchema.nullable(),
+});
+export type ChatPanel = z.infer<typeof ChatPanelSchema>;

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>;