@orkestrel/toolbox 0.0.5 → 0.0.7

package/dist/src/core/index.js

@@ -6,6 +6,7 @@ import { isRelationError } from "@orkestrel/relation";
 import { agentResultToJSON } from "@orkestrel/agent";
 import { createWorkspaceManager, isText, rangeOf } from "@orkestrel/workspace";
 import { createTool } from "@orkestrel/tool";
+import { createForm, isFormError, isFormValues, parseForm } from "@orkestrel/form";
 //#region src/core/constants.ts
 /**
 * The name {@link import('./factories.js').createAgentTool} advertises by default — the key a
@@ -232,23 +233,30 @@ var PROMPT_TOOL_NAME = "ask";
 * for the full teaching description; the full text stays retrievable via
 * {@link import('./factories.js').createDescribeTool}.
 */
-var 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.";
-/** The full prompt protocol {@link import('./factories.js').createPromptTool} advertises. */
+var 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.";
+/** The full form protocol {@link import('./factories.js').createPromptTool} advertises. */
 var PROMPT_TOOL_DESCRIPTION = [
-	"Ask another terminal a question and block until it answers. This call does not return until the addressed terminal answers, or the prompt fails.",
+	"Ask another terminal a multi-field form and block until it answers. This call does not return until the addressed terminal answers, or the form expires.",
 	"",
 	"Required:",
-	"  to      - the terminal name to ask.",
-	"  form    - the prompt kind: one of \"input\", \"password\", \"confirm\", \"select\", \"checkbox\", \"editor\".",
-	"  message - the question shown to the answering terminal.",
-	"Optional:",
-	"  options - form-specific options (e.g. choices for \"select\"/\"checkbox\").",
-	"A cycle (two terminals asking each other) or an expired prompt fails the call with a typed error.",
+	"  to     - the terminal name to ask.",
+	"  schema - an @orkestrel/form schema: each field declares `control` and `name`, plus optional `label`, `rule`, `default`, and `choices`; `fields` is an ordered array and each `name` must be unique.",
+	"The result is one values object keyed by those field names. A cycle or expired form fails with a typed error.",
 	"Example:",
 	JSON.stringify({
 		to: "reviewer",
-		form: "confirm",
-		message: "Approve the release?"
+		schema: {
+			label: "Release review",
+			fields: [{
+				control: "confirm",
+				name: "approved",
+				label: "Approve the release?"
+			}, {
+				control: "editor",
+				name: "notes",
+				label: "Review notes"
+			}]
+		}
 	})
 ].join("\n");
 /**
@@ -263,21 +271,24 @@ var ANSWER_TOOL_NAME = "answer";
 * for the full teaching description; the full text stays retrievable via
 * {@link import('./factories.js').createDescribeTool}.
 */
