@linkshell/wire 0.1.1 → 0.1.3

package/src/model.ts

@@ -19,6 +19,12 @@ export const agentCapabilitiesSchema = z.object({
   steer: z.boolean(),
   permissions: z.boolean(),
   images: z.boolean(),
+  /**
+   * The agent forks sessions itself, keeping everything it knew. Every agent's
+   * sessions can be forked: without this (or from a single reply, where the
+   * agent only forks whole sessions) LinkShell makes the fork — the new session
+   * shows the conversation and its agent is told it as text.
+   */
   fork: z.boolean(),
   models: z.boolean(),
   modes: z.boolean(),
@@ -108,6 +114,20 @@ export const queuedMessageSchema = z.object({
 });
 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),
@@ -131,6 +151,15 @@ export const sessionSummarySchema = z.object({
    * holds them (agents that can't take input mid-turn). Oldest first.
    */
   queue: z.array(queuedMessageSchema).optional(),
+  /**
+   * The session works in a git worktree LinkShell made for it: its own
+   * checkout and branch, so it can't disturb the project's working directory.
+   * `cwd` is inside the worktree; `source` is the directory it was made from
+   * (the project the session belongs to).
+   */
+  worktree: z.object({ branch: z.string(), source: z.string() }).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,11 +173,43 @@ export function parseSessionId(id: string): { agent: string; nativeId: string }
   return { agent: id.slice(0, index), nativeId: id.slice(index + 1) };
 }
 
+/** What git says about a directory, to offer starting a session in a worktree of it. */
+export const gitInfoSchema = z.object({
+  /** The repository's top directory. */
+  root: z.string(),
+  /** The branch checked out; absent on a detached HEAD. */
+  branch: z.string().optional(),
+  /** The commit checked out, abbreviated; absent before the first commit. */
+  head: z.string().optional(),
+  /** Uncommitted changes in the working directory (a new worktree starts from the last commit, without them). */
+  dirty: z.boolean(),
+});
+export type GitInfo = z.infer<typeof gitInfoSchema>;
+
+/** A worktree LinkShell made for sessions. */
+export const worktreeEntrySchema = z.object({
+  /** The worktree's top directory. */
+  path: z.string(),
+  branch: z.string(),
+  /** The repository it belongs to. */
+  source: z.string(),
+  createdAt: z.number(),
+  /** Sessions working in it. */
+  sessions: z.array(z.string()),
+  /** Uncommitted changes in it. */
+  dirty: z.boolean(),
+  /** Commits made in it since it was created. */
+  ahead: z.number().int().nonnegative(),
+});
+export type WorktreeEntry = z.infer<typeof worktreeEntrySchema>;
+
 export const projectSummarySchema = z.object({
   cwd: z.string(),
   name: z.string(),
   lastActiveAt: z.number(),
   sessionCount: z.number().int().nonnegative(),
+  /** For a git repository: the branch checked out there now (or the abbreviated commit, on a detached HEAD). */
+  branch: z.string().optional(),
 });
 export type ProjectSummary = z.infer<typeof projectSummarySchema>;
 

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,9 @@ import {
   terminalInfoSchema,
   sessionDriverSchema,
   sessionSummarySchema,
+  subagentInfoSchema,
+  gitInfoSchema,
+  worktreeEntrySchema,
 } from "./model.js";
 import { contentBlockSchema, sessionEventSchema } from "./updates.js";
 
@@ -60,6 +63,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>;
 
@@ -91,16 +97,71 @@ export const methods = {
       prompt: z.array(contentBlockSchema).optional(),
       clientMessageId: z.string().optional(),
       model: z.string().optional(),
+      /**
+       * Start in a new git worktree of `cwd`'s repository (its own branch, from
+       * the last commit) instead of in `cwd` itself. Refused with `not_a_repo`
+       * outside a git repository.
+       */
+      worktree: z.boolean().optional(),
     }),
     result: z.object({ session: sessionSummarySchema }),
   },
+  /**
+   * A new session that starts with this one's conversation: all of it, or up
+   * to and including the turn of `itemId` (a message in it). The original is
+   * untouched. With `worktree` the new session works in a new git worktree of
+   * the project instead of the same directory.
+   */
+  "sessions.fork": {
+    params: z.object({ sessionId: z.string().min(1), itemId: z.string().min(1).optional(), worktree: z.boolean().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(),
+      /**
+       * 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 +173,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 +204,20 @@ 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) }),
@@ -155,8 +237,13 @@ export const methods = {
    * 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.
    */
+  /**
+   * Deletes a session. Its worktree (when it has one that no other session
+   * uses) goes with it if nothing in it would be lost; `worktree: "remove"`
+   * removes it even with uncommitted changes or new commits, "keep" never.
+   */
   "sessions.delete": {
-    params: z.object({ sessionId: z.string().min(1) }),
+    params: z.object({ sessionId: z.string().min(1), worktree: z.enum(["keep", "remove"]).optional() }),
     result: empty,
   },
   "sessions.takeover": {
@@ -206,6 +293,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.
@@ -215,20 +308,44 @@ export const methods = {
     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 },
+  // ── Git: sessions in worktrees ──
+  /** What git says about `path`; no `git` when it isn't in a repository. */
+  "git.info": { params: z.object({ path: z.string().min(1) }), result: z.object({ git: gitInfoSchema.optional() }) },
+  /** The worktrees LinkShell made, newest first. */
+  "worktrees.list": { params: empty, result: z.object({ worktrees: z.array(worktreeEntrySchema) }) },
+  /** Removes a worktree and its branch. Refused (`busy`) while a session uses it, or (`dirty`) when work in it would be lost, unless `force`. */
+  "worktrees.remove": { params: z.object({ path: z.string().min(1), force: z.boolean().optional() }), 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) }),
+    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(),
@@ -237,7 +354,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(),
     }),
   },
   /**
@@ -366,6 +486,12 @@ 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() }),