@cleocode/contracts 2026.4.0 → 2026.4.3

package/src/errors.ts

@@ -20,6 +20,11 @@
  * @param fallbackMessage - Message to use if error provides none
  * @returns Normalized error with consistent shape
  *
+ * @remarks
+ * This function is safe to call on any value thrown by a `catch` clause.
+ * It guarantees the returned object is always an `Error` instance with a
+ * non-empty `message` property.
+ *
  * @example
  * ```typescript
  * try {
@@ -63,6 +68,10 @@ export function normalizeError(
  * @param fallback - Fallback message if extraction fails
  * @returns The error message string
  *
+ * @remarks
+ * Inspects the value for an `Error` instance, a plain string, or an object
+ * with a `message` property before falling back to the provided default.
+ *
  * @example
  * ```typescript
  * const message = getErrorMessage(err, 'Unknown error');
@@ -99,6 +108,11 @@ export function getErrorMessage(error: unknown, fallback = 'Unknown error'): str
  * @param includeStack - Whether to include stack traces (default: false)
  * @returns Formatted error string
  *
+ * @remarks
+ * When `context` is provided it is prefixed in square brackets (e.g.
+ * `[Database] Connection refused`). Stack traces are appended on a new line
+ * only when `includeStack` is `true` and the value is an `Error` with a stack.
+ *
  * @example
  * ```typescript
  * console.error(formatError(err, 'Database connection'));
@@ -126,6 +140,10 @@ export function formatError(error: unknown, context?: string, includeStack = fal
  * @param codeOrName - The error code or name to match
  * @returns True if the error matches
  *
+ * @remarks
+ * Checks both `Error.name` and a custom `code` property, supporting both
+ * standard and LAFS-style error codes (e.g. `"E_NOT_FOUND"`).
+ *
  * @example
  * ```typescript
  * if (isErrorType(err, 'E_NOT_FOUND')) {
@@ -154,6 +172,10 @@ export function isErrorType(error: unknown, codeOrName: string): boolean {
  * @param error - The error value
  * @returns Error result object
  *
+ * @remarks
+ * Pairs with {@link createSuccessResult} and {@link isErrorResult} to provide
+ * a consistent result-or-error pattern without exceptions.
+ *
  * @example
  * ```typescript
  * return createErrorResult(err);
@@ -172,6 +194,10 @@ export function createErrorResult(error: unknown): { success: false; error: stri
  *
  * @returns Success result object
  *
+ * @remarks
+ * Pairs with {@link createErrorResult} and {@link isErrorResult} to provide
+ * a consistent result-or-error pattern without exceptions.
+ *
  * @example
  * ```typescript
  * return createSuccessResult();
@@ -188,6 +214,10 @@ export function createSuccessResult(): { success: true } {
  * @param result - The result to check
  * @returns True if the result is an error result
  *
+ * @remarks
+ * Narrows the result type so that `result.error` is guaranteed to be a string
+ * after the guard returns `true`.
+ *
  * @example
  * ```typescript
  * const result = await someOperation();

package/src/install.ts

@@ -16,13 +16,13 @@ export interface AdapterInstallProvider {
 export interface InstallOptions {
   projectDir: string;
   global?: boolean;
-  mcpServerPath?: string;
 }
 
 export interface InstallResult {
   success: boolean;
   installedAt: string;
   instructionFileUpdated: boolean;
+  /** Always false. CLI dispatch only. */
   mcpRegistered: boolean;
   details?: Record<string, unknown>;
 }

package/src/lafs.ts

@@ -26,36 +26,57 @@ export type LAFSErrorCategory =
 
 /** LAFS error object. */
 export interface LAFSError {
+  /** Stable error code (numeric HTTP status or string identifier). */
   code: number | string;
+  /** High-level error classification category. */
   category: LAFSErrorCategory;
+  /** Human-readable error description. */
   message: string;
+  /**
+   * Suggested fix or recovery action for the caller.
+   *
+   * @defaultValue undefined
+   */
   fix?: string;
+  /**
+   * Arbitrary key-value pairs with additional error context.
+   *
+   * @defaultValue undefined
+   */
   details?: Record<string, unknown>;
 }
 
 /** LAFS warning. */
 export interface Warning {
+  /** Machine-readable warning code. */
   code: string;
+  /** Human-readable warning description. */
   message: string;
 }
 
 /** LAFS transport metadata. */
-export type LAFSTransport = 'mcp' | 'cli' | 'http' | 'sdk';
+export type LAFSTransport = 'cli' | 'http' | 'sdk';
 
 /** MVI (Minimal Viable Information) level. */
 export type MVILevel = 'minimal' | 'standard' | 'full';
 
 /** LAFS page — no pagination. */
 export interface LAFSPageNone {
+  /** Discriminant indicating no pagination is applied. */
   strategy: 'none';
 }
 
 /** LAFS page — offset-based pagination. */
 export interface LAFSPageOffset {
+  /** Discriminant identifying offset-based pagination. */
   strategy: 'offset';
+  /** Zero-based index of the first item in this page. */
   offset: number;
+  /** Maximum number of items per page. */
   limit: number;
+  /** Total number of items across all pages. */
   total: number;
+  /** Whether additional pages exist beyond the current one. */
   hasMore: boolean;
 }
 
@@ -64,31 +85,69 @@ export type LAFSPage = LAFSPageNone | LAFSPageOffset;
 
 /** LAFS metadata block. */
 export interface LAFSMeta {
+  /** Transport protocol used for this envelope. */
   transport: LAFSTransport;
+  /** Minimum Viable Information level controlling verbosity. */
   mvi: MVILevel;
+  /**
+   * Pagination metadata when the result is a paginated collection.
+   *
+   * @defaultValue undefined
+   */
   page?: LAFSPage;
+  /**
+   * Non-fatal warnings to surface to the consuming agent.
+   *
+   * @defaultValue undefined
+   */
   warnings?: Warning[];
+  /**
+   * Operation duration in milliseconds.
+   *
+   * @defaultValue undefined
+   */
   durationMs?: number;
 }
 
 /** LAFS envelope (canonical protocol type). */
 export interface LAFSEnvelope<T = unknown> {
+  /** Whether the operation completed successfully. */
   success: boolean;
+  /**
+   * Operation result payload on success.
+   *
+   * @defaultValue undefined
+   */
   data?: T;
+  /**
+   * Structured error payload on failure.
+   *
+   * @defaultValue undefined
+   */
   error?: LAFSError;
+  /**
+   * Protocol and transport metadata.
+   *
+   * @defaultValue undefined
+   */
   _meta?: LAFSMeta;
 }
 
 /** Flag input for conformance checks. */
 export interface FlagInput {
+  /** Name of the flag being checked. */
   flag: string;
+  /** Value of the flag to validate. */
   value: unknown;
 }
 
 /** Conformance report. */
 export interface ConformanceReport {
+  /** Whether all conformance checks passed. */
   valid: boolean;
+  /** List of conformance violation descriptions. */
   violations: string[];
+  /** List of non-fatal warning descriptions. */
   warnings: string[];
 }
 
@@ -98,17 +157,41 @@ export interface ConformanceReport {
 
 /** Actionable alternative the caller can try. */
 export interface LafsAlternative {
+  /** Description of the alternative action. */
   action: string;
+  /** CLI command the caller can run instead. */
   command: string;
 }
 
-/** LAFS error detail shared between CLI and MCP. */
+/** LAFS error detail shared between CLI and gateway. */
 export interface LafsErrorDetail {
+  /** Stable error code (numeric HTTP status or string identifier). */
   code: number | string;
+  /**
+   * Optional human-readable error name (e.g. `"NOT_FOUND"`).
+   *
+   * @defaultValue undefined
+   */
   name?: string;
+  /** Human-readable error description. */
   message: string;
+  /**
+   * Suggested fix or recovery action for the caller.
+   *
+   * @defaultValue undefined
+   */
   fix?: string;
+  /**
+   * Alternative commands the caller can try.
+   *
+   * @defaultValue undefined
+   */
   alternatives?: LafsAlternative[];
+  /**
+   * Arbitrary key-value pairs with additional error context.
+   *
+   * @defaultValue undefined
+   */
   details?: Record<string, unknown>;
 }
 
@@ -118,15 +201,29 @@ export interface LafsErrorDetail {
 
 /** LAFS success envelope (CLI). */
 export interface LafsSuccess<T = unknown> {
+  /** Discriminant: always `true` for success envelopes. */
   success: true;
+  /** Operation result payload. */
   data: T;
+  /**
+   * Optional human-readable summary of the operation outcome.
+   *
+   * @defaultValue undefined
+   */
   message?: string;
+  /**
+   * When `true`, the operation was a no-op (data is unchanged).
+   *
+   * @defaultValue undefined
+   */
   noChange?: boolean;
 }
 
 /** LAFS error envelope (CLI). */
 export interface LafsError {
+  /** Discriminant: always `false` for error envelopes. */
   success: false;
+  /** Structured error detail with code, message, and fix guidance. */
   error: LafsErrorDetail;
 }
 
@@ -134,43 +231,48 @@ export interface LafsError {
 export type LafsEnvelope<T = unknown> = LafsSuccess<T> | LafsError;
 
 // ---------------------------------------------------------------------------
-// MCP / gateway envelope extension (extends LAFSMeta)
+// Gateway envelope extension (extends LAFSMeta)
 // ---------------------------------------------------------------------------
 
 /**
- * Metadata attached to every MCP gateway response.
+ * Metadata attached to every gateway response.
  * Extends the canonical LAFSMeta with CLEO gateway-specific fields.
  *
  * @task T4655
  */
 export interface GatewayMeta extends LAFSMeta {
+  /** Gateway identifier that processed this request. */
   gateway: string;
+  /** CLEO domain that handled the operation (e.g. `"tasks"`, `"session"`). */
   domain: string;
+  /** Operation duration in milliseconds. */
   duration_ms: number;
 }
 
-/** MCP success envelope (extends CLI base with _meta). */
+/** Gateway success envelope (extends CLI base with _meta). */
 export interface GatewaySuccess<T = unknown> extends LafsSuccess<T> {
+  /** Gateway-specific metadata including domain and timing. */
   _meta: GatewayMeta;
 }
 
-/** MCP error envelope (extends CLI base with _meta). */
+/** Gateway error envelope (extends CLI base with _meta). */
 export interface GatewayError extends LafsError {
+  /** Gateway-specific metadata including domain and timing. */
   _meta: GatewayMeta;
 }
 
-/** MCP envelope union type. */
+/** Gateway envelope union type. */
 export type GatewayEnvelope<T = unknown> = GatewaySuccess<T> | GatewayError;
 
 // ---------------------------------------------------------------------------
-// Unified envelope (covers both CLI and MCP)
+// Unified envelope (covers both CLI and Gateway)
 // ---------------------------------------------------------------------------
 
 /**
  * Unified CLEO response envelope.
  *
- * Every CLEO response (CLI or MCP) is a CleoResponse. MCP responses include
- * the _meta field; CLI responses do not.
+ * Every CLEO response (CLI or Gateway) is a CleoResponse. Gateway responses
+ * include the _meta field; CLI responses do not.
  */
 export type CleoResponse<T = unknown> = LafsEnvelope<T> | GatewayEnvelope<T>;
 
@@ -178,17 +280,71 @@ export type CleoResponse<T = unknown> = LafsEnvelope<T> | GatewayEnvelope<T>;
 // Type guards
 // ---------------------------------------------------------------------------
 
-/** Type guard for success responses. */
+/**
+ * Type guard for success responses.
+ *
+ * @typeParam T - The data payload type of the envelope.
+ * @param envelope - The envelope to check.
+ * @returns `true` if the envelope represents a successful operation.
+ *
+ * @remarks
+ * Narrows a {@link LafsEnvelope} to {@link LafsSuccess} so that `envelope.data`
+ * is accessible without additional type assertions.
+ *
+ * @example
+ * ```ts
+ * const result: LafsEnvelope<Task[]> = await fetchTasks();
+ * if (isLafsSuccess(result)) {
+ *   console.log(result.data); // Task[]
+ * }
+ * ```
+ */
 export function isLafsSuccess<T>(envelope: LafsEnvelope<T>): envelope is LafsSuccess<T> {
   return envelope.success === true;
 }
 
-/** Type guard for error responses. */
+/**
+ * Type guard for error responses.
+ *
+ * @typeParam T - The data payload type of the envelope.
+ * @param envelope - The envelope to check.
+ * @returns `true` if the envelope represents a failed operation.
+ *
+ * @remarks
+ * Narrows a {@link LafsEnvelope} to {@link LafsError} so that `envelope.error`
+ * is accessible without additional type assertions.
+ *
+ * @example
+ * ```ts
+ * const result: LafsEnvelope<Task[]> = await fetchTasks();
+ * if (isLafsError(result)) {
+ *   console.error(result.error.message);
+ * }
+ * ```
+ */
 export function isLafsError<T>(envelope: LafsEnvelope<T>): envelope is LafsError {
   return envelope.success === false;
 }
 
-/** Type guard for MCP gateway responses (has _meta). */
+/**
+ * Type guard for gateway responses (has _meta).
+ *
+ * @typeParam T - The data payload type of the envelope.
+ * @param envelope - The response to check.
+ * @returns `true` if the response includes gateway metadata.
+ *
+ * @remarks
+ * Distinguishes gateway responses from plain CLI responses by checking for the
+ * presence of the `_meta` field, which carries gateway-specific routing and timing data.
+ *
+ * @example
+ * ```ts
+ * const response: CleoResponse<Task> = await handleRequest();
+ * if (isGatewayEnvelope(response)) {
+ *   console.log(response._meta.gateway);
+ * }
+ * ```
+ */
 export function isGatewayEnvelope<T>(envelope: CleoResponse<T>): envelope is GatewayEnvelope<T> {
   return '_meta' in envelope && envelope._meta !== undefined;
 }

package/src/memory.ts

@@ -6,52 +6,129 @@
  */
 
 export interface MemoryBridgeConfig {
+  /** Maximum number of recent observations to include in the bridge. */
   maxObservations: number;
+  /** Maximum number of key learnings to include. */
   maxLearnings: number;
+  /** Maximum number of patterns (follow/avoid) to include. */
   maxPatterns: number;
+  /** Maximum number of recent decisions to include. */
   maxDecisions: number;
+  /** Whether to include the last session handoff summary. */
   includeHandoff: boolean;
+  /** Whether to include anti-patterns alongside follow-patterns. */
   includeAntiPatterns: boolean;
 }
 
+/**
+ * Structured content of the `.cleo/memory-bridge.md` file.
+ *
+ * @remarks
+ * The memory bridge is auto-generated from brain.db and provides cross-session
+ * memory context to agents. It is refreshed on session end, task completion,
+ * and explicit `cleo refresh-memory` invocations.
+ */
 export interface MemoryBridgeContent {
+  /** ISO 8601 timestamp of when this bridge content was generated. */
   generatedAt: string;
+  /**
+   * Summary of the most recent session.
+   *
+   * @defaultValue undefined
+   */
   lastSession?: SessionSummary;
+  /** Key learnings extracted from brain.db observations. */
   learnings: BridgeLearning[];
+  /** Patterns to follow, identified from recurring successful outcomes. */
   patterns: BridgePattern[];
+  /** Anti-patterns to avoid, identified from recurring failures. */
   antiPatterns: BridgePattern[];
+  /** Recent decisions made during sessions. */
   decisions: BridgeDecision[];
+  /** Most recent observations from brain.db. */
   recentObservations: BridgeObservation[];
 }
 
+/**
+ * Summary of a completed session for the memory bridge.
+ *
+ * @remarks
+ * Captures the essential outcomes of a session so subsequent sessions
+ * can pick up where the previous one left off.
+ */
 export interface SessionSummary {
+  /** Unique identifier of the summarized session. */
   sessionId: string;
+  /** ISO 8601 date when the session occurred. */
   date: string;
+  /** Task IDs that were completed during this session. */
   tasksCompleted: string[];
+  /** Key decisions made during this session. */
   decisions: string[];
+  /** Suggested next actions for the following session. */
   nextSuggested: string[];
 }
 
+/**
+ * A key learning extracted from brain.db for the memory bridge.
+ *
+ * @remarks
+ * Learnings are observations that have been validated or reinforced across
+ * multiple sessions, with a confidence score reflecting their reliability.
+ */
 export interface BridgeLearning {
+  /** Brain.db entry identifier (e.g. `"L-abc123"`). */
   id: string;
+  /** Human-readable learning text. */
   text: string;
+  /** Confidence score from 0.0 to 1.0. */
   confidence: number;
 }
 
+/**
+ * A recurring pattern identified in brain.db entries.
+ *
+ * @remarks
+ * Patterns are classified as either `"follow"` (positive patterns to repeat)
+ * or `"avoid"` (anti-patterns to prevent).
+ */
 export interface BridgePattern {
+  /** Brain.db entry identifier (e.g. `"P-abc123"`). */
   id: string;
+  /** Human-readable pattern description. */
   text: string;
+  /** Whether this is a pattern to follow or avoid. */
   type: 'follow' | 'avoid';
 }
 
+/**
+ * A decision recorded in brain.db for the memory bridge.
+ *
+ * @remarks
+ * Decisions are high-signal observations that capture architectural or
+ * process choices made during sessions.
+ */
 export interface BridgeDecision {
+  /** Brain.db entry identifier (e.g. `"D-abc123"`). */
   id: string;
+  /** Short title summarizing the decision. */
   title: string;
+  /** ISO 8601 date when the decision was made. */
   date: string;
 }
 
+/**
+ * A recent observation from brain.db for the memory bridge.
+ *
+ * @remarks
+ * Observations are the raw input to the brain memory system. Only the most
+ * recent ones are included in the bridge to keep token cost low.
+ */
 export interface BridgeObservation {
+  /** Brain.db entry identifier (e.g. `"O-abc123"`). */
   id: string;
+  /** ISO 8601 date when the observation was recorded. */
   date: string;
+  /** Truncated summary of the observation content. */
   summary: string;
 }

package/src/operations/issues.ts

@@ -11,7 +11,7 @@
  * Common issue types
  */
 export type IssueSeverity = 'low' | 'medium' | 'high' | 'critical';
-export type IssueArea = 'cli' | 'mcp' | 'docs' | 'tests' | 'other';
+export type IssueArea = 'cli' | 'dispatch' | 'docs' | 'tests' | 'other';
 export type IssueType = 'bug' | 'feature' | 'help';
 
 export interface Diagnostics {

package/src/operations/session.ts

@@ -6,7 +6,7 @@
  *
  * SYNC: Canonical type definitions live in the CLI package at:
  *   src/types/session.ts (Session, SessionScope, etc.)
- * These MCP operation types are the API contract (wire format).
+ * These operation types are the API contract (wire format).
  */
 
 /**

package/src/operations/tasks.ts

@@ -6,7 +6,7 @@
  *
  * SYNC: Canonical type definitions live in the CLI package at:
  *   src/types/task.ts (TaskStatus, TaskPriority, Task, etc.)
- * These MCP operation types are the API contract (wire format).
+ * These operation types are the API contract (wire format).
  * Internal domain types must stay aligned with CLI definitions.
  */