@cleocode/cant 2026.4.109 → 2026.4.111

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 { NativeDiagnostic, NativeParseDocumentResult, NativeParseError, NativeParseResult, NativePipelineResult, NativePipelineStep, NativeValidateResult, } from './native-loader';
-export { cantClassifyDirectiveNative, cantExecutePipelineNative, cantExtractAgentProfilesNative, cantParseDocumentNative, cantParseNative, cantValidateDocumentNative, initWasm, isNativeAvailable, isWasmAvailable, } from './native-loader';
+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 { 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.isWasmAvailable = exports.isNativeAvailable = exports.initWasm = 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.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; } });
@@ -49,9 +49,12 @@ Object.defineProperty(exports, "cantExtractAgentProfilesNative", { enumerable: t
 Object.defineProperty(exports, "cantParseDocumentNative", { enumerable: true, get: function () { return native_loader_1.cantParseDocumentNative; } });
 Object.defineProperty(exports, "cantParseNative", { enumerable: true, get: function () { return native_loader_1.cantParseNative; } });
 Object.defineProperty(exports, "cantValidateDocumentNative", { enumerable: true, get: function () { return native_loader_1.cantValidateDocumentNative; } });
+Object.defineProperty(exports, "extractAgentProfilesTyped", { enumerable: true, get: function () { return native_loader_1.extractAgentProfilesTyped; } });
+Object.defineProperty(exports, "extractAgentSkills", { enumerable: true, get: function () { return native_loader_1.extractAgentSkills; } });
 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; } });
+Object.defineProperty(exports, "validateAgentCantPath", { enumerable: true, get: function () { return native_loader_1.validateAgentCantPath; } });
 // Parser
 var parse_1 = require("./parse");
 Object.defineProperty(exports, "initCantParser", { enumerable: true, get: function () { return parse_1.initCantParser; } });

package/dist/native-loader.d.ts

@@ -135,12 +135,93 @@ export declare function cantParseDocumentNative(content: string): NativeParseDoc
  * @param content - The raw `.cant` file content to parse and validate.
  */
 export declare function cantValidateDocumentNative(content: string): NativeValidateResult;
+/**
+ * A single agent profile extracted from a `.cant` document.
+ *
+ * @remarks
+ * Mirrors the subset of fields the Rust-side `cant_extract_agent_profiles`
+ * function emits (see R1-AGENT-ARCHITECTURE-AUDIT.md §1.7). Fields are
+ * optional because older `.cant` documents may omit them; resolver code
+ * MUST handle `undefined` per-field.
+ */
+export interface AgentProfile {
+    /** Agent business id (kebab-case), e.g. `"cleo-prime"`. */
+    agentId?: string;
+    /** Declared role, e.g. `"orchestrator"`, `"lead"`, `"worker"`. */
+    role?: string;
+    /** Declared parent agent id, if any. */
+    parent?: string;
+    /** Skill slugs declared on the agent (cached here; SSoT is `agent_skills`). */
+    skills?: string[];
+    /** Free-form fields the native binding did not typify. */
+    [extra: string]: unknown;
+}
 /**
  * Extract agent profiles from a `.cant` document via the native addon.
  *
  * @param content - The raw `.cant` file content.
+ *
+ * @remarks
+ * The native binding returns a loose `unknown[]`. Callers that need typed
+ * access should prefer {@link extractAgentProfilesTyped}, which validates
+ * the shape and returns `AgentProfile[]`.
  */
 export declare function cantExtractAgentProfilesNative(content: string): unknown[];
