@kontourai/flow-agents 0.2.0 → 0.4.0

package/integrations/strands-ts/src/hooks.ts

@@ -26,6 +26,8 @@
  *   // All methods callable; registerHooks() is a no-op without the SDK.
  */
 
+import fs from "node:fs";
+import path from "node:path";
 import { TelemetrySink } from "./telemetry.js";
 import { PolicyGate } from "./policy.js";
 
@@ -58,6 +60,81 @@ export interface StrandsEvent {
   [key: string]: unknown;
 }
 
+// ---------------------------------------------------------------------------
+// Kit flow discovery (Issue #32, Decision Q3: option (a))
+//
+// activateStrandsLocal (src/runtime-adapters.ts) writes kit flow files to
+// .flow-agents/runtime/strands/flows/<kit-id>/<asset-id>.flow.json.
+// steeringContext() reads those files and surfaces their id + description
+// so the agent is aware of available workflow guidance without the hooks
+// needing to know anything about the catalog layout.
+// ---------------------------------------------------------------------------
+
+interface KitFlowEntry {
+  kitId: string;
+  assetId: string;
+  description: string;
+}
+
+function findRepoRoot(start: string): string {
+  let current = path.resolve(start);
+  for (let i = 0; i < 40; i++) {
+    if (
+      fs.existsSync(path.join(current, ".git")) ||
+      fs.existsSync(path.join(current, "AGENTS.md"))
+    ) {
+      return current;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return path.resolve(start);
+}
+
+function readKitFlows(flowAgentsDir: string): KitFlowEntry[] {
+  const flowsDir = path.join(flowAgentsDir, "runtime", "strands", "flows");
+  if (!fs.existsSync(flowsDir)) return [];
+  const results: KitFlowEntry[] = [];
+
+  function walkDir(dir: string): void {
+    for (const name of fs.readdirSync(dir).sort()) {
+      const full = path.join(dir, name);
+      const stat = fs.statSync(full);
+      if (stat.isDirectory()) {
+        walkDir(full);
+      } else if (name.endsWith(".flow.json")) {
+        try {
+          const payload = JSON.parse(fs.readFileSync(full, "utf8")) as Record<string, unknown>;
+          const stemName = name.replace(/\.flow\.json$/, "");
+          const assetId = typeof payload.id === "string" ? payload.id : stemName;
+          const description = typeof payload.description === "string" ? payload.description : "";
+          // kit_id is the directory component between flows/ and the file
+          const rel = path.relative(flowsDir, full);
+          const relParts = rel.split(path.sep);
+          const kitId = relParts.length >= 2 ? relParts[0] : "";
+          results.push({ kitId, assetId, description });
+        } catch {
+          // Malformed file — skip silently (fail-open)
+        }
+      }
+    }
+  }
+
+  walkDir(flowsDir);
+  return results;
+}
+
+function buildKitFlowsHint(flows: KitFlowEntry[]): string {
+  if (flows.length === 0) return "";
+  const lines = ["KIT FLOWS: the following kit flows are activated for this workspace:"];
+  for (const flow of flows) {
+    const desc = flow.description ? ` — ${flow.description.slice(0, 120)}` : "";
+    lines.push(`  • ${flow.assetId}${desc}`);
+  }
+  return lines.join("\n");
+}
+
 // ---------------------------------------------------------------------------
 // FlowAgentsHooks options
 // ---------------------------------------------------------------------------
@@ -85,9 +162,12 @@ export interface FlowAgentsHooksOptions {
 export class FlowAgentsHooks {
   private readonly sink: TelemetrySink;
   private readonly policyGate: PolicyGate;
+  private readonly _workspace: string;
   private _sessionStartMs: number | null = null;
 
   constructor(options: FlowAgentsHooksOptions = {}) {
+    this._workspace = findRepoRoot(options.workspace ?? process.cwd());
+
     this.sink = new TelemetrySink({
       sinkPath: options.sinkPath,
       workspace: options.workspace,
@@ -100,6 +180,30 @@ export class FlowAgentsHooks {
     });
   }
 
+  // --------------------------------------------------------------------------
+  // Steering context — available without strands-agents installed (Issue #32 AC2)
+  // --------------------------------------------------------------------------
+
+  /**
+   * Return workflow-steering context text for the current workspace.
+   *
+   * Includes activated kit flows discovered from the strands-local runtime
+   * path (.flow-agents/runtime/strands/flows/) written by
+   * `flow-kit activate --adapter strands-local`.
+   *
+   * Callers should prepend this to the Agent's system prompt:
+   *
+   *   const hooks = new FlowAgentsHooks({ workspace: "." });
+   *   const agent = new Agent({ systemPrompt: basePrompt + hooks.steeringContext() });
+   */
+  steeringContext(): string {
+    const flowAgentsDir = path.join(this._workspace, ".flow-agents");
+    const flows = readKitFlows(flowAgentsDir);
+    const kitFlowsHint = buildKitFlowsHint(flows);
+    if (!kitFlowsHint) return "";
+    return "\n\n---\n" + kitFlowsHint + "\n---";
+  }
+
   // --------------------------------------------------------------------------
   // HookProvider protocol — registerHooks(registry)
   // This is the sole method required by the Strands HookProvider protocol.

package/integrations/strands-ts/test/test-steering.ts

@@ -0,0 +1,159 @@
+/**
+ * test-steering.ts — Tests for FlowAgentsHooks.steeringContext() kit flow surfacing.
+ *
+ * Issue #32 AC2: steering context surfaces activated kit flows from the
+ * strands-local runtime path (.flow-agents/runtime/strands/flows/).
+ *
+ * Fixture approach: write fake *.flow.json files (same structure as the real
+ * kit flow files produced by activateStrandsLocal) and assert the steering
+ * context text contains kit flow ids and descriptions.
+ */
+
+import { test, describe } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { FlowAgentsHooks } from "../src/hooks.js";
+
+function makeTmpDir(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "fa-ts-steering-"));
+}
+
+function writeFlow(
+  workspace: string,
+  kitId: string,
+  assetId: string,
+  description = ""
+): void {
+  const flowsDir = path.join(
+    workspace,
+    ".flow-agents",
+    "runtime",
+    "strands",
+    "flows",
+    kitId
+  );
+  fs.mkdirSync(flowsDir, { recursive: true });
+  const safeName = assetId.replace(/\./g, "-");
+  fs.writeFileSync(
+    path.join(flowsDir, `${safeName}.flow.json`),
+    JSON.stringify({ id: assetId, description }),
+    "utf8"
+  );
+}
+
+describe("FlowAgentsHooks.steeringContext() — kit flow surfacing (Issue #32 AC2)", () => {
+  test("empty string when no runtime strands dir exists", () => {
+    const tmpDir = makeTmpDir();
+    try {
+      const hooks = new FlowAgentsHooks({ workspace: tmpDir });
+      const ctx = hooks.steeringContext();
+      assert.strictEqual(ctx, "", "Expected empty steering context with no runtime dir");
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  test("KIT FLOWS hint appears when a flow file exists", () => {
+    const tmpDir = makeTmpDir();
+    try {
+      writeFlow(tmpDir, "builder", "builder.shape", "Shape a problem.");
+      const hooks = new FlowAgentsHooks({ workspace: tmpDir });
+      const ctx = hooks.steeringContext();
+      assert.ok(ctx.includes("KIT FLOWS"), `Expected 'KIT FLOWS' in context, got: ${ctx}`);
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  test("flow asset_id appears in steering context", () => {
+    const tmpDir = makeTmpDir();
+    try {
+      writeFlow(tmpDir, "builder", "builder.shape", "Shape a problem.");
+      const hooks = new FlowAgentsHooks({ workspace: tmpDir });
+      const ctx = hooks.steeringContext();
+      assert.ok(
+        ctx.includes("builder.shape"),
+        `Expected 'builder.shape' in context, got: ${ctx}`
+      );
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  test("flow description appears in steering context", () => {
+    const tmpDir = makeTmpDir();
+    try {
+      writeFlow(tmpDir, "builder", "builder.build", "Build a feature end-to-end.");
+      const hooks = new FlowAgentsHooks({ workspace: tmpDir });
+      const ctx = hooks.steeringContext();
+      assert.ok(
+        ctx.includes("Build a feature end-to-end."),
+        `Expected description in context, got: ${ctx}`
+      );
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  test("multiple flows all listed in steering context", () => {
+    const tmpDir = makeTmpDir();
+    try {
+      writeFlow(tmpDir, "builder", "builder.shape", "Shape.");
+      writeFlow(tmpDir, "builder", "builder.build", "Build.");
+      const hooks = new FlowAgentsHooks({ workspace: tmpDir });
+      const ctx = hooks.steeringContext();
+      assert.ok(ctx.includes("builder.shape"), "Expected builder.shape in context");
+      assert.ok(ctx.includes("builder.build"), "Expected builder.build in context");
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  test("malformed flow JSON does not crash; other flows still listed", () => {
+    const tmpDir = makeTmpDir();
+    try {
+      writeFlow(tmpDir, "builder", "builder.shape", "Shape.");
+      // Write a malformed flow file
+      const flowsDir = path.join(
+        tmpDir,
+        ".flow-agents",
+        "runtime",
+        "strands",
+        "flows",
+        "builder"
+      );
+      fs.writeFileSync(path.join(flowsDir, "bad.flow.json"), "{ not valid json", "utf8");
+      const hooks = new FlowAgentsHooks({ workspace: tmpDir });
+      const ctx = hooks.steeringContext();
+      // builder.shape should still appear
+      assert.ok(ctx.includes("builder.shape"), "Expected builder.shape despite bad file");
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  test("steering context wraps with --- delimiters", () => {
+    const tmpDir = makeTmpDir();
+    try {
+      writeFlow(tmpDir, "builder", "builder.shape", "Shape.");
+      const hooks = new FlowAgentsHooks({ workspace: tmpDir });
+      const ctx = hooks.steeringContext();
+      assert.ok(ctx.includes("---"), "Expected --- delimiters in context");
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  test("returns string type (even empty)", () => {
+    const tmpDir = makeTmpDir();
+    try {
+      const hooks = new FlowAgentsHooks({ workspace: tmpDir });
+      const ctx = hooks.steeringContext();
+      assert.strictEqual(typeof ctx, "string");
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+});

package/kits/catalog.json

@@ -6,6 +6,12 @@
       "name": "Builder Kit",
       "path": "kits/builder",
       "description": "Flow-backed shaping, planning, build, verification, merge readiness, pull request readiness, and learning workflows."
+    },
+    {
+      "id": "knowledge",
+      "name": "Knowledge Kit",
+      "path": "kits/knowledge",
+      "description": "Store contract with record types (raw/compiled/concept), mutation operations with required provenance, default markdown+frontmatter+wikilink+graph-index adapter, and a parameterized contract test suite."
     }
   ]
 }