@peers-app/peers-sdk 0.25.8 → 0.25.10

package/dist/contracts/__tests__/contract-proxy.test.js

@@ -426,6 +426,32 @@ describe("contract proxy — error handling", () => {
         const consumer = consumerVia(contract, provider);
         await expect(consumer.tables.Widgets.list()).rejects.toThrow(/does not provide table 'Widgets'/);
     });
+    it("forwards callerPackageId when the resolution opts into call context", async () => {
+        const seen = [];
+        const provider = (0, contract_proxy_1.createContractProvider)({
+            contractId: CONTRACT_ID,
+            version: 1,
+            forwardCallContext: true,
+            tools: {
+                listGrants: {
+                    tool: { toolId: (0, utils_1.newid)(), name: "listGrants", accessLevel: 0 },
+                    toolFn: async (host) => {
+                        seen.push(host.callerPackageId ?? null);
+                        return "ok";
+                    },
+                },
+            },
+        });
+        await provider({
+            contractId: CONTRACT_ID,
+            version: 1,
+            member: "tool",
+            name: "listGrants",
+            operation: "run",
+            args: [],
+        }, { callerPackageId: "00pkg00000000000000000001" });
+        expect(seen).toEqual(["00pkg00000000000000000001"]);
+    });
     it.each([
         ["tool", "missingTool"],
         ["observable", "missingObservable"],
@@ -520,6 +546,52 @@ describe("contract proxy — permission checks", () => {
         expect(denied.table.save).not.toHaveBeenCalled();
     });
 });
