@yaklabs-ai/plugin-sdk 0.52.1 → 0.54.0

package/dist/kay-agent.d.ts

@@ -2795,8 +2795,16 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 0.52.0 adds plugin-owned operational facts through existing manifests and registrations.
  *
  * 0.52.1 adds owner-qualified page feed and endpoint references and their kay.ui claims.
+ *
+ * 0.53.0 adds declared working-content layouts, family-root authority, draft projection discovery
+ * and session-bound page references. Older customized Whiteboard copies must accept the plugin
+ * update before using these interfaces.
+ *
+ * 0.54.0 adds named UI host grants for shared configuration/auth/account reads, retained connection
+ * progress/dismissal and support. Built-in-only page capability scopes are removed; executable
+ * pages declare capabilities on apps[].
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.52.1";
+declare const KAY_PLUGIN_SDK_VERSION: "0.54.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -2865,9 +2873,9 @@ export declare interface KayAgentEvents {
 /** This plugin's folder in the session family's shared Whiteboard. */
 export declare interface KayAgentFamilyFolder {
     /**
-     * The folder's absolute path, created on first use. The plugin that owns the Whiteboard gets
-     * the whole family folder; every other plugin gets its own `plugins/<plugin-id>/` inside it.
-     * Undefined outside a session.
+     * Absolute path, created on first use; undefined outside a session. A declared and granted
+     * family-root owner receives the whole folder; other plugins receive `plugins/<plugin-id>/`.
+     * Root access checks the live `family-folder.root` grant on every call.
      */
     path(): Promise<string | undefined>;
 }
@@ -5130,6 +5138,18 @@ declare const PluginCapabilityRefusalV1: z.ZodObject<{
         target: z.ZodLiteral<"kay.app">;
         slug: z.ZodLiteral<"plugins.set-enabled">;
         envelope: z.ZodObject<{}, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        target: z.ZodLiteral<"kay.app">;
+        slug: z.ZodLiteral<"sessions.assign-project">;
+        envelope: z.ZodObject<{}, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        target: z.ZodLiteral<"kay.app">;
+        slug: z.ZodLiteral<"artifacts.resolve-file">;
+        envelope: z.ZodObject<{}, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        target: z.ZodLiteral<"kay.app">;
+        slug: z.ZodLiteral<"process.run">;
+        envelope: z.ZodObject<{}, z.core.$strict>;
     }, z.core.$strict>, z.ZodObject<{
         target: z.ZodLiteral<"kay.app">;
         slug: z.ZodLiteral<"sessions.annotate">;
@@ -5353,6 +5373,10 @@ declare const PluginCapabilityRefusalV1: z.ZodObject<{
             command: z.ZodString;
             args: z.ZodArray<z.ZodString>;
         }, z.core.$strict>], "channel">;
