@moondeck/station 0.0.1 → 1.0.1

package/lib/agents/cursor.ts

@@ -0,0 +1,562 @@
+/**
+ * CursorSession — a real AgentSession backed by **Cursor Agent** (`cursor-agent`),
+ * run inside the task environment:
+ *
+ *   CURSOR_API_KEY=… /home/node/.local/bin/cursor-agent -p "<prompt>" \
+ *     --output-format stream-json --stream-partial-output --force --trust \
+ *     --model <model> [--resume <sessionId>]
+ *
+ * One-shot per turn (like Kimi/Grok); sends serialized; continuity via
+ * `--resume <sessionId>` captured from the stream. Cursor's stream-json is
+ * essentially Claude Code's — the RICHEST of the extra engines (streaming text
+ * AND tool cards):
+ *
+ *   {"type":"system","subtype":"init","session_id":…}          → session id
+ *   {"type":"thinking","subtype":"delta"|"completed",…}        → skipped
+ *   {"type":"assistant","message":{content:[{text}]},"timestamp_ms":…}
+ *                                                              → message_delta
+ *   {"type":"tool_call","subtype":"started","call_id","tool_call":{…}}
+ *                                                              → tool_call card
+ *   {"type":"result","subtype":"success"|"error","result",session_id}
+ *                                                              → message_complete + end
+ *
+ * AUTH is a Cursor API key (`CURSOR_API_KEY`) — env-injected at exec, like the
+ * Claude token (no config-dir copy). Cloud never sees it (ADR-015). `-p` runs
+ * headless with `--force` (auto-run tools; the container is the sandbox) and
+ * `--trust` (skip the workspace-trust prompt). Cursor has no system-prompt
+ * flag, so the briefing folds into the first turn's prompt.
+ */
+import { stripVTControlCharacters } from "node:util";
+
+import { ENGINE_ACCOUNT_ENV } from "../credential-consumers/engine-anchor";
+import { requireContainerRuntimeOperational } from "../runtime-guard";
+import type {
+  TaskEnvironmentAgentSessionSurface,
+  TaskEnvironmentSessionRequest,
+} from "../task-environment/types";
+import { newId } from "../ulid";
+import { register } from "./registry";
+import {
+  AGENT_SESSION_OUTPUT_BUFFER_BYTES,
+  spawnEnvironmentProcess,
+  type AgentEnvironmentProcess,
+} from "./proc";
+import {
+  CURSOR_PERIOD_PROBE_TIMEOUT_MS,
+  CURSOR_PERIOD_USAGE_LOG,
+  cursorAccessTokenFromAuthJson,
+  cursorPeriodProbeDue,
+  markCursorPeriodProbed,
+  readCursorAuthFromEnvironment,
+  readCursorPeriodUsage,
+} from "./cursor-period-usage";
+import { rateLimitErrorUsage } from "./rate-limit";
+import { extractResultUsage } from "./usage";
+import type {
+  AgentAccountUsage,
+  AgentEvent,
+  AgentEventHandler,
+  AgentKind,
+  AgentSession,
+  AgentUsage,
+  RosterAgent,
+} from "./types";
+
+const CURSOR_BIN = "/home/node/.local/bin/cursor-agent";
+
+// Cursor replays its captured sandbox environment immediately before it
+// evaluates each shell command. In loader tasks this restore hook is the last
+// step in that replay, so the command sees the current project environment
+// rather than Cursor's stale launch snapshot.
+export const CURSOR_SANDBOX_ENV_RESTORE =
+  ". /usr/local/share/uai/env-hook.sh; __uai_env_sync";
+
+// A curated fallback slice of Cursor's signed-in 2026.10.22 catalog. The
+// newest version of each tier comes first; older known-good ids follow.
+export const CURSOR_MODELS = [
+  "grok-4.7-high",
+  "grok-4.7-high-fast",
+  "composer-2.5",
+  "composer-2.5-fast",
+  "claude-opus-5-5-high",
+  "claude-fable-5-1-thinking-high",
+  "claude-sonnet-5-5-high",
+  "gpt-5.6-sol-high",
+  "gemini-4-argon-high",
+  "kimi-k3-high",
+  "auto",
+  "claude-opus-4-8-thinking-high",
+  "cursor-grok-4.5-high",
+  "claude-fable-5-thinking-high",
+];
+const CURSOR_DEFAULT_MODEL = "grok-4.7-high";
+const CURSOR_EFFORTS: string[] = []; // effort is baked into the model id
+
+// ---------------------------------------------------------------------------
+// Pure protocol mapping.
+// ---------------------------------------------------------------------------
+
+function assistantText(msg: Record<string, unknown>): string {
+  const message = msg.message as { content?: unknown } | undefined;
+  const content = Array.isArray(message?.content) ? message!.content : [];
+  let out = "";
+  for (const raw of content) {
+    const block = raw as { type?: unknown; text?: unknown };
+    if (block.type === "text" && typeof block.text === "string") out += block.text;
+  }
+  return out;
+}
+
+/** "shellToolCall" → "shell", "readFileToolCall" → "readFile". */
+function prettyTool(name: string): string {
+  return name.replace(/ToolCall$/, "") || "tool";
+}
+
+export interface MappedCursorLine {
+  textDelta?: string;
+  toolCall?: { id: string; title: string; detail: string };
+  end?: boolean;
+  finalText?: string;
+  sessionId?: string;
+  errorText?: string;
+  /** This model needs paid Cursor credits; the account itself is still usable. */
+  creditRefusal?: boolean;
+  /** Set when `errorText` is a usage cap. Secret-free; source `error-text`. */
+  accountUsage?: AgentAccountUsage;
+  /** Tokens from the result envelope. Claude-shaped lines carry cost;
+   *  cursor-agent 2026.10.x carries camelCase counts and no cost. */
+  usage?: AgentUsage;
+}
+
+/** Cursor Premium can refuse one paid-credit model while the same account can
+ * still run Cursor's Grok and Composer models. This is not account exhaustion:
+ * keep it non-retryable so the orchestrator neither rotates nor cools the
+ * account, and give the person an actionable model-specific error. */
+export function cursorCreditsRequiredMessage(message: string): string | null {
+  const match = stripVTControlCharacters(message).match(
+    /(?:ActionRequiredError:\s*)?([^\r\n]+?)\s+is not included in your weekly usage\b/i,
+  );
+  const model = match?.[1]?.trim();
+  return model
+    ? `${model} needs Cursor credits on this plan; use a Grok or Composer model`
+    : null;
+}
+
+export function mapCursorLine(line: string, now: number = Date.now()): MappedCursorLine {
+  const t = line.trim();
+  if (!t.startsWith("{")) return {};
+  let m: Record<string, unknown>;
+  try {
+    m = JSON.parse(t) as Record<string, unknown>;
+  } catch {
+    return {};
+  }
+
+  if (m.type === "system") {
+    return typeof m.session_id === "string" ? { sessionId: m.session_id } : {};
+  }
+  if (m.type === "assistant") {
+    // Streaming partials carry timestamp_ms; the final full message (finalized
+    // by `result`) does not — only stream the partials to avoid doubling.
+    if (typeof m.timestamp_ms === "number") {
+      const text = assistantText(m);
+      if (text) return { textDelta: text };
+    }
+    return {};
+  }
+  if (m.type === "tool_call" && m.subtype === "started") {
+    const tc = (m.tool_call ?? {}) as Record<string, unknown>;
+    const [name, spec] = Object.entries(tc)[0] ?? ["tool", {}];
+    const args = ((spec as Record<string, unknown>)?.args ?? {}) as Record<string, unknown>;
+    const pick = args.command ?? args.path ?? args.filePath ?? args.file_path ?? args.query;
+    return {
+      toolCall: {
+        id: typeof m.call_id === "string" ? m.call_id : newId(),
+        title: prettyTool(name),
+        detail: typeof pick === "string" ? pick : "",
+      },
+    };
+  }
+  if (m.type === "result") {
+    const errored = m.is_error === true;
+    const rawErrorText = errored
+      ? typeof m.result === "string"
+        ? m.result
+        : "cursor turn failed"
+      : undefined;
+    const creditError = rawErrorText
+      ? cursorCreditsRequiredMessage(rawErrorText)
+      : null;
+    const errorText = creditError ?? rawErrorText;
+    const accountUsage = errorText ? rateLimitErrorUsage(errorText, now) : null;
+    return {
+      end: true,
+      sessionId: typeof m.session_id === "string" ? m.session_id : undefined,
+      finalText: typeof m.result === "string" ? m.result : undefined,
+      errorText,
+      ...(creditError ? { creditRefusal: true } : {}),
+      ...(accountUsage ? { accountUsage } : {}),
+      usage: extractResultUsage(m),
+    };
+  }
+  // thinking / user / other → nothing.
+  return {};
+}
+
+// ---------------------------------------------------------------------------
+// Session
+// ---------------------------------------------------------------------------
+
+export type Spawner = (
+  request: TaskEnvironmentSessionRequest,
+) => AgentEnvironmentProcess;
+
+export class CursorSession implements AgentSession {
+  readonly agentId: string;
+  readonly kind: AgentKind = "cursor";
+
+  private readonly environment: TaskEnvironmentAgentSessionSurface;
+  private readonly model?: string;
+  private readonly systemPreamble: string;
+  private readonly agentEnv: Record<string, string>;
+  private readonly spawner: Spawner;
+  private readonly apiKey: string;
+  private readonly readAuthFile: (signal: AbortSignal) => Promise<string | null>;
+  private readonly fetchImpl: typeof fetch;
+  private readonly probeTimeoutMs: number;
+
+  private readonly handlers = new Set<AgentEventHandler>();
+  private sessionId: string | null = null;
+  private current: AgentEnvironmentProcess | null = null;
+  private queue: Promise<void> = Promise.resolve();
+  private sentPreamble = false;
+  private closed = false;
+
+  constructor(args: {
+    taskId: string;
+    agent: RosterAgent;
+    environment: TaskEnvironmentAgentSessionSurface;
+    systemPreamble: string;
+    agentEnv?: Record<string, string>;
+    spawner?: Spawner;
+    apiKey?: string;
+    /** Reads the CLI's auth.json from the task environment. Tests inject this.
+     *  The signal aborts when the probe deadline passes; the default reader
+     *  kills the auth process. */
+    readAuthFile?: (signal: AbortSignal) => Promise<string | null>;
+    /** Dashboard fetch. Tests inject this. Production uses the host's fetch. */
+    fetchImpl?: typeof fetch;
+    /** Whole-probe bound, including the auth.json read. Tests shrink it. */
+    probeTimeoutMs?: number;
+  }) {
+    this.agentId = args.agent.id;
+    this.environment = args.environment;
+    this.model = args.agent.model;
+    this.systemPreamble = args.systemPreamble;
+    this.agentEnv = args.agentEnv ?? {};
+    this.spawner =
+      args.spawner ?? ((request) => spawnEnvironmentProcess(this.environment, request));
+    // An account-bound key (ADR-076/ADR-131 D3, injected through agentEnv)
+    // beats the host's own .env.local key — a workspace's Cursor account must
+    // never fall through to the operator's, and on a shared host the ambient
+    // key is usually absent anyway.
+    this.apiKey =
+      args.apiKey ?? this.agentEnv.CURSOR_API_KEY ?? process.env.CURSOR_API_KEY ?? "";
+    this.readAuthFile =
+      args.readAuthFile ?? ((signal) => readCursorAuthFromEnvironment(this.environment, signal));
+    this.fetchImpl = args.fetchImpl ?? fetch;
+    this.probeTimeoutMs = args.probeTimeoutMs ?? CURSOR_PERIOD_PROBE_TIMEOUT_MS;
+  }
+
+  /**
+   * One dashboard probe for a leased account. The read runs after the CLI
+   * child has exited: the CLI rewrites ~/.config/cursor/auth.json at
+   * startup, and a probe overlapped with the turn reads the expired access
+   * token. A missing lease, a probe still inside the five-minute gate, or
+   * any failure sends nothing. The token never leaves this method except
+   * as the bearer of the two dashboard calls.
+   *
+   * The credential is marked before the first await. Two sessions that start
+   * together must not both pass the gate. The returned function is the read;
+   * call it once the child has exited, still before turn_complete.
+   */
+  private probePeriodUsage(): () => Promise<void> {
+    const skip = (): Promise<void> => Promise.resolve();
+    const credentialId = this.agentEnv[ENGINE_ACCOUNT_ENV];
+    if (!credentialId || this.closed) return skip;
+    const now = Date.now();
+    if (!cursorPeriodProbeDue(credentialId, now)) return skip;
+    markCursorPeriodProbed(credentialId, now);
+    return () => this.readPeriodUsage();
+  }
+
+  /** Auth read and both dashboard calls share one deadline. On expiry the
+   *  auth reader is aborted (the default reader kills its process) and this
+   *  promise settles so turn_complete is not held. */
+  private readPeriodUsage(): Promise<void> {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.probeTimeoutMs);
+    let finished = false;
+    const usagePromise = this.collectPeriodUsage(controller.signal);
+    return new Promise((resolve) => {
+      const finish = (usage: AgentAccountUsage | null): void => {
+        if (finished) return;
+        finished = true;
+        clearTimeout(timer);
+        if (!this.closed) {
+          if (!usage) console.warn(CURSOR_PERIOD_USAGE_LOG);
+          else this.emit({ type: "account_usage", usage });
+        }
+        resolve();
+      };
+      controller.signal.addEventListener("abort", () => finish(null));
+      void usagePromise.then(
+        (usage) => finish(controller.signal.aborted ? null : usage),
+        () => finish(null),
+      );
+    });
+  }
+
+  private async collectPeriodUsage(signal: AbortSignal): Promise<AgentAccountUsage | null> {
+    if (signal.aborted) return null;
+    const raw = await this.readAuthFile(signal);
+    if (signal.aborted) return null;
+    const token = raw ? cursorAccessTokenFromAuthJson(raw) : null;
+    if (!token) return null;
+    return readCursorPeriodUsage({
+      token,
+      fetchImpl: this.fetchImpl,
+      signal,
+    });
+  }
+
+  onEvent(handler: AgentEventHandler): () => void {
+    this.handlers.add(handler);
+    return () => this.handlers.delete(handler);
+  }
+
+  private emit(event: AgentEvent): void {
+    if (this.closed && event.type !== "exit") return;
+    for (const h of this.handlers) h(event);
+  }
+
+  async send(text: string): Promise<void> {
+    if (this.closed) return;
+    const turn = this.queue.catch(() => {}).then(() => this.runTurn(text));
+    this.queue = turn;
+    return turn;
+  }
+
+  private buildRequest(prompt: string): TaskEnvironmentSessionRequest {
+    const argv = [
+      CURSOR_BIN,
+      "--disable-auto-update",
+      "-p",
+      prompt,
+      "--output-format",
+      "stream-json",
+      "--stream-partial-output",
+      "--force", // container is the sandbox — auto-run tools
+      "--trust", // skip the workspace-trust prompt in headless
+      "--approve-mcps", // load the gateway MCP servers from ~/.cursor/mcp.json (ADR-057)
+    ];
+    // Long form only: the pinned CLI (2026.08.25) and its successors have no
+    // `-m` short flag and exit on it before the turn starts.
+    if (this.model && this.model !== "auto") argv.push("--model", this.model);
+    if (this.sessionId) argv.push("--resume", this.sessionId);
+    return {
+      argv: argv as [string, ...string[]],
+      projectEnvProfile: "task",
+      user: "node",
+      env: {
+        ...this.agentEnv,
+        CURSOR_API_KEY: this.apiKey,
+        ...(this.environment.descriptor.envMode === "loader"
+          ? { __CURSOR_SANDBOX_ENV_RESTORE: CURSOR_SANDBOX_ENV_RESTORE }
+          : {}),
+      },
+      maxOutputBytes: AGENT_SESSION_OUTPUT_BUFFER_BYTES,
+    };
+  }
+
+  private async runTurn(text: string): Promise<void> {
+    if (this.closed) return;
+    requireContainerRuntimeOperational();
+    // No system-prompt flag — fold the briefing into the first turn; later
+    // turns carry it via the resumed session.
+    const prompt =
+      !this.sentPreamble && this.systemPreamble.trim().length > 0
+        ? `${this.systemPreamble}\n\n---\n\n${text}`
+        : text;
+    this.sentPreamble = true;
+
+    const child = this.spawner(this.buildRequest(prompt));
+    this.current = child;
+    // Mark the gate now, before the child-exit await. The read itself waits
+    // until the CLI has rewritten auth.json.
+    const periodUsage = this.probePeriodUsage();
+
+    let acc = "";
+    let sawText = false;
+    let buf = "";
+    // Usage rides the result line but turn_complete fires on process exit;
+    // capture it here and attach it below (ADR-071 metering).
+    let turnUsage: AgentUsage | undefined;
+    // A result line that already explained the failure owns the error. The
+    // exit path must not add a second "cursor exited N" for the same turn.
+    // A usage cap is tracked on its own: a generic JSON error must not hide
+    // a cap that only shows up on stderr.
+    let sawError = false;
+    let reportedRateLimit = false;
+    let reportedCreditRefusal = false;
+    const consume = (chunk: string): void => {
+      buf += chunk;
+      let nl: number;
+      while ((nl = buf.indexOf("\n")) >= 0) {
+        const line = buf.slice(0, nl);
+        buf = buf.slice(nl + 1);
+        const m = mapCursorLine(line);
+        if (m.sessionId) this.sessionId = m.sessionId;
+        if (typeof m.textDelta === "string") {
+          // Cursor (--stream-partial-output) streams incremental token deltas
+          // and then a REDUNDANT full-message snapshot. The timestamp_ms
+          // heuristic in mapCursorLine drops that final snapshot for models
+          // whose final line is untagged — but Cursor's multi-model support
+          // (ADR-068) means SOME models tag the final full snapshot with
+          // timestamp_ms too, so it slips through and gets appended on top of
+          // the tokens: every message doubled (live 2026-07-21). Reconcile
+          // against what we've already streamed instead of trusting the tag —
+          // robust to incremental tokens, cumulative snapshots, and the
+          // redundant final repeat alike.
+          const t = m.textDelta;
+          let delta: string | null;
+          if (t === acc) {
+            delta = null; // full-message snapshot we've already emitted
+          } else if (acc.length > 0 && t.startsWith(acc)) {
+            delta = t.slice(acc.length); // cumulative snapshot → growth only
+            acc = t;
+          } else {
+            delta = t; // incremental token / genuinely new text
+            acc += t;
+          }
+          if (delta) {
+            sawText = true;
+            this.emit({ type: "message_delta", text: delta });
+          }
+        }
+        if (m.toolCall) {
+          this.emit({
+            type: "tool_call",
+            id: m.toolCall.id,
+            title: m.toolCall.title,
+            detail: m.toolCall.detail,
+          });
+        }
+        if (m.end) {
+          if (m.usage) turnUsage = m.usage;
+          if (m.errorText) {
+            sawError = true;
+            if (m.creditRefusal) reportedCreditRefusal = true;
+            if (m.accountUsage) {
+              reportedRateLimit = true;
+              this.emit({ type: "account_usage", usage: m.accountUsage });
+              this.emit({
+                type: "error",
+                message: m.errorText,
+                retryable: "rate_limit",
+                ...(m.accountUsage.resetsAt === undefined
+                  ? {}
+                  : { resetsAt: m.accountUsage.resetsAt }),
+              });
+            } else {
+              this.emit({ type: "error", message: m.errorText });
+            }
+          }
+          const finalText = m.finalText ?? acc;
+          if (sawText || finalText) {
+            this.emit({ type: "message_complete", text: finalText });
+          }
+        }
+      }
+    };
+    child.stdout?.on("data", (b: Buffer) => consume(b.toString("utf8")));
+    let stderr = "";
+    child.stderr?.on("data", (b: Buffer) => {
+      stderr += b.toString("utf8");
+    });
+
+    await new Promise<void>((resolve) => {
+      const finish = (code: number | null, spawnErr?: string): void => {
+        this.current = null;
+        if (buf.trim().length > 0) consume("\n");
+        if (this.closed) return resolve();
+        if (spawnErr) {
+          this.emit({ type: "error", message: `cursor spawn failed: ${spawnErr}` });
+        } else if (code !== 0) {
+          // Some cursor-agent errors (e.g. an invalid key) are coloured; strip
+          // the escape codes so the cap check and the error a human sees are
+          // plain text. A generic result error must not skip this check.
+          const plain = stripVTControlCharacters(stderr);
+          const tail = plain.trim().slice(-500);
+          const creditRefusal = cursorCreditsRequiredMessage(plain);
+          const message =
+            creditRefusal ??
+            `cursor exited ${code ?? "null"}${tail ? `: ${tail}` : ""}`;
+          const accountUsage = reportedRateLimit ? undefined : rateLimitErrorUsage(plain);
+          if (accountUsage) {
+            this.emit({ type: "account_usage", usage: accountUsage });
+          }
+          if (!sawError || (creditRefusal && !reportedCreditRefusal)) {
+            if (accountUsage) {
+              this.emit({
+                type: "error",
+                message,
+                retryable: "rate_limit",
+                ...(accountUsage.resetsAt === undefined
+                  ? {}
+                  : { resetsAt: accountUsage.resetsAt }),
+              });
+            } else {
+              this.emit({ type: "error", message });
+            }
+          }
+        }
+        resolve();
+      };
+      child.on("exit", (code) => finish(code));
+      child.on("error", (err) => finish(null, err.message));
+    });
+    await periodUsage();
+    if (!this.closed) this.emit({ type: "turn_complete", usage: turnUsage });
+  }
+
+  async interrupt(): Promise<void> {
+    this.current?.kill("SIGKILL");
+  }
+
+  async resolvePermission(): Promise<void> {
+    /* --force auto-approves; no permission requests are emitted */
+  }
+
+  async close(): Promise<void> {
+    if (this.closed) return;
+    this.closed = true;
+    this.current?.kill("SIGKILL");
+    this.current = null;
+    this.emit({ type: "exit", code: 0 });
+    this.handlers.clear();
+  }
+}
+
+register({
+  kind: "cursor",
+  label: "Cursor",
+  supportedModels: () => [...CURSOR_MODELS],
+  defaultModel: CURSOR_DEFAULT_MODEL,
+  supportedEfforts: () => [...CURSOR_EFFORTS],
+  // Gated on a Cursor API key in the host env (loaded from .env.local); the
+  // adapter injects it into the container. No key → engine not advertised.
+  available: () => Boolean(process.env.CURSOR_API_KEY),
+  create: async ({ taskId, agent, environment, systemPreamble, agentEnv }) =>
+    new CursorSession({ taskId, agent, environment, systemPreamble, 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 "../../src/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 };
+}