@orkestrel/workflow 0.0.2 → 0.0.4

package/dist/src/core/index.js

@@ -1,5 +1,4 @@
-import { createTool } from "@orkestrel/agent";
-import { arrayShape, compileGuard, createContract, integerShape, isArray, isBoolean, isNumber, isRecord, isString, literalShape, objectShape, optionalShape, rawShape, schemaToParameters, stringShape } from "@orkestrel/contract";
+import { arrayShape, compileGuard, createContract, integerShape, isArray, isBoolean, isNumber, isRecord, isString, literalShape, objectShape, optionalShape, rawShape, stringShape } from "@orkestrel/contract";
 import { createDatabase, createMemoryDriver } from "@orkestrel/database";
 import { createAbort } from "@orkestrel/abort";
 import { Emitter } from "@orkestrel/emitter";
@@ -178,102 +177,6 @@ var TASK_TRANSITIONS = Object.freeze({
 * phase may still DECLARE a larger explicit `concurrency` and pays that allocation knowingly.
 */
 var DEFAULT_PHASE_CONCURRENCY = 1024;
-/**
-* The maximum nesting depth a workflow → agent → workflow chain may reach — the bound
-* the {@link import('./factories.js').createAgentFunction} and
-* {@link import('./factories.js').createWorkflowTool} adapters' depth/cycle guards enforce.
-*
-* @remarks
-* The limit lives in ONE place. An {@link import('./factories.js').createAgentFunction}-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` {@link import('./errors.js').WorkflowError} throw). The chain
-* therefore nests workflows down to this depth, and the nested run at
-* depth `MAX_WORKFLOW_DEPTH` fails.
-*/
-var MAX_WORKFLOW_DEPTH = 8;
-/**
-* The name under which {@link import('./factories.js').createAgentFunction} BINDS the
-* depth/cycle-aware workflow tool onto a wrapped agent's `context.tools` (`AgentContextInterface`,
-* `@orkestrel/agent`).
-*
-* @remarks
-* The propagation seam's well-known key: when its `runner` option is supplied, the adapter adds a
-* {@link import('./factories.js').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}). An agent that wants to fan out into a workflow calls this tool by
-* this name; the bound handler runs the nested workflow at depth + 1.
-*/
-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
-* 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 {@link WorkflowDefinition}. It
-* is embedded VERBATIM in {@link WORKFLOW_TOOL_DESCRIPTION} and guarded by a parity test
-* (it must expand to a tree the STRICT contract accepts), so the doc example can never drift.
-*/
-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 {@link WorkflowDefinition}.
-*
-* @remarks
-* The full four-level form, documented in {@link WORKFLOW_TOOL_DESCRIPTION} as the advanced
-* alternative. It is embedded VERBATIM and guarded by a parity test (`createWorkflowContract().is`
-* must accept it), so the doc example can never drift from a valid definition.
-*/
-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
-* 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
-* {@link WorkflowDefinition} as the ADVANCED form with a minimal example
-* ({@link WORKFLOW_TOOL_NESTED_EXAMPLE}). Both examples are interpolated VERBATIM from the
-* validated constants, so a parity test pins them — the description can never drift from a
-* real, contract-valid example. The `parameters` the tool advertises are the FLAT shape's
-* schema; the nested form is the documented escape-hatch (the tool accepts both). NOTE: a step's
-* "registered behavior name" is authored STRUCTURE only —
-* {@link import('./factories.js').createWorkflowTool} runs the authored tree with no
-* {@link WorkflowFunctions} registry of its own, so every one of its tasks auto-completes under
-* the no-handler rule; the tool validates/synthesizes shape, it does not dispatch behavior.
-*/
-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");
 //#endregion
 //#region src/core/errors.ts
 /**
@@ -284,11 +187,11 @@ var WORKFLOW_TOOL_DESCRIPTION = [
 * offending node id / status. Thrown for an illegal lifecycle transition
 * (`TRANSITION`), a structurally invalid {@link import('./types.js').WorkflowSnapshot}
 * passed to {@link import('./factories.js').restoreWorkflow} (`RESTORE`), an over-deep /
-* cyclic nested-workflow dispatch (`DEPTH`), and a malformed
-* {@link import('./factories.js').createWorkflowTool} args blob (`TOOL`). On the
-* workflow-tool seam the `DEPTH` / `TOOL` throw is ISOLATED by the
-* `@orkestrel/agent` package's `ToolManager` into the tool result's
-* top-level `error` (AGENTS §14 — the universal tool-handler contract).
+* cyclic nested-workflow dispatch (`DEPTH`), and a malformed workflow-authoring-tool args
+* blob (`TOOL`). `DEPTH` and `TOOL` are public type surface constructed by the
+* `@orkestrel/tool` package's workflow-tool / agent-function adapters; on that seam the
+* throw is ISOLATED by its `ToolManager` into the tool result's top-level `error`
+* (AGENTS §14 — the universal tool-handler contract).
 */
 var WorkflowError = class extends Error {
 	code;
@@ -321,37 +224,6 @@ function isWorkflowError(value) {
 //#endregion
 //#region src/core/helpers.ts
 /**
-* The ancestry identifier of a workflow run — `workflow:<id>`.
-*
-* @remarks
-* The {@link import('./WorkflowRunner.js').WorkflowRunner}'s cycle guard records one of
-* these per workflow in the current nested run chain (carried on
-* {@link import('./types.js').WorkflowRunOptions.ancestry}). Tagging the bare id keeps a
-* workflow id and an {@link agentTag} agent name in ONE namespaced 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}: the runner adds one when it dispatches an
-* `agent` task, and rejects the task (a typed `DEPTH` `task.fail`) when the same tag is
-* already in the ancestry (a re-entry cycle). The `agent:` namespace keeps it distinct
-* from a same-string workflow id.
-*
-* @param name - The agent's registry name (the `agent`-form's `name`)
-* @returns The namespaced ancestry tag (`agent:<name>`)
-*/
-function agentTag(name) {
-	return `agent:${name}`;
-}
-/**
 * Test whether a {@link LifecycleStatus} is TERMINAL — a node in this state will not
 * transition further.
 *
@@ -721,120 +593,6 @@ function collectResults(phases) {
 	return phases.flat();
 }
 /**
-* Summarize a terminal {@link WorkflowResult} into the PLAIN value a
-* {@link import('./factories.js').createWorkflowTool} handler returns on success.
-*
-* @remarks
-* This is the run summary the handler returns DIRECTLY — NOT a `ToolResult` (the future `@orkestrel/agent` package).
-* The handler conforms to the universal tool-handler contract (AGENTS §14): it returns the plain value
-* (and throws on failure), so the `@orkestrel/agent` package's `ToolManager` performs
-* the ONE canonical wrap (`{ id, name, value }`) and the model reads exactly this summary — once,
-* identically — over BOTH the agent loop and MCP. 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 manager
-* supplies the canonical envelope's identity.)
-*
-* @param result - The terminal {@link WorkflowResult} 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 {@link PhaseDefinition} — 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 {@link PhaseDefinition}
-*/
-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 {@link TaskDefinition} — 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 {@link TaskDefinition}
-*/
-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 (AGENTS §21 — the simplest form a small
-* model can author). Each {@link 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 }] }))
-	});
-}
-/**
 * Insert one `[key, value]` entry at a positional index into a readonly entries array —
 * the pure splice-in step behind an insertion-ordered registry's `add`.
 *
@@ -1012,118 +770,6 @@ var workflowShape = objectShape({
 	bail: optionalShape(literalShape([true, false], { description: "Failure policy: false (default) continues gracefully, true halts on the first failure." }))
 });
 /**
-* The shape of a TASK in a draft workflow — identical to {@link taskShape} EXCEPT `id`
-* and `name` are OPTIONAL (the tool synthesizes any missing one positionally).
-*
-* @remarks
-* A PROVIDED `id` / `name` still carries `minLength: 1`, so an explicitly-empty `id: ''`
-* is INVALID (rejected by the draft contract), never auto-filled — keeping "garbage"
-* distinct from "omitted". `run` stays optional, mirroring {@link taskShape}.
-*/
-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 {@link phaseShape} 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 {@link workflowShape} 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; 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 {@link import('./factories.js').createWorkflowContract} 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 `createWorkflowTool` advertises as its `parameters` — the
-* simplest surface a small model can fill: `{ name?, steps: [{ name }] }`.
-*
-* @remarks
-* The deliberately-reduced surface (AGENTS §21): 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
-* {@link import('./factories.js').createWorkflowContract} 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').TaskUpdate} — a partial edit to a
 * `pending` task's `name` / `description`, both optional.
 *
