@zgeoff/atc 2.12.0 → 2.14.0

package/src/daemon/start-headless-turn.ts

@@ -44,10 +44,10 @@ export function startHeadlessTurn(
       cwd: s.cwd,
       prompt,
       ...(s.agentSessionID === undefined ? {} : { resume: s.agentSessionID }),
-      permissionMode: 'auto',
       sessionID,
       ...(s.model === undefined ? {} : { model: s.model }),
       ...(s.effort === undefined ? {} : { effort: s.effort }),
+      ...(s.withheldEnv.length === 0 ? {} : { withheldEnv: s.withheldEnv }),
     },
     {
       onOutput: (text) => {

package/src/daemon/start-session-bridge.ts

@@ -0,0 +1,294 @@
+import { z } from 'zod';
+import type { EventMsg } from '../protocol/protocol';
+import type { MessageID } from '../shared/message-id';
+import type { SessionID } from '../shared/session-id';
+import { toMessageID } from '../shared/to-message-id';
+import type { MessageRecord } from '../store/message-record';
+import type { TapClient } from './daemon-connection';
+import type { HarnessRelay } from './execution-provider';
+import type { HookEvent } from './hooks';
+import { isBindingCurrent } from './is-binding-current';
+import type { BridgeBinding } from './is-binding-current';
+import { parseHookLine } from './parse-hook-line';
+
+/**
+ * The fields of a live session the bridge checks its binding against and
+ * reads the status from.
+ */
+export interface BridgeSession {
+  readonly id: SessionID;
+  readonly target: string;
+  readonly targetIdentity: string;
+  readonly hostKey: SessionID;
+  readonly bridgeEpoch: number;
+  readonly state: string;
+  readonly lastMsg: string;
+}
+
+/**
+ * What the bridge needs from the daemon. Each operation acts on the one
+ * session the caller names, which is always the bridge's own.
+ */
+export interface BridgeContext {
+  readonly findSession: (sessionID: SessionID) => BridgeSession | undefined;
+  readonly applyHookEvent: (e: HookEvent) => void;
+
+  // Applies a report under the id its reporter gave it, and settles once
+  // the report is recorded; false when the payload is no report.
+  readonly applyReport: (
+    sessionID: SessionID,
+    payload: Readonly<Record<string, unknown>>,
+    reportID: string,
+  ) => Promise<boolean>;
+  readonly attachTap: (client: TapClient, sessionID: SessionID) => 'ok' | 'missing' | 'unsupported';
+  readonly ackMessage: (
+    client: TapClient,
+    sessionID: SessionID,
+    messageID: MessageID,
+  ) => Promise<MessageRecord | 'not_tapping' | 'unknown'>;
+  readonly detachTap: (client: TapClient) => void;
+}
+
+const REQUEST_SCHEMA = z.looseObject({ v: z.literal(1), id: z.string().min(1), op: z.string() });
+
+const REPORT_SCHEMA = z.looseObject({
+  reportID: z.string().min(1).max(128),
+  payload: z.record(z.string(), z.unknown()),
+});
+
+const ACK_SCHEMA = z.looseObject({ message: z.string().min(1) });
+
+type BridgeRefusal = 'forbidden' | 'stale_binding' | 'not_tapping' | 'unknown_message';
+
+/**
+ * Serves one connection a remote harness's processes opened to the daemon:
+ * the session bridge. A line without an `op` is a hook line, as the local
+ * reporter socket takes it. A request line `{ v: 1, id, op }` gets one
+ * answer line `{ id, ok }`, and the bridge's own inbox events go out as
+ * protocol event lines.
+ *
+ * The bridge takes hooks, reports, its session's tap and acks, and its
+ * session's own status, for the one session it was bound to and nothing
+ * else: an unknown op, a malformed request, or a report or hook for any
+ * other session answers `forbidden` and closes the connection. Every line
+ * checks the binding against the live session first, and one that no
+ * longer matches answers `stale_binding` and closes.
+ *
+ * Trust: the binding holds no secret. A host serves the bridge's socket
+ * inside itself alone, so reaching the socket is the proof of being inside
+ * that host. One host is one trust domain: a sub-session in its parent's
+ * host runs as the same user and can reach the parent's socket too. The
+ * per-session socket and binding stop processes in the host from crossing
+ * sessions by accident, never a hostile process inside the same host.
+ */
+export function startSessionBridge(
+  relay: HarnessRelay,
+  binding: Readonly<BridgeBinding>,
+  ctx: BridgeContext,
+): void {
+  let closed = false;
+  let writing: Promise<void> = Promise.resolve();
+
+  // Lines go out one at a time, in the order they were written, and none
+  // after the bridge closed.
+  const writeLine = async (value: Readonly<Record<string, unknown>>) => {
+    const line = JSON.stringify(value);
+    const previous = writing;
+
+    writing = (async () => {
+      await previous;
+
+      if (!closed) {
+        try {
+          await relay.writeLine(line);
+        } catch {}
+      }
+    })();
+
+    await writing;
+  };
+
+  const stopBridge = () => {
+    if (closed) {
+      return;
+    }
+
+    closed = true;
+
+    ctx.detachTap(tap);
+    relay.close();
+  };
+
+  // Answers a refusal, then closes once the answer has gone out.
+  const answerRefusal = async (id: string | null, code: BridgeRefusal) => {
+    await writeLine({ id, ok: false, code });
+
+    stopBridge();
+  };
+
+  const tap: TapClient = {
+    sendEvent: (event: EventMsg) => {
+      void (async () => {
+        await writeLine(event);
+
+        if (event.ev === 'InboxClosed') {
+          stopBridge();
+        }
+      })();
+    },
+  };
+
+  const isCurrent = () => isBindingCurrent(binding, ctx.findSession(binding.sessionID));
+
+  const applyRequest = async (
+    request: Readonly<Record<string, unknown>>,
+    id: string,
+    op: string,
+  ) => {
+    if (op === 'report') {
+      const parsed = REPORT_SCHEMA.safeParse(request);
+
+      if (
+        !parsed.success ||
+        !(await ctx.applyReport(binding.sessionID, parsed.data.payload, parsed.data.reportID))
+      ) {
+        void answerRefusal(id, 'forbidden');
+
+        return;
+      }
+
+      void writeLine({ id, ok: true });
+
+      return;
+    }
+
+    if (op === 'tap.open') {
+      if (ctx.attachTap(tap, binding.sessionID) !== 'ok') {
+        void answerRefusal(id, 'forbidden');
+
+        return;
+      }
+
+      void writeLine({ id, ok: true });
+
+      return;
+    }
+
+    if (op === 'tap.ack') {
+      const parsed = ACK_SCHEMA.safeParse(request);
+
+      if (!parsed.success) {
+        void answerRefusal(id, 'forbidden');
+
+        return;
+      }
+
+      const acked = await ctx.ackMessage(tap, binding.sessionID, toMessageID(parsed.data.message));
+
+      if (acked === 'not_tapping' || acked === 'unknown') {
+        const code: BridgeRefusal = acked === 'unknown' ? 'unknown_message' : 'not_tapping';
+
+        void writeLine({ id, ok: false, code });
+
+        return;
+      }
+
+      void writeLine({ id, ok: true, status: acked.status });
+
+      return;
+    }
+
+    if (op === 'status.read') {
+      const s = ctx.findSession(binding.sessionID);
+
+      void writeLine({ id, ok: true, state: s?.state ?? 'exited', lastMsg: s?.lastMsg ?? '' });
+
+      return;
+    }
+
+    void answerRefusal(id, 'forbidden');
+  };
+
+  // Lines are applied one at a time, in the order they arrived.
+  let applying: Promise<void> = Promise.resolve();
+
+  const applyLine = async (line: string) => {
+    if (closed) {
+      return;
+    }
+
+    let parsed: unknown;
+
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      void answerRefusal(null, 'forbidden');
+
+      return;
+    }
+
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+      void answerRefusal(null, 'forbidden');
+
+      return;
+    }
+
+    const record: Readonly<Record<string, unknown>> = Object.fromEntries(Object.entries(parsed));
+
+    if (!('op' in record)) {
+      const e = parseHookLine(line);
+
+      if (!isCurrent()) {
+        void answerRefusal(null, 'stale_binding');
+
+        return;
+      }
+
+      if (e === null || e.atcId !== binding.sessionID) {
+        void answerRefusal(null, 'forbidden');
+
+        return;
+      }
+
+      ctx.applyHookEvent(e);
+
+      return;
+    }
+
+    const request = REQUEST_SCHEMA.safeParse(record);
+
+    if (!request.success) {
+      const id = typeof record['id'] === 'string' ? record['id'] : null;
+
+      void answerRefusal(id, 'forbidden');
+
+      return;
+    }
+
+    if (!isCurrent()) {
+      void answerRefusal(request.data.id, 'stale_binding');
+
+      return;
+    }
+
+    await applyRequest(record, request.data.id, request.data.op);
+  };
+
+  relay.onLine((line) => {
+    const previous = applying;
+
+    applying = (async () => {
+      await previous;
+
+      try {
+        await applyLine(line);
+      } catch {}
+    })();
+  });
+
+  relay.onClose(() => {
+    closed = true;
+
+    ctx.detachTap(tap);
+  });
+}

