@llblab/pi-actors 0.56.0 → 0.57.0

package/lib/runs-process-windows-mi.ts

@@ -1,6 +1,15 @@
-// Owns: Bounded raw MI wire decoding, query inputs and unadmitted provenance fragments, subordinate to process acquisition.
-// Excludes: Identity construction/digest/comparison, status/liveness/lifecycle/publication/admission,
-// fallback, native invocation and asset loading. Decoded data never admits a representation profile.
+// Owns: Bounded raw MI wire decoding, query inputs, unadmitted provenance fragments, and unrouted
+// helper manifest/asset verification plus a shell-free invocation spec, subordinate to process acquisition.
+// Excludes: Identity construction/digest/comparison, status/liveness/lifecycle/publication/admission, fallback,
+// process spawning and package inventory. No production reader imports this owner; decoded data, verified
+// asset bytes and the invocation spec never admit a representation profile, architecture or activation.
+
+import { createHash } from 'node:crypto';
+
+const MANIFEST_MAX_BYTES = 32 * 1024;
+const EXECUTABLE_MAX_BYTES = 8 * 1024 * 1024;
+const HELPER_VERSION = /^(?:0|[1-9][0-9]{0,5})\.(?:0|[1-9][0-9]{0,5})\.(?:0|[1-9][0-9]{0,5})$/u;
+const MODULE_FILE = /\/lib\/runs-process-windows-mi\.(?:ts|js)$/u;
 
 type NativeStage = 'application' | 'session' | 'input' | 'retrieval' | 'operation' | 'representation' | 'cleanup';
 type RawTimestamp = {
@@ -111,3 +120,158 @@ export function decodeResponse(bytes: Uint8Array, profile: unknown, pids: unknow
   if (optionalNull) return { kind: 'unusable', reason: 'unsupported_optional_fields' };
   return { kind: 'decoded_unadmitted', rows };
 }
+
+/**
+ * Complete-helper manifest claim. Bounded reading, exact-key schema and closed lexemes only; a valid
+ * manifest is integrity/provenance input, never executable authenticity, an approved asset or activation.
+ */
+type HelperManifest = {
+  readonly helper_version: string;
+  readonly architecture: 'windows-x64';
+  readonly protocol: 'native-mi-v1';
+  readonly profiles: readonly ['scalar', 'shared'];
+  readonly native_source_sha256: string;
+  readonly executable_bytes: number;
+  readonly executable_sha256: string;
+  readonly toolchain: { readonly compiler: string; readonly sdk: string; readonly build_arguments: readonly string[] };
+  readonly dependencies: readonly string[];
+  readonly originating_source_commit: string;
+  readonly originating_build_job: string;
+};
+
+type ManifestUnusable =
+  | { readonly kind: 'unusable'; readonly reason: 'oversize_manifest' | 'invalid_manifest' | 'unsupported_manifest' };
+
+function boundedText(bytes: Uint8Array, maximumBytes: number): string | undefined {
+  if (!(bytes instanceof Uint8Array) || bytes.byteLength > maximumBytes) return undefined;
+  if (bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf) return undefined;
+  try { return new TextDecoder('utf-8', { fatal: true }).decode(bytes); }
+  catch { return undefined; }
+}
+
+function boundedLexemes(value: unknown, maximum: number): string[] | undefined {
+  if (!Array.isArray(value) || value.length > maximum) return undefined;
+  const selected: string[] = [];
+  for (const item of value) {
+    if (typeof item !== 'string' || item.length === 0 || item.length > 128 || !/^[\x20-\x7e]+$/.test(item) || selected.includes(item)) return undefined;
+    selected.push(item);
+  }
+  return selected;
+}
+
+/** Bounded complete-manifest reader: one strict UTF-8 JSON document with an exact reviewed shape. */
+export function readHelperManifest(bytes: Uint8Array):
+  | { readonly kind: 'manifest_unadmitted'; readonly manifest: HelperManifest }
+  | ManifestUnusable {
+  const invalid: ManifestUnusable = { kind: 'unusable', reason: 'invalid_manifest' };
+  if (!(bytes instanceof Uint8Array) || bytes.byteLength > MANIFEST_MAX_BYTES) return { kind: 'unusable', reason: 'oversize_manifest' };
+  const text = boundedText(bytes, MANIFEST_MAX_BYTES);
+  if (text === undefined) return invalid;
+  let value: unknown;
+  try { value = JSON.parse(text); }
+  catch { return invalid; }
+  if (!exactKeys(value, ['helper_version', 'architecture', 'protocol', 'profiles', 'native_source_sha256',
+    'executable_bytes', 'executable_sha256', 'toolchain', 'dependencies', 'originating_source_commit', 'originating_build_job']))
+    return invalid;
+  const { helper_version, architecture, protocol, profiles, native_source_sha256, executable_bytes,
+    executable_sha256, toolchain, dependencies, originating_source_commit, originating_build_job } = value;
+  if (typeof helper_version !== 'string' || !HELPER_VERSION.test(helper_version) ||
+    architecture !== 'windows-x64' || protocol !== 'native-mi-v1' ||
+    !Array.isArray(profiles) || profiles.length !== 2 || profiles[0] !== 'scalar' || profiles[1] !== 'shared')
+    return { kind: 'unusable', reason: 'unsupported_manifest' };
+  if (typeof native_source_sha256 !== 'string' || !/^[0-9a-f]{64}$/.test(native_source_sha256) ||
+    typeof executable_sha256 !== 'string' || !/^[0-9a-f]{64}$/.test(executable_sha256) ||
+    typeof originating_source_commit !== 'string' || !/^[0-9a-f]{40}$/.test(originating_source_commit) ||
+    typeof originating_build_job !== 'string' || !/^[1-9][0-9]*$/.test(originating_build_job) ||
+    typeof executable_bytes !== 'number' || !Number.isSafeInteger(executable_bytes) || executable_bytes <= 0)
+    return invalid;
+  if (executable_bytes > EXECUTABLE_MAX_BYTES) return { kind: 'unusable', reason: 'unsupported_manifest' };
+  if (!exactKeys(toolchain, ['compiler', 'sdk', 'build_arguments'])) return invalid;
+  const compiler = boundedLexemes([toolchain.compiler], 1)?.[0];
+  const sdk = boundedLexemes([toolchain.sdk], 1)?.[0];
+  const buildArguments = boundedLexemes(toolchain.build_arguments, 32);
+  const dependencyNames = boundedLexemes(dependencies, 32);
+  if (compiler === undefined || sdk === undefined || buildArguments === undefined || dependencyNames === undefined) return invalid;
+  // Fresh primitive claims only; the caller still owns target/version/source-digest policy.
+  return {
+    kind: 'manifest_unadmitted',
+    manifest: {
+      helper_version, architecture: 'windows-x64', protocol: 'native-mi-v1', profiles: ['scalar', 'shared'],
+      native_source_sha256, executable_bytes, executable_sha256,
+      toolchain: { compiler, sdk, build_arguments: buildArguments }, dependencies: dependencyNames,
+      originating_source_commit, originating_build_job,
+    },
+  };
+}
+
+type HelperAssetLocation = {
+  readonly kind: 'located';
+  readonly helper_version: string;
+  readonly manifest_url: URL;
+  readonly executable_url: URL;
+};
+
+/**
+ * Fixed versioned package-relative lookup. Never searches cwd, PATH or caller locations: the only base is
+ * the sibling `native/` directory of this module's own `lib/` (source) or `dist/lib/` (compiled) home.
+ */
+export function resolveHelperAsset(moduleUrl: unknown, runtime: unknown, helperVersion: unknown):
+  | HelperAssetLocation
+  | { readonly kind: 'unusable'; readonly reason: 'unsupported_location' | 'unsupported_target' | 'unsupported_version' } {
+  let url: URL;
+  try { url = new URL(String(moduleUrl)); }
+  catch { return { kind: 'unusable', reason: 'unsupported_location' }; }
+  if (url.protocol !== 'file:' || !MODULE_FILE.test(url.pathname)) return { kind: 'unusable', reason: 'unsupported_location' };
+  const target = runtime as { platform?: unknown; arch?: unknown } | null | undefined;
+  if (target?.platform !== 'win32' || target?.arch !== 'x64') return { kind: 'unusable', reason: 'unsupported_target' };
+  if (typeof helperVersion !== 'string' || !HELPER_VERSION.test(helperVersion)) return { kind: 'unusable', reason: 'unsupported_version' };
+  const directory = `../native/windows-mi/win32-x64/${helperVersion}/`;
+  return {
+    kind: 'located', helper_version: helperVersion,
+    manifest_url: new URL(`${directory}manifest.json`, url),
+    executable_url: new URL(`${directory}helper.exe`, url),
+  };
+}
+
+/** Injected bounded reader: exact bytes for one fixed URL or nothing. Never a path, cwd or PATH lookup. */
+export type HelperAssetReader = (url: URL, maximumBytes: number) => Uint8Array | undefined;
+
+type HelperAssetOutcome =
+  | { readonly kind: 'asset_verified_unadmitted'; readonly manifest: HelperManifest; readonly executable_sha256: string; readonly executable_bytes: number }
+  | { readonly kind: 'unusable'; readonly reason:
+    'missing_manifest' | 'oversize_manifest' | 'invalid_manifest' | 'unsupported_manifest' | 'version_mismatch' |
+    'missing_asset' | 'oversize_asset' | 'size_mismatch' | 'digest_mismatch' };
+
+/** Trusted exact-byte selection: bounded manifest read, exact declared size, then exact SHA-256 match. */
+export function loadHelperAsset(location: HelperAssetLocation, read: HelperAssetReader): HelperAssetOutcome {
+  const manifestBytes = read(location.manifest_url, MANIFEST_MAX_BYTES + 1);
+  if (manifestBytes === undefined) return { kind: 'unusable', reason: 'missing_manifest' };
+  if (manifestBytes.byteLength > MANIFEST_MAX_BYTES) return { kind: 'unusable', reason: 'oversize_manifest' };
+  const reading = readHelperManifest(manifestBytes);
+  if (reading.kind === 'unusable') return { kind: 'unusable', reason: reading.reason };
+  const { manifest } = reading;
+  if (manifest.helper_version !== location.helper_version) return { kind: 'unusable', reason: 'version_mismatch' };
+  // One extra byte detects growth; a shorter read can never satisfy the declared size.
+  const executableBytes = read(location.executable_url, manifest.executable_bytes + 1);
+  if (executableBytes === undefined) return { kind: 'unusable', reason: 'missing_asset' };
+  if (executableBytes.byteLength > manifest.executable_bytes) return { kind: 'unusable', reason: 'oversize_asset' };
+  if (executableBytes.byteLength !== manifest.executable_bytes) return { kind: 'unusable', reason: 'size_mismatch' };
+  const digest = createHash('sha256').update(executableBytes).digest('hex');
+  if (digest !== manifest.executable_sha256) return { kind: 'unusable', reason: 'digest_mismatch' };
+  return { kind: 'asset_verified_unadmitted', manifest, executable_sha256: digest, executable_bytes: executableBytes.byteLength };
+}
+
+type HelperInvocation =
+  | { readonly kind: 'invocation_unadmitted'; readonly command: string; readonly args: readonly string[];
+      readonly options: { readonly shell: false; readonly windowsHide: true } }
+  | { readonly kind: 'unusable'; readonly reason: 'unsupported_executable' | 'invalid_query' };
+
+/** Shell-free invocation spec only: no spawn, retry, fallback or execution-policy bypass. */
+export function helperInvocation(executablePath: unknown, profile: unknown, pids: unknown): HelperInvocation {
+  if (typeof executablePath !== 'string' || executablePath.length === 0 || executablePath.length > 4096 ||
+    !/^[A-Za-z]:[\\/][^\x00\r\n"]*\.exe$/.test(executablePath)) return { kind: 'unusable', reason: 'unsupported_executable' };
+  const query = queryArguments(profile, pids);
+  if (!query) return { kind: 'unusable', reason: 'invalid_query' };
+  return { kind: 'invocation_unadmitted', command: executablePath, args: query,
+    options: { shell: false, windowsHide: true } };
+}

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(