circuschief 0.1.0

package/packages/shared/src/contracts/kanban.js

@@ -0,0 +1,142 @@
+import { z } from 'zod';
+
+// Board contracts
+export const KanbanBoardResponse = z.object({
+  id: z.string().uuid(),
+  projectId: z.string().uuid(),
+  lanes: z.lazy(() => z.array(KanbanLaneResponse)),
+  createdAt: z.number(),
+  updatedAt: z.number(),
+});
+
+// Lane contracts
+export const CreateKanbanLaneRequest = z.object({
+  name: z.string().min(1),
+  sortOrder: z.number().optional(),
+  onEnterTemplateId: z.string().uuid().nullable().optional(),
+  onEnterPrompt: z.string().nullable().optional(),
+  onEnterMode: z.enum(['plan', 'standard', 'yolo']).nullable().optional(),
+  onEnterModel: z.string().nullable().optional(),
+  onEnterEffortLevel: z.enum(['low', 'medium', 'high', 'max', 'auto']).nullable().optional(),
+  onEnterThinkingEnabled: z.boolean().nullable().optional(),
+  onEnterAutoRescheduleEnabled: z.boolean().optional(),
+  onEnterRescheduleDelayMinutes: z.number().optional(),
+  onEnterRescheduleOnTokenLimit: z.boolean().optional(),
+  onEnterRescheduleOnServiceError: z.boolean().optional(),
+  onEnterMaxRescheduleCount: z.number().nullable().optional(),
+  onEnterMaxTotalTokens: z.number().nullable().optional(),
+  onEnterRescheduleAtTokenCount: z.number().nullable().optional(),
+}).refine(
+  (data) => {
+    // Mutual exclusivity: can't have both template and prompt set
+    const hasTemplate = data.onEnterTemplateId != null;
+    const hasPrompt = data.onEnterPrompt != null && data.onEnterPrompt.trim() !== '';
+    return !(hasTemplate && hasPrompt);
+  },
+  {
+    message: 'Cannot set both onEnterTemplateId and onEnterPrompt. Choose one automation type.',
+    path: ['onEnterPrompt'],
+  }
+);
+
+export const UpdateKanbanLaneRequest = z.object({
+  name: z.string().min(1).optional(),
+  sortOrder: z.number().optional(),
+  onEnterTemplateId: z.string().uuid().nullable().optional(),
+  onEnterPrompt: z.string().nullable().optional(),
+  onEnterMode: z.enum(['plan', 'standard', 'yolo']).nullable().optional(),
+  onEnterModel: z.string().nullable().optional(),
+  onEnterEffortLevel: z.enum(['low', 'medium', 'high', 'max', 'auto']).nullable().optional(),
+  onEnterThinkingEnabled: z.boolean().nullable().optional(),
+  onEnterAutoRescheduleEnabled: z.boolean().optional(),
+  onEnterRescheduleDelayMinutes: z.number().optional(),
+  onEnterRescheduleOnTokenLimit: z.boolean().optional(),
+  onEnterRescheduleOnServiceError: z.boolean().optional(),
+  onEnterMaxRescheduleCount: z.number().nullable().optional(),
+  onEnterMaxTotalTokens: z.number().nullable().optional(),
+  onEnterRescheduleAtTokenCount: z.number().nullable().optional(),
+}).refine(
+  (data) => {
+    // Mutual exclusivity: can't have both template and prompt set
+    const hasTemplate = data.onEnterTemplateId != null;
+    const hasPrompt = data.onEnterPrompt != null && data.onEnterPrompt.trim() !== '';
+    return !(hasTemplate && hasPrompt);
+  },
+  {
+    message: 'Cannot set both onEnterTemplateId and onEnterPrompt. Choose one automation type.',
+    path: ['onEnterPrompt'],
+  }
+);
+
+export const ReorderKanbanLanesRequest = z.array(z.string().uuid());
+
+export const KanbanLaneResponse = z.object({
+  id: z.string().uuid(),
+  boardId: z.string().uuid(),
+  name: z.string(),
+  sortOrder: z.number(),
+  onEnterTemplateId: z.string().uuid().nullable(),
+  onEnterPrompt: z.string().nullable(),
+  onEnterMode: z.enum(['plan', 'standard', 'yolo']).nullable(),
+  onEnterModel: z.string().nullable(),
+  onEnterEffortLevel: z.enum(['low', 'medium', 'high', 'max', 'auto']).nullable(),
+  onEnterThinkingEnabled: z.boolean().nullable(),
+  onEnterAutoRescheduleEnabled: z.boolean(),
+  onEnterRescheduleDelayMinutes: z.number().nullable(),
+  onEnterRescheduleOnTokenLimit: z.boolean().nullable(),
+  onEnterRescheduleOnServiceError: z.boolean().nullable(),
+  onEnterMaxRescheduleCount: z.number().nullable(),
+  onEnterMaxTotalTokens: z.number().nullable(),
+  onEnterRescheduleAtTokenCount: z.number().nullable(),
+  createdAt: z.number(),
+  updatedAt: z.number(),
+});
+
+// Card contracts
+export const CreateKanbanCardRequest = z.object({
+  sessionId: z.string().uuid(),
+  laneId: z.string().uuid(),
+});
+
+export const MoveKanbanCardRequest = z.object({
+  targetLaneId: z.string().uuid(),
+  sortOrder: z.number().optional(),
+  runOnEnterTemplate: z.boolean().default(true),
+});
+
+export const ReorderKanbanCardsRequest = z.array(z.string().uuid());
+
+// Card session info
+export const KanbanCardSessionResponse = z.object({
+  id: z.string().uuid(),
+  name: z.string(),
+  status: z.string(),
+  mode: z.string().optional(),
+  costUsd: z.number().optional(),
+  starred: z.boolean().optional(),
+  prUrl: z.string().nullable().optional(),
+  createdAt: z.number(),
+  updatedAt: z.number(),
+});
+
+export const KanbanCardResponse = z.object({
+  id: z.string().uuid(),
+  laneId: z.string().uuid(),
+  sortOrder: z.number(),
+  sessions: z.array(KanbanCardSessionResponse),
+  createdAt: z.number(),
+  updatedAt: z.number(),
+});
+
+// Full board with lanes and cards
+export const KanbanFullBoardResponse = z.object({
+  id: z.string().uuid(),
+  projectId: z.string().uuid(),
+  lanes: z.array(
+    KanbanLaneResponse.extend({
+      cards: z.array(KanbanCardResponse),
+    })
+  ),
+  createdAt: z.number(),
+  updatedAt: z.number(),
+});