+describe("contract provider endpoint event filter", () => {
+    it("delivers a generic event only to subscribers the filter allows", async () => {
+        const handlers = new Set();
+        const changed = {
+            eventName: () => "changed",
+            subscribe: (handler) => {
+                handlers.add(handler);
+                return {
+                    unsubscribe: () => {
+                        handlers.delete(handler);
+                        return true;
+                    },
+                };
+            },
+        };
+        const resolution = {
+            contractId: CONTRACT_ID,
+            version: 1,
+            events: { changed: changed },
+            eventFilter: (_eventName, payload, context) => payload.owner === context.callerPackageId,
+        };
+        const delivered = [];
+        const endpoint = (0, contract_proxy_1.createContractProviderEndpoint)(resolution, {
+            notify: async (notification) => {
+                delivered.push(notification.subscriptionId);
+            },
+        });
+        const subscribe = (subscriptionId, callerPackageId) => endpoint.handleCall({
+            contractId: CONTRACT_ID,
+            version: 1,
+            member: "event",
+            name: "changed",
+            operation: "subscribe",
+            subscriptionId,
+            args: [],
+        }, { callerPackageId });
+        await subscribe("allowed", "pkg-a");
+        await subscribe("denied", "pkg-b");
+        for (const handler of handlers) {
+            handler({ owner: "pkg-a" });
+        }
+        await new Promise((resolve) => setImmediate(resolve));
+        expect(delivered).toEqual(["allowed"]);
+        endpoint.dispose();
+    });
+});
 describe("connectionContractTransport", () => {
     it("emits on the request channel with the call and returns the response", async () => {
         const emit = jest.fn(async (_event, _call) => ["ok"]);

package/dist/contracts/contract-proxy.d.ts

@@ -220,6 +220,11 @@ export interface IContractToolContext {
      * by the host and returned only to the provider-side tool implementation.
      */
     getVariable(variableName: string, requestingToolId: string): Promise<string>;
+    /**
+     * Isolated package that originated this call, when the host runtime supplied one.
+     * Absent for trusted local callers (the signed-in UI session and the CLI).
+     */
+    callerPackageId?: string;
 }
 /**
  * Build the **consumer** side of a contract proxy from a contract definition and a
@@ -293,6 +298,13 @@ export interface IContractResolution {
      * Omit this for remote or otherwise untrusted provider routes.
      */
     toolContext?: IContractToolContext;
+    /**
+     * When true, provider tool functions receive an {@link IContractToolContext} as their
+     * final argument even if {@link toolContext} was not set, including
+     * {@link IContractToolContext.callerPackageId} from the current call. Host contracts
+     * that authorize by calling package set this.
+     */
+    forwardCallContext?: boolean;
     observables?: Record<string, Observable<any>>;
     /**
      * Provider-owned write policy for live observables. A `set` is allowed only when the
@@ -306,6 +318,20 @@ export interface IContractResolution {
      * their payloads to its configured notification sink.
      */
     events?: Record<string, Event<any>>;
+    /**
+     * Optional per-subscriber gate for generic contract events.
+     *
+     * Table and observable streams are not filtered. The endpoint invokes this once
+     * per subscriber with the {@link IContractCallContext} captured at subscribe time.
+     * Return false, or reject, to drop that notification for that subscriber only.
+     * A shared endpoint can therefore hide one caller's events from another.
+     *
+     * @param eventName Contract event name, such as `changed`.
+     * @param payload Payload about to be delivered.
+     * @param context Caller identity from the subscribe call.
+     * @returns Whether this subscriber may receive the payload.
+     */
+    eventFilter?: (eventName: string, payload: unknown, context: IContractCallContext) => boolean | Promise<boolean>;
 }
 /** Identity of the caller, supplied by the transport layer for permission checks. */
 export interface IContractCallContext {
@@ -319,6 +345,11 @@ export interface IContractCallContext {
      * host router before dispatch.
      */
     callerDeviceId?: string;
+    /**
+     * Isolated package that originated this call. Set by the isolate runtime from host
+     * state, never from a guest payload. Absent for trusted local UI and CLI callers.
+     */
+    callerPackageId?: string;
     /**
      * Provider-side data context used to resolve the caller's group/personal role.
      * In-process only — never serialized across a connection.
@@ -418,7 +449,9 @@ export interface IContractProviderEndpoint {
  * or an {@link Observable} (`resolution.observables[name]`) — is only subscribed to while at
  * least one consumer holds a subscription (refcounted by a resolved key), and each payload is
  * fanned out through the supplied {@link ContractNotificationSink} as an
- * {@link IContractNotification}. The endpoint owns no request listener, which lets a
+ * {@link IContractNotification}. Generic events pass through
+ * {@link IContractResolution.eventFilter} once per subscriber, using the caller context
+ * captured when that subscriber subscribed. The endpoint owns no request listener, which lets a
  * connection-wide router multiplex many endpoints through one request channel and later
  * substitute sandbox-backed endpoint implementations.
  *

package/dist/contracts/contract-proxy.js

@@ -534,9 +534,19 @@ function createContractProvider(resolution, opts = {}) {
                     throw new Error(`Contract ${call.contractId} does not provide tool '${call.name}'`);
                 }
                 await assertContractToolAccess(tool, call, context);
-                return resolution.toolContext
-                    ? tool.toolFn(...call.args, resolution.toolContext)
-                    : tool.toolFn(...call.args);
+                if (resolution.toolContext || resolution.forwardCallContext) {
+                    const base = resolution.toolContext ?? {
+                        dataContextId: context.dataContext?.dataContextId ?? "",
+                        getVariable: async () => {
+                            throw new Error("Persistent variables are not available to this contract tool");
+                        },
+                    };
+                    return tool.toolFn(...call.args, {
+                        ...base,
+                        callerPackageId: context.callerPackageId,
+                    });
+                }
+                return tool.toolFn(...call.args);
             }
             case "observable": {
                 const obs = resolution.observables?.[call.name];
@@ -571,7 +581,9 @@ function createContractProvider(resolution, opts = {}) {
  * or an {@link Observable} (`resolution.observables[name]`) — is only subscribed to while at
  * least one consumer holds a subscription (refcounted by a resolved key), and each payload is
  * fanned out through the supplied {@link ContractNotificationSink} as an
- * {@link IContractNotification}. The endpoint owns no request listener, which lets a
+ * {@link IContractNotification}. Generic events pass through
+ * {@link IContractResolution.eventFilter} once per subscriber, using the caller context
+ * captured when that subscriber subscribed. The endpoint owns no request listener, which lets a
  * connection-wide router multiplex many endpoints through one request channel and later
  * substitute sandbox-backed endpoint implementations.
  *
@@ -581,9 +593,10 @@ function createContractProvider(resolution, opts = {}) {
 function createContractProviderEndpoint(resolution, opts) {
     const { notify, permissionCheck, context: defaultContext } = opts;
     const dispatch = createContractProvider(resolution, { permissionCheck });
-    // One live subscription per resolved subscription key, refcounted by the set of
-    // consumer subscription ids currently attached to it, plus a reverse index for
-    // unsubscribe. Keys namespace generic events (`event:<name>`), table events
+    // One live subscription per resolved subscription key, refcounted by the subscribers
+    // currently attached to it, plus a reverse index for unsubscribe. Each subscriber keeps
+    // the caller context from its subscribe call so event filters can differ per consumer.
+    // Keys namespace generic events (`event:<name>`), table events
     // (`table:<name>:<event>`), and observable streams (`observable:<name>`) so the same
     // machinery serves all three.
     const byKey = new Map();
@@ -651,29 +664,51 @@ function createContractProviderEndpoint(resolution, opts) {
             },
         };
     };
-    const subscribe = (key, attach, subscriptionId) => {
+    const reportNotifyFailure = (subscriptionId, err) => {
+        console.error(`Contract notify failed for subscription '${subscriptionId}'`, err);
+    };
+    const deliver = (key, subscriptionId, payload, context) => {
+        // Start each notification independently. A slow or rejected destination must not
+        // block sibling subscribers, and every rejection is handled because Observable
+        // callbacks do not await returned promises. Without a filter, attach the catch
+        // directly so a rejected notify is logged on the same turn as before.
+        if (!(key.startsWith("event:") && resolution.eventFilter)) {
+            if (!subIdToKey.has(subscriptionId)) {
+                return;
+            }
+            void notifySink(subscriptionId, payload, key).catch((err) => {
+                reportNotifyFailure(subscriptionId, err);
+            });
+            return;
+        }
+        void (async () => {
+            const allowed = await resolution.eventFilter?.(key.slice("event:".length), payload, context);
+            if (!allowed || !subIdToKey.has(subscriptionId)) {
+                return;
+            }
+            await notifySink(subscriptionId, payload, key);
+        })().catch((err) => {
+            reportNotifyFailure(subscriptionId, err);
+        });
+    };
+    const subscribe = (key, attach, subscriptionId, context) => {
         if (subIdToKey.has(subscriptionId)) {
             throw new Error(`Duplicate contract subscriptionId '${subscriptionId}'`);
         }
         let entry = byKey.get(key);
         if (!entry) {
             // First subscriber for this key: attach the single live subscription.
-            const subIds = new Set();
+            const subscribers = new Map();
             const detach = attach((payload) => {
-                // Start each notification independently. A slow or rejected destination must not
-                // block sibling subscribers, and every rejection is handled because Observable
-                // callbacks do not await returned promises.
-                for (const sid of [...subIds]) {
-                    void notifySink(sid, payload, key).catch((err) => {
-                        console.error(`Contract notify failed for subscription '${sid}'`, err);
-                    });
+                for (const [sid, subscriberContext] of [...subscribers]) {
+                    deliver(key, sid, payload, subscriberContext);
                 }
             });
-            entry = { liveUnsub: detach, subIds };
+            entry = { liveUnsub: detach, subscribers };
             byKey.set(key, entry);
         }
         subIdToKey.set(subscriptionId, key);
-        entry.subIds.add(subscriptionId);
+        entry.subscribers.set(subscriptionId, context);
     };
     const unsubscribe = (subscriptionId) => {
         const key = subIdToKey.get(subscriptionId);
@@ -685,8 +720,8 @@ function createContractProviderEndpoint(resolution, opts) {
         if (!entry) {
             return;
         }
-        entry.subIds.delete(subscriptionId);
-        if (entry.subIds.size === 0) {
+        entry.subscribers.delete(subscriptionId);
+        if (entry.subscribers.size === 0) {
             // Last subscriber left: detach the live subscription (nothing more is pushed).
             entry.liveUnsub();
             byKey.delete(key);
@@ -731,7 +766,7 @@ function createContractProviderEndpoint(resolution, opts) {
                     throw new Error(`Contract provider endpoint ${resolution.contractId} v${resolution.version} is disposed`);
                 }
                 const { key, attach } = resolveSubscription(call);
-                subscribe(key, attach, call.subscriptionId);
+                subscribe(key, attach, call.subscriptionId, context);
             }
             finally {
                 pendingSubIds.delete(call.subscriptionId);

package/dist/contracts/contract-resolvers.js

@@ -149,6 +149,7 @@ const permissionDenied = (call, reason) => new Error(`Permission denied: ${call.
 const localOnlyContractIds = new Set([
     system_ids_1.identityContractId,
     system_ids_1.invitesContractId,
+    system_ids_1.localFoldersContractId,
     system_ids_1.toolAccessControlContractId,
 ]);
 /**

package/dist/contracts/index.d.ts

@@ -15,6 +15,7 @@ export { createRemoteContractEndpoint, getRemoteContractTransportFactory, type I
 export { DEVICE_OPERATIONS_CONTRACT_VERSION, DEVICE_OPERATIONS_MAX_QUERY_LENGTH, DEVICE_OPERATIONS_MAX_RESULT_BYTES, DEVICE_OPERATIONS_MAX_ROWS, DEVICE_OPERATIONS_MAX_TOOLS, type DeviceOperationCapability, deviceOperationsProviderPackageId, deviceOperationsToolIds, getDeviceOperationsContractDefinition, type IDeviceDatabaseQueryInput, type IDeviceDatabaseQueryResult, type IDeviceOperationStatus, type IDeviceToolListInput, type IDeviceToolLookupInput, type IDeviceToolLookupResult, type IDeviceToolRunInput, } from "./system/device-operations-contract";
 export { getIdentityContractDefinition, IDENTITY_CONTRACT_VERSION, type IIdentityConsumer, type IIdentitySessionInfo, } from "./system/identity-contract";
 export { getInvitesContractDefinition, type IAcceptInviteResult, type ICreatedInvite, type IInvitePreview, type IInvitesConsumer, INVITES_CONTRACT_VERSION, } from "./system/invites-contract";
+export { getLocalFoldersContractDefinition, type ILocalFolderChange, type ILocalFolderChangedEvent, type ILocalFolderEntry, type ILocalFolderFileBlocks, type ILocalFolderFileBlocksInput, type ILocalFolderGrantInfo, type ILocalFolderIndexInput, type ILocalFolderJobFinishedEvent, type ILocalFolderJobHandle, type ILocalFolderJobInfo, type ILocalFolderJobProgressEvent, type ILocalFolderListInput, type ILocalFolderMoveInput, type ILocalFolderPathInput, type ILocalFolderPurgeTrashInput, type ILocalFolderReadRangeInput, type ILocalFolderReadRangeResult, type ILocalFolderRequestGrantInput, type ILocalFolderStatInput, LOCAL_FOLDERS_CHUNK_AVG, LOCAL_FOLDERS_CHUNK_MAX, LOCAL_FOLDERS_CHUNK_MIN, LOCAL_FOLDERS_CONTRACT_VERSION, LOCAL_FOLDERS_JOB_TTL_MS, LOCAL_FOLDERS_READ_RANGE_MAX, LOCAL_FOLDERS_RESERVED_DIR, type LocalFolderChangeKind, type LocalFolderEntryKind, type LocalFolderMode, localFoldersProviderPackageId, } from "./system/local-folders-contract";
 export { getLogsContractDefinition, type ILogsConsumer, LOGS_CONTRACT_VERSION, resolveLogsContract, } from "./system/logs-contract";
 export * from "./system/network-contracts";
 export { getToolAccessControlContractDefinition, type IToolAccessControlConsumer, TOOL_ACCESS_CONTROL_CONTRACT_VERSION, } from "./system/tool-access-control-contract";

package/dist/contracts/index.js

@@ -15,7 +15,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEVICE_OPERATIONS_MAX_ROWS = exports.DEVICE_OPERATIONS_MAX_RESULT_BYTES = exports.DEVICE_OPERATIONS_MAX_QUERY_LENGTH = exports.DEVICE_OPERATIONS_CONTRACT_VERSION = exports.setRemoteContractTransportFactory = exports.resolveRemoteTargetEndpoint = exports.getRemoteContractTransportFactory = exports.createRemoteContractEndpoint = exports.ContractRegistry = exports.PersistentContractRegistry = exports.waitForHostContractTransport = exports.subscribeHostContractTransport = exports.registerHostContractTransport = exports.getHostContractTransport = exports.hostContractConsumer = exports.setSchemaToFieldsFn = exports.extractToolShape = exports.extractTableShape = exports.createLocalContractConsumer = exports.contractsSchema = exports.contractsMetaData = exports.ContractsTable = exports.Contracts = exports.inProcessTransportPair = exports.connectionContractTransport = exports.CONTRACT_REQUEST_CHANNEL = exports.CONTRACT_NOTIFY_CHANNEL = exports.verifyRemoteContractIdentity = exports.registerContractResolver = exports.isSelfTrustedContractCaller = exports.handleContractCall = exports.getContractResolver = exports.createUserContextContractProviderRouter = exports.createLocalUserContextContractProviderRouter = exports.authorizeRemoteContractCall = exports.sameUserContractPermissionCheck = exports.createRemoteContractConsumer = exports.createContractProviderSession = exports.createContractProviderEndpoint = exports.createContractProvider = exports.createContractConsumer = exports.CONTRACT_CALL_RPC = exports.contractProvidersSchema = exports.contractProvidersMetaData = exports.ContractProvidersTable = exports.ContractProviders = exports.createContractProviderRouter = exports.PackageBuilder = exports.definePackage = exports.ContractBuilder = void 0;
-exports.validateProviderSatisfiesContract = exports.validateImmutability = exports.validateAlsoImplements = exports.contractKey = exports.registerSystemContract = exports.listSystemContracts = exports.installSystemContracts = exports.TOOL_ACCESS_CONTROL_CONTRACT_VERSION = exports.getToolAccessControlContractDefinition = exports.resolveLogsContract = exports.LOGS_CONTRACT_VERSION = exports.getLogsContractDefinition = exports.INVITES_CONTRACT_VERSION = exports.getInvitesContractDefinition = exports.IDENTITY_CONTRACT_VERSION = exports.getIdentityContractDefinition = exports.getDeviceOperationsContractDefinition = exports.deviceOperationsToolIds = exports.deviceOperationsProviderPackageId = exports.DEVICE_OPERATIONS_MAX_TOOLS = void 0;
+exports.validateProviderSatisfiesContract = exports.validateImmutability = exports.validateAlsoImplements = exports.contractKey = exports.registerSystemContract = exports.listSystemContracts = exports.installSystemContracts = exports.TOOL_ACCESS_CONTROL_CONTRACT_VERSION = exports.getToolAccessControlContractDefinition = exports.resolveLogsContract = exports.LOGS_CONTRACT_VERSION = exports.getLogsContractDefinition = exports.localFoldersProviderPackageId = exports.LOCAL_FOLDERS_RESERVED_DIR = exports.LOCAL_FOLDERS_READ_RANGE_MAX = exports.LOCAL_FOLDERS_JOB_TTL_MS = exports.LOCAL_FOLDERS_CONTRACT_VERSION = exports.LOCAL_FOLDERS_CHUNK_MIN = exports.LOCAL_FOLDERS_CHUNK_MAX = exports.LOCAL_FOLDERS_CHUNK_AVG = exports.getLocalFoldersContractDefinition = exports.INVITES_CONTRACT_VERSION = exports.getInvitesContractDefinition = exports.IDENTITY_CONTRACT_VERSION = exports.getIdentityContractDefinition = exports.getDeviceOperationsContractDefinition = exports.deviceOperationsToolIds = exports.deviceOperationsProviderPackageId = exports.DEVICE_OPERATIONS_MAX_TOOLS = void 0;
 var builder_1 = require("./builder");
 Object.defineProperty(exports, "ContractBuilder", { enumerable: true, get: function () { return builder_1.ContractBuilder; } });
 Object.defineProperty(exports, "definePackage", { enumerable: true, get: function () { return builder_1.definePackage; } });
@@ -91,6 +91,16 @@ Object.defineProperty(exports, "IDENTITY_CONTRACT_VERSION", { enumerable: true,
 var invites_contract_1 = require("./system/invites-contract");
 Object.defineProperty(exports, "getInvitesContractDefinition", { enumerable: true, get: function () { return invites_contract_1.getInvitesContractDefinition; } });
 Object.defineProperty(exports, "INVITES_CONTRACT_VERSION", { enumerable: true, get: function () { return invites_contract_1.INVITES_CONTRACT_VERSION; } });
+var local_folders_contract_1 = require("./system/local-folders-contract");
+Object.defineProperty(exports, "getLocalFoldersContractDefinition", { enumerable: true, get: function () { return local_folders_contract_1.getLocalFoldersContractDefinition; } });
+Object.defineProperty(exports, "LOCAL_FOLDERS_CHUNK_AVG", { enumerable: true, get: function () { return local_folders_contract_1.LOCAL_FOLDERS_CHUNK_AVG; } });
+Object.defineProperty(exports, "LOCAL_FOLDERS_CHUNK_MAX", { enumerable: true, get: function () { return local_folders_contract_1.LOCAL_FOLDERS_CHUNK_MAX; } });
+Object.defineProperty(exports, "LOCAL_FOLDERS_CHUNK_MIN", { enumerable: true, get: function () { return local_folders_contract_1.LOCAL_FOLDERS_CHUNK_MIN; } });
+Object.defineProperty(exports, "LOCAL_FOLDERS_CONTRACT_VERSION", { enumerable: true, get: function () { return local_folders_contract_1.LOCAL_FOLDERS_CONTRACT_VERSION; } });
+Object.defineProperty(exports, "LOCAL_FOLDERS_JOB_TTL_MS", { enumerable: true, get: function () { return local_folders_contract_1.LOCAL_FOLDERS_JOB_TTL_MS; } });
+Object.defineProperty(exports, "LOCAL_FOLDERS_READ_RANGE_MAX", { enumerable: true, get: function () { return local_folders_contract_1.LOCAL_FOLDERS_READ_RANGE_MAX; } });
+Object.defineProperty(exports, "LOCAL_FOLDERS_RESERVED_DIR", { enumerable: true, get: function () { return local_folders_contract_1.LOCAL_FOLDERS_RESERVED_DIR; } });
+Object.defineProperty(exports, "localFoldersProviderPackageId", { enumerable: true, get: function () { return local_folders_contract_1.localFoldersProviderPackageId; } });
 var logs_contract_1 = require("./system/logs-contract");
 Object.defineProperty(exports, "getLogsContractDefinition", { enumerable: true, get: function () { return logs_contract_1.getLogsContractDefinition; } });
 Object.defineProperty(exports, "LOGS_CONTRACT_VERSION", { enumerable: true, get: function () { return logs_contract_1.LOGS_CONTRACT_VERSION; } });

package/dist/contracts/system/local-folders-contract.d.ts

@@ -0,0 +1,163 @@
+import type { IContractDefinition } from "../types";
+/** Version of the built-in System Local Folders contract. */
+export declare const LOCAL_FOLDERS_CONTRACT_VERSION = 1;
+/** Maximum byte length accepted by `readRange` in one call. */
+export declare const LOCAL_FOLDERS_READ_RANGE_MAX: number;
+/** FastCDC minimum block size. Files at or below this size are one block. */
+export declare const LOCAL_FOLDERS_CHUNK_MIN: number;
+/** FastCDC target average block size. */
+export declare const LOCAL_FOLDERS_CHUNK_AVG: number;
+/** FastCDC maximum block size. */
+export declare const LOCAL_FOLDERS_CHUNK_MAX: number;
+/** Directory name reserved inside every grant for trash and in-flight files. */
+export declare const LOCAL_FOLDERS_RESERVED_DIR = ".peers";
+/** How long finished index jobs stay readable via `getJob`. */
+export declare const LOCAL_FOLDERS_JOB_TTL_MS: number;
+/** Package ID used by live System Local Folders tool instances. */
+export declare const localFoldersProviderPackageId = "000peers0system0000000001";
+/** Grant mode accepted by `requestGrant`. */
+export type LocalFolderMode = "read" | "readwrite";
+/** Filesystem entry kind returned by `list` and `stat`. */
+export type LocalFolderEntryKind = "file" | "dir" | "symlink";
+/** Watcher change kind delivered on the `changed` event. */
+export type LocalFolderChangeKind = "created" | "modified" | "deleted" | "renamed";
+/** Input for {@link ILocalFoldersConsumer tools.requestGrant}. */
+export interface ILocalFolderRequestGrantInput {
+    groupId: string;
+    mode: LocalFolderMode;
+    /** Operator-only. Ignored when an isolated package is the caller. */
+    packageId?: string;
+    /**
+     * Operator-only absolute path. Isolated callers cannot set this.
+     * Omit it on a desktop host to open the folder picker.
+     */
+    absolutePath?: string;
+}
+/** One active grant returned by `requestGrant` and `listGrants`. */
+export interface ILocalFolderGrantInfo {
+    grantId: string;
+    groupId: string;
+    absolutePath: string;
+    mode: LocalFolderMode;
+    packageId?: string;
+    createdAt: number;
+}
+/** Input for listing a directory inside a grant. */
+export interface ILocalFolderListInput {
+    grantId: string;
+    /** Relative path. Empty lists the grant root. */
+    relPath?: string;
+    recursive?: boolean;
+}
+/** One directory entry. */
+export interface ILocalFolderEntry {
+    relPath: string;
+    name: string;
+    kind: LocalFolderEntryKind;
+    size: number;
+    mtimeMs: number;
+    inode: string;
+}
+/** Input for `stat`. */
+export interface ILocalFolderStatInput {
+    grantId: string;
+    relPath: string;
+}
+/** Input for a bounded read. `length` is capped at {@link LOCAL_FOLDERS_READ_RANGE_MAX}. */
+export interface ILocalFolderReadRangeInput {
+    grantId: string;
+    relPath: string;
+    offset: number;
+    length: number;
+}
+/** Bytes returned by `readRange`. `data` is a base64 string so it survives JSON tool results. */
+export interface ILocalFolderReadRangeResult {
+    dataBase64: string;
+    bytesRead: number;
+}
+/** Input for starting an index job. */
+export interface ILocalFolderIndexInput {
+    grantId: string;
+    /** Relative directory or file. Empty indexes the whole grant. */
+    relPath?: string;
+}
+/** Handle returned by `index`. */
+export interface ILocalFolderJobHandle {
+    jobId: string;
+}
+/** Input for `getFileBlocks`. */
+export interface ILocalFolderFileBlocksInput {
+    grantId: string;
+    /** Relative file path. */
+    relPath: string;
+}
+/** Indexed blocks for one file. `indexed` is false when the path has no index row. */
+export interface ILocalFolderFileBlocks {
+    indexed: boolean;
+    size?: number;
+    mtimeMs?: number;
+    blocks: {
+        hash: string;
+        size: number;
+    }[];
+}
+/** Index job snapshot returned by `getJob`. */
+export interface ILocalFolderJobInfo {
+    jobId: string;
+    kind: "index";
+    status: "running" | "done" | "error" | "cancelled";
+    done: number;
+    total: number;
+    error?: string;
+    result?: {
+        files: number;
+        rehashed: number;
+        skipped: number;
+        removed: number;
+    };
+}
+/** Input for `move`. */
+export interface ILocalFolderMoveInput {
+    grantId: string;
+    from: string;
+    to: string;
+}
+/** Input for `trash` and single-path tools. */
+export interface ILocalFolderPathInput {
+    grantId: string;
+    relPath: string;
+}
+/** Input for `purgeTrash`. */
+export interface ILocalFolderPurgeTrashInput {
+    grantId: string;
+    olderThanDays: number;
+}
+/** One path change inside a grant. */
+export interface ILocalFolderChange {
+    relPath: string;
+    kind: LocalFolderChangeKind;
+}
+/** Payload of the `changed` event. */
+export interface ILocalFolderChangedEvent {
+    grantId: string;
+    changes: ILocalFolderChange[];
+}
+/** Payload of the `jobProgress` event. */
+export interface ILocalFolderJobProgressEvent {
+    jobId: string;
+    done: number;
+    total: number;
+}
+/** Payload of the `jobFinished` event. */
+export interface ILocalFolderJobFinishedEvent {
+    jobId: string;
+    status: "done" | "error" | "cancelled";
+    error?: string;
+}
+/**
+ * Return the local-only System Local Folders contract shape.
+ *
+ * The host checks every path against an operator grant. Remote devices cannot call
+ * this contract; bytes between devices move through block exchange, not these tools.
+ */
+export declare function getLocalFoldersContractDefinition(): IContractDefinition;