@peers-app/peers-sdk 0.26.6 → 0.27.1

package/dist/define/serve.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startPackage = startPackage;
+exports.servePackage = servePackage;
+const events_1 = require("./events");
+const observables_1 = require("./observables");
+const serve_members_1 = require("./serve-members");
+const tool_1 = require("./tool");
+const vars_1 = require("./vars");
+const worker_state_1 = require("./worker-state");
+/**
+ * Start a package's own state with the worker's context: load its variables, tell its events
+ * which contracts they're on, run its `pkg.onStart` hooks, and publish its in-memory
+ * observables. `servePackage` runs this when the worker starts; call it yourself only in tests,
+ * with a fake `ctx`.
+ *
+ * @param definition - The package's default export from `src/package.ts`.
+ * @param ctx - The worker's context, bound to no call.
+ */
+async function startPackage(definition, ctx) {
+    (0, worker_state_1.setPackageContext)(ctx);
+    (0, events_1.bindPackageEvents)(definition.provides);
+    // An in-memory source may derive from a variable. Load stored values before taking its
+    // initial snapshot, so the first read cannot race a publication of the variable's default.
+    await (0, vars_1.bindPackageVars)(ctx);
+    // After the variables load, before the observables' first publish: a value a hook sets is
+    // the first one readers see.
+    for (const hook of definition.startHooks ?? []) {
+        await hook(ctx);
+    }
+    await (0, observables_1.servePackageObservables)(definition.provides, ctx);
+}
+/**
+ * Register every provided tool's handler with the Runtime, serve each provided contract's
+ * tables, observables, and events from the worker (guest API 3: every consumer call and
+ * outgoing message goes through the package), and start the package's variables, events, and
+ * observables when the worker starts, before any call. `peers-package build` generates the
+ * call; packages don't call this themselves.
+ *
+ * @param definition - The package's default export from `src/package.ts`.
+ */
+function servePackage(definition) {
+    const worker = globalThis;
+    const register = worker.registerContractTool;
+    const registerHandler = worker.registerHandler;
+    if (typeof register !== "function" ||
+        typeof registerHandler !== "function" ||
+        typeof worker.onWorkerStart !== "function") {
+        throw new Error("servePackage runs inside an isolated package worker");
+    }
+    worker.onWorkerStart((ctx) => startPackage(definition, ctx));
+    for (const contract of definition.provides) {
+        for (const tool of contract.tools) {
+            register(contract.contractId, contract.version, tool.definition.name, (args, ctx) => (0, tool_1.runPackageTool)(tool, args, ctx));
+        }
+        (0, serve_members_1.serveContractMembers)(contract, registerHandler);
+    }
+}

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

@@ -0,0 +1,41 @@
+/**
+ * System HTTP v1: requests to the hosts in the package's `network.allowedHosts`. Declare it
+ * with `pkg.consumes(SystemHttp)`.
+ */
+export declare const SystemHttp: import("./contract-ref").IContractRef<{
+    request(input: import("../contracts/system/http-contract").IHttpRequestInput): Promise<import("../contracts/system/http-contract").IHttpRequestResult>;
+    cancel(input: import("../contracts/system/http-contract").IHttpCancelInput): Promise<{
+        cancelled: boolean;
+    }>;
+    describePolicy(input: {
+        packageId: string;
+    }): Promise<import("../contracts/system/http-contract").IHttpPolicyInfo>;
+}>;
+/**
+ * System Scheduler v1: run one of the package's own tools later, on this device. Declare it
+ * with `pkg.consumes(SystemScheduler)`, optionally.
+ */
+export declare const SystemScheduler: import("./contract-ref").IContractRef<{
+    schedule(input: import("../contracts/system/scheduler-contract").IScheduleInput): Promise<{
+        scheduleId: string;
+    }>;
+    cancel(input: {
+        scheduleId: string;
+    }): Promise<{
+        cancelled: boolean;
+    }>;
+    list(): Promise<{
+        schedules: import("../contracts/system/scheduler-contract").IScheduleInfo[];
+    }>;
+}>;
+/**
+ * System Contract Catalog v1: every installed provider of a contract, not just the active one,
+ * for a hub that calls them all (Voice Hub and its skills). Declare it with
+ * `pkg.consumes(SystemContractCatalog)`.
+ */
+export declare const SystemContractCatalog: import("./contract-ref").IContractRef<{
+    listContractProviders(input: import("../contracts/system/contract-catalog-contract").IListContractProvidersInput): Promise<{
+        providers: import("../contracts/system/contract-catalog-contract").IContractProviderInfo[];
+    }>;
+    getContractDefinition(input: import("../contracts/system/contract-catalog-contract").IGetContractDefinitionInput): Promise<import("../contracts/system/contract-catalog-contract").IContractDefinitionWithPolicy>;
+}>;

