@kontourai/flow-agents 3.12.1 → 4.1.0

package/src/narrative/intent-economics.ts

@@ -0,0 +1,119 @@
+/**
+ * #622 (R6/AC5): annotation-on/off A/B token measurement with uncertainty.
+ *
+ * `appendIntentEconomics` is an append-only local sink mirroring
+ * narrative-render.ts:appendEconomics (O_APPEND|O_CREAT|O_WRONLY, no-follow,
+ * 0600). `reduceIntentEconomics` is a NET-NEW pure paired-delta reducer: it
+ * pairs annotation_on/off samples in order and reports the MEAN delta together
+ * with an uncertainty spread (sample standard deviation + observed range) for
+ * each metric. No external stats dependency.
+ *
+ * This is the measurement MECHANISM + dry-run harness; scaled behavioral deltas
+ * across many real runs feed #612.
+ *
+ * @module
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export const INTENT_ECONOMICS_FILE = "intent-economics.jsonl";
+
+export type IntentAnnotationMode = "annotation_on" | "annotation_off";
+
+export interface IntentEconomicsRecord {
+  mode: IntentAnnotationMode;
+  input_tokens: number;
+  output_tokens: number;
+  wall_clock_ms: number;
+  attempted_at: string;
+}
+
+export function appendIntentEconomics(dir: string, record: IntentEconomicsRecord): void {
+  const file = path.join(dir, INTENT_ECONOMICS_FILE);
+  if (fs.existsSync(file)) {
+    const stat = fs.lstatSync(file);
+    if (stat.isSymbolicLink() || !stat.isFile()) throw new Error(`refusing unsafe intent economics target at ${file}`);
+  }
+  const noFollow = typeof fs.constants.O_NOFOLLOW === "number" ? fs.constants.O_NOFOLLOW : 0;
+  const descriptor = fs.openSync(file, fs.constants.O_APPEND | fs.constants.O_CREAT | fs.constants.O_WRONLY | noFollow, 0o600);
+  try { fs.writeSync(descriptor, `${JSON.stringify(record)}\n`, undefined, "utf8"); }
+  finally { fs.closeSync(descriptor); }
+}
+
+/**
+ * A mean delta reported WITH its uncertainty spread (never a bare point estimate).
+ *
+ * #622 (review MEDIUM A/B): an EMPTY window (no paired samples) reports
+ * `has_data:false` rather than a false-precise `{mean:0, sample_std:0, min:0,
+ * max:0}` — a consumer must not misread "we measured nothing" as "we measured and
+ * confirmed a null delta". `n` is retained in both shapes.
+ */
+export type IntentEconomicsDelta =
+  | { has_data: false; n: 0 }
+  | {
+      has_data: true;
+      /** Number of paired (on,off) deltas contributing to this metric. */
+      n: number;
+      mean: number;
+      /** Sample standard deviation (Bessel-corrected); 0 for a single pair. */
+      sample_std: number;
+      min: number;
+      max: number;
+    };
+
+export interface IntentEconomicsSummary {
+  pairs: number;
+  on_samples: number;
+  off_samples: number;
+  delta_input_tokens: IntentEconomicsDelta;
+  delta_output_tokens: IntentEconomicsDelta;
+  delta_wall_clock_ms: IntentEconomicsDelta;
+}
+
+function summarizeDeltas(values: readonly number[]): IntentEconomicsDelta {
+  const n = values.length;
+  // #622 (review MEDIUM A/B): an empty window is NOT a confirmed zero delta.
+  if (n === 0) return { has_data: false, n: 0 };
+  const mean = values.reduce((sum, value) => sum + value, 0) / n;
+  // Bessel-corrected sample variance; a single pair has undefined spread -> 0.
+  const variance = n > 1 ? values.reduce((sum, value) => sum + (value - mean) ** 2, 0) / (n - 1) : 0;
+  return { has_data: true, n, mean, sample_std: Math.sqrt(variance), min: Math.min(...values), max: Math.max(...values) };
+}
+
+export function reduceIntentEconomics(records: readonly IntentEconomicsRecord[]): IntentEconomicsSummary {
+  const on = records.filter((record) => record.mode === "annotation_on");
+  const off = records.filter((record) => record.mode === "annotation_off");
+  const pairs = Math.min(on.length, off.length);
+  const inputDeltas: number[] = [];
+  const outputDeltas: number[] = [];
+  const wallDeltas: number[] = [];
+  // #622 (review LOW, disclosed mechanism-scope): pairs annotation_on/off samples
+  // by INDEX for the dry-run harness (not by attempted_at / matched conditions);
+  // scaled cross-run attribution is sequenced to #612.
+  for (let index = 0; index < pairs; index += 1) {
+    inputDeltas.push(on[index].input_tokens - off[index].input_tokens);
+    outputDeltas.push(on[index].output_tokens - off[index].output_tokens);
+    wallDeltas.push(on[index].wall_clock_ms - off[index].wall_clock_ms);
+  }
+  return {
+    pairs,
+    on_samples: on.length,
+    off_samples: off.length,
+    delta_input_tokens: summarizeDeltas(inputDeltas),
+    delta_output_tokens: summarizeDeltas(outputDeltas),
+    delta_wall_clock_ms: summarizeDeltas(wallDeltas),
+  };
+}
+
+/** Read + parse an intent-economics.jsonl sink into typed records (skips blank lines). */
+export function readIntentEconomics(dir: string): IntentEconomicsRecord[] {
+  const file = path.join(dir, INTENT_ECONOMICS_FILE);
+  if (!fs.existsSync(file)) return [];
+  const stat = fs.lstatSync(file);
+  if (stat.isSymbolicLink() || !stat.isFile()) throw new Error(`refusing unsafe intent economics target at ${file}`);
+  return fs.readFileSync(file, "utf8")
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0)
+    .map((line) => JSON.parse(line) as IntentEconomicsRecord);
+}

