@llblab/pi-actors 0.55.0 → 0.56.1

package/lib/registry.ts

@@ -16,11 +16,13 @@ import {
   writeTextAtomic,
 } from "./file-state.ts";
 import * as Identity from "./identity.ts";
+import * as Limits from "./limits.ts";
 import * as Paths from "./paths.ts";
 import * as RecipesContext from "./recipes-context.ts";
 import * as RecipesDiscovery from "./recipes-discovery.ts";
 import * as RecipesReferences from "./recipes-references.ts";
 import * as Schema from "./schema.ts";
+import * as ToolsResponse from "./tools-response.ts";
 
 export interface RegisterToolInput {
   name?: string;
@@ -89,17 +91,32 @@ function textContent(text: string) {
   return { type: "text" as const, text };
 }
 
+function registryListText(rows: readonly string[]): string {
+  const budget = Limits.RUN_DELIVERY_MODEL_MAX_BYTES - 1;
+  const coverage = (shown: number, reason?: string) => ({ ...(reason ? { reason } : {}), shown, omitted: rows.length - shown, total: rows.length });
+  const malformed = rows.some(row => !row.isWellFormed());
+  if (!malformed) {
+    // Remove only the compiler prefix after the original key coercion and join.
+    const complete = ToolsResponse.renderYamlMetadata({ registered_tools: rows.map(row => row.slice(2)), registered_tools_coverage: coverage(rows.length) }, budget);
+    if (complete.state === "available") return complete.text;
+  }
+  const fallback = ToolsResponse.renderYamlMetadata({ registered_tools: malformed ? "[unavailable]" : "[omitted]", registered_tools_coverage: coverage(0, malformed ? "malformed_selected_text" : "response_too_large") }, budget);
+  // Fixed keys/reasons and finite array-length counts are bounded far below budget.
+  return (fallback as Extract<ToolsResponse.YamlMetadataRendering, { state: "available" }>).text;
+}
+
 function listTools<TContext>(
   deps: RegisterToolRuntimeDeps<TContext>,
 ): RegisterToolResult {
   const names = [...deps.getTools().keys()].sort();
+  const rows = names.length > 0 ? names.map((name) => `- ${name}`) : [];
+  // Retain the original conditional map/join observations before read-time projection.
+  void (names.length > 0 ? `Registered tools:\n${rows.join("\n")}` : "No registered tools.");
   return {
     content: [
       textContent(
         ExecutionOutput.formatToolText(
-          names.length > 0
-            ? `Registered tools:\n${names.map((name) => `- ${name}`).join("\n")}`
-            : "No registered tools.",
+          registryListText(rows),
         ),
       ),
     ],
@@ -155,6 +172,139 @@ function registrationNextActions(
   ];
 }
 
+/** Read-time text only: callers supply the original post-activation selections, not live ports. */
+function registrationReceiptText(data: {
+  tool: string; result: "registered" | "updated" | "persisted"; source: string; callable: boolean;
+  boundary?: string; required: readonly unknown[]; optional: readonly unknown[];
+  warnings: readonly unknown[]; next: string;
+}): string {
+  const budget = Limits.RUN_DELIVERY_MODEL_MAX_BYTES - 1;
+  const renderPart = (value: Record<string, unknown>) => ToolsResponse.renderYamlMetadata(value, budget);
+  const omission = (key: string, count: number, malformed: boolean): Record<string, unknown> => ({
+    [key]: malformed ? "[unavailable]" : "[omitted]",
+    [key + "_omission"]: { reason: malformed ? "malformed_selected_text" : "response_too_large", shown: 0, omitted: count, total: count },
+  });
+  const part = (full: Record<string, unknown>, omitted: Record<string, unknown>) => {
+    const complete = renderPart(full), fallback = renderPart(omitted);
+    return { full, selected: complete.state === "available" && fallback.state === "available" && Buffer.byteLength(complete.text) <= Buffer.byteLength(fallback.text) ? full : omitted };
+  };
+  const scalar = (key: string, value: string) => {
+    const wellFormed = value.isWellFormed();
+    const omitted = omission(key, 1, !wellFormed);
+    return part(wellFormed ? { [key]: value } : omitted, omitted);
+  };
+  const sequence = (key: string, values: readonly unknown[]) => {
+    const rows: string[] = [];
+    let malformed = false;
+    for (let index = 0; index < values.length; index++) {
+      const value = values[index];
+      if (typeof value !== "string" || !value.isWellFormed()) { malformed = true; break; }
+      rows.push(value);
+    }
+    const omitted = omission(key, values.length, malformed);
+    return part(malformed ? omitted : { [key]: rows }, omitted);
+  };
+  const tool = scalar("tool", data.tool);
+  const source = scalar("source", data.source);
+  const required = sequence("required_args", data.required), optional = sequence("optional_args", data.optional);
+  const warnings = data.warnings.length ? sequence("warnings", data.warnings) : undefined;
+  const nextWellFormed = data.next.isWellFormed();
+  const omittedNext = omission("next_action", 1, !nextWellFormed);
+  // This producer knows only its existing status hint; invocation advice stays opaque.
+  const next = part(nextWellFormed
+    ? data.callable ? { instruction: data.next } : { next: { tool: "inspect", target: `tool:${data.tool}`, view: "status" } }
+    : omittedNext, omittedNext);
+  const render = () => renderPart({ ...tool.selected, result: data.result, ...source.selected, callable_now: data.callable,
+    ...(data.boundary === undefined ? {} : { activation_boundary: data.boundary }), ...required.selected, ...optional.selected,
+    ...(warnings ? warnings.selected : {}), ...next.selected });
+  // Preserve complete safety notes before large argument lists; all seeds are monotone.
+  for (const current of [...(warnings ? [warnings] : []), tool, source, next, required, optional]) {
+    if (current.selected === current.full) continue;
+    const previous = current.selected;
+    current.selected = current.full;
+    if (render().state !== "available") current.selected = previous;
+  }
+  return (render() as Extract<ToolsResponse.YamlMetadataRendering, { state: "available" }>).text;
+}
+
+function registryNoticeText(kind: "activated" | "promoted" | "deleted", name: string): string {
+  const report = { activated: "Tool activated", promoted: "Promoted draft recipe", deleted: "Deleted tool" }[kind];
+  const selected = name.isWellFormed() ? ToolsResponse.formatMarkdownField("tool", name)
+    : "- tool: [unavailable]\n- tool_omission:\n  - reason: malformed_selected_text\n  - shown: 0\n  - omitted: 1\n  - total: 1";
+  return ToolsResponse.formatMarkdownField("report", report) + "\n" + selected;
+}
+
+function registrationTransactionFailureText(stage: string, generation: string, summary: string, error: string): string {
+  const field = ToolsResponse.formatMarkdownField;
+  const part = (key: string, value: string) => {
+    const wellFormed = value.isWellFormed();
+    const omitted = `- ${key}: [${wellFormed ? "omitted" : "unavailable"}]\n- ${key}_omission:\n  - reason: ${wellFormed ? "response_too_large" : "malformed_selected_text"}\n  - shown: 0\n  - omitted: 1\n  - total: 1`;
+    const full = wellFormed ? field(key, value) : omitted;
+    return { full, selected: Buffer.byteLength(full) <= Buffer.byteLength(omitted) ? full : omitted };
+  };
+  const selectedGeneration = part("resolution_generation", generation);
+  const selectedSummary = part("active_skills_summary", summary);
+  const selectedError = part("error", error);
+  const render = () => [field("result", "Tool registration transaction failed."), field("stage", stage),
+    selectedGeneration.selected, selectedSummary.selected, selectedError.selected].join("\n");
+  // Keep a fitting surfaced error before large optional resolution metadata.
+  for (const current of [selectedError, selectedGeneration, selectedSummary]) {
+    if (current.selected === current.full) continue;
+    const previous = current.selected;
+    current.selected = current.full;
+    if (Buffer.byteLength(render()) > Limits.RUN_DELIVERY_MODEL_MAX_BYTES - 1) current.selected = previous;
+  }
+  return render();
+}
+
+function candidateAdmissionFailureText(data: { kind: "source"; source: string; diagnostics: string; summary: string; instruction: string } | { kind: "recipe"; diagnostics: string }): string {
+  const field = ToolsResponse.formatMarkdownField;
+  const part = (key: string, value: string, literal = false) => {
+    const wellFormed = value.isWellFormed();
+    const omitted = `- ${key}: [${wellFormed ? "omitted" : "unavailable"}]\n- ${key}_omission:\n  - reason: ${wellFormed ? "response_too_large" : "malformed_selected_text"}\n  - shown: 0\n  - omitted: 1\n  - total: 1`;
+    const full = wellFormed ? field(key, literal ? ToolsResponse.formatLiteralBlock(value) : value) : omitted;
+    return { full, selected: Buffer.byteLength(full) <= Buffer.byteLength(omitted) ? full : omitted };
+  };
+  const diagnostics = part("diagnostics_summary", data.diagnostics);
+  const source = data.kind === "source" ? part("source", data.source, true) : undefined;
+  const summary = data.kind === "source" ? part("active_skills_summary", data.summary) : undefined;
+  const instruction = data.kind === "source" ? part("instruction", data.instruction) : undefined;
+  const render = () => [field("field", "recipe"), ...(source ? [source.selected] : []),
+    field("result", data.kind === "source" ? "Recipe source validation failed." : "Tool recipe validation failed."),
+    diagnostics.selected, ...(summary ? [summary.selected] : []), ...(instruction ? [instruction.selected] : [])].join("\n");
+  // Preserve fitting diagnostics before large optional source/context/advice fields.
+  for (const current of [diagnostics, source, summary, instruction]) {
+    if (!current || current.selected === current.full) continue;
+    const previous = current.selected;
+    current.selected = current.full;
+    if (Buffer.byteLength(render()) > Limits.RUN_DELIVERY_MODEL_MAX_BYTES - 1) current.selected = previous;
+  }
+  return render();
+}
+
+function sourceNormalizationFailureText(source: string, reason: string, summary: string, instruction: string): string {
+  const field = ToolsResponse.formatMarkdownField;
+  const part = (key: string, value: string, literal = false) => {
+    const wellFormed = value.isWellFormed();
+    const omitted = `- ${key}: [${wellFormed ? "omitted" : "unavailable"}]\n- ${key}_omission:\n  - reason: ${wellFormed ? "response_too_large" : "malformed_selected_text"}\n  - shown: 0\n  - omitted: 1\n  - total: 1`;
+    const full = wellFormed ? field(key, literal ? ToolsResponse.formatLiteralBlock(value) : value) : omitted;
+    return { full, selected: Buffer.byteLength(full) <= Buffer.byteLength(omitted) ? full : omitted };
+  };
+  const selectedSource = part("source", source, true);
+  const selectedReason = part("reason", reason);
+  const selectedSummary = part("active_skills_summary", summary);
+  const selectedInstruction = part("instruction", instruction);
+  const render = () => [field("field", "from"), selectedSource.selected, field("result", "Recipe source is invalid."),
+    selectedReason.selected, selectedSummary.selected, selectedInstruction.selected].join("\n");
+  for (const current of [selectedSource, selectedReason, selectedSummary, selectedInstruction]) {
+    if (current.selected === current.full) continue;
+    const previous = current.selected;
+    current.selected = current.full;
+    if (Buffer.byteLength(render()) > Limits.RUN_DELIVERY_MODEL_MAX_BYTES - 1) current.selected = previous;
+  }
+  return render();
+}
+
 function activeSkillSummary(
   resolutionContext: RecipesContext.RecipeResolutionContext,
 ): string {
@@ -168,6 +318,19 @@ function activeSkillSummary(
   return names.length > 0 ? names.join(", ") : "<none>";
 }
 
+function draftPathFailureText(kind: "root" | "missing", reference: string): string {
+  const key = kind === "root" ? "allowed_root" : "path";
+  const render = (selected: string) => "- field: draft\n" + selected + (kind === "root"
+    ? "\n- result: Draft must be under the allowed root.\n- instruction: Use inspect target=recipes view=summary to list drafts."
+    : "\n- result: Draft not found.");
+  const wellFormed = reference.isWellFormed();
+  if (wellFormed) {
+    const complete = render(ToolsResponse.formatMarkdownField(key, ToolsResponse.formatLiteralBlock(reference)));
+    if (Buffer.byteLength(complete) <= Limits.RUN_DELIVERY_MODEL_MAX_BYTES - 1) return complete;
+  }
+  return render(`- ${key}: [${wellFormed ? "omitted" : "unavailable"}]\n- ${key}_omission:\n  - reason: ${wellFormed ? "response_too_large" : "malformed_selected_text"}\n  - shown: 0\n  - omitted: 1\n  - total: 1`);
+}
+
 function assertDraftPath<TContext>(
   deps: RegisterToolRuntimeDeps<TContext>,
   draft: string,
@@ -182,16 +345,63 @@ function assertDraftPath<TContext>(
   ) {
     throw new Error(
       ExecutionOutput.formatToolText(
-        `Draft must be under ${draftRoot}. Use inspect target=recipes view=summary to list drafts.`,
+        draftPathFailureText("root", `${draftRoot}`),
       ),
     );
   }
   if (!existsSync(path)) {
-    throw new Error(ExecutionOutput.formatToolText(`Draft not found: ${path}`));
+    throw new Error(ExecutionOutput.formatToolText(draftPathFailureText("missing", `${path}`)));
   }
   return path;
 }
 
+function draftReceiptText(result: "updated" | "registered", tool: string, callable: string, next: string): string {
+  const budget = Limits.RUN_DELIVERY_MODEL_MAX_BYTES - 1;
+  const renderPart = (value: Record<string, unknown>) => ToolsResponse.renderYamlMetadata(value, budget);
+  const part = (key: string, value: string, rendered: Record<string, unknown>) => {
+    const wellFormed = value.isWellFormed();
+    const omitted: Record<string, unknown> = { [key]: wellFormed ? "[omitted]" : "[unavailable]",
+      [key + "_omission"]: { reason: wellFormed ? "response_too_large" : "malformed_selected_text", shown: 0, omitted: 1, total: 1 } };
+    const full = wellFormed ? rendered : omitted;
+    const complete = renderPart(full), fallback = renderPart(omitted);
+    return { full, selected: complete.state === "available" && fallback.state === "available" && Buffer.byteLength(complete.text) <= Buffer.byteLength(fallback.text) ? full : omitted };
+  };
+  const identity = part("tool", tool, { tool });
+  const flag = part("callable_now", callable, { callable_now: callable });
+  // Only this producer's exact canonical read-only status hint is typed, never body advice.
+  const status = /^inspect target=(tool:[a-z][a-z0-9_]{0,63}) view=status$/u.exec(next);
+  const hint = part("next_action", next, status ? { next: { tool: "inspect", target: status[1], view: "status" } } : { instruction: next });
+  const render = () => renderPart({ ...identity.selected, result, source: "draft", ...flag.selected, ...hint.selected });
+  for (const current of [identity, flag, hint]) {
+    if (current.selected === current.full) continue;
+    const previous = current.selected;
+    current.selected = current.full;
+    if (render().state !== "available") current.selected = previous;
+  }
+  return (render() as Extract<ToolsResponse.YamlMetadataRendering, { state: "available" }>).text;
+}
+
+function duplicateRegistrationText(value: string): string {
+  const render = (selected: string) => "- field: name\n" + selected + "\n- result: Tool already registered.\n- instruction: Use update=true to overwrite.";
+  const wellFormed = value.isWellFormed();
+  if (wellFormed) {
+    const complete = render(ToolsResponse.formatMarkdownField("value", value));
+    if (Buffer.byteLength(complete) <= Limits.RUN_DELIVERY_MODEL_MAX_BYTES - 1) return complete;
+  }
+  return render(`- value: [${wellFormed ? "omitted" : "unavailable"}]\n- value_omission:\n  - reason: ${wellFormed ? "response_too_large" : "malformed_selected_text"}\n  - shown: 0\n  - omitted: 1\n  - total: 1`);
+}
+
+function draftRecipeFailureText(key: "reason" | "diagnostics_summary", value?: string): string {
+  const header = "- field: draft\n- result: Draft recipe is invalid.";
+  if (value === undefined) return header;
+  const wellFormed = value.isWellFormed();
+  if (wellFormed) {
+    const complete = header + "\n" + ToolsResponse.formatMarkdownField(key, value);
+    if (Buffer.byteLength(complete) <= Limits.RUN_DELIVERY_MODEL_MAX_BYTES - 1) return complete;
+  }
+  return header + `\n- ${key}: [${wellFormed ? "omitted" : "unavailable"}]\n- ${key}_omission:\n  - reason: ${wellFormed ? "response_too_large" : "malformed_selected_text"}\n  - shown: 0\n  - omitted: 1\n  - total: 1`;
+}
+
 function promoteDraftRecipe<TContext>(
   name: string,
   input: RegisterToolInput,
@@ -207,7 +417,7 @@ function promoteDraftRecipe<TContext>(
   if ((existing || existsSync(targetPath)) && !input.update) {
     throw new Error(
       ExecutionOutput.formatToolText(
-        `Tool "${name}" already registered. Use update=true to overwrite.`,
+        duplicateRegistrationText(`${name}`),
       ),
     );
   }
@@ -216,7 +426,7 @@ function promoteDraftRecipe<TContext>(
     const reason = RecipesReferences.diagnoseRawRecipeConfigFailure(draftPath);
     throw new Error(
       ExecutionOutput.formatToolText(
-        `Draft recipe is invalid${reason ? `: ${reason}` : "."}`,
+        draftRecipeFailureText("reason", reason ? `${reason}` : undefined),
       ),
     );
   }
@@ -239,7 +449,7 @@ function promoteDraftRecipe<TContext>(
   if (!candidate.validated || !candidate.tool) {
     throw new Error(
       ExecutionOutput.formatToolText(
-        `Draft recipe is invalid: ${candidate.diagnostics.join("; ")}`,
+        draftRecipeFailureText("diagnostics_summary", `${candidate.diagnostics.join("; ")}`),
       ),
     );
   }
@@ -254,12 +464,13 @@ function promoteDraftRecipe<TContext>(
   const argSummary = RecipesDiscovery.summarizeRegisteredToolArgs(promoted);
   const callableNow = activation?.callable_now ?? false;
   const nextActions = registrationNextActions(name, "draft", callableNow);
-  deps.notify(ctx, `Promoted draft recipe: ${name}`, "info");
+  deps.notify(ctx, registryNoticeText("promoted", `${name}`), "info");
   return {
     content: [
       textContent(
         ExecutionOutput.formatToolText(
-          `${existing ? "Updated" : "Registered"} tool "${name}" from draft; callable_now=${callableNow}; next=${nextActions[0]}.`,
+          // Preserve the old name→flag→hint template conversions here, after notify.
+          draftReceiptText(existing ? "updated" : "registered", `${name}`, `${callableNow}`, `${nextActions[0]}`),
         ),
       ),
     ],
@@ -296,6 +507,19 @@ function persistToolRecipe<TContext>(
   return path;
 }
 
+function registryDeletionText(name: string, result: "deleted" | "not found"): string {
+  const budget = Limits.RUN_DELIVERY_MODEL_MAX_BYTES - 1;
+  const facts = { result, ...(result === "deleted" ? { instruction: "Reload to remove it from the complete registry." } : {}) };
+  const wellFormed = name.isWellFormed();
+  if (wellFormed) {
+    const complete = ToolsResponse.renderYamlMetadata({ tool: name, ...facts }, budget);
+    if (complete.state === "available") return complete.text;
+  }
+  const fallback = ToolsResponse.renderYamlMetadata({ tool: wellFormed ? "[omitted]" : "[unavailable]", tool_omission: { reason: wellFormed ? "response_too_large" : "malformed_selected_text", shown: 0, omitted: 1, total: 1 }, ...facts }, budget);
+  // Fixed metadata is well formed and bounded far below budget.
+  return (fallback as Extract<ToolsResponse.YamlMetadataRendering, { state: "available" }>).text;
+}
+
 function deleteTool<TContext>(
   name: string,
   ctx: TContext,
@@ -306,7 +530,7 @@ function deleteTool<TContext>(
     return {
       content: [
         textContent(
-          ExecutionOutput.formatToolText(`Tool "${name}" not found.`),
+          ExecutionOutput.formatToolText(registryDeletionText(`${name}`, "not found")),
         ),
       ],
       details: { tool: name },
@@ -318,12 +542,12 @@ function deleteTool<TContext>(
   deps.setActiveTools(
     deps.getActiveTools().filter((toolName) => toolName !== name),
   );
-  deps.notify(ctx, `Deleted tool: ${name}`, "info");
+  deps.notify(ctx, registryNoticeText("deleted", `${name}`), "info");
   return {
     content: [
       textContent(
         ExecutionOutput.formatToolText(
-          `Deleted tool "${name}". Reload to remove it from the complete registry.`,
+          registryDeletionText(`${name}`, "deleted"),
         ),
       ),
     ],
@@ -384,7 +608,7 @@ function assertTemplateIsNotNestedRecipe(value: unknown): void {
   ) {
     throw new Error(
       ExecutionOutput.formatToolText(
-        "Nested Recipe-shaped templates are not a register_tool source mode. Next: retry with from=<skill>/<recipe> and defaults={...}.",
+        "- field: template\n- result: Nested Recipe-shaped templates are not a register_tool source mode.\n- instruction: retry with from=<skill>/<recipe> and defaults={...}.",
       ),
     );
   }
@@ -402,7 +626,7 @@ function getInputTemplate(
     });
     if (steps.length === 0)
       throw new Error(
-        ExecutionOutput.formatToolText("Tool template sequence is empty."),
+        ExecutionOutput.formatToolText("- field: template\n- result: Tool template sequence is empty."),
       );
     return value;
   }
@@ -414,7 +638,7 @@ function getInputTemplate(
   }
   throw new Error(
     ExecutionOutput.formatToolText(
-      "Tool template must be a string, object, or sequence.",
+      "- field: template\n- result: unsupported template type\n- supported_types:\n  - string\n  - object\n  - sequence",
     ),
   );
 }
@@ -441,7 +665,7 @@ function normalizeDefaults(value: unknown): Record<string, unknown> | undefined
   if (value === undefined) return undefined;
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     throw new Error(
-      ExecutionOutput.formatToolText("Tool defaults must be an object."),
+      ExecutionOutput.formatToolText("- field: defaults\n- result: Tool defaults must be an object."),
     );
   }
   return { ...(value as Record<string, unknown>) };
@@ -502,7 +726,7 @@ function buildAuthoredRecipe(
   if (!description && !from) {
     throw new Error(
       ExecutionOutput.formatToolText(
-        "Tool description is required for command-template registration.",
+        "- field: description\n- result: Tool description is required for command-template registration.",
       ),
     );
   }
@@ -514,7 +738,7 @@ function buildAuthoredRecipe(
     if (runtimeOwnedDefault) {
       throw new Error(
         ExecutionOutput.formatToolText(
-          `Tool defaults cannot set runtime-owned input: ${runtimeOwnedDefault}. Next: remove that default and retry register_tool; the runtime supplies it.`,
+          `- field: defaults\n- key: ${runtimeOwnedDefault}\n- result: Tool defaults cannot set runtime-owned input.\n- instruction: remove that default and retry register_tool; the runtime supplies it.`,
         ),
       );
     }
@@ -534,7 +758,7 @@ function buildAuthoredRecipe(
   const template = getInputTemplate(input.template);
   if (template === null) {
     throw new Error(
-      ExecutionOutput.formatToolText("Tool template cannot be null here."),
+      ExecutionOutput.formatToolText("- field: template\n- result: Tool template cannot be null here."),
     );
   }
   const finalTemplate =
@@ -543,7 +767,7 @@ function buildAuthoredRecipe(
       : template;
   if (!finalTemplate) {
     throw new Error(
-      ExecutionOutput.formatToolText("Tool template is required."),
+      ExecutionOutput.formatToolText("- field: template\n- result: Tool template is required."),
     );
   }
   const authored: Record<string, unknown> = {
@@ -569,7 +793,7 @@ function assertRegisterToolInputModes(input: RegisterToolInput): void {
   if (Object.hasOwn(record, "values")) {
     throw new Error(
       ExecutionOutput.formatToolText(
-        "register_tool values was removed. Next: retry register_tool with defaults for caller inputs, or use from=<skill>/<recipe> for maintained composition.",
+        "- field: values\n- result: register_tool values was removed.\n- replacement_fields:\n  - defaults\n  - from\n- instruction: retry register_tool with defaults for caller inputs, or use from=<skill>/<recipe> for maintained composition.",
       ),
     );
   }
@@ -580,7 +804,7 @@ function assertRegisterToolInputModes(input: RegisterToolInput): void {
   ) {
     throw new Error(
       ExecutionOutput.formatToolText(
-        "Tool from must be a non-empty Recipe reference. Next: retry register_tool with from=<skill>/<recipe> or an explicit .json/.md path.",
+        "- field: from\n- result: Tool from must be a non-empty Recipe reference.\n- reference_forms:\n  - <skill>/<recipe>\n  - explicit .json path\n  - explicit .md path\n- instruction: retry register_tool with from=<skill>/<recipe> or an explicit .json/.md path.",
       ),
     );
   }
@@ -592,7 +816,7 @@ function assertRegisterToolInputModes(input: RegisterToolInput): void {
   if (modeCount > 1) {
     throw new Error(
       ExecutionOutput.formatToolText(
-        "Use exactly one register_tool source mode: from, template, or draft. Next: remove the extra source fields and retry register_tool.",
+        "- result: Use exactly one register_tool source mode.\n- source_modes:\n  - from\n  - template\n  - draft\n- instruction: remove the extra source fields and retry register_tool.",
       ),
     );
   }
@@ -602,12 +826,22 @@ function assertRegisterToolInputModes(input: RegisterToolInput): void {
   ) {
     throw new Error(
       ExecutionOutput.formatToolText(
-        "register_tool from inherits args and async behavior. Next: retry register_tool with from and optional defaults only; omit args and async.",
+        "- field: from\n- result: register_tool from inherits args and async behavior.\n- inherited_fields:\n  - args\n  - async\n- instruction: retry register_tool with from and optional defaults only; omit args and async.",
       ),
     );
   }
 }
 
+function reservedRegistrationNameText(value: string): string {
+  const render = (selected: string) => "- field: name\n" + selected + "\n- result: Reserved tool name.";
+  const wellFormed = value.isWellFormed();
+  if (wellFormed) {
+    const complete = render(ToolsResponse.formatMarkdownField("value", value));
+    if (Buffer.byteLength(complete) <= Limits.RUN_DELIVERY_MODEL_MAX_BYTES - 1) return complete;
+  }
+  return render(`- value: [${wellFormed ? "omitted" : "unavailable"}]\n- value_omission:\n  - reason: ${wellFormed ? "response_too_large" : "malformed_selected_text"}\n  - shown: 0\n  - omitted: 1\n  - total: 1`);
+}
+
 function executeRegisterToolUnlocked<TContext>(
   params: unknown,
   ctx: TContext,
@@ -622,10 +856,10 @@ function executeRegisterToolUnlocked<TContext>(
   if (!input.name) return listTools(deps);
   const name = Identity.normalizeToolName(input.name);
   if (!name)
-    throw new Error(ExecutionOutput.formatToolText("Invalid tool name."));
+    throw new Error(ExecutionOutput.formatToolText("- field: name\n- result: Invalid tool name."));
   if (deps.reservedToolNames.has(name)) {
     throw new Error(
-      ExecutionOutput.formatToolText(`Reserved tool name: ${name}`),
+      ExecutionOutput.formatToolText(reservedRegistrationNameText(`${name}`)),
     );
   }
   if (typeof input.draft === "string" && input.draft.trim()) {
@@ -647,7 +881,7 @@ function executeRegisterToolUnlocked<TContext>(
         : requestedSource ?? "";
       throw new Error(
         ExecutionOutput.formatToolText(
-          `Recipe source "${requestedSource}" is invalid: ${reason}. Active Skills: ${activeSkillSummary(resolutionContext)}. Next: ${recipeDoctorAction(diagnosticSource)}`,
+          sourceNormalizationFailureText(`${requestedSource}`, `${reason}`, `${activeSkillSummary(resolutionContext)}`, `${recipeDoctorAction(diagnosticSource)}`),
         ),
       );
     }
@@ -664,14 +898,14 @@ function executeRegisterToolUnlocked<TContext>(
   if ((authoritative.exists || existing) && !input.update) {
     throw new Error(
       ExecutionOutput.formatToolText(
-        `Tool "${name}" already registered. Use update=true to overwrite.`,
+        duplicateRegistrationText(`${name}`),
       ),
     );
   }
   if (template === undefined && !input.from && !existing) {
     throw new Error(
       ExecutionOutput.formatToolText(
-        "New registration requires exactly one source mode: from, template, or draft. Next: retry register_tool with one source field.",
+        "- result: New registration requires exactly one source mode.\n- source_modes:\n  - from\n  - template\n  - draft\n- instruction: retry register_tool with one source field.",
       ),
     );
   }
@@ -688,8 +922,8 @@ function executeRegisterToolUnlocked<TContext>(
   );
   if (!candidate.validated || !candidate.tool) {
     const sourceDiagnostic = requestedSource
-      ? `Recipe source "${requestedSource}" validation failed: ${candidate.diagnostics.join("; ")}. Active Skills: ${activeSkillSummary(resolutionContext)}. Next: ${recipeDoctorAction(requestedSource)}`
-      : `Tool recipe validation failed: ${candidate.diagnostics.join("; ")}`;
+      ? candidateAdmissionFailureText({ kind: "source", source: `${requestedSource}`, diagnostics: `${candidate.diagnostics.join("; ")}`, summary: `${activeSkillSummary(resolutionContext)}`, instruction: `${recipeDoctorAction(requestedSource)}` })
+      : candidateAdmissionFailureText({ kind: "recipe", diagnostics: `${candidate.diagnostics.join("; ")}` });
     throw new Error(ExecutionOutput.formatToolText(sourceDiagnostic));
   }
   const activeBefore = deps.getActiveTools();
@@ -739,11 +973,11 @@ function executeRegisterToolUnlocked<TContext>(
     deps.setActiveTools(activeBefore);
     throw new Error(
       ExecutionOutput.formatToolText(
-        `Tool registration transaction failed at ${transactionStage} (${resolutionContext.generation}; active Skills: ${activeSkillSummary(resolutionContext)}): ${error instanceof Error ? error.message : String(error)}`,
+        registrationTransactionFailureText(`${transactionStage}`, `${resolutionContext.generation}`, `${activeSkillSummary(resolutionContext)}`, `${error instanceof Error ? error.message : String(error)}`),
       ),
     );
   }
-  deps.notify(ctx, `Tool activated: ${name}`, "info");
+  deps.notify(ctx, registryNoticeText("activated", `${name}`), "info");
   const templateWarnings = CommandTemplates.getCommandTemplateWarnings(
     typeof cfg.recipe?.template === "object" && !Array.isArray(cfg.recipe.template)
       ? cfg.recipe.template
@@ -757,14 +991,19 @@ function executeRegisterToolUnlocked<TContext>(
   const source = requestedSource ?? "template";
   const argSummary = RecipesDiscovery.summarizeRegisteredToolArgs(cfg);
   const nextActions = registrationNextActions(name, source, callableNow);
+  let displayBoundary: string | undefined;
   const outcomeText = callableNow
     ? `${existing ? "Updated" : "Registered"} tool "${name}" from ${source}; callable_now=true`
-    : `Persisted tool "${name}" from ${source}; callable_now=false; activation_boundary=${activationBoundary(activation)}`;
+    : `Persisted tool "${name}" from ${source}; callable_now=false; activation_boundary=${displayBoundary = activationBoundary(activation)}`;
+  // Keep original fallible advisory evaluation/order after effects, before the new text.
+  void `${outcomeText}; required=${Schema.formatToolArgs(argSummary.required)}; optional=${Schema.formatToolArgs(argSummary.optional)}; next=${nextActions[0]}.${warningText}`;
   return {
     content: [
       textContent(
         ExecutionOutput.formatToolText(
-          `${outcomeText}; required=${Schema.formatToolArgs(argSummary.required)}; optional=${Schema.formatToolArgs(argSummary.optional)}; next=${nextActions[0]}.${warningText}`,
+          registrationReceiptText({ tool: name, result: callableNow ? existing ? "updated" : "registered" : "persisted",
+            source, callable: Boolean(callableNow), boundary: displayBoundary, required: argSummary.required,
+            optional: argSummary.optional, warnings: templateWarnings, next: nextActions[0] }),
         ),
       ),
     ],