@orkestrel/tool 0.0.3 → 0.0.4

package/README.md

@@ -33,7 +33,7 @@ npm install @orkestrel/tool
 
 ## Requirements
 
-- Node.js >= 24
+- Node.js >= 22
 - Dual ESM + CommonJS builds (`import` and `require` both supported)
 
 ## Guide

package/dist/src/core/index.cjs

@@ -425,6 +425,108 @@ var RELATION_TOOL_DESCRIPTION = [
 var RELATION_TOOL_LIMIT = 1e3;
 /** The default cap on how many `include` path segments deep a `load` / `find` call may traverse — the relation tool's default include-depth ceiling. */
 var RELATION_TOOL_DEPTH = 3;
+/**
+* The name {@link import('./factories.js').createInferTool} advertises by default — the key a
+* model calls and the `ToolManagerInterface` (`@orkestrel/agent`) registers under.
+*/
+var INFER_TOOL_NAME = "infer";
+/**
+* The lean {@link import('@orkestrel/agent').ToolInterface.summary} {@link import('./factories.js').createInferTool}
+* advertises in place of {@link INFER_TOOL_DESCRIPTION} — a `ToolManagerInterface.definitions()`
+* (`@orkestrel/agent`) advertises `summary ?? description`, so this one-sentence text stands in
+* for the full teaching description; the full text stays retrievable via
+* {@link import('./factories.js').createDescribeTool}.
+*/
+var INFER_TOOL_SUMMARY = "Infer a JSON Schema (as advertised tool parameters) from one or more example values. Call describe('infer') for the required fields.";
+var INFER_TOOL_DESCRIPTION = [
+	"Infer a JSON Schema from example values, returned in the same shape a tool advertises its parameters.",
+	"",
+	"Required:",
+	"  samples    - an array of at least one example value to infer the schema from.",
+	"Optional:",
+	"  format     - infer string formats (date-time, email, ...) from the samples. Defaults to false.",
+	"  enum       - infer enum constraints from repeated literal values across the samples. Defaults to false.",
+	"  candidates - values to check against the freshly inferred schema. When present, the result",
+	"               is wrapped as { parameters, checks } instead of the bare parameters record, one",
+	"               check per candidate (same index). Every check has the uniform shape",
+	"               { index, valid, coercible, faults? }. `valid` is a STRICT verdict (no coercion)",
+	"               — e.g. the number 7 is NOT valid against a string slot. `coercible` answers a",
+	"               separate question: would the SAME value be accepted by an endpoint tool call,",
+	"               whose enforcement NORMALIZES args (7 coerces to '7')? So 7 against a string slot",
+	"               yields { valid: false, coercible: true, faults: [] } — a strict mismatch that",
+	"               normalization would silently accept, so faults is EMPTY. `faults` only ever",
+	"               populates for a non-coercible mismatch (a wrong type normalization cannot fix,",
+	"               a missing required key, an out-of-enum value); checks never throw, regardless of",
+	"               candidate shape.",
+	"Example (no candidates):",
+	`  in:  ${JSON.stringify({ samples: [{
+		id: 1,
+		name: "Ada"
+	}, {
+		id: 2,
+		name: "Bob"
+	}] })}`,
+	`  out: ${JSON.stringify({
+		type: "object",
+		properties: {
+			id: { type: "integer" },
+			name: { type: "string" }
+		},
+		required: ["id", "name"],
+		additionalProperties: false
+	})}`,
+	"Example (with candidates):",
+	`  in:  ${JSON.stringify({
+		samples: [{
+			id: 1,
+			name: "Ada"
+		}],
+		candidates: [
+			{
+				id: 3,
+				name: "Cy"
+			},
+			{
+				id: "x",
+				name: "Cy"
+			},
+			{
+				id: 1,
+				name: 7
+			}
+		]
+	})}`,
+	`  out: ${JSON.stringify({
+		parameters: {
+			type: "object",
+			properties: {
+				id: { type: "integer" },
+				name: { type: "string" }
+			},
+			required: ["id", "name"],
+			additionalProperties: false
+		},
+		checks: [
+			{
+				index: 0,
+				valid: true,
+				coercible: true
+			},
+			{
+				index: 1,
+				valid: false,
+				coercible: false,
+				faults: "<structured faults>"
+			},
+			{
+				index: 2,
+				valid: false,
+				coercible: true,
+				faults: []
+			}
+		]
+	})}`
+].join("\n");
 //#endregion
 //#region src/core/errors.ts
 /**
@@ -1106,6 +1208,28 @@ var relationToolShape = (0, _orkestrel_contract.unionShape)((0, _orkestrel_contr
 		description: "The \"through\" relation name."
 	})
 }));
+/**
+* The shape of {@link import('./factories.js').createInferTool}'s call arguments — one or more
+* example `samples` to infer a JSON Schema from, plus per-call `format` / `enum` toggles and an
+* optional `candidates` array to check against the inferred schema.
+*
+* @remarks
+* `samples` requires at least one element (`min: 1`) — an empty array parses to `undefined`,
+* surfaced by the handler as a typed `TOOL` {@link import('./errors.js').AgentToolError}. When
+* `candidates` is present (any array, including empty), the handler compiles a contract from the
+* freshly inferred schema and checks each candidate against it with a STRICT guard (`.is`, no
+* coercion) — the opposite of {@link import('./factories.js').createEndpointTool}'s NORMALIZING
+* `.parse` enforcement.
+*/
+var inferToolShape = (0, _orkestrel_contract.objectShape)({
+	samples: (0, _orkestrel_contract.arrayShape)((0, _orkestrel_contract.jsonShape)(), {
+		min: 1,
+		description: "The example values to infer a JSON Schema from (at least one)."
+	}),
+	format: (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.booleanShape)({ description: "Infer string formats (date-time, email, ...) from the samples. Defaults to false." })),
+	enum: (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.booleanShape)({ description: "Infer enum constraints from repeated literal values. Defaults to false." })),
+	candidates: (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.arrayShape)((0, _orkestrel_contract.jsonShape)(), { description: "Optional values to check against the freshly inferred schema. When present, the tool returns a per-candidate verdict (strict — no coercion) alongside the inferred parameters." }))
+});
 //#endregion
 //#region src/core/helpers.ts
 /**
@@ -2820,6 +2944,216 @@ function createRelationTool(options) {
 		}
 	});
 }
+/**
+* Build a standalone LLM-callable tool that infers a JSON Schema from example values — the
+* utility half of the "existing API/DB → MCP tool" bridge (the other half,
+* {@link createEndpointTool}, wraps one CONCRETE endpoint).
+*
+* @remarks
+* The universal tool-handler contract (AGENTS §14): validates the call args against
+* {@link import('./shapers.js').inferToolShape} (`samples` non-empty, `format` / `enum` optional
+* booleans, `candidates` an optional array), infers a schema via `@orkestrel/contract`'s
+* `samplesToSchema`, wraps a non-object root as `{ value: <schema> }` via `schemaToObject` (mirrors
+* the tool-parameters convention every other `create*Tool` factory advertises), and RETURNS the
+* resulting parameters record. An empty `samples` array fails `inferToolShape`'s `min: 1` bound —
+* `contract.parse` returns `undefined` and the handler throws a typed `TOOL`
+* {@link import('./errors.js').AgentToolError}.
+*
+* When `candidates` is ABSENT, the return is the bare parameters record — unchanged from before
+* this array existed. When `candidates` is PRESENT (any array, including empty), the handler
+* compiles a SEPARATE per-call contract from the RAW inferred schema (via `@orkestrel/contract`'s
+* `schemaToShape`, NOT the `schemaToObject`-wrapped parameters — a bare-value sample checks a
+* bare-value candidate) and returns `{ parameters, checks }`, one check per candidate at the same
+* index. Every entry has a UNIFORM shape — `{ index, valid, coercible }`, with `faults` added ONLY
+* when `valid` is `false`: `valid` is the STRICT guard verdict (`checker.is(candidate)`), the
+* OPPOSITE of {@link createEndpointTool}'s enforcement, which coerces (`7` becomes `'7'` for a
+* string slot) — here a conformance report answers "does this value conform AS-IS": `7` against a
+* string slot is `valid: false`, full stop. `coercible` answers a SEPARATE question — "would the
+* NORMALIZING parse accept this value", i.e. would {@link createEndpointTool}'s default enforcement
+* admit it (`checker.parse(candidate) !== undefined`) — computed for every candidate regardless of
+* `valid`; by the house parse/guard round-trip guarantee (AGENTS §14), a `valid: true` entry is
+* ALWAYS also `coercible: true`. `@orkestrel/contract` 0.0.7's `explain` mirrors the normalizing
+* `parse`'s leniency, not `is`'s strictness — so a strictly-invalid but coercible candidate (`7`
+* against a string slot) yields `{ valid: false, coercible: true, faults: [] }`: EMPTY faults, since
+* the mismatch the normalizing parse would silently fix is not one `explain` reports. `faults`
+* therefore only ever populates for a NON-coercible mismatch — a wrong type the parse can't coerce
+* (a boolean in a string slot), a missing required key, or an out-of-enum value — where
+* `coercible: false`. `checker.is` / `.parse` / `.explain` are all total over JSON-safe input — a
+* JSON-safe hostile candidate (a `__proto__`-carrying object, deeply nested data) reaches all three
+* and yields a bounded, non-throwing per-candidate verdict; a NON-JSON-safe candidate (e.g. a
+* throwing-getter `Proxy`) never reaches the checker at all — it fails the OUTER `args` parse
+* against {@link import('./shapers.js').inferToolShape} and rejects the WHOLE call with the same
+* `TOOL` {@link import('./errors.js').AgentToolError} a malformed `samples`/`format`/`enum` throws,
+* with no per-candidate verdict produced.
+*
+* @param options - Advertised `name` / `description` overrides (see
+*   {@link import('./types.js').InferToolOptions})
+* @returns A `ToolInterface` (named {@link import('./constants.js').INFER_TOOL_NAME} by default)
+*
+* @example
+* ```ts
+* import { createInferTool } from '@src/core'
+* import { createToolManager } from '@orkestrel/agent'
+*
+* const tool = createInferTool()
+* const tools = createToolManager()
+* tools.add(tool)
+*
+* const result = await tools.execute({
+* 	id: 'call-1',
+* 	name: 'infer',
+* 	arguments: { samples: [{ id: 1, name: 'Ada' }, { id: 2, name: 'Bob' }] },
+* })
+* // result.value -> { type: 'object', properties: { id: {...}, name: {...} }, ... }
+*
+* // with candidates, the result is wrapped with per-candidate verdicts
+* const checked = await tools.execute({
+* 	id: 'call-2',
+* 	name: 'infer',
+* 	arguments: {
+* 		samples: [{ id: 1, name: 'Ada' }],
+* 		candidates: [{ id: 2, name: 'Bob' }, { id: 'x', name: 'Cy' }],
+* 	},
+* })
+* // checked.value -> { parameters: {...}, checks: [
+* //   { index: 0, valid: true, coercible: true },
+* //   { index: 1, valid: false, coercible: false, faults: [...] },
+* // ] }
+* ```
+*/
+function createInferTool(options) {
+	const contract = (0, _orkestrel_contract.createContract)(inferToolShape);
+	const parameters = (0, _orkestrel_contract.schemaToParameters)(contract.schema);
+	return (0, _orkestrel_agent.createTool)({
+		name: options?.name ?? "infer",
+		description: options?.description ?? INFER_TOOL_DESCRIPTION,
+		summary: INFER_TOOL_SUMMARY,
+		parameters,
+		execute: async (args) => {
+			const parsed = contract.parse(args);
+			if (parsed === void 0) throw new AgentToolError("TOOL", "malformed infer arguments", { args });
+			const schema = (0, _orkestrel_contract.samplesToSchema)(parsed.samples, {
+				format: parsed.format ?? false,
+				enum: parsed.enum ?? false
+			});
+			const result = (0, _orkestrel_contract.schemaToParameters)((0, _orkestrel_contract.schemaToObject)(schema));
+			if (result === void 0) throw new AgentToolError("TOOL", "could not infer a schema", { args });
+			if (parsed.candidates === void 0) return result;
+			const checker = (0, _orkestrel_contract.createContract)((0, _orkestrel_contract.schemaToShape)(schema));
+			return {
+				parameters: result,
+				checks: parsed.candidates.map((candidate, index) => {
+					const valid = checker.is(candidate);
+					const coercible = checker.parse(candidate) !== void 0;
+					return valid ? {
+						index,
+						valid,
+						coercible
+					} : {
+						index,
+						valid,
+						coercible,
+						faults: checker.explain(candidate)
+					};
+				})
+			};
+		}
+	});
+}
+/**
+* Wrap one CONCRETE endpoint ({@link import('./types.js').EndpointDefinition}) as an LLM-callable
+* `ToolInterface` — the endpoint half of the "existing API/DB → MCP tool" bridge (the other half,
+* {@link createInferTool}, is a standalone inference utility).
+*
+* @remarks
+* `parameters` is inferred ONCE at construction from `definition.samples` via
+* `@orkestrel/contract`'s `samplesToSchema` (tuned by {@link import('./types.js').EndpointToolOptions}'s
+* `format` / `enum`), wrapping a non-object root as `{ value: <schema> }` via `schemaToObject` —
+* the SAME object-rooted schema is both the ADVERTISED `parameters` and, by default
+* ({@link import('./types.js').EndpointToolOptions.validate} `true`), the ENFORCED contract:
+* `@orkestrel/contract` 0.0.7's `schemaToShape` compiles it ONCE (via `createContract`) into a
+* `ContractInterface` whose `.parse` runs on every call's `args` before `definition.invoke` — a
+* NORMALIZING parse, not a strict type check: a scalar is COERCED to its inferred type where the
+* house parsers coerce (a number to/from a numeric string, a boolean from `'1'`/`'0'`/`'true'`/
+* `'false'`/`1`/`0`), so `definition.invoke` receives the COERCED value (e.g. `7` sent for a
+* string slot arrives as `'7'`), not the raw call value. A call whose `args` fails to parse into
+* a record — a required key missing, or a value not coercible to its slot's type — THROWS a
+* typed `TOOL` {@link import('./errors.js').AgentToolError} carrying the compiled contract's
+* structured `explain` faults, and `definition.invoke` is never called. `format` annotations are
+* NEVER asserted, and a key outside the closed inferred schema is SILENTLY DROPPED rather than
+* rejected (see {@link import('./types.js').EndpointToolOptions.validate}). With
+* `validate: false`, `execute` PASSES THROUGH the model-supplied `args` to `definition.invoke`
+* WITHOUT re-validation — the pre-0.0.7 behavior, preserved as an explicit opt-out. Either way,
+* `invoke`'s return flows back as the tool call's plain result; a throw PROPAGATES uncaught,
+* isolated by the `ToolManagerInterface` (`@orkestrel/agent`) into the canonical error envelope
+* (AGENTS §14) — never caught or re-wrapped here.
+*
+* @param definition - The endpoint's identity, non-empty samples, and local handler (see
+*   {@link import('./types.js').EndpointDefinition})
+* @param options - Construction-time inference tuning + the validate opt-out (see
+*   {@link import('./types.js').EndpointToolOptions})
+* @returns A `ToolInterface` named `definition.name`
+*
+* @example
+* ```ts
+* import { createEndpointTool } from '@src/core'
+* import { createToolManager } from '@orkestrel/agent'
+*
+* const tool = createEndpointTool({
+* 	name: 'lookupUser',
+* 	description: 'Look up a user by id.',
+* 	samples: [{ id: '1', name: 'Ada' }, { id: '2', name: 'Bob' }],
+* 	invoke: (args) => ({ id: args.id, name: 'Ada' }),
+* })
+* const tools = createToolManager()
+* tools.add(tool)
+*
+* // conforming args (all required keys present) parse and reach `invoke`
+* const result = await tools.execute({
+* 	id: 'call-1',
+* 	name: 'lookupUser',
+* 	arguments: { id: '1', name: 'Ada' },
+* })
+* // result.value -> { id: '1', name: 'Ada' }
+*
+* // a nonconforming call (id is not coercible to the required string) is rejected before
+* // `invoke` runs
+* const rejected = await tools.execute({
+* 	id: 'call-2',
+* 	name: 'lookupUser',
+* 	arguments: { id: true, name: 'Ada' },
+* })
+* // rejected.error -> the TOOL AgentToolError message
+* ```
+*/
+function createEndpointTool(definition, options) {
+	if (definition.samples.length === 0) throw new AgentToolError("TOOL", "endpoint requires at least one sample", { name: definition.name });
+	const objectSchema = (0, _orkestrel_contract.schemaToObject)((0, _orkestrel_contract.samplesToSchema)(definition.samples, {
+		format: options?.format ?? false,
+		enum: options?.enum ?? false
+	}));
+	const parameters = (0, _orkestrel_contract.schemaToParameters)(objectSchema);
+	if (!(options?.validate ?? true)) return (0, _orkestrel_agent.createTool)({
+		name: definition.name,
+		description: definition.description,
+		parameters,
+		execute: (args) => definition.invoke(args)
+	});
+	const contract = (0, _orkestrel_contract.createContract)((0, _orkestrel_contract.schemaToShape)(objectSchema));
+	return (0, _orkestrel_agent.createTool)({
+		name: definition.name,
+		description: definition.description,
+		parameters,
+		execute: (args) => {
+			const parsed = contract.parse(args);
+			if (parsed === void 0 || !(0, _orkestrel_contract.isRecord)(parsed)) throw new AgentToolError("TOOL", "malformed endpoint call arguments", {
+				name: definition.name,
+				faults: contract.explain(args)
+			});
+			return definition.invoke(parsed);
+		}
+	});
+}
 //#endregion
 exports.AGENT_TOOL_DEPTH = AGENT_TOOL_DEPTH;
 exports.AGENT_TOOL_DESCRIPTION = AGENT_TOOL_DESCRIPTION;
