productfoo 0.0.0-stage → 1.0.1

package/dist-public/src/feedback.js

@@ -0,0 +1,294 @@
+// alpha-distribution-telemetry-v0 (T-009 / T-010 / T-011) — satisfaction signal,
+// friction-triggered error feedback, and the consented eval-capture lane.
+//
+// D-011: reuse the existing telemetry substrate — the append-only
+// `.foo/agent-events.jsonl` ledger, the pseudonymous tester id, and the
+// enabled/opt-out gate — never a parallel ledger. Existing ledger readers
+// filter by `event_type`, so the new `feedback` events are additive and ignored
+// by `foo agent logs`.
+//
+// D-010: every default signal is CONTENT-FREE. Solicited free-text is
+// redacted-before-store (same engine as B1). The ONLY place raw (idea, record)
+// content is retained is the explicit opt-in eval lane (T-011) — encrypted at
+// rest, TTL'd, and tester-deletable. Not opted in ⇒ nothing beyond the envelope.
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { readJson } from "./jsonFile.js";
+import path from "node:path";
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+import { agentLogPath, nextAgentEventId, readAgentTelemetryConfig, resolveTesterId } from "./commands/agent.js";
+import { redactText } from "./redactEngine.js";
+// Gate: opted-in config AND not DO_NOT_TRACK — the same posture as recordCliUsage,
+// so feedback honors the exact opt-out testers already have (OQ-4 / D-010).
+export function feedbackEnabled(root, env = process.env) {
+    if (env.DO_NOT_TRACK === "1" || env.DO_NOT_TRACK === "true")
+        return false;
+    return readAgentTelemetryConfig(root).config.enabled;
+}
+// Redact a tester-authored note before it is ever stored (D-010). Returns the
+// redacted text and the count of spans removed — never the secret value.
+export function redactNote(note) {
+    const result = redactText(note, { threshold: "medium" });
+    return { text: result.redactedText, redactions: result.receipt.redactions };
+}
+// Append a content-free feedback event to the shared ledger. Fire-and-forget:
+// like recordCliUsage, a failure here never alters CLI behavior.
+export function recordFeedback(root, event, env = process.env) {
+    try {
+        if (!feedbackEnabled(root, env))
+            return null;
+        const testerId = resolveTesterId(root);
+        const full = {
+            schema_version: "0.1",
+            event_type: "feedback",
+            id: nextAgentEventId(),
+            timestamp: new Date().toISOString(),
+            ...event,
+            ...(testerId ? { tester_id: testerId } : {}),
+        };
+        const logPath = agentLogPath(root);
+        mkdirSync(path.dirname(logPath), { recursive: true });
+        appendFileSync(logPath, `${JSON.stringify(full)}\n`);
+        return full;
+    }
+    catch {
+        return null;
+    }
+}
+// Revealed preference (T-009): behavioral, zero-friction, no content. The
+// strongest satisfaction signal — what the tester DID with the output.
+export function recordRevealed(root, kind, ctx = {}, env = process.env) {
+    return recordFeedback(root, { signal: "revealed", kind, ...ctx }, env);
+}
+// Sampled solicited micro-poll (T-009): one keystroke → a small integer rating.
+export function recordRating(root, rating, ctx = {}, env = process.env) {
+    return recordFeedback(root, { signal: "solicited", kind: "rating", rating, ...ctx }, env);
+}
+// Spontaneous `foo feedback "..."` (T-009): tester-authored product feedback,
+// redacted-before-store. The text is the tester's, about the product — never
+// their idea/prompt — but it is scrubbed for secrets all the same (B1).
+export function recordSpontaneous(root, note, env = process.env) {
+    const { text, redactions } = redactNote(note);
+    return recordFeedback(root, { signal: "solicited", kind: "spontaneous", note: text, redactions }, env);
+}
+// Revealed preference from an ideate record (T-009): the strongest signal is
+// whether the human kept the AI's recommendation or overrode it. Content-free —
+// it compares the record's `recommendation:` and `pick:` fields and returns only
+// the CLASS ("override" | "kept"), never either value. "undecided" = no pick yet;
+// null = decided but nothing to compare against.
+export function classifyDecision(recordText) {
+    const grab = (re) => recordText.match(re)?.[1] ?? null;
+    const norm = (v) => {
+        if (v == null)
+            return null;
+        const t = v.trim().replace(/^["']|["']$/g, "").trim();
+        return t === "" || t === "null" ? null : t;
+    };
+    const rec = norm(grab(/^recommendation:\s*(.+)$/m));
+    const pick = norm(grab(/^pick:\s*(.+)$/m));
+    if (pick == null)
+        return "undecided";
+    if (rec == null)
+        return null;
+    return rec === pick ? "kept" : "override";
+}
+// Fire-and-forget instrumentation for `foo ideate check`: read the record,
+// classify the decision, and record the content-free revealed event. Never
+// throws, never alters the caller's exit code (mirrors recordCliUsage).
+export function recordIdeateDecision(root, recordPath, env = process.env) {
+    try {
+        if (!feedbackEnabled(root, env))
+            return null;
+        const full = path.resolve(root, recordPath);
+        if (!existsSync(full))
+            return null;
+        const kind = classifyDecision(readFileSync(full, "utf8"));
+        if (kind === "override" || kind === "kept") {
+            recordRevealed(root, kind, { domain: "ideate", command: "ideate check" }, env);
+            return kind;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+// --- friction-triggered feedback (T-010) -------------------------------------
+// Error classes that are transient / auto-recovered — never worth interrupting
+// a tester over. A blip that recovers is not a satisfaction event.
+export const TRANSIENT_ERROR_CLASSES = new Set(["offline", "network", "io_error", "none"]);
+// Decide whether to interrupt the tester after an error. Only on a real
+// (non-transient) failure, and only a sampled fraction of the time — over-
+// prompting trains reflexive dismissal and destroys the signal (D-012).
+export function shouldPromptOnError(errorClass, opts = {}) {
+    if (TRANSIENT_ERROR_CLASSES.has(errorClass))
+        return false;
+    const rate = opts.sampleRate ?? 0.5;
+    const draw = (opts.sampler ?? Math.random)();
+    return draw < rate;
+}
+export const ERROR_REASON_CODES = ["too_slow", "wrong", "crashed", "other"];
+// Record the tester's answer to "what happened?". The structured reason is the
+// analyzable label (D-012); an optional free-text note (on "other") is redacted
+// before it is stored. The content-free cli_usage error event fires separately
+// and unconditionally (recordCliUsage) — this only adds the human's intent.
+export function recordErrorFeedback(root, input, env = process.env) {
+    let note;
+    let redactions;
+    if (input.note && input.note.trim()) {
+        const r = redactNote(input.note);
+        note = r.text;
+        redactions = r.redactions;
+    }
+    return recordFeedback(root, {
+        signal: "friction",
+        kind: "error",
+        reason_code: input.reason_code,
+        ...(input.error_class ? { error_class: input.error_class } : {}),
+        ...(input.domain ? { domain: input.domain } : {}),
+        ...(input.command ? { command: input.command } : {}),
+        ...(note !== undefined ? { note, redactions } : {}),
+    }, env);
+}
+// The one-keystroke prompt the CLI renders after a real error. Kept as a pure
+// string so the copy is testable; the TTY read is a thin wrapper in the CLI.
+export function renderErrorPrompt() {
+    return "That didn't work. What happened?  [1] too slow  [2] output wrong  [3] crashed  [4] other  (enter to skip)";
+}
+export function reasonForKey(key) {
+    return { "1": "too_slow", "2": "wrong", "3": "crashed", "4": "other" }[key.trim()] ?? null;
+}
+// Feedback is durably recorded in the local ledger without network access.
+export function feedbackIsOfflineDurable() {
+    return true;
+}
+// --- consented eval-capture lane (T-011) -------------------------------------
+// The "separate consent gate" R-005/D-004 deferred, made concrete. Opt-in only.
+// Retains the (idea, record, label) triple for consenting testers — redacted,
+// AES-256-GCM encrypted at rest, TTL'd, and tester-visible/deletable.
+const EVAL_DIR = ".foo/eval-capture";
+const CONSENT_FILE = ".foo/eval-consent.json";
+function evalDir(root) {
+    return path.join(root, EVAL_DIR);
+}
+function consentPath(root) {
+    return path.join(root, CONSENT_FILE);
+}
+export function readEvalConsent(root) {
+    const p = consentPath(root);
+    if (!existsSync(p))
+        return false; // opt-IN: default is no capture
+    try {
+        return readJson(p).opted_in === true;
+    }
+    catch {
+        return false;
+    }
+}
+export function setEvalConsent(root, optedIn) {
+    mkdirSync(path.dirname(consentPath(root)), { recursive: true });
+    writeFileSync(consentPath(root), `${JSON.stringify({ schema_version: "0.1", opted_in: optedIn, updated: new Date().toISOString() }, null, 2)}\n`);
+}
+// Local at-rest key: 32 random bytes, mode 0600, gitignored under .foo. Genuine
+// encryption for the local skeleton (the hosted lane would use a managed key).
+function evalKey(root) {
+    const keyPath = path.join(evalDir(root), ".key");
+    if (existsSync(keyPath))
+        return Buffer.from(readFileSync(keyPath, "utf8"), "hex");
+    mkdirSync(evalDir(root), { recursive: true });
+    const key = randomBytes(32);
+    writeFileSync(keyPath, key.toString("hex"), { mode: 0o600 });
+    return key;
+}
+const DEFAULT_TTL_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
+// Capture a run for eval — ONLY if the tester opted in. Idea + record are
+// redacted (B1) then encrypted at rest. Returns the capture id, or null when
+// not consented (nothing is written). The label is the satisfaction signal
+// (e.g. "bad", "override") that makes this a curated example, not noise.
+export function captureForEval(root, triple, opts = {}) {
+    if (!readEvalConsent(root))
+        return null; // not opted in ⇒ retain nothing
+    const idea = redactNote(triple.idea);
+    const record = redactNote(triple.record);
+    const now = opts.now ?? Date.now();
+    const id = `ev_${now.toString(36)}_${randomBytes(4).toString("hex")}`;
+    const payload = JSON.stringify({ idea: idea.text, record: record.text, label: triple.label });
+    const key = evalKey(root);
+    const iv = randomBytes(12);
+    const cipher = createCipheriv("aes-256-gcm", key, iv);
+    const enc = Buffer.concat([cipher.update(payload, "utf8"), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    const meta = {
+        id,
+        captured_at: new Date(now).toISOString(),
+        expires_at: new Date(now + (opts.ttlMs ?? DEFAULT_TTL_MS)).toISOString(),
+        label: triple.label,
+        redactions: idea.redactions + record.redactions,
+    };
+    mkdirSync(evalDir(root), { recursive: true });
+    writeFileSync(path.join(evalDir(root), `${id}.enc`), JSON.stringify({ meta, iv: iv.toString("hex"), tag: tag.toString("hex"), data: enc.toString("hex") }));
+    return id;
+}
+// Tester-visible: list metadata only (never decrypts). This is the "show me
+// what's retained" surface the consent story requires.
+export function listEvalCaptures(root) {
+    const dir = evalDir(root);
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const f of readdirSync(dir)) {
+        if (!f.endsWith(".enc"))
+            continue;
+        try {
+            out.push(readJson(path.join(dir, f)).meta);
+        }
+        catch {
+            continue;
+        }
+    }
+    return out.sort((a, b) => a.captured_at.localeCompare(b.captured_at));
+}
+// Tester-deletable: forget one capture, or all of them.
+export function deleteEvalCapture(root, id) {
+    const p = path.join(evalDir(root), `${id}.enc`);
+    if (!existsSync(p))
+        return false;
+    rmSync(p);
+    return true;
+}
+export function forgetAllEvalCaptures(root) {
+    const before = listEvalCaptures(root);
+    for (const m of before)
+        deleteEvalCapture(root, m.id);
+    return before.length;
+}
+// TTL enforcement: drop expired captures. The maintainer (or a cron) calls this;
+// retention is a promise, so it must be mechanical, not aspirational.
+export function pruneExpiredEvalCaptures(root, now = Date.now()) {
+    let pruned = 0;
+    for (const m of listEvalCaptures(root)) {
+        if (new Date(m.expires_at).getTime() <= now) {
+            if (deleteEvalCapture(root, m.id))
+                pruned += 1;
+        }
+    }
+    return pruned;
+}
+// Decrypt one capture — the eval-set builder's read path (maintainer-side, with
+// the local key). Returns null if expired, tampered, or missing.
+export function readEvalCapture(root, id, now = Date.now()) {
+    const p = path.join(evalDir(root), `${id}.enc`);
+    if (!existsSync(p))
+        return null;
+    try {
+        const box = readJson(p);
+        if (new Date(box.meta.expires_at).getTime() <= now)
+            return null;
+        const decipher = createDecipheriv("aes-256-gcm", evalKey(root), Buffer.from(box.iv, "hex"));
+        decipher.setAuthTag(Buffer.from(box.tag, "hex"));
+        const dec = Buffer.concat([decipher.update(Buffer.from(box.data, "hex")), decipher.final()]).toString("utf8");
+        return JSON.parse(dec);
+    }
+    catch {
+        return null;
+    }
+}

package/dist-public/src/firefliesClient.d.ts

@@ -0,0 +1,106 @@
+export type FetchLike = typeof globalThis.fetch;
+export type FirefliesRuntimeErrorCode = "not_connected" | "auth_expired" | "access_denied" | "provider_failure" | "network" | "provider_timeout" | "transcript_too_large" | "budget_exhausted";
+export declare class FirefliesRuntimeError extends Error {
+    readonly code: FirefliesRuntimeErrorCode;
+    constructor(code: FirefliesRuntimeErrorCode, message: string);
+}
+export declare const FIREFLIES_POLICY: {
+    readonly policy_version: "fireflies-local-worker-0.1";
+    readonly max_response_bytes: number;
+    readonly fetch_timeout_ms: 90000;
+    readonly max_model_input_tokens: 100000;
+    readonly max_list_pages: 5;
+    readonly min_request_interval_ms: 350;
+};
+export type FirefliesConnectionEnv = Record<string, string | undefined>;
+export type FirefliesConnection = {
+    connection_ref: string;
+    broker: "direct";
+    credential: {
+        type: "key";
+        api_key: string;
+    };
+    transcript_access: "granted" | "unknown";
+};
+export declare function firefliesConnectionConfigured(env: FirefliesConnectionEnv): boolean;
+export declare function firefliesCredentialBroker(env: FirefliesConnectionEnv): "direct" | null;
+/**
+ * Resolve the user's Fireflies connection from the environment. No network, no
+ * broker: a direct read of FOO_FIREFLIES_API_KEY for one command. The key is
+ * never logged; the connection_ref is a stable hash of it so reports can name
+ * the connection without exposing it.
+ */
+export declare function resolveFirefliesConnection(input: {
+    env: FirefliesConnectionEnv;
+}): FirefliesConnection;
+export type FirefliesViewer = {
+    user_id?: string;
+    email?: string;
+};
+export type FirefliesListedTranscript = {
+    id: string;
+    title?: string;
+    started_at?: string;
+    ended?: string;
+    status?: string;
+    participants?: Array<{
+        display_name?: string;
+        email?: string;
+    }>;
+};
+export type FirefliesTranscript = {
+    title?: string;
+    speakers?: Array<{
+        name?: string;
+    }>;
+    sentences?: Array<{
+        text?: string;
+        start_date?: string;
+        end_date?: string;
+        speaker_id?: string;
+    }>;
+};
+type FirefliesClientOptions = {
+    fetchImpl: FetchLike;
+    baseUrl?: string;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+};
+/**
+ * Minimal read-only Fireflies GraphQL client. The single request() function is
+ * the write-refusal choke point (R-009): GraphQL speaks over POST, so a
+ * mutation is refused by inspecting the query text — the only read operations
+ * reachable are the three query constants above.
+ */
+export declare class FirefliesClient {
+    private readonly credential;
+    private readonly options;
+    readonly requests: {
+        viewer: number;
+        list: number;
+        transcript: number;
+    };
+    private lastRequestAt;
+    private readonly baseUrl;
+    private readonly sleep;
+    private readonly now;
+    constructor(credential: FirefliesConnection["credential"], options: FirefliesClientOptions);
+    private request;
+    /** Identity probe for readiness (R-005): the connection answers for one user. The result is never printed. */
+    probe(): Promise<FirefliesViewer>;
+    /** Bounded metadata listing: one time window, a page ceiling, no content fields requested. */
+    listTranscripts(window: {
+        from: string;
+        to: string;
+    }): Promise<{
+        transcripts: FirefliesListedTranscript[];
+        pages: number;
+        truncated: boolean;
+    }>;
+    /**
+     * Exactly one transcript's content (R-007). A fixture observes that the
+     * request carries a single well-formed identifier and nothing else.
+     */
+    transcript(id: string): Promise<FirefliesTranscript>;
+}
+export {};

package/dist-public/src/firefliesClient.js

@@ -0,0 +1,258 @@
+// Fireflies direct-key client (fireflies-discovery-connector-v0, local worker
+// mode, D-001).
+//
+// There is no broker: the credential is the user's own Fireflies API key (D-002
+// granola rule), read from this runtime's environment for one command, held in
+// process memory, never persisted or printed — an opaque `connection_ref` (a
+// hash of the key) stands in for it on every report. This is the structural
+// difference from gongNango (R-004: no Nango OAuth for this source): the broker
+// type is `"direct" | null`, so a nango-brokered Fireflies connection is not
+// even expressible here.
+//
+// Everything is content-free on every surface productfoo owns: errors carry a typed
+// code plus a bounded message that never embeds a provider response or key
+// material, responses are read under a byte ceiling, and the only HTTP paths
+// are the read queries below — any GraphQL mutation routes through the single
+// write-refusal choke point (R-009) so the refusal is testable, not scattered.
+//
+// Every provider shape below — the GraphQL endpoint, the auth header scheme,
+// the field names, offset pagination — is a BELIEF owned by the packet's
+// feasibility task (T-001, still open), pinned by fixtures in
+// test/discoveryFireflies.test.ts. Nothing here has ever spoken to the live
+// Fireflies API; the dogfood run (T-008) is what would promote these beliefs,
+// with receipts.
+import { createHash } from "node:crypto";
+import { refuseSourceWrite } from "./sourceIngress.js";
+export class FirefliesRuntimeError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "FirefliesRuntimeError";
+    }
+}
+// Versioned policy fields (R-006): hard ceilings the worker enforces and
+// reports, kept identical to GONG_POLICY's values so a later divergence is an
+// explicit decision — test/discoveryFireflies.test.ts pins the equality.
+export const FIREFLIES_POLICY = {
+    policy_version: "fireflies-local-worker-0.1",
+    max_response_bytes: 8 * 1024 * 1024,
+    fetch_timeout_ms: 90_000,
+    max_model_input_tokens: 100_000,
+    max_list_pages: 5,
+    min_request_interval_ms: 350,
+};
+const DEFAULT_FIREFLIES_BASE = "https://api.fireflies.ai";
+export function firefliesConnectionConfigured(env) {
+    return Boolean(env.FOO_FIREFLIES_API_KEY?.trim());
+}
+export function firefliesCredentialBroker(env) {
+    return firefliesConnectionConfigured(env) ? "direct" : null;
+}
+/**
+ * Resolve the user's Fireflies connection from the environment. No network, no
+ * broker: a direct read of FOO_FIREFLIES_API_KEY for one command. The key is
+ * never logged; the connection_ref is a stable hash of it so reports can name
+ * the connection without exposing it.
+ */
+export function resolveFirefliesConnection(input) {
+    const api_key = input.env.FOO_FIREFLIES_API_KEY?.trim();
+    if (!api_key) {
+        throw new FirefliesRuntimeError("not_connected", "Fireflies is not connected: set FOO_FIREFLIES_API_KEY to your own Fireflies API key");
+    }
+    return {
+        connection_ref: `fireflies:direct:${createHash("sha256").update(api_key).digest("hex").slice(0, 16)}`,
+        broker: "direct",
+        credential: { type: "key", api_key },
+        transcript_access: "unknown",
+    };
+}
+async function fetchWithTimeout(fetchImpl, url, init, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await fetchImpl(url, { ...init, signal: controller.signal });
+    }
+    catch (error) {
+        if (controller.signal.aborted)
+            throw new FirefliesRuntimeError("provider_timeout", "the provider did not answer within the fetch ceiling");
+        throw new FirefliesRuntimeError("network", `network failure reaching ${new URL(url).hostname}`);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+// Reads a response body while counting toward the byte ceiling, so an
+// oversized payload is dropped before it is ever materialized in full.
+async function readBounded(response, maxBytes) {
+    const declared = Number(response.headers.get("content-length") ?? "0");
+    if (Number.isFinite(declared) && declared > maxBytes)
+        throw new FirefliesRuntimeError("transcript_too_large", "the provider response exceeds the byte ceiling");
+    if (!response.body) {
+        const buffer = await response.arrayBuffer();
+        if (buffer.byteLength > maxBytes)
+            throw new FirefliesRuntimeError("transcript_too_large", "the provider response exceeds the byte ceiling");
+        return new TextDecoder().decode(buffer);
+    }
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.byteLength;
+        if (total > maxBytes) {
+            await reader.cancel().catch(() => undefined);
+            chunks.length = 0;
+            throw new FirefliesRuntimeError("transcript_too_large", "the provider response exceeds the byte ceiling");
+        }
+        chunks.push(value);
+    }
+    return new TextDecoder().decode(Buffer.concat(chunks));
+}
+function parseJson(text, label) {
+    try {
+        const parsed = JSON.parse(text);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            throw new Error("not an object");
+        return parsed;
+    }
+    catch {
+        throw new FirefliesRuntimeError("provider_failure", `${label} returned a response productfoo could not read`);
+    }
+}
+// BELIEF (T-001): Fireflies' API is GraphQL at /graphql, bearer-key auth,
+// offset pagination, and the field names below. The query strings are the
+// single place to correct if the live API differs.
+const FIREFLIES_VIEWER_QUERY = "query FooViewer { viewer { user_id email } }";
+const FIREFLIES_LIST_QUERY = "query FooListTranscripts($from: String!, $to: String!, $limit: Int!, $offset: Int!) { transcripts(fromDate: $from, toDate: $to, limit: $limit, offset: $offset) { id title date end_date status participants { display_name email } } }";
+const FIREFLIES_TRANSCRIPT_QUERY = "query FooTranscript($id: ID!) { transcript(id: $id) { title speakers { name } sentences { text start_date end_date speaker_id } } }";
+const LIST_PAGE_SIZE = 50;
+function epochToIso(value) {
+    if (typeof value === "number" && Number.isFinite(value))
+        return new Date(value).toISOString();
+    if (typeof value === "string" && value.trim())
+        return value;
+    return undefined;
+}
+function stringOrUndefined(value) {
+    return typeof value === "string" && value.trim() ? value : undefined;
+}
+/**
+ * Minimal read-only Fireflies GraphQL client. The single request() function is
+ * the write-refusal choke point (R-009): GraphQL speaks over POST, so a
+ * mutation is refused by inspecting the query text — the only read operations
+ * reachable are the three query constants above.
+ */
+export class FirefliesClient {
+    credential;
+    options;
+    requests = { viewer: 0, list: 0, transcript: 0 };
+    lastRequestAt = 0;
+    baseUrl;
+    sleep;
+    now;
+    constructor(credential, options) {
+        this.credential = credential;
+        this.options = options;
+        this.baseUrl = (options.baseUrl ?? DEFAULT_FIREFLIES_BASE).replace(/\/+$/, "");
+        this.sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+        this.now = options.now ?? (() => Date.now());
+    }
+    async request(query, variables, maxBytes = FIREFLIES_POLICY.max_response_bytes) {
+        // GraphQL rides over POST, so the read-only rule is the query text: a
+        // mutation never leaves this process (R-009).
+        if (/\bmutation\b/i.test(query))
+            refuseSourceWrite(`fireflies graphql mutation`);
+        const wait = this.lastRequestAt + FIREFLIES_POLICY.min_request_interval_ms - this.now();
+        if (wait > 0)
+            await this.sleep(wait);
+        this.lastRequestAt = this.now();
+        const response = await fetchWithTimeout(this.options.fetchImpl, `${this.baseUrl}/graphql`, {
+            method: "POST",
+            headers: { authorization: `Bearer ${this.credential.api_key}`, "content-type": "application/json", accept: "application/json" },
+            body: JSON.stringify({ query, variables }),
+        }, FIREFLIES_POLICY.fetch_timeout_ms);
+        if (response.status === 401)
+            throw new FirefliesRuntimeError("auth_expired", "Fireflies rejected the API key; check the key or replace it");
+        if (response.status === 403)
+            throw new FirefliesRuntimeError("access_denied", "Fireflies denied this read; the key lacks the required access");
+        if (response.status === 429)
+            throw new FirefliesRuntimeError("budget_exhausted", "Fireflies rate limit reached; no retry was attempted");
+        if (!response.ok)
+            throw new FirefliesRuntimeError("provider_failure", `Fireflies answered ${response.status}`);
+        const body = parseJson(await readBounded(response, maxBytes), "Fireflies");
+        const errors = Array.isArray(body.errors) ? body.errors : [];
+        if (errors.length > 0)
+            throw new FirefliesRuntimeError("provider_failure", "Fireflies reported the query could not be served");
+        const data = (body.data ?? {});
+        return data;
+    }
+    /** Identity probe for readiness (R-005): the connection answers for one user. The result is never printed. */
+    async probe() {
+        this.requests.viewer += 1;
+        const data = await this.request(FIREFLIES_VIEWER_QUERY, {}, 64 * 1024);
+        const viewer = (data.viewer ?? {});
+        return { user_id: stringOrUndefined(viewer.user_id), email: stringOrUndefined(viewer.email) };
+    }
+    /** Bounded metadata listing: one time window, a page ceiling, no content fields requested. */
+    async listTranscripts(window) {
+        const transcripts = [];
+        let offset = 0;
+        let pages = 0;
+        for (;;) {
+            if (pages >= FIREFLIES_POLICY.max_list_pages)
+                return { transcripts, pages, truncated: true };
+            this.requests.list += 1;
+            const data = await this.request(FIREFLIES_LIST_QUERY, { from: window.from, to: window.to, limit: LIST_PAGE_SIZE, offset }, 4 * 1024 * 1024);
+            pages += 1;
+            const entries = Array.isArray(data.transcripts) ? data.transcripts : [];
+            for (const entry of entries) {
+                if (!entry || typeof entry.id !== "string")
+                    continue;
+                const participants = Array.isArray(entry.participants) ? entry.participants : [];
+                transcripts.push({
+                    id: entry.id,
+                    title: stringOrUndefined(entry.title),
+                    started_at: epochToIso(entry.date),
+                    ended: epochToIso(entry.end_date),
+                    status: stringOrUndefined(entry.status),
+                    participants: participants
+                        .filter((participant) => participant && (typeof participant.display_name === "string" || typeof participant.email === "string"))
+                        .map((participant) => ({ display_name: stringOrUndefined(participant.display_name), email: stringOrUndefined(participant.email) })),
+                });
+            }
+            if (entries.length < LIST_PAGE_SIZE)
+                return { transcripts, pages, truncated: false };
+            offset += LIST_PAGE_SIZE;
+        }
+    }
+    /**
+     * Exactly one transcript's content (R-007). A fixture observes that the
+     * request carries a single well-formed identifier and nothing else.
+     */
+    async transcript(id) {
+        if (!id || /\s/.test(id))
+            throw new FirefliesRuntimeError("provider_failure", "a single well-formed transcript identifier is required");
+        this.requests.transcript += 1;
+        const data = await this.request(FIREFLIES_TRANSCRIPT_QUERY, { id });
+        const entry = (data.transcript ?? {});
+        if (!entry || typeof entry !== "object")
+            throw new FirefliesRuntimeError("access_denied", "Fireflies returned no transcript for the selected identifier");
+        const speakers = Array.isArray(entry.speakers) ? entry.speakers : [];
+        const sentences = Array.isArray(entry.sentences) ? entry.sentences : [];
+        return {
+            title: stringOrUndefined(entry.title),
+            speakers: speakers.map((speaker) => ({ name: stringOrUndefined(speaker.name) })),
+            sentences: sentences
+                .filter((sentence) => typeof sentence.text === "string")
+                .map((sentence) => ({
+                text: sentence.text,
+                start_date: stringOrUndefined(sentence.start_date),
+                end_date: stringOrUndefined(sentence.end_date),
+                speaker_id: stringOrUndefined(sentence.speaker_id),
+            })),
+        };
+    }
+}

package/dist-public/src/firstMoveTensions.d.ts

@@ -0,0 +1,10 @@
+export type Tension = {
+    id: string;
+    factA: string;
+    factB: string;
+    ask: string;
+    title: string;
+    evidence: string[];
+    confidence: "high" | "medium";
+};
+export declare function detectTensions(root: string): Tension[];