+/**
+ * Typed wrapper around {@link cantExtractAgentProfilesNative}. Returns a
+ * best-effort `AgentProfile[]` by shallow-validating each entry.
+ *
+ * @param content - The raw `.cant` file content.
+ *
+ * @remarks
+ * Implements R1-AGENT-ARCHITECTURE-AUDIT Recommendation 3 by consolidating
+ * agent-profile / skill extraction into a single well-typed surface so
+ * downstream packages (`agent-install.ts`, `agent-doctor.ts`) do not have
+ * to re-implement `.cant` field parsing.
+ */
+export declare function extractAgentProfilesTyped(content: string): AgentProfile[];
+/**
+ * Extract the `skills: [...]` list from a `.cant` agent document.
+ *
+ * @param content - The raw `.cant` file content.
+ *
+ * @returns Deduplicated, trimmed skill slug list (empty array if none).
+ *
+ * @remarks
+ * Consolidates skill-parsing logic previously duplicated in
+ * `packages/core/src/store/agent-install.ts` and
+ * `packages/core/src/store/agent-doctor.ts` (R1 Recommendation 3). Both
+ * modules now delegate to this helper so they stay in lock-step.
+ */
+export declare function extractAgentSkills(content: string): string[];
+/**
+ * Validate that a `.cant` file path stays within a declared root directory.
+ *
+ * @param cantPath - Absolute path to the `.cant` file from the registry row.
+ * @param rootDir - Absolute root directory that the path MUST live inside
+ *   (typically the project root or the global CANT agents dir).
+ *
+ * @returns `true` when `cantPath` is a descendant of `rootDir`; `false`
+ *   otherwise. Also returns `false` for relative paths.
+ *
+ * @remarks
+ * Implements R1-AGENT-ARCHITECTURE-AUDIT Recommendation 4. A malicious or
+ * corrupted `agents.cant_path` row could point to `../../../etc/passwd`
+ * or a symlink outside the project. Callers (agent resolver, doctor)
+ * MUST gate any `readFileSync(cantPath)` on a successful
+ * `validateAgentCantPath()` check.
+ *
+ * @example
+ * ```ts
+ * import { validateAgentCantPath } from '@cleocode/cant';
+ *
+ * const cantPath = row.cant_path;
+ * if (!validateAgentCantPath(cantPath, projectRoot)) {
+ *   throw new Error(`cant_path outside project root: ${cantPath}`);
+ * }
+ * ```
+ */
+export declare function validateAgentCantPath(cantPath: string, rootDir: string): boolean;
 /**
  * Execute a deterministic pipeline from a `.cant` file via the native addon.
  *

package/dist/native-loader.js

@@ -19,6 +19,9 @@ exports.cantClassifyDirectiveNative = cantClassifyDirectiveNative;
 exports.cantParseDocumentNative = cantParseDocumentNative;
 exports.cantValidateDocumentNative = cantValidateDocumentNative;
 exports.cantExtractAgentProfilesNative = cantExtractAgentProfilesNative;
+exports.extractAgentProfilesTyped = extractAgentProfilesTyped;
+exports.extractAgentSkills = extractAgentSkills;
+exports.validateAgentCantPath = validateAgentCantPath;
 exports.cantExecutePipelineNative = cantExecutePipelineNative;
 /* eslint-disable @typescript-eslint/no-require-imports */
 const node_path_1 = require("node:path");
