@yaklabs-ai/plugin-sdk 0.12.5 → 0.13.0

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.5"
+    "@kay/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.13.0"
   }
 }
 ```

package/THIRD-PARTY-INVENTORY.json

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

package/dist/disclosure.d.ts

@@ -1024,52 +1024,14 @@ declare interface KayAgentEvents {
     publish(localId: string, payload: unknown): void;
 }
 
-/**
- * Claim-checked filesystem operations. Paths are root-relative; canonical host paths never cross
- * the seam. Writes are atomic: readers see the old file or the new one, never a partial write. A
- * replace keeps the file's mode but makes a new file, so owner and extended attributes are not
- * carried over. On a volume without hard links an exclusive create can briefly show an empty file.
- */
-declare interface KayAgentFilesystem {
-    readText(location: KayAgentFilesystemLocation): Promise<string>;
-    writeText(location: KayAgentFilesystemLocation, content: string, options?: KayAgentFilesystemWriteOptions): Promise<void>;
-    /** The whole file, or the requested window of it. */
-    readBytes(location: KayAgentFilesystemLocation, range?: KayAgentFilesystemByteRange): Promise<Uint8Array>;
-    writeBytes(location: KayAgentFilesystemLocation, bytes: Uint8Array, options?: KayAgentFilesystemWriteOptions): Promise<void>;
-    mkdir(location: KayAgentFilesystemLocation): Promise<void>;
-    readDir(location: KayAgentFilesystemLocation): Promise<readonly KayAgentFilesystemEntry[]>;
-    stat(location: KayAgentFilesystemLocation): Promise<KayAgentFilesystemStat>;
-    rename(from: KayAgentFilesystemLocation, to: KayAgentFilesystemLocation): Promise<void>;
-    /** Returns the canonical path relative to the selected grant root. */
-    realpath(location: KayAgentFilesystemLocation): Promise<string>;
-}
-
-/** A byte window of a file; `maxBytes` is capped by the host. */
-declare interface KayAgentFilesystemByteRange {
-    readonly offset: number;
-    readonly maxBytes: number;
-}
-
-declare interface KayAgentFilesystemEntry {
-    readonly name: string;
-    readonly kind: "file" | "directory" | "symlink" | "other";
-}
-
-declare interface KayAgentFilesystemLocation {
-    /** Exact `root` selector the host bound for this target, plus a path relative to it. */
-    readonly root: string;
-    readonly path: string;
-}
-
-declare interface KayAgentFilesystemStat {
-    readonly kind: "file" | "directory" | "other";
-    readonly size: number;
-    readonly modifiedAtMs: number;
-}
-
-declare interface KayAgentFilesystemWriteOptions {
-    /** Fail with `already_exists` instead of replacing a file already at the location. */
-    readonly exclusive?: boolean;
+/** This plugin's folder in the session family's shared Whiteboard. */
+declare interface KayAgentFamilyFolder {
+    /**
+     * The folder's absolute path, created on first use. The plugin that owns the Whiteboard gets
+     * the whole family folder; every other plugin gets its own `plugins/<plugin-id>/` inside it.
+     * Undefined outside a session.
+     */
+    path(): Promise<string | undefined>;
 }
 
 declare interface KayAgentInteractionSurfaces {
@@ -1211,11 +1173,8 @@ declare interface KayAgentPluginApi {
         /** Register a whole URI module (a scheme handler that owns its address space, e.g. `drive://`). */
         registerModule(module: UriExtensionModule): void;
     };
-    /**
-     * Always present; each call is checked against `filesystem.read {root}` / `filesystem.write
-     * {root}` for the root it touches, and against the host's binding for that root.
-     */
-    readonly filesystem: KayAgentFilesystem;
+    /** This plugin's folder in the session family's shared Whiteboard, created on first use. Undefined outside a session. */
+    readonly familyFolder: KayAgentFamilyFolder;
     /** Absent unless the `knowledgeSearch` grant is requested and effectively granted. */
     readonly knowledgeSearch?: KayAgentKnowledgeSearch;
     /** Absent unless the `knownResources` grant is requested and effectively granted. */