package/packages/shared/src/contracts/projects.js

@@ -0,0 +1,63 @@
+import { z } from 'zod';
+
+export const CreateProjectRequest = z.object({
+  name: z.string().min(1),
+  workingDirectory: z.string().min(1),
+  systemPrompt: z.string().nullable().optional(),
+  onSessionCreated: z.string().nullable().optional(),
+  onSessionDeleted: z.string().nullable().optional(),
+  prPollInterval: z.number().int().min(10000).optional(), // Min 10 seconds
+  repoUrl: z.string().url().nullable().optional(),
+  kanbanEnabled: z.boolean().optional(), // Default true
+});
+
+export const UpdateProjectRequest = z.object({
+  name: z.string().min(1).optional(),
+  workingDirectory: z.string().min(1).optional(),
+  systemPrompt: z.string().nullable().optional(),
+  onSessionCreated: z.string().nullable().optional(),
+  onSessionDeleted: z.string().nullable().optional(),
+  prPollInterval: z.number().int().min(10000).optional(), // Min 10 seconds
+  repoUrl: z.string().url().nullable().optional(),
+  kanbanEnabled: z.boolean().optional(),
+});
+
+export const ProjectResponse = z.object({
+  id: z.string().uuid(),
+  name: z.string(),
+  workingDirectory: z.string(),
+  systemPrompt: z.string().nullable(),
+  onSessionCreated: z.string().nullable(),
+  onSessionDeleted: z.string().nullable(),
+  prPollInterval: z.number().int(),
+  repoUrl: z.string().url().nullable().optional(),
+  kanbanEnabled: z.boolean(),
+  createdAt: z.number(),
+  updatedAt: z.number(),
+});
+
+export const ProjectListResponse = z.array(ProjectResponse);
+
+export const ProjectSessionDefaultsRequest = z.object({
+  mode: z.enum(['plan', 'standard', 'yolo']).nullable().optional(),
+  thinkingEnabled: z.boolean().nullable().optional(),
+  effortLevel: z.enum(['low', 'medium', 'high', 'max', 'auto']).nullable().optional(),
+  startImmediately: z.boolean().nullable().optional(),
+  gitMode: z.enum(['branch', 'worktree']).nullable().optional(),
+  gitBranch: z.string().nullable().optional(),
+  model: z.string().nullable().optional(),
+});
+
+export const ProjectSessionDefaultsResponse = z.object({
+  id: z.string().uuid(),
+  projectId: z.string().uuid(),
+  mode: z.enum(['plan', 'standard', 'yolo']).nullable(),
+  thinkingEnabled: z.boolean().nullable(),
+  effortLevel: z.enum(['low', 'medium', 'high', 'max', 'auto']).nullable(),
+  startImmediately: z.boolean().nullable(),
+  gitMode: z.enum(['branch', 'worktree']).nullable(),
+  gitBranch: z.string().nullable(),
+  model: z.string().nullable(),
+  createdAt: z.number(),
+  updatedAt: z.number(),
+});

