@runuai/host 0.9.6 → 0.9.7

package/db/migrations/0012_agent_session_attach_key.sql

@@ -0,0 +1,4 @@
+-- Durable runners otherwise attach by task + agent alone. Persist the
+-- host-owned launch-policy generation so a rolling policy/tool transition can
+-- replace an incompatible live runner instead of silently inheriting it.
+ALTER TABLE `host_agent_sessions` ADD `attach_compatibility_key` text;

package/db/migrations/meta/_journal.json

@@ -85,6 +85,13 @@
       "when": 1779900012000,
       "tag": "0011_codex_thread_id",
       "breakpoints": true
+    },
+    {
+      "idx": 12,
+      "version": "6",
+      "when": 1779900013000,
+      "tag": "0012_agent_session_attach_key",
+      "breakpoints": true
     }
   ]
-}
+}

package/db/schema.ts

@@ -140,6 +140,10 @@ export const hostAgentSessions = sqliteTable(
     sessionDir: text("session_dir").notNull(),
     containerName: text("container_name").notNull(),
     kind: text("kind").notNull(), // "claude" | "codex" | ...
+    // Attach only when the process was launched under the same host-owned
+    // policy generation. Null preserves legacy attach behavior for ordinary
+    // agents; Secretary transitions use an explicit key.
+    attachCompatibilityKey: text("attach_compatibility_key"),
     outboxOffset: integer("outbox_offset", { mode: "number" })
       .notNull()
       .default(0),

package/lib/agent-cli.ts

@@ -66,15 +66,23 @@ export function apiUrlFromCloudUrl(cloudUrl: string | undefined): string | null
  * Write the CLI script + shared config (apiUrl only — NO token) into the task
  * workspace. Each agent's OWN token is injected per-agent via its docker exec
  * env (agentCliEnv), so no shared file ever holds a token. Best-effort +
- * idempotent. No-op (false) if there's no api url or the roster has zero
- * permissions — nothing the CLI could do.
+ * idempotent. No-op (false) if there's no api url, or if the roster has zero
+ * permissions and the task has no permissionless role action (Secretary
+ * dispatch). The latter is explicit rather than globally minting empty-power
+ * tokens for every task.
  */
 export function writeAgentCli(
   taskId: string,
   roster: RosterAgent[],
   apiUrl: string | null,
+  allowPermissionless = false,
 ): boolean {
-  if (!apiUrl || rosterPermissions(roster).length === 0) return false;
+  if (
+    !apiUrl ||
+    (rosterPermissions(roster).length === 0 && !allowPermissionless)
+  ) {
+    return false;
+  }
   try {
     const dir = resolve(taskWorkspaceDir(taskId), ".uai");
     mkdirSync(dir, { recursive: true });
@@ -95,8 +103,10 @@ export function writeAgentCli(
 /**
  * Per-agent env for the `docker exec` that spawns one agent (ADR-048): its OWN
  * task token (carrying only ITS permissions) + the API url. Empty when the agent
- * has no permissions (or no owner/url) — its `uai` CLI then reports "not
- * available" rather than borrowing anyone else's powers.
+ * has no permissions (or no owner/url) — unless `allowPermissionless` is set
+ * for the designated Secretary, whose dispatch route is role-gated rather than
+ * permission-gated. That token still carries an empty permission set and
+ * cannot borrow anyone else's powers.
  */
 export function agentCliEnv(
   taskId: string,
@@ -104,9 +114,17 @@ export function agentCliEnv(
   ownerUserId: string | null,
   apiUrl: string | null,
   cliSecret: string | null,
+  allowPermissionless = false,
 ): Record<string, string> {
   const permissions = agent.permissions ?? [];
-  if (!ownerUserId || !apiUrl || !cliSecret || permissions.length === 0) return {};
+  if (
+    !ownerUserId ||
+    !apiUrl ||
+    !cliSecret ||
+    (permissions.length === 0 && !allowPermissionless)
+  ) {
+    return {};
+  }
   return {
     UAI_TASK_TOKEN: signTaskToken(
       { taskId, userId: ownerUserId, permissions, agentId: agent.id },
@@ -121,7 +139,7 @@ export function agentCliEnv(
 // file with no dependencies (Node 22 in the image provides global fetch).
 // ---------------------------------------------------------------------------
 
-const CLI_SOURCE = `#!/usr/bin/env node
+export const CLI_SOURCE = `#!/usr/bin/env node
 // uai — in-task agent CLI (ADR-048). Talks to the cloud agent API as the task.
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
@@ -171,6 +189,30 @@ const [group, action, ...rest] = argv;
 const { flags, rest: pos } = parseFlags(rest);
 
 async function main() {
+  if (group === "dispatch") {
+    const args = [action, ...rest].filter((value) => typeof value === "string");
+    const recipientArgs = [];
+    while (args.length && /^@[A-Za-z0-9_-]+$/.test(args[0])) {
+      recipientArgs.push(args.shift().slice(1));
+    }
+    const instruction = args.join(" ").trim();
+    if (!recipientArgs.length || !instruction) {
+      console.error('uai: dispatch needs one or more @agent ids and a quoted instruction');
+      process.exit(1);
+    }
+    const result = await api("POST", "/api/agent/dispatch", {
+      to: recipientArgs,
+      instruction,
+    });
+    out("dispatched to " + result.recipients.map((id) => "@" + id).join(", "));
+    if (Array.isArray(result.failedRecipients) && result.failedRecipients.length) {
+      console.error(
+        "uai: could not wake " +
+          result.failedRecipients.map((id) => "@" + id).join(", "),
+      );
+    }
+    return;
+  }
   const key = group + " " + (action || "");
   switch (key) {
     case "projects list": out((await api("GET", "/api/agent/projects")).projects); break;
@@ -298,6 +340,7 @@ async function main() {
         "  uai task search <query>            (your own past tasks)",
         "  uai task history                   (list your past tasks)",
         "  uai task read <taskId>             (full chat of a past task you were on)",
+        '  uai dispatch @agent [@agent…] "instruction"   (Secretary only)',
         "  uai react <heart|check|x> [--msg #id]   (no --msg = the message you were last handed)",
         "  uai whoami",
       ].join("\\n"));

package/lib/agents/claude.ts

@@ -24,6 +24,16 @@ import { newId } from "../ulid";
 import { createAgentTransport, type LineTransport } from "./transport";
 import { isRateLimitMessage } from "./rate-limit";
 import { register } from "./registry";
+import {
+  DISPATCH_INPUT_SCHEMA,
+  DISPATCH_RECIPIENT_ID_PATTERN,
+  DISPATCH_TOOL_NAME,
+  MAX_DISPATCH_INSTRUCTION_CHARS,
+  MAX_DISPATCH_RECIPIENT_ID_CHARS,
+  MAX_DISPATCH_RECIPIENTS,
+  parseDispatchInput,
+  type DispatchInput,
+} from "./dispatch";
 import { extractResultUsage } from "./usage";
 import type {
   AgentEvent,
@@ -59,6 +69,156 @@ const CLAUDE_DEFAULT_EFFORT = "high";
 const CLAUDE_COMMUNICATOR_MODEL = "haiku";
 const CLAUDE_COMMUNICATOR_EFFORT = "low";
 
+/**
+ * ADR-083's one host-owned communicator tool. The server is deliberately
+ * dependency-free and rides in the adapter argv so an updated host can add it
+ * to an already-built task image. It performs no routing itself: Claude's
+ * structured tool_use block is the durable runner output, and ClaudeSession
+ * correlates its successful tool_result into the typed AgentEvent the
+ * orchestrator forwards.
+ *
+ * Keeping the MCP server a constant also keeps the strict config independent
+ * of project/user MCP files. The communicator gets exactly this server, never
+ * the task's arbitrary extension set.
+ */
+export const CLAUDE_DISPATCH_TOOL = `mcp__uai__${DISPATCH_TOOL_NAME}`;
+
+export const CLAUDE_DISPATCH_MCP_SOURCE = String.raw`
+import { createInterface } from "node:readline";
+
+const RECIPIENT_ID = new RegExp(${JSON.stringify(DISPATCH_RECIPIENT_ID_PATTERN)});
+
+const TOOL = {
+  name: "dispatch",
+  title: "Dispatch work to Uai crew agents",
+  description:
+    "Send one concrete instruction to one or more Uai crew agents. Use this instead of naming agents in prose; prose stays in the normal human-facing lane.",
+  inputSchema: ${JSON.stringify(DISPATCH_INPUT_SCHEMA)},
+};
+
+const write = (value) => process.stdout.write(JSON.stringify(value) + "\n");
+const ok = (id, result) => write({ jsonrpc: "2.0", id, result });
+const fail = (id, code, message) =>
+  write({ jsonrpc: "2.0", id, error: { code, message } });
+const validArguments = (value) =>
+  value &&
+  typeof value === "object" &&
+  !Array.isArray(value) &&
+  Array.isArray(value.recipients) &&
+  value.recipients.length > 0 &&
+  value.recipients.length <= ${MAX_DISPATCH_RECIPIENTS} &&
+  value.recipients.every(
+    (recipient) =>
+      typeof recipient === "string" &&
+      recipient.length <= ${MAX_DISPATCH_RECIPIENT_ID_CHARS} &&
+      RECIPIENT_ID.test(recipient),
+  ) &&
+  new Set(value.recipients).size === value.recipients.length &&
+  typeof value.instruction === "string" &&
+  value.instruction.trim().length > 0 &&
+  value.instruction.length <= ${MAX_DISPATCH_INSTRUCTION_CHARS};
+
+createInterface({ input: process.stdin, crlfDelay: Infinity }).on(
+  "line",
+  (line) => {
+    let message;
+    try {
+      message = JSON.parse(line);
+    } catch {
+      return;
+    }
+    if (!message || typeof message !== "object" || !("id" in message)) return;
+    if (message.method === "initialize") {
+      ok(message.id, {
+        protocolVersion: message.params?.protocolVersion ?? "2025-06-18",
+        capabilities: { tools: {} },
+        serverInfo: { name: "uai-dispatch", version: "1" },
+      });
+      return;
+    }
+    if (message.method === "ping") {
+      ok(message.id, {});
+      return;
+    }
+    if (message.method === "tools/list") {
+      ok(message.id, { tools: [TOOL] });
+      return;
+    }
+    if (message.method === "tools/call") {
+      if (
+        message.params?.name !== "dispatch" ||
+        !validArguments(message.params?.arguments)
+      ) {
+        ok(message.id, {
+          content: [{ type: "text", text: "Dispatch rejected: provide 1-${MAX_DISPATCH_RECIPIENTS} unique recipient ids and a non-empty instruction." }],
+          isError: true,
+        });
+        return;
+      }
+      ok(message.id, {
+        content: [{ type: "text", text: "Dispatch request accepted by the host; Uai will validate recipients and delivery." }],
+      });
+      return;
+    }
+    fail(message.id, -32601, "Method not found");
+  },
+);
+`;
+
+const CLAUDE_DISPATCH_MCP_CONFIG = JSON.stringify({
+  mcpServers: {
+    uai: {
+      command: "node",
+      args: ["--input-type=module", "--eval", CLAUDE_DISPATCH_MCP_SOURCE],
+      // The trusted bridge needs no task/provider credentials. Override the
+      // secrets the host intentionally forwards to Claude instead of enabling
+      // Claude's global subprocess scrub, which hard-requires bubblewrap and
+      // makes the CLI abort in existing task images that do not contain it.
+      env: {
+        CLAUDE_CODE_OAUTH_TOKEN: "",
+        ANTHROPIC_API_KEY: "",
+        ANTHROPIC_AUTH_TOKEN: "",
+        UAI_TASK_TOKEN: "",
+      },
+      // Claude defers MCP schemas by default. Dispatch is a core action named
+      // in the preamble, so it must be connected and visible on prompt one.
+      alwaysLoad: true,
+    },
+  },
+});
+
+const CLAUDE_COMMUNICATOR_SETTINGS = JSON.stringify({
+  disableAllHooks: true,
+  enabledPlugins: {},
+});
+
+/**
+ * `--safe-mode` cannot be used here: Claude 2.1.220 disables even an explicit
+ * `--mcp-config` in safe mode, which makes the host-owned dispatch tool
+ * disappear. Recreate the customization lockdown while leaving that one
+ * strict MCP server available. These values override any agent/account env.
+ */
+const CLAUDE_COMMUNICATOR_ENV: Record<string, string> = {
+  CLAUDE_CODE_DISABLE_AUTO_MEMORY: "1",
+  CLAUDE_CODE_DISABLE_BUNDLED_SKILLS: "1",
+  CLAUDE_CODE_DISABLE_CLAUDE_MDS: "1",
+  CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL: "1",
+  CLAUDE_CODE_DISABLE_POLICY_SKILLS: "1",
+  CLAUDE_CODE_DISABLE_WORKFLOWS: "1",
+  CLAUDE_CODE_SKIP_PLUGIN_MCP_SERVERS: "1",
+  CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS: "1",
+  ENABLE_CLAUDEAI_MCP_SERVERS: "false",
+  // Some hosts export this globally. Claude's current implementation aborts
+  // when it is enabled but the task image has no bubblewrap binary.
+  CLAUDE_CODE_SUBPROCESS_ENV_SCRUB: "",
+  // The enforced profile dispatches through its host-owned MCP event, not the
+  // task CLI. Keep the bearer token and API origin out of the Claude process
+  // itself (not merely its MCP child), where Read could otherwise inspect
+  // /proc/self/environ and recover a permission-null task credential.
+  UAI_TASK_TOKEN: "",
+  UAI_API_URL: "",
+};
+
 // ---------------------------------------------------------------------------
 // Pure protocol mapping — stream-json line → AgentEvent[].
 // ---------------------------------------------------------------------------
@@ -68,6 +228,15 @@ function isObj(v: unknown): v is Record<string, unknown> {
   return typeof v === "object" && v !== null;
 }
 
+function parseLineObject(raw: string): Record<string, unknown> | null {
+  try {
+    const value: unknown = JSON.parse(raw);
+    return isObj(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Map one stream-json stdout line to zero or more AgentEvents.
  *
@@ -82,13 +251,8 @@ function isObj(v: unknown): v is Record<string, unknown> {
  * side-effect free.
  */
 export function mapClaudeLine(raw: string): AgentEvent[] {
-  let json: unknown;
-  try {
-    json = JSON.parse(raw);
-  } catch {
-    return [];
-  }
-  if (!isObj(json)) return [];
+  const json = parseLineObject(raw);
+  if (!json) return [];
 
   const type = json.type;
 
@@ -114,6 +278,12 @@ export function mapClaudeLine(raw: string): AgentEvent[] {
     for (const block of content) {
       if (isObj(block) && block.type === "tool_use") {
         const name = typeof block.name === "string" ? block.name : "tool";
+        if (name === CLAUDE_DISPATCH_TOOL) {
+          // Dispatch is intentionally absent here. Claude emits this assistant
+          // block before it calls the MCP server; ClaudeSession correlates the
+          // later tool_result and emits only after the call succeeds.
+          continue;
+        }
         out.push({
           type: "tool_call",
           id: typeof block.id === "string" ? block.id : newId(),
@@ -221,24 +391,29 @@ const CLAUDE_FULL_ACCESS_ARGS = [
 
 /**
  * ADR-083 communicator profile. This is deliberately an engine-level tool
- * boundary, not prompt advice: safe mode suppresses project/user extensions,
- * the explicit tool set contains no shell or mutation primitive, `dontAsk`
- * denies anything outside it in headless mode, and the empty strict MCP config
- * prevents a user-installed server from reintroducing a write/deploy tool.
+ * boundary, not prompt advice: setting sources, hooks, skills, workflows and
+ * plug-in MCP are suppressed; the explicit tool set contains no shell or
+ * mutation primitive; `dontAsk` denies anything outside it; and strict MCP
+ * exposes only Uai's host-owned dispatch tool.
  */
 const CLAUDE_COMMUNICATOR_ARGS = [
   ...CLAUDE_BASE_ARGS,
-  "--safe-mode",
+  "--setting-sources",
+  "",
+  "--settings",
+  CLAUDE_COMMUNICATOR_SETTINGS,
   "--disable-slash-commands",
   "--no-chrome",
   "--permission-mode",
   "dontAsk",
   "--tools",
   "Read,Glob,Grep",
+  "--allowedTools",
+  CLAUDE_DISPATCH_TOOL,
   "--disallowedTools",
   "Bash,Edit,Write,NotebookEdit,Agent,Task,WebFetch,WebSearch",
   "--mcp-config",
-  '{"mcpServers":{}}',
+  CLAUDE_DISPATCH_MCP_CONFIG,
   "--strict-mcp-config",
 ];
 
@@ -248,6 +423,8 @@ export class ClaudeSession implements AgentSession {
 
   private readonly proc: LineTransport;
   private readonly handlers = new Set<AgentEventHandler>();
+  private readonly pendingDispatches = new Map<string, DispatchInput>();
+  private readonly settledDispatches = new Set<string>();
   private closed = false;
   // Claude's `total_cost_usd` is CUMULATIVE across the persistent session
   // process (ADR-061 keeps one claude alive across turns), so per-turn cost is
@@ -263,6 +440,7 @@ export class ClaudeSession implements AgentSession {
     containerName: string;
     systemPreamble: string;
     executionProfile?: "communicator";
+    attachCompatibilityKey?: string;
     agentEnv?: Record<string, string>;
   }) {
     this.agentId = args.agent.id;
@@ -308,10 +486,11 @@ export class ClaudeSession implements AgentSession {
     // ADR-061: durable by default — the CLI is owned by an in-container
     // runner and survives host restarts (attach resumes it); legacy pipes
     // behind UAI_DURABLE_SESSIONS=0. Claude is host-side stateless, so a
-    // live runner can be re-attached (allowAttach). The communicator profile
-    // is the exception: attach is keyed only by task + agent identity, not by
-    // execution profile, so a pre-existing full-access runner must be stopped
-    // and replaced rather than inherited across this security boundary.
+    // live runner can be re-attached (allowAttach). A communicator profile is
+    // never attached, and the orchestrator also supplies a persisted policy
+    // compatibility key for normal-tools Secretaries. That second fence makes
+    // the reverse rolling upgrade safe: an old restricted runner cannot be
+    // inherited after the default policy changes back to normal tools.
     this.proc = createAgentTransport({
       taskId: args.taskId,
       agentId: this.agentId,
@@ -319,12 +498,17 @@ export class ClaudeSession implements AgentSession {
       cli: "claude",
       cliArgs,
       passEnv: ["CLAUDE_CODE_OAUTH_TOKEN", "ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN"],
-      explicitEnv: args.agentEnv ?? {},
+      explicitEnv:
+        args.executionProfile === "communicator"
+          ? { ...(args.agentEnv ?? {}), ...CLAUDE_COMMUNICATOR_ENV }
+          : (args.agentEnv ?? {}),
       allowAttach: args.executionProfile !== "communicator",
+      attachCompatibilityKey: args.attachCompatibilityKey,
       kind: "claude",
       debugLabel: `claude:${this.agentId}`,
     });
     this.proc.onLine((line) => {
+      for (const event of this.dispatchEventsForLine(line)) this.emit(event);
       for (const event of mapClaudeLine(line)) this.emit(this.perTurnCost(event));
     });
     this.proc.onExit((code) => {
@@ -349,6 +533,7 @@ export class ClaudeSession implements AgentSession {
               : " — no stderr. Is the claude CLI installed in the task container, and is the container running?"),
         });
       }
+      this.clearDispatches();
       this.closed = true;
       this.emit({ type: "exit", code: code ?? -1 });
     });
@@ -364,6 +549,73 @@ export class ClaudeSession implements AgentSession {
     for (const h of this.handlers) h(event);
   }
 
+  /**
+   * Claude writes an assistant tool_use before invoking MCP, then a user
+   * tool_result carrying the same id. Waking crew on the first line would turn
+   * a rejected or failed tool call into real work, so hold validated input
+   * until the matching result succeeds. The settled set makes replayed output
+   * idempotent for the remainder of the turn.
+   */
+  private dispatchEventsForLine(raw: string): AgentEvent[] {
+    const json = parseLineObject(raw);
+    if (!json) return [];
+
+    if (json.type === "assistant" && isObj(json.message)) {
+      const content = json.message.content;
+      if (!Array.isArray(content)) return [];
+      for (const block of content) {
+        if (
+          !isObj(block) ||
+          block.type !== "tool_use" ||
+          block.name !== CLAUDE_DISPATCH_TOOL ||
+          typeof block.id !== "string" ||
+          this.settledDispatches.has(block.id)
+        ) {
+          continue;
+        }
+        const input = parseDispatchInput(block.input);
+        if (input) this.pendingDispatches.set(block.id, input);
+        else this.pendingDispatches.delete(block.id);
+      }
+      return [];
+    }
+
+    if (json.type === "user" && isObj(json.message)) {
+      const content = json.message.content;
+      if (!Array.isArray(content)) return [];
+      const events: AgentEvent[] = [];
+      for (const block of content) {
+        if (
+          !isObj(block) ||
+          block.type !== "tool_result" ||
+          typeof block.tool_use_id !== "string"
+        ) {
+          continue;
+        }
+        const pending = this.pendingDispatches.get(block.tool_use_id);
+        if (!pending) continue;
+        this.pendingDispatches.delete(block.tool_use_id);
+        this.settledDispatches.add(block.tool_use_id);
+        if (block.is_error !== true) {
+          events.push({
+            type: "dispatch",
+            dispatchId: block.tool_use_id,
+            ...pending,
+          });
+        }
+      }
+      return events;
+    }
+
+    if (json.type === "result") this.clearDispatches();
+    return [];
+  }
+
+  private clearDispatches(): void {
+    this.pendingDispatches.clear();
+    this.settledDispatches.clear();
+  }
+
   /** Convert Claude's cumulative session cost to this turn's delta. Tokens are
    *  already per-turn and pass through untouched. */
   private perTurnCost(event: AgentEvent): AgentEvent {
@@ -424,6 +676,7 @@ export class ClaudeSession implements AgentSession {
       return;
     }
     this.closed = true;
+    this.clearDispatches();
     await this.proc.close();
     this.emit({ type: "exit", code: 0 });
     this.handlers.clear();
@@ -442,7 +695,7 @@ register({
   executionProfiles: [
     {
       id: "communicator",
-      mechanism: "claude-safe-mode-tool-allowlist-v1",
+      mechanism: "claude-explicit-tool-boundary-v2",
       defaultModel: CLAUDE_COMMUNICATOR_MODEL,
       defaultEffort: CLAUDE_COMMUNICATOR_EFFORT,
     },
@@ -461,6 +714,7 @@ register({
     containerName,
     systemPreamble,
     executionProfile,
+    attachCompatibilityKey,
     agentEnv,
   }) =>
     new ClaudeSession({
@@ -469,6 +723,7 @@ register({
       containerName,
       systemPreamble,
       executionProfile,
+      attachCompatibilityKey,
       agentEnv,
     }),
 });

package/lib/agents/dispatch.ts

@@ -0,0 +1,78 @@
+/** Shared typed-dispatch contract for adapters that expose ADR-083's action. */
+
+import {
+  MAX_AGENT_ID_CHARS,
+  MAX_SECRETARY_DISPATCH_INSTRUCTION_CHARS,
+  MAX_SECRETARY_DISPATCH_RECIPIENTS,
+} from "@runuai/host/protocol";
+
+export const DISPATCH_TOOL_NAME = "dispatch";
+export const MAX_DISPATCH_RECIPIENTS = MAX_SECRETARY_DISPATCH_RECIPIENTS;
+export const MAX_DISPATCH_RECIPIENT_ID_CHARS =
+  MAX_AGENT_ID_CHARS;
+export const MAX_DISPATCH_INSTRUCTION_CHARS =
+  MAX_SECRETARY_DISPATCH_INSTRUCTION_CHARS;
+export const DISPATCH_RECIPIENT_ID_PATTERN = "^[A-Za-z0-9_-]+$";
+
+export const DISPATCH_INPUT_SCHEMA = {
+  type: "object",
+  properties: {
+    recipients: {
+      type: "array",
+      minItems: 1,
+      maxItems: MAX_DISPATCH_RECIPIENTS,
+      uniqueItems: true,
+      items: {
+        type: "string",
+        minLength: 1,
+        maxLength: MAX_DISPATCH_RECIPIENT_ID_CHARS,
+        pattern: DISPATCH_RECIPIENT_ID_PATTERN,
+      },
+      description:
+        "Exact @ids of the crew agents that should receive the instruction, without the @ prefix.",
+    },
+    instruction: {
+      type: "string",
+      minLength: 1,
+      maxLength: MAX_DISPATCH_INSTRUCTION_CHARS,
+      description:
+        "Self-contained backstage instruction. Include all context the recipients need; do not include prose meant only for the human.",
+    },
+  },
+  required: ["recipients", "instruction"],
+  additionalProperties: false,
+} as const;
+
+export interface DispatchInput {
+  recipients: string[];
+  instruction: string;
+}
+
+const recipientId = new RegExp(DISPATCH_RECIPIENT_ID_PATTERN);
+
+export function parseDispatchInput(value: unknown): DispatchInput | null {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return null;
+  }
+  const record = value as Record<string, unknown>;
+  const recipients = record.recipients;
+  const instruction = record.instruction;
+  if (
+    !Array.isArray(recipients) ||
+    recipients.length === 0 ||
+    recipients.length > MAX_DISPATCH_RECIPIENTS ||
+    !recipients.every(
+      (recipient): recipient is string =>
+        typeof recipient === "string" &&
+          recipient.length <= MAX_DISPATCH_RECIPIENT_ID_CHARS &&
+          recipientId.test(recipient),
+    ) ||
+    new Set(recipients).size !== recipients.length ||
+    typeof instruction !== "string" ||
+    instruction.trim().length === 0 ||
+    instruction.length > MAX_DISPATCH_INSTRUCTION_CHARS
+  ) {
+    return null;
+  }
+  return { recipients, instruction };
+}

package/lib/agents/mode.ts

@@ -55,3 +55,10 @@ export function resolveAgentMode(
 export function agentMode(): AgentMode {
   return resolveAgentMode().mode;
 }
+
+/** Echo/mock sessions cannot execute the in-task structured-dispatch CLI. */
+export function canAdvertiseTypedSecretaryDispatch(
+  raw: string | undefined = process.env.UAI_AGENTS,
+): boolean {
+  return resolveAgentMode(raw).mode === "real";
+}

package/lib/agents/transport.ts

@@ -59,6 +59,8 @@ export interface AgentTransportOptions {
    * protocol state can't outlive the host process (codex handshake).
    */
   allowAttach: boolean;
+  /** Host-owned launch-policy generation. Both absent remains compatible. */
+  attachCompatibilityKey?: string;
   kind: string;
   debugLabel?: string;
 }
@@ -139,7 +141,14 @@ export function createAgentTransport(opts: AgentTransportOptions): LineTransport
   const tailKey = `${opts.taskId}:${opts.agentId}`;
 
   // ---- Attach: a previous host process left this agent's runner alive. ----
-  if (opts.allowAttach && row && row.status === "running" && heartbeatFresh(row.sessionDir)) {
+  if (
+    opts.allowAttach &&
+    row &&
+    row.status === "running" &&
+    (row.attachCompatibilityKey ?? null) ===
+      (opts.attachCompatibilityKey ?? null) &&
+    heartbeatFresh(row.sessionDir)
+  ) {
     const proc = new DurableProcess({
       hostSessionDir: row.sessionDir,
       initialOutboxOffset: row.outboxOffset,
@@ -233,6 +242,7 @@ export function createAgentTransport(opts: AgentTransportOptions): LineTransport
       sessionDir,
       containerName: opts.containerName,
       kind: opts.kind,
+      attachCompatibilityKey: opts.attachCompatibilityKey ?? null,
       outboxOffset: 0,
       status: "running",
       createdAt: now,
@@ -244,6 +254,7 @@ export function createAgentTransport(opts: AgentTransportOptions): LineTransport
         sessionDir,
         containerName: opts.containerName,
         kind: opts.kind,
+        attachCompatibilityKey: opts.attachCompatibilityKey ?? null,
         outboxOffset: 0,
         status: "running",
         updatedAt: now,