@linkshell/wire 0.2.21 → 0.2.23

package/dist/workflow.d.ts

@@ -1,14 +1,35 @@
 import { z } from "zod";
-export declare const workflowStateSchema: z.ZodEnum<["running", "paused", "completed", "failed", "stopped"]>;
+export declare const workflowStateSchema: z.ZodEnum<{
+    paused: "paused";
+    running: "running";
+    completed: "completed";
+    failed: "failed";
+    stopped: "stopped";
+}>;
 export type WorkflowState = z.infer<typeof workflowStateSchema>;
-export declare const workflowAgentStateSchema: z.ZodEnum<["pending", "running", "paused", "completed", "failed", "stopped", "unknown"]>;
+export declare const workflowAgentStateSchema: z.ZodEnum<{
+    unknown: "unknown";
+    paused: "paused";
+    running: "running";
+    completed: "completed";
+    failed: "failed";
+    stopped: "stopped";
+    pending: "pending";
+}>;
 export type WorkflowAgentState = z.infer<typeof workflowAgentStateSchema>;
 export declare const workflowAgentSchema: z.ZodObject<{
     id: z.ZodString;
-    /** Present only after the host has imported this agent's transcript. */
     toolCallId: z.ZodOptional<z.ZodString>;
     title: z.ZodString;
-    state: z.ZodEnum<["pending", "running", "paused", "completed", "failed", "stopped", "unknown"]>;
+    state: z.ZodEnum<{
+        unknown: "unknown";
+        paused: "paused";
+        running: "running";
+        completed: "completed";
+        failed: "failed";
+        stopped: "stopped";
+        pending: "pending";
+    }>;
     phaseId: z.ZodOptional<z.ZodString>;
     model: z.ZodOptional<z.ZodString>;
     tokens: z.ZodOptional<z.ZodNumber>;
@@ -17,54 +38,25 @@ export declare const workflowAgentSchema: z.ZodObject<{
     startedAt: z.ZodOptional<z.ZodNumber>;
     endedAt: z.ZodOptional<z.ZodNumber>;
     result: z.ZodOptional<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
-    id: string;
-    title: string;
-    state: "unknown" | "paused" | "running" | "completed" | "failed" | "stopped" | "pending";
-    toolCallId?: string | undefined;
-    phaseId?: string | undefined;
-    model?: string | undefined;
-    tokens?: number | undefined;
-    toolCalls?: number | undefined;
-    durationMs?: number | undefined;
-    startedAt?: number | undefined;
-    endedAt?: number | undefined;
-    result?: string | undefined;
-}, {
-    id: string;
-    title: string;
-    state: "unknown" | "paused" | "running" | "completed" | "failed" | "stopped" | "pending";
-    toolCallId?: string | undefined;
-    phaseId?: string | undefined;
-    model?: string | undefined;
-    tokens?: number | undefined;
-    toolCalls?: number | undefined;
-    durationMs?: number | undefined;
-    startedAt?: number | undefined;
-    endedAt?: number | undefined;
-    result?: string | undefined;
-}>;
+}, z.core.$strip>;
 export type WorkflowAgent = z.infer<typeof workflowAgentSchema>;
 export declare const workflowPhaseSchema: z.ZodObject<{
     id: z.ZodString;
     title: z.ZodString;
     order: z.ZodNumber;
-}, "strip", z.ZodTypeAny, {
-    id: string;
-    title: string;
-    order: number;
-}, {
-    id: string;
-    title: string;
-    order: number;
-}>;
+}, z.core.$strip>;
 export type WorkflowPhase = z.infer<typeof workflowPhaseSchema>;
 /** A complete run snapshot, independent of the loaded conversation window. */
 export declare const workflowSchema: z.ZodObject<{
     runId: z.ZodOptional<z.ZodString>;
     name: z.ZodOptional<z.ZodString>;
-    state: z.ZodOptional<z.ZodEnum<["running", "paused", "completed", "failed", "stopped"]>>;
-    /** Observed counts: a dynamic script may start more agents later. */
+    state: z.ZodOptional<z.ZodEnum<{
+        paused: "paused";
+        running: "running";
+        completed: "completed";
+        failed: "failed";
+        stopped: "stopped";
+    }>>;
     started: z.ZodOptional<z.ZodNumber>;
     completed: z.ZodOptional<z.ZodNumber>;
     tokens: z.ZodOptional<z.ZodNumber>;
@@ -75,21 +67,20 @@ export declare const workflowSchema: z.ZodObject<{
         id: z.ZodString;
         title: z.ZodString;
         order: z.ZodNumber;
-    }, "strip", z.ZodTypeAny, {
-        id: string;
-        title: string;
-        order: number;
-    }, {
-        id: string;
-        title: string;
-        order: number;
-    }>, "many">>;
+    }, z.core.$strip>>>;
     agents: z.ZodOptional<z.ZodArray<z.ZodObject<{
         id: z.ZodString;
-        /** Present only after the host has imported this agent's transcript. */
         toolCallId: z.ZodOptional<z.ZodString>;
         title: z.ZodString;
-        state: z.ZodEnum<["pending", "running", "paused", "completed", "failed", "stopped", "unknown"]>;
+        state: z.ZodEnum<{
+            unknown: "unknown";
+            paused: "paused";
+            running: "running";
+            completed: "completed";
+            failed: "failed";
+            stopped: "stopped";
+            pending: "pending";
+        }>;
         phaseId: z.ZodOptional<z.ZodString>;
         model: z.ZodOptional<z.ZodString>;
         tokens: z.ZodOptional<z.ZodNumber>;
@@ -98,90 +89,6 @@ export declare const workflowSchema: z.ZodObject<{
         startedAt: z.ZodOptional<z.ZodNumber>;
         endedAt: z.ZodOptional<z.ZodNumber>;
         result: z.ZodOptional<z.ZodString>;
-    }, "strip", z.ZodTypeAny, {
-        id: string;
-        title: string;
-        state: "unknown" | "paused" | "running" | "completed" | "failed" | "stopped" | "pending";
-        toolCallId?: string | undefined;
-        phaseId?: string | undefined;
-        model?: string | undefined;
-        tokens?: number | undefined;
-        toolCalls?: number | undefined;
-        durationMs?: number | undefined;
-        startedAt?: number | undefined;
-        endedAt?: number | undefined;
-        result?: string | undefined;
-    }, {
-        id: string;
-        title: string;
-        state: "unknown" | "paused" | "running" | "completed" | "failed" | "stopped" | "pending";
-        toolCallId?: string | undefined;
-        phaseId?: string | undefined;
-        model?: string | undefined;
-        tokens?: number | undefined;
-        toolCalls?: number | undefined;
-        durationMs?: number | undefined;
-        startedAt?: number | undefined;
-        endedAt?: number | undefined;
-        result?: string | undefined;
-    }>, "many">>;
-}, "strip", z.ZodTypeAny, {
-    name?: string | undefined;
-    completed?: number | undefined;
-    state?: "paused" | "running" | "completed" | "failed" | "stopped" | undefined;
-    tokens?: number | undefined;
-    durationMs?: number | undefined;
-    startedAt?: number | undefined;
-    endedAt?: number | undefined;
-    runId?: string | undefined;
-    started?: number | undefined;
-    phases?: {
-        id: string;
-        title: string;
-        order: number;
-    }[] | undefined;
-    agents?: {
-        id: string;
-        title: string;
-        state: "unknown" | "paused" | "running" | "completed" | "failed" | "stopped" | "pending";
-        toolCallId?: string | undefined;
-        phaseId?: string | undefined;
-        model?: string | undefined;
-        tokens?: number | undefined;
-        toolCalls?: number | undefined;
-        durationMs?: number | undefined;
-        startedAt?: number | undefined;
-        endedAt?: number | undefined;
-        result?: string | undefined;
-    }[] | undefined;
-}, {
-    name?: string | undefined;
-    completed?: number | undefined;
-    state?: "paused" | "running" | "completed" | "failed" | "stopped" | undefined;
-    tokens?: number | undefined;
-    durationMs?: number | undefined;
-    startedAt?: number | undefined;
-    endedAt?: number | undefined;
-    runId?: string | undefined;
-    started?: number | undefined;
-    phases?: {
-        id: string;
-        title: string;
-        order: number;
-    }[] | undefined;
-    agents?: {
-        id: string;
-        title: string;
-        state: "unknown" | "paused" | "running" | "completed" | "failed" | "stopped" | "pending";
-        toolCallId?: string | undefined;
-        phaseId?: string | undefined;
-        model?: string | undefined;
-        tokens?: number | undefined;
-        toolCalls?: number | undefined;
-        durationMs?: number | undefined;
-        startedAt?: number | undefined;
-        endedAt?: number | undefined;
-        result?: string | undefined;
-    }[] | undefined;
-}>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
 export type Workflow = z.infer<typeof workflowSchema>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linkshell/wire",
