@linkshell/wire 0.0.0-stage → 0.1.0

package/src/relay.ts

@@ -0,0 +1,206 @@
+import { z } from "zod";
+import {
+  channelKeys,
+  ephemeralKey,
+  SecureChannel,
+  sign,
+  verifySignature,
+  type Identity,
+  type PublicIdentity,
+} from "./crypto.js";
+
+// Gateway v2 frames. The gateway authenticates peers by their keys, routes
+// opaque frames between a device and a machine it is allowed to reach, and
+// brokers pairing. Everything inside a routed frame is end-to-end encrypted:
+// the gateway never sees RPC, session content or terminal output.
+
+export const RELAY_PATH = "/v2/connect";
+
+export const publicIdentitySchema = z.object({ id: z.string(), signKey: z.string(), boxKey: z.string() });
+
+export const peerRoleSchema = z.enum(["machine", "device"]);
+export type PeerRole = z.infer<typeof peerRoleSchema>;
+
+/** A machine as a device sees it in the gateway's list. */
+export const machineEntrySchema = publicIdentitySchema.extend({
+  name: z.string(),
+  platform: z.string().optional(),
+  online: z.boolean(),
+  /** How this device may reach it: it paired, or both belong to the same account. */
+  via: z.enum(["paired", "account"]),
+});
+export type MachineEntry = z.infer<typeof machineEntrySchema>;
+
+export const deviceEntrySchema = publicIdentitySchema.extend({
+  name: z.string(),
+  online: z.boolean(),
+  pairedAt: z.number().optional(),
+});
+export type DeviceEntry = z.infer<typeof deviceEntrySchema>;
+
+// ── peer → gateway ───────────────────────────────────────────────────
+
+export const clientFrameSchema = z.discriminatedUnion("t", [
+  /** Answer to the challenge: a signature over it proves the key. */
+  z.object({
+    t: z.literal("auth"),
+    role: peerRoleSchema,
+    identity: publicIdentitySchema,
+    signature: z.string(),
+    name: z.string().max(120),
+    platform: z.string().max(40).optional(),
+    /** Account access token, when signed in. */
+    token: z.string().optional(),
+  }),
+  z.object({ t: z.literal("req"), id: z.number().int(), method: z.string(), params: z.unknown().optional() }),
+  /** An encrypted frame for a peer. */
+  z.object({ t: z.literal("to"), to: z.string(), d: z.string().max(40 * 1024 * 1024) }),
+  z.object({ t: z.literal("ping") }),
+]);
+export type ClientFrame = z.infer<typeof clientFrameSchema>;
+
+// ── gateway → peer ───────────────────────────────────────────────────
+
+export const serverFrameSchema = z.discriminatedUnion("t", [
+  z.object({ t: z.literal("challenge"), nonce: z.string() }),
+  z.object({ t: z.literal("ready"), userId: z.string().optional(), email: z.string().optional() }),
+  z.object({
+    t: z.literal("res"),
+    id: z.number().int(),
+    result: z.unknown().optional(),
+    error: z.object({ code: z.string(), message: z.string() }).optional(),
+  }),
+  z.object({ t: z.literal("event"), name: z.string(), data: z.unknown() }),
+  /** An encrypted frame from a peer, with the keys the gateway verified it holds. */
+  z.object({ t: z.literal("from"), from: publicIdentitySchema, via: z.enum(["paired", "account"]), d: z.string() }),
+  /** A frame couldn't be delivered: the peer is offline or not reachable. */
+  z.object({ t: z.literal("undeliverable"), to: z.string(), reason: z.string() }),
+  z.object({ t: z.literal("pong") }),
+  z.object({ t: z.literal("error"), code: z.string(), message: z.string() }),
+]);
+export type ServerFrame = z.infer<typeof serverFrameSchema>;
+
+/** Control methods and their results. */
+export interface RelayMethods {
+  /** Machine: open a pairing window. The QR carries `secret`; the code is for typing. */
+  "pair.offer": { params: { secretHash?: string }; result: { code: string; expiresAt: number } };
+  /** Machine: accept or refuse a claim it received as a `pair.request` event. */
+  "pair.decide": { params: { requestId: string; accept: boolean }; result: Record<string, never> };
+  /** Device: claim a pairing by code (typed) or by machine id (scanned). */
+  "pair.claim": {
+    params: { code?: string; machineId?: string; proof: string };
+    result: { machine: MachineEntry };
+  };
+  "machines.list": { params: Record<string, never>; result: { machines: MachineEntry[] } };
+  "machines.forget": { params: { machineId: string }; result: Record<string, never> };
+  "devices.list": { params: Record<string, never>; result: { devices: DeviceEntry[] } };
+  "devices.revoke": { params: { deviceId: string }; result: Record<string, never> };
+}
+export type RelayMethod = keyof RelayMethods;
+
+/** Events the gateway pushes. */
+export interface RelayEvents {
+  /** To a machine: a device wants to pair. */
+  "pair.request": { requestId: string; device: PublicIdentity & { name: string }; proof: string; code: string };
+  /** To a machine: pairing finished (accepted or not). */
+  "pair.done": { requestId: string; accepted: boolean; device?: DeviceEntry };
+  /** A reachable peer came online or went offline. */
+  presence: { id: string; online: boolean };
+  /** To a device: the list of reachable machines changed (paired, revoked, account). */
+  "machines.changed": Record<string, never>;
+}
+
+/**
+ * What `linkshell pair` puts in the QR code, kept short so the code stays
+ * scannable: the gateway, the machine's signing key (its id derives from it,
+ * and every channel is checked against it), a one-time secret and the code.
+ * The machine's name and box key come from the gateway; a wrong box key can't
+ * break a channel's secrecy because the ephemeral keys are signed.
+ */
+export interface PairingLink {
+  gateway: string;
+  signKey: string;
+  secret: string;
+  code: string;
+}
+
+export const PAIRING_LINK_PREFIX = "linkshell://pair?";
+
+export function encodePairingLink(link: PairingLink): string {
+  const params = new URLSearchParams({ g: link.gateway, k: link.signKey, s: link.secret, c: link.code });
+  return PAIRING_LINK_PREFIX + params.toString();
+}
+
+export function decodePairingLink(text: string): PairingLink | undefined {
+  const trimmed = text.trim();
+  if (!trimmed.startsWith(PAIRING_LINK_PREFIX)) return undefined;
+  const params = new URLSearchParams(trimmed.slice(PAIRING_LINK_PREFIX.length));
+  const gateway = params.get("g");
+  const signKey = params.get("k");
+  const secret = params.get("s");
+  const code = params.get("c");
+  if (!gateway || !signKey || !secret || !code || !/^(wss?|https?):\/\//.test(gateway)) return undefined;
+  return { gateway, signKey, secret, code };
+}
+
+// ── end-to-end channel over the relay ────────────────────────────────
+
+/**
+ * Frames inside `to` / `from`. A device opens channel `ch` with `hello`, the
+ * machine answers `welcome`; both sign their ephemeral key with their
+ * long-term key, so neither can be impersonated by the gateway. After that
+ * every frame is `data`, sealed with the channel keys.
+ */
+export const tunnelFrameSchema = z.discriminatedUnion("k", [
+  z.object({ k: z.literal("hello"), ch: z.string(), eph: z.string(), sig: z.string() }),
+  z.object({ k: z.literal("welcome"), ch: z.string(), eph: z.string(), sig: z.string() }),
+  z.object({ k: z.literal("data"), ch: z.string(), box: z.string() }),
+  z.object({ k: z.literal("close"), ch: z.string(), reason: z.string().optional() }),
+  z.object({ k: z.literal("refuse"), ch: z.string(), code: z.string(), message: z.string() }),
+]);
+export type TunnelFrame = z.infer<typeof tunnelFrameSchema>;
+
+function helloMessage(kind: "hello" | "welcome", channel: string, from: string, to: string, eph: string): string {
+  return `linkshell-tunnel-v2:${kind}:${channel}:${from}:${to}:${eph}`;
+}
+
+/** Device side: start a channel to `machine`. */
+export function openTunnel(device: Identity, machine: PublicIdentity, channel: string) {
+  const eph = ephemeralKey();
+  const hello: TunnelFrame = {
+    k: "hello",
+    ch: channel,
+    eph: eph.public,
+    sig: sign(device, helloMessage("hello", channel, device.id, machine.id, eph.public)),
+  };
+  return {
+    hello,
+    /** Checks the machine's answer and returns the channel, or throws. */
+    accept(welcome: Extract<TunnelFrame, { k: "welcome" }>): SecureChannel {
+      if (!verifySignature(machine.signKey, helloMessage("welcome", channel, machine.id, device.id, welcome.eph), welcome.sig)) {
+        throw new Error("the computer's key doesn't match: refusing to connect");
+      }
+      return new SecureChannel(
+        channelKeys({ initiator: true, local: device, localEphemeral: eph.secret, remoteBoxKey: machine.boxKey, remoteEphemeral: welcome.eph }),
+      );
+    },
+  };
+}
+
+/** Machine side: answer a device's hello. Throws when the signature is wrong. */
+export function answerTunnel(machine: Identity, device: PublicIdentity, hello: Extract<TunnelFrame, { k: "hello" }>) {
+  if (!verifySignature(device.signKey, helloMessage("hello", hello.ch, device.id, machine.id, hello.eph), hello.sig)) {
+    throw new Error("bad hello signature");
+  }
+  const eph = ephemeralKey();
+  const welcome: TunnelFrame = {
+    k: "welcome",
+    ch: hello.ch,
+    eph: eph.public,
+    sig: sign(machine, helloMessage("welcome", hello.ch, machine.id, device.id, eph.public)),
+  };
+  const channel = new SecureChannel(
+    channelKeys({ initiator: false, local: machine, localEphemeral: eph.secret, remoteBoxKey: device.boxKey, remoteEphemeral: hello.eph }),
+  );
+  return { welcome, channel };
+}

package/src/rpc.ts

@@ -0,0 +1,364 @@
+import { z } from "zod";
+import {
+  gatewayStatusSchema,
+  machineInfoSchema,
+  portInfoSchema,
+  projectSummarySchema,
+  terminalInfoSchema,
+  sessionDriverSchema,
+  sessionSummarySchema,
+} from "./model.js";
+import { contentBlockSchema, sessionEventSchema } from "./updates.js";
+
+// ── JSON-RPC 2.0 framing ─────────────────────────────────────────────
+
+export const rpcIdSchema = z.union([z.string(), z.number()]);
+export type RpcId = z.infer<typeof rpcIdSchema>;
+
+export const rpcErrorSchema = z.object({
+  code: z.number().int(),
+  message: z.string(),
+  data: z.unknown().optional(),
+});
+export type RpcErrorObject = z.infer<typeof rpcErrorSchema>;
+
+export const rpcMessageSchema = z.object({
+  jsonrpc: z.literal("2.0"),
+  id: rpcIdSchema.optional(),
+  method: z.string().optional(),
+  params: z.unknown().optional(),
+  result: z.unknown().optional(),
+  error: rpcErrorSchema.optional(),
+});
+export type RpcMessage = z.infer<typeof rpcMessageSchema>;
+
+/** Application error codes carried in `error.data.code`. */
+export const appErrorCodeSchema = z.enum([
+  "invalid_params",
+  "not_found",
+  "agent_unavailable",
+  "not_supported",
+  /** The session exists but can't be joined yet (e.g. a new Codex thread before its first turn). */
+  "not_ready",
+  "busy",
+  /** Client side: the link to the computer is down. */
+  "offline",
+  "internal",
+]);
+export type AppErrorCode = z.infer<typeof appErrorCodeSchema>;
+
+export const RPC_INVALID_PARAMS = -32602;
+export const RPC_METHOD_NOT_FOUND = -32601;
+export const RPC_APP_ERROR = -32000;
+
+// ── Methods (client → host) ──────────────────────────────────────────
+
+const empty = z.object({}).passthrough();
+
+export const directoryEntrySchema = z.object({
+  name: z.string(),
+  path: z.string(),
+  /** Looks like a code project (has .git, package.json, …). */
+  project: z.boolean().optional(),
+});
+export type DirectoryEntry = z.infer<typeof directoryEntrySchema>;
+
+export const methods = {
+  "machine.info": {
+    params: empty,
+    result: machineInfoSchema,
+  },
+  "projects.list": {
+    params: z.object({ limit: z.number().int().positive().max(200).optional() }),
+    result: z.object({ projects: z.array(projectSummarySchema) }),
+  },
+  "sessions.list": {
+    params: z.object({
+      limit: z.number().int().positive().max(200).optional(),
+      /** Only sessions updated strictly before this timestamp (pagination). */
+      before: z.number().optional(),
+      includeArchived: z.boolean().optional(),
+    }),
+    result: z.object({
+      sessions: z.array(sessionSummarySchema),
+      nextBefore: z.number().optional(),
+    }),
+  },
+  "sessions.create": {
+    params: z.object({
+      agent: z.string().min(1),
+      cwd: z.string().min(1),
+      prompt: z.array(contentBlockSchema).optional(),
+      clientMessageId: z.string().optional(),
+      model: z.string().optional(),
+    }),
+    result: z.object({ session: sessionSummarySchema }),
+  },
+  "sessions.subscribe": {
+    params: z.object({
+      sessionId: z.string().min(1),
+      /** Last seq the client already has; 0 for a fresh subscription. */
+      fromSeq: z.number().int().nonnegative(),
+    }),
+    result: z.object({ session: sessionSummarySchema }),
+  },
+  "sessions.unsubscribe": {
+    params: z.object({ sessionId: z.string().min(1) }),
+    result: empty,
+  },
+  "sessions.prompt": {
+    params: z.object({
+      sessionId: z.string().min(1),
+      /** Client-generated idempotency key; a retried send is not delivered twice. */
+      clientMessageId: z.string().min(1),
+      content: z.array(contentBlockSchema).min(1),
+    }),
+    /** queued: the agent can't take input mid-turn; it is sent when the turn ends. */
+    result: z.object({ delivery: z.enum(["started", "steered", "queued", "duplicate"]) }),
+  },
+  "sessions.cancel": {
+    params: z.object({ sessionId: z.string().min(1) }),
+    result: empty,
+  },
+  "sessions.permission": {
+    params: z.object({
+      sessionId: z.string().min(1),
+      requestId: z.string().min(1),
+      optionId: z.string().min(1),
+    }),
+    result: empty,
+  },
+  "sessions.setConfig": {
+    params: z.object({
+      sessionId: z.string().min(1),
+      optionId: z.string().min(1),
+      value: z.string().min(1),
+    }),
+    result: empty,
+  },
+  "sessions.takeover": {
+    params: z.object({ sessionId: z.string().min(1) }),
+    result: z.object({ driver: sessionDriverSchema.optional() }),
+  },
+  "sessions.release": {
+    params: z.object({ sessionId: z.string().min(1) }),
+    result: z.object({ driver: sessionDriverSchema.optional() }),
+  },
+  /**
+   * How a desktop terminal should launch the agent's native UI attached to the
+   * host (used by `linkshell <agent>`). The shim execs exactly what it gets.
+   * For handoff agents the calling connection becomes the session's desktop
+   * controller: it receives `desktop.yield` when a device takes over.
+   */
+  "desktop.launch": {
+    params: z.object({
+      agent: z.string().min(1),
+      sessionId: z.string().optional(),
+      args: z.array(z.string()).default([]),
+      /** The terminal's working directory and environment. */
+      cwd: z.string().optional(),
+      env: z.record(z.string()).optional(),
+    }),
+    result: z.object({
+      command: z.string(),
+      args: z.array(z.string()),
+      env: z.record(z.string()).optional(),
+      /** Set for handoff agents: the session this terminal now drives. */
+      sessionId: z.string().optional(),
+    }),
+  },
+  /** The shim's native UI exited after a `desktop.yield`; the device may drive now. */
+  "desktop.yielded": {
+    params: z.object({ sessionId: z.string().min(1) }),
+    result: empty,
+  },
+  /** The user is back at the keyboard: stop remote driving, relaunch the native UI. */
+  "desktop.reclaim": {
+    params: z.object({ sessionId: z.string().min(1) }),
+    result: z.object({
+      command: z.string(),
+      args: z.array(z.string()),
+      env: z.record(z.string()).optional(),
+    }),
+  },
+  // ── Gateway: reach this computer from anywhere ──
+  "gateway.status": { params: empty, result: gatewayStatusSchema },
+  /**
+   * Opens a pairing window (local only). `link` is what the QR encodes; the
+   * code can be typed instead. `pairing.done` follows when a device pairs.
+   */
+  "pairing.start": {
+    params: empty,
+    result: z.object({ link: z.string(), code: z.string(), expiresAt: z.number(), gateway: z.string() }),
+  },
+  "devices.revoke": { params: z.object({ deviceId: z.string().min(1) }), result: empty },
+  // ── Directories: pick where a new session runs ──
+  /** Subdirectories of `path` (default: the home directory). */
+  "fs.list": {
+    params: z.object({ path: z.string().optional(), hidden: z.boolean().default(false) }),
+    result: z.object({
+      path: z.string(),
+      parent: z.string().optional(),
+      home: z.string(),
+      entries: z.array(directoryEntrySchema),
+    }),
+  },
+  /** A file's contents, for viewing: text as-is, images as base64, anything else refused. */
+  "fs.read": {
+    params: z.object({ path: z.string().min(1), maxBytes: z.number().int().min(1).max(8_000_000).default(2_000_000) }),
+    result: z.object({
+      path: z.string(),
+      size: z.number().int(),
+      modifiedAt: z.number(),
+      kind: z.enum(["text", "image", "binary"]),
+      text: z.string().optional(),
+      data: z.string().optional(),
+      mimeType: z.string().optional(),
+      truncated: z.boolean(),
+    }),
+  },
+  /**
+   * Saves a file from the device into `dir`. A name that's taken gets a
+   * numbered suffix ("photo 2.jpg") rather than overwriting.
+   */
+  "fs.upload": {
+    params: z.object({
+      dir: z.string().min(1),
+      name: z.string().min(1).max(255),
+      /** base64; up to ~30 MB of file. */
+      data: z.string().max(40_000_000),
+    }),
+    result: z.object({ path: z.string(), size: z.number().int() }),
+  },
+  /** Creates a directory `name` inside `parent`. */
+  "fs.mkdir": {
+    params: z.object({ parent: z.string().min(1), name: z.string().min(1).max(255) }),
+    result: z.object({ path: z.string() }),
+  },
+  /** Directories under the home directory whose name contains `query`, projects first. */
+  "fs.search": {
+    params: z.object({ query: z.string().min(1).max(200), limit: z.number().int().min(1).max(200).default(60) }),
+    result: z.object({ entries: z.array(directoryEntrySchema), truncated: z.boolean() }),
+  },
+  // ── Terminals: plain shells on the host, any command, like SSH ──
+  "terminals.list": {
+    params: empty,
+    result: z.object({ terminals: z.array(terminalInfoSchema) }),
+  },
+  "terminals.create": {
+    params: z.object({
+      cwd: z.string().optional(),
+      /** Run this in the shell right away (the shell stays open after it). */
+      command: z.string().max(4000).optional(),
+      cols: z.number().int().min(10).max(1000).default(80),
+      rows: z.number().int().min(4).max(500).default(24),
+    }),
+    result: z.object({ terminal: terminalInfoSchema }),
+  },
+  /**
+   * Start receiving `terminal.output` for a terminal. With `fromSeq` the host
+   * sends only newer output when it still has it; otherwise `replay` holds the
+   * recent screen history to redraw from scratch.
+   */
+  "terminals.attach": {
+    params: z.object({ terminalId: z.string().min(1), fromSeq: z.number().int().min(0).optional() }),
+    result: z.object({
+      terminal: terminalInfoSchema,
+      /** Output to write before any `terminal.output` that follows. */
+      replay: z.string(),
+      /** Clear the screen before writing `replay` (the host no longer has what came after `fromSeq`). */
+      reset: z.boolean(),
+      /** The last output seq `replay` covers; later chunks arrive as `terminal.output`. */
+      seq: z.number().int(),
+    }),
+  },
+  "terminals.detach": {
+    params: z.object({ terminalId: z.string().min(1) }),
+    result: empty,
+  },
+  "terminals.input": {
+    params: z.object({ terminalId: z.string().min(1), data: z.string().max(1_000_000) }),
+    result: empty,
+  },
+  "terminals.resize": {
+    params: z.object({
+      terminalId: z.string().min(1),
+      cols: z.number().int().min(10).max(1000),
+      rows: z.number().int().min(4).max(500),
+    }),
+    result: empty,
+  },
+  "terminals.close": {
+    params: z.object({ terminalId: z.string().min(1) }),
+    result: empty,
+  },
+  // ── Previews: the host's local servers, reached through this channel ──
+  /** Servers listening on the host that look like something to preview. */
+  "ports.list": {
+    params: empty,
+    result: z.object({ ports: z.array(portInfoSchema) }),
+  },
+  /**
+   * A TCP stream to `port` on the host's loopback, like `ssh -L`: the device
+   * runs a local listener and carries each connection over this channel, so a
+   * page, its WebSocket (hot reload) and its cookies all work unchanged. The
+   * host's bytes arrive as `proxy.data`; the stream ends with `proxy.closed`.
+   */
+  "proxy.open": {
+    params: z.object({ port: z.number().int().min(1).max(65535) }),
+    result: z.object({ streamId: z.string() }),
+  },
+  /**
+   * Starts the host's screen viewer: a page plus H.264 stream on a loopback
+   * port, opened like a preview (`proxy.open`) at `/?token=…&display=…`.
+   */
+  "screen.start": {
+    params: empty,
+    result: z.object({
+      port: z.number().int(),
+      token: z.string(),
+      displays: z.array(z.object({ index: z.number().int(), name: z.string() })),
+    }),
+  },
+  /** Bytes to the host's end of a stream (base64). */
+  "proxy.write": {
+    params: z.object({ streamId: z.string().min(1), data: z.string().max(2_000_000) }),
+    result: empty,
+  },
+  "proxy.close": {
+    params: z.object({ streamId: z.string().min(1) }),
+    result: empty,
+  },
+} as const;
+
+export type MethodName = keyof typeof methods;
+export type MethodParams<M extends MethodName> = z.input<(typeof methods)[M]["params"]>;
+export type MethodResult<M extends MethodName> = z.infer<(typeof methods)[M]["result"]>;
+
+export function isMethodName(name: string): name is MethodName {
+  return Object.prototype.hasOwnProperty.call(methods, name);
+}
+
+// ── Notifications (host → client) ────────────────────────────────────
+
+export const notifications = {
+  "session.event": sessionEventSchema,
+  "session.summary": z.object({ session: sessionSummarySchema }),
+  /** To a desktop shim: a device is taking over; exit the native UI, then call desktop.yielded. */
+  "desktop.yield": z.object({ sessionId: z.string() }),
+  /** To a desktop shim: progress from the remote driver, to show in the terminal. */
+  "desktop.remoteActivity": z.object({ sessionId: z.string(), line: z.string() }),
+  "pairing.done": z.object({ device: z.object({ id: z.string(), name: z.string() }) }),
+  "gateway.changed": gatewayStatusSchema,
+  /** Output from an attached terminal, in order; `seq` increases by one per chunk. */
+  "terminal.output": z.object({ terminalId: z.string(), seq: z.number().int(), data: z.string() }),
+  /** A terminal's list entry changed (title, size, exit), or it was closed (`closed`). */
+  "terminal.changed": z.object({ terminal: terminalInfoSchema, closed: z.boolean().optional() }),
+  /** Bytes from the host's end of a `proxy.open` stream (base64), in order. */
+  "proxy.data": z.object({ streamId: z.string(), data: z.string() }),
+  /** The host's end of a stream closed (the server hung up, or refused). */
+  "proxy.closed": z.object({ streamId: z.string(), error: z.string().optional() }),
+} as const;
+
+export type NotificationName = keyof typeof notifications;
+export type NotificationParams<N extends NotificationName> = z.infer<(typeof notifications)[N]>;

package/src/shell.ts

@@ -0,0 +1,53 @@
+// Agents run commands through a login shell (`/bin/zsh -lc '<script>'`) and
+// report that whole line. Both the host and clients show the script alone.
+
+/**
+ * Reads one POSIX shell word starting at `from`: any mix of '…', "…" and bare
+ * characters, as the shell would join them. Returns the word and where it
+ * ended, or undefined for an unterminated quote.
+ */
+function readWord(text: string, from: number): { word: string; end: number } | undefined {
+  let word = "";
+  let i = from;
+  while (i < text.length && !/\s/.test(text[i]!)) {
+    const ch = text[i]!;
+    if (ch === "'") {
+      const close = text.indexOf("'", i + 1);
+      if (close < 0) return undefined;
+      word += text.slice(i + 1, close);
+      i = close + 1;
+    } else if (ch === '"') {
+      i += 1;
+      for (;;) {
+        if (i >= text.length) return undefined;
+        const c = text[i]!;
+        if (c === '"') break;
+        if (c === "\\" && i + 1 < text.length && '"\\$`\n'.includes(text[i + 1]!)) {
+          if (text[i + 1] !== "\n") word += text[i + 1];
+          i += 2;
+        } else {
+          word += c;
+          i += 1;
+        }
+      }
+      i += 1;
+    } else if (ch === "\\" && i + 1 < text.length) {
+      word += text[i + 1];
+      i += 2;
+    } else {
+      word += ch;
+      i += 1;
+    }
+  }
+  return { word, end: i };
+}
+
+/** `/bin/zsh -lc 'npm test'` → `npm test`. Anything else comes back unchanged. */
+export function unwrapShellCommand(command: string): string {
+  const text = command.trim();
+  const prefix = /^(?:\/\S*\/)?(?:ba|z|da|k)?sh\s+-l?c\s+/.exec(text);
+  if (!prefix) return command;
+  const read = readWord(text, prefix[0].length);
+  if (!read || text.slice(read.end).trim()) return command;
+  return read.word.trim() || command;
+}