-var ANSWER_TOOL_SUMMARY = "List prompts addressed to this terminal, or answer one by id. Call describe('answer') for the required fields.";
+var 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.";
 /** The pending/answer protocol {@link import('./factories.js').createAnswerTool} advertises. */
 var ANSWER_TOOL_DESCRIPTION = [
-	"List the prompts currently addressed to this terminal, or answer one of them by id. Every call is ONE operation, chosen by the \"operation\" field.",
+	"List the forms currently addressed to this terminal, or answer one of them by id. Every call is ONE operation, chosen by the \"operation\" field.",
 	"",
 	"Operations:",
-	"- pending { \"operation\": \"pending\" } — list every prompt currently addressed to this terminal (id, form, message, options, time).",
-	"- answer  { \"operation\": \"answer\", \"id\": \"<prompt id>\", \"value\": <answer value> } — answer the prompt with that id; \"value\" must match the prompt's form (a string for \"input\"/\"password\"/\"editor\", a boolean for \"confirm\", a choice for \"select\", an array of choices for \"checkbox\").",
-	"Example — list pending prompts:",
+	"- pending { \"operation\": \"pending\" } — list every form currently addressed to this terminal (id, from, schema).",
+	"- answer  { \"operation\": \"answer\", \"id\": \"<form id>\", \"values\": { \"<field name>\": <field value> } } — answer every required field with the value its control accepts.",
+	"Example — list pending forms:",
 	JSON.stringify({ operation: "pending" }),
 	"Example — answer one:",
 	JSON.stringify({
 		operation: "answer",
 		id: "abc123",
-		value: true
+		values: {
+			approved: true,
+			notes: "Ready"
+		}
 	})
 ].join("\n");
 /**
@@ -566,104 +577,36 @@ function isToolboxError(value) {
 //#endregion
 //#region src/core/shapers.ts
 /**
-* 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.
 */
 var promptToolShape = objectShape({
 	to: stringShape({
 		min: 1,
-		description: "The terminal identity to address the prompt to."
+		description: "The terminal identity to address the form to."
 	}),
-	form: literalShape([
-		"input",
-		"password",
-		"confirm",
-		"select",
-		"checkbox",
-		"editor"
-	], { description: "Which prompt form to ask." }),
-	message: stringShape({
-		min: 1,
-		description: "The prompt's question."
-	}),
-	default: optionalShape(stringShape({ description: "The default answer if the responder submits blank — 'input' / 'editor' text, 'confirm' 'true'/'false', or a 'select' choice value." })),
-	choices: optionalShape(arrayShape(objectShape({
-		name: stringShape({
-			min: 1,
-			description: "The choice label shown to the answering party."
-		}),
-		value: stringShape({
-			min: 1,
-			description: "The value submitted when this choice is picked."
-		}),
-		description: optionalShape(stringShape({ description: "An optional one-line elaboration." }))
-	}), { description: "The selectable choices for 'select' / 'checkbox'." })),
-	mask: optionalShape(stringShape({
-		min: 1,
-		description: "The mask character 'password' renders in place of input."
-	})),
-	min: optionalShape(integerShape({
-		min: 0,
-		description: "The minimum number of 'checkbox' selections required."
-	})),
-	max: optionalShape(integerShape({
-		min: 0,
-		description: "The maximum number of 'checkbox' selections allowed."
-	})),
-	validate: optionalShape(objectShape({
-		required: optionalShape(booleanShape({ description: "Reject an empty (trimmed) input." })),
-		minimum: optionalShape(integerShape({
-			min: 0,
-			description: "Reject an input shorter than this many characters."
-		})),
-		maximum: optionalShape(integerShape({
-			min: 0,
-			description: "Reject an input longer than this many characters."
-		})),
-		pattern: optionalShape(stringShape({ description: "Reject an input that fails this regular-expression source." })),
-		email: optionalShape(booleanShape({ description: "Require a valid email-address shape." })),
-		url: optionalShape(booleanShape({ description: "Require a valid URL shape." })),
-		numeric: optionalShape(booleanShape({ description: "Require a numeric value." })),
-		integer: optionalShape(booleanShape({ description: "Require an integer value." })),
-		alphanumeric: optionalShape(booleanShape({ description: "Require letters and digits only." }))
-	})),
-	timeout: optionalShape(integerShape({
-		min: 0,
-		description: "Milliseconds to wait before the prompt expires."
-	}))
+	schema: jsonShape({ description: "The @orkestrel/form schema to ask, with form metadata and one or more typed fields." })
 });
 /**
 * 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).
-*/
-var answerToolShape = unionShape(objectShape({ operation: literalShape(["pending"], { description: "List the prompts currently addressed to this terminal." }) }), objectShape({
-	operation: literalShape(["answer"], { description: "Answer one pending prompt by id." }),
+* `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.
+*/
+var answerToolShape = unionShape(objectShape({ operation: literalShape(["pending"], { description: "List the forms currently addressed to this terminal." }) }), objectShape({
+	operation: literalShape(["answer"], { description: "Answer one pending form by id." }),
 	id: stringShape({
 		min: 1,
-		description: "The id of the pending prompt to answer."
+		description: "The id of the pending form to answer."
 	}),
-	value: unionShape(stringShape({ description: "A text / select / editor answer." }), booleanShape({ description: "A confirm answer." }), arrayShape(stringShape(), { description: "A checkbox answer — the checked values." }))
+	values: jsonShape({ description: "The form answers keyed by field name." })
 }));
 /**
 * The shape of {@link import('./types.js').AgentToolArguments} —
@@ -1418,48 +1361,6 @@ function expandSteps(flat) {
 	});
 }
 /**
-* 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
-*/
-function coerceAnswer(form, value) {
-	if (form === "confirm") {
-		if (typeof value === "boolean") return value;
-		if (typeof value === "string") {
-			const lower = value.trim().toLowerCase();
-			if (lower === "true") return true;
-			if (lower === "false") return false;
-		}
-		return Boolean(value);
-	}
-	if (form === "checkbox") {
-		if (Array.isArray(value)) return value.map((entry) => String(entry));
-		if (typeof value === "string") {
-			if (value.includes(",")) return value.split(",").map((entry) => entry.trim());
-			return [value];
-		}
-		return [String(value)];
-	}
-	if (typeof value === "string") return value;
-	if (typeof value === "object" && value !== null) return "";
-	return String(value);
-}
-/**
 * Map a caught error to the {@link ToolboxErrorCode} the terminal-tool factory should throw
 * with — the pure classification step of that factory's error handling.
 *
@@ -1468,8 +1369,8 @@ function coerceAnswer(form, value) {
 * 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`
@@ -2564,19 +2465,18 @@ function createDescribeTool(tools) {
 	});
 }
 /**
-* 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()`).
 *
@@ -2609,51 +2509,23 @@ function createPromptTool(options) {
 		async execute(args) {
 			const call = contract.parse(args);
 			if (call === void 0) throw new ToolboxError("TOOL", "malformed ask call", { args });
-			if ((call.form === "select" || call.form === "checkbox") && (call.choices ?? []).length === 0) throw new ToolboxError("TOOL", "select/checkbox requires at least one choice", {
-				to: call.to,
-				form: call.form
+			const schema = parseForm(call.schema);
+			if (schema === void 0) throw new ToolboxError("TOOL", "malformed form schema", { schema: call.schema });
+			for (const field of schema.fields) if ((field.control === "select" || field.control === "checkbox") && !field.choices.some((choice) => choice.disabled !== true)) throw new ToolboxError("TOOL", `${field.control} field '${field.name}' has no enabled choices`, {
+				control: field.control,
+				field: field.name
 			});
 			try {
-				switch (call.form) {
-					case "input": return await options.manager.ask(options.from, call.to, call.form, {
-						message: call.message,
-						...call.default === void 0 ? {} : { default: call.default },
-						...call.validate === void 0 ? {} : { validate: call.validate }
-					});
-					case "editor": return await options.manager.ask(options.from, call.to, call.form, {
-						message: call.message,
-						...call.default === void 0 ? {} : { default: call.default },
-						...call.validate === void 0 ? {} : { validate: call.validate }
-					});
-					case "password": return await options.manager.ask(options.from, call.to, call.form, {
-						message: call.message,
-						...call.mask === void 0 ? {} : { mask: call.mask },
-						...call.validate === void 0 ? {} : { validate: call.validate }
-					});
-					case "confirm": return await options.manager.ask(options.from, call.to, call.form, {
-						message: call.message,
-						...call.default === void 0 ? {} : { default: call.default === "true" }
-					});
-					case "select": return await options.manager.ask(options.from, call.to, call.form, {
-						message: call.message,
-						choices: call.choices ?? [],
-						...call.default === void 0 ? {} : { default: call.default }
-					});
-					case "checkbox": return await options.manager.ask(options.from, call.to, call.form, {
-						message: call.message,
-						choices: call.choices ?? [],
-						...call.min === void 0 ? {} : { min: call.min },
-						...call.max === void 0 ? {} : { max: call.max }
-					});
-				}
+				return await options.manager.ask(options.from, call.to, createForm(schema));
 			} catch (error) {
+				if (isFormError(error) && error.code === "ABANDONED") throw new ToolboxError("EXPIRE", `form to '${call.to}' expired before it was answered`, { to: call.to });
 				const code = terminalToolCode(error);
 				if (code === void 0) throw error;
-				if (code === "DEADLOCK") throw new ToolboxError("DEADLOCK", `asking '${call.to}' would form a prompt cycle`, isTerminalError(error) ? error.context : {
+				if (code === "DEADLOCK") throw new ToolboxError("DEADLOCK", `asking '${call.to}' would create a form cycle`, isTerminalError(error) ? error.context : {
 					from: options.from,
 					to: call.to
 				});
-				if (code === "EXPIRE") throw new ToolboxError("EXPIRE", `prompt to '${call.to}' expired before it was answered`, { to: call.to });
+				if (code === "EXPIRE") throw new ToolboxError("EXPIRE", `form to '${call.to}' expired before it was answered`, { to: call.to });
 				if (isTerminalError(error) && error.code === "TARGET") throw new ToolboxError("TOOL", `unknown terminal '${call.to}'`, {
 					to: call.to,
 					known: options.manager.terminals()
@@ -2664,24 +2536,22 @@ function createPromptTool(options) {
 	});
 }
 /**
-* 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
@@ -2698,7 +2568,7 @@ function createPromptTool(options) {
 * 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
 * ```
 */
 function createAnswerTool(options) {
@@ -2712,22 +2582,21 @@ function createAnswerTool(options) {
 		async execute(args) {
 			const call = contract.parse(args);
 			if (call === void 0) throw new ToolboxError("TOOL", "malformed answer call", { args });
-			if (call.operation === "pending") return options.manager.pending(options.to).map((prompt) => ({
-				id: prompt.id,
-				from: prompt.from,
-				form: prompt.form,
-				message: prompt.message
+			if (call.operation === "pending") return options.manager.pending(options.to).map((form) => ({
+				id: form.id,
+				from: form.from,
+				schema: form.schema
 			}));
-			const prompt = options.manager.pending(options.to).find((entry) => entry.id === call.id);
-			if (prompt === void 0) throw new ToolboxError("ANSWER", `unknown prompt '${call.id}'`, {
+			if (options.manager.pending(options.to).find((entry) => entry.id === call.id) === void 0) throw new ToolboxError("ANSWER", `unknown form '${call.id}'`, {
 				id: call.id,
 				reason: "unknown"
 			});
-			const coerced = coerceAnswer(prompt.form, call.value);
-			const result = options.manager.answer(options.to, call.id, coerced);
-			if (!result.success) throw new ToolboxError("ANSWER", `failed to answer prompt '${call.id}': ${result.error}`, {
+			if (!isFormValues(call.values)) throw new ToolboxError("TOOL", "malformed form values", { values: call.values });
+			const result = options.manager.answer(options.to, call.id, call.values);
+			if (!result.success) throw new ToolboxError("ANSWER", `failed to answer form '${call.id}': ${result.error.reason}`, {
 				id: call.id,
-				reason: result.error
+				reason: result.error.reason,
+				...result.error.reason === "rejected" ? { errors: result.error.errors } : {}
 			});
 			return { answered: call.id };
 		}
@@ -3319,6 +3188,6 @@ function createEndpointTool(definition, options) {
 	});
 }
 //#endregion
-export { AGENT_TOOL_DEPTH, AGENT_TOOL_DESCRIPTION, AGENT_TOOL_NAME, AGENT_TOOL_SUMMARY, ANSWER_TOOL_DESCRIPTION, ANSWER_TOOL_NAME, ANSWER_TOOL_SUMMARY, DATABASE_TOOL_DESCRIPTION, DATABASE_TOOL_LIMIT, DATABASE_TOOL_MUTATIONS, DATABASE_TOOL_NAME, DATABASE_TOOL_SUMMARY, DESCRIBE_TOOL_DESCRIPTION, DESCRIBE_TOOL_NAME, DESCRIBE_TOOL_SUMMARY, DatabaseDefinitionStore, DatabaseResolver, INFER_TOOL_DESCRIPTION, INFER_TOOL_NAME, INFER_TOOL_SUMMARY, MAX_WORKFLOW_DEPTH, MemoryDefinitionStore, PROMPT_TOOL_DESCRIPTION, PROMPT_TOOL_NAME, PROMPT_TOOL_SUMMARY, RELATION_TOOL_DEPTH, RELATION_TOOL_DESCRIPTION, RELATION_TOOL_LIMIT, RELATION_TOOL_NAME, RELATION_TOOL_SUMMARY, ToolboxError, WORKFLOW_TOOL_DESCRIPTION, WORKFLOW_TOOL_FLAT_EXAMPLE, WORKFLOW_TOOL_NAME, WORKFLOW_TOOL_NESTED_EXAMPLE, WORKFLOW_TOOL_SUMMARY, WORKSPACE_TOOL_DESCRIPTION, WORKSPACE_TOOL_EXAMPLE, WORKSPACE_TOOL_NAME, WORKSPACE_TOOL_SUMMARY, agentTag, agentToolShape, answerToolShape, clampQuery, coerceAnswer, columnKindShape, columnShape, columnSpecShape, completeDraft, completePhaseDraft, completeTaskDraft, conditionShape, createAgentFunction, createAgentTool, createAnswerTool, createDatabaseDefinitionStore, createDatabaseTool, createDescribeTool, createEndpointTool, createInferTool, createMemoryDefinitionStore, createPromptTool, createRelationTool, createToolFunction, createWorkflowDraftContract, createWorkflowFunctions, createWorkflowTool, createWorkspaceTool, databaseToolCode, databaseToolShape, deriveWorkflowDepth, describeToolShape, expandInclude, expandSteps, expandTables, extendLineage, includeShape, inferToolShape, isAgentFunction, isColumnKind, isColumnSpec, isDatabaseDefinition, isToolboxError, isWorkflowLineage, keyShape, kindShape, lineageOf, managerShape, orderShape, phaseDraftShape, promptToolShape, queryOf, queryShape, relationKeyShape, relationManagerOf, relationModelOf, relationToolCode, relationToolShape, rowShape, rowsShape, singleKeyShape, stepShape, tableSpecShape, taskDraftShape, terminalToolCode, workflowDraftShape, workflowStepsShape, workflowTag, workflowToolSummary, workspaceToolShape };
+export { AGENT_TOOL_DEPTH, AGENT_TOOL_DESCRIPTION, AGENT_TOOL_NAME, AGENT_TOOL_SUMMARY, ANSWER_TOOL_DESCRIPTION, ANSWER_TOOL_NAME, ANSWER_TOOL_SUMMARY, DATABASE_TOOL_DESCRIPTION, DATABASE_TOOL_LIMIT, DATABASE_TOOL_MUTATIONS, DATABASE_TOOL_NAME, DATABASE_TOOL_SUMMARY, DESCRIBE_TOOL_DESCRIPTION, DESCRIBE_TOOL_NAME, DESCRIBE_TOOL_SUMMARY, DatabaseDefinitionStore, DatabaseResolver, INFER_TOOL_DESCRIPTION, INFER_TOOL_NAME, INFER_TOOL_SUMMARY, MAX_WORKFLOW_DEPTH, MemoryDefinitionStore, PROMPT_TOOL_DESCRIPTION, PROMPT_TOOL_NAME, PROMPT_TOOL_SUMMARY, RELATION_TOOL_DEPTH, RELATION_TOOL_DESCRIPTION, RELATION_TOOL_LIMIT, RELATION_TOOL_NAME, RELATION_TOOL_SUMMARY, ToolboxError, WORKFLOW_TOOL_DESCRIPTION, WORKFLOW_TOOL_FLAT_EXAMPLE, WORKFLOW_TOOL_NAME, WORKFLOW_TOOL_NESTED_EXAMPLE, WORKFLOW_TOOL_SUMMARY, WORKSPACE_TOOL_DESCRIPTION, WORKSPACE_TOOL_EXAMPLE, WORKSPACE_TOOL_NAME, WORKSPACE_TOOL_SUMMARY, agentTag, agentToolShape, answerToolShape, clampQuery, columnKindShape, columnShape, columnSpecShape, completeDraft, completePhaseDraft, completeTaskDraft, conditionShape, createAgentFunction, createAgentTool, createAnswerTool, createDatabaseDefinitionStore, createDatabaseTool, createDescribeTool, createEndpointTool, createInferTool, createMemoryDefinitionStore, createPromptTool, createRelationTool, createToolFunction, createWorkflowDraftContract, createWorkflowFunctions, createWorkflowTool, createWorkspaceTool, databaseToolCode, databaseToolShape, deriveWorkflowDepth, describeToolShape, expandInclude, expandSteps, expandTables, extendLineage, includeShape, inferToolShape, isAgentFunction, isColumnKind, isColumnSpec, isDatabaseDefinition, isToolboxError, isWorkflowLineage, keyShape, kindShape, lineageOf, managerShape, orderShape, phaseDraftShape, promptToolShape, queryOf, queryShape, relationKeyShape, relationManagerOf, relationModelOf, relationToolCode, relationToolShape, rowShape, rowsShape, singleKeyShape, stepShape, tableSpecShape, taskDraftShape, terminalToolCode, workflowDraftShape, workflowStepsShape, workflowTag, workflowToolSummary, workspaceToolShape };
 
 //# sourceMappingURL=index.js.map

package/dist/src/server/index.cjs

@@ -1,5 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 let _orkestrel_terminal = require("@orkestrel/terminal");
+let _orkestrel_form = require("@orkestrel/form");
+let _orkestrel_contract = require("@orkestrel/contract");
 let _orkestrel_server = require("@orkestrel/server");
 //#region src/server/constants.ts
 /**
@@ -19,13 +21,9 @@ var TERMINAL_KEEPALIVE_MS = 15e3;
 /**
 * Own one terminal SSE connection's replay, subscriptions, keepalive, and teardown.
 *
-* @example
-* ```ts
-* import { TerminalConnection } from '@orkestrel/toolbox/server'
-*
-* const connection = new TerminalConnection(manager, name, request, stream, accepts, timer, 15_000)
-* const response = connection.open()
-* ```
+* Internal to this module: `TerminalRoutes` builds the `accepts` predicate from its own token
+* option and opens the stream, so no consumer can construct one. Reach this behaviour through
+* `createTerminalRoutes`.
 */
 var TerminalConnection = class {
 	#manager;
@@ -44,7 +42,7 @@ var TerminalConnection = class {
 	/**
 	* Create a terminal stream connection.
 	*
-	* @param manager - Terminal manager supplying pending prompts and lifecycle events
+	* @param manager - Terminal manager supplying pending forms and lifecycle events
 	* @param name - Terminal endpoint streamed by this connection
 	* @param request - Request whose abort signal owns the connection lifetime
 	* @param stream - Open SSE stream
@@ -67,7 +65,7 @@ var TerminalConnection = class {
 		this.#tickHandler = this.#tick.bind(this);
 	}
 	/**
-	* Open the connection by replaying pending prompts, subscribing, and arming keepalive handling.
+	* Open the connection by replaying pending forms, subscribing, and arming keepalive handling.
 	*
 	* @returns The SSE response
 	*/
@@ -77,7 +75,7 @@ var TerminalConnection = class {
 			return this.#stream.response;
 		}
 		if (this.#cancel !== void 0) return this.#stream.response;
-		for (const prompt of this.#manager.pending(this.#name)) this.#write((0, _orkestrel_terminal.serializePending)(prompt));
+		for (const form of this.#manager.pending(this.#name)) this.#write((0, _orkestrel_terminal.serializePending)(form));
 		this.#manager.emitter.on("pending", this.#pendingHandler);
 		this.#manager.emitter.on("expire", this.#expireHandler);
 		this.#cancel = this.#timer(this.#tickHandler, this.#keepalive);
@@ -91,13 +89,13 @@ var TerminalConnection = class {
 			...wire.id === void 0 ? {} : { id: wire.id }
 		});
 	}
-	#pending(prompt) {
-		if (prompt.to !== this.#name) return;
+	#pending(form) {
+		if (form.to !== this.#name) return;
 		if (this.#stream.closed) {
 			this.#destroy();
 			return;
 		}
-		this.#write((0, _orkestrel_terminal.serializePending)(prompt));
+		this.#write((0, _orkestrel_terminal.serializePending)(form));
 	}
 	#expire(to, id) {
 		if (to !== this.#name) return;
@@ -223,11 +221,11 @@ var TerminalRoutes = class {
 		} catch {
 			return new Response(null, { status: 400 });
 		}
-		if (!(0, _orkestrel_terminal.isAnswerPayload)(body)) return new Response(null, { status: 422 });
-		const result = this.#manager.answer(name, body.id, body.value);
-		if (result.success) return new Response(null, { status: 204 });
-		if (result.error === "terminal") return new Response(result.error, { status: 404 });
-		return new Response(result.error, { status: 422 });
+		if (!(0, _orkestrel_contract.isRecord)(body) || !(0, _orkestrel_contract.isNonEmptyString)(body.id) || !(0, _orkestrel_form.isFormValues)(body.values)) return new Response(null, { status: 422 });
+		const result = this.#manager.answer(name, body.id, body.values);
+		if (result.success) return Response.json(result);
+		if (result.error.reason === "terminal") return Response.json(result, { status: 404 });
+		return Response.json(result, { status: 422 });
 	}
 };
 //#endregion
@@ -260,7 +258,6 @@ function createTerminalRoutes(manager, options) {
 //#endregion
 exports.TERMINAL_KEEPALIVE_MS = TERMINAL_KEEPALIVE_MS;
 exports.TERMINAL_ROUTES_PATH = TERMINAL_ROUTES_PATH;
-exports.TerminalConnection = TerminalConnection;
 exports.TerminalRoutes = TerminalRoutes;
 exports.createTerminalRoutes = createTerminalRoutes;
 

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

@@ -1,4 +1,3 @@
-import { StreamInterface } from '@orkestrel/server';
 import { TerminalManagerInterface } from '@orkestrel/terminal';
 import { TimerHandler } from '@orkestrel/terminal';
 
@@ -43,39 +42,6 @@ export declare const TERMINAL_KEEPALIVE_MS = 15000;
  */
 export declare const TERMINAL_ROUTES_PATH = "/terminals/:name";
 
-/**
- * Own one terminal SSE connection's replay, subscriptions, keepalive, and teardown.
- *
- * @example
- * ```ts
- * import { TerminalConnection } from '@orkestrel/toolbox/server'
- *
- * const connection = new TerminalConnection(manager, name, request, stream, accepts, timer, 15_000)
- * const response = connection.open()
- * ```
- */
-export declare class TerminalConnection {
-    #private;
-    /**
-     * Create a terminal stream connection.
-     *
-     * @param manager - Terminal manager supplying pending prompts and lifecycle events
-     * @param name - Terminal endpoint streamed by this connection
-     * @param request - Request whose abort signal owns the connection lifetime
-     * @param stream - Open SSE stream
-     * @param accepts - Presented-token validator
-     * @param timer - Keepalive timer implementation
-     * @param keepalive - Keepalive interval in milliseconds
-     */
-    constructor(manager: TerminalManagerInterface, name: string, request: Request, stream: StreamInterface, accepts: (presented: string | undefined) => boolean, timer: TimerHandler, keepalive: number);
-    /**
-     * Open the connection by replaying pending prompts, subscribing, and arming keepalive handling.
-     *
-     * @returns The SSE response
-     */
-    open(): Response;
-}
-
 /**
  * One structural route record {@link import('./factories.js').createTerminalRoutes} returns — a
  * plain `{ method, path, handler }` shape carrying NO dependency on `@orkestrel/router`'s own

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

@@ -1,4 +1,3 @@
-import { StreamInterface } from '@orkestrel/server';
 import { TerminalManagerInterface } from '@orkestrel/terminal';
 import { TimerHandler } from '@orkestrel/terminal';
 
@@ -43,39 +42,6 @@ export declare const TERMINAL_KEEPALIVE_MS = 15000;
  */
 export declare const TERMINAL_ROUTES_PATH = "/terminals/:name";
 
-/**
- * Own one terminal SSE connection's replay, subscriptions, keepalive, and teardown.
- *
- * @example
- * ```ts
- * import { TerminalConnection } from '@orkestrel/toolbox/server'
- *
- * const connection = new TerminalConnection(manager, name, request, stream, accepts, timer, 15_000)
- * const response = connection.open()
- * ```
- */
-export declare class TerminalConnection {
-    #private;
-    /**
-     * Create a terminal stream connection.
-     *
-     * @param manager - Terminal manager supplying pending prompts and lifecycle events
-     * @param name - Terminal endpoint streamed by this connection
-     * @param request - Request whose abort signal owns the connection lifetime
-     * @param stream - Open SSE stream
-     * @param accepts - Presented-token validator
-     * @param timer - Keepalive timer implementation
-     * @param keepalive - Keepalive interval in milliseconds
-     */
-    constructor(manager: TerminalManagerInterface, name: string, request: Request, stream: StreamInterface, accepts: (presented: string | undefined) => boolean, timer: TimerHandler, keepalive: number);
-    /**
-     * Open the connection by replaying pending prompts, subscribing, and arming keepalive handling.
-     *
-     * @returns The SSE response
-     */
-    open(): Response;
-}
-
 /**
  * One structural route record {@link import('./factories.js').createTerminalRoutes} returns — a
  * plain `{ method, path, handler }` shape carrying NO dependency on `@orkestrel/router`'s own