package/packages/shared/src/contracts/providers.js

@@ -0,0 +1,81 @@
+import { z } from 'zod';
+
+export const CreateProviderRequest = z.object({
+  name: z.string().min(1).max(100),
+  baseUrl: z.string().url().nullable().optional(),
+  authToken: z.string().nullable().optional(),
+  apiTimeoutMs: z.number().int().positive().nullable().optional(),
+  additionalEnvVars: z.record(z.string()).nullable().optional(),
+});
+
+export const UpdateProviderRequest = z.object({
+  name: z.string().min(1).max(100).optional(),
+  baseUrl: z.string().url().nullable().optional(),
+  authToken: z.string().nullable().optional(),
+  apiTimeoutMs: z.number().int().positive().nullable().optional(),
+  additionalEnvVars: z.record(z.string()).nullable().optional(),
+});
+
+export const ProviderResponse = z.object({
+  id: z.string().uuid(),
+  name: z.string(),
+  baseUrl: z.string().nullable(),
+  authToken: z.string().nullable(), // Will be redacted in API responses
+  apiTimeoutMs: z.number().nullable(),
+  additionalEnvVars: z.record(z.string()).nullable(),
+  isBuiltIn: z.boolean(),
+  createdAt: z.number(),
+  updatedAt: z.number(),
+  models: z.array(
+    z.object({
+      id: z.string().uuid(),
+      providerId: z.string().uuid(),
+      modelId: z.string(),
+      displayName: z.string(),
+      description: z.string().nullable(),
+      tier: z.enum(['opus', 'sonnet', 'haiku', 'custom']),
+      createdAt: z.number(),
+    })
+  ),
+});
+
+export const ProviderListResponse = z.array(ProviderResponse);
+
+export const CreateProviderModelRequest = z.object({
+  modelId: z.string().min(1),
+  displayName: z.string().min(1).max(100),
+  description: z.string().nullable().optional(),
+  tier: z.enum(['opus', 'sonnet', 'haiku', 'custom']).nullable().optional(),
+});
+
+export const ProviderModelResponse = z.object({
+  id: z.string().uuid(),
+  providerId: z.string().uuid(),
+  modelId: z.string(),
+  displayName: z.string(),
+  description: z.string().nullable(),
+  tier: z.string().nullable(),
+  createdAt: z.number(),
+});
+
+export const ProviderModelListResponse = z.array(ProviderModelResponse);
+
+export const TestConnectionRequest = z.object({
+  baseUrl: z.string().url().nullable().optional(),
+  authToken: z.string().nullable().optional(),
+  defaultSonnetModel: z.string().nullable().optional(),
+  apiTimeoutMs: z.number().int().positive().nullable().optional(),
+});
+
+export const TestConnectionResponse = z.object({
+  success: z.boolean(),
+  message: z.string(),
+  details: z
+    .object({
+      model: z.string().optional(),
+      usage: z.any().optional(),
+      code: z.union([z.string(), z.number()]).optional(),
+      type: z.string().optional(),
+    })
+    .optional(),
+});