@@ -1268,9 +1227,8 @@ declare interface KayAgentPluginApi {
     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
+     * answered as a typed result. Always present and ungated: 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;

package/dist/disclosure.js

@@ -765,17 +765,6 @@ function unavailableInteractionSurfaces(message) {
 // packages/plugin-sdk/dist/disclosure/probe-kay-agent-capabilities.js
 var inertResult = () => new Promise(() => {
 });
-var INERT_FILESYSTEM = {
-  readText: inertResult,
-  writeText: inertResult,
-  readBytes: inertResult,
-  writeBytes: inertResult,
-  mkdir: inertResult,
-  readDir: inertResult,
-  stat: inertResult,
-  rename: inertResult,
-  realpath: inertResult
-};
 var INERT_NETWORK = {
   fetch: inertResult
 };
@@ -807,7 +796,6 @@ var INERT_WHITEBOARD = {
 var INERT_WITH_JEV = async (_use, fallback) => fallback();
 function createKayAgentProbeCapabilityHandles() {
   return {
-    filesystem: INERT_FILESYSTEM,
     network: INERT_NETWORK,
     webSession: INERT_WEB_SESSION,
     process: INERT_PROCESS,
@@ -825,7 +813,7 @@ function createKayAgentProbeCapabilityHandles() {
     time: {
       snapshot: () => ({ nowMs: 0, zone: "UTC", zoneSource: "utc-fallback" })
     },
-    // Inert like the filesystem broker: a probe must never touch the user's disk.
+    // Inert like the process broker: a probe must never touch the user's disk.
     userFiles: {
       stat: inertResult,
       readText: inertResult,
@@ -835,7 +823,9 @@ function createKayAgentProbeCapabilityHandles() {
       writeText: inertResult,
       mkdir: inertResult,
       rename: inertResult
-    }
+    },
+    // A probe runs outside any session, and must not create a folder on the user's disk.
+    familyFolder: { path: async () => void 0 }
   };
 }
 

package/dist/fs.d.ts

@@ -0,0 +1,156 @@
+import { constants } from 'node:fs';
+import { FileHandle } from 'node:fs/promises';
+import * as nodeFsp from 'node:fs/promises';
+
+export declare const access: typeof nodeFsp.access;
+
+export declare const appendFile: typeof nodeFsp.appendFile;
+
+export declare const chmod: typeof nodeFsp.chmod;
+
+export declare const chown: typeof nodeFsp.chown;
+
+export { constants }
+
+export declare const copyFile: typeof nodeFsp.copyFile;
+
+export declare const cp: typeof nodeFsp.cp;
+
+declare const _default: {
+    access: typeof nodeFsp.access;
+    appendFile: typeof nodeFsp.appendFile;
+    chmod: typeof nodeFsp.chmod;
+    chown: typeof nodeFsp.chown;
+    constants: typeof constants;
+    copyFile: typeof nodeFsp.copyFile;
+    cp: typeof nodeFsp.cp;
+    glob: typeof nodeFsp.glob;
+    lchmod: typeof nodeFsp.lchmod;
+    lchown: typeof nodeFsp.lchown;
+    link: typeof nodeFsp.link;
+    lstat: typeof nodeFsp.lstat;
+    lutimes: typeof nodeFsp.lutimes;
+    mkdir: typeof nodeFsp.mkdir;
+    mkdtemp: typeof nodeFsp.mkdtemp;
+    mkdtempDisposable: (prefix: string, options?: unknown) => Promise<{
+        path: string;
+        remove(): Promise<void>;
+        [Symbol.asyncDispose](): Promise<void>;
+    }>;
+    open: typeof nodeFsp.open;
+    opendir: typeof nodeFsp.opendir;
+    readdir: typeof nodeFsp.readdir;
+    readFile: typeof nodeFsp.readFile;
+    readlink: typeof nodeFsp.readlink;
+    realpath: typeof nodeFsp.realpath;
+    rename: typeof nodeFsp.rename;
+    rm: typeof nodeFsp.rm;
+    rmdir: typeof nodeFsp.rmdir;
+    stat: typeof nodeFsp.stat;
+    statfs: typeof nodeFsp.statfs;
+    symlink: typeof nodeFsp.symlink;
+    truncate: typeof nodeFsp.truncate;
+    unlink: typeof nodeFsp.unlink;
+    utimes: typeof nodeFsp.utimes;
+    watch: typeof nodeFsp.watch;
+    writeFile: typeof nodeFsp.writeFile;
+    writeFileAtomic: typeof writeFileAtomic;
+    withTimeout: typeof withTimeout;
+};
+export default _default;
+
+export { FileHandle }
+
+export declare const glob: typeof nodeFsp.glob;
+
+/** Not tried: a call at or above this path missed its deadline recently. */
+export declare const KAY_FS_COOLING_DOWN = "ERR_KAY_FS_COOLING_DOWN";
+
+/** The call did not finish by its deadline; the host abandoned the worker running it. */
+export declare const KAY_FS_DEADLINE = "ERR_KAY_FS_DEADLINE";
+
+/** A call's deadline when its options name none. */
+export declare const KAY_FS_DEFAULT_TIMEOUT_MS = 30000;
+
+/** Not tried: the host's file workers are all stuck on other paths. */
+export declare const KAY_FS_SATURATED = "ERR_KAY_FS_SATURATED";
+
+/** The host's file service is closed, or its worker could not start or died mid-call. */
+export declare const KAY_FS_UNAVAILABLE = "ERR_KAY_FS_UNAVAILABLE";
+
+/** An option or function this module does not implement (see the module docs). */
+export declare const KAY_FS_UNSUPPORTED = "ERR_KAY_FS_UNSUPPORTED";
+
+export declare const lchmod: typeof nodeFsp.lchmod;
+
+export declare const lchown: typeof nodeFsp.lchown;
+
+export declare const link: typeof nodeFsp.link;
+
+export declare const lstat: typeof nodeFsp.lstat;
+
+export declare const lutimes: typeof nodeFsp.lutimes;
+
+export declare const mkdir: typeof nodeFsp.mkdir;
+
+export declare const mkdtemp: typeof nodeFsp.mkdtemp;
+
+/** Node 24's disposable temporary directory, built on {@link mkdtemp} and {@link rm}. */
+export declare const mkdtempDisposable: (prefix: string, options?: unknown) => Promise<{
+    path: string;
+    remove(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+}>;
+
+export declare const open: typeof nodeFsp.open;
+
+export declare const opendir: typeof nodeFsp.opendir;
+
+export declare const readdir: typeof nodeFsp.readdir;
+
+export declare const readFile: typeof nodeFsp.readFile;
+
+export declare const readlink: typeof nodeFsp.readlink;
+
+export declare const realpath: typeof nodeFsp.realpath;
+
+export declare const rename: typeof nodeFsp.rename;
+
+export declare const rm: typeof nodeFsp.rm;
+
+export declare const rmdir: typeof nodeFsp.rmdir;
+
+export declare const stat: typeof nodeFsp.stat;
+
+export declare const statfs: typeof nodeFsp.statfs;
+
+export declare const symlink: typeof nodeFsp.symlink;
+
+export declare const truncate: typeof nodeFsp.truncate;
+
+export declare const unlink: typeof nodeFsp.unlink;
+
+export declare const utimes: typeof nodeFsp.utimes;
+
+export declare const watch: typeof nodeFsp.watch;
+
+/**
+ * Run `run` with `timeoutMs` as the deadline of every call it makes that names none itself,
+ * including calls without an options object (`open`, `stat`, a file handle's methods). Not in
+ * Node; with no host installed it only runs `run`.
+ */
+export declare function withTimeout<T>(timeoutMs: number, run: () => T): T;
+
+export declare const writeFile: typeof nodeFsp.writeFile;
+
+/**
+ * Replace `path` so a reader never sees a partial file: write a temporary file beside it, flush
+ * it to disk, then rename it over `path`. Not in Node; works with or without a host.
+ */
+export declare function writeFileAtomic(path: string | URL, data: string | NodeJS.ArrayBufferView, options?: {
+    readonly encoding?: BufferEncoding;
+    readonly mode?: number;
+    readonly timeoutMs?: number;
+}): Promise<void>;
+
+export { }