@linkshell/wire 0.2.21 → 0.2.23

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.string(), 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

@@ -22,6 +22,7 @@ import {
 } 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 ─────────────────────────────────────────────
 
@@ -73,10 +74,11 @@ export const RPC_APP_ERROR = -32000;
  * 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 = 1;
+export const HOST_PROTOCOL = 2;
 
-const empty = z.object({}).passthrough();
+const empty = z.looseObject({});
 
 export const directoryEntrySchema = z.object({
   name: z.string(),
@@ -109,7 +111,7 @@ const acpMethods = {
     result: empty,
   },
   "agents.providers": {
-    params: z.object({ agent: z.string().min(1), operation: z.enum(["list", "set", "disable"]), config: z.object({ providerId: z.string(), apiType: z.string().optional(), baseUrl: z.string().url().optional(), headers: z.record(z.string()).optional() }).optional() }),
+    params: z.object({ agent: z.string().min(1), operation: z.enum(["list", "set", "disable"]), config: z.object({ providerId: z.string(), apiType: z.string().optional(), baseUrl: z.url().optional(), headers: z.record(z.string(), z.string()).optional() }).optional() }),
     result: z.object({ providers: z.array(acpProviderSchema) }),
   },
   "agents.custom": {
@@ -149,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
@@ -408,12 +434,12 @@ const coreMethods = {
       args: z.array(z.string()).default([]),
       /** The terminal's working directory and environment. */
       cwd: z.string().optional(),
-      env: z.record(z.string()).optional(),
+      env: z.record(z.string(), z.string()).optional(),
     }),
     result: z.object({
       command: z.string(),
       args: z.array(z.string()),
-      env: z.record(z.string()).optional(),
+      env: z.record(z.string(), z.string()).optional(),
       /** Set for handoff agents: the session this terminal now drives. */
       sessionId: z.string().optional(),
     }),
@@ -429,7 +455,7 @@ const coreMethods = {
     result: z.object({
       command: z.string(),
       args: z.array(z.string()),
-      env: z.record(z.string()).optional(),
+      env: z.record(z.string(), z.string()).optional(),
     }),
   },
   // ── Gateway: reach this computer from anywhere ──
@@ -566,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),
@@ -700,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"]>;

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. */