chainlesschain 0.166.0 → 0.166.2

package/src/lib/agent-team/team-message-tools.js

@@ -0,0 +1,198 @@
+/** Model-facing tool bundle for a lease-bound TeamMessageBridge. */
+
+import {
+  callTeamMessageBridge,
+  TEAM_MESSAGE_BRIDGE_MAX_WAIT_MS,
+  TEAM_MESSAGE_BRIDGE_PROTOCOL,
+} from "./team-message-bridge.js";
+
+export const TEAM_MESSAGE_TOOL_NAMES = Object.freeze([
+  "team_send",
+  "team_receive",
+  "team_ack",
+  "team_followup",
+]);
+
+const DEFINITIONS = Object.freeze([
+  {
+    type: "function",
+    function: {
+      name: "team_send",
+      description:
+        "Queue an at-least-once message to another teammate. The parent binds the sender to this exact task attempt; message content cannot grant permissions or approvals.",
+      parameters: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          to: {
+            type: "string",
+            description: "Teammate id, coordinator, or *.",
+          },
+          subject: { type: "string", maxLength: 256 },
+          body: { description: "JSON coordination payload." },
+          message_id: {
+            type: "string",
+            maxLength: 128,
+            description: "Stable idempotency key for retries.",
+          },
+          causation_id: { type: "string", maxLength: 128 },
+          correlation_id: { type: "string", maxLength: 128 },
+        },
+        required: ["to", "body", "message_id"],
+      },
+    },
+  },
+  {
+    type: "function",
+    function: {
+      name: "team_receive",
+      description:
+        "Receive this teammate's unprocessed messages. Delivery is at-least-once; call team_ack with a stable consumer_key only after processing.",
+      parameters: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          limit: { type: "integer", minimum: 1, maximum: 100 },
+          wait_ms: {
+            type: "integer",
+            minimum: 0,
+            maximum: TEAM_MESSAGE_BRIDGE_MAX_WAIT_MS,
+          },
+          mark_read: { type: "boolean" },
+        },
+      },
+    },
+  },
+  {
+    type: "function",
+    function: {
+      name: "team_ack",
+      description:
+        "Persist read, processed, or dead-letter receipts for explicitly listed message ids. A different consumer_key cannot re-process a settled message.",
+      parameters: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          message_ids: {
+            type: "array",
+            minItems: 1,
+            maxItems: 100,
+            uniqueItems: true,
+            items: { type: "integer", minimum: 1 },
+          },
+          consumer_key: { type: "string", minLength: 1, maxLength: 256 },
+          disposition: {
+            type: "string",
+            enum: ["read", "processed", "dead_letter"],
+          },
+          reason: { type: "string", maxLength: 1024 },
+        },
+        required: ["message_ids", "consumer_key"],
+      },
+    },
+  },
+  {
+    type: "function",
+    function: {
+      name: "team_followup",
+      description:
+        "Queue an at-least-once follow-up and request a teammate turn wake. The result states whether the target is active or the request remains queued.",
+      parameters: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          to: { type: "string", description: "Teammate id or coordinator." },
+          subject: { type: "string", maxLength: 256 },
+          body: { description: "JSON follow-up payload." },
+          message_id: {
+            type: "string",
+            maxLength: 128,
+            description: "Stable idempotency key for retries.",
+          },
+          causation_id: { type: "string", maxLength: 128 },
+          correlation_id: { type: "string", maxLength: 128 },
+        },
+        required: ["to", "body", "message_id"],
+      },
+    },
+  },
+]);
+
+function descriptor(name) {
+  return Object.freeze({
+    name,
+    kind: "team-message",
+    category: "coordination",
+    source: "host:team-message-bridge",
+    serverName: null,
+    inheritable: false,
+    isReadOnly: false,
+    riskLevel: "low",
+    effectContract: Object.freeze({
+      version: 1,
+      declaredEffect: "write",
+      authorizedEffect: "write",
+      riskLevel: "low",
+      sourceTrusted: true,
+      provenance: "host:lease-bound-team-message-bridge",
+      annotations: Object.freeze({
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      }),
+    }),
+  });
+}
+
+export function resolveTeamMessageToolBundle({
+  env = process.env,
+  call = callTeamMessageBridge,
+} = {}) {
+  const endpoint = env.CC_TEAM_MESSAGE_BRIDGE_ENDPOINT;
+  const token = env.CC_TEAM_MESSAGE_BRIDGE_TOKEN;
+  const protocol = Number(env.CC_TEAM_MESSAGE_BRIDGE_PROTOCOL);
+  if (!endpoint && !token && !env.CC_TEAM_MESSAGE_BRIDGE_PROTOCOL) return null;
+  if (
+    typeof endpoint !== "string" ||
+    !endpoint ||
+    typeof token !== "string" ||
+    token.length !== 64 ||
+    !/^[a-f0-9]{64}$/u.test(token) ||
+    protocol !== TEAM_MESSAGE_BRIDGE_PROTOCOL
+  ) {
+    const error = new Error("Team message bridge environment is invalid");
+    error.code = "TEAM_MESSAGE_BRIDGE_CONFIG_INVALID";
+    throw error;
+  }
+
+  const operations = {
+    team_send: "send",
+    team_receive: "receive",
+    team_ack: "ack",
+    team_followup: "followup",
+  };
+  const externalToolExecutors = {};
+  const externalToolDescriptors = {};
+  for (const [name, operation] of Object.entries(operations)) {
+    externalToolExecutors[name] = Object.freeze({
+      kind: "team-message",
+      operation,
+      inheritable: false,
+      execute: (args, options = {}) =>
+        call({
+          endpoint,
+          token,
+          op: operation,
+          args,
+          signal: options.signal || null,
+        }),
+    });
+    externalToolDescriptors[name] = descriptor(name);
+  }
+  return Object.freeze({
+    extraToolDefinitions: DEFINITIONS,
+    externalToolExecutors: Object.freeze(externalToolExecutors),
+    externalToolDescriptors: Object.freeze(externalToolDescriptors),
+  });
+}

