@scfloworg/actions 0.0.0-stage → 0.1.0

package/dist/parameters.d.ts

@@ -0,0 +1,31 @@
+import type { ValidateFunction } from "ajv/dist/2020.js";
+import type { ActionDefinition, JsonSchema, RefResolver } from "./types.js";
+/**
+ * The parameters of a definition as a JSON Schema object: its JSON text read,
+ * or an empty object schema when it declares none. Text that is not JSON, or a
+ * schema whose `type` is not `object`, is refused with `constraint_violation`.
+ */
+export declare function parametersSchema(definition: ActionDefinition): JsonSchema;
+/**
+ * The validator of a parameters schema, compiled once per schema object. A
+ * schema that is not a valid JSON Schema, or uses an unknown keyword, is
+ * refused with `constraint_violation`.
+ */
+export declare function compileParameters(id: string, schema: JsonSchema): ValidateFunction;
+/**
+ * Checks parameters against the JSON Schema of an action and gives the
+ * parameters its body receives: a copy, with the `default` of each absent
+ * property, and each `ref` value replaced by the key of the instance it names.
+ *
+ * `undefined` stands for no parameters, an empty object. Parameters that break
+ * the schema are refused with `invalid_parameters`. A `ref` value is resolved
+ * by `resolveRef` under the rule of the specification: the instance whose id
+ * is the value wins; otherwise the one instance whose `display_name` is the
+ * value; no instance or several are refused with `invalid_parameters`. Without
+ * `resolveRef`, a `ref` value is kept as it is.
+ *
+ * `validate` is the compiled validator, which a registry keeps; it is compiled
+ * from the definition when absent.
+ */
+export declare function validateParameters(definition: ActionDefinition, params: unknown, resolveRef?: RefResolver, validate?: ValidateFunction): Promise<unknown>;
+//# sourceMappingURL=parameters.d.ts.map

package/dist/parameters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parameters.d.ts","sourceRoot":"","sources":["../src/parameters.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAGzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AA4D5E;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,gBAAgB,GAAG,UAAU,CA0BzE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,gBAAgB,CAclF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,gBAAgB,EAC5B,MAAM,EAAE,OAAO,EACf,UAAU,CAAC,EAAE,WAAW,EACxB,QAAQ,GAAE,gBAAiF,GAC1F,OAAO,CAAC,OAAO,CAAC,CA4BlB"}

package/dist/parameters.js

