@cleocode/contracts 2.0.0

package/src/session.ts

@@ -0,0 +1,157 @@
+/**
+ * Session type definitions for CLEO V2.
+ *
+ * Plain TypeScript interfaces derived from the Drizzle/Zod schemas
+ * in src/store/validation-schemas.ts. Contracts must not depend on Zod/Drizzle.
+ *
+ * @epic T4454
+ */
+
+import type { SessionStatus } from './status-registry.js';
+export type { SessionStatus };
+
+/** Session scope JSON blob shape. */
+export interface SessionScope {
+  type: string;
+  epicId?: string;
+  rootTaskId?: string;
+  includeDescendants?: boolean;
+  phaseFilter?: string | null;
+  labelFilter?: string[] | null;
+  maxDepth?: number | null;
+  explicitTaskIds?: string[] | null;
+  excludeTaskIds?: string[] | null;
+  computedTaskIds?: string[];
+  computedAt?: string;
+}
+
+/** Session statistics. */
+export interface SessionStats {
+  tasksCompleted: number;
+  tasksCreated: number;
+  tasksUpdated: number;
+  focusChanges: number;
+  totalActiveMinutes: number;
+  suspendCount: number;
+}
+
+/** Active task work state within a session. */
+export interface SessionTaskWork {
+  taskId: string | null;
+  setAt: string | null;
+}
+
+/** Session domain type — plain interface aligned with Drizzle sessions table. */
+export interface Session {
+  id: string;
+  name: string;
+  status: SessionStatus;
+  scope: SessionScope;
+  taskWork: SessionTaskWork;
+  startedAt: string;
+  endedAt?: string;
+  agent?: string;
+  notes?: string[];
+  tasksCompleted?: string[];
+  tasksCreated?: string[];
+  handoffJson?: string | null;
+  previousSessionId?: string | null;
+  nextSessionId?: string | null;
+  agentIdentifier?: string | null;
+  handoffConsumedAt?: string | null;
+  handoffConsumedBy?: string | null;
+  debriefJson?: string | null;
+  stats?: SessionStats;
+  resumeCount?: number;
+  gradeMode?: boolean;
+  providerId?: string | null;
+}
+
+/**
+ * Result of a session start operation.
+ *
+ * The `sessionId` field is a convenience alias for `session.id`,
+ * provided for consumers that expect it at the top level of the result.
+ */
+export interface SessionStartResult {
+  session: Session;
+  sessionId: string;
+}
+
+/**
+ * SessionView — typed wrapper over Session[] with collection helpers.
+ *
+ * Provides discoverable query methods for common session lookups.
+ * Does NOT change the DataAccessor interface — consumers create views from Session[].
+ */
+export class SessionView {
+  private readonly _sessions: Session[];
+
+  constructor(sessions: Session[]) {
+    this._sessions = sessions;
+  }
+
+  /** Create a SessionView from a Session array. */
+  static from(sessions: Session[]): SessionView {
+    return new SessionView(sessions);
+  }
+
+  /** All sessions in the view (readonly). */
+  get all(): readonly Session[] {
+    return this._sessions;
+  }
+
+  /** Number of sessions. */
+  get length(): number {
+    return this._sessions.length;
+  }
+
+  /** Find the currently active session (if any). */
+  findActive(): Session | undefined {
+    return this._sessions.find((s) => s.status === 'active');
+  }
+
+  /** Find a session by ID. */
+  findById(id: string): Session | undefined {
+    return this._sessions.find((s) => s.id === id);
+  }
+
+  /** Filter sessions by one or more statuses. */
+  filterByStatus(...statuses: SessionStatus[]): Session[] {
+    return this._sessions.filter((s) => (statuses as string[]).includes(s.status));
+  }
+
+  /** Find sessions matching a scope type and optional rootTaskId. */
+  findByScope(type: string, rootTaskId?: string): Session[] {
+    return this._sessions.filter((s) => {
+      if (s.scope?.type !== type) return false;
+      if (rootTaskId && s.scope?.rootTaskId !== rootTaskId) return false;
+      return true;
+    });
+  }
+
+  /** Sort sessions by a date field. Returns a new array (does not mutate). */
+  sortByDate(field: 'startedAt' | 'endedAt', descending = true): Session[] {
+    return [...this._sessions].sort((a, b) => {
+      const aDate = new Date(a[field] || '').getTime();
+      const bDate = new Date(b[field] || '').getTime();
+      return descending ? bDate - aDate : aDate - bDate;
+    });
+  }
+
+  /** Get the most recently started session. */
+  mostRecent(): Session | undefined {
+    if (this._sessions.length === 0) return undefined;
+    return this.sortByDate('startedAt', true)[0];
+  }
+
+  /** Convert back to a plain Session array (shallow copy). */
+  toArray(): Session[] {
+    return [...this._sessions];
+  }
+
+  /** Support for-of iteration. */
+  [Symbol.iterator](): Iterator<Session> {
+    return this._sessions[Symbol.iterator]();
+  }
+}

