cleo — Types

Type contracts for the cleo package

Type contracts exported by this package: interfaces, type aliases, and enums.

TaskRecord

Task object as stored in task data.

Property	Type	Required	Description
id	string	Yes	Unique task identifier (e.g. “T001”).
title	string	Yes	Short summary of the task.
description	string	Yes	Full task description.
status	string	Yes	Current status (pending, active, blocked, done, cancelled).
priority	string	Yes	Priority level (critical, high, medium, low).
type	string | undefined	No	Task type (task, epic, milestone, bug).
phase	string | undefined	No	Project phase this task belongs to.
createdAt	string	Yes	ISO timestamp when the task was created.
updatedAt	string | null	Yes	ISO timestamp of the last update, or null.
completedAt	string | null | undefined	No	ISO timestamp when the task was completed, or null.
cancelledAt	string | null | undefined	No	ISO timestamp when the task was cancelled, or null.
parentId	string | null | undefined	No	Parent task ID for hierarchical nesting, or null for root tasks.
position	number | null | undefined	No	Ordering position among siblings.
positionVersion	number | undefined	No	Optimistic concurrency version for position updates.
depends	string[] | undefined	No	Task IDs this task depends on (must complete first).
relates	{ taskId: string; type: string; reason?: string; }[] | undefined	No	Related tasks with relationship type and optional reason.
files	string[] | undefined	No	File paths associated with this task.
acceptance	string[] | undefined	No	Acceptance criteria lines.
notes	string[] | undefined	No	Free-form notes.
labels	string[] | undefined	No	Classification labels.
size	string | null | undefined	No	Complexity sizing (small, medium, large).
epicLifecycle	string | null | undefined	No	Epic lifecycle state for epic-type tasks.
noAutoComplete	boolean | null | undefined	No	When true, prevents auto-completion on child task completion.
verification	import("/mnt/projects/cleocode/packages/contracts/dist/task").TaskVerification | null | undefined	No	Verification gate state and round tracking.
origin	string | null | undefined	No	How the task was created (manual, decomposition, import).
createdBy	string | null | undefined	No	Agent or user who created the task.
validatedBy	string | null | undefined	No	Agent or user who validated the task.
testedBy	string | null | undefined	No	Agent or user who tested the task.
lifecycleState	string | null | undefined	No	Current lifecycle governance state.
validationHistory	Record<string, unknown>[] | undefined	No	History of lifecycle validation transitions.
blockedBy	string[] | undefined	No	Task IDs that are blocking this task.
cancellationReason	string | undefined	No	Reason provided when the task was cancelled.
pipelineStage	string | null | undefined	No	RCASD-IVTR+C pipeline stage (T060).

MinimalTaskRecord

Minimal task representation for find results.

Property	Type	Required	Description
id	string	Yes	Unique task identifier.
title	string	Yes	Short summary of the task.
status	string	Yes	Current status.
priority	string	Yes	Priority level.
parentId	string | null | undefined	No	Parent task ID, or null for root tasks.

GatewayMetaRecord

GatewayMeta with an index signature for DomainResponse._meta compatibility. All domain handlers receive this from createGatewayMeta(). T4655

GatewayMetaRecord

ShimOption

Parsed option definition.

Property	Type	Required	Description
longName	string	Yes	Long flag name (camelCase), e.g. ‘dryRun’
shortName	string | undefined	No	Short alias, e.g. ‘s’
takesValue	boolean	Yes	Whether it takes a value (vs boolean flag)
description	string	Yes	Description text
required	boolean	Yes	Whether this option is required
parseFn	((val: string) => unknown) | undefined	No	Custom parse function (e.g. parseInt)
defaultValue	unknown	Yes	Default value

ShimArg

Positional argument definition.

Property	Type	Required	Description
name	string	Yes	name
required	boolean	Yes	required
variadic	boolean | undefined	No	variadic

CommanderCompatOption

Commander-compatible option view for tests.

Property	Type	Required	Description
long	string	Yes	long
required	boolean	Yes	required
defaultValue	unknown	Yes	defaultValue

ActionHandler

Type for the action handler function - flexible to support various signatures

ActionHandler