package/src/narrative/intent.ts

@@ -0,0 +1,216 @@
+/**
+ * #622: bounded, capability-declared, at-action stated-intent capture.
+ *
+ * `captureIntent` is PURE (no I/O). It takes a caller-resolved capability status
+ * (the CLI resolves it via queryCapability(runtime, "intent_annotation") — this
+ * module deliberately does NOT import the capability table so it stays inside the
+ * #619 narrative import boundary) and an OPTIONAL agent-supplied bounded purpose:
+ *
+ *   - supported + a purpose that survives the policy filter -> an `agent_stated`
+ *     statement (typed self-report, never proof).
+ *   - otherwise -> a deterministic `workflow_derived_purpose` statement derived
+ *     ONLY from the active gate reference. The else-branch is STRUCTURALLY
+ *     incapable of emitting `agent_stated` (R4: no fabricated rationale).
+ *
+ * `bindIntentAnnotation` freezes the captured annotation into a write-once
+ * channel (link(2)/EEXIST, mirroring snapshot.ts:createOnlyWriteManifest). A
+ * post-hoc / second write to an already-frozen channel fails EEXIST and is
+ * structurally rejected (R1/AC3): there is no mutable, late-writable side
+ * channel for reconstructed rationale.
+ *
+ * Imports are restricted to node builtins, ./-relative narrative files, and the
+ * shared ../lib/fs.js helper (the #619 arch-isolation test enforces this).
+ *
+ * @module
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { atomicWriteFile } from "../lib/fs.js";
+import { effectiveNarrativeRedactionFields, filterNarrativeRecord } from "./policy-filter.js";
+import { agentStatedIntent, workflowDerivedPurpose, type Statement } from "./statements.js";
+
+/**
+ * Structural mirror of capability-declarations.ts:CapabilityStatus. Declared
+ * locally so this module never imports the capability table (which is outside
+ * the narrative import boundary); a real `CapabilityStatus` is assignable here.
+ */
+export type IntentCapabilityStatus =
+  | { readonly status: "supported" }
+  | { readonly status: "partial"; readonly note: string }
+  | { readonly status: "unsupported"; readonly reason: string };
+
+export type IntentCaptureMode = "agent_stated" | "workflow_derived_purpose";
+
+export interface CaptureIntentInput {
+  /** Caller-resolved capability status (queryCapability(runtime,"intent_annotation")). */
+  capability: IntentCapabilityStatus;
+  /** Attributed actor for the self-report (required for agent_stated). */
+  actor: string;
+  /** Runtime id, recorded for provenance. */
+  runtimeId: string;
+  /** fa1 source id of the material action being annotated (the citation). */
+  actionRef: string;
+  /** fa1 source id of the active gate/operation — the ONLY input to the fallback derivation. */
+  activeGateRef: string;
+  /** Optional agent-supplied bounded purpose (redactable narrative source). */
+  purpose?: string;
+  /** Optional fa1 source id of the objective, cited by the fallback. */
+  objectiveRef?: string;
+  /** Effective redaction fields; defaults to effectiveNarrativeRedactionFields(). */
+  redactionFields?: readonly string[];
+  turnRef?: number;
+}
+
+export interface CapturedIntent {
+  mode: IntentCaptureMode;
+  statement: Statement;
+  runtime: string;
+  action_ref: string;
+  /**
+   * The action source's OWN frozen-manifest `captured_at` (R1 temporal co-binding).
+   * Derived from the resolved action entry — NOT a fresh clock read at bind time —
+   * so a forged or late annotation cannot claim at-action timing for an action it
+   * did not co-occur with.
+   */
+  action_captured_at: string;
+  /** Redaction field names that nulled the supplied purpose (empty when none applied). */
+  redactions: string[];
+}
+
+/**
+ * Dependencies for {@link captureIntent}. `resolveAction` resolves the material
+ * action's fa1 id to its FROZEN MANIFEST ENTRY (existence + the action's own
+ * `capturedAt`) — R1 co-binding. It returns `undefined` for an absent / fabricated
+ * ref (or an unreadable manifest), which captureIntent rejects. Injected so the pure
+ * capture logic stays testable and this module never itself does I/O — the CLI wires
+ * in `(ref) => resolveManifestEntry(narrativeDir, ref)`.
+ */
+export interface CaptureIntentDependencies {
+  resolveAction: (actionRef: string) => { capturedAt: string } | undefined;
+}
+
+/**
+ * Route the agent-supplied purpose through the policy-filtered view (D5/R7). A
+ * redacted `purpose` field is nulled BEFORE emission — a nulled purpose never
+ * reaches an agent_stated statement (capture falls back to workflow_derived).
+ * A policy that is unresolvable/invalid fails closed (treated as redacted).
+ */
+function filterPurpose(purpose: string, redactionFields: readonly string[]): { purpose?: string; redactions: string[] } {
+  const filtered = filterNarrativeRecord({ purpose }, redactionFields);
+  if (filtered.kind !== "filtered") return { redactions: filtered.fields };
+  const value = filtered.record.purpose;
+  // #622 (review LOW): the record handed to filterNarrativeRecord is the FLAT
+  // single-key shape `{ purpose }`, so an actual purpose redaction is reported as
+  // exactly the field `"purpose"`. Matching `.endsWith(".purpose")` would let an
+  // unrelated `foo.purpose`-style redaction masquerade as a purpose redaction; only
+  // the exact flat key is a real purpose redaction for this record.
+  const redactions = filtered.redactions.filter((field) => field === "purpose");
+  return typeof value === "string" && value.length > 0 ? { purpose: value, redactions } : { redactions };
+}
+
+export function captureIntent(input: CaptureIntentInput, deps: CaptureIntentDependencies): CapturedIntent {
+  // R1 (review HIGH): the annotation MUST cite a material action that actually
+  // exists in the FROZEN narrative manifest. Resolve the action ref to its frozen
+  // manifest entry; a fabricated / nonexistent action (absent from the manifest, or
+  // an unreadable manifest) is rejected outright — you cannot annotate an action
+  // that is not in the frozen manifest.
+  const actionEntry = deps.resolveAction(input.actionRef);
+  if (actionEntry === undefined) {
+    throw new Error(
+      `intent capture requires a resolvable frozen action source: ${input.actionRef} is not present in the frozen narrative manifest`,
+    );
+  }
+  // Co-bind timing to the action's OWN frozen captured_at (not a fresh clock),
+  // so a forged/late annotation cannot claim at-action timing.
+  const actionCapturedAt = actionEntry.capturedAt;
+
+  const redactionFields = input.redactionFields ?? effectiveNarrativeRedactionFields();
+  const { purpose, redactions } = typeof input.purpose === "string" && input.purpose.length > 0
+    ? filterPurpose(input.purpose, redactionFields)
+    : { purpose: undefined, redactions: [] as string[] };
+
+  if (input.capability.status === "supported" && purpose !== undefined) {
+    return {
+      mode: "agent_stated",
+      statement: agentStatedIntent({
+        sourceId: input.actionRef,
+        purpose,
+        actor: input.actor,
+        ...(input.turnRef !== undefined ? { turnRef: input.turnRef } : {}),
+      }),
+      runtime: input.runtimeId,
+      action_ref: input.actionRef,
+      action_captured_at: actionCapturedAt,
+      redactions,
+    };
+  }
+
+  // Structural guarantee (R4): the fallback branch can NEVER emit agent_stated —
+  // it only ever constructs a deterministic_derived workflow_derived_purpose.
+  return {
+    mode: "workflow_derived_purpose",
+    statement: workflowDerivedPurpose({
+      activeGateRef: input.activeGateRef,
+      ...(input.objectiveRef ? { objectiveRef: input.objectiveRef } : {}),
+    }),
+    runtime: input.runtimeId,
+    action_ref: input.actionRef,
+    action_captured_at: actionCapturedAt,
+    redactions,
+  };
+}
+
+export const INTENT_ANNOTATION_FILE = "intent-annotation.json";
+export const INTENT_ANNOTATION_SCHEMA_VERSION = "1.0" as const;
+
+export interface IntentAnnotation {
+  schema_version: typeof INTENT_ANNOTATION_SCHEMA_VERSION;
+  mode: IntentCaptureMode;
+  /**
+   * The material action's OWN frozen-manifest captured_at (R1 temporal co-binding).
+   * Derived from the resolved action entry at capture time — NOT a fresh wall-clock
+   * read at bind time — so a fabricated/late annotation cannot claim at-action
+   * timing for an action it did not co-occur with.
+   */
+  captured_at: string;
+  runtime: string;
+  action_ref: string;
+  statement: Statement;
+  redactions: string[];
+}
+
+/**
+ * Freeze a captured annotation into a write-once channel (R1/AC3). Uses the same
+ * create-only link(2)/EEXIST discipline as snapshot.ts:createOnlyWriteManifest:
+ * a second/late write to an already-frozen channel throws (EEXIST), so a
+ * post-hoc-reconstructed rationale can never overwrite or masquerade as the
+ * at-action annotation. `captured_at` is carried from the resolved action entry
+ * (see {@link captureIntent}), co-binding the annotation to the real action
+ * capture rather than to bind-time wall-clock.
+ */
+export function bindIntentAnnotation(
+  channelDir: string,
+  captured: CapturedIntent,
+): { path: string; annotation: IntentAnnotation } {
+  const annotation: IntentAnnotation = {
+    schema_version: INTENT_ANNOTATION_SCHEMA_VERSION,
+    mode: captured.mode,
+    captured_at: captured.action_captured_at,
+    runtime: captured.runtime,
+    action_ref: captured.action_ref,
+    statement: captured.statement,
+    redactions: captured.redactions,
+  };
+  const file = path.join(channelDir, INTENT_ANNOTATION_FILE);
+  const temp = path.join(channelDir, `.intent-annotation.${process.pid}.${Date.now().toString(36)}.tmp`);
+  atomicWriteFile(channelDir, temp, Buffer.from(`${JSON.stringify(annotation, null, 2)}\n`));
+  try {
+    fs.linkSync(temp, file);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "EEXIST") throw new Error("intent annotation channel already frozen");
+    throw error;
+  } finally {
+    fs.rmSync(temp, { force: true });
+  }
+  return { path: file, annotation };
+}

