@kontourai/flow-agents 0.1.2 → 0.3.0

package/build/src/cli/init.js

@@ -13,12 +13,67 @@ const runtimeBundles = {
     codex: "codex",
     "claude-code": "claude-code",
     kiro: "kiro",
+    opencode: "opencode",
+    pi: "pi",
 };
+// Stable marker present in every Flow Agents claude-code hook command.
+// Used by scope-collision detection to identify an existing flow-agents install.
+// Marker must be distinctive to Flow Agents generated settings. Sibling
+// products from the same lineage ship identically named hook scripts such
+// as claude-hook-adapter.js, so script filenames are NOT a safe marker.
+export const COLLISION_MARKER = "Recording Flow Agents telemetry";
+/**
+ * Check whether a user-level Claude Code settings file already contains
+ * Flow Agents hook commands. If it does, print a WARNING explaining that
+ * Claude Code merges user-level and project-level settings and runs ALL
+ * matching hooks, so having flow-agents in both places causes duplicate
+ * hook execution (double telemetry, double policy enforcement).
+ *
+ * The check does NOT block the install; it is advisory only.
+ *
+ * @param userSettingsFile Path to inspect (defaults to $HOME/.claude/settings.json;
+ *   overridable via FLOW_AGENTS_USER_CLAUDE_SETTINGS env var for testability).
+ * @returns true if a collision was detected, false otherwise.
+ */
+export function checkScopeCollision(userSettingsFile) {
+    const filePath = userSettingsFile
+        ?? process.env["FLOW_AGENTS_USER_CLAUDE_SETTINGS"]
+        ?? path.join(os.homedir(), ".claude", "settings.json");
+    if (!fs.existsSync(filePath))
+        return false;
+    let text;
+    try {
+        text = fs.readFileSync(filePath, "utf8");
+    }
+    catch {
+        return false;
+    }
+    if (!text.includes(COLLISION_MARKER))
+        return false;
+    console.warn(`\nWARNING: Flow Agents scope collision detected.\n` +
+        `  ${filePath}\n` +
+        `already contains Flow Agents hook commands (marker: ${COLLISION_MARKER}).\n` +
+        `\n` +
+        `Claude Code merges user-level (~/.claude/settings.json) and project-level\n` +
+        `(.claude/settings.json) settings, then runs ALL matching hooks from both files.\n` +
+        `Installing Flow Agents at the project level while it is also present at the\n` +
+        `user level will cause duplicate hook execution: telemetry events are recorded\n` +
+        `twice and policy hooks (workflow-steering, config-protection, quality-gate,\n` +
+        `stop-goal-fit) run twice per event.\n` +
+        `\n` +
+        `To resolve:\n` +
+        `  - Remove the hooks section from ${filePath} and rely solely on the\n` +
+        `    project-level .claude/settings.json installed by flow-agents init, OR\n` +
+        `  - Remove the project-level install and keep only the user-level one.\n` +
+        `\n` +
+        `The install will continue; resolve the collision before running Claude Code.\n`);
+    return true;
+}
 function usage() {
     console.error(`usage: flow-agents init [options]
 
 Options:
-  --runtime base|codex|claude-code|kiro
+  --runtime base|codex|claude-code|kiro|opencode|pi
   --dest PATH
   --telemetry-sink local-files|local-kontour-console|kontour-hosted-console|user-hosted-console
   --console-url URL
@@ -35,9 +90,9 @@ function normalizeRuntime(value) {
         return undefined;
     if (value === "claude")
         return "claude-code";
-    if (value === "base" || value === "codex" || value === "claude-code" || value === "kiro")
+    if (value === "base" || value === "codex" || value === "claude-code" || value === "kiro" || value === "opencode" || value === "pi")
         return value;
-    throw new Error(`unknown runtime '${value}'; expected base, codex, claude-code, or kiro`);
+    throw new Error(`unknown runtime '${value}'; expected base, codex, claude-code, kiro, opencode, or pi`);
 }
 function normalizeTelemetrySink(value) {
     if (value === "local-files" || value === "local-kontour-console" || value === "kontour-hosted-console" || value === "user-hosted-console" || value === "kontour-cloud" || value === "hosted-kontour-console")
@@ -67,7 +122,7 @@ async function questionHidden(prompt) {
         let value = "";
         const onData = (buffer) => {
             const text = buffer.toString("utf8");
-            if (text === "\u0003") {
+            if (text === "") {
                 stdout.write("\n");
                 process.exit(130);
             }
@@ -78,7 +133,7 @@ async function questionHidden(prompt) {
                 resolve(value);
                 return;
             }
-            if (text === "\u007f") {
+            if (text === "") {
                 value = value.slice(0, -1);
                 return;
             }
@@ -224,6 +279,18 @@ export async function main(argv = process.argv.slice(2)) {
     const headless = argv.includes("--yes") || argv.includes("--headless") || !process.stdin.isTTY;
     try {
         const options = headless ? headlessOptions(argv) : await interactiveOptions(argv);
+        // Scope-collision check for claude-code: Claude Code merges user-level
+        // (~/.claude/settings.json) and project-level (.claude/settings.json) settings
+        // and runs ALL matching hooks from both files. If a user-level settings file
+        // already contains flow-agents hooks, installing at the project level will
+        // cause duplicate hook execution. We warn but do not block.
+        //
+        // Codex note: Codex hooks live in .codex/hooks.json (project-level only).
+        // There is no well-known user-level codex hooks file in our install paths,
+        // so no collision check is needed for codex.
+        if (options.runtime === "claude-code") {
+            checkScopeCollision();
+        }
         const bundle = ensureBundle(options.runtime);
         const installed = installBundle(bundle, options);
         if (installed !== 0)
@@ -235,5 +302,148 @@ export async function main(argv = process.argv.slice(2)) {
         return 2;
     }
 }
+// ---------------------------------------------------------------------------
+// Dogfood subcommand
+//
+// `flow-agents dogfood --runtime claude-code [--dest PATH]`
+//
+// Writes only the hook-wiring artifacts for the specified runtime into the
+// target directory (default: cwd). Unlike a full install, dogfood:
+//   - Does NOT rsync the full bundle (no agents/skills duplication).
+//   - Reads the generated settings/config from dist/<runtime>/ so the output
+//     cannot drift from what the bundle generates (DRY guarantee).
+//   - For claude-code: OMITS permissions.defaultMode and
+//     skipDangerousModePermissionPrompt (permissive defaults are for installed
+//     workspaces, not source repos).
+//   - Runs the same scope-collision warning as init.
+// ---------------------------------------------------------------------------
+function dogfoodUsage() {
+    console.error(`usage: flow-agents dogfood [options]
+
+Options:
+  --runtime claude-code|codex|opencode|pi   (required)
+  --dest PATH                               (default: cwd)
+  --yes, --headless
+`);
+}
+function normalizeDogfoodRuntime(value) {
+    if (!value)
+        return undefined;
+    if (value === "claude" || value === "claude-code")
+        return "claude-code";
+    if (value === "codex" || value === "opencode" || value === "pi")
+        return value;
+    throw new Error(`dogfood: unsupported runtime '${value}'; expected claude-code, codex, opencode, or pi`);
+}
+/**
+ * Write the claude-code hook-wiring artifacts into dest.
+ * Reads dist/claude-code/.claude/settings.json (generated by build-bundles),
+ * strips the permissive-mode permission keys (defaultMode, skipDangerousModePermissionPrompt),
+ * and writes .claude/settings.json to dest.
+ */
+function dogfoodClaudeCode(bundleRoot, dest) {
+    const sourcePath = path.join(bundleRoot, ".claude", "settings.json");
+    if (!fs.existsSync(sourcePath))
+        throw new Error(`dogfood: bundle settings missing: ${sourcePath}`);
+    const settings = JSON.parse(fs.readFileSync(sourcePath, "utf8"));
+    // Remove permissive defaults that are only appropriate for installed workspaces.
+    // These keys must not be present in the source repo's .claude/settings.json.
+    delete settings["permissions"];
+    delete settings["skipDangerousModePermissionPrompt"];
+    const outDir = path.join(dest, ".claude");
+    fs.mkdirSync(outDir, { recursive: true });
+    fs.writeFileSync(path.join(outDir, "settings.json"), `${JSON.stringify(settings, null, 2)}\n`, "utf8");
+}
+/**
+ * Write the codex hook-wiring artifacts into dest.
+ * Reads dist/codex/.codex/hooks.json and writes .codex/hooks.json to dest.
+ * The monolithic .codex/config.toml is not written here because it contains
+ * workspace settings (approvals_reviewer, features) that would override the
+ * developer's existing codex configuration. Only the hooks file is written.
+ */
+function dogfoodCodex(bundleRoot, dest) {
+    const sourcePath = path.join(bundleRoot, ".codex", "hooks.json");
+    if (!fs.existsSync(sourcePath))
+        throw new Error(`dogfood: bundle hooks.json missing: ${sourcePath}`);
+    const hooks = fs.readFileSync(sourcePath, "utf8");
+    const outDir = path.join(dest, ".codex");
+    fs.mkdirSync(outDir, { recursive: true });
+    fs.writeFileSync(path.join(outDir, "hooks.json"), hooks, "utf8");
+}
+/**
+ * Write the opencode hook-wiring artifacts into dest.
+ * Reads dist/opencode/.opencode/plugins/flow-agents.js and opencode.json,
+ * and writes them into dest. These are the minimal hook-wiring files; the
+ * full skill/agent tree is not copied.
+ */
+function dogfoodOpencode(bundleRoot, dest) {
+    const pluginSource = path.join(bundleRoot, ".opencode", "plugins", "flow-agents.js");
+    const configSource = path.join(bundleRoot, "opencode.json");
+    if (!fs.existsSync(pluginSource))
+        throw new Error(`dogfood: bundle plugin missing: ${pluginSource}`);
+    const pluginDir = path.join(dest, ".opencode", "plugins");
+    fs.mkdirSync(pluginDir, { recursive: true });
+    fs.copyFileSync(pluginSource, path.join(pluginDir, "flow-agents.js"));
+    // Write opencode.json only if it does not already exist to avoid clobbering
+    // any workspace-specific opencode configuration.
+    const destConfig = path.join(dest, "opencode.json");
+    if (!fs.existsSync(destConfig) && fs.existsSync(configSource)) {
+        fs.copyFileSync(configSource, destConfig);
+    }
+}
+/**
+ * Write the pi hook-wiring artifacts into dest.
+ * Reads dist/pi/.pi/extensions/flow-agents.ts and writes it to dest.
+ * The extension is the only hook-wiring file needed for pi.
+ */
+function dogfoodPi(bundleRoot, dest) {
+    const extSource = path.join(bundleRoot, ".pi", "extensions", "flow-agents.ts");
+    if (!fs.existsSync(extSource))
+        throw new Error(`dogfood: bundle extension missing: ${extSource}`);
+    const extDir = path.join(dest, ".pi", "extensions");
+    fs.mkdirSync(extDir, { recursive: true });
+    fs.copyFileSync(extSource, path.join(extDir, "flow-agents.ts"));
+}
+export async function mainDogfood(argv = process.argv.slice(2)) {
+    if (argv.includes("--help") || argv.includes("-h")) {
+        dogfoodUsage();
+        return 0;
+    }
+    const args = parseArgs(argv);
+    try {
+        const runtimeRaw = flagString(args.flags, "runtime");
+        const runtime = normalizeDogfoodRuntime(runtimeRaw);
+        if (!runtime) {
+            console.error("dogfood: --runtime is required (claude-code, codex, opencode, or pi)");
+            dogfoodUsage();
+            return 2;
+        }
+        const dest = path.resolve(flagString(args.flags, "dest") ?? process.cwd());
+        // Ensure the bundle for the requested runtime is built.
+        const bundleRuntime = runtime;
+        const bundleRoot = ensureBundle(bundleRuntime);
+        // Scope-collision check: warn if user-level claude settings already has flow-agents.
+        // Codex: no user-level hooks file in our install paths — skip with note above.
+        if (runtime === "claude-code") {
+            checkScopeCollision();
+        }
+        // Write only the hook-wiring artifacts, not the full bundle.
+        fs.mkdirSync(dest, { recursive: true });
+        if (runtime === "claude-code")
+            dogfoodClaudeCode(bundleRoot, dest);
+        else if (runtime === "codex")
+            dogfoodCodex(bundleRoot, dest);
+        else if (runtime === "opencode")
+            dogfoodOpencode(bundleRoot, dest);
+        else if (runtime === "pi")
+            dogfoodPi(bundleRoot, dest);
+        console.log(`Flow Agents dogfood hooks wired for ${runtime} in ${dest}`);
+        return 0;
+    }
+    catch (error) {
+        console.error(`flow-agents dogfood: ${error.message}`);
+        return 2;
+    }
+}
 if (import.meta.url === `file://${process.argv[1]}`)
     process.exit(await main());

package/build/src/cli/runtime-adapter.js

@@ -1,21 +1,25 @@
 import * as path from "node:path";
 import { parseArgs, flagString } from "../lib/args.js";
-import { activateCodexLocal } from "../runtime-adapters.js";
+import { activateCodexLocal, activateStrandsLocal } from "../runtime-adapters.js";
+const AVAILABLE_ADAPTERS = ["codex-local", "strands-local"];
 export function main(argv = process.argv.slice(2)) {
     const [command, ...rest] = argv;
     if (command !== "activate") {
-        console.error("usage: runtime-adapter activate [--dest DIR] [--source-root DIR] [--adapter codex-local]");
+        console.error("usage: runtime-adapter activate [--dest DIR] [--source-root DIR] [--adapter codex-local|strands-local]");
         return 2;
     }
     const args = parseArgs(rest);
     const dest = path.resolve(flagString(args.flags, "dest", ".") ?? ".");
     const sourceRoot = path.resolve(flagString(args.flags, "source-root", path.resolve(path.dirname(process.argv[1]), "..")) ?? ".");
     const adapter = flagString(args.flags, "adapter");
-    if (adapter && adapter !== "codex-local") {
-        console.log(JSON.stringify({ selected_adapter: null, available_adapters: ["codex-local"], supported_asset_classes: [], generated_runtime_files: [], skipped_assets: [], warnings: [], errors: [`unknown runtime adapter '${adapter}'; available adapters: codex-local`] }, null, 2));
+    if (adapter && !AVAILABLE_ADAPTERS.includes(adapter)) {
+        console.log(JSON.stringify({ selected_adapter: null, available_adapters: AVAILABLE_ADAPTERS, supported_asset_classes: [], generated_runtime_files: [], skipped_assets: [], warnings: [], errors: [`unknown runtime adapter '${adapter}'; available adapters: ${AVAILABLE_ADAPTERS.join(", ")}`] }, null, 2));
         return 2;
     }
-    const result = activateCodexLocal(sourceRoot, dest);
+    // Default to codex-local for backward compatibility; strands-local is opt-in via --adapter.
+    const result = adapter === "strands-local"
+        ? activateStrandsLocal(sourceRoot, dest)
+        : activateCodexLocal(sourceRoot, dest);
     console.log(JSON.stringify(result, null, 2));
     return Array.isArray(result.errors) && result.errors.length ? 1 : 0;
 }

package/build/src/cli/telemetry-doctor.js

@@ -46,7 +46,10 @@ function channelConfigValue(config, channel, key, fallback = "") {
 }
 function telemetryDataDir(dest) {
     const configured = process.env.TELEMETRY_DATA_DIR;
-    return configured ? path.resolve(dest, configured) : path.resolve(dest, "..", ".telemetry");
+    // Must mirror scripts/telemetry/lib/config.sh: the sink lives INSIDE the
+    // workspace at <dest>/.telemetry. The previous "../.telemetry" duplicated
+    // the parent-escape bug fixed in config.sh on 2026-06-11.
+    return configured ? path.resolve(dest, configured) : path.resolve(dest, ".telemetry");
 }
 function deriveConsoleEndpoint(consoleUrl, explicitEndpoint) {
     if (explicitEndpoint)

package/build/src/cli/utterance-check.js

@@ -15,6 +15,9 @@ function usage() {
         "  --utterance TEXT      Utterance text to check (required unless --not-configured).",
         "  --bundle-path FILE    Trust bundle JSON file. Omit for an empty bundle (all unsupported).",
         "  --agent-id ID         Agent identifier for provenance (default: flow-agents-utterance-check).",
+        "  --extractor NAME      Extractor to use: 'reference' (default, pattern-based) or 'anthropic'",
+        "                        (model-backed, requires ANTHROPIC_API_KEY and @kontourai/survey/anthropic).",
+        "  --model MODEL         Model for the anthropic extractor (e.g. claude-haiku-4-5).",
         "  --not-configured      Skip survey call; output not_configured without error.",
         "  --strict              Exit non-zero when any badge is disputed, rejected, or unsupported.",
         "  --help                Show this help.",
@@ -51,6 +54,43 @@ async function loadSurvey() {
         return undefined;
     }
 }
+/**
+ * Dynamically import @kontourai/survey/anthropic and create the Anthropic extractor.
+ * Fails open with a clear not_configured message when the key or peer dep is missing.
+ */
+async function loadAnthropicExtractor(model) {
+    const apiKey = process.env.ANTHROPIC_API_KEY;
+    if (!apiKey) {
+        return {
+            notConfigured: true,
+            reason: "anthropic extractor requires ANTHROPIC_API_KEY to be set. " +
+                "Set the environment variable or switch extractor to 'reference'.",
+        };
+    }
+    try {
+        const pkg = "@kontourai/survey/anthropic";
+        const mod = await Function("m", "return import(m)")(pkg);
+        if (typeof mod.createAnthropicUtteranceExtractor !== "function") {
+            return {
+                notConfigured: true,
+                reason: "@kontourai/survey/anthropic does not export createAnthropicUtteranceExtractor. " +
+                    "Update @kontourai/survey to a version that supports the anthropic extractor.",
+            };
+        }
+        const opts = { apiKey };
+        if (model)
+            opts.model = model;
+        return mod.createAnthropicUtteranceExtractor(opts);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            notConfigured: true,
+            reason: `@kontourai/survey/anthropic is not available: ${msg}. ` +
+                "Install @kontourai/survey with the anthropic subpath export, or switch extractor to 'reference'.",
+        };
+    }
+}
 // ---------------------------------------------------------------------------
 // Core check logic
 // ---------------------------------------------------------------------------
@@ -63,6 +103,8 @@ async function runCheck(argv) {
     const agentId = flagString(flags, "agent-id") ?? "flow-agents-utterance-check";
     const notConfigured = flagBool(flags, "not-configured");
     const strict = flagBool(flags, "strict");
+    const extractorName = flagString(flags, "extractor") ?? "reference";
+    const model = flagString(flags, "model");
     if (notConfigured) {
         const report = {
             status: "not_configured",
@@ -106,9 +148,31 @@ async function runCheck(argv) {
         return 1;
     }
     const { surveyAgentUtterance, referenceUtteranceExtractor } = survey;
+    // Resolve which extractor to use.
+    let extractor;
+    if (extractorName === "anthropic") {
+        const anthropicResult = await loadAnthropicExtractor(model);
+        if ("notConfigured" in anthropicResult) {
+            // Fail open: emit not_configured with a clear reason rather than erroring.
+            const report = {
+                status: "not_configured",
+                agent_id: agentId,
+                utterance_excerpt: excerptText(utterance),
+                statements: [],
+                summary: anthropicResult.reason,
+            };
+            process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+            process.stderr.write(`[UtteranceCheck] not_configured: ${anthropicResult.reason}\n`);
+            return 0;
+        }
+        extractor = anthropicResult;
+    }
+    else {
+        extractor = referenceUtteranceExtractor;
+    }
     let trustReport;
     try {
-        trustReport = await surveyAgentUtterance(utterance, referenceUtteranceExtractor, {
+        trustReport = await surveyAgentUtterance(utterance, extractor, {
             bundle,
             agentId,
         });

package/build/src/runtime-adapters.js

@@ -144,3 +144,37 @@ export function activateCodexLocal(sourceRoot, dest) {
     generated.push({ asset_class: "activation-manifest", path: relPath(dest, manifestPath), kit_id: "runtime", asset_id: "codex-local.activation", source_path: manifestPath.split(path.sep).join("/") });
     return { selected_adapter: "codex-local", supported_asset_classes: ["flows"], generated_runtime_files: generated, skipped_assets: skipped, warnings: inventory.warnings, errors: inventory.errors };
 }
+// Decision Q3 (Issue #32): Option (a) — new adapter id "strands-local" rather than
+// loading kit flows inside FlowAgentsHooks. Rationale: activation is a workspace-prep
+// concern (reads catalog + installed kits, writes runtime files, produces diagnostics).
+// Keeping it in the CLI adapter layer maximises reuse of readKitInventory and safeSegment,
+// mirrors the codex-local pattern exactly, and keeps framework adapters free of catalog-
+// layout knowledge. The Strands steering layer then reads the written runtime files.
+export function activateStrandsLocal(sourceRoot, dest) {
+    const inventory = readKitInventory(sourceRoot, dest);
+    // Runtime flows land at .flow-agents/runtime/strands/flows/<kit-id>/<asset-id>.flow.json
+    // so the Strands steering context can glob for *.flow.json under this path.
+    const runtimeDir = path.join(dest, ".flow-agents", "runtime", "strands");
+    const generated = [];
+    const skipped = [];
+    for (const asset of inventory.assets) {
+        if (asset.asset_class !== "flows") {
+            skipped.push({ asset_class: asset.asset_class, path: asset.relative_path, kit_id: asset.kit_id, asset_id: asset.asset_id, reason: "asset class is diagnostic-only for strands-local" });
+            continue;
+        }
+        if (!asset.asset_id) {
+            skipped.push({ asset_class: asset.asset_class, path: asset.relative_path, kit_id: asset.kit_id, asset_id: null, reason: "flow asset is missing an id" });
+            continue;
+        }
+        const output = path.join(runtimeDir, "flows", safeSegment(asset.kit_id), `${safeSegment(asset.asset_id)}.flow.json`);
+        fs.mkdirSync(path.dirname(output), { recursive: true });
+        fs.copyFileSync(asset.source_path, output);
+        generated.push({ asset_class: asset.asset_class, path: relPath(dest, output), kit_id: asset.kit_id, asset_id: asset.asset_id, source_path: asset.source_path.split(path.sep).join("/") });
+    }
+    fs.mkdirSync(runtimeDir, { recursive: true });
+    const manifest = { schema_version: "1.0", adapter: "strands-local", supported_asset_classes: ["flows"], generated_runtime_files: generated, skipped_assets: skipped, warnings: inventory.warnings, errors: inventory.errors };
+    const manifestPath = path.join(runtimeDir, "activation.json");
+    writeJson(manifestPath, manifest);
+    generated.push({ asset_class: "activation-manifest", path: relPath(dest, manifestPath), kit_id: "runtime", asset_id: "strands-local.activation", source_path: manifestPath.split(path.sep).join("/") });
+    return { selected_adapter: "strands-local", supported_asset_classes: ["flows"], generated_runtime_files: generated, skipped_assets: skipped, warnings: inventory.warnings, errors: inventory.errors };
+}