LafsShapeViolation

The minimum shape invariants for a LAFS envelope, compatible with both minimal ({ok, r, _m}) and full ({success, result, _meta}) formats.

Property	Type	Required	Description
isObject	boolean	Yes	True iff the input is a well-formed JSON object.
hasSuccessField	boolean	Yes	True iff the envelope has exactly one success-indicator field.
successIsBoolean	boolean	Yes	True iff the success-indicator is a boolean.
hasMeta	boolean	Yes	True iff a metadata field (_m or _meta) is present.
resultOrErrorValid	boolean	Yes	True iff the result/error invariants hold for the indicated success value.
reasons	string[]	Yes	Human-readable reasons the envelope failed validation (empty = valid).

CliOutputOptions

Property	Type	Required	Description
command	string	Yes	Command name (used to pick the correct human renderer).
message	string | undefined	No	Optional success message for JSON envelope.
operation	string | undefined	No	Operation name for LAFS _meta.
page	import("/mnt/projects/cleocode/packages/lafs/dist/src/types").LAFSPage | undefined	No	Pagination for LAFS envelope.
extensions	Record<string, unknown> | undefined	No	Extra LAFS extensions.

CliErrorDetails

Error details for structured error output.

Property	Type	Required	Description
name	string | undefined	No	name
details	unknown	Yes	details
fix	unknown	Yes	fix

Gateway

CQRS gateway: read-only queries vs state-modifying mutations.

Gateway

Source

Where the request originated.

"cli"

Tier

Progressive disclosure tier. 0 = tasks + session (80% of agents) 1 = + memory + check (15% of agents) 2 = + pipeline + orchestrate + tools + admin + nexus (5%)

Tier

ParamType

The concrete value types a parameter can carry at runtime. Drives JSON Schema type and Commander argument/option parsing.

ParamType

ParamCliDef

CLI-specific decoration for a parameter. All fields are optional — omit the entire cli key for params with no CLI surface.

Property	Type	Required	Description
positional	boolean | undefined	No	When true, registers as .argument('<name>') (positional). When false or omitted, registers as .option('--name <value>'). false
short	string | undefined	No	Short flag alias, e.g. '-t' for --type, '-s' for --status. Only meaningful when positional is false/omitted.
flag	string | undefined	No	Override the CLI flag name when it differs from the param’s name. e.g. name: 'includeArchive' but flag: 'include-archive' Defaults to kebab-case of name.
variadic	boolean | undefined	No	For array-type params on the CLI: when true the option can be repeated. When false/omitted, the CLI accepts a single comma-separated string. false
parse	((value: string) => unknown) | undefined	No	Custom parse function applied by Commander (e.g. parseInt).

ParamDef

A fully-described parameter definition. One ParamDef entry drives Commander: .argument() (positional) or .option() (flag).

Property	Type	Required	Description
name	string	Yes	Canonical camelCase parameter name (matches the key in params dict).
type	ParamType	Yes	Runtime value type. Drives JSON Schema type and Commander parsing.
required	boolean	Yes	When true, Commander registers as a positional argument (<name> or [name]).
description	string	Yes	Human-readable description used in Commander help text.
cli	ParamCliDef | undefined	No	CLI-specific metadata. Omit entire key if this param has no CLI surface.
enum	readonly string[] | undefined	No	JSON Schema enum constraint for this parameter.
hidden	boolean | undefined	No	When true, the parameter is excluded from schema generation. Use for CLI-only params (e.g. --dry-run, --offset). false

CanonicalDomain

"memory" | "pipeline" | "session" | "tasks" | "check" | "orchestrate" | "tools" | "admin" | "nexus" | "sticky" | "conduit"

DispatchRequest

Canonical request shape that the CLI adapter produces. The dispatcher validates this against the OperationRegistry before passing it through the middleware pipeline and into a DomainHandler.

