@yaklabs-ai/plugin-sdk 0.12.4 → 0.12.5

package/README.md

@@ -13,7 +13,7 @@ it under the name your plugin code actually imports:
 ```json
 {
   "dependencies": {
-    "@kay/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.12.4"
+    "@kay/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.12.5"
   }
 }
 ```

package/THIRD-PARTY-INVENTORY.json

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

package/dist/disclosure.d.ts

@@ -1266,6 +1266,14 @@ declare interface KayAgentPluginApi {
      * the same zone-of-record port the session stamp uses; see {@link KayAppTime.snapshot}.
      */
     readonly time: KayAppTime;
+    /**
+     * File I/O in user folders, run by the host on its own worker threads under a deadline and
+     * answered as a typed result. Always present and ungated: unlike {@link filesystem} it takes
+     * absolute paths and checks no grant, because it adds no authority a plugin's `node:fs` does not
+     * already have. What it adds is that a slow or unresponsive folder never blocks the daemon. See
+     * {@link KayAppUserFiles}.
+     */
+    readonly userFiles: KayAppUserFiles;
     /**
      * Publish the plugin's declared events, for example so a default notification rule can tell the
      * user what the agent just did. Always present, like {@link withJev}: there is nothing to
@@ -1570,6 +1578,135 @@ declare interface KayAppTimeSnapshot {
     readonly zoneSource: "host" | "utc-fallback";
 }
 
+declare interface KayAppUserFileEntry {
+    readonly name: string;
+    /** From the directory entry itself: a symlink is reported as `symlink`, never followed. */
+    readonly kind: KayAppUserFileKind;
+}
+
+/**
+ * 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.
+ *
+ * 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.
+ */
+declare type KayAppUserFileKind = "file" | "directory" | "symlink" | "other";
+
+declare interface KayAppUserFileListing {
+    readonly entries: readonly KayAppUserFileEntry[];
+    /** True when the directory had more entries than `maxEntries`; the rest were not read. */
+    readonly entryLimitReached: boolean;
+}
+
+/**
+ * File I/O in user folders, run by the host off the daemon's main thread. Every path is absolute.
+ * No method rejects; each answers a {@link KayAppUserFilesResult}. This is not a sandbox: it does
+ * not limit which paths a plugin may touch. Added in SDK 0.12.5: a plugin that calls it declares
+ * `compatibility.sdk` `^0.12.5`, so an older Bonsai refuses a directory or repository plugin at
+ * load instead of the call failing.
+ */
+declare interface KayAppUserFiles {
+    /** Follows symlinks. */
+    stat(path: string, options?: KayAppUserFilesCallOptions): Promise<KayAppUserFilesResult<KayAppUserFileStat>>;
+    /** UTF-8. */
+    readText(path: string, options?: KayAppUserFilesReadTextOptions): Promise<KayAppUserFilesResult<string>>;
+    list(path: string, options?: KayAppUserFilesListOptions): Promise<KayAppUserFilesResult<KayAppUserFileListing>>;
+    /** Depth-first below `path`; symlinks are reported, never followed. */
+    walk(path: string, options?: KayAppUserFilesWalkOptions): Promise<KayAppUserFilesResult<KayAppUserFileWalk>>;
+    /** The path with every symlink resolved. */
+    realpath(path: string, options?: KayAppUserFilesCallOptions): Promise<KayAppUserFilesResult<string>>;
+    /**
+     * Creates or replaces a UTF-8 file, not atomically. After `timeout` or `aborted` the write may
+     * still happen.
+     */
+    writeText(path: string, content: string, options?: KayAppUserFilesCallOptions): Promise<KayAppUserFilesResult<null>>;
+    /** Creates the directory and any missing parents; succeeds when it already exists. */
+    mkdir(path: string, options?: KayAppUserFilesCallOptions): Promise<KayAppUserFilesResult<null>>;
+    rename(from: string, to: string, options?: KayAppUserFilesCallOptions): Promise<KayAppUserFilesResult<null>>;
+}
+
+declare interface KayAppUserFilesCallOptions {
+    /** Deadline in milliseconds from the call, waiting included. Default 5000, at most 60000. */
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+
+declare interface KayAppUserFilesListOptions extends KayAppUserFilesCallOptions {
+    /** Default 5000, at most 50000. */
+    readonly maxEntries?: number;
+}
+
+declare interface KayAppUserFilesReadTextOptions extends KayAppUserFilesCallOptions {
+    /** A larger file answers `error` with code `EFBIG`. Default 8 MiB, at most 64 MiB. */
+    readonly maxBytes?: number;
+}
+
+/**
+ * Every answer. `missing`: nothing exists at the path (ENOENT). `timeout`: no answer from the path
+ * in time. Its `reason` is `deadline` (this request ran out of time), `cooling-down` (a request at
+ * or above this path timed out recently, so the host did not try) or `saturated` (the host's
+ * workers are stuck on other paths, so it did not try). `aborted`: the caller's signal fired.
+ * `error`: anything else, with the Node error `code` when there is one (`EACCES`, `EISDIR`,
+ * `EFBIG` for a file over `maxBytes`, `EINVAL` for a relative path).
+ */
+declare type KayAppUserFilesResult<T> = {
+    readonly kind: "ok";
+    readonly value: T;
+} | {
+    readonly kind: "missing";
+} | {
+    readonly kind: "timeout";
+    readonly reason: "deadline" | "cooling-down" | "saturated";
+    readonly detail: string;
+} | {
+    readonly kind: "aborted";
+} | {
+    readonly kind: "error";
+    readonly code?: string;
+    readonly detail: string;
+};
+
+declare interface KayAppUserFileStat {
+    /** What the path is after following symlinks; never `symlink`. */
+    readonly kind: "file" | "directory" | "other";
+    /** Bytes. */
+    readonly size: number;
+    /** Milliseconds since the Unix epoch. */
+    readonly modifiedAtMs: number;
+}
+
+declare interface KayAppUserFilesWalkOptions extends KayAppUserFilesCallOptions {
+    /** Default 10000, at most 100000. */
+    readonly maxEntries?: number;
+    /** Deepest level reported; the root's children are depth 1. Default 16, at most 64. */
+    readonly maxDepth?: number;
+    /** Report and descend into dot-prefixed entries. Default true. */
+    readonly includeHidden?: boolean;
+}
+
+declare interface KayAppUserFileWalk {
+    readonly entries: readonly KayAppUserFileWalkEntry[];
+    /** True when the walk stopped at `maxEntries`. */
+    readonly entryLimitReached: boolean;
+    /** True when a directory at `maxDepth` was reported but not descended into. */
+    readonly depthLimitReached: boolean;
+}
+
+declare interface KayAppUserFileWalkEntry {
+    /** Path segments below the walk's root. */
+    readonly segments: readonly string[];
+    readonly kind: KayAppUserFileKind;
+}
+
 declare type KnownApi = "openai-completions" | "mistral-conversations" | "openai-responses" | "azure-openai-responses" | "openai-codex-responses" | "anthropic-messages" | "bedrock-converse-stream" | "google-generative-ai" | "google-vertex" | "pi-messages";
 
 declare type KnownProvider = "amazon-bedrock" | "ant-ling" | "anthropic" | "google" | "google-vertex" | "openai" | "azure-openai-responses" | "openai-codex" | "radius" | "typesafe" | "nvidia" | "deepseek" | "github-copilot" | "xai" | "groq" | "cerebras" | "openrouter" | "vercel-ai-gateway" | "zai" | "zai-coding-cn" | "mistral" | "minimax" | "minimax-cn" | "moonshotai" | "moonshotai-cn" | "huggingface" | "fireworks" | "together" | "baseten" | "opencode" | "opencode-go" | "kimi-coding" | "meta" | "cloudflare-workers-ai" | "cloudflare-ai-gateway" | "qwen-token-plan" | "qwen-token-plan-cn" | "qwen-token-plan-individual" | "xiaomi" | "xiaomi-token-plan-cn" | "xiaomi-token-plan-ams" | "xiaomi-token-plan-sgp";

package/dist/disclosure.js

@@ -824,6 +824,17 @@ function createKayAgentProbeCapabilityHandles() {
     // real capability keeps for a zone the host cannot read.
     time: {
       snapshot: () => ({ nowMs: 0, zone: "UTC", zoneSource: "utc-fallback" })
+    },
+    // Inert like the filesystem broker: a probe must never touch the user's disk.
+    userFiles: {
+      stat: inertResult,
+      readText: inertResult,
+      list: inertResult,
+      walk: inertResult,
+      realpath: inertResult,
+      writeText: inertResult,
+      mkdir: inertResult,
+      rename: inertResult
     }
   };
 }

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

