@orkestrel/toolbox 0.0.21 → 0.0.22

package/dist/src/core/index.cjs

@@ -8,7 +8,7 @@ let _orkestrel_agent = require("@orkestrel/agent");
 let _orkestrel_workspace = require("@orkestrel/workspace");
 let _orkestrel_tool = require("@orkestrel/tool");
 let _orkestrel_form = require("@orkestrel/form");
-//#region src/core/constants.ts
+// src/core/constants.ts
 /**
 * Holds the name {@link import('./factories.js').createAgentTool} advertises by default, `'agent'`
 * — the key a model calls and the `ToolManagerInterface` (`@orkestrel/tool`) registers under.
@@ -581,8 +581,7 @@ var INFER_TOOL_DESCRIPTION = [
 		]
 	})}`
 ].join("\n");
-//#endregion
-//#region src/core/errors.ts
+// src/core/errors.ts
 /**
 * Represents a package-owned tool-call failure: malformed input or unresolved configuration (`TOOL`),
 * delegation depth/cycle rejection (`DEPTH`), prompt failure (`DEADLOCK` / `EXPIRE` / `ANSWER`),
@@ -610,6 +609,7 @@ var ToolboxError = class extends Error {
 	code;
 	constructor(code, message, context) {
 		super(message);
+		_orkestrel_contract.INTRINSICS.define(this, Symbol.for("@orkestrel/toolbox.ToolboxError"), { value: this });
 		this.name = "ToolboxError";
 		this.code = code;
 		if (context !== void 0) this.context = context;
@@ -618,6 +618,10 @@ var ToolboxError = class extends Error {
 /**
 * Narrows an unknown caught value to a {@link ToolboxError}.
 *
+* @remarks
+* Recognizes the self-brand across package copies and subclasses without requiring a name.
+* Rejects transparent proxies and validates the code and optional context.
+*
 * @param value - The value to test (typically a `catch` binding)
 * @returns True if `value` is an {@link ToolboxError}; false otherwise
 *
@@ -633,10 +637,14 @@ var ToolboxError = class extends Error {
 * ```
 */
 function isToolboxError(value) {
-	return (0, _orkestrel_contract.isInstance)(value, ToolboxError);
+	return (0, _orkestrel_contract.holds)(() => {
+		if (!(value instanceof Error && _orkestrel_contract.INTRINSICS.prototype(value) !== Error.prototype && _orkestrel_contract.INTRINSICS.describe(value, Symbol.for("@orkestrel/toolbox.ToolboxError"))?.value === value)) return false;
+		const code = _orkestrel_contract.INTRINSICS.reflect.read(value, "code");
+		const context = _orkestrel_contract.INTRINSICS.reflect.read(value, "context");
+		return (code === "TOOL" || code === "DEPTH" || code === "DEADLOCK" || code === "EXPIRE" || code === "ANSWER" || code === "DATABASE" || code === "RELATION") && (context === void 0 || (0, _orkestrel_contract.isObject)(context) || (0, _orkestrel_contract.isFunction)(context));
+	});
 }