package/packages/shared/src/contracts/quickResponses.js

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+
+export const CreateQuickResponseRequest = z.object({
+  label: z.string().min(1, 'Label is required').max(50, 'Label must be 50 characters or less'),
+  content: z.string().min(1, 'Content is required').max(10000, 'Content must be 10000 characters or less'),
+  autoSubmit: z.boolean().optional().default(false),
+  category: z.string().max(50).nullable().optional(),
+  sortOrder: z.number().int().min(0).optional().default(0),
+  isGlobal: z.boolean().optional().default(false),
+});
+
+export const UpdateQuickResponseRequest = z.object({
+  label: z.string().min(1).max(50).optional(),
+  content: z.string().min(1).max(10000).optional(),
+  autoSubmit: z.boolean().optional(),
+  category: z.string().max(50).nullable().optional(),
+  sortOrder: z.number().int().min(0).optional(),
+}).refine((obj) => Object.keys(obj).length > 0, 'At least one field must be provided for update');
+
+export const QuickResponseResponse = z.object({
+  id: z.string(),
+  projectId: z.string().nullable(),
+  label: z.string(),
+  content: z.string(),
+  autoSubmit: z.boolean(),
+  category: z.string().nullable(),
+  sortOrder: z.number().int(),
+  createdAt: z.number(),
+  updatedAt: z.number(),
+});
+
+export const QuickResponseListResponse = z.array(QuickResponseResponse);
+
+export const QuickResponsesForProjectResponse = z.object({
+  project: QuickResponseListResponse,
+  global: QuickResponseListResponse,
+});
+
+export const ReorderQuickResponsesRequest = z.array(
+  z.object({
+    id: z.string(),
+    sortOrder: z.number().int().min(0),
+  })
+);

package/packages/shared/src/contracts/sessions.js

