@linkshell/wire 0.0.0-stage → 0.1.1

package/src/model.ts

@@ -0,0 +1,210 @@
+import { z } from "zod";
+
+/**
+ * How far LinkShell can take a given agent. The UI renders capabilities from
+ * this instead of guessing:
+ * - multi_client: desktop TUI and remote devices are live clients of one agent
+ *   server (Codex app-server, OpenCode server).
+ * - handoff: the native TUI owns the session on the desktop; a remote device can
+ *   take it over and the session continues headlessly under the same id.
+ * - remote: structured control only; the desktop uses LinkShell's own UI.
+ * - terminal: PTY only.
+ */
+export const agentTierSchema = z.enum(["multi_client", "handoff", "remote", "terminal"]);
+export type AgentTier = z.infer<typeof agentTierSchema>;
+
+export const agentCapabilitiesSchema = z.object({
+  interrupt: z.boolean(),
+  /** Inject a message into a running turn instead of queueing it. */
+  steer: z.boolean(),
+  permissions: z.boolean(),
+  images: z.boolean(),
+  fork: z.boolean(),
+  models: z.boolean(),
+  modes: z.boolean(),
+});
+export type AgentCapabilities = z.infer<typeof agentCapabilitiesSchema>;
+
+/**
+ * How the agent authenticates on this machine, as the agent itself reports it
+ * (e.g. `claude auth status`, `codex login status`). LinkShell never handles
+ * the credentials; it runs agents with the user's own environment and config.
+ */
+export const agentAuthSchema = z.object({
+  state: z.enum(["ok", "missing", "unknown"]),
+  /** e.g. "claude.ai", "api_key", "oauth_token", "chatgpt", "bedrock". */
+  method: z.string().optional(),
+  /** What the user should do when state is "missing". */
+  hint: z.string().optional(),
+});
+export type AgentAuth = z.infer<typeof agentAuthSchema>;
+
+export const agentInfoSchema = z.object({
+  id: z.string().min(1),
+  label: z.string().min(1),
+  tier: agentTierSchema,
+  installed: z.boolean(),
+  version: z.string().optional(),
+  /** Human-readable reason when the agent is installed but unusable. */
+  problem: z.string().optional(),
+  auth: agentAuthSchema.optional(),
+  capabilities: agentCapabilitiesSchema,
+});
+export type AgentInfo = z.infer<typeof agentInfoSchema>;
+
+/**
+ * Who is driving a handoff session right now: the desktop's native UI, this
+ * host on behalf of a device, or nobody (either side can continue).
+ */
+export const sessionDriverSchema = z.enum(["desktop", "remote", "none"]);
+export type SessionDriver = z.infer<typeof sessionDriverSchema>;
+
+export const sessionStateSchema = z.enum(["idle", "running", "waiting", "error", "offline"]);
+export type SessionState = z.infer<typeof sessionStateSchema>;
+
+export const toolKindSchema = z.enum([
+  "read",
+  "edit",
+  "delete",
+  "move",
+  "search",
+  "execute",
+  "think",
+  "fetch",
+  "other",
+]);
+export type ToolKind = z.infer<typeof toolKindSchema>;
+
+export const permissionOptionSchema = z.object({
+  optionId: z.string().min(1),
+  name: z.string().min(1),
+  kind: z.enum(["allow_once", "allow_always", "reject_once", "reject_always"]),
+});
+export type PermissionOption = z.infer<typeof permissionOptionSchema>;
+
+/** What a running session is doing right now, for list rows. Live only. */
+export const sessionActivitySchema = z.object({
+  kind: z.enum(["thinking", "responding", "tool"]),
+  title: z.string().optional(),
+  toolKind: toolKindSchema.optional(),
+});
+export type SessionActivity = z.infer<typeof sessionActivitySchema>;
+
+/** The oldest unanswered permission request, so lists can offer approval inline. Live only. */
+export const pendingPermissionSchema = z.object({
+  requestId: z.string(),
+  toolCallId: z.string().optional(),
+  title: z.string(),
+  detail: z.string().optional(),
+  options: z.array(permissionOptionSchema).min(1),
+});
+export type PendingPermissionSummary = z.infer<typeof pendingPermissionSchema>;
+
+export const queuedMessageSchema = z.object({
+  clientMessageId: z.string(),
+  /** The message's text (images are counted, not sent). */
+  text: z.string(),
+  images: z.number().int().nonnegative(),
+});
+export type QueuedMessage = z.infer<typeof queuedMessageSchema>;
+
+export const sessionSummarySchema = z.object({
+  /** `${agent}:${nativeId}` — stable across daemon restarts and rediscovery. */
+  id: z.string().min(1),
+  agent: z.string().min(1),
+  nativeId: z.string().min(1),
+  title: z.string().optional(),
+  preview: z.string().optional(),
+  cwd: z.string(),
+  state: sessionStateSchema,
+  driver: sessionDriverSchema.optional(),
+  pendingPermissions: z.number().int().nonnegative(),
+  model: z.string().optional(),
+  createdAt: z.number(),
+  updatedAt: z.number(),
+  lastSeq: z.number().int().nonnegative(),
+  archived: z.boolean(),
+  activity: sessionActivitySchema.optional(),
+  permission: pendingPermissionSchema.optional(),
+  /**
+   * Live only: messages waiting for the current turn to end, when the host
+   * holds them (agents that can't take input mid-turn). Oldest first.
+   */
+  queue: z.array(queuedMessageSchema).optional(),
+});
+export type SessionSummary = z.infer<typeof sessionSummarySchema>;
+
+export function sessionIdFor(agent: string, nativeId: string): string {
+  return `${agent}:${nativeId}`;
+}
+
+export function parseSessionId(id: string): { agent: string; nativeId: string } | null {
+  const index = id.indexOf(":");
+  if (index <= 0 || index === id.length - 1) return null;
+  return { agent: id.slice(0, index), nativeId: id.slice(index + 1) };
+}
+
+export const projectSummarySchema = z.object({
+  cwd: z.string(),
+  name: z.string(),
+  lastActiveAt: z.number(),
+  sessionCount: z.number().int().nonnegative(),
+});
+export type ProjectSummary = z.infer<typeof projectSummarySchema>;
+
+export const machineInfoSchema = z.object({
+  machineId: z.string().min(1),
+  hostname: z.string(),
+  platform: z.string(),
+  hostVersion: z.string(),
+  /** The host user's home directory, so apps can show paths as `~/…`. */
+  home: z.string().optional(),
+  agents: z.array(agentInfoSchema),
+});
+export type MachineInfo = z.infer<typeof machineInfoSchema>;
+
+/** A server listening on the host, which a device can preview through the encrypted channel. */
+export const portInfoSchema = z.object({
+  port: z.number().int().min(1).max(65535),
+  /** The listening process ("node", "python3.12"). */
+  process: z.string(),
+  pid: z.number().int().optional(),
+  /** The process's working directory: which project the server belongs to. */
+  cwd: z.string().optional(),
+  /** The page title, when the port answers HTTP with an HTML page. */
+  title: z.string().optional(),
+  /** Answers HTTP at all (a dev server, not a database). */
+  http: z.boolean(),
+});
+export type PortInfo = z.infer<typeof portInfoSchema>;
+
+/** A shell the host keeps open, independent of any device connection. */
+export const terminalInfoSchema = z.object({
+  id: z.string(),
+  /** What's running in the foreground (the shell or its current command). */
+  title: z.string(),
+  cwd: z.string(),
+  cols: z.number().int(),
+  rows: z.number().int(),
+  createdAt: z.number(),
+  /** Last output time. */
+  activeAt: z.number(),
+  /** The command it was started to run, if any (else it's a plain shell). */
+  command: z.string().optional(),
+  /** Set once the shell ended; the terminal and its output stay until deleted. */
+  exitCode: z.number().int().nullable().optional(),
+  /** Ended without an exit code: the host stopped while it ran. */
+  interrupted: z.boolean().optional(),
+});
+export type TerminalInfo = z.infer<typeof terminalInfoSchema>;
+
+/** The host's link to a v2 gateway, for `linkshell status` and the app's computer page. */
+export const gatewayStatusSchema = z.object({
+  url: z.string().optional(),
+  status: z.enum(["off", "connecting", "online", "offline"]),
+  error: z.object({ code: z.string(), message: z.string() }).optional(),
+  machine: z.object({ id: z.string(), name: z.string() }).optional(),
+  account: z.object({ userId: z.string(), email: z.string().optional() }).optional(),
+  devices: z.array(z.object({ id: z.string(), name: z.string(), pairedAt: z.number(), online: z.boolean() })),
+});
+export type GatewayStatus = z.infer<typeof gatewayStatusSchema>;

