@cleocode/cant 2026.4.114 → 2026.4.115

package/dist/index.d.ts

@@ -12,8 +12,8 @@ export type { ConsolidateOptions, MentalModel, MentalModelObservation, MentalMod
 export { consolidate, createEmptyModel, harvestObservations, renderMentalModel, } from './mental-model.js';
 export type { ConvertedFile, MigrationOptions, MigrationResult, UnconvertedSection, } from './migrate/index';
 export { migrateMarkdown, serializeCantDocument, showDiff, showSummary } from './migrate/index';
-export type { AgentProfile, NativeDiagnostic, NativeParseDocumentResult, NativeParseError, NativeParseResult, NativePipelineResult, NativePipelineStep, NativeValidateResult, } from './native-loader';
-export { cantClassifyDirectiveNative, cantExecutePipelineNative, cantExtractAgentProfilesNative, cantParseDocumentNative, cantParseNative, cantValidateDocumentNative, extractAgentProfilesTyped, extractAgentSkills, initWasm, isNativeAvailable, isWasmAvailable, validateAgentCantPath, } from './native-loader';
+export type { AgentProfile, NativeDiagnostic, NativeParseDocumentResult, NativeParseError, NativeParseResult, NativePipelineResult, NativePipelineStep, NativeValidateResult, SeedPersonaId, } from './native-loader';
+export { cantClassifyDirectiveNative, cantExecutePipelineNative, cantExtractAgentProfilesNative, cantParseDocumentNative, cantParseNative, cantValidateDocumentNative, extractAgentProfilesTyped, extractAgentSkills, initWasm, isNativeAvailable, isWasmAvailable, loadSeedAgentIdentities, SEED_PERSONA_IDS, validateAgentCantPath, } from './native-loader';
 export type { ParsedCANTMessage } from './parse';
 export { initCantParser, parseCANTMessage } from './parse';
 export type { CantAgentV3, CantContextSourceDef, CantContractBlock, CantContractClause, CantMentalModelRef, CantOverflowStrategy, CantPathPermissions, CantTier, DirectiveType, } from './types';

package/dist/index.js

@@ -2,7 +2,7 @@
 // JIT Agent Composer (ULTRAPLAN Wave 5)
 // Wave 7a: BRAIN-backed ContextProvider (T432)
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveWorktreeRoot = exports.mergeWorktree = exports.listWorktrees = exports.createWorktree = exports.isCantAgentV3 = exports.parseCANTMessage = exports.initCantParser = exports.validateAgentCantPath = exports.isWasmAvailable = exports.isNativeAvailable = exports.initWasm = exports.extractAgentSkills = exports.extractAgentProfilesTyped = exports.cantValidateDocumentNative = exports.cantParseNative = exports.cantParseDocumentNative = exports.cantExtractAgentProfilesNative = exports.cantExecutePipelineNative = exports.cantClassifyDirectiveNative = exports.showSummary = exports.showDiff = exports.serializeCantDocument = exports.migrateMarkdown = exports.renderMentalModel = exports.harvestObservations = exports.createEmptyModel = exports.consolidate = exports.WORKER_FORBIDDEN_SPAWN_TOOLS = exports.validateSpawnRequest = exports.THIN_AGENT_TOOLS_STRIPPED = exports.stripSpawnToolsForWorker = exports.ORCHESTRATOR_FORBIDDEN_TOOLS = exports.LEAD_FORBIDDEN_TOOLS = exports.filterToolsForRole = exports.validateDocument = exports.parseDocument = exports.listSections = exports.executePipeline = exports.brainContextProvider = exports.TIER_CAPS = exports.estimateTokens = exports.escalateTier = exports.composeSpawnPayload = exports.toCantAgentV3 = exports.compileBundle = void 0;
+exports.resolveWorktreeRoot = exports.mergeWorktree = exports.listWorktrees = exports.createWorktree = exports.isCantAgentV3 = exports.parseCANTMessage = exports.initCantParser = exports.validateAgentCantPath = exports.SEED_PERSONA_IDS = exports.loadSeedAgentIdentities = exports.isWasmAvailable = exports.isNativeAvailable = exports.initWasm = exports.extractAgentSkills = exports.extractAgentProfilesTyped = exports.cantValidateDocumentNative = exports.cantParseNative = exports.cantParseDocumentNative = exports.cantExtractAgentProfilesNative = exports.cantExecutePipelineNative = exports.cantClassifyDirectiveNative = exports.showSummary = exports.showDiff = exports.serializeCantDocument = exports.migrateMarkdown = exports.renderMentalModel = exports.harvestObservations = exports.createEmptyModel = exports.consolidate = exports.WORKER_FORBIDDEN_SPAWN_TOOLS = exports.validateSpawnRequest = exports.THIN_AGENT_TOOLS_STRIPPED = exports.stripSpawnToolsForWorker = exports.ORCHESTRATOR_FORBIDDEN_TOOLS = exports.LEAD_FORBIDDEN_TOOLS = exports.filterToolsForRole = exports.validateDocument = exports.parseDocument = exports.listSections = exports.executePipeline = exports.brainContextProvider = exports.TIER_CAPS = exports.estimateTokens = exports.escalateTier = exports.composeSpawnPayload = exports.toCantAgentV3 = exports.compileBundle = void 0;
 // Bundle compiler
 var bundle_1 = require("./bundle");
 Object.defineProperty(exports, "compileBundle", { enumerable: true, get: function () { return bundle_1.compileBundle; } });
@@ -54,6 +54,9 @@ Object.defineProperty(exports, "extractAgentSkills", { enumerable: true, get: fu
 Object.defineProperty(exports, "initWasm", { enumerable: true, get: function () { return native_loader_1.initWasm; } });
 Object.defineProperty(exports, "isNativeAvailable", { enumerable: true, get: function () { return native_loader_1.isNativeAvailable; } });
 Object.defineProperty(exports, "isWasmAvailable", { enumerable: true, get: function () { return native_loader_1.isWasmAvailable; } });
+// T1210 — PeerIdentity SDK surface
+Object.defineProperty(exports, "loadSeedAgentIdentities", { enumerable: true, get: function () { return native_loader_1.loadSeedAgentIdentities; } });
+Object.defineProperty(exports, "SEED_PERSONA_IDS", { enumerable: true, get: function () { return native_loader_1.SEED_PERSONA_IDS; } });
 Object.defineProperty(exports, "validateAgentCantPath", { enumerable: true, get: function () { return native_loader_1.validateAgentCantPath; } });
 // Parser
 var parse_1 = require("./parse");

package/dist/native-loader.d.ts

@@ -10,6 +10,7 @@
  * Replaces the previous WASM loader. Follows the same pattern as
  * `packages/lafs/src/native-loader.ts`.
  */
+import type { PeerIdentity } from '@cleocode/contracts';
 /** Shape of a parsed CANT message returned by the native binding. */
 export interface NativeParseResult {
     /** The directive verb if present (e.g., `"done"`), or `undefined`. */
@@ -229,6 +230,53 @@ export declare function validateAgentCantPath(cantPath: string, rootDir: string)
  * @param pipelineName - The name of the `pipeline { ... }` block to run.
  */
 export declare function cantExecutePipelineNative(filePath: string, pipelineName: string): Promise<NativePipelineResult>;
+/**
+ * Canonical IDs of the 7 CLEO seed personas.
+ *
+ * Kept in declaration order: orchestrator first, then leads, then universal base.
+ * Used by the regression test and as documentation for the expected registry
+ * contents. Any persona on this list MUST be resolvable from the canonical
+ * seed-agents path (either `seed-agents/<id>.cant` or `cleo-subagent.cant`).
+ *
+ * @task T1210
+ */
+export declare const SEED_PERSONA_IDS: readonly ["cleo-prime", "cleo-dev", "cleo-db-lead", "cleo-historian", "cleo-rust-lead", "cleo-subagent", "cleoos-opus-orchestrator"];
+/** Type-safe union of the 7 canonical seed persona IDs. */
+export type SeedPersonaId = (typeof SEED_PERSONA_IDS)[number];
+/**
+ * Load all seed-agent {@link PeerIdentity} records from the canonical
+ * `packages/agents/` directory shipped with `@cleocode/agents`.
+ *
+ * Walk order:
+ *  1. All `.cant` files inside `packages/agents/seed-agents/` (generic templates
+ *     + any project-specific personas installed there).
+ *  2. `packages/agents/cleo-subagent.cant` — the universal protocol base.
+ *
+ * Files that cannot be parsed (unreadable, missing `agent <id>:` block) are
+ * silently skipped.
+ *
+ * This function is intentionally pure-TS and does NOT require the native addon.
+ * It is safe to call in environments where `cant-napi` is absent (CI, test, etc.).
+ *
+ * @param agentsRoot - Optional override for the `packages/agents/` root. When
+ *   omitted the path is resolved automatically relative to this file. Tests
+ *   should pass an absolute path to an isolated fixture directory.
+ * @returns `PeerIdentity[]` for every successfully-parsed `.cant` file, in
+ *   seed-agents-first, universal-base-last order.
+ *
+ * @example
+ * ```ts
+ * import { loadSeedAgentIdentities } from '@cleocode/cant';
+ *
+ * const peers = loadSeedAgentIdentities();
+ * console.log(peers.map((p) => p.peerId));
+ * // ['project-code-worker', 'project-dev-lead', ..., 'cleo-subagent']
+ * ```
+ *
+ * @task T1210
+ * @epic T1144
+ */
+export declare function loadSeedAgentIdentities(agentsRoot?: string): PeerIdentity[];
 export declare const isWasmAvailable: typeof isNativeAvailable;
 /**
  * Backward-compatible no-op initializer.

package/dist/native-loader.js

@@ -12,7 +12,7 @@
  * `packages/lafs/src/native-loader.ts`.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.initWasm = exports.isWasmAvailable = void 0;
+exports.initWasm = exports.isWasmAvailable = exports.SEED_PERSONA_IDS = void 0;
 exports.isNativeAvailable = isNativeAvailable;
 exports.cantParseNative = cantParseNative;
 exports.cantClassifyDirectiveNative = cantClassifyDirectiveNative;
@@ -23,7 +23,9 @@ exports.extractAgentProfilesTyped = extractAgentProfilesTyped;
 exports.extractAgentSkills = extractAgentSkills;
 exports.validateAgentCantPath = validateAgentCantPath;
 exports.cantExecutePipelineNative = cantExecutePipelineNative;
+exports.loadSeedAgentIdentities = loadSeedAgentIdentities;
 /* eslint-disable @typescript-eslint/no-require-imports */
+const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 let nativeModule = null;
 let loadAttempted = false;
@@ -227,6 +229,240 @@ function validateAgentCantPath(cantPath, rootDir) {
 function cantExecutePipelineNative(filePath, pipelineName) {
     return requireNative().cantExecutePipeline(filePath, pipelineName);
 }
+// ============================================================================
+// Seed-agent identity loader (T1210 — PeerIdentity SDK surface)
+// ============================================================================
+/**
+ * Canonical IDs of the 7 CLEO seed personas.
+ *
+ * Kept in declaration order: orchestrator first, then leads, then universal base.
+ * Used by the regression test and as documentation for the expected registry
+ * contents. Any persona on this list MUST be resolvable from the canonical
+ * seed-agents path (either `seed-agents/<id>.cant` or `cleo-subagent.cant`).
+ *
+ * @task T1210
+ */
+exports.SEED_PERSONA_IDS = [
+    'cleo-prime',
+    'cleo-dev',
+    'cleo-db-lead',
+    'cleo-historian',
+    'cleo-rust-lead',
+    'cleo-subagent',
+    'cleoos-opus-orchestrator',
+];
+/**
+ * Discover the `packages/agents/` root by walking up from the compiled
+ * `native-loader.js` / source `native-loader.ts` file.
+ *
+ * Walk candidates covering `src/` (dev), `dist/` (compiled), and the
+ * installed `node_modules/@cleocode/cant/dist/` layout.
+ *
+ * Uses `__dirname` (available in the CJS-compiled output) to resolve paths
+ * relative to this module, matching the pattern used by `ensureLoaded()`.
+ *
+ * @returns Absolute path to the `packages/agents/` directory, or `null` when
+ *   none of the candidates resolves to an existing directory.
+ *
+ * @internal
+ */
+function resolveAgentsPackageRoot() {
+    // __dirname is always available in the CJS-compiled output (packages/cant/dist/).
+    // In the TypeScript source tree (packages/cant/src/) tsc injects __dirname via
+    // the module-resolution helpers, so this is safe in both contexts.
+    const here = __dirname;
+    const candidates = [
+        // packages/cant/src/ → packages/agents/
+        (0, node_path_1.resolve)(here, '..', '..', 'agents'),
+        // packages/cant/dist/ → packages/agents/
+        (0, node_path_1.resolve)(here, '..', '..', '..', 'agents'),
+        // node_modules/@cleocode/cant/dist/ → @cleocode/agents (relative to node_modules)
+        (0, node_path_1.resolve)(here, '..', '..', '..', '..', 'agents'),
+        (0, node_path_1.resolve)(here, '..', '..', '..', '..', '@cleocode', 'agents'),
+    ];
+    return candidates.find((p) => (0, node_fs_1.existsSync)(p)) ?? null;
+}
+/**
+ * Extract the `role:` value from a raw `.cant` file body.
+ *
+ * Looks for a line matching `  role: <value>` within the `agent <id>:` block
+ * using a simple regex — intentionally avoids full CANT parsing to remove the
+ * native-addon dependency from this path (the addon may not be present in all
+ * environments where the loader runs).
+ *
+ * @param content - Raw `.cant` file text.
+ * @returns Extracted role string, or `null` when no `role:` line is found.
+ * @internal
+ */
+function extractRoleFromCant(content) {
+    const match = /^\s{2}role:\s*(\S+)/m.exec(content);
+    return match ? (match[1] ?? null) : null;
+}
+/**
+ * Map a raw role string from a `.cant` file to a {@link PeerKind}.
+ *
+ * Unrecognised values default to `"subagent"` so the loader remains
+ * forward-compatible with new role names.
+ *
+ * @param rawRole - Raw role string extracted from the `.cant` file.
+ * @internal
+ */
+function roleToPeerKind(rawRole) {
+    switch (rawRole) {
+        case 'orchestrator':
+            return 'orchestrator';
+        case 'lead':
+            return 'lead';
+        case 'worker':
+            return 'worker';
+        default:
+            return 'subagent';
+    }
+}
+/**
+ * Extract the `description:` value from a raw `.cant` file body.
+ *
+ * Handles single-line descriptions (`description: "..."`) and multiline
+ * block-scalar descriptions (`description: |`). Returns the first line of
+ * the block-scalar body for multiline values. Returns empty string when no
+ * `description:` field is found.
+ *
+ * @param content - Raw `.cant` file text.
+ * @internal
+ */
+function extractDescriptionFromCant(content) {
+    // Single-line: `  description: "some text"` or `  description: some text`
+    const singleLine = /^\s{2}description:\s+"([^"]+)"/m.exec(content);
+    if (singleLine)
+        return singleLine[1] ?? '';
+    const singleLineUnquoted = /^\s{2}description:\s+(.+)/m.exec(content);
+    if (singleLineUnquoted) {
+        const raw = singleLineUnquoted[1] ?? '';
+        // Exclude multiline indicator '|'
+        if (raw.trim() !== '|')
+            return raw.trim();
+    }
+    // Multiline block scalar: grab first non-empty line after `description: |`
+    const blockScalar = /^\s{2}description:\s+\|\s*\n((?:\s+\S[^\n]*\n?)+)/m.exec(content);
+    if (blockScalar) {
+        const bodyLines = (blockScalar[1] ?? '').split('\n');
+        for (const line of bodyLines) {
+            const trimmed = line.trim();
+            if (trimmed.length > 0)
+                return trimmed;
+        }
+    }
+    return '';
+}
+/**
+ * Extract the agent business id from a raw `.cant` file body.
+ *
+ * Looks for the `agent <id>:` declaration line. Returns `null` when not found.
+ *
+ * @param content - Raw `.cant` file text.
+ * @internal
+ */
+function extractAgentIdFromCant(content) {
+    const match = /^agent\s+([a-z][a-z0-9-]*):/m.exec(content);
+    return match ? (match[1] ?? null) : null;
+}
+/**
+ * Parse a single `.cant` file at `cantFile` into a {@link PeerIdentity}.
+ *
+ * Returns `null` when the file cannot be parsed (missing `agent <id>:` block
+ * or unreadable file). The caller is responsible for logging / skipping nulls.
+ *
+ * @param cantFile - Absolute path to the `.cant` file.
+ * @param fallbackId - Id to use when the `agent <id>:` block is absent (e.g.,
+ *   when loading the universal base by a known filename).
+ * @internal
+ */
+function parseCantFileToIdentity(cantFile, fallbackId) {
+    let content;
+    try {
+        content = (0, node_fs_1.readFileSync)(cantFile, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+    const agentId = extractAgentIdFromCant(content) ?? fallbackId ?? null;
+    if (!agentId)
+        return null;
+    const rawRole = extractRoleFromCant(content);
+    const peerKind = roleToPeerKind(rawRole);
+    const description = extractDescriptionFromCant(content);
+    return {
+        peerId: agentId,
+        peerKind,
+        cantFile,
+        displayName: agentId,
+        description,
+    };
+}
+/**
+ * Load all seed-agent {@link PeerIdentity} records from the canonical
+ * `packages/agents/` directory shipped with `@cleocode/agents`.
+ *
+ * Walk order:
+ *  1. All `.cant` files inside `packages/agents/seed-agents/` (generic templates
+ *     + any project-specific personas installed there).
+ *  2. `packages/agents/cleo-subagent.cant` — the universal protocol base.
+ *
+ * Files that cannot be parsed (unreadable, missing `agent <id>:` block) are
+ * silently skipped.
+ *
+ * This function is intentionally pure-TS and does NOT require the native addon.
+ * It is safe to call in environments where `cant-napi` is absent (CI, test, etc.).
+ *
+ * @param agentsRoot - Optional override for the `packages/agents/` root. When
+ *   omitted the path is resolved automatically relative to this file. Tests
+ *   should pass an absolute path to an isolated fixture directory.
+ * @returns `PeerIdentity[]` for every successfully-parsed `.cant` file, in
+ *   seed-agents-first, universal-base-last order.
+ *
+ * @example
+ * ```ts
+ * import { loadSeedAgentIdentities } from '@cleocode/cant';
+ *
+ * const peers = loadSeedAgentIdentities();
+ * console.log(peers.map((p) => p.peerId));
+ * // ['project-code-worker', 'project-dev-lead', ..., 'cleo-subagent']
+ * ```
+ *
+ * @task T1210
+ * @epic T1144
+ */
+function loadSeedAgentIdentities(agentsRoot) {
+    const root = agentsRoot ?? resolveAgentsPackageRoot();
+    if (!root)
+        return [];
+    const identities = [];
+    // 1. Walk seed-agents/ directory
+    const seedDir = (0, node_path_1.join)(root, 'seed-agents');
+    if ((0, node_fs_1.existsSync)(seedDir)) {
+        let entries = [];
+        try {
+            entries = (0, node_fs_1.readdirSync)(seedDir).filter((f) => f.endsWith('.cant'));
+        }
+        catch {
+            // unreadable — skip
+        }
+        for (const entry of entries) {
+            const cantFile = (0, node_path_1.join)(seedDir, entry);
+            const identity = parseCantFileToIdentity(cantFile);
+            if (identity)
+                identities.push(identity);
+        }
+    }
+    // 2. Universal base: packages/agents/cleo-subagent.cant
+    const universalBase = (0, node_path_1.join)(root, 'cleo-subagent.cant');
+    if ((0, node_fs_1.existsSync)(universalBase)) {
+        const identity = parseCantFileToIdentity(universalBase, 'cleo-subagent');
+        if (identity)
+            identities.push(identity);
+    }
+    return identities;
+}
 // Backward compatibility aliases (kept so existing callers compile).
 exports.isWasmAvailable = isNativeAvailable;
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/cant",
-  "version": "2026.4.114",
+  "version": "2026.4.115",
   "description": "CANT protocol parser and runtime for CLEO — wraps cant-core via napi-rs",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -9,9 +9,9 @@
     "napi/"
   ],
   "dependencies": {
-    "@cleocode/lafs": "2026.4.114",
-    "@cleocode/core": "2026.4.114",
-    "@cleocode/contracts": "2026.4.114"
+    "@cleocode/lafs": "2026.4.115",
+    "@cleocode/core": "2026.4.115",
+    "@cleocode/contracts": "2026.4.115"
   },
   "devDependencies": {
     "typescript": "^6.0.2",