@cleocode/contracts 2026.4.114 → 2026.4.116

package/dist/peer.d.ts

@@ -0,0 +1,125 @@
+/**
+ * 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
+ */
+/**
+ * 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';
+/**
+ * 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;
+}
+/**
+ * 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 declare function isPeerIdentity(value: unknown): value is PeerIdentity;
+/**
+ * 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 declare function assertPeerIdentity(value: unknown): asserts value is PeerIdentity;
+/**
+ * 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 declare function filterPeerIdentities(values: unknown[]): PeerIdentity[];
+//# sourceMappingURL=peer.d.ts.map

package/dist/peer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"peer.d.ts","sourceRoot":"","sources":["../src/peer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAMH;;;;;;;;GAQG;AACH,MAAM,MAAM,QAAQ,GAAG,cAAc,GAAG,MAAM,GAAG,QAAQ,GAAG,UAAU,CAAC;AAMvE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;OAKG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,QAAQ,EAAE,QAAQ,CAAC;IAEnB;;;;;;OAMG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;CACrB;AAMD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CAapE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,YAAY,CAMhF;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,YAAY,EAAE,CAEtE"}

package/dist/peer.js

@@ -0,0 +1,82 @@
+/**
+ * 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
+ */
+// ============================================================================
+// 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) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const v = value;
+    return (typeof v['peerId'] === 'string' &&
+        v['peerId'].length > 0 &&
+        typeof v['peerKind'] === 'string' &&
+        ['orchestrator', 'lead', 'worker', 'subagent'].includes(v['peerKind']) &&
+        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) {
+    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) {
+    return values.filter(isPeerIdentity);
+}
+//# sourceMappingURL=peer.js.map

package/dist/peer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"peer.js","sourceRoot":"","sources":["../src/peer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAgFH,+EAA+E;AAC/E,qBAAqB;AACrB,+EAA+E;AAE/E;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC9D,MAAM,CAAC,GAAG,KAAgC,CAAC;IAC3C,OAAO,CACL,OAAO,CAAC,CAAC,QAAQ,CAAC,KAAK,QAAQ;QAC/B,CAAC,CAAC,QAAQ,CAAC,CAAC,MAAM,GAAG,CAAC;QACtB,OAAO,CAAC,CAAC,UAAU,CAAC,KAAK,QAAQ;QACjC,CAAC,cAAc,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAW,CAAC;QAChF,OAAO,CAAC,CAAC,UAAU,CAAC,KAAK,QAAQ;QACjC,CAAC,CAAC,UAAU,CAAC,CAAC,MAAM,GAAG,CAAC;QACxB,OAAO,CAAC,CAAC,aAAa,CAAC,KAAK,QAAQ;QACpC,OAAO,CAAC,CAAC,aAAa,CAAC,KAAK,QAAQ,CACrC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAc;IAC/C,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,SAAS,CACjB,yFAAyF,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CACjH,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAiB;IACpD,OAAO,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;AACvC,CAAC"}

package/dist/transport.d.ts

@@ -11,7 +11,7 @@
  * @module transport
  */
 import type { TransportConfig } from './agent-registry.js';