Property	Type	Required	Description
gateway	Gateway	Yes	CQRS gateway.
domain	string	Yes	Target domain (canonical name).
operation	string	Yes	Domain-specific operation name.
params	Record<string, unknown> | undefined	No	Operation parameters (already sanitized by middleware).
source	"cli"	Yes	Where this request came from.
requestId	string	Yes	Unique request identifier for tracing.
sessionId	string | undefined	No	Bound session ID, if any.
_fields	string[] | undefined	No	LAFS field selection: filter response data to these fields only.
_mvi	import("/mnt/projects/cleocode/packages/lafs/dist/src/types").MVILevel | undefined	No	LAFS envelope verbosity. Defaults to ‘standard’. ‘custom’ is server-set via _fields.

RateLimitMeta

Rate limit metadata attached to every response.

Property	Type	Required	Description
limit	number	Yes	limit
remaining	number	Yes	remaining
resetMs	number	Yes	resetMs
category	string	Yes	category

DispatchError

Structured error shape (LAFS-compatible).

Property	Type	Required	Description
code	string	Yes	Machine-readable error code (E_NOT_FOUND, E_VALIDATION_FAILED, …).
exitCode	number | undefined	No	LAFS exit code (1-99).
message	string	Yes	Human-readable message.
details	Record<string, unknown> | undefined	No	Additional structured details.
fix	string | undefined	No	Copy-paste fix command.
alternatives	{ action: string; command: string; }[] | undefined	No	Alternative actions the caller can try.
problemDetails	import("/mnt/projects/cleocode/packages/core/dist/errors").ProblemDetails | undefined	No	RFC 9457 Problem Details (optional, populated from CleoError.toProblemDetails()).

DispatchResponse

Canonical response shape returned by the dispatcher. The CLI adapter translates this into cliOutput() / cliError() + process.exit().

Property	Type	Required	Description
_meta	{ [key: string]: unknown; gateway: Gateway; domain: string; operation: string; timestamp: string; duration_ms: number; source: Source; requestId: string; rateLimit?: RateLimitMeta; sessionId?: string; version?: string; }	No	_meta
success	boolean	Yes	success
data	unknown	Yes	data
page	import("/mnt/projects/cleocode/packages/lafs/dist/src/types").LAFSPage | undefined	No	page
partial	boolean | undefined	No	partial
error	DispatchError | undefined	No	error

DomainHandler

Contract for domain handlers. Each of the 9 target domains (tasks, session, memory, check, pipeline, orchestrate, tools, admin, nexus) implements this interface.

Property	Type	Required	Description
query	(operation: string, params?: Record<string, unknown>) => Promise<DispatchResponse>	No	Execute a read-only query operation.
mutate	(operation: string, params?: Record<string, unknown>) => Promise<DispatchResponse>	No	Execute a state-modifying mutation operation.
getSupportedOperations	() => { query: string[]; mutate: string[]; }	Yes	Declared operations for introspection and validation.

DispatchNext

Async function that produces a DispatchResponse.

DispatchNext

Middleware

Middleware function signature. Receives the request and a next continuation. Can short-circuit by returning early (e.g., rate-limit exceeded) or modify the request/response.

Middleware

OperationDef

Definition of a single dispatchable operation.

Property	Type	Required	Description
gateway	Gateway	Yes	The CQRS gateway (‘query’ or ‘mutate’).
domain	"memory" | "pipeline" | "session" | "tasks" | "check" | "orchestrate" | "tools" | "admin" | "nexus" | "sticky" | "conduit"	Yes	The canonical domain this operation belongs to.
operation	string	Yes	The specific operation name (e.g. ‘show’, ‘skill.list’).
description	string	Yes	Brief description of what the operation does.
tier	Tier	Yes	Agent progressive-disclosure tier (0=basic, 1=memory/check, 2=full).
idempotent	boolean	Yes	Whether the operation is safe to retry.
sessionRequired	boolean	Yes	Whether this operation requires an active session.
requiredParams	string[]	Yes	List of parameter keys that MUST be present in the request.
params	ParamDef[] | undefined	No	Fully-described parameter list. Replaces requiredParams when populated. Empty array = “no declared params” (not “no params accepted”). Optional during T4897 migration — defaults to [] when absent.

Resolution

Resolution output for a dispatch request.

