@cleocode/contracts 2026.4.114 → 2026.4.116

package/src/operations/worktree.ts

@@ -0,0 +1,295 @@
+/**
+ * Worktree backend SDK operation types (T1161).
+ *
+ * Wire-format types for the `@cleocode/worktree-backend` SDK surface.
+ * Defines the contract for createWorktree, destroyWorktree, listWorktrees,
+ * and pruneWorktrees operations with XDG path canon (D029) and declarative
+ * hooks (D030 native lift of worktrunk missing features).
+ *
+ * @task T1161
+ * @adr ADR-055
+ */
+
+// ---------------------------------------------------------------------------
+// Hooks framework
+// ---------------------------------------------------------------------------
+
+/**
+ * A declarative lifecycle hook definition for worktree events.
+ *
+ * Hooks are executed synchronously (shell commands) or via node spawns
+ * in the worktree directory. Mirrors the worktrunk hooks contract lifted
+ * natively per D030.
+ *
+ * @task T1161
+ */
+export interface WorktreeHook {
+  /** Shell command to run (executed via `sh -c` in the worktree dir). */
+  command: string;
+  /**
+   * When to run the hook.
+   *
+   * - `post-create` — immediately after `git worktree add` succeeds.
+   * - `post-start`  — after the agent CWD is established (env vars injected).
+   */
+  event: 'post-create' | 'post-start';
+  /**
+   * Optional timeout in milliseconds before the hook is killed.
+   *
+   * @default 30000
+   */
+  timeoutMs?: number;
+  /**
+   * When true, a non-zero exit from this hook causes the worktree operation
+   * to fail. When false (default), errors are logged but ignored.
+   *
+   * @default false
+   */
+  failOnError?: boolean;
+}
+
+/**
+ * Result of a single hook execution.
+ *
+ * @task T1161
+ */
+export interface WorktreeHookResult {
+  /** The hook that was executed. */
+  hook: WorktreeHook;
+  /** Whether the hook exited with code 0. */
+  success: boolean;
+  /** Hook stdout (trimmed). */
+  stdout: string;
+  /** Hook stderr (trimmed). */
+  stderr: string;
+  /** Exit code (null if killed by timeout). */
+  exitCode: number | null;
+  /** Duration in milliseconds. */
+  durationMs: number;
+}
+
+// ---------------------------------------------------------------------------
+// Worktree-include glob pattern
+// ---------------------------------------------------------------------------
+
+/**
+ * A parsed entry from `.cleo/worktree-include`.
+ *
+ * The file lists glob patterns (one per line, `#` comments stripped) that
+ * control which files from the main project tree are symlinked or copied
+ * into new worktrees on creation. This is a native lift of the worktrunk
+ * `.cleo/worktree-include` feature (D030).
+ *
+ * @task T1161
+ */
+export interface WorktreeIncludePattern {
+  /** The raw glob pattern string (e.g. `node_modules/.pnpm/**`). */
+  pattern: string;
+  /**
+   * Whether this entry was negated (prefixed with `!`).
+   *
+   * @default false
+   */
+  negated: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Create operation
+// ---------------------------------------------------------------------------
+
+/**
+ * Options for creating a new agent worktree.
+ *
+ * @task T1161
+ */
+export interface CreateWorktreeOptions {
+  /** The task ID that will own this worktree. */
+  taskId: string;
+  /** The base ref to branch from (default: current HEAD). */
+  baseRef?: string;
+  /** Explicit branch name. Defaults to `task/<taskId>`. */
+  branchName?: string;
+  /**
+   * Reason for creation. Used for git worktree lock comment and audit logs.
+   *
+   * @default 'subagent'
+   */
+  reason?: 'subagent' | 'experiment' | 'parallel-wave';
+  /** Declarative hooks to run after creation. */
+  hooks?: WorktreeHook[];
+  /**
+   * When true, read `.cleo/worktree-include` from the project root and apply
+   * any declared include patterns to the new worktree.
+   *
+   * @default true
+   */
+  applyIncludePatterns?: boolean;
+  /**
+   * When true, apply git worktree lock (`git worktree lock`) to prevent
+   * accidental pruning by git.
+   *
+   * @default true
+   */
+  lockWorktree?: boolean;
+}
+
+/**
+ * Result of a successful worktree creation.
+ *
+ * @task T1161
+ */
+export interface CreateWorktreeResult {
+  /**
+   * Absolute path to the created worktree directory.
+   *
+   * Always under `~/.local/share/cleo/worktrees/<projectHash>/<taskId>/`
+   * per D029 canonical layout.
+   */
+  path: string;
+  /** Branch name created for this worktree (format: `task/<taskId>`). */
+  branch: string;
+  /** Base ref the branch was created from. */
+  baseRef: string;
+  /** Task ID that owns this worktree. */
+  taskId: string;
+  /** Project hash scoping this worktree under the XDG root. */
+  projectHash: string;
+  /** ISO 8601 timestamp when the worktree was created. */
+  createdAt: string;
+  /** Whether git worktree lock was applied. */
+  locked: boolean;
+  /** Environment variables to inject into the spawned agent process. */
+  envVars: Record<string, string>;
+  /** Prompt preamble text for agent isolation context. */
+  preamble: string;
+  /** Results of any post-create hooks that were executed. */
+  hookResults: WorktreeHookResult[];
+  /** Include patterns that were applied (empty if none). */
+  appliedPatterns: WorktreeIncludePattern[];
+}
+
+// ---------------------------------------------------------------------------
+// Destroy operation
+// ---------------------------------------------------------------------------
+
+/**
+ * Options for destroying a worktree.
+ *
+ * @task T1161
+ */
+export interface DestroyWorktreeOptions {
+  /** Task ID whose worktree to destroy. */
+  taskId: string;
+  /**
+   * When true, delete the associated git branch after removing the worktree.
+   *
+   * @default true
+   */
+  deleteBranch?: boolean;
+  /**
+   * When true, cherry-pick any commits on the task branch back to the
+   * orchestrator's current branch before destroying.
+   *
+   * @default false
+   */
+  cherryPickFirst?: boolean;
+}
+
+/**
+ * Result of a worktree destroy operation.
+ *
+ * @task T1161
+ */
+export interface DestroyWorktreeResult {
+  /** Task ID that was destroyed. */
+  taskId: string;
+  /** Whether the worktree directory was successfully removed. */
+  worktreeRemoved: boolean;
+  /** Whether the task branch was deleted. */
+  branchDeleted: boolean;
+  /** Whether cherry-pick was attempted and succeeded. */
+  cherryPicked: boolean;
+  /** Number of commits cherry-picked (0 if none or not requested). */
+  commitCount: number;
+  /** Error message if any step failed (non-fatal — caller decides). */
+  error?: string;
+}
+
+// ---------------------------------------------------------------------------
+// List operation
+// ---------------------------------------------------------------------------
+
+/**
+ * A single entry from the worktree listing.
+ *
+ * @task T1161
+ */
+export interface WorktreeListEntry {
+  /** Absolute path to the worktree directory. */
+  path: string;
+  /** Branch checked out in this worktree. */
+  branch: string;
+  /**
+   * Task ID derived from the worktree directory name.
+   *
+   * Convention: the last path segment is the taskId.
+   */
+  taskId: string;
+  /** Project hash derived from the path. */
+  projectHash: string;
+}
+
+/**
+ * Options for listing worktrees.
+ *
+ * @task T1161
+ */
+export interface ListWorktreesOptions {
+  /** Filter to only return worktrees for a specific project hash. */
+  projectHash?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Prune operation
+// ---------------------------------------------------------------------------
+
+/**
+ * Options for pruning orphaned worktrees.
+ *
+ * @task T1161
+ */
+export interface PruneWorktreesOptions {
+  /** Absolute path to the project root (used to resolve the worktree root). */
+  projectRoot: string;
+  /**
+   * Set of task IDs to preserve. Any worktree directory whose name is NOT in
+   * this set will be pruned.
+   *
+   * When omitted, only stale git administrative entries are pruned (via
+   * `git worktree prune`). No worktree directories are removed.
+   */
+  preserveTaskIds?: Set<string>;
+  /**
+   * When true, also run `git worktree prune` to clean up stale git
+   * administrative entries even if `preserveTaskIds` is not provided.
+   *
+   * @default true
+   */
+  gitPrune?: boolean;
+}
+
+/**
+ * Result of a prune operation.
+ *
+ * @task T1161
+ */
+export interface PruneWorktreesResult {
+  /** Number of worktree directories removed. */
+  removed: number;
+  /** Absolute paths that were removed. */
+  removedPaths: string[];
+  /** Entries that failed to remove (with reasons). */
+  errors: Array<{ path: string; reason: string }>;
+  /** Whether `git worktree prune` was run. */
+  gitPruneRan: boolean;
+}

package/src/peer.ts

@@ -0,0 +1,166 @@
+/**
+ * PeerIdentity — canonical type for CANT agent persona records.
+ *
+ * Introduced by T1210 (v2026.4.110 Wave 0.2) as the SDK-first contract
+ * for agent identity. `packages/cant/src/native-loader.ts` produces
+ * `PeerIdentity[]` from the canonical seed-agents path; dispatch and
+ * CLI layers consume it to drive `cleo agents list` and spawn routing.
+ *
+ * Design constraints (ADR-055 / D028 boundary rules):
+ *  - Lives in `packages/contracts/` — ZERO runtime dependencies.
+ *  - Consumed by `packages/cant/` (loader) and `packages/cleo/` (CLI).
+ *  - No cross-package relative imports.
+ *
+ * @module peer
+ * @task T1210
+ * @epic T1144
+ */
+
+// ============================================================================
+// PeerKind taxonomy
+// ============================================================================
+
+/**
+ * Classification of a peer agent's role in the orchestration hierarchy.
+ *
+ * Mirrors the three-tier model in {@link AgentSpawnCapability}:
+ *  - `orchestrator` — coordinates multi-agent workflows; may spawn leads and workers
+ *  - `lead`         — specialist; dispatches workers only
+ *  - `worker`       — terminal; executes tasks, cannot spawn
+ *  - `subagent`     — universal base role; resolved to a specific tier at spawn time
+ */
+export type PeerKind = 'orchestrator' | 'lead' | 'worker' | 'subagent';
+
+// ============================================================================
+// PeerIdentity
+// ============================================================================
+
+/**
+ * Canonical identity record for a CANT-defined agent persona.
+ *
+ * Produced by `loadSeedAgentIdentities()` in `packages/cant/src/native-loader.ts`
+ * and consumed by the dispatch layer + `cleo agents list`. Every field is
+ * required — loaders MUST supply a value for each field, using empty strings
+ * for absent optional content in the source `.cant` file.
+ *
+ * @example
+ * ```ts
+ * import type { PeerIdentity } from '@cleocode/contracts';
+ *
+ * const personas: PeerIdentity[] = loadSeedAgentIdentities();
+ * for (const p of personas) {
+ *   console.log(`${p.peerId} (${p.peerKind}): ${p.displayName}`);
+ * }
+ * ```
+ *
+ * @task T1210
+ * @epic T1144
+ */
+export interface PeerIdentity {
+  /**
+   * Stable business identifier for the agent, matching the `agent <id>:` block
+   * name in the `.cant` file and the `agents.agent_id` column in the registry.
+   *
+   * @example `"cleo-prime"`, `"cleo-dev"`, `"cleo-subagent"`
+   */
+  peerId: string;
+
+  /**
+   * Role classification derived from the `role:` field in the `.cant` agent
+   * block. Determines spawn authority in the orchestration hierarchy.
+   */
+  peerKind: PeerKind;
+
+  /**
+   * Absolute path to the canonical `.cant` file that defines this persona.
+   *
+   * For seed-agents this is inside `packages/agents/seed-agents/` or
+   * `packages/agents/cleo-subagent.cant` (universal base). For project-tier
+   * personas it is inside `.cleo/cant/agents/`.
+   */
+  cantFile: string;
+
+  /**
+   * Human-readable name for the persona, derived from the `display_name:` or
+   * `description:` field. Falls back to the `peerId` value when neither field
+   * is present in the source `.cant`.
+   */
+  displayName: string;
+
+  /**
+   * Short description of the persona's purpose, taken from the `description:`
+   * field in the `.cant` agent block. Empty string when absent.
+   */
+  description: string;
+}
+
+// ============================================================================
+// Runtime validation
+// ============================================================================
+
+/**
+ * Validate that an unknown value conforms to the {@link PeerIdentity} shape.
+ *
+ * Performs a lightweight structural check without Zod to keep `packages/contracts`
+ * dependency-free at runtime. Callers that need schema-level validation
+ * (e.g., test fixtures) can use {@link assertPeerIdentity}.
+ *
+ * @param value - Value to test.
+ * @returns `true` when `value` is a valid {@link PeerIdentity}.
+ *
+ * @example
+ * ```ts
+ * if (isPeerIdentity(raw)) {
+ *   console.log(raw.peerId);
+ * }
+ * ```
+ */
+export function isPeerIdentity(value: unknown): value is PeerIdentity {
+  if (typeof value !== 'object' || value === null) return false;
+  const v = value as Record<string, unknown>;
+  return (
+    typeof v['peerId'] === 'string' &&
+    v['peerId'].length > 0 &&
+    typeof v['peerKind'] === 'string' &&
+    ['orchestrator', 'lead', 'worker', 'subagent'].includes(v['peerKind'] as string) &&
+    typeof v['cantFile'] === 'string' &&
+    v['cantFile'].length > 0 &&
+    typeof v['displayName'] === 'string' &&
+    typeof v['description'] === 'string'
+  );
+}
+
+/**
+ * Assert that a value is a valid {@link PeerIdentity}, throwing a descriptive
+ * error when the shape does not conform.
+ *
+ * @param value - Value to assert.
+ * @throws {TypeError} When the value does not satisfy {@link isPeerIdentity}.
+ *
+ * @example
+ * ```ts
+ * assertPeerIdentity(raw); // throws if invalid
+ * console.log(raw.peerId); // safe
+ * ```
+ */
+export function assertPeerIdentity(value: unknown): asserts value is PeerIdentity {
+  if (!isPeerIdentity(value)) {
+    throw new TypeError(
+      `Expected PeerIdentity { peerId, peerKind, cantFile, displayName, description } — got: ${JSON.stringify(value)}`,
+    );
+  }
+}
+
+/**
+ * Validate and filter an array of unknown values to {@link PeerIdentity}[].
+ *
+ * Invalid entries are silently dropped. This is the safe variant for loading
+ * from untrusted sources (e.g., the result of parsing a directory of `.cant`
+ * files whose format may vary).
+ *
+ * @param values - Array of unknown values.
+ * @returns Array containing only values that pass {@link isPeerIdentity}.
+ */
+export function filterPeerIdentities(values: unknown[]): PeerIdentity[] {
+  return values.filter(isPeerIdentity);
+}

package/src/transport.ts

@@ -12,7 +12,12 @@
  */
 
 import type { TransportConfig } from './agent-registry.js';
-import type { ConduitMessage } from './conduit.js';
+import type {
+  ConduitMessage,
+  ConduitTopicPublishOptions,
+  ConduitTopicSubscribeOptions,
+  ConduitUnsubscribe,
+} from './conduit.js';
 
 // ============================================================================
 // Transport connection config
@@ -61,6 +66,58 @@ export interface Transport {
 
   /** Subscribe to real-time events (SSE/WebSocket). Returns unsubscribe. */
   subscribe?(handler: (message: ConduitMessage) => void): () => void;
+
+  // ── A2A Topic Operations (T1252 — optional, LocalTransport only) ─────────
+
+  /**
+   * Subscribe agent to a named topic.
+   *
+   * Optional — only implemented by `LocalTransport`. Cloud transports
+   * (HttpTransport, SseTransport) do not yet support topic operations.
+   *
+   * @param topicName - Topic name, e.g. `"epic-T1149.wave-2"`.
+   * @param options   - Subscription filter options.
+   * @task T1252
+   */
+  subscribeTopic?(topicName: string, options?: ConduitTopicSubscribeOptions): Promise<void>;
+
+  /**
+   * Publish a message to a named topic.
+   *
+   * Optional — only implemented by `LocalTransport`.
+   *
+   * @param topicName - Target topic name.
+   * @param content   - Message content.
+   * @param options   - Kind and optional payload.
+   * @task T1252
+   */
+  publishToTopic?(
+    topicName: string,
+    content: string,
+    options?: ConduitTopicPublishOptions,
+  ): Promise<{ messageId: string }>;
+
+  /**
+   * Register a real-time handler for topic messages.
+   *
+   * Optional — only implemented by `LocalTransport`.
+   *
+   * @param topicName - Topic name to watch.
+   * @param handler   - Handler invoked for each new message.
+   * @returns Unsubscribe function.
+   * @task T1252
+   */
+  onTopic?(topicName: string, handler: (message: ConduitMessage) => void): ConduitUnsubscribe;
+
+  /**
+   * Unsubscribe agent from a named topic.
+   *
+   * Optional — only implemented by `LocalTransport`.
+   *
+   * @param topicName - Topic name to leave.
+   * @task T1252
+   */
+  unsubscribeTopic?(topicName: string): Promise<void>;
 }
 
 // ============================================================================