@llblab/pi-actors 0.56.1 → 0.57.0

package/lib/tools-inspect.ts

@@ -30,7 +30,6 @@ import * as ToolsResponse from "./tools-response.ts";
 import * as TraceProjection from "./trace-projection.ts";
 
 const asRecord = ToolsResponse.asRecord;
-const maybeJsonText = ToolsResponse.maybeJsonText;
 
 export interface InspectToolDeps<TContext = unknown> {
   getRunStatus?: (runOrDir: string) => Record<string, any>;
@@ -185,16 +184,44 @@ function runtimeTriage(
   };
 }
 
+/** Compact metadata-only documents share the same emitter/omission policy as other receipts. */
+function compactDocument(value: Record<string, unknown>): string {
+  return ToolsResponse.compactYamlDocument(value);
+}
+
+/** Generated definition metadata is YAML like other owned output; the machine JSON stays in details. */
+function schemaDocument(details: Record<string, unknown>): string {
+  // Absent definition fields stay absent exactly as JSON.stringify omitted them; values are native nodes.
+  const selected: Record<string, unknown> = {};
+  for (const key of ["name", "description", "parameters", "promptSnippet"])
+    if (details[key] !== undefined) selected[key] = details[key];
+  // The shared emitter's own execution ceiling is the only wider allowance; a pathological schema
+  // keeps the exact legacy JSON text rather than being clipped or partly reformatted.
+  const rendered = ToolsResponse.renderYamlMetadata(selected, 49152);
+  return rendered.state === "available"
+    ? `\n${rendered.text}` : `\n${JSON.stringify(details, null, 2)}`;
+}
+
+function compactSelected(key: string, value: string): ToolsResponse.YamlPart {
+  return ToolsResponse.selectYamlField(key, value, Limits.RUN_DELIVERY_MODEL_MAX_BYTES);
+}
+
+function compactArguments(key: string, value: unknown): ToolsResponse.YamlPart {
+  const selected = Array.isArray(value) && value.length
+    ? value.map(item => String(item)) : Array.isArray(value) ? "none" : "unknown";
+  return ToolsResponse.selectYamlField(key, selected, Limits.RUN_DELIVERY_MODEL_MAX_BYTES);
+}
+
 function compactRuntime(view: string, details: Record<string, unknown>): string {
-  const fields = view === "runs" ? { runs: (details.runs as unknown[] | undefined)?.length ?? 0 }
+  const count = (value: unknown) => (Array.isArray(value) ? value.length : 0);
+  return compactDocument(view === "runs" ? { runtime: view, runs: count(details.runs) }
     : view === "triage" ? {
-      failed: (details.failed_runs as unknown[] | undefined)?.length ?? 0,
+      runtime: view, failed: count(details.failed_runs),
       pending_controls: Number(details.pending_control_count ?? 0), stale_controls: Number(details.stale_control_count ?? 0),
       backpressured: Number(details.backpressured_run_count ?? 0), incomplete_trace: Number(details.trace_diagnostic_count ?? 0),
-      attention: (details.attention_events as unknown[] | undefined)?.length ?? 0,
-    } : { version: String(details.version), state_schema: String(details.state_schema), automatic_review: String(details.automatic_review) };
-  return "\n" + [ToolsResponse.formatMarkdownField("runtime", view),
-    ...Object.entries(fields).map(([key, value]) => ToolsResponse.formatMarkdownField(key, String(value)))].join("\n");
+      attention: count(details.attention_events),
+    } : { runtime: view, version: String(details.version), state_schema: String(details.state_schema),
+      automatic_review: String(details.automatic_review) });
 }
 
 // Projects local refusals only; does not intercept other throws or change existing catches.
