@humwick/server 0.0.0-stage → 0.130.0

package/runner/src/adapter.ts

@@ -0,0 +1,1061 @@
+import type { ServiceAccessHandoff } from "@humwick/sdk";
+import type { AgentProfile, InteractivePrompt, LivenessSignal, Message, MessageFinalityConfidence, MessageTurnEndReason, OperatorDecisionFileInput, ProviderState, ToolCallCategory } from "@humwick/sdk";
+// Leaf subpaths, not the barrel: the Claude monitor bundle imports this module and must stay small.
+import { receivesTurnResponseAutomatically } from "./response-routing";
+import { heldForSender } from "@humwick/sdk/held-for";
+import { isHumanAgentId } from "@humwick/sdk/types/users";
+import type { ResolvedModelRecord } from "@humwick/sdk/provider-catalog";
+import { isRecord } from "@humwick/sdk/types/guards";
+import type { LivenessInputs } from "./liveness";
+import type { SessionEvent } from "./session-insights";
+import { messageBodyMaxCharsFromEnv, monitorDeliveryLineMaxCharsFromEnv, monitorDeliveryMaxCharsFromEnv } from "./message-body-config";
+import { resolveRelayContext } from "./relay-instructions";
+export { profileAllowsRelayFeature } from "./relay-instructions";
+export { resolveRelayContext } from "./relay-instructions";
+
+export type SemanticStatus = "idle" | "busy" | "offline" | "error";
+
+/**
+ * #1656 — the independent pane read is THREE-VALUED on its non-busy side, and collapsing it to a
+ * boolean was the defect. `false` used to mean both "captured the pane, no spinner" (evidence the
+ * turn is over) and "could not read the pane at all" (no evidence of anything), and the busy
+ * backstop's force-clear consumed the second as if it were the first: absence of evidence taken
+ * as consent, on a turn that was still running.
+ *
+ * - `busy`       — captured, the pane visibly reads busy. Vetoes a clear.
+ * - `not-busy`   — captured, no busy chrome. The ONLY positive evidence the turn is over.
+ * - `no-session` — the pane doesn't exist to be read (no tmux session).
+ * - `unreadable` — the capture failed. Says nothing about the provider, only about the read.
+ *
+ * The last two are both `unknown` to the reconciler and behave identically there; they are kept
+ * distinct so the session log names which failure happened. Neither may ever authorize a mutation.
+ */
+export type PaneBusyReading = "busy" | "not-busy" | "no-session" | "unreadable";
+type ProviderWorkKind = "provider-turn" | "subagent" | "background-script";
+
+export interface ProviderStatusEvent {
+  status: SemanticStatus;
+  providerSessionId?: string;
+  reason?: ProviderWorkKind;
+  clear?: ProviderWorkKind[];
+  timeline?: {
+    status: string;
+    id?: string;
+    timestamp?: number;
+    title?: string;
+    body?: string;
+    icon?: string;
+    metadata?: Record<string, unknown>;
+  };
+  id?: string;
+  label?: string;
+  role?: string;
+  parentId?: string;
+  // OS pids of the process(es) this busy work tracks (#650). When supplied, the
+  // runner reconciles them against actual liveness and clears the busy marker if
+  // every pid is dead — recovering from a tracked process killed out-of-band.
+  pids?: number[];
+  providerState?: ProviderState;
+  /**
+   * With a rate-limit `providerState`: relay ids the runner already took as delivered for the turn the provider then
+   * refused. The runner parks them again (framed as a redelivery) so they replay with their own routes after the hold.
+   */
+  refusedInputIds?: number[];
+  metadata?: Record<string, unknown>;
+  // #1235 — the live transcript path for a hookless (monitorless) provider turn. When an
+  // adapter that learns turn boundaries WITHOUT Stop/UserPromptSubmit hooks (Claude's tmux
+  // monitorless watch) supplies this on a `provider-turn` busy/idle event, the runner drives
+  // the transcript reasoning tail natively: start on turn-start, capture the final response on
+  // turn-end. Absent for hook-driven agents, whose capture stays hook-triggered (no double-run).
+  transcriptPath?: string;
+}
+
+export type ProviderStatusUpdate = SemanticStatus | ProviderStatusEvent;
+
+/**
+ * #1651 — pane evidence cannot end a turn, clear work, complete claims, decide a restart,
+ * or send input. It carries no SemanticStatus or work-kind `clear`. The one display-only
+ * exception is a startup-scoped bypass acceptance dialog (#2629): the runner may show a
+ * blocked badge and timeline alert until the modal disappears. This does not mutate work.
+ *
+ * A detector that wants to say something about the pane emits one of these via
+ * {@link ProviderAdapter.onPaneObservation}; the runner records it and nothing else.
+ */
+export interface PaneObservation {
+  /** Stable event id, e.g. "claude.pane_gate_candidate". */
+  eventType: string;
+  /** Always "pane" — names the (untrusted) evidence class this reading came from. */
+  source: "pane";
+  /** Adapter-scoped detector id: a prompt-gate id, "connection-retry", "model-unavailable". */
+  detectorId: string;
+  observedAt: number;
+  sessionName?: string;
+  /** The pane line that triggered the observation, when there is one. Diagnostic only. */
+  message?: string;
+  /** Detector-specific extras. Diagnostic only — never read for a control decision. */
+  detail?: Record<string, unknown>;
+  /** Startup modal display only; the adapter supplies copy and the runner never changes work state. */
+  displayGate?:
+    | { phase: "show"; providerState: ProviderState; timelineTitle: string }
+    | { phase: "clear" };
+}
+
+/**
+ * A session-mirror event surfaced by an adapter that learns about session
+ * activity through provider events rather than hooks/transcripts (e.g. the Codex
+ * app-server). The runner turns these into `kind: "session"` chat messages, the
+ * same lane Claude's transcript capture uses. Provider-independent boundary.
+ */
+export interface ProviderSessionEvent {
+  type: "prompt" | "response" | "narration" | "reasoning" | "tool";
+  body: string;
+  origin?: "chat" | "terminal" | "provider";
+  turnId?: string;
+  occurredAt?: number;
+  /** True only when this response is the completed provider turn, not an intermediate flush. */
+  final?: boolean;
+  /** Whether the turn-final edge was provider-native or reconstructed. Set only alongside `final`. */
+  confidence?: MessageFinalityConfidence;
+  /** Why the provider turn ended. Set only alongside `final`. */
+  endedBy?: MessageTurnEndReason;
+  /** Whether this response may clear a direct user obligation; Codex keeps this false. */
+  replyToUserObligation?: boolean;
+  /** Route captured with the submitted inbox turn; null means mirror only, undefined uses the runner cache. */
+  replyRoute?: { to: string; replyToMessageId: number; channelTarget?: boolean; replyExpected?: boolean } | null;
+  /** #2840 — the turn opener, already resolved by the runner (a hookless capture finishing after its idle
+   *  edge); null = none. Absent ⇒ the runner resolves it from the final's turn id. */
+  opener?: ProviderSessionEvent["replyRoute"];
+  label?: string;
+  /** Provider-independent tool-call category (#1498), adapter-resolved; only set when type is "tool". */
+  category?: ToolCallCategory;
+  /** #3411 — absolute paths of the files a tool reads or edits, from its raw input (never `params`,
+   *  which is capped); only set when type is "tool". The runner matches them to path areas. */
+  paths?: string[];
+  /**
+   * Tool/step lifecycle status. `cancelled` (#2354) is the terminal outcome for a tool the
+   * provider interrupted before it finished (OpenCode's ToolPart error state with
+   * `interrupted:true`), distinct from `failed` (ran and errored). Extended ONCE here for every
+   * provider — see MessageSessionMeta.status.
+   */
+  status?: "running" | "completed" | "failed" | "cancelled";
+  streaming?: boolean;
+  /** Stable provider-side step id (Codex app-server item id). Carried into
+   * MessageSessionMeta.stepId so the server upserts the step's row in place instead of
+   * appending a duplicate (a tool's running→completed, a streamed reasoning row). */
+  stepId?: string;
+  /**
+   * #2397 round 3 — true only for a narration ABOUT the adapter's own retry/failure mechanics
+   * (e.g. "retrying in 4s…", "gave up after N retries"), never for anything the model itself
+   * produced. `noteOutput` (empty-turn.ts) excludes these from empty-turn evidence the same way it
+   * already excludes an echoed `prompt`: a retry storm that ends in terminal failure must not read
+   * as forward progress and cancel the #2389 input-armed escalation that wakes the spawn parent.
+   * Distinct from `status: "failed"` on purpose — a failed TOOL call is still evidence the model is
+   * alive and working; this is evidence only that the TRANSPORT is still failing.
+   */
+  diagnostic?: boolean;
+  /** #2437 — redacted, size-capped tool input/arguments, only set when type is "tool". Carried
+   * straight into MessageSessionMeta.params by the adapter-event→session-meta conversion. */
+  params?: unknown;
+}
+
+export type ProviderSessionEventBatch = ProviderSessionEvent[];
+
+export interface ProviderSessionTurnInput {
+  transcriptPath: string;
+  lastAssistantMessage?: unknown;
+  promptId?: string;
+  isPreFlush?: boolean;
+  toolName?: string;
+  toolInput?: unknown;
+}
+
+/**
+ * One provider-observed token-usage report. Providers own extraction from their
+ * native session data; the runner owns authenticated delivery to Relay.
+ */
+export interface ProviderTokenUsageRecord {
+  subagentId?: string;
+  sessionId: string;
+  provider: string;
+  model: string;
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens: number;
+  cacheWriteTokens: number;
+  reasoningOutputTokens?: number;
+  dedupeKey: string;
+  createdAt: number;
+  /** #3351 — the provider recorded usage without counts; buckets are zero and the ledger marks it unknown. */
+  usageStatus?: "unknown";
+}
+
+/** Runner-owned transport supplied to adapters that can capture token usage. */
+export interface ProviderTokenUsageReporter {
+  report(record: ProviderTokenUsageRecord): Promise<unknown>;
+  /** Keep unread/failed capture unknown until a pass durably reports usage. */
+  capture?(key: string, read: () => Promise<number>, pending?: boolean): Promise<void>;
+  debug(message: string): void;
+  reportFailure(error: unknown): void;
+}
+
+export interface ProviderSessionTurnContext {
+  turnId?: string;
+  turnStartedAt?: number;
+  /** #2840 — set only on a hookless capture after the idle edge: the opener snapshotted there. */
+  opener?: ProviderSessionEvent["opener"];
+  chatCaptureMode: ProviderConfig["chatCaptureMode"];
+  reasoningCapture?: boolean;
+  settlePollIntervalMs: number;
+  settlePollTimeoutMs: number;
+  flushSessionEvents(timeoutMs: number): Promise<boolean>;
+  pendingSessionEventCount(): number;
+  log(message: string): void;
+  debug(message: string): void;
+  /** #2919 — set only on a turn-end capture: input the provider already accepted runs as the next turn
+   *  with no busy edge of its own, so the runner keeps a turn open across this end. */
+  noteQueuedTurn?(): void;
+}
+
+export interface ProviderSessionTurnResult {
+  reasoningSettled?: boolean;
+  // The transcript-embedded event time of the exact tool_use anchor that triggered this
+  // pre-flush harvest (when resolvable) — a more accurate stamp for a resolved permission
+  // prompt's display ordering than the hook's own wall-clock receipt time, which a provider
+  // can flush/timestamp its transcript entry after.
+  toolUseOccurredAt?: number;
+}
+
+export interface ProviderUserPromptInput {
+  prompt: string;
+  transcriptPath?: string;
+  promptId?: string;
+  /** Epoch ms at which the provider ran its hook, when it reports one. */
+  firedAt?: number;
+}
+
+export interface ProviderPermissionResolvedPrompt {
+  provider: "claude";
+  kind: "questions" | "plan" | "command" | "tool";
+  title: string;
+  body: string;
+  promptBody?: string;
+  toolName: string;
+  hookEventName: string;
+  approvalId: string;
+  decision: ProviderPermissionDecisionInput["decision"];
+  decisionLabel: string;
+  occurredAt: number;
+  resolvedAt: number;
+  decisionReason: ProviderPermissionDecisionReason;
+  questions?: unknown[];
+  answers?: Record<string, string>;
+}
+
+export interface ProviderPermissionPromptHandler {
+  source: string;
+  resolvedLabel: string;
+  buildView(id: string, body: Record<string, unknown>, reasoningSettled: boolean): InteractivePrompt;
+  buildHookResponse(decision: ProviderPermissionDecisionInput, body: Record<string, unknown>): Record<string, unknown>;
+  buildResolvedPrompt(view: InteractivePrompt, decision: ProviderPermissionDecisionInput, body: Record<string, unknown>, occurredAt: number): ProviderPermissionResolvedPrompt;
+  // #1173: for prompt kinds whose PreToolUse hook is answered immediately (deny-then-hold —
+  // see control-server.ts's AskUserQuestion branch) rather than held open for the decision,
+  // this renders the eventual "answer" decision as the normal user-prompt text to inject back
+  // into the session. Absent for prompt kinds that still ride the hook response directly.
+  buildAnswerInjectionPrompt?(view: InteractivePrompt, decision: ProviderPermissionDecisionInput, body: Record<string, unknown>): string;
+  // #2914: maps a "questions" prompt to a durable operator decision a coordinator files instead.
+  buildDecisionRequest?(body: Record<string, unknown>): OperatorDecisionFileInput | undefined;
+}
+
+export interface ProviderConfig {
+  command: string;
+  defaultArgs: string[];
+  env: Record<string, string>;
+  pluginDirs: string[];
+  globalInstructionFiles?: string[];
+  defaultCapabilities: string[];
+  defaultApprovalMode: string;
+  defaultTags: string[];
+  chatCaptureMode: "final" | "full";
+  // When false, the runner does not stream reasoning/tool steps into chat. Defaults
+  // to enabled (steps render discreetly, never as chat bubbles).
+  reasoningCapture?: boolean;
+  // #2539 Phase A — how a provider WITH a mid-turn steer channel treats an ordinary message
+  // offered while a turn is active. Optional everywhere: absent resolves through the OWNING
+  // adapter's default (see resolveActiveTurnMessageDelivery in mid-turn-delivery.ts — adapters
+  // with a mid-turn steer channel, codex and opencode/zai, default to steer; adapters without
+  // one to defer), and `"defer"` doubles as the operational kill switch. Deliberately resolved
+  // per-ADAPTER, never a provider-name table.
+  activeTurnMessageDelivery?: ActiveTurnMessageDelivery;
+  headless: {
+    tmuxPrefix: string;
+    shutdownTimeoutMs: number;
+  };
+}
+
+/** #2539 Phase A — the mid-turn delivery policy. `"steer"` folds an ordinary message offered
+ *  mid-turn into the in-flight turn; `"defer"` keeps queue-until-turn-end. */
+export type ActiveTurnMessageDelivery = "steer" | "defer";
+
+export const ACTIVE_TURN_MESSAGE_DELIVERY_VALUES = ["steer", "defer"] as const;
+
+export interface RunnerSpawnConfig {
+  serviceAccess?: ServiceAccessHandoff;
+  /** Runner-local overlay; never serialized in a command. */
+  serviceAccessEnv?: Record<string, string>;
+  provider: string;
+  model?: string;
+  effort?: string;
+  /** #2595 — effective-catalog context window from the spawn payload (incl. DB overrides);
+   * adapters prefer it over their static manifest lookup. Absent ⇒ fall back to the manifest. */
+  contextWindowTokens?: number;
+  /** #2599 — the full server-resolved model record (protocol ≥ 2). Precedence over the manifest
+   * for window / qualified name / descriptor / threshold; absent ⇒ manifest (or the legacy
+   * #2595 `contextWindowTokens` above, which the adapter reads only when no record is present). */
+  modelRecord?: ResolvedModelRecord;
+  runnerId: string;
+  instanceId: string;
+  agentId: string;
+  relayUrl: string;
+  /** Runner-owned live credential accessor for adapter accounting RPCs. */
+  getRelayToken?: () => string | undefined;
+  cwd: string;
+  headless: boolean;
+  lifecycle?: "persistent" | "transient";
+  approvalMode: string;
+  label?: string;
+  rig?: string;
+  profile?: string;
+  harnessSubagents?: boolean;
+  agentProfile?: AgentProfile;
+  prompt?: string;
+  systemPromptAppend?: string;
+  tmuxSession?: string;
+  providerArgs: string[];
+  providerConfig: ProviderConfig;
+  /** Async snapshot of the host Claude config, loaded before launch assembly. */
+  hostClaudeConfig?: Record<string, unknown>;
+  /** Narrow host Claude settings snapshot used when host hooks are enabled in an isolated home. */
+  hostClaudeSettings?: Record<string, unknown>;
+  env: Record<string, string>;
+  controlPort: number;
+  // Stage 2 (#215): the MCP endpoint the agent connects to — the runner-local proxy URL when the
+  // proxy is active. Undefined → the adapter targets the relay's MCP endpoint directly (Stage 1).
+  relayMcpEndpoint?: string;
+  // #1450: the per-session proxy secret the agent authenticates to the runner-local proxy with (the
+  // same value exported as AGENT_RELAY_SESSION_TOKEN). Set only when the proxy is active; the Codex
+  // per-agent metaOnly callmux uses it to reach the relay endpoint on-demand THROUGH the proxy, so
+  // identity rides the proxy's live-token injection and no relay token is ever written to disk.
+  mcpProxySecret?: string;
+  // #672: the shared host-listener URL the per-agent `callmux bridge` connects to, when the
+  // profile/spawn opted into `agentProfile.sharedMcp`. Resolved runner-side (env → default);
+  // the launch assembler only emits the bridge entry when sharedMcp is on.
+  sharedMcpUrl?: string;
+  monitor?: {
+    deliver(messages: Message[]): Promise<number[]>;
+  };
+  [key: string]: unknown;
+}
+
+export interface SpawnArgs {
+  command: string;
+  args: string[];
+  cwd: string;
+  env: Record<string, string>;
+  /** #2513 — env keys that must be explicitly UNSET in the launch environment (the tmux
+   * launcher script exports only whitelisted keys but still inherits the tmux server's
+   * env, so deleting from `env` alone cannot scrub an ambient credential). */
+  envUnset?: string[];
+  /** A launch-time stdin file, used only by one-shot provider commands. */
+  stdinFile?: string;
+  /** Written by a one-shot launcher after the provider process exits. */
+  exitCodeFile?: string;
+  /** Initial one-shot user assignment, staged into stdinFile immediately before provider spawn. */
+  stdinContents?: string;
+}
+
+export interface ManagedProcess {
+  pid?: number;
+  process?: Bun.Subprocess;
+  meta?: Record<string, unknown>;
+}
+
+/**
+ * #1746 — the terminal verdict of a provider shutdown. `killed` means the provider
+ * process (tmux pane / pid tree) is POSITIVELY confirmed gone; `failed-to-kill` means it
+ * survived even a SIGKILL of its process group (near-impossible on a same-user Linux host,
+ * so it is the operator-visible safety surface, not the happy path). The runner uses this
+ * to gate deregistration: a roster removal must imply the process is dead (#1746 ask 2), so
+ * a `failed-to-kill` keeps the agent visible rather than turning it into a silent zombie.
+ */
+export type ShutdownOutcome = "killed" | "failed-to-kill";
+
+export interface TerminalAttachSpec {
+  mode: "guest";
+  provider: string;
+  cwd: string;
+  command: string[];
+  /**
+   * #2459 round 1 (review A) — REMOVED: a per-key env record let the guest credential ride
+   * the attach-spec HTTP response body and the orchestrator's process state. Credentials now
+   * travel ONLY via {@link envFile}: the runner pre-stages a 0600 env file it owns and the
+   * spec carries its PATH (never its contents); the orchestrator wraps the guest command in a
+   * shell that sources that file, so the secret materializes solely in the guest process
+   * environment.
+   */
+  title?: string;
+  ttlMs?: number;
+  /**
+   * #2459 — absolute path to a 0600 env file written by the runner (same host + user), for
+   * the orchestrator's guest wrapper to source into the guest process environment. The path
+   * is not a secret; the file contents never travel through the control server, the
+   * orchestrator's memory/persistence, logs, or any argv.
+   */
+  envFile?: string;
+  /**
+   * #2459 — non-secret attachment generation, derived from the provider's ACTIVE session id
+   * (a one-way digest — never the session id itself, never a credential). The orchestrator
+   * stores it with the guest tmux session and re-reads the runner's current generation before
+   * terminal input and on stream connect/reconnect; a mismatch means clearContext()/retry
+   * re-rolled the session and the guest TUI is attached to a dead conversation, so the guest
+   * is killed with a typed "session changed; reopening terminal" result. Absent for providers
+   * whose attach target cannot go stale (codex resumes a pinned thread id).
+   */
+  generation?: string;
+}
+
+export type ProviderPermissionDecision = "approve" | "approve-session" | "deny" | "abort" | "answer";
+
+export interface ProviderPermissionDecisionInput {
+  approvalId: string;
+  decision: ProviderPermissionDecision;
+  reason?: string;
+  decisionReason?: ProviderPermissionDecisionReason;
+  // For "answer" decisions (Claude AskUserQuestion): maps each question's text
+  // to the chosen option label(s). Multi-select labels are comma-joined.
+  answers?: Record<string, string>;
+}
+
+export interface ProviderPermissionDecisionReason {
+  kind: "timeout" | "dismissed" | "answered";
+  message?: string;
+}
+
+// Fresh, per-turn context usage a transcript-backed adapter reads from its
+// session log (#1512). tokensUsed is the context-window token sum for the turn;
+// occurredAt is the wall-clock ms of the turn when the log stamps one.
+export interface ProviderContextUsage {
+  tokensUsed: number;
+  model?: string;
+  occurredAt?: number;
+}
+
+/**
+ * Runner-owned live turn state is sampled when the adapter offers input.
+ *
+ * #2539 Phase B — the SAME context carries the deferred-settlement handoff for a mid-turn steer whose
+ * acceptance is not yet consumption (OpenCode/zai noReply persist: the provider row exists, the model
+ * reads it at a LATER step). The callbacks are runner-owned implementations of the ONE settlement seam —
+ * `settleMidTurnConsumed` completes an awaiting id's settlement exactly like an immediate ack (mark read,
+ * release the claim, poison the intake guard against re-enqueue); `reofferMidTurnIds` returns ids to the
+ * NORMAL queue when they can no longer be consumed where they were persisted (session clear/compact/reroll
+ * swap, shutdown, definitive non-persistence after an ambiguous POST) — never a repost into the provider.
+ * The adapter NEVER settles or requeues on its own; it only reports ids through these.
+ */
+/** Evidence for one input offer; acceptance callbacks must stay bound to that offer. */
+export interface ProviderInputObserver {
+  offered(at: number, hasConsumptionSignal: boolean): void;
+  consumed(): void;
+}
+
+export interface ProviderDeliverContext {
+  inputObserver?: ProviderInputObserver;
+  /** #2840 — for an adapter that runs one provider turn PER message: these messages open the next turn.
+   *  Returns a disarm for when they open none (failed, refused). Absent call ⇒ the whole batch opens one. */
+  openTurnFor?: (messages: Message[]) => () => void;
+  /** #3415 — this offer's turn is opened by only these messages (a split batch); a no-op unless the offer armed an opener. Returns its disarm. */
+  narrowTurnOpener?: (messages: Message[]) => () => void;
+  isRecipientMidTurn?: () => boolean;
+  /** Text an adapter types as a provider user turn, so its prompt-hook echo is not mirrored as terminal input. */
+  recordSubmittedPrompt?: (text: string, imagePaths?: readonly string[]) => void;
+  /**
+   * #2539 Phase B — positively CONSUMED ids for a batch previously reported through
+   * {@link DeliverResult.awaitingConsumptionIds}. Fires once per id when the model has read the
+   * persisted row (SSE parentID correlation or the bounded idle-wake settle). Absent callback ⇒
+   * the adapter must hold the ids in its ledger (fail-safe: never silently settled).
+   */
+  settleMidTurnConsumed?: (relayIds: number[]) => void;
+  /**
+   * #2539 Phase B — ids to hand BACK to the normal queue (settled as undelivered, re-offered at
+   * the next boundary) because their persisted row can no longer be consumed where it lives.
+   * Absent callback ⇒ hold in the ledger, same fail-safe as {@link settleMidTurnConsumed}.
+   */
+  reofferMidTurnIds?: (relayIds: number[]) => void;
+}
+
+export interface DeliverResult {
+  acknowledgedIds: number[];
+  /**
+   * #2539 Phase B — ids the adapter positively accepted for the in-flight turn (or holds in
+   * ambiguous custody after ONE timed-out POST whose bounded exact-id reconcile was inconclusive)
+   * but whose CONSUMPTION has not happened yet, so their settlement completes LATER through
+   * {@link ProviderDeliverContext.settleMidTurnConsumed} / {@link ProviderDeliverContext.reofferMidTurnIds}.
+   * The runner records the delivery attempt but does NOT mark read, release the claim, or treat
+   * them as settled — persistence is not delivery. Must be DISJOINT from `acknowledgedIds`; ids in
+   * neither set are requeued for turn-end delivery as usual.
+   */
+  awaitingConsumptionIds?: number[];
+  /**
+   * #2397 round 3 review (MED-3r) — ids the adapter positively knows failed a TERMINAL provider
+   * error (e.g. OpenCode's retry+reroll budget exhausted against a rate-limited upstream), as
+   * opposed to an ordinary un-acknowledged id (recipient mid-turn, transport busy). The runner
+   * paces its re-drain of these with bounded exponential backoff instead of an immediate re-drain — without
+   * this, a re-queued message whose provider is already rate-limiting hammers it again on the very
+   * next tick, forever. Must be a SUBSET of the ids NOT in `acknowledgedIds`.
+   */
+  terminalFailureIds?: number[];
+  /**
+   * #2619 — ids the provider REFUSED under a rate-limit/quota hold (the turn ended in the shared
+   * `blocked/rate_limit` hold, not a terminal failure). Not delivered and not failed: the runner
+   * parks them (never re-drained into the wall, claims released so no Task completes) until a
+   * provider turn goes through again, then redelivers them. Must be disjoint from `acknowledgedIds`.
+   */
+  providerHeldIds?: number[];
+}
+
+/**
+ * #2534 — thrown by a synchronous-endpoint adapter (OpenCode/zai) when its outbound prompt was
+ * positively ACCEPTED and persisted by the provider, but the turn's COMPLETION await itself
+ * failed afterwards (transport drop, turn-timeout abort). The provider is already working on the
+ * prompt, so the caller must NOT requeue it: a requeue would run the same assignment a second
+ * time. The `cause` carries the original transport failure for the diagnostic trail.
+ */
+export class PromptAcceptedError extends Error {
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message, options);
+    this.name = "PromptAcceptedError";
+  }
+}
+
+export interface ProviderAdapter {
+  /** Mask tool responses before the provider consumes them when hooks cannot replace results. */
+  mcpToolResponseRedactor?(cwd: string): ((response: Response) => Promise<Response>) | undefined;
+  provider: string;
+  statusSourceId?: string;
+  stopObligationPath?: string;
+  permissionPromptHandler?: ProviderPermissionPromptHandler;
+  spawn(config: RunnerSpawnConfig): Promise<ManagedProcess>;
+  // #1746 — resolves once the provider is terminal. Returns the outcome so the runner can
+  // gate deregistration on confirmed death; `void` from a legacy adapter is treated as
+  // `killed` (best-effort back-compat), but both first-party adapters now report explicitly.
+  shutdown(process: ManagedProcess, opts: { graceful: boolean; timeoutMs: number }): Promise<ShutdownOutcome | void>;
+  /** Synchronously cancel current adapter status sources before the runner publishes terminal status. */
+  stopStatusWatchers?(): void;
+  /** Re-arm status sources for the same process when a restart attempt fails before replacement. */
+  resumeStatusWatchers?(process: ManagedProcess): Promise<void> | void;
+  compact?(process: ManagedProcess, opts?: { instructions?: string; signal?: AbortSignal; onSubmitted?: () => void }): Promise<Record<string, unknown> | void>;
+  compactSupportsInstructions?: boolean;
+  // Blind submits stamp onSubmitted and need a separate compacted/idle completion barrier.
+  /** #3398 — the adapter emits its own `compacted` / `context-cleared` timelines; hook copies are not reset facts. */
+  reportsContextResets?: boolean;
+  compactReportsSubmission?: boolean;
+  clearContext?(process: ManagedProcess): Promise<Record<string, unknown> | void>;
+  // #2950 — change effort in place. Resolves with the confirmed `effort`, throws when the provider
+  // refused or never confirmed it. Only processes whose meta.effortSwitch is true may receive it.
+  setEffort?(process: ManagedProcess, effort: string): Promise<{ effort: string } & Record<string, unknown>>;
+  // #1588 — when true, the runner delivers a self-resume clear-inject continuation IN-PROCESS,
+  // coupled to the very same agent.clearContext command (deliverCoupledContinuationAfterClear),
+  // rather than leaving it to the separate reactive agent.injectContext command, and only when
+  // clearContext reports `clearConfirmed: true`. Set it when a separate inject could race the clear
+  // (Claude tmux's async `/clear`, the #1588 silent mind-wipe) or land after a queued inbox message
+  // (headless Claude, whose clear resolves on its native conversation_reset boundary). Codex leaves
+  // it unset: its awaited threadStart is the barrier and the separate inject (backstopped by the
+  // server-side #1023 sweep) stays untouched.
+  couplesClearInjectContinuation?: boolean;
+  // #2043 F1 — when true, this provider's `/compact` // `/clear` must be submitted to an IDLE
+  // provider: Claude tmux keystrokes typed mid-turn dequeue as literal chat, and headless Claude
+  // queues stream-json input behind the live turn. The runner therefore gates the submit on the
+  // live provider turn CLEARING first (waitForProviderTurnClear). Providers whose compact/clear is an
+  // awaited app-server handshake (Codex) leave this unset — a plain turn-clear wait would time out
+  // on their in-turn compaction. Those providers fence the PREDECESSOR turn a different way
+  // instead — see interruptsTurnBeforeContextCommand below (#2569).
+  awaitsIdleBeforeContextCommand?: boolean;
+  // #2569 — when true, the runner must INTERRUPT and SETTLE the predecessor provider turn before
+  // this provider's compact/clearContext runs. Set for app-server providers (Codex) whose
+  // clearContext starts a FRESH thread (and whose compact rewrites the current one) via an awaited
+  // handshake: the await confirms the NEW generation is ready but does NOT settle the OLD turn.
+  // relay_compact_and_resume is called from within the model's own live turn, so that turn keeps
+  // running on the previous thread while the successor generation is armed on the new one — two
+  // generations then write the single worktree and revert each other (the #2569 silent overlap).
+  // A plain wait would time out on the still-live in-turn compaction (why blind-submit providers
+  // can't share this path), so the fence actively interrupts the turn, then waits for it to reach
+  // a terminal state (interrupt-then-settle, mirroring the redirect path) before the destructive
+  // step. Adapters that fence internally (OpenCode's turnQueue) or have no interrupt leave this unset.
+  interruptsTurnBeforeContextCommand?: boolean;
+  // Derive the current context-window token usage from a transcript-backed
+  // provider's session log (#1512). The runner calls this every heartbeat with the
+  // latest transcript so context stats keep advancing per-turn even when a provider's
+  // out-of-band probe (Claude's status-line command) goes silent after a
+  // compact/clear/native-resume. Pure parse — no process state. Event-stream
+  // providers (Codex) report context through `meta.getContext` instead and omit this.
+  contextUsageFromTranscript?(jsonl: string): ProviderContextUsage | undefined;
+  // Normalize the session so far into the provider-agnostic SessionEvent stream the
+  // Insights context-ratio signal (#183/#184) reduces. Called by the runner's
+  // pre-session-destroy seam before any compact/clear/restart/shutdown. The runner owns
+  // the per-segment cursor (it slices events since the last capture), so this returns the
+  // full ordered event list for the current process lifetime. `ctx.transcriptPath` is
+  // supplied for transcript-backed providers (Claude); event-stream providers (Codex)
+  // ignore it and return their accumulated log. Return null when there is nothing to
+  // measure. Best-effort: may be omitted by providers without a session view yet.
+  collectSessionEvents?(process: ManagedProcess, ctx: { transcriptPath?: string }): Promise<SessionEvent[] | null>;
+  // Full searchable transcript/archive source for destructive boundaries. The runner
+  // slices the returned stream by cursor, so adapters should return the session-so-far
+  // view when they have one.
+  collectSessionArchiveSegment?(process: ManagedProcess, ctx: { transcriptPath?: string }): Promise<string | null>;
+  // Interrupt the in-flight turn without ending the session (ESC for Claude's
+  // tmux pane, turn/interrupt for the Codex app-server). Provider-independent at
+  // the runner boundary; each adapter does what its provider actually supports.
+  // Contract: abort the turn, never drain it and never attempt Relay-side rollback.
+  // Tool side effects already applied (including partial file writes) remain for the
+  // agent to reconcile. Redirect waits for provider idle before starting a clean turn.
+  interrupt?(process: ManagedProcess): Promise<Record<string, unknown> | void>;
+  // Whether the adapter supports additive input into a running provider turn.
+  supportsMidTurnSteer?: boolean;
+  /**
+   * #2539 Phase A — the shared mid-turn steer contract (Phase B: opencode/zai implement against
+   * the same shape). Given a batch offered while the recipient is mid-turn, the adapter owns the
+   * ONE eligibility decision: fold the steerable subset (ordinary persisted messages,
+   * `partitionMidTurnDelivery`) into the in-flight turn and return/ack ONLY those ids;
+   * leave the boundary-only classes (synthetic memory/self-resume
+   * injections, claimable/task assignments) un-acked so the runner requeues them for turn-end
+   * delivery. Throwing defers the whole batch (the runner requeues it). Adapters honor
+   * `ProviderConfig.activeTurnMessageDelivery` — `"defer"` (the kill switch) restricts the
+   * steerable set to empty. Implemented by adapters with
+   * `supportsMidTurnSteer`; their `deliver` consults it at the paste instant, so the runner
+   * keeps a single call path.
+   *
+   * #2539 Phase B (OpenCode/zai) — the acceptance/consumption split: the ack for this adapter
+   * means POSITIVE PERSISTENCE (POST /session/:id/message with a caller messageID +
+   * noReply:true — a user row the active loop consumes at its next step; live-proven on pinned
+   * 1.18.21), not consumption, so persisted/ambiguous ids are returned as
+   * {@link DeliverResult.awaitingConsumptionIds} and settle later through the ctx's
+   * `settleMidTurnConsumed`/`reofferMidTurnIds` — the adapter owns the durable-until-consumed
+   * ledger, SSE consumption detection, the bounded idle-wake fallback and session fencing; the
+   * runner keeps owning claims and settlement. Definitive non-persistence (reconciled absent)
+   * throws so the runner paces the retry; ids past the adapter's backpressure caps are left
+   * un-acked for the normal lane.
+   */
+  deliverMidTurn?(process: ManagedProcess, messages: Message[], ctx?: ProviderDeliverContext): Promise<void | number[] | DeliverResult>;
+  // Out-of-band activity probe for the busy-state reconciler: returns the real
+  // provider activity when the runner's claim state may have gone stale (e.g. the
+  // turn was interrupted from the web terminal so no Stop hook fired). "unknown"
+  // means the provider can't be cheaply probed and the reconciler should defer.
+  probeActivity?(process: ManagedProcess): Promise<"busy" | "idle" | "unknown">;
+  // #769 P1-A: an independent "is the provider still visibly busy?" read, consulted by the
+  // busy backstop — a probeActivity()=idle must not clear a live turn while this reads `busy`
+  // (defense-in-depth when the primary probe can momentarily read idle mid-turn, e.g. a
+  // connection retry). #1656: three-valued on purpose. Only `not-busy` is evidence the turn
+  // ended; `no-session`/`unreadable` are unknown and must never authorize a clear.
+  probePaneBusy?(process: ManagedProcess): Promise<PaneBusyReading>;
+  // #1138: resolve a real OS pid for a busy provider-turn whose ManagedProcess carries
+  // none directly (e.g. Claude's tmux launch — process.pid is undefined, only a tmux
+  // session/socket). The runner calls this as a fallback when a busy report supplies no
+  // explicit pids, so the #650 liveness reconcile (and the stale-turn backstop) has real
+  // proof-of-life instead of only an elapsed-time heuristic. Returning undefined leaves
+  // the runner's existing process.pid fallback (or no pid at all) unchanged.
+  resolveBusyPid?(process: ManagedProcess): number | undefined;
+  terminalAttachSpec?(process: ManagedProcess): Promise<TerminalAttachSpec>;
+  // #2459 — the CURRENT non-secret attachment generation (see TerminalAttachSpec.generation).
+  // Read by the runner control server's GET /terminal/generation so the orchestrator can
+  // detect a session rotation without ever learning the session id or any credential.
+  // Absent ⇒ the provider's attach target cannot go stale (codex) and the endpoint reports
+  // no generation, which the orchestrator treats as "nothing to check".
+  terminalAttachGeneration?(process: ManagedProcess): string | undefined;
+  respondToPermissionDecision?(process: ManagedProcess, input: ProviderPermissionDecisionInput): Promise<Record<string, unknown> | void>;
+  /** Configure the runner-owned authenticated delivery path for provider-native usage capture. */
+  configureTokenUsageReporter?(reporter: ProviderTokenUsageReporter): void;
+  captureSessionTurn?(input: ProviderSessionTurnInput, ctx: ProviderSessionTurnContext): Promise<ProviderSessionTurnResult | void>;
+  captureSubagentTokenUsage?(transcriptPath: string): Promise<void>;
+  /**
+   * Bounded final provider-native accounting pass before a session is torn down. `transcriptPath`
+   * is `undefined` for a provider with no transcript file to tail (#2484 round 2 review MED-1 —
+   * OpenCode's capture is event-sourced, not file-tailed); the adapter owns whatever precondition
+   * it needs (a transcript-tailing adapter bails itself on a missing path, an event-sourced one
+   * ignores the argument entirely).
+   */
+  captureFinalTokenUsage?(transcriptPath: string | undefined, ctx: ProviderSessionTurnContext): Promise<void>;
+  /** Start the provider-owned lifecycle observation for a prompt seeded in the launch command. */
+  startLaunchSeededTurn?(process: ManagedProcess): Promise<void>;
+  handleUserPrompt?(input: ProviderUserPromptInput, ctx: ProviderSessionTurnContext): Promise<void>;
+  /** Whether a prompt the provider reports is one the runner submitted, through the provider's paste transport (#3081). */
+  matchesSubmittedPrompt?(providerPrompt: string, submitted: string, imagePaths?: readonly string[]): boolean;
+  /** A session-start hook's stamped check-in (#2664): the provider's hook path works. */
+  handleHookCheck?(input: { firedAt?: number }, ctx: ProviderSessionTurnContext): void;
+  /** File paths from a synchronous provider tool hook; absent means transcript delivery. */
+  toolHookPaths?(input: unknown): string[] | undefined;
+  drainSessionTrace?(ctx: ProviderSessionTurnContext): Promise<void>;
+  settleSessionTraceForToolUse?(transcriptPath: string, toolName: string | undefined, toolInput: unknown, ctx: ProviderSessionTurnContext): Promise<{ settled: boolean; jsonl?: string }>;
+  stopSessionTrace?(): void;
+  publishPassiveTelemetry?(): Promise<void>;
+  // `options.readyTimeoutMs` lets the runner widen the provider-ready wait for the
+  // first (cold-start) delivery vs. a fast re-attempt after a ready signal (#329).
+  // `options.isInitial` (default true) tells the adapter whether this delivery is the
+  // agent's genuine first turn — the runner passes false from the dashboard
+  // prompt-injection / continue paths (#1228) so a mid-session nudge isn't mislabeled
+  // as the initial prompt.
+  // Resolves "held" (#2619) when the provider REFUSED the prompt under a rate-limit/quota hold:
+  // not delivered, not failed — the runner parks it for redelivery (provider-hold.ts).
+  deliverInitialPrompt?(process: ManagedProcess, prompt: string, options?: PromptOfferOptions): Promise<void | "held">;
+  /** Confirm that a previously ambiguous input was consumed before the runner lifts its delivery hold. */
+  confirmSubmitRecovery?(process: ManagedProcess, turnStarted: boolean): Promise<boolean>;
+  /** The operator released the runner's submit hold (#2664): drop any adapter-side submit fence. */
+  releaseSubmitHold?(process: ManagedProcess): void;
+  // When true, the adapter seeds the spawn-time initial prompt as a launch argument
+  // (Claude's positional `claude "<prompt>"`), so it's already delivered the instant the
+  // session starts. The runner must then NOT also deliver it post-launch via
+  // deliverInitialPrompt — that would double-deliver and re-introduce the send-keys
+  // onboarding race (#352). deliverInitialPrompt stays available for mid-session injection
+  // (dashboard chat box) and ongoing message delivery, which have no launch-arg equivalent.
+  seedsInitialPromptAtLaunch?: boolean;
+  /** Return accepted ids, plus consumption or failure outcomes when the transport reports them. */
+  deliver(process: ManagedProcess, messages: Message[], ctx?: ProviderDeliverContext): Promise<void | number[] | DeliverResult>;
+  onStatusChange(cb: (status: ProviderStatusUpdate) => void): void;
+  // #1651 — subscribe to pane-derived DIAGNOSTICS. Separate from onStatusChange on purpose:
+  // this channel's payload cannot carry a status, a clear, or a providerState, so wiring a
+  // detector here is a structural guarantee that it cannot mutate runner state. Optional;
+  // adapters with no pane to scrape simply never call it.
+  onPaneObservation?(cb: (observation: PaneObservation) => void): void;
+  // Subscribe to session-mirror events from providers. Batch callbacks preserve
+  // shared idempotency for multiple trace steps discovered in one provider poll.
+  onSessionEvent?(cb: (event: ProviderSessionEvent) => void): void;
+  onSessionEvents?(cb: (events: ProviderSessionEventBatch) => void): void;
+  // #2389 — "the model produced something in the current turn", for output an adapter can OBSERVE
+  // but cannot mirror. It exists because the runner has to tell a turn that did nothing at all from
+  // one that finished work, and mirrored session events do not cover every provider: OpenCode's
+  // wire carries tool parts whose internal shape we deliberately do not guess at, so they are
+  // reported as bare activity rather than published as a half-understood trace step. Evidence only
+  // — nothing is displayed, nothing is persisted. Optional; adapters whose output is fully mirrored
+  // never need it.
+  onTurnActivity?(cb: () => void): void;
+  // §4.1 of the Runner↔provider contract (#725 / #746): fold the runner-tracked raw
+  // transport/timeline/token/work-kind signals into ONE normalized LivenessSignal the
+  // server reads instead of six raw `meta` fields. Each adapter owns what counts as
+  // progress for its provider (Claude #713 timeline transitions; Codex #724 live
+  // subprocess work). Optional so test/mock adapters fall back to the shared
+  // {@link computeLivenessSignal} fold — the runner always has a verdict to ship.
+  liveness?(inputs: LivenessInputs): LivenessSignal;
+  // Headless providers with no tmux session (e.g. the Codex app-server) still
+  // warrant an automatic restart on unexpected exit. Returning true opts the
+  // provider into the runner's restart-with-backoff path.
+  supportsUnexpectedExitRestart?(): boolean;
+  /** Provider-owned preload for runner registration metadata. The returned snapshot is passed to
+   * synchronous assembly/reporting only; provider-specific I/O stays behind this boundary. */
+  preloadRunnerConfig?(): Promise<Pick<RunnerSpawnConfig, "hostClaudeConfig" | "hostClaudeSettings"> | undefined>;
+  /** Hydrates one spawn/restart config before the provider-neutral runner passes it to any
+   * synchronous launch assembly consumer. */
+  hydrateSpawnConfig?(config: RunnerSpawnConfig): Promise<RunnerSpawnConfig>;
+  buildSpawnArgs(config: RunnerSpawnConfig, providerConfig: ProviderConfig): SpawnArgs;
+}
+
+// #552 — the strictest base. Beyond the isolated provider home that every
+// non-host base already gets (fresh CLAUDE_CONFIG_DIR / CODEX_HOME, which drops
+// the GLOBAL instruction + host MCP/hooks/plugins cascade), "vanilla" actively
+// suppresses every remaining host customization channel at launch, including the
+// REPO CLAUDE.md/AGENTS.md cascade that lives in the cwd and so survives home
+// isolation. Claude: `--setting-sources "user"` (the --safe-mode pivot — safe-mode
+// blocked even explicit provisioning). Codex: `project_doc_max_bytes=0`.
+export function profileIsVanillaBase(config: Pick<RunnerSpawnConfig, "agentProfile">): boolean {
+  return config.agentProfile?.base === "vanilla";
+}
+
+export function relayContext(): string {
+  return resolveRelayContext({ slug: "relay.context.codex" }).text;
+}
+
+// #306 — deliver the FULL message body by default. Only a pathological body beyond this
+// high cap truncates (with a get-message hint) so it can't nuke an agent's context; the 99%
+// case (incl. multi-thousand-char handoffs/reports) arrives whole in one shot, no extra
+// round-trip. The mirror flow (user typing directly) already injects full text — this removes
+// the asymmetry where agent↔agent + attachment-bearing messages were second-class.
+export const DEFAULT_PROVIDER_MESSAGE_BODY_MAX_CHARS = 24_000;
+
+// Resolve the delivered-body cap. Deployment-dependent (the right ceiling tracks the host's
+// context budget), so it's overridable via env — set on the orchestrator/host that spawns runners.
+export function providerMessageBodyMaxChars(): number {
+  const raw = messageBodyMaxCharsFromEnv();
+  if (raw !== undefined) {
+    const parsed = Number.parseInt(raw.trim(), 10);
+    if (Number.isFinite(parsed) && parsed > 0) return parsed;
+  }
+  return DEFAULT_PROVIDER_MESSAGE_BODY_MAX_CHARS;
+}
+
+// #1935 — the Claude Code monitor surfaces each delivered event with a HARD cap on the content that
+// reaches the agent's context; beyond it the harness truncates the event and spills the tail to an
+// output file the agent must re-read (paying for the message ~twice, both copies persisting in
+// context). Two independent bounds, measured 2026-08-02 against the live harness:
+//   - per delivered event total ≈ 3000 chars
+//   - per single line          ≈ 500 chars
+// We keep a safety margin below each (a delivery near the edge should still land whole) and allow a
+// per-deployment override, since the true ceiling tracks the host's harness build. Delivery
+// composition consults these to choose fits-in-full vs emit-a-minimal-stub (see claude-delivery.ts).
+export const DEFAULT_MONITOR_DELIVERY_MAX_CHARS = 2_800;
+export const DEFAULT_MONITOR_DELIVERY_LINE_MAX_CHARS = 480;
+
+function resolvePositiveIntEnv(raw: string | undefined, fallback: number): number {
+  if (raw !== undefined) {
+    const parsed = Number.parseInt(raw.trim(), 10);
+    if (Number.isFinite(parsed) && parsed > 0) return parsed;
+  }
+  return fallback;
+}
+
+export function monitorDeliveryMaxChars(): number {
+  return resolvePositiveIntEnv(monitorDeliveryMaxCharsFromEnv(), DEFAULT_MONITOR_DELIVERY_MAX_CHARS);
+}
+
+export function monitorDeliveryLineMaxChars(): number {
+  return resolvePositiveIntEnv(monitorDeliveryLineMaxCharsFromEnv(), DEFAULT_MONITOR_DELIVERY_LINE_MAX_CHARS);
+}
+
+// A composed monitor delivery reaches the agent whole iff its total length (plus `reserved` — any
+// content already emitted into the SAME batched event, e.g. the once-per-session context block on
+// first delivery) stays within the per-event cap AND no single line exceeds the per-line cap.
+// Either breach means the harness truncates and forces a re-fetch, so the caller should emit a
+// minimal stub instead of a large truncated preview.
+export function fitsMonitorDelivery(
+  text: string,
+  options: { reserved?: number; maxChars?: number; lineMaxChars?: number } = {},
+): boolean {
+  const maxChars = options.maxChars ?? monitorDeliveryMaxChars();
+  const lineMaxChars = options.lineMaxChars ?? monitorDeliveryLineMaxChars();
+  if (text.length + (options.reserved ?? 0) > maxChars) return false;
+  for (const line of text.split("\n")) {
+    if (line.length > lineMaxChars) return false;
+  }
+  return true;
+}
+
+export interface DeliveredBodyPreview {
+  body: string;
+  truncated: boolean;
+  /** Retrieval-guidance lines (empty when not truncated). Call sites may append provider extras. */
+  guidance: string[];
+}
+
+// #1058 — one home for the delivered-body cap. Head-only truncation silently ate the TAIL, which is
+// exactly where a report-up final puts its verdict / SHIP recommendation. Preserve BOTH ends: keep a
+// head slice for opening context and a tail slice for the conclusion, eliding the middle and pointing
+// at the untrimmed body. The tail is favored (it holds the verdict). Slices snap to whitespace so we
+// don't deliver a half-word at either seam. Grep before adding another truncation site — this is it.
+export function previewDeliveredBody(
+  rawBody: string,
+  messageId: number,
+  maxChars: number = providerMessageBodyMaxChars(),
+): DeliveredBodyPreview {
+  if (rawBody.length <= maxChars) return { body: rawBody, truncated: false, guidance: [] };
+  const fetchLines = [
+    `Read full: agent-relay get-message ${messageId}`,
+    `Body only: agent-relay get-message ${messageId} --body`,
+  ];
+  const marker = (elided: number) => `[… ${elided} chars elided from the middle — full report: relay_get_message #${messageId} …]`;
+  // Reserve room for the marker and its two blank-line joins; upper-bound the marker length by using
+  // the (always-larger) full body length so the reserved budget can never underflow the real marker.
+  const budget = maxChars - marker(rawBody.length).length - 4;
+  if (budget < 200) {
+    // Cap too small to keep a useful head — front-truncate, preserving the tail/verdict whole.
+    const tail = rawBody.slice(rawBody.length - maxChars).replace(/^\S*\s+/, "").trimStart();
+    return {
+      body: tail,
+      truncated: true,
+      guidance: [`[truncated: showing last ${tail.length} of ${rawBody.length} chars — head trimmed, tail/verdict preserved]`, ...fetchLines],
+    };
+  }
+  const headChars = Math.floor(budget * 0.35);
+  const tailChars = budget - headChars;
+  const head = rawBody.slice(0, headChars).replace(/\s+\S*$/, "").trimEnd();
+  const tail = rawBody.slice(rawBody.length - tailChars).replace(/^\S*\s+/, "").trimStart();
+  const elided = rawBody.length - head.length - tail.length;
+  return {
+    body: `${head}\n\n${marker(elided)}\n\n${tail}`,
+    truncated: true,
+    guidance: [`[truncated: showing first ${head.length} + last ${tail.length} of ${rawBody.length} chars — tail/verdict preserved]`, ...fetchLines],
+  };
+}
+
+function attachmentRefs(message: Message): Record<string, unknown>[] {
+  const payloadRefs = message.payload?.attachments;
+  const topLevelRefs = (message as Message & { attachments?: unknown }).attachments;
+  const refs = Array.isArray(payloadRefs) ? payloadRefs : Array.isArray(topLevelRefs) ? topLevelRefs : [];
+  return refs.filter(isRecord);
+}
+
+function attachmentLabel(ref: Record<string, unknown>): string {
+  const parts = [
+    typeof ref.kind === "string" ? ref.kind : undefined,
+    typeof ref.role === "string" ? ref.role : undefined,
+    typeof ref.title === "string" ? `"${ref.title}"` : undefined,
+  ].filter(Boolean);
+  return parts.length ? ` (${parts.join(", ")})` : "";
+}
+
+function attachmentCacheMetadata(ref: Record<string, unknown>): Record<string, unknown> | undefined {
+  const metadata = isRecord(ref.metadata) ? ref.metadata : undefined;
+  const agentRelay = metadata && isRecord(metadata.agentRelay) ? metadata.agentRelay : undefined;
+  return agentRelay;
+}
+
+export function isMemoryInjection(message: Message): boolean {
+  return isRecord(message.payload) && message.payload.memoryInjection === true;
+}
+
+export function isSelfResumeInjection(message: Message): boolean {
+  return isRecord(message.payload) && message.payload.resumeInjection === true;
+}
+
+export function isReactionNotification(message: Message): boolean {
+  const event = isRecord(message.payload?.event) ? message.payload.event : undefined;
+  return message.payload?.reactionNotification === true || event?.type === "message.reaction";
+}
+
+export function isPersistedRelayMessage(message: Message): boolean {
+  return Number.isSafeInteger(message.id) && message.id > 0;
+}
+
+// #283 — one-line nudge that replaces the reply-scaffold footer for notification-class
+// (replyExpected:false) messages. Deliberately tiny so a bloated context can't drown the
+// no-reply rule established at session start. Shared with the Claude delivery path.
+export const NOTIFICATION_NUDGE = "↪ Notification — no reply needed.";
+
+// A notification is a persisted message the server marked replyExpected:false.
+export function isNotificationMessage(message: Message): boolean {
+  return isPersistedRelayMessage(message) && message.replyExpected === false;
+}
+
+export function isSpawnObligationMessage(message: Message): boolean {
+  return isRecord(message.payload) && message.payload.source === "spawn-obligation";
+}
+
+export function latestReplyableMessage(messages: Message[]): Message | undefined {
+  return messages
+    .filter((message) => isPersistedRelayMessage(message) && !isMemoryInjection(message) && !isReactionNotification(message) && !isSpawnObligationMessage(message) && message.replyExpected !== false)
+    .at(-1);
+}
+
+export function dedupePersistedMessages(messages: Message[]): Message[] {
+  const seen = new Set<number>();
+  return messages.filter((message) => {
+    if (!isPersistedRelayMessage(message)) return true;
+    if (seen.has(message.id)) return false;
+    seen.add(message.id);
+    return true;
+  });
+}
+
+/** A human wrote it: a human address, or a prompt parked on a human's behalf (#3415). */
+export function isHumanSenderMessage(message: Message): boolean {
+  return isHumanAgentId(heldForSender(message) ?? message.from);
+}
+
+export function providerSenderLabel(message: Message): string {
+  const heldFor = heldForSender(message);
+  if (heldFor) return isHumanAgentId(heldFor) ? "human user" : heldFor;
+  if (isHumanAgentId(message.from)) return "human user";
+  const source = isRecord(message.payload?.source) ? message.payload.source : undefined;
+  const isHumanChannel = Boolean(source && (
+    isRecord(source.telegram) ||
+    isRecord(source.slack) ||
+    isRecord(source.discord)
+  ));
+  return isHumanChannel ? `human user via ${message.from}` : message.from;
+}
+
+/** `imagePaths`: cached attachment paths the prompt text lists (#2664). */
+export interface PromptOfferOptions { readyTimeoutMs?: number; isInitial?: boolean; imagePaths?: string[]; inputObserver?: ProviderInputObserver }
+
+/** A parked prompt's attachment paths, carried on its inbox row so the redelivery keeps them (#2664). */
+export const HELD_PROMPT_IMAGE_PATHS = "heldPromptImagePaths";
+
+/** Local cache paths of the messages' attachments, as providerAttachmentText lists them. */
+export function providerAttachmentLocalPaths(messages: Message[]): string[] {
+  return messages.flatMap((message) => {
+    const held = isRecord(message.payload) ? message.payload[HELD_PROMPT_IMAGE_PATHS] : undefined;
+    return [...attachmentRefs(message).flatMap((ref) => {
+      const localPath = attachmentCacheMetadata(ref)?.localPath;
+      return typeof localPath === "string" ? [localPath] : [];
+    }), ...(Array.isArray(held) ? held.filter((path): path is string => typeof path === "string") : [])];
+  });
+}
+
+export function providerAttachmentText(message: Message): string | undefined {
+  const refs = attachmentRefs(message);
+  if (!refs.length) return undefined;
+  const refLines = refs.flatMap((ref) => {
+    const artifactId = typeof ref.artifactId === "string" ? ref.artifactId : "unknown-artifact";
+    const source = isRecord(ref.ref)
+      ? [
+        typeof ref.ref.provider === "string" ? ref.ref.provider : undefined,
+        typeof ref.ref.id === "string" ? ref.ref.id : undefined,
+      ].filter(Boolean).join(":")
+      : "";
+    const cache = attachmentCacheMetadata(ref);
+    const localPath = typeof cache?.localPath === "string" ? cache.localPath : undefined;
+    const cacheError = typeof cache?.cacheError === "string" ? cache.cacheError : undefined;
+    return [
+      `- ${artifactId}${attachmentLabel(ref)}${source ? ` source=${source}` : ""}`,
+      ...(localPath ? [`  local: ${localPath}`] : []),
+      ...(cacheError ? [`  cache error: ${cacheError}`] : []),
+    ];
+  });
+  const hasLocalPaths = refs.some((ref) => typeof attachmentCacheMetadata(ref)?.localPath === "string");
+  const canFetchMessage = isPersistedRelayMessage(message);
+  const guidance = !canFetchMessage
+    ? []
+    : hasLocalPaths
+    ? [
+      "Use the local path above when inspecting the attachment.",
+      `Read attachment details: agent-relay get-message ${message.id} --json`,
+    ]
+    : [
+      `Read attachment details: agent-relay get-message ${message.id} --json`,
+      `Fetch content: curl -fsS -H "X-Agent-Relay-Token: $AGENT_RELAY_TOKEN" "$AGENT_RELAY_URL/api/artifacts/<artifactId>/content" -o <filename>`,
+    ];
+  return [
+    "Attachments:",
+    ...refLines,
+    ...guidance,
+  ].join("\n");
+}
+
+export function providerMessageText(messages: Message[]): string {
+  const uniqueMessages = dedupePersistedMessages(messages);
+  const maxChars = providerMessageBodyMaxChars();
+  const sections = uniqueMessages
+    .map((message) => {
+      const subject = message.subject ? `Subject: ${message.subject}\n` : "";
+      const isMemoryContext = isMemoryInjection(message);
+      const canReferenceMessage = isPersistedRelayMessage(message) && !isMemoryContext && !isReactionNotification(message);
+      const preview = canReferenceMessage
+        ? previewDeliveredBody(message.body, message.id, maxChars)
+        : { body: message.body, truncated: false, guidance: [] };
+      const truncationGuidance = preview.truncated
+        ? preview.guidance.join("\n")
+        : undefined;
+      if (isMemoryContext) {
+        return [
+          `[agent-relay ${isSelfResumeInjection(message) ? "self-resume continuation" : "context"} from ${message.from}]`,
+          providerAttachmentText(message),
+          `${subject}${preview.body}`,
+        ].join("\n");
+      }
+      return [
+        receivesTurnResponseAutomatically(message.from) ? undefined : `[relay message #${message.id} from ${providerSenderLabel(message)}]`,
+        truncationGuidance,
+        providerAttachmentText(message),
+        `${subject}${preview.body}`,
+      ].filter(Boolean).join("\n");
+    });
+  if (uniqueMessages.length > 0 && uniqueMessages.every(message => isNotificationMessage(message) && !receivesTurnResponseAutomatically(message.from))) {
+    sections.push(NOTIFICATION_NUDGE);
+  }
+  return sections.join("\n\n");
+}