-import type { ConduitMessage } from './conduit.js';
+import type { ConduitMessage, ConduitTopicPublishOptions, ConduitTopicSubscribeOptions, ConduitUnsubscribe } from './conduit.js';
 /** Configuration passed to Transport.connect(). */
 export interface TransportConnectConfig extends TransportConfig {
     /** Agent ID to connect as. */
@@ -45,6 +45,50 @@ export interface Transport {
     ack(messageIds: string[]): Promise<void>;
     /** Subscribe to real-time events (SSE/WebSocket). Returns unsubscribe. */
     subscribe?(handler: (message: ConduitMessage) => void): () => void;
+    /**
+     * 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>;
 }
 /** @deprecated Use Transport instead. Will be removed after unification. */
 export interface AdapterTransportProvider {

package/dist/transport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAMnD,mDAAmD;AACnD,MAAM,WAAW,sBAAuB,SAAQ,eAAe;IAC7D,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAC;CACpB;AAMD,oDAAoD;AACpD,MAAM,WAAW,SAAS;IACxB,gFAAgF;IAChF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,wCAAwC;IACxC,OAAO,CAAC,MAAM,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvD,6CAA6C;IAC7C,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5B,8BAA8B;IAC9B,IAAI,CACF,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QACR,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,GACA,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAElC,oDAAoD;IACpD,IAAI,CAAC,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;IAE9E,2DAA2D;IAC3D,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzC,0EAA0E;IAC1E,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CACpE;AAMD,4EAA4E;AAC5E,MAAM,WAAW,wBAAwB;IACvC,iEAAiE;IACjE,eAAe,IAAI,OAAO,CAAC;IAC3B,yDAAyD;IACzD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC"}
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,KAAK,EACV,cAAc,EACd,0BAA0B,EAC1B,4BAA4B,EAC5B,kBAAkB,EACnB,MAAM,cAAc,CAAC;AAMtB,mDAAmD;AACnD,MAAM,WAAW,sBAAuB,SAAQ,eAAe;IAC7D,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAC;CACpB;AAMD,oDAAoD;AACpD,MAAM,WAAW,SAAS;IACxB,gFAAgF;IAChF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,wCAAwC;IACxC,OAAO,CAAC,MAAM,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvD,6CAA6C;IAC7C,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5B,8BAA8B;IAC9B,IAAI,CACF,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QACR,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,GACA,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAElC,oDAAoD;IACpD,IAAI,CAAC,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;IAE9E,2DAA2D;IAC3D,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzC,0EAA0E;IAC1E,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IAInE;;;;;;;;;OASG;IACH,cAAc,CAAC,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,4BAA4B,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1F;;;;;;;;;OASG;IACH,cAAc,CAAC,CACb,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,0BAA0B,GACnC,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAElC;;;;;;;;;OASG;IACH,OAAO,CAAC,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,GAAG,kBAAkB,CAAC;IAE5F;;;;;;;OAOG;IACH,gBAAgB,CAAC,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrD;AAMD,4EAA4E;AAC5E,MAAM,WAAW,wBAAwB;IACvC,iEAAiE;IACjE,eAAe,IAAI,OAAO,CAAC;IAC3B,yDAAyD;IACzD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/contracts",
-  "version": "2026.4.114",
+  "version": "2026.4.116",
   "description": "Domain types, interfaces, and contracts for the CLEO ecosystem",
   "type": "module",
   "main": "./dist/index.js",

package/src/conduit.ts

@@ -35,6 +35,76 @@ export interface ConduitMessage {
   timestamp: string;
   /** Optional structured metadata. */
   metadata?: Record<string, unknown>;
+  /**
+   * Message semantics for A2A (Agent-to-Agent) coordination.
+   *
+   * - `message` — default, backward-compat direct message
+   * - `request` — sender expects a response; receiver should reply
+   * - `notify`  — informational broadcast; no response expected
+   * - `subscribe` — sender subscribes to a topic
+   *
+   * @default `"message"` for backward compatibility
+   * @see T1252 CONDUIT A2A
+   */
+  kind?: 'message' | 'request' | 'notify' | 'subscribe';
+  /**
+   * Sender peer identity — stable peer ID from PeerIdentity.peerId.
+   * Populated for A2A topic messages; absent on legacy direct messages.
+   *
+   * @see T1252 CONDUIT A2A
+   */
+  fromPeerId?: string;
+  /**
+   * Recipient peer identity — agent peerId for direct messages, `null` for
+   * topic broadcasts (one-to-many).
+   *
+   * @see T1252 CONDUIT A2A
+   */
+  toPeerId?: string | null;
+  /**
+   * Structured payload accompanying the message.
+   *
+   * JSON-serializable object; stored as TEXT in the database.
+   * Used for structured A2A coordination data (findings, events, etc.).
+   *
+   * @see T1252 CONDUIT A2A
+   */
+  payload?: Record<string, unknown>;
+}
+
+/**
+ * A2A (Agent-to-Agent) topic subscription options.
+ *
+ * Passed to `subscribeTopic()` to filter messages by kind or event.
+ *
+ * @see T1252 CONDUIT A2A
+ */
+export interface ConduitTopicSubscribeOptions {
+  /**
+   * Filter messages by kind. When absent, all kinds are delivered.
+   * @example `['notify', 'request']`
+   */
+  filter?: {
+    /** Accept only these message kinds. */
+    kind?: Array<'message' | 'request' | 'notify' | 'subscribe'>;
+    /** Accept only messages whose `payload.event` is in this list. */
+    event?: string[];
+  };
+}
+
+/**
+ * Options for publishing a message to a topic.
+ *
+ * @see T1252 CONDUIT A2A
+ */
+export interface ConduitTopicPublishOptions {
+  /**
+   * Message kind.
+   * @default `"message"`
+   */
+  kind?: 'message' | 'request' | 'notify' | 'subscribe';
+  /** Structured payload to attach to the message. */
+  payload?: Record<string, unknown>;
 }
 
 /** Options for sending a message. */
@@ -123,6 +193,57 @@ export interface Conduit {
   /** List currently online agents (optional — may not be supported by all implementations). */
   listOnline?(): Promise<string[]>;
 
+  // --- A2A Topic Pub-Sub (T1252) ---
+
+  /**
+   * Subscribe this agent to a named topic for broadcast messages.
+   *
+   * Creates the topic in conduit.db if it does not yet exist (idempotent).
+   * The agent will receive messages published to this topic via `onTopic()`.
+   *
+   * @param topicName - Topic name, e.g. `"epic-T1149.wave-2"` or `"epic-T1149.coordination"`.
+   * @param options   - Optional subscription filter (kind, event).
+   * @throws When no local transport is available (LocalTransport required for topic ops).
+   * @see T1252 CONDUIT A2A
+   */
+  subscribeTopic?(topicName: string, options?: ConduitTopicSubscribeOptions): Promise<void>;
+
+  /**
+   * Publish a message to a topic (broadcast to all current subscribers).
+   *
+   * @param topicName - Target topic name.
+   * @param content   - Human-readable message content.
+   * @param options   - Message kind and optional structured payload.
+   * @returns Send result with the assigned message ID.
+   * @see T1252 CONDUIT A2A
+   */
+  publishToTopic?(
+    topicName: string,
+    content: string,
+    options?: ConduitTopicPublishOptions,
+  ): Promise<ConduitSendResult>;
+
+  /**
+   * Register a real-time handler for messages on a named topic.
+   *
+   * @param topicName - Topic name to watch.
+   * @param handler   - Callback invoked for each message (includes A2A fields).
+   * @returns Unsubscribe function that stops delivery to this handler.
+   * @see T1252 CONDUIT A2A
+   */
+  onTopic?(topicName: string, handler: (message: ConduitMessage) => void): ConduitUnsubscribe;
+
+  /**
+   * Unsubscribe this agent from a named topic.
+   *
+   * Removes the subscription record from conduit.db. The agent will no longer
+   * receive messages published to the topic.
+   *
+   * @param topicName - Topic name to leave.
+   * @see T1252 CONDUIT A2A
+   */
+  unsubscribeTopic?(topicName: string): Promise<void>;
+
   // --- Connection lifecycle ---
 
   /** Connect to the messaging backend. */

package/src/index.ts

@@ -176,6 +176,8 @@ export type {
   ConduitSendResult,
   ConduitState,
   ConduitStateChange,
+  ConduitTopicPublishOptions,
+  ConduitTopicSubscribeOptions,
   ConduitUnsubscribe,
 } from './conduit.js';
 // === Configuration Types ===
@@ -491,6 +493,22 @@ export type {
   SubstitutionSource,
   VariableResolver,
 } from './operations/variable-substitution.js';
+// === Worktree Backend SDK Types (T1161) ===
+// Re-exported at top level so @cleocode/worktree-backend and callers can
+// import without the `ops.` namespace hop.
+export type {
+  CreateWorktreeOptions,
+  CreateWorktreeResult,
+  DestroyWorktreeOptions,
+  DestroyWorktreeResult,
+  ListWorktreesOptions,
+  PruneWorktreesOptions,
+  PruneWorktreesResult,
+  WorktreeHook,
+  WorktreeHookResult,
+  WorktreeIncludePattern,
+  WorktreeListEntry,
+} from './operations/worktree.js';
 // === Orchestration Hierarchy ===
 export {
   type AgentHierarchy,
@@ -499,6 +517,14 @@ export {
   type OrchestrationHierarchyAPI,
   OrchestrationLevel,
 } from './orchestration-hierarchy.js';
+// === Peer Identity (T1210 — SDK-first CANT persona contract) ===
+export {
+  assertPeerIdentity,
+  filterPeerIdentities,
+  isPeerIdentity,
+  type PeerIdentity,
+  type PeerKind,
+} from './peer.js';
 // === Playbook DSL Types (T889 / T904 / W4-6) ===
 export type {
   PlaybookAgenticNode,

package/src/operations/conduit.ts

@@ -187,3 +187,113 @@ export interface ConduitSendResult {
   /** ISO 8601 send timestamp. */
   sentAt: string;
 }
+
+// ============================================================================
+// A2A Topic Operations (T1252 — Wave 9 Agent-to-Agent coordination)
+// ============================================================================
+
+// --------------------------------------------------------------------------
+// conduit.subscribe → register agent subscription to a named topic
+// --------------------------------------------------------------------------
+
+/**
+ * Parameters for `conduit.subscribe`.
+ *
+ * @see T1252 CONDUIT A2A
+ */
+export interface ConduitSubscribeParams {
+  /** Topic name to subscribe to, e.g. `"epic-T1149.wave-2"`. */
+  topicName: string;
+  /** Send as this agent. Omit to use the active agent from the registry. */
+  agentId?: string;
+  /** Optional message kind / event filter. */
+  filter?: { kind?: string[]; event?: string[] };
+}
+
+/**
+ * Result of `conduit.subscribe`.
+ *
+ * @see T1252 CONDUIT A2A
+ */
+export interface ConduitSubscribeResult {
+  /** The agent id that was subscribed. */
+  agentId: string;
+  /** Topic name subscribed to. */
+  topicName: string;
+  /** Human-readable status message. */
+  message: string;
+}
+
+// --------------------------------------------------------------------------
+// conduit.publish → broadcast a message to a topic
+// --------------------------------------------------------------------------
+
+/**
+ * Parameters for `conduit.publish`.
+ *
+ * @see T1252 CONDUIT A2A
+ */
+export interface ConduitPublishParams {
+  /** Target topic name. */
+  topicName: string;
+  /** Message content (human-readable). */
+  content: string;
+  /** Message kind (default `"message"`). */
+  kind?: 'message' | 'request' | 'notify' | 'subscribe';
+  /** Optional structured payload (JSON-serializable). */
+  payload?: Record<string, unknown>;
+  /** Publish as this agent. Omit to use the active agent from the registry. */
+  agentId?: string;
+}
+
+/**
+ * Result of `conduit.publish`.
+ *
+ * @see T1252 CONDUIT A2A
+ */
+export interface ConduitPublishResult {
+  /** Assigned message id. */
+  messageId: string;
+  /** Publisher agent id. */
+  from: string;
+  /** Topic the message was published to. */
+  topicName: string;
+  /** Transport backing this call. */
+  transport: ConduitTransportKind;
+  /** ISO 8601 publish timestamp. */
+  publishedAt: string;
+}
+
+// --------------------------------------------------------------------------
+// conduit.listen → one-shot poll for topic messages
+// --------------------------------------------------------------------------
+
+/**
+ * Parameters for `conduit.listen`.
+ *
+ * @see T1252 CONDUIT A2A
+ */
+export interface ConduitListenParams {
+  /** Topic name to poll. */
+  topicName: string;
+  /** Listen as this agent. Omit to use the active agent from the registry. */
+  agentId?: string;
+  /** Maximum messages to return (default 50). */
+  limit?: number;
+  /** Only return messages created after this ISO 8601 timestamp. */
+  since?: string;
+}
+
+/**
+ * Result of `conduit.listen`.
+ *
+ * @see T1252 CONDUIT A2A
+ */
+export interface ConduitListenResult {
+  /** Topic that was polled. */
+  topicName: string;
+  /** Messages received (may be empty). */
+  messages: ConduitInboxMessage[];
+  /** Duration of the listen call in milliseconds. */
+  listenedForMs: number;
+}

package/src/operations/index.ts

@@ -21,3 +21,4 @@ export * from './system.js';
 export * from './tasks.js';
 export * from './validate.js';
 export * from './variable-substitution.js';
+export * from './worktree.js';