@peers-app/peers-sdk 0.25.21 → 0.26.1

package/dist/contracts/system/tool-catalog-contract.d.ts

@@ -0,0 +1,73 @@
+import type { ITool } from "../../data/tools";
+import type { IContractConsumerBase } from "../contract-proxy";
+import type { ToolCatalogTarget } from "../tool-catalog-identity";
+import type { IContractDefinition } from "../types";
+/** Version of the local System Tool Catalog API. */
+export declare const TOOL_CATALOG_CONTRACT_VERSION = 1;
+/** Built-in provider of the System Tool Catalog. */
+export declare const toolCatalogProviderPackageId = "000peers0system0000000001";
+/** Permanent tool metadata combined with this context's live dispatch and policy state. */
+export interface IToolCatalogEntry {
+    toolId: string;
+    aliases: string[];
+    name: string;
+    usageDescription: string;
+    inputSchema: ITool["inputSchema"];
+    outputSchema: ITool["outputSchema"];
+    catalogState: ITool["catalogState"];
+    catalogIdentity: ITool["catalogIdentity"];
+    target?: ToolCatalogTarget;
+    workflowInvocable: boolean;
+    availability: {
+        dispatch: "contract" | "unavailable";
+        reason?: string;
+        message?: string;
+        requiresWorkflowRun?: boolean;
+    };
+    provider?: {
+        activePackageId?: string;
+        registeredPackageIds: string[];
+        implementation?: {
+            contractId: string;
+            version: number;
+        };
+    };
+    access?: {
+        accessLevel: number;
+        callerAccessLevel: number;
+        allowed: boolean;
+    };
+}
+/** Bounded text discovery in one data context. */
+export interface IListToolCatalogInput {
+    query?: string;
+    limit?: number;
+}
+/** Exact ID, exact name, then unambiguous text lookup. */
+export interface IGetToolCatalogInput {
+    toolIdOrName: string;
+    runnableOnly?: boolean;
+}
+/** Checked contract invocation; caller authority is never accepted in this payload. */
+export interface IInvokeToolCatalogInput {
+    toolId: string;
+    args?: Record<string, unknown>;
+    providerPackageId?: string;
+    fallbackToDefaultProvider?: boolean;
+}
+/** Authenticated local CLI/UI consumer of the System Tool Catalog. */
+export interface IToolCatalogConsumer extends IContractConsumerBase {
+    tools: {
+        listTools(input: IListToolCatalogInput): Promise<{
+            tools: IToolCatalogEntry[];
+        }>;
+        getTool(input: IGetToolCatalogInput): Promise<{
+            tool?: IToolCatalogEntry;
+        }>;
+        invokeTool(input: IInvokeToolCatalogInput): Promise<{
+            result: unknown;
+        }>;
+    };
+}
+/** Return the local-only discovery and checked contract invocation definition. */
+export declare function getToolCatalogContractDefinition(): IContractDefinition;

