@kontourai/flow-agents 3.12.1 → 4.1.0

package/dist/pi/build/src/flow-kit/provision.d.ts

@@ -0,0 +1,23 @@
+export type ProvisionedFile = {
+    id: string;
+    target: string;
+};
+export type ProvisionPlanEntry = ProvisionedFile & {
+    source: string;
+    destination: string;
+};
+export type ProvisionResult = {
+    kit_id: string;
+    kit_hash?: string;
+    files: ProvisionPlanEntry[];
+    manifest_path?: string;
+    dry_run: boolean;
+};
+export declare class ProvisionConflictError extends Error {
+    readonly conflicts: ProvisionPlanEntry[];
+    constructor(conflicts: ProvisionPlanEntry[]);
+}
+export declare function provisionKit(kitDir: string, targetDir: string, options?: {
+    force?: boolean;
+    dryRun?: boolean;
+}): Promise<ProvisionResult>;

package/dist/pi/build/src/flow-kit/provision.js

@@ -0,0 +1,99 @@
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { atomicCopyFile, atomicWriteJson, canonicalProspectivePath, walkFiles } from "../lib/fs.js";
+import { PROVISION_MANIFEST_DIR, assertKitRepository } from "./validate.js";
+export class ProvisionConflictError extends Error {
+    conflicts;
+    constructor(conflicts) {
+        super(`provisioning conflicts with ${conflicts.length} existing destination(s)`);
+        this.name = "ProvisionConflictError";
+        this.conflicts = conflicts;
+    }
+}
+function kitContentHash(kitDir) {
+    const hash = crypto.createHash("sha256");
+    for (const file of walkFiles(kitDir)) {
+        const rel = path.relative(kitDir, file).split(path.sep).join("/");
+        if (rel.split("/").some((part) => [".git", "__pycache__", ".pytest_cache"].includes(part)))
+            continue;
+        hash.update(rel);
+        hash.update("\0");
+        hash.update(fs.readFileSync(file));
+        hash.update("\0");
+    }
+    return `sha256:${hash.digest("hex")}`;
+}
+function isContained(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return relative !== "" && !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+function assertSafeDestination(rootReal, destination) {
+    const prospective = canonicalProspectivePath(destination);
+    if (!isContained(rootReal, prospective))
+        throw new Error(`provision target escapes consumer repository: ${destination}`);
+    if (!fs.existsSync(destination))
+        return;
+    const stat = fs.lstatSync(destination);
+    if (stat.isSymbolicLink())
+        throw new Error(`refusing provision target symlink: ${destination}`);
+    if (!stat.isFile())
+        throw new Error(`provision target is not a regular file: ${destination}`);
+}
+function manifestProvisions(manifest) {
+    if (!Array.isArray(manifest.provisions))
+        return [];
+    return manifest.provisions.map((entry) => {
+        const record = entry;
+        return {
+            id: String(record.id),
+            path: String(record.path),
+            target: path.posix.normalize(String(record.target).replace(/\\/g, "/")),
+            ...(typeof record.description === "string" ? { description: record.description } : {}),
+        };
+    });
+}
+export async function provisionKit(kitDir, targetDir, options = {}) {
+    const kitRoot = fs.realpathSync(path.resolve(kitDir));
+    const targetPath = path.resolve(targetDir);
+    if (!fs.existsSync(targetPath) || !fs.statSync(targetPath).isDirectory()) {
+        throw new Error(`provision target must exist and be a directory: ${targetPath}`);
+    }
+    const targetRoot = fs.realpathSync(targetPath);
+    const manifest = await assertKitRepository(kitRoot);
+    const kitId = String(manifest.id);
+    const files = manifestProvisions(manifest).map((entry) => ({
+        id: entry.id,
+        target: entry.target,
+        source: path.resolve(kitRoot, entry.path),
+        destination: path.resolve(targetRoot, ...entry.target.split("/")),
+    }));
+    for (const file of files)
+        assertSafeDestination(targetRoot, file.destination);
+    // Defense in depth against a source swapped to a link after validation: re-assert the
+    // link-resolved source stays inside the kit before we read and copy its bytes.
+    for (const file of files) {
+        const realSource = fs.realpathSync(file.source);
+        if (realSource !== kitRoot && !realSource.startsWith(`${kitRoot}${path.sep}`)) {
+            throw new Error(`provision source escapes the kit directory: ${file.id}`);
+        }
+    }
+    const conflicts = options.force ? [] : files.filter((file) => fs.existsSync(file.destination));
+    if (conflicts.length)
+        throw new ProvisionConflictError(conflicts);
+    const kitHash = kitContentHash(kitRoot);
+    if (options.dryRun || files.length === 0)
+        return { kit_id: kitId, kit_hash: kitHash, files, dry_run: Boolean(options.dryRun) };
+    const manifestPath = path.join(targetRoot, ...PROVISION_MANIFEST_DIR.split("/"), `${kitId}.json`);
+    assertSafeDestination(targetRoot, manifestPath);
+    for (const file of files)
+        atomicCopyFile(targetRoot, file.source, file.destination);
+    atomicWriteJson(targetRoot, manifestPath, {
+        schema_version: "1.0",
+        kit_id: kitId,
+        kit_hash: kitHash,
+        provisioned_at: new Date().toISOString(),
+        files: files.map(({ id, target }) => ({ id, target })),
+    });
+    return { kit_id: kitId, kit_hash: kitHash, files, manifest_path: manifestPath, dry_run: false };
+}

package/dist/pi/build/src/flow-kit/validate.d.ts

@@ -4,6 +4,13 @@ export interface KitDependencyEntry {
     kit_id: string;
     reason?: string;
 }
+export interface KitProvisionEntry {
+    id: string;
+    path: string;
+    target: string;
+    description?: string;
+}
+export declare const PROVISION_MANIFEST_DIR = ".kontourai/flow-agents/provisions";
 export interface KitWorkflowTriggerEntry {
     id: string;
     when: string;
@@ -25,6 +32,18 @@ export interface KitHookInfluenceExpectationEntry {
     must_include_guidance: string[];
     must_include_actions: string[];
 }
+export interface KitAgentSpawnTriggerGuards {
+    dedup_key: string;
+    cooldown_seconds: number;
+    daily_cap: number;
+    max_concurrent: number;
+}
+export interface KitAgentSpawnTriggerEntry {
+    id: string;
+    description: string;
+    spawns_agent_runs: boolean;
+    guards?: KitAgentSpawnTriggerGuards;
+}
 export type KitSkillRole = "entrypoint" | "profile" | "step" | "shared-primitive" | "extension";
 export interface KitSkillRoleEntry {
     skill_id: string;
@@ -61,6 +80,29 @@ export declare function parseKitHookInfluenceExpectations(manifest: Record<strin
     entries: KitHookInfluenceExpectationEntry[];
     errors: string[];
 };
+/**
+ * Parse and shape-validate a kit manifest's optional `agent_spawn_triggers` field:
+ * perimeter trigger surfaces (check failures, schedules, watchers) that spawn agent
+ * runs, plus their guard config. Contract: context/contracts/trigger-guards.md.
+ *
+ * Shape rules (ERRORS):
+ *  - `agent_spawn_triggers` (if present) must be an array of objects.
+ *  - `id` must match the workflow-trigger identifier pattern and be unique.
+ *  - `description` must be a non-empty string.
+ *  - `spawns_agent_runs` must be a boolean.
+ *  - `guards` (if present) must be an object with exactly the four guard fields when
+ *    complete: `dedup_key` non-empty string; `cooldown_seconds`, `daily_cap`,
+ *    `max_concurrent` integers >= 1. Unknown guard fields are errors.
+ *
+ * Guard-completeness (WARNINGS, never errors — declaration-first rollout, #664):
+ *  - an entry with `spawns_agent_runs: true` and missing or incomplete `guards`
+ *    produces a warning naming the missing guard fields and the contract doc.
+ */
+export declare function parseKitAgentSpawnTriggers(manifest: Record<string, unknown>, manifestPath: string): {
+    entries: KitAgentSpawnTriggerEntry[];
+    errors: string[];
+    warnings: string[];
+};
 export declare function parseKitSkillRoles(manifest: Record<string, unknown>, manifestPath: string): {
     entries: KitSkillRoleEntry[];
     errors: string[];
@@ -126,4 +168,14 @@ export interface KitTargetsResult {
  */
 export declare function deriveKitTargets(manifest: Record<string, unknown>, kitDir?: string, sourceRoot?: string): Promise<KitTargetsResult>;
 export declare function validateKitRepository(kitDir: string): Promise<string[]>;
+/**
+ * Repository validation with a non-blocking warnings channel alongside the blocking
+ * errors `validateKitRepository` has always returned. Warnings are advisory quality
+ * findings (today: an agent-spawning trigger surface declared without complete guard
+ * config — context/contracts/trigger-guards.md); they never fail validation.
+ */
+export declare function validateKitRepositoryDiagnostics(kitDir: string): Promise<{
+    errors: string[];
+    warnings: string[];
+}>;
 export declare function assertKitRepository(kitDir: string): Promise<Record<string, unknown>>;

package/dist/pi/build/src/flow-kit/validate.js

@@ -5,19 +5,24 @@ import { parseKitFlowStepActions, workflowTriggerIdentifier } from "./action-met
 import { validateActionRepositoryMetadata } from "./action-repository-validation.js";
 export { isObservableBuilderArtifactRef, isSafeBuilderArtifactRef, parseKitFlowStepActions } from "./action-metadata.js";
 // Extension-only asset classes: validated by Flow Agents. Flows are validated by @kontourai/flow.
-const EXTENSION_ASSET_CLASSES = ["skills", "docs", "adapters", "evals", "assets"];
+const EXTENSION_ASSET_CLASSES = ["skills", "docs", "adapters", "evals", "assets", "provisions"];
 // Core container fields owned by kontourai/flow (flow-kit-container.schema.json).
 // agent-extension fields are skills, docs, adapters, evals, assets.
 const CORE_CONTAINER_FIELDS = new Set(["schema_version", "id", "name", "description", "product_name", "flows"]);
-const AGENT_EXTENSION_CLASSES = new Set(["skills", "docs", "adapters", "evals", "assets"]);
+const AGENT_EXTENSION_CLASSES = new Set(["skills", "docs", "adapters", "evals", "assets", "provisions"]);
 // Flow Agents-recognized metadata fields that are neither core container fields nor
 // agent-extension asset classes. Recognized here so they are never misreported as
 // unknown third-party extension namespaces. `dependencies` declares cross-kit skill
 // dependencies (extension-layer ownership; see docs/adr/0019-kit-dependency-ownership.md),
 // workflow_triggers / hook_influence_expectations declare kit-owned runtime influence,
-// and first_party is legacy catalog/marketplace metadata. It does not grant runtime
-// capability or steering privilege.
-const KNOWN_METADATA_FIELDS = new Set(["dependencies", "workflow_triggers", "hook_influence_expectations", "flow_step_actions", "skill_roles", "first_party"]);
+// agent_spawn_triggers declares perimeter trigger surfaces that spawn agent runs plus
+// their guard config (context/contracts/trigger-guards.md), and first_party is legacy
+// catalog/marketplace metadata. It does not grant runtime capability or steering privilege.
+const KNOWN_METADATA_FIELDS = new Set(["dependencies", "workflow_triggers", "hook_influence_expectations", "flow_step_actions", "skill_roles", "first_party", "agent_spawn_triggers"]);
+// Consumer-repo-relative directory (posix, lowercase) where the engine writes its own
+// per-kit provision manifest. Reserved: a provision may not target inside it. Shared with
+// provision.ts so the reservation and the actual manifest write stay in agreement.
+export const PROVISION_MANIFEST_DIR = ".kontourai/flow-agents/provisions";
 /**
  * Parse and shape-validate a kit manifest's `dependencies` field (Flow Agents
  * extension-layer metadata; see docs/adr/0019-kit-dependency-ownership.md).
@@ -221,6 +226,120 @@ export function parseKitHookInfluenceExpectations(manifest, manifestPath) {
     });
     return { entries, errors };
 }
+const AGENT_SPAWN_TRIGGER_GUARD_FIELDS = ["dedup_key", "cooldown_seconds", "daily_cap", "max_concurrent"];
+/**
+ * Parse and shape-validate a kit manifest's optional `agent_spawn_triggers` field:
+ * perimeter trigger surfaces (check failures, schedules, watchers) that spawn agent
+ * runs, plus their guard config. Contract: context/contracts/trigger-guards.md.
+ *
+ * Shape rules (ERRORS):
+ *  - `agent_spawn_triggers` (if present) must be an array of objects.
+ *  - `id` must match the workflow-trigger identifier pattern and be unique.
+ *  - `description` must be a non-empty string.
+ *  - `spawns_agent_runs` must be a boolean.
+ *  - `guards` (if present) must be an object with exactly the four guard fields when
+ *    complete: `dedup_key` non-empty string; `cooldown_seconds`, `daily_cap`,
+ *    `max_concurrent` integers >= 1. Unknown guard fields are errors.
+ *
+ * Guard-completeness (WARNINGS, never errors — declaration-first rollout, #664):
+ *  - an entry with `spawns_agent_runs: true` and missing or incomplete `guards`
+ *    produces a warning naming the missing guard fields and the contract doc.
+ */
+export function parseKitAgentSpawnTriggers(manifest, manifestPath) {
+    const entries = [];
+    const errors = [];
+    const warnings = [];
+    const raw = manifest.agent_spawn_triggers;
+    if (raw === undefined)
+        return { entries, errors, warnings };
+    if (!Array.isArray(raw)) {
+        errors.push(`${manifestPath}: .agent_spawn_triggers must be a list`);
+        return { entries, errors, warnings };
+    }
+    const fields = new Set(["id", "description", "spawns_agent_runs", "guards"]);
+    const seen = new Set();
+    raw.forEach((entry, index) => {
+        if (typeof entry !== "object" || entry === null) {
+            errors.push(`${manifestPath}: agent_spawn_triggers[${index}] must be an object`);
+            return;
+        }
+        const record = entry;
+        const unknown = Object.keys(record).filter((field) => !fields.has(field));
+        if (unknown.length > 0) {
+            errors.push(`${manifestPath}: agent_spawn_triggers[${index}] contains unsupported field(s): ${unknown.join(", ")}`);
+            return;
+        }
+        const id = record.id;
+        if (!workflowTriggerIdentifier(id)) {
+            errors.push(`${manifestPath}: agent_spawn_triggers[${index}].id must match ^[a-z0-9]+(?:[.-][a-z0-9]+)*$`);
+            return;
+        }
+        if (seen.has(id)) {
+            errors.push(`${manifestPath}: agent_spawn_triggers[${index}].id duplicates '${id}'`);
+            return;
+        }
+        seen.add(id);
+        if (typeof record.description !== "string" || !record.description.trim()) {
+            errors.push(`${manifestPath}: agent_spawn_triggers[${index}].description must be a non-empty string`);
+            return;
+        }
+        if (typeof record.spawns_agent_runs !== "boolean") {
+            errors.push(`${manifestPath}: agent_spawn_triggers[${index}].spawns_agent_runs must be a boolean`);
+            return;
+        }
+        let guards;
+        let guardsShapeValid = true;
+        const missingGuardFields = [];
+        if (record.guards !== undefined) {
+            if (typeof record.guards !== "object" || record.guards === null || Array.isArray(record.guards)) {
+                errors.push(`${manifestPath}: agent_spawn_triggers[${index}].guards must be an object when present`);
+                return;
+            }
+            const guardRecord = record.guards;
+            const guardFieldSet = new Set(AGENT_SPAWN_TRIGGER_GUARD_FIELDS);
+            const unknownGuards = Object.keys(guardRecord).filter((field) => !guardFieldSet.has(field));
+            if (unknownGuards.length > 0) {
+                errors.push(`${manifestPath}: agent_spawn_triggers[${index}].guards contains unsupported field(s): ${unknownGuards.join(", ")}`);
+                return;
+            }
+            if (guardRecord.dedup_key !== undefined && (typeof guardRecord.dedup_key !== "string" || !guardRecord.dedup_key.trim())) {
+                errors.push(`${manifestPath}: agent_spawn_triggers[${index}].guards.dedup_key must be a non-empty string`);
+                guardsShapeValid = false;
+            }
+            for (const field of ["cooldown_seconds", "daily_cap", "max_concurrent"]) {
+                const value = guardRecord[field];
+                if (value !== undefined && (typeof value !== "number" || !Number.isInteger(value) || value < 1)) {
+                    errors.push(`${manifestPath}: agent_spawn_triggers[${index}].guards.${field} must be an integer >= 1`);
+                    guardsShapeValid = false;
+                }
+            }
+            if (!guardsShapeValid)
+                return;
+            for (const field of AGENT_SPAWN_TRIGGER_GUARD_FIELDS) {
+                if (guardRecord[field] === undefined)
+                    missingGuardFields.push(field);
+            }
+            if (missingGuardFields.length === 0) {
+                guards = {
+                    dedup_key: guardRecord.dedup_key,
+                    cooldown_seconds: guardRecord.cooldown_seconds,
+                    daily_cap: guardRecord.daily_cap,
+                    max_concurrent: guardRecord.max_concurrent,
+                };
+            }
+        }
+        else {
+            missingGuardFields.push(...AGENT_SPAWN_TRIGGER_GUARD_FIELDS);
+        }
+        if (record.spawns_agent_runs === true && missingGuardFields.length > 0) {
+            warnings.push(`${manifestPath}: agent_spawn_triggers[${index}] ('${id}') spawns agent runs without complete guard config` +
+                ` (missing: ${missingGuardFields.join(", ")}); declare dedup_key, cooldown_seconds, daily_cap, and max_concurrent` +
+                ` per context/contracts/trigger-guards.md`);
+        }
+        entries.push({ id, description: record.description, spawns_agent_runs: record.spawns_agent_runs, ...(guards ? { guards } : {}) });
+    });
+    return { entries, errors, warnings };
+}
 export function parseKitSkillRoles(manifest, manifestPath) {
     const entries = [];
     const errors = [];
@@ -393,7 +512,17 @@ export async function deriveKitTargets(manifest, kitDir = "", sourceRoot = proce
     };
 }
 export async function validateKitRepository(kitDir) {
+    return (await validateKitRepositoryDiagnostics(kitDir)).errors;
+}
+/**
+ * Repository validation with a non-blocking warnings channel alongside the blocking
+ * errors `validateKitRepository` has always returned. Warnings are advisory quality
+ * findings (today: an agent-spawning trigger surface declared without complete guard
+ * config — context/contracts/trigger-guards.md); they never fail validation.
+ */
+export async function validateKitRepositoryDiagnostics(kitDir) {
     const errors = [];
+    const warnings = [];
     const manifestPath = path.join(kitDir, "kit.json");
     let manifest;
     try {
@@ -401,14 +530,16 @@ export async function validateKitRepository(kitDir) {
     }
     catch (error) {
         errors.push(`${manifestPath}: invalid JSON: ${error.message}`);
-        return errors;
+        return { errors, warnings };
     }
     errors.push(...await delegateCoreContainerValidation(kitDir, manifest));
     errors.push(...validateExtensionAssets(kitDir, manifestPath, manifest));
-    errors.push(...validateAgentMetadata(kitDir, manifestPath, manifest));
+    const metadata = validateAgentMetadata(kitDir, manifestPath, manifest);
+    errors.push(...metadata.errors);
+    warnings.push(...metadata.warnings);
     if (manifest.first_party !== undefined && typeof manifest.first_party !== "boolean")
         errors.push(`${manifestPath}: .first_party must be a boolean when present`);
-    return errors;
+    return { errors, warnings };
 }
 function validateExtensionAssets(kitDir, manifestPath, manifest) {
     const errors = [];
@@ -429,11 +560,15 @@ function validateExtensionAssets(kitDir, manifestPath, manifest) {
             const record = entry;
             const id = record.id;
             const rel = record.path;
+            const kitId = typeof manifest.id === "string" ? manifest.id : "";
             if (typeof id === "string") {
                 if (seen.has(id))
                     errors.push(`${manifestPath}: ${section}[${index}].id duplicates`);
                 seen.add(id);
             }
+            if (section === "provisions" && (typeof id !== "string" || !kitId || !id.startsWith(`${kitId}.`))) {
+                errors.push(`${manifestPath}: provisions[${index}].id must be prefixed with '${kitId}.'`);
+            }
             if (typeof rel !== "string" || !rel) {
                 errors.push(`${manifestPath}: ${section}[${index}].path must be a string`);
                 return;
@@ -442,6 +577,10 @@ function validateExtensionAssets(kitDir, manifestPath, manifest) {
                 errors.push(`${manifestPath}: ${section}[${index}].path must be relative`);
                 return;
             }
+            if (rel.replace(/\\/g, "/").split("/").includes("..")) {
+                errors.push(`${manifestPath}: ${section}[${index}].path must not contain traversal segments`);
+                return;
+            }
             const resolved = path.resolve(kitDir, rel);
             const root = path.resolve(kitDir);
             if (resolved !== root && !resolved.startsWith(`${root}${path.sep}`)) {
@@ -451,12 +590,73 @@ function validateExtensionAssets(kitDir, manifestPath, manifest) {
             if (!fs.existsSync(resolved)) {
                 errors.push(`${manifestPath}: ${section}[${index}].path points at missing asset: ${rel}`);
             }
+            else if (section === "provisions") {
+                if (!fs.statSync(resolved).isFile()) {
+                    errors.push(`${manifestPath}: provisions[${index}].path must point at a file: ${rel}`);
+                }
+                else {
+                    // A provisioned source is copied byte-for-byte into a consumer repo, so a symlink that
+                    // resolves outside the kit would exfiltrate arbitrary readable host files. Require the
+                    // link-resolved real path to stay inside the kit.
+                    const realResolved = fs.realpathSync(resolved);
+                    const realRoot = fs.realpathSync(root);
+                    if (realResolved !== realRoot && !realResolved.startsWith(`${realRoot}${path.sep}`)) {
+                        errors.push(`${manifestPath}: provisions[${index}].path must not resolve outside the kit directory`);
+                    }
+                }
+            }
+        });
+    }
+    const rawProvisions = manifest.provisions;
+    if (Array.isArray(rawProvisions)) {
+        const targets = new Set();
+        rawProvisions.forEach((entry, index) => {
+            if (typeof entry !== "object" || entry === null)
+                return;
+            const record = entry;
+            if (record.description !== undefined && typeof record.description !== "string") {
+                errors.push(`${manifestPath}: provisions[${index}].description must be a string when present`);
+            }
+            const target = record.target;
+            if (typeof target !== "string" || target.trim().length === 0) {
+                errors.push(`${manifestPath}: provisions[${index}].target must be a non-empty string`);
+                return;
+            }
+            if (path.isAbsolute(target) || path.win32.isAbsolute(target)) {
+                errors.push(`${manifestPath}: provisions[${index}].target must be relative`);
+                return;
+            }
+            const segments = target.replace(/\\/g, "/").split("/");
+            if (segments.includes("..")) {
+                errors.push(`${manifestPath}: provisions[${index}].target must not contain traversal segments`);
+                return;
+            }
+            const normalized = path.posix.normalize(segments.join("/"));
+            if (normalized === "." || normalized.startsWith("..")) {
+                errors.push(`${manifestPath}: provisions[${index}].target must stay inside the consumer repository`);
+                return;
+            }
+            // Case-fold reserved-directory and collision checks: on a case-insensitive filesystem
+            // `.GIT/` still lands in the real `.git`, and README.md/readme.md still collide.
+            const lowered = normalized.toLowerCase();
+            if (lowered === ".git" || lowered.startsWith(".git/")) {
+                errors.push(`${manifestPath}: provisions[${index}].target must not be inside .git`);
+                return;
+            }
+            if (lowered === PROVISION_MANIFEST_DIR || lowered.startsWith(`${PROVISION_MANIFEST_DIR}/`)) {
+                errors.push(`${manifestPath}: provisions[${index}].target must not be inside the provision manifest namespace (${PROVISION_MANIFEST_DIR}/)`);
+                return;
+            }
+            if (targets.has(lowered))
+                errors.push(`${manifestPath}: provisions[${index}].target duplicates '${normalized}'`);
+            targets.add(lowered);
         });
     }
     return errors;
 }
 function validateAgentMetadata(kitDir, manifestPath, manifest) {
     const errors = [];
+    const warnings = [];
     const depResult = parseKitDependencies(manifest, manifestPath);
     for (const err of depResult.errors)
         errors.push(err);
@@ -466,6 +666,11 @@ function validateAgentMetadata(kitDir, manifestPath, manifest) {
     const hookExpectationResult = parseKitHookInfluenceExpectations(manifest, manifestPath);
     for (const err of hookExpectationResult.errors)
         errors.push(err);
+    const agentSpawnTriggerResult = parseKitAgentSpawnTriggers(manifest, manifestPath);
+    for (const err of agentSpawnTriggerResult.errors)
+        errors.push(err);
+    for (const warning of agentSpawnTriggerResult.warnings)
+        warnings.push(warning);
     const flowStepActionResult = parseKitFlowStepActions(manifest, manifestPath);
     for (const err of flowStepActionResult.errors)
         errors.push(err);
@@ -475,7 +680,7 @@ function validateAgentMetadata(kitDir, manifestPath, manifest) {
     if ((manifest.skill_roles !== undefined || manifest.flow_step_actions !== undefined) && skillRoleResult.errors.length === 0) {
         errors.push(...validateActionRepositoryMetadata({ kitDir, manifestPath, manifest, actions: flowStepActionResult.entries, skillRoles: skillRoleResult.entries }));
     }
-    return errors;
+    return { errors, warnings };
 }
 export async function assertKitRepository(kitDir) {
     const errors = await validateKitRepository(kitDir);

package/dist/pi/build/src/index.d.ts

@@ -1,13 +1,44 @@
+export { NARRATIVE_SOURCE_ID_VERSION, SourceIdParseError, compareSourceIds, formatSourceId, parseSourceId, } from "./narrative/source-ids.js";
+export type { AgentEventSourceId, ChainedCommandLogSourceId, CommandLogSourceId, FileSourceId, FlowReportSourceId, FlowStateSourceId, FlowTransitionSourceId, LegacyCommandLogSourceId, NarrativeSourceId, NarrativeSourceStream, SourceIdErrorCode, SurfaceExplanationSourceId, TelemetrySourceId, TranscriptSourceId, TrustSourceId, } from "./narrative/source-ids.js";
+export { DEFAULT_INTEGRITY_CLASS, KNOWN_CAPTURE_GAPS, buildCaptureCompleteness, integrityClassForSource, } from "./narrative/integrity.js";
+export type { CaptureChannelStatus, CaptureCompleteness, IntegrityClass, KnownGapClass, UnavailableReason, } from "./narrative/integrity.js";
+export { TELEMETRY_CHANNEL_ANALYTICS_REDACT_DEFAULT, TELEMETRY_CHANNEL_FULL_REDACT_DEFAULT, effectiveNarrativeRedactionFields, filterNarrativeRecord, } from "./narrative/policy-filter.js";
+export type { NarrativePolicyFilterResult } from "./narrative/policy-filter.js";
+export { snapshotNarrative, validateNarrativeSourceManifest } from "./narrative/snapshot.js";
+export type { NarrativeLineageEvent, NarrativeSourceManifest, NarrativeSourceManifestEntry, NarrativeSourceOrigin, NarrativeSourceRequest, NarrativeSourceRoots, SnapshotNarrativeDependencies, SnapshotNarrativeInput, } from "./narrative/snapshot.js";
+export { resolveManifestEntry, resolveSource, verifyManifest } from "./narrative/resolver.js";
+export type { FrozenManifestEntry, ResolveSourceOptions, ResolveSourceResult, VerifyManifestReport } from "./narrative/resolver.js";
+export { NARRATIVE_RUNTIME_PROJECTION_SCHEMA_VERSION, NARRATIVE_RUNTIME_PROJECTOR, NarrativeProjectionError, projectRuntimeNarrative, stableStringify, validateNarrativeRuntimeProjection, } from "./narrative/projection.js";
+export { GROUNDED_EXECUTION_NARRATIVE_COMPILER_NAME, GROUNDED_EXECUTION_NARRATIVE_SCHEMA_VERSION, GroundedNarrativeError, composeGroundedNarrative, validateGroundedNarrative, writeEnvelope, } from "./narrative/envelope.js";
+export { renderGroundedNarrative } from "./narrative/render.js";
+export type { GroundedExecutionNarrative, GroundedNarrativeConclusion, GroundedNarrativeConfig, GroundedNarrativeCorrelation, GroundedNarrativeErrorCode, GroundedNarrativeFlowTransition, GroundedNarrativeForeignSection, GroundedNarrativeRule, GroundedNarrativeRuntimeSection, GroundedNarrativeSection, SchemaIssue as GroundedNarrativeSchemaIssue, WriteEnvelopeOptions, WrittenGroundedNarrative, } from "./narrative/envelope.js";
+export type { NarrativeRuntimeProjection, NarrativeProjectionErrorCode, ProjectRuntimeNarrativeOptions, RuntimePurpose, RuntimeProjectionTurn, } from "./narrative/projection.js";
+export { QUARANTINE_SESSION_ID, TURN_SPINE_RULE_ID, buildTurnSpine } from "./narrative/turn-spine.js";
+export type { ResolvedTelemetryRecord, Turn, TurnBoundary } from "./narrative/turn-spine.js";
+export { AGENT_STATED_ACTOR_MAX_LENGTH, AGENT_STATED_PURPOSE_MAX_LENGTH, NarrativeStatementError, agentStatedIntent, derivedNoOpTurn, derivedRetry, derivedTimeout, derivedUnavailableSource, observedCommand, observedDelegation, observedFileCreation, observedToolAction, summarizerInferredConnective, workflowDerivedPurpose, } from "./narrative/statements.js";
+export type { NarrativeStatementErrorCode, ObservedResult, Statement, StatementClass, StatementRule, } from "./narrative/statements.js";
+export { INTENT_ANNOTATION_FILE, INTENT_ANNOTATION_SCHEMA_VERSION, bindIntentAnnotation, captureIntent, } from "./narrative/intent.js";
+export type { CaptureIntentDependencies, CaptureIntentInput, CapturedIntent, IntentAnnotation, IntentCapabilityStatus, IntentCaptureMode, } from "./narrative/intent.js";
+export { INTENT_ECONOMICS_FILE, appendIntentEconomics, readIntentEconomics, reduceIntentEconomics, } from "./narrative/intent-economics.js";
+export type { IntentAnnotationMode, IntentEconomicsDelta, IntentEconomicsRecord, IntentEconomicsSummary, } from "./narrative/intent-economics.js";
+export { entailmentIndependenceHolds, isAssertionProhibited, materialEventCoverage, NarrativeGroundingError, validateNarrativeGrounding, } from "./narrative/grounding-validator.js";
+export type { AssertionKind, EntailmentIdentity, EntailmentProvenance, EntailmentVerdict, GroundingKnownGap, GroundingViolation, GroundingViolationCode, GroundingVerdict, MaterialEventClassCoverage, MaterialEventCoverage, MaterialEventKind, ValidateNarrativeGroundingOptions, } from "./narrative/grounding-validator.js";
+export { NARRATIVE_EVAL_RESULT_SCHEMA_VERSION, validateNarrativeEvalResult, } from "./narrative/eval-result.js";
+export type { NarrativeEvalCapabilityParity, NarrativeEvalFixtureResult, NarrativeEvalKnownGap, NarrativeEvalMetricUncertainty, NarrativeEvalMetrics, NarrativeEvalRawSourceLink, NarrativeEvalResult, NarrativeEvalVerdict, SchemaIssue as NarrativeEvalResultSchemaIssue, } from "./narrative/eval-result.js";
+export { GeneratorTimeoutError, PROSE_ECONOMICS_FILE, PROSE_PROMPT_VERSION, ProviderNotAllowedError, hostedModelGenerator, localModelGenerator, providerAllowed, renderProse, stubGenerator, } from "./cli/narrative-render.js";
+export type { GeneratedProse, ModelGeneratorConfig, ProseEconomicsRecord, ProseGenerator, ProseGeneratorInput, ProseGeneratorSentence, ProseGeneratorUsage, ProseRenderOutcome, ProseSourceView, ProviderConfig, ProviderOptIn, RenderProseOptions, RenderProseResult, } from "./cli/narrative-render.js";
 export { BUILDER_BUILD_FLOW_ID, BUILDER_BUILD_FLOW_RELATIVE_PATH, BuilderBuildRunInputError, BuilderBuildRunIdentityError, evaluateBuilderBuildRun, loadBuilderBuildRun, resolveBuilderBuildFlowDefinitionPath, startBuilderBuildRun, } from "./builder-flow-run-adapter.js";
 export type { BuilderBuildRunResult, BuilderBuildRunIdentityMismatch, BuilderBuildTrustBundleEvidenceInput, EvaluateBuilderBuildRunInput, LoadBuilderBuildRunInput, StartBuilderBuildRunInput, } from "./builder-flow-run-adapter.js";
 export { archiveBuilderFlowSession, cancelBuilderFlowSession, pauseBuilderFlowSession, recoverBuilderFlowSession, releaseBuilderFlowAssignment, resumeBuilderFlowSession, startBuilderFlowSession, syncBuilderFlowSession, } from "./builder-flow-runtime.js";
 export type { BuilderFlowAgentLifecycleInput, BuilderFlowAuthorizedLifecycleInput, BuilderFlowSessionInput, BuilderFlowSessionResult } from "./builder-flow-runtime.js";
 export { deriveBuilderGateActionEnvelope, gateActionProgressSnapshot, withGateActionPriorProgress, } from "./builder-gate-action-envelope.js";
-export type { BuilderGateActionEnvelopeInput, GateActionEnvelope, GateActionInterfaceParameter, GateActionPriorProgress, GateActionProgressSnapshot, GateActionPublicMutation, } from "./builder-gate-action-envelope.js";
+export type { BuilderGateActionEnvelopeInput, GateActionArtifactBinding, GateActionArtifactTarget, GateActionEnvelope, GateActionInterfaceParameter, GateActionPriorProgress, GateActionProgressSnapshot, GateActionPublicMutation, } from "./builder-gate-action-envelope.js";
 export { ContinuationAdapterTimeoutError, MAX_CONTINUATION_ADAPTER_EVIDENCE_BYTES, MAX_CONTINUATION_TURN_RESULT_BYTES, createFileContinuationStore, driveBuilderFlowSession, runContinuationDriver, withContinuationDriverLock, } from "./continuation-driver.js";
-export type { ContinuationBarrier, ContinuationAcceptedTurn, ContinuationDriverEvent, ContinuationDriverLockLease, ContinuationDriverOutcome, ContinuationDriverState, ContinuationRuntimePort, ContinuationSnapshot, ContinuationStateStore, ContinuationTurnAuthority, ContinuationTurnContext, ContinuationTurnRequest, ContinuationTurnResult, DriveBuilderFlowSessionInput, RunContinuationDriverInput, } from "./continuation-driver.js";
+export type { ContinuationBarrier, ContinuationContextPolicy, ContinuationContextStrategy, ContinuationAcceptedTurn, ContinuationDriverEvent, ContinuationDriverLockLease, ContinuationDriverOutcome, ContinuationDriverState, ContinuationRuntimePort, ContinuationSnapshot, ContinuationStateStore, ContinuationTurnAuthority, ContinuationTurnContext, ContinuationTurnRequest, ContinuationTurnResult, DriveBuilderFlowSessionInput, RunContinuationDriverInput, } from "./continuation-driver.js";
 export { builderLifecycleAuthorizationPayload, loadBuilderLifecycleAuthorization } from "./builder-lifecycle-authority.js";
 export type { BuilderLifecycleAuthorization } from "./builder-lifecycle-authority.js";
+export { CAPABILITIES, RUNTIME_ADAPTER_IDS, RUNTIME_CAPABILITY_DECLARATIONS, RUNTIME_ID_ALIASES, getDeclaration, normalizeRuntimeId, queryCapability, } from "./lib/capability-declarations.js";
+export type { Capability, CapabilityStatus, RuntimeAdapterId, RuntimeCapabilityDeclaration, } from "./lib/capability-declarations.js";
 export { defaultArtifactRootForRead, defaultCodexHome, defaultTelemetryDirForRead, defaultTelemetryDirsForRead, durableFlowAgentsRoot, durableInstallRecordPath, DURABLE_FLOW_AGENTS_DIR, FLOW_AGENTS_RUNTIME_DIR, FLOW_AGENTS_RUNTIME_SUBDIR, firstExistingPath, flowAgentsArtifactRoot, KONTOURAI_DIR, legacyTelemetryDataDir, LEGACY_TELEMETRY_DIR, telemetryDataDir, } from "./lib/local-artifact-root.js";
 export { validateTrustBundle, normalizeCheck, normalizeFinding, normalizeLearning, normalizeEvidenceRefs, validateEvidenceRef, validateLearningCorrection, loadJson, writeJson, appendJsonl, sidecarBase, writeState, statuses, phases, checkKinds, checkStatuses, verdicts, } from "./cli/workflow-sidecar.js";
 /** Read a sidecar JSON file from a workflow artifact directory; returns `{}` if absent. */

package/dist/pi/build/src/index.js

@@ -13,6 +13,29 @@
  */
 import * as path from "node:path";
 import { loadJson as _loadJson, writeJson as _writeJson } from "./cli/workflow-sidecar.js";
+export { NARRATIVE_SOURCE_ID_VERSION, SourceIdParseError, compareSourceIds, formatSourceId, parseSourceId, } from "./narrative/source-ids.js";
+export { DEFAULT_INTEGRITY_CLASS, KNOWN_CAPTURE_GAPS, buildCaptureCompleteness, integrityClassForSource, } from "./narrative/integrity.js";
+export { TELEMETRY_CHANNEL_ANALYTICS_REDACT_DEFAULT, TELEMETRY_CHANNEL_FULL_REDACT_DEFAULT, effectiveNarrativeRedactionFields, filterNarrativeRecord, } from "./narrative/policy-filter.js";
+export { snapshotNarrative, validateNarrativeSourceManifest } from "./narrative/snapshot.js";
+export { resolveManifestEntry, resolveSource, verifyManifest } from "./narrative/resolver.js";
+export { NARRATIVE_RUNTIME_PROJECTION_SCHEMA_VERSION, NARRATIVE_RUNTIME_PROJECTOR, NarrativeProjectionError, projectRuntimeNarrative, stableStringify, validateNarrativeRuntimeProjection, } from "./narrative/projection.js";
+export { GROUNDED_EXECUTION_NARRATIVE_COMPILER_NAME, GROUNDED_EXECUTION_NARRATIVE_SCHEMA_VERSION, GroundedNarrativeError, composeGroundedNarrative, validateGroundedNarrative, writeEnvelope, } from "./narrative/envelope.js";
+export { renderGroundedNarrative } from "./narrative/render.js";
+export { QUARANTINE_SESSION_ID, TURN_SPINE_RULE_ID, buildTurnSpine } from "./narrative/turn-spine.js";
+export { AGENT_STATED_ACTOR_MAX_LENGTH, AGENT_STATED_PURPOSE_MAX_LENGTH, NarrativeStatementError, agentStatedIntent, derivedNoOpTurn, derivedRetry, derivedTimeout, derivedUnavailableSource, observedCommand, observedDelegation, observedFileCreation, observedToolAction, summarizerInferredConnective, workflowDerivedPurpose, } from "./narrative/statements.js";
+// #622: bounded, capability-declared at-action stated-intent capture + the
+// annotation-on/off A/B measurement with uncertainty.
+export { INTENT_ANNOTATION_FILE, INTENT_ANNOTATION_SCHEMA_VERSION, bindIntentAnnotation, captureIntent, } from "./narrative/intent.js";
+export { INTENT_ECONOMICS_FILE, appendIntentEconomics, readIntentEconomics, reduceIntentEconomics, } from "./narrative/intent-economics.js";
+export { entailmentIndependenceHolds, isAssertionProhibited, materialEventCoverage, NarrativeGroundingError, validateNarrativeGrounding, } from "./narrative/grounding-validator.js";
+// #612: consolidated grounded-narrative eval-result schema + ajv-free validator.
+// The shared, versioned package (corpus.json + this result schema) consumed by
+// kontourai/evals#95 unmodified (R6/AC6).
+export { NARRATIVE_EVAL_RESULT_SCHEMA_VERSION, validateNarrativeEvalResult, } from "./narrative/eval-result.js";
+// #614: model-assisted prose renderer (display-only, fail-closed). Lives outside
+// src/narrative/ (I/O, provider gating, timeout orchestration; see narrative-render.ts's
+// header comment) but is exported here alongside the pure narrative primitives it composes.
+export { GeneratorTimeoutError, PROSE_ECONOMICS_FILE, PROSE_PROMPT_VERSION, ProviderNotAllowedError, hostedModelGenerator, localModelGenerator, providerAllowed, renderProse, stubGenerator, } from "./cli/narrative-render.js";
 export { BUILDER_BUILD_FLOW_ID, BUILDER_BUILD_FLOW_RELATIVE_PATH, BuilderBuildRunInputError, BuilderBuildRunIdentityError, evaluateBuilderBuildRun, loadBuilderBuildRun, resolveBuilderBuildFlowDefinitionPath, startBuilderBuildRun, } from "./builder-flow-run-adapter.js";
 export { archiveBuilderFlowSession, cancelBuilderFlowSession, pauseBuilderFlowSession, recoverBuilderFlowSession, releaseBuilderFlowAssignment, resumeBuilderFlowSession, startBuilderFlowSession, syncBuilderFlowSession, } from "./builder-flow-runtime.js";
 export { deriveBuilderGateActionEnvelope, gateActionProgressSnapshot, withGateActionPriorProgress, } from "./builder-gate-action-envelope.js";
@@ -20,6 +43,7 @@ export { ContinuationAdapterTimeoutError, MAX_CONTINUATION_ADAPTER_EVIDENCE_BYTE
 // Pure serialization contract used by external lifecycle authorities when
 // signing requests. This does not load, create, or mutate a Flow run.
 export { builderLifecycleAuthorizationPayload, loadBuilderLifecycleAuthorization } from "./builder-lifecycle-authority.js";
+export { CAPABILITIES, RUNTIME_ADAPTER_IDS, RUNTIME_CAPABILITY_DECLARATIONS, RUNTIME_ID_ALIASES, getDeclaration, normalizeRuntimeId, queryCapability, } from "./lib/capability-declarations.js";
 export { defaultArtifactRootForRead, defaultCodexHome, defaultTelemetryDirForRead, defaultTelemetryDirsForRead, durableFlowAgentsRoot, durableInstallRecordPath, DURABLE_FLOW_AGENTS_DIR, FLOW_AGENTS_RUNTIME_DIR, FLOW_AGENTS_RUNTIME_SUBDIR, firstExistingPath, flowAgentsArtifactRoot, KONTOURAI_DIR, legacyTelemetryDataDir, LEGACY_TELEMETRY_DIR, telemetryDataDir, } from "./lib/local-artifact-root.js";
 export { 
 // Trust-bundle (Hachure) validation — the same validator the writer uses.