@yaklabs-ai/plugin-sdk 0.42.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.42.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.42.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.42.0",
+  "version": "0.42.1",
   "target": "npm",
   "firstPartyLicense": "MIT",
   "bundled": [

package/dist/disclosure.d.ts

@@ -2421,8 +2421,11 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 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.42.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.42.1";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -2871,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}.
@@ -3089,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.
@@ -3136,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;
@@ -2475,8 +2475,11 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 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.42.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.42.1";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -2922,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}.
@@ -3140,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.
@@ -3187,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;
 }
@@ -5499,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>;
@@ -5511,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;

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

@@ -2750,8 +2750,11 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 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.42.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.42.1";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -3229,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
@@ -3465,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.
@@ -3512,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;
 }
@@ -5133,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">;
@@ -5477,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;
@@ -9204,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

@@ -2726,8 +2726,11 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 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.42.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.42.1";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -7926,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.
@@ -7973,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;
 }

package/package.json

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