@kontourai/flow-agents 0.1.2 → 0.3.0

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/integrations/strands-ts/test/test-telemetry.ts

@@ -0,0 +1,226 @@
+/**
+ * test-telemetry.ts — Tests for telemetry module.
+ *
+ * Covers: event mapping, JSONL emission shape, normalizeToolName.
+ * Uses node:test only — no additional dependencies.
+ */
+
+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 { TelemetrySink, STRANDS_TO_CANONICAL, normalizeToolName, SCHEMA_VERSION } from "../src/telemetry.js";
+
+// ---------------------------------------------------------------------------
+// STRANDS_TO_CANONICAL mapping table
+// ---------------------------------------------------------------------------
+
+describe("STRANDS_TO_CANONICAL mapping", () => {
+  test("contains all expected Strands TS event class names", () => {
+    const expected = new Set([
+      "BeforeInvocationEvent",
+      "AfterInvocationEvent",
+      "BeforeToolCallEvent",
+      "AfterToolCallEvent",
+      "AgentInitializedEvent",
+      "AfterModelCallEvent",
+      "MessageAddedEvent",
+    ]);
+    assert.deepStrictEqual(new Set(Object.keys(STRANDS_TO_CANONICAL)), expected);
+  });
+
+  test("BeforeInvocationEvent → userPromptSubmit", () => {
+    assert.strictEqual(STRANDS_TO_CANONICAL.BeforeInvocationEvent, "userPromptSubmit");
+  });
+
+  test("AfterInvocationEvent → stop", () => {
+    assert.strictEqual(STRANDS_TO_CANONICAL.AfterInvocationEvent, "stop");
+  });
+
+  test("BeforeToolCallEvent → preToolUse", () => {
+    assert.strictEqual(STRANDS_TO_CANONICAL.BeforeToolCallEvent, "preToolUse");
+  });
+
+  test("AfterToolCallEvent → postToolUse", () => {
+    assert.strictEqual(STRANDS_TO_CANONICAL.AfterToolCallEvent, "postToolUse");
+  });
+
+  test("AgentInitializedEvent → agentSpawn", () => {
+    assert.strictEqual(STRANDS_TO_CANONICAL.AgentInitializedEvent, "agentSpawn");
+  });
+
+  test("all values are non-empty strings", () => {
+    for (const [key, value] of Object.entries(STRANDS_TO_CANONICAL)) {
+      assert.strictEqual(typeof value, "string", `${key} value must be a string`);
+      assert.ok(value.length > 0, `${key} value must be non-empty`);
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// normalizeToolName
+// ---------------------------------------------------------------------------
+
+describe("normalizeToolName", () => {
+  test("bash → execute_bash", () => {
+    assert.strictEqual(normalizeToolName("bash"), "execute_bash");
+  });
+
+  test("edit → fs_write", () => {
+    assert.strictEqual(normalizeToolName("edit"), "fs_write");
+  });
+
+  test("write → fs_write", () => {
+    assert.strictEqual(normalizeToolName("write"), "fs_write");
+  });
+
+  test("read → fs_read", () => {
+    assert.strictEqual(normalizeToolName("read"), "fs_read");
+  });
+
+  test("task → use_subagent", () => {
+    assert.strictEqual(normalizeToolName("task"), "use_subagent");
+  });
+
+  test("unknown passthrough", () => {
+    assert.strictEqual(normalizeToolName("my_custom_tool"), "my_custom_tool");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// TelemetrySink emission shape
+// ---------------------------------------------------------------------------
+
+function makeTempSink(agentName = "test-agent", runtime = "strands-test"): { sink: TelemetrySink; dir: string } {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "fa-ts-telemetry-"));
+  const sink = new TelemetrySink({ sinkPath: dir, agentName, runtime });
+  return { sink, dir };
+}
+
+function readEvents(dir: string): Record<string, unknown>[] {
+  const logFile = path.join(dir, "full.jsonl");
+  if (!fs.existsSync(logFile)) return [];
+  const lines = fs.readFileSync(logFile, "utf8").trim().split("\n");
+  return lines.filter((l) => l.trim()).map((l) => JSON.parse(l) as Record<string, unknown>);
+}
+
+describe("TelemetrySink emission shape", () => {
+  test("session start event has correct schema_version and event_type", () => {
+    const { sink, dir } = makeTempSink();
+    const evt = sink.emitSessionStart();
+    assert.strictEqual(evt.schema_version, SCHEMA_VERSION);
+    assert.strictEqual(evt.event_type, "session.start");
+    // cleanup
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("session start written to JSONL", () => {
+    const { sink, dir } = makeTempSink();
+    sink.emitSessionStart();
+    const events = readEvents(dir);
+    assert.strictEqual(events.length, 1);
+    assert.strictEqual((events[0] as Record<string, unknown>).event_type, "session.start");
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("event has required top-level fields (timestamp, session_id, event_id)", () => {
+    const { sink, dir } = makeTempSink();
+    const evt = sink.emitSessionStart();
+    assert.ok("timestamp" in evt, "missing timestamp");
+    assert.ok("session_id" in evt, "missing session_id");
+    assert.ok("event_id" in evt, "missing event_id");
+    assert.ok("agent" in evt, "missing agent");
+    assert.ok("hook" in evt, "missing hook");
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("agent sub-object has name and runtime", () => {
+    const { sink, dir } = makeTempSink("my-agent", "strands-ts");
+    const evt = sink.emitSessionStart();
+    const agent = evt.agent as Record<string, unknown>;
+    assert.strictEqual(agent.name, "my-agent");
+    assert.strictEqual(agent.runtime, "strands-ts");
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("hook sub-object has event_name and source fields", () => {
+    const { sink, dir } = makeTempSink();
+    const evt = sink.emitSessionStart();
+    const hook = evt.hook as Record<string, unknown>;
+    assert.ok("event_name" in hook, "hook.event_name missing");
+    assert.ok("source" in hook, "hook.source missing");
+    assert.strictEqual(hook.source, "strands-ts");
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("tool invoke event has correct event_type and tool fields", () => {
+    const { sink, dir } = makeTempSink();
+    const evt = sink.emitToolInvoke("edit", { path: "foo.py" });
+    assert.strictEqual(evt.event_type, "tool.invoke");
+    const tool = evt.tool as Record<string, unknown>;
+    assert.strictEqual(tool.name, "edit");
+    assert.strictEqual(tool.normalized_name, "fs_write");
+    assert.deepStrictEqual(tool.input, { path: "foo.py" });
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("tool result event has correct event_type", () => {
+    const { sink, dir } = makeTempSink();
+    const evt = sink.emitToolResult("read", "file contents");
+    assert.strictEqual(evt.event_type, "tool.result");
+    const tool = evt.tool as Record<string, unknown>;
+    assert.strictEqual(tool.name, "read");
+    assert.strictEqual(tool.normalized_name, "fs_read");
+    assert.strictEqual(tool.output, "file contents");
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("session end has event_type session.end", () => {
+    const { sink, dir } = makeTempSink();
+    const evt = sink.emitSessionEnd(1000);
+    assert.strictEqual(evt.event_type, "session.end");
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("user prompt submit has event_type turn.user", () => {
+    const { sink, dir } = makeTempSink();
+    const evt = sink.emitUserPromptSubmit();
+    assert.strictEqual(evt.event_type, "turn.user");
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("multiple events share the same session_id", () => {
+    const { sink, dir } = makeTempSink();
+    sink.emitSessionStart();
+    sink.emitToolInvoke("read", {});
+    sink.emitSessionEnd();
+    const events = readEvents(dir);
+    const sessionIds = new Set(events.map((e) => (e as Record<string, unknown>).session_id));
+    assert.strictEqual(sessionIds.size, 1, "All events must share one session_id");
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("each JSONL line is valid JSON", () => {
+    const { sink, dir } = makeTempSink();
+    sink.emitSessionStart();
+    sink.emitToolInvoke("bash", { command: "ls" });
+    sink.emitSessionEnd(500);
+    const logFile = path.join(dir, "full.jsonl");
+    const lines = fs.readFileSync(logFile, "utf8").split("\n");
+    for (const line of lines) {
+      if (!line.trim()) continue;
+      const parsed = JSON.parse(line); // throws on invalid JSON
+      assert.strictEqual(typeof parsed, "object");
+    }
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("sinkPath directory creates full.jsonl", () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "fa-ts-sink-dir-"));
+    const sink = new TelemetrySink({ sinkPath: dir });
+    sink.emitSessionStart();
+    assert.ok(fs.existsSync(path.join(dir, "full.jsonl")));
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+});

package/integrations/strands-ts/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "ignoreDeprecations": "6.0",
+    "lib": ["ES2022"],
+    "types": ["node"],
+    "rootDir": ".",
+    "outDir": "dist",
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*.ts", "test/**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}

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."
     }
   ]
 }