Property	Type	Required	Description
domain	"memory" | "pipeline" | "session" | "tasks" | "check" | "orchestrate" | "tools" | "admin" | "nexus" | "sticky" | "conduit"	Yes	The canonical domain.
operation	string	Yes	The operation name.
def	OperationDef	Yes	The definition of the matched operation.

DispatcherConfig

Property	Type	Required	Description
handlers	Map<string, DomainHandler>	Yes	handlers
middlewares	Middleware[] | undefined	No	middlewares

ProviderMatrixEntry

Coverage summary for a single provider in the hook matrix.

Property	Type	Required	Description
providerId	string	Yes	CAAMP provider identifier (e.g. “claude-code”).
supportedCount	number	Yes	Number of canonical events this provider supports.
totalCanonical	number	Yes	Total canonical events in the taxonomy.
coverage	number	Yes	Coverage percentage (0-100, integer).
supported	string[]	Yes	Canonical events supported by this provider.
unsupported	string[]	Yes	Canonical events not supported by this provider.

HookMatrixResult

Full hook matrix result.

Property	Type	Required	Description
caampVersion	string	Yes	CAAMP hook mappings version.
events	string[]	Yes	All canonical event names (rows).
providers	string[]	Yes	Provider IDs included in the matrix (columns).
matrix	Record<string, Record<string, boolean>>	Yes	Two-dimensional matrix: event name → provider ID → support flag. true means the provider natively supports the canonical event.
summary	ProviderMatrixEntry[]	Yes	Per-provider summary with coverage stats.
detectedProvider	string | null	Yes	Provider ID detected as the current runtime, or null.

RuntimeData

RuntimeDiagnostics

DashboardData

Dashboard data shape returned by systemDash.

Property	Type	Required	Description
project	string	Yes	Project name or directory basename.
currentPhase	string | null	Yes	Currently active project phase, or null.
summary	{ pending: number; active: number; blocked: number; done: number; cancelled: number; total: number; archived: number; grandTotal: number; }	Yes	Task count breakdown by status.
taskWork	{ currentTask: string | null; task: TaskRecord | null; }	Yes	Currently focused task work state.
activeSession	string | null	Yes	Active session ID, or null.
highPriority	{ count: number; tasks: TaskRecord[]; }	Yes	High-priority tasks summary.
blockedTasks	{ count: number; limit: number; tasks: TaskRecord[]; }	Yes	Blocked tasks summary.
recentCompletions	TaskRecord[]	Yes	Recently completed task records.
topLabels	{ label: string; count: number; }[]	Yes	Most frequently used labels with counts.

StatsData

Project statistics data shape returned by systemStats.

Property	Type	Required	Description
currentState	{ pending: number; active: number; done: number; blocked: number; cancelled: number; totalActive: number; archived: number; grandTotal: number; }	Yes	Current task counts by status.
byPriority	Record<string, number>	Yes	Task counts grouped by priority level.
byType	Record<string, number>	Yes	Task counts grouped by task type.
byPhase	Record<string, number>	Yes	Task counts grouped by project phase.
completionMetrics	{ periodDays: number; completedInPeriod: number; createdInPeriod: number; completionRate: number; }	Yes	Completion rate metrics over the configured period.
activityMetrics	{ createdInPeriod: number; completedInPeriod: number; archivedInPeriod: number; }	Yes	Activity metrics over the configured period.
allTime	{ totalCreated: number; totalCompleted: number; totalCancelled: number; totalArchived: number; archivedCompleted: number; }	Yes	Lifetime metrics across all time.
cycleTimes	{ averageDays: number | null; samples: number; }	Yes	Average time from creation to completion.

LogQueryData

Paginated operation log query result.

Property	Type	Required	Description
entries	{ [key: string]: unknown; operation: string; taskId?: string; timestamp: string; }[]	No	Log entries matching the query.
pagination	{ total: number; offset: number; limit: number; hasMore: boolean; }	Yes	Pagination metadata.

ContextData

Context window monitoring data.

Property	Type	Required	Description
available	boolean	Yes	Whether context data is available.
status	string	Yes	Status level (ok, warning, caution, critical, emergency).
percentage	number	Yes	Usage percentage (0-100).
currentTokens	number	Yes	Current token usage.
maxTokens	number	Yes	Maximum context window size.
timestamp	string | null	Yes	ISO timestamp of last update, or null.
stale	boolean	Yes	Whether the data is stale (older than configured threshold).
sessions	{ file: string; sessionId: string | null; percentage: number; status: string; timestamp: string; }[]	Yes	Per-session context state entries.

