@rulvar/core 1.17.0 → 1.18.0

package/dist/index.d.ts

@@ -3112,11 +3112,14 @@ interface ResolvedToolset {
 /** The empty toolset (no tools declared anywhere). */
 declare function emptyToolset(): ResolvedToolset;
 /**
-* Expands sources, validates every tool name and duplicate names across
-* the whole toolset (ConfigError at spawn time), and computes the
-* toolsetHash over contracts sorted by name.
-*/
-declare function resolveToolset(specs: ToolsOption | undefined, session: ToolSourceSession): Promise<ResolvedToolset>;
+* Expands registered names and sources, validates every tool name and
+* duplicate names across the whole toolset (ConfigError at spawn time),
+* and computes the toolsetHash over contracts sorted by name. The
+* `toolsets` registry is the engine's `defaults.toolsets` snapshot;
+* without one, string entries fail with the same unknown-name error as
+* a miss, so nothing outside the declared registry is ever reachable.
+*/
+declare function resolveToolset(specs: ToolsOption | undefined, session: ToolSourceSession, toolsets?: Record<string, ToolsOption>): Promise<ResolvedToolset>;
 //#endregion
 //#region src/journal/termination.d.ts
 /** The frozen limits vector written into termination.init. */
@@ -6081,9 +6084,12 @@ declare function tierWithinCaps(tier: StructuredOutputTier, caps: ModelCaps): bo
 /**
 * Renders the registry into the shared agent vocabulary card. Sorted,
 * deterministic, byte-stable; an empty registry renders explicitly so
-* the planner never guesses at unregistered agentTypes.
+* the planner never guesses at unregistered agentTypes. When the engine
+* registers toolsets, their names render as a closing line (v1.17.0
+* review P1-3): those are the ONLY values valid as string entries of a
+* tools option, so the planner never invents a registry name.
 */
-declare function profileCard(profiles: Record<string, AgentProfile> | undefined): string;
+declare function profileCard(profiles: Record<string, AgentProfile> | undefined, toolsets?: Record<string, ToolsOption>): string;
 //#endregion
 //#region src/model/projector.d.ts
 /** The provider family of an adapter: `provider` when set, else `id`. */

package/dist/index.js

@@ -2597,9 +2597,14 @@ function toolContract(def) {
 * Toolset resolution and hashing (M3-T01): expands the per-spawn tools
 * array (ToolDef | ToolSource | string) into the spawn's toolset snapshot,
 * validates names and collisions, and derives toolsetHash from the
-* contracts only. The snapshot is captured at spawn time and stays stable
-* for the agent's lifetime; provider-side drift of a source's tools
-* changes the content key of NEW spawns only.
+* contracts only. A string entry names a registered toolset from
+* `createEngine({ defaults: { toolsets } })` (v1.17.0 review P1-3): the
+* registry snapshot belongs to the engine configuration, so the same
+* name expands identically for direct calls, agent profiles, and the
+* sandbox dialect, and an unknown name is a typed ConfigError at spawn
+* time, before any provider call. The snapshot is captured at spawn
+* time and stays stable for the agent's lifetime; provider-side drift
+* of a source's tools changes the content key of NEW spawns only.
 *
 * Docs: https://docs.rulvar.com/guide/tools.
 */
@@ -2615,21 +2620,35 @@ function isToolDef(spec) {
 	return typeof spec !== "string" && spec.kind === "tool";
 }
 /**
-* Expands sources, validates every tool name and duplicate names across
-* the whole toolset (ConfigError at spawn time), and computes the
-* toolsetHash over contracts sorted by name.
+* Expands registered names and sources, validates every tool name and
+* duplicate names across the whole toolset (ConfigError at spawn time),
+* and computes the toolsetHash over contracts sorted by name. The
+* `toolsets` registry is the engine's `defaults.toolsets` snapshot;
+* without one, string entries fail with the same unknown-name error as
+* a miss, so nothing outside the declared registry is ever reachable.
 */
-async function resolveToolset(specs, session) {
+async function resolveToolset(specs, session, toolsets) {
 	if (specs === void 0 || specs.length === 0) return emptyToolset();
 	const tools = [];
 	for (const spec of specs) {
-		if (typeof spec === "string") throw new ConfigError(`tools by registered name ('${spec}') are not supported here: pass ToolDef or ToolSource values. Registered toolset names exist only for the dynamic orchestrator's spawn_agent toolsetRef (https://docs.rulvar.com/guide/tools)`);
+		if (typeof spec === "string") {
+			const named = toolsets?.[spec];
+			if (named === void 0) throw new ConfigError(`unknown registered toolset '${spec}': register it under defaults.toolsets (https://docs.rulvar.com/guide/tools)`);
+			for (const entry of named) {
+				if (typeof entry === "string") throw new ConfigError(`registered toolset '${spec}' contains the name '${entry}': registry values hold ToolDef or ToolSource entries, never other registered names`);
+				if (isToolDef(entry)) {
+					tools.push(entry);
+					continue;
+				}
+				tools.push(...await entry.tools(session));
+			}
+			continue;
+		}
 		if (isToolDef(spec)) {
 			tools.push(spec);
 			continue;
 		}
-		const imported = await spec.tools(session);
-		tools.push(...imported);
+		tools.push(...await spec.tools(session));
 	}
 	const seen = /* @__PURE__ */ new Map();
 	for (const def of tools) {
@@ -6676,7 +6695,7 @@ function affordableOutputTokens(pricing, remainingUsd, estimatedInputTokens) {
 //#region src/model/profile-card.ts
 function toolNamesOf(profile) {
 	return (profile.tools ?? []).map((entry) => {
-		if (typeof entry === "string") return `${entry} (profile toolset)`;
+		if (typeof entry === "string") return `${entry} (registered toolset)`;
 		if ("kind" in entry && entry.kind === "tool") return entry.name;
 		return `${entry.id}:* (tool source)`;
 	});
@@ -6684,11 +6703,19 @@ function toolNamesOf(profile) {
 /**
 * Renders the registry into the shared agent vocabulary card. Sorted,
 * deterministic, byte-stable; an empty registry renders explicitly so
-* the planner never guesses at unregistered agentTypes.
-*/
-function profileCard(profiles) {
+* the planner never guesses at unregistered agentTypes. When the engine
+* registers toolsets, their names render as a closing line (v1.17.0
+* review P1-3): those are the ONLY values valid as string entries of a
+* tools option, so the planner never invents a registry name.
+*/
+function profileCard(profiles, toolsets) {
+	const toolsetNames = Object.keys(toolsets ?? {}).sort();
+	const toolsetsLine = toolsetNames.length === 0 ? void 0 : `Registered toolsets (valid string entries of a tools option): ${toolsetNames.join(", ")}.`;
 	const names = Object.keys(profiles ?? {}).sort();
-	if (profiles === void 0 || names.length === 0) return "Agent profiles: none registered. Calls take no agentType.";
+	if (profiles === void 0 || names.length === 0) {
+		const empty = "Agent profiles: none registered. Calls take no agentType.";
+		return toolsetsLine === void 0 ? empty : `${empty}\n${toolsetsLine}`;
+	}
 	const lines = ["Agent profiles (agentType values):"];
 	for (const name of names) {
 		const profile = profiles[name];
@@ -6700,6 +6727,7 @@ function profileCard(profiles) {
 		if (profile.estCost !== void 0) lines.push(`  estCost: ${profile.estCost.toFixed(2)} USD`);
 		if (profile.escalation !== void 0) lines.push(`  escalation: flavor ${profile.escalation.flavor ?? "A"} (opt-in)`);
 	}
+	if (toolsetsLine !== void 0) lines.push(toolsetsLine);
 	return lines.join("\n");
 }
 //#endregion
@@ -10325,7 +10353,7 @@ function createCtx(internals, rootWorkflow) {
 			if (escalation.flavor === "B" && escalation.deadlineMs === void 0) throw new ConfigError("escalation flavor 'B' requires an explicit deadlineMs");
 		}
 		const declaredTools = opts.tools ?? profile?.tools ?? [];
-		const toolset = await resolveToolset(escalation === void 0 ? declaredTools : [...declaredTools, escalateTool()], { runId: internals.runId });
+		const toolset = await resolveToolset(escalation === void 0 ? declaredTools : [...declaredTools, escalateTool()], { runId: internals.runId }, internals.defaults.toolsets);
 		const layers = [
 			callLayer,
 			profileLayer,
@@ -13028,10 +13056,10 @@ function createEngine(options) {
 		pruneRun,
 		profileCard: (names) => {
 			const registered = defaults.profiles ?? {};
-			if (names === void 0) return profileCard(registered);
+			if (names === void 0) return profileCard(registered, defaults.toolsets);
 			const filtered = {};
 			for (const name of names) if (registered[name] !== void 0) filtered[name] = registered[name];
-			return profileCard(filtered);
+			return profileCard(filtered, defaults.toolsets);
 		}
 	};
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulvar/core",
-  "version": "1.17.0",
+  "version": "1.18.0",
   "description": "Rulvar core: L0 contracts, journal kernel, ctx primitives, agent runtime, model router, tool system, dynamic orchestrator, InMemory and JSONL stores, event stream.",
   "type": "module",
   "license": "Apache-2.0",