@llblab/pi-actors 0.56.1 → 0.57.1

package/dist/lib/tools-inspect.js

@@ -25,7 +25,6 @@ import * as ToolsAccess from "./tools-access.js";
 import * as ToolsResponse from "./tools-response.js";
 import * as TraceProjection from "./trace-projection.js";
 const asRecord = ToolsResponse.asRecord;
-const maybeJsonText = ToolsResponse.maybeJsonText;
 function runtimeStatus() {
     return {
         automatic_review: Paths.isAutomaticRecipeReviewEnabled(),
@@ -154,44 +153,80 @@ function runtimeTriage(ctx, deps) {
         ],
     };
 }
+/** Compact metadata-only documents share the same emitter/omission policy as other receipts. */
+function compactDocument(value) {
+    return ToolsResponse.compactYamlDocument(value);
+}
+/** Generated definition metadata is YAML like other owned output; the machine JSON stays in details. */
+function schemaDocument(details) {
+    // Absent definition fields stay absent exactly as JSON.stringify omitted them; values are native nodes.
+    const selected = {};
+    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, value) {
+    return ToolsResponse.selectYamlField(key, value, Limits.RUN_DELIVERY_MODEL_MAX_BYTES);
+}
+function compactArguments(key, value) {
+    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, details) {
-    const fields = view === "runs" ? { runs: details.runs?.length ?? 0 }
+    const count = (value) => (Array.isArray(value) ? value.length : 0);
+    return compactDocument(view === "runs" ? { runtime: view, runs: count(details.runs) }
         : view === "triage" ? {
-            failed: details.failed_runs?.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?.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.
 function formatInspectFailure(fields, next) {
-    // 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) => `- ${key}:\n  - state: omitted\n  - reason: response_too_large\n  - shown: 0\n  - omitted: 1\n  - total: 1`;
-    const field = ([key, value]) => 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) => {
+        const rendered = ToolsResponse.renderYamlMetadata(value, budget);
+        return rendered.state === "available" ? rendered.text : undefined;
+    };
+    const parts = fields.map(([key, value, omittable]) => {
+        const full = typeof value === "string" ? { [key]: value } : { [key]: [...value] };
+        const fallback = { [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(view, input, ctx, deps) {
     if (view === "status")
@@ -312,7 +347,9 @@ function inspectRecipeIdentity(identity, resolutionContext, namespaces, inventor
                 : ["inspect target=recipes view=imports verbose=true"],
     };
 }
-function inspectRecipes(view, input, deps, context) {
+function inspectRecipes(requestedView, input, deps, context) {
+    // `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" &&
         view !== "doctor" &&
@@ -320,7 +357,7 @@ function inspectRecipes(view, input, deps, context) {
         view !== "reviews") {
         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();
@@ -515,40 +552,49 @@ function compactResult(target, view, details) {
     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;
-        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 = () => ({ 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, value) => 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 = () => ({ ...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);
+        return compactDocument({ tool: target.slice(5), view });
+    return compactDocument({ run: target.slice(4), view });
 }
 export function createInspectToolDefinition(deps = {}) {
     return {
@@ -562,7 +608,7 @@ export function createInspectToolDefinition(deps = {}) {
             status: Schema.stringSchema("Optional runtime Run status filter. With verbose runs, failed prioritizes observed failed subtrees without filtering the navigation map."),
             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."),
+            view: Schema.stringSchema("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"]),
         async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
             const input = asRecord(params);
@@ -592,7 +638,11 @@ export function createInspectToolDefinition(deps = {}) {
             return {
                 content: [{
                         type: "text",
-                        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/dist/lib/tools-local.js

@@ -4,6 +4,7 @@
  * Owns wrapping saved local capabilities as executable pi tools
  */
 import * as AsyncRuns from "./async-runs.js";
+import * as Limits from "./limits.js";
 import * as ModelContext from "./model-context.js";
 import * as Execution from "./execution.js";
 import * as Prompts from "./prompts.js";
@@ -44,6 +45,16 @@ function shouldAddRuntimeToolUsageHint(error) {
     const message = error instanceof Error ? error.message : String(error);
     return (/^Argument \S+ must /.test(message) || /^Missing .* value: /.test(message));
 }
+/** Owned usage facts only; the JSON invocation example stays unparsed instructional body text. */
+function runtimeToolUsageMetadata(cfg, required, includeRunId) {
+    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, required, includeRunId) {
     const optional = cfg.args.filter((arg) => !RecipesReferences.isRuntimeOwnedRecipeInput(arg) &&
         !required.includes(arg));
@@ -59,15 +70,10 @@ function formatRuntimeToolUsageHint(cfg, required, includeRunId) {
         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(cfg, callerValues, ctx) {
     const recipeRuntimeValues = {
@@ -88,7 +94,9 @@ function formatRuntimeToolArgumentError(cfg, error, required, includeRunId) {
     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(cfg, exec) {
     const paramSchema = {};

package/dist/lib/tools-message.js

@@ -14,82 +14,96 @@ function asRecord(value) {
         ? value
         : {};
 }
-const controlField = ToolsResponse.formatMarkdownField;
+const CONTROL_BUDGET = Limits.RUN_DELIVERY_MODEL_MAX_BYTES - 1;
+function controlMetadata(value) {
+    return ToolsResponse.renderYamlMetadata(value, CONTROL_BUDGET).text;
+}
+/** One opaque selected scalar as a whole value or an explicit whole-field omission, never a clip. */
+function controlSelected(key, value) {
+    return ToolsResponse.selectYamlField(key, value, CONTROL_BUDGET);
+}
+/** Compiler-selected option strings stay a native sequence; malformed selections stay unavailable. */
+function controlChoices(options) {
+    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 = { [key]: wellFormed ? "[omitted]" : "[unavailable]",
+        [key + "_omission"]: { reason: wellFormed ? "response_too_large" : "malformed_selected_text",
+            shown: 0, omitted: values.length, total: values.length } };
+    const full = !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, order) {
+    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) {
+    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 = { next: { instruction: wellFormed ? "[omitted]" : "[unavailable]",
+            instruction_omission: { reason: wellFormed ? "response_too_large" : "malformed_selected_text", shown: 0, omitted: 1, total: 1 } } };
+    const full = 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(request, result, options) {
     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 = [];
-        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, choices) => 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) {
-    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 = () => ({ ...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. */
 export function compactControlResult(request, result) {
-    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 = {};
     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) => 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 = () => ({ ...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, result) {
     if (result.stopped === true)
@@ -198,16 +212,13 @@ export function createControlToolDefinition(deps = {}) {
                     }
                     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 = () => ({ ...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.

package/dist/lib/tools-response.d.ts

@@ -13,6 +13,20 @@ export type YamlMetadataRendering = {
 };
 /** Pure selected-metadata formatting, not admission or authority. */
 export declare function renderYamlMetadata(value: unknown, byteBudget: number): YamlMetadataRendering;
+export type YamlPart = {
+    full: Record<string, unknown>;
+    selected: Record<string, unknown>;
+};
+/** One selected metadata node, kept whole or covered by a field/group omission. */
+export declare function selectYamlNode(key: string, value: unknown, byteBudget: number, total?: number): YamlPart;
+/** Opaque selected text or string sequence; malformed selections stay unavailable without repair. */
+export declare function selectYamlField(key: string, value: string | readonly string[], byteBudget: number): YamlPart;
+/** Grow whole selected fields in priority order while the complete document still fits. */
+export declare function growYamlDocument(render: () => Record<string, unknown>, order: readonly YamlPart[], byteBudget: number): string;
+/** Uncapped UI-only flat metadata; never borrow a model-output allowance for notices. */
+export declare function formatYamlNotice(value: Record<string, string | number | boolean>): string;
+/** Close one rendered YAML header; a separate opaque body gets exactly one delimiter pair. */
+export declare function frameMetadataDocument(header: string, body?: string): string;
 export declare function formatMarkdownField(key: string, value: string, depth?: number): string;
 export declare function formatInspectNextAction(target: string, view: string, verbose?: boolean): string;
 export declare function formatLiteralBlock(value: string): string;
@@ -42,6 +56,10 @@ export declare function spawnMetadataText(value: unknown, verbose: boolean | und
 export declare function compactRecipeImports(summary: Record<string, unknown>): string;
 export declare function compactRecipeDoctor(summary: Record<string, unknown>): string;
 export declare function recipeRegistryNextActions(summary: Record<string, unknown>, view: string): string[];
+/** Compact metadata-only document text: one leading LF, no trailing LF, shared emitter budget. */
+export declare function compactYamlDocument(value: Record<string, unknown>): string;
+/** Only the closed read-only Recipe inspect literals become typed next; other advice stays opaque content. */
+export declare function nextActionMetadata(action: string, byteBudget: number): YamlPart;
 /** Only these existing read-only inspection hints become action nodes; other advice stays content. */
 export declare function formatInspectionHint(action: string): string;
 export declare function compactRecipeRegistry(summary: Record<string, unknown>): string;