@peers-app/peers-sdk 0.25.20 → 0.26.0

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

@@ -0,0 +1,287 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.workflowInvocableSystemContractIds = void 0;
+exports.isWorkflowInvocableTarget = isWorkflowInvocableTarget;
+exports.describeToolCatalogRow = describeToolCatalogRow;
+exports.listToolCatalogEntries = listToolCatalogEntries;
+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_catalog_1 = require("./tool-catalog");
+const tool_catalog_identity_1 = require("./tool-catalog-identity");
+const tool_catalog_migrations_1 = require("./tool-catalog-migrations");
+/** System tools admitted to workflows; administrative contracts remain excluded. */
+exports.workflowInvocableSystemContractIds = new Set([
+    system_ids_1.hostToolsContractId,
+    system_ids_1.desktopToolsContractId,
+]);
+/** Whether a contract target may execute inside a workflow or assistant run. */
+function isWorkflowInvocableTarget(target) {
+    return (!(0, system_contracts_1.isSystemContractId)(target.contractId) ||
+        exports.workflowInvocableSystemContractIds.has(target.contractId));
+}
+function liveResolver(dataContext, target, provider) {
+    const implementation = dataContext.packageLoader.contractRegistry.getProviderImplementation(target.contractId, target.version, provider) ?? target;
+    return (0, contract_resolvers_1.getContractResolver)(implementation.contractId, implementation.version, provider, dataContext);
+}
+/** Synchronously describe a row using registry state only. Callers await catalogReady first. */
+function describeToolCatalogRow(dataContext, row) {
+    const entry = {
+        toolId: row.toolId,
+        aliases: [],
+        name: row.name,
+        usageDescription: row.usageDescription,
+        inputSchema: row.inputSchema,
+        outputSchema: row.outputSchema,
+        catalogState: row.catalogState,
+        catalogIdentity: row.catalogIdentity,
+        workflowInvocable: false,
+        availability: {
+            dispatch: "unavailable",
+            reason: row.packageId ? "legacy-package-upgrade-required" : "legacy-execution-removed",
+            message: row.packageId
+                ? `Package ${row.packageId} must be upgraded to implement this tool through a contract resolver (docs/Packages/contracts.md#migrating-from-toolinstances).`
+                : "Legacy tool execution has been removed; implement this tool through a contract resolver (docs/Packages/contracts.md#migrating-from-toolinstances).",
+        },
+    };
+    try {
+        (0, tool_catalog_1.validateToolCatalogWrite)(undefined, row);
+        entry.target = (0, tool_catalog_1.toolCatalogTarget)(row) ?? (0, tool_catalog_migrations_1.resolveLegacyToolId)(row.toolId);
+        entry.aliases = entry.target ? (0, tool_catalog_migrations_1.toolCatalogIds)(entry.target) : [row.toolId];
+    }
+    catch {
+        entry.availability.reason = "invalid-identity";
+        entry.availability.message =
+            "Tool identity is invalid; inspect the catalog conflict and reinstall its provider.";
+        return entry;
+    }
+    if (row.catalogState === "quarantined") {
+        entry.availability.reason = "quarantined";
+        entry.availability.message =
+            "Tool identity is quarantined; resolve the catalog identity conflict before running it.";
+        return entry;
+    }
+    const target = entry.target;
+    if (target) {
+        const loader = dataContext.packageLoader;
+        const registry = loader.contractRegistry;
+        const provider = registry.getProviderPackageId(target.contractId, target.version);
+        entry.provider = {
+            activePackageId: provider,
+            registeredPackageIds: registry.getRegisteredProviderIds(target.contractId, target.version),
+            implementation: provider
+                ? registry.getProviderImplementation(target.contractId, target.version, provider)
+                : undefined,
+        };
+        if (provider) {
+            const member = registry
+                .resolve(target.contractId, target.version)
+                ?.tools.find((t) => t.name === target.toolName);
+            if (!member) {
+                entry.availability.reason = "member-removed";
+                entry.availability.message = `Provider ${provider} no longer declares ${target.toolName}; install a version that declares and implements it.`;
+                return entry;
+            }
+            if (loader.isolatedRuntime?.isInstalled(provider) ||
+                liveResolver(dataContext, target, provider)) {
+                entry.availability = {
+                    dispatch: "contract",
+                    requiresWorkflowRun: member.requiresWorkflowRun,
+                };
+                entry.workflowInvocable = isWorkflowInvocableTarget(target);
+                return entry;
+            }
+        }
+        entry.availability.reason = provider ? "no-implementation" : "no-provider";
+        entry.availability.message = provider
+            ? `Provider ${provider} declares ${target.toolName} but registers no implementation; install a version that implements it.`
+            : `No provider is installed for ${target.contractId}@${target.version}; install a package that implements ${target.toolName}.`;
+    }
+    return entry;
+}
+/** List bounded catalog rows after the context's catalog initialization. */
+async function listToolCatalogEntries(dataContext, input = {}) {
+    await dataContext.packageLoader.catalogReady;
+    const rows = await (0, tools_1.Tools)(dataContext).list({}, { pageSize: Math.min(input.limit ?? 100, 500), textSearch: input.query });
+    return rows.map((row) => describeToolCatalogRow(dataContext, row));
+}
+/** Resolve one identity without letting unavailable IDs fall through to unrelated names. */
+async function findToolCatalogEntry(dataContext, input, callerContext) {
+    await dataContext.packageLoader.catalogReady;
+    const table = (0, tools_1.Tools)(dataContext);
+    const exact = await table.get(input.toolIdOrName);
+    const choose = (rows) => {
+        const entries = rows
+            .map((row) => describeToolCatalogRow(dataContext, row))
+            .filter((entry) => !input.runnableOnly || entry.availability.dispatch !== "unavailable");
+        const groups = new Map(entries.map((entry) => [
+            entry.target ? (0, tool_catalog_identity_1.toolCatalogTargetKey)(entry.target) : entry.toolId,
+            entry,
+        ]));
+        if (groups.size > 1)
+            throw new Error(`Ambiguous tool "${input.toolIdOrName}": matched ${groups.size} tools (${entries.map((entry) => entry.toolId).join(", ")}); use a tool ID`);
+        return entries[0];
+    };
+    const entry = exact
+        ? describeToolCatalogRow(dataContext, exact)
+        : (choose(await table.list({ name: input.toolIdOrName })) ??
+            choose(await table.list({}, { textSearch: input.toolIdOrName })));
+    if (entry && callerContext)
+        await projectToolCatalogAccess(dataContext, entry, callerContext);
+    if (entry && input.runnableOnly && entry.availability.dispatch === "unavailable")
+        return undefined;
+    return entry;
+}
+/** Project live policy without resolving endpoints or starting isolated workers. */
+async function projectToolCatalogAccess(dataContext, entry, callerContext) {
+    const userId = callerContext.callerUserId ?? callerContext.localUserId;
+    if (entry?.availability.dispatch === "contract" && entry.target && userId) {
+        const provider = entry.provider?.activePackageId;
+        if (!provider)
+            return entry;
+        const runtime = dataContext.packageLoader.isolatedRuntime;
+        const accessLevel = runtime?.isInstalled(provider)
+            ? runtime.getEffectiveToolLevel?.(entry.target, provider)
+            : (0, tool_access_1.recordAccessLevel)((await liveResolver(dataContext, entry.target, provider)?.({ dataContext }))?.tools?.[entry.target.toolName]?.tool);
+        if (accessLevel !== undefined) {
+            const callerAccessLevel = await (0, group_permissions_1.getUserAccessLevel)(dataContext, userId);
+            entry.access = {
+                accessLevel,
+                callerAccessLevel,
+                allowed: (0, tool_access_1.decideToolAccess)({
+                    userAccessLevel: callerAccessLevel,
+                    toolAccessLevel: accessLevel,
+                    assistantAccessLevel: callerContext?.authority?.assistantAccessLevel,
+                }).kind === "allow",
+            };
+        }
+    }
+    return entry;
+}
+function requirePlainObject(value, label) {
+    if (!value ||
+        typeof value !== "object" ||
+        (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null))
+        throw new Error(`${label} requires a plain object`);
+}
+/**
+ * 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.
+ */
+async function invokeToolCatalogTool(dataContext, input, context, opts = {}) {
+    await dataContext.packageLoader.catalogReady;
+    requirePlainObject(input, "invokeTool");
+    for (const key of Reflect.ownKeys(input))
+        if (!["toolId", "args", "providerPackageId", "fallbackToDefaultProvider"].includes(String(key)) ||
+            typeof key !== "string")
+            throw new Error(`Unexpected invokeTool input key: ${String(key)}`);
+    if (context?.dataContext !== dataContext || !(context.callerUserId ?? context.localUserId))
+        throw new Error("Tool catalog requires an authenticated caller in the same data context");
+    if (context.callerDeviceId && !context.callerUserId)
+        throw new Error("Remote catalog invocation requires the caller user identity");
+    if (context.workflow && context.workflow.dataContextId !== dataContext.dataContextId)
+        throw new Error("Workflow data context does not match the catalog call");
+    if (context.callerPackageId || (context.callerDeviceId && !opts.allowRemoteCaller))
+        throw new Error("Tool catalog invocation requires a local user caller");
+    if (typeof input.toolId !== "string" ||
+        (input.providerPackageId !== undefined &&
+            (typeof input.providerPackageId !== "string" || !(0, utils_1.isid)(input.providerPackageId))) ||
+        (input.fallbackToDefaultProvider !== undefined &&
+            typeof input.fallbackToDefaultProvider !== "boolean"))
+        throw new Error("Invalid invokeTool input");
+    const row = await (0, tools_1.Tools)(dataContext).get(input.toolId);
+    if (!row)
+        throw new Error(`Tool not found: ${input.toolId}`);
+    (0, tool_catalog_1.validateToolCatalogWrite)(undefined, row);
+    const target = (0, tool_catalog_1.toolCatalogTarget)(row) ?? (0, tool_catalog_migrations_1.resolveLegacyToolId)(row.toolId);
+    if (row.catalogState === "quarantined" || !target || target.contractId === system_ids_1.toolCatalogContractId)
+        throw new Error("Tool catalog target is quarantined, unresolved, or the catalog itself");
+    if (opts.allowRemoteCaller && (0, contract_resolvers_1.isLocalOnlyContractId)(target.contractId))
+        throw new Error("Tool target is local-only");
+    if (context.workflow && !isWorkflowInvocableTarget(target))
+        throw new Error("Tool target is not available to workflows");
+    const loader = dataContext.packageLoader;
+    await loader.toolCatalog.assertTargetUsable(target);
+    for (let attempt = 0; attempt < 2; attempt++) {
+        const selected = loader.contractRegistry.selectProvider({
+            contractId: target.contractId,
+            version: target.version,
+            providerPackageIds: input.providerPackageId ? [input.providerPackageId] : undefined,
+            fallbackToDefaultProvider: input.fallbackToDefaultProvider,
+        });
+        if (!selected)
+            throw new Error(`Strict provider selection failed (no-provider) for ${target.contractId} v${target.version}`);
+        const providerPackageId = selected.providerPackageId;
+        const tool = selected.definition.tools.find((t) => t.name === target.toolName);
+        if (!tool)
+            throw new Error(`Tool member-removed: ${target.toolName}`);
+        if (tool.requiresWorkflowRun &&
+            (!context.workflow || loader.isolatedRuntime?.isInstalled(providerPackageId)))
+            throw new Error(`Tool ${target.toolName} requires a host workflow run`);
+        if (!loader.isolatedRuntime?.isInstalled(providerPackageId) &&
+            !liveResolver(dataContext, target, providerPackageId))
+            throw new Error(`Tool no-implementation: ${providerPackageId}`);
+        if (opts.maxAccessLevel !== undefined) {
+            const liveLevel = loader.isolatedRuntime?.isInstalled(providerPackageId)
+                ? loader.isolatedRuntime.getEffectiveToolLevel?.(target, providerPackageId)
+                : (0, tool_access_1.recordAccessLevel)((await liveResolver(dataContext, target, providerPackageId)?.({ dataContext }))
+                    ?.tools?.[target.toolName]?.tool);
+            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");
+        const args = { ...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 dataContextId = dataContext.dataContextId;
+        const { workflow: _workflow, ...caller } = context;
+        const endpointContext = loader.isolatedRuntime?.isInstalled(providerPackageId)
+            ? caller
+            : context;
+        const endpoint = await loader.resolveContractEndpoint({
+            contractId: target.contractId,
+            version: target.version,
+            providerPackageId,
+            dataContextId,
+            context: endpointContext,
+            notify: async () => undefined,
+        }, { providerPackageId, resolveVariable: opts.resolveVariable });
+        try {
+            return await endpoint.handleCall({
+                contractId: target.contractId,
+                version: target.version,
+                member: "tool",
+                operation: "run",
+                name: target.toolName,
+                args: [args],
+                providerPackageId,
+                dataContextId,
+            }, endpointContext);
+        }
+        catch (error) {
+            if (attempt !== 0 ||
+                !(error instanceof contract_provider_router_1.RetiredContractProviderEndpointError) ||
+                error.endpoint !== endpoint)
+                throw error;
+        }
+        finally {
+            endpoint.dispose();
+        }
+    }
+    throw new Error("Tool provider retired");
+}

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

@@ -0,0 +1,91 @@
+import type { DataContext } from "../context/data-context";
+import { type ITool } from "../data/tools";
+import type { ContractRegistry, IContractProviderRegistration } from "./registry";
+import { type ToolCatalogTarget } from "./tool-catalog-identity";
+/** Supplemental metadata keyed by a declared public contract member, never by executable IDs. */
+export type IToolCatalogMetadata = ToolCatalogTarget & Pick<Partial<ITool>, "isAssistantRunner" | "configSchema" | "detailedDescription">;
+/** Read a complete canonical target; partial mappings are invalid, not legacy tools. */
+export declare function toolCatalogTarget(row: Partial<ITool>): ToolCatalogTarget | undefined;
+/**
+ * Mixed-version sync: runtimes that predate the catalog columns reconstruct and write
+ * full rows without them. When a synced candidate carries none of the catalog-owned
+ * fields, keep the established row's identity and state rather than rejecting the
+ * write as a retarget. A candidate carrying any catalog field is returned unchanged
+ * and validated as written, so partial stripping and retargeting still fail.
+ *
+ * @param existing - Materialized row, if any.
+ * @param candidate - Reconstructed row about to replace it.
+ * @returns The row to validate and write.
+ */
+export declare function retainToolCatalogFields<T extends Partial<ITool>>(existing: Partial<ITool> | undefined, candidate: T): T;
+/**
+ * Shared pre-persistence identity guard for local writes and reconstructed sync rows.
+ * Existing mappings cannot be retargeted, stripped or deleted. Rejected sync evidence
+ * belongs in the sync recovery queue; it must not replace the established row.
+ * Pass recordId for deletes so reserved identities are protected before materialization.
+ *
+ * Catalog identities are permanent. Unresolved legacy rows are a holdover until their
+ * tools move to contracts: they stay ordinary rows that local writers and older
+ * runtimes may delete.
+ */
+export declare function validateToolCatalogWrite(existing: Partial<ITool> | undefined, candidate: Partial<ITool> | undefined, recordId?: string | undefined): void;
+/**
+ * Per-context runtime owner of permanent Tools identities. Construction is inert;
+ * ready() explicitly initializes storage after UserContext construction completes.
+ * No worker, resolver or executable ToolInstance is needed to index public members.
+ */
+export declare class ToolCatalog {
+    readonly dataContext: DataContext;
+    readonly registry: ContractRegistry;
+    private tail;
+    private initialization?;
+    private subscription?;
+    private disposed;
+    private reconciliationQueued;
+    /** Bind to the registry shared by host and isolated providers in this context. */
+    constructor(dataContext: DataContext, registry: ContractRegistry);
+    private enqueue;
+    /** Await successful backfill and system publication. Failed initialization can be retried. */
+    ready(): Promise<void>;
+    private assertLive;
+    private validate;
+    /**
+     * Serialize validation, catalog persistence, package preparation and activation.
+     * A failed preparation never publishes the candidate or changes live tool policy.
+     * Successful catalog additions remain historical even if later preparation fails.
+     * Descriptive metadata of existing rows is refreshed only after preparation
+     * succeeds, so a failed replacement leaves the active provider's rows unchanged.
+     * Async activation must call the supplied guard in its final synchronous commit
+     * turn, before publishing providers or changing live bindings. The guard observes
+     * catalog changes immediately, independently of queued reconciliation.
+     */
+    publish<T>(provider: string, registrations: readonly IContractProviderRegistration[], prepare: () => Promise<void>, activate: (assertCatalogCurrent: () => void) => T | Promise<T>, toolMetadata?: readonly IToolCatalogMetadata[]): Promise<T>;
+    private guardActivation;
+    private definitions;
+    /**
+     * Insert every public member's catalog rows, validating the batch first. With
+     * `refresh`, existing rows with absent or matching provider provenance also take the
+     * definition's name, usage description and IO schemas.
+     */
+    private materialize;
+    /**
+     * Patch the listed descriptive fields whose stored values differ. A marked patch
+     * leaves every other column, including concurrently synced policy, untouched.
+     */
+    private refresh;
+    private reconcile;
+    /**
+     * Patch supplemental metadata of existing system members, preserving identity,
+     * historical source and provenance, descriptions and all authorization policy.
+     * @throws If any entry is unresolved, quarantined or outside the system inventory.
+     */
+    saveToolMetadata(entries: readonly (Partial<ITool> & {
+        toolId: string;
+    })[]): Promise<void>;
+    /** Reject quarantined or conflicting retained evidence before a contract tool call. */
+    assertTargetUsable(target: ToolCatalogTarget): Promise<void>;
+    /** Serialize host removal with pending publications while retaining all catalog rows. */
+    removeProvider(provider: string, deactivate: () => void): Promise<void>;
+    /** Stop subscriptions and queued lifecycle work; permanent rows are retained. */
+    dispose(): Promise<void>;
+}