@cleocode/contracts 2026.3.74 → 2026.4.0

package/src/data-accessor.ts

@@ -17,6 +17,26 @@ import type { ArchivedTask } from './archive.js';
 import type { Session } from './session.js';
 import type { Task, TaskPriority, TaskSize, TaskStatus, TaskType } from './task.js';
 
+/**
+ * Agent instance row shape for DataAccessor methods.
+ * Mirrors the agent_instances Drizzle table in core but avoids Drizzle dependency.
+ */
+export interface DataAccessorAgentInstance {
+  id: string;
+  agentType: string;
+  status: string;
+  sessionId: string | null;
+  taskId: string | null;
+  startedAt: string;
+  lastHeartbeat: string;
+  stoppedAt: string | null;
+  errorCount: number;
+  totalTasksCompleted: number;
+  capacity: string;
+  metadataJson: string | null;
+  parentAgentId: string | null;
+}
+
 /** Archive-specific fields for task upsert. */
 export interface ArchiveFields {
   archivedAt?: string;
@@ -83,6 +103,7 @@ export interface TaskFieldUpdates {
   modifiedBy?: string | null;
   sessionId?: string | null;
   updatedAt?: string | null;
+  assignee?: string | null;
 }
 
 /**
@@ -227,6 +248,41 @@ export interface DataAccessor {
 
   /** Remove a single session by ID. */
   removeSingleSession(sessionId: string): Promise<void>;
+
+  // ---- Agent instances ----
+
+  /** List agent instances with optional filters. Returns rows from agent_instances table. */
+  listAgentInstances(filters?: {
+    status?: string | string[];
+    agentType?: string | string[];
+  }): Promise<DataAccessorAgentInstance[]>;
+
+  /** Get a single agent instance by ID. Returns null if not found. */
+  getAgentInstance(agentId: string): Promise<DataAccessorAgentInstance | null>;
+
+  // ---- Agent task claiming ----
+
+  /**
+   * Atomically claim a task for an agent.
+   *
+   * Uses `UPDATE ... WHERE assignee IS NULL OR assignee = agentId` to prevent
+   * race conditions. Throws if the task is already claimed by a different agent.
+   *
+   * @param taskId - ID of the task to claim.
+   * @param agentId - Agent identifier claiming the task.
+   * @throws {Error} When the task is not found or is already claimed by another agent.
+   */
+  claimTask(taskId: string, agentId: string): Promise<void>;
+
+  /**
+   * Release a claimed task, clearing its assignee.
+   *
+   * No-op if the task is not currently claimed.
+   *
+   * @param taskId - ID of the task to unclaim.
+   * @throws {Error} When the task is not found.
+   */
+  unclaimTask(taskId: string): Promise<void>;
 }
 
 // Factory functions (createDataAccessor, getAccessor) live in @cleocode/core,

package/src/index.ts

@@ -8,6 +8,13 @@
 
 // === Provider Adapter Contracts ===
 export type { AdapterHealthStatus, CLEOProviderAdapter } from './adapter.js';