SequenceData

Task ID sequence state.

Property	Type	Required	Description
counter	number	Yes	Current counter value.
lastId	string	Yes	Last assigned task ID.
checksum	string	Yes	Integrity checksum.
nextId	string	Yes	Next task ID that would be assigned.

RoadmapData

Project roadmap data with upcoming epics and release history.

Property	Type	Required	Description
currentVersion	string	Yes	Current project version.
upcoming	{ id: string; title: string; status: string; priority: string; phase?: string; childCount: number; completedChildren: number; }[]	No	Upcoming epics and milestones.
releaseHistory	{ version: string; date: string; }[] | undefined	No	Past releases.
completedEpics	number | undefined	No	Total completed epics.
summary	{ totalUpcoming: number; totalTasks: number; }	Yes	Summary counts.

ComplianceData

Compliance monitoring data.

Property	Type	Required	Description
totalEntries	number	Yes	Total compliance audit entries.
averagePassRate	number	Yes	Average pass rate (0-100).
averageAdherence	number	Yes	Average adherence score (0-100).
totalViolations	number	Yes	Total violation count.
trend	string | undefined	No	Trend direction (improving, declining, stable).
dataPoints	{ date: string; entries: number; avgPassRate: number; violations: number; }[] | undefined	No	Historical data points for charting.

HelpData

Help topic content and related commands.

Property	Type	Required	Description
topic	string | undefined	No	Topic identifier.
content	string	Yes	Human-readable help content.
relatedCommands	string[] | undefined	No	Related CLI commands for cross-reference.

SyncData

Property	Type	Required	Description
direction	string	Yes	direction
synced	number	Yes	synced
conflicts	number	Yes	conflicts
message	string	Yes	message

PathsData

Summary of all resolved CleoOS paths (project + global hub).

Property	Type	Required	Description
projectCleoDir	string	Yes	Project-local .cleo directory (absolute).
cleoHome	string	Yes	XDG-compliant global data root (Linux: ~/.local/share/cleo).
configDir	string	Yes	XDG config dir (Linux: ~/.config/cleo).
hub	{ globalRecipes: string; globalJustfile: string; piExtensions: string; cantWorkflows: string; globalAgents: string; }	Yes	CleoOS Hub subdirectories under cleoHome.
scaffolded	{ globalRecipes: boolean; globalJustfile: boolean; piExtensions: boolean; cantWorkflows: boolean; globalAgents: boolean; }	Yes	Scaffolding status — true if hub directories + seed files exist.

ScaffoldHubData

Result of scaffolding the CleoOS Hub.

Property	Type	Required	Description
action	"created" | "skipped" | "repaired"	Yes	action
path	string	Yes	path
details	string | undefined	No	details

SmokeProbe

Result for a single domain smoke probe.

Property	Type	Required	Description
domain	string	Yes	domain
operation	string	Yes	operation
status	"pass" | "fail" | "skip"	Yes	status
timeMs	number	Yes	timeMs
error	string | undefined	No	error

SmokeResult

Aggregate smoke test result.

Property	Type	Required	Description
probes	SmokeProbe[]	Yes	probes
dbChecks	SmokeProbe[]	Yes	dbChecks
passed	number	Yes	passed
failed	number	Yes	failed
skipped	number	Yes	skipped
totalMs	number	Yes	totalMs

EngineResult

Engine result shape accepted by wrapResult. Matches the union of what all engine functions return.

Property	Type	Required	Description
success	boolean	Yes	success
data	unknown	Yes	data
page	import("/mnt/projects/cleocode/packages/lafs/dist/src/types").LAFSPage | undefined	No	page
error	{ code: string; message: string; details?: unknown; exitCode?: number; fix?: string; alternatives?: Array<{ action: string; command: string; }>; problemDetails?: ProblemDetails; } | undefined	No	error

JobStatus

Background job status

JobStatus