package/dist/define/system-contracts.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SystemContractCatalog = exports.SystemScheduler = exports.SystemHttp = void 0;
+const system_ids_1 = require("../system-ids");
+const contract_ref_1 = require("./contract-ref");
+/**
+ * System HTTP v1: requests to the hosts in the package's `network.allowedHosts`. Declare it
+ * with `pkg.consumes(SystemHttp)`.
+ */
+exports.SystemHttp = (0, contract_ref_1.contractRef)(system_ids_1.httpContractId, 1);
+/**
+ * System Scheduler v1: run one of the package's own tools later, on this device. Declare it
+ * with `pkg.consumes(SystemScheduler)`, optionally.
+ */
+exports.SystemScheduler = (0, contract_ref_1.contractRef)(system_ids_1.schedulerContractId, 1);
+/**
+ * System Contract Catalog v1: every installed provider of a contract, not just the active one,
+ * for a hub that calls them all (Voice Hub and its skills). Declare it with
+ * `pkg.consumes(SystemContractCatalog)`.
+ */
+exports.SystemContractCatalog = (0, contract_ref_1.contractRef)(system_ids_1.contractCatalogContractId, 1);

package/dist/define/table-handle.d.ts

@@ -0,0 +1,13 @@
+import type { IsolatedContractTableOperation } from "../package-loader/isolated-runtime";
+import type { IPackageTableHandle } from "./table";
+/** Sends one table operation with its arguments and resolves with the host's reply. */
+export type PackageTableCall = (operation: IsolatedContractTableOperation, args: unknown[]) => Promise<unknown>;
+/**
+ * A consumer's table methods over one way of calling the host: a consumed contract's
+ * (`News(ctx).tables.Feeds`) or a UI client's (`hostContract`). Replies are normalized the same
+ * way for both: a missing row is `undefined`, a list is an array. Saved records are copied for
+ * the bridge (undefined fields omitted); the providing package's table parses a `save`.
+ *
+ * @param call - Sends an operation to the table.
+ */
+export declare function packageTableMethods<T extends Record<string, any>, TInput = T>(call: PackageTableCall): IPackageTableHandle<T, TInput>;

package/dist/define/table-handle.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.packageTableMethods = packageTableMethods;
+const wire_value_1 = require("./wire-value");
+/**
+ * A consumer's table methods over one way of calling the host: a consumed contract's
+ * (`News(ctx).tables.Feeds`) or a UI client's (`hostContract`). Replies are normalized the same
+ * way for both: a missing row is `undefined`, a list is an array. Saved records are copied for
+ * the bridge (undefined fields omitted); the providing package's table parses a `save`.
+ *
+ * @param call - Sends an operation to the table.
+ */
+function packageTableMethods(call) {
+    return {
+        async get(recordId) {
+            return ((await call("get", [recordId])) ?? undefined);
+        },
+        async list(filter = {}, options = {}) {
+            const rows = await call("list", [filter, options]);
+            return (Array.isArray(rows) ? rows : []);
+        },
+        async count(filter = {}) {
+            return Number(await call("count", [filter]));
+        },
+        async findOne(filter = {}) {
+            return ((await call("findOne", [filter])) ?? undefined);
+        },
+        async save(record) {
+            // A field left undefined is omitted (stored unset); the bridge carries no undefined.
+            return (await call("save", [(0, wire_value_1.snapshotPackageValue)(record)]));
+        },
+        async delete(recordId) {
+            await call("delete", [recordId]);
+        },
+    };
+}