@@ -0,0 +1,141 @@
+import { Ajv2020 } from "ajv/dist/2020.js";
+import { actionError } from "./errors.js";
+import { copyJson } from "./json.js";
+/** The sites of the validation running now; validation is synchronous, so one list is enough. */
+let collecting = null;
+/**
+ * The validator of every action: JSON Schema draft 2020-12, the version of MCP
+ * tools. Unknown keywords are refused, `default` fills absent properties, and
+ * `format` is an annotation only, since no format vocabulary is loaded.
+ */
+const ajv = new Ajv2020({
+    allErrors: true,
+    useDefaults: true,
+    strictSchema: true,
+    strictTypes: false,
+    strictTuples: false,
+    strictRequired: false,
+    validateFormats: false,
+});
+/**
+ * `ref` names a schema of the model: the value is the id or the display name
+ * of one of its instances. The validator only notes where each value sits;
+ * `validateParameters` resolves them once the parameters are valid.
+ */
+ajv.addKeyword({
+    keyword: "ref",
+    schemaType: "string",
+    errors: false,
+    validate(schema, data, _parentSchema, context) {
+        if (collecting && typeof data === "string" && context && context.parentData !== undefined) {
+            collecting.push({
+                schema,
+                value: data,
+                parent: context.parentData,
+                property: context.parentDataProperty,
+            });
+        }
+        return true;
+    },
+});
+const compiled = new WeakMap();
+/** The parameters of an action that declares none. */
+const NO_PARAMETERS = Object.freeze({ type: "object", properties: Object.freeze({}) });
+/**
+ * The parameters of a definition as a JSON Schema object: its JSON text read,
+ * or an empty object schema when it declares none. Text that is not JSON, or a
+ * schema whose `type` is not `object`, is refused with `constraint_violation`.
+ */
+export function parametersSchema(definition) {
+    const { parameters } = definition;
+    if (parameters === undefined)
+        return NO_PARAMETERS;
+    let schema = parameters;
+    if (typeof parameters === "string") {
+        try {
+            schema = JSON.parse(parameters);
+        }
+        catch (error) {
+            throw actionError("constraint_violation", `${definition.id}: parameters are not JSON: ${error.message}`);
+        }
+    }
+    if (schema === null ||
+        typeof schema !== "object" ||
+        Array.isArray(schema) ||
+        schema.type !== "object") {
+        throw actionError("constraint_violation", `${definition.id}: parameters must be a JSON Schema of type object`);
+    }
+    return schema;
+}
+/**
+ * The validator of a parameters schema, compiled once per schema object. A
+ * schema that is not a valid JSON Schema, or uses an unknown keyword, is
+ * refused with `constraint_violation`.
+ */
+export function compileParameters(id, schema) {
+    const known = compiled.get(schema);
+    if (known)
+        return known;
+    let validate;
+    try {
+        validate = ajv.compile(schema);
+    }
+    catch (error) {
+        throw actionError("constraint_violation", `${id}: parameters are not a valid JSON Schema: ${error.message}`);
+    }
+    compiled.set(schema, validate);
+    return validate;
+}
+/**
+ * Checks parameters against the JSON Schema of an action and gives the
+ * parameters its body receives: a copy, with the `default` of each absent
+ * property, and each `ref` value replaced by the key of the instance it names.
+ *
+ * `undefined` stands for no parameters, an empty object. Parameters that break
+ * the schema are refused with `invalid_parameters`. A `ref` value is resolved
+ * by `resolveRef` under the rule of the specification: the instance whose id
+ * is the value wins; otherwise the one instance whose `display_name` is the
+ * value; no instance or several are refused with `invalid_parameters`. Without
+ * `resolveRef`, a `ref` value is kept as it is.
+ *
+ * `validate` is the compiled validator, which a registry keeps; it is compiled
+ * from the definition when absent.
+ */
+export async function validateParameters(definition, params, resolveRef, validate = compileParameters(definition.id, parametersSchema(definition))) {
+    const data = params === undefined ? {} : copyJson(params);
+    const sites = [];
+    collecting = sites;
+    let valid;
+    try {
+        valid = validate(data);
+    }
+    finally {
+        collecting = null;
+    }
+    if (!valid) {
+        throw actionError("invalid_parameters", `${definition.id}: ${ajv.errorsText(validate.errors, { dataVar: "parameters" })}`);
+    }
+    if (resolveRef) {
+        // A value under several subschemas (allOf, anyOf) is met more than once: resolve it once.
+        const done = new Map();
+        for (const site of sites) {
+            const properties = done.get(site.parent) ?? new Set();
+            if (properties.has(site.property))
+                continue;
+            properties.add(site.property);
+            done.set(site.parent, properties);
+            site.parent[site.property] = await resolveKey(definition.id, site, resolveRef);
+        }
+    }
+    return data;
+}
+async function resolveKey(id, site, resolveRef) {
+    const matches = await resolveRef(site.schema, site.value);
+    if (matches.id !== null)
+        return matches.id;
+    if (matches.names.length === 1)
+        return matches.names[0];
+    const count = matches.names.length === 0 ? "no" : "several";
+    throw actionError("invalid_parameters", `${id}: "${site.value}" names ${count} instance of ${site.schema}`);
+}
+//# sourceMappingURL=parameters.js.map

package/dist/parameters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parameters.js","sourceRoot":"","sources":["../src/parameters.ts"],"names":[],"mappings":"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"}

package/dist/registry.d.ts

