@orkestrel/tool 0.0.3 → 0.0.4

package/dist/src/core/index.d.cts

@@ -673,6 +673,153 @@ export declare function createDatabaseTool(options?: DatabaseToolOptions): ToolI
  */
 export declare function createDescribeTool(tools: ToolManagerInterface): ToolInterface;
 
+/**
+ * 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
+ * ```
+ */
+export declare function createEndpointTool(definition: EndpointDefinition, options?: EndpointToolOptions): ToolInterface;
+
+/**
+ * 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: [...] },
+ * // ] }
+ * ```
+ */
+export declare function createInferTool(options?: InferToolOptions): ToolInterface;
+
 /**
  * Create the in-memory {@link DefinitionStoreInterface} — a process-lifetime `Map` of database
  * definitions, the DEFAULT store the upcoming database / relation tools will persist their
@@ -1349,6 +1496,76 @@ export declare const describeToolShape: ObjectShape<{
     name: StringShape;
 }, false>;
 
+/**
+ * One concrete endpoint {@link import('./factories.js').createEndpointTool} wraps as an
+ * LLM-callable `ToolInterface` — the advertised identity, a non-empty set of example values its
+ * `parameters` are inferred from, and the local handler that runs a call.
+ *
+ * @remarks
+ * `samples` MUST be non-empty — {@link import('./factories.js').createEndpointTool} throws a
+ * typed `TOOL` {@link import('./errors.js').AgentToolError} at CONSTRUCTION when it is empty,
+ * since an empty sample set cannot infer a schema. By DEFAULT ({@link EndpointToolOptions.validate}
+ * `true`) `invoke` receives the PARSED, NORMALIZED args record — a copy of the model-supplied
+ * `args` with each scalar coerced to its inferred type (e.g. a number sent for a string slot
+ * arrives coerced to a string), checked against the same schema advertised as `parameters` — and
+ * a call with a missing required key or a non-coercible value never reaches `invoke` at all (see
+ * {@link EndpointToolOptions.validate}). With
+ * `validate: false`, `invoke` receives the model-supplied `args` VERBATIM (raw passthrough, never
+ * checked against the inferred schema). Either way `invoke`'s return flows back as the tool
+ * call's result; a throw PROPAGATES uncaught, isolated by the `ToolManagerInterface`
+ * (`@orkestrel/agent`) into the canonical error envelope. When `samples` are non-object values,
+ * the advertised schema wraps them under a single required `value` property, so `invoke` receives
+ * an `args` record of the shape `{ value: ... }` — never the bare value.
+ */
+export declare interface EndpointDefinition {
+    readonly name: string;
+    readonly description: string;
+    readonly samples: readonly unknown[];
+    readonly invoke: EndpointHandler;
+}
+
+/**
+ * The handler {@link import('./types.js').EndpointDefinition.invoke} implements — mirrors
+ * `@orkestrel/agent`'s `ToolOptions.execute` signature EXACTLY (same `Readonly<Record<string,
+ * unknown>>` argument, same `Promise<unknown> | unknown` return) so
+ * `execute: (args) => definition.invoke(args)` typechecks with zero assertions in
+ * {@link import('./factories.js').createEndpointTool}.
+ */
+export declare type EndpointHandler = (args: Readonly<Record<string, unknown>>) => Promise<unknown> | unknown;
+
+/**
+ * Construction-time tuning for {@link import('./factories.js').createEndpointTool} — the
+ * inferred `parameters` schema's `format` / `enum` constraints, and whether that same schema is
+ * ENFORCED at `execute` time.
+ *
+ * @remarks
+ * `format` / `enum` default to `false`, matching `@orkestrel/contract`'s own
+ * `ValueToSchemaOptions` defaults. `validate` defaults to `true`: the schema
+ * `createEndpointTool` advertises as `parameters` (`samplesToSchema` + `schemaToObject`) is
+ * compiled ONCE at construction (via `@orkestrel/contract` 0.0.7's `schemaToShape`) into a
+ * `ContractInterface` used to `parse` every call's `args` before `invoke` runs — a NORMALIZING
+ * parse: a scalar value 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 `invoke`
+ * receives the COERCED values (e.g. `7` sent for a string slot arrives at `invoke` as `'7'`), not
+ * the raw call args. A call whose `args` fails to parse — 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 structured `explain` faults, and `invoke` is never called. Beyond that coercion,
+ * enforcement is STRUCTURAL — required keys, `enum` membership, and numeric bounds — `format`
+ * annotations (`email`, `date-time`, `uuid`, `uri`, ...) are NEVER asserted, mirroring
+ * `@orkestrel/contract`'s own widening-only law for `schemaToShape`: a `format: true`-tuned
+ * endpoint still ACCEPTS a non-conforming string in a format-tagged slot. A key NOT present in
+ * the inferred (closed, `additionalProperties: false`) schema is NEVER a rejection either — it is
+ * SILENTLY DROPPED before `invoke` runs (the same leniency `@orkestrel/contract`'s own `parse`
+ * grants a closed object generally), so `invoke` may see fewer keys than the caller sent. Set
+ * `validate: false` to restore the PRE-0.0.7 behavior exactly — `execute` passes the
+ * model-supplied `args` straight to `invoke` UNCHANGED, unchecked and unstripped.
+ */
+export declare interface EndpointToolOptions {
+    readonly format?: boolean;
+    readonly enum?: boolean;
+    readonly validate?: boolean;
+}
+
 /**
  * Expand the relation tool's FLAT dot-path `include` list into a live `@orkestrel/relation`
  * {@link Include} tree — the pure leaf {@link import('./factories.js').createRelationTool} calls
@@ -1408,6 +1625,54 @@ export declare function expandTables(spec: TableSpec): TablesShape;
 /** Flat dot-path relation include list, expanded via {@link import('./helpers.js').expandInclude}. */
 export declare const includeShape: OptionalShape<ArrayShape<StringShape>>;
 