package/dist/define/table.d.ts

@@ -0,0 +1,128 @@
+import type { z } from "zod";
+import type { DataFilter, IDataQueryParams } from "../data/orm/data-query";
+import type { IDataChangedEvent } from "../data/orm/subscribable.data-source";
+import type { IPackageContext } from "./context";
+/** What {@link defineTable} takes. */
+export interface IPackageTableDefinition<S extends z.AnyZodObject = z.AnyZodObject> {
+    /** Table name, unique in the package. Other packages reach it only through a contract. */
+    name: string;
+    /** What the rows are. */
+    description: string;
+    /** The field that holds each row's id. */
+    primaryKeyName: Extract<keyof z.infer<S>, string>;
+    /** The row schema. The manifest carries its fields as Peers IR. */
+    schema: S;
+    /** Raise when the fields change, so every device adopts the new definition. */
+    versionNumber?: number;
+    /** Keep rows on this device only. They never sync. */
+    localOnly?: boolean;
+    /**
+     * The table's class, to override its methods: `Feeds(ctx)` returns one, and so does every
+     * consumer call through a contract, so an override is always the logic in use. Defaults to
+     * {@link PackageTable}.
+     */
+    tableClass?: PackageTableClass<S>;
+}
+/** A class extending {@link PackageTable} for a table's schema. */
+export type PackageTableClass<S extends z.AnyZodObject = z.AnyZodObject> = new (ctx: IPackageContext, definition: Readonly<IPackageTableDefinition<S>>) => PackageTable<S>;
+/** One table's methods, bound to one handler call. */
+export interface IPackageTableHandle<T extends Record<string, any>, TInput = T> {
+    /** One row by id, or `undefined`. */
+    get(recordId: string): Promise<T | undefined>;
+    /** Rows matching `filter` (all rows when omitted), with paging and sorting options. */
+    list(filter?: DataFilter<T>, options?: IDataQueryParams<T>): Promise<T[]>;
+    /** How many rows match `filter`. */
+    count(filter?: DataFilter<T>): Promise<number>;
+    /** The first row matching `filter`, or `undefined`. */
+    findOne(filter?: DataFilter<T>): Promise<T | undefined>;
+    /**
+     * Insert or replace a row. It reaches the providing package's table, which parses it with the
+     * schema first (so defaults and transforms apply), through any override its class makes.
+     */
+    save(record: TInput): Promise<T>;
+    /** Delete a row by id. */
+    delete(recordId: string): Promise<void>;
+}
+/**
+ * One of the package's tables, for one call: what `Feeds(ctx)` returns, and what answers a
+ * consumer's call through a contract (from a UI or another package). It runs in the provider's
+ * worker, never in the host.
+ *
+ * Subclass it to change a method, as with any table class, and pass the class to
+ * {@link defineTable}. The package's own handlers and its consumers then go through the same
+ * methods. `super` reaches Peers: `save` parses the row with the schema (so defaults and
+ * transforms apply), then stores it. Rows read from storage leave out empty optional fields,
+ * including nested fields written by an older build.
+ *
+ * ```ts
+ * class FeedsTable extends PackageTable<typeof feedSchema> {
+ *   async save(feed: z.input<typeof feedSchema>) {
+ *     return super.save({ ...feed, title: feed.title.trim() });
+ *   }
+ * }
+ * export const Feeds = defineTable({ name: "Feeds", ..., schema: feedSchema, tableClass: FeedsTable });
+ * ```
+ *
+ * Consumers can call `get`, `list`, `count`, `findOne`, `save`, and `delete`; other methods on a
+ * subclass stay private to the package. `this.ctx` is the call's context, carrying its caller.
+ */
+export declare class PackageTable<S extends z.AnyZodObject = z.AnyZodObject> implements IPackageTableHandle<z.infer<S>, z.input<S>> {
+    readonly ctx: IPackageContext;
+    readonly definition: Readonly<IPackageTableDefinition<S>>;
+    /**
+     * @param ctx - The call this instance serves.
+     * @param definition - The table's declaration.
+     */
+    constructor(ctx: IPackageContext, definition: Readonly<IPackageTableDefinition<S>>);
+    /** Send one operation to storage and clean rows before provider code receives them. */
+    private store;
+    /** One row by id, or `undefined`. */
+    get(recordId: string): Promise<z.infer<S> | undefined>;
+    /** Rows matching `filter` (all rows when omitted), with paging and sorting options. */
+    list(filter?: DataFilter<z.infer<S>>, options?: IDataQueryParams<z.infer<S>>): Promise<z.infer<S>[]>;
+    /** How many rows match `filter`. */
+    count(filter?: DataFilter<z.infer<S>>): Promise<number>;
+    /** The first row matching `filter`, or `undefined`. */
+    findOne(filter?: DataFilter<z.infer<S>>): Promise<z.infer<S> | undefined>;
+    /**
+     * Insert or replace a row, parsed with the schema first so defaults and transforms apply. An
+     * optional field that is `null` or `undefined` is left out, so it's stored unset; a field with
+     * a default gets the default. Resolves to the row as stored.
+     */
+    save(record: z.input<S>): Promise<z.infer<S>>;
+    /** Delete a row by id. */
+    delete(recordId: string): Promise<void>;
+    /**
+     * One change on its way to one subscriber of the table's `dataChanged`, with `this.ctx`
+     * carrying that subscriber. Return it to send it, a changed copy to send that instead, or
+     * `undefined` to drop it. Sends it unchanged by default.
+     *
+     * @param event - The change: the row and whether it was inserted, updated, or deleted.
+     */
+    dataChanged(event: IDataChangedEvent<z.infer<S>>): IDataChangedEvent<z.infer<S>> | undefined | Promise<IDataChangedEvent<z.infer<S>> | undefined>;
+}
+/**
+ * A table declared with {@link defineTable}, named `N`. Call it with a handler's `ctx` to use it:
+ * `Headlines(ctx).list({ feedId })`. `H` is the table's class instance.
+ */
+export interface IPackageTable<S extends z.AnyZodObject = z.AnyZodObject, N extends string = string, H extends PackageTable<S> = PackageTable<S>> {
+    (ctx: IPackageContext): H;
+    /** Marks a table declaration. */
+    readonly kind: "table";
+    /** What was passed to {@link defineTable}. */
+    readonly definition: Readonly<IPackageTableDefinition<S>> & {
+        readonly name: N;
+    };
+}
+/**
+ * Declare one of the package's tables from a zod schema.
+ *
+ * List it in a contract's `tables` (`defineContract`) to expose it, or on `pkg.tables` to keep
+ * it private to the package. Pass `tableClass` to override its methods ({@link PackageTable}).
+ *
+ * @param definition - Name, description, primary key, row schema, and optional class.
+ */
+export declare function defineTable<S extends z.AnyZodObject, N extends string, C extends PackageTableClass<S> = typeof PackageTable<S>>(definition: IPackageTableDefinition<S> & {
+    name: N;
+    tableClass?: C;
+}): IPackageTable<S, N, InstanceType<C>>;