BackgroundJob

Background job representation

Property	Type	Required	Description
id	string	Yes	id
operation	string	Yes	operation
status	JobStatus	Yes	status
startedAt	string	Yes	startedAt
completedAt	string | undefined	No	completedAt
result	unknown	Yes	result
error	string | undefined	No	error
progress	number | undefined	No	progress

BackgroundJobManagerConfig

Configuration for BackgroundJobManager

Property	Type	Required	Description
maxJobs	number | undefined	No	maxJobs
retentionMs	number | undefined	No	retentionMs

SessionContext

Immutable snapshot of the bound session context.

Property	Type	Required	Description
sessionId	string	Yes	Active session ID.
scope	{ type: string; epicId?: string; }	No	Session scope.
gradeMode	boolean	Yes	Whether full audit logging is enabled for behavioral grading.
agentPid	number	Yes	PID of the process that bound this context.
boundAt	string	Yes	ISO timestamp when this context was bound.

RateLimitConfig

Per-category rate limit thresholds.

Property	Type	Required	Description
maxRequests	number	Yes	Maximum number of requests allowed within the window.
windowMs	number	Yes	Sliding window duration in milliseconds.

RateLimitingConfig

Full rate limiting configuration across all categories.

Property	Type	Required	Description
enabled	boolean	Yes	Whether rate limiting is active.
query	RateLimitConfig	Yes	Limits for read-only query operations.
mutate	RateLimitConfig	Yes	Limits for mutate (write) operations.
spawn	RateLimitConfig	Yes	Limits for spawn (subagent launch) operations.

LifecycleEnforcementConfig

Lifecycle enforcement configuration (Section 12.2)

Property	Type	Required	Description
mode	"strict" | "advisory" | "off"	Yes	Enforcement mode: strict blocks, advisory warns, off skips
allowSkip	string[]	Yes	Stages that may be skipped without failing gates
emergencyBypass	boolean	Yes	Emergency bypass flag - disables all gate checks

ProtocolValidationConfig

Protocol validation configuration (Section 12.3)

Property	Type	Required	Description
strictMode	boolean	Yes	Enable strict protocol validation
blockOnViolation	boolean	Yes	Block operations on protocol violations
logViolations	boolean	Yes	Log protocol violations to audit trail

DispatchConfig

Property	Type	Required	Description
cliPath	string	Yes	Path to CLEO CLI binary (default: ‘cleo’)
timeout	number	Yes	Operation timeout in milliseconds (default: 30000)
logLevel	"error" | "warn" | "info" | "debug"	Yes	Logging verbosity level (default: ‘info’)
enableMetrics	boolean	Yes	Enable token tracking metrics (default: false)
maxRetries	number	Yes	Retry count for failed operations (default: 3)
queryCache	boolean	Yes	Enable query cache (default: true)
queryCacheTtl	number	Yes	Query cache TTL in milliseconds (default: 30000)
auditLog	boolean	Yes	Enable audit logging (default: true)
strictValidation	boolean	Yes	Strict validation mode (default: true)
lifecycleEnforcement	LifecycleEnforcementConfig	Yes	Lifecycle enforcement configuration (Section 12.2)
protocolValidation	ProtocolValidationConfig	Yes	Protocol validation configuration (Section 12.3)
rateLimiting	RateLimitingConfig	Yes	Rate limiting configuration (Section 13.3)

MCPConfig

Alias for DispatchConfig.

DispatchConfig

ProgressOptions

Property	Type	Required	Description
enabled	boolean	Yes	Whether to show progress (true for human mode, false for JSON mode)
prefix	string | undefined	No	Prefix for progress messages

MviTier

Disclosure tier level for MVI (Minimum Viable Information) filtering.

MviTier

ProjectionConfig

Configuration for a single MVI projection tier.

Property	Type	Required	Description
allowedDomains	string[]	Yes	Operations allowed at this tier
excludeFields	string[] | undefined	No	Fields to exclude from responses
maxDepth	number | undefined	No	Maximum depth for nested objects

ProjectionContext

Property	Type	Required	Description
tier	MviTier	Yes	tier
config	ProjectionConfig	Yes	config