@yaklabs-ai/plugin-sdk 0.41.0 → 0.42.1

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.41.0"
+    "@bonsai/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.42.1"
   }
 }
 ```
@@ -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.41.0" },
+  "compatibility": { "sdk": "^0.42.1" },
   "targets": {
     "kay": {
       "agent": {

package/THIRD-PARTY-INVENTORY.json

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

package/dist/disclosure.d.ts

@@ -2417,8 +2417,15 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  *
  * 0.41.0 adds app.mcp.callTool for background calls to a plugin's own manifest-declared MCP
  * servers, using Bonsai's managed connection without a session or working directory (#16172).
+ *
+ * 0.42.0 hands background work the shared ResolvedCredential in auth.credential. Workflow
+ * accounts carry auth resolution outcomes, and Poller callbacks receive only the credential.
+ * Older SDK ranges are refused because their background success shape is no longer served.
+ *
+ * 0.42.1 adds current-session tool lifetimes and invocation-bound artifact reads/new outputs,
+ * plus described-tool execution, guidance and permission resource metadata.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.41.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.42.1";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -2867,8 +2874,42 @@ declare interface KayAgentProcessRunResult {
     readonly stderrTruncated?: boolean;
 }
 
+/** A loaded session's volatile lifetime. Reopening a released session gets a fresh key. */
+declare interface KayAgentSession {
+    readonly key: string;
+    /** Registers synchronous cleanup, invoked once on release. Returns an unregister function. */
+    onDispose(disposer: () => void): () => void;
+    /** Valid only while this tool call is active. */
+    readonly artifacts: KayAgentSessionArtifacts;
+}
+
+/** Metadata returned by a current-session artifact operation; no filesystem authority. */
+declare interface KayAgentSessionArtifact {
+    readonly uri: string;
+    readonly name: string;
+    readonly mimeType?: string;
+}
+
+/** Current-session file access, authorized at each call; never retained between tool calls. */
+declare interface KayAgentSessionArtifacts {
+    readBytes(input: {
+        readonly uri: string;
+        readonly maxBytes?: number;
+    }): Promise<KayAgentSessionArtifact & {
+        readonly bytes: Uint8Array;
+    }>;
+    publishNew(input: {
+        readonly name: string;
+        readonly bytes: Uint8Array;
+    }): Promise<KayAgentSessionArtifact>;
+}
+
+declare type KayAgentToolContext = Parameters<ToolDefinition["execute"]>[4] & {
+    readonly session?: KayAgentSession;
+};
+
 /** The `execute` a plugin supplies for a tool its manifest describes. */
-declare type KayAgentToolExecute = ToolDefinition["execute"];
+declare type KayAgentToolExecute = (toolCallId: string, params: Parameters<ToolDefinition["execute"]>[1], signal: AbortSignal | undefined, onUpdate: Parameters<ToolDefinition["execute"]>[3], ctx: KayAgentToolContext) => ReturnType<ToolDefinition["execute"]>;
 
 /**
  * Calls tools on the plugin's own vendored MCP servers. See {@link KayAgentPluginApi.vendoredMcp}.
@@ -3085,13 +3126,14 @@ declare interface KayAppUserFileEntry {
  * The plugin-facing user-files contract: file I/O in folders the user owns, done by the host on
  * its own worker threads.
  *
- * Ungated and always present, like `app.paths`. It confers no authority: a plugin runs in the
- * daemon's process and can call `node:fs` itself. What the door adds is where the work runs. A
- * `node:fs` sync call blocks the daemon's event loop for as long as the path takes to answer,
- * which under a macOS-protected folder or on a drive that stopped answering can be a very long
- * time (kay#11575); an async one holds a thread of the pool the whole daemon shares. The host runs
- * each request on a dedicated worker, gives it a deadline, and answers a typed result instead of
- * throwing.
+ * Ungated and always present, like `app.paths`. It confers no authority: the process a plugin
+ * runs in, the daemon or the plugin host, could call `node:fs` itself. What the door adds is where
+ * the work runs. A `node:fs` sync call blocks that process's event loop for as long as the path
+ * takes to answer, which under a macOS-protected folder or on a drive that stopped answering can
+ * be a very long time (kay#11575); an async one holds a thread of the pool the whole process
+ * shares. The daemon's user-files service runs each request on a dedicated worker, gives it a
+ * deadline, and answers a typed result instead of throwing. A plugin in the plugin host reaches
+ * the same service: each call is sent to the daemon and answered from there.
  *
  * This is a leaf module. It lives beside both target SDKs, like `time.ts`, so the `kay.agent` SDK
  * exposes the same door without importing the `kay.app` surface.
@@ -3132,7 +3174,12 @@ declare interface KayAppUserFiles {
 }
 
 declare interface KayAppUserFilesCallOptions {
-    /** Deadline in milliseconds from the call, waiting included. Default 5000, at most 60000. */
+    /**
+     * Deadline in milliseconds, waiting included. Default 5000, at most 60000. It starts when the
+     * daemon's user-files service receives the request: from the call in the daemon, or, for a
+     * plugin in the plugin host, once the request has crossed to the daemon. A daemon that never
+     * reads the request leaves the call waiting until the host's connection to it is closed.
+     */
     readonly timeoutMs?: number;
     readonly signal?: AbortSignal;
 }

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

@@ -1629,7 +1629,7 @@ declare class InvalidLiteralValue extends Error {
  * `ctx` (with a `credential` for an auth-gated tool) to exercise anything beyond the
  * happy-path default.
  */
-export declare function invokeToolForTest<TDetails = unknown>(tool: ToolDefinition<any, TDetails>, params: Record<string, unknown>, ctx?: ToolContext): Promise<AgentToolResult<TDetails>>;
+export declare function invokeToolForTest<TDetails = unknown>(tool: ToolDefinition<any, TDetails>, params: Record<string, unknown>, ctx?: KayAgentToolContext): Promise<AgentToolResult<TDetails>>;
 
 /** Returns true if the given value is a TAny. */
 declare function IsAny(value: unknown): value is TAny;
@@ -2471,8 +2471,15 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  *
  * 0.41.0 adds app.mcp.callTool for background calls to a plugin's own manifest-declared MCP
  * servers, using Bonsai's managed connection without a session or working directory (#16172).
+ *
+ * 0.42.0 hands background work the shared ResolvedCredential in auth.credential. Workflow
+ * accounts carry auth resolution outcomes, and Poller callbacks receive only the credential.
+ * Older SDK ranges are refused because their background success shape is no longer served.
+ *
+ * 0.42.1 adds current-session tool lifetimes and invocation-bound artifact reads/new outputs,
+ * plus described-tool execution, guidance and permission resource metadata.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.41.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.42.1";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -2918,8 +2925,42 @@ declare interface KayAgentProcessRunResult {
     readonly stderrTruncated?: boolean;
 }
 
+/** A loaded session's volatile lifetime. Reopening a released session gets a fresh key. */
+declare interface KayAgentSession {
+    readonly key: string;
+    /** Registers synchronous cleanup, invoked once on release. Returns an unregister function. */
+    onDispose(disposer: () => void): () => void;
+    /** Valid only while this tool call is active. */
+    readonly artifacts: KayAgentSessionArtifacts;
+}
+
+/** Metadata returned by a current-session artifact operation; no filesystem authority. */
+declare interface KayAgentSessionArtifact {
+    readonly uri: string;
+    readonly name: string;
+    readonly mimeType?: string;
+}
+
+/** Current-session file access, authorized at each call; never retained between tool calls. */
+declare interface KayAgentSessionArtifacts {
+    readBytes(input: {
+        readonly uri: string;
+        readonly maxBytes?: number;
+    }): Promise<KayAgentSessionArtifact & {
+        readonly bytes: Uint8Array;
+    }>;
+    publishNew(input: {
+        readonly name: string;
+        readonly bytes: Uint8Array;
+    }): Promise<KayAgentSessionArtifact>;
+}
+
+declare type KayAgentToolContext = Parameters<ToolDefinition["execute"]>[4] & {
+    readonly session?: KayAgentSession;
+};
+
 /** The `execute` a plugin supplies for a tool its manifest describes. */
-declare type KayAgentToolExecute = ToolDefinition["execute"];
+declare type KayAgentToolExecute = (toolCallId: string, params: Parameters<ToolDefinition["execute"]>[1], signal: AbortSignal | undefined, onUpdate: Parameters<ToolDefinition["execute"]>[3], ctx: KayAgentToolContext) => ReturnType<ToolDefinition["execute"]>;
 
 /**
  * Calls tools on the plugin's own vendored MCP servers. See {@link KayAgentPluginApi.vendoredMcp}.
@@ -3136,13 +3177,14 @@ declare interface KayAppUserFileEntry {
  * The plugin-facing user-files contract: file I/O in folders the user owns, done by the host on
  * its own worker threads.
  *
- * Ungated and always present, like `app.paths`. It confers no authority: a plugin runs in the
- * daemon's process and can call `node:fs` itself. What the door adds is where the work runs. A
- * `node:fs` sync call blocks the daemon's event loop for as long as the path takes to answer,
- * which under a macOS-protected folder or on a drive that stopped answering can be a very long
- * time (kay#11575); an async one holds a thread of the pool the whole daemon shares. The host runs
- * each request on a dedicated worker, gives it a deadline, and answers a typed result instead of
- * throwing.
+ * Ungated and always present, like `app.paths`. It confers no authority: the process a plugin
+ * runs in, the daemon or the plugin host, could call `node:fs` itself. What the door adds is where
+ * the work runs. A `node:fs` sync call blocks that process's event loop for as long as the path
+ * takes to answer, which under a macOS-protected folder or on a drive that stopped answering can
+ * be a very long time (kay#11575); an async one holds a thread of the pool the whole process
+ * shares. The daemon's user-files service runs each request on a dedicated worker, gives it a
+ * deadline, and answers a typed result instead of throwing. A plugin in the plugin host reaches
+ * the same service: each call is sent to the daemon and answered from there.
  *
  * This is a leaf module. It lives beside both target SDKs, like `time.ts`, so the `kay.agent` SDK
  * exposes the same door without importing the `kay.app` surface.
@@ -3183,7 +3225,12 @@ declare interface KayAppUserFiles {
 }
 
 declare interface KayAppUserFilesCallOptions {
-    /** Deadline in milliseconds from the call, waiting included. Default 5000, at most 60000. */
+    /**
+     * Deadline in milliseconds, waiting included. Default 5000, at most 60000. It starts when the
+     * daemon's user-files service receives the request: from the call in the daemon, or, for a
+     * plugin in the plugin host, once the request has crossed to the daemon. A daemon that never
+     * reads the request leaves the call waiting until the host's connection to it is closed.
+     */
     readonly timeoutMs?: number;
     readonly signal?: AbortSignal;
 }
@@ -5495,6 +5542,12 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
         displayName: z.ZodOptional<z.ZodString>;
         description: z.ZodOptional<z.ZodString>;
         parameters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<authoringCommonSchemas.JsonValue, unknown, z.core.$ZodTypeInternals<authoringCommonSchemas.JsonValue, unknown>>>>;
+        executionMode: z.ZodOptional<z.ZodEnum<{
+            sequential: "sequential";
+            parallel: "parallel";
+        }>>;
+        promptSnippet: z.ZodOptional<z.ZodString>;
+        promptGuidelines: z.ZodOptional<z.ZodArray<z.ZodString>>;
         requiresAuth: z.ZodOptional<z.ZodObject<{
             serviceId: z.ZodString;
             schemeId: z.ZodOptional<z.ZodString>;
@@ -5507,6 +5560,8 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
                 execute: "execute";
             }>;
             ruleKey: z.ZodOptional<z.ZodString>;
+            scheme: z.ZodOptional<z.ZodString>;
+            resourcePrefix: z.ZodOptional<z.ZodString>;
             resourceArgs: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strict>>;
         localId: z.ZodString;
@@ -5796,6 +5851,7 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
                 "artifacts.read": "artifacts.read";
                 "artifacts.preview": "artifacts.preview";
                 "markdown.document-view": "markdown.document-view";
+                "references.open": "references.open";
                 "billing.read": "billing.read";
                 "automations.read": "automations.read";
                 "automations.run": "automations.run";

package/dist/kay-agent-testing.js

@@ -124,14 +124,15 @@ function createKayPluginLog(write, bound = {}) {
 
 // packages/plugin-sdk/dist/kay-agent/declared-tool.js
 function permissionHint(permission) {
-  const { kind, ruleKey, resourceArgs } = permission;
+  const { kind, ruleKey, resourceArgs, scheme, resourcePrefix } = permission;
   return {
     kind,
+    ...scheme === void 0 ? {} : { scheme },
     ...ruleKey === void 0 ? {} : { ruleKey },
     ...resourceArgs === void 0 ? {} : {
       deriveResources: (input) => resourceArgs.flatMap((arg) => {
         const value = input[arg];
-        return typeof value === "string" ? [value] : [];
+        return typeof value === "string" ? [`${resourcePrefix ?? ""}${value}`] : [];
       })
     }
   };
@@ -146,6 +147,9 @@ function declaredToolDefinition(tool, execute) {
     label: tool.displayName ?? tool.toolName,
     description,
     parameters,
+    ...tool.executionMode === void 0 ? {} : { executionMode: tool.executionMode },
+    ...tool.promptSnippet === void 0 ? {} : { promptSnippet: tool.promptSnippet },
+    ...tool.promptGuidelines === void 0 ? {} : { promptGuidelines: tool.promptGuidelines },
     ...requiresAuth === void 0 ? {} : {
       requiresAuth: {
         serviceId: requiresAuth.serviceId,

package/dist/kay-agent.d.ts

@@ -2746,8 +2746,15 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  *
  * 0.41.0 adds app.mcp.callTool for background calls to a plugin's own manifest-declared MCP
  * servers, using Bonsai's managed connection without a session or working directory (#16172).
+ *
+ * 0.42.0 hands background work the shared ResolvedCredential in auth.credential. Workflow
+ * accounts carry auth resolution outcomes, and Poller callbacks receive only the credential.
+ * Older SDK ranges are refused because their background success shape is no longer served.
+ *
+ * 0.42.1 adds current-session tool lifetimes and invocation-bound artifact reads/new outputs,
+ * plus described-tool execution, guidance and permission resource metadata.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.41.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.42.1";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -3225,8 +3232,42 @@ export declare interface KayAgentProcessRunResult {
     readonly stderrTruncated?: boolean;
 }
 
+/** A loaded session's volatile lifetime. Reopening a released session gets a fresh key. */
+export declare interface KayAgentSession {
+    readonly key: string;
+    /** Registers synchronous cleanup, invoked once on release. Returns an unregister function. */
+    onDispose(disposer: () => void): () => void;
+    /** Valid only while this tool call is active. */
+    readonly artifacts: KayAgentSessionArtifacts;
+}
+
+/** Metadata returned by a current-session artifact operation; no filesystem authority. */
+export declare interface KayAgentSessionArtifact {
+    readonly uri: string;
+    readonly name: string;
+    readonly mimeType?: string;
+}
+
+/** Current-session file access, authorized at each call; never retained between tool calls. */
+export declare interface KayAgentSessionArtifacts {
+    readBytes(input: {
+        readonly uri: string;
+        readonly maxBytes?: number;
+    }): Promise<KayAgentSessionArtifact & {
+        readonly bytes: Uint8Array;
+    }>;
+    publishNew(input: {
+        readonly name: string;
+        readonly bytes: Uint8Array;
+    }): Promise<KayAgentSessionArtifact>;
+}
+
+export declare type KayAgentToolContext = Parameters<ToolDefinition["execute"]>[4] & {
+    readonly session?: KayAgentSession;
+};
+
 /** The `execute` a plugin supplies for a tool its manifest describes. */
-export declare type KayAgentToolExecute = ToolDefinition["execute"];
+export declare type KayAgentToolExecute = (toolCallId: string, params: Parameters<ToolDefinition["execute"]>[1], signal: AbortSignal | undefined, onUpdate: Parameters<ToolDefinition["execute"]>[3], ctx: KayAgentToolContext) => ReturnType<ToolDefinition["execute"]>;
 
 /**
  * The facts a plugin declares about a URI module in its manifest (`contributes.uriModules[]`), so
@@ -3461,13 +3502,14 @@ export declare interface KayAppUserFileEntry {
  * The plugin-facing user-files contract: file I/O in folders the user owns, done by the host on
  * its own worker threads.
  *
- * Ungated and always present, like `app.paths`. It confers no authority: a plugin runs in the
- * daemon's process and can call `node:fs` itself. What the door adds is where the work runs. A
- * `node:fs` sync call blocks the daemon's event loop for as long as the path takes to answer,
- * which under a macOS-protected folder or on a drive that stopped answering can be a very long
- * time (kay#11575); an async one holds a thread of the pool the whole daemon shares. The host runs
- * each request on a dedicated worker, gives it a deadline, and answers a typed result instead of
- * throwing.
+ * Ungated and always present, like `app.paths`. It confers no authority: the process a plugin
+ * runs in, the daemon or the plugin host, could call `node:fs` itself. What the door adds is where
+ * the work runs. A `node:fs` sync call blocks that process's event loop for as long as the path
+ * takes to answer, which under a macOS-protected folder or on a drive that stopped answering can
+ * be a very long time (kay#11575); an async one holds a thread of the pool the whole process
+ * shares. The daemon's user-files service runs each request on a dedicated worker, gives it a
+ * deadline, and answers a typed result instead of throwing. A plugin in the plugin host reaches
+ * the same service: each call is sent to the daemon and answered from there.
  *
  * This is a leaf module. It lives beside both target SDKs, like `time.ts`, so the `kay.agent` SDK
  * exposes the same door without importing the `kay.app` surface.
@@ -3508,7 +3550,12 @@ export declare interface KayAppUserFiles {
 }
 
 export declare interface KayAppUserFilesCallOptions {
-    /** Deadline in milliseconds from the call, waiting included. Default 5000, at most 60000. */
+    /**
+     * Deadline in milliseconds, waiting included. Default 5000, at most 60000. It starts when the
+     * daemon's user-files service receives the request: from the call in the daemon, or, for a
+     * plugin in the plugin host, once the request has crossed to the daemon. A daemon that never
+     * reads the request leaves the call waiting until the host's connection to it is closed.
+     */
     readonly timeoutMs?: number;
     readonly signal?: AbortSignal;
 }
@@ -5129,6 +5176,21 @@ declare const PluginCapabilityRefusalV1: z.ZodObject<{
         envelope: z.ZodObject<{
             source: z.ZodString;
         }, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        target: z.ZodLiteral<"kay.agent">;
+        slug: z.ZodLiteral<"session-artifacts.read">;
+        envelope: z.ZodObject<{
+            kind: z.ZodEnum<{
+                output: "output";
+                upload: "upload";
+            }>;
+        }, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        target: z.ZodLiteral<"kay.agent">;
+        slug: z.ZodLiteral<"session-artifacts.create">;
+        envelope: z.ZodObject<{
+            kind: z.ZodLiteral<"output">;
+        }, z.core.$strict>;
     }, z.core.$strict>, z.ZodObject<{
         target: z.ZodLiteral<"kay.app">;
         slug: z.ZodLiteral<"artifacts.read">;
@@ -5473,7 +5535,7 @@ declare const PluginTargetName: z.ZodEnum<{
 declare type PluginTargetName = z.infer<typeof PluginTargetName>;
 
 export declare type PluginToolDefinition<TParams extends ToolParametersWire = ToolParametersWire, TDetails = unknown> = Omit<ToolDefinition<TParams, TDetails>, "execute"> & {
-    readonly execute: (toolCallId: string, params: ToolExecutionAwareParams<InferToolInput<TParams>>, signal: AbortSignal | undefined, onUpdate: AgentToolUpdateCallback<TDetails> | undefined, ctx: ToolContext) => Promise<AgentToolResult<TDetails>>;
+    readonly execute: (toolCallId: string, params: ToolExecutionAwareParams<InferToolInput<TParams>>, signal: AbortSignal | undefined, onUpdate: AgentToolUpdateCallback<TDetails> | undefined, ctx: KayAgentToolContext) => Promise<AgentToolResult<TDetails>>;
 };
 
 declare const PluginToolName: z.ZodString;
@@ -9200,7 +9262,7 @@ export declare interface ToolDefinition<TParams extends ToolParametersWire = Too
  * The `execute` of a described tool for {@link KayAgentPluginApi.implementTool}: `body` receives
  * the call's arguments parsed by `schema`, the schema the manifest's `parameters` came from.
  */
-export declare function toolExecute<TSchema extends z_2.ZodType>(schema: TSchema, body: (toolCallId: string, input: z_2.output<TSchema>, signal: AbortSignal | undefined, onUpdate: AgentToolUpdateCallback<unknown> | undefined, ctx: ToolContext) => Promise<AgentToolResult<unknown>>): KayAgentToolExecute;
+export declare function toolExecute<TSchema extends z_2.ZodType>(schema: TSchema, body: (toolCallId: string, input: z_2.output<TSchema>, signal: AbortSignal | undefined, onUpdate: AgentToolUpdateCallback<unknown> | undefined, ctx: KayAgentToolContext) => Promise<AgentToolResult<unknown>>): KayAgentToolExecute;
 
 /** Runtime execute input shape that always allows reserved execution directives. */
 export declare type ToolExecutionAwareParams<T> = T & {

package/dist/kay-app.d.ts

@@ -2722,8 +2722,15 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  *
  * 0.41.0 adds app.mcp.callTool for background calls to a plugin's own manifest-declared MCP
  * servers, using Bonsai's managed connection without a session or working directory (#16172).
+ *
+ * 0.42.0 hands background work the shared ResolvedCredential in auth.credential. Workflow
+ * accounts carry auth resolution outcomes, and Poller callbacks receive only the credential.
+ * Older SDK ranges are refused because their background success shape is no longer served.
+ *
+ * 0.42.1 adds current-session tool lifetimes and invocation-bound artifact reads/new outputs,
+ * plus described-tool execution, guidance and permission resource metadata.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.41.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.42.1";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -3932,7 +3939,7 @@ export declare interface KayAppAutomationUriChangeCondition {
 
 /** Exact-account credential resolution for a plugin's durable background jobs. */
 export declare interface KayAppBackgroundAuth {
-    resolveCredential(request: KayAppBackgroundCredentialRequest): Promise<KayAppBackgroundCredentialResult>;
+    resolveCredential(request: KayAppBackgroundCredentialRequest): Promise<KayAppCredentialResolution>;
 }
 
 /** A credential request for durable background work bound to one known account. */
@@ -3948,21 +3955,6 @@ export declare interface KayAppBackgroundCredentialRequest {
     readonly jobId: string;
 }
 
-/** The non-secret outcome of a durable background credential lookup. */
-export declare type KayAppBackgroundCredentialResult = {
-    readonly status: "resolved";
-    readonly accessToken: string;
-    readonly accountId: string;
-    readonly scopes: readonly string[];
-} | {
-    readonly status: "missing";
-    readonly reason: string;
-} | {
-    readonly status: "requires-auth";
-    readonly reason: string;
-    readonly requiredScopes?: readonly string[];
-};
-
 /**
  * The `kay.app` system-prompt contract (`app.systemPrompt`): text a plugin adds to every chat's
  * system prompt, rendered by the daemon from a few facts about the chat and reused across chats.
@@ -4114,6 +4106,19 @@ export declare class KayAppCredentialRejectedError extends Error {
     readonly name = "KayAppCredentialRejectedError";
 }
 
+/** A credential for this call, or an account failure with no secret material. Never persist it. */
+export declare type KayAppCredentialResolution = {
+    readonly status: "resolved";
+    readonly credential: ResolvedCredential;
+} | {
+    readonly status: "missing";
+    readonly reason: string;
+} | {
+    readonly status: "requires-auth";
+    readonly reason: string;
+    readonly requiredScopes?: readonly string[];
+};
+
 export declare interface KayAppData {
     /**
      * Register the live definition behind one declared source. At most one registration per source
@@ -4359,18 +4364,17 @@ export declare interface KayAppDynamicContextSearchOptions {
     } | undefined;
 }
 
-/**
- * The app-wide endpoint bus. A plugin registers named handlers a consuming surface can invoke; the
- * host routes invocations (e.g. Bonsai Desktop forwards the renderer's frame-gated call to the daemon,
- * where the endpoint is single-homed). The corpus is NEVER reachable here - only what the plugin
- * explicitly exposes. Both `payload` and the handler's return ride strict JSON on the wire.
- */
+/** Per-invocation authority prepared from the endpoint's manifest declaration. */
+export declare interface KayAppEndpointContext {
+    readonly credentials: readonly KayAppResolvedCredential[];
+    readonly signal: AbortSignal;
+    /** Record only a scheme from this call's credentials after its provider operation succeeds. */
+    reportWorked(schemeId: string): void;
+}
+
+/** The app-wide endpoint bus; payloads and returned values must be JSON. */
 export declare interface KayAppEndpoints {
-    /**
-     * Register a handler under `name`. Names are app-wide (open bus); a duplicate name is rejected by
-     * the host registry.
-     */
-    register(name: string, handler: (payload: unknown) => unknown | Promise<unknown>): void;
+    register(name: string, handler: (payload: unknown, context: KayAppEndpointContext) => unknown | Promise<unknown>): void;
 }
 
 /**
@@ -5407,9 +5411,7 @@ export declare interface KayAppPollerOptions<Cursor extends JsonValue> {
     readonly poll: (input: {
         readonly account: KayAppAccountSummary;
         readonly cursor: Cursor | undefined;
-        readonly credential: Extract<KayAppBackgroundCredentialResult, {
-            readonly status: "resolved";
-        }>;
+        readonly credential: ResolvedCredential;
         readonly runId: string;
     }) => Promise<KayAppPollResult<Cursor>>;
 }
@@ -5564,50 +5566,7 @@ export declare interface KayAppResolveCredentialRequest {
     readonly purpose: string;
 }
 
-/**
- * ---
- * responsibility: The plugin-facing credential surface of the `kay.app` target SDK. A daemon-hosted
- *   plugin lists account metadata or resolves credentials for an owned or consumed auth service
- *   under explicit grants. Credential material is read where the work happens.
- * owns:
- *   - {@link KayAppAuth}, {@link KayAppResolvedCredential}.
- * does_not_own:
- *   - Acquisition, storage, refresh, or revocation. Those are the credential authority's, reached
- *     through the host. A plugin can only ask for material it is granted, for a purpose it declared.
- * ---
- *
- * ## Deny-by-default
- *
- * `KayAppPluginApi.auth` is **present only for plugins the host grants** (`auth.operations`
- * containing `"list"` or `"resolve"` in `permissions.byTarget["kay.app"]`, against an owned or consumed
- * service) and `undefined` otherwise - an ungranted plugin cannot even reference the capability.
- * This mirrors `KayAppPluginApi.sessions`, and it is the rule for every capability behind a grant:
- * never hand a plugin an object whose grant is decorative.
- *
- * ## Secrets do not leave this object
- *
- * A resolved credential is live secret material. Never log it, never echo it into an error message,
- * never put it in an event payload, never return it from an endpoint handler, and never accept it
- * as a URI or config value. Read it, use it in the outbound request, drop it.
- */
-/**
- * Live credential material for one account of one auth scheme.
- *
- * Shaped to match the kernel's `ResolvedCredential` so a plugin that already reads
- * `ctx.auth.credential` in a URI verb reads the same thing here.
- */
-export declare interface KayAppResolvedCredential {
-    /** Bearer for OAuth schemes, the api key for api-key schemes. Host-resolved and refreshed. */
-    readonly accessToken: string;
-    readonly accountId: string;
-    readonly schemeId: string;
-    readonly scopes?: readonly string[];
-    /**
-     * Every value of a multi-field api-key credential, keyed by the scheme's declared field id
-     * (`accessToken` mirrors the primary field). Absent for single-secret schemes.
-     */
-    readonly fields?: Readonly<Record<string, string>>;
-}
+export declare type KayAppResolvedCredential = ResolvedCredential;
 
 /** Hard limits on the routes a `tier` or `model` selection may use. */
 export declare interface KayAppRouteConstraints {
@@ -7970,13 +7929,14 @@ export declare interface KayAppUserFileEntry {
  * The plugin-facing user-files contract: file I/O in folders the user owns, done by the host on
  * its own worker threads.
  *
- * Ungated and always present, like `app.paths`. It confers no authority: a plugin runs in the
- * daemon's process and can call `node:fs` itself. What the door adds is where the work runs. A
- * `node:fs` sync call blocks the daemon's event loop for as long as the path takes to answer,
- * which under a macOS-protected folder or on a drive that stopped answering can be a very long
- * time (kay#11575); an async one holds a thread of the pool the whole daemon shares. The host runs
- * each request on a dedicated worker, gives it a deadline, and answers a typed result instead of
- * throwing.
+ * Ungated and always present, like `app.paths`. It confers no authority: the process a plugin
+ * runs in, the daemon or the plugin host, could call `node:fs` itself. What the door adds is where
+ * the work runs. A `node:fs` sync call blocks that process's event loop for as long as the path
+ * takes to answer, which under a macOS-protected folder or on a drive that stopped answering can
+ * be a very long time (kay#11575); an async one holds a thread of the pool the whole process
+ * shares. The daemon's user-files service runs each request on a dedicated worker, gives it a
+ * deadline, and answers a typed result instead of throwing. A plugin in the plugin host reaches
+ * the same service: each call is sent to the daemon and answered from there.
  *
  * This is a leaf module. It lives beside both target SDKs, like `time.ts`, so the `kay.agent` SDK
  * exposes the same door without importing the `kay.app` surface.
@@ -8017,7 +7977,12 @@ export declare interface KayAppUserFiles {
 }
 
 export declare interface KayAppUserFilesCallOptions {
-    /** Deadline in milliseconds from the call, waiting included. Default 5000, at most 60000. */
+    /**
+     * Deadline in milliseconds, waiting included. Default 5000, at most 60000. It starts when the
+     * daemon's user-files service receives the request: from the call in the daemon, or, for a
+     * plugin in the plugin host, once the request has crossed to the daemon. A daemon that never
+     * reads the request leaves the call waiting until the host's connection to it is closed.
+     */
     readonly timeoutMs?: number;
     readonly signal?: AbortSignal;
 }
@@ -8145,7 +8110,7 @@ export declare interface KayAppWhiteboardTypes {
  */
 export declare interface KayAppWorkflowAccount {
     readonly account: KayAppAccountSummary;
-    readonly credential: KayAppBackgroundCredentialResult;
+    readonly auth: KayAppCredentialResolution;
 }
 
 /**
@@ -10314,7 +10279,7 @@ export declare function requireWriteContent(payload: UriPayload | Uint8Array | u
  * verb (`ctx.auth.credential`), a tool (`ctx.credential`) or a search provider (`ctx.credential`).
  * Plain data, so it crosses a process boundary with the call; plugin code never asks for one.
  */
-declare interface ResolvedCredential {
+export declare interface ResolvedCredential {
     /** Bearer for OAuth schemes, apiKey for api-key schemes. Host-resolved and refreshed. */
     readonly accessToken: string;
     readonly accountId: string;
@@ -16963,6 +16928,9 @@ declare const WithElementList_0: (input: string, result?: unknown[]) => [unknown
 
 declare function WithElementListMapping(input: [unknown, unknown, unknown] | []): unknown;
 
+/** Try the call's credentials in order; only credential rejection advances to the next. */
+export declare function withEndpointCredential<T>(context: KayAppEndpointContext, use: (credential: KayAppResolvedCredential) => Promise<T>): Promise<T>;
+
 declare function WithMapping(input: [unknown, unknown] | []): unknown;
 
 declare const WithNull: (input: string) => [unknown, string] | [];

package/dist/kay-app.js

@@ -599,11 +599,6 @@ function payload(name, schema, options = {}) {
   };
 }
 
-// packages/plugin-sdk/dist/kay-app/account.js
-function isRetryable(result) {
-  return result.status === "not-ready";
-}
-
 // packages/plugin-sdk/dist/kay-app/auth.js
 var KayAppCredentialRejectedError = class extends Error {
   name = "KayAppCredentialRejectedError";
@@ -626,6 +621,32 @@ async function withCredential(auth, request, use) {
   throw rejection ?? new Error(`No credential is resolvable for '${request.serviceId}'.`);
 }
 
+// packages/plugin-sdk/dist/kay-app/endpoints.js
+async function withEndpointCredential(context, use) {
+  let rejection;
+  for (const credential of context.credentials) {
+    context.signal.throwIfAborted();
+    try {
+      const result = await use(credential);
+      try {
+        context.reportWorked(credential.schemeId);
+      } catch {
+      }
+      return result;
+    } catch (error) {
+      if (!(error instanceof KayAppCredentialRejectedError))
+        throw error;
+      rejection = error;
+    }
+  }
+  throw rejection ?? new Error("No credential is resolvable for this endpoint.");
+}
+
+// packages/plugin-sdk/dist/kay-app/account.js
+function isRetryable(result) {
+  return result.status === "not-ready";
+}
+
 // packages/plugin-sdk/dist/kay-app/automations.js
 var KAY_APP_AUTOMATION_CONDITION_KINDS = [
   "time",
@@ -715,7 +736,7 @@ function definePoller(app, localId, options) {
     let skipped = 0;
     let failed = 0;
     let refused = 0;
-    for (const { account, credential } of accounts) {
+    for (const { account, auth } of accounts) {
       const saved = previous.find((entry) => entry.schemeId === account.schemeId && entry.accountId === account.accountId);
       const name = `${account.schemeId}/${account.accountId}`;
       const keepSaved = (summary) => {
@@ -723,9 +744,9 @@ function definePoller(app, localId, options) {
           next.push(saved);
         details.push(`${name}: ${summary}`);
       };
-      if (credential.status !== "resolved") {
+      if (auth.status !== "resolved") {
         skipped++;
-        keepSaved(credential.status === "requires-auth" ? "Sign-in or required scope missing" : "Credential missing");
+        keepSaved(auth.status === "requires-auth" ? "Sign-in or required scope missing" : "Credential missing");
         continue;
       }
       let result;
@@ -733,7 +754,7 @@ function definePoller(app, localId, options) {
         result = await options.poll({
           account,
           cursor: structuredClone(saved?.cursor),
-          credential,
+          credential: auth.credential,
           runId
         });
       } catch {
@@ -964,5 +985,6 @@ export {
   transcriptMessageText,
   transcriptMessageTexts,
   transcriptRoleLabel,
-  withCredential
+  withCredential,
+  withEndpointCredential
 };

package/package.json

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