@kontourai/flow-agents 4.0.0 → 4.2.0

package/src/flow-kit/validate.ts

@@ -7,27 +7,40 @@ export { isObservableBuilderArtifactRef, isSafeBuilderArtifactRef, parseKitFlowS
 export type { KitFlowStepActionEntry, KitFlowStepArtifactBinding, KitFlowStepExpectationBinding } 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"] as const;
+const EXTENSION_ASSET_CLASSES = ["skills", "docs", "adapters", "evals", "assets", "provisions"] as const;
 
 // 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"]);
 
 export interface KitDependencyEntry {
   kit_id: string;
   reason?: string;
 }
 
+export interface KitProvisionEntry {
+  id: string;
+  path: string;
+  target: string;
+  description?: string;
+}
+
+// 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";
+
 export interface KitWorkflowTriggerEntry {
   id: string;
   when: string;
@@ -48,6 +61,20 @@ export interface KitHookInfluenceExpectationEntry {
   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 {
@@ -266,6 +293,120 @@ export function parseKitHookInfluenceExpectations(manifest: Record<string, unkno
   return { entries, errors };
 }
 
+const AGENT_SPAWN_TRIGGER_GUARD_FIELDS = ["dedup_key", "cooldown_seconds", "daily_cap", "max_concurrent"] as const;
+
+/**
+ * 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: Record<string, unknown>, manifestPath: string): { entries: KitAgentSpawnTriggerEntry[]; errors: string[]; warnings: string[] } {
+  const entries: KitAgentSpawnTriggerEntry[] = [];
+  const errors: string[] = [];
+  const warnings: string[] = [];
+  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<string>();
+  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 as Record<string, unknown>;
+    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: KitAgentSpawnTriggerGuards | undefined;
+    let guardsShapeValid = true;
+    const missingGuardFields: string[] = [];
+    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 as Record<string, unknown>;
+      const guardFieldSet = new Set<string>(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"] as const) {
+        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 as string,
+          cooldown_seconds: guardRecord.cooldown_seconds as number,
+          daily_cap: guardRecord.daily_cap as number,
+          max_concurrent: guardRecord.max_concurrent as number,
+        };
+      }
+    } 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: Record<string, unknown>, manifestPath: string): { entries: KitSkillRoleEntry[]; errors: string[] } {
   const entries: KitSkillRoleEntry[] = [];
   const errors: string[] = [];
@@ -493,21 +634,34 @@ export async function deriveKitTargets(manifest: Record<string, unknown>, kitDir
 }
 
 export async function validateKitRepository(kitDir: string): Promise<string[]> {
+  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: string): Promise<{ errors: string[]; warnings: string[] }> {
   const errors: string[] = [];
+  const warnings: string[] = [];
   const manifestPath = path.join(kitDir, "kit.json");
   let manifest: Record<string, unknown>;
   try {
     manifest = readJson(manifestPath) as Record<string, unknown>;
   } catch (error) {
     errors.push(`${manifestPath}: invalid JSON: ${(error as 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: string, manifestPath: string, manifest: Record<string, unknown>): string[] {
@@ -528,10 +682,14 @@ function validateExtensionAssets(kitDir: string, manifestPath: string, manifest:
       const record = entry as Record<string, unknown>;
       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;
@@ -540,6 +698,10 @@ function validateExtensionAssets(kitDir: string, manifestPath: string, 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}`)) {
@@ -548,21 +710,82 @@ function validateExtensionAssets(kitDir: string, manifestPath: string, 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<string>();
+    rawProvisions.forEach((entry, index) => {
+      if (typeof entry !== "object" || entry === null) return;
+      const record = entry as Record<string, unknown>;
+      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: string, manifestPath: string, manifest: Record<string, unknown>): string[] {
+function validateAgentMetadata(kitDir: string, manifestPath: string, manifest: Record<string, unknown>): { errors: string[]; warnings: string[] } {
   const errors: string[] = [];
+  const warnings: string[] = [];
   const depResult = parseKitDependencies(manifest, manifestPath);
   for (const err of depResult.errors) errors.push(err);
   const workflowTriggerResult = parseKitWorkflowTriggers(manifest, manifestPath);
   for (const err of workflowTriggerResult.errors) errors.push(err);
   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);
   const skillRoleResult = parseKitSkillRoles(manifest, manifestPath);
@@ -570,7 +793,7 @@ function validateAgentMetadata(kitDir: string, manifestPath: string, manifest: R
   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: string): Promise<Record<string, unknown>> {

package/src/runtime-adapters.ts

@@ -59,7 +59,7 @@ export type LoadedKit = {
   hook_influence_expectations: KitHookInfluenceExpectationRef[];
 };
 
-const ASSET_CLASSES = ["flows", "skills", "docs", "adapters", "evals", "assets"];
+const ASSET_CLASSES = ["flows", "skills", "docs", "adapters", "evals", "assets", "provisions"];
 const KIT_ID_RE = /^[a-z][a-z0-9-]*$/;
 
 function assetPath(root: string, value: string): string | null {