package/dist/contracts/system/tool-catalog-contract.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toolCatalogProviderPackageId = exports.TOOL_CATALOG_CONTRACT_VERSION = void 0;
+exports.getToolCatalogContractDefinition = getToolCatalogContractDefinition;
+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 local System Tool Catalog API. */
+exports.TOOL_CATALOG_CONTRACT_VERSION = 1;
+/** Built-in provider of the System Tool Catalog. */
+exports.toolCatalogProviderPackageId = system_ids_1.peersSystemPackageId;
+const field = (name, type, description, optional = false) => ({
+    name,
+    type,
+    description,
+    optional,
+});
+let definition;
+/** Return the local-only discovery and checked contract invocation definition. */
+function getToolCatalogContractDefinition() {
+    definition ??= {
+        contractId: system_ids_1.toolCatalogContractId,
+        version: exports.TOOL_CATALOG_CONTRACT_VERSION,
+        devTag: "dev",
+        name: "System Tool Catalog",
+        description: "Discover tools and invoke their selected contract providers.",
+        tables: [],
+        observables: [],
+        events: [],
+        tools: [
+            {
+                name: "listTools",
+                usageDescription: "List tool metadata and current dispatch availability.",
+                inputFields: [
+                    field("query", field_type_1.FieldType.string, "Text query.", true),
+                    field("limit", field_type_1.FieldType.number, "Maximum rows (up to 500).", true),
+                ],
+                outputFields: [{ ...field("tools", field_type_1.FieldType.object, "Catalog entries."), isArray: true }],
+            },
+            {
+                name: "getTool",
+                usageDescription: "Find one tool by ID, exact name or unambiguous text.",
+                inputFields: [
+                    field("toolIdOrName", field_type_1.FieldType.string, "ID or name."),
+                    field("runnableOnly", field_type_1.FieldType.boolean, "Exclude unavailable name/text matches.", true),
+                ],
+                outputFields: [field("tool", field_type_1.FieldType.object, "Catalog entry, if found.", true)],
+            },
+            {
+                name: "invokeTool",
+                usageDescription: "Validate arguments and invoke a contract tool as the original caller.",
+                inputFields: [
+                    // The shipped Scheduler alias has 26 characters; global isid stays strict.
+                    field("toolId", field_type_1.FieldType.string, "Catalog tool ID."),
+                    field("args", field_type_1.FieldType.object, "Target arguments.", true),
+                    field("providerPackageId", field_type_1.FieldType.id, "Preferred provider package.", true),
+                    field("fallbackToDefaultProvider", field_type_1.FieldType.boolean, "Allow the active provider when the preference is missing.", true),
+                ],
+                outputFields: [field("result", field_type_1.FieldType.any, "Target result.")],
+            },
+        ],
+    };
+    return definition;
+}
+(0, system_contracts_1.registerSystemContract)({
+    providerPackageId: exports.toolCatalogProviderPackageId,
+    contractId: system_ids_1.toolCatalogContractId,
+    version: exports.TOOL_CATALOG_CONTRACT_VERSION,
+    getDefinition: getToolCatalogContractDefinition,
+});

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

