@yaklabs-ai/plugin-sdk 0.53.0 → 0.54.0

package/README.md

@@ -13,7 +13,7 @@ it under the name your plugin code actually imports:
 ```json
 {
   "dependencies": {
-    "@bonsai/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.53.0"
+    "@bonsai/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.54.0"
   }
 }
 ```
@@ -62,7 +62,7 @@ Every tool the entrypoint registers is declared in the manifest too:
   "description": "Greets people by name.",
   "version": "0.1.0",
   "namespace": "widgets",
-  "compatibility": { "sdk": "^0.53.0" },
+  "compatibility": { "sdk": "^0.54.0" },
   "targets": {
     "kay": {
       "agent": {
@@ -134,24 +134,26 @@ naming both versions, instead of loading it and finding no `activate`.
 
 ## Entrypoints
 
-| Import                                  | What it gives you                                                                        |
-| --------------------------------------- | ---------------------------------------------------------------------------------------- |
-| `@bonsai/plugin-sdk/kay-agent`          | Tools, URI modules, search providers, auth — the per-session agent surface               |
-| `@bonsai/plugin-sdk/kay-app`            | App-lifetime surface: storage, endpoints, app-scoped URI modules                         |
-| `@bonsai/plugin-sdk/uri`                | Sessionless resource caller types, revision digest and unavailable fallback, from 0.49.0 |
-| `@bonsai/plugin-sdk/endpoints`          | Sessionless cross-plugin endpoint caller and outcome types, from 0.50.0                  |
-| `@bonsai/plugin-sdk/kay-agent/testing`  | `invokeToolForTest`, `fauxAuthContext` — for your own `node --test` runs                 |
-| `@bonsai/plugin-sdk/disclosure`         | The conformance audit Bonsai gates your plugin with — run it before you ship             |
-| `@bonsai/plugin-sdk/time`               | `Temporal` (Bonsai's own instance) and the time-zone helpers, from 0.13.6                |
-| `@bonsai/plugin-sdk/transcript`         | The active-branch walk; the turn walk and run records from 0.13.6                        |
-| `@bonsai/plugin-sdk/transcript-review`  | The review fold: a session's spans, tool-call attempts and records, from 0.13.7          |
-| `@bonsai/plugin-sdk/agent-conversation` | How a session's agent-to-agent traffic groups into conversations, from 0.13.7            |
-| `@bonsai/plugin-sdk/app-data`           | The app-data size caps, on an entry with no other import, from 0.13.7                    |
-| `@bonsai/plugin-sdk/vendored-mcp`       | The kit for a plugin built on a vendor's hosted MCP server, from 0.13.7                  |
-| `@bonsai/plugin-sdk/system-one`         | The types and error class for `api.systemOne` / `app.systemOne`, from 0.13.8             |
-| `@bonsai/plugin-sdk/zod`                | `z` (the host's in the daemon), on an entry with no other import, from 0.13.9            |
-
-A plugin that imports these subpaths declares the current supported SDK range (`^0.53.0`).
+| Import                                  | What it gives you                                                                                             |
+| --------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `@bonsai/plugin-sdk/kay-agent`          | Tools, URI modules, search providers, auth — the per-session agent surface                                    |
+| `@bonsai/plugin-sdk/kay-app`            | App-lifetime surface: storage, endpoints, app-scoped URI modules                                              |
+| `@bonsai/plugin-sdk/uri`                | Sessionless resource caller types, revision digest and unavailable fallback, from 0.49.0                      |
+| `@bonsai/plugin-sdk/endpoints`          | Sessionless cross-plugin endpoint caller and outcome types, from 0.50.0; `projectDirectories` endpoint shapes |
+| `@bonsai/plugin-sdk/kay-agent/testing`  | `invokeToolForTest`, `fauxAuthContext` — for your own `node --test` runs                                      |
+| `@bonsai/plugin-sdk/disclosure`         | The conformance audit Bonsai gates your plugin with — run it before you ship                                  |
+| `@bonsai/plugin-sdk/time`               | `Temporal` (Bonsai's own instance) and the time-zone helpers, from 0.13.6                                     |
+| `@bonsai/plugin-sdk/transcript`         | Active-branch and turn walks, message origin, preceding messages, and skill evidence folds                    |
+| `@bonsai/plugin-sdk/transcript-review`  | The review fold: a session's spans, tool-call attempts and records, from 0.13.7                               |
+| `@bonsai/plugin-sdk/agent-conversation` | How a session's agent-to-agent traffic groups into conversations, from 0.13.7                                 |
+| `@bonsai/plugin-sdk/text-diff`          | Word-level draft comparison and Unicode-safe text clipping                                                    |
+| `@bonsai/plugin-sdk/fs`                 | File I/O, shared keyed work ordering and committed-change notices                                             |
+| `@bonsai/plugin-sdk/app-data`           | The app-data size caps, on an entry with no other import, from 0.13.7                                         |
+| `@bonsai/plugin-sdk/vendored-mcp`       | The kit for a plugin built on a vendor's hosted MCP server, from 0.13.7                                       |
+| `@bonsai/plugin-sdk/system-one`         | The types and error class for `api.systemOne` / `app.systemOne`, from 0.13.8                                  |
+| `@bonsai/plugin-sdk/zod`                | `z` (the host's in the daemon), on an entry with no other import, from 0.13.9                                 |
+
+A plugin that imports these subpaths declares the current supported SDK range (`^0.54.0`).
 The rows record when each subpath appeared, not retained runtime compatibility. `vendored-mcp` builds the plugin's URI module (its link cards and help); hosting the
 vendor's MCP server itself is a separate host decision: Bonsai hosts it once a person approves
 the plugin's `mcp.host-server` grant for that server's name and URL. A server that needs an OAuth
@@ -159,7 +161,7 @@ sign-in names one of the plugin's auth services in `authService`; that service m
 one `delegated` scheme, which Bonsai uses to sign the person in to the server. Bonsai declares that
 scheme at runtime; the plugin's code must not declare it again. From 0.16.2 a plugin's code can also
 call the server's tools through `api.vendoredMcp.port(<server>)`, typed by this subpath's
-`VendoredMcpPort` and `VendoredMcpOutcome` (declare `^0.53.0`).
+`VendoredMcpPort` and `VendoredMcpOutcome` (declare `^0.54.0`).
 
 From 0.13.10 the manifest schema carries two facts Bonsai reads for its own plugins only; another
 plugin's are ignored, with a load diagnostic. An `external-cli` auth scheme's `cli` says how Bonsai
@@ -241,7 +243,7 @@ Provider schemas remain authoritative; declaring a dependency grants no authorit
 through `app.uri`, parse returned Markdown in the consuming plugin, and retain the read's
 revision (or `contentDigest` from `/uri`) for edits. The old `memory.read` and `memory.write`
 grants do not authorize the replacement scheme-and-verb calls. Contracts before 0.49.0 are
-refused; migrate and declare `^0.53.0`. The current host also serves the 0.49.0 resource contract.
+refused; migrate and declare `^0.54.0`. The current host also serves the 0.49.0 resource contract.
 
 ## What this package is, and is not, at runtime
 

package/THIRD-PARTY-INVENTORY.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "package": "@yaklabs-ai/plugin-sdk",
-  "version": "0.53.0",
+  "version": "0.54.0",
   "target": "npm",
   "firstPartyLicense": "MIT",
   "bundled": [

package/dist/disclosure.d.ts

@@ -2466,8 +2466,12 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 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.53.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.54.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 

package/dist/disclosure.js

@@ -737,6 +737,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 {

package/dist/endpoints.d.ts

@@ -1,3 +1,5 @@
+import { z } from 'zod';
+
 export declare function createUnavailablePluginEndpointCaller(message: string): PluginEndpointCaller;
 
 /** Sessionless JSON calls to another plugin's declared, publicly reachable endpoint. */
@@ -22,4 +24,31 @@ export declare type PluginEndpointOutcome = {
     readonly message: string;
 };
 
+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>;
+
 export { }

package/dist/endpoints.js

@@ -1,3 +1,28 @@
+// packages/plugin-protocol/dist/project-directories.js
+import { z } from "zod";
+var PluginProjectDirectories = z.strictObject({
+  /** An endpoint this plugin's app target declares; called with a {@link ProjectDirectoryRequest}. */
+  endpoint: z.string().min(1),
+  /** A scheme this plugin's URI modules serve; a project is addressed as `<scheme>://<id>`. */
+  scheme: z.string().min(1)
+});
+var ProjectDirectoryRequest = z.strictObject({
+  /** The project's stable id. */
+  id: z.string().min(1)
+});
+var ProjectDirectory = z.strictObject({
+  id: z.string().min(1),
+  /** Absolute path of the project's folder. */
+  path: z.string().min(1),
+  /** Absolute path a new session in this project starts in. */
+  defaultCwd: z.string().min(1),
+  /** Ancestor project ids, root first. */
+  ancestorIds: z.array(z.string().min(1))
+});
+var ProjectDirectoryResponse = z.strictObject({
+  project: ProjectDirectory.nullable()
+});
+
 // packages/plugin-sdk/dist/endpoints.js
 function createUnavailablePluginEndpointCaller(message) {
   return {
@@ -5,5 +30,8 @@ function createUnavailablePluginEndpointCaller(message) {
   };
 }
 export {
+  ProjectDirectory,
+  ProjectDirectoryRequest,
+  ProjectDirectoryResponse,
   createUnavailablePluginEndpointCaller
 };

package/dist/fs.d.ts

@@ -10,6 +10,9 @@ export declare const chmod: typeof nodeFsp.chmod;
 
 export declare const chown: typeof nodeFsp.chown;
 
+/** Receives the committed paths under the folder it subscribed to. */
+export declare type CommittedChangeListener = (paths: readonly string[]) => void;
+
 export { constants }
 
 export declare const copyFile: typeof nodeFsp.copyFile;
@@ -59,6 +62,21 @@ declare const _default: {
 };
 export default _default;
 
+/**
+ * Report paths whose writes have landed: created, replaced, moved or removed. A path is a source
+ * that changed, never a claim that anything is gone. Never throws: a subscriber's failure goes
+ * to its own `warn`, and a failing `warn` is ignored, because a report cannot undo the write.
+ */
+export declare function emitCommittedChanges(paths: readonly string[]): void;
+
+/**
+ * Run `work` after every task queued earlier under `key` in this process, and
+ * before every task queued later. Nothing touches the filesystem: `key` is an
+ * opaque string, and there is no cross-process lock. Use it when this process
+ * is the only writer and only same-process ordering matters.
+ */
+export declare function enqueueInProcess<T>(key: string, work: () => Promise<T>): Promise<T>;
+
 export { FileHandle }
 
 export declare const glob: typeof nodeFsp.glob;
@@ -124,6 +142,14 @@ export declare const stat: typeof nodeFsp.stat;
 
 export declare const statfs: typeof nodeFsp.statfs;
 
+/**
+ * Hear about writes any plugin in this process reports with {@link emitCommittedChanges} under
+ * `folder`. `listener` receives the absolute, deduplicated paths inside `folder` (the folder
+ * itself included), synchronously from the emit. A throw from `listener` goes to `warn`. Returns
+ * the function that stops delivery.
+ */
+export declare function subscribeCommittedChanges(folder: string, listener: CommittedChangeListener, warn: (error: unknown) => void): () => void;
+
 export declare const symlink: typeof nodeFsp.symlink;
 
 export declare const truncate: typeof nodeFsp.truncate;

package/dist/fs.js

@@ -2,7 +2,7 @@
 import { Buffer as Buffer3 } from "node:buffer";
 import { constants } from "node:fs";
 import * as nodeFsp from "node:fs/promises";
-import { basename, dirname, join, resolve as resolve2 } from "node:path";
+import { basename, dirname, join, resolve as resolve3 } from "node:path";
 
 // packages/plugin-sdk/dist/fs/handle.js
 import { Buffer as Buffer2 } from "node:buffer";
@@ -611,6 +611,50 @@ function currentKayFsBackend() {
   return globalThis[KAY_FS_BACKEND];
 }
 
+// packages/plugin-sdk/dist/fs/mutation-queue.js
+var mutationQueues = /* @__PURE__ */ new Map();
+async function enqueueInProcess(key, work) {
+  const previous = mutationQueues.get(key) ?? Promise.resolve();
+  const next = previous.catch(() => void 0).then(work);
+  mutationQueues.set(key, next);
+  try {
+    return await next;
+  } finally {
+    if (mutationQueues.get(key) === next)
+      mutationQueues.delete(key);
+  }
+}
+
+// packages/plugin-sdk/dist/fs/committed-changes.js
+import { isAbsolute, relative, resolve as resolve2 } from "node:path";
+var subscriptions = /* @__PURE__ */ new Set();
+function subscribeCommittedChanges(folder, listener, warn) {
+  const subscription = { folder: resolve2(folder), listener, warn };
+  subscriptions.add(subscription);
+  return () => {
+    subscriptions.delete(subscription);
+  };
+}
+function emitCommittedChanges(paths) {
+  const resolved = [...new Set(paths.map((path) => resolve2(path)))];
+  for (const subscription of subscriptions) {
+    const owned = resolved.filter((path) => {
+      const fromFolder = relative(subscription.folder, path);
+      return fromFolder === "" || !fromFolder.startsWith("..") && !isAbsolute(fromFolder);
+    });
+    if (owned.length === 0)
+      continue;
+    try {
+      subscription.listener(owned);
+    } catch (error) {
+      try {
+        subscription.warn(error);
+      } catch {
+      }
+    }
+  }
+}
+
 // packages/plugin-sdk/dist/fs/index.js
 function route(node, host) {
   return ((...args) => {
@@ -766,7 +810,7 @@ var glob2 = route(() => nodeFsp.glob, (backend, pattern, options) => {
       pattern,
       wire === void 0 ? {} : { ...wire, ...cwd === void 0 ? {} : { cwd: wirePath(cwd) } }
     ], {
-      paths: [cwd === void 0 ? resolve2(".") : keyPath(cwd)],
+      paths: [cwd === void 0 ? resolve3(".") : keyPath(cwd)],
       timeoutMs: timeoutOf(options),
       walksTree: true
     });
@@ -864,6 +908,8 @@ export {
   copyFile2 as copyFile,
   cp2 as cp,
   index_default as default,
+  emitCommittedChanges,
+  enqueueInProcess,
   glob2 as glob,
   lchmod2 as lchmod,
   lchown2 as lchown,
@@ -884,6 +930,7 @@ export {
   rmdir2 as rmdir,
   stat2 as stat,
   statfs2 as statfs,
+  subscribeCommittedChanges,
   symlink2 as symlink,
   truncate2 as truncate,
   unlink2 as unlink,

package/dist/kay-agent-testing.d.ts

@@ -2520,8 +2520,12 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 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.53.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.54.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -4959,6 +4963,10 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
         usage: z.ZodString;
         endpointId: z.ZodString;
     }, z.core.$strict>>>;
+    projectDirectories: z.ZodOptional<z.ZodObject<{
+        scheme: z.ZodString;
+        endpointId: z.ZodString;
+    }, z.core.$strict>>;
     authServices: z.ZodArray<z.ZodObject<{
         localId: z.ZodString;
         globalId: z.ZodString;
@@ -5001,9 +5009,11 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
             globalId: z.ZodString;
             kind: z.ZodLiteral<"oauth2">;
             scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            connectScopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
             authorizationUrl: z.ZodURL;
             tokenUrl: z.ZodURL;
             extraAuthorizeParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            extraAuthorizeParamsWhenAccountHeld: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
             displayName: z.ZodOptional<z.ZodString>;
             agentHint: z.ZodOptional<z.ZodString>;
             summary: z.ZodOptional<z.ZodString>;
@@ -5032,9 +5042,11 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
             globalId: z.ZodString;
             kind: z.ZodLiteral<"oauth2">;
             scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            connectScopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
             authorizationUrl: z.ZodURL;
             tokenUrl: z.ZodURL;
             extraAuthorizeParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            extraAuthorizeParamsWhenAccountHeld: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
             displayName: z.ZodOptional<z.ZodString>;
             agentHint: z.ZodOptional<z.ZodString>;
             summary: z.ZodOptional<z.ZodString>;
@@ -5668,6 +5680,7 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
             skills: z.ZodExactOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strict>>;
         localId: z.ZodString;
+        adapterId: z.ZodOptional<z.ZodString>;
         globalId: z.ZodString;
         schemes: z.ZodArray<z.ZodString>;
         displayName: z.ZodOptional<z.ZodString>;
@@ -6140,6 +6153,13 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
             }, z.core.$strict>]>>>;
             host: z.ZodOptional<z.ZodArray<z.ZodEnum<{
                 "navigation.open-session": "navigation.open-session";
+                "navigation.open-external": "navigation.open-external";
+                "configuration.read": "configuration.read";
+                "auth-services.read": "auth-services.read";
+                "connect-flows.read": "connect-flows.read";
+                "connect-flows.dismiss": "connect-flows.dismiss";
+                "support.report": "support.report";
+                "navigation.open-page": "navigation.open-page";
                 "sessions.create": "sessions.create";
                 "models.complete": "models.complete";
                 "artifacts.read": "artifacts.read";
@@ -6147,6 +6167,10 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
                 "markdown.document-view": "markdown.document-view";
                 "references.open": "references.open";
                 "billing.read": "billing.read";
+                "account.read": "account.read";
+                "plugins.read": "plugins.read";
+                "plugins.settings": "plugins.settings";
+                "permissions.manage": "permissions.manage";
                 "automations.read": "automations.read";
                 "automations.run": "automations.run";
                 "shared-artifacts.read": "shared-artifacts.read";

package/dist/kay-agent.d.ts

@@ -2799,8 +2799,12 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 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.53.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.54.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -5134,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">;
@@ -5678,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;

package/dist/kay-agent.js

@@ -999,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 {
@@ -1171,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",
@@ -1181,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;
@@ -1331,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 {
@@ -1507,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) {
@@ -1517,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) {
@@ -1717,6 +1742,9 @@ export {
   OSASCRIPT_ENVELOPE_JXA,
   OSASCRIPT_TIMEOUT_MS,
   PluginApiError,
+  ProjectDirectory,
+  ProjectDirectoryRequest,
+  ProjectDirectoryResponse,
   SearchProviderError,
   SecureTransportError,
   URI_TEXT_EDIT_SHAPE_SUMMARY,
@@ -1787,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