package/src/spawn-types.ts

@@ -0,0 +1,140 @@
+/**
+ * CLEO Spawn Adapter Types
+ *
+ * Type definitions for the spawn adapter system that wraps/extends
+ * CAAMP SpawnAdapter interface. Self-contained version for contracts
+ * (no dependency on @cleocode/caamp).
+ *
+ * @task T5236
+ * @phase 1B
+ */
+
+/**
+ * Provider identifier for spawn operations.
+ */
+export type Provider = string;
+
+/**
+ * CAAMP-compatible spawn options (inlined for zero-dep contracts).
+ */
+export interface CAAMPSpawnOptions {
+  [key: string]: unknown;
+}
+
+/**
+ * CAAMP-compatible spawn result (inlined for zero-dep contracts).
+ */
+export interface CAAMPSpawnResult {
+  instanceId: string;
+  output: string;
+  exitCode: number;
+  [key: string]: unknown;
+}
+
+/**
+ * CLEO-specific spawn context
+ * Extends CAAMP options with CLEO task and protocol metadata
+ */
+export interface CLEOSpawnContext {
+  /** Task ID being spawned */
+  taskId: string;
+
+  /** Protocol to use for the spawned task */
+  protocol: string;
+
+  /** Fully-resolved prompt to send to subagent */
+  prompt: string;
+
+  /** Provider to use for spawning */
+  provider: Provider;
+
+  /** CAAMP-compatible spawn options */
+  options: CAAMPSpawnOptions;
+
+  /** Project root or working directory for provider-specific files and process execution */
+  workingDirectory?: string;
+
+  /** Token resolution information for the prompt */
+  tokenResolution?: TokenResolution;
+}
+
+/**
+ * CLEO spawn result
+ * Extends CAAMP SpawnResult with CLEO-specific timing and metadata
+ */
+export interface CLEOSpawnResult extends CAAMPSpawnResult {
+  /** Task ID that was spawned */
+  taskId: string;
+
+  /** Provider ID used for the spawn */
+  providerId: string;
+
+  /** Timing information for the spawn operation */
+  timing: {
+    /** ISO timestamp when spawn started */
+    startTime: string;
+    /** ISO timestamp when spawn completed (if finished) */
+    endTime?: string;
+    /** Duration in milliseconds */
+    durationMs?: number;
+  };
+
+  /** Reference to manifest entry if output was captured */
+  manifestEntryId?: string;
+}
+
+/**
+ * Spawn adapter interface
+ * Wraps CAAMP SpawnAdapter with CLEO-specific context and result types
+ */
+export interface CLEOSpawnAdapter {
+  /** Unique identifier for this adapter instance */
+  readonly id: string;
+
+  /** Provider ID this adapter uses */
+  readonly providerId: string;
+
+  /**
+   * Check if this adapter can spawn in the current environment
+   * @returns Promise resolving to true if spawning is possible
+   */
+  canSpawn(): Promise<boolean>;
+
+  /**
+   * Execute a spawn using the provider's native mechanism
+   * @param context - Fully-resolved spawn context
+   * @returns Promise resolving to spawn result
+   * @throws SpawnExecutionError if spawn fails
+   */
+  spawn(context: CLEOSpawnContext): Promise<CLEOSpawnResult>;
+
+  /**
+   * List currently running spawns
+   * @returns Promise resolving to array of running spawn results
+   */
+  listRunning(): Promise<CLEOSpawnResult[]>;
+
+  /**
+   * Terminate a running spawn
+   * @param instanceId - ID of the spawn instance to terminate
+   * @returns Promise that resolves when termination is complete
+   */
+  terminate(instanceId: string): Promise<void>;
+}
+
+/**
+ * Token resolution information for prompt processing
+ */
+export interface TokenResolution {
+  /** Array of resolved token identifiers */
+  resolved: string[];
+  /** Array of unresolved token identifiers */
+  unresolved: string[];
+  /** Total number of tokens processed */
+  totalTokens: number;
+}
+
+/**
+ * Spawn status values
+ */
+export type SpawnStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';

package/src/spawn.ts

