@kontourai/flow-agents 3.3.0 → 3.4.1

package/scripts/install-owned-files.js

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+// Install a prepared Flow Agents overlay without claiming or deleting unrelated files.
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const path = require("node:path");
+
+function fail(message) {
+  process.stderr.write(`install-owned-files: ${message}\n`);
+  process.exit(1);
+}
+
+const [sourceArg, destArg, manifestArg] = process.argv.slice(2);
+if (!sourceArg || !destArg || !manifestArg) fail("usage: install-owned-files.js <overlay> <destination> <manifest-relative-path>");
+const source = fs.realpathSync(sourceArg);
+const dest = fs.realpathSync(destArg);
+const manifestPath = path.join(dest, manifestArg);
+
+function hashFile(file) {
+  return crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex");
+}
+
+function relativeFiles(root, current = root) {
+  const out = [];
+  for (const name of fs.readdirSync(current).sort()) {
+    const file = path.join(current, name);
+    const stat = fs.lstatSync(file);
+    if (stat.isSymbolicLink()) fail(`refusing symlink in install overlay: ${file}`);
+    if (stat.isDirectory()) out.push(...relativeFiles(root, file));
+    else if (stat.isFile()) out.push(path.relative(root, file).split(path.sep).join("/"));
+    else fail(`unsupported install overlay entry: ${file}`);
+  }
+  return out;
+}
+
+function targetFor(rel) {
+  if (!rel || rel.split("/").some((part) => !part || part === "." || part === "..")) fail(`unsafe relative path: ${rel}`);
+  const target = path.resolve(dest, ...rel.split("/"));
+  const relative = path.relative(dest, target);
+  if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) fail(`path escapes destination: ${rel}`);
+  return target;
+}
+
+function ensureSafeParent(target, create) {
+  const relative = path.relative(dest, path.dirname(target));
+  let current = dest;
+  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()) fail(`refusing to write through symlink: ${current}`);
+      if (!stat.isDirectory()) fail(`destination component is not a directory: ${current}`);
+    } else if (create) {
+      fs.mkdirSync(current);
+    }
+  }
+}
+
+function readManifest() {
+  if (!fs.existsSync(manifestPath)) return new Map();
+  ensureSafeParent(manifestPath, false);
+  const stat = fs.lstatSync(manifestPath);
+  if (stat.isSymbolicLink() || !stat.isFile()) fail(`ownership manifest is not a regular file: ${manifestPath}`);
+  let parsed;
+  try { parsed = JSON.parse(fs.readFileSync(manifestPath, "utf8")); } catch (error) { fail(`invalid ownership manifest: ${error.message}`); }
+  if (parsed.schema_version !== "1.0" || !Array.isArray(parsed.files)) fail("unsupported ownership manifest; remove it only after manually auditing installed files");
+  return new Map(parsed.files.map((entry) => [String(entry.path), String(entry.sha256)]));
+}
+
+function legacyInstallCutoff() {
+  if (fs.existsSync(manifestPath)) return null;
+  const recordPath = path.join(dest, ".flow-agents", "install.json");
+  const hooksPath = path.join(dest, "hooks.json");
+  for (const file of [recordPath, hooksPath]) {
+    if (!fs.existsSync(file)) return null;
+    ensureSafeParent(file, false);
+    const stat = fs.lstatSync(file);
+    if (stat.isSymbolicLink() || !stat.isFile()) return null;
+  }
+  let record;
+  try { record = JSON.parse(fs.readFileSync(recordPath, "utf8")); } catch { return null; }
+  const installedAt = Date.parse(String(record.installedAt ?? ""));
+  if (record.runtime !== "codex" || !/^\d+\.\d+\.\d+(?:[-+].*)?$/.test(String(record.version ?? "")) || !Number.isFinite(installedAt)) return null;
+  const hooks = fs.readFileSync(hooksPath, "utf8");
+  if (!hooks.includes("Recording Flow Agents telemetry") && !hooks.includes("stop-goal-fit.js")) return null;
+  return installedAt + 2000;
+}
+
+// Exact path classes managed by the pre-manifest installer. These are an
+// auditable historical contract, intentionally narrower than "all incoming
+// files": root config/auth/hooks, kits/local, user-extensible skills/agents,
+// and arbitrary destination files are never bootstrapped from timestamps.
+function wasLegacyManagedPath(rel) {
+  const [top] = rel.split("/");
+  const managedTrees = new Set([
+    ".flow-agents", "agent-cards", "build", "context", "docs", "evals",
+    "integrations", "packaging", "powers", "prompts", "schemas", "scripts",
+  ]);
+  if (managedTrees.has(top)) return rel !== ".flow-agents/install.json";
+  if (top === "kits") return !rel.startsWith("kits/local/");
+  return new Set(["README.md", "console.telemetry.json", "install.sh"]).has(rel);
+}
+
+const previous = readManifest();
+const legacyCutoff = legacyInstallCutoff();
+const incoming = relativeFiles(source).map((rel) => ({ rel, source: path.join(source, ...rel.split("/")), hash: hashFile(path.join(source, ...rel.split("/"))) }));
+
+// Complete preflight before the first destination mutation.
+for (const entry of incoming) {
+  const target = targetFor(entry.rel);
+  ensureSafeParent(target, false);
+  if (!fs.existsSync(target)) continue;
+  const stat = fs.lstatSync(target);
+  if (stat.isSymbolicLink()) fail(`refusing to replace symlink: ${target}`);
+  if (!stat.isFile()) fail(`destination collision is not a regular file: ${target}`);
+  const oldHash = previous.get(entry.rel);
+  const currentHash = hashFile(target);
+  // Migration from the pre-manifest installer: byte-identical bundle files can
+  // be adopted without overwriting them. Any differing unowned file is a hard
+  // collision and remains untouched.
+  if (!oldHash) {
+    if (currentHash !== entry.hash) {
+      const recognizableLegacy = legacyCutoff !== null && wasLegacyManagedPath(entry.rel) && stat.mtimeMs <= legacyCutoff;
+      if (!recognizableLegacy) fail(`refusing to overwrite unowned or ambiguous file: ${target}`);
+    }
+  } else if (currentHash !== oldHash && currentHash !== entry.hash) {
+    fail(`refusing to overwrite modified Flow Agents file: ${target}`);
+  }
+}
+for (const [rel] of previous) {
+  const target = targetFor(rel);
+  ensureSafeParent(target, false);
+  if (fs.existsSync(target) && fs.lstatSync(target).isSymbolicLink()) fail(`refusing to remove symlink replacing owned file: ${target}`);
+}
+
+for (const entry of incoming) {
+  const target = targetFor(entry.rel);
+  ensureSafeParent(target, true);
+  const temp = path.join(path.dirname(target), `.${path.basename(target)}.flow-agents-${process.pid}-${crypto.randomBytes(6).toString("hex")}.tmp`);
+  try {
+    fs.copyFileSync(entry.source, temp, fs.constants.COPYFILE_EXCL);
+    fs.chmodSync(temp, fs.statSync(entry.source).mode & 0o777);
+    fs.renameSync(temp, target);
+  } finally {
+    fs.rmSync(temp, { force: true });
+  }
+}
+
+const incomingPaths = new Set(incoming.map((entry) => entry.rel));
+const staleParents = new Set();
+for (const [rel, oldHash] of previous) {
+  if (incomingPaths.has(rel)) continue;
+  const target = targetFor(rel);
+  if (!fs.existsSync(target)) continue;
+  const stat = fs.lstatSync(target);
+  if (!stat.isFile() || hashFile(target) !== oldHash) {
+    process.stderr.write(`install-owned-files: preserving modified former Flow Agents file: ${target}\n`);
+    continue;
+  }
+  fs.rmSync(target);
+  staleParents.add(path.dirname(target));
+}
+for (const start of [...staleParents].sort((a, b) => b.length - a.length)) {
+  let current = start;
+  while (current !== dest) {
+    try { fs.rmdirSync(current); } catch { break; }
+    current = path.dirname(current);
+  }
+}
+
+ensureSafeParent(manifestPath, true);
+if (fs.existsSync(manifestPath) && fs.lstatSync(manifestPath).isSymbolicLink()) fail(`refusing to replace symlink: ${manifestPath}`);
+const manifestTemp = `${manifestPath}.tmp.${process.pid}.${crypto.randomBytes(6).toString("hex")}`;
+try {
+  fs.writeFileSync(manifestTemp, `${JSON.stringify({ schema_version: "1.0", files: incoming.map((entry) => ({ path: entry.rel, sha256: entry.hash })) }, null, 2)}\n`, { flag: "wx" });
+  fs.renameSync(manifestTemp, manifestPath);
+} finally {
+  fs.rmSync(manifestTemp, { force: true });
+}

