@kontourai/flow-agents 3.3.0 → 3.4.0

package/build/src/lib/fs.js

@@ -1,5 +1,6 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
+import * as crypto from "node:crypto";
 export function readJson(file) {
     return JSON.parse(fs.readFileSync(file, "utf8"));
 }
@@ -7,6 +8,123 @@ export function writeJson(file, value) {
     fs.mkdirSync(path.dirname(file), { recursive: true });
     fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`, "utf8");
 }
+function existingAncestor(file) {
+    let current = path.resolve(file);
+    const missing = [];
+    while (!fs.existsSync(current)) {
+        missing.unshift(path.basename(current));
+        const parent = path.dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return { ancestor: current, missing };
+}
+/** Resolve a possibly-missing path through its nearest existing ancestor. */
+export function canonicalProspectivePath(file) {
+    const { ancestor, missing } = existingAncestor(file);
+    return path.resolve(fs.realpathSync(ancestor), ...missing);
+}
+function isContained(root, target) {
+    const relative = path.relative(root, target);
+    return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+/** Reject equality and either-direction containment after canonical resolution. */
+export function assertPathsDisjoint(first, second) {
+    const firstReal = canonicalProspectivePath(first);
+    const secondReal = canonicalProspectivePath(second);
+    if (isContained(firstReal, secondReal) || isContained(secondReal, firstReal)) {
+        throw new Error(`refusing overlapping paths: ${firstReal} and ${secondReal}`);
+    }
+}
+/**
+ * Create a directory below root without following any symlink that already
+ * exists at or below the root. Ambient aliases above root (for example macOS
+ * /tmp -> /private/tmp) are resolved once and are not treated as destination
+ * components.
+ */
+export function ensureSafeDirectory(root, directory) {
+    const rootPath = path.resolve(root);
+    if (fs.existsSync(rootPath)) {
+        const rootStat = fs.lstatSync(rootPath);
+        if (rootStat.isSymbolicLink())
+            throw new Error(`refusing symlink destination root: ${rootPath}`);
+        if (!rootStat.isDirectory())
+            throw new Error(`destination root is not a directory: ${rootPath}`);
+    }
+    else {
+        const { ancestor, missing } = existingAncestor(rootPath);
+        let current = fs.realpathSync(ancestor);
+        for (const part of missing) {
+            current = path.join(current, part);
+            if (fs.existsSync(current)) {
+                const stat = fs.lstatSync(current);
+                if (stat.isSymbolicLink())
+                    throw new Error(`refusing to write through symlink: ${current}`);
+                if (!stat.isDirectory())
+                    throw new Error(`destination component is not a directory: ${current}`);
+            }
+            else {
+                fs.mkdirSync(current);
+            }
+        }
+    }
+    const rootReal = fs.realpathSync(rootPath);
+    const target = path.resolve(directory);
+    const prospective = canonicalProspectivePath(target);
+    if (!isContained(rootReal, prospective))
+        throw new Error(`path escapes root: ${target}`);
+    const relative = path.relative(rootReal, prospective);
+    let current = rootReal;
+    for (const part of relative.split(path.sep).filter(Boolean)) {
+        current = path.join(current, part);
+        if (fs.existsSync(current)) {
+            const stat = fs.lstatSync(current);
+            if (stat.isSymbolicLink())
+                throw new Error(`refusing to write through symlink: ${current}`);
+            if (!stat.isDirectory())
+                throw new Error(`destination component is not a directory: ${current}`);
+        }
+        else {
+            fs.mkdirSync(current);
+        }
+    }
+    return prospective;
+}
+function assertSafeFileTarget(root, file) {
+    const target = path.resolve(file);
+    ensureSafeDirectory(root, path.dirname(target));
+    const rootReal = fs.realpathSync(path.resolve(root));
+    const prospective = canonicalProspectivePath(target);
+    if (!isContained(rootReal, prospective) || prospective === rootReal)
+        throw new Error(`path escapes root: ${target}`);
+    if (fs.existsSync(target)) {
+        const stat = fs.lstatSync(target);
+        if (stat.isSymbolicLink())
+            throw new Error(`refusing to replace symlink: ${target}`);
+        if (!stat.isFile())
+            throw new Error(`destination is not a regular file: ${target}`);
+    }
+    return target;
+}
+/** Atomically replace a regular file without following a final-component symlink. */
+export function atomicWriteFile(root, file, data) {
+    const target = assertSafeFileTarget(root, file);
+    const temp = path.join(path.dirname(target), `.${path.basename(target)}.flow-agents-${process.pid}-${crypto.randomBytes(6).toString("hex")}.tmp`);
+    try {
+        fs.writeFileSync(temp, data, { flag: "wx" });
+        fs.renameSync(temp, target);
+    }
+    finally {
+        fs.rmSync(temp, { force: true });
+    }
+}
+export function atomicWriteJson(root, file, value) {
+    atomicWriteFile(root, file, `${JSON.stringify(value, null, 2)}\n`);
+}
+export function atomicCopyFile(root, source, target) {
+    atomicWriteFile(root, target, fs.readFileSync(source));
+}
 export function copyDir(src, dest) {
     fs.mkdirSync(path.dirname(dest), { recursive: true });
     if (fs.existsSync(dest))
@@ -16,6 +134,60 @@ export function copyDir(src, dest) {
         filter: (source) => !source.split(path.sep).some((part) => [".git", "__pycache__", ".pytest_cache"].includes(part)),
     });
 }
+function copiedTreeDigest(root) {
+    const hash = crypto.createHash("sha256");
+    for (const file of walkFiles(root)) {
+        const rel = path.relative(root, 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 hash.digest("hex");
+}
+/** Copy through a verified sibling directory, then swap with rollback. */
+export function copyDirAtomic(root, src, dest) {
+    assertPathsDisjoint(src, dest);
+    const parent = ensureSafeDirectory(root, path.dirname(dest));
+    if (fs.existsSync(dest)) {
+        const stat = fs.lstatSync(dest);
+        if (stat.isSymbolicLink())
+            throw new Error(`refusing to replace symlink: ${dest}`);
+        if (!stat.isDirectory())
+            throw new Error(`destination is not a directory: ${dest}`);
+    }
+    const nonce = `${process.pid}-${crypto.randomBytes(6).toString("hex")}`;
+    const temp = path.join(parent, `.${path.basename(dest)}.flow-agents-${nonce}.tmp`);
+    const backup = path.join(parent, `.${path.basename(dest)}.flow-agents-${nonce}.old`);
+    try {
+        fs.cpSync(src, temp, {
+            recursive: true,
+            errorOnExist: true,
+            force: false,
+            filter: (source) => !source.split(path.sep).some((part) => [".git", "__pycache__", ".pytest_cache"].includes(part)),
+        });
+        if (copiedTreeDigest(src) !== copiedTreeDigest(temp))
+            throw new Error(`copied kit verification failed: ${src}`);
+        if (fs.existsSync(dest))
+            fs.renameSync(dest, backup);
+        try {
+            fs.renameSync(temp, dest);
+        }
+        catch (error) {
+            if (fs.existsSync(backup))
+                fs.renameSync(backup, dest);
+            throw error;
+        }
+        fs.rmSync(backup, { recursive: true, force: true });
+    }
+    finally {
+        fs.rmSync(temp, { recursive: true, force: true });
+        if (fs.existsSync(backup) && !fs.existsSync(dest))
+            fs.renameSync(backup, dest);
+    }
+}
 export function assertPathContained(root, target) {
     const rootReal = fs.realpathSync(root);
     let existingParent = path.dirname(target);

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

@@ -11,10 +11,53 @@ export declare const LEGACY_TELEMETRY_DIR = ".telemetry";
  * and the durable per-destination install record root
  * (`DURABLE_FLOW_AGENTS_DIR`, i.e. `.flow-agents`).
  */
-export declare function defaultCodexHome(): string;
+export declare function defaultCodexHome(env?: NodeJS.ProcessEnv, homedir?: string): string;
+/**
+ * #357: resolve the SHARED, git-common-dir-anchored `.kontourai/flow-agents` root for `cwd`.
+ *
+ * `git rev-parse --git-common-dir` returns the ONE `.git` directory shared by every worktree
+ * of a repository (in the primary checkout this is simply `.git` relative to cwd; in a linked
+ * worktree it resolves to the primary checkout's real `.git` directory, e.g.
+ * `/path/to/primary/.git`, NOT the worktree's own `.git` file). Taking `path.dirname()` of that
+ * resolved, absolute path yields the primary checkout's repo root — the one location every
+ * worktree of the same repo should treat as the shared `.kontourai/flow-agents` store, so a
+ * `liveness claim` or `ensure-session` invoked from ANY worktree's cwd is visible to a reader
+ * in any other checkout of the same repo (including the primary one).
+ *
+ * Returns null (never throws) when git is unavailable, `cwd` is not inside a git working tree,
+ * or the command otherwise fails — callers MUST fail open to the existing cwd-based
+ * `path.resolve(cwd, FLOW_AGENTS_RUNTIME_DIR)` behavior in that case (see flowAgentsArtifactRoot
+ * below), which is also exactly what happens today in the single-checkout case: there,
+ * `--git-common-dir` resolves to `.git` under cwd itself, so `path.dirname()` of its absolute
+ * form is cwd — byte-identical to today's plain `path.resolve(cwd, ...)` result.
+ *
+ * #413 iteration-2 Fix 3: strips the ambient GIT_DIR/GIT_COMMON_DIR/GIT_WORK_TREE/
+ * GIT_CEILING_DIRECTORIES env vars before shelling out. Any of these, if set in the calling
+ * process's environment (e.g. leaked from an outer `git rebase`/hook invocation, or a stray
+ * export in a dev shell), can silently redirect `--git-common-dir` to resolve a DIFFERENT
+ * repository's `.git` than the one `cwd` is actually inside — which would silently redirect
+ * the shared `.kontourai/flow-agents` store to that other repo. Passing an explicit env with
+ * those keys deleted makes resolution depend only on `cwd`, never on ambient process state.
+ */
+export declare function resolveSharedRepoRoot(cwd: string): string | null;
+/**
+ * #413 iteration-2 Fix 2 (documentation only, no behavior change): when `cwd` is a
+ * SUBDIRECTORY of a plain (non-worktree) checkout, `git rev-parse --git-common-dir` returns a
+ * RELATIVE path (e.g. `../.git` or deeper) that `resolveSharedRepoRoot` walks up to the repo
+ * root — so this intentionally resolves to `<repo-root>/.kontourai/flow-agents` regardless of
+ * which subdirectory `cwd` is, NOT `<subdir>/.kontourai/flow-agents` (the old plain
+ * `path.resolve(cwd, ...)` cwd-anchored behavior). This is the CORRECT shared-store semantics —
+ * one store per repo, matching every other cwd (primary checkout, linked worktree) this
+ * resolver already unifies — not a regression to guard against. See
+ * evals/integration/test_liveness_worktree_root.sh's AC6b for the explicit assertion, and its
+ * header docstring for why AC6's "byte-identical" guarantee is scoped to repo-root cwd and
+ * non-git cwd only, never to an arbitrary subdirectory cwd.
+ */
 export declare function flowAgentsArtifactRoot(cwd?: string): string;
 export declare function durableFlowAgentsRoot(cwd?: string): string;
 export declare function durableInstallRecordPath(cwd?: string): string;
+/** Path to the per-skill-file content-hash drift manifest, a sibling of `install.json` under the same durable root. */
+export declare function skillsManifestPath(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,6 +1,7 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import { execFileSync } from "node:child_process";
 export const KONTOURAI_DIR = ".kontourai";
 export const FLOW_AGENTS_RUNTIME_SUBDIR = "flow-agents";
 export const FLOW_AGENTS_RUNTIME_DIR = `${KONTOURAI_DIR}/${FLOW_AGENTS_RUNTIME_SUBDIR}`;
@@ -14,11 +15,134 @@ export const LEGACY_TELEMETRY_DIR = ".telemetry";
  * 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 defaultCodexHome(env = process.env, homedir = os.homedir()) {
+    return env["CODEX_HOME"] || path.join(homedir, ".codex");
 }
+/**
+ * #357: resolve the SHARED, git-common-dir-anchored `.kontourai/flow-agents` root for `cwd`.
+ *
+ * `git rev-parse --git-common-dir` returns the ONE `.git` directory shared by every worktree
+ * of a repository (in the primary checkout this is simply `.git` relative to cwd; in a linked
+ * worktree it resolves to the primary checkout's real `.git` directory, e.g.
+ * `/path/to/primary/.git`, NOT the worktree's own `.git` file). Taking `path.dirname()` of that
+ * resolved, absolute path yields the primary checkout's repo root — the one location every
+ * worktree of the same repo should treat as the shared `.kontourai/flow-agents` store, so a
+ * `liveness claim` or `ensure-session` invoked from ANY worktree's cwd is visible to a reader
+ * in any other checkout of the same repo (including the primary one).
+ *
+ * Returns null (never throws) when git is unavailable, `cwd` is not inside a git working tree,
+ * or the command otherwise fails — callers MUST fail open to the existing cwd-based
+ * `path.resolve(cwd, FLOW_AGENTS_RUNTIME_DIR)` behavior in that case (see flowAgentsArtifactRoot
+ * below), which is also exactly what happens today in the single-checkout case: there,
+ * `--git-common-dir` resolves to `.git` under cwd itself, so `path.dirname()` of its absolute
+ * form is cwd — byte-identical to today's plain `path.resolve(cwd, ...)` result.
+ *
+ * #413 iteration-2 Fix 3: strips the ambient GIT_DIR/GIT_COMMON_DIR/GIT_WORK_TREE/
+ * GIT_CEILING_DIRECTORIES env vars before shelling out. Any of these, if set in the calling
+ * process's environment (e.g. leaked from an outer `git rebase`/hook invocation, or a stray
+ * export in a dev shell), can silently redirect `--git-common-dir` to resolve a DIFFERENT
+ * repository's `.git` than the one `cwd` is actually inside — which would silently redirect
+ * the shared `.kontourai/flow-agents` store to that other repo. Passing an explicit env with
+ * those keys deleted makes resolution depend only on `cwd`, never on ambient process state.
+ */
+export function resolveSharedRepoRoot(cwd) {
+    try {
+        const env = { ...process.env };
+        delete env["GIT_DIR"];
+        delete env["GIT_COMMON_DIR"];
+        delete env["GIT_WORK_TREE"];
+        delete env["GIT_CEILING_DIRECTORIES"];
+        const out = execFileSync("git", ["rev-parse", "--git-common-dir"], {
+            cwd,
+            env,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        if (!out)
+            return null;
+        const absoluteCommonDir = path.resolve(cwd, out);
+        return path.dirname(absoluteCommonDir);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * #413 iteration-2 Fix 1: cheap discriminator for the loud-vs-silent fail-open decision below.
+ * Walks up from `cwd` (bounded, same 40-level cap the hook-side ancestor walks use) looking for
+ * a `.git` entry — a FILE (linked worktree's gitdir pointer) or a DIRECTORY (primary checkout) —
+ * without shelling out to git at all, so it stays meaningful even when git itself is the thing
+ * that's broken/absent. Never throws; a filesystem error at any level is treated as "no .git
+ * found here", not as a crash.
+ */
+function isInsideGitWorkingTree(cwd) {
+    try {
+        let dir = path.resolve(cwd);
+        const root = path.parse(dir).root;
+        for (let depth = 0; depth < 40; depth++) {
+            if (fs.existsSync(path.join(dir, ".git")))
+                return true;
+            if (dir === root)
+                break;
+            const parent = path.dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+        return false;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * #413 iteration-2 Fix 1 (HIGH, security): emit a LOUD stderr warning before falling open, but
+ * ONLY when `cwd` is genuinely inside a git working tree (per isInsideGitWorkingTree above) AND
+ * resolveSharedRepoRoot still returned null — i.e. git resolution was ATTEMPTED and FAILED, not
+ * merely "there was no git repo to resolve in the first place". That second, benign case (a
+ * scratch dir, a non-git cwd) must stay perfectly silent — this is exactly what
+ * evals/integration/test_liveness_worktree_root.sh's AC6 companion case (no git at all) already
+ * asserts, and it must remain byte-identical to today.
+ *
+ * The loud case (corrupted gitlink, bad GIT_DIR-in-cwd's-own-config, git binary missing, a
+ * permissions error on .git, etc.) is #357's exact silent-fail-open bug: an actor's
+ * liveness/ownership claim lands in an ISOLATED cwd-local store invisible to every other
+ * worktree/checkout of the same repo, with no diagnostic at all. A warning (not a hard refuse —
+ * this helper sits on read paths too, and a degraded read must still return something usable)
+ * gives an operator the signal needed to pass `--artifact-root` explicitly instead of silently
+ * losing coordination visibility.
+ */
+function warnIfFailingOpenInsideGitTree(cwd, fallbackPath) {
+    if (!isInsideGitWorkingTree(cwd))
+        return;
+    process.stderr.write(`[artifact-root] WARNING: inside a git working tree but could not resolve the shared repo root ` +
+        `(git rev-parse --git-common-dir failed or returned nothing from ${cwd}); falling back to a ` +
+        `cwd-local store at ${fallbackPath} — coordination claims may be invisible to other ` +
+        `worktrees/actors. Pass --artifact-root explicitly to fix.\n`);
+}
+/**
+ * #413 iteration-2 Fix 2 (documentation only, no behavior change): when `cwd` is a
+ * SUBDIRECTORY of a plain (non-worktree) checkout, `git rev-parse --git-common-dir` returns a
+ * RELATIVE path (e.g. `../.git` or deeper) that `resolveSharedRepoRoot` walks up to the repo
+ * root — so this intentionally resolves to `<repo-root>/.kontourai/flow-agents` regardless of
+ * which subdirectory `cwd` is, NOT `<subdir>/.kontourai/flow-agents` (the old plain
+ * `path.resolve(cwd, ...)` cwd-anchored behavior). This is the CORRECT shared-store semantics —
+ * one store per repo, matching every other cwd (primary checkout, linked worktree) this
+ * resolver already unifies — not a regression to guard against. See
+ * evals/integration/test_liveness_worktree_root.sh's AC6b for the explicit assertion, and its
+ * header docstring for why AC6's "byte-identical" guarantee is scoped to repo-root cwd and
+ * non-git cwd only, never to an arbitrary subdirectory cwd.
+ */
 export function flowAgentsArtifactRoot(cwd = process.cwd()) {
-    return path.resolve(cwd, FLOW_AGENTS_RUNTIME_DIR);
+    const sharedRepoRoot = resolveSharedRepoRoot(cwd);
+    if (sharedRepoRoot)
+        return path.resolve(sharedRepoRoot, FLOW_AGENTS_RUNTIME_DIR);
+    // Fail-open: not a git repo, git unavailable, or command failed — reproduce today's plain
+    // cwd-based behavior unchanged (AC6 backward-compat guarantee). #413 iteration-2 Fix 1: loud,
+    // not silent, when cwd IS inside a git working tree (see warnIfFailingOpenInsideGitTree).
+    const fallback = path.resolve(cwd, FLOW_AGENTS_RUNTIME_DIR);
+    warnIfFailingOpenInsideGitTree(cwd, fallback);
+    return fallback;
 }
 export function durableFlowAgentsRoot(cwd = process.cwd()) {
     return path.resolve(cwd, DURABLE_FLOW_AGENTS_DIR);
@@ -26,6 +150,10 @@ export function durableFlowAgentsRoot(cwd = process.cwd()) {
 export function durableInstallRecordPath(cwd = process.cwd()) {
     return path.join(durableFlowAgentsRoot(cwd), "install.json");
 }
+/** Path to the per-skill-file content-hash drift manifest, a sibling of `install.json` under the same durable root. */
+export function skillsManifestPath(cwd = process.cwd()) {
+    return path.join(durableFlowAgentsRoot(cwd), "skills-manifest.json");
+}
 export function telemetryDataDir(cwd = process.cwd()) {
     return path.resolve(cwd, KONTOURAI_DIR, "telemetry");
 }

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

@@ -8,8 +8,36 @@ export type KitAsset = {
     source_kind: string;
     description?: string;
 };
+export type KitWorkflowTriggerRef = {
+    kit_id: string;
+    source_kind: string;
+    id: string;
+    when: string;
+    target_flow_id?: string;
+    default_skill?: string;
+    conditional_skills?: {
+        when: string;
+        skill: string;
+    }[];
+    required_sequence?: string[];
+    post_verify_targets?: string[];
+};
+export type KitHookInfluenceExpectationRef = {
+    kit_id: string;
+    source_kind: string;
+    id: string;
+    description: string;
+    tier: string;
+    hook?: string;
+    event?: string;
+    must_include_guidance: string[];
+    must_include_actions: string[];
+};
 export type KitInventory = {
     assets: KitAsset[];
+    dependencies: KitDependencyRef[];
+    workflow_triggers: KitWorkflowTriggerRef[];
+    hook_influence_expectations: KitHookInfluenceExpectationRef[];
     warnings: string[];
     errors: string[];
 };
@@ -24,7 +52,15 @@ export type LoadedKit = {
     kit_id: string;
     assets: KitAsset[];
     dependencies: KitDependencyRef[];
+    workflow_triggers: KitWorkflowTriggerRef[];
+    hook_influence_expectations: KitHookInfluenceExpectationRef[];
 };
-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>;
+export declare function readKitInventory(sourceRoot: string, dest: string, options?: {
+    kitIdFilter?: string[];
+}): KitInventory;
+export declare function activateCodexLocal(sourceRoot: string, dest: string, options?: {
+    kitIdFilter?: string[];
+}): Record<string, unknown>;
+export declare function activateStrandsLocal(sourceRoot: string, dest: string, options?: {
+    kitIdFilter?: string[];
+}): Record<string, unknown>;