package/src/peer.ts

@@ -0,0 +1,170 @@
+import type { RpcErrorObject, RpcId } from "./rpc.js";
+import { RPC_APP_ERROR, RPC_METHOD_NOT_FOUND } from "./rpc.js";
+
+/** An error that crosses the wire as a JSON-RPC error object. */
+export class RpcError extends Error {
+  constructor(
+    readonly code: number,
+    message: string,
+    readonly data?: unknown,
+  ) {
+    super(message);
+    this.name = "RpcError";
+  }
+
+  static app(appCode: string, message: string, extra?: Record<string, unknown>): RpcError {
+    return new RpcError(RPC_APP_ERROR, message, { code: appCode, ...extra });
+  }
+
+  /** The `data.code` of an application error, if any. */
+  get appCode(): string | undefined {
+    const data = this.data as { code?: unknown } | undefined;
+    return typeof data?.code === "string" ? data.code : undefined;
+  }
+
+  toObject(): RpcErrorObject {
+    return this.data === undefined
+      ? { code: this.code, message: this.message }
+      : { code: this.code, message: this.message, data: this.data };
+  }
+}
+
+/** Returned by a request handler to leave a request unanswered for good. */
+export const ABANDON = Symbol("rpc.abandon");
+
+export type RequestHandler = (
+  method: string,
+  params: unknown,
+  id: RpcId,
+) => unknown | Promise<unknown>;
+export type NotificationHandler = (method: string, params: unknown) => void;
+
+export interface RpcPeerOptions {
+  /** Sends one serialized JSON-RPC message. */
+  send: (text: string) => void;
+  onRequest?: RequestHandler;
+  onNotification?: NotificationHandler;
+  /** Default timeout for outgoing requests; 0 disables it. */
+  requestTimeoutMs?: number;
+}
+
+interface Pending {
+  resolve: (value: unknown) => void;
+  reject: (error: Error) => void;
+  timer?: ReturnType<typeof setTimeout>;
+  method: string;
+}
+
+/**
+ * Transport-agnostic JSON-RPC 2.0 peer: both sides can issue requests and
+ * notifications. Feed incoming text frames to `receive()`.
+ */
+export class RpcPeer {
+  private nextId = 1;
+  private readonly pending = new Map<RpcId, Pending>();
+  private closed = false;
+
+  constructor(private readonly options: RpcPeerOptions) {}
+
+  request<T = unknown>(method: string, params?: unknown, timeoutMs?: number): Promise<T> {
+    if (this.closed) return Promise.reject(new RpcError(RPC_APP_ERROR, `connection closed (${method})`));
+    const id = this.nextId++;
+    return new Promise<T>((resolve, reject) => {
+      const entry: Pending = { resolve: resolve as (v: unknown) => void, reject, method };
+      const limit = timeoutMs ?? this.options.requestTimeoutMs ?? 30_000;
+      if (limit > 0) {
+        entry.timer = setTimeout(() => {
+          this.pending.delete(id);
+          reject(new RpcError(RPC_APP_ERROR, `${method} timed out after ${limit}ms`, { code: "timeout" }));
+        }, limit);
+      }
+      this.pending.set(id, entry);
+      this.write({ jsonrpc: "2.0", id, method, params: params ?? {} });
+    });
+  }
+
+  notify(method: string, params?: unknown): void {
+    if (this.closed) return;
+    this.write({ jsonrpc: "2.0", method, params: params ?? {} });
+  }
+
+  receive(text: string): void {
+    for (const line of text.split("\n")) {
+      if (!line.trim()) continue;
+      let message: Record<string, unknown>;
+      try {
+        message = JSON.parse(line) as Record<string, unknown>;
+      } catch {
+        continue;
+      }
+      this.dispatch(message);
+    }
+  }
+
+  /** Rejects every in-flight request; later calls fail immediately. */
+  close(reason = "connection closed"): void {
+    if (this.closed) return;
+    this.closed = true;
+    for (const [id, entry] of this.pending) {
+      if (entry.timer) clearTimeout(entry.timer);
+      entry.reject(new RpcError(RPC_APP_ERROR, `${reason} (${entry.method})`, { code: "closed" }));
+      this.pending.delete(id);
+    }
+  }
+
+  get isClosed(): boolean {
+    return this.closed;
+  }
+
+  private dispatch(message: Record<string, unknown>): void {
+    const id = message.id as RpcId | undefined;
+    const method = typeof message.method === "string" ? message.method : undefined;
+
+    if (method === undefined) {
+      if (id === undefined) return;
+      const entry = this.pending.get(id);
+      if (!entry) return;
+      this.pending.delete(id);
+      if (entry.timer) clearTimeout(entry.timer);
+      const error = message.error as RpcErrorObject | undefined;
+      if (error) entry.reject(new RpcError(error.code, error.message, error.data));
+      else entry.resolve(message.result);
+      return;
+    }
+
+    if (id === undefined) {
+      this.options.onNotification?.(method, message.params);
+      return;
+    }
+
+    const handler = this.options.onRequest;
+    if (!handler) {
+      this.write({ jsonrpc: "2.0", id, error: { code: RPC_METHOD_NOT_FOUND, message: `no handler for ${method}` } });
+      return;
+    }
+    Promise.resolve()
+      .then(() => handler(method, message.params, id))
+      .then(
+        (result) => {
+          if (result === ABANDON) return;
+          this.write({ jsonrpc: "2.0", id, result: result ?? {} });
+        },
+        (error: unknown) => {
+          const rpcError =
+            error instanceof RpcError
+              ? error
+              : new RpcError(RPC_APP_ERROR, error instanceof Error ? error.message : String(error), { code: "internal" });
+          this.write({ jsonrpc: "2.0", id, error: rpcError.toObject() });
+        },
+      );
+  }
+
+  private write(message: Record<string, unknown>): void {
+    if (this.closed) return;
+    try {
+      this.options.send(JSON.stringify(message));
+    } catch {
+      this.close("send failed");
+    }
+  }
+}