@@ -0,0 +1,38 @@
+import type { Action, RunEntry, RunHost, RunOutcome, RunTrace } from "./types.js";
+/** A registry of actions, each known by its id. */
+export interface ActionRegistry<C = RunTrace> {
+    /**
+     * Adds an action. Its id must be a namespace, a slash and a name, and its
+     * parameters a valid JSON Schema object, or it is refused with
+     * `constraint_violation`; an id already registered is refused with
+     * `duplicate_name`.
+     */
+    register(action: Action<C>): void;
+    /** The action with this id, or `undefined`. */
+    get(id: string): Action<C> | undefined;
+    /** Every action, in the order of registration. */
+    list(): readonly Action<C>[];
+    /**
+     * Runs one action: checks its parameters (see `validateParameters`), runs its
+     * body with the context the host builds, and records the call as a run
+     * entry, which `host.onEntry` receives, done or refused. An id that names no
+     * action is refused with `unknown_action`, and no entry is recorded.
+     *
+     * It opens no transaction: the host runs it inside the transaction of the
+     * action.
+     */
+    run(id: string, params?: unknown, host?: RunHost<C>): Promise<RunOutcome>;
+}
+/** The run entry recorded for an exception a run threw, if any. */
+export declare function entryOfRefusal(error: unknown): RunEntry | undefined;
+/** Creates an empty registry. `C` is the context a host gives the bodies, the trace by default. */
+export declare function createActionRegistry<C = RunTrace>(): ActionRegistry<C>;
+/** A run log: the entries of the runs it is given to, in order. */
+export interface RunLog {
+    readonly entries: readonly RunEntry[];
+    /** Adds an entry; pass it as `RunHost.onEntry`. */
+    readonly record: (entry: RunEntry) => void;
+}
+/** Creates an empty run log, kept in memory. */
+export declare function createRunLog(): RunLog;
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,UAAU,EAAW,QAAQ,EAAE,MAAM,YAAY,CAAC;AAK3F,mDAAmD;AACnD,MAAM,WAAW,cAAc,CAAC,CAAC,GAAG,QAAQ;IAC1C;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAClC,+CAA+C;IAC/C,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;IACvC,kDAAkD;IAClD,IAAI,IAAI,SAAS,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;IAC7B;;;;;;;;OAQG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CAC3E;AAUD,mEAAmE;AACnE,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,GAAG,SAAS,CAEnE;AAWD,mGAAmG;AACnG,wBAAgB,oBAAoB,CAAC,CAAC,GAAG,QAAQ,KAAK,cAAc,CAAC,CAAC,CAAC,CAyFtE;AAED,mEAAmE;AACnE,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,OAAO,EAAE,SAAS,QAAQ,EAAE,CAAC;IACtC,mDAAmD;IACnD,QAAQ,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,CAAC;CAC5C;AAED,gDAAgD;AAChD,wBAAgB,YAAY,IAAI,MAAM,CAGrC"}

package/dist/registry.js