package/dist/define/table.js

@@ -0,0 +1,122 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PackageTable = void 0;
+exports.defineTable = defineTable;
+const empty_fields_1 = require("./empty-fields");
+const wire_value_1 = require("./wire-value");
+/**
+ * One of the package's tables, for one call: what `Feeds(ctx)` returns, and what answers a
+ * consumer's call through a contract (from a UI or another package). It runs in the provider's
+ * worker, never in the host.
+ *
+ * Subclass it to change a method, as with any table class, and pass the class to
+ * {@link defineTable}. The package's own handlers and its consumers then go through the same
+ * methods. `super` reaches Peers: `save` parses the row with the schema (so defaults and
+ * transforms apply), then stores it. Rows read from storage leave out empty optional fields,
+ * including nested fields written by an older build.
+ *
+ * ```ts
+ * class FeedsTable extends PackageTable<typeof feedSchema> {
+ *   async save(feed: z.input<typeof feedSchema>) {
+ *     return super.save({ ...feed, title: feed.title.trim() });
+ *   }
+ * }
+ * export const Feeds = defineTable({ name: "Feeds", ..., schema: feedSchema, tableClass: FeedsTable });
+ * ```
+ *
+ * Consumers can call `get`, `list`, `count`, `findOne`, `save`, and `delete`; other methods on a
+ * subclass stay private to the package. `this.ctx` is the call's context, carrying its caller.
+ */
+class PackageTable {
+    ctx;
+    definition;
+    /**
+     * @param ctx - The call this instance serves.
+     * @param definition - The table's declaration.
+     */
+    constructor(ctx, definition) {
+        this.ctx = ctx;
+        this.definition = definition;
+    }
+    /** Send one operation to storage and clean rows before provider code receives them. */
+    async store(operation, args) {
+        const result = await this.ctx.callOwnedTable(this.definition.name, operation, args);
+        const { schema } = this.definition;
+        if (operation === "list" && Array.isArray(result)) {
+            return result.map((row) => (0, empty_fields_1.withoutEmptySchemaFields)(schema, row));
+        }
+        if (operation === "get" || operation === "findOne" || operation === "save") {
+            return (0, empty_fields_1.withoutEmptySchemaFields)(schema, result);
+        }
+        return result;
+    }
+    /** One row by id, or `undefined`. */
+    async get(recordId) {
+        return ((await this.store("get", [recordId])) ?? undefined);
+    }
+    /** Rows matching `filter` (all rows when omitted), with paging and sorting options. */
+    async list(filter = {}, options = {}) {
+        const rows = await this.store("list", [filter, options]);
+        return (Array.isArray(rows) ? rows : []);
+    }
+    /** How many rows match `filter`. */
+    async count(filter = {}) {
+        return Number(await this.store("count", [filter]));
+    }
+    /** The first row matching `filter`, or `undefined`. */
+    async findOne(filter = {}) {
+        return ((await this.store("findOne", [filter])) ?? undefined);
+    }
+    /**
+     * Insert or replace a row, parsed with the schema first so defaults and transforms apply. An
+     * optional field that is `null` or `undefined` is left out, so it's stored unset; a field with
+     * a default gets the default. Resolves to the row as stored.
+     */
+    async save(record) {
+        const { schema } = this.definition;
+        const row = (0, wire_value_1.snapshotPackageValue)(schema.parse((0, empty_fields_1.withoutEmptySchemaFields)(schema, record)));
+        return (await this.store("save", [row]));
+    }
+    /** Delete a row by id. */
+    async delete(recordId) {
+        await this.store("delete", [recordId]);
+    }
+    /**
+     * One change on its way to one subscriber of the table's `dataChanged`, with `this.ctx`
+     * carrying that subscriber. Return it to send it, a changed copy to send that instead, or
+     * `undefined` to drop it. Sends it unchanged by default.
+     *
+     * @param event - The change: the row and whether it was inserted, updated, or deleted.
+     */
+    dataChanged(event) {
+        return event;
+    }
+}
+exports.PackageTable = PackageTable;
+/**
+ * Declare one of the package's tables from a zod schema.
+ *
+ * List it in a contract's `tables` (`defineContract`) to expose it, or on `pkg.tables` to keep
+ * it private to the package. Pass `tableClass` to override its methods ({@link PackageTable}).
+ *
+ * @param definition - Name, description, primary key, row schema, and optional class.
+ */
+function defineTable(definition) {
+    if (typeof definition.name !== "string" || definition.name.trim() === "") {
+        throw new Error("defineTable requires a name");
+    }
+    if (!definition.schema || typeof definition.schema.shape !== "object") {
+        throw new Error(`Table ${definition.name} needs a zod object schema`);
+    }
+    if (!(definition.primaryKeyName in definition.schema.shape)) {
+        throw new Error(`Table ${definition.name} primary key "${definition.primaryKeyName}" is not in its schema`);
+    }
+    const TableClass = definition.tableClass ?? PackageTable;
+    if (typeof TableClass !== "function" ||
+        !(TableClass.prototype instanceof PackageTable || TableClass === PackageTable)) {
+        throw new Error(`Table ${definition.name} tableClass must extend PackageTable`);
+    }
+    const frozen = Object.freeze({ ...definition });
+    const table = (ctx) => new TableClass(ctx, frozen);
+    return Object.freeze(Object.assign(table, { kind: "table", definition: frozen }));
+}