package/src/relay-client.ts

@@ -0,0 +1,289 @@
+import { gatewayChallengeMessage, publicIdentity, sign, type Identity, type PublicIdentity } from "./crypto.js";
+import {
+  serverFrameSchema,
+  tunnelFrameSchema,
+  type ClientFrame,
+  type PeerRole,
+  type RelayEvents,
+  type RelayMethod,
+  type RelayMethods,
+  type TunnelFrame,
+} from "./relay.js";
+
+// One connection from a machine or device to a v2 gateway: authenticates,
+// reconnects, makes control requests and carries tunnel frames. Runs on
+// Node (ws) and in React Native (WebSocket) alike.
+
+export interface RelaySocket {
+  readonly readyState: number;
+  send(data: string): void;
+  close(code?: number, reason?: string): void;
+  onopen: ((event: unknown) => void) | null;
+  onmessage: ((event: { data: unknown }) => void) | null;
+  onclose: ((event: { code?: number; reason?: string }) => void) | null;
+  onerror: ((event: unknown) => void) | null;
+}
+
+export type RelayStatus = "connecting" | "online" | "offline" | "stopped";
+
+export interface RelayClientOptions {
+  url: string;
+  identity: Identity;
+  role: PeerRole;
+  name: string;
+  platform?: string;
+  /** Account token, fetched fresh for each connection. */
+  token?: () => Promise<string | undefined> | string | undefined;
+  createSocket: (url: string) => RelaySocket;
+  minBackoffMs?: number;
+  maxBackoffMs?: number;
+  requestTimeoutMs?: number;
+}
+
+export class RelayRequestError extends Error {
+  constructor(
+    readonly code: string,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+const OPEN = 1;
+
+export class RelayClient {
+  private socket?: RelaySocket;
+  private statusValue: RelayStatus = "offline";
+  private attempt = 0;
+  private timer?: ReturnType<typeof setTimeout>;
+  private nextId = 1;
+  private readonly pending = new Map<number, { resolve: (value: unknown) => void; reject: (error: Error) => void; timer: ReturnType<typeof setTimeout> }>();
+  private readonly statusListeners = new Set<(status: RelayStatus, error?: { code: string; message: string }) => void>();
+  private readonly frameListeners = new Set<(from: PublicIdentity, via: "paired" | "account", frame: TunnelFrame) => void>();
+  private readonly undeliverableListeners = new Set<(to: string, reason: string) => void>();
+  private readonly eventListeners = new Map<string, Set<(data: unknown) => void>>();
+  private readonly waiters = new Set<() => void>();
+  /** Account the gateway recognised on the last connection. */
+  account?: { userId: string; email?: string };
+  lastError?: { code: string; message: string };
+
+  constructor(private readonly options: RelayClientOptions) {}
+
+  get status(): RelayStatus {
+    return this.statusValue;
+  }
+
+  get identity(): PublicIdentity {
+    return publicIdentity(this.options.identity);
+  }
+
+  onStatus(listener: (status: RelayStatus, error?: { code: string; message: string }) => void): () => void {
+    this.statusListeners.add(listener);
+    return () => this.statusListeners.delete(listener);
+  }
+
+  onFrame(listener: (from: PublicIdentity, via: "paired" | "account", frame: TunnelFrame) => void): () => void {
+    this.frameListeners.add(listener);
+    return () => this.frameListeners.delete(listener);
+  }
+
+  onUndeliverable(listener: (to: string, reason: string) => void): () => void {
+    this.undeliverableListeners.add(listener);
+    return () => this.undeliverableListeners.delete(listener);
+  }
+
+  on<N extends keyof RelayEvents>(name: N, listener: (data: RelayEvents[N]) => void): () => void {
+    let set = this.eventListeners.get(name);
+    if (!set) this.eventListeners.set(name, (set = new Set()));
+    const entry = listener as (data: unknown) => void;
+    set.add(entry);
+    return () => set.delete(entry);
+  }
+
+  start(): void {
+    if (this.statusValue === "connecting" || this.statusValue === "online") return;
+    this.open();
+  }
+
+  stop(): void {
+    this.setStatus("stopped");
+    clearTimeout(this.timer);
+    this.socket?.close(1000, "stopped");
+    this.socket = undefined;
+    this.failPending("stopped");
+    for (const wake of this.waiters) wake();
+  }
+
+  /** Reconnect now instead of waiting out the backoff (app foregrounded, network back). */
+  reconnectNow(): void {
+    if (this.statusValue === "stopped" || this.statusValue === "online" || this.statusValue === "connecting") return;
+    clearTimeout(this.timer);
+    this.attempt = 0;
+    this.open();
+  }
+
+  /** Waits (up to `timeoutMs`) for the gateway connection. */
+  waitOnline(timeoutMs: number): Promise<boolean> {
+    if (this.statusValue === "online") return Promise.resolve(true);
+    if (this.statusValue === "stopped") return Promise.resolve(false);
+    return new Promise((resolve) => {
+      const done = () => {
+        clearTimeout(timer);
+        this.waiters.delete(done);
+        resolve(this.statusValue === "online");
+      };
+      const timer = setTimeout(done, timeoutMs);
+      this.waiters.add(done);
+    });
+  }
+
+  async request<M extends RelayMethod>(method: M, params: RelayMethods[M]["params"], timeoutMs?: number): Promise<RelayMethods[M]["result"]> {
+    const limit = timeoutMs ?? this.options.requestTimeoutMs ?? 20_000;
+    if (!(await this.waitOnline(limit))) throw new RelayRequestError("offline", "not connected to the gateway");
+    const id = this.nextId++;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new RelayRequestError("timeout", `${method} timed out`));
+      }, limit);
+      this.pending.set(id, { resolve: resolve as (value: unknown) => void, reject, timer });
+      this.sendFrame({ t: "req", id, method, params });
+    });
+  }
+
+  /** Sends a tunnel frame to a peer. Returns false when not connected. */
+  send(to: string, frame: TunnelFrame): boolean {
+    if (this.statusValue !== "online") return false;
+    return this.sendFrame({ t: "to", to, d: JSON.stringify(frame) });
+  }
+
+  // ── internals ─────────────────────────────────────────────────────
+
+  private sendFrame(frame: ClientFrame): boolean {
+    if (!this.socket || this.socket.readyState !== OPEN) return false;
+    this.socket.send(JSON.stringify(frame));
+    return true;
+  }
+
+  private setStatus(status: RelayStatus, error?: { code: string; message: string }): void {
+    if (error) this.lastError = error;
+    if (status === "online") this.lastError = undefined;
+    if (this.statusValue === status && !error) return;
+    this.statusValue = status;
+    for (const listener of this.statusListeners) listener(status, error);
+    if (status === "online" || status === "stopped") for (const wake of this.waiters) wake();
+  }
+
+  private failPending(reason: string): void {
+    for (const [id, entry] of this.pending) {
+      clearTimeout(entry.timer);
+      entry.reject(new RelayRequestError("offline", reason));
+      this.pending.delete(id);
+    }
+  }
+
+  private open(): void {
+    this.setStatus("connecting");
+    let socket: RelaySocket;
+    try {
+      socket = this.options.createSocket(this.options.url);
+    } catch (error) {
+      this.scheduleReconnect({ code: "connect_failed", message: error instanceof Error ? error.message : String(error) });
+      return;
+    }
+    this.socket = socket;
+    let fatal: { code: string; message: string } | undefined;
+    socket.onmessage = (event) => {
+      let frame;
+      try {
+        const parsed = serverFrameSchema.safeParse(JSON.parse(String(event.data)));
+        if (!parsed.success) return;
+        frame = parsed.data;
+      } catch {
+        return;
+      }
+      switch (frame.t) {
+        case "challenge":
+          void this.authenticate(frame.nonce);
+          return;
+        case "ready":
+          this.attempt = 0;
+          this.account = frame.userId ? { userId: frame.userId, email: frame.email } : undefined;
+          this.setStatus("online");
+          return;
+        case "res": {
+          const entry = this.pending.get(frame.id);
+          if (!entry) return;
+          clearTimeout(entry.timer);
+          this.pending.delete(frame.id);
+          if (frame.error) entry.reject(new RelayRequestError(frame.error.code, frame.error.message));
+          else entry.resolve(frame.result);
+          return;
+        }
+        case "event":
+          for (const listener of this.eventListeners.get(frame.name) ?? []) listener(frame.data);
+          return;
+        case "from": {
+          let inner: TunnelFrame;
+          try {
+            const parsed = tunnelFrameSchema.safeParse(JSON.parse(frame.d));
+            if (!parsed.success) return;
+            inner = parsed.data;
+          } catch {
+            return;
+          }
+          for (const listener of this.frameListeners) listener(frame.from, frame.via, inner);
+          return;
+        }
+        case "undeliverable":
+          for (const listener of this.undeliverableListeners) listener(frame.to, frame.reason);
+          return;
+        case "error":
+          fatal = { code: frame.code, message: frame.message };
+          return;
+        case "pong":
+          return;
+      }
+    };
+    socket.onerror = () => {};
+    socket.onclose = (event) => {
+      if (this.socket !== socket) return;
+      this.socket = undefined;
+      this.failPending("connection closed");
+      if (this.statusValue === "stopped") return;
+      // Another connection with our identity took over: don't fight it.
+      if (event.code === 4000) {
+        this.setStatus("offline", { code: "replaced", message: "connected elsewhere with this identity" });
+        return;
+      }
+      this.scheduleReconnect(fatal ?? { code: "disconnected", message: event.reason || "connection lost" });
+    };
+  }
+
+  private async authenticate(nonce: string): Promise<void> {
+    let token: string | undefined;
+    try {
+      token = (await this.options.token?.()) ?? undefined;
+    } catch {
+      token = undefined;
+    }
+    this.sendFrame({
+      t: "auth",
+      role: this.options.role,
+      identity: publicIdentity(this.options.identity),
+      signature: sign(this.options.identity, gatewayChallengeMessage(nonce)),
+      name: this.options.name.slice(0, 120),
+      platform: this.options.platform,
+      token,
+    });
+  }
+
+  private scheduleReconnect(error: { code: string; message: string }): void {
+    this.setStatus("offline", error);
+    const min = this.options.minBackoffMs ?? 500;
+    const max = this.options.maxBackoffMs ?? 30_000;
+    const delay = Math.min(max, min * 2 ** this.attempt) * (0.75 + Math.random() * 0.5);
+    this.attempt += 1;
+    this.timer = setTimeout(() => this.open(), delay);
+  }
+}