@kontourai/flow-agents 0.1.2 → 0.3.0

package/kits/knowledge/adapters/flow-runner/telemetry.js

@@ -0,0 +1,174 @@
+/**
+ * Knowledge Kit — Telemetry Helper
+ *
+ * Emits canonical Flow Agents telemetry events (schema v0.3.0) to a JSONL
+ * sink file. Matches the event shape produced by telemetry.sh and the Python
+ * TelemetrySink in integrations/strands/flow_agents_strands/telemetry.py.
+ *
+ * Zero runtime dependencies beyond Node.js built-ins.
+ * Fails open: telemetry errors never block kit operations.
+ *
+ * Sink path: <workspace>/.telemetry/full.jsonl
+ * The workspace is resolved from FLOW_AGENTS_WORKSPACE env var, falling back
+ * to process.cwd().
+ *
+ * @module adapters/flow-runner/telemetry
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as crypto from "node:crypto";
+
+// ---------------------------------------------------------------------------
+// Schema constants
+// ---------------------------------------------------------------------------
+
+const SCHEMA_VERSION = "0.3.0";
+
+// Canonical event name → schema event_type  (mirrors telemetry.sh schema_event_type())
+const CANONICAL_TO_SCHEMA = {
+  agentSpawn:        "session.start",
+  userPromptSubmit:  "turn.user",
+  preToolUse:        "tool.invoke",
+  permissionRequest: "tool.permission_request",
+  postToolUse:       "tool.result",
+  stop:              "session.end",
+  subagentStart:     "agent.delegate",
+  subagentStop:      "agent.delegate",
+};
+
+function schemaEventType(canonical) {
+  return CANONICAL_TO_SCHEMA[canonical] || "unknown";
+}
+
+// ---------------------------------------------------------------------------
+// Sink resolution
+// ---------------------------------------------------------------------------
+
+function resolveSinkPath(workspace) {
+  const ws = workspace || process.env.FLOW_AGENTS_WORKSPACE || process.cwd();
+  return path.join(ws, ".telemetry", "full.jsonl");
+}
+
+// ---------------------------------------------------------------------------
+// KnowledgeTelemetry
+// ---------------------------------------------------------------------------
+
+/**
+ * Thin telemetry sink for the Knowledge Kit flow runner.
+ *
+ * Usage:
+ *   const tel = new KnowledgeTelemetry({ workspace: "/path/to/workspace" });
+ *   tel.emitGate("knowledge.ingest", "classify-gate", { category: "research", record_id: id });
+ */
+export class KnowledgeTelemetry {
+  /**
+   * @param {{ workspace?: string, agentName?: string, sessionId?: string }} options
+   */
+  constructor({ workspace, agentName, sessionId } = {}) {
+    this._sinkPath = resolveSinkPath(workspace);
+    this._agentName = agentName || "knowledge-kit";
+    this._sessionId = sessionId || crypto.randomUUID();
+
+    // Ensure the sink directory exists; fail open on error
+    try {
+      fs.mkdirSync(path.dirname(this._sinkPath), { recursive: true });
+    } catch {
+      // fail open
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Core emit
+  // -------------------------------------------------------------------------
+
+  /**
+   * Build and append a canonical telemetry event to the JSONL sink.
+   * Returns the emitted event object (useful for tests).
+   * Fails open: never throws.
+   *
+   * @param {string} canonicalEvent  - canonical event name (e.g. "preToolUse")
+   * @param {object} [extra]         - additional fields merged into the event
+   * @returns {object} the emitted event
+   */
+  emit(canonicalEvent, extra) {
+    const schemaType = schemaEventType(canonicalEvent);
+    const event = {
+      schema_version: SCHEMA_VERSION,
+      timestamp: String(Date.now()),
+      session_id: this._sessionId,
+      event_id: crypto.randomUUID(),
+      event_type: schemaType,
+      agent: {
+        name: this._agentName,
+        runtime: "knowledge-kit",
+        version: "unknown",
+      },
+      hook: {
+        event_name: canonicalEvent,
+        runtime_session_id: "",
+        turn_id: "",
+        transcript_path: "",
+        model: "",
+        source: "knowledge-kit",
+        stop_hook_active: null,
+        last_assistant_message: "",
+        raw_input: null,
+      },
+    };
+
+    if (extra && typeof extra === "object") {
+      Object.assign(event, extra);
+    }
+
+    try {
+      fs.appendFileSync(this._sinkPath, JSON.stringify(event) + "\n", "utf8");
+    } catch {
+      // fail open — telemetry must never block kit operations
+    }
+
+    return event;
+  }
+
+  // -------------------------------------------------------------------------
+  // Semantic helpers
+  // -------------------------------------------------------------------------
+
+  /**
+   * Emit a gate event. Used at each flow gate point in the runner.
+   *
+   * @param {string} flowId    - e.g. "knowledge.ingest"
+   * @param {string} gateId    - e.g. "classify-gate"
+   * @param {object} [context] - gate-specific context payload
+   * @returns {object} the emitted event
+   */
+  emitGate(flowId, gateId, context) {
+    return this.emit("preToolUse", {
+      tool: {
+        name: `${flowId}.${gateId}`,
+        normalized_name: "flow.gate",
+        input: context || null,
+      },
+    });
+  }
+
+  /**
+   * Emit a gate-result event.
+   *
+   * @param {string} flowId    - e.g. "knowledge.ingest"
+   * @param {string} gateId    - e.g. "classify-gate"
+   * @param {object} [result]  - gate result payload
+   * @returns {object} the emitted event
+   */
+  emitGateResult(flowId, gateId, result) {
+    return this.emit("postToolUse", {
+      tool: {
+        name: `${flowId}.${gateId}`,
+        normalized_name: "flow.gate",
+        output: result || null,
+      },
+    });
+  }
+}
+
+export default KnowledgeTelemetry;

package/kits/knowledge/docs/README.md

@@ -0,0 +1,135 @@
+---
+title: Knowledge Kit
+---
+
+# Knowledge Kit
+
+A Flow Kit for durable, gated knowledge storage. The kit defines a store contract with precise
+record types, mutation operations, and provenance requirements — then ships a default adapter
+backed by markdown files, YAML frontmatter, `[[wikilink]]` inline links, and a JSON graph
+index.
+
+Any storage backend can adopt this kit by implementing the contract without forking kit flows.
+
+---
+
+## Contract Summary
+
+See [`store-contract.md`](store-contract.md) for the full specification. Quick reference:
+
+**Record types**
+
+| Type | Purpose |
+|---|---|
+| `raw` | Unprocessed source material — excerpts, transcripts, URLs with notes. |
+| `compiled` | Normalized, editor-reviewed distillations of raw records. |
+| `concept` | Named ideas or principles that other records reference. |
+
+**Mutation operations**
+
+| Op | Required evidence fields |
+|---|---|
+| `create` | `type`, `title`, `body`, `category`, `provenance.agent` |
+| `update` | `agent` (in evidence) + at least one mutable field |
+| `link` | `agent`, non-empty `links` array |
+| `propose` | `agent`, `proposal` (non-empty) |
+| `apply` | `agent`, `new_body` (non-empty), `rationale` (non-empty) |
+| `reject` | `agent`, `reason` (non-empty) |
+
+Every mutation throws with `error.code === "MISSING_EVIDENCE"` when required evidence is absent.
+
+---
+
+## Running the Contract Suite
+
+The contract suite is a `node:test` suite parameterized by adapter.
+
+### Default adapter (runs automatically)
+
+```bash
+node --test kits/knowledge/evals/contract-suite/suite.test.js
+```
+
+### Alternative adapter
+
+```bash
+KNOWLEDGE_ADAPTER=/path/to/my-adapter.js \
+  node --test kits/knowledge/evals/contract-suite/suite.test.js
+```
+
+Or via CLI flag:
+
+```bash
+node --test kits/knowledge/evals/contract-suite/suite.test.js \
+  -- --adapter=/path/to/my-adapter.js
+```
+
+### Expected output (default adapter)
+
+All tests pass and exit 0. Any failure indicates a contract regression or an adapter gap.
+
+---
+
+## Acceptance Criteria Mapping
+
+| AC | Requirement | Evidence |
+|---|---|---|
+| AC1 | Contract doc exists; mutation ops enumerate evidence fields. | [`docs/store-contract.md`](store-contract.md) — §6 covers all six ops with required-field tables. |
+| AC2 | Default adapter passes contract suite (command evidence). | Run `node --test kits/knowledge/evals/contract-suite/suite.test.js` — exit 0, all tests pass. |
+| AC3 | Record round-trips raw → stored → queried with category + links intact. | Suite §2 "create: round-trip raw → stored → queried" tests this directly. |
+
+---
+
+## Default Adapter Details
+
+Located at `adapters/default-store/index.js`. Zero runtime dependencies; uses Node.js
+built-ins only.
+
+**Storage layout**
+
+```
+<store_root>/
+  records/
+    <id>.md        ← one markdown file per record, YAML frontmatter + body
+  graph-index.json ← forward + reverse link index, schema_version 1.0
+```
+
+**Constructor**
+
+```js
+import DefaultKnowledgeStore from './adapters/default-store/index.js';
+const store = new DefaultKnowledgeStore({ storeRoot: '/path/to/store' });
+```
+
+**Interface** (all methods return Promises):
+
+- `create(input)` → `Promise<string>` (new id)
+- `update(id, fields, evidence)` → `Promise<void>`
+- `link(sourceId, links, evidence)` → `Promise<void>`
+- `propose(conceptId, proposerId, evidence)` → `Promise<void>`
+- `apply(conceptId, proposerId, evidence)` → `Promise<void>`
+- `reject(conceptId, proposerId, evidence)` → `Promise<void>`
+- `get(id)` → `Promise<Record | null>`
+- `getLinks(id)` → `Promise<{ forward: Link[], reverse: Link[] }>`
+- `listByCategory(category, options?)` → `Promise<Record[]>`
+- `listByType(type)` → `Promise<Record[]>`
+
+---
+
+## Flow
+
+The kit ships one flow:
+
+**`knowledge.store-contract`** — gates on three evidence claims before a store implementation
+is accepted: contract-suite pass, provenance-enforcement pass, and round-trip integrity pass.
+S2 will add pipeline flows for raw ingestion, compilation, and concept management; this flow
+and adapter infrastructure remain the foundation.
+
+---
+
+## Non-Goals (this iteration)
+
+- Vector/semantic retrieval (parked as I10)
+- Multi-user concurrency
+- Store migrations
+- Personal-KB import (parked as I11)