@orkestrel/tool 0.0.1 → 0.0.2

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

@@ -8,7 +8,9 @@ import { LiteralShape } from '@orkestrel/contract';
 import { NumberShape } from '@orkestrel/contract';
 import { ObjectShape } from '@orkestrel/contract';
 import { OptionalShape } from '@orkestrel/contract';
+import { PromptType } from '@orkestrel/terminal';
 import { StringShape } from '@orkestrel/contract';
+import { TerminalManagerInterface } from '@orkestrel/terminal';
 import { ToolInterface } from '@orkestrel/agent';
 import { ToolManagerInterface } from '@orkestrel/agent';
 import { UnionShape } from '@orkestrel/contract';
@@ -112,8 +114,11 @@ export declare interface AgentToolArguments {
 /**
  * Thrown by {@link import('./factories.js').createAgentTool}'s and
  * {@link import('./factories.js').createDescribeTool}'s handlers on every failure path — a
- * malformed / unresolvable call or an unknown tool name (`TOOL`), or a delegation that would
- * exceed the configured depth bound or re-enter an ancestor (`DEPTH`).
+ * malformed / unresolvable call or an unknown tool name (`TOOL`), a delegation that would
+ * exceed the configured depth bound or re-enter an ancestor (`DEPTH`), a prompt cycle
+ * (`DEADLOCK`), a prompt that expired before it was answered (`EXPIRE`), or an answer that
+ * failed to apply (`ANSWER`) — the last three thrown by
+ * {@link import('./factories.js').createPromptTool} / {@link import('./factories.js').createAnswerTool}.
  *
  * @remarks
  * Carries a machine-readable `code` (see {@link import('./types.js').AgentToolErrorCode}) and
@@ -148,8 +153,15 @@ export declare class AgentToolError extends Error {
  * `TOOL` — malformed / unresolvable call args (a missing `task`, no resolvable `provider`).
  * `DEPTH` — the delegation would exceed {@link import('./constants.js').AGENT_TOOL_DEPTH}, or
  * the resolved agent is already an ancestor (a cycle).
+ * `DEADLOCK` — an `ask` call ({@link import('./factories.js').createPromptTool}) would form a
+ * prompt cycle (`TerminalManagerInterface.ask`, `@orkestrel/terminal`, rejects with its own
+ * `TerminalError('DEADLOCK')`, re-surfaced here).
+ * `EXPIRE` — the addressed prompt expired before it was answered.
+ * `ANSWER` — {@link import('./factories.js').createAnswerTool}'s answer call failed to apply
+ * (an unknown prompt id, a rejected value, or the terminal itself unknown —
+ * `TerminalAnswerResult.error`, `@orkestrel/terminal`).
  */
-export declare type AgentToolErrorCode = 'TOOL' | 'DEPTH';
+export declare type AgentToolErrorCode = 'TOOL' | 'DEPTH' | 'DEADLOCK' | 'EXPIRE' | 'ANSWER';
 
 /**
  * Options for {@link import('./factories.js').createAgentTool} — the sub-agent delegation
@@ -209,6 +221,86 @@ export declare const agentToolShape: ObjectShape<{
     system: OptionalShape<StringShape>;
 }>;
 
+export declare const ANSWER_TOOL_DESCRIPTION: string;
+
+/**
+ * The name {@link import('./factories.js').createAnswerTool} advertises by default — the key a
+ * model calls and the `ToolManagerInterface` (`@orkestrel/agent`) registers under.
+ */
+export declare const ANSWER_TOOL_NAME = "answer";
+
+/**
+ * The lean {@link import('@orkestrel/agent').ToolInterface.summary} {@link import('./factories.js').createAnswerTool}
+ * advertises in place of {@link ANSWER_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 ANSWER_TOOL_SUMMARY = "List prompts addressed to this terminal, or answer one by id. Call describe('answer') for the required fields.";
+
+/**
+ * Options for {@link import('./factories.js').createAnswerTool} — the live
+ * {@link TerminalManagerInterface} (`@orkestrel/terminal`) to list / answer prompts through, the
+ * 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
+ *   `ANSWER` {@link import('./errors.js').AgentToolError}.
+ * - `to` — the terminal identity this tool lists / answers prompts FOR.
+ * - `name` / `description` — advertised tool overrides; default to
+ *   {@link import('./constants.js').ANSWER_TOOL_NAME} / {@link import('./constants.js').ANSWER_TOOL_DESCRIPTION}.
+ */
+export declare interface AnswerToolOptions {
+    readonly manager: TerminalManagerInterface;
+    readonly to: string;
+    readonly name?: string;
+    readonly description?: string;
+}
+
+/**
+ * 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`.
+ *
+ * @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).
+ */
+export declare const answerToolShape: UnionShape<[ ObjectShape<{
+    operation: LiteralShape<readonly ["pending"]>;
+}>, ObjectShape<{
+    operation: LiteralShape<readonly ["answer"]>;
+    id: StringShape;
+    value: UnionShape<[ StringShape, BooleanShape, ArrayShape<StringShape>]>;
+}>]>;
+
+/**
+ * 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[];
+
 /**
  * Complete a {@link WorkflowDraft} into a strict {@link WorkflowDefinition} — synthesize any
  * MISSING `id` deterministically + positionally, and default any MISSING `name` to its
@@ -334,6 +426,45 @@ 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
+ * 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').AgentToolError}),
+ * normalizes the model-supplied `value` to the prompt's own form
+ * ({@link import('./helpers.js').coerceAnswer}), and applies it via
+ * `TerminalManagerInterface.answer` — a rejected / unknown / unresolvable outcome
+ * (`TerminalAnswerResult.error`) re-surfaces as a typed `ANSWER` `AgentToolError`; 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
+ * `ANSWER` `AgentToolError` (surfaced as a 422 over HTTP).
+ *
+ * @param options - The live manager, the fixed `to` identity, and advertised overrides (see
+ *   {@link import('./types.js').AnswerToolOptions})
+ * @returns A `ToolInterface` (named {@link import('./constants.js').ANSWER_TOOL_NAME} by default)
+ *
+ * @example
+ * ```ts
+ * import { createAnswerTool } from '@src/core'
+ * import { createTerminalManager, createToolManager } from '@orkestrel/terminal'
+ *
+ * const manager = createTerminalManager()
+ * 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
+ * ```
+ */
+export declare function createAnswerTool(options: AnswerToolOptions): ToolInterface;
+
 /**
  * Build an LLM-callable tool that returns the FULL `description` of another registered tool by
  * name — the counterpart to the lean `summary` the other tools in this package advertise
@@ -370,6 +501,42 @@ export declare function createAgentTool(registry: AgentRegistryInterface, option
  */
 export declare function createDescribeTool(tools: ToolManagerInterface): ToolInterface;
 
+/**
+ * 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.
+ *
+ * @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('./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
+ * `TerminalError('DEADLOCK')`, re-surfaced as a typed `DEADLOCK`
+ * {@link import('./errors.js').AgentToolError}; an expired prompt 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()`).
+ *
+ * @param options - The live manager, the fixed `from` identity, and advertised overrides (see
+ *   {@link import('./types.js').PromptToolOptions})
+ * @returns A `ToolInterface` (named {@link import('./constants.js').PROMPT_TOOL_NAME} by default)
+ *
+ * @example
+ * ```ts
+ * import { createPromptTool } from '@src/core'
+ * import { createTerminalManager, createToolManager } from '@orkestrel/terminal'
+ *
+ * const manager = createTerminalManager()
+ * manager.add('agent')
+ * manager.add('reviewer')
+ * const tool = createPromptTool({ manager, from: 'agent' })
+ * const tools = createToolManager()
+ * tools.add(tool) // the agent can now ask 'reviewer' and block for the answer
+ * ```
+ */
+export declare function createPromptTool(options: PromptToolOptions): ToolInterface;
+
 /**
  * Wrap a registered tool as a {@link WorkflowFunction} (`@orkestrel/workflow`) — the OPT-IN
  * adapter that lets a `function`-form task run a `@orkestrel/agent` tool BY NAME.
@@ -680,6 +847,89 @@ export declare const phaseDraftShape: ObjectShape<{
     bail: OptionalShape<LiteralShape<readonly [true, false]>>;
 }>;
 
+export declare const PROMPT_TOOL_DESCRIPTION: string;
+
+/**
+ * The name {@link import('./factories.js').createPromptTool} advertises by default — the key a
+ * model calls and the `ToolManagerInterface` (`@orkestrel/agent`) registers under.
+ */
+export declare const PROMPT_TOOL_NAME = "ask";
+
+/**
+ * The lean {@link import('@orkestrel/agent').ToolInterface.summary} {@link import('./factories.js').createPromptTool}
+ * advertises in place of {@link PROMPT_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 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.";
+
+/**
+ * Options for {@link import('./factories.js').createPromptTool} — the live
+ * {@link TerminalManagerInterface} (`@orkestrel/terminal`) to `ask` through, the terminal name
+ * `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
+ *   rejects — a cycle throws `TerminalError('DEADLOCK')`, re-surfaced as a typed `DEADLOCK`
+ *   {@link import('./errors.js').AgentToolError}; 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.
+ * - `name` / `description` — advertised tool overrides; default to
+ *   {@link import('./constants.js').PROMPT_TOOL_NAME} / {@link import('./constants.js').PROMPT_TOOL_DESCRIPTION}.
+ */
+export declare interface PromptToolOptions {
+    readonly manager: TerminalManagerInterface;
+    readonly from: string;
+    readonly name?: string;
+    readonly description?: string;
+}
+
+/**
+ * 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).
+ *
+ * @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'`).
+ */
+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>;
+    }>>>;
+    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>;
+    }>>;
+    timeout: OptionalShape<NumberShape>;
+}>;
+
 /**
  * The shape of ONE flat step — `{ name }` — the building block of {@link workflowStepsShape}.
  *
@@ -724,6 +974,23 @@ export declare const taskDraftShape: ObjectShape<{
     timeout: OptionalShape<NumberShape>;
 }>;
 
+/**
+ * Map a caught error to the {@link AgentToolErrorCode} the terminal-tool factory should throw
+ * with — the pure classification step of that factory's error handling.
+ *
+ * @remarks
+ * Narrows `error` with {@link isTerminalError} (`@orkestrel/terminal`) first: a non-`TerminalError`
+ * 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.
+ *
+ * @param error - The value caught from a terminal-manager operation (`ask` / `answer` / …)
+ * @returns The mapped {@link AgentToolErrorCode}, or `undefined` if `error` is not a `TerminalError`
+ */
+export declare function terminalToolCode(error: unknown): AgentToolErrorCode | undefined;
+
 export declare const WORKFLOW_TOOL_DESCRIPTION: string;
 
 /**

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

@@ -8,7 +8,9 @@ import { LiteralShape } from '@orkestrel/contract';
 import { NumberShape } from '@orkestrel/contract';
 import { ObjectShape } from '@orkestrel/contract';
 import { OptionalShape } from '@orkestrel/contract';
+import { PromptType } from '@orkestrel/terminal';
 import { StringShape } from '@orkestrel/contract';
+import { TerminalManagerInterface } from '@orkestrel/terminal';
 import { ToolInterface } from '@orkestrel/agent';
 import { ToolManagerInterface } from '@orkestrel/agent';
 import { UnionShape } from '@orkestrel/contract';
@@ -112,8 +114,11 @@ export declare interface AgentToolArguments {
 /**
  * Thrown by {@link import('./factories.js').createAgentTool}'s and
  * {@link import('./factories.js').createDescribeTool}'s handlers on every failure path — a
- * malformed / unresolvable call or an unknown tool name (`TOOL`), or a delegation that would
- * exceed the configured depth bound or re-enter an ancestor (`DEPTH`).
+ * malformed / unresolvable call or an unknown tool name (`TOOL`), a delegation that would
+ * exceed the configured depth bound or re-enter an ancestor (`DEPTH`), a prompt cycle
+ * (`DEADLOCK`), a prompt that expired before it was answered (`EXPIRE`), or an answer that
+ * failed to apply (`ANSWER`) — the last three thrown by
+ * {@link import('./factories.js').createPromptTool} / {@link import('./factories.js').createAnswerTool}.
  *
  * @remarks
  * Carries a machine-readable `code` (see {@link import('./types.js').AgentToolErrorCode}) and
@@ -148,8 +153,15 @@ export declare class AgentToolError extends Error {
  * `TOOL` — malformed / unresolvable call args (a missing `task`, no resolvable `provider`).
  * `DEPTH` — the delegation would exceed {@link import('./constants.js').AGENT_TOOL_DEPTH}, or
  * the resolved agent is already an ancestor (a cycle).
+ * `DEADLOCK` — an `ask` call ({@link import('./factories.js').createPromptTool}) would form a
+ * prompt cycle (`TerminalManagerInterface.ask`, `@orkestrel/terminal`, rejects with its own
+ * `TerminalError('DEADLOCK')`, re-surfaced here).
+ * `EXPIRE` — the addressed prompt expired before it was answered.
+ * `ANSWER` — {@link import('./factories.js').createAnswerTool}'s answer call failed to apply
+ * (an unknown prompt id, a rejected value, or the terminal itself unknown —
+ * `TerminalAnswerResult.error`, `@orkestrel/terminal`).
  */