@@ -531,7 +531,7 @@ declare interface ExtensionPaths {
 export declare function fauxAuthContext(overrides?: Partial<ExtensionAuthContext>): ExtensionAuthContext;
 
 /** The capability handles a `KayAgentPluginApi` always carries — authority is decided per call. */
-export declare type FauxKayAgentCapabilities = Pick<KayAgentPluginApi, "filesystem" | "network" | "webSession" | "process" | "whiteboard" | "interaction" | "interceptToolCall" | "withJev" | "events" | "time">;
+export declare type FauxKayAgentCapabilities = Pick<KayAgentPluginApi, "filesystem" | "network" | "webSession" | "process" | "whiteboard" | "interaction" | "interceptToolCall" | "withJev" | "events" | "time" | "userFiles">;
 
 export declare function fauxKayAgentCapabilities(): FauxKayAgentCapabilities;
 
@@ -1167,6 +1167,14 @@ declare interface KayAgentPluginApi {
      * the same zone-of-record port the session stamp uses; see {@link KayAppTime.snapshot}.
      */
     readonly time: KayAppTime;
+    /**
+     * File I/O in user folders, run by the host on its own worker threads under a deadline and
+     * answered as a typed result. Always present and ungated: unlike {@link filesystem} it takes
+     * absolute paths and checks no grant, because it adds no authority a plugin's `node:fs` does not
+     * already have. What it adds is that a slow or unresponsive folder never blocks the daemon. See
+     * {@link KayAppUserFiles}.
+     */
+    readonly userFiles: KayAppUserFiles;
     /**
      * Publish the plugin's declared events, for example so a default notification rule can tell the
      * user what the agent just did. Always present, like {@link withJev}: there is nothing to
@@ -1471,6 +1479,135 @@ declare interface KayAppTimeSnapshot {
     readonly zoneSource: "host" | "utc-fallback";
 }
 
+declare interface KayAppUserFileEntry {
+    readonly name: string;
+    /** From the directory entry itself: a symlink is reported as `symlink`, never followed. */
+    readonly kind: KayAppUserFileKind;
+}
+
+/**
+ * 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.
+ *
+ * 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.
+ */
+declare type KayAppUserFileKind = "file" | "directory" | "symlink" | "other";
+
+declare interface KayAppUserFileListing {
+    readonly entries: readonly KayAppUserFileEntry[];
+    /** True when the directory had more entries than `maxEntries`; the rest were not read. */
+    readonly entryLimitReached: boolean;
+}
+
+/**
+ * File I/O in user folders, run by the host off the daemon's main thread. Every path is absolute.
+ * No method rejects; each answers a {@link KayAppUserFilesResult}. This is not a sandbox: it does
+ * not limit which paths a plugin may touch. Added in SDK 0.12.5: a plugin that calls it declares
+ * `compatibility.sdk` `^0.12.5`, so an older Bonsai refuses a directory or repository plugin at
+ * load instead of the call failing.
+ */
+declare interface KayAppUserFiles {
+    /** Follows symlinks. */
+    stat(path: string, options?: KayAppUserFilesCallOptions): Promise<KayAppUserFilesResult<KayAppUserFileStat>>;
+    /** UTF-8. */
+    readText(path: string, options?: KayAppUserFilesReadTextOptions): Promise<KayAppUserFilesResult<string>>;
+    list(path: string, options?: KayAppUserFilesListOptions): Promise<KayAppUserFilesResult<KayAppUserFileListing>>;
+    /** Depth-first below `path`; symlinks are reported, never followed. */
+    walk(path: string, options?: KayAppUserFilesWalkOptions): Promise<KayAppUserFilesResult<KayAppUserFileWalk>>;
+    /** The path with every symlink resolved. */
+    realpath(path: string, options?: KayAppUserFilesCallOptions): Promise<KayAppUserFilesResult<string>>;
+    /**
+     * Creates or replaces a UTF-8 file, not atomically. After `timeout` or `aborted` the write may
+     * still happen.
+     */
+    writeText(path: string, content: string, options?: KayAppUserFilesCallOptions): Promise<KayAppUserFilesResult<null>>;
+    /** Creates the directory and any missing parents; succeeds when it already exists. */
+    mkdir(path: string, options?: KayAppUserFilesCallOptions): Promise<KayAppUserFilesResult<null>>;
+    rename(from: string, to: string, options?: KayAppUserFilesCallOptions): Promise<KayAppUserFilesResult<null>>;
+}
+
+declare interface KayAppUserFilesCallOptions {
+    /** Deadline in milliseconds from the call, waiting included. Default 5000, at most 60000. */
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+
+declare interface KayAppUserFilesListOptions extends KayAppUserFilesCallOptions {
+    /** Default 5000, at most 50000. */
+    readonly maxEntries?: number;
+}
+
+declare interface KayAppUserFilesReadTextOptions extends KayAppUserFilesCallOptions {
+    /** A larger file answers `error` with code `EFBIG`. Default 8 MiB, at most 64 MiB. */
+    readonly maxBytes?: number;
+}
+
+/**
+ * Every answer. `missing`: nothing exists at the path (ENOENT). `timeout`: no answer from the path
+ * in time. Its `reason` is `deadline` (this request ran out of time), `cooling-down` (a request at
+ * or above this path timed out recently, so the host did not try) or `saturated` (the host's
+ * workers are stuck on other paths, so it did not try). `aborted`: the caller's signal fired.
+ * `error`: anything else, with the Node error `code` when there is one (`EACCES`, `EISDIR`,
+ * `EFBIG` for a file over `maxBytes`, `EINVAL` for a relative path).
+ */
+declare type KayAppUserFilesResult<T> = {
+    readonly kind: "ok";
+    readonly value: T;
+} | {
+    readonly kind: "missing";
+} | {
+    readonly kind: "timeout";
+    readonly reason: "deadline" | "cooling-down" | "saturated";
+    readonly detail: string;
+} | {
+    readonly kind: "aborted";
+} | {
+    readonly kind: "error";
+    readonly code?: string;
+    readonly detail: string;
+};
+
+declare interface KayAppUserFileStat {
+    /** What the path is after following symlinks; never `symlink`. */
+    readonly kind: "file" | "directory" | "other";
+    /** Bytes. */
+    readonly size: number;
+    /** Milliseconds since the Unix epoch. */
+    readonly modifiedAtMs: number;
+}
+
+declare interface KayAppUserFilesWalkOptions extends KayAppUserFilesCallOptions {
+    /** Default 10000, at most 100000. */
+    readonly maxEntries?: number;
+    /** Deepest level reported; the root's children are depth 1. Default 16, at most 64. */
+    readonly maxDepth?: number;
+    /** Report and descend into dot-prefixed entries. Default true. */
+    readonly includeHidden?: boolean;
+}
+
+declare interface KayAppUserFileWalk {
+    readonly entries: readonly KayAppUserFileWalkEntry[];
+    /** True when the walk stopped at `maxEntries`. */
+    readonly entryLimitReached: boolean;
+    /** True when a directory at `maxDepth` was reported but not descended into. */
+    readonly depthLimitReached: boolean;
+}
+
+declare interface KayAppUserFileWalkEntry {
+    /** Path segments below the walk's root. */
+    readonly segments: readonly string[];
+    readonly kind: KayAppUserFileKind;
+}
+
 declare type KnownApi = "openai-completions" | "mistral-conversations" | "openai-responses" | "azure-openai-responses" | "openai-codex-responses" | "anthropic-messages" | "bedrock-converse-stream" | "google-generative-ai" | "google-vertex" | "pi-messages";
 
 declare type KnownProvider = "amazon-bedrock" | "ant-ling" | "anthropic" | "google" | "google-vertex" | "openai" | "azure-openai-responses" | "openai-codex" | "radius" | "typesafe" | "nvidia" | "deepseek" | "github-copilot" | "xai" | "groq" | "cerebras" | "openrouter" | "vercel-ai-gateway" | "zai" | "zai-coding-cn" | "mistral" | "minimax" | "minimax-cn" | "moonshotai" | "moonshotai-cn" | "huggingface" | "fireworks" | "together" | "baseten" | "opencode" | "opencode-go" | "kimi-coding" | "meta" | "cloudflare-workers-ai" | "cloudflare-ai-gateway" | "qwen-token-plan" | "qwen-token-plan-cn" | "qwen-token-plan-individual" | "xiaomi" | "xiaomi-token-plan-cn" | "xiaomi-token-plan-ams" | "xiaomi-token-plan-sgp";

package/dist/kay-agent-testing.js

@@ -135,6 +135,16 @@ var UNWIRED_SURFACE = {
   screenshot: NOT_WIRED,
   open: NOT_WIRED
 };
+var USER_FILE_METHODS = [
+  "stat",
+  "readText",
+  "list",
+  "walk",
+  "realpath",
+  "writeText",
+  "mkdir",
+  "rename"
+];
 function fauxKayAgentCapabilities() {
   return {
     filesystem: {
@@ -191,7 +201,16 @@ function fauxKayAgentCapabilities() {
     // zone-of-record path overrides this handle after the spread.
     time: {
       snapshot: () => ({ nowMs: 0, zone: "UTC", zoneSource: "utc-fallback" })
-    }
+    },
+    // Answers every call `error` naming itself, keeping the real contract's promise never to
+    // reject. A test that exercises a plugin's file I/O overrides this handle after the spread.
+    userFiles: Object.fromEntries(USER_FILE_METHODS.map((name) => [
+      name,
+      async () => ({
+        kind: "error",
+        detail: `userFiles.${name} is not wired in this test double`
+      })
+    ]))
   };
 }
 function defaultTestToolContext() {

package/dist/kay-agent.d.ts

@@ -1628,6 +1628,14 @@ export declare interface KayAgentPluginApi {
      * the same zone-of-record port the session stamp uses; see {@link KayAppTime.snapshot}.
      */
     readonly time: KayAppTime;
+    /**
+     * File I/O in user folders, run by the host on its own worker threads under a deadline and
+     * answered as a typed result. Always present and ungated: unlike {@link filesystem} it takes
+     * absolute paths and checks no grant, because it adds no authority a plugin's `node:fs` does not
+     * already have. What it adds is that a slow or unresponsive folder never blocks the daemon. See
+     * {@link KayAppUserFiles}.
+     */
+    readonly userFiles: KayAppUserFiles;
     /**
      * Publish the plugin's declared events, for example so a default notification rule can tell the
      * user what the agent just did. Always present, like {@link withJev}: there is nothing to
@@ -1946,6 +1954,135 @@ declare interface KayAppTimeSnapshot {
     readonly zoneSource: "host" | "utc-fallback";
 }
 
+export declare interface KayAppUserFileEntry {
+    readonly name: string;
+    /** From the directory entry itself: a symlink is reported as `symlink`, never followed. */
+    readonly kind: KayAppUserFileKind;
+}
+
+/**
+ * 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.
+ *
+ * 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.
+ */
+export declare type KayAppUserFileKind = "file" | "directory" | "symlink" | "other";
+
+export declare interface KayAppUserFileListing {
+    readonly entries: readonly KayAppUserFileEntry[];
+    /** True when the directory had more entries than `maxEntries`; the rest were not read. */
+    readonly entryLimitReached: boolean;
+}
+
+/**
+ * File I/O in user folders, run by the host off the daemon's main thread. Every path is absolute.
+ * No method rejects; each answers a {@link KayAppUserFilesResult}. This is not a sandbox: it does
+ * not limit which paths a plugin may touch. Added in SDK 0.12.5: a plugin that calls it declares
+ * `compatibility.sdk` `^0.12.5`, so an older Bonsai refuses a directory or repository plugin at
+ * load instead of the call failing.
+ */
+export declare interface KayAppUserFiles {
+    /** Follows symlinks. */
+    stat(path: string, options?: KayAppUserFilesCallOptions): Promise<KayAppUserFilesResult<KayAppUserFileStat>>;
+    /** UTF-8. */
+    readText(path: string, options?: KayAppUserFilesReadTextOptions): Promise<KayAppUserFilesResult<string>>;
+    list(path: string, options?: KayAppUserFilesListOptions): Promise<KayAppUserFilesResult<KayAppUserFileListing>>;
+    /** Depth-first below `path`; symlinks are reported, never followed. */
+    walk(path: string, options?: KayAppUserFilesWalkOptions): Promise<KayAppUserFilesResult<KayAppUserFileWalk>>;
+    /** The path with every symlink resolved. */
+    realpath(path: string, options?: KayAppUserFilesCallOptions): Promise<KayAppUserFilesResult<string>>;
+    /**
+     * Creates or replaces a UTF-8 file, not atomically. After `timeout` or `aborted` the write may
+     * still happen.
+     */
+    writeText(path: string, content: string, options?: KayAppUserFilesCallOptions): Promise<KayAppUserFilesResult<null>>;
+    /** Creates the directory and any missing parents; succeeds when it already exists. */
+    mkdir(path: string, options?: KayAppUserFilesCallOptions): Promise<KayAppUserFilesResult<null>>;
+    rename(from: string, to: string, options?: KayAppUserFilesCallOptions): Promise<KayAppUserFilesResult<null>>;
+}
+
+export declare interface KayAppUserFilesCallOptions {
+    /** Deadline in milliseconds from the call, waiting included. Default 5000, at most 60000. */
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+
+export declare interface KayAppUserFilesListOptions extends KayAppUserFilesCallOptions {
+    /** Default 5000, at most 50000. */
+    readonly maxEntries?: number;
+}
+
+export declare interface KayAppUserFilesReadTextOptions extends KayAppUserFilesCallOptions {
+    /** A larger file answers `error` with code `EFBIG`. Default 8 MiB, at most 64 MiB. */
+    readonly maxBytes?: number;
+}
+
+/**
+ * Every answer. `missing`: nothing exists at the path (ENOENT). `timeout`: no answer from the path
+ * in time. Its `reason` is `deadline` (this request ran out of time), `cooling-down` (a request at
+ * or above this path timed out recently, so the host did not try) or `saturated` (the host's
+ * workers are stuck on other paths, so it did not try). `aborted`: the caller's signal fired.
+ * `error`: anything else, with the Node error `code` when there is one (`EACCES`, `EISDIR`,
+ * `EFBIG` for a file over `maxBytes`, `EINVAL` for a relative path).
+ */
+export declare type KayAppUserFilesResult<T> = {
+    readonly kind: "ok";
+    readonly value: T;
+} | {
+    readonly kind: "missing";
+} | {
+    readonly kind: "timeout";
+    readonly reason: "deadline" | "cooling-down" | "saturated";
+    readonly detail: string;
+} | {
+    readonly kind: "aborted";
+} | {
+    readonly kind: "error";
+    readonly code?: string;
+    readonly detail: string;
+};
+
+export declare interface KayAppUserFileStat {
+    /** What the path is after following symlinks; never `symlink`. */
+    readonly kind: "file" | "directory" | "other";
+    /** Bytes. */
+    readonly size: number;
+    /** Milliseconds since the Unix epoch. */
+    readonly modifiedAtMs: number;
+}
+
+export declare interface KayAppUserFilesWalkOptions extends KayAppUserFilesCallOptions {
+    /** Default 10000, at most 100000. */
+    readonly maxEntries?: number;
+    /** Deepest level reported; the root's children are depth 1. Default 16, at most 64. */
+    readonly maxDepth?: number;
+    /** Report and descend into dot-prefixed entries. Default true. */
+    readonly includeHidden?: boolean;
+}
+
+export declare interface KayAppUserFileWalk {
+    readonly entries: readonly KayAppUserFileWalkEntry[];
+    /** True when the walk stopped at `maxEntries`. */
+    readonly entryLimitReached: boolean;
+    /** True when a directory at `maxDepth` was reported but not descended into. */
+    readonly depthLimitReached: boolean;
+}
+
+export declare interface KayAppUserFileWalkEntry {
+    /** Path segments below the walk's root. */
+    readonly segments: readonly string[];
+    readonly kind: KayAppUserFileKind;
+}
+
 declare const KayPluginManifestV1: z.ZodObject<{
     protocol: z.ZodLiteral<"kay.plugin.v1">;
     id: z.ZodString;

package/dist/kay-app.d.ts

@@ -2729,6 +2729,13 @@ export declare interface KayAppPluginApi {
      * which blocks the daemon; see {@link KayAppRepos}.
      */
     readonly repos: KayAppRepos;
+    /**
+     * File I/O in user folders (stat, read, list, walk, realpath, write, mkdir, rename), run by the
+     * host on its own worker threads under a deadline and answered as a typed result. Always present
+     * and ungated, like {@link paths}. Use it instead of `node:fs`, whose sync calls block the
+     * daemon; see {@link KayAppUserFiles}.
+     */
+    readonly userFiles: KayAppUserFiles;
     /**
      * Read/arrange access to the live desktop workspace. Present whenever the host has a workspace
      * (a headless daemon may not); absence is a host fact, never a grant signal. Reading the snapshot
@@ -4224,6 +4231,135 @@ export declare interface KayAppUiActionSessionEvent extends KayAppSessionEventBa
     readonly toolCallId: string;
 }
 
+export declare interface KayAppUserFileEntry {
+    readonly name: string;
+    /** From the directory entry itself: a symlink is reported as `symlink`, never followed. */
+    readonly kind: KayAppUserFileKind;
+}
+
+/**
+ * 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.
+ *
+ * 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.
+ */
+export declare type KayAppUserFileKind = "file" | "directory" | "symlink" | "other";
+
+export declare interface KayAppUserFileListing {
+    readonly entries: readonly KayAppUserFileEntry[];
+    /** True when the directory had more entries than `maxEntries`; the rest were not read. */
+    readonly entryLimitReached: boolean;
+}
+
+/**
+ * File I/O in user folders, run by the host off the daemon's main thread. Every path is absolute.
+ * No method rejects; each answers a {@link KayAppUserFilesResult}. This is not a sandbox: it does
+ * not limit which paths a plugin may touch. Added in SDK 0.12.5: a plugin that calls it declares
+ * `compatibility.sdk` `^0.12.5`, so an older Bonsai refuses a directory or repository plugin at
+ * load instead of the call failing.
+ */
+export declare interface KayAppUserFiles {
+    /** Follows symlinks. */
+    stat(path: string, options?: KayAppUserFilesCallOptions): Promise<KayAppUserFilesResult<KayAppUserFileStat>>;
+    /** UTF-8. */
+    readText(path: string, options?: KayAppUserFilesReadTextOptions): Promise<KayAppUserFilesResult<string>>;
+    list(path: string, options?: KayAppUserFilesListOptions): Promise<KayAppUserFilesResult<KayAppUserFileListing>>;
+    /** Depth-first below `path`; symlinks are reported, never followed. */
+    walk(path: string, options?: KayAppUserFilesWalkOptions): Promise<KayAppUserFilesResult<KayAppUserFileWalk>>;
+    /** The path with every symlink resolved. */
+    realpath(path: string, options?: KayAppUserFilesCallOptions): Promise<KayAppUserFilesResult<string>>;
+    /**
+     * Creates or replaces a UTF-8 file, not atomically. After `timeout` or `aborted` the write may
+     * still happen.
+     */
+    writeText(path: string, content: string, options?: KayAppUserFilesCallOptions): Promise<KayAppUserFilesResult<null>>;
+    /** Creates the directory and any missing parents; succeeds when it already exists. */
+    mkdir(path: string, options?: KayAppUserFilesCallOptions): Promise<KayAppUserFilesResult<null>>;
+    rename(from: string, to: string, options?: KayAppUserFilesCallOptions): Promise<KayAppUserFilesResult<null>>;
+}
+
+export declare interface KayAppUserFilesCallOptions {
+    /** Deadline in milliseconds from the call, waiting included. Default 5000, at most 60000. */
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+
+export declare interface KayAppUserFilesListOptions extends KayAppUserFilesCallOptions {
+    /** Default 5000, at most 50000. */
+    readonly maxEntries?: number;
+}
+
+export declare interface KayAppUserFilesReadTextOptions extends KayAppUserFilesCallOptions {
+    /** A larger file answers `error` with code `EFBIG`. Default 8 MiB, at most 64 MiB. */
+    readonly maxBytes?: number;
+}
+
+/**
+ * Every answer. `missing`: nothing exists at the path (ENOENT). `timeout`: no answer from the path
+ * in time. Its `reason` is `deadline` (this request ran out of time), `cooling-down` (a request at
+ * or above this path timed out recently, so the host did not try) or `saturated` (the host's
+ * workers are stuck on other paths, so it did not try). `aborted`: the caller's signal fired.
+ * `error`: anything else, with the Node error `code` when there is one (`EACCES`, `EISDIR`,
+ * `EFBIG` for a file over `maxBytes`, `EINVAL` for a relative path).
+ */
+export declare type KayAppUserFilesResult<T> = {
+    readonly kind: "ok";
+    readonly value: T;
+} | {
+    readonly kind: "missing";
+} | {
+    readonly kind: "timeout";
+    readonly reason: "deadline" | "cooling-down" | "saturated";
+    readonly detail: string;
+} | {
+    readonly kind: "aborted";
+} | {
+    readonly kind: "error";
+    readonly code?: string;
+    readonly detail: string;
+};
+
+export declare interface KayAppUserFileStat {
+    /** What the path is after following symlinks; never `symlink`. */
+    readonly kind: "file" | "directory" | "other";
+    /** Bytes. */
+    readonly size: number;
+    /** Milliseconds since the Unix epoch. */
+    readonly modifiedAtMs: number;
+}
+
+export declare interface KayAppUserFilesWalkOptions extends KayAppUserFilesCallOptions {
+    /** Default 10000, at most 100000. */
+    readonly maxEntries?: number;
+    /** Deepest level reported; the root's children are depth 1. Default 16, at most 64. */
+    readonly maxDepth?: number;
+    /** Report and descend into dot-prefixed entries. Default true. */
+    readonly includeHidden?: boolean;
+}
+
+export declare interface KayAppUserFileWalk {
+    readonly entries: readonly KayAppUserFileWalkEntry[];
+    /** True when the walk stopped at `maxEntries`. */
+    readonly entryLimitReached: boolean;
+    /** True when a directory at `maxDepth` was reported but not descended into. */
+    readonly depthLimitReached: boolean;
+}
+
+export declare interface KayAppUserFileWalkEntry {
+    /** Path segments below the walk's root. */
+    readonly segments: readonly string[];
+    readonly kind: KayAppUserFileKind;
+}
+
 export declare interface KayAppWhiteboard {
     /**
      * Binds read-only Whiteboard access to the exact context issued to this plugin's session source.

package/package.json

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