package/src/narrative/policy-filter.ts

@@ -0,0 +1,66 @@
+/** Mirrors scripts/telemetry/lib/config.sh TELEMETRY_CHANNEL_FULL_REDACT. */
+export const TELEMETRY_CHANNEL_FULL_REDACT_DEFAULT = ["hook.raw_input", "turn.prompt_text", "tool.input", "tool.output"] as const;
+
+/** Mirrors scripts/telemetry/lib/config.sh TELEMETRY_CHANNEL_ANALYTICS_REDACT. */
+export const TELEMETRY_CHANNEL_ANALYTICS_REDACT_DEFAULT = [
+  "tool.input", "tool.output", "turn.prompt_text", "delegation.targets.query",
+  "context.cwd", "hook.raw_input", "hook.last_assistant_message", "hook.transcript_path",
+] as const;
+
+export type NarrativePolicyFilterResult =
+  | { kind: "filtered"; record: Record<string, unknown>; redactions: string[] }
+  | { kind: "redacted"; fields: string[]; diagnostic: string };
+
+function uniqueFields(fields: readonly string[]): string[] {
+  return [...new Set(fields.map((field) => field.trim()).filter(Boolean))];
+}
+
+export function effectiveNarrativeRedactionFields(narrativeFields: readonly string[] = []): string[] {
+  return uniqueFields([...TELEMETRY_CHANNEL_FULL_REDACT_DEFAULT, ...narrativeFields]);
+}
+
+function failure(fields: readonly string[], diagnostic: string): NarrativePolicyFilterResult {
+  return { kind: "redacted", fields: uniqueFields(fields), diagnostic };
+}
+
+export function filterNarrativeRecord(
+  input: unknown,
+  effectiveFields: readonly string[] | null | undefined,
+): NarrativePolicyFilterResult {
+  if (!Array.isArray(effectiveFields)) return failure([], "redaction policy is unresolvable");
+  const fields = uniqueFields(effectiveFields);
+  if (fields.some((field) => !field.split(".").every((part) => part.length > 0 && part !== "__proto__" && part !== "prototype" && part !== "constructor"))) {
+    return failure(fields, `redaction policy contains an invalid field name: ${fields.join(", ")}`);
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = typeof input === "string" || Buffer.isBuffer(input) ? JSON.parse(input.toString()) : structuredClone(input);
+  } catch {
+    return failure(fields, `record could not be parsed under fields: ${fields.join(", ")}`);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return failure(fields, `record is not an object under fields: ${fields.join(", ")}`);
+
+  const record = parsed as Record<string, unknown>;
+  try {
+    for (const field of fields) {
+      const parts = field.split(".");
+      let cursor: Record<string, unknown> = record;
+      for (const part of parts.slice(0, -1)) {
+        const next = cursor[part];
+        if (next === undefined || next === null) {
+          cursor[part] = {};
+          cursor = cursor[part] as Record<string, unknown>;
+        } else if (typeof next === "object" && !Array.isArray(next)) {
+          cursor = next as Record<string, unknown>;
+        } else {
+          throw new Error(field);
+        }
+      }
+      cursor[parts.at(-1)!] = null;
+    }
+  } catch {
+    return failure(fields, `field nulling failed for fields: ${fields.join(", ")}`);
+  }
+  return { kind: "filtered", record, redactions: fields };
+}