+export declare const INFER_TOOL_DESCRIPTION: string;
+
+/**
+ * The name {@link import('./factories.js').createInferTool} advertises by default — the key a
+ * model calls and the `ToolManagerInterface` (`@orkestrel/agent`) registers under.
+ */
+export declare const 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}.
+ */
+export declare const INFER_TOOL_SUMMARY = "Infer a JSON Schema (as advertised tool parameters) from one or more example values. Call describe('infer') for the required fields.";
+
+/**
+ * Options for {@link import('./factories.js').createInferTool} — advertised name/description
+ * overrides only; `format` / `enum` are RUNTIME call arguments (see
+ * {@link import('./shapers.js').inferToolShape}), not construction-time options, since a model
+ * chooses them per call.
+ */
+export declare interface InferToolOptions {
+    readonly name?: string;
+    readonly description?: string;
+}
+
+/**
+ * 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.
+ */
+export declare const inferToolShape: ObjectShape<{
+    samples: ArrayShape<JSONShape>;
+    format: OptionalShape<BooleanShape>;
+    enum: OptionalShape<BooleanShape>;
+    candidates: OptionalShape<ArrayShape<JSONShape>>;
+}, false>;
+
 /**
  * Type guard narrowing an unknown caught value to an {@link AgentToolError}.
  *

package/dist/src/core/index.d.ts

@@ -673,6 +673,153 @@ export declare function createDatabaseTool(options?: DatabaseToolOptions): ToolI
  */
 export declare function createDescribeTool(tools: ToolManagerInterface): ToolInterface;
 