@@ -0,0 +1,113 @@
+import { actionError, errorCodeOf } from "./errors.js";
+import { canonicalJson, copyJson } from "./json.js";
+import { compileParameters, parametersSchema, validateParameters } from "./parameters.js";
+/** An action id: the namespace of its module, a slash and a name, both identifiers. */
+const ACTION_ID = /^[A-Za-z_][A-Za-z0-9_]*\/[A-Za-z_][A-Za-z0-9_]*$/;
+/** The entry of each refused run, by its exception, so a caller records it as a step. */
+const refusedEntries = new WeakMap();
+/** The run entry recorded for an exception a run threw, if any. */
+export function entryOfRefusal(error) {
+    return error !== null && typeof error === "object" ? refusedEntries.get(error) : undefined;
+}
+/** The parameters as given, in canonical form, or their text when they are not JSON. */
+function givenParameters(params) {
+    try {
+        return canonicalJson(params === undefined ? {} : params);
+    }
+    catch {
+        return JSON.stringify(String(params));
+    }
+}
+/** Creates an empty registry. `C` is the context a host gives the bodies, the trace by default. */
+export function createActionRegistry() {
+    const actions = new Map();
+    function refuse(error, action, parameters, steps) {
+        const entry = {
+            action,
+            parameters,
+            steps,
+            outcome: "refused",
+            error: errorCodeOf(error),
+        };
+        if (error !== null && typeof error === "object")
+            refusedEntries.set(error, entry);
+        throw error;
+    }
+    async function execute(id, params, host) {
+        const registered = actions.get(id);
+        if (!registered)
+            throw actionError("unknown_action", `no action ${id}`);
+        const steps = [];
+        let checked;
+        try {
+            checked = await validateParameters(registered.action, params, host.resolveRef, registered.validate);
+        }
+        catch (error) {
+            refuse(error, id, givenParameters(params), steps);
+        }
+        const parameters = canonicalJson(checked);
+        const trace = {
+            action: id,
+            command(command, result) {
+                steps.push({ command: copyJson(command), result: canonicalJson(result) });
+            },
+            async call(calledId, calledParams) {
+                try {
+                    const outcome = await execute(calledId, calledParams, host);
+                    steps.push({ call: outcome.entry });
+                    return outcome.result;
+                }
+                catch (error) {
+                    const entry = entryOfRefusal(error);
+                    if (entry)
+                        steps.push({ call: entry });
+                    throw error;
+                }
+            },
+        };
+        const context = host.context ? host.context(trace) : trace;
+        let result;
+        try {
+            result = await registered.action.run(checked, context);
+        }
+        catch (error) {
+            refuse(error, id, parameters, steps);
+        }
+        const entry = result === undefined
+            ? { action: id, parameters, steps, outcome: "done" }
+            : { action: id, parameters, steps, outcome: "done", result: canonicalJson(result) };
+        return { result, entry };
+    }
+    return {
+        register(action) {
+            if (typeof action.id !== "string" || !ACTION_ID.test(action.id)) {
+                throw actionError("constraint_violation", `"${action.id}" is not a namespace, a slash and a name`);
+            }
+            if (actions.has(action.id))
+                throw actionError("duplicate_name", `action ${action.id} is already registered`);
+            const validate = compileParameters(action.id, parametersSchema(action));
+            actions.set(action.id, { action, validate });
+        },
+        get: (id) => actions.get(id)?.action,
+        list: () => [...actions.values()].map((registered) => registered.action),
+        async run(id, params, host = {}) {
+            try {
+                const outcome = await execute(id, params, host);
+                host.onEntry?.(outcome.entry);
+                return outcome;
+            }
+            catch (error) {
+                const entry = entryOfRefusal(error);
+                if (entry)
+                    host.onEntry?.(entry);
+                throw error;
+            }
+        },
+    };
+}
+/** Creates an empty run log, kept in memory. */
+export function createRunLog() {
+    const entries = [];
+    return { entries, record: (entry) => void entries.push(entry) };
+}
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"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"}

package/dist/tools.d.ts

