@llblab/pi-actors 0.42.3 → 0.43.1

package/lib/tools-message.ts

@@ -1,15 +1,13 @@
 /**
- * Public message tool behavior
- * Zones: addressed actor messages, run controls, branch/room delivery, tool actor invocation
- * Owns the public message execution path and compact delivery responses
+ * Public Control facade under the stable `message` tool name.
+ * Zones: Control request validation, Run/runtime dispatch, compact receipts
+ * Owns public Control execution; journaling, delivery, and lifecycle mutation stay in Run domains.
  */
 
 import * as AsyncRuns from "./async-runs.ts";
-import * as Messages from "./messages.ts";
-import * as Rooms from "./rooms.ts";
+import * as Control from "./control.ts";
 import * as Schema from "./schema.ts";
 import * as ToolsAccess from "./tools-access.ts";
-import * as ToolsMailbox from "./tools-mailbox.ts";
 import * as ToolsResponse from "./tools-response.ts";
 
 function asRecord(value: unknown): Record<string, unknown> {
@@ -18,325 +16,62 @@ function asRecord(value: unknown): Record<string, unknown> {
     : {};
 }
 
-function maybeJsonText(
-  value: unknown,
-  verbose: boolean | undefined,
-  compact: string,
-): string {
-  return verbose ? ToolsResponse.jsonText(value) : compact;
-}
-
-function messageBodyToRunLine(message: Messages.ActorMessage): string {
-  if (message.type !== "run.message") return JSON.stringify(message);
-  if (typeof message.body === "string") return message.body;
-  if (message.body === undefined) return message.type;
-  return JSON.stringify(message.body);
-}
-
-function messageBodyToToolParams(
-  message: Messages.ActorMessage,
-): Record<string, unknown> {
-  if (
-    message.body &&
-    typeof message.body === "object" &&
-    !Array.isArray(message.body)
-  ) {
-    return message.body as Record<string, unknown>;
-  }
-  if (message.body === undefined) return {};
-  return { input: message.body };
-}
-
-function formatToolActorFailure(
-  tool: string,
-  message: Messages.ActorMessage,
-  params: Record<string, unknown>,
-  error: unknown,
-): Error {
-  const original = error instanceof Error ? error.message : String(error);
-  const paramsPreview = ToolsResponse.compactPreview(params, 240) ?? "{}";
-  return Object.assign(
-    new Error(
-      `tool actor ${tool} failed for message type ${message.type}: ${original}; params=${paramsPreview}`,
-    ),
-    {
-      message_type: message.type,
-      original_error: original,
-      params_preview: paramsPreview,
-      tool,
-    },
-  );
-}
-
-function assertMessageSenderBelongsToRun(
-  message: Messages.ActorMessage,
-  run: string,
-  routeLabel: string,
-): void {
-  if (!message.from) {
-    throw new Error(`message to ${message.to} requires from=<actor address>.`);
-  }
-  const sender = Messages.parseActorAddress(message.from);
-  if (
-    (sender.kind !== "run" && sender.kind !== "branch") ||
-    sender.value !== run
-  ) {
-    throw new Error(
-      `message to ${routeLabel} requires from=run:${run} or branch:${run}/<branch>; got ${message.from}.`,
-    );
-  }
-}
-
-async function routeBranchEnvelope(
-  stateDir: string,
-  runId: string,
-  recipient: string,
-  message: Messages.ActorMessage,
-  _options: { source: "direct" | "room-multicast" },
-): Promise<Record<string, unknown>> {
-  const branchMessage = { ...message, to: recipient };
-  Rooms.appendBranchInboxMessage(stateDir, runId, recipient, branchMessage);
-  try {
-    return await AsyncRuns.sendRunMessage(runId, JSON.stringify(branchMessage));
-  } catch (error) {
-    const record =
-      error && typeof error === "object"
-        ? (error as Record<string, unknown>)
-        : {};
-    if (record.queued === true) {
-      return {
-        control_path: record.control_path,
-        control_type: record.control_type,
-        delivery_error:
-          record.delivery_error ??
-          (error instanceof Error ? error.message : String(error)),
-        inbox_id: record.inbox_id,
-        queued: true,
-        run: runId,
-        sent: false,
-        state_dir: stateDir,
-      };
-    }
-    throw error;
-  }
-}
-
-function getRoomMulticastRecipients(
-  message: Messages.ActorMessage,
-  run: string,
-): string[] {
-  const raw = message.metadata?.recipients;
-  if (raw === undefined) return [];
-  if (!Array.isArray(raw)) {
-    throw new Error("room multicast metadata.recipients must be an array.");
-  }
-  return raw.map((recipient) => {
-    if (typeof recipient !== "string") {
-      throw new Error("room multicast recipients must be actor addresses.");
-    }
-    const parsed = Messages.parseActorAddress(recipient);
-    if (parsed.kind !== "branch" || parsed.value !== run) {
-      throw new Error(
-        `room multicast recipient must be branch:${run}/<branch>; got ${recipient}.`,
-      );
-    }
-    return Messages.formatActorAddress(parsed);
-  });
-}
-
-function normalizeDeliveryOutcome(
-  address: Messages.ActorAddress,
-  result: Record<string, unknown>,
-): Record<string, unknown> {
-  if (result.reason) return result;
-  if (address.kind === "run") {
-    if (result.stopped === true) {
-      return {
-        ...result,
-        consumer: "run-control",
-        delivered: true,
-        persisted: true,
-        reason: "control_applied",
-      };
-    }
-    return {
-      ...result,
-      consumer: result.control_type ?? result.control ?? "run-control",
-      delivered: result.sent === true && result.queued !== true,
-      persisted: true,
-      reason: result.delivery_error
-        ? "delivery_failed_persisted"
-        : result.queued === true
-          ? "queued_mailbox"
-          : "delivered",
-    };
-  }
-  if (address.kind === "branch") {
-    return {
-      ...result,
-      consumer: "branch-mailbox",
-      delivered: result.sent === true,
-      persisted: true,
-      reason: result.delivery_error
-        ? "branch_persisted_parent_unavailable"
-        : "branch_persisted_forwarded",
-    };
-  }
-  if (address.kind === "room") {
-    return {
-      ...result,
-      consumer: "room-timeline",
-      delivered: true,
-      forwarded: Number(result.multicast_count ?? 0) > 0,
-      persisted: true,
-      reason: "room_persisted",
-    };
-  }
-  if (address.kind === "tool") {
-    return {
-      ...result,
-      consumer: "tool",
-      delivered: true,
-      persisted: false,
-      reason: "tool_invoked",
-    };
-  }
-  if (address.kind === "coordinator" || address.kind === "session") {
-    return {
-      ...result,
-      consumer: "run-outbox",
-      delivered: false,
-      persisted: true,
-      queued: true,
-      reason: `${address.kind}_outbox_persisted`,
-    };
-  }
-  return result;
-}
-
-function actorMessageNextActions(
-  message: Messages.ActorMessage,
-  result: Record<string, unknown>,
-): string[] {
-  const actions: string[] = [];
-  const address = Messages.parseActorAddress(message.to);
-  if (result.delivery_error || result.sent === false) {
-    if (address.kind === "run" && address.value) {
-      actions.push(`inspect target=run:${address.value} view=status`);
-      actions.push(`inspect target=run:${address.value} view=mailbox`);
-    } else if (address.kind === "branch" && address.value) {
-      actions.push(
-        `inspect target=branch:${address.value}/${address.branch ?? "main"} view=mailbox`,
-      );
-      actions.push(`inspect target=run:${address.value} view=status`);
-    }
-  }
-  if (result.queued === true) {
-    if (address.kind === "branch" && address.value) {
-      actions.push(
-        `inspect target=branch:${address.value}/${address.branch ?? "main"} view=mailbox`,
-      );
-    } else if (address.kind === "run" && address.value) {
-      actions.push(`inspect target=run:${address.value} view=mailbox`);
-    }
-  }
-  return [...new Set(actions)].slice(0, 3);
-}
-
-function compactActorMessageResult(
-  message: Messages.ActorMessage,
+function compactControlResult(
+  request: Control.ControlRequest,
   result: Record<string, unknown>,
 ): string {
   const tokens = [
-    `to=${message.to}`,
-    `type=${message.type}`,
-    `message=${result.sent === true || result.stopped === true ? "sent" : "not_sent"}`,
+    `target=${request.target}`,
+    `action=${request.action}`,
+    `status=${String(result.delivery ?? result.status ?? (result.stopped === true ? "handled" : "accepted"))}`,
   ];
-  if (result.bytes !== undefined) tokens.push(`bytes=${String(result.bytes)}`);
-  if (result.delivered !== undefined)
-    tokens.push(`delivered=${String(result.delivered)}`);
-  if (result.queued === true) tokens.push("queued=true");
-  if (result.persisted !== undefined)
-    tokens.push(`persisted=${String(result.persisted)}`);
-  if (result.forwarded !== undefined)
-    tokens.push(`forwarded=${String(result.forwarded)}`);
-  if (result.consumer) tokens.push(`consumer=${String(result.consumer)}`);
-  if (result.reason) tokens.push(`reason=${String(result.reason)}`);
-  if (result.control) tokens.push(`control=${String(result.control)}`);
-  if (result.outbox) tokens.push(`messages=${String(result.outbox)}`);
-  if (result.message_count !== undefined)
-    tokens.push(`messages=${String(result.message_count)}`);
-  if (result.roster_count !== undefined)
-    tokens.push(`roster=${String(result.roster_count)}`);
-  if (result.room) tokens.push(`room=${String(result.room)}`);
-  if (result.tool) tokens.push(`tool=${String(result.tool)}`);
-  if (result.stopped === true) tokens.push("stopped=true");
-  if (result.signal) tokens.push(`signal=${String(result.signal)}`);
-  if (result.invoked === true) tokens.push("invoked=true");
-  if (result.delivery_error) {
+  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(
-      `delivery_error=${ToolsResponse.compactPreview(result.delivery_error, 96)}`,
+      `next=${(result.next_actions as string[])
+        .map((action) => action.replaceAll(/\s+/g, "_"))
+        .join("|")}`,
     );
   }
-  const nextActions = Array.isArray(result.next_actions)
-    ? (result.next_actions as string[])
-    : actorMessageNextActions(message, result);
-  if (nextActions.length > 0)
-    tokens.push(
-      `next=${nextActions.map((action) => action.replaceAll(/\s+/g, "_")).join("|")}`,
-    );
   return `\n${tokens.join(" ")}`;
 }
 
-export interface ActorMessageToolDeps<TContext = unknown> {
-  getTool?: (name: string) => any | undefined;
-  handleRuntimeMessage?: (
-    type: string,
-    body: unknown,
+function runNextActions(run: string, result: Record<string, unknown>): string[] {
+  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 [];
+}
+
+export interface ControlToolDeps {
+  handleRuntimeControl?: (
+    action: string,
+    input: unknown,
   ) => Record<string, unknown>;
 }
 
-export function createActorMessageToolDefinition<TContext = unknown>(
-  deps: ActorMessageToolDeps<TContext> = {},
+export function createControlToolDefinition<TContext = unknown>(
+  deps: ControlToolDeps = {},
 ): any {
   return {
     name: "message",
-    label: "Message",
+    label: "Control",
     description:
-      "Send one typed addressed message to steer an existing actor instead of restarting it. Core routes are run:<id> and tool:<name>; advanced routes include branch:<run>/<branch>, room:<run> group timelines, coordinator, and session:<id>.",
+      "Apply one Control action to an existing Run or the pi-actors runtime.",
     parameters: Schema.objectSchema(
       {
-        body: Schema.unionSchema([
-          Schema.stringSchema(
-            "Message body. For run:<id>, this is the run-local command line.",
-          ),
-          Schema.looseObjectSchema("Structured JSON message body."),
-          Schema.arraySchema("Structured JSON message body array."),
+        target: Schema.stringSchema("Run target run:<id>, or literal runtime."),
+        action: Schema.stringSchema("Lowercase ASCII Control action, at most 64 characters."),
+        input: Schema.unionSchema([
+          Schema.stringSchema("Optional Control input string; serialized JSON must fit 380 bytes."),
+          Schema.looseObjectSchema("Optional structured Control input; serialized JSON must fit 380 bytes."),
+          Schema.arraySchema("Optional structured Control input array; serialized JSON must fit 380 bytes."),
         ]),
-        correlation_id: Schema.stringSchema(
-          "Optional correlation id for workflow/task linkage.",
-        ),
-        from: Schema.stringSchema(
-          "Optional sender address, such as coordinator or run:<id>.",
-        ),
-        metadata: Schema.looseObjectSchema(
-          "Optional structured metadata for routing or domain hints.",
-        ),
-        reply_to: Schema.stringSchema(
-          "Optional message id this message replies to.",
-        ),
-        summary: Schema.stringSchema("Optional short human-facing summary."),
-        to: Schema.stringSchema(
-          "Destination actor address, e.g. run:<id> or tool:<name>; advanced: branch:<run>/<branch>, room:<run>, coordinator, session:<id>.",
-        ),
-        type: Schema.stringSchema(
-          "Semantic message type, e.g. control.approve or checkpoint.needs_scope.",
-        ),
-        verbose: Schema.booleanSchema(
-          "Return full JSON instead of compact text.",
-        ),
+        verbose: Schema.booleanSchema("Return full JSON instead of compact text."),
       },
-      ["to", "type"],
+      ["target", "action"],
     ),
     async execute(
       _toolCallId: string,
@@ -345,239 +80,96 @@ export function createActorMessageToolDefinition<TContext = unknown>(
       _onUpdate: unknown,
       ctx: TContext,
     ) {
-      const input = asRecord(params);
-      const message = Messages.normalizeActorMessage(input);
-      const address = Messages.parseActorAddress(message.to);
+      const request = Control.normalizeControlRequest(params);
       let result: Record<string, unknown>;
-      if (address.kind === "run" && address.value) {
-        const status = ToolsAccess.assertRunAccessibleToContext(
-          address.value,
-          ctx,
-        );
-        const normalizedMailbox = ToolsMailbox.normalizeMailboxContracts(
-          asRecord(status.mailbox),
-        );
-        const acceptedTypes = new Set(
-          ToolsMailbox.mailboxTypes(normalizedMailbox.accepts),
-        );
-        const advisoryWarnings =
-          acceptedTypes.size > 0 && !acceptedTypes.has(message.type)
-            ? [
-                `Message type ${message.type} is not declared in mailbox.accepts for run:${address.value}.`,
-              ]
-            : [];
-        if (message.type === "control.kill") {
-          result = typeof status.run_instance_id === "string"
-            ? AsyncRuns.killRun(address.value, {
-                ...(typeof status.ownerId === "string"
-                  ? { ownerId: status.ownerId }
-                  : {}),
-                runInstanceId: status.run_instance_id,
-              })
-            : { killed: false, reason: "run generation unavailable" };
-        } else if (message.type === "control.archive") {
-          result = AsyncRuns.archiveRun(address.value);
-        } else if (message.type === "control.prune") {
-          const body = asRecord(message.body);
-          result = AsyncRuns.pruneRun(address.value, {
-            preserveArtifacts:
-              body.preserve_artifacts === true ||
-              body.preserveArtifacts === true,
-          });
-        } else {
-          result = await AsyncRuns.sendRunMessage(
-            address.value,
-            messageBodyToRunLine(message),
+      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`,
           );
         }
-        if (advisoryWarnings.length > 0)
-          result = { ...result, warnings: advisoryWarnings };
-      } else if (address.kind === "branch" && address.value) {
-        const runId = address.value;
-        if (message.from)
-          assertMessageSenderBelongsToRun(
-            message,
-            runId,
-            `branch:${runId}/<branch>`,
-          );
-        const status = ToolsAccess.assertRunAccessibleToContext(runId, ctx);
-        const stateDir = String(status.state_dir ?? "");
-        if (stateDir && address.branch) {
-          const ensureBranchMember = (actorAddress: string) => {
-            Rooms.ensureRoomMember(
-              stateDir,
-              runId,
-              "main",
-              actorAddress,
-              {
-                parent: `run:${runId}`,
-                role: "branch",
-                status: "present",
-              },
-              "Branch joined default room",
-            );
-            Rooms.writeBranchCommunicationSnapshot(
-              stateDir,
-              runId,
-              actorAddress,
-            );
-          };
-          ensureBranchMember(message.to);
-          if (message.from) {
-            const sender = Messages.parseActorAddress(message.from);
-            if (sender.kind === "branch" && sender.value === runId) {
-              ensureBranchMember(message.from);
-            }
-          }
-          Rooms.writeCommunicationSnapshot(stateDir, runId);
+        if (!deps.handleRuntimeControl) {
+          throw new Error("runtime Control is unavailable");
         }
-        result = await routeBranchEnvelope(
-          stateDir,
-          runId,
-          message.to,
-          message,
-          {
-            source: "direct",
-          },
-        );
-      } else if (address.kind === "room" && address.value && address.room) {
-        const runId = address.value;
-        assertMessageSenderBelongsToRun(message, runId, `room:${runId}`);
-        const status = ToolsAccess.assertRunAccessibleToContext(runId, ctx);
-        const stateDir = String(status.state_dir ?? "");
-        if (!stateDir)
-          throw new Error(`${message.to} has no run state directory.`);
-        const recipients = getRoomMulticastRecipients(message, runId);
-        const roomResult = Rooms.appendRoomMessage(
-          stateDir,
-          address.room,
-          message,
-        );
-        const multicastResults = await Promise.all(
-          recipients.map(async (recipient) =>
-            normalizeDeliveryOutcome(
-              { kind: "branch", branch: recipient.split("/").at(-1), value: runId },
-              await routeBranchEnvelope(stateDir, runId, recipient, message, {
-                source: "room-multicast",
-              }),
-            ),
-          ),
-        );
-        result = {
-          ...roomResult,
-          ...(recipients.length > 0
-            ? {
-                multicast: recipients,
-                multicast_count: recipients.length,
-                multicast_results: multicastResults,
-              }
-            : {}),
-        };
-      } else if (address.kind === "tool" && address.value) {
-        if (address.value === "pi-actors" && deps.handleRuntimeMessage) {
-          result = deps.handleRuntimeMessage(message.type, message.body);
+        result = deps.handleRuntimeControl(request.action, request.input);
+      } else {
+        const run = request.target.slice(4);
+        const status = ToolsAccess.assertRunAccessibleToContext(run, ctx);
+        const runInstanceId =
+          typeof status.run_instance_id === "string"
+            ? status.run_instance_id
+            : undefined;
+        if (!runInstanceId) throw new Error(`Run generation unavailable: ${run}`);
+        if (request.action === "kill") {
+          result = AsyncRuns.killRun(run, {
+            ...(typeof status.ownerId === "string"
+              ? { ownerId: status.ownerId }
+              : {}),
+            runInstanceId,
+          });
+        } else if (request.action === "archive") {
+          result = AsyncRuns.archiveRun(run, {
+            ...(typeof status.ownerId === "string"
+              ? { ownerId: status.ownerId }
+              : {}),
+            runInstanceId,
+          });
+        } else if (request.action === "prune") {
+          const input = asRecord(request.input);
+          result = AsyncRuns.pruneRun(
+            run,
+            {
+              preserveArtifacts:
+                input.preserve_artifacts === true ||
+                input.preserveArtifacts === true,
+            },
+            {
+              ...(typeof status.ownerId === "string"
+                ? { ownerId: status.ownerId }
+                : {}),
+              runInstanceId,
+            },
+          );
         } else {
-          const tool = deps.getTool?.(address.value);
-          if (!tool || typeof tool.execute !== "function") {
+          const declared = Array.isArray(status.control)
+            ? status.control.filter(
+                (action): action is string => typeof action === "string",
+              )
+            : [];
+          if (!declared.includes(request.action)) {
             throw new Error(
-              `tool actor not found or not executable: ${address.value}`,
+              `undeclared Run Control action: ${request.action}; available=${declared.join(",") || "none"}`,
             );
           }
-          const toolParams = messageBodyToToolParams(message);
-          let toolResult: unknown;
-          try {
-            toolResult = await tool.execute(
-              `message:${message.type}`,
-              toolParams,
-              _signal,
-              _onUpdate,
-              ctx,
-            );
-          } catch (error) {
-            throw formatToolActorFailure(
-              address.value,
-              message,
-              toolParams,
-              error,
-            );
-          }
-          result = {
-            invoked: true,
-            sent: true,
-            tool: address.value,
-            tool_result: toolResult,
-          };
-        }
-      } else if (address.kind === "coordinator" || address.kind === "session") {
-        if (!message.from) {
-          throw new Error(`message to ${address.kind} requires from=run:<id>.`);
-        }
-        const sender = Messages.parseActorAddress(message.from);
-        if (sender.kind !== "run" || !sender.value) {
-          throw new Error(
-            `message to ${address.kind} currently requires from=run:<id>.`,
+          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 }
+                : {}),
+            },
           );
         }
-        const senderStatus = ToolsAccess.assertRunAccessibleToContext(
-          sender.value,
-          ctx,
-        );
-        if (address.kind === "session") {
-          if (!senderStatus.ownerId) {
-            throw ToolsAccess.sessionMismatchError({
-              currentSession: undefined,
-              expectedSession: address.value,
-              run: sender.value,
-              target: `session:${address.value}`,
-            });
-          }
-          if (senderStatus.ownerId !== address.value) {
-            throw ToolsAccess.sessionMismatchError({
-              currentSession: String(senderStatus.ownerId),
-              expectedSession: address.value,
-              run: sender.value,
-              target: `session:${address.value}`,
-            });
-          }
-        }
-        result = AsyncRuns.appendRunOutboxEvent(sender.value, {
-          body: message.body,
-          correlation_id: message.correlation_id,
-          delivery:
-            message.metadata?.requires_response === true ||
-            address.kind === "session"
-              ? "followup"
-              : undefined,
-          event: message.type,
-          from: message.from,
-          metadata: message.metadata,
-          reply_to: message.reply_to,
-          summary: message.summary,
-          to: message.to,
-          type: message.type,
-        });
-      } else {
-        throw new Error(
-          `message currently supports run:<id>, branch:<run>/<branch>, room:<run>, tool:<name>, coordinator, and session:<id> destinations; unsupported destination: ${message.to}`,
-        );
+        const nextActions = runNextActions(run, result);
+        if (nextActions.length > 0) result = { ...result, next_actions: nextActions };
       }
-      result = normalizeDeliveryOutcome(address, result);
-      const nextActions = actorMessageNextActions(message, result);
-      const resultWithNext = nextActions.length
-        ? { ...result, next_actions: nextActions }
-        : result;
+      const response = { control: request, result };
       return {
         content: [
           {
             type: "text" as const,
-            text: maybeJsonText(
-              { message, result: resultWithNext },
-              input.verbose === true,
-              compactActorMessageResult(message, resultWithNext),
-            ),
+            text:
+              request.verbose === true
+                ? ToolsResponse.jsonText(response)
+                : compactControlResult(request, result),
           },
         ],
-        details: { message, result: resultWithNext },
+        details: response,
       };
     },
   };