+/**
+ * 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
+ * ```
+ */
+export declare function createEndpointTool(definition: EndpointDefinition, options?: EndpointToolOptions): ToolInterface;
+
+/**
+ * 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: [...] },
+ * // ] }
+ * ```
+ */
+export declare function createInferTool(options?: InferToolOptions): ToolInterface;
+
 /**
  * Create the in-memory {@link DefinitionStoreInterface} — a process-lifetime `Map` of database
  * definitions, the DEFAULT store the upcoming database / relation tools will persist their
@@ -1349,6 +1496,76 @@ export declare const describeToolShape: ObjectShape<{
     name: StringShape;
 }, false>;
 
+/**
+ * One concrete endpoint {@link import('./factories.js').createEndpointTool} wraps as an
+ * LLM-callable `ToolInterface` — the advertised identity, a non-empty set of example values its
+ * `parameters` are inferred from, and the local handler that runs a call.
+ *
+ * @remarks
+ * `samples` MUST be non-empty — {@link import('./factories.js').createEndpointTool} throws a
+ * typed `TOOL` {@link import('./errors.js').AgentToolError} at CONSTRUCTION when it is empty,
+ * since an empty sample set cannot infer a schema. By DEFAULT ({@link EndpointToolOptions.validate}
+ * `true`) `invoke` receives the PARSED, NORMALIZED args record — a copy of the model-supplied
+ * `args` with each scalar coerced to its inferred type (e.g. a number sent for a string slot
+ * arrives coerced to a string), checked against the same schema advertised as `parameters` — and
+ * a call with a missing required key or a non-coercible value never reaches `invoke` at all (see
+ * {@link EndpointToolOptions.validate}). With
+ * `validate: false`, `invoke` receives the model-supplied `args` VERBATIM (raw passthrough, never
+ * checked against the inferred schema). Either way `invoke`'s return flows back as the tool
+ * call's result; a throw PROPAGATES uncaught, isolated by the `ToolManagerInterface`
+ * (`@orkestrel/agent`) into the canonical error envelope. When `samples` are non-object values,
+ * the advertised schema wraps them under a single required `value` property, so `invoke` receives
+ * an `args` record of the shape `{ value: ... }` — never the bare value.
+ */
+export declare interface EndpointDefinition {
+    readonly name: string;
+    readonly description: string;
+    readonly samples: readonly unknown[];
+    readonly invoke: EndpointHandler;
+}
+
+/**
+ * The handler {@link import('./types.js').EndpointDefinition.invoke} implements — mirrors
+ * `@orkestrel/agent`'s `ToolOptions.execute` signature EXACTLY (same `Readonly<Record<string,
+ * unknown>>` argument, same `Promise<unknown> | unknown` return) so
+ * `execute: (args) => definition.invoke(args)` typechecks with zero assertions in
+ * {@link import('./factories.js').createEndpointTool}.
+ */
+export declare type EndpointHandler = (args: Readonly<Record<string, unknown>>) => Promise<unknown> | unknown;
+
+/**
+ * Construction-time tuning for {@link import('./factories.js').createEndpointTool} — the
+ * inferred `parameters` schema's `format` / `enum` constraints, and whether that same schema is
+ * ENFORCED at `execute` time.
+ *
+ * @remarks
+ * `format` / `enum` default to `false`, matching `@orkestrel/contract`'s own
+ * `ValueToSchemaOptions` defaults. `validate` defaults to `true`: the schema
+ * `createEndpointTool` advertises as `parameters` (`samplesToSchema` + `schemaToObject`) is
+ * compiled ONCE at construction (via `@orkestrel/contract` 0.0.7's `schemaToShape`) into a
+ * `ContractInterface` used to `parse` every call's `args` before `invoke` runs — a NORMALIZING
+ * parse: a scalar value 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 `invoke`
+ * receives the COERCED values (e.g. `7` sent for a string slot arrives at `invoke` as `'7'`), not
+ * the raw call args. A call whose `args` fails to parse — 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 structured `explain` faults, and `invoke` is never called. Beyond that coercion,
+ * enforcement is STRUCTURAL — required keys, `enum` membership, and numeric bounds — `format`
+ * annotations (`email`, `date-time`, `uuid`, `uri`, ...) are NEVER asserted, mirroring
+ * `@orkestrel/contract`'s own widening-only law for `schemaToShape`: a `format: true`-tuned
+ * endpoint still ACCEPTS a non-conforming string in a format-tagged slot. A key NOT present in
+ * the inferred (closed, `additionalProperties: false`) schema is NEVER a rejection either — it is
+ * SILENTLY DROPPED before `invoke` runs (the same leniency `@orkestrel/contract`'s own `parse`
+ * grants a closed object generally), so `invoke` may see fewer keys than the caller sent. Set
+ * `validate: false` to restore the PRE-0.0.7 behavior exactly — `execute` passes the
+ * model-supplied `args` straight to `invoke` UNCHANGED, unchecked and unstripped.
+ */
+export declare interface EndpointToolOptions {
+    readonly format?: boolean;
+    readonly enum?: boolean;
+    readonly validate?: boolean;
+}
+
 /**
  * Expand the relation tool's FLAT dot-path `include` list into a live `@orkestrel/relation`
  * {@link Include} tree — the pure leaf {@link import('./factories.js').createRelationTool} calls
@@ -1408,6 +1625,54 @@ export declare function expandTables(spec: TableSpec): TablesShape;
 /** Flat dot-path relation include list, expanded via {@link import('./helpers.js').expandInclude}. */
 export declare const includeShape: OptionalShape<ArrayShape<StringShape>>;
 
+export declare const INFER_TOOL_DESCRIPTION: string;
+
+/**
+ * The name {@link import('./factories.js').createInferTool} advertises by default — the key a
+ * model calls and the `ToolManagerInterface` (`@orkestrel/agent`) registers under.
+ */
+export declare const 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}.
+ */
+export declare const INFER_TOOL_SUMMARY = "Infer a JSON Schema (as advertised tool parameters) from one or more example values. Call describe('infer') for the required fields.";
+
+/**
+ * Options for {@link import('./factories.js').createInferTool} — advertised name/description
+ * overrides only; `format` / `enum` are RUNTIME call arguments (see
+ * {@link import('./shapers.js').inferToolShape}), not construction-time options, since a model
+ * chooses them per call.
+ */
+export declare interface InferToolOptions {
+    readonly name?: string;
+    readonly description?: string;
+}
+
+/**
+ * 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.
+ */
+export declare const inferToolShape: ObjectShape<{
+    samples: ArrayShape<JSONShape>;
+    format: OptionalShape<BooleanShape>;
+    enum: OptionalShape<BooleanShape>;
+    candidates: OptionalShape<ArrayShape<JSONShape>>;
+}, false>;
+
 /**
  * Type guard narrowing an unknown caught value to an {@link AgentToolError}.
  *