@@ -2197,6 +1843,91 @@ var Workflow = class {
 	}
 };
 //#endregion
+//#region src/core/WorkflowManager.ts
+/**
+* The store-backed registry of {@link WorkflowInterface}s keyed by `id`, in insertion order —
+* the additive manager tier mirroring the `@orkestrel/agent` line's `ConversationManager` /
+* `WorkspaceManager`. Event-free (a registry, like its twins); the observability lives on each
+* {@link WorkflowInterface}.
+*
+* @remarks
+* - **Registry.** Workflows live in an insertion-ordered `Map` keyed by `id`. `add(definition)`
+*   mints a live {@link WorkflowInterface} through {@link createWorkflow} (flowing the manager's
+*   `functions` registry in) and stores it under `definition.id` — an already-present id
+*   OVERWRITES (last write wins). `count` is the map size, `workflow(id)` looks one up,
+*   `workflows()` lists them in insertion order.
+* - **Durable open / save.** `open(id)` returns an already-registered workflow directly; on a
+*   registry MISS with a `store` set it rehydrates through {@link restoreWorkflow} (flowing the
+*   manager's `functions` registry in so the rehydrated tree is RUNNABLE), registers it, and
+*   returns it — lenient (`undefined`) with no store or a store miss. `save(id)` persists a
+*   registered workflow's `snapshot()` to the `store` — lenient (`false`) with no store or an
+*   unknown id.
+* - **Removal.** `remove` drops one by id, or a batch (§9.2, array overload FIRST) — `true` when
+*   any was removed. `clear` empties the registry.
+* - **No active pointer.** Unlike its `ConversationManager` / `WorkspaceManager` twins, there is
+*   no `active` / `switch` — nothing in the workflow domain renders "the current workflow".
+*
+* @example
+* ```ts
+* const manager = new WorkflowManager({
+* 	functions: { compile: async (controller) => `built ${controller.task.id}` },
+* })
+* const workflow = manager.add(definition) // minted, registered, RUNNABLE
+* manager.workflow(workflow.id) // the same workflow
+* manager.count // 1
+* ```
+*/
+var WorkflowManager = class {
+	#workflows = /* @__PURE__ */ new Map();
+	#functions;
+	#store;
+	constructor(options) {
+		this.#functions = options?.functions;
+		this.#store = options?.store;
+	}
+	get count() {
+		return this.#workflows.size;
+	}
+	workflow(id) {
+		return this.#workflows.get(id);
+	}
+	workflows() {
+		return [...this.#workflows.values()];
+	}
+	add(definition) {
+		const workflow = createWorkflow(definition, { functions: this.#functions });
+		this.#workflows.set(workflow.id, workflow);
+		return workflow;
+	}
+	async open(id) {
+		const existing = this.#workflows.get(id);
+		if (existing !== void 0) return existing;
+		if (this.#store === void 0) return void 0;
+		const snapshot = await this.#store.get(id);
+		if (snapshot === void 0) return void 0;
+		const workflow = restoreWorkflow(snapshot, { functions: this.#functions });
+		this.#workflows.set(workflow.id, workflow);
+		return workflow;
+	}
+	async save(id) {
+		const workflow = this.#workflows.get(id);
+		if (this.#store === void 0 || workflow === void 0) return false;
+		await this.#store.set(workflow.snapshot());
+		return true;
+	}
+	remove(ids) {
+		if (isArray(ids)) {
+			let removed = false;
+			for (const id of ids) if (this.#workflows.delete(id)) removed = true;
+			return removed;
+		}
+		return this.#workflows.delete(ids);
+	}
+	clear() {
+		this.#workflows.clear();
+	}
+};
+//#endregion
 //#region src/core/Controller.ts
 /**
 * The per-unit handle a runner handler receives — wraps the unit's identity,
@@ -2580,10 +2311,10 @@ var TaskController = class {
 *   {@link import('./types.js').TaskInterface.handler} ONCE at construction (build, restore,
 *   or a live mint all resolve it identically, from {@link WorkflowOptions.functions}), so
 *   dispatch is simply "invoke the task's own handler". Static tool / agent calling is an
-*   OPT-IN concern of `factories.ts`'s adapter factories ({@link import('./factories.js').createToolFunction},
-*   {@link import('./factories.js').createAgentFunction}) — plain {@link import('./types.js').WorkflowFunction}s a
-*   caller wires into {@link WorkflowOptions.functions} like any other behavior. This module
-*   never imports `@orkestrel/agent`.
+*   OPT-IN concern of the `@orkestrel/tool` package's adapter factories — plain
+*   {@link import('./types.js').WorkflowFunction}s a caller wires into
+*   {@link WorkflowOptions.functions} like any other behavior. This module never imports
+*   any tool/agent package.
 * - **Two `execute` forms, one engine.** `execute(definition, options)` BUILDS the live tree
 *   from a {@link WorkflowDefinition} (single source of truth for the `run` / `concurrency`
 *   metadata); `execute(workflow, options)` DRIVES a caller-owned, ALREADY-BUILT
@@ -2896,41 +2627,6 @@ function createWorkflowContract() {
 	};
 }
 /**
-* Compile the LENIENT workflow DRAFT contract — identical to
-* {@link createWorkflowContract} 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 — {@link createWorkflowContract} 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 required.
-*
-* @returns The compiled {@link WorkflowDraft} contract
-*
-* @example
-* ```ts
-* import { createWorkflowDraftContract, completeDraft } from '@src/core'
-*
-* const draft = createWorkflowDraftContract()
-* const parsed = draft.parse({ phases: [{ tasks: [{ run: { via: 'function', name: 'f' } }] }] })
-* const definition = parsed && completeDraft(parsed) // ids/names filled positionally
-* draft.parse({ id: '', phases: [] })                // undefined — an explicit empty id is rejected
-* ```
-*/
-function createWorkflowDraftContract() {
-	const contract = createContract(workflowDraftShape);
-	return {
-		schema: contract.schema,
-		is: contract.is,
-		generate: (random) => contract.generate(random),
-		parse: (value) => contract.parse(value)
-	};
-}
-/**
 * Build the live W-b entity tree from a {@link WorkflowDefinition} — the whole
 * {@link WorkflowInterface} → {@link import('./types.js').PhaseInterface} →
 * {@link import('./types.js').TaskInterface} tree, each level wired with its lineage
@@ -3164,11 +2860,11 @@ function createDatabaseWorkflowStore(driver = createMemoryDriver()) {
 * the live entity (`start` → `complete` / `fail`), and resolves a
 * {@link import('./types.js').WorkflowResult}.
 *
-* Static tool / agent calling is OPT-IN, wired through the adapter factories
-* {@link createToolFunction} / {@link createAgentFunction} — plain
-* {@link import('./types.js').WorkflowFunction}s a caller composes into its OWN
-* {@link WorkflowOptions.functions} registry, same as any other behavior. A task with no
-* resolved handler AUTO-COMPLETES (the ROADMAP no-handler rule).
+* Static tool / agent calling is OPT-IN: a caller wires a plain
+* {@link import('./types.js').WorkflowFunction} into its OWN {@link WorkflowOptions.functions}
+* registry, same as any other behavior — the `@orkestrel/tool` package ships the
+* tool/agent adapter factories for that. A task with no resolved handler AUTO-COMPLETES
+* (the ROADMAP no-handler rule).
 *
 * @param options - An optional pacing `scheduler` (default the shipped cross-environment one).
 *   See {@link WorkflowRunnerOptions}.
@@ -3193,229 +2889,38 @@ function createWorkflowRunner(options) {
 	return new WorkflowRunner(options?.scheduler ?? createScheduler());
 }
 /**
-* Wrap a registered tool as a {@link WorkflowFunction} — the OPT-IN adapter that lets a
-* `function`-form task run a `@orkestrel/agent` tool BY NAME.
-*
-* @remarks
-* Composes into a caller's {@link WorkflowOptions.functions} registry like any other behavior
-* (`{ publish: createToolFunction(tools, 'publish') }`); the PURE
-* {@link import('./WorkflowRunner.js').WorkflowRunner} 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` 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` {@link WorkflowError}.
-*
-* @param tools - The {@link ToolManagerInterface} 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, createToolManager, createWorkflowRunner } from '@src/core'
-*
-* 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} — 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
-* Composes into a caller's {@link WorkflowOptions.functions} registry like any other behavior;
-* the PURE {@link import('./WorkflowRunner.js').WorkflowRunner} has no knowledge of agents
-* itself. Before running the agent, the depth/cycle guard REJECTS the call (a THROWN typed
-* `DEPTH` {@link WorkflowError}, which the leaf `fail`s) when running it would push a nested
-* chain past {@link MAX_WORKFLOW_DEPTH}, OR when this agent is already an ancestor (a cycle) —
-* ported from the former engine-side guard. When {@link 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 {@link 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 AgentFunctionOptions})
-* @returns A {@link WorkflowFunction} that runs `agent` to its settled result
-*
-* @example
-* ```ts
-* import { createAgentFunction, createWorkflowRunner } from '@src/core'
-*
-* 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);
-		}
-	};
-}
-/**
-* Wrap a {@link WorkflowDefinition} as an LLM-callable {@link ToolInterface} — 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
-* returns the run SUMMARY (throwing a typed {@link WorkflowError} on failure).
+* Create a {@link WorkflowManagerInterface} — the store-backed registry of
+* {@link WorkflowInterface}s, the additive manager tier mirroring the `@orkestrel/agent`
+* line's `createConversationManager` / `createWorkspaceManager`.
 *
 * @remarks
-* A plain {@link ToolManagerInterface}-compatible tool (so `createMCPServer` / `createMCPRoutes`
-* expose it for free — nothing MCP is wired here). 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 WorkflowToolOptions}, and the
-* handler enforces the SAME depth / cycle guard itself (this function owns it now — the engine
-* carries none) 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
-* {@link 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 (documented in the
-*   description), accepted as the draft super-set.
-*
-* The handler conforms to the universal tool-handler contract (AGENTS §14): it returns the PLAIN
-* run-summary VALUE on success and THROWS a typed {@link WorkflowError} on every failure path. It
-* does NOT build a {@link ToolResult} itself — the `@orkestrel/agent` package's `ToolManager`
-* performs the ONE canonical wrap (`{ id, name, value }` on a return; `{ id, name, error }` on a
-* throw, ISOLATED so nothing escapes the run), so the outcome appears EXACTLY ONCE, identically,
-* over BOTH the agent loop and MCP (a throw → MCP `isError: true`):
-* - **No authored args** (an empty `arguments`) ⇒ runs the WRAPPED `definition`.
-* - **A `steps` array** ⇒ the FLAT form: parse it, {@link import('./helpers.js').expandSteps} it.
-* - **Otherwise** ⇒ the nested form: {@link createWorkflowDraftContract}-parse it,
-*   {@link import('./helpers.js').completeDraft} it.
-* - **Strict gate** ⇒ the expanded / completed result is validated against
-*   {@link createWorkflowContract}.`is`; a blob that can't expand, or whose result fails the strict
-*   gate (e.g. an explicit empty `id`, `concurrency: 0`) ⇒ THROW a `TOOL` {@link WorkflowError} (no run).
-* - **Over-deep / cyclic** ⇒ THROW a `DEPTH` {@link WorkflowError} when the nested run would exceed
-*   {@link MAX_WORKFLOW_DEPTH}, or the target workflow id is already an ancestor (a cycle) — the
-*   SAME `code` {@link createAgentFunction}'s own guard raises. Enforced HERE, INSIDE this
-*   handler, before ever calling `runner.execute` — the engine itself performs no such check.
-* - **Otherwise** ⇒ `runner.execute(target)`, RETURNING the plain summary of the terminal run
-*   (`{ status, count }`, via {@link workflowToolSummary}).
-*
-* The tool executes AUTHORED STRUCTURE, not consumer behavior: a nested tree authored through
-* it (flat, draft, or full form) carries no {@link WorkflowFunctions} registry, so EVERY one of
-* its tasks auto-completes under the no-handler rule. This handler validates and synthesizes
-* shape — it never runs a caller's handlers.
-*
-* @param definition - The workflow the tool runs when called with no authored args
-* @param runner - The {@link WorkflowRunnerInterface} that executes the (nested) workflow
-* @param options - The depth + ancestry to run the nested workflow under (see
-*   {@link WorkflowToolOptions}); omitted ⇒ depth `0` / empty ancestry (a top-level wrap)
-* @returns A {@link ToolInterface} (named {@link import('./constants.js').WORKFLOW_TOOL_NAME})
-*   whose `parameters` advertise the FLAT authoring schema (the nested form stays accepted)
+* `options.functions` flows into every workflow the manager mints (`add`, via
+* {@link createWorkflow}) or hydrates (`open`'s registry-miss path, via
+* {@link restoreWorkflow}), so a hydrated workflow is RUNNABLE rather than a dead snapshot
+* mirror. `options.store` is the EXACT analogue of the twins' `store` seam — omitted ⇒ the
+* manager is registry-only (`open` resolves only what is registered, `save` is a no-op). This
+* is PURELY ADDITIVE: direct {@link WorkflowStoreInterface} use and
+* {@link restoreWorkflow} remain valid — the manager is one more caller-driven persistence
+* seam, not a replacement.
+*
+* @param options - The optional `store` seam and the `functions` registry threaded into every mint/hydrate
+* @returns A working {@link WorkflowManagerInterface}
 *
 * @example
 * ```ts
-* import { createWorkflowRunner, createWorkflowTool, createToolManager } from '@src/core'
+* import { createMemoryWorkflowStore, createWorkflowManager } from '@src/core'
 *
-* const runner = createWorkflowRunner()
-* const tool = createWorkflowTool(definition, runner)
-* const tools = createToolManager()
-* tools.add(tool) // a model can now author + run a workflow in one call
+* const manager = createWorkflowManager({
+* 	store: createMemoryWorkflowStore(),
+* 	functions: { compile: async (controller) => `built ${controller.task.id}` },
+* })
+* const workflow = manager.add(definition) // minted, registered, RUNNABLE
+* await manager.save(workflow.id)          // persisted to the store
+* const reopened = await manager.open(workflow.id) // already registered — no store hit
 * ```
 */
-function createWorkflowTool(definition, runner, options) {
-	const strict = createWorkflowContract();
-	const draft = createWorkflowDraftContract();
-	const steps = createContract(workflowStepsShape);
-	const depth = options?.depth ?? 0;
-	const ancestry = options?.ancestry ?? [];
-	return createTool({
-		name: WORKFLOW_TOOL_NAME,
-		description: WORKFLOW_TOOL_DESCRIPTION,
-		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]
-			});
-			return workflowToolSummary(await runner.execute(target));
-		}
-	});
+function createWorkflowManager(options) {
+	return new WorkflowManager(options);
 }
 /**
 * Create the safe cross-environment cooperative-yield default — a
@@ -3509,6 +3014,6 @@ function createRunner(options) {
 	return new Runner(options);
 }
 //#endregion
-export { Controller, DEFAULT_BAIL, DEFAULT_PHASE_CONCURRENCY, DatabaseWorkflowStore, MAX_WORKFLOW_DEPTH, MemoryWorkflowStore, PHASE_STATUSES, Phase, PhaseManager, Runner, Scheduler, TASK_STATUSES, TASK_TRANSITIONS, TERMINAL_TASK_STATUSES, Task, TaskController, TaskManager, WORKFLOW_STATUSES, WORKFLOW_TOOL_DESCRIPTION, WORKFLOW_TOOL_FLAT_EXAMPLE, WORKFLOW_TOOL_NAME, WORKFLOW_TOOL_NESTED_EXAMPLE, Workflow, WorkflowError, WorkflowRunner, agentTag, assertSnapshot, buildPhaseContext, buildTaskContext, buildWorkflowContext, canTransitionTask, collectResults, completeDraft, completePhaseDraft, completeTaskDraft, createAgentFunction, createDatabaseWorkflowStore, createDeferred, createMemoryWorkflowStore, createRunner, createScheduler, createToolFunction, createWorkflow, createWorkflowContract, createWorkflowDraftContract, createWorkflowRunner, createWorkflowTool, definitionToSnapshot, deriveBoundary, derivePhaseStatus, deriveWorkflowStatus, expandSteps, failure, findFailure, insertEntry, isTerminalStatus, isWorkflowError, isWorkflowSnapshot, moveEntry, parkSignal, phaseDefinitionToSnapshot, phaseDraftShape, phaseShape, phaseUpdateShape, restoreWorkflow, stepShape, success, taskDefinitionToSnapshot, taskDraftShape, taskShape, taskUpdateShape, workflowDraftShape, workflowShape, workflowStepsShape, workflowTag, workflowToolSummary };
+export { Controller, DEFAULT_BAIL, DEFAULT_PHASE_CONCURRENCY, DatabaseWorkflowStore, MemoryWorkflowStore, PHASE_STATUSES, Phase, PhaseManager, Runner, Scheduler, TASK_STATUSES, TASK_TRANSITIONS, TERMINAL_TASK_STATUSES, Task, TaskController, TaskManager, WORKFLOW_STATUSES, Workflow, WorkflowError, WorkflowManager, WorkflowRunner, assertSnapshot, buildPhaseContext, buildTaskContext, buildWorkflowContext, canTransitionTask, collectResults, createDatabaseWorkflowStore, createDeferred, createMemoryWorkflowStore, createRunner, createScheduler, createWorkflow, createWorkflowContract, createWorkflowManager, createWorkflowRunner, definitionToSnapshot, deriveBoundary, derivePhaseStatus, deriveWorkflowStatus, failure, findFailure, insertEntry, isTerminalStatus, isWorkflowError, isWorkflowSnapshot, moveEntry, parkSignal, phaseDefinitionToSnapshot, phaseShape, phaseUpdateShape, restoreWorkflow, success, taskDefinitionToSnapshot, taskShape, taskUpdateShape, workflowShape };
 
 //# sourceMappingURL=index.js.map