@@ -2838,6 +3172,9 @@ exports.DESCRIBE_TOOL_DESCRIPTION = DESCRIBE_TOOL_DESCRIPTION;
 exports.DESCRIBE_TOOL_NAME = DESCRIBE_TOOL_NAME;
 exports.DESCRIBE_TOOL_SUMMARY = DESCRIBE_TOOL_SUMMARY;
 exports.DatabaseDefinitionStore = DatabaseDefinitionStore;
+exports.INFER_TOOL_DESCRIPTION = INFER_TOOL_DESCRIPTION;
+exports.INFER_TOOL_NAME = INFER_TOOL_NAME;
+exports.INFER_TOOL_SUMMARY = INFER_TOOL_SUMMARY;
 exports.MAX_WORKFLOW_DEPTH = MAX_WORKFLOW_DEPTH;
 exports.MemoryDefinitionStore = MemoryDefinitionStore;
 exports.PROMPT_TOOL_DESCRIPTION = PROMPT_TOOL_DESCRIPTION;
@@ -2876,6 +3213,8 @@ exports.createAnswerTool = createAnswerTool;
 exports.createDatabaseDefinitionStore = createDatabaseDefinitionStore;
 exports.createDatabaseTool = createDatabaseTool;
 exports.createDescribeTool = createDescribeTool;
+exports.createEndpointTool = createEndpointTool;
+exports.createInferTool = createInferTool;
 exports.createMemoryDefinitionStore = createMemoryDefinitionStore;
 exports.createPromptTool = createPromptTool;
 exports.createRelationTool = createRelationTool;
@@ -2892,6 +3231,7 @@ exports.expandInclude = expandInclude;
 exports.expandSteps = expandSteps;
 exports.expandTables = expandTables;
 exports.includeShape = includeShape;
+exports.inferToolShape = inferToolShape;
 exports.isAgentToolError = isAgentToolError;
 exports.isColumnKind = isColumnKind;
 exports.isColumnSpec = isColumnSpec;