-export declare type AgentToolErrorCode = 'TOOL' | 'DEPTH';
+export declare type AgentToolErrorCode = 'TOOL' | 'DEPTH' | 'DEADLOCK' | 'EXPIRE' | 'ANSWER';
 
 /**
  * Options for {@link import('./factories.js').createAgentTool} — the sub-agent delegation
@@ -209,6 +221,86 @@ export declare const agentToolShape: ObjectShape<{
     system: OptionalShape<StringShape>;
 }>;
 
+export declare const ANSWER_TOOL_DESCRIPTION: string;
+
+/**
+ * The name {@link import('./factories.js').createAnswerTool} advertises by default — the key a
+ * model calls and the `ToolManagerInterface` (`@orkestrel/agent`) registers under.
+ */
+export declare const ANSWER_TOOL_NAME = "answer";
+
+/**
+ * The lean {@link import('@orkestrel/agent').ToolInterface.summary} {@link import('./factories.js').createAnswerTool}
+ * advertises in place of {@link ANSWER_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 ANSWER_TOOL_SUMMARY = "List prompts addressed to this terminal, or answer one by id. Call describe('answer') for the required fields.";
+
+/**
+ * Options for {@link import('./factories.js').createAnswerTool} — the live
+ * {@link TerminalManagerInterface} (`@orkestrel/terminal`) to list / answer prompts through, the
+ * 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
+ *   `ANSWER` {@link import('./errors.js').AgentToolError}.
+ * - `to` — the terminal identity this tool lists / answers prompts FOR.
+ * - `name` / `description` — advertised tool overrides; default to
+ *   {@link import('./constants.js').ANSWER_TOOL_NAME} / {@link import('./constants.js').ANSWER_TOOL_DESCRIPTION}.
+ */
+export declare interface AnswerToolOptions {
+    readonly manager: TerminalManagerInterface;
+    readonly to: string;
+    readonly name?: string;
+    readonly description?: string;
+}
+
+/**
+ * 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`.
+ *
+ * @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).
+ */
+export declare const answerToolShape: UnionShape<[ ObjectShape<{
+    operation: LiteralShape<readonly ["pending"]>;
+}>, ObjectShape<{
+    operation: LiteralShape<readonly ["answer"]>;
+    id: StringShape;
+    value: UnionShape<[ StringShape, BooleanShape, ArrayShape<StringShape>]>;
+}>]>;
+
+/**
+ * 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[];
+
 /**
  * Complete a {@link WorkflowDraft} into a strict {@link WorkflowDefinition} — synthesize any
  * MISSING `id` deterministically + positionally, and default any MISSING `name` to its
@@ -334,6 +426,45 @@ 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
+ * 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').AgentToolError}),
+ * normalizes the model-supplied `value` to the prompt's own form
+ * ({@link import('./helpers.js').coerceAnswer}), and applies it via
+ * `TerminalManagerInterface.answer` — a rejected / unknown / unresolvable outcome
+ * (`TerminalAnswerResult.error`) re-surfaces as a typed `ANSWER` `AgentToolError`; 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
+ * `ANSWER` `AgentToolError` (surfaced as a 422 over HTTP).
+ *
+ * @param options - The live manager, the fixed `to` identity, and advertised overrides (see
+ *   {@link import('./types.js').AnswerToolOptions})
+ * @returns A `ToolInterface` (named {@link import('./constants.js').ANSWER_TOOL_NAME} by default)
+ *
+ * @example
+ * ```ts
+ * import { createAnswerTool } from '@src/core'
+ * import { createTerminalManager, createToolManager } from '@orkestrel/terminal'
+ *
+ * const manager = createTerminalManager()
+ * 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
+ * ```
+ */
+export declare function createAnswerTool(options: AnswerToolOptions): ToolInterface;
+
 /**
  * Build an LLM-callable tool that returns the FULL `description` of another registered tool by
  * name — the counterpart to the lean `summary` the other tools in this package advertise
@@ -370,6 +501,42 @@ export declare function createAgentTool(registry: AgentRegistryInterface, option
  */
 export declare function createDescribeTool(tools: ToolManagerInterface): ToolInterface;
 
