@scfloworg/actions 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SCFlow Core contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,61 @@
-# Temporary Holding Version
+# @scfloworg/actions
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The neutral action package: the action type aligned on MCP tools, the check of
+parameters by a standard JSON Schema validator, a registry, batches of calls,
+the export of actions as AI tools, and the run log of executed actions.
+
+It depends on no other SCFlow package and knows no model, so a host that is not
+MCL, such as an application framework, uses it as it is. Its only dependency is
+[Ajv](https://ajv.js.org). The engine plugs in what needs a dataset: the
+resolution of `ref` values, the context of bodies, the steps `when`, `each` and
+`fail` of a batch, and the transaction. The rules are in the specification
+([Action](../core/docs/spec/meta-model.md#action) and
+[Action Package](../core/docs/spec/typescript-reference-implementation.md#action-package)),
+and the use of the package in [docs/actions.md](docs/actions.md).
+
+```ts
+import { createActionRegistry, createRunLog, runBatch, toAiTools } from "@scfloworg/actions";
+
+const registry = createActionRegistry();
+registry.register({
+  id: "demo/create_actor",
+  title: "Create an actor",
+  description: "Creates an actor and returns it",
+  parameters: {
+    type: "object",
+    properties: { display_name: { type: "string" }, parent: { type: "string", ref: "actor" } },
+    required: ["display_name"],
+  },
+  run(params, trace) {
+    const actor = { id: "a1", ...params };
+    trace.command({ create: "actor", input: params }, { after: [actor] });
+    return actor;
+  },
+});
+
+const log = createRunLog();
+const { result } = await registry.run("demo/create_actor", { display_name: "Plant" }, { onEntry: log.record });
+
+await runBatch(registry, {
+  commands: [
+    { call: "demo/create_actor", with: { display_name: "Plant" }, as: "plant" },
+    { call: "demo/create_actor", with: { display_name: "Line", parent: "${plant.id}" } },
+  ],
+}, { onEntry: log.record });
+
+const tools = toAiTools(registry.list()); // MCP tool definitions, hidden actions left out
+```
+
+| Part | Gives |
+| --- | --- |
+| `Action`, `ActionDefinition` | The declaration of an action, as a manifest holds it, and its body `run(params, context)` |
+| `validateParameters` | The check of parameters against their JSON Schema, with defaults and `ref` resolution |
+| `createActionRegistry` | `register`, `get`, `list` and `run`: one call, checked and recorded |
+| `runBatch` | A batch of `call` steps with `${name.path}` references |
+| `toAiTools`, `toolName`, `actionIdOfTool` | The export to AI tools, in the schema AI providers accept; `languages` names the languages of the project in localized parameters |
+| `RunEntry`, `createRunLog`, `canonicalJson` | The run log of the specification, in canonical JSON |
+| `ActionError` | The error of the package; callers branch on `.code` |
+
+The cases of the language it follows are in `@scfloworg/conformance`, as
+`runActionConformanceSuite`, which `tests/conformance.test.ts` runs against this
+package.

package/dist/batch.d.ts

@@ -0,0 +1,44 @@
+import type { ActionRegistry } from "./registry.js";
+import type { RunEntry, RunHost, RunTrace } from "./types.js";
+/**
+ * A step of a batch run by this package: a call of an action by id, with its
+ * parameters in `with`, its result named by `as`.
+ */
+export interface BatchCall {
+    readonly call: string;
+    readonly with?: unknown;
+    readonly as?: string;
+}
+/**
+ * A batch: a script whose steps call actions, with no parameters
+ * (`packages/core/docs/spec/model-command-language.md`, section Script). This
+ * package runs the batches whose steps are only calls; a batch with `when`,
+ * `each` or `fail` runs through the script runner of the engine.
+ */
+export interface Batch {
+    readonly commands: readonly BatchCall[];
+    /** A placeholder giving the result of the batch; the result of its last call when absent. */
+    readonly result?: string;
+}
+/** What a batch gives: its result, and the entry of each of its calls, in order. */
+export interface BatchOutcome {
+    readonly result: unknown;
+    readonly entries: readonly RunEntry[];
+}
+/**
+ * Runs a batch of calls in order through a registry, each a run of
+ * `registry.run` with the host, so the run log gets one entry per call.
+ * Before each call, the placeholders of its `with` are resolved against the
+ * results named by the `as` of earlier calls.
+ *
+ * The batch is checked whole before any call: a step that is not a `call`
+ * with only `with` and `as`, or a batch with `parameters`, is refused with
+ * `invalid_script_step`. A placeholder naming an `as` name not set yet is
+ * refused with `unknown_reference`. A refused call stops the batch and its
+ * exception is thrown as is.
+ *
+ * It opens no transaction: the host runs the whole batch in one, and rolls it
+ * back when the batch throws, so a batch can be undone as one.
+ */
+export declare function runBatch<C = RunTrace>(registry: ActionRegistry<C>, batch: Batch, host?: RunHost<C>): Promise<BatchOutcome>;
+//# sourceMappingURL=batch.d.ts.map

package/dist/batch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch.d.ts","sourceRoot":"","sources":["../src/batch.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE9D;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,QAAQ,EAAE,SAAS,SAAS,EAAE,CAAC;IACxC,6FAA6F;IAC7F,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,oFAAoF;AACpF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,SAAS,QAAQ,EAAE,CAAC;CACvC;AA4FD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,QAAQ,CAAC,CAAC,GAAG,QAAQ,EACzC,QAAQ,EAAE,cAAc,CAAC,CAAC,CAAC,EAC3B,KAAK,EAAE,KAAK,EACZ,IAAI,GAAE,OAAO,CAAC,CAAC,CAAM,GACpB,OAAO,CAAC,YAAY,CAAC,CAkBvB"}

package/dist/batch.js

@@ -0,0 +1,132 @@
+import { actionError } from "./errors.js";
+import { canonicalJson } from "./json.js";
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const STEP_KEYS = new Set(["call", "with", "as"]);
+/** A placeholder whose content is a path: a name, then segments that are identifiers, indexes or `*`. */
+const PATH = /^[A-Za-z_][A-Za-z0-9_]*(?:\.(?:[A-Za-z0-9_]+|\*))*$/;
+const WHOLE = /^\$\{([^}]*)\}$/;
+const ANY = /\$\{([^}]*)\}/g;
+/** Checks the shape of a batch before any call runs. */
+function checkBatch(batch) {
+    if (batch === null || typeof batch !== "object" || Array.isArray(batch)) {
+        throw actionError("invalid_script_step", "a batch is an object with commands");
+    }
+    if ("parameters" in batch)
+        throw actionError("invalid_script_step", "a batch has no parameters");
+    const { commands, result } = batch;
+    if (!Array.isArray(commands))
+        throw actionError("invalid_script_step", "a batch has an array of commands");
+    if (result !== undefined && typeof result !== "string") {
+        throw actionError("invalid_script_step", "the result of a batch is a placeholder");
+    }
+    commands.forEach((step, index) => {
+        const where = `step ${index}`;
+        if (step === null || typeof step !== "object" || Array.isArray(step)) {
+            throw actionError("invalid_script_step", `${where} is not a call`);
+        }
+        const keys = Object.keys(step);
+        const other = keys.find((key) => !STEP_KEYS.has(key));
+        if (other !== undefined || typeof step.call !== "string") {
+            throw actionError("invalid_script_step", `${where} is not a call with only with and as${other ? ` (it has ${other})` : ""}; ` +
+                "a batch with commands, when, each or fail runs through the script runner of the engine");
+        }
+        const { as } = step;
+        if (as !== undefined && (typeof as !== "string" || !IDENTIFIER.test(as))) {
+            throw actionError("invalid_script_step", `${where}: as must be an identifier`);
+        }
+    });
+    return batch;
+}
+/** Follows the segments of a path from a value, by the rules of placeholders on arrays. */
+function follow(value, segments) {
+    if (segments.length === 0)
+        return value;
+    if (value === null || value === undefined)
+        return undefined;
+    const [segment, ...rest] = segments;
+    if (Array.isArray(value)) {
+        if (/^\d+$/.test(segment))
+            return follow(value[Number(segment)], rest);
+        if (segment === "*")
+            return value.map((entry) => follow(entry, rest));
+        return follow(value[0], segments);
+    }
+    if (typeof value === "object")
+        return follow(value[segment], rest);
+    return undefined;
+}
+/**
+ * Resolves the `${name.path}` placeholders of a value against the results
+ * named so far. A placeholder that is the whole string gives the value it
+ * reaches, of any type; one inside text gives its text. A placeholder that is
+ * not a path, such as `${now()}`, is kept for the called action.
+ */
+function resolve(value, names) {
+    const lookup = (path) => {
+        const [name, ...segments] = path.split(".");
+        if (!names.has(name))
+            throw actionError("unknown_reference", `\${${path}}: ${name} is not set yet`);
+        return follow(names.get(name), segments);
+    };
+    if (typeof value === "string") {
+        const whole = WHOLE.exec(value);
+        if (whole && PATH.test(whole[1]))
+            return lookup(whole[1]);
+        return value.replace(ANY, (text, content) => {
+            if (!PATH.test(content))
+                return text;
+            const found = lookup(content);
+            if (found === null || found === undefined)
+                return "";
+            return typeof found === "object" ? canonicalJson(found) : String(found);
+        });
+    }
+    if (Array.isArray(value))
+        return value.map((entry) => resolve(entry, names));
+    if (value !== null && typeof value === "object") {
+        const resolved = {};
+        for (const [key, entry] of Object.entries(value)) {
+            const result = resolve(entry, names);
+            if (result !== undefined)
+                resolved[key] = result;
+        }
+        return resolved;
+    }
+    return value;
+}
+/**
+ * Runs a batch of calls in order through a registry, each a run of
+ * `registry.run` with the host, so the run log gets one entry per call.
+ * Before each call, the placeholders of its `with` are resolved against the
+ * results named by the `as` of earlier calls.
+ *
+ * The batch is checked whole before any call: a step that is not a `call`
+ * with only `with` and `as`, or a batch with `parameters`, is refused with
+ * `invalid_script_step`. A placeholder naming an `as` name not set yet is
+ * refused with `unknown_reference`. A refused call stops the batch and its
+ * exception is thrown as is.
+ *
+ * It opens no transaction: the host runs the whole batch in one, and rolls it
+ * back when the batch throws, so a batch can be undone as one.
+ */
+export async function runBatch(registry, batch, host = {}) {
+    const { commands, result } = checkBatch(batch);
+    const entries = [];
+    const recording = {
+        ...host,
+        onEntry(entry) {
+            entries.push(entry);
+            host.onEntry?.(entry);
+        },
+    };
+    const names = new Map();
+    let last;
+    for (const step of commands) {
+        const params = step.with === undefined ? undefined : resolve(step.with, names);
+        last = (await registry.run(step.call, params, recording)).result;
+        if (step.as !== undefined)
+            names.set(step.as, last);
+    }
+    return { result: result === undefined ? last : resolve(result, names), entries };
+}
+//# sourceMappingURL=batch.js.map

package/dist/batch.js.map

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

package/dist/describe.d.ts

@@ -0,0 +1,27 @@
+import type { ActionDefinition } from "./types.js";
+/** What a host plugs in to describe a call: the names of objects and the translations. */
+export interface DescribeOptions {
+    /**
+     * The name of the instance of `schema` whose key is `id`, or `undefined` when
+     * it has none. This package reads no instance: the host does.
+     */
+    label?(schema: string, id: string): string | undefined | Promise<string | undefined>;
+    /**
+     * The translation of `key` with `vars`, or `undefined` when there is none.
+     * The keys are `action.<id>.title`, `action.<id>.param.<name>` and
+     * `action.<id>.summary`, whose variables are the parameters as they are shown.
+     */
+    t?(key: string, vars?: Readonly<Record<string, string>>): string | undefined;
+    /** The language of the localized texts, tried first. */
+    language?: string;
+}
+/**
+ * The call of an action as a short line for a person who approves it: the
+ * title of the action, then its parameters by name and value. A value that
+ * names an instance (`ref`) is shown by the name `options.label` gives, never
+ * by its uuid; a uuid that is not found is cut to its last four characters.
+ * Texts come from `options.t`, then from the `title` of the action, then from
+ * its id.
+ */
+export declare function describeCall(action: ActionDefinition, params: unknown, options?: DescribeOptions): Promise<string>;
+//# sourceMappingURL=describe.d.ts.map

package/dist/describe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe.d.ts","sourceRoot":"","sources":["../src/describe.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD,0FAA0F;AAC1F,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACrF;;;;OAIG;IACH,CAAC,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,MAAM,GAAG,SAAS,CAAC;IAC7E,wDAAwD;IACxD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAiFD;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE,OAAO,EACf,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,MAAM,CAAC,CAUjB"}

package/dist/describe.js

@@ -0,0 +1,104 @@
+import { parametersSchema } from "./parameters.js";
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const MAX_TEXT = 48;
+const MAX_ITEMS = 3;
+const isNode = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** The id of a call as people read it: no module namespace, spaces for underscores. */
+function readableId(id) {
+    const name = id.slice(id.lastIndexOf("/") + 1).replace(/_/g, " ");
+    return name.charAt(0).toUpperCase() + name.slice(1);
+}
+function clip(text) {
+    return text.length > MAX_TEXT ? `${text.slice(0, MAX_TEXT - 1)}…` : text;
+}
+/** The subschemas of `schema` that apply to a value, through `anyOf`, `oneOf` and `allOf`. */
+function variants(schema) {
+    if (!schema)
+        return [];
+    const nested = ["anyOf", "oneOf", "allOf"].flatMap((keyword) => {
+        const list = schema[keyword];
+        return Array.isArray(list) ? list.filter(isNode).flatMap((item) => variants(item)) : [];
+    });
+    return [schema, ...nested];
+}
+class Describer {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    /** A value as it is shown; `schema` is the schema of the value, which names an object when it has `ref`. */
+    async show(value, schema) {
+        if (typeof value === "string") {
+            const ref = variants(schema).find((variant) => typeof variant.ref === "string")?.ref;
+            if (ref !== undefined && this.options.label) {
+                const label = await this.options.label(ref, value);
+                if (label !== undefined)
+                    return clip(label);
+            }
+            if (UUID.test(value))
+                return "…" + value.slice(-4);
+            return clip(value);
+        }
+        if (Array.isArray(value)) {
+            const items = variants(schema).find((variant) => isNode(variant.items))?.items;
+            const shown = await Promise.all(value.slice(0, MAX_ITEMS).map((item) => this.show(item, items)));
+            return shown.join(", ") + (value.length > MAX_ITEMS ? `, +${value.length - MAX_ITEMS}` : "");
+        }
+        if (isNode(value)) {
+            const language = this.options.language;
+            const texts = Object.entries(value);
+            // A localized text is a map of language to string: only one language is shown.
+            if (texts.length > 0 && texts.every(([, text]) => typeof text === "string")) {
+                const preferred = language === undefined ? undefined : value[language];
+                return clip(String(preferred ?? texts[0][1]));
+            }
+            const properties = variants(schema).find((variant) => isNode(variant.properties))?.properties;
+            const parts = await this.parts(value, properties);
+            return `{${parts.join(", ")}}`;
+        }
+        return String(value);
+    }
+    /** The `name value` parts of an object, without the empty values. */
+    async parts(params, properties, action) {
+        const parts = [];
+        for (const [name, value] of Object.entries(params)) {
+            if (value === undefined || value === null || value === "")
+                continue;
+            const property = isNode(properties?.[name]) ? properties[name] : undefined;
+            const label = (action && this.options.t?.(`action.${action}.param.${name}`)) || name;
+            parts.push(`${label}=${await this.show(value, property)}`);
+        }
+        return parts;
+    }
+}
+/**
+ * The call of an action as a short line for a person who approves it: the
+ * title of the action, then its parameters by name and value. A value that
+ * names an instance (`ref`) is shown by the name `options.label` gives, never
+ * by its uuid; a uuid that is not found is cut to its last four characters.
+ * Texts come from `options.t`, then from the `title` of the action, then from
+ * its id.
+ */
+export async function describeCall(action, params, options = {}) {
+    const describer = new Describer(options);
+    const schemaProperties = parametersSchema(action).properties;
+    const properties = isNode(schemaProperties) ? schemaProperties : undefined;
+    const title = options.t?.(`action.${action.id}.title`) ?? action.title ?? readableId(action.id);
+    if (!isNode(params))
+        return title;
+    const parts = await describer.parts(params, properties, action.id);
+    if (parts.length === 0)
+        return title;
+    const summary = options.t?.(`action.${action.id}.summary`, await shownVariables(describer, params, properties));
+    return summary ?? `${title}: ${parts.join(", ")}`;
+}
+async function shownVariables(describer, params, properties) {
+    const vars = {};
+    for (const [name, value] of Object.entries(params)) {
+        if (value === undefined || value === null || value === "")
+            continue;
+        vars[name] = await describer.show(value, isNode(properties?.[name]) ? properties[name] : undefined);
+    }
+    return vars;
+}
+//# sourceMappingURL=describe.js.map

package/dist/describe.js.map

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

package/dist/errors.d.ts

@@ -0,0 +1,30 @@
+/** Every code an `ActionError` carries, each with the condition that raises it. */
+export declare const ActionErrorCode: {
+    /** The parameters break the JSON Schema of the action, or a `ref` matches no instance or several. */
+    readonly invalid_parameters: "invalid_parameters";
+    /** An id names no action of the registry. */
+    readonly unknown_action: "unknown_action";
+    /** An action is registered with the id of another one. */
+    readonly duplicate_name: "duplicate_name";
+    /** An action is registered with an id or parameters that are not valid. */
+    readonly constraint_violation: "constraint_violation";
+    /** A step of a batch is not a `call` with only `with` and `as`, or a batch has `parameters`. */
+    readonly invalid_script_step: "invalid_script_step";
+    /** A placeholder of a batch names an `as` name that is not set yet. */
+    readonly unknown_reference: "unknown_reference";
+};
+/** The name of one code of `ActionErrorCode`. */
+export type ActionErrorCodeName = keyof typeof ActionErrorCode;
+/**
+ * The error this package throws: `code` names the cause, with the names the
+ * engine uses for the same causes, so a caller branches on `.code` alike.
+ */
+export declare class ActionError extends Error {
+    readonly code: ActionErrorCodeName;
+    constructor(code: ActionErrorCodeName, message?: string);
+}
+/** Builds an `ActionError`; `message` defaults to the code. */
+export declare function actionError(code: ActionErrorCodeName, message?: string): ActionError;
+/** The code of an exception when it has one, otherwise its message: the `error` of a refused run entry. */
+export declare function errorCodeOf(error: unknown): string;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,mFAAmF;AACnF,eAAO,MAAM,eAAe;IAC1B,qGAAqG;;IAErG,6CAA6C;;IAE7C,0DAA0D;;IAE1D,2EAA2E;;IAE3E,gGAAgG;;IAEhG,uEAAuE;;CAE/D,CAAC;AAEX,iDAAiD;AACjD,MAAM,MAAM,mBAAmB,GAAG,MAAM,OAAO,eAAe,CAAC;AAE/D;;;GAGG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;gBAEvB,IAAI,EAAE,mBAAmB,EAAE,OAAO,CAAC,EAAE,MAAM;CAKxD;AAED,+DAA+D;AAC/D,wBAAgB,WAAW,CAAC,IAAI,EAAE,mBAAmB,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,WAAW,CAEpF;AAED,2GAA2G;AAC3G,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAOlD"}

package/dist/errors.js

@@ -0,0 +1,43 @@
+/** Every code an `ActionError` carries, each with the condition that raises it. */
+export const ActionErrorCode = {
+    /** The parameters break the JSON Schema of the action, or a `ref` matches no instance or several. */
+    invalid_parameters: "invalid_parameters",
+    /** An id names no action of the registry. */
+    unknown_action: "unknown_action",
+    /** An action is registered with the id of another one. */
+    duplicate_name: "duplicate_name",
+    /** An action is registered with an id or parameters that are not valid. */
+    constraint_violation: "constraint_violation",
+    /** A step of a batch is not a `call` with only `with` and `as`, or a batch has `parameters`. */
+    invalid_script_step: "invalid_script_step",
+    /** A placeholder of a batch names an `as` name that is not set yet. */
+    unknown_reference: "unknown_reference",
+};
+/**
+ * The error this package throws: `code` names the cause, with the names the
+ * engine uses for the same causes, so a caller branches on `.code` alike.
+ */
+export class ActionError extends Error {
+    code;
+    constructor(code, message) {
+        super(message ?? code);
+        this.name = "ActionError";
+        this.code = code;
+    }
+}
+/** Builds an `ActionError`; `message` defaults to the code. */
+export function actionError(code, message) {
+    return new ActionError(code, message);
+}
+/** The code of an exception when it has one, otherwise its message: the `error` of a refused run entry. */
+export function errorCodeOf(error) {
+    if (error !== null && typeof error === "object") {
+        const { code, message } = error;
+        if (typeof code === "string")
+            return code;
+        if (typeof message === "string")
+            return message;
+    }
+    return String(error);
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,mFAAmF;AACnF,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,qGAAqG;IACrG,kBAAkB,EAAE,oBAAoB;IACxC,6CAA6C;IAC7C,cAAc,EAAE,gBAAgB;IAChC,0DAA0D;IAC1D,cAAc,EAAE,gBAAgB;IAChC,2EAA2E;IAC3E,oBAAoB,EAAE,sBAAsB;IAC5C,gGAAgG;IAChG,mBAAmB,EAAE,qBAAqB;IAC1C,uEAAuE;IACvE,iBAAiB,EAAE,mBAAmB;CAC9B,CAAC;AAKX;;;GAGG;AACH,MAAM,OAAO,WAAY,SAAQ,KAAK;IAC3B,IAAI,CAAsB;IAEnC,YAAY,IAAyB,EAAE,OAAgB;QACrD,KAAK,CAAC,OAAO,IAAI,IAAI,CAAC,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;QAC1B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED,+DAA+D;AAC/D,MAAM,UAAU,WAAW,CAAC,IAAyB,EAAE,OAAgB;IACrE,OAAO,IAAI,WAAW,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AACxC,CAAC;AAED,2GAA2G;AAC3G,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,KAA8C,CAAC;QACzE,IAAI,OAAO,IAAI,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QAC1C,IAAI,OAAO,OAAO,KAAK,QAAQ;YAAE,OAAO,OAAO,CAAC;IAClD,CAAC;IACD,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;AACvB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `@scfloworg/actions`, the neutral action package: the action type aligned on
+ * MCP tools, the check of parameters by a JSON Schema validator, a registry,
+ * the batches made only of calls, the export to AI tools and the run log. It
+ * depends on no other SCFlow package; the engine plugs in what needs a dataset
+ * (see `docs/actions.md`).
+ */
+export type { Action, ActionDefinition, JsonSchema, RefMatches, RefResolver, RunEntry, RunHost, RunOutcome, RunStep, RunTrace, } from "./types.js";
+export { ActionError, ActionErrorCode, actionError, errorCodeOf } from "./errors.js";
+export type { ActionErrorCodeName } from "./errors.js";
+export { canonicalJson } from "./json.js";
+export { compileParameters, parametersSchema, validateParameters } from "./parameters.js";
+export { createActionRegistry, createRunLog, entryOfRefusal } from "./registry.js";
+export type { ActionRegistry, RunLog } from "./registry.js";
+export { runBatch } from "./batch.js";
+export type { Batch, BatchCall, BatchOutcome } from "./batch.js";
+export { actionIdOfTool, languagesNote, parametersWithLanguages, toAiTool, toAiTools, toolName } from "./tools.js";
+export type { AiTool, ToolOptions } from "./tools.js";
+export { describeCall } from "./describe.js";
+export type { DescribeOptions } from "./describe.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,YAAY,EACV,MAAM,EACN,gBAAgB,EAChB,UAAU,EACV,UAAU,EACV,WAAW,EACX,QAAQ,EACR,OAAO,EACP,UAAU,EACV,OAAO,EACP,QAAQ,GACT,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACrF,YAAY,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAC1F,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACnF,YAAY,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAC5D,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,YAAY,EAAE,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AACjE,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,uBAAuB,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACnH,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+export { ActionError, ActionErrorCode, actionError, errorCodeOf } from "./errors.js";
+export { canonicalJson } from "./json.js";
+export { compileParameters, parametersSchema, validateParameters } from "./parameters.js";
+export { createActionRegistry, createRunLog, entryOfRefusal } from "./registry.js";
+export { runBatch } from "./batch.js";
+export { actionIdOfTool, languagesNote, parametersWithLanguages, toAiTool, toAiTools, toolName } from "./tools.js";
+export { describeCall } from "./describe.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAErF,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAC1F,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEnF,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,uBAAuB,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEnH,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC"}

package/dist/json.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The canonical form of JSON, in which the run log holds parameters and
+ * results and a replay compares steps: the keys of every object sorted, no
+ * white space. As in `JSON.stringify`, a property whose value is `undefined`
+ * or a function is left out, and such a value in an array becomes `null`.
+ * `undefined` itself gives `null`.
+ */
+export declare function canonicalJson(value: unknown): string;
+/** A deep copy of JSON data, through its JSON text. */
+export declare function copyJson<T>(value: T): T;
+//# sourceMappingURL=json.d.ts.map

package/dist/json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../src/json.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEpD;AA+BD,uDAAuD;AACvD,wBAAgB,QAAQ,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAEvC"}

package/dist/json.js

@@ -0,0 +1,44 @@
+/**
+ * The canonical form of JSON, in which the run log holds parameters and
+ * results and a replay compares steps: the keys of every object sorted, no
+ * white space. As in `JSON.stringify`, a property whose value is `undefined`
+ * or a function is left out, and such a value in an array becomes `null`.
+ * `undefined` itself gives `null`.
+ */
+export function canonicalJson(value) {
+    return write(value) ?? "null";
+}
+function write(value) {
+    if (value === null)
+        return "null";
+    if (typeof value === "object" && typeof value.toJSON === "function") {
+        return write(value.toJSON());
+    }
+    switch (typeof value) {
+        case "string":
+        case "number":
+        case "boolean":
+            return JSON.stringify(value);
+        case "bigint":
+            throw new TypeError("canonicalJson: a bigint has no JSON form");
+        case "object": {
+            if (Array.isArray(value))
+                return `[${value.map((entry) => write(entry) ?? "null").join(",")}]`;
+            const record = value;
+            const members = Object.keys(record)
+                .sort()
+                .flatMap((key) => {
+                const text = write(record[key]);
+                return text === undefined ? [] : [`${JSON.stringify(key)}:${text}`];
+            });
+            return `{${members.join(",")}}`;
+        }
+        default:
+            return undefined;
+    }
+}
+/** A deep copy of JSON data, through its JSON text. */
+export function copyJson(value) {
+    return value === undefined ? value : JSON.parse(JSON.stringify(value));
+}
+//# sourceMappingURL=json.js.map

package/dist/json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.js","sourceRoot":"","sources":["../src/json.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,OAAO,KAAK,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC;AAChC,CAAC;AAED,SAAS,KAAK,CAAC,KAAc;IAC3B,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IAClC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAQ,KAA8B,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;QAC9F,OAAO,KAAK,CAAE,KAA+B,CAAC,MAAM,EAAE,CAAC,CAAC;IAC1D,CAAC;IACD,QAAQ,OAAO,KAAK,EAAE,CAAC;QACrB,KAAK,QAAQ,CAAC;QACd,KAAK,QAAQ,CAAC;QACd,KAAK,SAAS;YACZ,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QAC/B,KAAK,QAAQ;YACX,MAAM,IAAI,SAAS,CAAC,0CAA0C,CAAC,CAAC;QAClE,KAAK,QAAQ,CAAC,CAAC,CAAC;YACd,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;gBACtB,OAAO,IAAI,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;YACvE,MAAM,MAAM,GAAG,KAAgC,CAAC;YAChD,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC;iBAChC,IAAI,EAAE;iBACN,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE;gBACf,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;gBAChC,OAAO,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;YACtE,CAAC,CAAC,CAAC;YACL,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;QAClC,CAAC;QACD;YACE,OAAO,SAAS,CAAC;IACrB,CAAC;AACH,CAAC;AAED,uDAAuD;AACvD,MAAM,UAAU,QAAQ,CAAI,KAAQ;IAClC,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAO,CAAC;AAChF,CAAC"}