package/dist/define/tool.d.ts

@@ -0,0 +1,129 @@
+import type { z } from "zod";
+import type { IField } from "../types/field-type";
+import type { IPackageContext } from "./context";
+/** Settings every tool declaration shares. */
+export interface IPackageToolOptions {
+    /** Tool name, unique on its contract. */
+    name: string;
+    /** What the tool does, for people and agents choosing it. */
+    usageDescription: string;
+    /** Access level (0–100) a caller needs. Use the {@link AccessLevel} constants. */
+    accessLevel: number;
+    /** Keep the caller's level for this tool's outgoing calls (`preserve`), or cap it (`cap`). */
+    authorityPropagation?: "cap" | "preserve";
+    /** A package-internal target, left out of the public contract definition. */
+    private?: boolean;
+    /** Level a caller on another device needs. Omit to keep the tool local to this device. */
+    remoteAccessLevel?: number;
+    /** Per-call deadline in milliseconds (at most 120 000). */
+    timeoutMs?: number;
+}
+/** A tool declared with zod schemas. Its input is parsed with `inputSchema` before `handler` runs. */
+export interface IPackageToolSchemaDefinition<I extends z.AnyZodObject = z.AnyZodObject, O extends z.AnyZodObject = z.AnyZodObject> extends IPackageToolOptions {
+    /** Input schema. The manifest carries its fields as Peers IR. */
+    inputSchema: I;
+    /** Output schema. It describes the result; the result is not parsed with it. */
+    outputSchema: O;
+    /** Runs the call. `ctx` carries the host calls for this call's caller. */
+    handler: (args: z.output<I>, ctx: IPackageContext) => z.output<O> | Promise<z.output<O>>;
+}
+/**
+ * A tool declared directly in Peers IR, for a contract defined elsewhere (Voice Skill, for
+ * example). Its input reaches `handler` as sent.
+ */
+export interface IPackageToolFieldsDefinition extends IPackageToolOptions {
+    /** Input fields. */
+    inputFields: IField[];
+    /** Output fields. */
+    outputFields: IField[];
+    /** Runs the call. `ctx` carries the host calls for this call's caller. */
+    handler: (args: unknown, ctx: IPackageContext) => unknown;
+}
+/** Either form of tool declaration. */
+export type PackageToolDefinition = IPackageToolSchemaDefinition | IPackageToolFieldsDefinition;
+/** A tool's shape from zod schemas, without its handler: what {@link declareTool} takes. */
+export type IPackageToolSchemaShape<I extends z.AnyZodObject = z.AnyZodObject, O extends z.AnyZodObject = z.AnyZodObject> = Omit<IPackageToolSchemaDefinition<I, O>, "handler">;
+/** A tool's shape in Peers IR, without its handler: what {@link declareTool} takes. */
+export type IPackageToolFieldsShape = Omit<IPackageToolFieldsDefinition, "handler">;
+/** Either form of tool shape. */
+export type PackageToolShape = IPackageToolSchemaShape | IPackageToolFieldsShape;
+/**
+ * A tool's shape, from {@link declareTool}: what a contract declaration lists, with no handler.
+ * `I` and `O` are what a caller sends and receives, and `N` is its name; {@link contractRef}
+ * uses them to type calls. `P` is the parsed input a handler (or a mock host's fake) receives
+ * after defaults and transforms.
+ */
+export interface IPackageToolDeclaration<I = unknown, O = unknown, N extends string = string, P = unknown> {
+    /** Marks a tool. */
+    readonly kind: "tool";
+    /** What was passed to {@link declareTool} (or {@link defineTool}). */
+    readonly definition: Readonly<PackageToolShape> & {
+        readonly name: N;
+    };
+    /** Type-only: what a caller sends and receives. Always undefined at runtime. */
+    readonly types?: {
+        input: I;
+        output: O;
+        parsedInput: P;
+    };
+}
+/** A tool declared with {@link defineTool}: its shape and its handler. */
+export interface IPackageTool<I = unknown, O = unknown, N extends string = string, P = unknown> extends IPackageToolDeclaration<I, O, N, P> {
+    /** What was passed to {@link defineTool}. */
+    readonly definition: Readonly<PackageToolDefinition> & {
+        readonly name: N;
+    };
+}
+/**
+ * Declare a tool from zod schemas: its shape and its handler together. The handler gets the
+ * input as `inputSchema` parses it.
+ *
+ * @param definition - Name, description, access level, schemas, and handler.
+ */
+export declare function defineTool<I extends z.AnyZodObject, O extends z.AnyZodObject, N extends string>(definition: IPackageToolSchemaDefinition<I, O> & {
+    name: N;
+}): IPackageTool<z.input<I>, z.output<O>, NoInfer<N>, z.output<I>>;
+/**
+ * Declare a tool from Peers IR fields, for a contract defined elsewhere. The handler gets the
+ * input as sent.
+ *
+ * @param definition - Name, description, access level, IR fields, and handler.
+ */
+export declare function defineTool<N extends string>(definition: IPackageToolFieldsDefinition & {
+    name: N;
+}): IPackageTool<unknown, unknown, NoInfer<N>>;
+/**
+ * Declare a tool's shape from zod schemas, with no handler, for a contract declared with
+ * `declareContract`: each package that implements the contract supplies the handler.
+ *
+ * @param definition - Name, description, access level, and schemas.
+ */
+export declare function declareTool<I extends z.AnyZodObject, O extends z.AnyZodObject, N extends string>(definition: IPackageToolSchemaShape<I, O> & {
+    name: N;
+}): IPackageToolDeclaration<z.input<I>, z.output<O>, NoInfer<N>, z.output<I>>;
+/**
+ * Declare a tool's shape in Peers IR fields, with no handler. An implementation's handler gets
+ * the input as sent.
+ *
+ * @param definition - Name, description, access level, and IR fields.
+ */
+export declare function declareTool<N extends string>(definition: IPackageToolFieldsShape & {
+    name: N;
+}): IPackageToolDeclaration<unknown, unknown, NoInfer<N>>;
+/**
+ * True when `tool` has a handler: from {@link defineTool}, not {@link declareTool}.
+ *
+ * @param tool - A tool from either.
+ */
+export declare function isImplementedTool(tool: IPackageToolDeclaration): tool is IPackageTool;
+/**
+ * Run a tool the way the Runtime does: parse the input with its schema, call the handler, and
+ * snapshot what it returns as the bridge carries it. An optional field that is `null` or
+ * `undefined` is left out, in the input before parsing and in the result. Handy in tests with a
+ * fake `ctx`.
+ *
+ * @param tool - A tool from {@link defineTool}.
+ * @param args - The call's arguments, as a caller sends them.
+ * @param ctx - The host calls for this call.
+ */
+export declare function runPackageTool<I, O>(tool: IPackageTool<I, O, string, any>, args: unknown, ctx: IPackageContext): Promise<O>;