+/**
+ * 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.
+ *
+ * @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('./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
+ * `TerminalError('DEADLOCK')`, re-surfaced as a typed `DEADLOCK`
+ * {@link import('./errors.js').AgentToolError}; an expired prompt 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()`).
+ *
+ * @param options - The live manager, the fixed `from` identity, and advertised overrides (see
+ *   {@link import('./types.js').PromptToolOptions})
+ * @returns A `ToolInterface` (named {@link import('./constants.js').PROMPT_TOOL_NAME} by default)
+ *
+ * @example
+ * ```ts
+ * import { createPromptTool } from '@src/core'
+ * import { createTerminalManager, createToolManager } from '@orkestrel/terminal'
+ *
+ * const manager = createTerminalManager()
+ * manager.add('agent')
+ * manager.add('reviewer')
+ * const tool = createPromptTool({ manager, from: 'agent' })
+ * const tools = createToolManager()
+ * tools.add(tool) // the agent can now ask 'reviewer' and block for the answer
+ * ```
+ */
+export declare function createPromptTool(options: PromptToolOptions): ToolInterface;
+
 /**
  * Wrap a registered tool as a {@link WorkflowFunction} (`@orkestrel/workflow`) — the OPT-IN
  * adapter that lets a `function`-form task run a `@orkestrel/agent` tool BY NAME.
@@ -680,6 +847,89 @@ export declare const phaseDraftShape: ObjectShape<{
     bail: OptionalShape<LiteralShape<readonly [true, false]>>;
 }>;
 
+export declare const PROMPT_TOOL_DESCRIPTION: string;
+
+/**
+ * The name {@link import('./factories.js').createPromptTool} advertises by default — the key a
+ * model calls and the `ToolManagerInterface` (`@orkestrel/agent`) registers under.
+ */
+export declare const PROMPT_TOOL_NAME = "ask";
+
+/**
+ * The lean {@link import('@orkestrel/agent').ToolInterface.summary} {@link import('./factories.js').createPromptTool}
+ * advertises in place of {@link PROMPT_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 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.";
+
+/**
+ * Options for {@link import('./factories.js').createPromptTool} — the live
+ * {@link TerminalManagerInterface} (`@orkestrel/terminal`) to `ask` through, the terminal name
+ * `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
+ *   rejects — a cycle throws `TerminalError('DEADLOCK')`, re-surfaced as a typed `DEADLOCK`
+ *   {@link import('./errors.js').AgentToolError}; 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.
+ * - `name` / `description` — advertised tool overrides; default to
+ *   {@link import('./constants.js').PROMPT_TOOL_NAME} / {@link import('./constants.js').PROMPT_TOOL_DESCRIPTION}.
+ */
+export declare interface PromptToolOptions {
+    readonly manager: TerminalManagerInterface;
+    readonly from: string;
+    readonly name?: string;
+    readonly description?: string;
+}
+
+/**
+ * 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).
+ *
+ * @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'`).
+ */
+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>;
+    }>>>;
+    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>;
+    }>>;
+    timeout: OptionalShape<NumberShape>;
+}>;
+
 /**
  * The shape of ONE flat step — `{ name }` — the building block of {@link workflowStepsShape}.
  *
@@ -724,6 +974,23 @@ export declare const taskDraftShape: ObjectShape<{
     timeout: OptionalShape<NumberShape>;
 }>;
 
+/**
+ * Map a caught error to the {@link AgentToolErrorCode} the terminal-tool factory should throw
+ * with — the pure classification step of that factory's error handling.
+ *
+ * @remarks
+ * Narrows `error` with {@link isTerminalError} (`@orkestrel/terminal`) first: a non-`TerminalError`
+ * 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.
+ *
+ * @param error - The value caught from a terminal-manager operation (`ask` / `answer` / …)
+ * @returns The mapped {@link AgentToolErrorCode}, or `undefined` if `error` is not a `TerminalError`
+ */
+export declare function terminalToolCode(error: unknown): AgentToolErrorCode | undefined;
+
 export declare const WORKFLOW_TOOL_DESCRIPTION: string;
 
 /**