@@ -109,10 +112,112 @@ function cantValidateDocumentNative(content) {
  * Extract agent profiles from a `.cant` document via the native addon.
  *
  * @param content - The raw `.cant` file content.
+ *
+ * @remarks
+ * The native binding returns a loose `unknown[]`. Callers that need typed
+ * access should prefer {@link extractAgentProfilesTyped}, which validates
+ * the shape and returns `AgentProfile[]`.
  */
 function cantExtractAgentProfilesNative(content) {
     return requireNative().cantExtractAgentProfiles(content);
 }
+/**
+ * Typed wrapper around {@link cantExtractAgentProfilesNative}. Returns a
+ * best-effort `AgentProfile[]` by shallow-validating each entry.
+ *
+ * @param content - The raw `.cant` file content.
+ *
+ * @remarks
+ * Implements R1-AGENT-ARCHITECTURE-AUDIT Recommendation 3 by consolidating
+ * agent-profile / skill extraction into a single well-typed surface so
+ * downstream packages (`agent-install.ts`, `agent-doctor.ts`) do not have
+ * to re-implement `.cant` field parsing.
+ */
+function extractAgentProfilesTyped(content) {
+    const raw = cantExtractAgentProfilesNative(content);
+    if (!Array.isArray(raw))
+        return [];
+    return raw.filter((entry) => {
+        return typeof entry === 'object' && entry !== null;
+    });
+}
+/**
+ * Extract the `skills: [...]` list from a `.cant` agent document.
+ *
+ * @param content - The raw `.cant` file content.
+ *
+ * @returns Deduplicated, trimmed skill slug list (empty array if none).
+ *
+ * @remarks
+ * Consolidates skill-parsing logic previously duplicated in
+ * `packages/core/src/store/agent-install.ts` and
+ * `packages/core/src/store/agent-doctor.ts` (R1 Recommendation 3). Both
+ * modules now delegate to this helper so they stay in lock-step.
+ */
+function extractAgentSkills(content) {
+    const profiles = extractAgentProfilesTyped(content);
+    const skills = new Set();
+    for (const profile of profiles) {
+        if (Array.isArray(profile.skills)) {
+            for (const skill of profile.skills) {
+                if (typeof skill === 'string') {
+                    const trimmed = skill.trim();
+                    if (trimmed.length > 0)
+                        skills.add(trimmed);
+                }
+            }
+        }
+    }
+    return [...skills];
+}
+/**
+ * Validate that a `.cant` file path stays within a declared root directory.
+ *
+ * @param cantPath - Absolute path to the `.cant` file from the registry row.
+ * @param rootDir - Absolute root directory that the path MUST live inside
+ *   (typically the project root or the global CANT agents dir).
+ *
+ * @returns `true` when `cantPath` is a descendant of `rootDir`; `false`
+ *   otherwise. Also returns `false` for relative paths.
+ *
+ * @remarks
+ * Implements R1-AGENT-ARCHITECTURE-AUDIT Recommendation 4. A malicious or
+ * corrupted `agents.cant_path` row could point to `../../../etc/passwd`
+ * or a symlink outside the project. Callers (agent resolver, doctor)
+ * MUST gate any `readFileSync(cantPath)` on a successful
+ * `validateAgentCantPath()` check.
+ *
+ * @example
+ * ```ts
+ * import { validateAgentCantPath } from '@cleocode/cant';
+ *
+ * const cantPath = row.cant_path;
+ * if (!validateAgentCantPath(cantPath, projectRoot)) {
+ *   throw new Error(`cant_path outside project root: ${cantPath}`);
+ * }
+ * ```
+ */
+function validateAgentCantPath(cantPath, rootDir) {
+    if (typeof cantPath !== 'string' || cantPath.length === 0)
+        return false;
+    if (typeof rootDir !== 'string' || rootDir.length === 0)
+        return false;
+    if (!(0, node_path_1.isAbsolute)(cantPath) || !(0, node_path_1.isAbsolute)(rootDir))
+        return false;
+    const resolvedRoot = (0, node_path_1.resolve)(rootDir);
+    const resolvedPath = (0, node_path_1.resolve)(cantPath);
+    const rel = (0, node_path_1.relative)(resolvedRoot, resolvedPath);
+    // `relative()` returns a path that starts with `..` when the target is
+    // outside the root. An absolute return value (Windows drive change) is
+    // also outside. Empty string means the path IS the root — reject that.
+    if (rel.length === 0)
+        return false;
+    if (rel.startsWith('..'))
+        return false;
+    if ((0, node_path_1.isAbsolute)(rel))
+        return false;
+    return true;
+}
 /**
  * Execute a deterministic pipeline from a `.cant` file via the native addon.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/cant",
-  "version": "2026.4.109",
+  "version": "2026.4.111",
   "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/contracts": "2026.4.109",
-    "@cleocode/lafs": "2026.4.109",
-    "@cleocode/core": "2026.4.109"
+    "@cleocode/contracts": "2026.4.111",
+    "@cleocode/core": "2026.4.111",
+    "@cleocode/lafs": "2026.4.111"
   },
   "devDependencies": {
     "typescript": "^6.0.2",