@orkestrel/tool 0.0.1

package/dist/src/core/index.js

@@ -0,0 +1,1199 @@
+import { arrayShape, booleanShape, createContract, integerShape, literalShape, objectShape, optionalShape, schemaToParameters, stringShape, unionShape } from "@orkestrel/contract";
+import { WorkspaceError, createTool, createWorkspaceManager, isText, rangeOf } from "@orkestrel/agent";
+import { WorkflowError, createWorkflowContract } from "@orkestrel/workflow";
+//#region src/core/constants.ts
+/**
+* The name {@link import('./factories.js').createAgentTool} advertises by default — the key a
+* model calls and the `ToolManagerInterface` (`@orkestrel/agent`) registers under.
+*/
+var AGENT_TOOL_NAME = "agent";
+/**
+* The maximum nesting depth a delegation chain (agent tool → sub-agent → agent tool → …) may
+* reach — the bound {@link import('./factories.js').createAgentTool}'s depth/cycle guard
+* enforces.
+*
+* @remarks
+* Deliberately a SEPARATE constant from {@link MAX_WORKFLOW_DEPTH} (rather than the two guards
+* sharing one reference): the two guards bound DIFFERENT chains (workflow nesting vs. agent
+* delegation) that happen to share a value today, and keeping this bound decoupled means a
+* future change to one never silently shifts the other. Same numeric value by convention, not
+* by shared reference.
+*/
+var AGENT_TOOL_DEPTH = 8;
+/**
+* The DESCRIPTION {@link import('./factories.js').createAgentTool} advertises — a short guide
+* that teaches a model how to delegate a task to a sub-agent.
+*
+* @remarks
+* Mirrors {@link WORKFLOW_TOOL_DESCRIPTION} / `WORKSPACE_TOOL_DESCRIPTION`'s teaching style: names
+* the required `task` field, and documents the optional per-call `provider` / `tools` /
+* `system` overrides.
+*/
+/**
+* The lean {@link import('@orkestrel/agent').ToolInterface.summary} {@link import('./factories.js').createAgentTool}
+* advertises in place of {@link AGENT_TOOL_DESCRIPTION} — a `ToolManagerInterface.definitions()`
+* (`@orkestrel/agent`) advertises `summary ?? description`, so this one-sentence text stands in
+* for the full teaching description; the full text stays retrievable via
+* {@link import('./factories.js').createDescribeTool}.
+*/
+var AGENT_TOOL_SUMMARY = "Delegate a task to a sub-agent and return its result; each call runs one sub-agent turn to completion. Call describe('agent') for the optional provider/tools/system overrides.";
+var AGENT_TOOL_DESCRIPTION = [
+	"Delegate a task to a sub-agent and return its result. Every call runs ONE sub-agent turn to completion.",
+	"",
+	"Required:",
+	"  task     - the instructions the sub-agent should carry out.",
+	"Optional overrides (default to the values this tool was configured with):",
+	"  provider - the registry key of the model/provider the sub-agent runs against.",
+	"  tools    - registry keys of the tools loaded into the sub-agent (replaces the default list, not merged).",
+	"  system   - a system prompt seeding the sub-agent's context (replaces the default).",
+	"Example:",
+	JSON.stringify({ task: "Summarize the attached notes in three bullet points." })
+].join("\n");
+/**
+* The maximum nesting depth a workflow → agent → workflow chain may reach — the bound
+* {@link import('./factories.js').createAgentFunction} and
+* {@link import('./factories.js').createWorkflowTool}'s depth/cycle guards enforce.
+*
+* @remarks
+* OWNED here now (ported from `@orkestrel/workflow`, whose engine no longer uses it — only the
+* tool-authoring guards this package now owns consume it). The limit lives in ONE place: an
+* agent-function-wrapped agent running at this depth can no longer author + run a NESTED
+* workflow through its bound workflow tool (that would be depth `MAX_WORKFLOW_DEPTH + 1`), so
+* the over-deep invocation is REJECTED (a typed `DEPTH` `WorkflowError` throw, `@orkestrel/workflow`).
+*/
+var MAX_WORKFLOW_DEPTH = 8;
+/**
+* The name {@link import('./factories.js').createWorkflowTool} advertises by default — the key a
+* model calls and the `ToolManagerInterface` (`@orkestrel/agent`) registers under, and the name
+* {@link import('./factories.js').createAgentFunction} binds the depth/cycle-aware workflow tool
+* under onto a wrapped agent's `context.tools`.
+*
+* @remarks
+* OWNED here now (ported from `@orkestrel/workflow`). The propagation seam's well-known key: when
+* `createAgentFunction`'s `runner` option is supplied, it adds a `createWorkflowTool`-built tool
+* under this name to the agent's `context.tools`, so it can author + run a NESTED workflow
+* (bounded by {@link MAX_WORKFLOW_DEPTH}).
+*/
+var WORKFLOW_TOOL_NAME = "workflow";
+/**
+* A complete FLAT authoring example — the PRIMARY way a small model authors a workflow through
+* {@link import('./factories.js').createWorkflowTool}: `{ name, steps: [{ name }] }`.
+*
+* @remarks
+* OWNED here now (ported from `@orkestrel/workflow`). Each step becomes a one-task phase, in
+* order; a step's `name` is a REGISTERED behavior name (not a label) — the registry key its
+* task's `run` resolves against. The tool expands this
+* ({@link import('./helpers.js').expandSteps}) into a valid `WorkflowDefinition`
+* (`@orkestrel/workflow`). It is embedded VERBATIM in {@link WORKFLOW_TOOL_DESCRIPTION}.
+*/
+var WORKFLOW_TOOL_FLAT_EXAMPLE = Object.freeze({
+	name: "release",
+	steps: Object.freeze([Object.freeze({ name: "compile" }), Object.freeze({ name: "publish" })])
+});
+/**
+* A minimal NESTED authoring example — the ADVANCED escape-hatch form a model may use instead of
+* the flat shape: a full `WorkflowDefinition` (`@orkestrel/workflow`).
+*
+* @remarks
+* OWNED here now (ported from `@orkestrel/workflow`). The full four-level form, documented in
+* {@link WORKFLOW_TOOL_DESCRIPTION} as the advanced alternative. It is embedded VERBATIM.
+*/
+var WORKFLOW_TOOL_NESTED_EXAMPLE = Object.freeze({
+	id: "release",
+	name: "Release",
+	phases: Object.freeze([Object.freeze({
+		id: "build",
+		name: "Build",
+		tasks: Object.freeze([Object.freeze({
+			id: "compile",
+			name: "Compile",
+			run: "compile"
+		})])
+	})])
+});
+/**
+* The DESCRIPTION {@link import('./factories.js').createWorkflowTool} advertises — a multi-line
+* guide that teaches a small model how to author a complete workflow tree.
+*
+* @remarks
+* OWNED here now (ported from `@orkestrel/workflow`). Presents the SIMPLE flat shape
+* (`{ name, steps: [{ name }] }`) as the PRIMARY way with one complete worked example
+* ({@link WORKFLOW_TOOL_FLAT_EXAMPLE}), names that a step's `name` is a REGISTERED name (not a
+* human label), and documents the full nested `WorkflowDefinition` as the ADVANCED form with a
+* minimal example ({@link WORKFLOW_TOOL_NESTED_EXAMPLE}). The `parameters` the tool advertises
+* are the FLAT shape's schema; the nested form is the documented escape-hatch (the tool accepts
+* both).
+*/
+/**
+* The lean {@link import('@orkestrel/agent').ToolInterface.summary} {@link import('./factories.js').createWorkflowTool}
+* advertises in place of {@link WORKFLOW_TOOL_DESCRIPTION} — a `ToolManagerInterface.definitions()`
+* (`@orkestrel/agent`) advertises `summary ?? description`, so this one-sentence text stands in
+* for the full teaching description; the full text stays retrievable via
+* {@link import('./factories.js').createDescribeTool}.
+*/
+var WORKFLOW_TOOL_SUMMARY = "Author and run a multi-phase workflow in one call — phases run in sequence, tasks within a phase run concurrently. Call describe('workflow') for the full authoring schema and examples.";
+var WORKFLOW_TOOL_DESCRIPTION = [
+	"Author and run a workflow (phases run sequentially, the tasks within a phase run concurrently) in one call.",
+	"",
+	"SIMPLEST way — a flat list of steps. Each step runs one registered behavior; steps run one after another:",
+	"  { \"name\": \"<workflow name>\", \"steps\": [ { \"name\": \"<registered name>\" }, ... ] }",
+	"- a step's \"name\" is a REGISTERED behavior name (a registry key), NOT a human label.",
+	"- the top-level \"name\" (the workflow name) is optional. Ids are filled in for you.",
+	"Example:",
+	JSON.stringify(WORKFLOW_TOOL_FLAT_EXAMPLE),
+	"",
+	"ADVANCED — the full nested form, for multi-task phases or explicit ids. A workflow has phases; a phase has tasks; a task has a \"run\" (a registered behavior name):",
+	JSON.stringify(WORKFLOW_TOOL_NESTED_EXAMPLE),
+	"In the nested form you may omit any \"id\"/\"name\" and they are filled in positionally; a provided one is kept."
+].join("\n");
+/**
+* The name {@link import('./factories.js').createWorkspaceTool} advertises by default — the key a
+* model calls and the `ToolManagerInterface` (`@orkestrel/agent`) registers under.
+*
+* @remarks
+* OWNED here now (ported from `@orkestrel/agent`).
+*/
+var WORKSPACE_TOOL_NAME = "workspace";
+/**
+* A valid `WorkspaceOperation` (`@orkestrel/agent`) object — the canonical example embedded
+* VERBATIM in {@link WORKSPACE_TOOL_DESCRIPTION}.
+*
+* @remarks
+* OWNED here now (ported from `@orkestrel/agent`). A `'write'` op (the most common authoring
+* action): create or overwrite `notes.txt` with `hello`. Frozen so it cannot be mutated in
+* place.
+*/
+var WORKSPACE_TOOL_EXAMPLE = Object.freeze({
+	operation: "write",
+	path: "notes.txt",
+	content: "hello"
+});
+/**
+* The DESCRIPTION {@link import('./factories.js').createWorkspaceTool} advertises — a multi-line
+* guide that teaches a small model how to drive a workspace through the single
+* `operation`-keyed tool.
+*
+* @remarks
+* OWNED here now (ported from `@orkestrel/agent`). Mirrors {@link WORKFLOW_TOOL_DESCRIPTION}'s
+* teaching style: names the `operation` discriminant field, enumerates all 13 operations with
+* their FLAT fields, gives a worked example for the common ones, and embeds
+* {@link WORKSPACE_TOOL_EXAMPLE} verbatim.
+*/
+/**
+* The lean {@link import('@orkestrel/agent').ToolInterface.summary} {@link import('./factories.js').createWorkspaceTool}
+* advertises in place of {@link WORKSPACE_TOOL_DESCRIPTION} — a `ToolManagerInterface.definitions()`
+* (`@orkestrel/agent`) advertises `summary ?? description`, so this one-sentence text stands in
+* for the full teaching description; the full text stays retrievable via
+* {@link import('./factories.js').createDescribeTool}.
+*/
+var WORKSPACE_TOOL_SUMMARY = "Read and edit files in a workspace — one operation per call (read, write, list, search, replace, splice, move, remove, plus workspace switching), chosen by the 'operation' field. Call describe('workspace') for the full operation list and fields.";
+var WORKSPACE_TOOL_DESCRIPTION = [
+	"Read and edit files in a workspace. Every call is ONE operation, chosen by the \"operation\" field.",
+	"All file operations act on the ACTIVE workspace; use \"workspaces\" then \"switch\" to move between workspaces.",
+	"",
+	"Operations (each takes the fields listed):",
+	"- read     { \"operation\": \"read\", \"path\": \"<file>\" } — return the file's text.",
+	"- list     { \"operation\": \"list\" } — list every file in the active workspace (path, state, size, lines, kind).",
+	"- has      { \"operation\": \"has\", \"path\": \"<file>\" } — whether the file exists.",
+	"- search   { \"operation\": \"search\", \"query\": \"<text>\", \"regex\"?: bool, \"exact\"?: bool, \"limit\"?: int } — find lines matching the query across all files.",
+	"- replace  { \"operation\": \"replace\", \"query\": \"<text>\", \"replacement\": \"<text>\", \"regex\"?: bool, \"exact\"?: bool, \"limit\"?: int } — replace matches across all files.",
+	"- write    { \"operation\": \"write\", \"path\": \"<file>\", \"content\": \"<text>\" } — create or overwrite the whole file.",
+	"- splice   { \"operation\": \"splice\", \"path\": \"<file>\", \"content\": \"<text>\", \"fromLine\": int, \"fromColumn\": int, \"toLine\": int, \"toColumn\": int } — replace a 1-based range (from inclusive, to exclusive) with content.",
+	"- prepend  { \"operation\": \"prepend\", \"path\": \"<file>\", \"content\": \"<text>\" } — add content to the start of the file.",
+	"- append   { \"operation\": \"append\", \"path\": \"<file>\", \"content\": \"<text>\" } — add content to the end of the file.",
+	"- move     { \"operation\": \"move\", \"from\": \"<file>\", \"to\": \"<file>\" } — rename / move a file.",
+	"- remove   { \"operation\": \"remove\", \"path\": \"<file>\" } — delete a file.",
+	"- workspaces { \"operation\": \"workspaces\" } — list the workspaces you can switch between (each id, file count, active).",
+	"- switch   { \"operation\": \"switch\", \"id\": \"<id>\" } — make the workspace with that id active (ids come from \"workspaces\").",
+	"",
+	"Notes: lines and columns are 1-based (column 1 is the first character). \"regex\" defaults to false (a literal substring), \"exact\" defaults to true (case-sensitive). \"search\"/\"replace\"/\"splice\" act only on text files. Editing with no active workspace auto-creates one.",
+	"",
+	"Example — write a file:",
+	JSON.stringify(WORKSPACE_TOOL_EXAMPLE)
+].join("\n");
+/**
+* The name {@link import('./factories.js').createDescribeTool} advertises by default — the key a
+* model calls and the `ToolManagerInterface` (`@orkestrel/agent`) registers under.
+*
+* @remarks
+* Net-new: pairs with the other three tools' lean {@link AGENT_TOOL_SUMMARY} /
+* {@link WORKFLOW_TOOL_SUMMARY} / {@link WORKSPACE_TOOL_SUMMARY} — a model that reads only the
+* advertised summary can call `describe` with that tool's registered name to get its full
+* teaching description back.
+*/
+var DESCRIBE_TOOL_NAME = "describe";
+/**
+* The lean {@link import('@orkestrel/agent').ToolInterface.summary} {@link import('./factories.js').createDescribeTool}
+* advertises — this tool needs no teaching of its own, so its summary and description are both
+* short.
+*/
+var DESCRIBE_TOOL_SUMMARY = "Return the full description of a named registered tool.";
+/**
+* The DESCRIPTION {@link import('./factories.js').createDescribeTool} advertises.
+*
+* @remarks
+* Deliberately short — unlike the workflow / workspace / agent tools, this one has no authoring
+* schema or multi-step protocol to teach.
+*/
+var DESCRIBE_TOOL_DESCRIPTION = "Return the full description of a registered tool by its name. Required: name - the registered tool name (see another tool listing for available names).";
+//#endregion
+//#region src/core/errors.ts
+/**
+* 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`).
+*
+* @remarks
+* Carries a machine-readable `code` (see {@link import('./types.js').AgentToolErrorCode}) and
+* an optional `context` bag for structured diagnostics. The `ToolManagerInterface`
+* (`@orkestrel/agent`) isolates every throw into the canonical tool result's top-level `error`
+* (AGENTS §14) — nothing escapes the run.
+*
+* @example
+* ```ts
+* import { AgentToolError, isAgentToolError } from '@src/core'
+*
+* try {
+* 	throw new AgentToolError('TOOL', 'task is required')
+* } catch (error) {
+* 	if (isAgentToolError(error)) console.log(error.code) // 'TOOL'
+* }
+* ```
+*/
+var AgentToolError = class extends Error {
+	code;
+	context;
+	constructor(code, message, context) {
+		super(message);
+		this.name = "AgentToolError";
+		this.code = code;
+		this.context = context;
+	}
+};
+/**
+* Type guard narrowing an unknown caught value to an {@link AgentToolError}.
+*
+* @param value - The value to test (typically a `catch` binding)
+* @returns `true` when `value` is an {@link AgentToolError}
+*
+* @example
+* ```ts
+* import { isAgentToolError } from '@src/core'
+*
+* try {
+* 	// ...
+* } catch (error) {
+* 	if (isAgentToolError(error)) console.log(error.code)
+* }
+* ```
+*/
+function isAgentToolError(value) {
+	return value instanceof AgentToolError;
+}
+//#endregion
+//#region src/core/shapers.ts
+/**
+* The shape of {@link import('./types.js').AgentToolArguments} —
+* {@link import('./factories.js').createAgentTool}'s advertised `parameters`.
+*
+* @remarks
+* `task` is the only required field (a non-empty string); `provider` / `tools` / `system`
+* are per-call overrides of the tool's own configured defaults.
+*/
+var agentToolShape = objectShape({
+	task: stringShape({
+		min: 1,
+		description: "The instructions the sub-agent should carry out."
+	}),
+	provider: optionalShape(stringShape({
+		min: 1,
+		description: "Registry key of the provider to run the sub-agent against (overrides the default)."
+	})),
+	tools: optionalShape(arrayShape(stringShape({ min: 1 }), { description: "Registry keys of the tools loaded into the sub-agent (replaces the default list)." })),
+	system: optionalShape(stringShape({ description: "A system prompt seeding the sub-agent's context (overrides the default)." }))
+});
+/**
+* The shape of {@link import('./types.js').DescribeToolArguments} —
+* {@link import('./factories.js').createDescribeTool}'s advertised `parameters`.
+*
+* @remarks
+* `name` is the only field (a non-empty string) — the registered tool name to look up.
+*/
+var describeToolShape = objectShape({ name: stringShape({
+	min: 1,
+	description: "The registered name of the tool whose full description to return."
+}) });
+/**
+* The shape of a {@link import('./types.js').TaskDraft} — identical to a strict task shape
+* EXCEPT `id` and `name` are OPTIONAL.
+*/
+var taskDraftShape = objectShape({
+	id: optionalShape(stringShape({
+		min: 1,
+		description: "Task id; auto-filled when omitted."
+	})),
+	name: optionalShape(stringShape({
+		min: 1,
+		description: "Task name; defaults to the id when omitted."
+	})),
+	description: optionalShape(stringShape({ description: "Optional task description." })),
+	run: optionalShape(stringShape({
+		min: 1,
+		description: "The registered behavior name to invoke (a registry key, not a label); omitted has no handler."
+	})),
+	retries: optionalShape(integerShape({
+		min: 0,
+		description: "Extra attempts after the first on failure; overrides the phase default. Omitted means none."
+	})),
+	timeout: optionalShape(integerShape({
+		min: 0,
+		description: "Per-attempt deadline in milliseconds; overrides the phase default. Omitted means no deadline."
+	}))
+});
+/**
+* The shape of a PHASE in a draft workflow — identical to a strict phase shape EXCEPT `id` and
+* `name` are OPTIONAL, and its tasks are {@link taskDraftShape}s.
+*/
+var phaseDraftShape = objectShape({
+	id: optionalShape(stringShape({
+		min: 1,
+		description: "Phase id; auto-filled when omitted."
+	})),
+	name: optionalShape(stringShape({
+		min: 1,
+		description: "Phase name; defaults to the id when omitted."
+	})),
+	description: optionalShape(stringShape({ description: "Optional phase description." })),
+	tasks: arrayShape(taskDraftShape, { description: "The phase tasks; they run CONCURRENTLY." }),
+	concurrency: optionalShape(integerShape({
+		min: 1,
+		description: "Max tasks in flight at once (a resource throttle); omitted means unbounded."
+	})),
+	bail: optionalShape(literalShape([true, false], { description: "Per-phase failure-policy override; omitted inherits the workflow bail." }))
+});
+/**
+* The shape of a DRAFT workflow — identical to a strict workflow shape EXCEPT `id` and `name`
+* are OPTIONAL at all three levels (workflow / phase / task), so a small model can omit the six
+* identity strings and let the tool synthesize them positionally.
+*
+* @remarks
+* The lenient counterpart {@link import('./factories.js').createWorkflowDraftContract} compiles.
+* `run` stays required on the strict form; a provided `id` / `name` still has `minLength: 1` (so
+* an explicitly-empty `id: ''` is REJECTED, not auto-filled). After
+* {@link import('./helpers.js').completeDraft} fills the missing ids/names, the result is
+* validated against the STRICT `createWorkflowContract` (`@orkestrel/workflow`) gate before
+* running.
+*/
+var workflowDraftShape = objectShape({
+	id: optionalShape(stringShape({
+		min: 1,
+		description: "Workflow id; auto-filled when omitted."
+	})),
+	name: optionalShape(stringShape({
+		min: 1,
+		description: "Workflow name; defaults to the id when omitted."
+	})),
+	description: optionalShape(stringShape({ description: "Optional workflow description." })),
+	phases: arrayShape(phaseDraftShape, { description: "The workflow phases; they run SEQUENTIALLY, in order." }),
+	bail: optionalShape(literalShape([true, false], { description: "Failure policy: false (default) continues gracefully, true halts on the first failure." }))
+});
+/**
+* The shape of ONE flat step — `{ name }` — the building block of {@link workflowStepsShape}.
+*
+* @remarks
+* `name` is the REGISTERED behavior name the step runs (it becomes the task's `run`). The tool
+* expands each step into a one-task phase, in order ({@link import('./helpers.js').expandSteps}).
+*/
+var stepShape = objectShape({ name: stringShape({
+	min: 1,
+	description: "The registered behavior name this step runs (becomes the task run)."
+}) });
+/**
+* The FLAT authoring shape {@link import('./factories.js').createWorkflowTool} advertises as its
+* `parameters` — the simplest surface a small model can fill: `{ name?, steps: [{ name }] }`.
+*
+* @remarks
+* A deliberately-reduced surface: a flat ordered list of steps, each a `{ name }`. The tool
+* EXPANDS it ({@link import('./helpers.js').expandSteps}) into a full
+* {@link import('./types.js').WorkflowDefinition} — one one-task phase per step, in order —
+* then validates against the STRICT `createWorkflowContract` (`@orkestrel/workflow`) gate. The
+* full nested form is STILL accepted by the tool (it branches on the args' shape) and is
+* documented as the advanced escape-hatch in the tool's description — but THIS is what
+* `parameters` advertises.
+*/
+var workflowStepsShape = objectShape({
+	name: optionalShape(stringShape({
+		min: 1,
+		description: "Optional workflow name."
+	})),
+	steps: arrayShape(stepShape, { description: "The ordered steps to run, one after another (each becomes a one-task phase)." })
+});
+/**
+* The shape of a {@link import('./types.js').WorkspaceOperation} — a descriptive tagged union
+* over the 13 workspace edit / read / navigation operations, discriminated by the `operation`
+* literal (never a bare `kind`; AGENTS §4.4). Each variant leads with its `operation`
+* discriminant then its FLAT fields, every field via `stringShape` / `optionalShape` /
+* `integerShape({ min: 1 })` / `booleanShape`, each carrying a strong field-level `description`.
+*
+* @remarks
+* The union compiles to an `anyOf` JSON Schema + a `unionOf` guard + a first-match parser
+* automatically ({@link import('./factories.js').createWorkspaceTool} types the result to the
+* hand-written {@link import('./types.js').WorkspaceOperation}). `limit` and the four `'splice'`
+* caret components are POSITIVE integers (`integerShape({ min: 1 })`); `regex` / `exact` are
+* `optionalShape(booleanShape(...))`. The two REGISTRY arms — `workspaces` (list the workspaces
+* the model can move between) and `switch` (re-point the active one by `id`) — let a model
+* DISCOVER then CHOOSE which workspace the edit / read arms target.
+*/
+var workspaceToolShape = unionShape(objectShape({
+	operation: literalShape(["read"], { description: "Read a whole text file's text by path." }),
+	path: stringShape({ description: "The path of the file to read." })
+}), objectShape({ operation: literalShape(["list"], { description: "List every file in the workspace." }) }), objectShape({
+	operation: literalShape(["has"], { description: "Check whether a file exists at the path." }),
+	path: stringShape({ description: "The path to check for." })
+}), objectShape({
+	operation: literalShape(["search"], { description: "Search every text file for a query, returning each hit." }),
+	query: stringShape({ description: "The text (or regular-expression source) to search for." }),
+	regex: optionalShape(booleanShape({ description: "Treat the query as a regular expression. Defaults to false (a literal substring)." })),
+	exact: optionalShape(booleanShape({ description: "Match case-sensitively. Defaults to true (set false for case-insensitive)." })),
+	limit: optionalShape(integerShape({
+		min: 1,
+		description: "Stop after this many matches across all files. Omitted means unlimited."
+	}))
+}), objectShape({
+	operation: literalShape(["replace"], { description: "Replace a query with a replacement across every text file." }),
+	query: stringShape({ description: "The text (or regular-expression source) to replace." }),
+	replacement: stringShape({ description: "The text to substitute for each match." }),
+	regex: optionalShape(booleanShape({ description: "Treat the query as a regular expression. Defaults to false (a literal substring)." })),
+	exact: optionalShape(booleanShape({ description: "Match case-sensitively. Defaults to true (set false for case-insensitive)." })),
+	limit: optionalShape(integerShape({
+		min: 1,
+		description: "Stop after this many replacements across all files. Omitted means unlimited."
+	}))
+}), objectShape({
+	operation: literalShape(["write"], { description: "Create or overwrite a whole file with content." }),
+	path: stringShape({ description: "The path of the file to write." }),
+	content: stringShape({ description: "The full new contents of the file." })
+}), objectShape({
+	operation: literalShape(["splice"], { description: "Replace a 1-based range of an existing text file (from inclusive, to exclusive) with content." }),
+	path: stringShape({ description: "The path of the text file to edit." }),
+	content: stringShape({ description: "The text to splice in place of the range." }),
+	fromLine: integerShape({
+		min: 1,
+		description: "The 1-based start line of the range (inclusive)."
+	}),
+	fromColumn: integerShape({
+		min: 1,
+		description: "The 1-based start column of the range (inclusive; column 1 is the first character)."
+	}),
+	toLine: integerShape({
+		min: 1,
+		description: "The 1-based end line of the range (exclusive)."
+	}),
+	toColumn: integerShape({
+		min: 1,
+		description: "The 1-based end column of the range (exclusive)."
+	})
+}), objectShape({
+	operation: literalShape(["prepend"], { description: "Add content to the start of a file (creating it when absent)." }),
+	path: stringShape({ description: "The path of the file to prepend to." }),
+	content: stringShape({ description: "The text to add at the start of the file." })
+}), objectShape({
+	operation: literalShape(["append"], { description: "Add content to the end of a file (creating it when absent)." }),
+	path: stringShape({ description: "The path of the file to append to." }),
+	content: stringShape({ description: "The text to add at the end of the file." })
+}), objectShape({
+	operation: literalShape(["move"], { description: "Rename or move a file (overwriting an occupied target)." }),
+	from: stringShape({ description: "The current path of the file." }),
+	to: stringShape({ description: "The new path for the file." })
+}), objectShape({
+	operation: literalShape(["remove"], { description: "Delete a file from the workspace." }),
+	path: stringShape({ description: "The path of the file to remove." })
+}), objectShape({ operation: literalShape(["workspaces"], { description: "List the workspaces you can move between (each id, file count, and whether it is active), so you can pick an id to switch to." }) }), objectShape({
+	operation: literalShape(["switch"], { description: "Switch the active workspace to the one with this id (get ids from the \"workspaces\" operation). Edit and read operations then target it." }),
+	id: stringShape({ description: "The id of the workspace to make active (from the \"workspaces\" listing)." })
+}));
+//#endregion
+//#region src/core/helpers.ts
+/**
+* The ancestry identifier of a workflow in a run chain — `workflow:<id>`.
+*
+* @remarks
+* Namespacing keeps a workflow id and an {@link agentTag} agent name in ONE set without
+* collision, so re-entering a workflow OR an agent already in the chain is a single `includes`
+* check.
+*
+* @param id - The workflow definition's `id`
+* @returns The namespaced ancestry tag (`workflow:<id>`)
+*/
+function workflowTag(id) {
+	return `workflow:${id}`;
+}
+/**
+* The ancestry identifier of an agent in a run chain — `agent:<name>`.
+*
+* @remarks
+* The agent counterpart of {@link workflowTag}: {@link import('./factories.js').createAgentFunction}
+* / {@link import('./factories.js').createWorkflowTool} guard against re-entering an agent or
+* workflow already in the chain (a typed `DEPTH` `WorkflowError`, `@orkestrel/workflow`). The
+* `agent:` namespace keeps it distinct from a same-string workflow id.
+*
+* @param name - The agent's identifier / registry name
+* @returns The namespaced ancestry tag (`agent:<name>`)
+*/
+function agentTag(name) {
+	return `agent:${name}`;
+}
+/**
+* Build the plain success summary {@link import('./factories.js').createWorkflowTool} returns on
+* a completed run — the universal tool-handler contract (AGENTS §14): return a plain value on
+* success, appearing identically over BOTH the agent loop and MCP.
+*
+* @remarks
+* The summary is LEAN: the workflow's terminal `status` and the COUNT of settled task results —
+* enough for a caller / model to react without serializing the whole live tree. (It carries no
+* synthetic `id` / `name`: a tool handler has no call id; the `ToolManagerInterface`
+* (`@orkestrel/agent`) supplies the canonical envelope's identity.)
+*
+* @param result - The terminal `WorkflowResult` (`@orkestrel/workflow`) the run produced
+* @returns The plain success summary — `{ status, count }`
+*/
+function workflowToolSummary(result) {
+	return {
+		status: result.status,
+		count: result.results.length
+	};
+}
+/**
+* Complete a {@link WorkflowDraft} into a strict {@link WorkflowDefinition} — synthesize any
+* MISSING `id` deterministically + positionally, and default any MISSING `name` to its
+* (now-resolved) `id`.
+*
+* @remarks
+* The positional id scheme is stable and human-legible: the workflow is `wf`, phase `i` is
+* `phase-<i>`, and task `j` of that phase is `<phaseId>-task-<j>` (so a provided phase id flows
+* into its tasks' synthesized ids). A PROVIDED `id` / `name` at any level is kept VERBATIM —
+* synthesis touches only the omitted ones. A missing `name` defaults to the resolved `id` (never
+* the other way round), so the result always has both. `run`, `description`, the per-phase
+* `concurrency` / `bail`, the per-task `retries` / `timeout`, and the workflow `bail` carry over
+* unchanged. The result is a complete {@link WorkflowDefinition}; the caller still validates it
+* against the STRICT contract.
+*
+* @param draft - The draft workflow (id/name optional at all three levels)
+* @returns A complete {@link WorkflowDefinition} with every id/name filled
+*/
+function completeDraft(draft) {
+	const id = draft.id ?? "wf";
+	return {
+		id,
+		name: draft.name ?? id,
+		...draft.description === void 0 ? {} : { description: draft.description },
+		phases: draft.phases.map((phase, index) => completePhaseDraft(phase, index)),
+		...draft.bail === void 0 ? {} : { bail: draft.bail }
+	};
+}
+/**
+* Complete one {@link PhaseDraft} into a strict phase definition — the per-phase step of
+* {@link completeDraft} (phase `index` → `phase-<index>` when its id is omitted).
+*
+* @param phase - The draft phase
+* @param index - The phase's positional index in the workflow
+* @returns A complete phase definition
+*/
+function completePhaseDraft(phase, index) {
+	const id = phase.id ?? `phase-${index}`;
+	return {
+		id,
+		name: phase.name ?? id,
+		...phase.description === void 0 ? {} : { description: phase.description },
+		tasks: phase.tasks.map((task, taskIndex) => completeTaskDraft(task, id, taskIndex)),
+		...phase.concurrency === void 0 ? {} : { concurrency: phase.concurrency },
+		...phase.bail === void 0 ? {} : { bail: phase.bail }
+	};
+}
+/**
+* Complete one {@link TaskDraft} into a strict task definition — the per-task leaf step of
+* {@link completeDraft} (task `index` of phase `<phaseId>` → `<phaseId>-task-<index>` when its id
+* is omitted).
+*
+* @param task - The draft task
+* @param phaseId - The (resolved) parent phase id, so the synthesized task id nests under it
+* @param index - The task's positional index within its phase
+* @returns A complete task definition
+*/
+function completeTaskDraft(task, phaseId, index) {
+	const id = task.id ?? `${phaseId}-task-${index}`;
+	return {
+		id,
+		name: task.name ?? id,
+		...task.description === void 0 ? {} : { description: task.description },
+		...task.run === void 0 ? {} : { run: task.run },
+		...task.retries === void 0 ? {} : { retries: task.retries },
+		...task.timeout === void 0 ? {} : { timeout: task.timeout }
+	};
+}
+/**
+* Expand a flat {@link WorkflowSteps} blob into a strict {@link WorkflowDefinition} — each step
+* becomes a one-task phase, IN ORDER.
+*
+* @remarks
+* The expansion of the tool's ADVERTISED surface: the deliberately-reduced flat form. Each
+* {@link import('./types.js').WorkflowStep} maps to a phase holding exactly one task: the step's
+* `name` becomes the task's `run` (the behavior-registry key). Ids/names are auto-filled
+* positionally — it builds an ids-omitted {@link WorkflowDraft} and delegates to
+* {@link completeDraft}, so the two lenient surfaces share ONE synthesis path (step `i` → phase
+* `phase-<i>`, its task `phase-<i>-task-0`). The optional `name` becomes the workflow's `name`.
+* The result is a complete definition the caller validates against the STRICT contract before
+* running.
+*
+* @param flat - The flat steps blob (`{ name?, steps: [{ name }] }`)
+* @returns A complete {@link WorkflowDefinition} (one one-task phase per step)
+*/
+function expandSteps(flat) {
+	return completeDraft({
+		...flat.name === void 0 ? {} : { name: flat.name },
+		phases: flat.steps.map((step) => ({ tasks: [{ run: step.name }] }))
+	});
+}
+//#endregion
+//#region src/core/factories.ts
+/**
+* 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.
+*
+* @remarks
+* OWNED here now (ported from `@orkestrel/workflow`). Composes into a caller's
+* `WorkflowOptions.functions` registry like any other behavior
+* (`{ publish: createToolFunction(tools, 'publish') }`); the pure workflow runner has no
+* knowledge of tools itself. The returned function executes `name` against `tools` with the
+* task's `controller.input` as the call arguments, id-correlated to the task's own id. A
+* `ToolManagerInterface.execute` (`@orkestrel/agent`) NEVER throws (a handler throw is isolated
+* into `result.error`), so a failing tool is surfaced here as a THROWN `Error` carrying the
+* original message as `cause` — the leaf `fail`s, honouring `bail`. An UNREGISTERED tool name is
+* a programmer error (an explicit binding to a name that doesn't exist) — unlike the engine's
+* own silent auto-complete of an unresolved task handler, this THROWS a typed `TOOL`
+* `WorkflowError` (`@orkestrel/workflow`).
+*
+* @param tools - The `ToolManagerInterface` (`@orkestrel/agent`) the named tool is registered on
+* @param name - The registered tool's name
+* @returns A {@link WorkflowFunction} that runs the named tool
+*
+* @example
+* ```ts
+* import { createToolFunction } from '@src/core'
+* import { createToolManager } from '@orkestrel/agent'
+* import { createWorkflowRunner } from '@orkestrel/workflow'
+*
+* const tools = createToolManager()
+* tools.add(myPublishTool)
+* const runner = createWorkflowRunner()
+* await runner.execute(definition, { functions: { publish: createToolFunction(tools, 'publish') } })
+* ```
+*/
+function createToolFunction(tools, name) {
+	return async (controller) => {
+		if (tools.tool(name) === void 0) throw new WorkflowError("TOOL", `tool '${name}' is not registered`, { tool: name });
+		const result = await tools.execute({
+			id: controller.task.id,
+			name,
+			arguments: controller.input
+		});
+		if (result.error !== void 0) throw new Error(result.error, { cause: result.error });
+		return result.value;
+	};
+}
+/**
+* Wrap a live `AgentInterface` (`@orkestrel/agent`) as a {@link WorkflowFunction}
+* (`@orkestrel/workflow`) — the OPT-IN adapter that runs the agent to a settled result, folding
+* a nested workflow-authoring depth / cycle guard into its own closure.
+*
+* @remarks
+* OWNED here now (ported from `@orkestrel/workflow`). Composes into a caller's
+* `WorkflowOptions.functions` registry like any other behavior; the pure workflow runner has no
+* knowledge of agents itself. Before running the agent, the depth/cycle guard REJECTS the call
+* (a THROWN typed `DEPTH` `WorkflowError`, which the leaf `fail`s) when running it would push a
+* nested chain past {@link import('./constants.js').MAX_WORKFLOW_DEPTH}, OR when this agent is
+* already an ancestor (a cycle). When {@link import('./types.js').AgentFunctionOptions.runner}
+* is supplied, the adapter BINDS a depth/cycle-aware {@link createWorkflowTool} onto the agent's
+* `context.tools` (the propagation seam) — closed over `depth` and the extended ancestry (the
+* tool itself computes `depth + 1` internally) — so the agent can author + run a NESTED workflow
+* through it; the wrapped default is the CURRENT task's own workflow id (used only on a no-args
+* tool call). The task's cancellation folds into the agent run: an already-aborted
+* `controller.signal` cancels the agent up front; otherwise a one-shot listener fires
+* `agent.abort(reason)` when the task cancels, removed in `finally`. `agent.generate()` resolves
+* a partial `AgentResult` on a cancel (never rejects), returned as the task's completed value.
+*
+* A bound agent is effectively SINGLE-RUN: `context.tools.add` binds one `ToolInterface` under
+* the fixed {@link import('./constants.js').WORKFLOW_TOOL_NAME}, and `agent.generate()` /
+* `agent.abort()` are per-agent state. Two CONCURRENT tasks sharing the SAME `agent` instance
+* race on that one tool binding (last-write-wins) and on generate/abort — give each concurrent
+* task its OWN agent instance.
+*
+* @param agent - The live `AgentInterface` to run
+* @param options - The nested-workflow binding + depth/cycle bookkeeping (see {@link import('./types.js').AgentFunctionOptions})
+* @returns A {@link WorkflowFunction} that runs `agent` to its settled result
+*
+* @example
+* ```ts
+* import { createAgentFunction } from '@src/core'
+* import { createWorkflowRunner } from '@orkestrel/workflow'
+*
+* const runner = createWorkflowRunner()
+* const review = createAgentFunction(myAgent, { runner })
+* await runner.execute(definition, { functions: { review } })
+* ```
+*/
+function createAgentFunction(agent, options) {
+	return async (controller) => {
+		const depth = options?.depth ?? 0;
+		const ancestry = options?.ancestry ?? [];
+		if (depth + 1 > 8) throw new WorkflowError("DEPTH", `agent '${agent.id}' exceeds max workflow depth`, {
+			agent: agent.id,
+			depth,
+			max: 8
+		});
+		const tag = agentTag(agent.id);
+		if (ancestry.includes(tag)) throw new WorkflowError("DEPTH", `agent '${agent.id}' is already an ancestor (cycle)`, {
+			agent: agent.id,
+			ancestry: [...ancestry]
+		});
+		const runner = options?.runner;
+		if (runner !== void 0) {
+			const workflowId = controller.task.phase.workflow.id;
+			const wrapped = {
+				id: workflowId,
+				name: workflowId,
+				phases: []
+			};
+			agent.context.tools.add(createWorkflowTool(wrapped, runner, {
+				depth,
+				ancestry: [...ancestry, tag]
+			}));
+		}
+		const signal = controller.signal;
+		const onAbort = () => agent.abort(signal.reason);
+		if (signal.aborted) agent.abort(signal.reason);
+		else signal.addEventListener("abort", onAbort, { once: true });
+		try {
+			return await agent.generate();
+		} finally {
+			signal.removeEventListener("abort", onAbort);
+		}
+	};
+}
+/**
+* Compile the LENIENT workflow DRAFT contract — identical to `createWorkflowContract`
+* (`@orkestrel/workflow`) EXCEPT `id` and `name` are OPTIONAL at all three levels (workflow /
+* phase / task), so a small model can omit the six identity strings.
+*
+* @remarks
+* The widened authoring surface {@link createWorkflowTool} parses an authored blob through
+* before {@link import('./helpers.js').completeDraft} fills the missing ids/names. It does NOT
+* relax the canonical contract — `createWorkflowContract` (`@orkestrel/workflow`) stays
+* byte-for-byte unchanged and STRICT, and the completed draft is re-validated against THAT
+* strict gate before running (soundness preserved). A PROVIDED `id` / `name` still carries
+* `minLength: 1`, so an explicitly-empty `id: ''` is REJECTED (parses to `undefined`), never
+* auto-filled — keeping "garbage" distinct from "omitted". `run` stays optional (a plain name
+* string).
+*
+* @returns The compiled {@link import('./types.js').WorkflowDraft} contract
+*
+* @example
+* ```ts
+* import { createWorkflowDraftContract, completeDraft } from '@src/core'
+*
+* const draft = createWorkflowDraftContract()
+* const parsed = draft.parse({ phases: [{ tasks: [{ run: 'compile' }] }] })
+* const definition = parsed && completeDraft(parsed) // ids/names filled positionally
+* draft.parse({ id: '', phases: [] }) // undefined — an explicit empty id is rejected
+* ```
+*/
+function createWorkflowDraftContract() {
+	return createContract(workflowDraftShape);
+}
+/**
+* Wrap a {@link WorkflowDefinition} as an LLM-callable tool — it ADVERTISES the SIMPLE flat
+* authoring shape (`{ name?, steps: [{ name }] }`) as its `parameters` so even a small model can
+* author a complete tree, and its handler EXPANDS / COMPLETES the authored blob, validates it
+* against the STRICT contract, runs it through `runner`, and, when
+* {@link import('./types.js').WorkflowToolOptions.store} is supplied, PERSISTS each executed
+* workflow's final snapshot after the run settles.
+*
+* @remarks
+* A plain `ToolManagerInterface`-compatible tool (`@orkestrel/agent`), reproducing
+* `@orkestrel/workflow`'s former call contract exactly (flat / draft / full authoring forms, the
+* strict soundness gate, the depth/cycle guard). It is ALSO the propagation carrier
+* {@link createAgentFunction} binds onto a wrapped agent's `context.tools`: because a tool
+* handler receives ONLY the model-supplied `args` (no ambient context, no signal), the run's
+* depth + ancestry are CLOSED OVER at bind time via {@link import('./types.js').WorkflowToolOptions},
+* and the handler enforces the SAME depth / cycle guard itself before running the nested
+* workflow at `depth + 1` with the extended ancestry.
+*
+* **Widened authoring surface (additive — the canonical contract + runner stay STRICT and
+* unchanged).** A 2B model reliably CALLS the tool but cannot reliably emit the full four-level
+* nested {@link WorkflowDefinition} (six required `id`/`name` strings, an all-or-nothing tree).
+* So the tool ACCEPTS three authoring forms and converges them on the SAME strict
+* `createWorkflowContract` gate before running (soundness preserved):
+* - the FLAT shape `{ name?, steps: [{ name }] }` — the ADVERTISED `parameters` (the simplest
+*   form, {@link import('./helpers.js').expandSteps}'d into one one-task phase per step);
+* - a nested DRAFT with any `id`/`name` OMITTED — {@link createWorkflowDraftContract}-parsed then
+*   {@link import('./helpers.js').completeDraft}'d (missing ids synthesized positionally);
+* - the full nested {@link WorkflowDefinition} — the advanced escape-hatch, accepted as the draft
+*   super-set.
+*
+* The universal tool-handler contract (AGENTS §14): returns the plain run summary
+* (`{ status, count }`) on success, THROWS a typed `WorkflowError` (`@orkestrel/workflow`) on
+* every failure path — malformed authored args (`TOOL`), or an over-deep / cyclic nested run
+* (`DEPTH`). The `ToolManagerInterface` isolates every throw into the canonical tool result's
+* top-level `error`, so nothing escapes the run. `options.depth` / `options.ancestry` are the
+* propagation carrier across a workflow → agent → workflow chain; `options.store` is this
+* package's ADDITION — the persisted snapshot is retrievable via the store afterwards (a caller
+* restores it through `@orkestrel/workflow`'s own `Workflow.restore` / store-backed factories).
+*
+* @param definition - The workflow the tool runs when called with no authored args
+* @param runner - The `WorkflowRunnerInterface` (`@orkestrel/workflow`) that executes the (nested) workflow
+* @param options - Depth/ancestry bookkeeping plus the optional durable store (see {@link import('./types.js').WorkflowToolOptions})
+* @returns A `ToolInterface` (named {@link import('./constants.js').WORKFLOW_TOOL_NAME}) whose
+*   `parameters` advertise the flat authoring schema
+*
+* @example
+* ```ts
+* import { createWorkflowTool } from '@src/core'
+* import { createWorkflowRunner, createMemoryWorkflowStore } from '@orkestrel/workflow'
+* import { createToolManager } from '@orkestrel/agent'
+*
+* const runner = createWorkflowRunner()
+* const store = createMemoryWorkflowStore()
+* const tool = createWorkflowTool(definition, runner, { store })
+* const tools = createToolManager()
+* tools.add(tool) // authored runs are now persisted to `store` on settle
+* ```
+*/
+function createWorkflowTool(definition, runner, options) {
+	const strict = createWorkflowContract();
+	const draft = createWorkflowDraftContract();
+	const steps = createContract(workflowStepsShape);
+	const depth = options?.depth ?? 0;
+	const ancestry = options?.ancestry ?? [];
+	const store = options?.store;
+	return createTool({
+		name: WORKFLOW_TOOL_NAME,
+		description: WORKFLOW_TOOL_DESCRIPTION,
+		summary: WORKFLOW_TOOL_SUMMARY,
+		parameters: schemaToParameters(steps.schema),
+		execute: async (args) => {
+			let target;
+			if (Object.keys(args).length === 0) target = definition;
+			else if (Array.isArray(args.steps)) {
+				const flat = steps.parse(args);
+				target = flat === void 0 ? void 0 : expandSteps(flat);
+			} else {
+				const parsed = draft.parse(args);
+				target = parsed === void 0 ? void 0 : completeDraft(parsed);
+			}
+			if (target === void 0 || !strict.is(target)) throw new WorkflowError("TOOL", "malformed workflow definition", { workflow: definition.id });
+			if (depth + 1 > 8) throw new WorkflowError("DEPTH", `nested workflow exceeds max depth 8`, {
+				workflow: target.id,
+				depth,
+				max: 8
+			});
+			const tag = workflowTag(target.id);
+			if (ancestry.includes(tag)) throw new WorkflowError("DEPTH", `workflow '${target.id}' is already an ancestor (cycle)`, {
+				workflow: target.id,
+				ancestry: [...ancestry]
+			});
+			const result = await runner.execute(target);
+			if (store !== void 0) await store.set(result.workflow.snapshot());
+			return workflowToolSummary(result);
+		}
+	});
+}
+/**
+* Build an LLM-callable workspace-editing tool — it ADVERTISES the `operation`-discriminated
+* 13-op union ({@link import('./shapers.js').workspaceToolShape}) as its `parameters`, and its
+* handler PARSES the model-supplied args against that contract and DISPATCHES the matched
+* operation against the manager's ACTIVE workspace (the registry ops drive the manager itself),
+* returning the plain result (throwing a typed `WorkspaceError`, `@orkestrel/agent`, on
+* failure). EITHER drives a caller-supplied {@link WorkspaceToolOptions.manager} directly, OR
+* constructs a fresh `WorkspaceManagerInterface` (`@orkestrel/agent`) over
+* {@link import('./types.js').WorkspaceToolOptions.store} (via `@orkestrel/agent`'s
+* `createWorkspaceManager`); neither given constructs a manager backed by `@orkestrel/agent`'s
+* in-memory store default.
+*
+* @remarks
+* MANAGER-DRIVEN: every edit / read op (read / list / has / search / replace / write / splice /
+* prepend / append / move / remove) targets `manager.active`, so the model edits whichever
+* workspace is active and a host can re-point it (`WorkspaceManagerInterface.switch`) between
+* turns. Two REGISTRY ops make the model self-sufficient: `workspaces` LISTS the registered
+* workspaces (each `{ id, files, active }`) so it can discover an id, and `switch` re-points the
+* active workspace by id (lenient — an unknown id is a no-op reporting `switched: false`, never a
+* throw).
+*
+* NO-ACTIVE RULE (the ergonomic seam): a WRITING op (write / splice / prepend / append / move /
+* remove / replace) run when `manager.active` is `undefined` AUTO-CREATES + activates a default
+* workspace (`manager.add()`) so the model can just start writing; a pure-READ op (read / list /
+* has / search) against no active workspace returns the EMPTY result (`undefined` / `[]` /
+* `false`), never creating one and never throwing.
+*
+* The handler conforms to the universal tool-handler contract (AGENTS §14): it `contract.parse`s
+* the args, THROWS a `TOOL` `WorkspaceError` when no operation arm matched (a malformed / unknown
+* operation), else `switch`es on `op.operation` and RETURNS the plain result — letting a
+* `WorkspaceError` raised by the live workspace (`MODALITY` / `PATTERN` / `RANGE`) PROPAGATE
+* uncaught. The range edit is the FLAT `'splice'` op: its four flat caret integers are
+* reassembled into a `Range` (`@orkestrel/agent`) by `rangeOf` and fed to the workspace's ranged
+* `write`.
+*
+* @param options - `manager` (drive directly) OR `store` (build a manager over it); neither ⇒
+*   an in-memory-backed manager (see {@link import('./types.js').WorkspaceToolOptions})
+* @returns A `ToolInterface` (named {@link import('./constants.js').WORKSPACE_TOOL_NAME} by default)
+*
+* @example
+* ```ts
+* import { createWorkspaceTool } from '@src/core'
+* import { createToolManager } from '@orkestrel/agent'
+*
+* const tool = createWorkspaceTool() // in-memory workspace, no persistence
+* const tools = createToolManager()
+* tools.add(tool)
+* ```
+*/
+function createWorkspaceTool(options) {
+	const manager = options?.manager ?? createWorkspaceManager(options?.store === void 0 ? void 0 : { store: options.store });
+	const contract = createContract(workspaceToolShape);
+	const parameters = schemaToParameters(contract.schema);
+	return createTool({
+		name: options?.name ?? "workspace",
+		description: options?.description ?? WORKSPACE_TOOL_DESCRIPTION,
+		summary: WORKSPACE_TOOL_SUMMARY,
+		parameters,
+		execute: (args) => {
+			const op = contract.parse(args);
+			if (op === void 0) throw new WorkspaceError("TOOL", `unknown or malformed operation`, { args });
+			if (op.operation === "workspaces") {
+				const activeId = manager.active?.id;
+				return manager.workspaces().map((workspace) => ({
+					id: workspace.id,
+					files: workspace.count,
+					active: workspace.id === activeId
+				}));
+			}
+			if (op.operation === "switch") {
+				const switched = manager.switch(op.id);
+				return switched === void 0 ? {
+					id: op.id,
+					switched: false
+				} : {
+					id: switched.id,
+					switched: true,
+					files: switched.count
+				};
+			}
+			const active = manager.active;
+			switch (op.operation) {
+				case "read": return active?.read(op.path);
+				case "list": return (active?.files() ?? []).map((file) => ({
+					path: file.path,
+					state: file.state,
+					size: file.size,
+					lines: file.lines,
+					kind: isText(file.content) ? "text" : "binary"
+				}));
+				case "has": return active?.has(op.path) ?? false;
+				case "search": return active?.search(op.query, {
+					regex: op.regex,
+					exact: op.exact,
+					limit: op.limit
+				}) ?? [];
+				case "replace": return (active ?? manager.add()).replace(op.query, op.replacement, {
+					regex: op.regex,
+					exact: op.exact,
+					limit: op.limit
+				});
+				case "write": {
+					const workspace = active ?? manager.add();
+					workspace.write(op.path, op.content);
+					return {
+						path: op.path,
+						state: workspace.file(op.path)?.state
+					};
+				}
+				case "splice": {
+					const workspace = active ?? manager.add();
+					workspace.write(op.path, op.content, rangeOf(op.fromLine, op.fromColumn, op.toLine, op.toColumn));
+					return {
+						path: op.path,
+						state: workspace.file(op.path)?.state
+					};
+				}
+				case "prepend": {
+					const workspace = active ?? manager.add();
+					workspace.prepend(op.path, op.content);
+					return {
+						path: op.path,
+						state: workspace.file(op.path)?.state
+					};
+				}
+				case "append": {
+					const workspace = active ?? manager.add();
+					workspace.append(op.path, op.content);
+					return {
+						path: op.path,
+						state: workspace.file(op.path)?.state
+					};
+				}
+				case "move": {
+					const workspace = active ?? manager.add();
+					return {
+						from: op.from,
+						to: op.to,
+						moved: workspace.move(op.from, op.to)
+					};
+				}
+				case "remove": {
+					const workspace = active ?? manager.add();
+					return {
+						path: op.path,
+						removed: workspace.remove(op.path)
+					};
+				}
+			}
+		}
+	});
+}
+/**
+* Build an LLM-callable sub-agent delegation tool — resolves a live, seeded `AgentInterface`
+* from `registry` and runs it to completion for ONE delegated `task`.
+*
+* @remarks
+* The universal tool-handler contract (AGENTS §14): validates the call args against
+* {@link import('./shapers.js').agentToolShape}, assembles an `AgentJobInput` (`task` seeds the
+* sub-agent's conversation as a single `user` message; `provider` / `tools` / `system` fall
+* back to the tool's own {@link import('./types.js').AgentToolOptions} defaults), rehydrates the sub-agent via
+* `registry.build`, runs it with `agent.generate()`, and returns the settled
+* `AgentResult.content` string (the sub-agent's final text). A missing / unresolvable `provider`, or a malformed call, THROWS a typed `TOOL`
+* {@link import('./errors.js').AgentToolError}; a delegation that would exceed
+* {@link import('./constants.js').AGENT_TOOL_DEPTH}, or re-enter an already-delegated agent (a
+* cycle), THROWS a typed `DEPTH` {@link import('./errors.js').AgentToolError} — both isolated
+* by the `ToolManagerInterface` into the canonical tool result's top-level `error`.
+*
+* `AgentInterface` (`@orkestrel/agent`) exposes no teardown method — a bound sub-agent's
+* lifetime is the single `generate()` call this handler awaits; there is nothing to release
+* afterwards (unlike a store-backed resource, its state lives entirely in the resolved
+* `AgentContextInterface`, owned by the caller's registry).
+*
+* @param registry - The `AgentRegistryInterface` a delegated job resolves against (providers,
+*   tools, authorities, schedulers, and the `build` rehydration seam)
+* @param options - Delegation defaults, depth/ancestry bookkeeping, and advertised overrides
+*   (see {@link import('./types.js').AgentToolOptions})
+* @returns A `ToolInterface` (named {@link import('./constants.js').AGENT_TOOL_NAME} by default)
+*
+* @example
+* ```ts
+* import { createAgentTool } from '@src/core'
+* import { createAgentRegistry, createToolManager } from '@orkestrel/agent'
+*
+* const registry = createAgentRegistry({ providers: { openai: myProvider } })
+* const tool = createAgentTool(registry, { provider: 'openai' })
+* const tools = createToolManager()
+* tools.add(tool) // a model can now delegate a task to a sub-agent
+* ```
+*/
+function createAgentTool(registry, options) {
+	const contract = createContract(agentToolShape);
+	const parameters = schemaToParameters(contract.schema);
+	const depth = options?.depth ?? 0;
+	const ancestry = options?.ancestry ?? [];
+	return createTool({
+		name: options?.name ?? "agent",
+		description: options?.description ?? AGENT_TOOL_DESCRIPTION,
+		summary: AGENT_TOOL_SUMMARY,
+		parameters,
+		execute: async (args) => {
+			const call = contract.parse(args);
+			if (call === void 0) throw new AgentToolError("TOOL", "malformed agent-delegation call", { args });
+			const provider = call.provider ?? options?.provider;
+			if (provider === void 0) throw new AgentToolError("TOOL", "no provider resolved for the delegated agent", { task: call.task });
+			if (depth + 1 > 8) throw new AgentToolError("DEPTH", `delegation exceeds max agent depth 8`, {
+				provider,
+				depth,
+				max: 8
+			});
+			const tag = agentTag(provider);
+			if (ancestry.includes(tag)) throw new AgentToolError("DEPTH", `agent '${provider}' is already an ancestor (cycle)`, {
+				provider,
+				ancestry: [...ancestry]
+			});
+			const tools = call.tools ?? options?.tools;
+			const system = call.system ?? options?.system;
+			const agent = registry.build({
+				provider,
+				messages: [{
+					role: "user",
+					content: call.task
+				}],
+				...system === void 0 ? {} : { system },
+				...tools === void 0 ? {} : { tools }
+			});
+			const result = await agent.generate();
+			if (options?.store !== void 0) {
+				const active = agent.context.conversations.active;
+				if (active !== void 0) await options.store.set(active.snapshot());
+			}
+			return result.content;
+		}
+	});
+}
+/**
+* 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
+* (`AGENT_TOOL_SUMMARY` / `WORKFLOW_TOOL_SUMMARY` / `WORKSPACE_TOOL_SUMMARY`).
+*
+* @remarks
+* `ToolManagerInterface.definitions()` (`@orkestrel/agent`) advertises `tool.summary ??
+* tool.description` — a lean one-sentence summary stands in for a tool's full teaching
+* description when `summary` is set, keeping the advertised tool list compact for a small model.
+* This tool is the on-demand expansion seam: given a registered tool's `name`, it looks the tool
+* up via `tools.tool(name)` and returns its full `description` (falling back to `summary` when a
+* tool has no `description` of its own, then a placeholder when it has neither).
+*
+* The universal tool-handler contract (AGENTS §14): validates the call args against
+* {@link import('./shapers.js').describeToolShape}, RETURNS the plain description string on
+* success, THROWS a typed `TOOL` {@link import('./errors.js').AgentToolError} on a malformed call
+* or an unknown tool name.
+*
+* @param tools - The `ToolManagerInterface` (`@orkestrel/agent`) whose registered tools this
+*   tool can describe
+* @returns A `ToolInterface` (named {@link import('./constants.js').DESCRIBE_TOOL_NAME})
+*
+* @example
+* ```ts
+* import { createDescribeTool, createWorkflowTool } from '@src/core'
+* import { createToolManager } from '@orkestrel/agent'
+*
+* const tools = createToolManager()
+* tools.add(createWorkflowTool(definition, runner))
+* tools.add(createDescribeTool(tools))
+* const full = await tools.execute({ id: '1', name: 'describe', arguments: { name: 'workflow' } })
+* full.value // the workflow tool's full teaching description
+* ```
+*/
+function createDescribeTool(tools) {
+	const contract = createContract(describeToolShape);
+	return createTool({
+		name: DESCRIBE_TOOL_NAME,
+		description: DESCRIBE_TOOL_DESCRIPTION,
+		summary: DESCRIBE_TOOL_SUMMARY,
+		parameters: schemaToParameters(contract.schema),
+		execute: async (args) => {
+			const call = contract.parse(args);
+			if (call === void 0) throw new AgentToolError("TOOL", "malformed describe call", { args });
+			const tool = tools.tool(call.name);
+			if (tool === void 0) throw new AgentToolError("TOOL", `unknown tool '${call.name}'`, { name: call.name });
+			return tool.description ?? tool.summary ?? "<no description>";
+		}
+	});
+}
+//#endregion
+export { AGENT_TOOL_DEPTH, AGENT_TOOL_DESCRIPTION, AGENT_TOOL_NAME, AGENT_TOOL_SUMMARY, AgentToolError, DESCRIBE_TOOL_DESCRIPTION, DESCRIBE_TOOL_NAME, DESCRIBE_TOOL_SUMMARY, MAX_WORKFLOW_DEPTH, 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, completeDraft, completePhaseDraft, completeTaskDraft, createAgentFunction, createAgentTool, createDescribeTool, createToolFunction, createWorkflowDraftContract, createWorkflowTool, createWorkspaceTool, describeToolShape, expandSteps, isAgentToolError, phaseDraftShape, stepShape, taskDraftShape, workflowDraftShape, workflowStepsShape, workflowTag, workflowToolSummary, workspaceToolShape };
+
+//# sourceMappingURL=index.js.map