feat: single-source cross-app wire contracts in @boocode/contracts (v2.7.13)

Move all hand-synced cross-app wire contracts into one built workspace
package, @boocode/contracts, consumed by server/web/coder/coder-web via
workspace:* + a per-subpath exports map. The ws-frames and provider-config
Zod schemas are schema-first (z.infer); MessageMetadata, ErrorReason,
AgentSessionConfig, the provider snapshot types, and WorktreeRiskReport are
each single-sourced. Deletes the byte-identical copies and their parity
tests, fixes a live AgentSessionConfig drift (coder dead copy removed,
unified to the web required/nullable shape), removes the dead pending_change
WS arms in the fallback SPA, and inverts the build order (contracts builds
first) across root build, Dockerfile, and the coder deploy docs. Reverses
the shared-package decision declined in v2.5.12.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

packages/contracts/src/__tests__/ws-frames.test.ts

@@ -0,0 +1,136 @@
+import { describe, it, expect } from 'vitest';
+import { WsFrameSchema, KNOWN_FRAME_TYPES } from '../ws-frames.js';
+
+const VALID_UUID_A = '00000000-0000-0000-0000-000000000001';
+const VALID_UUID_B = '00000000-0000-0000-0000-000000000002';
+const VALID_UUID_C = '00000000-0000-0000-0000-000000000003';
+const VALID_TIMESTAMP = '2026-05-22T14:30:00.000Z';
+
+describe('WsFrameSchema (v1.13.11-a)', () => {
+  it('accepts a well-formed chat_status frame', () => {
+    const result = WsFrameSchema.safeParse({
+      type: 'chat_status',
+      chat_id: VALID_UUID_A,
+      status: 'streaming',
+      at: VALID_TIMESTAMP,
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it('rejects an unknown frame type', () => {
+    const result = WsFrameSchema.safeParse({
+      type: 'cosmic_ray_strike',
+      chat_id: VALID_UUID_A,
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects a chat_status frame with invalid status enum', () => {
+    // v1.12.1 dropped the legacy 'working' status. Any frame still emitting it
+    // should fail validation — that's a drift catcher.
+    const result = WsFrameSchema.safeParse({
+      type: 'chat_status',
+      chat_id: VALID_UUID_A,
+      status: 'working',
+      at: VALID_TIMESTAMP,
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects a UUID field with a non-UUID string', () => {
+    const result = WsFrameSchema.safeParse({
+      type: 'chat_status',
+      chat_id: 'not-a-uuid',
+      status: 'idle',
+      at: VALID_TIMESTAMP,
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects negative token counts in usage frame', () => {
+    const result = WsFrameSchema.safeParse({
+      type: 'usage',
+      message_id: VALID_UUID_A,
+      chat_id: VALID_UUID_B,
+      completion_tokens: -1,
+      ctx_used: 100,
+      ctx_max: 1000,
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it('accepts a usage frame with nullable token counts (pre-v1.13.7 history)', () => {
+    const result = WsFrameSchema.safeParse({
+      type: 'usage',
+      message_id: VALID_UUID_A,
+      chat_id: VALID_UUID_B,
+      completion_tokens: null,
+      ctx_used: null,
+      ctx_max: null,
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it('accepts a tool_result frame with non-UUID tool_call_id (model-emitted)', () => {
+    // Model-emitted tool_call_ids look like "call_abc123", not UUIDs.
+    const result = WsFrameSchema.safeParse({
+      type: 'tool_result',
+      tool_message_id: VALID_UUID_A,
+      chat_id: VALID_UUID_B,
+      tool_call_id: 'call_abc123',
+      output: { whatever: true },
+      truncated: false,
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it('accepts a compacted frame', () => {
+    const result = WsFrameSchema.safeParse({
+      type: 'compacted',
+      session_id: VALID_UUID_A,
+      chat_id: VALID_UUID_B,
+      summary_message_id: VALID_UUID_C,
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it('accepts a session_workspace_updated frame', () => {
+    const result = WsFrameSchema.safeParse({
+      type: 'session_workspace_updated',
+      session_id: VALID_UUID_A,
+      workspace_panes: [{ id: 'p1', kind: 'chat', chatIds: [], activeChatIdx: 0 }],
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it('accepts a message_complete frame with a null model (external coder, no model selected)', () => {
+    // Regression guard: the dispatcher publishes `model: task.model` (string |
+    // null). When null, this MUST validate or publishFrame fail-closes and drops
+    // the whole frame, incl. the status:'complete' transition.
+    const result = WsFrameSchema.safeParse({
+      type: 'message_complete',
+      message_id: VALID_UUID_A,
+      chat_id: VALID_UUID_B,
+      model: null,
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it('every KNOWN_FRAME_TYPES entry has a discriminated branch', () => {
+    // Probe each known type by attempting a minimal valid construction.
+    // Failure here means the union and the KNOWN_FRAME_TYPES list drifted.
+    for (const type of KNOWN_FRAME_TYPES) {
+      const probe = WsFrameSchema.safeParse({ type, __dummy__: true });
+      // We expect FAILURE on every type because we're missing required fields,
+      // but the failure must be ABOUT the missing fields, not about an unknown
+      // type. A "Invalid discriminator value" error means the type isn't in
+      // the union — that's a drift.
+      if (probe.success) continue;
+      const issues = probe.error.issues;
+      const hasInvalidDiscriminator = issues.some(
+        (i) => i.code === 'invalid_union_discriminator',
+      );
+      expect(hasInvalidDiscriminator, `frame type '${type}' is missing from the discriminated union`).toBe(false);
+    }
+  });
+});

packages/contracts/src/index.ts

@@ -0,0 +1,5 @@
+// @boocode/contracts — single source of truth for cross-app wire contracts.
+// Each contract is exported from its own subpath (e.g. @boocode/contracts/ws-frames).
+// This root module is intentionally empty; import from the subpath directly.
+
+export {};

packages/contracts/src/message-metadata.ts

@@ -0,0 +1,45 @@
+// Single source of truth for cross-app message metadata contracts.
+// ErrorReason + MessageMetadata: sentinel shapes stored in messages.metadata
+// and carried on WS frames. AgentSessionConfig: the required/nullable shape
+// used by CoderPane/AgentComposerBar for provider dispatch.
+
+export type ErrorReason =
+  | 'llm_provider_error'
+  | 'tool_execution_failed'
+  | 'summary_after_cap_failed';
+
+export type MessageMetadata =
+  | {
+      kind: 'cap_hit';
+      used: number;
+      limit: number;
+      agent_name: string | null;
+      can_continue: boolean;
+    }
+  | {
+      kind: 'doom_loop';
+      tool_name: string;
+      args: Record<string, unknown>;
+      threshold: number;
+    }
+  | {
+      kind: 'mistake_recovery';
+      failure_kinds: string[];
+      count: number;
+      escalated: boolean;
+      can_continue?: boolean;
+    }
+  | {
+      kind: 'error';
+      error_reason: ErrorReason;
+      error_text: string;
+    };
+
+// Unified definition is the web required/nullable shape (the coder's all-optional
+// copy was dead — zero importers in apps/coder/src).
+export interface AgentSessionConfig {
+  provider: string;
+  model: string;
+  modeId: string | null;
+  thinkingOptionId: string | null;
+}

packages/contracts/src/provider-config.ts

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+
+export const ProviderOverrideSchema = z.object({
+  extends: z.enum(['acp']).optional(),
+  label: z.string().min(1).optional(),
+  description: z.string().optional(),
+  command: z.array(z.string().min(1)).min(1).optional(),
+  env: z.record(z.string()).optional(),
+  enabled: z.boolean().optional(),
+  order: z.number().int().optional(),
+  models: z.array(z.object({ id: z.string(), label: z.string() })).optional(),
+  additionalModels: z.array(z.object({ id: z.string(), label: z.string() })).optional(),
+});
+
+export const CoderProvidersFileSchema = z.object({
+  providers: z.record(ProviderOverrideSchema).default({}),
+});
+
+export const ProviderConfigPatchSchema = z.object({
+  providers: z.record(ProviderOverrideSchema.nullable()).default({}),
+});
+
+export type ProviderOverride = z.infer<typeof ProviderOverrideSchema>;
+export type CoderProvidersFile = z.infer<typeof CoderProvidersFileSchema>;
+export type ProviderConfigPatch = z.infer<typeof ProviderConfigPatchSchema>;

packages/contracts/src/provider-snapshot.ts

@@ -0,0 +1,52 @@
+/** Provider snapshot types — single source of truth. Plain TS, no runtime. */
+
+export interface ProviderMode {
+  id: string;
+  label: string;
+  description?: string;
+  /** Auto-approve tool permissions when this mode is selected. */
+  isUnattended?: boolean;
+}
+
+export interface ThinkingOption {
+  id: string;
+  label: string;
+  isDefault?: boolean;
+}
+
+export interface ProviderModel {
+  id: string;
+  label: string;
+  description?: string;
+  isDefault?: boolean;
+  thinkingOptions?: ThinkingOption[];
+  defaultThinkingOptionId?: string;
+}
+
+// v2.3 phase 2: 'loading' (cache-miss, probe in flight) + 'unavailable'
+// (disabled or not installed) restored alongside the terminal 'ready' | 'error'.
+export type ProviderSnapshotStatus = 'loading' | 'ready' | 'unavailable' | 'error';
+
+export interface AgentCommand {
+  name: string;
+  description?: string;
+  // v2.5.11: 'skill' (plugin skill) vs 'command' (native/CLI slash command).
+  // Drives the icon split in the coder slash menu. Undefined → command.
+  kind?: 'command' | 'skill';
+}
+
+export interface ProviderSnapshotEntry {
+  name: string;
+  label: string;
+  description?: string;
+  transport: string;
+  status: ProviderSnapshotStatus;
+  enabled: boolean;
+  installed: boolean;
+  models: ProviderModel[];
+  modes: ProviderMode[];
+  defaultModeId: string | null;
+  commands: AgentCommand[];
+  error?: string;
+  fetchedAt?: string;
+}

packages/contracts/src/worktree-risk.ts

@@ -0,0 +1,13 @@
+// Single source of truth for the worktree work-loss guard type.
+// WorktreeRiskReport: returned by BooCoder's checkWorktreeWorkAtRisk, passed
+// through the server, and consumed by the web dialog. Three-way contract.
+
+export interface WorktreeRiskReport {
+  worktreePath: string;
+  branch: string;
+  dirty: boolean;
+  unpushed: number; // commits ahead of upstream, or -1 if no upstream is set
+  unmerged: number; // commits on this branch not in the project default branch
+  atRisk: boolean;  // dirty || unmerged > 0 || (upstream && unpushed > 0) || git error
+  error?: string;   // populated on a git failure; presence forces atRisk
+}

packages/contracts/src/ws-frames.ts

@@ -0,0 +1,401 @@
+// Single source of truth for the WebSocket frame Zod runtime schema.
+// Validation runs on send (broker.publishFrame / publishUserFrame) and
+// on receive (apps/web hooks useSessionStream + useUserEvents). Catches
+// silent protocol drift between publisher and consumer.
+//
+// Per-kind payload schemas stay z.unknown() — frame-level drift detection
+// is the goal; deep payload validation is follow-up work.
+
+import { z } from 'zod';
+
+// ---- shared primitives -----------------------------------------------------
+
+const Uuid = z.string().uuid();
+// Tool call IDs are model-emitted (e.g. "call_abc123") — not UUIDs.
+const ToolCallId = z.string().min(1);
+// v1.13.12 fix: postgres returns timestamp columns as JS Date objects, not
+// strings. The publish sites pass them through unchanged, so the schema must
+// tolerate both. preprocess converts Date → ISO string before string-validation;
+// on the web side (where frames arrive via JSON.parse) it's a no-op. Before
+// this fix, every message_complete / session_updated / chat_updated frame
+// failed validation and got dropped — symptoms: token tracking blank in UI,
+// status stuck at 'streaming' tripping the 60s stale-stream banner.
+const IsoTimestamp = z.preprocess(
+  (v) => (v instanceof Date ? v.toISOString() : v),
+  z.string().min(1),
+);
+
+const ChatStatusValue = z.enum([
+  'streaming',
+  'tool_running',
+  'waiting_for_input',
+  'idle',
+  'error',
+]);
+
+// agent-status-normalize (#10): normalized per-(chat,agent) lifecycle status for
+// external coding agents (warm-acp / opencode / claude-sdk / pty). Distinct from
+// ChatStatusValue (native-inference chat lifecycle) — published by BooCoder's
+// dispatcher + permission flow on the per-session channel.
+const AgentStatusValue = z.enum(['working', 'blocked', 'idle', 'error']);
+
+const ErrorReasonValue = z.enum([
+  'llm_provider_error',
+  'doom_loop',
+  'doom_loop_summary_failed',
+  'cap_hit',
+  'cap_hit_summary_failed',
+]);
+
+const MessageRoleValue = z.enum(['user', 'assistant', 'system', 'tool']);
+
+const ToolCallShape = z.object({
+  id: ToolCallId,
+  name: z.string().min(1),
+  args: z.record(z.string(), z.unknown()),
+});
+
+// Free-form bags: opaque to the frame schema; deep validation is out of
+// scope for v1.13.11 (frame-level drift detection is the goal; per-kind
+// payload narrowing is follow-up work). z.unknown() means the consumer
+// must narrow before reading — TypeScript-side this is fine because every
+// consumer already operates on the hand-maintained Project / Chat / Session
+// / WorkspacePane types, and the Zod-typed shape is only used at the
+// publishFrame boundary.
+const OpaqueObject = z.unknown();
+
+// ---- per-session channel frames --------------------------------------------
+
+export const SnapshotFrame = z.object({
+  type: z.literal('snapshot'),
+  messages: z.array(OpaqueObject),
+});
+
+export const MessageStartedFrame = z.object({
+  type: z.literal('message_started'),
+  message_id: Uuid,
+  chat_id: Uuid.optional(),
+  role: MessageRoleValue,
+});
+
+export const DeltaFrame = z.object({
+  type: z.literal('delta'),
+  message_id: Uuid,
+  chat_id: Uuid.optional(),
+  content: z.string(),
+});
+
+export const ReasoningDeltaFrame = z.object({
+  type: z.literal('reasoning_delta'),
+  message_id: Uuid,
+  chat_id: Uuid.optional(),
+  content: z.string(),
+});
+
+export const ToolCallFrame = z.object({
+  type: z.literal('tool_call'),
+  message_id: Uuid,
+  chat_id: Uuid.optional(),
+  tool_call: ToolCallShape,
+});
+
+export const ToolResultFrame = z.object({
+  type: z.literal('tool_result'),
+  tool_message_id: Uuid,
+  chat_id: Uuid.optional(),
+  tool_call_id: ToolCallId,
+  output: z.unknown(),
+  truncated: z.boolean(),
+  error: z.string().optional(),
+});
+
+export const MessageCompleteFrame = z.object({
+  type: z.literal('message_complete'),
+  message_id: Uuid,
+  chat_id: Uuid.optional(),
+  tokens_used: z.number().int().nonnegative().nullable().optional(),
+  ctx_used: z.number().int().nonnegative().nullable().optional(),
+  ctx_max: z.number().int().positive().nullable().optional(),
+  started_at: IsoTimestamp.nullable().optional(),
+  finished_at: IsoTimestamp.nullable().optional(),
+  // nullable: external-coder turns carry task.model, which is null when no
+  // model was selected. This frame is published through the same fail-closed
+  // publishFrame, so null MUST validate or the entire frame (incl. the
+  // status:'complete' transition) is dropped.
+  model: z.string().nullable().optional(),
+  metadata: OpaqueObject.nullable().optional(),
+});
+
+export const UsageFrame = z.object({
+  type: z.literal('usage'),
+  message_id: Uuid,
+  chat_id: Uuid.optional(),
+  completion_tokens: z.number().int().nonnegative().nullable(),
+  ctx_used: z.number().int().nonnegative().nullable(),
+  ctx_max: z.number().int().positive().nullable(),
+});
+
+export const MessagesDeletedFrame = z.object({
+  type: z.literal('messages_deleted'),
+  message_ids: z.array(Uuid),
+  chat_id: Uuid.optional(),
+});
+
+export const ChatRenamedFrame = z.object({
+  type: z.literal('chat_renamed'),
+  chat_id: Uuid,
+  name: z.string(),
+});
+
+export const CompactedFrame = z.object({
+  type: z.literal('compacted'),
+  session_id: Uuid,
+  chat_id: Uuid,
+  summary_message_id: Uuid,
+});
+
+export const ErrorFrame = z.object({
+  type: z.literal('error'),
+  message_id: Uuid.optional(),
+  chat_id: Uuid.optional(),
+  error: z.string(),
+  reason: ErrorReasonValue.optional(),
+});
+
+// ---- per-user channel frames (sidebar refresh) -----------------------------
+
+export const ChatStatusFrame = z.object({
+  type: z.literal('chat_status'),
+  chat_id: Uuid,
+  status: ChatStatusValue,
+  at: IsoTimestamp,
+  reason: ErrorReasonValue.optional(),
+});
+
+export const SessionUpdatedFrame = z.object({
+  type: z.literal('session_updated'),
+  session_id: Uuid,
+  project_id: Uuid,
+  name: z.string(),
+  updated_at: IsoTimestamp,
+});
+
+export const SessionRenamedFrame = z.object({
+  type: z.literal('session_renamed'),
+  session_id: Uuid,
+  name: z.string(),
+});
+
+export const SessionCreatedFrame = z.object({
+  type: z.literal('session_created'),
+  session: OpaqueObject,
+  project_id: Uuid,
+});
+
+export const SessionArchivedFrame = z.object({
+  type: z.literal('session_archived'),
+  session_id: Uuid,
+  project_id: Uuid,
+});
+
+export const SessionDeletedFrame = z.object({
+  type: z.literal('session_deleted'),
+  session_id: Uuid,
+  project_id: Uuid,
+});
+
+export const SessionWorkspaceUpdatedFrame = z.object({
+  type: z.literal('session_workspace_updated'),
+  session_id: Uuid,
+  // v2.6.x: widened from z.array — the payload is now either the legacy bare
+  // WorkspacePane[] OR the WorkspaceState envelope object (panes + tabNumbers +
+  // nextTabNumber + closedPaneStack). z.array alone would fail-closed and drop
+  // every envelope frame at validation.
+  workspace_panes: z.union([z.array(OpaqueObject), z.record(z.unknown())]),
+});
+
+export const ChatCreatedFrame = z.object({
+  type: z.literal('chat_created'),
+  chat: OpaqueObject,
+  session_id: Uuid,
+});
+
+export const ChatUpdatedFrame = z.object({
+  type: z.literal('chat_updated'),
+  chat_id: Uuid,
+  session_id: Uuid,
+  name: z.string().nullable(),
+  updated_at: IsoTimestamp,
+});
+
+export const ChatArchivedFrame = z.object({
+  type: z.literal('chat_archived'),
+  chat_id: Uuid,
+  session_id: Uuid,
+});
+
+export const ChatUnarchivedFrame = z.object({
+  type: z.literal('chat_unarchived'),
+  chat: OpaqueObject,
+});
+
+export const ChatDeletedFrame = z.object({
+  type: z.literal('chat_deleted'),
+  chat_id: Uuid,
+  session_id: Uuid,
+});
+
+export const ProjectCreatedFrame = z.object({
+  type: z.literal('project_created'),
+  project: OpaqueObject,
+});
+
+export const ProjectArchivedFrame = z.object({
+  type: z.literal('project_archived'),
+  project_id: Uuid,
+});
+
+export const ProjectUnarchivedFrame = z.object({
+  type: z.literal('project_unarchived'),
+  project: OpaqueObject,
+});
+
+export const ProjectUpdatedFrame = z.object({
+  type: z.literal('project_updated'),
+  project_id: Uuid,
+  name: z.string(),
+});
+
+export const ProjectDeletedFrame = z.object({
+  type: z.literal('project_deleted'),
+  project_id: Uuid,
+});
+
+const PermissionOptionShape = z.object({
+  option_id: z.string(),
+  label: z.string(),
+});
+
+export const PermissionRequestedFrame = z.object({
+  type: z.literal('permission_requested'),
+  task_id: Uuid,
+  session_id: Uuid,
+  kind: z.enum(['tool', 'question', 'plan', 'elicitation']).optional(),
+  tool_title: z.string().optional(),
+  input: z.record(z.unknown()).optional(),
+  options: z.array(PermissionOptionShape),
+});
+
+export const PermissionResolvedFrame = z.object({
+  type: z.literal('permission_resolved'),
+  task_id: Uuid,
+  session_id: Uuid,
+});
+
+const AgentCommandShape = z.object({
+  name: z.string(),
+  description: z.string().optional(),
+});
+
+export const AgentCommandsFrame = z.object({
+  type: z.literal('agent_commands'),
+  task_id: Uuid,
+  session_id: Uuid,
+  commands: z.array(AgentCommandShape),
+});
+
+// agent-status-normalize (#10): published by BooCoder on the per-session channel
+// when an external agent's normalized status changes (turn start/end, permission
+// block/unblock). Keyed per (chat_id, agent); the frontend tracks the latest per
+// pair and resets on chat switch. `reason` is a free-form discriminator
+// (turn_start / turn_complete / failed / crashed / permission_request /
+// permission_resolved).
+export const AgentStatusUpdatedFrame = z.object({
+  type: z.literal('agent_status_updated'),
+  chat_id: Uuid,
+  agent: z.string().min(1),
+  status: AgentStatusValue,
+  reason: z.string().optional(),
+  at: IsoTimestamp,
+});
+
+// ---- discriminated union ---------------------------------------------------
+
+export const WsFrameSchema = z.discriminatedUnion('type', [
+  // per-session
+  SnapshotFrame,
+  MessageStartedFrame,
+  DeltaFrame,
+  ReasoningDeltaFrame,
+  ToolCallFrame,
+  ToolResultFrame,
+  MessageCompleteFrame,
+  UsageFrame,
+  MessagesDeletedFrame,
+  ChatRenamedFrame,
+  CompactedFrame,
+  ErrorFrame,
+  PermissionRequestedFrame,
+  PermissionResolvedFrame,
+  AgentCommandsFrame,
+  AgentStatusUpdatedFrame,
+  // per-user
+  ChatStatusFrame,
+  SessionUpdatedFrame,
+  SessionRenamedFrame,
+  SessionCreatedFrame,
+  SessionArchivedFrame,
+  SessionDeletedFrame,
+  SessionWorkspaceUpdatedFrame,
+  ChatCreatedFrame,
+  ChatUpdatedFrame,
+  ChatArchivedFrame,
+  ChatUnarchivedFrame,
+  ChatDeletedFrame,
+  ProjectCreatedFrame,
+  ProjectArchivedFrame,
+  ProjectUnarchivedFrame,
+  ProjectUpdatedFrame,
+  ProjectDeletedFrame,
+]);
+
+export type WsFrame = z.infer<typeof WsFrameSchema>;
+
+// Convenience: the set of known frame types. Useful for the publishFrame
+// helper to log the offending type name when validation fails. Kept in sync
+// by the drift test in src/__tests__/ws-frames.test.ts.
+export const KNOWN_FRAME_TYPES: readonly WsFrame['type'][] = [
+  'snapshot',
+  'message_started',
+  'delta',
+  'reasoning_delta',
+  'tool_call',
+  'tool_result',
+  'message_complete',
+  'usage',
+  'messages_deleted',
+  'chat_renamed',
+  'compacted',
+  'error',
+  'permission_requested',
+  'permission_resolved',
+  'agent_commands',
+  'agent_status_updated',
+  'chat_status',
+  'session_updated',
+  'session_renamed',
+  'session_created',
+  'session_archived',
+  'session_deleted',
+  'session_workspace_updated',
+  'chat_created',
+  'chat_updated',
+  'chat_archived',
+  'chat_unarchived',
+  'chat_deleted',
+  'project_created',
+  'project_archived',
+  'project_unarchived',
+  'project_updated',
+  'project_deleted',
+] as const;