-  "version": "0.2.21",
+  "version": "0.2.23",
   "description": "Wire protocol for LinkShell v2: session model, JSON-RPC methods, end-to-end encryption and the relay client.",
   "license": "MIT",
   "repository": {
@@ -29,7 +29,7 @@
     "@noble/ciphers": "^2.4.0",
     "@noble/curves": "^1.9.7",
     "@noble/hashes": "^1.8.0",
-    "zod": "^3.24.3"
+    "zod": "^4.6.7"
   },
   "devDependencies": {
     "vitest": "^3.2.1"

package/src/acp.ts

@@ -1,10 +1,10 @@
 import { z } from "zod";
 
-const env = z.record(z.string());
+const env = z.record(z.string(), z.string());
 export const mcpServerSchema = z.discriminatedUnion("type", [
   z.object({ type: z.literal("stdio"), name: z.string().min(1), command: z.string().min(1), args: z.array(z.string()).default([]), env: env.default({}) }),
-  z.object({ type: z.literal("http"), name: z.string().min(1), url: z.string().url(), headers: env.default({}) }),
-  z.object({ type: z.literal("sse"), name: z.string().min(1), url: z.string().url(), headers: env.default({}) }),
+  z.object({ type: z.literal("http"), name: z.string().min(1), url: z.url(), headers: env.default({}) }),
+  z.object({ type: z.literal("sse"), name: z.string().min(1), url: z.url(), headers: env.default({}) }),
   z.object({ type: z.literal("acp"), name: z.string().min(1), command: z.string().min(1), args: z.array(z.string()).default([]), env: env.default({}) }),
 ]);
 export type AcpMcpServer = z.infer<typeof mcpServerSchema>;
@@ -23,10 +23,10 @@ export const acpRemoteAgentSchema = z.object({
   label: z.string().min(1).max(80),
   transport: z.enum(["stdio", "http", "websocket"]),
   command: z.string().optional(), args: z.array(z.string()).default([]),
-  url: z.string().url().optional(),
+  url: z.url().optional(),
   /** Header name to environment-variable name. The UI does not store secrets. */
   headerEnv: env.default({}),
-  settings: acpAgentSettingsSchema.default({}),
+  settings: acpAgentSettingsSchema.prefault({}),
 });
 export type AcpRemoteAgent = z.infer<typeof acpRemoteAgentSchema>;
 

package/src/computer-preview.ts

@@ -4,7 +4,7 @@ export const PREVIEW_MAX_BYTES = 48 * 1024;
 export const previewFrameSchema = z.object({
   id: z.string().regex(/^[a-f0-9]{64}$/),
   target: z.string().max(1024),
-  capturedAt: z.number().finite().nonnegative(),
+  capturedAt: z.number().nonnegative(),
   width: z.number().int().positive().max(2048),
   height: z.number().int().positive().max(2048),
   mimeType: z.literal("image/webp"),

package/src/content.ts

@@ -1,9 +1,9 @@
 import { z } from "zod";
 
-const optionalString = z.string().nullish().transform((value) => value ?? undefined);
-const optionalMeta = z.record(z.unknown()).nullish().transform((value) => value ?? undefined);
+const optionalString = z.string().nullish().transform((value) => value ?? undefined).optional();
+const optionalMeta = z.record(z.string(), z.unknown()).nullish().transform((value) => value ?? undefined).optional();
 const contentMetadata = {
-  annotations: z.object({ audience: z.array(z.enum(["user", "assistant"])).nullish().transform((value) => value ?? undefined), priority: z.number().nullish().transform((value) => value ?? undefined), lastModified: optionalString }).passthrough().nullish().transform((value) => value ?? undefined),
+  annotations: z.looseObject({ audience: z.array(z.enum(["user", "assistant"])).nullish().transform((value) => value ?? undefined).optional(), priority: z.number().nullish().transform((value) => value ?? undefined).optional(), lastModified: optionalString }).nullish().transform((value) => value ?? undefined).optional(),
   _meta: optionalMeta,
 };
 const contentVariants = z.discriminatedUnion("type", [
@@ -28,7 +28,7 @@ const contentVariants = z.discriminatedUnion("type", [
     title: optionalString,
     description: optionalString,
     mimeType: optionalString,
-    size: z.number().nullish().transform((value) => value ?? undefined),
+    size: z.number().nullish().transform((value) => value ?? undefined).optional(),
     ...contentMetadata,
     /** What the link names: a file (default), a skill the user invoked, or another agent. */
     kind: z.enum(["file", "skill", "agent"]).optional(),
@@ -36,7 +36,7 @@ const contentVariants = z.discriminatedUnion("type", [
 ]);
 export type ContentBlock = z.infer<typeof contentVariants>;
 // Hide the nested validator implementation from every exported RPC declaration.
-export const contentBlockSchema: z.ZodType<ContentBlock, z.ZodTypeDef, unknown> = contentVariants;
+export const contentBlockSchema: z.ZodType<ContentBlock, unknown> = contentVariants;
 
 export const toolCallStatusSchema = z.enum(["pending", "in_progress", "completed", "failed"]);
 export type ToolCallStatus = z.infer<typeof toolCallStatusSchema>;

package/src/envelopes.ts

@@ -0,0 +1,288 @@
+// What agents and their desktop clients wrap around a person's words. Claude Code adds reminders
+// and IDE state, the Claude app adds session events and peer mail, Codex Desktop adds the files,
+// selection and browser state it attached: context for the model, not what the person typed.
+// Readers show the words, and the context as a chip or an event line where it means something to
+// them, the way Claude's and Codex's own apps do. Shared by the host (titles, previews, what it
+// keeps from Claude's transcripts) and every client.
+
+/** Tags whose whole content is for the model only: the Claude app's own list, then Codex's. */
+const HIDDEN_TAGS = [
+  "system-reminder",
+  "task-notification",
+  "slack_context",
+  "uploaded_files",
+  "available-deferred-tools",
+  "new-diagnostics",
+  "critical_user_preferences_reminder",
+  "persisted-output",
+  "local-command-caveat",
+  "tick",
+  "goal",
+  "mcp-resource",
+  "mcp-resource-update",
+  "mcp-polling-update",
+  "teammate-message",
+  "cross-session-message",
+  "launch-selected-element",
+  "connected_office_files",
+  "thinking",
+  "ide_opened_file",
+  "ide_selection",
+  "ide_diagnostics",
+  "browser_instruction",
+  "cell",
+  "cell_type",
+  "language",
+  "command-message",
+  "command-args",
+  "no-action-needed",
+  "comprehensive-mode-instructions",
+  "cu_window_hints",
+  "widget_context_hint",
+  "preview-annotation-context",
+  "terminal-selection",
+  "environment_context",
+  "user_instructions",
+  "turn_aborted",
+  "subagent_notification",
+  "external_codex_apps_open_page",
+];
+
+const hiddenPattern = (tags: string[]) => new RegExp(`<(${tags.join("|")})(?:\\s[^>]*)?>[\\s\\S]*?</\\1>`, "gi");
+const HIDDEN = hiddenPattern(HIDDEN_TAGS);
+/** Mail between sessions and agents: hidden in a person's bubble, but a message of its own when it is the whole message. */
+const PEER_TAGS = ["teammate-message", "cross-session-message"];
+const HIDDEN_BUT_PEERS = hiddenPattern(HIDDEN_TAGS.filter((tag) => !PEER_TAGS.includes(tag)));
+
+/** Something attached to a message, shown as a chip beside the words. */
+export interface UserContext {
+  kind: "file" | "image" | "pasted" | "selection" | "comments" | "checks" | "annotations" | "browser" | "review" | "pull-request" | "merge" | "history" | "other";
+  label: string;
+  /** A path, or the start of the attached text. */
+  detail?: string;
+}
+
+/** A message that is an event, not something said: one line in the conversation. */
+export type UserEvent =
+  | { kind: "ci"; count: number }
+  | { kind: "github"; count: number }
+  | { kind: "sessions"; sessions: { id?: string; title: string }[] }
+  | { kind: "scheduled"; name: string; detail?: string };
+
+export interface UserTextView {
+  /** The words to show; empty when the message is only context, an event or a command's output. */
+  text: string;
+  context: UserContext[];
+  /** A shell command run from the prompt (Claude's `!` mode), and what it printed. */
+  shell?: { command?: string; stdout?: string; stderr?: string };
+  /** What a local slash command printed (`/cost`, `/context`). */
+  output?: string;
+  event?: UserEvent;
+  /** Nothing in it is for a reader. */
+  hidden: boolean;
+}
+
+/** The text without what is for the model only; `keepPeers` keeps mail from other sessions and agents. */
+export function stripHiddenContext(text: string, { keepPeers = false }: { keepPeers?: boolean } = {}): string {
+  return text
+    .replace(/\r\n/g, "\n")
+    .replace(keepPeers ? HIDDEN_BUT_PEERS : HIDDEN, "")
+    .replace(/<\/?tool_use_error>/g, "")
+    // Claude's pointers to a background task's files, for itself.
+    .replace(/^(?:Full transcript available at|Read the output file to retrieve the result):.*$/gm, "")
+    .replace(/\s*\[event:[\da-f-]{36}\]\s*$/i, "")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+}
+
+// eslint-disable-next-line no-control-regex -- terminal colour codes start with ESC.
+const ANSI = /\u001b\[[\d;?]*[ -/]*[@-~]/g;
+
+function tagText(source: string, tag: string): string | undefined {
+  const match = new RegExp(`<${tag}(?:\\s[^>]*)?>([\\s\\S]*?)</${tag}>`, "i").exec(source);
+  return match ? match[1]! : undefined;
+}
+
+function attribute(attrs: string, name: string): string | undefined {
+  const match = new RegExp(`\\b${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)')`, "i").exec(attrs);
+  return match ? (match[1] ?? match[2]) : undefined;
+}
+
+const EVENT_TAGS = ["side-sessions-event", "ci-monitor-event", "github-webhook-activity"] as const;
+const EVENT_PATTERNS = new Map(EVENT_TAGS.map((tag) => [tag, new RegExp(`<${tag}\\b[^>]*>[\\s\\S]*?</${tag}>`, "gi")]));
+
+/** A message made only of one kind of tag, repeated: the count, else undefined. */
+function only(text: string, tag: (typeof EVENT_TAGS)[number]): number | undefined {
+  if (!text.startsWith(`<${tag}`)) return undefined;
+  const pattern = EVENT_PATTERNS.get(tag)!;
+  const all = text.match(pattern);
+  if (!all) return undefined;
+  return text.replace(pattern, "").trim() ? undefined : all.length;
+}
+
+/** Codex Desktop's sections before "## My request:", by heading. */
+const CONTEXT_SECTIONS: Record<string, UserContext["kind"]> = {
+  "Files mentioned by the user": "file",
+  "Files pasted by the user": "pasted",
+  "Selected text": "selection",
+  "Diff comments": "comments",
+  "Browser comments": "comments",
+  "Failing PR checks": "checks",
+  "Response annotations": "annotations",
+};
+const MODES: Record<string, [UserContext["kind"], string]> = {
+  "Code review guidelines": ["review", "审查模式"],
+  "Pull request fix": ["pull-request", "PR 修复"],
+  "Auto resolve merge": ["merge", "自动解决冲突"],
+  "Prior conversation with Codex": ["history", "参考历史对话"],
+};
+const SECTION_LABELS: Record<string, string> = {
+  "Selected text": "选中的文本",
+  "Diff comments": "差异评论",
+  "Browser comments": "浏览器评论",
+  "Failing PR checks": "失败的 PR 检查",
+  "Response annotations": "回复批注",
+};
+const REQUEST = /^## My request(?: for Codex)?:[ \t]*$/gm;
+
+const baseName = (path: string) => path.split(/[\\/]/).filter(Boolean).at(-1) ?? path;
+
+function codexContext(text: string, images: number): { text: string; context: UserContext[] } | undefined {
+  const start = /^(#{1,2}) ([^\n:]+):[ \t]*$/m.exec(text);
+  // Only an envelope Codex wrote: it opens the message with one of its own headings.
+  if (!start || start.index !== 0) return undefined;
+  const heading = start[2]!;
+  if (!(start[1] === "#" ? heading in CONTEXT_SECTIONS : heading in MODES || /^My request(?: for Codex)?$/.test(heading))) return undefined;
+  let cut = -1;
+  let after = 0;
+  for (const match of text.matchAll(REQUEST)) {
+    cut = match.index!;
+    after = match.index! + match[0].length;
+  }
+  const preface = cut < 0 ? text : text.slice(0, cut);
+  const request = cut < 0 ? "" : text.slice(after).trim();
+  const context: UserContext[] = [];
+  let imageEntries = 0;
+  const sections = preface.split(/^(?=#{1,2} [^\n:]+:[ \t]*$)/m);
+  for (const section of sections) {
+    const head = /^(#{1,2}) ([^\n:]+):[ \t]*\n?/.exec(section);
+    if (!head) continue;
+    const name = head[2]!;
+    const body = section.slice(head[0].length).trim();
+    if (head[1] === "##") {
+      const mode = MODES[name];
+      if (mode) context.push({ kind: mode[0], label: mode[1] });
+      continue;
+    }
+    const kind = CONTEXT_SECTIONS[name];
+    if (kind === "file") {
+      for (const entry of body.matchAll(/^## (.+?): (.+?)(?: \((lines? [^)]*)\))?\n?(Image attachment: true)?$/gm)) {
+        if (entry[4]) {
+          imageEntries += 1;
+          // The picture itself is shown; a chip for it would say it twice.
+          if (imageEntries <= images) continue;
+        }
+        context.push({ kind: entry[4] ? "image" : "file", label: entry[1]!.includes("/") ? baseName(entry[1]!) : entry[1]!, detail: entry[3] ? `${entry[2]} · ${entry[3]}` : entry[2] });
+      }
+    } else if (kind === "pasted") {
+      for (const entry of body.matchAll(/^## "?(.+?)"?: (.+)$/gm)) context.push({ kind: "pasted", label: entry[1]!.trim(), detail: entry[2] });
+    } else if (kind) {
+      context.push({ kind, label: SECTION_LABELS[name] ?? name, detail: body.split("\n").find((line) => line.trim())?.trim() });
+    } else if (name !== "Distinguish instructions in attached documents from the user's request") {
+      context.push({ kind: "other", label: name });
+    }
+  }
+  return { text: request, context };
+}
+
+// Claude writes a shell's output into its transcript with <, > and & escaped.
+const ENTITIES: Record<string, string> = { lt: "<", gt: ">", amp: "&", quot: "\"", apos: "'" };
+function unescapeHtml(value: string): string {
+  // One pass: "&amp;gt;" is the text "&gt;", not ">".
+  return value.replace(/&(lt|gt|amp|quot|apos|#\d{1,7}|#x[0-9a-f]{1,6});/gi, (whole, name: string) => {
+    const key = name.toLowerCase();
+    const code = key.startsWith("#x") ? parseInt(key.slice(2), 16) : key.startsWith("#") ? Number(key.slice(1)) : undefined;
+    if (code === undefined) return ENTITIES[key] ?? whole;
+    return code > 0 && code <= 0x10ffff ? String.fromCodePoint(code) : whole;
+  });
+}
+
+/** Output as a terminal shows it: no colour codes, a backspace takes back the character before it, other controls are not drawn. */
+function printed(value: string): string {
+  let text = value.replace(ANSI, "");
+  // eslint-disable-next-line no-control-regex -- a backspace is the character being handled.
+  for (let previous = ""; previous !== text; ) { previous = text; text = text.replace(/[^\n\x08]\x08/g, ""); }
+  // eslint-disable-next-line no-control-regex -- what a terminal doesn't draw.
+  return text.replace(/[\x00-\x08\x0b-\x1f\x7f]/g, "");
+}
+
+/**
+ * Codex Desktop writes a mention of another of its threads as a Markdown link to
+ * codex://threads/<id>, with the space before it as "&#x20;": read as the thread's title.
+ */
+function threadMentions(text: string): string {
+  const read = text.replace(/&#(?:x20|32);/gi, " ").replace(/\[([^\]\n]+)\]\(codex:\/\/threads\/[\w-]+\)/g, "「$1」");
+  return read === text ? text : read.trim();
+}
+
+/**
+ * How to show a person's message: its words, what came with it, or the one event it is. `images`
+ * is how many pictures the message carries besides its text, so an envelope naming them doesn't
+ * also chip them.
+ */
+export function readUserText(raw: string, { images = 0 }: { images?: number } = {}): UserTextView {
+  let text = raw.replace(/\r\n/g, "\n");
+  const context: UserContext[] = [];
+  const view = (rest: Partial<UserTextView>): UserTextView => ({ text: "", context, hidden: false, ...rest });
+
+  // The Claude app tells a session about the sessions it started in a reminder beside the event.
+  const sessions = [...text.matchAll(/The session "([^"\n]+)" you started \((local_[\w-]+)\)/g)].map((match) => ({ title: match[1]!, id: match[2] }));
+  const browser = /<in-app-browser-context\b[^>]*>[\s\S]*?<\/in-app-browser-context>/gi;
+  const withoutBrowser = text.replace(browser, "");
+  if (withoutBrowser !== text) {
+    context.push({ kind: "browser", label: "浏览器上下文" });
+    text = withoutBrowser;
+  }
+  text = stripHiddenContext(text);
+
+  if (only(text, "side-sessions-event")) return view({ event: { kind: "sessions", sessions } });
+  if (!text) return view({ hidden: images === 0 && context.length === 0 });
+  if (/^\[Request interrupted by user(?: for tool use)?\]$/.test(text)) return view({ hidden: true });
+  const ci = only(text, "ci-monitor-event");
+  if (ci) return view({ event: { kind: "ci", count: ci } });
+  const github = only(text, "github-webhook-activity");
+  if (github) return view({ event: { kind: "github", count: github } });
+  const scheduled = /^<scheduled-task\b([^>]*)>([\s\S]*?)<\/scheduled-task>$/i.exec(text);
+  if (scheduled) {
+    const name = attribute(scheduled[1]!, "name") ?? baseName(attribute(scheduled[1]!, "file") ?? "").replace(/\.md$/i, "");
+    return view({ event: { kind: "scheduled", name: name || "定时任务", detail: scheduled[2]!.trim() || undefined } });
+  }
+
+  if (/^<bash-(?:input|stdout|stderr)>/.test(text)) {
+    const clean = (value?: string) => (value === undefined ? undefined : printed(unescapeHtml(value)).replace(/\n+$/, "")) || undefined;
+    const command = clean(tagText(text, "bash-input"))?.trim();
+    const stdout = clean(tagText(text, "bash-stdout"));
+    const stderr = clean(tagText(text, "bash-stderr"));
+    const rest = text.replace(/<(bash-(?:input|stdout|stderr|exit-code))>[\s\S]*?<\/\1>/g, "").trim();
+    return view({ shell: { command, stdout, stderr }, text: rest, hidden: !command && !stdout && !stderr && !rest });
+  }
+  if (/^<local-command-(?:stdout|stderr)>/.test(text)) {
+    const raw = [tagText(text, "local-command-stdout"), tagText(text, "local-command-stderr")]
+      .filter((part): part is string => !!part?.trim())
+      .join("\n")
+      .replace(ANSI, "");
+    const output = unescapeHtml(raw).trim();
+    // /model's confirmation: the Claude app doesn't show the switch as a line either.
+    return view({ output: output || undefined, hidden: !output || /^Set model to\b/.test(output) });
+  }
+  // Slash-command plumbing the host couldn't read as a command, and notifications it didn't match.
+  if (/^<(?:command-name|local-command-|task-notification)/.test(text)) return view({ hidden: true });
+
+  const codex = codexContext(text, images);
+  if (codex) {
+    context.push(...codex.context);
+    const words = threadMentions(codex.text);
+    return view({ text: words, hidden: !words && images === 0 && context.length === 0 });
+  }
+  return view({ text: threadMentions(text) });
+}

package/src/index.ts

@@ -18,3 +18,5 @@ export * from "./live-activity.js";
 export * from "./watch.js";
 export * from "./usage.js";
 export * from "./side.js";
+export * from "./rpc-mcp.js";
+export * from "./envelopes.js";

package/src/live-activity.ts

@@ -42,7 +42,7 @@ export interface LiveActivityPayload extends Partial<LiveActivityContentState> {
 export const liveActivityIdSchema = z.string().min(1).max(128).regex(/^[a-zA-Z0-9-]+$/);
 export const liveActivitySubscriptionSchema = z.object({
   activityId: liveActivityIdSchema,
-  serviceUrl: z.string().url().max(256),
+  serviceUrl: z.url().max(256),
   grant: z.string().regex(/^[a-f0-9]{64}$/),
   expiresAt: z.number().int().positive(),
   computerKey: z.string().min(1).max(512),

package/src/model.ts

@@ -254,6 +254,25 @@ export const sessionSummarySchema = z.object({
    * (the project the session belongs to).
    */
   worktree: z.object({ branch: z.string(), source: z.string() }).optional(),
+  /**
+   * The LinkShell session that started this one (e.g. a Claude desktop
+   * session's start_session or hand-off): the sidebar nests it there. Set
+   * only when this host has that session too. Absent from older hosts.
+   */
+  parentId: z.string().optional(),
+  /**
+   * The LinkShell session this one was forked from (made here with
+   * `sessions.fork`, or recorded by the agent), when this host has it. Kept
+   * apart from `parentId`: a fork is a copy, not something that session
+   * started, so whether it nests is the list's choice.
+   */
+  forkedFrom: z.string().optional(),
+  /**
+   * The id an app of the agent's knows the session by (the Claude desktop
+   * app's `local_…`): mail between its sessions names the sender by it, so a
+   * client can open the sender. Absent from older hosts.
+   */
+  appId: 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(),
   /** Live only, for sessions that left commands running: how many, and how many still run (`sessions.tasks` lists them). */
@@ -363,6 +382,11 @@ export const terminalInfoSchema = z.object({
   exitCode: z.number().int().nullable().optional(),
   /** Ended without an exit code: the host stopped while it ran. */
   interrupted: z.boolean().optional(),
+  /**
+   * The session it was opened for. Such a terminal belongs to the session: it closes when its
+   * shell exits or the session is archived or deleted, and isn't kept across a host restart.
+   */
+  sessionId: z.string().optional(),
 });
 export type TerminalInfo = z.infer<typeof terminalInfoSchema>;
 

package/src/relay.ts

@@ -74,7 +74,7 @@ export const serverFrameSchema = z.discriminatedUnion("t", [
     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() }),
+  z.object({ t: z.literal("event"), name: z.string(), data: z.unknown().optional() }),
   /** 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. */