@linkshell/wire 0.2.20 → 0.2.22

package/src/envelopes.ts

@@ -0,0 +1,278 @@
+// 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();
+}
+
+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;
+  });
+}
+
+/**
+ * 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 : unescapeHtml(value).replace(ANSI, "").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

@@ -17,3 +17,6 @@ export * from "./editor.js";
 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/model.ts

@@ -33,6 +33,8 @@ export const agentCapabilitiesSchema = z.object({
    * shows the conversation and its agent is told it as text.
    */
   fork: z.boolean(),
+  /** The agent has a side conversation of its own (`sessions.side`). Absent from older hosts. */
+  side: z.boolean().optional(),
   models: z.boolean(),
   modes: z.boolean(),
 });
@@ -252,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). */
@@ -314,6 +335,8 @@ export const machineInfoSchema = z.object({
   hostname: z.string(),
   platform: z.string(),
   hostVersion: z.string(),
+  /** The host's RPC revision (`HOST_PROTOCOL`); absent from hosts older than it. */
+  protocol: z.number().int().nonnegative().optional(),
   /** The host user's home directory, so apps can show paths as `~/…`. */
   home: z.string().optional(),
   agents: z.array(agentInfoSchema),
@@ -359,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/rpc-mcp.ts

@@ -0,0 +1,81 @@
+import { z } from "zod";
+import { mcpAppDisplayModeSchema } from "./updates.js";
+
+// MCP Apps: an MCP tool can declare a page of its own (a `ui://` HTML
+// resource) that the client shows in a sandboxed frame, and that page can call
+// its server's tools back. Codex sessions only: Codex is the agent that tells
+// the host which tools have pages and lets a client read and call them. Other
+// agents' sessions are refused with `not_supported`; a Codex that isn't
+// running with `agent_unavailable`. Hosts older than these methods answer
+// "method not found".
+
+/** A tool Codex offers as an app of the thread (what its "插件和 MCP" menu lists). */
+export const mcpAppSchema = z.object({
+  server: z.string(),
+  tool: z.string(),
+  /** The plugin's or connector's name where there is one, else the tool's. */
+  title: z.string(),
+  description: z.string().optional(),
+  /** Always `ui://…`. */
+  resourceUri: z.string(),
+  /** Where Codex offers it (`openai/ui.entrypoints[].type`): always includes "thread". */
+  entrypoints: z.array(z.string()),
+  /** Who may call the tool (`ui.visibility`: "model", "app"); absent: both. */
+  visibility: z.array(z.string()).optional(),
+  displayMode: mcpAppDisplayModeSchema.optional(),
+  /** The Codex connector (server `codex_apps`): `mcp.call` needs it there. */
+  connector: z.string().optional(),
+});
+export type McpApp = z.infer<typeof mcpAppSchema>;
+
+export const mcpMethods = {
+  /** The apps the session's Codex can open in the thread. */
+  "mcp.apps": {
+    params: z.object({ sessionId: z.string().min(1) }),
+    result: z.object({ apps: z.array(mcpAppSchema) }),
+  },
+  /**
+   * A page's HTML (its first content), as the MCP server gives it. Only `ui://`
+   * URIs (`invalid_params` otherwise); one over 4 MB is refused (`too_large`).
+   * `meta` is the content's `_meta`: CSP domains, display modes, border.
+   */
+  "mcp.resource": {
+    params: z.object({
+      sessionId: z.string().min(1),
+      server: z.string().min(1),
+      uri: z.string().min(1),
+      /** The page's connector (`detail.app.connector`, `McpApp.connector`), for server `codex_apps`. */
+      connector: z.string().optional(),
+    }),
+    result: z.object({
+      mimeType: z.string().optional(),
+      text: z.string().optional(),
+      blob: z.string().optional(),
+      meta: z.unknown().optional(),
+    }),
+  },
+  /**
+   * A page calls one of its server's tools, in the session's thread. Refused
+   * (`forbidden`) for a server without a page, a tool the page may not call
+   * (`ui.visibility` without "app", `openai/fileParams`), or, on `codex_apps`, a
+   * tool of another connector than `connector` (required there:
+   * `invalid_params` without it); `not_found` for a tool the server doesn't
+   * have. Codex's own failure is `agent_error`; a tool that ran and failed is
+   * `isError` in the result.
+   */
+  "mcp.call": {
+    params: z.object({
+      sessionId: z.string().min(1),
+      server: z.string().min(1),
+      tool: z.string().min(1),
+      arguments: z.record(z.unknown()).optional(),
+      connector: z.string().optional(),
+    }),
+    result: z.object({
+      content: z.array(z.unknown()),
+      structuredContent: z.unknown().optional(),
+      isError: z.boolean().optional(),
+      meta: z.unknown().optional(),
+    }),
+  },
+} as const;

package/src/rpc.ts

@@ -21,6 +21,8 @@ import {
   pendingPermissionSchema,
 } from "./model.js";
 import { contentBlockSchema, sessionEventSchema, sessionNoticeSchema } from "./updates.js";
+import { sideChatSchema } from "./side.js";
+import { mcpMethods } from "./rpc-mcp.js";
 
 // ── JSON-RPC 2.0 framing ─────────────────────────────────────────────
 
@@ -67,6 +69,15 @@ export const RPC_APP_ERROR = -32000;
 
 // ── Methods (client → host) ──────────────────────────────────────────
 
+/**
+ * The host's RPC revision, in `machine.info`. Goes up when the host gains
+ * methods or notifications an app may rely on, so an app can tell the
+ * computer is older than itself and say so (an absent revision is 0).
+ * 1: side conversations (`sessions.side`), `machine.info.protocol` itself.
+ * 2: session terminals (`terminals.create` `sessionId`, `TerminalInfo.sessionId`).
+ */
+export const HOST_PROTOCOL = 2;
+
 const empty = z.object({}).passthrough();
 
 export const directoryEntrySchema = z.object({
@@ -140,12 +151,36 @@ const coreMethods = {
       nextBefore: z.number().optional(),
     }),
   },
+  /**
+   * The models a new session of `agent` can start on, for choosing one before
+   * there is a session (whose own list comes later, in its `ls_config`).
+   * `current` is the one the agent takes when `sessions.create` names none:
+   * its own default, which a new session keeps unless another is picked.
+   * Agents that tell their models only to a session give what they said in
+   * the latest one opened on this computer; never asked by starting one, so
+   * empty until there has been one (`current` too may be missing then).
+   * With an empty list `sessions.create` takes no model. Hosts older than
+   * this method answer "method not found".
+   */
+  "agents.models": {
+    params: z.object({
+      agent: z.string().min(1),
+      /** Where the session will work: an agent's project settings can choose another model. */
+      cwd: z.string().optional(),
+    }),
+    result: z.object({
+      /** As a session's model option lists them (`group`: the heading some agents put models under). */
+      models: z.array(z.object({ value: z.string(), name: z.string(), description: z.string().optional(), group: z.string().optional() })),
+      current: z.string().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(),
+      /** One of `agents.models`' values; absent: the agent's own default. */
       model: z.string().optional(),
       /**
        * Start in a new git worktree of `cwd`'s repository (its own branch, from
@@ -218,6 +253,31 @@ const coreMethods = {
     params: z.object({ sessionId: z.string().min(1), toolCallId: z.string().min(1), lazyImages: z.boolean().optional() }),
     result: z.object({ events: z.array(sessionEventSchema) }),
   },
+  /**
+   * Asks in a side conversation of the session (a new one without `sideId`):
+   * answered from what the session knows, never added to it. Returns once the
+   * question is on its way; the answer comes in `session.side`. Only for an
+   * agent whose capabilities say `side`.
+   */
+  "sessions.side": {
+    params: z.object({ sessionId: z.string().min(1), sideId: z.string().min(1).optional(), text: z.string().min(1).max(20_000) }),
+    result: z.object({ side: sideChatSchema }),
+  },
+  /** The session's open side conversations, oldest first. */
+  "sessions.sides": {
+    params: z.object({ sessionId: z.string().min(1) }),
+    result: z.object({ sides: z.array(sideChatSchema) }),
+  },
+  /** Stops the answer under way. */
+  "sessions.sideCancel": {
+    params: z.object({ sessionId: z.string().min(1), sideId: z.string().min(1) }),
+    result: empty,
+  },
+  /** Ends a side conversation: it is forgotten, and whatever the agent kept for it let go. */
+  "sessions.sideClose": {
+    params: z.object({ sessionId: z.string().min(1), sideId: z.string().min(1) }),
+    result: empty,
+  },
   /** The commands this session left running in the background, and the ones that have ended; newest first. */
   "sessions.tasks": {
     params: z.object({ sessionId: z.string().min(1) }),
@@ -532,6 +592,8 @@ const coreMethods = {
   "terminals.create": {
     params: z.object({
       cwd: z.string().optional(),
+      /** Open it for this session, in its directory unless `cwd` says otherwise (see `TerminalInfo.sessionId`). */
+      sessionId: 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),
@@ -666,7 +728,7 @@ const coreMethods = {
   },
 } as const;
 
-export const methods: typeof coreMethods & typeof acpMethods = { ...coreMethods, ...acpMethods };
+export const methods: typeof coreMethods & typeof acpMethods & typeof mcpMethods = { ...coreMethods, ...acpMethods, ...mcpMethods };
 
 export type MethodName = keyof typeof methods;
 export type MethodParams<M extends MethodName> = z.input<(typeof methods)[M]["params"]>;
@@ -690,6 +752,8 @@ export const notifications = {
    */
   "session.window": z.object({ sessionId: z.string(), startSeq: z.number().int().nonnegative() }),
   "session.summary": z.object({ session: sessionSummarySchema }),
+  /** A side conversation changed (to every client), or ended (`closed`). */
+  "session.side": z.object({ sessionId: z.string(), side: sideChatSchema, closed: z.boolean().optional() }),
   /** A session was deleted (from any device, or natively by the agent). */
   "session.removed": z.object({ sessionId: z.string() }),
   "session.preview.show": z.object({ sessionId: z.string() }),

package/src/side.ts

@@ -0,0 +1,30 @@
+import { z } from "zod";
+
+/**
+ * A side conversation: questions about a session that are answered from what
+ * it knows but don't enter it, the agent's own feature (Codex's `/side`,
+ * Claude's and Grok's `/btw`). It lives on the computer only while it is
+ * open; nothing of it is in the session's history.
+ */
+
+export const sideMessageSchema = z.object({
+  id: z.string(),
+  role: z.enum(["user", "assistant"]),
+  text: z.string(),
+  /** What the agent did on the way to an answer (a file it read, a command it ran), one line each. */
+  activity: z.array(z.string()).optional(),
+  /** The answer didn't come: why. */
+  error: z.string().optional(),
+});
+export type SideMessage = z.infer<typeof sideMessageSchema>;
+
+export const sideChatSchema = z.object({
+  sideId: z.string(),
+  createdAt: z.number(),
+  /** Answering the last question. */
+  running: z.boolean(),
+  /** Goes up with every change: a client keeps the copy with the highest. */
+  revision: z.number().int().nonnegative(),
+  messages: z.array(sideMessageSchema),
+});
+export type SideChat = z.infer<typeof sideChatSchema>;

package/src/updates.ts

@@ -21,8 +21,22 @@ export type ToolCallLocation = z.infer<typeof toolCallLocationSchema>;
  * Host drivers fill it from each agent's own tool names; clients render it the
  * same way for every agent and fall back to `title` + `kind` without it.
  */
+export const mcpAppDisplayModeSchema = z.enum(["inline", "fullscreen"]);
+
 export const toolDetailSchema = z.discriminatedUnion("type", [
-  z.object({ type: z.literal("mcp"), server: z.string(), tool: z.string() }),
+  z.object({
+    type: z.literal("mcp"),
+    server: z.string(),
+    tool: z.string(),
+    /**
+     * The tool has a page of its own (an MCP App), which `mcp.resource` reads.
+     * Codex sessions only. It may arrive in a later `tool_call_update` than the
+     * call's card, when the host had to look the tool up first. `connector`:
+     * the Codex connector (server `codex_apps`) the page belongs to, which
+     * `mcp.call` needs for that server.
+     */
+    app: z.object({ resourceUri: z.string(), displayMode: mcpAppDisplayModeSchema.optional(), connector: z.string().optional() }).optional(),
+  }),
   z.object({
     type: z.literal("subagent"),
     /** spawn starts a sub-agent (its work nests under this call); the rest talk to one. */