@kontourai/flow-agents 2.3.0 → 2.4.0

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

@@ -1,3 +1,26 @@
+export interface KitDependencyEntry {
+    kit_id: string;
+    reason?: string;
+}
+/**
+ * Parse and shape-validate a kit manifest's `dependencies` field (Flow Agents
+ * extension-layer metadata; see docs/adr/0019-kit-dependency-ownership.md).
+ *
+ * Shape rules:
+ *  - `dependencies` (if present) must be an array.
+ *  - each entry must be an object with a `kit_id` string matching ^[a-z][a-z0-9-]*$.
+ *  - `kit_id` must not equal the declaring kit's own id (no self-reference).
+ *  - no duplicate `kit_id` across entries.
+ *  - `reason` is an optional string.
+ *
+ * Returns the parsed entries plus any shape errors (empty errors = valid). This is
+ * a sibling shape check, not a member of the file-path-oriented EXTENSION_ASSET_CLASSES
+ * loop, because dependency entries have no `path`/file to check.
+ */
+export declare function parseKitDependencies(manifest: Record<string, unknown>, manifestPath: string): {
+    entries: KitDependencyEntry[];
+    errors: string[];
+};
 export type KitTargetConsumer = "flow" | "flow-agents" | string;
 export interface KitConformanceLevel {
     /** K0: valid core Flow Kit container with at least one flow (gates evaluable agentlessly). */

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

@@ -7,6 +7,66 @@ const EXTENSION_ASSET_CLASSES = ["skills", "docs", "adapters", "evals", "assets"
 // 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"]);
+// 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).
+const KNOWN_METADATA_FIELDS = new Set(["dependencies"]);
+/**
+ * Parse and shape-validate a kit manifest's `dependencies` field (Flow Agents
+ * extension-layer metadata; see docs/adr/0019-kit-dependency-ownership.md).
+ *
+ * Shape rules:
+ *  - `dependencies` (if present) must be an array.
+ *  - each entry must be an object with a `kit_id` string matching ^[a-z][a-z0-9-]*$.
+ *  - `kit_id` must not equal the declaring kit's own id (no self-reference).
+ *  - no duplicate `kit_id` across entries.
+ *  - `reason` is an optional string.
+ *
+ * Returns the parsed entries plus any shape errors (empty errors = valid). This is
+ * a sibling shape check, not a member of the file-path-oriented EXTENSION_ASSET_CLASSES
+ * loop, because dependency entries have no `path`/file to check.
+ */
+export function parseKitDependencies(manifest, manifestPath) {
+    const entries = [];
+    const errors = [];
+    const raw = manifest.dependencies;
+    if (raw === undefined)
+        return { entries, errors };
+    if (!Array.isArray(raw)) {
+        errors.push(`${manifestPath}: .dependencies must be a list`);
+        return { entries, errors };
+    }
+    const ownId = typeof manifest.id === "string" ? manifest.id : "";
+    const seen = new Set();
+    raw.forEach((entry, index) => {
+        if (typeof entry !== "object" || entry === null) {
+            errors.push(`${manifestPath}: dependencies[${index}] must be an object`);
+            return;
+        }
+        const record = entry;
+        const kitId = record.kit_id;
+        if (typeof kitId !== "string" || !/^[a-z][a-z0-9-]*$/.test(kitId)) {
+            errors.push(`${manifestPath}: dependencies[${index}].kit_id must be a kebab-case kit id (^[a-z][a-z0-9-]*$)`);
+            return;
+        }
+        if (ownId && kitId === ownId) {
+            errors.push(`${manifestPath}: dependencies[${index}].kit_id must not reference the declaring kit itself ('${kitId}')`);
+            return;
+        }
+        if (seen.has(kitId)) {
+            errors.push(`${manifestPath}: dependencies[${index}].kit_id duplicates '${kitId}'`);
+            return;
+        }
+        seen.add(kitId);
+        if (record.reason !== undefined && typeof record.reason !== "string") {
+            errors.push(`${manifestPath}: dependencies[${index}].reason must be a string when present`);
+        }
+        const reason = typeof record.reason === "string" ? record.reason : undefined;
+        entries.push({ kit_id: kitId, ...(reason ? { reason } : {}) });
+    });
+    return { entries, errors };
+}
 /**
  * Allowlist of kit IDs that Kontour authors, tests, and ships with the flow-agents package.
  *
@@ -106,7 +166,7 @@ export async function deriveKitTargets(manifest, kitDir = "") {
     // Detect third-party extension namespaces: top-level keys that are neither
     // core fields nor Flow Agents extension classes.
     const thirdPartyExtensions = Object.keys(manifest)
-        .filter((key) => !CORE_CONTAINER_FIELDS.has(key) && !AGENT_EXTENSION_CLASSES.has(key))
+        .filter((key) => !CORE_CONTAINER_FIELDS.has(key) && !AGENT_EXTENSION_CLASSES.has(key) && !KNOWN_METADATA_FIELDS.has(key))
         .sort();
     const targets = [];
     if (k0)
@@ -187,6 +247,12 @@ export async function validateKitRepository(kitDir) {
             }
         });
     }
+    // Flow Agents metadata: cross-kit dependency declarations (extension-layer;
+    // see docs/adr/0019-kit-dependency-ownership.md). Shape-only here — presence is
+    // checked separately (non-blocking at install, hard error at activation).
+    const depResult = parseKitDependencies(manifest, manifestPath);
+    for (const err of depResult.errors)
+        errors.push(err);
     return errors;
 }
 export async function assertKitRepository(kitDir) {

package/build/src/index.d.ts

@@ -1,4 +1,4 @@
-export { defaultArtifactRootForRead, defaultTelemetryDirForRead, defaultTelemetryDirsForRead, firstExistingPath, flowAgentsArtifactRoot, KONTOURAI_DIR, legacyFlowAgentsArtifactRoot, LEGACY_FLOW_AGENTS_DIR, legacyTelemetryDataDir, LEGACY_TELEMETRY_DIR, telemetryDataDir, } from "./lib/local-artifact-root.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. */
 export declare function readSidecar(dir: string, name: string): Record<string, any>;

package/build/src/index.js

@@ -15,7 +15,7 @@
  */
 import * as path from "node:path";
 import { loadJson as _loadJson, writeJson as _writeJson } from "./cli/workflow-sidecar.js";
-export { defaultArtifactRootForRead, defaultTelemetryDirForRead, defaultTelemetryDirsForRead, firstExistingPath, flowAgentsArtifactRoot, KONTOURAI_DIR, legacyFlowAgentsArtifactRoot, LEGACY_FLOW_AGENTS_DIR, legacyTelemetryDataDir, LEGACY_TELEMETRY_DIR, telemetryDataDir, } from "./lib/local-artifact-root.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.
 validateTrustBundle, 

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

@@ -17,11 +17,11 @@
  *
  * Returns the validated absolute file path, or null when:
  *  - kitId or flowName contains chars outside SLUG_RE (rejects traversal)
- *  - FLOW_AGENTS_FLOW_DEFS_DIR resolves into a .flow-agents directory
+ *  - 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 (points into .flow-agents), falls back silently
- * to the repoRoot/kits/ path so the resolver still works for legit flows.
+ * When the override is unsafe, it is ignored and the resolver uses the
+ * canonical repoRoot/kits/ source for legitimate flows.
  */
 export declare function resolveFlowFilePath(kitId: string, flowName: string, flowId: string, repoRoot: string): string | null;
 /** A single gate expectation from a FlowDefinition expects[] entry. */
@@ -41,6 +41,8 @@ export type ActiveFlowStep = {
     stepId: string;
     gateId: string;
     gateExpects: GateExpectation[];
+    /** When resolved through a parent step's uses_flow edge, names the child FlowDefinition that owns the gate. */
+    sourceFlowId?: string;
 };
 /**
  * Resolve the gate expects[] for a specific (flowId, stepId) pair.
@@ -76,7 +78,7 @@ export declare function resolvePhaseMap(flowId: string, repoRoot: string): Recor
  * with a fallback to process.cwd(). This handles temp dirs, CI workspaces, and
  * subproject layouts without hardcoding the repo structure.
  *
- * @param flowAgentsDir Path to the .flow-agents directory (contains current.json).
+ * @param flowAgentsDir Path to the runtime artifact root directory (contains current.json).
  * @returns ActiveFlowStep or null when fields are absent or resolution fails.
  */
 export declare function resolveActiveFlowStep(flowAgentsDir: string): ActiveFlowStep | null;

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

@@ -18,9 +18,9 @@ import * as path from "node:path";
 //
 // Both kitId and flowName originate from agent-writable sources (active_flow_id
 // in current.json, and FLOW_AGENTS_FLOW_DEFS_DIR set by the runtime). A crafted
-// value like "builder.../../../.flow-agents/slug/fake-flow" produces:
+// value like "builder.../../../.kontourai/flow-agents/slug/fake-flow" produces:
 //   kitId = "builder"
-//   flowName = "../../../.flow-agents/slug/fake-flow"
+//   flowName = "../../../.kontourai/flow-agents/slug/fake-flow"
 // which resolves OUTSIDE kits/ via path.join traversal.
 //
 // SLUG_RE closes this: it rejects any value containing path separators, dots,
@@ -32,23 +32,36 @@ import * as path from "node:path";
 /** Strict slug pattern — allows only URL-safe identifier chars. */
 const SLUG_RE = /^[a-zA-Z0-9_-]+$/;
 /**
- * Returns true when the given resolved absolute path falls within a .flow-agents
- * directory (an agent-writable area). Used to reject FLOW_AGENTS_FLOW_DEFS_DIR
+ * Returns true when the given resolved absolute path falls within a Flow Agents
+ * runtime artifact directory (an agent-writable area). Used to reject FLOW_AGENTS_FLOW_DEFS_DIR
  * overrides that point into agent-controlled storage.
  */
+function hasAgentWritableRuntimeSegment(resolvedDir) {
+    const parts = resolvedDir.split(path.sep);
+    if (parts.includes(".flow-agents"))
+        return true;
+    return parts.some((part, index) => part === ".kontourai" && parts[index + 1] === "flow-agents");
+}
 function isAgentWritableDir(resolvedDir) {
-    return resolvedDir.split(path.sep).includes(".flow-agents");
+    if (hasAgentWritableRuntimeSegment(resolvedDir))
+        return true;
+    try {
+        return hasAgentWritableRuntimeSegment(fs.realpathSync.native(resolvedDir));
+    }
+    catch {
+        return false;
+    }
 }
 /**
  * Build and validate the FlowDefinition file path.
  *
  * Returns the validated absolute file path, or null when:
  *  - kitId or flowName contains chars outside SLUG_RE (rejects traversal)
- *  - FLOW_AGENTS_FLOW_DEFS_DIR resolves into a .flow-agents directory
+ *  - 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 (points into .flow-agents), falls back silently
- * to the repoRoot/kits/ path so the resolver still works for legit flows.
+ * When the override is unsafe, it is ignored and the resolver uses the
+ * canonical repoRoot/kits/ source for legitimate flows.
  */
 export function resolveFlowFilePath(kitId, flowName, flowId, repoRoot) {
     // Primary defense: reject any slug containing traversal chars or non-identifier chars.
@@ -60,8 +73,8 @@ export function resolveFlowFilePath(kitId, flowName, flowId, repoRoot) {
     if (override) {
         const resolvedOverride = path.resolve(override);
         if (isAgentWritableDir(resolvedOverride)) {
-            // Override targets an agent-writable .flow-agents path — reject it and
-            // fall back to the kit root.  The session will resolve the real kit flow.
+            // 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`);
         }
@@ -83,7 +96,47 @@ export function resolveFlowFilePath(kitId, flowName, flowId, repoRoot) {
     if (!resolvedPath.startsWith(expectedRoot + path.sep) && resolvedPath !== expectedRoot) {
         return null; // traversal still detected — paranoid fallback
     }
-    return resolvedPath;
+    // If the file exists, resolve final symlinks before returning a readable path.
+    // `readFileSync` follows symlinks; this keeps lexical containment from turning
+    // into an out-of-root file read through a symlinked FlowDefinition.
+    try {
+        const realExpectedRoot = fs.existsSync(expectedRoot) ? fs.realpathSync.native(expectedRoot) : expectedRoot;
+        const realPath = fs.realpathSync.native(resolvedPath);
+        if (!realPath.startsWith(realExpectedRoot + path.sep) && realPath !== realExpectedRoot) {
+            return null;
+        }
+        return realPath;
+    }
+    catch {
+        return resolvedPath;
+    }
+}
+function flowIdParts(flowId) {
+    if (!flowId)
+        return null;
+    const dotIdx = flowId.indexOf(".");
+    if (dotIdx < 1)
+        return null;
+    const kitId = flowId.slice(0, dotIdx);
+    const flowName = flowId.slice(dotIdx + 1);
+    if (!kitId || !flowName)
+        return null;
+    return { kitId, flowName };
+}
+function readFlowDefinition(flowId, repoRoot) {
+    const parts = flowIdParts(flowId);
+    if (!parts)
+        return null;
+    const flowFilePath = resolveFlowFilePath(parts.kitId, parts.flowName, flowId, repoRoot);
+    if (!flowFilePath)
+        return null;
+    try {
+        const raw = fs.readFileSync(flowFilePath, "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null; // ENOENT, permission error, or parse error → fail-open
+    }
 }
 /**
  * Resolve the gate expects[] for a specific (flowId, stepId) pair.
@@ -95,41 +148,73 @@ export function resolveFlowFilePath(kitId, flowName, flowId, repoRoot) {
  * @returns ActiveFlowStep with the matched gate's expects[], or null on any error.
  */
 export function resolveFlowStep(flowId, stepId, repoRoot) {
+    const resolved = resolveFlowStepInternal(flowId, stepId, repoRoot, new Set());
+    if (!resolved)
+        return null;
+    const { flowExports: _flowExports, ...publicStep } = resolved;
+    return publicStep;
+}
+function expectationExportKeys(expectation) {
+    const keys = [];
+    if (typeof expectation.id === "string" && expectation.id)
+        keys.push(expectation.id);
+    const claimType = expectation.bundle_claim?.claimType;
+    if (typeof claimType === "string" && claimType)
+        keys.push(claimType);
+    return keys;
+}
+function exportedExpectations(expectations, exportsList) {
+    if (!Array.isArray(exportsList))
+        return null;
+    const exported = new Set(exportsList.filter((item) => typeof item === "string" && item.length > 0));
+    const allowed = expectations.filter((expectation) => expectationExportKeys(expectation).some((key) => exported.has(key)));
+    return allowed.length === expectations.length ? allowed : null;
+}
+function resolveFlowStepInternal(flowId, stepId, repoRoot, seen) {
     if (!flowId || !stepId)
         return null;
-    const dotIdx = flowId.indexOf(".");
-    if (dotIdx < 1)
-        return null; // flowId must have at least one "." to derive kitId
-    const kitId = flowId.slice(0, dotIdx);
-    // The flow filename is the part after the first "." (e.g. "build" from "builder.build")
-    const flowName = flowId.slice(dotIdx + 1);
-    if (!kitId || !flowName)
+    if (!flowIdParts(flowId))
         return null;
     // Layer 1 defense: validate stepId too — it is matched against gate.step values but
     // still originates from agent-writable current.json active_step_id.
     if (!SLUG_RE.test(stepId))
         return null;
-    // Determine the FlowDefinition file path with slug validation + path containment check.
-    // Returns null for traversal attempts (e.g. flowName = "../../../.flow-agents/fake").
-    const flowFilePath = resolveFlowFilePath(kitId, flowName, flowId, repoRoot);
-    if (!flowFilePath)
+    const seenKey = `${flowId}:${stepId}`;
+    if (seen.has(seenKey))
         return null;
-    let flowDef;
-    try {
-        const raw = fs.readFileSync(flowFilePath, "utf8");
-        flowDef = JSON.parse(raw);
-    }
-    catch {
-        return null; // ENOENT, permission error, or parse error → fail-open
-    }
-    if (!flowDef || typeof flowDef !== "object" || !flowDef.gates)
+    seen.add(seenKey);
+    const flowDef = readFlowDefinition(flowId, repoRoot);
+    if (!flowDef)
+        return null;
+    if (!flowDef || typeof flowDef !== "object")
         return null;
     // Find the gate whose .step matches stepId.
-    for (const [gateId, gate] of Object.entries(flowDef.gates)) {
-        if (!gate || gate.step !== stepId)
-            continue;
-        const expects = Array.isArray(gate.expects) ? gate.expects : [];
-        return { flowId, stepId, gateId, gateExpects: expects };
+    if (flowDef.gates) {
+        for (const [gateId, gate] of Object.entries(flowDef.gates)) {
+            if (!gate || gate.step !== stepId)
+                continue;
+            const expects = Array.isArray(gate.expects) ? gate.expects : [];
+            return { flowId, stepId, gateId, gateExpects: expects, flowExports: flowDef.exports };
+        }
+    }
+    const composedStep = Array.isArray(flowDef.steps)
+        ? flowDef.steps.find((step) => step && step.id === stepId && typeof step.uses_flow === "string" && step.uses_flow.trim())
+        : null;
+    if (composedStep?.uses_flow) {
+        const child = resolveFlowStepInternal(composedStep.uses_flow, stepId, repoRoot, seen);
+        if (child) {
+            const childGateExpects = exportedExpectations(child.gateExpects, child.flowExports);
+            if (!childGateExpects)
+                return null;
+            return {
+                flowId,
+                stepId,
+                gateId: `${child.flowId}:${child.gateId}`,
+                gateExpects: childGateExpects,
+                sourceFlowId: child.flowId,
+                flowExports: flowDef.exports,
+            };
+        }
     }
     return null; // no gate matched the given stepId
 }
@@ -148,27 +233,9 @@ export function resolveFlowStep(flowId, stepId, repoRoot) {
  * @returns Record<string,string> phase→stepId map, or null on absence/error.
  */
 export function resolvePhaseMap(flowId, repoRoot) {
-    if (!flowId)
-        return null;
-    const dotIdx = flowId.indexOf(".");
-    if (dotIdx < 1)
-        return null;
-    const kitId = flowId.slice(0, dotIdx);
-    const flowName = flowId.slice(dotIdx + 1);
-    if (!kitId || !flowName)
+    const flowDef = readFlowDefinition(flowId, repoRoot);
+    if (!flowDef)
         return null;
-    // Layer 1 defense: same slug validation + path containment as resolveFlowStep.
-    const flowFilePath = resolveFlowFilePath(kitId, flowName, flowId, repoRoot);
-    if (!flowFilePath)
-        return null;
-    let flowDef;
-    try {
-        const raw = fs.readFileSync(flowFilePath, "utf8");
-        flowDef = JSON.parse(raw);
-    }
-    catch {
-        return null; // ENOENT, permission error, or parse error → fail-open
-    }
     if (!flowDef || typeof flowDef !== "object")
         return null;
     const pm = flowDef.phase_map;
@@ -186,7 +253,7 @@ export function resolvePhaseMap(flowId, repoRoot) {
  * the nearest ancestor that contains a `kits/` subdirectory. If none is found,
  * falls back to `process.cwd()` so the default "run from repo root" case still works.
  *
- * This is required because the .flow-agents directory can live anywhere (temp dirs,
+ * This is required because the runtime artifact directory can live anywhere (temp dirs,
  * subprojects, CI workspaces) while the kits/ directory is always at the repo root.
  */
 function findRepoRoot(startDir) {
@@ -212,7 +279,7 @@ function findRepoRoot(startDir) {
  * with a fallback to process.cwd(). This handles temp dirs, CI workspaces, and
  * subproject layouts without hardcoding the repo structure.
  *
- * @param flowAgentsDir Path to the .flow-agents directory (contains current.json).
+ * @param flowAgentsDir Path to the runtime artifact root directory (contains current.json).
  * @returns ActiveFlowStep or null when fields are absent or resolution fails.
  */
 export function resolveActiveFlowStep(flowAgentsDir) {

package/build/src/lib/local-artifact-root.d.ts

@@ -1,8 +1,20 @@
 export declare const KONTOURAI_DIR = ".kontourai";
-export declare const LEGACY_FLOW_AGENTS_DIR = ".flow-agents";
+export declare const FLOW_AGENTS_RUNTIME_SUBDIR = "flow-agents";
+export declare const FLOW_AGENTS_RUNTIME_DIR = ".kontourai/flow-agents";
+export declare const DURABLE_FLOW_AGENTS_DIR = ".flow-agents";
 export declare const LEGACY_TELEMETRY_DIR = ".telemetry";
+/**
+ * Default Codex home: `$CODEX_HOME` when set, else `~/.codex`.
+ *
+ * This is the Codex CLI's own config/state root and is conceptually
+ * distinct from the Flow Agents global bundle install root (`~/.flow-agents`)
+ * and the durable per-destination install record root
+ * (`DURABLE_FLOW_AGENTS_DIR`, i.e. `.flow-agents`).
+ */
+export declare function defaultCodexHome(): string;
 export declare function flowAgentsArtifactRoot(cwd?: string): string;
-export declare function legacyFlowAgentsArtifactRoot(cwd?: string): string;
+export declare function durableFlowAgentsRoot(cwd?: string): string;
+export declare function durableInstallRecordPath(cwd?: string): string;
 export declare function telemetryDataDir(cwd?: string): string;
 export declare function legacyTelemetryDataDir(cwd?: string): string;
 export declare function firstExistingPath(candidates: string[]): string;

package/build/src/lib/local-artifact-root.js

@@ -1,13 +1,30 @@
 import * as fs from "node:fs";
+import * as os from "node:os";
 import * as path from "node:path";
 export const KONTOURAI_DIR = ".kontourai";
-export const LEGACY_FLOW_AGENTS_DIR = ".flow-agents";
+export const FLOW_AGENTS_RUNTIME_SUBDIR = "flow-agents";
+export const FLOW_AGENTS_RUNTIME_DIR = `${KONTOURAI_DIR}/${FLOW_AGENTS_RUNTIME_SUBDIR}`;
+export const DURABLE_FLOW_AGENTS_DIR = ".flow-agents";
 export const LEGACY_TELEMETRY_DIR = ".telemetry";
+/**
+ * Default Codex home: `$CODEX_HOME` when set, else `~/.codex`.
+ *
+ * This is the Codex CLI's own config/state root and is conceptually
+ * distinct from the Flow Agents global bundle install root (`~/.flow-agents`)
+ * and the durable per-destination install record root
+ * (`DURABLE_FLOW_AGENTS_DIR`, i.e. `.flow-agents`).
+ */
+export function defaultCodexHome() {
+    return process.env["CODEX_HOME"] || path.join(os.homedir(), ".codex");
+}
 export function flowAgentsArtifactRoot(cwd = process.cwd()) {
-    return path.resolve(cwd, KONTOURAI_DIR, "flow-agents");
+    return path.resolve(cwd, FLOW_AGENTS_RUNTIME_DIR);
+}
+export function durableFlowAgentsRoot(cwd = process.cwd()) {
+    return path.resolve(cwd, DURABLE_FLOW_AGENTS_DIR);
 }
-export function legacyFlowAgentsArtifactRoot(cwd = process.cwd()) {
-    return path.resolve(cwd, LEGACY_FLOW_AGENTS_DIR);
+export function durableInstallRecordPath(cwd = process.cwd()) {
+    return path.join(durableFlowAgentsRoot(cwd), "install.json");
 }
 export function telemetryDataDir(cwd = process.cwd()) {
     return path.resolve(cwd, KONTOURAI_DIR, "telemetry");
@@ -19,7 +36,7 @@ export function firstExistingPath(candidates) {
     return candidates.find((candidate) => fs.existsSync(candidate)) ?? candidates[0];
 }
 export function defaultArtifactRootForRead(cwd = process.cwd()) {
-    return firstExistingPath([flowAgentsArtifactRoot(cwd), legacyFlowAgentsArtifactRoot(cwd)]);
+    return flowAgentsArtifactRoot(cwd);
 }
 export function defaultTelemetryDirForRead(cwd = process.cwd()) {
     return firstExistingPath([telemetryDataDir(cwd), legacyTelemetryDataDir(cwd)]);

package/build/src/lib/workflow-learning-projection.js

@@ -26,7 +26,7 @@ const KNOWN_CORRECTION_TYPES = new Set([
     "provider",
     "none",
 ]);
-const SKIPPED_ROOT_ENTRIES = new Set(["archive", "changes", "delivery-history"]);
+const SKIPPED_ROOT_ENTRIES = new Set(["archive", "changes", "delivery-history", "liveness"]);
 const MAX_SIDECAR_BYTES = 1024 * 1024;
 export function readWorkflowLearningSources(artifactRoot) {
     const root = path.resolve(artifactRoot);
@@ -75,7 +75,7 @@ export function buildWorkflowLearningProjection(sources, options) {
                 sourceRef: {
                     product: "flow-agents",
                     kind: "workflow-learning",
-                    id: ".flow-agents/*/learning.json",
+                    id: ".kontourai/flow-agents/*/learning.json",
                     label: "Local workflow learning sidecars",
                 },
             },

package/build/src/runtime-adapters.d.ts

@@ -13,6 +13,18 @@ export type KitInventory = {
     warnings: string[];
     errors: string[];
 };
+/** A cross-kit dependency edge discovered while loading a kit manifest. */
+export type KitDependencyRef = {
+    from_kit_id: string;
+    kit_id: string;
+    reason?: string;
+};
+/** The parsed result of a single kit manifest: its id, activatable assets, and declared dependencies. */
+export type LoadedKit = {
+    kit_id: string;
+    assets: KitAsset[];
+    dependencies: KitDependencyRef[];
+};
 export declare function readKitInventory(sourceRoot: string, dest: string): KitInventory;
 export declare function activateCodexLocal(sourceRoot: string, dest: string): Record<string, unknown>;
 export declare function activateStrandsLocal(sourceRoot: string, dest: string): Record<string, unknown>;