+// === Agent Registry (credential management) ===
+export type {
+  AgentCredential,
+  AgentListFilter,
+  AgentRegistryAPI,
+  TransportConfig,
+} from './agent-registry.js';
 // === Archive Types ===
 export type {
   ArchiveCycleTimesReport,
@@ -33,6 +40,13 @@ export type {
   SupersededEntry,
 } from './brain.js';
 export type { AdapterCapabilities } from './capabilities.js';
+// === Code Symbol Types (tree-sitter AST) ===
+export type {
+  BatchParseResult,
+  CodeSymbol,
+  CodeSymbolKind,
+  ParseResult,
+} from './code-symbol.js';
 // === Conduit Protocol (agent-to-agent communication) ===
 export type {
   Conduit,
@@ -76,6 +90,7 @@ export type {
   ArchiveFields,
   ArchiveFile,
   DataAccessor,
+  DataAccessorAgentInstance,
   QueryTasksResult,
   TaskFieldUpdates,
   TaskQueryFilters,
@@ -182,6 +197,14 @@ export type {
 export * as ops from './operations/index.js';
 // Commonly used ops types re-exported at top level for convenience
 export type { BrainState } from './operations/orchestrate.js';
+// === Orchestration Hierarchy ===
+export {
+  type AgentHierarchy,
+  type AgentHierarchyEntry,
+  type EscalationChain,
+  type OrchestrationHierarchyAPI,
+  OrchestrationLevel,
+} from './orchestration-hierarchy.js';
 export type { AdapterPathProvider } from './provider-paths.js';
 // === Result Types (Dashboard, Stats, Log, Context, Sequence, Analysis, Deps) ===
 export type {
@@ -313,7 +336,12 @@ export type {
   TesseraTemplate,
   TesseraVariable,
 } from './tessera.js';
-export type { AdapterTransportProvider } from './transport.js';
+// === Transport (low-level wire protocol) ===
+export type {
+  AdapterTransportProvider,
+  Transport,
+  TransportConnectConfig,
+} from './transport.js';
 // === WarpChain Types ===
 export type {
   ChainShape,
@@ -329,3 +357,6 @@ export type {
   WarpLink,
   WarpStage,
 } from './warp-chain.js';
+
+// === WASM SDK (Rust crate bindings) ===
+export * as wasm from './wasm/index.js';

package/src/lafs.ts

@@ -2,7 +2,7 @@
  * LAFS (LLM-Agent-First Schema) unified envelope types.
  *
  * Defines canonical LAFS types inline (contracts has ZERO external dependencies).
- * In the main CLEO codebase these are re-exported from @cleocode/lafs-protocol;
+ * In the main CLEO codebase these are re-exported from @cleocode/lafs;
  * here they are defined as plain interfaces for maximum portability.
  *
  * @epic T4654
@@ -10,7 +10,7 @@
  */
 
 // ---------------------------------------------------------------------------
-// Canonical LAFS types (inlined from @cleocode/lafs-protocol)
+// Canonical LAFS types (inlined from @cleocode/lafs)
 // ---------------------------------------------------------------------------
 
 /** LAFS error category. */

package/src/orchestration-hierarchy.ts

@@ -0,0 +1,107 @@
+/**
+ * Orchestration Hierarchy — 5-level agent hierarchy types.
+ *
+ * Codifies the agent authority chain from ORCH-PLAN.md:
+ *   Level 0: HITL (Human-In-The-Loop) — Owner, final authority
+ *   Level 1: Prime Orchestrator — Cross-project coordination
+ *   Level 2: Project Lead — Project-level architecture decisions
+ *   Level 3: Team Lead — Team-level task management, can spawn ephemeral agents
+ *   Level 4: Ephemeral — Task-scoped agents spawned by Team Leads
+ *
+ * @see docs/specs/CLEO-ORCH-PLAN.md
+ * @task T217
+ */
+
+// ============================================================================
+// Hierarchy levels
+// ============================================================================
+
+/** The 5 orchestration levels in order of authority. */
+export enum OrchestrationLevel {
+  /** Level 0: Human owner. Final authority. Never contacted by agents directly. */
+  HITL = 0,
+  /** Level 1: Prime Orchestrator. Cross-project coordination. Breaks ties. */
+  Prime = 1,
+  /** Level 2: Project Lead. Architecture decisions within a project. */
+  ProjectLead = 2,
+  /** Level 3: Team Lead. Task management. Can spawn ephemeral agents. */
+  TeamLead = 3,
+  /** Level 4: Ephemeral agent. Task-scoped, short-lived. */
+  Ephemeral = 4,
+}
+
+// ============================================================================
+// Agent hierarchy membership
+// ============================================================================
+
+/** An agent's position in the orchestration hierarchy. */
+export interface AgentHierarchyEntry {
+  /** The agent's unique ID (e.g. 'cleo-rust-lead'). */
+  agentId: string;
+  /** Display name for human-readable output. */
+  displayName: string;
+  /** The agent's orchestration level. */
+  level: OrchestrationLevel;
+  /** The agent's direct superior (null for HITL). */
+  reportsTo: string | null;
+  /** Agents this agent directly manages (empty for Ephemeral). */
+  manages: string[];
+  /** Project scope (null for cross-project agents like Prime). */
+  projectId: string | null;
+  /** Team scope within a project (e.g. 'cleocode', 'signaldock'). */
+  teamId: string | null;
+  /** Whether this agent can spawn ephemeral sub-agents. */
+  canSpawn: boolean;
+}
+
+/** The full agent hierarchy tree. */
+export interface AgentHierarchy {
+  /** All agents in the hierarchy, keyed by agentId. */
+  agents: Record<string, AgentHierarchyEntry>;
+  /** The Prime Orchestrator agent ID. */
+  primeId: string;
+  /** Project IDs in this hierarchy. */
+  projectIds: string[];
+}
+
+// ============================================================================
+// Escalation chain
+// ============================================================================
+
+/** An escalation path from an agent to its authority chain. */
+export interface EscalationChain {
+  /** The requesting agent. */
+  fromAgentId: string;
+  /** Ordered list of agents to escalate to (nearest first). */
+  chain: string[];
+  /** The final authority (PRIME or HITL). */
+  finalAuthority: string;
+}
+
+// ============================================================================
+// Hierarchy API
+// ============================================================================
+
+/** API for querying and managing the agent hierarchy. */
+export interface OrchestrationHierarchyAPI {
+  /** Get the full hierarchy. */
+  getHierarchy(): AgentHierarchy;
+
+  /** Get a single agent's hierarchy entry. */
+  getAgent(agentId: string): AgentHierarchyEntry | null;
+
+  /** Get all agents at a specific level. */
+  getAgentsAtLevel(level: OrchestrationLevel): AgentHierarchyEntry[];
+
+  /** Get the escalation chain for an agent. */
+  getEscalationChain(agentId: string): EscalationChain;
+
+  /** Get all agents managed by a specific agent (direct reports). */
+  getDirectReports(agentId: string): AgentHierarchyEntry[];
+
+  /** Check if agent A has authority over agent B. */
+  hasAuthority(agentIdA: string, agentIdB: string): boolean;
+
+  /** Get all agents scoped to a project. */
+  getProjectAgents(projectId: string): AgentHierarchyEntry[];
+}

package/src/task.ts

@@ -214,6 +214,9 @@ export interface Task {
    * @task T060
    */
   pipelineStage?: string | null;
+
+  /** Agent ID that has claimed/is assigned to this task. Null when unclaimed. */
+  assignee?: string | null;
 }
 
 // ---------------------------------------------------------------------------

package/src/transport.ts

@@ -1,12 +1,76 @@
 /**
- * Transport provider interface for CLEO provider adapters.
- * Allows providers to supply custom inter-agent transport mechanisms.
- * @task T5240
+ * Transport — Low-level wire protocol adapters for agent messaging.
+ *
+ * Transport is the HOW layer: it moves messages over the wire using
+ * HTTP polling, SSE, WebSocket, or in-process napi-rs calls.
+ *
+ * The Conduit interface (conduit.ts) wraps Transport to provide
+ * high-level messaging semantics (WHAT the agent wants to do).
+ *
+ * @see docs/specs/SIGNALDOCK-UNIFIED-AGENT-REGISTRY.md Section 4
+ * @module transport
  */
 
+import type { TransportConfig } from './agent-registry.js';
+import type { ConduitMessage } from './conduit.js';
+
+// ============================================================================
+// Transport connection config
+// ============================================================================
+
+/** Configuration passed to Transport.connect(). */
+export interface TransportConnectConfig extends TransportConfig {
+  /** Agent ID to connect as. */
+  agentId: string;
+  /** API key for authentication. */
+  apiKey: string;
+  /** Base URL of the messaging API. */
+  apiBaseUrl: string;
+}
+
+// ============================================================================
+// Transport interface
+// ============================================================================
+
+/** Low-level wire transport for agent messaging. */
+export interface Transport {
+  /** Transport name for logging/debugging (e.g. 'http', 'sse', 'ws', 'local'). */
+  readonly name: string;
+
+  /** Connect to the messaging backend. */
+  connect(config: TransportConnectConfig): Promise<void>;
+
+  /** Disconnect from the messaging backend. */
+  disconnect(): Promise<void>;
+
+  /** Send a message payload. */
+  push(
+    to: string,
+    content: string,
+    options?: {
+      conversationId?: string;
+      replyTo?: string;
+    },
+  ): Promise<{ messageId: string }>;
+
+  /** Poll for new messages (non-destructive peek). */
+  poll(options?: { limit?: number; since?: string }): Promise<ConduitMessage[]>;
+
+  /** Acknowledge processed messages (marks as delivered). */
+  ack(messageIds: string[]): Promise<void>;
+
+  /** Subscribe to real-time events (SSE/WebSocket). Returns unsubscribe. */
+  subscribe?(handler: (message: ConduitMessage) => void): () => void;
+}
+
+// ============================================================================
+// Legacy adapter (kept for backward compatibility during migration)
+// ============================================================================
+
+/** @deprecated Use Transport instead. Will be removed after unification. */
 export interface AdapterTransportProvider {
-  /** Create a transport instance for inter-agent communication */
+  /** Create a transport instance for inter-agent communication. */
   createTransport(): unknown;
-  /** Name of this transport type for logging/debugging */
+  /** Name of this transport type for logging/debugging. */
   readonly transportName: string;
 }

package/src/wasm/index.ts

@@ -0,0 +1,193 @@
+/**
+ * Central WASM SDK for CLEO Core Contracts
+ *
+ * Provides unified access to all Rust crate WASM modules:
+ * - lafs-core: LAFS envelope types and validation
+ * - conduit-core: Conduit wire types and CANT metadata
+ * - cant-core: CANT grammar parser (via @cleocode/cant)
+ *
+ * Usage:
+ * ```typescript
+ * import { initWasm, lafs, conduit } from '@cleocode/contracts/wasm';
+ *
+ * await initWasm();
+ *
+ * // LAFS
+ * const meta = new lafs.WasmLafsMeta('tasks.list', 'http');
+ * const envelope = lafs.WasmLafsEnvelope.createSuccess('{"tasks":[]}', meta);
+ *
+ * // Conduit
+ * const msg = new conduit.WasmConduitMessage('msg-1', 'agent-a', 'Hello', '2026-03-25T00:00:00Z');
+ * const cant = new conduit.WasmCantMetadata('actionable', '["@agent"]', '["T123"]', '["#tag"]');
+ * ```
+ */
+
+/** Resolved type of the lafs-core WASM module. */
+type LafsWasmModule = typeof import('./lafs-core/lafs_core.js');
+/** Resolved type of the conduit-core WASM module. */
+type ConduitWasmModule = typeof import('./conduit-core/conduit_core.js');
+
+// WASM module instances
+let lafsModule: LafsWasmModule | null = null;
+let conduitModule: ConduitWasmModule | null = null;
+let isInitialized = false;
+let isInitializing = false;
+let initPromise: Promise<void> | null = null;
+
+/**
+ * Initialize all WASM modules
+ * Must be called before using any WASM classes/functions
+ *
+ * @example
+ * ```typescript
+ * import { initWasm, lafs, conduit } from '@cleocode/contracts/wasm';
+ *
+ * await initWasm();
+ *
+ * // Now you can use WASM classes
+ * const meta = new lafs.WasmLafsMeta('tasks.list', 'http');
+ * ```
+ */
+export async function initWasm(): Promise<void> {
+  if (isInitialized) return;
+  if (isInitializing) {
+    return initPromise!;
+  }
+
+  isInitializing = true;
+  initPromise = (async () => {
+    try {
+      // Dynamic imports to avoid loading if not needed
+      const [lafs, conduit] = await Promise.all([
+        import('./lafs-core/lafs_core.js'),
+        import('./conduit-core/conduit_core.js'),
+      ]);
+
+      // Initialize modules
+      await Promise.all([lafs.default(), conduit.default()]);
+
+      lafsModule = lafs;
+      conduitModule = conduit;
+      isInitialized = true;
+    } catch (_error) {
+      throw new Error('WASM initialization failed. Ensure WASM files are present.');
+    }
+  })();
+
+  await initPromise;
+  isInitializing = false;
+}
+
+/**
+ * Check if WASM is initialized and ready to use
+ *
+ * @returns true if WASM modules are loaded and initialized
+ */
+export function isWasmReady(): boolean {
+  return isInitialized;
+}
+
+/**
+ * LAFS Core WASM exports
+ *
+ * Available after calling initWasm():
+ * - WasmLafsTransport - Transport type (Cli, Http, Grpc, Sdk)
+ * - WasmLafsMeta - Metadata for LAFS envelopes
+ * - WasmLafsEnvelope - The main LAFS response envelope
+ * - createTransport() - Helper to create transport from string
+ */
+export const lafs = {
+  /**
+   * LAFS Transport enum
+   * Use WasmLafsTransport.cli(), .http(), .grpc(), or .sdk()
+   */
+  get WasmLafsTransport() {
+    if (!lafsModule) throw new Error('WASM not initialized. Call initWasm() first.');
+    return lafsModule.WasmLafsTransport;
+  },
+
+  /**
+   * LAFS Metadata constructor
+   * new WasmLafsMeta(operation: string, transport: string)
+   */
+  get WasmLafsMeta() {
+    if (!lafsModule) throw new Error('WASM not initialized. Call initWasm() first.');
+    return lafsModule.WasmLafsMeta;
+  },
+
+  /**
+   * LAFS Envelope class
+   * Use WasmLafsEnvelope.createSuccess() or .createError()
+   */
+  get WasmLafsEnvelope() {
+    if (!lafsModule) throw new Error('WASM not initialized. Call initWasm() first.');
+    return lafsModule.WasmLafsEnvelope;
+  },
+
+  /**
+   * Helper function to create transport from string
+   * @param transport - "cli", "http", "grpc", or "sdk"
+   */
+  get createTransport() {
+    if (!lafsModule) throw new Error('WASM not initialized. Call initWasm() first.');
+    return lafsModule.create_transport;
+  },
+};
+
+/**
+ * Conduit Core WASM exports
+ *
+ * Available after calling initWasm():
+ * - WasmConduitMessage - Agent-to-agent messages
+ * - WasmConduitState - Connection states (Disconnected, Connecting, Connected, etc.)
+ * - WasmCantMetadata - CANT parsing results
+ * - parseConduitMessage() - Parse message from JSON
+ * - createConduitState() - Create state from string
+ */
+export const conduit = {
+  /**
+   * Conduit Message constructor
+   * new WasmConduitMessage(id, from, content, timestamp)
+   */
+  get WasmConduitMessage() {
+    if (!conduitModule) throw new Error('WASM not initialized. Call initWasm() first.');
+    return conduitModule.WasmConduitMessage;
+  },
+
+  /**
+   * Conduit State enum
+   * Use WasmConduitState.disconnected(), .connecting(), .connected(), etc.
+   */
+  get WasmConduitState() {
+    if (!conduitModule) throw new Error('WASM not initialized. Call initWasm() first.');
+    return conduitModule.WasmConduitState;
+  },
+
+  /**
+   * CANT Metadata constructor
+   * new WasmCantMetadata(directiveType, addressesJson, taskRefsJson, tagsJson)
+   */
+  get WasmCantMetadata() {
+    if (!conduitModule) throw new Error('WASM not initialized. Call initWasm() first.');
+    return conduitModule.WasmCantMetadata;
+  },
+
+  /**
+   * Parse a ConduitMessage from JSON string
+   * @param json - JSON string
+   * @returns WasmConduitMessage or undefined
+   */
+  get parseConduitMessage() {
+    if (!conduitModule) throw new Error('WASM not initialized. Call initWasm() first.');
+    return conduitModule.parse_conduit_message;
+  },
+
+  /**
+   * Create a ConduitState from string
+   * @param state - "disconnected", "connecting", "connected", "reconnecting", "error"
+   */
+  get createConduitState() {
+    if (!conduitModule) throw new Error('WASM not initialized. Call initWasm() first.');
+    return conduitModule.create_conduit_state;
+  },
+};