@llblab/pi-actors 0.54.0 → 0.56.0

package/lib/tools-local.ts

@@ -15,12 +15,15 @@ import * as RecipesReferences from "./recipes-references.ts";
 import * as RecipesUsage from "./recipes-usage.ts";
 import * as Schema from "./schema.ts";
 import * as ToolsResponse from "./tools-response.ts";
+import { readRunFileNavigationForContext } from "./tools-access.ts";
 
 type JsonSchema = Schema.JsonSchema;
 
 export interface RuntimeToolContext extends ModelContext.CurrentModelContext {
   recipeResolutionContext?: RecipeResolution.RecipeResolutionContext;
   cwd: string;
+  /** Kernel-injected only; never sourced from tool input/actor values. */
+  onSupervisionClockCaptured?: AsyncRuns.AsyncRunStartOptions["onSupervisionClockCaptured"];
   sessionManager?: { getSessionId?: () => string };
 }
 
@@ -213,6 +216,11 @@ export function createRuntimeToolDefinition(
       _onUpdate: unknown,
       ctx: RuntimeToolContext,
     ) {
+      let dispatchEntered = false;
+      const execute: Execution.RegisteredToolExec = (...args) => {
+        dispatchEntered = true;
+        return exec(...args);
+      };
       try {
         if (
           cfg.sourcePath &&
@@ -231,37 +239,40 @@ export function createRuntimeToolDefinition(
             : typeof run_id === "string" && run_id.trim()
               ? run_id.trim()
               : `${cfg.name}-${Date.now()}`;
+          const startParams: AsyncRuns.AsyncRunStartParams = {
+            ...base,
+            launch_source: "tool",
+            launch_correlation: { tool_call_id: toolCallId },
+            ...(transport_context &&
+            typeof transport_context === "object" &&
+            !Array.isArray(transport_context)
+              ? {
+                  transport_context: transport_context as Record<string, unknown>,
+                } : {}),
+            ownerId: getRunOwnerId(ctx),
+            run_id: runId,
+            tool: cfg.name,
+            policy_values: ModelContext.withCurrentModelValues(
+              { ...(cfg.recipe?.values ?? {}), ...values },
+              ctx,
+            ),
+            values: resolveRecipeToolValues(cfg, values, ctx),
+          };
+          dispatchEntered = true;
           const meta = AsyncRuns.startRun(
-            {
-              ...base,
-              launch_source: "tool",
-              launch_correlation: { tool_call_id: toolCallId },
-              ...(transport_context &&
-              typeof transport_context === "object" &&
-              !Array.isArray(transport_context)
-                ? {
-                    transport_context: transport_context as Record<string, unknown>,
-                  } : {}),
-              ownerId: getRunOwnerId(ctx),
-              run_id: runId,
-              tool: cfg.name,
-              policy_values: ModelContext.withCurrentModelValues(
-                { ...(cfg.recipe?.values ?? {}), ...values },
-                ctx,
-              ),
-              values: resolveRecipeToolValues(cfg, values, ctx),
-            },
+            startParams,
             ctx.cwd,
-            { skillContext: ctx.recipeResolutionContext?.activeSkills },
+            { skillContext: ctx.recipeResolutionContext?.activeSkills, onSupervisionClockCaptured: ctx.onSupervisionClockCaptured },
           );
+          const details = { ...meta, file_navigation: readRunFileNavigationForContext(meta, ctx) };
           return {
             content: [
               {
                 type: "text" as const,
-                text: ToolsResponse.compactAsyncRunStatus(meta),
+                text: ToolsResponse.compactAsyncRunStatus(details),
               },
             ],
-            details: meta,
+            details,
           };
         }
         if (isRecipe && recipeTemplate) {
@@ -272,7 +283,7 @@ export function createRuntimeToolDefinition(
               params as Record<string, unknown>,
               ctx,
             ),
-            exec,
+            execute,
             ctx.cwd,
             signal,
           );
@@ -286,11 +297,13 @@ export function createRuntimeToolDefinition(
             ),
             cfg.argTypes,
           ),
-          exec,
+          execute,
           ctx.cwd,
           signal,
         );
       } catch (error) {
+        // Dispatch entry is not effect/closure proof; matching error text cannot justify argument repair or retry.
+        if (dispatchEntered) throw error;
         throw formatRuntimeToolArgumentError(
           cfg,
           error,

package/lib/tools-message.ts

@@ -1,6 +1,6 @@
 /**
  * Public Control facade under the stable `message` tool name.
- * Zones: Control request validation, Run/runtime dispatch, compact receipts
+ * Zones: Control request validation, Run/runtime dispatch, recipient-scoped receipts
  * Owns public Control execution; journaling, delivery, and lifecycle mutation stay in Run domains.
  */
 
@@ -8,6 +8,7 @@ import * as AsyncRuns from "./async-runs.ts";
 import * as Control from "./control.ts";
 import * as Schema from "./schema.ts";
 import * as ToolsAccess from "./tools-access.ts";
+import * as Limits from "./limits.ts";
 import * as ToolsResponse from "./tools-response.ts";
 
 function asRecord(value: unknown): Record<string, unknown> {
@@ -16,32 +17,92 @@ function asRecord(value: unknown): Record<string, unknown> {
     : {};
 }
 
-function compactControlResult(
+const controlField = ToolsResponse.formatMarkdownField;
+
+/** Only the four compiler-owned guard sites below; never wraps dispatch/dependency errors. */
+function controlGuardText(
+  request: Control.ControlRequest,
+  result: "unsupported runtime Control action" | "runtime Control is unavailable" | "Run generation unavailable" | "undeclared Run Control action",
+  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);
+}
+
+/** Pure first-layer copy; legacy stopped/killed flags are not scope-closure proof. */
+export function compactControlResult(
   request: Control.ControlRequest,
   result: Record<string, unknown>,
 ): string {
-  const tokens = [
-    `target=${request.target}`,
-    `action=${request.action}`,
-    `status=${String(result.delivery ?? result.status ?? (result.stopped === true ? "handled" : "accepted"))}`,
-  ];
-  if (result.control_id) tokens.push(`control=${String(result.control_id)}`);
-  if (result.reason) tokens.push(`reason=${String(result.reason).replaceAll(/\s+/g, "_")}`);
-  if (Array.isArray(result.next_actions) && result.next_actions.length > 0) {
-    tokens.push(
-      `next=${(result.next_actions as string[])
-        .map((action) => action.replaceAll(/\s+/g, "_"))
-        .join("|")}`,
-    );
+  const fields = [request.target.startsWith("run:") ? controlField("run", request.target.slice(4)) : controlField("target", request.target),
+    controlField("action", request.action)];
+  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));
+  } else if (request.action === "kill" && result.stopped === true) {
+    fields.push(controlField("result", "kill attempted"), controlField("termination", "unconfirmed"));
+  } else if (result.archived === true) {
+    fields.push(controlField("result", "archived"));
+  } else if (result.pruned === true) {
+    fields.push(controlField("result", "pruned"));
+  } else if (result.delivery === "queued" || result.delivery === "delivered") {
+    fields.push(controlField("delivery", result.delivery), controlField("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));
   }
-  return `\n${tokens.join(" ")}`;
+  if (typeof result.control_id === "string") fields.push(controlField("control_id", result.control_id));
+  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"));
 }
 
 function runNextActions(run: string, result: Record<string, unknown>): string[] {
+  if (result.stopped === true) return [`inspect target=run:${run} view=trace`];
+  if (result.stopped === false || result.archived === false || result.pruned === false) {
+    if (result.reason === "ownership changed" || result.reason === "run generation changed") {
+      return ["inspect target=runtime view=runs"];
+    }
+    if (result.stopped === false && result.reason !== "not running") return [`inspect target=run:${run} view=trace`];
+  }
   if (result.delivery === "queued" || result.delivery === "delivered") {
     return [`inspect target=run:${run} view=control`];
   }
-  if (result.stopped === true) return [`inspect target=run:${run} view=control`];
   return [];
 }
 
@@ -85,12 +146,12 @@ export function createControlToolDefinition<TContext = unknown>(
       let result: Record<string, unknown>;
       if (request.target === "runtime") {
         if (request.action !== "review.retry" && request.action !== "review.reset") {
-          throw new Error(
-            `unsupported runtime Control action: ${request.action}; use review.retry or review.reset`,
-          );
+          throw new Error(controlGuardText(request, "unsupported runtime Control action", {
+            key: "supported_actions", values: ["review.retry", "review.reset"],
+          }));
         }
         if (!deps.handleRuntimeControl) {
-          throw new Error("runtime Control is unavailable");
+          throw new Error(controlGuardText(request, "runtime Control is unavailable"));
         }
         result = deps.handleRuntimeControl(request.action, request.input);
       } else {
@@ -106,7 +167,7 @@ export function createControlToolDefinition<TContext = unknown>(
           typeof status.run_instance_id === "string"
             ? status.run_instance_id
             : undefined;
-        if (!runInstanceId) throw new Error(`Run generation unavailable: ${run}`);
+        if (!runInstanceId) throw new Error(controlGuardText(request, "Run generation unavailable"));
         if (request.action === "kill") {
           result = AsyncRuns.killRun(run, {
             ...(typeof status.ownerId === "string"
@@ -144,23 +205,45 @@ export function createControlToolDefinition<TContext = unknown>(
               )
             : [];
           if (!declared.includes(request.action)) {
-            throw new Error(
-              `undeclared Run Control action: ${request.action}; available=${declared.join(",") || "none"}`,
+            // The old join/template evaluation may itself throw or have observable hooks.
+            // Preserve it before the new presentation; it is not an action-list parser.
+            void `${declared.join(",") || "none"}`;
+            throw new Error(controlGuardText(request, "undeclared Run Control action", {
+              key: "available_actions", values: declared,
+            }));
+          }
+          try {
+            result = await AsyncRuns.sendRunControl(
+              run,
+              {
+                action: request.action,
+                ...(request.input !== undefined ? { input: request.input } : {}),
+                run_instance_id: runInstanceId,
+              },
+              {
+                ...(typeof status.ownerId === "string"
+                  ? { ownerId: status.ownerId }
+                  : {}),
+              },
             );
+          } 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 });
           }
-          result = await AsyncRuns.sendRunControl(
-            run,
-            {
-              action: request.action,
-              ...(request.input !== undefined ? { input: request.input } : {}),
-              run_instance_id: runInstanceId,
-            },
-            {
-              ...(typeof status.ownerId === "string"
-                ? { ownerId: status.ownerId }
-                : {}),
-            },
-          );
+        }
+        // A refused identity change must not publish the replacement's status, even in verbose/details.
+        if (result.reason === "ownership changed" || result.reason === "run generation changed") {
+          result = { ...result };
+          delete result.status;
         }
         const nextActions = runNextActions(run, result);
         if (nextActions.length > 0) result = { ...result, next_actions: nextActions };