@orkestrel/tool 0.0.1

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

@@ -0,0 +1,1180 @@
+import { AgentInterface } from '@orkestrel/agent';
+import { AgentRegistryInterface } from '@orkestrel/agent';
+import { ArrayShape } from '@orkestrel/contract';
+import { BooleanShape } from '@orkestrel/contract';
+import { ContractInterface } from '@orkestrel/contract';
+import { ConversationStoreInterface } from '@orkestrel/agent';
+import { LiteralShape } from '@orkestrel/contract';
+import { NumberShape } from '@orkestrel/contract';
+import { ObjectShape } from '@orkestrel/contract';
+import { OptionalShape } from '@orkestrel/contract';
+import { StringShape } from '@orkestrel/contract';
+import { ToolInterface } from '@orkestrel/agent';
+import { ToolManagerInterface } from '@orkestrel/agent';
+import { UnionShape } from '@orkestrel/contract';
+import { WorkflowDefinition } from '@orkestrel/workflow';
+import { WorkflowFunction } from '@orkestrel/workflow';
+import { WorkflowResult } from '@orkestrel/workflow';
+import { WorkflowRunnerInterface } from '@orkestrel/workflow';
+import { WorkflowStatus } from '@orkestrel/workflow';
+import { WorkflowStoreInterface } from '@orkestrel/workflow';
+import { WorkspaceManagerInterface } from '@orkestrel/agent';
+import { WorkspaceStoreInterface } from '@orkestrel/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.
+ */
+export declare const AGENT_TOOL_DEPTH = 8;
+
+export declare const AGENT_TOOL_DESCRIPTION: string;
+
+/**
+ * The name {@link import('./factories.js').createAgentTool} advertises by default — the key a
+ * model calls and the `ToolManagerInterface` (`@orkestrel/agent`) registers under.
+ */
+export declare const AGENT_TOOL_NAME = "agent";
+
+/**
+ * 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}.
+ */
+export declare const 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.";
+
+/**
+ * Options for {@link import('./factories.js').createAgentFunction} — the OPT-IN adapter that
+ * wraps a live `AgentInterface` (`@orkestrel/agent`) as a `WorkflowFunction`
+ * (`@orkestrel/workflow`), folding a nested workflow-authoring depth / cycle guard into its
+ * closure.
+ *
+ * @remarks
+ * All fields are optional: omitted entirely, the adapter runs the agent with no nested workflow
+ * tool bound and no depth/cycle bound (depth `0`, empty ancestry).
+ * - `runner` — when supplied, the adapter BINDS a depth/cycle-aware
+ *   {@link import('./factories.js').createWorkflowTool} onto the agent's `context.tools` (the
+ *   propagation seam), so the agent can author + run a NESTED workflow through it. Omitted ⇒ the
+ *   agent runs with no workflow tool bound.
+ * - `depth` — this invocation's nesting depth (default `0`); the bound workflow tool runs its
+ *   nested workflow at `depth + 1`, bounded by
+ *   {@link import('./constants.js').MAX_WORKFLOW_DEPTH}.
+ * - `ancestry` — the workflow / agent identifiers already in this run chain (default empty); a
+ *   cycle (this agent already present) is rejected with a typed `DEPTH` `WorkflowError`
+ *   (`@orkestrel/workflow`).
+ */
+export declare interface AgentFunctionOptions {
+    readonly runner?: WorkflowRunnerInterface;
+    readonly depth?: number;
+    readonly ancestry?: readonly string[];
+}
+
+/**
+ * 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>`)
+ */
+export declare function agentTag(name: string): string;
+
+/**
+ * The FLAT args {@link import('./factories.js').createAgentTool} accepts — a delegated `task`
+ * plus the minimal optional `AgentJobInput` (`@orkestrel/agent`) fields a caller may override
+ * per-call.
+ *
+ * @remarks
+ * `task` becomes the seed user message in the sub-agent's rehydrated conversation
+ * (`AgentJobInput.messages`). `provider` / `tools` / `system` shadow the tool's own
+ * {@link AgentToolOptions} defaults for this ONE call when supplied.
+ */
+export declare interface AgentToolArguments {
+    readonly task: string;
+    readonly provider?: string;
+    readonly tools?: readonly string[];
+    readonly system?: string;
+}
+
+/**
+ * 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'
+ * }
+ * ```
+ */
+export declare class AgentToolError extends Error {
+    readonly code: AgentToolErrorCode;
+    readonly context?: Readonly<Record<string, unknown>>;
+    constructor(code: AgentToolErrorCode, message: string, context?: Readonly<Record<string, unknown>>);
+}
+
+/**
+ * The error CODE a thrown {@link import('./errors.js').AgentToolError} carries — the SAME
+ * two-code shape `@orkestrel/workflow`'s `WorkflowError` uses for its own tool guard, kept
+ * distinct per package (AGENTS §14: a thrown, typed, code-bearing error, never a `{ error }`
+ * return).
+ *
+ * @remarks
+ * `TOOL` — malformed / unresolvable call args (a missing `task`, no resolvable `provider`).
+ * `DEPTH` — the delegation would exceed {@link import('./constants.js').AGENT_TOOL_DEPTH}, or
+ * the resolved agent is already an ancestor (a cycle).
+ */
+export declare type AgentToolErrorCode = 'TOOL' | 'DEPTH';
+
+/**
+ * Options for {@link import('./factories.js').createAgentTool} — the sub-agent delegation
+ * defaults, the nesting-depth / cycle guard bookkeeping, and the advertised tool overrides.
+ *
+ * @remarks
+ * - `name` / `description` — advertised tool overrides; default to
+ *   {@link import('./constants.js').AGENT_TOOL_NAME} / {@link import('./constants.js').AGENT_TOOL_DESCRIPTION}.
+ * - `provider` — the DEFAULT registry provider key used when a call omits `provider`; a call
+ *   that supplies its own `provider` overrides this. One of `provider` (here or per-call) MUST
+ *   resolve, or the handler throws a typed `TOOL` {@link import('./errors.js').AgentToolError}.
+ * - `tools` — the DEFAULT registry tool-name list loaded into the delegated sub-agent; a
+ *   per-call `tools` list overrides (never merges with) this default.
+ * - `system` — the DEFAULT system prompt seeding the sub-agent's context; a per-call `system`
+ *   overrides this.
+ * - `depth` — this invocation's nesting depth (default `0`); a delegated sub-agent that itself
+ *   calls this tool again runs at `depth + 1`, bounded by
+ *   {@link import('./constants.js').AGENT_TOOL_DEPTH}.
+ * - `ancestry` — the sub-agent identifiers already in this delegation chain (default empty); a
+ *   cycle (the resolved agent already present) is rejected with a typed `DEPTH`
+ *   {@link import('./errors.js').AgentToolError}.
+ * - `store` — this package's ADDITION: when supplied, the handler persists the delegated
+ *   sub-agent's active conversation snapshot (`store.set(agent.context.conversations.active.snapshot())`)
+ *   once `agent.generate()` settles successfully, before returning — one snapshot per delegation
+ *   (each `registry.build` mints a fresh conversation id, so a shared store accumulates an
+ *   audit log rather than colliding). Omitted ⇒ no persistence from this tool.
+ *
+ * Conversation persistence for a delegated sub-agent has TWO independent seams, composable
+ * together: this `store` slot persists EACH delegation's conversation individually, and/or an
+ * `AgentRegistryInterface` built with `AgentRegistryOptions.store` (`@orkestrel/agent`) backs
+ * EVERY agent it builds — including ones built through this tool — with a store-backed
+ * `ConversationManagerInterface` of its own. Neither is required; either or both may be used.
+ */
+export declare interface AgentToolOptions {
+    readonly name?: string;
+    readonly description?: string;
+    readonly provider?: string;
+    readonly tools?: readonly string[];
+    readonly system?: string;
+    readonly depth?: number;
+    readonly ancestry?: readonly string[];
+    readonly store?: ConversationStoreInterface;
+}
+
+/**
+ * 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.
+ */
+export declare const agentToolShape: ObjectShape<{
+    task: StringShape;
+    provider: OptionalShape<StringShape>;
+    tools: OptionalShape<ArrayShape<StringShape>>;
+    system: OptionalShape<StringShape>;
+}>;
+
+/**
+ * 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
+ */
+export declare function completeDraft(draft: WorkflowDraft): WorkflowDefinition;
+
+/**
+ * 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
+ */
+export declare function completePhaseDraft(phase: PhaseDraft, index: number): WorkflowDefinition['phases'][number];
+
+/**
+ * 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
+ */
+export declare function completeTaskDraft(task: TaskDraft, phaseId: string, index: number): WorkflowDefinition['phases'][number]['tasks'][number];
+
+/**
+ * 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 } })
+ * ```
+ */
+export declare function createAgentFunction(agent: AgentInterface, options?: AgentFunctionOptions): WorkflowFunction;
+
+/**
+ * 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
+ * ```
+ */
+export declare function createAgentTool(registry: AgentRegistryInterface, options?: AgentToolOptions): ToolInterface;
+
+/**
+ * Build an LLM-callable tool that returns the FULL `description` of another registered tool by
+ * name — the counterpart to the lean `summary` the other tools in this package advertise
+ * (`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
+ * ```
+ */
+export declare function createDescribeTool(tools: ToolManagerInterface): ToolInterface;
+
+/**
+ * Wrap a registered tool as a {@link WorkflowFunction} (`@orkestrel/workflow`) — the OPT-IN
+ * adapter that lets a `function`-form task run a `@orkestrel/agent` tool BY NAME.
+ *
+ * @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') } })
+ * ```
+ */
+export declare function createToolFunction(tools: ToolManagerInterface, name: string): WorkflowFunction;
+
+/**
+ * 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
+ * ```
+ */
+export declare function createWorkflowDraftContract(): ContractInterface<WorkflowDraft>;
+
+/**
+ * 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
+ * ```
+ */
+export declare function createWorkflowTool(definition: WorkflowDefinition, runner: WorkflowRunnerInterface, options?: WorkflowToolOptions): ToolInterface;
+
+/**
+ * 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)
+ * ```
+ */
+export declare function createWorkspaceTool(options?: WorkspaceToolOptions): ToolInterface;
+
+/**
+ * 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.
+ */
+export declare const 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).";
+
+/**
+ * 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.
+ */
+export declare const 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.
+ */
+export declare const DESCRIBE_TOOL_SUMMARY = "Return the full description of a named registered tool.";
+
+/**
+ * The FLAT args {@link import('./factories.js').createDescribeTool} accepts — the registered
+ * tool `name` whose full `description` a model wants back.
+ *
+ * @remarks
+ * `name` must match a tool registered on the {@link import('@orkestrel/agent').ToolManagerInterface}
+ * the describe tool was built over — it is looked up via `tools.tool(name)`.
+ */
+export declare interface DescribeToolArguments {
+    readonly name: string;
+}
+
+/**
+ * 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.
+ */
+export declare const describeToolShape: ObjectShape<{
+    name: StringShape;
+}>;
+
+/**
+ * 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)
+ */
+export declare function expandSteps(flat: WorkflowSteps): WorkflowDefinition;
+
+/**
+ * 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)
+ * }
+ * ```
+ */
+export declare function isAgentToolError(value: unknown): value is AgentToolError;
+
+/**
+ * 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`).
+ */
+export declare const MAX_WORKFLOW_DEPTH = 8;
+
+/** A draft phase — a `PhaseDefinition` (`@orkestrel/workflow`) with OPTIONAL `id` / `name` and {@link TaskDraft} tasks. */
+export declare interface PhaseDraft {
+    readonly id?: string;
+    readonly name?: string;
+    readonly description?: string;
+    readonly tasks: readonly TaskDraft[];
+    /** Max tasks in flight at once (a resource throttle); omitted ⇒ unbounded. */
+    readonly concurrency?: number;
+    /** The per-phase failure-policy OVERRIDE; omitted ⇒ inherits the workflow `bail`. */
+    readonly bail?: boolean;
+}
+
+/**
+ * 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.
+ */
+export declare const phaseDraftShape: ObjectShape<{
+    id: OptionalShape<StringShape>;
+    name: OptionalShape<StringShape>;
+    description: OptionalShape<StringShape>;
+    tasks: ArrayShape<ObjectShape<{
+        id: OptionalShape<StringShape>;
+        name: OptionalShape<StringShape>;
+        description: OptionalShape<StringShape>;
+        run: OptionalShape<StringShape>;
+        retries: OptionalShape<NumberShape>;
+        timeout: OptionalShape<NumberShape>;
+    }>>;
+    concurrency: OptionalShape<NumberShape>;
+    bail: OptionalShape<LiteralShape<readonly [true, false]>>;
+}>;
+
+/**
+ * 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}).
+ */
+export declare const stepShape: ObjectShape<{
+    name: StringShape;
+}>;
+
+/**
+ * A draft task — a `TaskDefinition` (`@orkestrel/workflow`) with OPTIONAL `id` / `name`.
+ *
+ * @remarks
+ * The tool synthesizes a missing `id` positionally and defaults a missing `name` to its `id`
+ * ({@link import('./helpers.js').completeDraft}). A PROVIDED `id` / `name` is preserved verbatim
+ * (and must be non-empty — the draft contract's `minLength: 1`).
+ */
+export declare interface TaskDraft {
+    readonly id?: string;
+    readonly name?: string;
+    readonly description?: string;
+    /** The behavior reference — a registry key resolved against a workflow's functions registry at construction; omitted ⇒ no handler. */
+    readonly run?: string;
+    /** Extra attempts after the first on failure (a non-negative integer); overrides the phase Runner default. Execution-only. */
+    readonly retries?: number;
+    /** The per-attempt deadline in milliseconds (a non-negative integer); overrides the phase Runner default. Execution-only. */
+    readonly timeout?: number;
+}
+
+/**
+ * The shape of a {@link import('./types.js').TaskDraft} — identical to a strict task shape
+ * EXCEPT `id` and `name` are OPTIONAL.
+ */
+export declare const taskDraftShape: ObjectShape<{
+    id: OptionalShape<StringShape>;
+    name: OptionalShape<StringShape>;
+    description: OptionalShape<StringShape>;
+    run: OptionalShape<StringShape>;
+    retries: OptionalShape<NumberShape>;
+    timeout: OptionalShape<NumberShape>;
+}>;
+
+export declare const WORKFLOW_TOOL_DESCRIPTION: string;
+
+/**
+ * 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}.
+ */
+export declare const WORKFLOW_TOOL_FLAT_EXAMPLE: WorkflowSteps;
+
+/**
+ * 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}).
+ */
+export declare const WORKFLOW_TOOL_NAME = "workflow";
+
+/**
+ * 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.
+ */
+export declare const WORKFLOW_TOOL_NESTED_EXAMPLE: WorkflowDefinition;
+
+/**
+ * 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}.
+ */
+export declare const WORKFLOW_TOOL_SUMMARY = "Author and run a multi-phase workflow in one call \u2014 phases run in sequence, tasks within a phase run concurrently. Call describe('workflow') for the full authoring schema and examples.";
+
+/**
+ * A draft workflow — a `WorkflowDefinition` (`@orkestrel/workflow`) with OPTIONAL `id` / `name`
+ * at all three levels (workflow / phase / task).
+ *
+ * @remarks
+ * The lenient authoring form {@link import('./factories.js').createWorkflowDraftContract}
+ * validates and {@link import('./helpers.js').completeDraft} completes into a strict
+ * `WorkflowDefinition`. `run` stays optional (a plain name string); the `bail` policy carries
+ * over.
+ */
+export declare interface WorkflowDraft {
+    readonly id?: string;
+    readonly name?: string;
+    readonly description?: string;
+    readonly phases: readonly PhaseDraft[];
+    /** Failure policy: `false` (default) continues gracefully, `true` halts on the first failure. */
+    readonly bail?: boolean;
+}
+
+/**
+ * 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.
+ */
+export declare const workflowDraftShape: ObjectShape<{
+    id: OptionalShape<StringShape>;
+    name: OptionalShape<StringShape>;
+    description: OptionalShape<StringShape>;
+    phases: ArrayShape<ObjectShape<{
+        id: OptionalShape<StringShape>;
+        name: OptionalShape<StringShape>;
+        description: OptionalShape<StringShape>;
+        tasks: ArrayShape<ObjectShape<{
+            id: OptionalShape<StringShape>;
+            name: OptionalShape<StringShape>;
+            description: OptionalShape<StringShape>;
+            run: OptionalShape<StringShape>;
+            retries: OptionalShape<NumberShape>;
+            timeout: OptionalShape<NumberShape>;
+        }>>;
+        concurrency: OptionalShape<NumberShape>;
+        bail: OptionalShape<LiteralShape<readonly [true, false]>>;
+    }>>;
+    bail: OptionalShape<LiteralShape<readonly [true, false]>>;
+}>;
+
+/**
+ * One flat step — `{ name }` — the building block of a {@link WorkflowSteps} blob.
+ *
+ * @remarks
+ * `name` is the REGISTERED behavior name the step runs (it becomes the task's `run`, NOT a
+ * human label) — resolved against a workflow-level functions registry at construction.
+ */
+export declare interface WorkflowStep {
+    /** The registered behavior name this step runs (becomes the task's `run`). */
+    readonly name: string;
+}
+
+/**
+ * The FLAT authoring blob {@link import('./factories.js').createWorkflowTool} advertises —
+ * `{ name?, steps }` — the simplest surface a small model can fill.
+ *
+ * @remarks
+ * Each {@link WorkflowStep} becomes a one-task phase, in order
+ * ({@link import('./helpers.js').expandSteps}); `name` is the optional workflow name (defaulted
+ * when omitted).
+ */
+export declare interface WorkflowSteps {
+    readonly name?: string;
+    readonly steps: readonly WorkflowStep[];
+}
+
+/**
+ * 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.
+ */
+export declare const workflowStepsShape: ObjectShape<{
+    name: OptionalShape<StringShape>;
+    steps: ArrayShape<ObjectShape<{
+        name: StringShape;
+    }>>;
+}>;
+
+/**
+ * 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>`)
+ */
+export declare function workflowTag(id: string): string;
+
+/**
+ * Options for {@link import('./factories.js').createWorkflowTool} — the depth + ancestry a
+ * nested workflow run is bound at, plus the optional durable {@link WorkflowStoreInterface}
+ * (`@orkestrel/workflow`) this package layers on top of the ported handler logic.
+ *
+ * @remarks
+ * This is the PROPAGATION carrier across the agent/tool boundary. A `Tool`'s handler receives
+ * ONLY the model-supplied `args` (no ambient context, no signal — see `@orkestrel/agent`'s
+ * `ToolOptions`), so the run's position in the workflow→agent→workflow chain CANNOT be threaded
+ * through a tool call at runtime. Instead {@link import('./factories.js').createAgentFunction}
+ * CLOSES `depth` / `ancestry` over the tool at BIND time. Both are OPTIONAL: a workflow tool
+ * built for a TOP-LEVEL caller omits them — its nested run starts the chain at depth `1` with
+ * the bare `workflow:<id>` ancestry.
+ *
+ * `store` is this package's ADDITION: when supplied, the tool's handler persists the run's final
+ * snapshot (`store.set(result.workflow.snapshot())`) once the run settles, so a workflow
+ * authored + run through the tool is retrievable / restorable afterwards. Omitted ⇒ no
+ * persistence.
+ */
+export declare interface WorkflowToolOptions {
+    /** The depth the INVOKING agent runs at; the nested workflow runs at `depth + 1`. Default `0`. */
+    readonly depth?: number;
+    /** The ancestry of the invoking run; the nested run extends it with its own `workflow:<id>`. Default empty. */
+    readonly ancestry?: readonly string[];
+    readonly store?: WorkflowStoreInterface;
+}
+
+/**
+ * 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 }`
+ */
+export declare function workflowToolSummary(result: WorkflowResult): Readonly<{
+    status: WorkflowStatus;
+    count: number;
+}>;
+
+export declare const WORKSPACE_TOOL_DESCRIPTION: string;
+
+/**
+ * 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.
+ */
+export declare const WORKSPACE_TOOL_EXAMPLE: WorkspaceOperation;
+
+/**
+ * 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`).
+ */
+export declare const WORKSPACE_TOOL_NAME = "workspace";
+
+/**
+ * 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}.
+ */
+export declare const WORKSPACE_TOOL_SUMMARY = "Read and edit files in a workspace \u2014 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.";
+
+/**
+ * One operation an agent invokes through {@link import('./factories.js').createWorkspaceTool} — a
+ * FLAT, descriptive tagged union over the 13 workspace edit / read / navigation actions,
+ * discriminated by the `operation` literal (AGENTS §4.8: a discriminant is named for its axis —
+ * the action being performed — NEVER `kind`).
+ *
+ * @remarks
+ * This is the SOURCE OF TRUTH the tool contract is typed to
+ * ({@link import('./shapers.js').workspaceToolShape} compiles to a structurally-identical guard /
+ * parser / JSON Schema). Every field is FLAT (no nested objects) — the small-model ergonomic
+ * lever: a range edit is the four flat integers of the `'splice'` arm (`fromLine` /
+ * `fromColumn` / `toLine` / `toColumn`), reassembled into a 1-based `Range` (`@orkestrel/agent`)
+ * by `rangeOf`, never a nested `{ start, end }`. Each EDIT / READ arm maps onto exactly one
+ * `WorkspaceInterface` call against the manager's ACTIVE workspace; the two REGISTRY arms
+ * (`switch` / `workspaces`) drive the {@link WorkspaceManagerInterface} pointer instead —
+ * `workspaces` LISTS the workspaces the model can move between, and `switch` re-points which one
+ * the edit / read arms target.
+ */
+export declare type WorkspaceOperation = 
+/** Read a whole text file's text by `path` from the ACTIVE workspace (a binary / absent path — or no active workspace — yields no content). */
+    {
+    readonly operation: 'read';
+    readonly path: string;
+}
+/** List every file in the ACTIVE workspace (path / state / size / lines / kind summaries); `[]` when no workspace is active. */
+| {
+    readonly operation: 'list';
+}
+/** Whether a file exists at `path` in the ACTIVE workspace (`false` when no workspace is active). */
+| {
+    readonly operation: 'has';
+    readonly path: string;
+}
+/**
+* Scan every text file for `query`, returning each hit (path + 1-based line / column + the line).
+*
+* @remarks
+* `regex` treats `query` as a regular-expression source (default `false` — a literal substring);
+* `exact` matches case-sensitively (default `true`); `limit` caps the total hits returned.
+*/
+| {
+    readonly operation: 'search';
+    readonly query: string;
+    readonly regex?: boolean;
+    readonly exact?: boolean;
+    readonly limit?: number;
+}
+/**
+* Replace `query` with `replacement` across every text file, returning the tally.
+*
+* @remarks
+* Same matching axes as `search`: `regex` (default `false`), `exact` (default `true`), `limit`
+* (cap the total replacements).
+*/
+| {
+    readonly operation: 'replace';
+    readonly query: string;
+    readonly replacement: string;
+    readonly regex?: boolean;
+    readonly exact?: boolean;
+    readonly limit?: number;
+}
+/** Write (create or overwrite) the whole file at `path` with `content`. */
+| {
+    readonly operation: 'write';
+    readonly path: string;
+    readonly content: string;
+}
+/**
+* Splice `content` into an existing text file, replacing the 1-based range
+* `(fromLine, fromColumn)` (INCLUSIVE) → `(toLine, toColumn)` (EXCLUSIVE).
+*
+* @remarks
+* The FLAT range edit — the four positive-integer caret components reassemble into a `Range`
+* (`@orkestrel/agent`) via `rangeOf`. An empty span (`from === to`) inserts; a span past the
+* end is clamped. An inverted / sub-1 range throws `RANGE`; a binary target throws
+* `MODALITY`.
+*/
+| {
+    readonly operation: 'splice';
+    readonly path: string;
+    readonly content: string;
+    readonly fromLine: number;
+    readonly fromColumn: number;
+    readonly toLine: number;
+    readonly toColumn: number;
+}
+/** Prepend `content` to the start of the file at `path` (creating it when absent). */
+| {
+    readonly operation: 'prepend';
+    readonly path: string;
+    readonly content: string;
+}
+/** Append `content` to the end of the file at `path` (creating it when absent). */
+| {
+    readonly operation: 'append';
+    readonly path: string;
+    readonly content: string;
+}
+/** Re-key the file `from` → `to` (overwriting an occupied target). */
+| {
+    readonly operation: 'move';
+    readonly from: string;
+    readonly to: string;
+}
+/** Remove the file at `path` from the workspace. */
+| {
+    readonly operation: 'remove';
+    readonly path: string;
+}
+/** List the workspaces the model can move between — each `{ id, files, active }` — so it can choose an `id` to `switch` to. */
+| {
+    readonly operation: 'workspaces';
+}
+/** Re-point the manager's ACTIVE workspace to the one with `id` (an unknown `id` is a lenient no-op). The edit / read arms target the active workspace from then on. */
+| {
+    readonly operation: 'switch';
+    readonly id: string;
+};
+
+/**
+ * Options for {@link import('./factories.js').createWorkspaceTool} — EITHER a caller-built
+ * {@link WorkspaceManagerInterface} to drive directly, OR a {@link WorkspaceStoreInterface} the
+ * tool constructs a fresh manager over; neither given constructs a manager over
+ * `@orkestrel/agent`'s in-memory store.
+ *
+ * @remarks
+ * - `manager` — drive THIS manager directly (its `active` workspace is what every edit / read
+ *   operation targets). Takes priority over `store` when both are supplied.
+ * - `store` — construct a manager over this durable {@link WorkspaceStoreInterface} (via
+ *   `@orkestrel/agent`'s `createWorkspaceManager`) — used only when `manager` is omitted.
+ *   The store only backs the manager's own `open` / `save` operations: the tool's edits are
+ *   NOT auto-persisted — durability requires an explicit caller `save` on the manager
+ *   (unlike the workflow tool's `store`, which persists each executed snapshot on settle).
+ * - `name` / `description` — advertised tool overrides; default to
+ *   {@link import('./constants.js').WORKSPACE_TOOL_NAME} / {@link import('./constants.js').WORKSPACE_TOOL_DESCRIPTION}.
+ */
+export declare interface WorkspaceToolOptions {
+    readonly name?: string;
+    readonly description?: string;
+    readonly manager?: WorkspaceManagerInterface;
+    readonly store?: WorkspaceStoreInterface;
+}
+
+/**
+ * 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.
+ */
+export declare const workspaceToolShape: UnionShape<[ ObjectShape<{
+    operation: LiteralShape<readonly ["read"]>;
+    path: StringShape;
+}>, ObjectShape<{
+    operation: LiteralShape<readonly ["list"]>;
+}>, ObjectShape<{
+    operation: LiteralShape<readonly ["has"]>;
+    path: StringShape;
+}>, ObjectShape<{
+    operation: LiteralShape<readonly ["search"]>;
+    query: StringShape;
+    regex: OptionalShape<BooleanShape>;
+    exact: OptionalShape<BooleanShape>;
+    limit: OptionalShape<NumberShape>;
+}>, ObjectShape<{
+    operation: LiteralShape<readonly ["replace"]>;
+    query: StringShape;
+    replacement: StringShape;
+    regex: OptionalShape<BooleanShape>;
+    exact: OptionalShape<BooleanShape>;
+    limit: OptionalShape<NumberShape>;
+}>, ObjectShape<{
+    operation: LiteralShape<readonly ["write"]>;
+    path: StringShape;
+    content: StringShape;
+}>, ObjectShape<{
+    operation: LiteralShape<readonly ["splice"]>;
+    path: StringShape;
+    content: StringShape;
+    fromLine: NumberShape;
+    fromColumn: NumberShape;
+    toLine: NumberShape;
+    toColumn: NumberShape;
+}>, ObjectShape<{
+    operation: LiteralShape<readonly ["prepend"]>;
+    path: StringShape;
+    content: StringShape;
+}>, ObjectShape<{
+    operation: LiteralShape<readonly ["append"]>;
+    path: StringShape;
+    content: StringShape;
+}>, ObjectShape<{
+    operation: LiteralShape<readonly ["move"]>;
+    from: StringShape;
+    to: StringShape;
+}>, ObjectShape<{
+    operation: LiteralShape<readonly ["remove"]>;
+    path: StringShape;
+}>, ObjectShape<{
+    operation: LiteralShape<readonly ["workspaces"]>;
+}>, ObjectShape<{
+    operation: LiteralShape<readonly ["switch"]>;
+    id: StringShape;
+}>]>;
+
+export { }