@yaklabs-ai/plugin-sdk 0.54.1 → 0.55.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.54.1"
+    "@bonsai/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.55.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.54.1" },
+  "compatibility": { "sdk": "^0.55.0" },
   "targets": {
     "kay": {
       "agent": {
@@ -153,7 +153,7 @@ naming both versions, instead of loading it and finding no `activate`.
 | `@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.1`).
+A plugin that imports these subpaths declares the current supported SDK range (`^0.55.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
@@ -161,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.54.1`).
+`VendoredMcpPort` and `VendoredMcpOutcome` (declare `^0.55.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
@@ -243,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.54.1`. The current host also serves the 0.49.0 resource contract.
+refused; migrate and declare `^0.55.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.54.1",
+  "version": "0.55.0",
   "target": "npm",
   "firstPartyLicense": "MIT",
   "bundled": [

package/dist/canonical-transcript.d.ts

@@ -3873,14 +3873,20 @@ declare interface RunFailureObservedSessionEvent {
     readonly failure?: RunFailureOccurrence;
 }
 
-declare type RunFailureOccurrence = FailureOccurrence<RunFailureCause>;
+/**
+ * One run failure record. `Code` and `Domain` default to `string`, as every
+ * reader takes them; a producer passes `RunFailureCode` and
+ * `RunFailureDomain` on the record it makes, so an undeclared code fails to
+ * compile.
+ */
+declare type RunFailureOccurrence<Code extends string = string, Domain extends string = string> = FailureOccurrence<RunFailureCause, Code, Domain>;
 
 declare type RunFailureReason = (typeof RUN_FAILURE_REASONS)[number];
 
 declare type RunFailureRecord = z.infer<typeof runFailureRecordSchema>;
 
 declare const runFailureRecordSchema: z.ZodObject<{
-    failure: z.ZodType<RunFailureOccurrence, unknown, z.core.$ZodTypeInternals<RunFailureOccurrence, unknown>>;
+    failure: z.ZodType<RunFailureOccurrence<string, string>, unknown, z.core.$ZodTypeInternals<RunFailureOccurrence<string, string>, unknown>>;
     errorText: z.ZodString;
 }, z.core.$strict>;
 
@@ -3898,8 +3904,8 @@ declare const runRecoveryOutcomeSchema: z.ZodObject<{
         id: z.ZodString;
     }, z.core.$strict>;
     action: z.ZodEnum<{
-        compact: "compact";
         retry: "retry";
+        compact: "compact";
         switch_model: "switch_model";
         switch_account: "switch_account";
     }>;

package/dist/canonical-transcript.js

@@ -221,6 +221,26 @@ var coverageSchema = z2.strictObject({
   knownOmittedCount: z2.number().int().nonnegative().optional()
 }).refine((value) => value.status !== "complete" || !value.knownOmittedCount);
 
+// packages/herd-transcript/dist/is-object.js
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// packages/herd-transcript/dist/subscription-failure.js
+var SUBSCRIPTION_FAILURE_KEYS = [
+  "subscription.expired",
+  "subscription.access-denied",
+  "subscription.client-refused",
+  "subscription.scope-refused",
+  "subscription.renewal-failed",
+  "subscription.unreachable",
+  "subscription.incomplete",
+  "subscription.temporary",
+  // Picked by a screen that knows a renewal failed but holds no record.
+  "subscription.no-record",
+  "subscription.unclassified"
+];
+
 // packages/herd-transcript/dist/run-failure.js
 var RUN_FAILURE_DIAGNOSTIC_TYPE = "herd.run.failure";
 var RUN_FAILURE_CUSTOM_TYPE = "run_failure";
@@ -243,8 +263,27 @@ var runFailureCauseSchema = z3.strictObject({
   authSource: z3.enum(["oauth", "api-key"]).optional(),
   credentialRef: z3.string().optional()
 });
+var RUN_FAILURE_DOMAINS = ["model", "runtime"];
+var RUN_FAILURE_ORGANIZATION_CODES = [
+  "model.organization_unavailable.changed",
+  "model.organization_unavailable.unreachable",
+  "model.organization_unavailable.connecting",
+  "model.organization_unavailable.not_ready"
+];
+var RUN_FAILURE_SIGN_IN_REASONS = [
+  "auth",
+  "network",
+  "server_error"
+];
+var RUN_FAILURE_CODES = [
+  ...RUN_FAILURE_REASONS.map((reason) => `model.${reason}`),
+  "runtime.interrupted",
+  "runtime.final_output_missing",
+  ...RUN_FAILURE_ORGANIZATION_CODES,
+  ...RUN_FAILURE_SIGN_IN_REASONS.flatMap((reason) => SUBSCRIPTION_FAILURE_KEYS.map((key) => `model.${reason}.${key}`))
+];
 var runFailureSchema = failureSchema(runFailureCauseSchema).extend({
-  domain: z3.enum(["model", "runtime"])
+  domain: z3.enum(RUN_FAILURE_DOMAINS)
 });
 var runFailureRecordSchema = z3.strictObject({
   failure: runFailureSchema.refine((failure) => readFailure(runFailureSchema, failure).status === "valid", "invalid or oversized model failure occurrence"),
@@ -631,13 +670,6 @@ function parsePresentationAnchor(value) {
 
 // packages/herd-transcript/dist/tool-call-failure.js
 import { z as z5 } from "zod";
-
-// packages/herd-transcript/dist/is-object.js
-function isObject(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-// packages/herd-transcript/dist/tool-call-failure.js
 var TOOL_CALL_FAILURE_DETAILS_KEY = "toolCallFailure";
 var TOOL_CALL_FAILURE_DOMAIN = "tool-call";
 var TOOL_CALL_FAILURE_CATEGORIES = [

package/dist/disclosure.d.ts

@@ -2668,8 +2668,16 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  *
  * 0.54.1 adds manifest-declared plugin workers on both backend targets and exposes the canonical
  * transcript placement and answer-stretch rules through the SDK.
+ *
+ * 0.54.2 lets a signal list the files that came with it (epic #15668). `PluginSignal` gains an
+ * optional `attachments`: each file's name, media type, size and the address its bytes are read
+ * from, never the bytes. Gmail lists a mail's attachments there, so Flows can file them. Additive:
+ * a plugin that publishes attachments declares ^0.54.2.
+ *
+ * 0.55.0 carries managed MCP calls over resource writes in both daemon and plugin-host code.
+ * Existing agent and background MCP call shapes remain supported.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.54.1";
+declare const KAY_PLUGIN_SDK_VERSION: "0.55.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -3127,13 +3135,8 @@ declare interface KayAgentVendoredMcp {
      * The port to `server`, a name this plugin declares in its `kay.app` target's
      * `contributes.mcpServers`. Throws when the plugin declares no server of that name. A declared
      * server that Bonsai does not host for this plugin still returns a port; each call then answers
-     * `unknown-server`. Its message names the plugin that holds the name, or else lists the possible
-     * reasons (no approved `mcp.host-server` grant, a sign-in the server cannot use, or a name that
-     * a plugin Bonsai ships or another installed plugin also claims) and points at the plugin's load
-     * diagnostic.
-     *
-     * A port reaches this plugin's own server only. To use another plugin's data, declare that
-     * plugin in the manifest's `dependencies.plugins`; a later SDK surface reaches it.
+     * `unknown-server`. Each invocation uses the resource caller's exact `kay.agent` `uri.call`
+     * grant for `mcp` / `write`; MCP checks the host-stamped caller against server ownership.
      */
     port<TTool extends string = string>(server: string): VendoredMcpPort<TTool>;
 }
@@ -10634,7 +10637,7 @@ declare interface Usage {
 /**
  * ---
  * responsibility: The one interface through which a vendored-MCP plugin's code calls a tool on its
- *   own vendored MCP server, so every read-through plugin and the daemon that implements the port
+ *   own vendored MCP server, so every read-through plugin and the SDK that implements the port
  *   agree on the same shape by construction.
  * owns:
  *   - {@link VendoredMcpPort} - what a plugin's URI module and tools call.
@@ -10642,8 +10645,8 @@ declare interface Usage {
  *     must surface to the agent rather than swallow.
  * does_not_own:
  *   - The implementation. A plugin never dials MCP itself: it takes the port from
- *     `api.vendoredMcp.port(server)` (`@bonsai/plugin-sdk/kay-agent`), which the daemon binds to the
- *     plugin's own hosted server over its MCP host. Plugin source stays host-free, and a plugin
+ *     `api.vendoredMcp.port(server)` (`@bonsai/plugin-sdk/kay-agent`), which the SDK binds through
+ *     resource calls to the plugin's own hosted server. Plugin source stays host-free, and a plugin
  *     under test substitutes a fake port.
  *   - Which tool names exist. `TTool` is the plugin's own union of the vendor tools it calls; the
  *     port is generic so a typo in a tool name fails typecheck inside the plugin.
@@ -10679,8 +10682,8 @@ declare type VendoredMcpOutcome =
 
 /**
  * One vendored MCP server, as the plugin that declares it calls it. `invoke` calls any tool the
- * server has, whether it reads or writes. The port checks no permission of its own: a call is as
- * permitted as the plugin tool or URI verb that makes it.
+ * server has, whether it reads or writes. The resource caller checks the target's exact
+ * `uri.call` grant, and MCP checks the host-stamped caller against server ownership.
  */
 declare interface VendoredMcpPort<TTool extends string = string> {
     invoke(input: {

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

@@ -2722,8 +2722,16 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  *
  * 0.54.1 adds manifest-declared plugin workers on both backend targets and exposes the canonical
  * transcript placement and answer-stretch rules through the SDK.
+ *
+ * 0.54.2 lets a signal list the files that came with it (epic #15668). `PluginSignal` gains an
+ * optional `attachments`: each file's name, media type, size and the address its bytes are read
+ * from, never the bytes. Gmail lists a mail's attachments there, so Flows can file them. Additive:
+ * a plugin that publishes attachments declares ^0.54.2.
+ *
+ * 0.55.0 carries managed MCP calls over resource writes in both daemon and plugin-host code.
+ * Existing agent and background MCP call shapes remain supported.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.54.1";
+declare const KAY_PLUGIN_SDK_VERSION: "0.55.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -3178,13 +3186,8 @@ declare interface KayAgentVendoredMcp {
      * The port to `server`, a name this plugin declares in its `kay.app` target's
      * `contributes.mcpServers`. Throws when the plugin declares no server of that name. A declared
      * server that Bonsai does not host for this plugin still returns a port; each call then answers
-     * `unknown-server`. Its message names the plugin that holds the name, or else lists the possible
-     * reasons (no approved `mcp.host-server` grant, a sign-in the server cannot use, or a name that
-     * a plugin Bonsai ships or another installed plugin also claims) and points at the plugin's load
-     * diagnostic.
-     *
-     * A port reaches this plugin's own server only. To use another plugin's data, declare that
-     * plugin in the manifest's `dependencies.plugins`; a later SDK surface reaches it.
+     * `unknown-server`. Each invocation uses the resource caller's exact `kay.agent` `uri.call`
+     * grant for `mcp` / `write`; MCP checks the host-stamped caller against server ownership.
      */
     port<TTool extends string = string>(server: string): VendoredMcpPort<TTool>;
 }
@@ -5150,6 +5153,7 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
             eventSubscription: "eventSubscription";
             appDataSource: "appDataSource";
             whiteboardType: "whiteboardType";
+            workingDocumentProvider: "workingDocumentProvider";
             approvalType: "approvalType";
             workflow: "workflow";
             contextContributor: "contextContributor";
@@ -6209,6 +6213,24 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
         handover: z.ZodOptional<z.ZodLiteral<true>>;
         globalId: z.ZodString;
     }, z.core.$strict>>>;
+    kayAppWorkingDocumentProviders: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        localId: z.ZodString;
+        globalId: z.ZodString;
+        displayName: z.ZodString;
+        schemes: z.ZodArray<z.ZodString>;
+        hosts: z.ZodArray<z.ZodString>;
+        authServiceId: z.ZodOptional<z.ZodString>;
+        authSchemeId: z.ZodOptional<z.ZodString>;
+        scopeRequirement: z.ZodOptional<z.ZodObject<{
+            purpose: z.ZodString;
+            alternatives: z.ZodArray<z.ZodObject<{
+                allOf: z.ZodArray<z.ZodObject<{
+                    scope: z.ZodString;
+                    reason: z.ZodExactOptional<z.ZodString>;
+                }, z.core.$strict>>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>>;
     kayAppMcpServers: z.ZodOptional<z.ZodArray<z.ZodObject<{
         name: z.ZodString;
         pluginId: z.ZodString;
@@ -12020,7 +12042,7 @@ declare interface Usage {
 /**
  * ---
  * responsibility: The one interface through which a vendored-MCP plugin's code calls a tool on its
- *   own vendored MCP server, so every read-through plugin and the daemon that implements the port
+ *   own vendored MCP server, so every read-through plugin and the SDK that implements the port
  *   agree on the same shape by construction.
  * owns:
  *   - {@link VendoredMcpPort} - what a plugin's URI module and tools call.
@@ -12028,8 +12050,8 @@ declare interface Usage {
  *     must surface to the agent rather than swallow.
  * does_not_own:
  *   - The implementation. A plugin never dials MCP itself: it takes the port from
- *     `api.vendoredMcp.port(server)` (`@bonsai/plugin-sdk/kay-agent`), which the daemon binds to the
- *     plugin's own hosted server over its MCP host. Plugin source stays host-free, and a plugin
+ *     `api.vendoredMcp.port(server)` (`@bonsai/plugin-sdk/kay-agent`), which the SDK binds through
+ *     resource calls to the plugin's own hosted server. Plugin source stays host-free, and a plugin
  *     under test substitutes a fake port.
  *   - Which tool names exist. `TTool` is the plugin's own union of the vendor tools it calls; the
  *     port is generic so a typo in a tool name fails typecheck inside the plugin.
@@ -12065,8 +12087,8 @@ declare type VendoredMcpOutcome =
 
 /**
  * One vendored MCP server, as the plugin that declares it calls it. `invoke` calls any tool the
- * server has, whether it reads or writes. The port checks no permission of its own: a call is as
- * permitted as the plugin tool or URI verb that makes it.
+ * server has, whether it reads or writes. The resource caller checks the target's exact
+ * `uri.call` grant, and MCP checks the host-stamped caller against server ownership.
  */
 declare interface VendoredMcpPort<TTool extends string = string> {
     invoke(input: {

package/dist/kay-agent.d.ts

@@ -3076,8 +3076,16 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  *
  * 0.54.1 adds manifest-declared plugin workers on both backend targets and exposes the canonical
  * transcript placement and answer-stretch rules through the SDK.
+ *
+ * 0.54.2 lets a signal list the files that came with it (epic #15668). `PluginSignal` gains an
+ * optional `attachments`: each file's name, media type, size and the address its bytes are read
+ * from, never the bytes. Gmail lists a mail's attachments there, so Flows can file them. Additive:
+ * a plugin that publishes attachments declares ^0.54.2.
+ *
+ * 0.55.0 carries managed MCP calls over resource writes in both daemon and plugin-host code.
+ * Existing agent and background MCP call shapes remain supported.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.54.1";
+declare const KAY_PLUGIN_SDK_VERSION: "0.55.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -3575,13 +3583,8 @@ export declare interface KayAgentVendoredMcp {
      * The port to `server`, a name this plugin declares in its `kay.app` target's
      * `contributes.mcpServers`. Throws when the plugin declares no server of that name. A declared
      * server that Bonsai does not host for this plugin still returns a port; each call then answers
-     * `unknown-server`. Its message names the plugin that holds the name, or else lists the possible
-     * reasons (no approved `mcp.host-server` grant, a sign-in the server cannot use, or a name that
-     * a plugin Bonsai ships or another installed plugin also claims) and points at the plugin's load
-     * diagnostic.
-     *
-     * A port reaches this plugin's own server only. To use another plugin's data, declare that
-     * plugin in the manifest's `dependencies.plugins`; a later SDK surface reaches it.
+     * `unknown-server`. Each invocation uses the resource caller's exact `kay.agent` `uri.call`
+     * grant for `mcp` / `write`; MCP checks the host-stamped caller against server ownership.
      */
     port<TTool extends string = string>(server: string): VendoredMcpPort<TTool>;
 }
@@ -11847,6 +11850,7 @@ export declare class UriProviderError extends UriError {
     readonly uri: string;
     readonly status?: number;
     readonly providerCode?: string;
+    readonly serviceId?: string;
     readonly retryable?: boolean;
     /** Provider-directed delay before retrying, in milliseconds. */
     readonly retryAfterMs?: number;
@@ -11864,6 +11868,8 @@ export declare interface UriProviderErrorOptions {
     readonly message: string;
     readonly status?: number;
     readonly providerCode?: string;
+    /** Service to reconnect when the provider requires sign-in. */
+    readonly serviceId?: string;
     readonly retryable?: boolean;
     /** Provider-directed delay before retrying, in milliseconds. */
     readonly retryAfterMs?: number;
@@ -12335,7 +12341,7 @@ declare interface Usage {
 /**
  * ---
  * responsibility: The one interface through which a vendored-MCP plugin's code calls a tool on its
- *   own vendored MCP server, so every read-through plugin and the daemon that implements the port
+ *   own vendored MCP server, so every read-through plugin and the SDK that implements the port
  *   agree on the same shape by construction.
  * owns:
  *   - {@link VendoredMcpPort} - what a plugin's URI module and tools call.
@@ -12343,8 +12349,8 @@ declare interface Usage {
  *     must surface to the agent rather than swallow.
  * does_not_own:
  *   - The implementation. A plugin never dials MCP itself: it takes the port from
- *     `api.vendoredMcp.port(server)` (`@bonsai/plugin-sdk/kay-agent`), which the daemon binds to the
- *     plugin's own hosted server over its MCP host. Plugin source stays host-free, and a plugin
+ *     `api.vendoredMcp.port(server)` (`@bonsai/plugin-sdk/kay-agent`), which the SDK binds through
+ *     resource calls to the plugin's own hosted server. Plugin source stays host-free, and a plugin
  *     under test substitutes a fake port.
  *   - Which tool names exist. `TTool` is the plugin's own union of the vendor tools it calls; the
  *     port is generic so a typo in a tool name fails typecheck inside the plugin.
@@ -12380,8 +12386,8 @@ declare type VendoredMcpOutcome =
 
 /**
  * One vendored MCP server, as the plugin that declares it calls it. `invoke` calls any tool the
- * server has, whether it reads or writes. The port checks no permission of its own: a call is as
- * permitted as the plugin tool or URI verb that makes it.
+ * server has, whether it reads or writes. The resource caller checks the target's exact
+ * `uri.call` grant, and MCP checks the host-stamped caller against server ownership.
  */
 declare interface VendoredMcpPort<TTool extends string = string> {
     invoke(input: {

package/dist/kay-agent.js

@@ -422,6 +422,7 @@ var UriProviderError = class extends UriError {
   uri;
   status;
   providerCode;
+  serviceId;
   retryable;
   /** Provider-directed delay before retrying, in milliseconds. */
   retryAfterMs;
@@ -439,6 +440,8 @@ var UriProviderError = class extends UriError {
       this.status = options.status;
     if (options.providerCode !== void 0)
       this.providerCode = options.providerCode;
+    if (options.serviceId !== void 0)
+      this.serviceId = options.serviceId;
     if (options.retryable !== void 0)
       this.retryable = options.retryable;
     if (options.retryAfterMs !== void 0) {

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

@@ -3404,14 +3404,20 @@ declare const runFailureCauseSchema: z.ZodObject<{
     credentialRef: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 
-declare type RunFailureOccurrence = FailureOccurrence<RunFailureCause>;
+/**
+ * One run failure record. `Code` and `Domain` default to `string`, as every
+ * reader takes them; a producer passes `RunFailureCode` and
+ * `RunFailureDomain` on the record it makes, so an undeclared code fails to
+ * compile.
+ */
+declare type RunFailureOccurrence<Code extends string = string, Domain extends string = string> = FailureOccurrence<RunFailureCause, Code, Domain>;
 
 declare type RunFailureReason = (typeof RUN_FAILURE_REASONS)[number];
 
 declare type RunFailureRecord = z.infer<typeof runFailureRecordSchema>;
 
 declare const runFailureRecordSchema: z.ZodObject<{
-    failure: z.ZodType<RunFailureOccurrence, unknown, z.core.$ZodTypeInternals<RunFailureOccurrence, unknown>>;
+    failure: z.ZodType<RunFailureOccurrence<string, string>, unknown, z.core.$ZodTypeInternals<RunFailureOccurrence<string, string>, unknown>>;
     errorText: z.ZodString;
 }, z.core.$strict>;
 

package/dist/kay-app.d.ts

@@ -324,7 +324,7 @@ declare const AgentRuntimeAutomationRunDetail: z.ZodObject<{
                 retryable: z.ZodBoolean;
                 retryAfterMs: z.ZodOptional<z.ZodNumber>;
             }, z.core.$strict>>;
-            failure: z.ZodOptional<z.ZodType<RunFailureOccurrence, unknown, z.core.$ZodTypeInternals<RunFailureOccurrence, unknown>>>;
+            failure: z.ZodOptional<z.ZodType<RunFailureOccurrence<string, string>, unknown, z.core.$ZodTypeInternals<RunFailureOccurrence<string, string>, unknown>>>;
             sessionId: z.ZodOptional<z.ZodString>;
             retryAtMs: z.ZodOptional<z.ZodNumber>;
             tries: z.ZodOptional<z.ZodNumber>;
@@ -4304,8 +4304,16 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  *
  * 0.54.1 adds manifest-declared plugin workers on both backend targets and exposes the canonical
  * transcript placement and answer-stretch rules through the SDK.
+ *
+ * 0.54.2 lets a signal list the files that came with it (epic #15668). `PluginSignal` gains an
+ * optional `attachments`: each file's name, media type, size and the address its bytes are read
+ * from, never the bytes. Gmail lists a mail's attachments there, so Flows can file them. Additive:
+ * a plugin that publishes attachments declares ^0.54.2.
+ *
+ * 0.55.0 carries managed MCP calls over resource writes in both daemon and plugin-host code.
+ * Existing agent and background MCP call shapes remain supported.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.54.1";
+declare const KAY_PLUGIN_SDK_VERSION: "0.55.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -6604,6 +6612,11 @@ export declare interface KayAppPluginApi {
     readonly resourcePicks?: {
         registerCompletion(moduleId: string, handler: PluginResourcePickHandler): void;
     };
+    /**
+     * Working-document providers. Present when the manifest declares `workingDocumentProviders`;
+     * each registration must name one of them.
+     */
+    readonly workingDocuments?: KayAppWorkingDocuments;
     readonly mcp: KayAppMcp;
     /** This plugin's canonical id (already validated by the host registry). */
     readonly id: string;
@@ -9882,6 +9895,73 @@ export declare type KayAppWorkflowTimeTrigger = Extract<KayAppAutomationConditio
  */
 export declare type KayAppWorkflowTrigger = KayAppWorkflowTimeTrigger | KayAppAutomationPluginEventCondition | KayAppWorkflowSignalsTrigger;
 
+/** One binary asset pulled with a document (an image, an embed). */
+export declare interface KayAppWorkingDocumentAsset {
+    /** A file-safe suggested name; the daemon dedupes it. */
+    readonly suggestedName: string;
+    readonly bytes: Uint8Array;
+    readonly mime: string;
+    /** Where it was downloaded from, so a push can put the upstream URL back. */
+    readonly sourceUrl?: string;
+}
+
+/**
+ * What one working-document call receives. The daemon owns the local copy, the base text and the
+ * revision guard; a provider only talks to its document source. `auth` is the token the daemon
+ * resolved from the provider's declared `authService`, absent for a provider that declares none.
+ */
+export declare interface KayAppWorkingDocumentContext {
+    /** The source the person named, as the daemon parsed it: a web link or a URI. */
+    readonly sourceUrl: string;
+    readonly auth?: {
+        readonly accessToken: string;
+        readonly accountId?: string;
+    };
+    readonly signal: AbortSignal;
+}
+
+/**
+ * A document source's code, registered for a `workingDocumentProviders` entry the manifest
+ * declares. Which URLs it serves, its display name and its sign-in are manifest data.
+ */
+export declare interface KayAppWorkingDocumentProvider {
+    pull(ctx: KayAppWorkingDocumentContext): Promise<KayAppWorkingDocumentPull>;
+    push(ctx: KayAppWorkingDocumentContext, input: KayAppWorkingDocumentPushInput): Promise<KayAppWorkingDocumentPushResult>;
+    /** The live upstream revision, which the daemon compares before a push. */
+    checkRevision(ctx: KayAppWorkingDocumentContext): Promise<string>;
+}
+
+/** What a pull returns: the document as Markdown, its title, its upstream revision and assets. */
+export declare interface KayAppWorkingDocumentPull {
+    readonly markdown: string;
+    readonly title: string;
+    readonly revision: string;
+    readonly assets: readonly KayAppWorkingDocumentAsset[];
+    /** Notes for the person who pulled it (blocks that did not convert, rewrites). */
+    readonly notes: readonly string[];
+}
+
+/** What a push receives: the text the copy was pulled at and the edited text to write upstream. */
+export declare interface KayAppWorkingDocumentPushInput {
+    readonly baseText: string;
+    readonly nextText: string;
+    /** The person forced past a changed upstream: overwrite the whole body. */
+    readonly force?: boolean;
+    /** A snippet naming the block to scroll to afterwards; return `anchor` if you can resolve it. */
+    readonly anchorHint?: string;
+}
+
+export declare interface KayAppWorkingDocumentPushResult {
+    readonly revision: string;
+    readonly warnings: readonly string[];
+    readonly anchor?: string;
+}
+
+export declare interface KayAppWorkingDocuments {
+    /** Register the code for the declared provider `localId`, once, during activation. */
+    registerProvider(localId: string, provider: KayAppWorkingDocumentProvider): void;
+}
+
 /**
  * Read/arrange access to the live desktop workspace (tabs, panes, the shell chrome). Always
  * present. `snapshot` is ungated; `execute` is checked per call against the `workspace.command`
@@ -11363,6 +11443,15 @@ declare function PickDeferred<Type extends TSchema, Indexer extends TSchema>(typ
  */
 export declare const PLUGIN_EVENT_REFUSED_ERROR_NAME = "PluginEventRefusedError";
 
+/** An attachment's file name, at most this many characters. */
+export declare const PLUGIN_SIGNAL_ATTACHMENT_NAME_MAX = 255;
+
+/** An attachment's media type (`application/pdf`), at most this many characters. */
+export declare const PLUGIN_SIGNAL_ATTACHMENT_TYPE_MAX = 127;
+
+/** At most this many entries in a signal's `attachments`; a source lists the first ones. */
+export declare const PLUGIN_SIGNAL_ATTACHMENTS_MAX = 10;
+
 /** The `kind` values of `PluginSignal` v1. `status` is system state that clears itself. */
 export declare const PLUGIN_SIGNAL_KINDS: readonly ["message", "request", "mention", "invite", "status"];
 
@@ -11561,6 +11650,12 @@ export declare const PluginSignal: z.ZodObject<{
         open: "open";
         resolved: "resolved";
     }>>;
+    attachments: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodString;
+        size: z.ZodNumber;
+        uri: z.ZodString;
+    }, z.core.$strict>>>;
 }, z.core.$strict>;
 
 export declare type PluginSignal = z.infer<typeof PluginSignal>;
@@ -11599,6 +11694,12 @@ export declare const PluginSignalPublish: z.ZodObject<{
             open: "open";
             resolved: "resolved";
         }>>;
+        attachments: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            type: z.ZodString;
+            size: z.ZodNumber;
+            uri: z.ZodString;
+        }, z.core.$strict>>>;
     }, z.core.$strict>;
     related: z.ZodObject<{
         thread: z.ZodString;
@@ -12270,14 +12371,20 @@ declare const runFailureCauseSchema: z.ZodObject<{
     credentialRef: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 
-declare type RunFailureOccurrence = FailureOccurrence<RunFailureCause>;
+/**
+ * One run failure record. `Code` and `Domain` default to `string`, as every
+ * reader takes them; a producer passes `RunFailureCode` and
+ * `RunFailureDomain` on the record it makes, so an undeclared code fails to
+ * compile.
+ */
+declare type RunFailureOccurrence<Code extends string = string, Domain extends string = string> = FailureOccurrence<RunFailureCause, Code, Domain>;
 
 declare type RunFailureReason = (typeof RUN_FAILURE_REASONS)[number];
 
 declare type RunFailureRecord = z.infer<typeof runFailureRecordSchema>;
 
 declare const runFailureRecordSchema: z.ZodObject<{
-    failure: z.ZodType<RunFailureOccurrence, unknown, z.core.$ZodTypeInternals<RunFailureOccurrence, unknown>>;
+    failure: z.ZodType<RunFailureOccurrence<string, string>, unknown, z.core.$ZodTypeInternals<RunFailureOccurrence<string, string>, unknown>>;
     errorText: z.ZodString;
 }, z.core.$strict>;
 
@@ -18166,6 +18273,7 @@ export declare class UriProviderError extends UriError {
     readonly uri: string;
     readonly status?: number;
     readonly providerCode?: string;
+    readonly serviceId?: string;
     readonly retryable?: boolean;
     /** Provider-directed delay before retrying, in milliseconds. */
     readonly retryAfterMs?: number;
@@ -18183,6 +18291,8 @@ export declare interface UriProviderErrorOptions {
     readonly message: string;
     readonly status?: number;
     readonly providerCode?: string;
+    /** Service to reconnect when the provider requires sign-in. */
+    readonly serviceId?: string;
     readonly retryable?: boolean;
     /** Provider-directed delay before retrying, in milliseconds. */
     readonly retryAfterMs?: number;
@@ -18695,7 +18805,7 @@ declare type UserShellCommandMessage = CustomMessage<UserShellCommandDetails> &
 /**
  * ---
  * responsibility: The one interface through which a vendored-MCP plugin's code calls a tool on its
- *   own vendored MCP server, so every read-through plugin and the daemon that implements the port
+ *   own vendored MCP server, so every read-through plugin and the SDK that implements the port
  *   agree on the same shape by construction.
  * owns:
  *   - {@link VendoredMcpPort} - what a plugin's URI module and tools call.
@@ -18703,8 +18813,8 @@ declare type UserShellCommandMessage = CustomMessage<UserShellCommandDetails> &
  *     must surface to the agent rather than swallow.
  * does_not_own:
  *   - The implementation. A plugin never dials MCP itself: it takes the port from
- *     `api.vendoredMcp.port(server)` (`@bonsai/plugin-sdk/kay-agent`), which the daemon binds to the
- *     plugin's own hosted server over its MCP host. Plugin source stays host-free, and a plugin
+ *     `api.vendoredMcp.port(server)` (`@bonsai/plugin-sdk/kay-agent`), which the SDK binds through
+ *     resource calls to the plugin's own hosted server. Plugin source stays host-free, and a plugin
  *     under test substitutes a fake port.
  *   - Which tool names exist. `TTool` is the plugin's own union of the vendor tools it calls; the
  *     port is generic so a typo in a tool name fails typecheck inside the plugin.

package/dist/kay-app.js

@@ -55,6 +55,7 @@ var UriProviderError = class extends UriError {
   uri;
   status;
   providerCode;
+  serviceId;
   retryable;
   /** Provider-directed delay before retrying, in milliseconds. */
   retryAfterMs;
@@ -72,6 +73,8 @@ var UriProviderError = class extends UriError {
       this.status = options.status;
     if (options.providerCode !== void 0)
       this.providerCode = options.providerCode;
+    if (options.serviceId !== void 0)
+      this.serviceId = options.serviceId;
     if (options.retryable !== void 0)
       this.retryable = options.retryable;
     if (options.retryAfterMs !== void 0) {
@@ -370,6 +373,9 @@ var PLUGIN_SIGNAL_TITLE_MAX = 300;
 var PLUGIN_SIGNAL_SNIPPET_MAX = 500;
 var PLUGIN_SIGNAL_LABELS_MAX = 20;
 var PLUGIN_SIGNAL_LABEL_MAX = 64;
+var PLUGIN_SIGNAL_ATTACHMENTS_MAX = 10;
+var PLUGIN_SIGNAL_ATTACHMENT_NAME_MAX = 255;
+var PLUGIN_SIGNAL_ATTACHMENT_TYPE_MAX = 127;
 var PLUGIN_SIGNAL_RELATED_KEYS = [
   "thread",
   "from",
@@ -1184,6 +1190,9 @@ export {
   KayAppWorkflowFailure,
   MAX_CHOICE_LABELS,
   PLUGIN_EVENT_REFUSED_ERROR_NAME,
+  PLUGIN_SIGNAL_ATTACHMENTS_MAX,
+  PLUGIN_SIGNAL_ATTACHMENT_NAME_MAX,
+  PLUGIN_SIGNAL_ATTACHMENT_TYPE_MAX,
   PLUGIN_SIGNAL_KINDS,
   PLUGIN_SIGNAL_LABELS_MAX,
   PLUGIN_SIGNAL_LABEL_MAX,

package/dist/vendored-mcp.d.ts

@@ -1,3 +1,9 @@
+export declare function createKayAgentVendoredMcp(pluginId: string, servers: readonly string[], uri: PluginUriCaller): KayAgentVendoredMcp;
+
+export declare function createKayAppMcp(pluginId: string, servers: readonly string[], uri: PluginUriCaller): KayAppMcp;
+
+export declare function createVendoredMcpPort(server: string, uri: PluginUriCaller): VendoredMcpPort;
+
 /**
  * The URI module for one vendored-MCP integration plugin.
  *
@@ -44,6 +50,35 @@ declare type JsonValue = JsonPrimitive | {
     readonly [key: string]: JsonValue;
 } | readonly JsonValue[];
 
+/**
+ * Calls tools on the plugin's own vendored MCP servers. See {@link KayAgentPluginApi.vendoredMcp}.
+ */
+declare interface KayAgentVendoredMcp {
+    /**
+     * The port to `server`, a name this plugin declares in its `kay.app` target's
+     * `contributes.mcpServers`. Throws when the plugin declares no server of that name. A declared
+     * server that Bonsai does not host for this plugin still returns a port; each call then answers
+     * `unknown-server`. Each invocation uses the resource caller's exact `kay.agent` `uri.call`
+     * grant for `mcp` / `write`; MCP checks the host-stamped caller against server ownership.
+     */
+    port<TTool extends string = string>(server: string): VendoredMcpPort<TTool>;
+}
+
+/** Calls tools on this plugin's manifest-declared MCP servers through Bonsai's managed connection. */
+declare interface KayAppMcp {
+    /**
+     * Uses the current app-wide server set, without a session or working directory.
+     * Refuses undeclared or no-longer-hosted servers. Sign-in and tool failures return typed outcomes;
+     * credentials remain with the host. Like the agent-side vendored MCP API, calls can read or write
+     * and do not use the agent's per-tool approval path.
+     */
+    callTool(input: {
+        readonly server: string;
+        readonly tool: string;
+        readonly args: Readonly<Record<string, unknown>>;
+    }): Promise<VendoredMcpOutcome>;
+}
+
 declare interface LineRange {
     readonly start: number;
     readonly end: number;
@@ -127,6 +162,38 @@ declare interface ObservationMaterial {
     readonly retainForMs?: number;
 }
 
+/**
+ * Sessionless resource calls. Each call checks the calling target's exact scheme and verb grant.
+ * Results retain provider bytes, metadata and revisions; provider failures retain their URI tags.
+ * A cancellation or lost response does not prove a mutation was not applied.
+ */
+declare interface PluginUriCaller {
+    read(input: string, options?: PluginUriReadOptions): Promise<RawResource>;
+    list(input: string, params?: UriListParams, options?: PluginUriCallOptions): Promise<UriListResult>;
+    search(input: string, params: UriSearchParams, options?: PluginUriCallOptions): Promise<UriSearchResult>;
+    write(input: string, content?: UriPayload | Uint8Array, options?: PluginUriWriteOptions): Promise<UriMutationResult | void>;
+    edit(input: string, payload: UriPayload, options?: PluginUriMutationOptions): Promise<UriMutationResult>;
+    delete(input: string, options?: PluginUriMutationOptions): Promise<UriMutationResult>;
+}
+
+declare interface PluginUriCallOptions {
+    readonly cwd?: string;
+    readonly signal?: AbortSignal;
+}
+
+declare interface PluginUriMutationOptions extends PluginUriCallOptions {
+    readonly expectedRevision?: string;
+}
+
+declare interface PluginUriReadOptions extends PluginUriCallOptions {
+    readonly knownRevision?: string;
+}
+
+declare interface PluginUriWriteOptions extends PluginUriMutationOptions {
+    readonly sources?: readonly UriWriteSource[];
+    readonly writeSource?: UriSourceDescriptor;
+}
+
 declare interface RawResource {
     readonly uri: string;
     readonly content: string | Uint8Array;
@@ -1246,7 +1313,7 @@ declare type VendoredMcpFactClaim = {
 /**
  * ---
  * responsibility: The one interface through which a vendored-MCP plugin's code calls a tool on its
- *   own vendored MCP server, so every read-through plugin and the daemon that implements the port
+ *   own vendored MCP server, so every read-through plugin and the SDK that implements the port
  *   agree on the same shape by construction.
  * owns:
  *   - {@link VendoredMcpPort} - what a plugin's URI module and tools call.
@@ -1254,8 +1321,8 @@ declare type VendoredMcpFactClaim = {
  *     must surface to the agent rather than swallow.
  * does_not_own:
  *   - The implementation. A plugin never dials MCP itself: it takes the port from
- *     `api.vendoredMcp.port(server)` (`@bonsai/plugin-sdk/kay-agent`), which the daemon binds to the
- *     plugin's own hosted server over its MCP host. Plugin source stays host-free, and a plugin
+ *     `api.vendoredMcp.port(server)` (`@bonsai/plugin-sdk/kay-agent`), which the SDK binds through
+ *     resource calls to the plugin's own hosted server. Plugin source stays host-free, and a plugin
  *     under test substitutes a fake port.
  *   - Which tool names exist. `TTool` is the plugin's own union of the vendor tools it calls; the
  *     port is generic so a typo in a tool name fails typecheck inside the plugin.
@@ -1291,8 +1358,8 @@ export declare type VendoredMcpOutcome =
 
 /**
  * One vendored MCP server, as the plugin that declares it calls it. `invoke` calls any tool the
- * server has, whether it reads or writes. The port checks no permission of its own: a call is as
- * permitted as the plugin tool or URI verb that makes it.
+ * server has, whether it reads or writes. The resource caller checks the target's exact
+ * `uri.call` grant, and MCP checks the host-stamped caller against server ownership.
  */
 export declare interface VendoredMcpPort<TTool extends string = string> {
     invoke(input: {

package/dist/vendored-mcp.js

@@ -480,6 +480,30 @@ var UriPayloadContractSchema = z2.strictObject({
   examples: z2.array(z2.unknown()).optional()
 });
 
+// packages/herd-uri/dist/payloads.js
+function isJsonPrimitive(value) {
+  return value === null || typeof value === "string" || typeof value === "boolean" || typeof value === "number" && Number.isFinite(value);
+}
+function isJsonValue(value) {
+  return isJsonValueInner(value, /* @__PURE__ */ new WeakSet());
+}
+function isJsonValueInner(value, seen) {
+  if (isJsonPrimitive(value))
+    return true;
+  if (typeof value !== "object" || value === null)
+    return false;
+  if (seen.has(value))
+    return false;
+  seen.add(value);
+  if (Array.isArray(value)) {
+    return value.every((item) => isJsonValueInner(item, seen));
+  }
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null)
+    return false;
+  return Object.values(value).every((item) => isJsonValueInner(item, seen));
+}
+
 // packages/herd-uri/dist/text-edit.js
 import { z as z3 } from "zod";
 var findReplaceArm = z3.strictObject({
@@ -664,7 +688,70 @@ function createVendoredMcpUriModule(descriptor) {
     }
   };
 }
+
+// packages/plugin-sdk/dist/vendored-mcp.js
+function createVendoredMcpPort(server, uri) {
+  return {
+    async invoke({ cwd, tool, args }) {
+      try {
+        if (!isJsonValue(args)) {
+          return {
+            ok: false,
+            reason: "failed",
+            message: "MCP tool arguments must be JSON-compatible."
+          };
+        }
+        const result = await uri.write(`mcp://${encodeURIComponent(server)}/tools/${encodeURIComponent(tool)}`, args, { cwd });
+        if (result === void 0 || result.resource === void 0) {
+          return {
+            ok: false,
+            reason: "failed",
+            message: `MCP server '${server}' returned no tool result.`
+          };
+        }
+        return { ok: true, value: result.resource };
+      } catch (error) {
+        const failure = error;
+        const code = failure?.providerCode;
+        const reason = failure?._tag === "UriProviderError" && failure.moduleId === "mcp.servers" && (code === "needs-auth" || code === "unknown-server" || code === "unknown-tool" || code === "failed") ? code : "failed";
+        return {
+          ok: false,
+          reason,
+          message: error instanceof Error ? error.message : String(error),
+          ...typeof failure?.serviceId === "string" ? { serviceId: failure.serviceId } : {}
+        };
+      }
+    }
+  };
+}
+function createKayAgentVendoredMcp(pluginId, servers, uri) {
+  return {
+    port(server) {
+      if (!servers.includes(server)) {
+        throw new Error(`Plugin '${pluginId}' declares no MCP server '${server}' in its kay.app target's contributes.mcpServers, so api.vendoredMcp has no port to it.`);
+      }
+      return createVendoredMcpPort(server, uri);
+    }
+  };
+}
+function createKayAppMcp(pluginId, servers, uri) {
+  return {
+    async callTool({ server, tool, args }) {
+      if (!servers.includes(server)) {
+        return {
+          ok: false,
+          reason: "unknown-server",
+          message: `Plugin '${pluginId}' does not declare MCP server '${server}'.`
+        };
+      }
+      return createVendoredMcpPort(server, uri).invoke({ cwd: "", tool, args });
+    }
+  };
+}
 export {
+  createKayAgentVendoredMcp,
+  createKayAppMcp,
+  createVendoredMcpPort,
   createVendoredMcpUriModule,
   vendoredMcpUriModuleFacts
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaklabs-ai/plugin-sdk",
-  "version": "0.54.1",
+  "version": "0.55.0",
   "description": "The Kay plugin SDK — types and helpers for authoring a Kay directory plugin.",
   "author": "YakLabs",
   "type": "module",