@linkshell/wire 0.1.0 → 0.1.2

package/src/model.ts

@@ -100,6 +100,28 @@ export const pendingPermissionSchema = z.object({
 });
 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>;
+
+/** A sub-agent a session started: the tool call it runs under, and how it is doing. */
+export const subagentInfoSchema = z.object({
+  toolCallId: z.string(),
+  /** What it was asked to do. */
+  task: z.string(),
+  /** Its role or type, e.g. "Explore". */
+  agentType: z.string().optional(),
+  running: z.boolean(),
+  failed: z.boolean().optional(),
+  startedAt: z.number(),
+  endedAt: z.number().optional(),
+});
+export type SubagentInfo = z.infer<typeof subagentInfoSchema>;
+
 export const sessionSummarySchema = z.object({
   /** `${agent}:${nativeId}` — stable across daemon restarts and rediscovery. */
   id: z.string().min(1),
@@ -118,6 +140,13 @@ export const sessionSummarySchema = z.object({
   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(),
+  /** Live only, for sessions that started sub-agents: how many, and how many are working now (`sessions.subagents` lists them). */
+  subagents: z.object({ total: z.number().int(), running: z.number().int() }).optional(),
 });
 export type SessionSummary = z.infer<typeof sessionSummarySchema>;
 
@@ -144,6 +173,8 @@ export const machineInfoSchema = z.object({
   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>;

package/src/relay-client.ts

@@ -122,6 +122,18 @@ export class RelayClient {
     this.open();
   }
 
+  /** Connects afresh so the gateway sees the current account (after a login or logout). */
+  reauthenticate(): void {
+    if (this.statusValue === "stopped") return;
+    clearTimeout(this.timer);
+    this.attempt = 0;
+    const socket = this.socket;
+    this.socket = undefined;
+    socket?.close(1000, "signing in again");
+    this.failPending("connection closed");
+    this.open();
+  }
+
   /** Waits (up to `timeoutMs`) for the gateway connection. */
   waitOnline(timeoutMs: number): Promise<boolean> {
     if (this.statusValue === "online") return Promise.resolve(true);

package/src/rpc.ts

@@ -7,6 +7,7 @@ import {
   terminalInfoSchema,
   sessionDriverSchema,
   sessionSummarySchema,
+  subagentInfoSchema,
 } from "./model.js";
 import { contentBlockSchema, sessionEventSchema } from "./updates.js";
 
@@ -60,6 +61,9 @@ export const directoryEntrySchema = z.object({
   path: z.string(),
   /** Looks like a code project (has .git, package.json, …). */
   project: z.boolean().optional(),
+  /** A file (only listed when asked for); everything else is a directory. */
+  file: z.boolean().optional(),
+  size: z.number().int().optional(),
 });
 export type DirectoryEntry = z.infer<typeof directoryEntrySchema>;
 
@@ -99,8 +103,47 @@ export const methods = {
       sessionId: z.string().min(1),
       /** Last seq the client already has; 0 for a fresh subscription. */
       fromSeq: z.number().int().nonnegative(),
+      /**
+       * The client loads pictures when it shows them (`sessions.image`): they
+       * arrive as image blocks with a `linkshell-event:` uri and no data.
+       * Without it, large pictures are replaced by a text note.
+       */
+      lazyImages: z.boolean().optional(),
     }),
-    result: z.object({ session: sessionSummarySchema }),
+    /**
+     * A fresh subscription starts at the session's latest turns, not at its
+     * beginning: `startSeq` is the seq before the first event sent (0 when the
+     * whole log was). `sessions.history` pages back from there.
+     */
+    result: z.object({ session: sessionSummarySchema, startSeq: z.number().int().nonnegative().optional() }),
+  },
+  /** The page of events before `beforeSeq` (whole turns), oldest first; `startSeq` 0 means that was the beginning. */
+  "sessions.history": {
+    params: z.object({
+      sessionId: z.string().min(1),
+      beforeSeq: z.number().int().positive(),
+      lazyImages: z.boolean().optional(),
+    }),
+    result: z.object({ events: z.array(sessionEventSchema), startSeq: z.number().int().nonnegative() }),
+  },
+  /** The sub-agents this session started, newest first, wherever in its history they are. */
+  "sessions.subagents": {
+    params: z.object({ sessionId: z.string().min(1) }),
+    result: z.object({ subagents: z.array(subagentInfoSchema) }),
+  },
+  /**
+   * One sub-agent's conversation: the call that started it and the events
+   * under it (the latest 2000), oldest first. Later ones arrive on the
+   * session's own subscription, with this call as `parentToolCallId`.
+   */
+  "sessions.subagent": {
+    params: z.object({ sessionId: z.string().min(1), toolCallId: z.string().min(1), lazyImages: z.boolean().optional() }),
+    result: z.object({ events: z.array(sessionEventSchema) }),
+  },
+  /** The picture behind a `linkshell-event:` uri. */
+  "sessions.image": {
+    params: z.object({ sessionId: z.string().min(1), uri: z.string().min(1) }),
+    result: z.object({ mimeType: z.string(), data: z.string() }),
   },
   "sessions.unsubscribe": {
     params: z.object({ sessionId: z.string().min(1) }),
@@ -112,8 +155,15 @@ export const methods = {
       /** Client-generated idempotency key; a retried send is not delivered twice. */
       clientMessageId: z.string().min(1),
       content: z.array(contentBlockSchema).min(1),
+      /**
+       * What to do while a turn is running. "queue": hold the message (it
+       * shows in SessionSummary.queue, where it can be reordered, taken back
+       * or sent at once) and send it when the turn ends. Unset: the agent's
+       * own way — taken into the running turn where it can be, queued where not.
+       */
+      whenBusy: z.enum(["queue"]).optional(),
     }),
-    /** queued: the agent can't take input mid-turn; it is sent when the turn ends. */
+    /** queued: held until the running turn ends (see `whenBusy`, `sessions.sendQueued`). */
     result: z.object({ delivery: z.enum(["started", "steered", "queued", "duplicate"]) }),
   },
   "sessions.cancel": {
@@ -136,6 +186,43 @@ export const methods = {
     }),
     result: empty,
   },
+  /**
+   * Sends a queued message (the first, or `clientMessageId`) now instead of
+   * when the running turn ends: taken into that turn where the agent allows
+   * it, otherwise the turn is stopped first, wherever it runs.
+   */
+  "sessions.sendQueued": {
+    params: z.object({ sessionId: z.string().min(1), clientMessageId: z.string().min(1).optional() }),
+    result: empty,
+  },
+  /** Puts the queued messages in this order (ids not named keep theirs, after the named ones). */
+  "sessions.reorderQueue": {
+    params: z.object({ sessionId: z.string().min(1), clientMessageIds: z.array(z.string().min(1)) }),
+    result: empty,
+  },
+  /** Drops a message still waiting in the host's queue (see SessionSummary.queue). */
+  "sessions.unqueue": {
+    params: z.object({ sessionId: z.string().min(1), clientMessageId: z.string().min(1) }),
+    result: z.object({ removed: z.boolean() }),
+  },
+  /** Archives (or restores) a session: hidden from lists, kept on disk; natively where the agent supports it. */
+  "sessions.archive": {
+    params: z.object({ sessionId: z.string().min(1), archived: z.boolean() }),
+    result: z.object({ session: sessionSummarySchema }),
+  },
+  /** Names a session; an empty title goes back to the agent's own. */
+  "sessions.rename": {
+    params: z.object({ sessionId: z.string().min(1), title: z.string().max(200) }),
+    result: z.object({ session: sessionSummarySchema }),
+  },
+  /**
+   * Deletes a session: the agent's own record where it has one (Codex thread,
+   * Claude transcript), and LinkShell's copy either way. Not while it runs.
+   */
+  "sessions.delete": {
+    params: z.object({ sessionId: z.string().min(1) }),
+    result: empty,
+  },
   "sessions.takeover": {
     params: z.object({ sessionId: z.string().min(1) }),
     result: z.object({ driver: sessionDriverSchema.optional() }),
@@ -183,6 +270,12 @@ export const methods = {
   },
   // ── Gateway: reach this computer from anywhere ──
   "gateway.status": { params: empty, result: gatewayStatusSchema },
+  /**
+   * Applies the computer's current gateway choice and account (local only):
+   * after `linkshell login` / `logout` or `linkshell host --gateway`, a running
+   * host connects, moves or disconnects without a restart.
+   */
+  "gateway.refresh": { 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.
@@ -195,17 +288,34 @@ export const methods = {
   // ── 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) }),
+    params: z.object({
+      path: z.string().optional(),
+      hidden: z.boolean().default(false),
+      /** Also list the directory's files (after its subdirectories), to browse a project. */
+      files: z.boolean().default(false),
+    }),
     result: z.object({
       path: z.string(),
       parent: z.string().optional(),
       home: z.string(),
       entries: z.array(directoryEntrySchema),
+      /** The directory holds more than a listing carries (1000 entries). */
+      truncated: z.boolean().optional(),
     }),
   },
-  /** A file's contents, for viewing: text as-is, images as base64, anything else refused. */
+  /**
+   * A file's contents, for viewing. Text comes a part at a time: up to
+   * `maxBytes` from `offset`, with `nextOffset` when more follows. A picture
+   * comes whole, as base64. A binary file is only described, and a file too
+   * big to look at on a phone (text over 20 MB, a picture over 10 MB) is
+   * refused with `too_large`.
+   */
   "fs.read": {
-    params: z.object({ path: z.string().min(1), maxBytes: z.number().int().min(1).max(8_000_000).default(2_000_000) }),
+    params: z.object({
+      path: z.string().min(1),
+      offset: z.number().int().nonnegative().default(0),
+      maxBytes: z.number().int().min(1).max(2_000_000).default(512_000),
+    }),
     result: z.object({
       path: z.string(),
       size: z.number().int(),
@@ -214,7 +324,10 @@ export const methods = {
       text: z.string().optional(),
       data: z.string().optional(),
       mimeType: z.string().optional(),
+      /** Text: more of the file follows this part. */
       truncated: z.boolean(),
+      /** Where the next part starts (pass it as `offset`). */
+      nextOffset: z.number().int().optional(),
     }),
   },
   /**
@@ -343,7 +456,15 @@ export function isMethodName(name: string): name is MethodName {
 
 export const notifications = {
   "session.event": sessionEventSchema,
+  /**
+   * Sent before a subscription's backlog when it doesn't continue from the
+   * client's `fromSeq`: the events that follow start after `startSeq`, so a
+   * client holding older events of this session drops them first.
+   */
+  "session.window": z.object({ sessionId: z.string(), startSeq: z.number().int().nonnegative() }),
   "session.summary": z.object({ session: sessionSummarySchema }),
+  /** A session was deleted (from any device, or natively by the agent). */
+  "session.removed": z.object({ sessionId: z.string() }),
   /** 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. */