@@ -0,0 +1,112 @@
+import { z } from 'zod';
+
+export const CreateSessionRequest = z.object({
+  prompt: z.string().min(1),
+  name: z.string().optional(),
+  mode: z.enum(['plan', 'standard', 'yolo']).optional(),
+  thinkingEnabled: z.boolean().optional(),
+  effortLevel: z.enum(['low', 'medium', 'high', 'max', 'auto']).optional(),
+  gitBranch: z.string().optional(),
+  gitMode: z.enum(['branch', 'worktree']).optional(),
+  templateId: z.string().uuid().optional(), // Template to apply on session creation
+  nextTemplateId: z.string().uuid().nullable().optional(),
+  // Scheduling fields
+  scheduledAt: z.number().optional(), // Unix timestamp in ms
+  autoRescheduleEnabled: z.boolean().optional(),
+  rescheduleDelayMinutes: z.number().min(5).max(1440).optional(), // 5 min to 24 hours
+  rescheduleOnTokenLimit: z.boolean().optional(),
+  rescheduleOnServiceError: z.boolean().optional(),
+  maxRescheduleCount: z.number().min(1).max(100).nullable().optional(),
+  maxTotalTokens: z.number().min(1000).nullable().optional(),
+  rescheduleAtTokenCount: z.number().min(10000).nullable().optional(), // e.g., 100k, 150k tokens
+});
+
+export const UpdateSessionRequest = z.object({
+  name: z.string().min(1).optional(),
+  manuallyNamed: z.boolean().optional(),
+  thinkingEnabled: z.boolean().optional(),
+  effortLevel: z.enum(['low', 'medium', 'high', 'max', 'auto']).nullable().optional(),
+  status: z.enum(['starting', 'running', 'waiting', 'error', 'stopped', 'scheduled']).optional(),
+  mode: z.enum(['plan', 'standard', 'yolo']).optional(),
+  model: z.string().nullable().optional(),
+  pendingModel: z.string().nullable().optional(),
+  providerId: z.string().uuid().nullable().optional(),
+  nextTemplateId: z.string().uuid().nullable().optional(),
+  // PR URL - GitHub PR URL (e.g., https://github.com/owner/repo/pull/123) or null to clear
+  prUrl: z.string().url().regex(/^https:\/\/github\.com\/[^/]+\/[^/]+\/pull\/\d+$/).nullable().optional(),
+  // Scheduling fields
+  scheduledAt: z.number().nullable().optional(), // Unix timestamp in ms
+  autoRescheduleEnabled: z.boolean().optional(),
+  rescheduleDelayMinutes: z.number().min(5).max(1440).optional(), // 5 min to 24 hours
+  rescheduleOnTokenLimit: z.boolean().optional(),
+  rescheduleOnServiceError: z.boolean().optional(),
+  maxRescheduleCount: z.number().min(1).max(100).nullable().optional(),
+  maxTotalTokens: z.number().min(1000).nullable().optional(),
+  rescheduleCount: z.number().optional(), // For resetting
+  rescheduleAtTokenCount: z.number().min(10000).nullable().optional(),
+  // Kanban fields
+  targetLaneId: z.string().uuid().nullable().optional(), // Lane to move to when turn ends
+});
+
+export const SendMessageRequest = z.object({
+  content: z.string().min(1),
+});
+
+export const SessionResponse = z.object({
+  id: z.string().uuid(),
+  projectId: z.string().uuid(),
+  name: z.string(),
+  status: z.enum(['starting', 'running', 'waiting', 'stopped', 'completed', 'error', 'scheduled']),
+  mode: z.enum(['plan', 'standard', 'yolo']),
+  model: z.string().nullable(),
+  thinkingEnabled: z.boolean(),
+  effortLevel: z.enum(['low', 'medium', 'high', 'max', 'auto']).nullable(),
+  gitBranch: z.string().nullable(),
+  gitWorktree: z.string().nullable(),
+  prUrl: z.string().nullable(),
+  manuallyNamed: z.boolean(),
+  error: z.string().nullable(),
+  nextTemplateId: z.string().uuid().nullable(),
+  parentSessionId: z.string().uuid().nullable(),
+  // Scheduling fields
+  scheduledAt: z.number().nullable(),
+  rescheduleDelayMinutes: z.number(),
+  autoRescheduleEnabled: z.boolean(),
+  rescheduleOnTokenLimit: z.boolean(),
+  rescheduleOnServiceError: z.boolean(),
+  maxRescheduleCount: z.number().nullable(),
+  maxTotalTokens: z.number().nullable(),
+  rescheduleCount: z.number(),
+  rescheduleAtTokenCount: z.number().nullable(),
+  // Kanban fields
+  targetLaneId: z.string().uuid().nullable(),
+  laneTriggerDepth: z.number(),
+  createdAt: z.number(),
+  updatedAt: z.number(),
+  lastActivityAt: z.number(),
+});
+
+export const SessionListResponse = z.array(SessionResponse);
+
+export const AttachmentResponse = z.object({
+  id: z.string().uuid(),
+  messageId: z.string().uuid().nullable(),
+  sessionId: z.string().uuid(),
+  filename: z.string(),
+  mimeType: z.string(),
+  size: z.number(),
+  storageType: z.enum(['base64', 'file_path', 'project_file']).optional(),
+  createdAt: z.number(),
+});
+
+export const ConversationMessageResponse = z.object({
+  id: z.string().uuid(),
+  sessionId: z.string().uuid(),
+  role: z.enum(['user', 'assistant', 'system']),
+  content: z.string(),
+  toolUse: z.array(z.any()).nullable(),
+  attachments: z.array(AttachmentResponse).optional(),
+  timestamp: z.number(),
+});
+
+export const ConversationListResponse = z.array(ConversationMessageResponse);