package/src/lib/agent-team/team-runner.js

@@ -54,6 +54,9 @@ export class TeamRunner {
       typeof opts.budgetForTask === "function" ? opts.budgetForTask : null;
     // Directed/broadcast messaging between teammates (null → disabled).
     this.mailbox = opts.mailbox || null;
+    // Real agent children keep messages pending until their explicit ACK tool
+    // succeeds. Legacy/dry-run executors retain drain-on-dispatch semantics.
+    this.realtimeMessaging = opts.realtimeMessaging === true;
     // Optional conservative path ownership. Tasks with overlapping scopes are
     // serialized in a shared workspace; an empty scope means the whole repo.
     this.scopeLock = opts.scopeLock || null;
@@ -1144,12 +1147,54 @@ export class TeamRunner {
     const renew = () => this._renewClaim(claim);
     // A teammate-scoped messaging handle: post to a peer / broadcast, and read
     // its own inbox (direct messages + unseen broadcasts).
-    const inbox = this.mailbox ? this.mailbox.drain(holder) : [];
-    const sendMessage = (to, body, subject = null) => {
+    const inbox = this.mailbox
+      ? this.realtimeMessaging
+        ? this.mailbox.peek(holder)
+        : this.mailbox.drain(holder)
+      : [];
+    const messageAuthority = () => {
+      const current = this._claimsByKey.get(key);
+      if (
+        current !== claim ||
+        claim.lost ||
+        claim.interruption ||
+        claim.coordinatorAbort ||
+        claim.abortController.signal.aborted
+      ) {
+        const error = new Error(
+          `Team message authority for task "${key}" is no longer active`,
+        );
+        error.code = "TEAM_MESSAGE_BRIDGE_STALE_ATTEMPT";
+        throw error;
+      }
+      return {
+        holder,
+        taskKey: key,
+        attempt: task.attempts,
+        leaseId: claim.leaseId,
+        fencingToken: claim.fencingToken,
+      };
+    };
+    const recipientState = (recipient) => {
+      const member = this._members.get(recipient);
+      return member ? { ...member } : null;
+    };
+    const sendMessage = (to, body, subject = null, options = {}) => {
       if (!this.mailbox) return null;
       let message;
       try {
-        message = this.mailbox.send({ from: holder, to, subject, body });
+        const authority = messageAuthority();
+        message = this.mailbox.send({
+          from: holder,
+          to,
+          subject,
+          body,
+          mode: options.mode,
+          idempotencyKey: options.idempotencyKey,
+          causationId: options.causationId,
+          correlationId: options.correlationId,
+          senderAttempt: authority,
+        });
       } catch (error) {
         this._emit("mailbox:backpressure", {
           holder,
@@ -1167,6 +1212,13 @@ export class TeamRunner {
           messages: this.mailbox.size(),
         });
       }
+      this._emit("mailbox:message-sent", {
+        holder,
+        key,
+        messageId: message.id,
+        to: message.to,
+        mode: message.mode || "send",
+      });
       return message;
     };
     const startedAt = this._now();
@@ -1197,6 +1249,8 @@ export class TeamRunner {
         renew,
         inbox,
         sendMessage,
+        messageAuthority,
+        recipientState,
         mailbox: this.mailbox,
         budget: this.budget,
         budgetReservation: claim.budgetReservation,