@llblab/pi-actors 0.56.1 → 0.57.1

package/lib/tools-response.ts

@@ -84,6 +84,69 @@ export function renderYamlMetadata(value: unknown, byteBudget: number): YamlMeta
   }
 }
 
+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 function selectYamlNode(key: string, value: unknown, byteBudget: number, total = 1): YamlPart {
+  const full = { [key]: value };
+  const complete = renderYamlMetadata(full, byteBudget);
+  const invalid = complete.state === "unavailable" && complete.reason === "metadata_invalid";
+  const omitted = { [key]: invalid ? "[unavailable]" : "[omitted]",
+    [key + "_omission"]: { reason: invalid ? "invalid_selected_metadata" : "response_too_large", shown: 0, omitted: total, total } };
+  const fallback = renderYamlMetadata(omitted, byteBudget);
+  // Seed the shorter complete-or-omitted form: omission scaffolding must never manufacture overflow.
+  const selected = complete.state === "available" && fallback.state === "available" &&
+    Buffer.byteLength(complete.text) <= Buffer.byteLength(fallback.text) ? full : omitted;
+  return { full: invalid ? omitted : full, selected };
+}
+
+/** Opaque selected text or string sequence; malformed selections stay unavailable without repair. */
+export function selectYamlField(key: string, value: string | readonly string[], byteBudget: number): YamlPart {
+  const values = typeof value === "string" ? [value] : value;
+  if (values.every(item => item.isWellFormed()))
+    return selectYamlNode(key, typeof value === "string" ? value : [...value], byteBudget, typeof value === "string" ? 1 : value.length);
+  const total = typeof value === "string" ? 1 : value.length;
+  const omitted = { [key]: "[unavailable]",
+    [key + "_omission"]: { reason: "malformed_selected_text", shown: 0, omitted: total, total } };
+  return { full: omitted, selected: omitted };
+}
+
+/** Grow whole selected fields in priority order while the complete document still fits. */
+export function growYamlDocument(
+  render: () => Record<string, unknown>,
+  order: readonly YamlPart[],
+  byteBudget: number,
+): string {
+  const fits = () => renderYamlMetadata(render(), byteBudget).state === "available";
+  for (const part of order) {
+    if (part.selected === part.full) continue;
+    const previous = part.selected;
+    part.selected = part.full;
+    if (!fits()) part.selected = previous;
+  }
+  const rendered = renderYamlMetadata(render(), byteBudget);
+  if (rendered.state !== "available")
+    throw new Error("Selected YAML metadata document is unavailable: " + rendered.reason);
+  return rendered.text;
+}
+
+/** Uncapped UI-only flat metadata; never borrow a model-output allowance for notices. */
+export function formatYamlNotice(value: Record<string, string | number | boolean>): string {
+  const selected: Record<string, unknown> = {};
+  for (const [key, field] of Object.entries(value)) {
+    if (typeof field === "string" && !field.isWellFormed()) {
+      selected[key] = "[unavailable]";
+      selected[key + "_omission"] = { reason: "malformed_selected_text", shown: 0, omitted: 1, total: 1 };
+    } else selected[key] = field;
+  }
+  return yamlMetadataText(selected).replace(/\n$/u, "");
+}
+
+/** Close one rendered YAML header; a separate opaque body gets exactly one delimiter pair. */
+export function frameMetadataDocument(header: string, body?: string): string {
+  return body === undefined ? header : `---\n${header}---\n${body}`;
+}
+
 export function formatMarkdownField(key: string, value: string, depth = 0): string {
   const indent = "  ".repeat(depth);
   return /[\r\n]/u.test(value)
@@ -463,6 +526,28 @@ export function recipeRegistryNextActions(
   return [...new Set(actions)].slice(0, 4);
 }
 
+/** Compact metadata-only document text: one leading LF, no trailing LF, shared emitter budget. */
+export function compactYamlDocument(value: Record<string, unknown>): string {
+  const text = growYamlDocument(() => value, [], Limits.RUN_DELIVERY_MODEL_MAX_BYTES);
+  return `\n${text.replace(/\n$/u, "")}`;
+}
+
+/** Only the closed read-only Recipe inspect literals become typed next; other advice stays opaque content. */
+export function nextActionMetadata(action: string, byteBudget: number): YamlPart {
+  const recognized = [
+    ["inspect target=recipes view=doctor", "doctor", false],
+    ["inspect target=recipes view=imports verbose=true", "imports", true],
+    ["inspect target=recipes view=summary verbose=true", "summary", true],
+  ] as const;
+  const match = recognized.find(([literal]) => literal === action);
+  if (match) {
+    const typed = { next: { tool: "inspect", target: "recipes", view: match[1], ...(match[2] ? { verbose: true } : {}) } };
+    return { full: typed, selected: typed };
+  }
+  const instruction = selectYamlField("instruction", action, byteBudget);
+  return { full: { next: instruction.full }, selected: { next: instruction.selected } };
+}
+
 /** Only these existing read-only inspection hints become action nodes; other advice stays content. */
 export function formatInspectionHint(action: string): string {
   if (action === "inspect target=recipes view=doctor") return formatInspectNextAction("recipes", "doctor");
@@ -474,21 +559,11 @@ export function formatInspectionHint(action: string): string {
 export function compactRecipeRegistry(
   summary: Record<string, unknown>,
 ): string {
-  const active = Array.isArray(summary.active) ? summary.active.length : 0;
-  const shadowed = Array.isArray(summary.shadowed)
-    ? summary.shadowed.length
-    : 0;
-  const invalid = Array.isArray(summary.invalid) ? summary.invalid.length : 0;
-  const disabled = Array.isArray(summary.disabled)
-    ? summary.disabled.length
-    : 0;
-  const diagnostics = Array.isArray(summary.diagnostics)
-    ? summary.diagnostics.length
-    : 0;
-  const drafts = Array.isArray(summary.drafts) ? summary.drafts.length : 0;
-  const recommendations = Array.isArray(summary.recommendations)
-    ? summary.recommendations.length
-    : 0;
+  const count = (key: string, source: unknown) => Array.isArray(source) ? source.length : 0;
+  const active = count("active", summary.active), shadowed = count("shadowed", summary.shadowed);
+  const invalid = count("invalid", summary.invalid), disabled = count("disabled", summary.disabled);
+  const diagnostics = count("diagnostics", summary.diagnostics), drafts = count("drafts", summary.drafts);
+  const recommendations = count("recommendations", summary.recommendations);
   const skillCatalogPartial = summary.skill_recipe_catalog_partial === true;
   const currentPolicy = Array.isArray(summary.active)
     ? (summary.active as Array<Record<string, unknown>>).filter(
@@ -498,11 +573,13 @@ export function compactRecipeRegistry(
   const nextActions = Array.isArray(summary.next_actions)
     ? (summary.next_actions as string[])
     : [];
-  const fields = [formatMarkdownField("recipes", "registry"), ...Object.entries({ active, drafts, shadowed, invalid, disabled,
-    current_policy: currentPolicy, skill_catalog_partial: skillCatalogPartial, recommendations, diagnostics })
-    .map(([key, value]) => formatMarkdownField(key, String(value)))];
-  if (nextActions.length) fields.push(formatInspectionHint(nextActions[0]));
-  return "\n" + fields.join("\n");
+  const hint = nextActions.length ? nextActionMetadata(nextActions[0]!, Limits.RUN_DELIVERY_MODEL_MAX_BYTES) : undefined;
+  const render = (): Record<string, unknown> => ({ recipes: "registry", active, drafts, shadowed, invalid, disabled,
+    current_policy: currentPolicy, skill_catalog_partial: skillCatalogPartial, recommendations, diagnostics,
+    ...(hint ? hint.selected : {}) });
+  return hint
+    ? `\n${growYamlDocument(render, [hint], Limits.RUN_DELIVERY_MODEL_MAX_BYTES).replace(/\n$/u, "")}`
+    : compactYamlDocument(render());
 }
 
 export const DEFAULT_INSPECT_LINES = Limits.DEFAULT_INSPECT_LINES;

package/lib/tools-spawn.ts

@@ -84,21 +84,28 @@ function writeSpawnDraftRecipe(
 
 /** Compiler-owned pre-launch diagnostics only; selected caller values are not admitted Run ids. */
 function spawnGuardText(kind: "state_dir" | "namespace" | "id", value?: string): string {
-  const field = ToolsResponse.formatMarkdownField;
   const facts = kind === "state_dir"
-    ? [field("result", "unsupported field"), field("reason", "Run state is runtime-owned; run:<id> remains addressable and retention-safe.")]
-    : [field("result", kind === "namespace" ? "unsupported Run target" : "invalid Run target"), field("accepted_format", "run:<id>"),
-      ...(kind === "id" ? [field("id_rule", "nonempty ASCII letters, digits, underscore, dot or hyphen")] : [])];
-  const render = (selected?: string) => ToolsResponse.withLeadingLineBreak(
-    [field("field", kind === "state_dir" ? "state_dir" : "as"), ...(selected === undefined ? [] : [selected]), ...facts].join("\n"));
-  if (value === undefined) return render();
-  const wellFormed = value.isWellFormed();
-  if (wellFormed) {
-    const complete = render(field("value", value));
-    if (Buffer.byteLength(complete) <= Limits.RUN_DELIVERY_MODEL_MAX_BYTES) return complete;
+    ? { result: "unsupported field", reason: "Run state is runtime-owned; run:<id> remains addressable and retention-safe." }
+    : { result: kind === "namespace" ? "unsupported Run target" : "invalid Run target", accepted_format: "run:<id>",
+        ...(kind === "id" ? { id_rule: "nonempty ASCII letters, digits, underscore, dot or hyphen" } : {}) };
+  // Measure the shared emitter's own projection: an unfit selected value must become an omission, not a clip.
+  const render = (selected?: Record<string, unknown>): string | undefined => {
+    const rendered = ToolsResponse.renderYamlMetadata({ field: kind === "state_dir" ? "state_dir" : "as", ...(selected ?? {}), ...facts },
+      Limits.RUN_DELIVERY_MODEL_MAX_BYTES);
+    return rendered.state === "available"
+      ? ToolsResponse.withLeadingLineBreak(ToolsResponse.frameMetadataDocument(rendered.text))
+      : undefined;
+  };
+  const required = (selected?: Record<string, unknown>) => render(selected) ?? render()!;
+  const wellFormed = value !== undefined && value.isWellFormed();
+  if (value !== undefined && wellFormed) {
+    const complete = render({ value });
+    if (complete !== undefined && Buffer.byteLength(complete) <= Limits.RUN_DELIVERY_MODEL_MAX_BYTES) return complete;
   }
+  if (value === undefined) return required();
   const reason = wellFormed ? "response_too_large" : "malformed_selected_text";
-  return render(`- value: [${reason === "response_too_large" ? "omitted" : "unavailable"}]\n- value_omission:\n  - reason: ${reason}\n  - shown: 0\n  - omitted: 1\n  - total: 1`);
+  return required({ value: reason === "response_too_large" ? "[omitted]" : "[unavailable]",
+    value_omission: { reason, shown: 0, omitted: 1, total: 1 } });
 }
 
 function runIdFromTarget(target: string | undefined): string | undefined {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-actors",
-  "version": "0.56.1",
+  "version": "0.57.1",
   "private": false,
   "description": "Local Actor Kernel for Pi",
   "keywords": [

package/skills/actors/SKILL.md

@@ -151,7 +151,7 @@ Run = Recipe + Trace + Control
 5. Send `message` only for an action declared and consumed by that controlled Recipe.
 6. Use terminal state, result, declared artifacts, and execution evidence to prove completion. When an outcome includes a retained primary-source, declaration-inventory or diagnostic-metadata reference, use that exact reference for further reading, not guessed captures or sibling files. Literal previews may be clipped; their field/range/counts describe what was shown. Diagnostic sources contain recorded command/error/failure-reason metadata only, not complete primary output; other recorded fields may be referenced without being shown. Artifact inventories list declarations only: they do not assert that target files exist or were produced, or grant body-read permission. Explicit unavailability has no guessed legacy body/path fallback.
 
-Compact launch receipts include `run_files` as nested block YAML containing the exact selected observed location values, labeled observed locations/mutable for the exact launched Run generation when the current session and physical identity agree; otherwise they report unavailability or whole-row omission. Machine `file_navigation` details stay JSON-compatible; saved terminal messages retain their own original encodings. Selectively ordinary-read those starting locations when needed; layout/size hints are not body, privacy, terminal or native proof. No evidence bodies or session-wide catalog map are read to build this row. New terminal packets also freeze bounded location rows for captured completion members at fresh current-session admission. Each shown result keeps its whole Run-file row or explicit per-record omission; wholly omitted results stay covered by result omission/inventory. This describes Run-row coverage, not a complete file/tree inventory. Older captured formats retain their original shown/omitted/total counters; unavailability remains explicit. Ordinary-read selected paths only when needed. Packet reload/render never refreshes sources, and old absent/request-only formats keep their text. Source/npm SDK verifies an explicitly requested ordinary read from a delivered terminal result path; this is research, never routine completion polling or new primary/privacy/clock/native authority. Use the request only for file investigation, not routine completion/status polling. Copied locations/hints remain data, never transferred scope; older batches keep their original text.
+Compact launch receipts include `run_files` as nested block YAML containing the exact selected observed location values, labeled observed locations/mutable for the exact launched Run generation when the current session and physical identity agree; otherwise they report unavailability or whole-row omission. Machine `file_navigation` details stay JSON-compatible; saved terminal messages retain their own original encodings. Selectively ordinary-read those starting locations when needed; layout/size hints are not body, privacy, terminal or native proof. No evidence bodies or session-wide catalog map are read to build this row. New terminal packets also freeze bounded location rows for captured completion members at fresh current-session admission. Fresh rooted completion headers group paths under literal roots with relative entries, English purposes and a read_first group/entry pointer; no cwd guess, source refresh or automatic read follows. Unknown bases stay explicit. Runtime navigation/omission/inventory facts remain above the Actor Markdown, not in a footer; retained packets keep their original projection. Each shown result keeps its whole Run-file row or explicit per-record omission; wholly omitted results stay covered by result omission/inventory. This describes Run-row coverage, not a complete file/tree inventory. Older captured formats retain their original shown/omitted/total counters; unavailability remains explicit. Ordinary-read selected paths only when needed. Packet reload/render never refreshes sources, and old absent/request-only formats keep their text. Source/npm SDK verifies an explicitly requested ordinary read from a delivered terminal result path; this is research, never routine completion polling or new primary/privacy/clock/native authority. Use the request only for file investigation, not routine completion/status polling. Copied locations/hints remain data, never transferred scope; older batches keep their original text.
 
 For selective investigation of already cataloged files, use `inspect target=runtime view=runs verbose=true`, then ordinary file tools on its current-session root-first navigation. Ordinary maps keep latest-registration order between roots and prioritize known failed subtrees within each root. For a failed investigation add status=failed: inventory is filtered, while the full owned map prioritizes observed failed subtrees across roots, always ancestors first. Priority uses only exact-generation matched inventory observations, not complete terminal truth. Launches and compatible singleton attachments populate the catalog; reads do not backfill missing locations. A `catalog: unavailable` launch warning is not workload failure: do not spawn again merely to repair navigation. The starting map's format hints do not certify syntax, encoding or complete output. See [Runs](./references/runs.md) for selective recorded-capture research and resume boundaries.
 

package/skills/actors/references/diagnostics.md

@@ -6,9 +6,12 @@ Preserve the intended logical identity and diagnose through public pi-actors sur
 
 ```text
 inspect target=recipes view=status
+inspect target=recipes view=summary
 inspect target=recipes view=doctor identity=<skill>/<recipe>
 ```
 
+`summary` and `registry` name the same inspection path: identical facts, details and rendering for identical `verbose` input, so only `verbose` selects compact text versus structured output. The compact label still reports `recipes: registry`, and that label is not a separate view to request. Unsupported-view refusals list the actual accepted view names.
+
 Compact Recipe/Run/tool replies use flat AX fields without changing their existing evidence or authorization. Required/optional tool arguments are sequences, with none distinct from unknown. Focused source_location remains one exact literal value. Run compact replies still identify only run/view: request verbose for structured evidence, and tool schema remains structured even without verbose. Compact text selects at most one existing hint; only exact read-only recipes doctor/imports/summary inspection literals become typed next nodes. Other advice stays instruction content with its original Markdown, never executable metadata or authority to rerun work/register a tool. The full original next_actions array remains in details; do not infer callability from an advisory string.
 
 Use the focused doctor form for one intended identity. It reports active-Skill ownership, exact resolvability, partial-catalog state, component status, portable source location, resolution generation, any rejection, and bounded next actions. Use the unfiltered doctor only for catalog-wide diagnosis. A partial catalog does not imply every exact component is unavailable. If the owning Skill is inactive, report that blocker rather than locating and running its helper manually.

package/skills/actors/references/runs.md

@@ -24,7 +24,7 @@ inspect target=run:<id> view=trace
 inspect target=run:<id> view=control
 ```
 
-Fresh root completions use index-first YAML frontmatter (index, run, state, admitted kind), followed by raw left-edge Markdown. No external #N heading, result:/preview: wrapper, list nesting, whole-body fence, Batch caption, members wrapper or routine outer counter is added. Primary/final Actor response uses kind:primary; explicit error/failure diagnostic text uses kind:diagnostic, never a launch command. Untracked fallback has no kind and keeps unknown original completeness/privacy explicit outside YAML. Known cut loss is [N characters omitted] at the cut, with no extra ellipsis or body clipping counters/flags in metadata. Unknown upstream loss remains separately unknown and does not assert a known positive omission. Exact source/generation/parent/location references remain in complete model content, with whole references or explicit omission, captured inventory recovery and non-done omitted states. The compact TUI independently renders literal headers/markers and native Markdown bodies from validated content-bound blocks; only whole header reference/location rows and framing are hidden. Expansion and invalid/missing hints reveal original text. Hashes/layout/markers establish consistency/correlation only, never authentication, read/action permission, acceptance or native truth. Authored YAML/next/tool/batch/omission lookalikes stay body content. Fresh packets share48KiB UTF-8 including service data, equally between up to64candidate rows, with256captured members and no redistribution of unused shares or fixed16KiB/2KiB text cap. Full admitted text fitting its share without upstream uncertainty has no cut marker; otherwise use the scalar/CRLF-safe prefix and exact retained-source loss. Allocation/text is frozen at admission; rendering/recovery does not reread sources or reallocate. Unsupported Pi event/control output is withheld. Source basis stays in reference metadata; retained structured coverage facts are not exposed as YAML clipping fields. Pending/queued/presented older formats—including #N records and the first frontmatter draft—keep exact bytes, hints and budgets. Encoding names are storage replay data, not public product choices, source permissions or work authority. No standing full-map instruction or automatic research/read follows; use selective same-session investigation when needed.
+Fresh root completions use index-first YAML frontmatter (index, run, state, admitted kind), followed by raw left-edge Markdown. New source captures put all runtime metadata above that body, with no service/file footer. files.groups gives one literal root plus relative entry paths; files.read_first names zero-based group/entry indices for the first useful source, not an automatic read. role/purpose guidance is English; Actor Markdown and path/name bytes are unchanged. External paths use separate roots; unknown bases remain explicit rather than guessed from cwd or Run id. Known cut counts alone may follow the cut body; unknown-loss warnings and packet omission/inventory facts stay in the header. Retained captures preserve their old bytes and presentation. No external #N heading, result:/preview: wrapper, list nesting, whole-body fence, Batch caption, members wrapper or routine outer counter is added. Primary/final Actor response uses kind:primary; explicit error/failure diagnostic text uses kind:diagnostic, never a launch command. Untracked fallback has no kind and keeps unknown original completeness/privacy explicit outside YAML. Known cut loss is [N characters omitted] at the cut, with no extra ellipsis or body clipping counters/flags in metadata. Unknown upstream loss remains separately unknown and does not assert a known positive omission. Exact source/generation/parent/location references remain in complete model content, with whole references or explicit omission, captured inventory recovery and non-done omitted states. The compact TUI independently renders literal headers/markers and native Markdown bodies from validated content-bound blocks; only whole header reference/location rows and framing are hidden. Expansion and invalid/missing hints reveal original text. Hashes/layout/markers establish consistency/correlation only, never authentication, read/action permission, acceptance or native truth. Authored YAML/next/tool/batch/omission lookalikes stay body content. Fresh packets share48KiB UTF-8 including service data, equally between up to64candidate rows, with256captured members and no redistribution of unused shares or fixed16KiB/2KiB text cap. Full admitted text fitting its share without upstream uncertainty has no cut marker; otherwise use the scalar/CRLF-safe prefix and exact retained-source loss. Allocation/text is frozen at admission; rendering/recovery does not reread sources or reallocate. Unsupported Pi event/control output is withheld. Source basis stays in reference metadata; retained structured coverage facts are not exposed as YAML clipping fields. Pending/queued/presented older formats—including #N records and the first frontmatter draft—keep exact bytes, hints and budgets. Encoding names are storage replay data, not public product choices, source permissions or work authority. No standing full-map instruction or automatic research/read follows; use selective same-session investigation when needed.
 
 Current completion index values restart within each packet; they are not session-wide historical references. Completion streams are adopted but not enabled, and no start-stream command is available yet. Do not infer an active stream or reset a counter from missing metadata or a pending target, and never relabel older saved packets. The kernel-only allocator now commits fixed scope/order/indices, the counter and first-packet target activation together, and an internal fresh-session bridge can use it after current manager/generation admission. The default runtime does not opt in; no public action exposes it. Event reason or a matching ID alone is insufficient. Old callbacks/wrappers cannot act after replacement; fresh wrappers must belong to the current original manager. Startup/reload/resume and ambiguous imports remain closed to stream capture/ACK, without changing saved packets or inferring a counter from history. Its whole-range exhaustion or admitted counter unavailability yields a frozen unknown index (quoted "?" in fresh YAML; #? in older saved layouts), never partial indices or an automatic fresh stream. Old packets retain their original scope while a pending switch waits; uncertainty does not permit reallocation. Stream state outlives packet cleanup/receipt rotation. Malformed/missing state remains refused, not a zero counter or proof of non-connection.