package/packages/shared/src/contracts/templates.js

@@ -0,0 +1,51 @@
+import { z } from 'zod';
+
+export const CreateSessionTemplateRequest = z.object({
+  name: z.string().min(1),
+  prompt: z.string().min(1),
+  nextTemplateId: z.string().uuid().nullable().optional(),
+  thinkingEnabled: z.boolean().nullable().optional(),
+  gitBranch: z.string().nullable().optional(),
+  gitMode: z.enum(['branch', 'worktree']).nullable().optional(),
+  model: z.string().nullable().optional(),
+  mode: z.enum(['plan', 'standard', 'yolo']).nullable().optional(),
+  effortLevel: z.enum(['low', 'medium', 'high', 'max', 'auto']).nullable().optional(),
+  targetLaneId: z.string().uuid().nullable().optional(), // Lane to place session in when created from this template
+});
+
+export const UpdateSessionTemplateRequest = z.object({
+  name: z.string().min(1).optional(),
+  prompt: z.string().min(1).optional(),
+  nextTemplateId: z.string().uuid().nullable().optional(),
+  thinkingEnabled: z.boolean().nullable().optional(),
+  gitBranch: z.string().nullable().optional(),
+  gitMode: z.enum(['branch', 'worktree']).nullable().optional(),
+  model: z.string().nullable().optional(),
+  mode: z.enum(['plan', 'standard', 'yolo']).nullable().optional(),
+  effortLevel: z.enum(['low', 'medium', 'high', 'max', 'auto']).nullable().optional(),
+  targetLaneId: z.string().uuid().nullable().optional(),
+});
+
+export const SessionTemplateResponse = z.object({
+  id: z.string().uuid(),
+  projectId: z.string().uuid().nullable(),
+  name: z.string(),
+  prompt: z.string(),
+  nextTemplateId: z.string().uuid().nullable(),
+  thinkingEnabled: z.boolean().nullable(),
+  gitBranch: z.string().nullable(),
+  gitMode: z.string().nullable(),
+  model: z.string().nullable(),
+  mode: z.string().nullable(),
+  effortLevel: z.enum(['low', 'medium', 'high', 'max', 'auto']).nullable(),
+  targetLaneId: z.string().uuid().nullable(),
+  createdAt: z.number(),
+  updatedAt: z.number(),
+});
+
+export const SessionTemplateListResponse = z.array(SessionTemplateResponse);
+
+export const AvailableTemplatesResponse = z.object({
+  project: SessionTemplateListResponse,
+  global: SessionTemplateListResponse,
+});

package/packages/shared/src/index.js

@@ -0,0 +1,5 @@
+export * from './types.js';
+export * from './protocol.js';
+export * from './constants.js';
+export * from './utils.js';
+export * from './contracts/canvas.js';

package/packages/shared/src/protocol.js

