@canonmsg/agent-sdk 13.2.0 → 13.3.0

package/dist/chunks/{chunk-6FD6KFQN.js → chunk-ZT3TJZAV.js}

@@ -8,7 +8,7 @@ import {
   wasmMlsCustody,
   windowsAclProblems,
   writeDurable
-} from "./chunk-DTAWEQCM.js";
+} from "./chunk-BQGXOAIW.js";
 import {
   BoundedFileReadError,
   CanonApiError,
@@ -30,17 +30,19 @@ import {
   renderCanonHostInboundContent,
   resolveCanonRuntimeConnection,
   splitTextWithinBytes,
+  utf8ByteLength,
   verifyCanonRuntimeConnection
-} from "./chunk-5YKGDUJX.js";
+} from "./chunk-AVR7QCHK.js";
 import {
   NodeMlsDevCustodyError,
   createNodeMlsDevCustody,
   createPortableNodeMlsDevCustody
-} from "./chunk-YJUPKU47.js";
+} from "./chunk-HFT75BNB.js";
 import {
   parseMlsDevClientConfiguration
-} from "./chunk-YHDDOADK.js";
+} from "./chunk-NIORQKUI.js";
 import {
+  AGENT_HOME_ELSEWHERE,
   CONNECTOR_RELAY_ANSWER_WITHIN_MS,
   CONNECTOR_RELAY_INSTALLATION_PATTERN,
   CONNECTOR_RELAY_INSTALLATION_PREFIX,
@@ -54,10 +56,13 @@ import {
   MLS_DEV_TEXT_PROTOCOL_V3,
   NO_REPLY_ACK_NOTE,
   PARTICIPATION_HISTORY_FETCH_LIMIT,
+  VERB_LIMITS,
   __name,
+  agentHomeElsewhereMessage,
   buildParticipationHistorySnapshot,
   connectorRelayResponseBytes,
   evaluateParticipationPolicy,
+  isCanonClientVersion,
   isConnectorRelayCredential,
   isConnectorRelayInstallation,
   isMlsDevTextProtocol,
@@ -70,7 +75,7 @@ import {
   parseMlsDevGroupRoster,
   resolveAllowedUploadMimeType,
   resolveConversationPolicyScope
-} from "./chunk-5WPAB5MB.js";
+} from "./chunk-CUPSYLBV.js";
 
 // src/runner/types.ts
 var DriverSessionError = class extends Error {
@@ -1636,6 +1641,282 @@ import { createHash as createHash4, createHmac } from "node:crypto";
 import { constants as constants3 } from "node:fs";
 import { open as open2, realpath as realpath2 } from "node:fs/promises";
 import { isAbsolute, resolve } from "node:path";
+
+// ../agent-tools/src/communication-tool.ts
+var CANON_COMMUNICATE_DISCOVERY_MAX_RESULTS = 10;
+var NON_EMPTY_ID = { type: "string", minLength: 1, maxLength: 160 };
+var ACTION_FIELDS = {
+  list_conversations: { required: [], optional: ["limit"] },
+  discover_agents: { required: [], optional: ["query", "limit", "cursor"] },
+  message_existing: { required: ["conversationId", "text"], optional: ["messageId"] },
+  start_conversation: { required: ["principalId", "text"], optional: ["selection", "messageId"] },
+  create_conversation: { required: ["memberIds"], optional: ["name"] },
+  manage_participants: { required: ["conversationId", "userId", "operation"], optional: [] },
+  leave_conversation: { required: ["conversationId"], optional: [] },
+  forward_message: { required: ["sourceConversationId", "targetConversationId", "messageId"], optional: ["text"] },
+  share_contact: { required: ["conversationId", "contactUserId"], optional: ["text", "messageId"] }
+};
+var ALIASES = {
+  start_direct: "start_conversation",
+  create_group: "create_conversation",
+  manage_group_members: "manage_participants"
+};
+var CANON_COMMUNICATE_SHAPE = Object.fromEntries(Object.entries(ACTION_FIELDS).map(([action, { required, optional }]) => [action, [...required, ...optional]]));
+var FIELD_SCHEMAS = {
+  limit: { type: "integer", minimum: 1, maximum: 100 },
+  query: { type: "string", maxLength: MAX_DISCOVER_AGENTS_QUERY_LENGTH },
+  cursor: { type: "string", minLength: 1 },
+  conversationId: NON_EMPTY_ID,
+  text: { type: "string" },
+  messageId: NON_EMPTY_ID,
+  principalId: NON_EMPTY_ID,
+  selection: {
+    type: "object",
+    required: ["mode"],
+    additionalProperties: false,
+    properties: { mode: { type: "string", enum: ["new", "latest_or_new", "specific"] }, conversationId: NON_EMPTY_ID }
+  },
+  memberIds: { type: "array", minItems: 1, maxItems: VERB_LIMITS.groupMembers - 1, uniqueItems: true, items: NON_EMPTY_ID },
+  name: { type: "string", minLength: 1, maxLength: VERB_LIMITS.groupNameChars },
+  userId: NON_EMPTY_ID,
+  operation: { type: "string", enum: ["add", "remove"] },
+  sourceConversationId: NON_EMPTY_ID,
+  targetConversationId: NON_EMPTY_ID,
+  contactUserId: NON_EMPTY_ID
+};
+var SEND_ID = "a stable id for this message; reuse it when retrying";
+var FIELD_NOTES = {
+  limit: { list_conversations: "how many conversations, 1 to 100", discover_agents: `how many agents, 1 to ${CANON_COMMUNICATE_DISCOVERY_MAX_RESULTS} (default ${CANON_COMMUNICATE_DISCOVERY_MAX_RESULTS})` },
+  query: { discover_agents: `a name or description prefix of at most ${MAX_DISCOVER_AGENTS_QUERY_LENGTH} characters; leave it out to list the directory` },
+  cursor: { discover_agents: "the cursor a previous discover_agents call with the same query returned" },
+  conversationId: {
+    message_existing: "the conversation to post in",
+    share_contact: "the conversation to share the contact in",
+    manage_participants: "the conversation",
+    leave_conversation: "the conversation to leave"
+  },
+  text: {
+    message_existing: "the message",
+    start_conversation: `the opening message, never split; at most ${MLS_DEV_TEXT_MAX_BYTES} UTF-8 bytes when encrypted. Use message_existing for longer follow-ups`,
+    forward_message: "a caption",
+    share_contact: "a caption"
+  },
+  messageId: { message_existing: SEND_ID, start_conversation: SEND_ID, share_contact: SEND_ID, forward_message: "the message to forward" },
+  principalId: { start_conversation: "the person or agent to talk to" },
+  selection: { start_conversation: "which direct conversation: mode new (the default), latest_or_new, or specific with its conversationId" },
+  memberIds: { create_conversation: "the people and agents to add besides you" },
+  name: { create_conversation: "a title" },
+  userId: { manage_participants: "the person or agent to add or remove" },
+  operation: { manage_participants: "add or remove" },
+  sourceConversationId: { forward_message: "the conversation the message is in" },
+  targetConversationId: { forward_message: "the conversation to forward it to" },
+  contactUserId: { share_contact: "whose contact card to share" }
+};
+function communicateInputSchema(shape, textMaxLength = VERB_LIMITS.messageTextBytes) {
+  const actions = Object.keys(shape);
+  const properties = {
+    action: { type: "string", enum: actions, description: "What to do. Each other field says which actions take it." }
+  };
+  for (const [field, schema] of Object.entries(FIELD_SCHEMAS)) {
+    const uses = actions.filter((action) => shape[action].includes(field) || ACTION_FIELDS[action].required.includes(field));
+    if (!uses.length) continue;
+    const notes = uses.map((action) => `${action} (${ACTION_FIELDS[action].required.includes(field) ? "required" : "optional"}): ${FIELD_NOTES[field][action]}`);
+    properties[field] = { ...schema, ...field === "text" && textMaxLength !== null ? { maxLength: textMaxLength } : {}, description: `${notes.join("; ")}.` };
+  }
+  return { type: "object", required: ["action"], additionalProperties: false, properties };
+}
+__name(communicateInputSchema, "communicateInputSchema");
+function isRecord3(value) {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+__name(isRecord3, "isRecord");
+function readRequiredString(value) {
+  return typeof value === "string" && value.trim() ? value : null;
+}
+__name(readRequiredString, "readRequiredString");
+var listed = /* @__PURE__ */ __name((names) => names.length < 2 ? names.join("") : `${names.slice(0, -1).join(", ")} and ${names.at(-1)}`, "listed");
+function parseCommunicateToolInput(value, shape = CANON_COMMUNICATE_SHAPE) {
+  if (!isRecord3(value)) throw new Error("communicate arguments must be an object");
+  const action = typeof value.action === "string" ? ALIASES[value.action] ?? value.action : "";
+  if (!Object.hasOwn(shape, action)) {
+    throw new Error(`communicate.action is invalid: use ${listed(Object.keys(shape))}`);
+  }
+  const fields = ACTION_FIELDS[action];
+  const missing = fields.required.filter((field) => value[field] === void 0 || value[field] === null || typeof value[field] === "string" && !value[field].trim());
+  if (missing.length) throw new Error(`${String(value.action)} needs ${listed(missing)}`);
+  const taken = ["action", ...fields.required, ...fields.optional];
+  const extra = Object.keys(value).filter((field) => !taken.includes(field));
+  if (extra.length) throw new Error(`${String(value.action)} does not take ${listed(extra)}`);
+  if (value.action === "list_conversations") {
+    if (value.limit !== void 0 && (!Number.isInteger(value.limit) || value.limit < 1 || value.limit > 100)) throw new Error("list_conversations requires an optional limit from 1 to 100");
+    return { action: "list_conversations", ...typeof value.limit === "number" ? { limit: value.limit } : {} };
+  }
+  if (value.action === "leave_conversation") {
+    const conversationId = readRequiredString(value.conversationId);
+    if (!conversationId) throw new Error("leave_conversation requires conversationId");
+    return { action: "leave_conversation", conversationId };
+  }
+  if (value.action === "discover_agents") {
+    if (value.query !== void 0 && typeof value.query !== "string") {
+      throw new Error("communicate.query must be a string");
+    }
+    if (typeof value.query === "string" && value.query.length > MAX_DISCOVER_AGENTS_QUERY_LENGTH) {
+      throw new Error(
+        `communicate.query must be at most ${MAX_DISCOVER_AGENTS_QUERY_LENGTH} characters`
+      );
+    }
+    if (value.limit !== void 0 && (!Number.isInteger(value.limit) || value.limit < 1 || value.limit > CANON_COMMUNICATE_DISCOVERY_MAX_RESULTS)) {
+      throw new Error(
+        `communicate.limit must be an integer from 1 to ${CANON_COMMUNICATE_DISCOVERY_MAX_RESULTS}`
+      );
+    }
+    if (value.cursor !== void 0 && (typeof value.cursor !== "string" || value.cursor.length === 0)) {
+      throw new Error("communicate.cursor must be a non-empty string");
+    }
+    return {
+      action: "discover_agents",
+      ...typeof value.query === "string" ? { query: value.query } : {},
+      limit: typeof value.limit === "number" ? value.limit : CANON_COMMUNICATE_DISCOVERY_MAX_RESULTS,
+      ...typeof value.cursor === "string" ? { cursor: value.cursor } : {}
+    };
+  }
+  if (value.action === "create_group" || value.action === "create_conversation") {
+    const name = value.name === void 0 ? void 0 : readRequiredString(value.name);
+    if (name === null) throw new Error("communicate.name must be a non-empty string when supplied");
+    if (!Array.isArray(value.memberIds) || value.memberIds.length === 0 || !value.memberIds.every((entry) => readRequiredString(entry) !== null)) {
+      throw new Error("communicate.memberIds must contain at least one principal id");
+    }
+    return {
+      action: value.action,
+      ...name ? { name } : {},
+      memberIds: [...new Set(value.memberIds)]
+    };
+  }
+  if (value.action === "forward_message") {
+    const sourceConversationId = readRequiredString(value.sourceConversationId);
+    const targetConversationId = readRequiredString(value.targetConversationId);
+    const messageId2 = readRequiredString(value.messageId);
+    if (!sourceConversationId) throw new Error("communicate.sourceConversationId is required");
+    if (!targetConversationId) throw new Error("communicate.targetConversationId is required");
+    if (!messageId2) throw new Error("communicate.messageId is required");
+    if (value.text !== void 0 && typeof value.text !== "string") {
+      throw new Error("communicate.text must be a string");
+    }
+    return {
+      action: "forward_message",
+      sourceConversationId,
+      targetConversationId,
+      messageId: messageId2,
+      ...value.text !== void 0 ? { text: value.text } : {}
+    };
+  }
+  if (value.action === "share_contact") {
+    const conversationId = readRequiredString(value.conversationId);
+    const contactUserId = readRequiredString(value.contactUserId);
+    const messageId2 = value.messageId === void 0 ? void 0 : readRequiredString(value.messageId);
+    if (!conversationId) throw new Error("communicate.conversationId is required");
+    if (!contactUserId) throw new Error("communicate.contactUserId is required");
+    if (value.text !== void 0 && typeof value.text !== "string") {
+      throw new Error("communicate.text must be a string");
+    }
+    if (value.messageId !== void 0 && !messageId2) {
+      throw new Error("communicate.messageId must be a non-empty string");
+    }
+    return {
+      action: "share_contact",
+      conversationId,
+      contactUserId,
+      ...value.text !== void 0 ? { text: value.text } : {},
+      ...messageId2 ? { messageId: messageId2 } : {}
+    };
+  }
+  if (value.action === "manage_group_members" || value.action === "manage_participants") {
+    const conversationId = readRequiredString(value.conversationId);
+    const userId = readRequiredString(value.userId);
+    if (!conversationId) throw new Error("communicate.conversationId is required");
+    if (!userId) throw new Error("communicate.userId is required");
+    if (value.operation !== "add" && value.operation !== "remove") {
+      throw new Error("communicate.operation must be add or remove");
+    }
+    return {
+      action: value.action,
+      conversationId,
+      userId,
+      operation: value.operation
+    };
+  }
+  const text3 = readRequiredString(value.text);
+  const messageId = value.messageId === void 0 ? void 0 : readRequiredString(value.messageId);
+  if (!text3) throw new Error("communicate.text is required");
+  if (value.messageId !== void 0 && !messageId) {
+    throw new Error("communicate.messageId must be a non-empty string");
+  }
+  if (value.action === "message_existing") {
+    const conversationId = readRequiredString(value.conversationId);
+    if (!conversationId) throw new Error("communicate.conversationId is required");
+    return {
+      action: "message_existing",
+      conversationId,
+      text: text3,
+      ...messageId ? { messageId } : {}
+    };
+  }
+  if (value.action === "start_direct" || value.action === "start_conversation") {
+    const principalId = readRequiredString(value.principalId);
+    if (!principalId) throw new Error("communicate.principalId is required");
+    if (utf8ByteLength(text3) > MLS_DEV_TEXT_MAX_BYTES) {
+      throw new Error(`${value.action} opening text must be at most ${MLS_DEV_TEXT_MAX_BYTES} UTF-8 bytes; use message_existing for longer follow-ups`);
+    }
+    const selection = value.selection === void 0 ? value.action === "start_conversation" ? { mode: "new" } : void 0 : parseDirectConversationSelection(value.selection);
+    return {
+      action: value.action,
+      principalId,
+      text: text3,
+      ...selection ? { selection } : {},
+      ...messageId ? { messageId } : {}
+    };
+  }
+  throw new Error("communicate.action is invalid");
+}
+__name(parseCommunicateToolInput, "parseCommunicateToolInput");
+function renderResult(result) {
+  let id;
+  if (result.status === "messaged" || result.status === "forwarded" || result.status === "shared") {
+    id = result.messageId;
+  } else if (result.status === "added" || result.status === "removed") {
+    id = result.userId;
+  } else if (result.status === "created") {
+    id = result.conversationId;
+  } else if (result.status === "requested" || result.status === "pending") {
+    id = result.requestId;
+  }
+  return {
+    content: [{
+      type: "text",
+      text: `communicate: ${result.status}${id ? ` (${id})` : ""}
+${JSON.stringify(result, null, 2)}`
+    }]
+  };
+}
+__name(renderResult, "renderResult");
+async function executeCanonCommunicateTool(client, args, shape = CANON_COMMUNICATE_SHAPE) {
+  let input;
+  try {
+    input = parseCommunicateToolInput(args, shape);
+  } catch (error) {
+    return {
+      content: [{
+        type: "text",
+        text: `Invalid communicate arguments: ${error.message}`
+      }],
+      isError: true
+    };
+  }
+  return renderResult(await client.communicate(input));
+}
+__name(executeCanonCommunicateTool, "executeCanonCommunicateTool");
+
+// src/runner/mls.ts
 var fail = /* @__PURE__ */ __name(() => {
   throw new Error("MLS_AUTHORITY_REQUIRED");
 }, "fail");
@@ -1712,30 +1993,22 @@ function mentionsAgent(text3, names) {
   });
 }
 __name(mentionsAgent, "mentionsAgent");
+var ENCRYPTED_COMMUNICATE_SHAPE = {
+  list_conversations: ["limit"],
+  discover_agents: ["limit"],
+  message_existing: ["conversationId", "text"]
+};
 var ENCRYPTED_COMMUNICATE = {
   name: "communicate",
   description: "List Canon conversations or agents, or send text to the current encrypted conversation. Other Canon outputs are not yet supported.",
-  inputSchema: { type: "object", oneOf: [
-    {
-      type: "object",
-      required: ["action"],
-      additionalProperties: false,
-      properties: { action: { const: "list_conversations" }, limit: { type: "integer", minimum: 1, maximum: 100 } }
-    },
-    {
-      type: "object",
-      required: ["action"],
-      additionalProperties: false,
-      properties: { action: { const: "discover_agents" }, limit: { type: "integer", minimum: 1, maximum: 10 } }
-    },
-    {
-      type: "object",
-      required: ["action", "conversationId", "text"],
-      additionalProperties: false,
-      properties: { action: { const: "message_existing" }, conversationId: { type: "string", minLength: 1 }, text: { type: "string", minLength: 1 } }
-    }
-  ] }
+  inputSchema: communicateInputSchema(ENCRYPTED_COMMUNICATE_SHAPE, null)
 };
+var errandShape = /* @__PURE__ */ __name((contact) => ({ ...ENCRYPTED_COMMUNICATE_SHAPE, ...contact ? { start_conversation: ["principalId", "text"] } : {} }), "errandShape");
+var errandCommunicate = /* @__PURE__ */ __name((contact) => ({
+  name: "communicate",
+  description: "List Canon conversations or agents, or send text to your errand's recipient or to the conversation it came from" + (contact ? ". Start the conversation with the recipient first, with start_conversation." : "."),
+  inputSchema: communicateInputSchema(errandShape(contact), null)
+}), "errandCommunicate");
 var MAX_CONFIGURATION_BYTES = 64 * 1024;
 function invalid() {
   throw new Error("MLS_DEV_CONFIGURATION_INVALID");
@@ -2412,232 +2685,16 @@ function relayRunnerHome(home, installationId) {
 }
 __name(relayRunnerHome, "relayRunnerHome");
 
+// src/version.ts
+var AGENT_SDK_VERSION = true ? "13.3.0" : void 0;
+var RUNNER_CLIENT = isCanonClientVersion(AGENT_SDK_VERSION) ? Object.freeze({ kind: "runner", version: AGENT_SDK_VERSION }) : void 0;
+
 // src/runner/runner.ts
 import { createHash as createHash9, randomUUID as randomUUID2 } from "node:crypto";
 import { readFileSync as readFileSync7, rmSync as rmSync2 } from "node:fs";
 import { realpath as realpath4, stat as stat2 } from "node:fs/promises";
 import { basename as basename4, isAbsolute as isAbsolute3, join as join8, sep } from "node:path";
 
-// ../agent-tools/src/communication-tool.ts
-var CANON_COMMUNICATE_DISCOVERY_MAX_RESULTS = 10;
-function isRecord3(value) {
-  return Boolean(value && typeof value === "object" && !Array.isArray(value));
-}
-__name(isRecord3, "isRecord");
-function readRequiredString(value) {
-  return typeof value === "string" && value.trim() ? value : null;
-}
-__name(readRequiredString, "readRequiredString");
-function hasOnlyKeys(record, allowed) {
-  return Object.keys(record).every((key) => allowed.has(key));
-}
-__name(hasOnlyKeys, "hasOnlyKeys");
-function parseCommunicateToolInput(value) {
-  if (!isRecord3(value)) throw new Error("communicate arguments must be an object");
-  if (value.action === "list_conversations") {
-    if (!hasOnlyKeys(value, /* @__PURE__ */ new Set(["action", "limit"])) || value.limit !== void 0 && (!Number.isInteger(value.limit) || value.limit < 1 || value.limit > 100)) throw new Error("list_conversations requires an optional limit from 1 to 100");
-    return { action: "list_conversations", ...typeof value.limit === "number" ? { limit: value.limit } : {} };
-  }
-  if (value.action === "leave_conversation") {
-    const conversationId = readRequiredString(value.conversationId);
-    if (!hasOnlyKeys(value, /* @__PURE__ */ new Set(["action", "conversationId"])) || !conversationId) throw new Error("leave_conversation requires conversationId");
-    return { action: "leave_conversation", conversationId };
-  }
-  if (value.action === "discover_agents") {
-    if (!hasOnlyKeys(value, /* @__PURE__ */ new Set(["action", "query", "limit", "cursor"]))) {
-      throw new Error("discover_agents contains unsupported fields");
-    }
-    if (value.query !== void 0 && typeof value.query !== "string") {
-      throw new Error("communicate.query must be a string");
-    }
-    if (typeof value.query === "string" && value.query.length > MAX_DISCOVER_AGENTS_QUERY_LENGTH) {
-      throw new Error(
-        `communicate.query must be at most ${MAX_DISCOVER_AGENTS_QUERY_LENGTH} characters`
-      );
-    }
-    if (value.limit !== void 0 && (!Number.isInteger(value.limit) || value.limit < 1 || value.limit > CANON_COMMUNICATE_DISCOVERY_MAX_RESULTS)) {
-      throw new Error(
-        `communicate.limit must be an integer from 1 to ${CANON_COMMUNICATE_DISCOVERY_MAX_RESULTS}`
-      );
-    }
-    if (value.cursor !== void 0 && (typeof value.cursor !== "string" || value.cursor.length === 0)) {
-      throw new Error("communicate.cursor must be a non-empty string");
-    }
-    return {
-      action: "discover_agents",
-      ...typeof value.query === "string" ? { query: value.query } : {},
-      limit: typeof value.limit === "number" ? value.limit : CANON_COMMUNICATE_DISCOVERY_MAX_RESULTS,
-      ...typeof value.cursor === "string" ? { cursor: value.cursor } : {}
-    };
-  }
-  if (value.action === "create_group" || value.action === "create_conversation") {
-    if (!hasOnlyKeys(value, /* @__PURE__ */ new Set(["action", "name", "memberIds"]))) {
-      throw new Error("create_group contains unsupported fields");
-    }
-    const name = value.name === void 0 ? void 0 : readRequiredString(value.name);
-    if (name === null) throw new Error("communicate.name must be a non-empty string when supplied");
-    if (!Array.isArray(value.memberIds) || value.memberIds.length === 0 || !value.memberIds.every((entry) => readRequiredString(entry) !== null)) {
-      throw new Error("communicate.memberIds must contain at least one principal id");
-    }
-    return {
-      action: value.action,
-      ...name ? { name } : {},
-      memberIds: [...new Set(value.memberIds)]
-    };
-  }
-  if (value.action === "forward_message") {
-    if (!hasOnlyKeys(value, /* @__PURE__ */ new Set([
-      "action",
-      "sourceConversationId",
-      "targetConversationId",
-      "messageId",
-      "text"
-    ]))) {
-      throw new Error("forward_message contains unsupported fields");
-    }
-    const sourceConversationId = readRequiredString(value.sourceConversationId);
-    const targetConversationId = readRequiredString(value.targetConversationId);
-    const messageId2 = readRequiredString(value.messageId);
-    if (!sourceConversationId) throw new Error("communicate.sourceConversationId is required");
-    if (!targetConversationId) throw new Error("communicate.targetConversationId is required");
-    if (!messageId2) throw new Error("communicate.messageId is required");
-    if (value.text !== void 0 && typeof value.text !== "string") {
-      throw new Error("communicate.text must be a string");
-    }
-    return {
-      action: "forward_message",
-      sourceConversationId,
-      targetConversationId,
-      messageId: messageId2,
-      ...value.text !== void 0 ? { text: value.text } : {}
-    };
-  }
-  if (value.action === "share_contact") {
-    if (!hasOnlyKeys(value, /* @__PURE__ */ new Set([
-      "action",
-      "conversationId",
-      "contactUserId",
-      "text",
-      "messageId"
-    ]))) {
-      throw new Error("share_contact contains unsupported fields");
-    }
-    const conversationId = readRequiredString(value.conversationId);
-    const contactUserId = readRequiredString(value.contactUserId);
-    const messageId2 = value.messageId === void 0 ? void 0 : readRequiredString(value.messageId);
-    if (!conversationId) throw new Error("communicate.conversationId is required");
-    if (!contactUserId) throw new Error("communicate.contactUserId is required");
-    if (value.text !== void 0 && typeof value.text !== "string") {
-      throw new Error("communicate.text must be a string");
-    }
-    if (value.messageId !== void 0 && !messageId2) {
-      throw new Error("communicate.messageId must be a non-empty string");
-    }
-    return {
-      action: "share_contact",
-      conversationId,
-      contactUserId,
-      ...value.text !== void 0 ? { text: value.text } : {},
-      ...messageId2 ? { messageId: messageId2 } : {}
-    };
-  }
-  if (value.action === "manage_group_members" || value.action === "manage_participants") {
-    if (!hasOnlyKeys(value, /* @__PURE__ */ new Set([
-      "action",
-      "conversationId",
-      "userId",
-      "operation"
-    ]))) {
-      throw new Error("manage_group_members contains unsupported fields");
-    }
-    const conversationId = readRequiredString(value.conversationId);
-    const userId = readRequiredString(value.userId);
-    if (!conversationId) throw new Error("communicate.conversationId is required");
-    if (!userId) throw new Error("communicate.userId is required");
-    if (value.operation !== "add" && value.operation !== "remove") {
-      throw new Error("communicate.operation must be add or remove");
-    }
-    return {
-      action: value.action,
-      conversationId,
-      userId,
-      operation: value.operation
-    };
-  }
-  const text3 = readRequiredString(value.text);
-  const messageId = value.messageId === void 0 ? void 0 : readRequiredString(value.messageId);
-  if (!text3) throw new Error("communicate.text is required");
-  if (value.messageId !== void 0 && !messageId) {
-    throw new Error("communicate.messageId must be a non-empty string");
-  }
-  if (value.action === "message_existing") {
-    if (!hasOnlyKeys(value, /* @__PURE__ */ new Set(["action", "conversationId", "text", "messageId"]))) {
-      throw new Error("message_existing contains unsupported fields");
-    }
-    const conversationId = readRequiredString(value.conversationId);
-    if (!conversationId) throw new Error("communicate.conversationId is required");
-    return {
-      action: "message_existing",
-      conversationId,
-      text: text3,
-      ...messageId ? { messageId } : {}
-    };
-  }
-  if (value.action === "start_direct" || value.action === "start_conversation") {
-    if (!hasOnlyKeys(value, /* @__PURE__ */ new Set(["action", "principalId", "text", "selection", "messageId"]))) {
-      throw new Error("start_direct contains unsupported fields");
-    }
-    const principalId = readRequiredString(value.principalId);
-    if (!principalId) throw new Error("communicate.principalId is required");
-    const selection = value.selection === void 0 ? value.action === "start_conversation" ? { mode: "new" } : void 0 : parseDirectConversationSelection(value.selection);
-    return {
-      action: value.action,
-      principalId,
-      text: text3,
-      ...selection ? { selection } : {},
-      ...messageId ? { messageId } : {}
-    };
-  }
-  throw new Error("communicate.action is invalid");
-}
-__name(parseCommunicateToolInput, "parseCommunicateToolInput");
-function renderResult(result) {
-  let id;
-  if (result.status === "messaged" || result.status === "forwarded" || result.status === "shared") {
-    id = result.messageId;
-  } else if (result.status === "added" || result.status === "removed") {
-    id = result.userId;
-  } else if (result.status === "created") {
-    id = result.conversationId;
-  } else if (result.status === "requested" || result.status === "pending") {
-    id = result.requestId;
-  }
-  return {
-    content: [{
-      type: "text",
-      text: `communicate: ${result.status}${id ? ` (${id})` : ""}
-${JSON.stringify(result, null, 2)}`
-    }]
-  };
-}
-__name(renderResult, "renderResult");
-async function executeCanonCommunicateTool(client, args) {
-  let input;
-  try {
-    input = parseCommunicateToolInput(args);
-  } catch (error) {
-    return {
-      content: [{
-        type: "text",
-        text: `Invalid communicate arguments: ${error.message}`
-      }],
-      isError: true
-    };
-  }
-  return renderResult(await client.communicate(input));
-}
-__name(executeCanonCommunicateTool, "executeCanonCommunicateTool");
-
 // src/runner/finals.ts
 import { createHash as createHash7 } from "node:crypto";
 import { readdirSync as readdirSync3, readFileSync as readFileSync5, rmdirSync, unlinkSync as unlinkSync2 } from "node:fs";
@@ -3371,7 +3428,21 @@ var STYLE_RULES = {
   observer: "Stay quiet unless a reply is necessary, and end your turn with no_reply."
 };
 var factText = /* @__PURE__ */ __name((value, limit = MAX_FACT_NAME) => speaker(value).slice(0, limit).trimEnd(), "factText");
-function factsPrompt({ name, topic, owner, members, rules }, kind) {
+var mentionKey = /* @__PURE__ */ __name((value) => value.normalize("NFC").trim().replace(/^@+/, "").replace(/\s+/g, " ").toLowerCase(), "mentionKey");
+var mentionsToo = /* @__PURE__ */ __name((name, other) => other.length > 0 && name.startsWith(other) && !/^[\p{L}\p{N}\p{M}_]/u.test(name.slice(other.length)), "mentionsToo");
+function mentionOf(peer, agents) {
+  const name = peer.name?.trim();
+  const key = name ? mentionKey(name) : "";
+  if (name && key && !name.startsWith("@") && factText(name) === name && !agents.some((other) => other !== peer && !other.isYou && [other.name, other.id].some((word) => word !== void 0 && mentionsToo(key, mentionKey(word))))) return name;
+  return ENDPOINT_ID_PATTERN.test(peer.id) ? peer.id : void 0;
+}
+__name(mentionOf, "mentionOf");
+function factsPrompt({ name, topic, owner, members, rules }, kind, self) {
+  const agents = members.filter((member) => member.type === "ai_agent");
+  const reach = rules && !rules.allowAgentToAgent ? [] : members.slice(0, MAX_FACT_MEMBERS).filter((member) => member.type === "ai_agent" && !member.isYou).flatMap((peer) => {
+    const mention = mentionOf(peer, agents), seen = factText(peer.name ?? peer.id);
+    return !mention ? [] : [mention === seen ? `@${mention}` : `@${mention} (the id of ${seen})`];
+  });
   const shown = members.slice(0, MAX_FACT_MEMBERS).map((member) => member.isYou ? "you" : factText(member.name ?? member.id) + (member.isOwner ? OWNER_MARK : member.type === "ai_agent" ? " [agent]" : ""));
   const lines = !rules ? [] : [
     STYLE_RULES[rules.style],
@@ -3382,10 +3453,12 @@ function factsPrompt({ name, topic, owner, members, rules }, kind) {
   ].filter((line) => line !== void 0);
   return [
     FACTS_OPEN,
+    ...self ? [`Your name: ${factText(self)}`] : [],
     `Your owner: ${factText(owner.name ?? owner.id)}`,
     ...name ? [`Conversation: ${factText(name)}`] : [],
     ...topic ? [`Topic: ${factText(topic, MAX_FACT_TOPIC)}`] : [],
     `Members: ${shown.join(", ")}${members.length > shown.length ? `, and ${members.length - shown.length} more` : ""}`,
+    ...reach.length ? [`${reach.length > 1 ? "Other agents here answer only a message that mentions them" : "Another agent here answers only a message that mentions it"}: ${reach.join(", ")}.`] : [],
     ...lines.length ? [
       "This conversation's rules, which your owner or any of its admins can set. They say how you take part here, not what you may do:",
       ...lines.map((line) => `- ${line}`)
@@ -3394,16 +3467,6 @@ function factsPrompt({ name, topic, owner, members, rules }, kind) {
   ];
 }
 __name(factsPrompt, "factsPrompt");
-var errandCommunicate = /* @__PURE__ */ __name((contact) => ({
-  name: "communicate",
-  description: "List Canon conversations or agents, or send text to your errand's recipient or to the conversation it came from" + (contact ? ". Start the conversation with the recipient first, with start_conversation." : "."),
-  inputSchema: { type: "object", oneOf: [...ENCRYPTED_COMMUNICATE.inputSchema.oneOf, ...contact ? [{
-    type: "object",
-    required: ["action", "principalId", "text"],
-    additionalProperties: false,
-    properties: { action: { const: "start_conversation" }, principalId: { type: "string", minLength: 1 }, text: { type: "string", minLength: 1 } }
-  }] : []] }
-}), "errandCommunicate");
 var promptLine = /* @__PURE__ */ __name((message2, name, media, mark = "") => [
   `${speaker(name)}${mark}: ${defused(renderCanonHostInboundContent(message2, media?.files))}`,
   ...(media?.failed ?? []).map((label) => `[Attachment "${defused(inert(label))}" could not be downloaded]`)
@@ -3553,6 +3616,7 @@ async function createRunner(options) {
   }, "keyed");
   let outboundClosed = false;
   let ownershipVersion;
+  let installationId;
   let displayName;
   let ownerOf;
   const refused = /* @__PURE__ */ new Set();
@@ -3686,11 +3750,18 @@ async function createRunner(options) {
     log(why === "plaintext" ? `Refusing room ${roomId}: it is not encrypted, and this runner takes part only in encrypted rooms. Its messages are not delivered to this agent.` : `Refusing encrypted room ${roomId}: ${why === "no-device" ? "this runner has no MLS device (run it with --mls-dev-config)" : why === "remote" ? `the ${driver.name} driver runs off this host, which an encrypted room allows only in relay mode` : "its encryption protocol is not supported"}. Its messages are not delivered to this agent.`);
   }
   __name(refuse, "refuse");
+  let homeSince = 0;
   async function authorize() {
     await endpoint.mlsDevDevice.ensureReady();
     const me = await client.getAgentMe();
     requireMlsSupport({ environmentId: options.environmentId });
     if (me.agentId !== agentId || me.ownershipVersion !== ownershipVersion) throw new Error("MLS_AUTHORITY_REQUIRED");
+    if (!options.relay && me.home && (me.home.kind === "connector" || me.home.installationId !== void 0 && me.home.installationId !== installationId)) {
+      const error = Object.assign(new Error(agentHomeElsewhereMessage(me.displayName, me.home)), { code: AGENT_HOME_ELSEWHERE });
+      options.onFatal?.(error);
+      throw error;
+    }
+    homeSince = !options.relay && me.home?.kind === "runner" ? me.home.since ?? 0 : 0;
     outboundClosed = me.outboundPolicy === "closed";
     if (outboundClosed && options.relay) throw new Error("MLS_AUTHORITY_REQUIRED");
     displayName = me.displayName;
@@ -3733,6 +3804,50 @@ ${error instanceof Error ? error.message : String(error)}`;
     turn.timer.unref?.();
   }
   __name(progress, "progress");
+  const waitingRooms = /* @__PURE__ */ new Map(), noting = /* @__PURE__ */ new Map();
+  let ownerAsk;
+  function noteAdmission(roomId, known) {
+    const next = (noting.get(roomId) ?? Promise.resolve()).then(() => lookAtAdmission(roomId, known));
+    noting.set(roomId, next.catch(() => void 0));
+    return next;
+  }
+  __name(noteAdmission, "noteAdmission");
+  async function lookAtAdmission(roomId, known) {
+    if (!mlsOn || stopping) return;
+    const inGroup = /* @__PURE__ */ __name(async () => {
+      const view = await endpoint.mlsDevGroups.read(roomId);
+      return !!view && view.status !== "removed";
+    }, "inGroup");
+    const read = /* @__PURE__ */ __name(async () => await endpoint.getConversation(roomId).catch(() => null) ?? void 0, "read");
+    let joined = await inGroup(), room2 = known;
+    if (!joined && known && !waitingRooms.has(roomId)) {
+      room2 = await read() ?? room2;
+      joined = await inGroup();
+    }
+    if (joined) {
+      if (waitingRooms.has(roomId)) log(`Joined ${waitingRooms.get(roomId)}.`);
+      waitingRooms.delete(roomId);
+      return;
+    }
+    if (waitingRooms.has(roomId) || (await endpoint.mlsDevGroups.readAdmissionHold(roomId)).outside !== true) return;
+    room2 ??= await read();
+    const members = Array.isArray(room2?.memberIds) ? room2.memberIds : [];
+    if (!members.includes(agentId)) return;
+    const label = typeof room2?.name === "string" && room2.name.trim() ? `"${room2.name.trim()}"` : `room ${roomId}`;
+    waitingRooms.set(roomId, label);
+    ownerAsk ??= client.getAgentMe().then((me) => ({ id: me.ownerId, ...me.ownerName ? { name: me.ownerName } : {} }));
+    const owner2 = await ownerAsk.catch(() => void 0);
+    const ask2 = owner2 && members.includes(owner2.id) ? `Ask ${owner2.name ?? "its owner"} to open Canon.` : "Ask one of its members to open Canon.";
+    log(`Waiting to join ${label}: only a device already in it can add this agent's device. ${ask2}`);
+  }
+  __name(lookAtAdmission, "lookAtAdmission");
+  async function noteAdmissions() {
+    const { conversations = [] } = await endpoint.query("list_conversations", { limit: 100 });
+    for (const room2 of conversations) {
+      if (typeof room2.id === "string" && ["mls", "mlsRequired", "mlsProtocol"].some((key) => Object.hasOwn(room2, key))) await noteAdmission(room2.id, room2);
+    }
+  }
+  __name(noteAdmissions, "noteAdmissions");
   async function offer(event) {
     offering += 1;
     touch();
@@ -3783,6 +3898,7 @@ ${error instanceof Error ? error.message : String(error)}`;
     await authorize();
     const binding = await groups.readVerifiedMessageBinding({ conversationId, messageId: payload.message.id });
     if (!binding) throw new Error("MLS_INPUT_NOT_VERIFIED");
+    if (binding.acceptedAtMs < homeSince) return void await handle.settle("mls-before-home");
     const { messages } = await endpoint.query("get_messages", { conversationId, messageIds: [binding.messageId] });
     const [message2] = messages;
     if (messages.length !== 1 || message2.id !== binding.messageId || message2.senderId !== binding.senderId || message2.senderType !== binding.senderPrincipal.type || !Number.isSafeInteger(message2.mlsFeedOrdinal) || typeof message2.text !== "string" && !(message2.text === null && (message2.attachments?.length ?? 0) === 1)) throw new Error("MLS_INPUT_NOT_VERIFIED");
@@ -4166,6 +4282,8 @@ ${decision.reasonCode}`;
   function bindTools(current, turn) {
     const questions = /* @__PURE__ */ new Map();
     let asked = 0;
+    const errandContact = Boolean(turn.errand && "contact" in turn.errand.target);
+    const shape = turn.errand ? errandShape(errandContact) : ENCRYPTED_COMMUNICATE_SHAPE;
     const handlers = {
       no_reply: /* @__PURE__ */ __name(async ({ reason }) => {
         turn.silenced = typeof reason === "string" && reason.trim() ? { reason } : {};
@@ -4186,7 +4304,7 @@ ${decision.reasonCode}`;
         turn.outbox.push(file.path);
         return { result: toolText(`${basename4(file.path)} will be sent with your reply.`) };
       }, "send_file"),
-      communicate: /* @__PURE__ */ __name(async (args) => ({ result: await communicate(current, turn, args) }), "communicate"),
+      communicate: /* @__PURE__ */ __name(async (args) => ({ result: await communicate(current, turn, args, shape) }), "communicate"),
       // RUN-25 through a tool: the same `ask`, so the same responder, card, expiry, waiting_input and paused deadline;
       // the turn's end or an abort withdraws it, and the call then fails.
       ask_question: /* @__PURE__ */ __name(async (args) => {
@@ -4213,7 +4331,7 @@ ${decision.reasonCode}`;
       // §12.6: an errand turn reaches its recipient and its origin, and asks only in an origin its report goes to.
       definitions: errand ? [
         TOOLS.no_reply,
-        errandCommunicate("contact" in errand.target),
+        errandCommunicate(errandContact),
         ...errand.reports && cards && offersQuestions ? [TOOLS.ask_question] : []
       ] : [
         TOOLS.no_reply,
@@ -4250,12 +4368,12 @@ ${decision.reasonCode}`;
     }, "call") } };
   }
   __name(bindTools, "bindTools");
-  async function communicate(current, turn, args) {
+  async function communicate(current, turn, args, shape) {
     const errand = turn.errand;
     const origins = errand ? errand.origin ? [errand.origin.room] : [] : turn.contexts.flatMap((record) => record.origin ? [record.origin] : []);
     let command;
     try {
-      command = parseCommunicateToolInput(args);
+      command = parseCommunicateToolInput(args, shape);
     } catch (error) {
       return toolText(`Invalid communicate arguments: ${error instanceof Error ? error.message : String(error)}`, true);
     }
@@ -4462,7 +4580,9 @@ ${JSON.stringify(result, null, 2)}`);
   async function stopOutput(record) {
     let queued2 = 0;
     for (const [index, { messageId }] of encryptedMessages(record.mls, record.text, record.options, record).entries()) {
-      const status = (await endpoint.getOperation(encryptedOperation(record.mls, messageId)))?.status;
+      let operation = await endpoint.getOperation(encryptedOperation(record.mls, messageId));
+      while (operation?.resentAs) operation = await endpoint.getOperation(operation.resentAs);
+      const status = operation?.status;
       if (status && status !== "succeeded" && status !== "rejected") queued2 = index + 1;
     }
     const { items: _items, errand: _errand, ...rest } = record;
@@ -4470,13 +4590,14 @@ ${JSON.stringify(result, null, 2)}`);
     else await endpoint.finishCompletion(record.turnId);
   }
   __name(stopOutput, "stopOutput");
+  const publicationGuard = /* @__PURE__ */ __name((audience) => ({ automaticResend }) => (automaticResend ? authorize() : assertAudience(audience)).then(() => true, (error) => {
+    if (audienceChanged(error)) throw error;
+    return false;
+  }), "publicationGuard");
   async function sendEncrypted(audience, messageId, text3, signal, replyAuthority) {
     const operationId = encryptedOperation(audience, messageId);
     if (!guards.has(operationId)) {
-      guards.set(operationId, endpoint.registerDeliveryGuard(operationId, () => assertAudience(audience).then(() => true, (error) => {
-        if (audienceChanged(error)) throw error;
-        return false;
-      })));
+      guards.set(operationId, endpoint.registerDeliveryGuard(operationId, publicationGuard(audience)));
     }
     if (!await endpoint.getOperation(operationId)) await assertAudience(audience);
     signal?.throwIfAborted();
@@ -4516,7 +4637,7 @@ ${JSON.stringify(result, null, 2)}`);
   async function sendEncryptedItems(audience, items, signal) {
     if (!items.length) return;
     const media = await client.getFileMediaPipeline(options.fetch);
-    const sendOptions = { signal, beforePublish: /* @__PURE__ */ __name(() => assertAudience(audience).then(() => true), "beforePublish") };
+    const sendOptions = { signal, beforePublish: publicationGuard(audience) };
     for (const item of items) {
       signal?.throwIfAborted();
       try {
@@ -4599,7 +4720,7 @@ ${JSON.stringify(result, null, 2)}`);
       session: turn.session,
       // §12.6: an errand turn's prompt is its errand; the owner's message is only its input's record.
       prompt: turn.errand ? errandPrompt(turn.errand) : [
-        ...turn.facts ? [...factsPrompt(turn.facts, kind), ""] : [],
+        ...turn.facts ? [...factsPrompt(turn.facts, kind, displayName), ""] : [],
         ...turn.notes.flatMap((note) => [NOTE_OPEN, defused(note.text), NOTE_CLOSE, ""]),
         ...turn.contexts.flatMap((record) => [...contextPrompt(record), ""]),
         ...history.length ? ["Earlier in this conversation (context, not new requests):", ...history.map((message2) => line(message2)), "", "New messages:"] : turn.facts || turn.notes.length || turn.contexts.length ? ["New messages:"] : [],
@@ -5073,7 +5194,7 @@ ${JSON.stringify(result, null, 2)}`);
     ...record.origin ? { origin: record.origin } : {}
   }), "errandFacts");
   function errandPrompt({ record, target, origin, reports }) {
-    const recipient = "contact" in target ? `${target.contact}. Start a new conversation with them: communicate start_conversation.` : `the encrypted conversation ${target.room}. Send to it with communicate message_existing.`;
+    const recipient = "contact" in target ? `${target.contact}. Start a new conversation with them: communicate start_conversation. If they are an agent, address them with @${target.contact} (their exact agent id): an agent's message reaches another only if it mentions it.` : `the encrypted conversation ${target.room}. Send to it with communicate message_existing. An agent's message reaches another agent there only if it mentions it, as @ and its exact agent id.`;
     const report = reports ? `your final answer is your report to your owner, posted in the conversation ${origin.room}.` : "your final answer is your report to your owner, and it stays on their machine.";
     return [
       `${ERRAND_OPEN} Your owner sends you on an errand, from the machine you run on. It is not a message in any conversation, and no one else sees it.`,
@@ -5283,7 +5404,10 @@ ${JSON.stringify(result, null, 2)}`);
       const known = rooms.get(data.conversationId);
       if (known && Array.isArray(merged.memberIds) && !merged.memberIds.includes(agentId)) loseMembership(known);
     }
-    if (mlsOn && (encrypted || Array.isArray(changes?.memberIds))) await checkAudience(rooms.get(data.conversationId));
+    if (mlsOn && (encrypted || Array.isArray(changes?.memberIds))) {
+      await checkAudience(rooms.get(data.conversationId));
+      await noteAdmission(data.conversationId).catch(warn("room admission"));
+    }
     if (encrypted) mlsAsks?.wake(data.conversationId);
   }
   __name(onRoomChanged, "onRoomChanged");
@@ -5393,9 +5517,12 @@ ${JSON.stringify(result, null, 2)}`);
         environmentId: connection.environmentId,
         streamUrl: connection.streamUrl,
         stateDirectory: join8(home, "endpoint"),
-        ...options.client ? { client: options.client } : {},
+        ...options.client ?? RUNNER_CLIENT ? { client: options.client ?? RUNNER_CLIENT } : {},
         // Below Canon's client floor nothing can work, wherever the refusal surfaces: a query, an operation or the stream.
         ...options.onFatal ? { onClientUpdateRequired: /* @__PURE__ */ __name((error) => options.onFatal(error), "onClientUpdateRequired") } : {},
+        // The runner is the agent's home; Canon's relay is the connector home under its own installation.
+        claimHome: true,
+        ...options.takeOver ? { takeOver: true } : {},
         ...options.installationId ? { installationId: options.installationId } : {},
         ...mls ? { mlsDev: { configuration: mls.configuration, custody: mls.custody } } : {},
         ...options.endpoint ? { endpoint: options.endpoint } : {},
@@ -5410,6 +5537,7 @@ ${JSON.stringify(result, null, 2)}`);
       }
       agentId = identity.principalId;
       ownershipVersion = identity.ownershipVersion;
+      installationId = identity.installationId;
       if (options.wake !== void 0) await client.configureWake(options.wake);
       mlsOn = !!(endpoint.mlsDevDevice && endpoint.mlsDevGroups);
       if (!mlsOn && (await endpoint.capabilities().catch(() => null))?.mls?.roomMode === "default") {
@@ -5488,6 +5616,7 @@ ${JSON.stringify(result, null, 2)}`);
         families: ["messages", "contacts", "runtime_turn"],
         onConnected: /* @__PURE__ */ __name(() => {
           heartbeat?.connect();
+          if (mlsOn) void noteAdmissions().catch(warn("room admission"));
           if (reconnect) {
             for (const target of rooms.values()) if (target.turn) scheduleControl(target);
           }
@@ -5761,6 +5890,7 @@ export {
   readRelayCredential,
   writeRelayCredential,
   relayRunnerHome,
+  RUNNER_CLIENT,
   runtimeDescriptor,
   createRunner,
   parseWakeConfiguration,