@yaklabs-ai/plugin-sdk 0.12.5 → 0.13.0

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" | "userFiles">;
+export declare type FauxKayAgentCapabilities = Pick<KayAgentPluginApi, "network" | "webSession" | "process" | "whiteboard" | "interaction" | "interceptToolCall" | "withJev" | "events" | "time" | "userFiles" | "familyFolder">;
 
 export declare function fauxKayAgentCapabilities(): FauxKayAgentCapabilities;
 
@@ -925,52 +925,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 {
@@ -1112,11 +1074,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. */
@@ -1169,9 +1128,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/kay-agent-testing.js

@@ -147,17 +147,6 @@ var USER_FILE_METHODS = [
 ];
 function fauxKayAgentCapabilities() {
   return {
-    filesystem: {
-      readText: unwired("filesystem.readText"),
-      writeText: unwired("filesystem.writeText"),
-      readBytes: unwired("filesystem.readBytes"),
-      writeBytes: unwired("filesystem.writeBytes"),
-      mkdir: unwired("filesystem.mkdir"),
-      readDir: unwired("filesystem.readDir"),
-      stat: unwired("filesystem.stat"),
-      rename: unwired("filesystem.rename"),
-      realpath: unwired("filesystem.realpath")
-    },
     network: { fetch: unwired("network.fetch") },
     webSession: {
       request: unwired("webSession.request"),
@@ -210,7 +199,10 @@ function fauxKayAgentCapabilities() {
         kind: "error",
         detail: `userFiles.${name} is not wired in this test double`
       })
-    ]))
+    ])),
+    // A test double runs outside any session, so it has no family folder — the same answer the
+    // real capability gives. A test that exercises one overrides this handle after the spread.
+    familyFolder: { path: async () => void 0 }
   };
 }
 function defaultTestToolContext() {

package/dist/kay-agent.d.ts

@@ -1273,14 +1273,6 @@ declare type JsonValue_3 = string | number | boolean | null | JsonValue_3[] | {
 
 declare const JsonValue_3: z.ZodType<JsonValue_3>;
 
-/**
- * The root selector the host binds to the session family's shared Whiteboard folder. The plugin
- * that owns the Whiteboard gets the whole folder; every other plugin gets its own
- * `plugins/<plugin-id>/` folder inside it. Calls on it are claims on
- * `filesystem.read`/`filesystem.write` with this `root`, decided like any other.
- */
-export declare const KAY_FAMILY_WHITEBOARD_FILESYSTEM_ROOT = "family-whiteboard";
-
 /** A plugin's Kay agent activation — receives only the brokered {@link KayAgentPluginApi}. */
 export declare type KayAgentActivate = (api: KayAgentPluginApi) => void;
 
@@ -1345,9 +1337,8 @@ export declare interface KayAgentAdvertisementAuthApi {
  * `grant-read-failed` means Kay could not read its own consent store and refused rather than
  * assume — the second is not something a grant prompt fixes.
  *
- * Structurally parallel to {@link KayAgentFilesystemError}: broker handles are declaration-gated,
- * so presence does not imply a current grant or concrete binding. This error says which ordered
- * policy layer refused one specific call.
+ * Broker handles are always present, so presence does not imply a current grant or concrete
+ * binding. This error says which ordered policy layer refused one specific call.
  */
 export declare class KayAgentCapabilityError extends Error {
     readonly refusal: PluginCapabilityRefusalV1;
@@ -1371,59 +1362,14 @@ export 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.
- */
-export 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. */
-export declare interface KayAgentFilesystemByteRange {
-    readonly offset: number;
-    readonly maxBytes: number;
-}
-
-export declare interface KayAgentFilesystemEntry {
-    readonly name: string;
-    readonly kind: "file" | "directory" | "symlink" | "other";
-}
-
-export declare class KayAgentFilesystemError extends Error {
-    readonly code: KayAgentFilesystemErrorCode;
-    constructor(code: KayAgentFilesystemErrorCode, message: string);
-}
-
-export declare type KayAgentFilesystemErrorCode = "denied" | "invalid_path" | "not_found" | "already_exists" | "not_directory" | "is_directory" | "io_error";
-
-export declare interface KayAgentFilesystemLocation {
-    /** Exact `root` selector the host bound for this target, plus a path relative to it. */
-    readonly root: string;
-    readonly path: string;
-}
-
-export declare interface KayAgentFilesystemStat {
-    readonly kind: "file" | "directory" | "other";
-    readonly size: number;
-    readonly modifiedAtMs: number;
-}
-
-export 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. */
+export 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>;
 }
 
 /**
@@ -1573,11 +1519,8 @@ export 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. */
@@ -1630,9 +1573,8 @@ export 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;
@@ -2118,16 +2060,8 @@ declare const KayPluginManifestV1: z.ZodObject<{
                         localId: z.ZodString;
                         schemes: z.ZodArray<z.ZodString>;
                         displayName: z.ZodOptional<z.ZodString>;
-                        filesystemBacking: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                        filesystemBacking: z.ZodOptional<z.ZodObject<{
                             root: z.ZodLiteral<"dataDir">;
-                        }, z.core.$strict>, z.ZodObject<{
-                            root: z.ZodLiteral<"filesystem">;
-                            selector: z.ZodString;
-                        }, z.core.$strict>], "root">>;
-                        verbs: z.ZodOptional<z.ZodObject<{
-                            writable: z.ZodOptional<z.ZodBoolean>;
-                            editable: z.ZodOptional<z.ZodBoolean>;
-                            deletable: z.ZodOptional<z.ZodBoolean>;
                         }, z.core.$strict>>;
                         authService: z.ZodOptional<z.ZodString>;
                         knownResources: z.ZodOptional<z.ZodLiteral<true>>;
@@ -3469,18 +3403,6 @@ declare const PluginCapabilityRefusalV1: z.ZodObject<{
             origin: z.ZodString;
             pathPrefix: z.ZodString;
         }, z.core.$strict>;
-    }, z.core.$strict>, z.ZodObject<{
-        target: z.ZodLiteral<"kay.agent">;
-        slug: z.ZodLiteral<"filesystem.read">;
-        envelope: z.ZodObject<{
-            root: z.ZodString;
-        }, z.core.$strict>;
-    }, z.core.$strict>, z.ZodObject<{
-        target: z.ZodLiteral<"kay.agent">;
-        slug: z.ZodLiteral<"filesystem.write">;
-        envelope: z.ZodObject<{
-            root: z.ZodString;
-        }, z.core.$strict>;
     }, z.core.$strict>, z.ZodObject<{
         target: z.ZodLiteral<"kay.agent">;
         slug: z.ZodLiteral<"process.spawn">;

package/dist/kay-agent.js

@@ -1374,15 +1374,6 @@ var DelegatedRefreshRejectedError = class extends Error {
 function isDelegatedRefreshRejected(error) {
   return typeof error === "object" && error !== null && error[DELEGATED_REFRESH_REJECTED] === true;
 }
-var KayAgentFilesystemError = class extends Error {
-  code;
-  constructor(code, message) {
-    super(message);
-    this.name = "KayAgentFilesystemError";
-    this.code = code;
-  }
-};
-var KAY_FAMILY_WHITEBOARD_FILESYSTEM_ROOT = "family-whiteboard";
 var KayAgentCapabilityError = class extends Error {
   refusal;
   constructor(refusal, message) {
@@ -1405,9 +1396,7 @@ export {
   DelegatedRefreshRejectedError,
   INTERACTION_CREDENTIAL_GUARD,
   JevCallError,
-  KAY_FAMILY_WHITEBOARD_FILESYSTEM_ROOT,
   KayAgentCapabilityError,
-  KayAgentFilesystemError,
   KayAgentWebSessionError,
   OBSERVATION_MIME,
   PluginApiError,

package/dist/kay-app.d.ts

@@ -6496,8 +6496,6 @@ export declare interface UriModule {
     readonly permissionDefaults?: UriPermissionDefaults;
     /** Requires a resolved URI connection before any verb handler runs. */
     readonly requiresConnection?: boolean;
-    /** Host-only marker: dispatch mutations as native file operations after locate finalization. */
-    readonly hostNativeFileMutations?: true;
     /**
      * This module refuses a whole-content overwrite of an address the dispatching
      * session has never read or written, when content is already stored there
@@ -6509,7 +6507,7 @@ export declare interface UriModule {
      * A module without the flag never receives the marked dispatch and behaves
      * exactly as before. Enforcement depth past this floor — refusing a write to
      * content that CHANGED since the read — stays the module's own call:
-     * `builtin:local-file` and host-native projections enforce both halves; the
+     * `builtin:local-file` enforces both halves; the
      * artifact factory enforces the floor and leaves change detection to its
      * `edit` anchor. A module declaring this flag obligates itself to one more
      * thing: every revision its mutations report must be a value its own reads

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaklabs-ai/plugin-sdk",
-  "version": "0.12.5",
+  "version": "0.13.0",
   "description": "The Kay plugin SDK — types and helpers for authoring a Kay directory plugin.",
   "author": "YakLabs",
   "type": "module",
@@ -17,6 +17,10 @@
       "types": "./dist/kay-app.d.ts",
       "default": "./dist/kay-app.js"
     },
+    "./fs": {
+      "types": "./dist/fs.d.ts",
+      "default": "./dist/fs.js"
+    },
     "./kay-agent/testing": {
       "types": "./dist/kay-agent-testing.d.ts",
       "default": "./dist/kay-agent-testing.js"