package/dist/define/tool.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineTool = defineTool;
+exports.declareTool = declareTool;
+exports.isImplementedTool = isImplementedTool;
+exports.runPackageTool = runPackageTool;
+const empty_fields_1 = require("./empty-fields");
+const wire_value_1 = require("./wire-value");
+/**
+ * Declare a tool: its shape and its handler together.
+ *
+ * @param definition - Name, description, access level, schemas (or IR fields), and handler.
+ */
+function defineTool(definition) {
+    checkToolShape(definition, "defineTool");
+    if (typeof definition.handler !== "function") {
+        throw new Error(`Tool ${definition.name} needs a handler`);
+    }
+    return Object.freeze({ kind: "tool", definition: Object.freeze({ ...definition }) });
+}
+/**
+ * Declare a tool's shape, with no handler.
+ *
+ * @param definition - Name, description, access level, and schemas (or IR fields).
+ */
+function declareTool(definition) {
+    checkToolShape(definition, "declareTool");
+    if ("handler" in definition) {
+        throw new Error(`Tool ${definition.name}: declareTool takes no handler; implementContract supplies it`);
+    }
+    return Object.freeze({ kind: "tool", definition: Object.freeze({ ...definition }) });
+}
+/**
+ * True when `tool` has a handler: from {@link defineTool}, not {@link declareTool}.
+ *
+ * @param tool - A tool from either.
+ */
+function isImplementedTool(tool) {
+    return typeof tool.definition.handler === "function";
+}
+/** Check what every tool, declared or defined, needs: a name, a level, and one form of shape. */
+function checkToolShape(definition, what) {
+    if (typeof definition?.name !== "string" || definition.name.trim() === "") {
+        throw new Error(`${what} requires a name`);
+    }
+    if (typeof definition.accessLevel !== "number" ||
+        !Number.isInteger(definition.accessLevel) ||
+        definition.accessLevel < 0 ||
+        definition.accessLevel > 100) {
+        throw new Error(`Tool ${definition.name} needs an accessLevel from 0 through 100`);
+    }
+    const withSchemas = "inputSchema" in definition || "outputSchema" in definition;
+    const withFields = "inputFields" in definition || "outputFields" in definition;
+    if (withSchemas === withFields) {
+        throw new Error(`Tool ${definition.name} needs either inputSchema and outputSchema, or inputFields and outputFields`);
+    }
+    if (withSchemas) {
+        const { inputSchema, outputSchema } = definition;
+        if (typeof inputSchema?.shape !== "object" || typeof outputSchema?.shape !== "object") {
+            throw new Error(`Tool ${definition.name} schemas must be zod objects`);
+        }
+    }
+    else {
+        const { inputFields, outputFields } = definition;
+        if (!Array.isArray(inputFields) || !Array.isArray(outputFields)) {
+            throw new Error(`Tool ${definition.name} fields must be arrays`);
+        }
+    }
+}
+/**
+ * Run a tool the way the Runtime does: parse the input with its schema, call the handler, and
+ * snapshot what it returns as the bridge carries it. An optional field that is `null` or
+ * `undefined` is left out, in the input before parsing and in the result. Handy in tests with a
+ * fake `ctx`.
+ *
+ * @param tool - A tool from {@link defineTool}.
+ * @param args - The call's arguments, as a caller sends them.
+ * @param ctx - The host calls for this call.
+ */
+async function runPackageTool(tool, args, ctx) {
+    const definition = tool.definition;
+    if (!("inputSchema" in definition)) {
+        const result = await definition.handler(args, ctx);
+        return (result === undefined ? result : (0, wire_value_1.snapshotPackageValue)(result));
+    }
+    const input = (0, empty_fields_1.withoutEmptySchemaFields)(definition.inputSchema, args ?? {});
+    const result = await definition.handler(definition.inputSchema.parse(input), ctx);
+    return (result === undefined
+        ? result
+        : (0, wire_value_1.snapshotPackageValue)((0, empty_fields_1.withoutEmptySchemaFields)(definition.outputSchema, result)));
+}