@@ -0,0 +1,51 @@
+import type { ActionDefinition, JsonSchema } from "./types.js";
+/** An AI tool, in the shape of an MCP tool definition. */
+export interface AiTool {
+    /** The id of the action with its slash replaced by a hyphen (see `toolName`). */
+    readonly name: string;
+    readonly title?: string;
+    readonly description?: string;
+    /** The parameters of the action, a JSON Schema object, `ref` keywords included, in the shape providers accept. */
+    readonly inputSchema: JsonSchema;
+    readonly annotations: {
+        readonly title?: string;
+        /** `true` for an action of kind `read`. */
+        readonly readOnlyHint: boolean;
+        /** `true` for a `destructive` action. */
+        readonly destructiveHint: boolean;
+    };
+}
+/**
+ * The tool name of an action id: the slash replaced by a hyphen, because AI
+ * clients accept only letters, digits, `_` and `-` in a tool name. A hyphen
+ * never appears in an identifier, so `actionIdOfTool` gives the id back.
+ */
+export declare function toolName(id: string): string;
+/** The action id of a tool name made by `toolName`, or `undefined` when the name has no hyphen. */
+export declare function actionIdOfTool(name: string): string | undefined;
+/** What the tools of a project are told about it. */
+export interface ToolOptions {
+    /**
+     * The ordered `languages` of the dataset, the first being the source
+     * language. The description of each localized text parameter then names them.
+     * Left out or empty (not stated), the descriptions are not changed.
+     */
+    readonly languages?: readonly string[] | undefined;
+}
+/** The sentence added to a localized parameter: the languages of the project and its source language. */
+export declare function languagesNote(languages: readonly string[]): string;
+/**
+ * The parameters of an action as `parametersSchema` gives them, with the
+ * languages of the project named in the description of each localized text.
+ * Gives the schema itself when `languages` is absent or empty.
+ */
+export declare function parametersWithLanguages(action: ActionDefinition, languages: readonly string[] | undefined): JsonSchema;
+/** The AI tool of one action, whatever its exposure. */
+export declare function toAiTool(action: ActionDefinition, options?: ToolOptions): AiTool;
+/**
+ * Exports actions to AI tools: the `visible` actions, in
+ * order, each by `toAiTool`. An action whose `exposure` is `hidden` is left
+ * out, because the author of the model says what an AI should use.
+ */
+export declare function toAiTools(actions: Iterable<ActionDefinition>, options?: ToolOptions): AiTool[];
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE/D,0DAA0D;AAC1D,MAAM,WAAW,MAAM;IACrB,iFAAiF;IACjF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,kHAAkH;IAClH,QAAQ,CAAC,WAAW,EAAE,UAAU,CAAC;IACjC,QAAQ,CAAC,WAAW,EAAE;QACpB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QACxB,2CAA2C;QAC3C,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;QAC/B,yCAAyC;QACzC,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;KACnC,CAAC;CACH;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAE3C;AAED,mGAAmG;AACnG,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAG/D;AAiBD,qDAAqD;AACrD,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;CACpD;AAgBD,yGAAyG;AACzG,wBAAgB,aAAa,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAElE;AAiBD;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,gBAAgB,EAAE,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GAAG,UAAU,CAMtH;AAED,wDAAwD;AACxD,wBAAgB,QAAQ,CAAC,MAAM,EAAE,gBAAgB,EAAE,OAAO,GAAE,WAAgB,GAAG,MAAM,CAkBpF;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,GAAE,WAAgB,GAAG,MAAM,EAAE,CAElG"}

package/dist/tools.js