-//#endregion
-//#region src/core/validators.ts
+// src/core/validators.ts
 /**
 * Narrows an unknown value to a valid alternating workflow lineage.
 *
@@ -726,8 +734,7 @@ function isDatabaseDefinition(value) {
 	if (value.version !== void 0 && !(0, _orkestrel_contract.isFiniteNumber)(value.version)) return false;
 	return true;
 }
-//#endregion
-//#region src/core/shapers.ts
+// src/core/shapers.ts
 /**
 * Describes the shape of {@link import('./factories.js').createPromptTool}'s call arguments — `to` names the
 * terminal identity and `schema` carries the complete multi-field form document.
@@ -1309,8 +1316,7 @@ var inferToolShape = (0, _orkestrel_contract.objectShape)({
 	enum: (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.booleanShape)({ description: "Infer enum constraints from repeated literal values. Defaults to false." })),
 	candidates: (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.arrayShape)((0, _orkestrel_contract.jsonShape)(), { description: "Optional values to check against the freshly inferred schema. When present, the tool returns a per-candidate verdict (strict — no coercion) alongside the inferred parameters." }))
 });
-//#endregion
-//#region src/core/helpers.ts
+// src/core/helpers.ts
 /**
 * Returns the ancestry identifier of a workflow in a run chain — `workflow:<id>`.
 *
@@ -1556,51 +1562,46 @@ function inferRelationCode(error) {
 * ```
 */
 function expandInclude(paths, depth) {
-	let include = {};
-	for (const path of paths ?? []) {
+	return Iterator.from(paths ?? []).reduce((include, path) => {
 		const segments = path.split(".");
 		if (segments.length > depth || segments.some((segment) => segment.length === 0)) throw new ToolboxError("TOOL", `malformed include path '${path}'`, {
 			path,
 			depth
 		});
-		const ancestors = [];
-		let branch = include;
+		const ancestors = [include];
 		const last = segments.length - 1;
-		for (let index = 0; index < last; index++) {
-			const segment = segments[index];
-			if (segment === void 0) throw new ToolboxError("TOOL", `malformed include path '${path}'`, {
+		for (const [index, segment] of segments.entries()) {
+			if (index === last) break;
+			const branch = ancestors.at(-1);
+			if (branch === void 0) throw new ToolboxError("TOOL", `malformed include path '${path}'`, {
 				path,
 				depth
 			});
-			ancestors.push(branch);
 			const existing = branch[segment];
-			branch = (0, _orkestrel_contract.isObject)(existing) ? existing : {};
+			ancestors.push((0, _orkestrel_contract.isObject)(existing) ? existing : {});
 		}
 		const leaf = segments[last];
-		if (leaf === void 0) throw new ToolboxError("TOOL", `malformed include path '${path}'`, {
+		const branch = ancestors.at(-1);
+		if (leaf === void 0 || branch === void 0) throw new ToolboxError("TOOL", `malformed include path '${path}'`, {
 			path,
 			depth
 		});
 		const existing = branch[leaf];
-		let merged = {
-			...branch,
-			[leaf]: existing === void 0 ? true : existing
-		};
-		for (let index = last - 1; index >= 0; index--) {
-			const ancestor = ancestors[index];
+		return ancestors.slice(0, -1).reduceRight((merged, ancestor, index) => {
 			const segment = segments[index];
-			if (ancestor === void 0 || segment === void 0) throw new ToolboxError("TOOL", `malformed include path '${path}'`, {
+			if (segment === void 0) throw new ToolboxError("TOOL", `malformed include path '${path}'`, {
 				path,
 				depth
 			});
-			merged = {
+			return {
 				...ancestor,
 				[segment]: merged
 			};
-		}
-		include = merged;
-	}
-	return include;
+		}, {
+			...branch,
+			[leaf]: existing === void 0 ? true : existing
+		});
+	}, {});
 }
 /**
 * Resolves which registered {@link RelationManagerInterface} a relation-tool call addresses — the
@@ -1736,8 +1737,28 @@ function clampQuery(query, cap) {
 		limit
 	};
 }
-//#endregion
-//#region src/core/compilers.ts
+/**
+* Resolves an owned workflow input through the supplied flat or draft contracts.
+* @example
+* ```ts
+* import { createContract } from '@orkestrel/contract'
+* import { completeDraft, createWorkflowDraftContract, resolveWorkflowTarget, workflowStepsShape } from '@src/core'
+*
+* const definition = completeDraft({ phases: [{ tasks: [{}] }] })
+* const steps: import('@orkestrel/contract').ContractInterface<import('./types.js').WorkflowSteps> = createContract(workflowStepsShape)
+* resolveWorkflowTarget({}, definition, steps, createWorkflowDraftContract()) // definition
+* ```
+*/
+function resolveWorkflowTarget(owned, definition, steps, draft) {
+	if (Object.keys(owned).length === 0) return definition;
+	if ((0, _orkestrel_contract.isArray)(owned.steps)) {
+		const flat = steps.parse(owned);
+		return flat === void 0 ? void 0 : expandSteps(flat);
+	}
+	const parsed = draft.parse(owned);
+	return parsed === void 0 ? void 0 : completeDraft(parsed);
+}
+// src/core/compilers.ts
 /**
 * Compiles a {@link TableSpec} into the `@orkestrel/database` {@link TableMap} it configures —
 * each {@link ColumnSpec} maps to the matching primitive shaper (`'string'` → `stringShape()`,
@@ -1782,8 +1803,7 @@ function compileColumnPrimitive(primitive) {
 	if (primitive === "number") return (0, _orkestrel_contract.numberShape)();
 	return (0, _orkestrel_contract.booleanShape)();
 }
-//#endregion
-//#region src/core/stores/MemoryDefinitionStore.ts
+// src/core/stores/MemoryDefinitionStore.ts
 /**
 * Represents the in-memory {@link DefinitionStoreInterface} — a process-lifetime `Map` of
 * {@link DatabaseDefinition}s keyed by database id, the default store
@@ -1853,8 +1873,7 @@ var MemoryDefinitionStore = class {
 		return Promise.resolve();
 	}
 };
-//#endregion
-//#region src/core/stores/DatabaseDefinitionStore.ts
+// src/core/stores/DatabaseDefinitionStore.ts
 /**
 * Represents a {@link DefinitionStoreInterface} backed by one table of the `@orkestrel/database` layer — a
 * database's durable config state is a row, so persistence reduces to keyed point-access
@@ -1942,8 +1961,7 @@ var DatabaseDefinitionStore = class {
 		await this.#table.remove(id);
 	}
 };
-//#endregion
-//#region src/core/databases/DatabaseResolver.ts
+// src/core/databases/DatabaseResolver.ts
 /**
 * Resolves a database definition into a cached live handle for a database tool, over the tool's
 * live handles, its stored definitions, its driver registry, and an optional key generator.
@@ -2046,8 +2064,7 @@ var DatabaseResolver = class {
 		throw new ToolboxError("TOOL", `unknown database '${id}'`, { id });
 	}
 };
-//#endregion
-//#region src/core/factories.ts
+// src/core/factories.ts
 /**
 * Wraps a registered tool as a {@link WorkflowFunction} (`@orkestrel/workflow`) — the opt-in
 * adapter that lets a `function`-form task run a `@orkestrel/tool` tool by name.
@@ -2336,15 +2353,7 @@ function createWorkflowTool(definition, runner, options) {
 			const cloned = (0, _orkestrel_contract.attempt)(() => (0, _orkestrel_contract.cloneJSONRecord)(args));
 			if (!cloned.success) throw new ToolboxError("TOOL", "malformed workflow definition", { workflow: definition.id });
 			const owned = cloned.value;
-			let target;
-			if (Object.keys(owned).length === 0) target = definition;
-			else if ((0, _orkestrel_contract.isArray)(owned.steps)) {
-				const flat = steps.parse(owned);
-				target = flat === void 0 ? void 0 : expandSteps(flat);
-			} else {
-				const parsed = draft.parse(owned);
-				target = parsed === void 0 ? void 0 : completeDraft(parsed);
-			}
+			const target = resolveWorkflowTarget(owned, definition, steps, draft);
 			if (target === void 0 || !strict.is(target)) throw new ToolboxError("TOOL", "malformed workflow definition", { workflow: definition.id });
 			const tag = tagWorkflow(target.id);
 			if (lineage.includes(tag)) throw new ToolboxError("DEPTH", `workflow '${target.id}' is already an ancestor (cycle)`, {
@@ -3386,7 +3395,6 @@ function createEndpointTool(definition, options) {
 		}
 	});
 }
-//#endregion
 exports.AGENT_TOOL_DEPTH = AGENT_TOOL_DEPTH;
 exports.AGENT_TOOL_DESCRIPTION = AGENT_TOOL_DESCRIPTION;
 exports.AGENT_TOOL_NAME = AGENT_TOOL_NAME;
@@ -3484,6 +3492,7 @@ exports.relationToolShape = relationToolShape;
 exports.resolveLimit = resolveLimit;
 exports.resolveRelationManager = resolveRelationManager;
 exports.resolveRelationModel = resolveRelationModel;
+exports.resolveWorkflowTarget = resolveWorkflowTarget;
 exports.rowShape = rowShape;
 exports.rowsShape = rowsShape;
 exports.singleKeyShape = singleKeyShape;