@@ -0,0 +1,32 @@
+/**
+ * Spawn provider interface for CLEO provider adapters.
+ *
+ * @task T5240
+ */
+
+export interface AdapterSpawnProvider {
+  canSpawn(): Promise<boolean>;
+  spawn(context: SpawnContext): Promise<SpawnResult>;
+  listRunning(): Promise<SpawnResult[]>;
+  terminate(instanceId: string): Promise<void>;
+}
+
+export interface SpawnContext {
+  taskId: string;
+  prompt: string;
+  workingDirectory?: string;
+  options?: Record<string, unknown>;
+}
+
+export interface SpawnResult {
+  instanceId: string;
+  taskId: string;
+  providerId: string;
+  /** Output captured from the spawned process. Optional for detached/fire-and-forget spawns. */
+  output?: string;
+  /** Exit code of the spawned process. Optional for detached/fire-and-forget spawns. */
+  exitCode?: number;
+  status: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+  startTime: string;
+  endTime?: string;
+}

package/src/status-registry.ts

@@ -0,0 +1,166 @@
+/**
+ * Unified Status Registry — single source of truth for all status enums.
+ *
+ * ADR-018: All status constants and types MUST be defined here.
+ * No other file may define status enum arrays as constants.
+ *
+ * Dependency direction:
+ *   status-registry.ts → schema.ts, types/task.ts, validation/engine.ts,
+ *                         mcp/lib/security.ts, dispatch/lib/security.ts, ...
+ */
+
+// === WORKFLOW NAMESPACE ===
+// Statuses for entities representing work being performed.
+
+export const TASK_STATUSES = [
+  'pending',
+  'active',
+  'blocked',
+  'done',
+  'cancelled',
+  'archived',
+] as const;
+
+export const SESSION_STATUSES = ['active', 'ended', 'orphaned', 'suspended'] as const;
+
+export const LIFECYCLE_PIPELINE_STATUSES = [
+  'active',
+  'completed',
+  'blocked',
+  'failed',
+  'cancelled',
+  'aborted',
+] as const;
+
+export const LIFECYCLE_STAGE_STATUSES = [
+  'not_started',
+  'in_progress',
+  'blocked',
+  'completed',
+  'skipped',
+  'failed',
+] as const;
+
+// === GOVERNANCE NAMESPACE ===
+// Statuses for decisions and approvals.
+
+export const ADR_STATUSES = ['proposed', 'accepted', 'superseded', 'deprecated'] as const;
+
+export const GATE_STATUSES = ['pending', 'passed', 'failed', 'waived'] as const;
+
+// === MANIFEST NAMESPACE ===
+// Statuses for protocol output artifacts.
+// NOTE: 'complete' was the old value — it is now 'completed' everywhere.
+
+export const MANIFEST_STATUSES = ['completed', 'partial', 'blocked', 'archived'] as const;
+
+// === DERIVED TYPES ===
+
+export type TaskStatus = (typeof TASK_STATUSES)[number];
+export type SessionStatus = (typeof SESSION_STATUSES)[number];
+export type PipelineStatus = (typeof LIFECYCLE_PIPELINE_STATUSES)[number];
+export type StageStatus = (typeof LIFECYCLE_STAGE_STATUSES)[number];
+export type AdrStatus = (typeof ADR_STATUSES)[number];
+export type GateStatus = (typeof GATE_STATUSES)[number];
+export type ManifestStatus = (typeof MANIFEST_STATUSES)[number];
+
+// === TERMINAL STATE SETS ===
+
+export const TERMINAL_TASK_STATUSES: ReadonlySet<TaskStatus> = new Set([
+  'done',
+  'cancelled',
+  'archived',
+]);
+
+export const TERMINAL_PIPELINE_STATUSES: ReadonlySet<PipelineStatus> = new Set([
+  'completed',
+  'failed',
+  'cancelled',
+  'aborted',
+]);
+
+export const TERMINAL_STAGE_STATUSES: ReadonlySet<StageStatus> = new Set([
+  'completed',
+  'skipped',
+  'failed',
+]);
+
+// === REGISTRY (for runtime queryability) ===
+
+export type EntityType =
+  | 'task'
+  | 'session'
+  | 'lifecycle_pipeline'
+  | 'lifecycle_stage'
+  | 'adr'
+  | 'gate'
+  | 'manifest';
+
+export const STATUS_REGISTRY: Record<EntityType, readonly string[]> = {
+  task: TASK_STATUSES,
+  session: SESSION_STATUSES,
+  lifecycle_pipeline: LIFECYCLE_PIPELINE_STATUSES,
+  lifecycle_stage: LIFECYCLE_STAGE_STATUSES,
+  adr: ADR_STATUSES,
+  gate: GATE_STATUSES,
+  manifest: MANIFEST_STATUSES,
+} as const;
+
+export function isValidStatus(entityType: EntityType, value: string): boolean {
+  return (STATUS_REGISTRY[entityType] as readonly string[]).includes(value);
+}
+
+// === DISPLAY ICONS ===
+// Typed Record maps — exhaustiveness is enforced by the compiler.
+// All icon consumers MUST import from here instead of hardcoding comparisons.
+
+/**
+ * Pipeline status → Unicode progress icon.
+ * Used wherever lifecycle pipeline status is rendered to a terminal.
+ */
+export const PIPELINE_STATUS_ICONS: Record<PipelineStatus, string> = {
+  active: '\u25b6', // pipeline is running
+  completed: '\u2713', // all stages done successfully
+  blocked: '\u23f8', // cannot advance; waiting
+  failed: '\u2717', // terminal failure
+  cancelled: '\u2298', // user-initiated abandonment
+  aborted: '\u23f9', // system-forced termination
+};
+
+/**
+ * Stage status → Unicode progress icon.
+ * Used wherever pipeline stage status is rendered to a terminal.
+ */
+export const STAGE_STATUS_ICONS: Record<StageStatus, string> = {
+  not_started: '\u23f9', // not yet entered
+  in_progress: '\u25b6', // actively running
+  blocked: '\u23f8', // paused / waiting
+  completed: '\u2713', // finished successfully
+  skipped: '\u23ed', // intentionally bypassed
+  failed: '\u2717', // terminal failure
+};
+
+/**
+ * Task status → Unicode symbol (rich terminal / Unicode-enabled).
+ * Falls back to TASK_STATUS_SYMBOLS_ASCII when Unicode is unavailable.
+ */
+export const TASK_STATUS_SYMBOLS_UNICODE: Record<TaskStatus, string> = {
+  pending: '\u25cb', // ○  not yet started
+  active: '\u25c9', // ◉  in progress
+  blocked: '\u2297', // ⊗  cannot advance
+  done: '\u2713', // ✓  complete
+  cancelled: '\u2717', // ✗  abandoned
+  archived: '\u25a3', // ▣  stored, inactive
+};
+
+/**
+ * Task status → ASCII fallback symbol (non-Unicode terminals, CI output).
+ */
+export const TASK_STATUS_SYMBOLS_ASCII: Record<TaskStatus, string> = {
+  pending: '-',
+  active: '*',
+  blocked: 'x',
+  done: '+',
+  cancelled: '~',
+  archived: '#',
+};