@@ -0,0 +1,106 @@
+import { copyJson } from "./json.js";
+import { parametersSchema } from "./parameters.js";
+/**
+ * The tool name of an action id: the slash replaced by a hyphen, because AI
+ * clients accept only letters, digits, `_` and `-` in a tool name. A hyphen
+ * never appears in an identifier, so `actionIdOfTool` gives the id back.
+ */
+export function toolName(id) {
+    return id.replace("/", "-");
+}
+/** The action id of a tool name made by `toolName`, or `undefined` when the name has no hyphen. */
+export function actionIdOfTool(name) {
+    const at = name.indexOf("-");
+    return at < 0 ? undefined : `${name.slice(0, at)}/${name.slice(at + 1)}`;
+}
+/** What AI providers refuse at the top level of the schema of a tool. */
+const TOP_LEVEL_REFUSED = ["anyOf", "oneOf", "allOf"];
+/** The properties of an `anyOf` whose branches each require one property, else `undefined`. */
+function atLeastOneOf(anyOf) {
+    if (!Array.isArray(anyOf) || anyOf.length === 0)
+        return undefined;
+    const names = [];
+    for (const branch of anyOf) {
+        const required = branch?.required;
+        if (Object.keys(branch ?? {}).length !== 1 || !Array.isArray(required) || required.length !== 1)
+            return undefined;
+        names.push(String(required[0]));
+    }
+    return names;
+}
+/** Whether a parameter schema is a localized text: a string, or a map of language to string, in an `anyOf`. */
+function isLocalizedText(node) {
+    const branches = node.anyOf;
+    if (!Array.isArray(branches))
+        return false;
+    const isMapOfStrings = (branch) => {
+        const values = branch.additionalProperties;
+        return branch.type === "object" && typeof values === "object" && values !== null && values.type === "string";
+    };
+    return (branches.some((branch) => branch?.type === "string") &&
+        branches.some((branch) => branch !== null && typeof branch === "object" && isMapOfStrings(branch)));
+}
+/** The sentence added to a localized parameter: the languages of the project and its source language. */
+export function languagesNote(languages) {
+    return `Write this text only in the languages of the project: ${languages.join(", ")}. The source language is ${languages[0]}. Give an object keyed by language code.`;
+}
+/** Appends `languagesNote` to every localized text found in `node`, in place. */
+function nameLanguages(node, note) {
+    if (Array.isArray(node)) {
+        for (const entry of node)
+            nameLanguages(entry, note);
+        return;
+    }
+    if (node === null || typeof node !== "object")
+        return;
+    const object = node;
+    if (isLocalizedText(object)) {
+        object.description = [object.description, note].filter((part) => typeof part === "string" && part !== "").join(" ");
+        return;
+    }
+    for (const value of Object.values(object))
+        nameLanguages(value, note);
+}
+/**
+ * The parameters of an action as `parametersSchema` gives them, with the
+ * languages of the project named in the description of each localized text.
+ * Gives the schema itself when `languages` is absent or empty.
+ */
+export function parametersWithLanguages(action, languages) {
+    const schema = parametersSchema(action);
+    if (!languages || languages.length === 0)
+        return schema;
+    const copy = copyJson(schema);
+    nameLanguages(copy, languagesNote(languages));
+    return copy;
+}
+/** The AI tool of one action, whatever its exposure. */
+export function toAiTool(action, options = {}) {
+    const { title } = action;
+    const inputSchema = copyJson(parametersWithLanguages(action, options.languages));
+    const required = atLeastOneOf(inputSchema.anyOf);
+    for (const keyword of TOP_LEVEL_REFUSED)
+        delete inputSchema[keyword];
+    const rule = required ? `Give at least one of: ${required.join(", ")}.` : undefined;
+    const description = rule ? [action.description, rule].filter(Boolean).join(" ") : action.description;
+    return {
+        name: toolName(action.id),
+        ...(title === undefined ? {} : { title }),
+        ...(description === undefined ? {} : { description }),
+        inputSchema: inputSchema,
+        annotations: {
+            ...(title === undefined ? {} : { title }),
+            readOnlyHint: action.kind === "read",
+            destructiveHint: action.destructive === true,
+        },
+    };
+}
+/**
+ * Exports actions to AI tools: the `visible` actions, in
+ * order, each by `toAiTool`. An action whose `exposure` is `hidden` is left
+ * out, because the author of the model says what an AI should use.
+ */
+export function toAiTools(actions, options = {}) {
+    return [...actions].filter((action) => action.exposure !== "hidden").map((action) => toAiTool(action, options));
+}
+//# sourceMappingURL=tools.js.map