@@ -36,7 +36,7 @@ export declare function registerSystemContract(registration: ISystemContractRegi
  * Register every known system contract into `registry` as a provider.
  * Safe to call more than once for the same registry (provider updates in place).
  */
-export declare function installSystemContracts(registry: ContractRegistry): void;
+export declare function installSystemContracts(registry: ContractRegistry): Promise<void>;
 /** Snapshot of registered system contracts (for tests and diagnostics). */
 export declare function listSystemContracts(): readonly ISystemContractRegistration[];
 /**
@@ -45,3 +45,5 @@ export declare function listSystemContracts(): readonly ISystemContractRegistrat
  * @internal
  */
 export declare function _clearSystemContractsForTests(): void;
+/** Whether an identity belongs to a built-in system contract. */
+export declare function isSystemContractId(contractId: string): boolean;

package/dist/contracts/system-contracts.js

@@ -4,6 +4,7 @@ exports.registerSystemContract = registerSystemContract;
 exports.installSystemContracts = installSystemContracts;
 exports.listSystemContracts = listSystemContracts;
 exports._clearSystemContractsForTests = _clearSystemContractsForTests;
+exports.isSystemContractId = isSystemContractId;
 const systemContracts = [];
 function systemContractKey(contractId, version) {
     return `${contractId}@${version}`;
@@ -48,13 +49,22 @@ function registerSystemContract(registration) {
  * Register every known system contract into `registry` as a provider.
  * Safe to call more than once for the same registry (provider updates in place).
  */
-function installSystemContracts(registry) {
+async function installSystemContracts(registry) {
+    if (registry.toolCatalog) {
+        await registry.toolCatalog.ready();
+        return;
+    }
+    // Standalone registries have no DataContext/storage (schema tooling and tests).
+    const groups = new Map();
     for (const entry of systemContracts) {
-        const definition = entry.getDefinition();
-        const result = registry.register(entry.providerPackageId, definition);
-        if (!result.valid) {
-            console.error(`[SystemContracts] Failed to register ${definition.name} (${definition.contractId}@${definition.version}):`, result.errors);
-        }
+        const registrations = groups.get(entry.providerPackageId) ?? [];
+        registrations.push({ definition: entry.getDefinition() });
+        groups.set(entry.providerPackageId, registrations);
+    }
+    for (const [provider, registrations] of groups) {
+        const result = registry.replaceBatch(provider, registrations);
+        if (!result.valid)
+            throw new Error(result.errors.map((error) => error.message).join("; "));
     }
 }
 /** Snapshot of registered system contracts (for tests and diagnostics). */
@@ -69,3 +79,7 @@ function listSystemContracts() {
 function _clearSystemContractsForTests() {
     systemContracts.length = 0;
 }
+/** Whether an identity belongs to a built-in system contract. */
+function isSystemContractId(contractId) {
+    return systemContracts.some((entry) => (entry.contractId ?? entry.getDefinition().contractId) === contractId);
+}

package/dist/contracts/tool-catalog-identity.d.ts

@@ -0,0 +1,35 @@
+/** Case-sensitive public contract member identity, independent of any provider. */
+export interface ToolCatalogTarget {
+    contractId: string;
+    version: number;
+    toolName: string;
+}
+/** The shipped 26-character contract ID is accepted only by catalog target validation. */
+export declare const legacyCatalogContractId = "000peers0toolaccessctl0001";
+/** The shipped Scheduler list tool ID is accepted only by Tools identity validation. */
+export declare const legacyCatalogToolId = "00muxgugn661g0qmpuwafrmsi4";
+/** Validate a contract ID without weakening global peer-ID validation. */
+export declare function isCatalogContractId(value: string): boolean;
+/** Validate a Tools primary key, including the single shipped length exception. */
+export declare function isCatalogToolId(value: string): boolean;
+/** Validate exact names and well-formed Unicode; never trim or normalize identity input. */
+export declare function validateToolCatalogTarget(target: ToolCatalogTarget): void;
+/**
+ * Permanent v1 encoding approved in the Tools Catalog Foreman specification
+ * (2026-10-13): UTF-8 of compact JSON, including the domain separator.
+ * The protocol and fixed vectors are published in docs/System/Tools.md.
+ */
+export declare function encodeToolCatalogTarget(target: ToolCatalogTarget): Uint8Array;
+/** Unambiguous, case-sensitive tuple key used for indexing and collision checks. */
+export declare function toolCatalogTargetKey(target: ToolCatalogTarget): string;
+/**
+ * Permanent catalog ID: SHA-512 as an unsigned big-endian integer modulo 36^17,
+ * padded lowercase base36 with the `000tool0` prefix (25 characters total).
+ *
+ * Explicit exception to newid(): random/time allocation would give the same public
+ * tool different IDs on independent installations. Never replace this derivation
+ * with newid(). Use newid() only for genuinely new contract IDs, committed once.
+ */
+export declare function deriveToolCatalogId(target: ToolCatalogTarget): string;
+/** Reject reuse of an ID for a different target, including genuine hash collisions. */
+export declare function validateToolCatalogCollision(identities: Map<string, string>, toolId: string, target: ToolCatalogTarget): void;

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

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.legacyCatalogToolId = exports.legacyCatalogContractId = void 0;
+exports.isCatalogContractId = isCatalogContractId;
+exports.isCatalogToolId = isCatalogToolId;
+exports.validateToolCatalogTarget = validateToolCatalogTarget;
+exports.encodeToolCatalogTarget = encodeToolCatalogTarget;
+exports.toolCatalogTargetKey = toolCatalogTargetKey;
+exports.deriveToolCatalogId = deriveToolCatalogId;
+exports.validateToolCatalogCollision = validateToolCatalogCollision;
+const nacl = require("tweetnacl");
+const tweetnacl_util_1 = require("tweetnacl-util");
+const utils_1 = require("../utils");
+/** The shipped 26-character contract ID is accepted only by catalog target validation. */
+exports.legacyCatalogContractId = "000peers0toolaccessctl0001";
+/** The shipped Scheduler list tool ID is accepted only by Tools identity validation. */
+exports.legacyCatalogToolId = "00muxgugn661g0qmpuwafrmsi4";
+/** Validate a contract ID without weakening global peer-ID validation. */
+function isCatalogContractId(value) {
+    return typeof value === "string" && ((0, utils_1.isid)(value) || value === exports.legacyCatalogContractId);
+}
+/** Validate a Tools primary key, including the single shipped length exception. */
+function isCatalogToolId(value) {
+    return typeof value === "string" && ((0, utils_1.isid)(value) || value === exports.legacyCatalogToolId);
+}
+/** Validate exact names and well-formed Unicode; never trim or normalize identity input. */
+function validateToolCatalogTarget(target) {
+    if (!isCatalogContractId(target.contractId))
+        throw new Error("Invalid catalog contractId");
+    if (!Number.isSafeInteger(target.version) || target.version < 1)
+        throw new Error("Invalid catalog version");
+    if (typeof target.toolName !== "string" || target.toolName.length === 0)
+        throw new Error("Invalid catalog toolName");
+    // Reject lone UTF-16 surrogates rather than letting a UTF-8 encoder replace them.
+    for (let i = 0; i < target.toolName.length; i++) {
+        const unit = target.toolName.charCodeAt(i);
+        if (unit >= 0xd800 && unit <= 0xdbff) {
+            const next = target.toolName.charCodeAt(++i);
+            if (!(next >= 0xdc00 && next <= 0xdfff))
+                throw new Error("Malformed Unicode toolName");
+        }
+        else if (unit >= 0xdc00 && unit <= 0xdfff)
+            throw new Error("Malformed Unicode toolName");
+    }
+}
+/**
+ * Permanent v1 encoding approved in the Tools Catalog Foreman specification
+ * (2026-10-13): UTF-8 of compact JSON, including the domain separator.
+ * The protocol and fixed vectors are published in docs/System/Tools.md.
+ */
+function encodeToolCatalogTarget(target) {
+    validateToolCatalogTarget(target);
+    return (0, tweetnacl_util_1.decodeUTF8)(toolCatalogTargetKey(target));
+}
+/** Unambiguous, case-sensitive tuple key used for indexing and collision checks. */
+function toolCatalogTargetKey(target) {
+    return JSON.stringify([
+        "peers.tools-catalog.v1",
+        target.contractId,
+        target.version,
+        target.toolName,
+    ]);
+}
+/**
+ * Permanent catalog ID: SHA-512 as an unsigned big-endian integer modulo 36^17,
+ * padded lowercase base36 with the `000tool0` prefix (25 characters total).
+ *
+ * Explicit exception to newid(): random/time allocation would give the same public
+ * tool different IDs on independent installations. Never replace this derivation
+ * with newid(). Use newid() only for genuinely new contract IDs, committed once.
+ */
+function deriveToolCatalogId(target) {
+    let digest = 0n;
+    for (const byte of nacl.hash(encodeToolCatalogTarget(target)))
+        digest = digest * 256n + BigInt(byte);
+    return `000tool0${(digest % 36n ** 17n).toString(36).padStart(17, "0")}`;
+}
+/** Reject reuse of an ID for a different target, including genuine hash collisions. */
+function validateToolCatalogCollision(identities, toolId, target) {
+    if (!isCatalogToolId(toolId))
+        throw new Error("Invalid catalog toolId");
+    validateToolCatalogTarget(target);
+    const key = toolCatalogTargetKey(target);
+    const previous = identities.get(toolId);
+    if (previous && previous !== key)
+        throw new Error(`Tool catalog identity collision: ${toolId}`);
+    identities.set(toolId, key);
+}

package/dist/contracts/tool-catalog-migrations.d.ts

@@ -0,0 +1,12 @@
+import { type ToolCatalogTarget } from "./tool-catalog-identity";
+/** Reviewed legacy identity with source provenance. No package code is imported. */
+export interface ToolCatalogMigration extends ToolCatalogTarget {
+    toolId: string;
+    source: string;
+}
+/** Append-only compatibility inventory. Multiple IDs for a tuple are equal aliases. */
+export declare const toolCatalogMigrations: readonly ToolCatalogMigration[];
+/** Resolve an explicit alias; ambiguity fails closed rather than choosing by order. */
+export declare function resolveLegacyToolId(toolId: string, inventory?: readonly ToolCatalogMigration[]): ToolCatalogTarget | undefined;
+/** All protocol-selected identities; explicit aliases suppress the deterministic ID. */
+export declare function toolCatalogIds(target: ToolCatalogTarget, inventory?: readonly ToolCatalogMigration[]): string[];

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

@@ -0,0 +1,179 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toolCatalogMigrations = void 0;
+exports.resolveLegacyToolId = resolveLegacyToolId;
+exports.toolCatalogIds = toolCatalogIds;
+const system_ids_1 = require("../system-ids");
+const tool_catalog_identity_1 = require("./tool-catalog-identity");
+/** Append-only compatibility inventory. Multiple IDs for a tuple are equal aliases. */
+exports.toolCatalogMigrations = [
+    ...reviewed("000peers0toolaccessctl0001", "peers-sdk/src/system-ids.ts: toolAccessControlToolIds; contracts/system/tool-access-control-contract.ts", [
+        ["000peers0tacapprove000001", "approve"],
+        ["000peers0tacreject0000001", "reject"],
+        ["000peers0taclist000000001", "listPending"],
+    ]),
+    ...reviewed("00mu8uuzvo2zux1wfb9f1r48l", "peers-sdk/src/system-ids.ts: invitesToolIds; contracts/system/invites-contract.ts", [
+        ["00mu8uuzvqbn5o23ya563wmp5", "createContactInvite"],
+        ["00mu8uuzvqz17wedq1iqmh9i4", "createGroupInvite"],
+        ["00mu8uuzvqhbk5avjpew7w9ng", "inviteContactToGroup"],
+        ["00mu8uuzvqwbo180wgz4ctslm", "previewInvite"],
+        ["00mu8uuzvq8i1boc4ml1ywk30", "acceptInvite"],
+        ["00mu8uuzvq97veint1977p2ey", "declineInvite"],
+        ["00mu8uuzvqisozhlfbe1oeo0e", "approveJoinRequest"],
+        ["00mu8uuzvqdars4o466eansi2", "denyJoinRequest"],
+        ["00mu8uuzvqndg6qdh74dob9j1", "revokeInvite"],
+        ["00mu8uuzvqbu5ri9octpk64oo", "regenerateProfileInvite"],
+        ["00mu8uuzvq4xlaiqrn5notj1j", "syncMailbox"],
+        ["00mu8uuzvqfego6lyjjkgr4s7", "listInvites"],
+    ]),
+    ...reviewed("00muc9mlzv32qg00zz7cyixu9", "peers-sdk/src/system-ids.ts: identityToolIds; contracts/system/identity-contract.ts", [
+        ["00muc9mlzx4hqsfm132w4bzfm", "startSource"],
+        ["00muc9mlzxnfqylatvsyl41fc", "startDestination"],
+        ["00muc9mlzx1vpfyfexbd1yjbc", "approve"],
+        ["00muc9mlzxij1praa2scg4v5r", "reject"],
+        ["00muc9mlzxtq87urc75qc4r5v", "cancel"],
+        ["00muc9mlzx3t5evd57bns5z5n", "getSession"],
+        ["00muc9mlzx456ecfmzp1xn0db", "signIn"],
+        ["00muc9mlzxwdm2yj5p5wkjvz7", "signOut"],
+        ["00muc9mlzx07q98l3f9x49o10", "registerWithPeersServices"],
+        ["00mus1g5sfmu8vhazy7grwtjz", "getKeyInfo"],
+        ["00mus1g5sfrifcnula9crst8s", "rotateKey"],
+        ["00mustp0jrvoxpgion9dfgizc", "getRecoveryEmail"],
+        ["00mustox69twakb9sss2cto4g", "bindEmailStart"],
+        ["00mustox6brb044r1ms5gylw5", "bindEmailVerify"],
+        ["00mustox6b3afftshfac8vc04", "unbindEmail"],
+        ["00mustox6bjv7mo0jtywuzehm", "startAnchorSession"],
+        ["00mustox6bvmiuzzq4t7kg18q", "confirmAnchorSession"],
+        ["00musvcrtk1bkhivlo3d9e51z", "contestRecovery"],
+        ["00musvcrtlpgic1r6w2boo4k4", "acceptRecovery"],
+        ["00musvcrtl6ruaysm9f8he39x", "recoverKey"],
+        ["00musw0he8emme6dxl16ks885", "setAnchors"],
+        ["00musw0he9s4v0lz8bn4qpk7w", "passkeyRegisterStart"],
+        ["00musw0he9w4smpnzer0gqy22", "passkeyRegisterFinish"],
+        ["00musw0he9ad5zggw924sqd05", "passkeyAuthStart"],
+        ["00musw0he9yq03hf7qyk3b8dn", "passkeyAuthFinish"],
+    ]),
+    ...reviewed("00mukk9dwb1mjtd845kftuazm", "peers-sdk/src/system-ids.ts: localFoldersToolIds; contracts/system/local-folders-contract.ts", [
+        ["00mukk9dwdcv4f99ydwxao97f", "requestGrant"],
+        ["00mukk9dwdq119xmvz4ap8aum", "listGrants"],
+        ["00mukk9dwdezt5sbjviq1n1sp", "revokeGrant"],
+        ["00mukk9dwd6mxscrv9eeaanai", "list"],
+        ["00mukk9dwdon2y2487clcg67k", "stat"],
+        ["00mukk9dwdih6mh8rrofph80o", "readRange"],
+        ["00mukk9dwdm01bxg3hrby6pli", "index"],
+        ["00mumw1pmmf3y2ujfdc99h4ib", "getFileBlocks"],
+        ["00mungara9ixeolgxukzj2aku", "assemble"],
+        ["00mukk9dwd1c1f51xjysssgtv", "getJob"],
+        ["00mukk9dweizvif4ghp6kfa92", "cancelJob"],
+        ["00mukk9dwer8wsw5eiwis8tzm", "move"],
+        ["00mukk9dwejbuehqzszpyxefx", "trash"],
+        ["00mukk9dwe6co8gvuy44kmuzd", "purgeTrash"],
+    ]),
+    ...reviewed("00muxgugn4tzd527r3cwnie2o", "peers-sdk/src/system-ids.ts: httpToolIds; contracts/system/http-contract.ts", [
+        ["00muxgugn6e3dan5ej6dotzy5", "request"],
+        ["00muxgugn6scnni9563focivs", "cancel"],
+        ["00muxgugn6kouo2ocpun70q31", "describePolicy"],
+    ]),
+    ...reviewed("00muxgugn6ncjuunb8r28puae", "peers-sdk/src/system-ids.ts: contractCatalogToolIds; contracts/system/contract-catalog-contract.ts", [["00muxgugn6ek5apk8d5jtfavp", "listContractProviders"]]),
+    ...reviewed("00muxgugn6pj2o0lcu7kxkvrs", "peers-sdk/src/system-ids.ts: schedulerToolIds; contracts/system/scheduler-contract.ts", [
+        ["00muxgugn6t0o5s7239zg6bf5", "schedule"],
+        ["00muxgugn6vqfxpppodqlgfhg", "cancel"],
+        ["00muxgugn661g0qmpuwafrmsi4", "list"],
+    ]),
+    ...reviewed("00mriijkhq94msfe9m2j6quwp", "peers-sdk/src/contracts/system/device-operations-contract.ts", [
+        ["00mriijkhr4iptdefp4a7ifcq", "getDeviceStatus"],
+        ["00mriijkhrd54n33ey0omeejo", "queryDatabase"],
+        ["00mriijkhr4fpyd70nyo5iqlq", "listTools"],
+        ["00mriijkhrid4wpf89i4ikvay", "getTool"],
+        ["00mriijkhrfequch2qaeoihol", "runTool"],
+    ]),
+    ...reviewed("00ms1yb50w29oi116uwwrg7rl", "peers-sdk/src/contracts/system/network-contracts.ts", [
+        ["00ms1yb50ym353ads0gel5jpv", "getOverview"],
+        ["00ms1yb50ykny9kdgiclpa1t4", "getConnections"],
+        ["00ms1yb50yp2q7jr0jglzsztq", "getGroupSyncStatus"],
+        ["00ms1yb50yw792rslve1q99qg", "getDeviceDetails"],
+        ["00ms1yb50yuru8h1fg4t9na3e", "getGroupDetails"],
+        ["00ms1yb50y3jpoby5zomltahr", "getDisconnectedDevices"],
+        ["00ms1yb50y2fbfnth22yz52eu", "queryRemoteLogs"],
+        ["00mujw2tgbpoohxvwd23u9moz", "getSyncRecoveryEntries"],
+    ]),
+    ...reviewed("00ms1yb50yj9w5qbytl69qfht", "peers-sdk/src/contracts/system/network-contracts.ts", [
+        ["00ms1yb50y9rsdyqmr81vjoli", "refreshNetworkInfo"],
+        ["00ms1yb50y40ty8tr0sic875x", "connectToDevice"],
+        ["00ms1yb50yqvboqmhshqvlibr", "disconnectDevice"],
+        ["00ms1yb50y5mc448nuavlex86", "deleteDevice"],
+        ["00ms1yb50ylnqlra26jx232py", "syncGroupNow"],
+        ["00ms1yb50yfuackpl1w37hmxc", "resetChangeTracking"],
+        ["00mujw2tgcelvpg556n836ah7", "retrySyncRecovery"],
+        ["00mujw2tgciywn8krykc6gmwx", "resolveSyncRecovery"],
+        ["00mujw2tgc5lrezqrw4oneaot", "resetDeviceSyncInfo"],
+    ]),
+    ...reviewed("00mp287gdomtx12ald8oelyp0", "peers-core/src/package.ts; common/tools/index.ts and *.tool.ts; common/consts.ts", [
+        ["000peers0tool0000000newid", "new-id"],
+        ["000peers0tool0000throwerr", "throw-error"],
+        ["000peers0tool000000setvar", "set-variable"],
+        ["000peers0tool00000sendmsg", "send-message"],
+        ["000peers0tool00wrkflwsrch", "search-workflows"],
+        ["000peers0tool0runworkflow", "run-a-workflow"],
+        ["00mlwl2km0iymo1hwhtvqij2n", "cli_assistant_runner"],
+    ]),
+    ...reviewed("00mp287gdl5atltgs5bh0vm9z", "peers-core/src/package.ts; tasks/tools/index.ts and *.tool.ts; tasks/consts.ts", [
+        ["00mh0wlipkdbeaw8newtsk001", "new-task"],
+        ["00mh0wlipkdbeaw8wrttsk001", "write-task"],
+        ["00mh0wlipkdbeaw8wrtcmt001", "write-task-comment"],
+    ]),
+    ...reviewed("00mp50k37x131g7owkejhyb2t", "official-packages/groceries/src/package.ts, consts.ts, tools/index.ts, tools/add-to-shopping-list.tool.ts", [["00mh0wlipkdbeaw8shopitm01", "add-to-shopping-list"]]),
+    ...reviewed("00muxgugn6xvs8f2r80ru205t", "official-packages/groceries/src/voice/groceries-voice-skill.ts and consts.ts; peers-core/src/tasks/voice-skill.ts and voice-skill-consts.ts", [
+        ["00muxoa8xeet2lpi8bdq55q03", "invoke"],
+        ["00muxob3hbo3f6g49mipy1hyt", "invoke"],
+    ]),
+    ...reviewed(system_ids_1.hostToolsContractId, "peers-device/src/host-tools/contract.ts", [
+        ["000peers0tool0creategroup", "create-group"],
+        ["000peers0tool00querydb001", "query-database"],
+    ]),
+    ...reviewed(system_ids_1.desktopToolsContractId, "peers-electron/src/data/system/tools/*", [
+        ["000peers0tool00000homedir", "get-user-home-directory"],
+        ["000peers0tool0000peersdir", "get-peers-data-directory"],
+        ["000peers0tool00000showdir", "open-directory-in-os"],
+        ["000peers0tool000000pkgdir", "get-peers-packages-directory"],
+        ["000peers0tool00describdir", "describe-directory-contents"],
+        ["000peers0tool00appversion", "app-version"],
+        ["000peers0tool000publishpk", "publish-package"],
+    ]),
+    ...reviewed(system_ids_1.hostToolsContractId, "peers-device/src/host-tools/contract.ts", [
+        ["000peers0tool00000runner1", "default_assistant_runner"],
+        ["000peers0tool00toolsearch", "tool-search"],
+    ]),
+    ...reviewed(system_ids_1.desktopToolsContractId, "peers-electron/src/data/system/tools/*", [
+        ["000peers0tool0000000dircd", "cd"],
+        ["000peers0tool000000notify", "send-notification"],
+    ]),
+];
+function reviewed(contractId, source, aliases) {
+    return aliases.map(([toolId, toolName]) => ({
+        toolId,
+        contractId,
+        version: 1,
+        toolName,
+        source,
+    }));
+}
+/** Resolve an explicit alias; ambiguity fails closed rather than choosing by order. */
+function resolveLegacyToolId(toolId, inventory = exports.toolCatalogMigrations) {
+    const matches = inventory.filter((entry) => entry.toolId === toolId);
+    if (new Set(matches.map(tool_catalog_identity_1.toolCatalogTargetKey)).size > 1)
+        throw new Error(`Ambiguous legacy tool mapping: ${toolId}`);
+    const entry = matches[0];
+    return (entry && { contractId: entry.contractId, version: entry.version, toolName: entry.toolName });
+}
+/** All protocol-selected identities; explicit aliases suppress the deterministic ID. */
+function toolCatalogIds(target, inventory = exports.toolCatalogMigrations) {
+    (0, tool_catalog_identity_1.validateToolCatalogTarget)(target);
+    const key = (0, tool_catalog_identity_1.toolCatalogTargetKey)(target);
+    const ids = [
+        ...new Set(inventory.filter((entry) => (0, tool_catalog_identity_1.toolCatalogTargetKey)(entry) === key).map((entry) => entry.toolId)),
+    ];
+    for (const id of ids)
+        resolveLegacyToolId(id, inventory);
+    return ids.length ? ids : [(0, tool_catalog_identity_1.deriveToolCatalogId)(target)];
+}

package/dist/contracts/tool-catalog-service.d.ts

@@ -0,0 +1,30 @@
+import type { DataContext } from "../context/data-context";
+import { type ITool } from "../data/tools";
+import type { IContractCallContext } from "./contract-proxy";
+import type { IGetToolCatalogInput, IInvokeToolCatalogInput, IListToolCatalogInput, IToolCatalogEntry } from "./system/tool-catalog-contract";
+import { type ToolCatalogTarget } from "./tool-catalog-identity";
+/** Host-only variable resolution passed to the target endpoint. */
+export interface IToolCatalogInvokeOptions {
+    /** Trusted Device Operations only: retain the remote caller’s own identity. */
+    allowRemoteCaller?: boolean;
+    /** Host workflow admission bound; a provider change must not exceed already authorized policy. */
+    maxAccessLevel?: number;
+    resolveVariable?: (variableName: string, requestingToolId: string) => Promise<string>;
+}
+/** System tools admitted to workflows; administrative contracts remain excluded. */
+export declare const workflowInvocableSystemContractIds: ReadonlySet<string>;
+/** Whether a contract target may execute inside a workflow or assistant run. */
+export declare function isWorkflowInvocableTarget(target: ToolCatalogTarget): boolean;
+/** Synchronously describe a row using registry state only. Callers await catalogReady first. */
+export declare function describeToolCatalogRow(dataContext: DataContext, row: ITool): IToolCatalogEntry;
+/** List bounded catalog rows after the context's catalog initialization. */
+export declare function listToolCatalogEntries(dataContext: DataContext, input?: IListToolCatalogInput): Promise<IToolCatalogEntry[]>;
+/** Resolve one identity without letting unavailable IDs fall through to unrelated names. */
+export declare function findToolCatalogEntry(dataContext: DataContext, input: IGetToolCatalogInput, callerContext?: IContractCallContext): Promise<IToolCatalogEntry | undefined>;
+/** Project live policy without resolving endpoints or starting isolated workers. */
+export declare function projectToolCatalogAccess(dataContext: DataContext, entry: IToolCatalogEntry, callerContext: IContractCallContext): Promise<IToolCatalogEntry>;
+/**
+ * Validate and invoke a contract target through the selected provider with original authority.
+ * Never dispatches legacy code. Disposes every endpoint and retries only its own retirement once.
+ */
+export declare function invokeToolCatalogTool(dataContext: DataContext, input: IInvokeToolCatalogInput, context: IContractCallContext, opts?: IToolCatalogInvokeOptions): Promise<unknown>;