@@ -202,28 +229,39 @@ function formatInspectFailure(
   fields: readonly (readonly [key: string, value: string | readonly string[], omittable?: true])[],
   next?: readonly [target: string, view: string],
 ): string {
-  // The unchanged public adapter adds exactly one leading LF to these Error messages.
-  const budget = Limits.RUN_DELIVERY_MODEL_MAX_BYTES - 1;
-  const omitted = (key: string) => `- ${key}:\n  - state: omitted\n  - reason: response_too_large\n  - shown: 0\n  - omitted: 1\n  - total: 1`;
-  const field = ([key, value]: (typeof fields)[number]) => typeof value === "string"
-    ? ToolsResponse.formatMarkdownField(key, value)
-    : `- ${key}:\n${value.map(item => `  - ${item}`).join("\n")}`;
-  // Unmarked fields are bounded compiler literals/lists. Short values seed full so admission only grows.
-  const formatted = fields.map(field);
-  const projected = fields.map((item, index) => {
-    const full = formatted[index]!, fallback = omitted(item[0]);
-    return item[2] && Buffer.byteLength(full, "utf8") > Buffer.byteLength(fallback, "utf8") ? fallback : full;
-  });
-  let action = next ? ToolsResponse.formatInspectNextAction(next[0], next[1]) : "";
-  const text = () => [...projected, ...(action ? [action] : [])].join("\n");
-  if (next && Buffer.byteLength(text(), "utf8") > budget) action = omitted("next_action");
-  fields.forEach((item, index) => {
-    if (!item[2]) return;
-    const fallback = projected[index]!;
-    projected[index] = formatted[index]!;
-    if (Buffer.byteLength(text(), "utf8") > budget) projected[index] = fallback;
+  // The unchanged public adapter replaces this document's trailing LF with its one leading LF.
+  const budget = Limits.RUN_DELIVERY_MODEL_MAX_BYTES;
+  // Field-local coverage record: an unfit selected scalar/sequence is omitted whole, never clipped.
+  const omitted = { state: "omitted", reason: "response_too_large", shown: 0, omitted: 1, total: 1 };
+  const render = (value: Record<string, unknown>): string | undefined => {
+    const rendered = ToolsResponse.renderYamlMetadata(value, budget);
+    return rendered.state === "available" ? rendered.text : undefined;
+  };
+  const parts = fields.map(([key, value, omittable]) => {
+    const full: Record<string, unknown> = typeof value === "string" ? { [key]: value } : { [key]: [...value] };
+    const fallback: Record<string, unknown> = { [key]: omitted };
+    // Unmarked fields are bounded compiler literals/lists. Short values seed full so admission only grows.
+    const complete = render(full);
+    const selected = omittable && (complete === undefined || Buffer.byteLength(complete) > Buffer.byteLength(render(fallback) ?? ""))
+      ? fallback : full;
+    return { omittable, full, selected };
   });
-  return text();
+  // Only producer-known read-only inspect literals become a typed next, never a parsed action.
+  const typedNext = next ? { next: { tool: "inspect", target: next[0], view: next[1] } } : undefined;
+  const nextFallback = { next_action: omitted };
+  const document = () => ({ ...Object.assign({}, ...parts.map((part) => part.selected)),
+    ...(typedNext ?? nextFallback) });
+  let selectedNext = typedNext;
+  if (next && render(document()) === undefined) selectedNext = undefined;
+  const nextValue = () => (next ? (selectedNext ?? nextFallback) : {});
+  for (const part of parts) {
+    if (!part.omittable) continue;
+    const previous = part.selected;
+    part.selected = part.full;
+    if (render({ ...Object.assign({}, ...parts.map((item) => item.selected)), ...nextValue() }) === undefined) part.selected = previous;
+  }
+  const text = render({ ...Object.assign({}, ...parts.map((item) => item.selected)), ...nextValue() });
+  return (text ?? "").replace(/\n$/u, "");
 }
 
 function inspectRuntime(
@@ -387,11 +425,13 @@ function inspectRecipeIdentity(
 }
 
 function inspectRecipes(
-  view: string,
+  requestedView: string,
   input: Record<string, unknown>,
   deps: InspectToolDeps,
   context: unknown,
 ): Record<string, unknown> {
+  // `registry` and `summary` name one inspection path; only `verbose` selects compact versus full output.
+  const view = requestedView === "registry" ? "summary" : requestedView;
   if (
     view !== "status" &&
     view !== "summary" &&
@@ -401,7 +441,7 @@ function inspectRecipes(
   ) {
     throw new Error(formatInspectFailure([
       ["target_kind", "recipes"], ["result", "unsupported view"],
-      ["supported_views", ["status", "summary", "doctor", "imports", "reviews"]],
+      ["supported_views", ["status", "summary", "registry", "doctor", "imports", "reviews"]],
     ]));
   }
   const recipeRoot = deps.recipeRoot ?? Paths.getRecipeRoot();
@@ -637,37 +677,47 @@ function inspectTool(
 function compactResult(target: string, view: string, details: Record<string, unknown>): string {
   if (target === "runtime") return compactRuntime(view, details);
   if (target === "recipes" && typeof details.identity === "string") {
-    const fields = [ToolsResponse.formatMarkdownField("recipes", "doctor"),
-      ...["identity", "skill_active", "resolvable", "catalog_partial", "component_status"]
-        .map(key => ToolsResponse.formatMarkdownField(key, String(details[key]))),
-      ...(details.source_location ? [ToolsResponse.formatMarkdownField("source_location", ToolsResponse.formatLiteralBlock(String(details.source_location)))] : []),
-      ToolsResponse.formatMarkdownField("resolution_generation", String(details.resolution_generation)),
-      ...(details.rejected_reason ? [ToolsResponse.formatMarkdownField("rejected_reason", String(details.rejected_reason))] : [])];
+    const identity = compactSelected("identity", String(details.identity));
+    const location = typeof details.source_location === "string"
+      ? compactSelected("source_location", details.source_location) : undefined;
+    const generation = compactSelected("resolution_generation", String(details.resolution_generation));
+    const rejected = typeof details.rejected_reason === "string"
+      ? compactSelected("rejected_reason", details.rejected_reason) : undefined;
     const actions = details.next_actions as unknown[] | undefined;
-    if (actions?.length) fields.push(ToolsResponse.formatInspectionHint(String(actions[0])));
-    return "\n" + fields.join("\n");
+    const hint = actions?.length
+      ? ToolsResponse.nextActionMetadata(String(actions[0]), Limits.RUN_DELIVERY_MODEL_MAX_BYTES) : undefined;
+    const parts = [identity, ...(location ? [location] : []), generation, ...(rejected ? [rejected] : []), ...(hint ? [hint] : [])];
+    const render = (): Record<string, unknown> => ({ recipes: "doctor", ...identity.selected,
+      skill_active: String(details.skill_active), resolvable: String(details.resolvable),
+      catalog_partial: String(details.catalog_partial), component_status: String(details.component_status),
+      ...(location ? location.selected : {}), ...generation.selected, ...(rejected ? rejected.selected : {}),
+      ...(hint ? hint.selected : {}) });
+    return `\n${ToolsResponse.growYamlDocument(render, parts, Limits.RUN_DELIVERY_MODEL_MAX_BYTES).replace(/\n$/u, "")}`;
   }
   if (target === "recipes") return ToolsResponse.compactRecipeRegistry(details);
   if (target.startsWith("tool:") && view === "status") {
-    const argumentsField = (key: string, value: unknown): string => Array.isArray(value) && value.length
-      ? "- " + key + ":\n" + value.map(item => "  - " + String(item).replace(/\r\n|\r|\n/gu, match => match + "    ")).join("\n")
-      : ToolsResponse.formatMarkdownField(key, Array.isArray(value) ? "none" : "unknown");
+    const name = target.slice(5);
+    const tool = compactSelected("tool", name);
+    const source = compactSelected("source", String(details.source ?? "unknown"));
+    const boundary = compactSelected("activation_boundary", String(details.activation_boundary ?? "unknown"));
     const next = Array.isArray(details.next_actions) && details.next_actions.length > 0
       ? String(details.next_actions[0])
       : details.callable_now === true
-        ? `call tool ${target.slice(5)}`
-        : `register_tool name=${target.slice(5)} update=true`;
-    return "\n" + [ToolsResponse.formatMarkdownField("tool", target.slice(5)),
-      ToolsResponse.formatMarkdownField("source", String(details.source ?? "unknown")),
-      ToolsResponse.formatMarkdownField("callable_now", String(details.callable_now ?? false)),
-      ToolsResponse.formatMarkdownField("activation_boundary", String(details.activation_boundary ?? "unknown")),
-      argumentsField("required_args", details.required_args), argumentsField("optional_args", details.optional_args),
-      ToolsResponse.formatMarkdownField("launch_kind", String(details.launch_kind ?? "none")),
-      ToolsResponse.formatMarkdownField("spawn_calls", String(Number(details.spawn_calls ?? 0))),
-      ToolsResponse.formatMarkdownField("tool_calls", String(Number(details.tool_calls ?? 0))), ToolsResponse.formatInspectionHint(next)].join("\n");
+        ? `call tool ${name}`
+        : `register_tool name=${name} update=true`;
+    const hint = ToolsResponse.nextActionMetadata(next, Limits.RUN_DELIVERY_MODEL_MAX_BYTES);
+    const required = compactArguments("required_args", details.required_args);
+    const optional = compactArguments("optional_args", details.optional_args);
+    const render = (): Record<string, unknown> => ({ ...tool.selected, ...source.selected,
+      callable_now: details.callable_now === true, ...boundary.selected,
+      ...required.selected, ...optional.selected,
+      launch_kind: String(details.launch_kind ?? "none"),
+      spawn_calls: Number(details.spawn_calls ?? 0), tool_calls: Number(details.tool_calls ?? 0),
+      ...hint.selected });
+    return `\n${ToolsResponse.growYamlDocument(render, [tool, source, boundary, required, optional, hint], Limits.RUN_DELIVERY_MODEL_MAX_BYTES).replace(/\n$/u, "")}`;
   }
-  if (target.startsWith("tool:")) return "\n" + ToolsResponse.formatMarkdownField("tool", target.slice(5)) + "\n" + ToolsResponse.formatMarkdownField("view", view);
-  return "\n" + ToolsResponse.formatMarkdownField("run", target.slice(4)) + "\n" + ToolsResponse.formatMarkdownField("view", view);
+  if (target.startsWith("tool:")) return compactDocument({ tool: target.slice(5), view });
+  return compactDocument({ run: target.slice(4), view });
 }
 
 export function createInspectToolDefinition<TContext = unknown>(
@@ -691,7 +741,7 @@ export function createInspectToolDefinition<TContext = unknown>(
         target: Schema.stringSchema("Target: run:<id>, runtime, recipes, or tool:<name>."),
         verbose: Schema.booleanSchema("Return full JSON instead of compact text."),
         view: Schema.stringSchema(
-          "Run view recipe|trace|control, or target-specific management view.",
+          "Run view recipe|trace|control, or one target-specific management view. runtime status|runs|triage; recipes status|summary|doctor|imports|reviews, where registry aliases summary; tool status|schema.",
         ),
       },
       ["target", "view"],
@@ -726,11 +776,11 @@ export function createInspectToolDefinition<TContext = unknown>(
       return {
         content: [{
           type: "text" as const,
-          text: maybeJsonText(
-            details,
-            input.verbose === true || (target.startsWith("tool:") && view === "schema"),
-            compactResult(target, view, details),
-          ),
+          text: input.verbose === true
+            ? ToolsResponse.jsonText(details)
+            : target.startsWith("tool:") && view === "schema"
+              ? schemaDocument(details)
+              : compactResult(target, view, details),
         }],
         details,
       };

package/lib/tools-local.ts

@@ -6,6 +6,7 @@
 
 import * as AsyncRuns from "./async-runs.ts";
 import * as CommandTemplates from "./command-templates.ts";
+import * as Limits from "./limits.ts";
 import * as ModelContext from "./model-context.ts";
 import type { RegisteredTool } from "./config.ts";
 import * as Execution from "./execution.ts";
@@ -66,6 +67,25 @@ function shouldAddRuntimeToolUsageHint(error: unknown): boolean {
   );
 }
 
+/** Owned usage facts only; the JSON invocation example stays unparsed instructional body text. */
+function runtimeToolUsageMetadata(
+  cfg: RegisteredTool,
+  required: string[],
+  includeRunId: boolean,
+): string {
+  const optional = cfg.args.filter(
+    (arg) =>
+      !RecipesReferences.isRuntimeOwnedRecipeInput(arg) &&
+      !required.includes(arg),
+  );
+  const budget = Limits.RUN_DELIVERY_MODEL_MAX_BYTES;
+  const tool = ToolsResponse.selectYamlField("tool", cfg.name, budget);
+  const requiredPart = ToolsResponse.selectYamlField("required", required, budget);
+  const optionalPart = ToolsResponse.selectYamlField("optional", [...optional, ...(includeRunId ? ["run_id"] : [])], budget);
+  return ToolsResponse.growYamlDocument(() => ({ ...tool.selected, ...requiredPart.selected, ...optionalPart.selected }),
+    [tool, requiredPart, optionalPart], budget);
+}
+
 function formatRuntimeToolUsageHint(
   cfg: RegisteredTool,
   required: string[],
@@ -87,16 +107,10 @@ function formatRuntimeToolUsageHint(
   for (const arg of optional)
     example[arg] = sampleValueForArg(arg, cfg.argTypes?.[arg], exampleDefaults);
   if (includeRunId) example.run_id = `${cfg.name}-1`;
-  const lines = [
+  return [
     `Expected call shape for ${cfg.name}:`,
     `${cfg.name}(${JSON.stringify(example, null, 2)})`,
-  ];
-  if (required.length) lines.push(`Required: ${required.join(", ")}`);
-  if (optional.length || includeRunId)
-    lines.push(
-      `Optional: ${[...optional, ...(includeRunId ? ["run_id"] : [])].join(", ")}`,
-    );
-  return lines.join("\n");
+  ].join("\n");
 }
 
 function resolveRecipeToolValues(
@@ -134,13 +148,10 @@ function formatRuntimeToolArgumentError(
   const message = error instanceof Error ? error.message : String(error);
   if (!shouldAddRuntimeToolUsageHint(error))
     return error instanceof Error ? error : new Error(message);
-  return new Error(
-    `Invalid arguments for tool "${cfg.name}": ${message}\n\n${formatRuntimeToolUsageHint(
-      cfg,
-      required,
-      includeRunId,
-    )}`,
-  );
+  // Whole usage groups fit the header budget or carry explicit omission; the JSON example stays opaque.
+  const header = runtimeToolUsageMetadata(cfg, required, includeRunId);
+  return new Error(ToolsResponse.withLeadingLineBreak(ToolsResponse.frameMetadataDocument(header,
+    `Invalid arguments for tool "${cfg.name}": ${message}\n\n${formatRuntimeToolUsageHint(cfg, required, includeRunId)}`)));
 }
 
 export function createRuntimeToolDefinition(

package/lib/tools-message.ts

@@ -17,7 +17,54 @@ function asRecord(value: unknown): Record<string, unknown> {
     : {};
 }
 
-const controlField = ToolsResponse.formatMarkdownField;
+const CONTROL_BUDGET = Limits.RUN_DELIVERY_MODEL_MAX_BYTES - 1;
+
+type ControlDocument = Record<string, unknown>;
+type ControlPart = { full: ControlDocument; selected: ControlDocument };
+
+function controlMetadata(value: ControlDocument): string {
+  return (ToolsResponse.renderYamlMetadata(value, CONTROL_BUDGET) as
+    Extract<ToolsResponse.YamlMetadataRendering, { state: "available" }>).text;
+}
+
+/** One opaque selected scalar as a whole value or an explicit whole-field omission, never a clip. */
+function controlSelected(key: string, value: string): ControlPart {
+  return ToolsResponse.selectYamlField(key, value, CONTROL_BUDGET);
+}
+
+/** Compiler-selected option strings stay a native sequence; malformed selections stay unavailable. */
+function controlChoices(options: { key: "supported_actions" | "available_actions"; values: readonly string[] }): ControlPart {
+  const key = options.key, values = options.values;
+  // Values were selected by the original string filter, not a new action grammar.
+  const wellFormed = values.every((value) => typeof value === "string" && value.isWellFormed());
+  const omitted: ControlDocument = { [key]: wellFormed ? "[omitted]" : "[unavailable]",
+    [key + "_omission"]: { reason: wellFormed ? "response_too_large" : "malformed_selected_text",
+      shown: 0, omitted: values.length, total: values.length } };
+  const full: ControlDocument = !wellFormed ? omitted : values.length ? { [key]: [...values] } : { [key]: "none" };
+  const complete = ToolsResponse.renderYamlMetadata(full, CONTROL_BUDGET);
+  return { full, selected: complete.state === "available" && Buffer.byteLength(complete.text) <= Buffer.byteLength(controlMetadata(omitted)) ? full : omitted };
+}
+
+/** Grow whole selected fields in priority order while the complete document still fits. */
+function controlDocument(render: () => ControlDocument, order: readonly ControlPart[]): string {
+  return ToolsResponse.growYamlDocument(render, order, CONTROL_BUDGET);
+}
+
+/** Only producer-known read-only inspect literals become typed next; other advice stays opaque content. */
+function controlNextPart(action: string): ControlPart {
+  const inspect = /^inspect target=([^\s]+) view=([^\s]+)$/u.exec(action);
+  if (inspect) {
+    return ToolsResponse.selectYamlNode("next", { tool: "inspect", target: inspect[1], view: inspect[2] }, CONTROL_BUDGET);
+  }
+  const wellFormed = action.isWellFormed();
+  const omitted: ControlDocument = { next: { instruction: wellFormed ? "[omitted]" : "[unavailable]",
+    instruction_omission: { reason: wellFormed ? "response_too_large" : "malformed_selected_text", shown: 0, omitted: 1, total: 1 } } };
+  const full: ControlDocument = wellFormed ? { next: { instruction: action } } : omitted;
+  const complete = wellFormed ? ToolsResponse.renderYamlMetadata(full, CONTROL_BUDGET) : undefined;
+  const selected = complete?.state === "available" && Buffer.byteLength(complete.text) <= Buffer.byteLength(controlMetadata(omitted))
+    ? full : omitted;
+  return { full, selected };
+}
 
 /** Only the four compiler-owned guard sites below; never wraps dispatch/dependency errors. */
 function controlGuardText(
@@ -26,37 +73,12 @@ function controlGuardText(
   options?: { key: "supported_actions" | "available_actions"; values: readonly string[] },
 ): string {
   const key = request.target === "runtime" ? "target" : "run";
-  const identity = controlField(key, request.target === "runtime" ? request.target : request.target.slice(4));
-  const omittedIdentity = `- ${key}: [omitted]\n- ${key}_omission:\n  - reason: response_too_large\n  - shown: 0\n  - omitted: 1\n  - total: 1`;
-  const fixed = [controlField("action", request.action), controlField("result", result)];
-  let fullOptions = "", omittedOptions = "";
-  if (options) {
-    const rows: string[] = [];
-    let malformed = false;
-    // Values were selected by the original string filter, not by a new action grammar.
-    for (let index = 0; index < options.values.length; index++) {
-      const value = options.values[index];
-      if (!value.isWellFormed()) { malformed = true; break; }
-      rows.push("  - " + value.replaceAll(/\r\n|\r|\n/gu, newline => newline + "    "));
-    }
-    omittedOptions = `- ${options.key}: [${malformed ? "unavailable" : "omitted"}]\n- ${options.key}_omission:\n  - reason: ${malformed ? "malformed_selected_text" : "response_too_large"}\n  - shown: 0\n  - omitted: ${options.values.length}\n  - total: ${options.values.length}`;
-    fullOptions = malformed ? omittedOptions : rows.length ? `- ${options.key}:\n${rows.join("\n")}` : controlField(options.key, "none");
-  }
-  // Start with the shorter complete-or-omitted rendering: adding an omission scaffold must
-  // never manufacture overflow when the complete small field would fit. Then grow only.
-  let selectedIdentity = Buffer.byteLength(identity) <= Buffer.byteLength(omittedIdentity) ? identity : omittedIdentity;
-  let selectedOptions = Buffer.byteLength(fullOptions) <= Buffer.byteLength(omittedOptions) ? fullOptions : omittedOptions;
-  const render = (target: string, choices: string) => ToolsResponse.withLeadingLineBreak(
-    [target, ...fixed, ...(options ? [choices] : [])].join("\n"));
-  if (Buffer.byteLength(render(identity, selectedOptions)) <= Limits.RUN_DELIVERY_MODEL_MAX_BYTES) selectedIdentity = identity;
-  if (options && Buffer.byteLength(render(selectedIdentity, fullOptions)) <= Limits.RUN_DELIVERY_MODEL_MAX_BYTES) selectedOptions = fullOptions;
-  return render(selectedIdentity, selectedOptions);
-}
-
-function controlNext(action: string): string {
-  const inspect = /^inspect target=([^\s]+) view=([^\s]+)$/u.exec(action);
-  return inspect ? ToolsResponse.formatInspectNextAction(inspect[1], inspect[2])
-    : "- next:\n" + controlField("instruction", action, 1);
+  const identity = controlSelected(key, request.target === "runtime" ? request.target : request.target.slice(4));
+  const choices = options ? controlChoices(options) : undefined;
+  const render = (): ControlDocument => ({ ...identity.selected, action: request.action, result,
+    ...(choices ? choices.selected : {}) });
+  // Whole identity first, then the complete option sequence: the shorter seed must never manufacture overflow.
+  return ToolsResponse.withLeadingLineBreak(controlDocument(render, choices ? [identity, choices] : [identity]));
 }
 
 /** Pure first-layer copy; legacy stopped/killed flags are not scope-closure proof. */
@@ -64,32 +86,40 @@ export function compactControlResult(
   request: Control.ControlRequest,
   result: Record<string, unknown>,
 ): string {
-  const fields = [request.target.startsWith("run:") ? controlField("run", request.target.slice(4)) : controlField("target", request.target),
-    controlField("action", request.action)];
+  const key = request.target.startsWith("run:") ? "run" : "target";
+  const identity = controlSelected(key, key === "run" ? request.target.slice(4) : request.target);
+  const facts: ControlDocument = {};
   if (result.stopped === false || result.archived === false || result.pruned === false) {
-    fields.push(controlField("result", "not applied"));
-    if (typeof result.reason === "string") fields.push(controlField("reason", result.reason));
-    const observed = asRecord(result.status);
-    if (result.reason === "not running" && typeof observed.status === "string") fields.push(controlField("state", observed.status));
+    facts.result = "not applied";
   } else if (request.action === "kill" && result.stopped === true) {
-    fields.push(controlField("result", "kill attempted"), controlField("termination", "unconfirmed"));
+    facts.result = "kill attempted";
+    facts.termination = "unconfirmed";
   } else if (result.archived === true) {
-    fields.push(controlField("result", "archived"));
+    facts.result = "archived";
   } else if (result.pruned === true) {
-    fields.push(controlField("result", "pruned"));
+    facts.result = "pruned";
   } else if (result.delivery === "queued" || result.delivery === "delivered") {
-    fields.push(controlField("delivery", result.delivery), controlField("handling", "unconfirmed"));
+    facts.delivery = result.delivery;
+    facts.handling = "unconfirmed";
   } else {
-    fields.push(controlField(typeof result.delivery === "string" ? "delivery" : "result",
-      typeof result.delivery === "string" ? result.delivery : typeof result.status === "string" ? result.status : "accepted"));
-    if (typeof result.reason === "string") fields.push(controlField("reason", result.reason));
+    facts[typeof result.delivery === "string" ? "delivery" : "result"] =
+      typeof result.delivery === "string" ? result.delivery : typeof result.status === "string" ? result.status : "accepted";
   }
-  if (typeof result.control_id === "string") fields.push(controlField("control_id", result.control_id));
+  const notApplied = result.stopped === false || result.archived === false || result.pruned === false;
+  const reason = typeof result.reason === "string" ? controlSelected("reason", result.reason) : undefined;
+  const observed = asRecord(result.status);
+  const state = notApplied && result.reason === "not running" && typeof observed.status === "string"
+    ? controlSelected("state", observed.status) : undefined;
+  const controlId = typeof result.control_id === "string" ? controlSelected("control_id", result.control_id) : undefined;
   const actions = Array.isArray(result.next_actions) ? result.next_actions
     : request.target.startsWith("run:") ? runNextActions(request.target.slice(4), result) : [];
   const next = actions.find((action): action is string => typeof action === "string" && action.length > 0);
-  if (next) fields.push(controlNext(next));
-  return ToolsResponse.withLeadingLineBreak(fields.join("\n"));
+  const nextPart = next === undefined ? undefined : controlNextPart(next);
+  const parts = [identity, ...(reason ? [reason] : []), ...(state ? [state] : []), ...(controlId ? [controlId] : []), ...(nextPart ? [nextPart] : [])];
+  const render = (): ControlDocument => ({ ...identity.selected, action: request.action, ...facts,
+    ...(reason ? reason.selected : {}), ...(state ? state.selected : {}), ...(controlId ? controlId.selected : {}),
+    ...(nextPart ? nextPart.selected : {}) });
+  return ToolsResponse.withLeadingLineBreak(controlDocument(render, parts));
 }
 
 function runNextActions(run: string, result: Record<string, unknown>): string[] {
@@ -228,16 +258,13 @@ export function createControlToolDefinition<TContext = unknown>(
             );
           } catch (cause) {
             // Admission-era correlation is not current reply-scope proof after an awaited dispatch.
-            const summary = [controlField("action", request.action), controlField("result", "request failed"),
-              controlField("delivery", "unconfirmed"), controlField("handling", "unconfirmed"),
-              controlField("warning", "Effects may already exist.\nDo not repeat automatically."),
-              controlNext("inspect target=runtime view=runs")].join("\n");
-            // Reserve both line breaks; display one whole caller-owned id or explicit whole-id omission.
-            const identity = controlField("run", run);
-            const target = Buffer.byteLength(identity) <= Limits.RUN_DELIVERY_MODEL_MAX_BYTES - Buffer.byteLength(summary) - 2
-              ? identity
-              : "- run: [omitted]\n- run_omission:\n  - reason: response_too_large\n  - shown: 0\n  - omitted: 1\n  - total: 1";
-            throw new Error(ToolsResponse.withLeadingLineBreak(target + "\n" + summary), { cause });
+            // Display one whole caller-owned id or an explicit whole-id omission; the warning stays literal.
+            const identity = controlSelected("run", run);
+            const next = controlNextPart("inspect target=runtime view=runs");
+            const render = (): ControlDocument => ({ ...identity.selected, action: request.action,
+              result: "request failed", delivery: "unconfirmed", handling: "unconfirmed",
+              warning: "Effects may already exist.\nDo not repeat automatically.", ...next.selected });
+            throw new Error(ToolsResponse.withLeadingLineBreak(controlDocument(render, [identity])), { cause });
           }
         }
         // A refused identity change must not publish the replacement's status, even in verbose/details.