package/src/mcp/mcp-tools.ts

@@ -42,6 +42,9 @@ const SPAWN_INPUT: Readonly<Record<string, unknown>> = z.toJSONSchema(
     target: SPAWN_SCHEMA.shape.target.describe(
       'Execution target for the new session, one of the target ids in atc_agents_list. Omit it to run on the default target (spawnDefaults.target). An unknown or unavailable target is refused; atc never runs the session on another target instead.',
     ),
+    workspace: SPAWN_SCHEMA.shape.workspace.describe(
+      "Where the session's working directory comes from. Omit it to run the session in cwd as it stands. With it, atc materializes a clean checkout into cwd on the target, which must not exist yet: {kind:'path', path, allowDirty?} checks out the pushed HEAD of a git checkout on the atc host, refusing uncommitted changes unless allowDirty is 'warn'; {kind:'git', url, ref or sha, credentialRef?} checks out a branch, tag, or full commit of a repository, with credentialRef {kind:'env', name} naming the atc daemon's environment variable that holds its token. A directory outside git runs in place only on a target on the atc host itself (provider local-pty), with cwd equal to its path. Submodules and Git LFS are refused, and so is a URL that carries a credential.",
+    ),
     detached: z
       .boolean()
       .optional()
@@ -112,6 +115,13 @@ const MESSAGE_GET_INPUT: Readonly<Record<string, unknown>> = z.toJSONSchema(
   { io: 'input' },
 );
 
+const REPORT_GET_INPUT: Readonly<Record<string, unknown>> = z.toJSONSchema(
+  z.strictObject({
+    report: z.string().describe("The cursor of the report's event, from atc_events_read"),
+  }),
+  { io: 'input' },
+);
+
 // Output schemas leave further properties open, so a field the daemon adds
 // later never fails a client that validates results against them.
 const MESSAGE_OUTPUT: Readonly<Record<string, unknown>> = {
@@ -274,6 +284,20 @@ const EVENTS_OUTPUT: Readonly<Record<string, unknown>> = {
   required: ['events', 'cursor', 'more'],
 };
 
+const REPORT_OUTPUT: Readonly<Record<string, unknown>> = {
+  type: 'object',
+  properties: {
+    report: { type: 'string' },
+    at: { type: 'number' },
+    session: { type: 'string' },
+    name: { type: ['string', 'null'] },
+    label: { type: 'string' },
+    text: { type: 'string' },
+    complete: { type: 'boolean' },
+  },
+  required: ['report', 'at', 'session', 'name', 'label', 'text', 'complete'],
+};
+
 interface MCPToolAnnotations {
   readonly readOnlyHint: boolean;
   readonly destructiveHint: boolean;
@@ -353,6 +377,7 @@ export const MCP_TOOLS: readonly MCPToolDefinition[] = [
         effort: 'spawn.options',
         idempotencyKey: 'spawn.idempotency',
         target: 'spawn.target',
+        workspace: 'spawn.workspace',
       },
     },
   },
@@ -361,12 +386,15 @@ export const MCP_TOOLS: readonly MCPToolDefinition[] = [
     annotations: AGENT_FACING_DESTRUCTIVE,
     scope: 'spawn',
     description:
-      'Type a line of text into a running session, as if the operator typed it and pressed enter. Use it to answer a session that is waiting on input.',
+      "Type a line of text into a running session and submit it, as if the operator typed it and pressed enter. atc submits the line the way the session's agent accepts one. Use it to answer a session that is waiting on input. A result of sent means atc wrote the line and its submit key to the session; it does not confirm that the agent took the line or answered it. Read the session's screen or events for that. The tool sends no raw keystrokes.",
     inputSchema: {
       type: 'object',
       properties: {
         session: { type: 'string', description: 'The atc session id' },
-        text: { type: 'string', description: 'The line to type; a newline is appended' },
+        text: {
+          type: 'string',
+          description: "The line to submit; atc adds the submit key the session's agent expects",
+        },
       },
       required: ['session', 'text'],
       additionalProperties: false,
@@ -457,11 +485,21 @@ export const MCP_TOOLS: readonly MCPToolDefinition[] = [
     annotations: READ_ONLY,
     scope: 'read',
     description:
-      'Catch up on the fleet: session events (started, prompt-submitted, needs-input, turn-done, ended), message events (message-accepted, message-delivered, message-answered), and reports (report) since a cursor, oldest first, each with the session id and name. A message event carries the message id; read the full message with atc_message_get. A report event carries its label. Without a cursor it returns the most recent events. Pass the returned cursor next time; more is true when the page stopped before the newest event, so read again at once. session limits the read to one session. waitMs holds the call open until an event arrives; pass it instead of polling in a tight loop.',
+      'Catch up on the fleet: session events (started, prompt-submitted, needs-input, turn-done, ended), message events (message-accepted, message-delivered, message-answered), and reports (report) since a cursor, oldest first, each with the session id and name. A message event carries the message id; read the full message with atc_message_get. A report event carries its label and a preview of its text; read the full text with atc_report_get, passing the cursor of that event. Without a cursor it returns the most recent events. Pass the returned cursor next time; more is true when the page stopped before the newest event, so read again at once. session limits the read to one session. waitMs holds the call open until an event arrives; pass it instead of polling in a tight loop.',
     inputSchema: EVENTS_READ_INPUT,
     outputSchema: EVENTS_OUTPUT,
     requires: { output: 'events.more', inputs: { session: 'events.session' } },
   },
+  {
+    name: 'atc_report_get',
+    annotations: READ_ONLY,
+    scope: 'read',
+    description:
+      "Read one report's full text without messaging the session that sent it. Pass the cursor of the report's event from atc_events_read. Returns the report cursor, at, the session id and name, the label, the text (up to 64 KiB, as the session sent it), and complete, which is false for a report recorded before atc kept full texts: its text is then only the preview the event held. A cursor of an event that is not a report answers as an unknown report.",
+    inputSchema: REPORT_GET_INPUT,
+    outputSchema: REPORT_OUTPUT,
+    requires: { tool: 'report.get' },
+  },
   {
     name: 'atc_session_message',
     annotations: AGENT_FACING,

package/src/mcp/reconnecting-caller.ts

@@ -12,6 +12,7 @@ const RETRYABLE_METHODS: ReadonlySet<string> = new Set([
   'dirs.list',
   'events.read',
   'message.get',
+  'report.get',
   'session.get',
   'session.list',
   'session.read',

package/src/mcp/require-daemon-features.ts

@@ -10,11 +10,15 @@ const FEATURE_USES: Readonly<Record<DaemonFeature, string>> = {
   'message.idempotency': "atc_session_message's idempotencyKey",
   'message.turn': "atc_message_get's turn and answeredWith",
   'message.wait': "atc_message_get's waitMs",
+  'session.forget': 'session.forget',
   'session.locator': "a session's locator",
+  'session.submit': 'atc_session_input',
   'spawn.idempotency': "atc_session_spawn's idempotencyKey",
   'spawn.options': "atc_session_spawn's model and effort",
   'spawn.target': "atc_session_spawn's target",
+  'report.get': 'atc_report_get',
   'request.principal': 'the target limits of a remote MCP client',
+  'spawn.workspace': "atc_session_spawn's workspace",
 };
 
 /**

package/src/mcp/run-tool.ts

@@ -46,12 +46,13 @@ export function runTool(
         ...(args['effort'] === undefined ? {} : { effort: args['effort'] }),
         ...(key === undefined ? {} : { idempotencyKey: key }),
         ...(args['target'] === undefined ? {} : { target: args['target'] }),
+        ...(args['workspace'] === undefined ? {} : { workspace: args['workspace'] }),
         cols: 100,
         rows: 30,
       };
 
-      // A model, effort, key, or target needs a daemon that takes them; the check
-      // runs on every connection the spawn rides.
+      // A model, effort, key, target, or workspace needs a daemon that takes
+      // them; the check runs on every connection the spawn rides.
       const optionFeatures: readonly DaemonFeature[] =
         args['model'] === undefined && args['effort'] === undefined ? [] : ['spawn.options'];
 
@@ -60,20 +61,38 @@ export function runTool(
       const targetFeatures: readonly DaemonFeature[] =
         args['target'] === undefined ? [] : ['spawn.target'];
 
-      const required = [...optionFeatures, ...keyFeatures, ...targetFeatures];
+      const workspaceFeatures: readonly DaemonFeature[] =
+        args['workspace'] === undefined ? [] : ['spawn.workspace'];
+
+      const required = [...optionFeatures, ...keyFeatures, ...targetFeatures, ...workspaceFeatures];
 
       const ok =
         nested && ctx.callerSessionID !== null
           ? await sendNestedSpawn(caller, params, ctx.callerSessionID, required)
           : await caller.sendRequest('session.spawn', params, required);
 
-      return buildObjectResult(ok['session']);
+      // A spawn whose workspace left changes behind returns its warnings
+      // beside the session's own fields.
+      const warnings = ok['warnings'];
+
+      const session =
+        warnings === undefined || !isRecord(ok['session'])
+          ? ok['session']
+          : { ...ok['session'], warnings };
+
+      return buildObjectResult(session);
     })
     .with('atc_session_input', async () => {
-      await caller.sendRequest('session.input', {
-        session: args['session'],
-        d: `${typeof args['text'] === 'string' ? args['text'] : ''}\n`,
-      });
+      // An older daemon would take the line as raw input, which some agents
+      // never submit.
+      await caller.sendRequest(
+        'session.submit',
+        {
+          session: args['session'],
+          text: typeof args['text'] === 'string' ? args['text'] : '',
+        },
+        ['session.submit'],
+      );
 
       return { text: 'sent', structured: null };
     })
@@ -153,6 +172,11 @@ export function runTool(
 
       return buildObjectResult(ok);
     })
+    .with('atc_report_get', async () => {
+      const ok = await caller.sendRequest('report.get', { report: args['report'] }, ['report.get']);
+
+      return buildObjectResult(ok);
+    })
     .with('atc_session_message', async () => {
       const given = args['from'];
 

package/src/protocol/daemon-features.ts

@@ -42,6 +42,20 @@ export const DAEMON_FEATURES = [
   // A request takes `as`, the principal it acts as, and `daemon.hello`
   // takes `principal`, the principal the whole connection acts as.
   'request.principal',
+
+  // `session.spawn` takes `workspace`, and a session descriptor holds the
+  // `workspace` its checkout was materialized from.
+  'spawn.workspace',
+
+  // `session.forget` exists, and a kill of a session asleep on a target that
+  // can destroy its host answers `confirmation_required`.
+  'session.forget',
+
+  // `session.submit` exists.
+  'session.submit',
+
+  // `report.get` exists.
+  'report.get',
 ] as const;
 
 export type DaemonFeature = (typeof DAEMON_FEATURES)[number];

package/src/protocol/protocol.ts

@@ -26,6 +26,29 @@ const ERROR_CODES = [
   'target_changed',
   'target_config_invalid',
   'target_forbidden',
+  'not_a_git_repo',
+  'no_commits',
+  'unreadable_tree',
+  'has_submodules',
+  'lfs_unsupported',
+  'workspace_dirty',
+  'no_origin',
+  'invalid_git_url',
+  'unpushed_head',
+  'credential_in_url',
+  'credential_missing',
+  'ref_not_found',
+  'clone_failed',
+  'sanitize_failed',
+  'tar_failed',
+  'workspace_exists',
+  'transfer_failed',
+  'workspace_mismatch',
+  'host_unavailable',
+  'auth_not_configured',
+  'host_leased',
+  'confirmation_required',
+  'confirm_token_invalid',
   'already_answered',
   'too_slow',
   'stale_epoch',

package/src/protocol/request-param-schemas.ts

@@ -23,6 +23,55 @@ const IDEMPOTENCY_KEY = z
   .max(200, 'idempotencyKey must be at most 200 characters')
   .optional();
 
+// A full commit id, SHA-1 or SHA-256.
+const COMMIT_ID = /^(?:[\da-f]{40}|[\da-f]{64})$/u;
+
+// The daemon environment variable a git workspace's token is read from.
+const CREDENTIAL_REF = z.strictObject({
+  kind: z.literal('env'),
+  name: z.string().regex(/^[A-Za-z_]\w*$/u, 'a credentialRef names an environment variable'),
+});
+
+/**
+ * Where a spawn's working directory comes from, materialized as a clean
+ * checkout into the spawn's `cwd` on its execution target. A `path` source
+ * is a directory on the daemon's host, resolved to its origin URL and
+ * pushed HEAD; `allowDirty: 'warn'` resolves a tree with uncommitted
+ * changes to HEAD and leaves the changes behind with a warning. A `git`
+ * source is a repository URL with exactly one of a branch or tag `ref` or
+ * a full commit `sha`, and an optional `credentialRef` naming the daemon
+ * environment variable that holds its token.
+ */
+const WORKSPACE_SOURCE = z.discriminatedUnion('kind', [
+  z.strictObject({
+    kind: z.literal('path'),
+    path: z
+      .string({ error: 'a path workspace requires an absolute path' })
+      .startsWith('/', 'a path workspace requires an absolute path'),
+    allowDirty: z.enum(['refuse', 'warn']).optional(),
+  }),
+  z
+    .strictObject({
+      kind: z.literal('git'),
+      url: z
+        .string({ error: 'a git workspace requires a url' })
+        .min(1, 'a git workspace requires a url')
+        .refine((url) => !url.startsWith('-'), 'a git workspace url must not start with -'),
+      ref: z
+        .string()
+        .min(1, 'a git workspace ref must not be empty')
+        .refine((ref) => !ref.startsWith('-'), 'a git workspace ref must not start with -')
+        .optional(),
+      sha: z.string().regex(COMMIT_ID, 'a git workspace sha is a full commit id').optional(),
+      credentialRef: CREDENTIAL_REF.optional(),
+    })
+    .refine((source) => (source.ref === undefined) !== (source.sha === undefined), {
+      message: 'a git workspace takes exactly one of ref or sha',
+    }),
+]);
+
+export type SpawnWorkspaceSource = z.infer<typeof WORKSPACE_SOURCE>;
+
 // The refusal of a terminal size outside the range a terminal takes.
 const TERMINAL_SIZE_ERROR = 'cols and rows must be whole numbers from 1 to 4096';
 
@@ -75,6 +124,11 @@ export const REQUEST_PARAM_SCHEMAS = {
       .min(1, 'session.spawn target must be a non-empty target id')
       .optional(),
 
+    // Where the session's working directory comes from: absent runs the
+    // session in cwd as it stands, and a source materializes a clean
+    // checkout into cwd first.
+    workspace: WORKSPACE_SOURCE.optional(),
+
     // The session the new one is a sub-session of; absent or empty spawns a
     // top-level session.
     parent: z.preprocess(
@@ -84,6 +138,15 @@ export const REQUEST_PARAM_SCHEMAS = {
   }),
   'session.kill': SESSION_DEFAULTED,
   'session.ack': SESSION_DEFAULTED,
+
+  // Without a token, a forget that destroys a host answers with one; the
+  // forget that carries it destroys the host.
+  'session.forget': SESSION_DEFAULTED.extend({
+    confirmToken: z
+      .string({ error: 'session.forget confirmToken must be a string' })
+      .min(1, 'session.forget confirmToken must not be empty')
+      .optional(),
+  }),
   'session.update': SESSION_DEFAULTED.extend({
     name: buildOptionalString(),
     pinned: buildOptionalBoolean(),
@@ -96,6 +159,9 @@ export const REQUEST_PARAM_SCHEMAS = {
   'session.input': SESSION_DEFAULTED.extend({
     d: buildDefaultedString(''),
   }),
+  'session.submit': SESSION_DEFAULTED.extend({
+    text: buildDefaultedString(''),
+  }),
   'session.resize': SESSION_DEFAULTED.extend({
     cols: buildTerminalSize(0),
     rows: buildTerminalSize(0),
@@ -150,6 +216,12 @@ export const REQUEST_PARAM_SCHEMAS = {
       waitMs: buildDefaultedWait(),
     })
     .refine((v) => v.message !== '', { message: 'message.get requires a message' }),
+  'report.get': z
+    .object({
+      // The cursor events.read returned with the report's event.
+      report: buildDefaultedString(''),
+    })
+    .refine((v) => v.report !== '', { message: 'report.get requires a report' }),
   'message.ack': SESSION_DEFAULTED.extend({
     message: buildDefaultedString('').transform(toMessageID),
   }).refine((v) => v.message !== '', { message: 'message.ack requires a message' }),