@peers-app/peers-sdk 0.27.2 → 0.27.4

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

@@ -375,6 +375,13 @@ export interface IContractResolution {
     version: number;
     tables?: Record<string, Table<any>>;
     tools?: Record<string, IContractToolImplementation>;
+    /**
+     * Trusted runtime invocation after access checks, with host context already appended.
+     * It validates the requested version's input and checks endpoint liveness immediately
+     * before running provider code. Without it, dispatch validates the system definition or
+     * the implementation's declared input fields and calls the tool function directly.
+     */
+    invokeTool?: (name: string, args: any[]) => any;
     /**
      * Host-only capabilities appended as the final argument to provider tool functions.
      * Omit this for remote or otherwise untrusted provider routes.

package/dist/contracts/contract-proxy.js

@@ -15,6 +15,8 @@ const observable_1 = require("../observable");
 const utils_1 = require("../utils");
 const action_dispatch_1 = require("./action-dispatch");
 const contract_transport_1 = require("./contract-transport");
+const system_contracts_1 = require("./system-contracts");
+const tool_arguments_1 = require("./tool-arguments");
 const STANDARD_REMOTE_TABLE_METHODS = new Set([
     "get",
     "list",
@@ -594,6 +596,21 @@ function createContractProvider(resolution, opts = {}) {
                 }
                 const { workflow, ...caller } = context;
                 const authority = await assertContractToolAccess(tool, call, caller);
+                const invoke = (...args) => {
+                    if (resolution.invokeTool)
+                        return resolution.invokeTool(call.name, args);
+                    const definition = (0, system_contracts_1.listSystemContracts)()
+                        .find((entry) => (entry.contractId ?? entry.getDefinition().contractId) === call.contractId &&
+                        (entry.version ?? entry.getDefinition().version) === call.version)
+                        ?.getDefinition();
+                    const member = definition?.tools.find((entry) => entry.name === call.name);
+                    if (definition && !member)
+                        throw new Error(`Contract ${call.contractId} does not declare tool '${call.name}'`);
+                    const fields = member?.inputFields ?? tool.tool.inputSchema?.fields;
+                    if (fields?.length)
+                        (0, tool_arguments_1.checkToolArguments)(fields, call.args[0], call.name);
+                    return tool.toolFn(...args);
+                };
                 if (resolution.toolContext ||
                     resolution.forwardCallContext ||
                     authority.strictActionScope) {
@@ -621,7 +638,7 @@ function createContractProvider(resolution, opts = {}) {
                             authority: (0, action_dispatch_1.narrowActionPrincipal)(frame, true),
                         });
                     };
-                    return tool.toolFn(call.args[0], {
+                    return invoke(call.args[0], {
                         ...base,
                         workflow: caller.callerDeviceId || caller.callerPackageId ? undefined : workflow,
                         callerPackageId: caller.callerPackageId,
@@ -632,7 +649,7 @@ function createContractProvider(resolution, opts = {}) {
                         authority,
                     });
                 }
-                return tool.toolFn(...call.args);
+                return invoke(...call.args);
             }
             case "observable": {
                 const obs = resolution.observables?.[call.name];

package/dist/contracts/create-local-consumer.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createLocalContractConsumer = createLocalContractConsumer;
 const contract_proxy_1 = require("./contract-proxy");
 const contract_transport_1 = require("./contract-transport");
+const tool_arguments_1 = require("./tool-arguments");
 /**
  * Build a same-process contract consumer wired to a live provider resolution.
  *
@@ -12,7 +13,21 @@ const contract_transport_1 = require("./contract-transport");
  */
 function createLocalContractConsumer(definition, resolution, opts) {
     const [consumerTransport, providerTransport] = (0, contract_transport_1.inProcessTransportPair)();
-    (0, contract_proxy_1.createContractProviderSession)(resolution, providerTransport, { context: opts?.context });
+    (0, contract_proxy_1.createContractProviderSession)({
+        ...resolution,
+        invokeTool: resolution.invokeTool ??
+            ((name, args) => {
+                const tool = resolution.tools?.[name];
+                if (!tool)
+                    throw new Error(`Contract ${definition.contractId} does not provide tool '${name}'`);
+                const member = definition.tools.find((tool) => tool.name === name);
+                if (!member)
+                    throw new Error(`Contract ${definition.contractId} does not declare tool '${name}'`);
+                if (member.inputFields.length)
+                    (0, tool_arguments_1.checkToolArguments)(member.inputFields, args[0], name);
+                return tool.toolFn(...args);
+            }),
+    }, providerTransport, { context: opts?.context });
     return (0, contract_proxy_1.createContractConsumer)(definition, consumerTransport, {
         dataContextId: opts?.dataContextId,
     });

package/dist/contracts/index.d.ts

@@ -29,9 +29,11 @@ export { getLogsContractDefinition, type ILogsConsumer, LOGS_CONTRACT_VERSION, r
 export * from "./system/network-contracts";
 export * from "./system/packages-contract";
 export { getSchedulerContractDefinition, type IScheduleInfo, type IScheduleInput, type ISchedulerConsumer, SCHEDULER_CONTRACT_VERSION, SCHEDULER_MAX_DELAY_MS, schedulerProviderPackageId, } from "./system/scheduler-contract";
+export * from "./system/sync-check-contract";
 export { getToolAccessControlContractDefinition, type IToolAccessControlConsumer, TOOL_ACCESS_CONTROL_CONTRACT_VERSION, } from "./system/tool-access-control-contract";
 export * from "./system/tool-catalog-contract";
 export { type ISystemContractRegistration, installSystemContracts, isSystemContractId, listSystemContracts, registerSystemContract, } from "./system-contracts";
+export * from "./tool-arguments";
 export * from "./tool-catalog";
 export * from "./tool-catalog-identity";
 export * from "./tool-catalog-migrations";

package/dist/contracts/index.js

@@ -143,6 +143,7 @@ Object.defineProperty(exports, "getSchedulerContractDefinition", { enumerable: t
 Object.defineProperty(exports, "SCHEDULER_CONTRACT_VERSION", { enumerable: true, get: function () { return scheduler_contract_1.SCHEDULER_CONTRACT_VERSION; } });
 Object.defineProperty(exports, "SCHEDULER_MAX_DELAY_MS", { enumerable: true, get: function () { return scheduler_contract_1.SCHEDULER_MAX_DELAY_MS; } });
 Object.defineProperty(exports, "schedulerProviderPackageId", { enumerable: true, get: function () { return scheduler_contract_1.schedulerProviderPackageId; } });
+__exportStar(require("./system/sync-check-contract"), exports);
 var tool_access_control_contract_1 = require("./system/tool-access-control-contract");
 Object.defineProperty(exports, "getToolAccessControlContractDefinition", { enumerable: true, get: function () { return tool_access_control_contract_1.getToolAccessControlContractDefinition; } });
 Object.defineProperty(exports, "TOOL_ACCESS_CONTROL_CONTRACT_VERSION", { enumerable: true, get: function () { return tool_access_control_contract_1.TOOL_ACCESS_CONTROL_CONTRACT_VERSION; } });
@@ -152,6 +153,7 @@ Object.defineProperty(exports, "installSystemContracts", { enumerable: true, get
 Object.defineProperty(exports, "isSystemContractId", { enumerable: true, get: function () { return system_contracts_1.isSystemContractId; } });
 Object.defineProperty(exports, "listSystemContracts", { enumerable: true, get: function () { return system_contracts_1.listSystemContracts; } });
 Object.defineProperty(exports, "registerSystemContract", { enumerable: true, get: function () { return system_contracts_1.registerSystemContract; } });
+__exportStar(require("./tool-arguments"), exports);
 __exportStar(require("./tool-catalog"), exports);
 __exportStar(require("./tool-catalog-identity"), exports);
 __exportStar(require("./tool-catalog-migrations"), exports);

package/dist/contracts/system/index.d.ts

@@ -13,6 +13,7 @@ import "./logs-contract";
 import "./network-contracts";
 import "./packages-contract";
 import "./scheduler-contract";
+import "./sync-check-contract";
 import "./tool-access-control-contract";
 export * from "./app-updates-contract";
 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 "./device-operations-contract";
@@ -22,6 +23,7 @@ export { getInvitesContractDefinition, type IAcceptInviteResult, type ICreatedIn
 export { getLogsContractDefinition, type ILogsConsumer, LOGS_CONTRACT_VERSION, resolveLogsContract, } from "./logs-contract";
 export * from "./network-contracts";
 export * from "./packages-contract";
+export * from "./sync-check-contract";
 export { getToolAccessControlContractDefinition, type IToolAccessControlConsumer, TOOL_ACCESS_CONTROL_CONTRACT_VERSION, } from "./tool-access-control-contract";
 import "./tool-catalog-contract";
 export * from "./desktop-tools-contract";

package/dist/contracts/system/index.js

@@ -30,6 +30,7 @@ require("./logs-contract");
 require("./network-contracts");
 require("./packages-contract");
 require("./scheduler-contract");
+require("./sync-check-contract");
 require("./tool-access-control-contract");
 __exportStar(require("./app-updates-contract"), exports);
 var device_operations_contract_1 = require("./device-operations-contract");
@@ -54,6 +55,7 @@ Object.defineProperty(exports, "LOGS_CONTRACT_VERSION", { enumerable: true, get:
 Object.defineProperty(exports, "resolveLogsContract", { enumerable: true, get: function () { return logs_contract_1.resolveLogsContract; } });
 __exportStar(require("./network-contracts"), exports);
 __exportStar(require("./packages-contract"), exports);
+__exportStar(require("./sync-check-contract"), exports);
 var tool_access_control_contract_1 = require("./tool-access-control-contract");
 Object.defineProperty(exports, "getToolAccessControlContractDefinition", { enumerable: true, get: function () { return tool_access_control_contract_1.getToolAccessControlContractDefinition; } });
 Object.defineProperty(exports, "TOOL_ACCESS_CONTROL_CONTRACT_VERSION", { enumerable: true, get: function () { return tool_access_control_contract_1.TOOL_ACCESS_CONTROL_CONTRACT_VERSION; } });

package/dist/contracts/system/invites-contract.js

@@ -47,8 +47,9 @@ function getInvitesContractDefinition() {
                     field("expiresInMs", field_type_1.FieldType.number, "Lifetime override in milliseconds.", {
                         optional: true,
                     }),
-                    field("uses", field_type_1.FieldType.string, "1 or unlimited (default unlimited).", {
+                    field("uses", field_type_1.FieldType.any, "1 or unlimited (default unlimited).", {
                         optional: true,
+                        enumValues: [1, "unlimited"],
                     }),
                 ],
                 outputFields: [field("invite", field_type_1.FieldType.object, "The issued invite and encodings.")],

package/dist/contracts/system/sync-check-contract.d.ts

@@ -0,0 +1,97 @@
+import type { IChangeCount, ICountChangesRequest } from "../../data/change-tracking";
+import type { Observable } from "../../observable";
+import type { IContractConsumerBase } from "../contract-proxy";
+import type { IContractDefinition } from "../types";
+/** Version of the built-in System Sync Check contract. */
+export declare const SYNC_CHECK_CONTRACT_VERSION = 1;
+/** A device's answer to `countChanges`. */
+export interface ICountChangesResult {
+    /** Tables this device never syncs for the context; the asking device leaves them out too. */
+    excludedTableNames: string[];
+    counts: IChangeCount[];
+}
+/** One change another device has that this device is missing. */
+export interface IMissingChange {
+    changeId: string;
+    tableName: string;
+    recordId: string;
+    op: string;
+    path: string;
+    /** Author time. Hybrid-logical-clock milliseconds. */
+    createdAt: number;
+}
+/** What the check found when it compared this device with one other device in one context. */
+export interface ISyncGap {
+    dataContextId: string;
+    dataContextName: string;
+    /** The device that has the changes. */
+    deviceId: string;
+    deviceName?: string;
+    checkedAt: number;
+    /** Changes the other device has that this device is missing. */
+    missingCount: number;
+    /** Up to 100 of the missing changes, oldest first. */
+    missing: IMissingChange[];
+    /** True when the check stopped before comparing everything; there may be more. */
+    truncated: boolean;
+}
+/** Live summary of the latest checks on this device. */
+export interface ISyncCheckStatus {
+    /** Missing changes found, each counted once across contexts and devices. */
+    missingChangeCount: number;
+    /** When the latest check finished. */
+    lastCheckedAt?: number;
+}
+/** Result of `checkSyncGaps`. */
+export interface ISyncCheckResult {
+    /** Device comparisons that completed. Devices without the check are skipped. */
+    compared: number;
+    /** Missing changes found. */
+    missingCount: number;
+    /** At least one comparison stopped at its bound; another check continues it. */
+    truncated?: boolean;
+    message: string;
+}
+/** Result of `repairSyncGaps`. */
+export interface ISyncRepairResult {
+    /** Missing changes this device now holds. */
+    repaired: number;
+    /** Missing changes still found after the repair. */
+    remaining: number;
+    message: string;
+}
+/** Typed consumer proxy for System Sync Check v1. */
+export interface ISyncCheckConsumer extends IContractConsumerBase {
+    tools: {
+        /** Count this device's active changes in the call's context. Group Readers may call it. */
+        countChanges(input: ICountChangesRequest): Promise<ICountChangesResult>;
+        /** What the latest checks found, for one context or every context. Local callers only. */
+        getSyncGaps(input?: {
+            dataContextId?: string;
+        }): Promise<{
+            gaps: ISyncGap[];
+        }>;
+        /** Check now against each connected device. Local callers only. */
+        checkSyncGaps(input?: {
+            dataContextId?: string;
+        }): Promise<ISyncCheckResult>;
+        /** Fetch and apply the missing changes found in one context. Local callers only. */
+        repairSyncGaps(input: {
+            dataContextId: string;
+            deviceId?: string;
+        }): Promise<ISyncRepairResult>;
+    };
+    observables: {
+        /** Live summary; available over the local host transport only. */
+        status: Observable<ISyncCheckStatus>;
+    };
+}
+/**
+ * Return the System Sync Check contract shape.
+ *
+ * Once a day each device compares its change history for each personal and group context with
+ * each connected device's, and reports changes the other device has that this one is missing.
+ * `countChanges` is how devices compare: other devices in a group may call it with Reader
+ * access. The other tools serve this device's UI and CLI and refuse remote callers.
+ */
+export declare function getSyncCheckContractDefinition(): IContractDefinition;

package/dist/contracts/system/sync-check-contract.js

@@ -0,0 +1,115 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SYNC_CHECK_CONTRACT_VERSION = void 0;
+exports.getSyncCheckContractDefinition = getSyncCheckContractDefinition;
+const access_level_1 = require("../../data/access-level");
+const system_ids_1 = require("../../system-ids");
+const field_type_1 = require("../../types/field-type");
+const system_contracts_1 = require("../system-contracts");
+/** Version of the built-in System Sync Check contract. */
+exports.SYNC_CHECK_CONTRACT_VERSION = 1;
+const field = (name, type, description, opts = {}) => ({ name, type, description, ...opts });
+const contextInput = field("dataContextId", field_type_1.FieldType.id, "Personal or group context ID.", {
+    optional: true,
+});
+let definition;
+/**
+ * Return the System Sync Check contract shape.
+ *
+ * Once a day each device compares its change history for each personal and group context with
+ * each connected device's, and reports changes the other device has that this one is missing.
+ * `countChanges` is how devices compare: other devices in a group may call it with Reader
+ * access. The other tools serve this device's UI and CLI and refuse remote callers.
+ */
+function getSyncCheckContractDefinition() {
+    definition ??= {
+        contractId: system_ids_1.syncCheckContractId,
+        version: exports.SYNC_CHECK_CONTRACT_VERSION,
+        devTag: "dev",
+        name: "System Sync Check",
+        description: "Find changes another device has that this device is missing, and repair them.",
+        tables: [],
+        tools: [
+            {
+                name: "countChanges",
+                usageDescription: "Count this device's active changes per table, or per table and change-id prefix, with a digest of their ids.",
+                inputFields: [
+                    field("before", field_type_1.FieldType.string, "Count only change ids below this one."),
+                    field("excludedTableNames", field_type_1.FieldType.string, "Tables to leave out.", {
+                        optional: true,
+                        isArray: true,
+                    }),
+                    field("tableName", field_type_1.FieldType.string, "Count only this table.", { optional: true }),
+                    field("prefix", field_type_1.FieldType.string, "Count only ids that start with this.", {
+                        optional: true,
+                    }),
+                    field("prefixLength", field_type_1.FieldType.number, "Also group by this many id characters.", {
+                        optional: true,
+                    }),
+                    field("afterPrefix", field_type_1.FieldType.string, "Resume after this prefix; grouped pages contain at most 500 rows.", {
+                        optional: true,
+                    }),
+                ],
+                outputFields: [
+                    field("excludedTableNames", field_type_1.FieldType.string, "Tables this device never syncs.", {
+                        isArray: true,
+                    }),
+                    field("counts", field_type_1.FieldType.object, "Counts and digests.", { isArray: true }),
+                ],
+                remoteAccessLevel: access_level_1.AccessLevel.Reader,
+            },
+            {
+                name: "getSyncGaps",
+                usageDescription: "List changes the latest checks found on another device but not here.",
+                inputFields: [contextInput],
+                outputFields: [
+                    field("gaps", field_type_1.FieldType.object, "Findings, one per context and device.", {
+                        isArray: true,
+                    }),
+                ],
+            },
+            {
+                name: "checkSyncGaps",
+                usageDescription: "Compare one context, or every context, with each connected device now. Only reports.",
+                inputFields: [contextInput],
+                outputFields: [
+                    field("compared", field_type_1.FieldType.number, "Device comparisons that completed."),
+                    field("missingCount", field_type_1.FieldType.number, "Missing changes found."),
+                    field("truncated", field_type_1.FieldType.boolean, "Another check is needed to finish a bounded comparison.", { optional: true }),
+                    field("message", field_type_1.FieldType.string, "Human-readable result."),
+                ],
+            },
+            {
+                name: "repairSyncGaps",
+                usageDescription: "Fetch the missing changes found in one context from the devices that have them and apply them as sync would.",
+                inputFields: [
+                    field("dataContextId", field_type_1.FieldType.id, "Personal or group context ID."),
+                    field("deviceId", field_type_1.FieldType.id, "Repair only what this device has.", {
+                        optional: true,
+                    }),
+                ],
+                outputFields: [
+                    field("repaired", field_type_1.FieldType.number, "Missing changes this device now holds."),
+                    field("remaining", field_type_1.FieldType.number, "Missing changes still found."),
+                    field("message", field_type_1.FieldType.string, "Human-readable result."),
+                ],
+            },
+        ],
+        observables: [
+            {
+                name: "status",
+                description: "Live summary of the latest checks on this device.",
+                valueType: field_type_1.FieldType.object,
+                writable: false,
+            },
+        ],
+        events: [],
+    };
+    return definition;
+}
+(0, system_contracts_1.registerSystemContract)({
+    providerPackageId: system_ids_1.peersSystemPackageId,
+    contractId: system_ids_1.syncCheckContractId,
+    version: exports.SYNC_CHECK_CONTRACT_VERSION,
+    getDefinition: getSyncCheckContractDefinition,
+});

package/dist/contracts/tool-arguments.d.ts

@@ -0,0 +1,15 @@
+import { type IField } from "../types/field-type";
+/**
+ * Check a contract tool's arguments against its declared input fields. The Runtime does this
+ * before every tool run, whoever calls: the UI, the CLI, an assistant, a package, or another
+ * device. A missing or `null` input counts as `{}`. Optional fields that are `null` are left
+ * out first, and an ISO string in a `Date` field is read as a date.
+ *
+ * @param fields - The tool's input fields, from its contract definition.
+ * @param input - The tool's argument as the caller sent it.
+ * @param toolName - The tool's name, for the error message.
+ * @returns The arguments without empty optional fields and with `Date` fields as dates.
+ * @throws If the input isn't an object, or a field is missing, of the wrong type, or not one
+ *   of its allowed values.
+ */
+export declare function checkToolArguments(fields: IField[], input: unknown, toolName: string): Record<string, unknown>;

package/dist/contracts/tool-arguments.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkToolArguments = checkToolArguments;
+const types_1 = require("../data/orm/types");
+const field_type_1 = require("../types/field-type");
+/**
+ * Check a contract tool's arguments against its declared input fields. The Runtime does this
+ * before every tool run, whoever calls: the UI, the CLI, an assistant, a package, or another
+ * device. A missing or `null` input counts as `{}`. Optional fields that are `null` are left
+ * out first, and an ISO string in a `Date` field is read as a date.
+ *
+ * @param fields - The tool's input fields, from its contract definition.
+ * @param input - The tool's argument as the caller sent it.
+ * @param toolName - The tool's name, for the error message.
+ * @returns The arguments without empty optional fields and with `Date` fields as dates.
+ * @throws If the input isn't an object, or a field is missing, of the wrong type, or not one
+ *   of its allowed values.
+ */
+function checkToolArguments(fields, input, toolName) {
+    const source = input ?? {};
+    if (typeof source !== "object" ||
+        Array.isArray(source) ||
+        (Object.getPrototypeOf(source) !== Object.prototype && Object.getPrototypeOf(source) !== null)) {
+        throw new Error(`Tool argument validation failed for ${toolName}: input must be an object`);
+    }
+    // An optional argument that is null (as models often send) or undefined is left out.
+    const args = (0, types_1.withoutEmptyFields)(fields, { ...source });
+    for (const field of fields) {
+        if (field.type === field_type_1.FieldType.Date && !field.isArray && typeof args[field.name] === "string") {
+            args[field.name] = new Date(args[field.name]);
+        }
+    }
+    // Zod reads named properties, including inherited ones. Object.prototype must not supply
+    // a missing argument such as `constructor`, or invalidate an omitted optional one.
+    const result = (0, types_1.fieldsToArgumentsSchema)(fields).safeParse(Object.assign(Object.create(null), args));
+    if (!result.success) {
+        const problems = result.error.issues.map((issue) => `${issue.path.join(".") || "input"}: ${issue.message}`);
+        throw new Error(`Tool argument validation failed for ${toolName}: ${problems.join("; ")}`);
+    }
+    return args;
+}

package/dist/contracts/tool-catalog-service.js

@@ -8,15 +8,14 @@ exports.findToolCatalogEntry = findToolCatalogEntry;
 exports.projectToolCatalogAccess = projectToolCatalogAccess;
 exports.invokeToolCatalogTool = invokeToolCatalogTool;
 const group_permissions_1 = require("../data/group-permissions");
-const types_1 = require("../data/orm/types");
 const tool_access_1 = require("../data/tool-access");
 const tools_1 = require("../data/tools");
 const system_ids_1 = require("../system-ids");
-const field_type_1 = require("../types/field-type");
 const utils_1 = require("../utils");
 const contract_provider_router_1 = require("./contract-provider-router");
 const contract_resolvers_1 = require("./contract-resolvers");
 const system_contracts_1 = require("./system-contracts");
+const tool_arguments_1 = require("./tool-arguments");
 const tool_catalog_1 = require("./tool-catalog");
 const tool_catalog_identity_1 = require("./tool-catalog-identity");
 const tool_catalog_migrations_1 = require("./tool-catalog-migrations");
@@ -258,16 +257,7 @@ async function invokeToolCatalogTool(dataContext, input, context, opts = {}) {
             if (liveLevel === undefined || liveLevel > opts.maxAccessLevel)
                 throw new Error("Tool provider access level exceeds the authorized workflow call");
         }
-        const source = input.args === undefined ? {} : input.args;
-        requirePlainObject(source, "Tool args");
-        // An optional argument that is null (as models often send) or undefined is left out.
-        const args = (0, types_1.withoutEmptyFields)(tool.inputFields, { ...source });
-        for (const field of tool.inputFields)
-            if (field.type === field_type_1.FieldType.Date && !field.isArray && typeof args[field.name] === "string")
-                args[field.name] = new Date(args[field.name]);
-        const validated = (0, types_1.fieldsToSchema)(tool.inputFields).passthrough().safeParse(args);
-        if (!validated.success)
-            throw new Error(`Tool argument validation failed: ${validated.error.message}`);
+        const args = (0, tool_arguments_1.checkToolArguments)(tool.inputFields, input.args, target.toolName);
         const dataContextId = dataContext.dataContextId;
         const { workflow: _workflow, ...caller } = context;
         const endpointContext = loader.isolatedRuntime?.isInstalled(providerPackageId)

package/dist/data/change-tracking.d.ts

@@ -51,6 +51,37 @@ export declare const changeRecordSchema: z.ZodObject<{
  * One JSON-patch operation (or root snapshot / delete) stored for synchronization.
  */
 export type IChangeRecord = z.infer<typeof changeRecordSchema>;
+/** Which active changes {@link ChangeTrackingTable.countChanges} counts, and how it groups them. */
+export interface ICountChangesRequest {
+    /**
+     * Count only change ids below this one. The first 10 characters of a change id are its author
+     * time in base36 milliseconds, so a 10-character prefix counts changes written before then.
+     */
+    before: string;
+    /** Tables to leave out. */
+    excludedTableNames?: string[];
+    /** Count only this table. */
+    tableName?: string;
+    /** Count only change ids that start with this. */
+    prefix?: string;
+    /** Group by the first this-many characters of the change id as well as by table. */
+    prefixLength?: number;
+    /** Count ids after this entire prefix; also resumes grouped pages (at most 500 rows each). */
+    afterPrefix?: string;
+}
+/** Number of active changes in one table (and one id prefix), with a digest of their ids. */
+export interface IChangeCount {
+    tableName: string;
+    /** The id prefix counted, when the request set `prefixLength`. */
+    prefix?: string;
+    count: number;
+    /**
+     * Two sums of numbers taken from the last 10 characters of each change id, as decimal text.
+     * Equal counts with different sums mean different changes, such as one device missing an edit
+     * that replaced an earlier change.
+     */
+    sums: string;
+}
 /**
  * Local-only change log used for peer sync.
  *
@@ -134,6 +165,15 @@ export declare class ChangeTrackingTable extends SQLDataSource<IChangeRecord> {
      * @returns Array of changeIds with no change records
      */
     filterToMissingChangeIds(changeIds: string[]): Promise<string[]>;
+    /**
+     * Count active changes per table, or per table and change-id prefix, with a digest of their ids.
+     * Two devices holding the same active changes get the same results. One scan of the
+     * `(tableName, supersededAt)` index, which holds every change id.
+     *
+     * @param request - Which changes to count and how to group them
+     * @returns One row per table (and prefix) that has any active changes
+     */
+    countChanges(request: ICountChangesRequest): Promise<IChangeCount[]>;
     /**
      * Mark every still-active change for `recordId` whose `createdAt` is older
      * than `supersededAt`. Used after a root snapshot, delete, or restore.

package/dist/data/change-tracking.js

@@ -37,6 +37,12 @@ exports.changeRecordSchema = zod_1.z.object({
         .describe("Local apply / sync-visibility time; assigned at insert, incoming values replaced"),
     supersededAt: zod_1.z.number().optional().describe("When this change was superseded; unset if active"),
 });
+/** Five id characters starting at `start`, read as one base-128 number. */
+function idTailNumber(start) {
+    return [0, 1, 2, 3, 4]
+        .map((i) => `${128 ** (4 - i)} * unicode(substr(changeId, ${start + i}, 1))`)
+        .join(" + ");
+}
 const changeTrackingV2TableMetaData = {
     name: "ChangeTrackingV2",
     primaryKeyName: "changeId",
@@ -228,6 +234,89 @@ class ChangeTrackingTable extends orm_1.SQLDataSource {
     `, changeIds);
         return missingChangeIds.map((d) => d.changeId);
     }
+    /**
+     * Count active changes per table, or per table and change-id prefix, with a digest of their ids.
+     * Two devices holding the same active changes get the same results. One scan of the
+     * `(tableName, supersededAt)` index, which holds every change id.
+     *
+     * @param request - Which changes to count and how to group them
+     * @returns One row per table (and prefix) that has any active changes
+     */
+    async countChanges(request) {
+        if (!request ||
+            typeof request.before !== "string" ||
+            !/^[0-9a-z]{1,25}$/i.test(request.before) ||
+            (request.tableName !== undefined &&
+                (typeof request.tableName !== "string" ||
+                    !request.tableName ||
+                    request.tableName.length > 256)) ||
+            (request.prefix !== undefined &&
+                (typeof request.prefix !== "string" || !/^[0-9a-z]{0,25}$/i.test(request.prefix))) ||
+            (request.prefixLength !== undefined &&
+                (!Number.isInteger(request.prefixLength) ||
+                    request.prefixLength < 1 ||
+                    request.prefixLength > 25 ||
+                    !request.tableName ||
+                    request.prefixLength <= (request.prefix?.length ?? 0))) ||
+            (request.afterPrefix !== undefined &&
+                (typeof request.afterPrefix !== "string" ||
+                    !request.tableName ||
+                    !/^[0-9a-z]{1,25}$/i.test(request.afterPrefix))) ||
+            (request.excludedTableNames !== undefined &&
+                (!Array.isArray(request.excludedTableNames) ||
+                    request.excludedTableNames.some((name) => typeof name !== "string" || name.length > 256)))) {
+            throw new Error("Invalid countChanges request");
+        }
+        await this.initTable();
+        const { before, excludedTableNames = [], tableName, prefix, prefixLength, afterPrefix, } = request;
+        const conditions = ["supersededAt IS NULL", "changeId < ?"];
+        const params = [before];
+        // Without one table, list the table names with a seek per name. Without index statistics,
+        // SQLite would otherwise read every row through the (supersededAt, ...) index, which lacks
+        // tableName, instead of scanning the covering one.
+        let tableNames = "";
+        if (tableName !== undefined) {
+            conditions.push("tableName = ?");
+            params.push(tableName);
+        }
+        else {
+            tableNames = `WITH RECURSIVE names(name) AS (
+           SELECT MIN(tableName) FROM "${this.tableName}"
+           UNION ALL
+           SELECT (SELECT MIN(tableName) FROM "${this.tableName}" WHERE tableName > names.name)
+           FROM names WHERE names.name IS NOT NULL
+         )`;
+            conditions.push("tableName IN (SELECT name FROM names)");
+        }
+        if (excludedTableNames.length) {
+            conditions.push(`tableName NOT IN (${excludedTableNames.map(() => "?").join(", ")})`);
+            params.push(...excludedTableNames);
+        }
+        if (prefix) {
+            // Change ids are lowercase base36, so every id with this prefix sorts below `prefix~`.
+            conditions.push("changeId >= ?", "changeId < ?");
+            params.push(prefix, `${prefix}~`);
+        }
+        if (afterPrefix) {
+            conditions.push("changeId > ?");
+            params.push(`${afterPrefix}~`);
+        }
+        const length = prefixLength ?? 0;
+        const prefixColumn = length ? `, substr(changeId, 1, ${length}) AS prefix` : "";
+        const rows = await this.db.all(`${tableNames}
+         SELECT tableName${prefixColumn}, COUNT(*) AS count,
+           CAST(SUM(${idTailNumber(16)}) AS TEXT) || ':' || CAST(SUM(${idTailNumber(21)}) AS TEXT) AS sums
+         FROM "${this.tableName}"
+         WHERE ${conditions.join(" AND ")}
+         GROUP BY tableName${length ? ", prefix" : ""}
+         ORDER BY tableName${length ? ", prefix LIMIT 500" : ""}`, params);
+        return rows.map((row) => ({
+            tableName: row.tableName,
+            ...(length ? { prefix: row.prefix } : {}),
+            count: Number(row.count),
+            sums: String(row.sums),
+        }));
+    }
     /**
      * Mark every still-active change for `recordId` whose `createdAt` is older
      * than `supersededAt`. Used after a root snapshot, delete, or restore.