@orkestrel/toolbox 0.0.5 → 0.0.7

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

@@ -21,7 +21,6 @@ import { ObjectShape } from '@orkestrel/contract';
 import { OptionalShape } from '@orkestrel/contract';
 import { OrderDirection } from '@orkestrel/database';
 import { PrimaryMap } from '@orkestrel/database';
-import { PromptType } from '@orkestrel/terminal';
 import { QueryInput } from '@orkestrel/database';
 import { RelationErrorCode } from '@orkestrel/relation';
 import { RelationManagerInterface } from '@orkestrel/relation';
@@ -214,7 +213,7 @@ export declare const ANSWER_TOOL_NAME = "answer";
  * for the full teaching description; the full text stays retrievable via
  * {@link import('./factories.js').createDescribeTool}.
  */
-export declare const ANSWER_TOOL_SUMMARY = "List prompts addressed to this terminal, or answer one by id. Call describe('answer') for the required fields.";
+export declare const ANSWER_TOOL_SUMMARY = "List forms addressed to this terminal, or answer one by id with a values record. Call describe('answer') for the required fields.";
 
 /**
  * Options for {@link import('./factories.js').createAnswerTool} — the live
@@ -222,9 +221,9 @@ export declare const ANSWER_TOOL_SUMMARY = "List prompts addressed to this termi
  * terminal name `to`, and the advertised tool overrides.
  *
  * @remarks
- * - `manager` — the terminal manager whose `pending(to)` / `answer(to, id, value)` the tool's
- *   handler calls — `pending` lists the prompts currently addressed to `to`, `answer` resolves
- *   one by `id`. A failed `answer` (`TerminalAnswerResult.error`) re-surfaces as a typed
+ * - `manager` — the terminal manager whose `pending(to)` / `answer(to, id, values)` the tool's
+ *   handler calls — `pending` lists the forms currently addressed to `to`, `answer` resolves
+ *   one by `id`. A failed `answer` (`TerminalAnswerError`) re-surfaces as a typed
  *   `ANSWER` {@link import('./errors.js').ToolboxError}.
  * - `to` — the terminal identity this tool lists / answers prompts FOR.
  * - `name` / `description` — advertised tool overrides; default to
@@ -239,22 +238,19 @@ export declare interface AnswerToolOptions {
 
 /**
  * The shape of {@link import('./factories.js').createAnswerTool}'s call arguments — discriminated
- * by `operation`: `'pending'` lists the prompts addressed to this tool's terminal, `'answer'`
- * resolves one by `id` with a `value`.
+ * by `operation`: `'pending'` lists the forms addressed to this tool's terminal, while `'answer'`
+ * resolves one by `id` with a complete `values` record.
  *
  * @remarks
- * `value`'s type varies by the ORIGINAL prompt's form (`string` for `'input'` / `'password'` /
- * `'select'` / `'editor'`, `boolean` for `'confirm'`, `readonly string[]` for `'checkbox'`) —
- * `unionShape(stringShape(), booleanShape(), arrayShape(stringShape()))` expresses that
- * union directly, so `value` is typed as the full `string | boolean | readonly string[]` union
- * here (no lossy string-only fallback needed).
+ * `values` is first bounded to exact JSON. The handler then narrows it with the originating Form
+ * package's `isFormValues` guard before the terminal manager applies it to the parked live form.
  */
 export declare const answerToolShape: UnionShape<readonly [ ObjectShape<{
     operation: LiteralShape<readonly ["pending"]>;
 }, false>, ObjectShape<{
     operation: LiteralShape<readonly ["answer"]>;
     id: StringShape;
-    value: UnionShape<readonly [ StringShape, BooleanShape, ArrayShape<StringShape>]>;
+    values: JSONShape;
 }, false>]>;
 
 /**
@@ -288,28 +284,6 @@ export declare function clampQuery(query: QueryInput | undefined, cap: number):
     limit: number;
 }>;
 
-/**
- * Normalize an LLM-supplied answer `value` to the type {@link PromptType} `form` expects, so a
- * caller that only ever emits strings can still answer a typed prompt.
- *
- * @remarks
- * `'confirm'` coerces to a `boolean` — a `boolean` passes through, and the strings `'true'` /
- * `'false'` (case-insensitively) map to it; any other string is truthy-coerced via
- * `Boolean(value)`. `'checkbox'` coerces to `readonly string[]` — an array passes through
- * (stringifying each entry), a comma-separated string splits + trims into one, and any other
- * single (non-comma) string becomes a one-item array. Every other form (`'input'` / `'password'`
- * / `'select'` / `'editor'`) coerces to a plain `string` — a string passes through verbatim; a
- * non-string, non-object scalar (`number` / `boolean`) stringifies via `String(value)`; an
- * object or array (no lossless string form) falls back to `''` rather than serializing garbage.
- * Pure and total — never throws.
- *
- * @param form - The {@link PromptType} the answer is being coerced FOR
- * @param value - The raw, LLM-supplied answer value
- * @returns The coerced answer — `boolean` for `'confirm'`, `readonly string[]` for `'checkbox'`,
- *   `string` otherwise
- */
-export declare function coerceAnswer(form: PromptType, value: unknown): string | boolean | readonly string[];
-
 /** One column's declared type — a primitive shorthand, or `integer` for a whole-number `number`. */
 export declare type ColumnKind = 'string' | 'integer' | 'number' | 'boolean';
 