package/scripts/liveness/relay.sh

@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+# relay.sh — OPTIONAL console liveness relay (#295, ADR 0021 §4/§7).
+#
+# Mirrors a single liveness event (claim/heartbeat/release) to the hosted Console as a
+# `kontour.console.liveness` record, reusing the telemetry transport's shared `console_post_json`
+# (endpoint-allow gate, Bearer + tenant auth, timeouts, temp-file handling, detached fire — one core,
+# never forked). The Console side ingests this record type and projects the fleet view + runs the
+# janitor (console repo #125); this script is only the flow-agents EMIT half.
+#
+# STRICTLY OPTIONAL and local-first (ADR 0012 §5): a no-op unless FLOW_AGENTS_CONSOLE_LIVENESS_RELAY
+# is enabled AND a console endpoint is configured. Best-effort throughout — it must NEVER block, slow,
+# or fail the local liveness write that already happened before this was invoked. Every failure path
+# is a quiet `exit 0`.
+#
+# Invoked (fully detached, best-effort) from scripts/hooks/lib/liveness-write.js after the durable
+# local append. Usage: relay.sh '<liveness-event-json>'
+set -uo pipefail
+
+# Opt-in gate — off by default.
+case "${FLOW_AGENTS_CONSOLE_LIVENESS_RELAY:-}" in
+  1 | true | TRUE | yes | on) ;;
+  *) exit 0 ;;
+esac
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" || exit 0
+
+# transport.sh sources ${TELEMETRY_DIR}/lib/redact.sh at load — point it at the telemetry lib dir,
+# then reuse the SAME console POST core the telemetry mirror uses.
+export TELEMETRY_DIR="${TELEMETRY_DIR:-$SCRIPT_DIR/../telemetry}"
+[[ -f "$TELEMETRY_DIR/lib/transport.sh" ]] || exit 0
+# shellcheck source=/dev/null
+source "$TELEMETRY_DIR/lib/transport.sh" 2>/dev/null || exit 0
+
+# Resolve the liveness records endpoint: an explicit override wins, else the base console URL + /records
+# ("POST /records with a liveness record type"). No console configured ⇒ no-op.
+endpoint="${FLOW_AGENTS_CONSOLE_LIVENESS_ENDPOINT_URL:-}"
+if [[ -z "$endpoint" ]]; then
+  base="${FLOW_AGENTS_CONSOLE_URL:-${CONSOLE_TELEMETRY_URL:-${CONSOLE_URL:-}}}"
+  [[ -z "$base" ]] && exit 0
+  endpoint="${base%/}/records"
+fi
+
+# Auth reuses the env names console_post_json reads (CONSOLE_TELEMETRY_TOKEN / CONSOLE_TENANT_ID),
+# accepting FLOW_AGENTS_CONSOLE_* aliases and an optional token file. Never fatal on a missing/bad
+# token — console_post_json only adds a header when the value passes its safety check.
+if [[ -z "${CONSOLE_TELEMETRY_TOKEN:-}" ]]; then
+  token_file="${FLOW_AGENTS_CONSOLE_TOKEN_FILE:-${CONSOLE_TELEMETRY_TOKEN_FILE:-}}"
+  if [[ -n "$token_file" && -r "$token_file" ]]; then
+    CONSOLE_TELEMETRY_TOKEN="$(tr -d '\r\n' < "$token_file" 2>/dev/null || true)"
+    export CONSOLE_TELEMETRY_TOKEN
+  fi
+fi
+if [[ -z "${CONSOLE_TENANT_ID:-}" && -n "${FLOW_AGENTS_CONSOLE_TENANT:-}" ]]; then
+  export CONSOLE_TENANT_ID="$FLOW_AGENTS_CONSOLE_TENANT"
+fi
+
+# The liveness event arrives as a single JSON argument.
+event_json="${1:-}"
+[[ -z "$event_json" ]] && exit 0
+
+# Build the kontour.console.liveness record with jq — guarantees valid JSON and, critically,
+# proper string escaping of every untrusted field (actor/subjectId/branch/artifact_dir), so hostile
+# control bytes are \u-escaped rather than emitted raw (injection discipline). No jq ⇒ no-op.
+command -v jq >/dev/null 2>&1 || exit 0
+record="$(printf '%s' "$event_json" | jq -c '{
+  schema: "kontour.console.liveness",
+  version: "0.1",
+  type: (.type // "claim"),
+  subjectId: .subjectId,
+  actor: .actor,
+  actor_key: (.actor_key // .actorKey // null),
+  at: .at,
+  ttlSeconds: (.ttlSeconds // null),
+  host: (.host // null),
+  branch: (.branch // null),
+  artifact_dir: (.artifact_dir // .artifactDir // null)
+}' 2>/dev/null)" || exit 0
+[[ -z "$record" || "$record" == "null" ]] && exit 0
+
+# Optional field redaction (default none — jq escaping already neutralizes injection), then the
+# shared best-effort POST. console_post_json enforces the https/localhost endpoint-allow gate.
+processed="$(redact_event "$record" "${FLOW_AGENTS_CONSOLE_LIVENESS_REDACT:-none}")"
+console_post_json "$endpoint" "$processed"
+exit 0

package/scripts/telemetry/economics-record.schema.json

@@ -0,0 +1,145 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://kontourai.dev/schemas/kontour.console.economics/0.1.json",
+  "title": "kontour.console.economics",
+  "description": "Per-run kit-economics record (flow-agents #349, console ADR 0003). Immutable per-run fact: cost, time, iterations, and defects caught. cost and defects are co-required (R7 Goodhart guard).",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["schema", "version", "run_id", "cost", "time", "iterations", "defects"],
+  "properties": {
+    "schema": { "const": "kontour.console.economics" },
+    "version": { "const": "0.1" },
+    "run_id": { "type": "string" },
+    "at": { "type": ["string", "null"] },
+    "task_slug": { "type": ["string", "null"] },
+    "model": { "type": ["string", "null"] },
+    "pricing_version": { "type": ["string", "null"] },
+    "cost": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": [
+        "input_tokens",
+        "output_tokens",
+        "cache_creation_input_tokens",
+        "cache_read_input_tokens",
+        "estimated_cost_usd",
+        "by_model"
+      ],
+      "properties": {
+        "input_tokens": { "type": "number" },
+        "output_tokens": { "type": "number" },
+        "cache_creation_input_tokens": { "type": "number" },
+        "cache_read_input_tokens": { "type": "number" },
+        "estimated_cost_usd": { "type": "number" },
+        "by_model": { "type": "array" }
+      }
+    },
+    "time": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["wall_clock_s", "human_wait_s"],
+      "properties": {
+        "wall_clock_s": { "type": "number" },
+        "human_wait_s": { "type": "number" }
+      }
+    },
+    "phases": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "required": ["phase"],
+        "properties": {
+          "phase": { "type": "string" },
+          "input_tokens": { "type": "number" },
+          "output_tokens": { "type": "number" },
+          "cache_creation_input_tokens": { "type": "number" },
+          "cache_read_input_tokens": { "type": "number" },
+          "estimated_cost_usd": { "type": "number" },
+          "wall_clock_s": { "type": "number" }
+        }
+      }
+    },
+    "iterations": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["count", "route_backs"],
+      "properties": {
+        "count": { "type": "number" },
+        "route_backs": { "type": "number" }
+      }
+    },
+    "defects": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": [
+        "gate_fires",
+        "findings_by_severity",
+        "caught_false_completions",
+        "verification_verdict"
+      ],
+      "properties": {
+        "gate_fires": { "type": "number" },
+        "findings_by_severity": {
+          "type": "object",
+          "additionalProperties": true,
+          "required": ["critical", "high", "medium", "low"],
+          "properties": {
+            "critical": { "type": "number" },
+            "high": { "type": "number" },
+            "medium": { "type": "number" },
+            "low": { "type": "number" }
+          }
+        },
+        "caught_false_completions": { "type": "number" },
+        "verification_verdict": {
+          "type": "string",
+          "enum": ["PASS", "FAIL", "NOT_VERIFIED"]
+        }
+      }
+    },
+    "delegations": {
+      "type": "array",
+      "description": "Per-sub-agent delegation facts (#415), one entry per delegated agent_id, joined from <slug>/agents/<agent-id>/events.jsonl (latest delegation/escalation event wins for role/model; outcome derived from the agent's full event set). No per-delegation cost (no runtime isolates per-sub-agent tokens yet — see signals.per_delegation_tokens; cost-per-(role,model) is a console projection). Empty when no --agents-dir or no delegations.",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "required": ["role", "resolved_model"],
+        "properties": {
+          "agent_id": { "type": ["string", "null"] },
+          "role": { "type": "string" },
+          "resolved_model": { "type": "string" },
+          "summary": { "type": ["string", "null"] },
+          "escalated_from": { "type": "string" },
+          "dispatch_count": {
+            "type": "number",
+            "description": "How many times the orchestrator (re)dispatched this agent_id (delegation + escalation events). >1 means it was re-prompted — an orchestrator-observable rework signal that needs no sub-agent introspection."
+          },
+          "outcome": {
+            "type": "string",
+            "description": "Derived ONLY from real recorded signals, never fabricated. 'unavailable' = no terminal verdict recorded on this harness, distinct from a real accept.",
+            "enum": ["accepted", "rework", "diverged", "failed", "unavailable"]
+          }
+        }
+      }
+    },
+    "signals": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "What telemetry the current runtime actually exposed (harness-capability declaration — see docs/specs/harness-capability-matrix.md). Lets a consumer distinguish a real zero from a harness-blind gap.",
+      "properties": {
+        "runtime": { "type": ["string", "null"] },
+        "per_delegation_tokens": {
+          "type": "boolean",
+          "description": "Whether the runtime isolates per-sub-agent token usage. False on every runtime today → per-delegation cost is unavailable."
+        },
+        "per_delegation_outcome": {
+          "type": "string",
+          "enum": ["full", "partial", "none", "n/a"],
+          "description": "Coverage of the per-delegation outcome signal on this run: full=every delegation has a real outcome; partial=some; none=delegations exist but none had a verdict/escalation; n/a=no delegations observed."
+        }
+      }
+    },
+    "tenant_id": { "type": ["string", "null"] }
+  }
+}