+    }, z.core.$strict>, z.ZodObject<{
+        target: z.ZodLiteral<"kay.agent">;
+        slug: z.ZodLiteral<"family-folder.root">;
+        envelope: z.ZodObject<{}, z.core.$strict>;
     }, z.core.$strict>, z.ZodObject<{
         target: z.ZodEnum<{
             "kay.agent": "kay.agent";
@@ -5670,6 +5694,33 @@ export declare interface ProducedResourceDeclaration {
     readonly action: ProducedResourceAction;
 }
 
+export declare const ProjectDirectory: z.ZodObject<{
+    id: z.ZodString;
+    path: z.ZodString;
+    defaultCwd: z.ZodString;
+    ancestorIds: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+
+export declare type ProjectDirectory = z.infer<typeof ProjectDirectory>;
+
+export declare const ProjectDirectoryRequest: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strict>;
+
+export declare type ProjectDirectoryRequest = z.infer<typeof ProjectDirectoryRequest>;
+
+/** `project` is null when no project has the requested id. */
+export declare const ProjectDirectoryResponse: z.ZodObject<{
+    project: z.ZodNullable<z.ZodObject<{
+        id: z.ZodString;
+        path: z.ZodString;
+        defaultCwd: z.ZodString;
+        ancestorIds: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+
+export declare type ProjectDirectoryResponse = z.infer<typeof ProjectDirectoryResponse>;
+
 declare const Properties: (input: string) => [unknown, string] | [];
 
 declare function PropertiesMapping(input: [unknown, unknown, unknown]): unknown;
@@ -12084,8 +12135,8 @@ export declare const WhiteboardEntryInfo: z.ZodObject<{
         authorSessionId: z.ZodNullable<z.ZodString>;
     }, z.core.$strict>>;
     state: z.ZodEnum<{
-        unavailable: "unavailable";
         available: "available";
+        unavailable: "unavailable";
         "unsupported-version": "unsupported-version";
         invalid: "invalid";
     }>;
@@ -12106,8 +12157,8 @@ export declare const WhiteboardEntryInspection: z.ZodObject<{
         authorSessionId: z.ZodNullable<z.ZodString>;
     }, z.core.$strict>>;
     state: z.ZodEnum<{
-        unavailable: "unavailable";
         available: "available";
+        unavailable: "unavailable";
         "unsupported-version": "unsupported-version";
         invalid: "invalid";
     }>;
@@ -12158,6 +12209,9 @@ export declare const WhiteboardTypeInfo: z.ZodObject<{
     displayName: z.ZodString;
     schemaVersion: z.ZodNumber;
     available: z.ZodBoolean;
+    reference: z.ZodOptional<z.ZodObject<{
+        uriTemplate: z.ZodString;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 
 export declare type WhiteboardTypeInfo = Readonly<z.infer<typeof WhiteboardTypeInfo>>;

package/dist/kay-agent.js

@@ -192,6 +192,8 @@ function isLoneCapture(pattern) {
   return pattern.length === 1 && pattern[0].capture !== void 0 && pattern[0].rest !== true;
 }
 function matchParts(pattern, value, separator, captures, foldLiterals = false) {
+  if (pattern.length === 0)
+    return value === "";
   const parts = separator === void 0 ? [value] : value.split(separator);
   let partIndex = 0;
   for (let i = 0; i < pattern.length; i += 1) {
@@ -997,6 +999,31 @@ function createUnavailableUriCaller(message) {
   };
 }
 
+// packages/plugin-protocol/dist/project-directories.js
+import { z as z5 } from "zod";
+var PluginProjectDirectories = z5.strictObject({
+  /** An endpoint this plugin's app target declares; called with a {@link ProjectDirectoryRequest}. */
+  endpoint: z5.string().min(1),
+  /** A scheme this plugin's URI modules serve; a project is addressed as `<scheme>://<id>`. */
+  scheme: z5.string().min(1)
+});
+var ProjectDirectoryRequest = z5.strictObject({
+  /** The project's stable id. */
+  id: z5.string().min(1)
+});
+var ProjectDirectory = z5.strictObject({
+  id: z5.string().min(1),
+  /** Absolute path of the project's folder. */
+  path: z5.string().min(1),
+  /** Absolute path a new session in this project starts in. */
+  defaultCwd: z5.string().min(1),
+  /** Ancestor project ids, root first. */
+  ancestorIds: z5.array(z5.string().min(1))
+});
+var ProjectDirectoryResponse = z5.strictObject({
+  project: ProjectDirectory.nullable()
+});
+
 // packages/plugin-sdk/dist/endpoints.js
 function createUnavailablePluginEndpointCaller(message) {
   return {
@@ -1169,7 +1196,7 @@ async function readBodyWithByteCap(response, maxBytes) {
 }
 
 // packages/plugin-primitives/dist/tool-parameters.js
-import { z as z5 } from "zod";
+import { z as z6 } from "zod";
 var URI_PAYLOAD_MARKER = "x-kay-uri-payload";
 var URI_PAYLOAD_WIRE_TYPES = [
   "string",
@@ -1179,16 +1206,16 @@ var URI_PAYLOAD_WIRE_TYPES = [
   "boolean",
   "null"
 ];
-var uriPayloadSchema = z5.union([
-  z5.string(),
-  z5.record(z5.string(), z5.unknown()),
-  z5.array(z5.unknown()),
-  z5.number(),
-  z5.boolean(),
-  z5.null()
+var uriPayloadSchema = z6.union([
+  z6.string(),
+  z6.record(z6.string(), z6.unknown()),
+  z6.array(z6.unknown()),
+  z6.number(),
+  z6.boolean(),
+  z6.null()
 ]).meta({ [URI_PAYLOAD_MARKER]: true });
 function toToolParameters(schema) {
-  const jsonSchema = z5.toJSONSchema(schema, {
+  const jsonSchema = z6.toJSONSchema(schema, {
     io: "input",
     override(ctx) {
       const node = ctx.jsonSchema;
@@ -1329,7 +1356,7 @@ function jsonValue(value) {
 }
 
 // packages/plugin-sdk/dist/kay-agent/index.js
-import { z as z7 } from "zod";
+import { z as z8 } from "zod";
 
 // packages/plugin-sdk/dist/kay-agent/http-client.js
 var PluginApiError = class extends Error {
@@ -1505,7 +1532,7 @@ function createUnavailableEndpoints(message) {
 }
 
 // packages/plugin-sdk/dist/kay-agent/osascript.js
-import { z as z6 } from "zod";
+import { z as z7 } from "zod";
 var OSASCRIPT_TIMEOUT_MS = 3e4;
 var OSASCRIPT_ENVELOPE_JXA = `
 function jsonOk(data) {
@@ -1515,11 +1542,11 @@ function jsonFail(code, message) {
   return JSON.stringify({ ok: false, error: { code: String(code), message: String(message) } });
 }
 `;
-var envelopeSchema = z6.discriminatedUnion("ok", [
-  z6.object({ ok: z6.literal(true), data: z6.unknown() }),
-  z6.object({
-    ok: z6.literal(false),
-    error: z6.object({ code: z6.string(), message: z6.string() })
+var envelopeSchema = z7.discriminatedUnion("ok", [
+  z7.object({ ok: z7.literal(true), data: z7.unknown() }),
+  z7.object({
+    ok: z7.literal(false),
+    error: z7.object({ code: z7.string(), message: z7.string() })
   })
 ]);
 function readOsascriptOutput(stdout) {
@@ -1715,6 +1742,9 @@ export {
   OSASCRIPT_ENVELOPE_JXA,
   OSASCRIPT_TIMEOUT_MS,
   PluginApiError,
+  ProjectDirectory,
+  ProjectDirectoryRequest,
+  ProjectDirectoryResponse,
   SearchProviderError,
   SecureTransportError,
   URI_TEXT_EDIT_SHAPE_SUMMARY,
@@ -1785,5 +1815,5 @@ export {
   uriTextEditPayloadSchema,
   withResolvedAuth,
   withResolvedSearchProvider,
-  z7 as z
+  z8 as z
 };

package/dist/kay-app-session-summary.d.ts

@@ -1824,6 +1824,18 @@ declare type KayAppSessionPageItem = (Omit<Extract<TranscriptPageItem, {
     readonly unreadable: unknown;
 }>;
 
+/** One write for {@link KayAppSessions.assignProject}. */
+declare interface KayAppSessionProjectAssignment {
+    readonly sessionId: string;
+    /**
+     * The project the session must still hold for the write to land: a project id, `null` for "no
+     * project" chosen on purpose, or absent for a session whose project was never decided.
+     */
+    readonly expectedProjectId?: string | null;
+    /** The project to set; `null` sets "no project". */
+    readonly projectId: string | null;
+}
+
 /**
  * What one headless system run reports back. The run's spend is read from the
  * ledger after the turn settles; `cost` is absent when no spend rows were
@@ -2158,6 +2170,15 @@ declare interface KayAppSessions {
     } | {
         readonly kind: "unavailable";
     }>;
+    /**
+     * Private API: only plugins Bonsai ships; refused for any other. Set the project of any stored
+     * sessions, each only while it still holds the project the caller last saw (a compare-and-set,
+     * so a person's own choice made meanwhile always wins). Answers one boolean per assignment, in
+     * order: `false` when the session is gone or its project changed. A written session's project
+     * folder and prompt block are refreshed. Checked against `sessions.assign-project`; a refused
+     * call rejects.
+     */
+    assignProject?(assignments: readonly KayAppSessionProjectAssignment[]): Promise<readonly boolean[]>;
     /**
      * Run one hidden headless system session through Bonsai's harness and resolve
      * with its final output - the sole sanctioned way for a `kay.app` plugin to

package/dist/kay-app.d.ts

@@ -1338,6 +1338,21 @@ declare class EncodeBuilder<Type extends TSchema, Encoded extends unknown, Decod
     Encode(callback: TEncodeCallback<Encoded, Decoded>): TCodec<Type, Decoded>;
 }
 
+export declare const EndpointContribution: z.ZodObject<{
+    localId: z.ZodString;
+    displayName: z.ZodOptional<z.ZodString>;
+    requestSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<authoringCommonSchemas.JsonValue, unknown, z.core.$ZodTypeInternals<authoringCommonSchemas.JsonValue, unknown>>>>;
+    responseSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<authoringCommonSchemas.JsonValue, unknown, z.core.$ZodTypeInternals<authoringCommonSchemas.JsonValue, unknown>>>>;
+    auth: z.ZodOptional<z.ZodObject<{
+        service: z.ZodString;
+        schemes: z.ZodArray<z.ZodString>;
+        purpose: z.ZodString;
+    }, z.core.$strict>>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+
+export declare type EndpointContribution = z.infer<typeof EndpointContribution>;
+
 declare interface EntryBase {
     id: string;
     parentId: string | null;
@@ -2911,11 +2926,49 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 0.52.0 adds plugin-owned operational facts through existing manifests and registrations.
  *
  * 0.52.1 adds owner-qualified page feed and endpoint references and their kay.ui claims.
+ *
+ * 0.53.0 adds declared working-content layouts, family-root authority, draft projection discovery
+ * and session-bound page references. Older customized Whiteboard copies must accept the plugin
+ * update before using these interfaces.
+ *
+ * 0.54.0 adds named UI host grants for shared configuration/auth/account reads, retained connection
+ * progress/dismissal and support. Built-in-only page capability scopes are removed; executable
+ * pages declare capabilities on apps[].
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.52.1";
+declare const KAY_PLUGIN_SDK_VERSION: "0.54.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
+/**
+ * One process the plugin asks the host to run.
+ *
+ * `argvClass` is required and is NOT decoration: it names the class of argument vector this
+ * invocation belongs to, and it must match a class the plugin declared alongside `command` in its
+ * manifest. Declaring a command alone would authorize `git log` and `git push --force` identically;
+ * the class is what a user can be shown and asked to consent to. The host judges the real `args`
+ * against the named class and refuses with `argv-outside-class` when they do not belong to it.
+ */
+declare interface KayAgentProcessRunRequest {
+    readonly command: string;
+    readonly argvClass: string;
+    readonly args: readonly string[];
+    /** Abort the run; the host kills the DIRECT child and rejects - a forked descendant may outlive it (#6153). */
+    readonly signal?: AbortSignal;
+}
+
+/**
+ * A finished run. `stdout`/`stderr` are decoded text, and the host CAPS them - a truncation flag is
+ * set rather than the output silently ending, so a plugin parsing the stream can tell "the command
+ * printed this" apart from "the command printed more than we kept".
+ */
+declare interface KayAgentProcessRunResult {
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly stdoutTruncated?: boolean;
+    readonly stderrTruncated?: boolean;
+}
+
 declare interface KayAgentWhiteboardCreateInput {
     readonly name: string;
     readonly title: string;
@@ -3475,6 +3528,16 @@ export declare type KayAppArtifactOutputFile = {
 };
 
 export declare interface KayAppArtifactOutputs extends Omit<KayAppKnowledgeSource, "watchRoots"> {
+    /**
+     * One page of canonical output URIs across every chat or, with `sessionId`,
+     * only that chat's outputs. A cursor continues the enumeration it came from.
+     */
+    enumerate(options: {
+        readonly cursor?: JsonValue;
+        readonly limit: number;
+        readonly signal: AbortSignal;
+        readonly sessionId?: string;
+    }): ReturnType<KayAppKnowledgeSource["enumerate"]>;
     subscribe(listener: (change: ArtifactOutputChange) => void): () => void;
     /**
      * The exact bytes of one canonical `output://<session>/<name>` file, at most `maxBytes`
@@ -3490,6 +3553,13 @@ export declare interface KayAppArtifactOutputs extends Omit<KayAppKnowledgeSourc
 export declare interface KayAppArtifacts {
     /** Activation-only request for the public artifacts.read {kind: output} capability. */
     outputs(): KayAppArtifactOutputs;
+    /**
+     * Private API: only plugins Bonsai ships; refused for any other. The absolute path of the file
+     * an address names as `sessionId`'s agent would see it (`output://`, `file://` and the other
+     * file-backed schemes), or `undefined` when it names no readable file. Checked against
+     * `artifacts.resolve-file`; a refused call rejects.
+     */
+    resolveFile?(sessionId: string, uri: string): Promise<string | undefined>;
 }
 
 /** A persisted assistant message, published without waiting for its subscribers. */
@@ -5194,6 +5264,13 @@ export declare interface KayAppPaths {
      * empty directory rather than an error.
      */
     readonly sessionsRoot?: string;
+    /**
+     * Absolute path to the folder holding the scratch working folders of chats started without a
+     * folder of their own (`<chatsRoot>/<id>`). Files written there belong to that one chat. Ask for
+     * this rather than deriving it: Desktop keeps it under the app's user-data root, not beside
+     * {@link sessionsRoot}. Absent when the host composed none.
+     */
+    readonly chatsRoot?: string;
     /**
      * Absolute path to Bonsai's local telemetry directory. The live telemetry lane itself is a
      * Postgres table (`telemetry.usage_events`), not anything under this path; it is never a
@@ -5333,6 +5410,11 @@ export declare interface KayAppPluginApi {
      * which blocks the daemon; see {@link KayAppRepos}.
      */
     readonly repos: KayAppRepos;
+    /**
+     * Private API: only plugins Bonsai ships; refused for any other. Runs a program the host bound
+     * for this plugin; see {@link KayAppProcess}. Absent when the host composed no program bindings.
+     */
+    readonly process?: KayAppProcess;
     /**
      * File I/O in user folders (stat, read, list, walk, realpath, write, mkdir, rename), run by the
      * host on its own worker threads under a deadline and answered as a typed result. Always present
@@ -5597,8 +5679,25 @@ export declare interface KayAppPollResult<Cursor extends JsonValue> {
     readonly summary?: string;
 }
 
+/**
+ * Private API: only plugins Bonsai ships; refused for any other. Run a program the host bound
+ * for this plugin, the way {@link import("../kay-agent/index.ts").KayAgentProcess} does for an
+ * agent tool: the plugin names a command and an argument class, the host owns the executable,
+ * which arguments belong to the class, the time limit, the output cap, the working directory and
+ * the environment. Each run is checked against `process.run` and then the exact
+ * `process.spawn {command, argvClass}` claim; a refusal rejects with `KayAgentCapabilityError`,
+ * a timeout resolves with exit code 124.
+ */
+export declare interface KayAppProcess {
+    run(request: KayAppProcessRunRequest): Promise<KayAppProcessRunResult>;
+}
+
 export declare type KayAppProcessingSpeed = "standard" | "fast";
 
+export declare type KayAppProcessRunRequest = KayAgentProcessRunRequest;
+
+export declare type KayAppProcessRunResult = KayAgentProcessRunResult;
+
 /**
  * A gap reason on the run-detail wire: something about the run's work the
  * daemon could not establish from its session transcripts. The vocabulary is
@@ -6261,6 +6360,18 @@ export declare type KayAppSessionPageItem = (Omit<Extract<TranscriptPageItem, {
     readonly unreadable: unknown;
 }>;
 
+/** One write for {@link KayAppSessions.assignProject}. */
+export declare interface KayAppSessionProjectAssignment {
+    readonly sessionId: string;
+    /**
+     * The project the session must still hold for the write to land: a project id, `null` for "no
+     * project" chosen on purpose, or absent for a session whose project was never decided.
+     */
+    readonly expectedProjectId?: string | null;
+    /** The project to set; `null` sets "no project". */
+    readonly projectId: string | null;
+}
+
 export declare type KayAppSessionProvenanceRecord = SessionProvenanceRecord;
 
 export declare type KayAppSessionRelationship = SessionRelationship;
@@ -6601,6 +6712,15 @@ export declare interface KayAppSessions {
     } | {
         readonly kind: "unavailable";
     }>;
+    /**
+     * Private API: only plugins Bonsai ships; refused for any other. Set the project of any stored
+     * sessions, each only while it still holds the project the caller last saw (a compare-and-set,
+     * so a person's own choice made meanwhile always wins). Answers one boolean per assignment, in
+     * order: `false` when the session is gone or its project changed. A written session's project
+     * folder and prompt block are refreshed. Checked against `sessions.assign-project`; a refused
+     * call rejects.
+     */
+    assignProject?(assignments: readonly KayAppSessionProjectAssignment[]): Promise<readonly boolean[]>;
     /**
      * Run one hidden headless system session through Bonsai's harness and resolve
      * with its final output - the sole sanctioned way for a `kay.app` plugin to
@@ -7688,6 +7808,12 @@ export declare interface KayAppSystemPromptFragment {
      * KayAppSystemPromptRegistration.refresh}.
      */
     readonly maxAgeMs?: number;
+    /**
+     * For text about the chat's project. A forked chat starts with its parent's texts unchanged, so
+     * the model's prompt cache still matches; when set, a fork whose project is then chosen drops the
+     * parent's copy of this text and renders its own. Absent: a fork keeps the parent's text.
+     */
+    readonly forksFollowProject?: boolean;
     /** The text, or `undefined` for none. A rejection leaves the text out and is logged. */
     render(request: KayAppSystemPromptRenderRequest): Promise<string | undefined>;
 }
@@ -9008,6 +9134,90 @@ declare type MatchTrueLike = (inferred: TProperties) => unknown;
 /** The most labels a recorded choice question may offer, and so the most one filter names. */
 export declare const MAX_CHOICE_LABELS = 64;
 
+/** The connection state published for one configured MCP server. */
+export declare type McpServerConnectionState = "disconnected" | "connecting" | "connected" | "needs-auth" | "failed";
+
+/** A server mark already resolved into a data URI by its publisher. */
+export declare interface McpServerIcon {
+    /** A `data:` URI. Consumers may render it directly in an `<img src>`. */
+    readonly src: string;
+    /**
+     * Where the mark came from, because the two are not equally trustworthy.
+     *
+     * `declared` is the server's own `serverInfo.icons` (MCP spec 2025-11-25, SEP-973): evidence.
+     * `favicon` is derived from an HTTP server's origin: still evidence, one step removed.
+     * A name match against Bonsai's brand table is neither, and deliberately does not appear here -
+     * that guess lives in the renderer's existing `BrandIcon` fallback, below both of these.
+     */
+    readonly source: "declared" | "favicon";
+    /** The theme the server nominated this variant for, when it declared more than one. */
+    readonly theme?: "light" | "dark";
+}
+
+/** One keyed change to the MCP inventory. */
+export declare type McpServerInventoryChange = {
+    readonly kind: "upsert";
+    readonly server: McpServerRecord;
+} | {
+    readonly kind: "remove";
+    readonly name: string;
+};
+
+/** One configured MCP server in the app-facing inventory. */
+export declare interface McpServerRecord {
+    /** The config key, and the id the `mcp.<name>` auth service keys on. */
+    readonly name: string;
+    /**
+     * The auth service that connects this server, when it has one: `mcp.<name>` for a plugins.mcp
+     * server, the shipping plugin's own service for a vendored one. The Plugins page joins a
+     * connection row to its server on THIS id - never by deriving a name from the service id,
+     * which only ever fit the user-config namespace and left every vendored server toolless.
+     */
+    readonly authServiceId?: string;
+    /** The server's own `serverInfo.title`, when it sent one. Display prefers it over `name`. */
+    readonly title?: string;
+    readonly transport: "stdio" | "http";
+    /** What the server launches or connects to: joined command for stdio, url for http. */
+    readonly target: string;
+    /** The config-level switch (`enabled: false` in `plugins.mcp`), not the connection. */
+    readonly enabled: boolean;
+    readonly state: McpServerConnectionState;
+    /** Live when connected, else from the persisted metadata cache. Zero is ordinary. */
+    readonly toolCount: number;
+    /**
+     * What this server offers, for a surface that lists it. Live when connected, else from the
+     * persisted metadata cache, so a server names its tools before it has connected this session
+     * and after a restart.
+     *
+     * NAMES AND DESCRIPTIONS ONLY. The JSON-Schema input declarations stay out: they are by far the
+     * biggest part of a tool list, nothing on this surface renders them, and this snapshot is
+     * re-encoded whenever any server changes state. A surface that genuinely needs a schema is
+     * asking a different question and should ask the agent bridge, which owns tool detail.
+     *
+     * Bounded by the publisher's tool-list limit - {@link toolCount} remains the true count, so a
+     * server past the bound still reports honestly even though the list is clipped.
+     */
+    readonly tools?: readonly McpServerToolSummary[];
+    readonly icon?: McpServerIcon;
+    /**
+     * Why a `failed` server failed, in one human-legible line, when the host knows. A broken row can
+     * then say what went wrong instead of only offering Retry.
+     */
+    readonly failure?: string;
+}
+
+/** A complete MCP inventory snapshot. */
+export declare interface McpServersSnapshot {
+    readonly servers: readonly McpServerRecord[];
+}
+
+/** A tool name and optional description for inventory presentation. */
+export declare interface McpServerToolSummary {
+    readonly name: string;
+    /** The server's own one-line description, trimmed to the publisher's summary limit. */
+    readonly description?: string;
+}
+
 export declare namespace Memory {
     export {
         Assign,
@@ -10252,6 +10462,33 @@ export declare interface PreparedAccessApproval {
     readonly binding?: unknown;
 }
 
+export declare const ProjectDirectory: z.ZodObject<{
+    id: z.ZodString;
+    path: z.ZodString;
+    defaultCwd: z.ZodString;
+    ancestorIds: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+
+export declare type ProjectDirectory = z.infer<typeof ProjectDirectory>;
+
+export declare const ProjectDirectoryRequest: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strict>;
+
+export declare type ProjectDirectoryRequest = z.infer<typeof ProjectDirectoryRequest>;
+
+/** `project` is null when no project has the requested id. */
+export declare const ProjectDirectoryResponse: z.ZodObject<{
+    project: z.ZodNullable<z.ZodObject<{
+        id: z.ZodString;
+        path: z.ZodString;
+        defaultCwd: z.ZodString;
+        ancestorIds: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+
+export declare type ProjectDirectoryResponse = z.infer<typeof ProjectDirectoryResponse>;
+
 declare const Properties: (input: string) => [unknown, string] | [];
 
 declare function PropertiesMapping(input: [unknown, unknown, unknown]): unknown;
@@ -17301,8 +17538,8 @@ declare const WhiteboardEntryInfo: z.ZodObject<{
         authorSessionId: z.ZodNullable<z.ZodString>;
     }, z.core.$strict>>;
     state: z.ZodEnum<{
-        unavailable: "unavailable";
         available: "available";
+        unavailable: "unavailable";
         "unsupported-version": "unsupported-version";
         invalid: "invalid";
     }>;
@@ -17323,8 +17560,8 @@ declare const WhiteboardEntryInspection: z.ZodObject<{
         authorSessionId: z.ZodNullable<z.ZodString>;
     }, z.core.$strict>>;
     state: z.ZodEnum<{
-        unavailable: "unavailable";
         available: "available";
+        unavailable: "unavailable";
         "unsupported-version": "unsupported-version";
         invalid: "invalid";
     }>;
@@ -17375,6 +17612,9 @@ export declare const WhiteboardTypeInfo: z.ZodObject<{
     displayName: z.ZodString;
     schemaVersion: z.ZodNumber;
     available: z.ZodBoolean;
+    reference: z.ZodOptional<z.ZodObject<{
+        uriTemplate: z.ZodString;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 
 export declare type WhiteboardTypeInfo = Readonly<z.infer<typeof WhiteboardTypeInfo>>;