@@ -464,24 +438,22 @@ export declare function createAgentFunction(agent: AgentInterface, options?: Age
 export declare function createAgentTool(registry: AgentRegistryInterface, options?: AgentToolOptions): ToolInterface;
 
 /**
- * Build an LLM-callable answer tool — the ANSWER side of the terminal seam. Lists the prompts
+ * Build an LLM-callable answer tool — the ANSWER side of the terminal seam. Lists the forms
  * currently addressed to {@link import('./types.js').AnswerToolOptions.to}, or answers one of
  * them by id.
  *
  * @remarks
  * The universal tool-handler contract (AGENTS §14): validates the call args against
  * {@link import('./shapers.js').answerToolShape} (discriminated by `operation`). `'pending'`
- * returns a compact list (`{ id, from, form, message }`) of every prompt currently addressed to
- * `to` (`TerminalManagerInterface.pending`, `@orkestrel/terminal`). `'answer'` looks the prompt
- * up by `id` (an unknown id throws a typed `ANSWER` {@link import('./errors.js').ToolboxError}),
- * normalizes the model-supplied `value` to the prompt's own form
- * ({@link import('./helpers.js').coerceAnswer}), and applies it via
+ * returns a compact list (`{ id, from, schema }`) of every form currently addressed to `to`.
+ * `'answer'` looks the form up by `id`, narrows the supplied `values` through `@orkestrel/form`,
+ * and applies it via
  * `TerminalManagerInterface.answer` — a rejected / unknown / unresolvable outcome
  * (`TerminalAnswerResult.error`) re-surfaces as a typed `ANSWER` `ToolboxError`; success returns
  * `{ answered: id }`. `to` is FIXED at construction
  * ({@link import('./types.js').AnswerToolOptions.to}) — never read from the model-supplied args —
  * so a model cannot spoof which terminal it is answering for. Concurrent answerers racing on one
- * endpoint are FIRST-WRITE-WINS — a late answer to an already-settled prompt returns a typed
+ * endpoint are FIRST-WRITE-WINS — a late answer to an already-settled form returns a typed
  * `ANSWER` `ToolboxError` (surfaced as a 422 over HTTP).
  *
  * @param options - The live manager, the fixed `to` identity, and advertised overrides (see
@@ -498,7 +470,7 @@ export declare function createAgentTool(registry: AgentRegistryInterface, option
  * manager.add('reviewer')
  * const tool = createAnswerTool({ manager, to: 'reviewer' })
  * const tools = createToolManager()
- * tools.add(tool) // the reviewer terminal can now list/answer prompts addressed to it
+ * tools.add(tool) // the reviewer terminal can now list/answer forms addressed to it
  * ```
  */
 export declare function createAnswerTool(options: AnswerToolOptions): ToolInterface;
@@ -782,19 +754,18 @@ export declare function createInferTool(options?: InferToolOptions): ToolInterfa
 export declare function createMemoryDefinitionStore(): DefinitionStoreInterface;
 
 /**
- * Build an LLM-callable prompt tool — the ASK side of the terminal seam. Asks
- * {@link import('./types.js').PromptToolOptions.to} a question and BLOCKS until it answers,
- * returning the resolved answer value.
+ * Build an LLM-callable form tool — the ASK side of the terminal seam. Asks
+ * a multi-field form and BLOCKS until it answers, returning the resolved values record.
  *
  * @remarks
  * The universal tool-handler contract (AGENTS §14): validates the call args against
- * {@link import('./shapers.js').promptToolShape}, dispatches to the matching
- * `TerminalManagerInterface.ask` overload (`@orkestrel/terminal`) for the call's `form`, and
- * RETURNS the resolved answer on success. `from` is FIXED at construction
+ * {@link import('./shapers.js').promptToolShape}, parses the call's schema through
+ * `@orkestrel/form`, constructs the live form, and passes it to `TerminalManagerInterface.ask`.
+ * `from` is FIXED at construction
  * ({@link import('./types.js').PromptToolOptions.from}) — never read from the model-supplied
- * args — so a model cannot spoof which terminal is asking. A prompt CYCLE rejects with
+ * args — so a model cannot spoof which terminal is asking. A form CYCLE rejects with
  * `TerminalError('DEADLOCK')`, re-surfaced as a typed `DEADLOCK`
- * {@link import('./errors.js').ToolboxError}; an expired prompt re-surfaces as `EXPIRE`; an
+ * {@link import('./errors.js').ToolboxError}; an expired form re-surfaces as `EXPIRE`; an
  * unknown `to` (or any other `TerminalError`) re-surfaces as `TOOL`, naming the unknown terminal
  * plus the known ones (`manager.terminals()`).
  *
@@ -1811,7 +1782,7 @@ export declare const phaseDraftShape: ObjectShape<{
     bail: OptionalShape<LiteralShape<readonly [true, false]>>;
 }, false>;
 
-/** The full prompt protocol {@link import('./factories.js').createPromptTool} advertises. */
+/** The full form protocol {@link import('./factories.js').createPromptTool} advertises. */
 export declare const PROMPT_TOOL_DESCRIPTION: string;
 
 /**
@@ -1827,7 +1798,7 @@ export declare const PROMPT_TOOL_NAME = "ask";
  * for the full teaching description; the full text stays retrievable via
  * {@link import('./factories.js').createDescribeTool}.
  */
-export declare const PROMPT_TOOL_SUMMARY = "Ask another terminal a question and BLOCK until it answers; the call resolves with the answered value. Call describe('ask') for the required fields.";
+export declare const PROMPT_TOOL_SUMMARY = "Ask another terminal a multi-field form and BLOCK until it answers; the call resolves with the values record. Call describe('ask') for the schema.";
 
 /**
  * Options for {@link import('./factories.js').createPromptTool} — the live
@@ -1835,12 +1806,12 @@ export declare const PROMPT_TOOL_SUMMARY = "Ask another terminal a question and
  * `from`, and the advertised tool overrides.
  *
  * @remarks
- * - `manager` — the terminal manager whose `ask(from, to, form, options)` the tool's handler
- *   calls; BLOCKS the calling agent turn until the addressed terminal answers (or the ask
+ * - `manager` — the terminal manager whose `ask(from, to, form)` the tool's handler calls with a
+ *   live `@orkestrel/form` form; BLOCKS the calling agent turn until the addressed terminal answers (or the ask
  *   rejects — a cycle throws `TerminalError('DEADLOCK')`, re-surfaced as a typed `DEADLOCK`
  *   {@link import('./errors.js').ToolboxError}; an expired prompt re-surfaces as `EXPIRE`).
  * - `from` — the terminal identity this tool asks AS; the model supplies the `to` target and the
- *   prompt form per call.
+ *   complete form schema per call.
  * - `name` / `description` — advertised tool overrides; default to
  *   {@link import('./constants.js').PROMPT_TOOL_NAME} / {@link import('./constants.js').PROMPT_TOOL_DESCRIPTION}.
  */
@@ -1852,47 +1823,16 @@ export declare interface PromptToolOptions {
 }
 
 /**
- * The shape of {@link import('./factories.js').createPromptTool}'s call arguments — `to` (the
- * terminal identity to address), `form` (which of the six {@link import('@orkestrel/terminal').PromptType}
- * forms to ask), `message`, an optional `timeout` override, and every per-form optional field
- * FLATTENED onto one object (mirrors `workspaceToolShape`'s flat-arm style, but a single shared
- * shape rather than a discriminated union — `form` alone does not vary the REQUIRED fields, only
- * which of the optional ones apply, so a flat shape stays faithful without duplicating `to` /
- * `message` / `timeout` across six near-identical arms).
+ * The shape of {@link import('./factories.js').createPromptTool}'s call arguments — `to` names the
+ * terminal identity and `schema` carries the complete multi-field form document.
  *
  * @remarks
- * `choices` backs `'select'` / `'checkbox'`; `default` backs `'input'` / `'confirm'` / `'select'`
- * (a string for the first two forms' text default, `'true'`/`'false'` string for confirm — the
- * contract layer cannot vary a field's type by a sibling field's value, so `default` stays a
- * string and the handler coerces per form); `mask` backs `'password'`; `min` / `max` backs
- * `'checkbox'`; `validate` (declarative only) backs the four text-shaped forms
- * (`'input'` / `'password'` / `'confirm'` / `'editor'`).
+ * The contract first requires exact JSON. The handler then delegates schema parsing and semantic
+ * validation to `@orkestrel/form`'s `parseForm`, so Toolbox does not duplicate the form schema.
  */
 export declare const promptToolShape: ObjectShape<{
     to: StringShape;
-    form: LiteralShape<readonly ["input", "password", "confirm", "select", "checkbox", "editor"]>;
-    message: StringShape;
-    default: OptionalShape<StringShape>;
-    choices: OptionalShape<ArrayShape<ObjectShape<{
-        name: StringShape;
-        value: StringShape;
-        description: OptionalShape<StringShape>;
-    }, boolean | ContractShape>>>;
-    mask: OptionalShape<StringShape>;
-    min: OptionalShape<NumberShape>;
-    max: OptionalShape<NumberShape>;
-    validate: OptionalShape<ObjectShape<{
-        required: OptionalShape<BooleanShape>;
-        minimum: OptionalShape<NumberShape>;
-        maximum: OptionalShape<NumberShape>;
-        pattern: OptionalShape<StringShape>;
-        email: OptionalShape<BooleanShape>;
-        url: OptionalShape<BooleanShape>;
-        numeric: OptionalShape<BooleanShape>;
-        integer: OptionalShape<BooleanShape>;
-        alphanumeric: OptionalShape<BooleanShape>;
-    }, boolean | ContractShape>>;
-    timeout: OptionalShape<NumberShape>;
+    schema: JSONShape;
 }, false>;
 
 /**
@@ -2160,8 +2100,8 @@ export declare const taskDraftShape: ObjectShape<{
  * value returns `undefined`, telling the caller this mapper does not apply (rethrow / handle
  * otherwise). For a genuine `TerminalError`, `'DEADLOCK'` maps to `'DEADLOCK'`, `'EXPIRE'` maps
  * to `'EXPIRE'`, and every other {@link import('@orkestrel/terminal').TerminalErrorCode}
- * (`'TARGET'`, `'CANCEL'`, `'DRIVER'`) maps to the generic `'TOOL'` code. The mapper only
- * classifies — the factory performs the actual throw.
+ * (`'TARGET'`, `'LIMIT'`, `'CANCEL'`, `'DRIVER'`, `'DESTROYED'`) maps to the generic `'TOOL'`
+ * code. The mapper only classifies — the factory performs the actual throw.
  *
  * @param error - The value caught from a terminal-manager operation (`ask` / `answer` / …)
  * @returns The mapped {@link ToolboxErrorCode}, or `undefined` if `error` is not a `TerminalError`

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

@@ -21,7 +21,6 @@ import { ObjectShape } from '@orkestrel/contract';
 import { OptionalShape } from '@orkestrel/contract';
 import { OrderDirection } from '@orkestrel/database';
 import { PrimaryMap } from '@orkestrel/database';
-import { PromptType } from '@orkestrel/terminal';
 import { QueryInput } from '@orkestrel/database';
 import { RelationErrorCode } from '@orkestrel/relation';
 import { RelationManagerInterface } from '@orkestrel/relation';
@@ -214,7 +213,7 @@ export declare const ANSWER_TOOL_NAME = "answer";
  * for the full teaching description; the full text stays retrievable via
  * {@link import('./factories.js').createDescribeTool}.
  */
-export declare const ANSWER_TOOL_SUMMARY = "List prompts addressed to this terminal, or answer one by id. Call describe('answer') for the required fields.";
+export declare const ANSWER_TOOL_SUMMARY = "List forms addressed to this terminal, or answer one by id with a values record. Call describe('answer') for the required fields.";
 
 /**
  * Options for {@link import('./factories.js').createAnswerTool} — the live
@@ -222,9 +221,9 @@ export declare const ANSWER_TOOL_SUMMARY = "List prompts addressed to this termi
  * terminal name `to`, and the advertised tool overrides.
  *
  * @remarks
- * - `manager` — the terminal manager whose `pending(to)` / `answer(to, id, value)` the tool's
- *   handler calls — `pending` lists the prompts currently addressed to `to`, `answer` resolves
- *   one by `id`. A failed `answer` (`TerminalAnswerResult.error`) re-surfaces as a typed
+ * - `manager` — the terminal manager whose `pending(to)` / `answer(to, id, values)` the tool's
+ *   handler calls — `pending` lists the forms currently addressed to `to`, `answer` resolves
+ *   one by `id`. A failed `answer` (`TerminalAnswerError`) re-surfaces as a typed
  *   `ANSWER` {@link import('./errors.js').ToolboxError}.
  * - `to` — the terminal identity this tool lists / answers prompts FOR.
  * - `name` / `description` — advertised tool overrides; default to
@@ -239,22 +238,19 @@ export declare interface AnswerToolOptions {
 
 /**
  * The shape of {@link import('./factories.js').createAnswerTool}'s call arguments — discriminated
- * by `operation`: `'pending'` lists the prompts addressed to this tool's terminal, `'answer'`
- * resolves one by `id` with a `value`.
+ * by `operation`: `'pending'` lists the forms addressed to this tool's terminal, while `'answer'`
+ * resolves one by `id` with a complete `values` record.
  *
  * @remarks
- * `value`'s type varies by the ORIGINAL prompt's form (`string` for `'input'` / `'password'` /
- * `'select'` / `'editor'`, `boolean` for `'confirm'`, `readonly string[]` for `'checkbox'`) —
- * `unionShape(stringShape(), booleanShape(), arrayShape(stringShape()))` expresses that
- * union directly, so `value` is typed as the full `string | boolean | readonly string[]` union
- * here (no lossy string-only fallback needed).
+ * `values` is first bounded to exact JSON. The handler then narrows it with the originating Form
+ * package's `isFormValues` guard before the terminal manager applies it to the parked live form.
  */
 export declare const answerToolShape: UnionShape<readonly [ ObjectShape<{
     operation: LiteralShape<readonly ["pending"]>;
 }, false>, ObjectShape<{
     operation: LiteralShape<readonly ["answer"]>;
     id: StringShape;
-    value: UnionShape<readonly [ StringShape, BooleanShape, ArrayShape<StringShape>]>;
+    values: JSONShape;
 }, false>]>;
 
 /**
@@ -288,28 +284,6 @@ export declare function clampQuery(query: QueryInput | undefined, cap: number):
     limit: number;
 }>;
 
-/**
- * Normalize an LLM-supplied answer `value` to the type {@link PromptType} `form` expects, so a
- * caller that only ever emits strings can still answer a typed prompt.
- *
- * @remarks
- * `'confirm'` coerces to a `boolean` — a `boolean` passes through, and the strings `'true'` /
- * `'false'` (case-insensitively) map to it; any other string is truthy-coerced via
- * `Boolean(value)`. `'checkbox'` coerces to `readonly string[]` — an array passes through
- * (stringifying each entry), a comma-separated string splits + trims into one, and any other
- * single (non-comma) string becomes a one-item array. Every other form (`'input'` / `'password'`
- * / `'select'` / `'editor'`) coerces to a plain `string` — a string passes through verbatim; a
- * non-string, non-object scalar (`number` / `boolean`) stringifies via `String(value)`; an
- * object or array (no lossless string form) falls back to `''` rather than serializing garbage.
- * Pure and total — never throws.
- *
- * @param form - The {@link PromptType} the answer is being coerced FOR
- * @param value - The raw, LLM-supplied answer value
- * @returns The coerced answer — `boolean` for `'confirm'`, `readonly string[]` for `'checkbox'`,
- *   `string` otherwise
- */
-export declare function coerceAnswer(form: PromptType, value: unknown): string | boolean | readonly string[];
-
 /** One column's declared type — a primitive shorthand, or `integer` for a whole-number `number`. */
 export declare type ColumnKind = 'string' | 'integer' | 'number' | 'boolean';
 
@@ -464,24 +438,22 @@ export declare function createAgentFunction(agent: AgentInterface, options?: Age
 export declare function createAgentTool(registry: AgentRegistryInterface, options?: AgentToolOptions): ToolInterface;
 
 /**
- * Build an LLM-callable answer tool — the ANSWER side of the terminal seam. Lists the prompts
+ * Build an LLM-callable answer tool — the ANSWER side of the terminal seam. Lists the forms
  * currently addressed to {@link import('./types.js').AnswerToolOptions.to}, or answers one of
  * them by id.
  *
  * @remarks
  * The universal tool-handler contract (AGENTS §14): validates the call args against
  * {@link import('./shapers.js').answerToolShape} (discriminated by `operation`). `'pending'`
- * returns a compact list (`{ id, from, form, message }`) of every prompt currently addressed to
- * `to` (`TerminalManagerInterface.pending`, `@orkestrel/terminal`). `'answer'` looks the prompt
- * up by `id` (an unknown id throws a typed `ANSWER` {@link import('./errors.js').ToolboxError}),
- * normalizes the model-supplied `value` to the prompt's own form
- * ({@link import('./helpers.js').coerceAnswer}), and applies it via
+ * returns a compact list (`{ id, from, schema }`) of every form currently addressed to `to`.
+ * `'answer'` looks the form up by `id`, narrows the supplied `values` through `@orkestrel/form`,
+ * and applies it via
  * `TerminalManagerInterface.answer` — a rejected / unknown / unresolvable outcome
  * (`TerminalAnswerResult.error`) re-surfaces as a typed `ANSWER` `ToolboxError`; success returns
  * `{ answered: id }`. `to` is FIXED at construction
  * ({@link import('./types.js').AnswerToolOptions.to}) — never read from the model-supplied args —
  * so a model cannot spoof which terminal it is answering for. Concurrent answerers racing on one
- * endpoint are FIRST-WRITE-WINS — a late answer to an already-settled prompt returns a typed
+ * endpoint are FIRST-WRITE-WINS — a late answer to an already-settled form returns a typed
  * `ANSWER` `ToolboxError` (surfaced as a 422 over HTTP).
  *
  * @param options - The live manager, the fixed `to` identity, and advertised overrides (see
@@ -498,7 +470,7 @@ export declare function createAgentTool(registry: AgentRegistryInterface, option
  * manager.add('reviewer')
  * const tool = createAnswerTool({ manager, to: 'reviewer' })
  * const tools = createToolManager()
- * tools.add(tool) // the reviewer terminal can now list/answer prompts addressed to it
+ * tools.add(tool) // the reviewer terminal can now list/answer forms addressed to it
  * ```
  */
 export declare function createAnswerTool(options: AnswerToolOptions): ToolInterface;
@@ -782,19 +754,18 @@ export declare function createInferTool(options?: InferToolOptions): ToolInterfa
 export declare function createMemoryDefinitionStore(): DefinitionStoreInterface;
 
 /**
- * Build an LLM-callable prompt tool — the ASK side of the terminal seam. Asks
- * {@link import('./types.js').PromptToolOptions.to} a question and BLOCKS until it answers,
- * returning the resolved answer value.
+ * Build an LLM-callable form tool — the ASK side of the terminal seam. Asks
+ * a multi-field form and BLOCKS until it answers, returning the resolved values record.
  *
  * @remarks
  * The universal tool-handler contract (AGENTS §14): validates the call args against
- * {@link import('./shapers.js').promptToolShape}, dispatches to the matching
- * `TerminalManagerInterface.ask` overload (`@orkestrel/terminal`) for the call's `form`, and
- * RETURNS the resolved answer on success. `from` is FIXED at construction
+ * {@link import('./shapers.js').promptToolShape}, parses the call's schema through
+ * `@orkestrel/form`, constructs the live form, and passes it to `TerminalManagerInterface.ask`.
+ * `from` is FIXED at construction
  * ({@link import('./types.js').PromptToolOptions.from}) — never read from the model-supplied
- * args — so a model cannot spoof which terminal is asking. A prompt CYCLE rejects with
+ * args — so a model cannot spoof which terminal is asking. A form CYCLE rejects with
  * `TerminalError('DEADLOCK')`, re-surfaced as a typed `DEADLOCK`
- * {@link import('./errors.js').ToolboxError}; an expired prompt re-surfaces as `EXPIRE`; an
+ * {@link import('./errors.js').ToolboxError}; an expired form re-surfaces as `EXPIRE`; an
  * unknown `to` (or any other `TerminalError`) re-surfaces as `TOOL`, naming the unknown terminal
  * plus the known ones (`manager.terminals()`).
  *
@@ -1811,7 +1782,7 @@ export declare const phaseDraftShape: ObjectShape<{
     bail: OptionalShape<LiteralShape<readonly [true, false]>>;
 }, false>;
 
-/** The full prompt protocol {@link import('./factories.js').createPromptTool} advertises. */
+/** The full form protocol {@link import('./factories.js').createPromptTool} advertises. */
 export declare const PROMPT_TOOL_DESCRIPTION: string;
 
 /**
@@ -1827,7 +1798,7 @@ export declare const PROMPT_TOOL_NAME = "ask";
  * for the full teaching description; the full text stays retrievable via
  * {@link import('./factories.js').createDescribeTool}.
  */
-export declare const PROMPT_TOOL_SUMMARY = "Ask another terminal a question and BLOCK until it answers; the call resolves with the answered value. Call describe('ask') for the required fields.";
+export declare const PROMPT_TOOL_SUMMARY = "Ask another terminal a multi-field form and BLOCK until it answers; the call resolves with the values record. Call describe('ask') for the schema.";
 
 /**
  * Options for {@link import('./factories.js').createPromptTool} — the live
@@ -1835,12 +1806,12 @@ export declare const PROMPT_TOOL_SUMMARY = "Ask another terminal a question and
  * `from`, and the advertised tool overrides.
  *
  * @remarks
- * - `manager` — the terminal manager whose `ask(from, to, form, options)` the tool's handler
- *   calls; BLOCKS the calling agent turn until the addressed terminal answers (or the ask
+ * - `manager` — the terminal manager whose `ask(from, to, form)` the tool's handler calls with a
+ *   live `@orkestrel/form` form; BLOCKS the calling agent turn until the addressed terminal answers (or the ask
  *   rejects — a cycle throws `TerminalError('DEADLOCK')`, re-surfaced as a typed `DEADLOCK`
  *   {@link import('./errors.js').ToolboxError}; an expired prompt re-surfaces as `EXPIRE`).
  * - `from` — the terminal identity this tool asks AS; the model supplies the `to` target and the
- *   prompt form per call.
+ *   complete form schema per call.
  * - `name` / `description` — advertised tool overrides; default to
  *   {@link import('./constants.js').PROMPT_TOOL_NAME} / {@link import('./constants.js').PROMPT_TOOL_DESCRIPTION}.
  */
@@ -1852,47 +1823,16 @@ export declare interface PromptToolOptions {
 }
 
 /**
- * The shape of {@link import('./factories.js').createPromptTool}'s call arguments — `to` (the
- * terminal identity to address), `form` (which of the six {@link import('@orkestrel/terminal').PromptType}
- * forms to ask), `message`, an optional `timeout` override, and every per-form optional field
- * FLATTENED onto one object (mirrors `workspaceToolShape`'s flat-arm style, but a single shared
- * shape rather than a discriminated union — `form` alone does not vary the REQUIRED fields, only
- * which of the optional ones apply, so a flat shape stays faithful without duplicating `to` /
- * `message` / `timeout` across six near-identical arms).
+ * The shape of {@link import('./factories.js').createPromptTool}'s call arguments — `to` names the
+ * terminal identity and `schema` carries the complete multi-field form document.
  *
  * @remarks
- * `choices` backs `'select'` / `'checkbox'`; `default` backs `'input'` / `'confirm'` / `'select'`
- * (a string for the first two forms' text default, `'true'`/`'false'` string for confirm — the
- * contract layer cannot vary a field's type by a sibling field's value, so `default` stays a
- * string and the handler coerces per form); `mask` backs `'password'`; `min` / `max` backs
- * `'checkbox'`; `validate` (declarative only) backs the four text-shaped forms
- * (`'input'` / `'password'` / `'confirm'` / `'editor'`).
+ * The contract first requires exact JSON. The handler then delegates schema parsing and semantic
+ * validation to `@orkestrel/form`'s `parseForm`, so Toolbox does not duplicate the form schema.
  */
 export declare const promptToolShape: ObjectShape<{
     to: StringShape;
-    form: LiteralShape<readonly ["input", "password", "confirm", "select", "checkbox", "editor"]>;
-    message: StringShape;
-    default: OptionalShape<StringShape>;
-    choices: OptionalShape<ArrayShape<ObjectShape<{
-        name: StringShape;
-        value: StringShape;
-        description: OptionalShape<StringShape>;
-    }, boolean | ContractShape>>>;
-    mask: OptionalShape<StringShape>;
-    min: OptionalShape<NumberShape>;
-    max: OptionalShape<NumberShape>;
-    validate: OptionalShape<ObjectShape<{
-        required: OptionalShape<BooleanShape>;
-        minimum: OptionalShape<NumberShape>;
-        maximum: OptionalShape<NumberShape>;
-        pattern: OptionalShape<StringShape>;
-        email: OptionalShape<BooleanShape>;
-        url: OptionalShape<BooleanShape>;
-        numeric: OptionalShape<BooleanShape>;
-        integer: OptionalShape<BooleanShape>;
-        alphanumeric: OptionalShape<BooleanShape>;
-    }, boolean | ContractShape>>;
-    timeout: OptionalShape<NumberShape>;
+    schema: JSONShape;
 }, false>;
 
 /**
@@ -2160,8 +2100,8 @@ export declare const taskDraftShape: ObjectShape<{
  * value returns `undefined`, telling the caller this mapper does not apply (rethrow / handle
  * otherwise). For a genuine `TerminalError`, `'DEADLOCK'` maps to `'DEADLOCK'`, `'EXPIRE'` maps
  * to `'EXPIRE'`, and every other {@link import('@orkestrel/terminal').TerminalErrorCode}
- * (`'TARGET'`, `'CANCEL'`, `'DRIVER'`) maps to the generic `'TOOL'` code. The mapper only
- * classifies — the factory performs the actual throw.
+ * (`'TARGET'`, `'LIMIT'`, `'CANCEL'`, `'DRIVER'`, `'DESTROYED'`) maps to the generic `'TOOL'`
+ * code. The mapper only classifies — the factory performs the actual throw.
  *
  * @param error - The value caught from a terminal-manager operation (`ask` / `answer` / …)
  * @returns The mapped {@link ToolboxErrorCode}, or `undefined` if `error` is not a `TerminalError`