package/src/task-record.ts

@@ -0,0 +1,71 @@
+/**
+ * TaskRecord — string-widened version of Task for JSON serialization in dispatch/LAFS layer.
+ *
+ * Union-typed fields (status, priority, origin, etc.) are widened to string
+ * so that the dispatch layer does not need to validate enum membership.
+ *
+ * @task T4657
+ * @epic T4654
+ */
+
+import type { TaskVerification } from './task.js';
+
+/** A single task relation entry (string-widened version). */
+export interface TaskRecordRelation {
+  taskId: string;
+  type: string;
+  reason?: string;
+}
+
+/** Validation history entry. */
+export interface ValidationHistoryEntry {
+  round: number;
+  agent: string;
+  result: string;
+  timestamp: string;
+}
+
+/** String-widened Task for JSON serialization in dispatch/LAFS layer. */
+export interface TaskRecord {
+  id: string;
+  title: string;
+  description: string;
+  status: string;
+  priority: string;
+  type?: string;
+  phase?: string;
+  createdAt: string;
+  updatedAt: string | null;
+  completedAt?: string | null;
+  cancelledAt?: string | null;
+  parentId?: string | null;
+  position?: number | null;
+  positionVersion?: number;
+  depends?: string[];
+  relates?: TaskRecordRelation[];
+  files?: string[];
+  acceptance?: string[];
+  notes?: string[];
+  labels?: string[];
+  size?: string | null;
+  epicLifecycle?: string | null;
+  noAutoComplete?: boolean | null;
+  verification?: TaskVerification | null;
+  origin?: string | null;
+  createdBy?: string | null;
+  validatedBy?: string | null;
+  testedBy?: string | null;
+  lifecycleState?: string | null;
+  validationHistory?: ValidationHistoryEntry[];
+  blockedBy?: string[];
+  cancellationReason?: string;
+}
+
+/** Minimal task representation for find results. */
+export interface MinimalTaskRecord {
+  id: string;
+  title: string;
+  status: string;
+  priority: string;
+  parentId?: string | null;
+}