package/dist/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,118 @@
+/**
+ * The types of the action contract (`packages/core/docs/spec/meta-model.md`,
+ * section Action). They hold no model: an action is an id, a description for
+ * people and AI, its parameters as JSON Schema and a body.
+ */
+/** A JSON Schema, as plain data. */
+export type JsonSchema = {
+    readonly [keyword: string]: unknown;
+};
+/**
+ * The declaration of an action, apart from its body. It matches an MCP tool
+ * definition: `id` gives the tool name, `description` and `parameters` the
+ * description and input schema, `kind: "read"` the read-only hint and
+ * `destructive` the destructive hint.
+ */
+export interface ActionDefinition {
+    /** The namespace of the module, a slash and a name, for example `scflow/create_actor`. */
+    readonly id: string;
+    /** A short label for people, used in a user interface and an undo history. */
+    readonly title?: string;
+    /** What the action does, for people and AI assistants. */
+    readonly description?: string;
+    /** `read` writes nothing; `action`, the default, writes. */
+    readonly kind?: "read" | "action";
+    /** Whether the action may destroy data. */
+    readonly destructive?: boolean;
+    /** Whether an AI sees the action: `visible`, the default, or `hidden`. */
+    readonly exposure?: "visible" | "hidden";
+    /**
+     * The parameters, a JSON Schema object (draft 2020-12), or its JSON text as a
+     * manifest holds it. It may use the keyword `ref`, which names a schema of
+     * the model: see `RefResolver`. Absent, the action takes an empty object.
+     */
+    readonly parameters?: JsonSchema | string;
+    /** The schemas the action writes. Kept for the engine, which enforces it. */
+    readonly writes?: readonly string[];
+}
+/**
+ * The trace of one run: a body records through it each command it emits, with
+ * its result, and calls other actions. A host builds the context of the body
+ * from it (`RunHost.context`); without a host context, the body receives the
+ * trace itself.
+ */
+export interface RunTrace {
+    /** The id of the running action. */
+    readonly action: string;
+    /**
+     * Records a command as the body emitted it, before its placeholders are
+     * resolved, with the result the engine gave.
+     */
+    command(command: unknown, result: unknown): void;
+    /**
+     * Runs another action of the registry with the same host, and records the
+     * call as a step of this run. It resolves to the result of the called action,
+     * and rejects with its exception.
+     */
+    call(id: string, params?: unknown): Promise<unknown>;
+}
+/**
+ * An action: its declaration and its body. The body is `run(params, context)`;
+ * it receives the parameters after their check, with each `ref` resolved to a
+ * key, and the context the host builds. Following the contract of a body, its
+ * only effect is to emit commands and calls through that context.
+ */
+export interface Action<C = RunTrace> extends ActionDefinition {
+    run(params: any, context: C): unknown;
+}
+/**
+ * The instances a `ref` value names, as the engine finds them: the key of the
+ * instance whose id is the value, if any, and the keys of the instances whose
+ * `display_name` is the value, in any language.
+ */
+export interface RefMatches {
+    readonly id: string | null;
+    readonly names: readonly string[];
+}
+/**
+ * Finds the instances of `schema` a `ref` value names. The engine gives it,
+ * since this package reads no instance; the package applies the rule of
+ * resolution (see `validateParameters`).
+ */
+export type RefResolver = (schema: string, value: string) => RefMatches | Promise<RefMatches>;
+/** What a host gives a run: the context of bodies, the resolver of `ref` and the run log. */
+export interface RunHost<C = RunTrace> {
+    /** Builds the context a body receives from the trace of its run. Absent, the body receives the trace. */
+    context?(trace: RunTrace): C;
+    /** Resolves the `ref` values of parameters. Absent, a `ref` value is given to the body as it is. */
+    resolveRef?: RefResolver;
+    /** Receives the entry of each top-level call, done or refused. A nested call is a step of its caller. */
+    onEntry?(entry: RunEntry): void;
+}
+/** One call of an action, as it ran (`run_entry` of the specification). */
+export interface RunEntry {
+    /** The id of the action. */
+    readonly action: string;
+    /** The parameters in canonical JSON, after their check with each ref resolved; as given when they were refused. */
+    readonly parameters: string;
+    /** What the body emitted, in order. */
+    readonly steps: readonly RunStep[];
+    readonly outcome: "done" | "refused";
+    /** The code of the exception of a refused call, or its message when it has no code. */
+    readonly error?: string;
+    /** The result of the action in canonical JSON; absent when the action returned none. */
+    readonly result?: string;
+}
+/** One effect of a body (`run_step`): a command with its result, or a call. */
+export type RunStep = {
+    readonly command: unknown;
+    readonly result: string;
+} | {
+    readonly call: RunEntry;
+};
+/** What a run gives: the result of the body and the entry of the call. */
+export interface RunOutcome {
+    readonly result: unknown;
+    readonly entry: RunEntry;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}