@kontourai/flow-agents 3.4.0 → 3.4.1

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [3.4.1](https://github.com/kontourai/flow-agents/compare/v3.4.0...v3.4.1) (2026-07-10)
+
+
+### Fixes
+
+* resolve packaged Flow definitions in consumer repos ([#532](https://github.com/kontourai/flow-agents/issues/532)) ([3eb4a2e](https://github.com/kontourai/flow-agents/commit/3eb4a2e42d49a9c31b16ef62484cf5b0a001c7a1))
+
 ## [3.4.0](https://github.com/kontourai/flow-agents/compare/v3.3.0...v3.4.0) (2026-07-10)
 
 

package/build/src/lib/flow-resolver.d.ts

@@ -20,8 +20,8 @@
  *  - FLOW_AGENTS_FLOW_DEFS_DIR resolves into a runtime artifact directory
  *  - The resolved path escapes the expected root (belt-and-suspenders)
  *
- * When the override is unsafe, it is ignored and the resolver uses the
- * canonical repoRoot/kits/ source for legitimate flows.
+ * An unsafe explicit override fails closed. Package fallback applies only to
+ * canonical lookup when no override was supplied.
  */
 export declare function resolveFlowFilePath(kitId: string, flowName: string, flowId: string, repoRoot: string, allowOverride?: boolean): string | null;
 /** A single gate expectation from a FlowDefinition expects[] entry. */

package/build/src/lib/flow-resolver.js

@@ -54,6 +54,35 @@ function isAgentWritableDir(resolvedDir) {
         return false;
     }
 }
+function installedPackageRoot() {
+    let directory = path.dirname(fileURLToPath(import.meta.url));
+    while (true) {
+        if (fs.existsSync(path.join(directory, "package.json")) && fs.existsSync(path.join(directory, "kits"))) {
+            return directory;
+        }
+        const parent = path.dirname(directory);
+        if (parent === directory)
+            return null;
+        directory = parent;
+    }
+}
+function packagedFlowFile(kitId, flowName, consumerRoot) {
+    const packageRoot = installedPackageRoot();
+    if (!packageRoot || path.resolve(packageRoot) === path.resolve(consumerRoot))
+        return null;
+    const kitsRoot = path.resolve(packageRoot, "kits");
+    const candidate = path.resolve(kitsRoot, kitId, "flows", `${flowName}.flow.json`);
+    if (!candidate.startsWith(kitsRoot + path.sep))
+        return null;
+    try {
+        const realKitsRoot = fs.realpathSync.native(kitsRoot);
+        const realCandidate = fs.realpathSync.native(candidate);
+        return realCandidate.startsWith(realKitsRoot + path.sep) ? realCandidate : null;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Build and validate the FlowDefinition file path.
  *
@@ -62,8 +91,8 @@ function isAgentWritableDir(resolvedDir) {
  *  - FLOW_AGENTS_FLOW_DEFS_DIR resolves into a runtime artifact directory
  *  - The resolved path escapes the expected root (belt-and-suspenders)
  *
- * When the override is unsafe, it is ignored and the resolver uses the
- * canonical repoRoot/kits/ source for legitimate flows.
+ * An unsafe explicit override fails closed. Package fallback applies only to
+ * canonical lookup when no override was supplied.
  */
 export function resolveFlowFilePath(kitId, flowName, flowId, repoRoot, allowOverride = true) {
     // Primary defense: reject any slug containing traversal chars or non-identifier chars.
@@ -72,13 +101,11 @@ export function resolveFlowFilePath(kitId, flowName, flowId, repoRoot, allowOver
     const override = allowOverride ? process.env["FLOW_AGENTS_FLOW_DEFS_DIR"] : undefined;
     let expectedRoot;
     let flowFilePath;
+    let canonicalLookup = false;
     if (override) {
         const resolvedOverride = path.resolve(override);
         if (isAgentWritableDir(resolvedOverride)) {
-            // Override targets an agent-writable runtime path; ignore it and use
-            // the canonical kit root. The session will resolve the real kit flow.
-            expectedRoot = path.resolve(repoRoot, "kits");
-            flowFilePath = path.join(repoRoot, "kits", kitId, "flows", `${flowName}.flow.json`);
+            return null;
         }
         else {
             expectedRoot = resolvedOverride;
@@ -90,6 +117,7 @@ export function resolveFlowFilePath(kitId, flowName, flowId, repoRoot, allowOver
     else {
         expectedRoot = path.resolve(repoRoot, "kits");
         flowFilePath = path.join(repoRoot, "kits", kitId, "flows", `${flowName}.flow.json`);
+        canonicalLookup = true;
     }
     // Belt-and-suspenders: confirm the resolved path stays within the expected root.
     // After slug validation this is theoretically unreachable, but defense-in-depth
@@ -110,6 +138,11 @@ export function resolveFlowFilePath(kitId, flowName, flowId, repoRoot, allowOver
         return realPath;
     }
     catch {
+        if (canonicalLookup) {
+            const packaged = packagedFlowFile(kitId, flowName, repoRoot);
+            if (packaged)
+                return packaged;
+        }
         return resolvedPath;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/flow-agents",
-  "version": "3.4.0",
+  "version": "3.4.1",
   "description": "Flow Agents — a Kontour product that applies Flow and Veritas discipline as a portable process layer inside the agent tools you already use: Claude Code, Codex, Kiro, opencode, pi, and GitHub Actions — with framework adapters (AWS Strands preview) on the same policy-engine contract.",
   "keywords": [
     "agents",

package/src/cli/flow-resolver-composition.test.mjs

@@ -4,7 +4,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
-import { resolveEffectiveFlowDefinition } from "../../build/src/lib/flow-resolver.js";
+import { resolveEffectiveFlowDefinition, resolveFlowFilePath } from "../../build/src/lib/flow-resolver.js";
 
 const REPO_ROOT = path.resolve(import.meta.dirname, "../..");
 
@@ -26,6 +26,35 @@ test("effective Builder definition materializes uses_flow and Flow-native comple
   );
 });
 
+test("installed package definitions resolve when a consumer repo has no kits directory", () => {
+  const consumer = fs.mkdtempSync(path.join(os.tmpdir(), "flow-agents-consumer-"));
+  const resolved = resolveFlowFilePath("builder", "build", "builder.build", consumer, false);
+  assert.ok(resolved);
+  assert.equal(fs.realpathSync(resolved), fs.realpathSync(path.join(REPO_ROOT, "kits", "builder", "flows", "build.flow.json")));
+  assert.equal(resolveEffectiveFlowDefinition("builder.build", consumer, { allowOverride: false })?.version, "1.1");
+});
+
+test("consumer-vendored definitions remain authoritative over package fallback", () => {
+  const consumer = fs.mkdtempSync(path.join(os.tmpdir(), "flow-agents-consumer-vendored-"));
+  const vendored = path.join(consumer, "kits", "builder", "flows", "build.flow.json");
+  writeJson(vendored, { id: "builder.build", version: "consumer", steps: [{ id: "local", next: null }], gates: {} });
+  assert.equal(resolveFlowFilePath("builder", "build", "builder.build", consumer, false), fs.realpathSync(vendored));
+});
+
+test("unsafe explicit overrides fail closed instead of using package fallback", () => {
+  const consumer = fs.mkdtempSync(path.join(os.tmpdir(), "flow-agents-consumer-unsafe-"));
+  const unsafeDefinitions = path.join(consumer, ".kontourai", "flow-agents", "definitions");
+  fs.mkdirSync(unsafeDefinitions, { recursive: true });
+  const prior = process.env.FLOW_AGENTS_FLOW_DEFS_DIR;
+  process.env.FLOW_AGENTS_FLOW_DEFS_DIR = unsafeDefinitions;
+  try {
+    assert.equal(resolveFlowFilePath("builder", "build", "builder.build", consumer), null);
+  } finally {
+    if (prior === undefined) delete process.env.FLOW_AGENTS_FLOW_DEFS_DIR;
+    else process.env.FLOW_AGENTS_FLOW_DEFS_DIR = prior;
+  }
+});
+
 test("effective definition compilation rejects uses_flow cycles", () => {
   const definitions = fs.mkdtempSync(path.join(os.tmpdir(), "flow-agents-composition-cycle-"));
   writeJson(path.join(definitions, "loop.one.flow.json"), {

package/src/lib/flow-resolver.ts

@@ -57,6 +57,33 @@ function isAgentWritableDir(resolvedDir: string): boolean {
   }
 }
 
+function installedPackageRoot(): string | null {
+  let directory = path.dirname(fileURLToPath(import.meta.url));
+  while (true) {
+    if (fs.existsSync(path.join(directory, "package.json")) && fs.existsSync(path.join(directory, "kits"))) {
+      return directory;
+    }
+    const parent = path.dirname(directory);
+    if (parent === directory) return null;
+    directory = parent;
+  }
+}
+
+function packagedFlowFile(kitId: string, flowName: string, consumerRoot: string): string | null {
+  const packageRoot = installedPackageRoot();
+  if (!packageRoot || path.resolve(packageRoot) === path.resolve(consumerRoot)) return null;
+  const kitsRoot = path.resolve(packageRoot, "kits");
+  const candidate = path.resolve(kitsRoot, kitId, "flows", `${flowName}.flow.json`);
+  if (!candidate.startsWith(kitsRoot + path.sep)) return null;
+  try {
+    const realKitsRoot = fs.realpathSync.native(kitsRoot);
+    const realCandidate = fs.realpathSync.native(candidate);
+    return realCandidate.startsWith(realKitsRoot + path.sep) ? realCandidate : null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Build and validate the FlowDefinition file path.
  *
@@ -65,8 +92,8 @@ function isAgentWritableDir(resolvedDir: string): boolean {
  *  - FLOW_AGENTS_FLOW_DEFS_DIR resolves into a runtime artifact directory
  *  - The resolved path escapes the expected root (belt-and-suspenders)
  *
- * When the override is unsafe, it is ignored and the resolver uses the
- * canonical repoRoot/kits/ source for legitimate flows.
+ * An unsafe explicit override fails closed. Package fallback applies only to
+ * canonical lookup when no override was supplied.
  */
 export function resolveFlowFilePath(
   kitId: string,
@@ -82,14 +109,12 @@ export function resolveFlowFilePath(
 
   let expectedRoot: string;
   let flowFilePath: string;
+  let canonicalLookup = false;
 
   if (override) {
     const resolvedOverride = path.resolve(override);
     if (isAgentWritableDir(resolvedOverride)) {
-      // Override targets an agent-writable runtime path; ignore it and use
-      // the canonical kit root. The session will resolve the real kit flow.
-      expectedRoot = path.resolve(repoRoot, "kits");
-      flowFilePath = path.join(repoRoot, "kits", kitId, "flows", `${flowName}.flow.json`);
+      return null;
     } else {
       expectedRoot = resolvedOverride;
       // flowId = kitId + "." + flowName; after slug validation this contains only
@@ -99,6 +124,7 @@ export function resolveFlowFilePath(
   } else {
     expectedRoot = path.resolve(repoRoot, "kits");
     flowFilePath = path.join(repoRoot, "kits", kitId, "flows", `${flowName}.flow.json`);
+    canonicalLookup = true;
   }
 
   // Belt-and-suspenders: confirm the resolved path stays within the expected root.
@@ -120,6 +146,10 @@ export function resolveFlowFilePath(
     }
     return realPath;
   } catch {
+    if (canonicalLookup) {
+      const packaged = packagedFlowFile(kitId, flowName, repoRoot);
+      if (packaged) return packaged;
+    }
     return resolvedPath;
   }
 }