@@ -0,0 +1,76 @@
+/**
+ * WebSocket message types
+ */
+
+export const WS_MESSAGE_TYPES = {
+  // Client -> Server
+  SUBSCRIBE_SESSION: 'subscribe:session',
+  UNSUBSCRIBE_SESSION: 'unsubscribe:session',
+  SUBSCRIBE_PROJECT: 'subscribe:project',
+  UNSUBSCRIBE_PROJECT: 'unsubscribe:project',
+
+  // Server -> Client
+  SESSION_CREATED: 'session:created',
+  SESSION_STATUS: 'session:status',
+  SESSION_MESSAGE: 'session:message',
+  SESSION_PARTIAL: 'session:partial',
+  SESSION_ERROR: 'session:error',
+  SESSION_DELETED: 'session:deleted',
+  SESSION_WORK_LOG: 'session:work_log',
+  SESSION_WORK_LOGS_ASSOCIATED: 'session:work_logs_associated',
+  SESSION_THINKING_PARTIAL: 'session:thinking_partial',
+  SESSION_SUMMARY_UPDATED: 'session:summary_updated',
+  SESSION_SUMMARY_GENERATING: 'session:summary_generating',
+  SESSION_UPDATED: 'session:updated',
+  CANVAS_ADD: 'canvas:add',
+  CANVAS_REMOVE: 'canvas:remove',
+  CANVAS_UPDATE: 'canvas:update',
+  TODOS_UPDATE: 'todos:update',
+  CHANGES_UPDATE: 'changes:update',
+
+  // Conversation events
+  CONVERSATION_CREATED: 'conversation:created',
+  CONVERSATION_UPDATED: 'conversation:updated',
+  CONVERSATION_DELETED: 'conversation:deleted',
+
+  // Usage events
+  SESSION_USAGE_UPDATE: 'session:usage_update',
+
+  // Command button events
+  COMMAND_RUN_OUTPUT: 'command:run:output',
+  COMMAND_RUN_COMPLETE: 'command:run:complete',
+  COMMAND_RUN_ERROR: 'command:run:error',
+  COMMAND_RUN_DELETED: 'command:run:deleted',
+
+  // System metrics events
+  SYSTEM_METRICS: 'system:metrics',
+
+  // Kanban events
+  KANBAN_BOARD_UPDATED: 'kanban:board_updated',
+  KANBAN_CARD_MOVED: 'kanban:card_moved',
+  KANBAN_CARD_ADDED: 'kanban:card_added',
+  KANBAN_CARD_REMOVED: 'kanban:card_removed',
+};
+
+/**
+ * Create a WebSocket message
+ * @param {string} type
+ * @param {Object} payload
+ * @returns {string}
+ */
+export function createMessage(type, payload) {
+  return JSON.stringify({ type, ...payload });
+}
+
+/**
+ * Parse a WebSocket message
+ * @param {string} data
+ * @returns {{ type: string, [key: string]: any } | null}
+ */
+export function parseMessage(data) {
+  try {
+    return JSON.parse(data);
+  } catch {
+    return null;
+  }
+}

package/packages/shared/src/routeParams.js

@@ -0,0 +1,36 @@
+/**
+ * Route parameter names used throughout the application
+ * This file serves as a single source of truth for route parameter names
+ * to prevent mismatches between route definitions and component implementations
+ */
+
+export const ROUTE_PARAMS = {
+  // Projects - NOTE: Inconsistent naming - some routes use :id, others use :projectId
+  // TODO: Standardize to use :projectId consistently
+  PROJECT_ID: 'projectId', // Used in command-buttons routes
+  PROJECT_ID_ALT: 'id', // Used in sessions, edit routes - needs migration
+
+  // Command Buttons
+  BUTTON_ID: 'buttonId',
+
+  // Sessions
+  SESSION_ID: 'id', // Used in /sessions/:id/:tab?
+  SESSION_TAB: 'tab',
+};
+
+/**
+ * Validates that a route has expected parameters
+ * Useful for testing route configurations
+ */
+export function validateRouteParams(route, expectedParams) {
+  const actual = Object.keys(route.params || {});
+  const missing = expectedParams.filter((p) => !actual.includes(p));
+
+  if (missing.length > 0) {
+    throw new Error(
+      `Route ${route.path} is missing expected params: ${missing.join(', ')}. Got: ${actual.join(', ')}`
+    );
+  }
+
+  return true;
+}