in2-agent-server 0.20260821.185429

package/dist/core/betaFeedback.js

@@ -0,0 +1,493 @@
+import path from "node:path";
+import { randomBytes } from "node:crypto";
+import { REPO_ROOT, harnessVersion } from "./paths.js";
+import { currentBatchContext } from "./telemetryContext.js";
+import { TelemetryGrantStore, TelemetrySpool } from "./telemetrySpool.js";
+// THE BETA FEEDBACK CHANNEL — what the run was LIKE, from both voices in it.
+//
+// The ledger records what the system DID. It has no channel for where the model got tripped up
+// (a tool failure it worked around, a doc that misled it, two instructions that conflicted) or how
+// the operator experienced the batch. Both currently evaporate at session end, or survive only as
+// prose buried in a transcript blob nobody queries — so the same tripwire gets rediscovered one
+// support conversation at a time. See docs/plans/2026-08-03-005-beta-feedback-channel.md.
+//
+// §9 added two more rows to the same table and the same outbox: the operator's estimate of what the
+// batch would have cost them BY HAND (asked before execution, so it is a counterfactual rather than
+// hindsight) and the sampled relational answer. Both are operator-voiced and both are their own
+// kind — see `FeedbackKind` for why they are not extra columns on the close-time row.
+//
+// WHY IT IS NOT AN EVENT. Feedback is prose. `convex/lib/events.ts` allowlists every payload key and
+// admits none, and widening PAYLOAD_KEYS to carry a friction report would end the shape-only
+// property of the event stream for every consumer of it, permanently, to answer one question.
+// `transcripts` set the precedent, `parcels` extended it, `operatorQa` made it three: content gets
+// its own route, its own table and a stated reason. This is the fourth, and the event stream is
+// untouched.
+//
+// A FEEDBACK ROW IS A SELF-REPORT. A model that misdiagnosed a failure will misdescribe it
+// fluently. Ground truth stays with the transcript and the event stream; batchId is what keeps every
+// row joinable to both, and the trip-up board is meant to be read BESIDE the failure board, never
+// instead of it.
+//
+// FAIL-OPEN, like every other reporting path here: nothing in this module may fail, delay or mask a
+// delivery. Every entry point returns a result instead of throwing.
+/** Bumped when the wire shape changes; the ledger refuses a version it does not know. */
+export const FEEDBACK_WIRE_VERSION = 1;
+export const FEEDBACK_ROUTE = "/api/feedback/v1";
+/**
+ * OFF UNLESS THE INSTALL SAYS OTHERWISE — the one place this family of switches is inverted.
+ *
+ * `CC_MCP_TRANSCRIPT_UPLOAD`, `CC_MCP_PARCEL_UPLOAD` and `CC_MCP_OPERATOR_QA_UPLOAD` all treat an
+ * unset variable as ON, because each of them ships something every install should be sending. This
+ * one is a BETA capability: it adds two tools and a section to the operating contract, and an
+ * install that never opted in must look exactly like one that predates the feature.
+ *
+ * `in2 setup` writes `CC_MCP_BETA=1` into the `claude mcp add` registration env (src/cli.ts), so
+ * the flag travels with the install and survives every npm update — flipping the eventual default
+ * is one setup change, not a server release.
+ *
+ * The DISABLED set is the same generous one transcript upload uses, for the same reason: an operator
+ * who reaches for `CC_MCP_BETA=false` to turn this off must actually turn it off.
+ */
+const DISABLED_VALUES = new Set(["0", "false", "off", "no"]);
+export function betaEnabled(env = process.env) {
+    const raw = env.CC_MCP_BETA?.trim().toLowerCase();
+    if (raw === undefined || raw === "")
+        return false;
+    return !DISABLED_VALUES.has(raw);
+}
+/**
+ * OFF BY DEFAULT — the test-corpus authoring tools, which no operator delivery ever calls.
+ *
+ * `create_campfire_requirements` and `mirror_requirements` exist to stand up and clone the CF-series
+ * MASTER CORPORA we run the product against: authoring a new requirement set, then mirroring it
+ * under a fresh token so two runs differ only by the build under test. Neither has a role in
+ * delivering a real client's batch — a consultant session never authors requirements, it reads the
+ * ones Campfire sent.
+ *
+ * Registering them anyway is not free. A tool definition is resident in EVERY context the server is
+ * connected to, before turn one, and these two are ~1.5 KB of description plus their schemas — paid
+ * by every delivery session and every analyzer subagent fanned out from one, all of which are
+ * forbidden to write to the consultant org in the first place.
+ *
+ * Same shape and same disabled-value set as `betaEnabled` above, and the same reason for the
+ * inversion: a capability an install did not ask for must be indistinguishable from one that
+ * predates it. Set `CC_MCP_CORPUS_TOOLS=1` on the registration when the install IS a test harness.
+ * The write gate is unchanged and still applies on top — this decides only whether the model is
+ * told the tools exist.
+ */
+export function corpusToolsEnabled(env = process.env) {
+    const raw = env.CC_MCP_CORPUS_TOOLS?.trim().toLowerCase();
+    if (raw === undefined || raw === "")
+        return false;
+    return !DISABLED_VALUES.has(raw);
+}
+/**
+ * Whether anything may LEAVE the machine on this channel.
+ *
+ * `CC_MCP_TELEMETRY=0` takes the feedback channel with it, and that is stated here rather than left
+ * to be true by accident. It would in fact be true by accident — with telemetry off there is no
+ * batch grant, and the grant is the only thing that can attribute an upload — but "one switch that
+ * stops all egress" is the behaviour an operator reaching for that variable expects, and an
+ * expectation that holds only as a side effect of the credential plumbing is one refactor away from
+ * being false.
+ *
+ * Note what this does NOT gate: the tools themselves, and the contract section, are gated on
+ * `betaEnabled` alone. A telemetry-disabled install in beta can still record feedback; it simply
+ * spools it and never ships it, and `flushFeedback` says so.
+ */
+export function feedbackUploadEnabled(env = process.env) {
+    if (env.CC_MCP_TELEMETRY === "0")
+        return false;
+    return betaEnabled(env);
+}
+let announced = false;
+/** Test seam — the once-guard is module state, and a suite asserting the line needs it reset. */
+export function resetBetaAnnouncementForTests() {
+    announced = false;
+}
+const defaultLog = (line) => void process.stderr.write(`[cc-mcp] ${line}\n`);
+/**
+ * Say it out loud at startup, once, whenever beta mode is on.
+ *
+ * Modelled on `transcriptUpload.announce`, and for the same reason: a machine in beta mode has two
+ * extra tools and an extra section of instructions, and must never be mistakable for one that does
+ * not. This is also the only disclosure that the model will be filing reports at all — the operator
+ * consented to telemetry and transcripts, not to a channel they cannot see being written to.
+ */
+export function announceBeta(opts = {}) {
+    if (announced)
+        return;
+    const env = opts.env ?? process.env;
+    if (!betaEnabled(env))
+        return;
+    announced = true;
+    const write = opts.log ?? defaultLog;
+    if (!feedbackUploadEnabled(env)) {
+        write("BETA MODE IS ON (CC_MCP_BETA) — the feedback tools are registered, but CC_MCP_TELEMETRY=0 means nothing leaves this machine. " +
+            "Anything recorded stays in the local outbox.");
+        return;
+    }
+    write("BETA MODE IS ON (CC_MCP_BETA). This session can send IN2 two extra things: the model's own reports on where it got " +
+        "tripped up — tool errors, doc gaps, conflicting instructions, never your org's content — and, if you answer them, your " +
+        `ratings and your own words about how the batch went. Both go to ${opts.endpoint ?? "the configured endpoint"}. ` +
+        "Set CC_MCP_BETA=0 to turn the whole channel off, or CC_MCP_TELEMETRY=0 to stop everything leaving this machine.");
+}
+/** Same host, same grant, different route — derived exactly as the other three endpoints are. */
+export function feedbackEndpointFrom(telemetryEndpoint) {
+    try {
+        const url = new URL(telemetryEndpoint);
+        url.pathname = FEEDBACK_ROUTE;
+        return url.toString();
+    }
+    catch {
+        return telemetryEndpoint.replace(/\/api\/telemetry\/v\d+$/, FEEDBACK_ROUTE);
+    }
+}
+/**
+ * THE LEDGER'S FIELD CAPS, MIRRORED — same contract as `operatorQa.WIRE_LIMITS`.
+ *
+ * Every number here is the number in `apps/campfire-launch/convex/feedback.ts`, which is the
+ * validator that actually refuses. Mirroring them moves the refusal to where the report is WRITTEN
+ * — a zod error naming the field, at the moment the model wrote it — instead of to a 400 during
+ * batch close with no attempt left. `betaFeedbackLimits.test.ts` reads both files and fails if they
+ * drift apart.
+ */
+export const FEEDBACK_LIMITS = {
+    title: 200,
+    body: 4_000,
+    citation: 2_000,
+    issue: 1_000,
+    wentWell: 300,
+    tool: 80,
+    stage: 60,
+    role: 60,
+    errorCode: 80,
+    additionalRemarks: 4_000
+};
+/** Ledger counterparts: MAX_FRICTION_POINTS / MAX_WENT_WELL / MAX_REPORTS in convex/feedback.ts. */
+export const FEEDBACK_COUNTS = {
+    frictionPoints: 25,
+    wentWell: 25,
+    reportsPerRequest: 50
+};
+/**
+ * THE TWO NUMERIC BOUNDS ON THE §9.1 ESTIMATE ROW — kept out of `FEEDBACK_LIMITS` on purpose.
+ *
+ * Everything in that block is a STRING-LENGTH cap on prose; these two bound an integer's VALUE. A
+ * reader who found `requirementCount: 1_000` sitting beside `title: 200` would reasonably conclude a
+ * requirement count is truncated at a thousand characters. Ledger counterparts are
+ * MAX_ESTIMATE_MINUTES / MAX_REQUIREMENT_COUNT, pinned by `betaFeedbackLimits.test.ts` like the rest.
+ */
+export const FEEDBACK_BOUNDS = {
+    estimateMinutes: 100_000,
+    requirementCount: 1_000
+};
+/** Mirrors MAX_BODY_BYTES in convex/feedback.ts, which measures raw request text and answers 413. */
+const MAX_REQUEST_BYTES = 1024 * 1024;
+/**
+ * A NARROW MECHANICAL BACKSTOP — not a secret scanner, and not the primary control.
+ *
+ * The primary control is the instruction: the tool description tells the model to replace
+ * secret-shaped values with `[REDACTED]`, stated at the point of writing because that is where it
+ * gets read. This exists because that control has a known failure mode with a known cost — quoted
+ * error text has carried a live activation code before, which is why the transcript table is marked
+ * sensitive — and because one format here is minted by this system and therefore recognisable
+ * without guessing: the activation code is bare `crypto.randomBytes(32).toString("base64url")`
+ * (campfire-launch/src/crypto.ts), exactly 43 base64url characters; the batch grant credential is
+ * the same 43 behind a `tgr_` prefix (campfire-launch/src/db/convexLedger.ts), 47 token characters
+ * in a row that the bare rule can never see — which is the Authorization bearer, i.e. exactly what
+ * a quoted HTTP error carries.
+ *
+ * The bounds are deliberately tight — exactly 43, with no adjacent token character — so it cannot
+ * eat things a citation needs. A 40-char git sha and a 64-char sha256 both fail the length test, and
+ * that is the point: over-redacting a citation would break the one property the report shape exists
+ * to guarantee.
+ */
+const MINTED_TOKEN_RE = /(?<![A-Za-z0-9_-])(?:tgr_)?[A-Za-z0-9_-]{43}(?![A-Za-z0-9_-])/g;
+export function redactSecrets(text) {
+    return text.replace(MINTED_TOKEN_RE, "[REDACTED]");
+}
+/** Every free-text field on a record, run through the backstop above. */
+export function redactRecord(record) {
+    const s = (value) => (value === undefined ? undefined : redactSecrets(value));
+    return {
+        ...record,
+        ...(record.title !== undefined ? { title: s(record.title) } : {}),
+        ...(record.body !== undefined ? { body: s(record.body) } : {}),
+        ...(record.additionalRemarks !== undefined ? { additionalRemarks: s(record.additionalRemarks) } : {}),
+        ...(record.tool !== undefined ? { tool: s(record.tool) } : {}),
+        ...(record.errorCode !== undefined ? { errorCode: s(record.errorCode) } : {}),
+        ...(record.stage !== undefined ? { stage: s(record.stage) } : {}),
+        ...(record.role !== undefined ? { role: s(record.role) } : {}),
+        ...(record.frictionPoints
+            ? {
+                frictionPoints: record.frictionPoints.map((point) => ({
+                    ...point,
+                    citation: redactSecrets(point.citation),
+                    issue: redactSecrets(point.issue)
+                }))
+            }
+            : {}),
+        ...(record.wentWell ? { wentWell: record.wentWell.map(redactSecrets) } : {})
+    };
+}
+export function newFeedbackId() {
+    return `fbk_${randomBytes(12).toString("hex")}`;
+}
+let sharedSpool;
+/** The process-wide feedback outbox, beside the telemetry and parcel ones. */
+export function defaultFeedbackSpool(runId = "feedback") {
+    if (sharedSpool !== undefined)
+        return sharedSpool;
+    try {
+        sharedSpool = new TelemetrySpool({
+            dir: process.env.CC_MCP_FEEDBACK_OUTBOX?.trim() || path.join(REPO_ROOT, ".local", "cc-mcp", "feedback-outbox"),
+            runId
+        });
+    }
+    catch {
+        sharedSpool = null;
+    }
+    return sharedSpool;
+}
+/** Test seam: the outbox is process-wide, and a suite pointing it elsewhere needs it re-resolved. */
+export function resetFeedbackSpoolForTests() {
+    sharedSpool = undefined;
+}
+/**
+ * Put one record in the outbox. NEVER THROWS — this is called from a tool handler.
+ *
+ * ATTRIBUTION IS THE WHOLE JOB HERE, and it is the reason a record without a batch is refused
+ * rather than held. A feedback row's value is that it joins to the run it describes; a row spooled
+ * with no batch would either sit until the caps retired it or — the version to actively avoid —
+ * later be attributed to whichever batch happened to be bound next, which is the mis-attribution
+ * `parcels.defaultResolveGrant` exists to prevent. Same rule, stated the same way.
+ */
+export function recordFeedback(record, opts = {}) {
+    try {
+        const batchId = opts.batchId ?? currentBatchContext()?.batchId ?? null;
+        if (!batchId) {
+            return {
+                recorded: false,
+                unattributed: true,
+                reason: "no batch is bound to this run yet, and a feedback row with no batch cannot be joined to the run it describes — activate a session first"
+            };
+        }
+        const spool = opts.spool === undefined ? defaultFeedbackSpool() : opts.spool;
+        if (!spool)
+            return { recorded: false, reason: "feedback outbox unavailable on this machine" };
+        const stamped = redactRecord({
+            ...record,
+            ...(record.skillVersion === undefined && harnessVersion() ? { skillVersion: harnessVersion() } : {})
+        });
+        const appended = spool.append({ batchId, event: stamped });
+        return appended
+            ? { recorded: true, reportId: stamped.eventId }
+            : { recorded: false, reason: "feedback outbox could not be written" };
+    }
+    catch (error) {
+        return { recorded: false, reason: error instanceof Error ? error.message : String(error) };
+    }
+}
+/**
+ * The grant for a batch, from the durable store first — the same two rules as `parcels`.
+ *
+ * A spooled report outlives the run that made it, so it resolves THAT batch's grant and never
+ * whichever batch happens to be bound now. Borrowing the current one would land a report from one
+ * engagement in the ledger attributed to another.
+ */
+export function defaultResolveFeedbackGrant(batchId) {
+    if (!batchId)
+        return null;
+    try {
+        const stored = new TelemetryGrantStore(path.join(REPO_ROOT, ".local", "cc-mcp", "telemetry-grants")).get(batchId);
+        if (stored?.credential && stored.endpoint) {
+            return { endpoint: feedbackEndpointFrom(stored.endpoint), credential: stored.credential };
+        }
+        // The live context covers the window before a grant reaches disk — same batch only.
+        const live = currentBatchContext();
+        if (live?.credential && live.endpoint && live.batchId === batchId) {
+            return { endpoint: feedbackEndpointFrom(live.endpoint), credential: live.credential };
+        }
+    }
+    catch {
+        // A grant store that cannot be read is a reason to retry later, never to fail a caller.
+    }
+    return null;
+}
+function envelope(reports) {
+    return JSON.stringify({
+        schemaVersion: FEEDBACK_WIRE_VERSION,
+        reports: reports.map(({ eventId, ...rest }) => ({ reportId: eventId, ...rest }))
+    });
+}
+/**
+ * Chunks bounded by BOTH caps the ledger enforces — 50 reports, and a megabyte of request text.
+ *
+ * A single record larger than the whole budget still gets its own chunk rather than being dropped
+ * here: it will be refused on its own, which costs exactly that record, and being refused with the
+ * ledger's own message names the field a client and server disagree about.
+ */
+function planChunks(records) {
+    const overhead = Buffer.byteLength(envelope([]), "utf8");
+    const chunks = [];
+    let current = [];
+    let bytes = overhead;
+    for (const record of records) {
+        const cost = Buffer.byteLength(JSON.stringify(record), "utf8") + 1;
+        if (current.length > 0 && (current.length >= FEEDBACK_COUNTS.reportsPerRequest || bytes + cost > MAX_REQUEST_BYTES)) {
+            chunks.push(current);
+            current = [];
+            bytes = overhead;
+        }
+        current.push(record);
+        bytes += cost;
+    }
+    if (current.length > 0)
+        chunks.push(current);
+    return chunks;
+}
+/**
+ * Ship a batch's records under its grant. Never throws; every failure is a described result.
+ *
+ * A PAYLOAD REFUSAL RE-SENDS ONE AT A TIME, for the same reason the Q&A uploader does: the ledger
+ * validates a request whole and answers 400 for the first field it dislikes, so one malformed record
+ * would otherwise discard the 49 good ones travelling with it — silently, at close, with no second
+ * attempt. The retry is deliberately NOT made for network errors or 5xx: those are not
+ * record-specific, and re-sending 50 records one at a time against a dead endpoint only makes a slow
+ * close slower.
+ */
+export async function uploadFeedback(opts) {
+    const fetchFn = opts.fetchFn ?? fetch;
+    const result = { uploaded: [], rejected: [], retained: [] };
+    const post = async (chunk) => {
+        try {
+            const res = await fetchFn(opts.endpoint, {
+                method: "POST",
+                headers: { "content-type": "application/json", authorization: `Bearer ${opts.credential}` },
+                body: envelope(chunk),
+                signal: AbortSignal.timeout(30_000)
+            });
+            if (res.ok)
+                return { ok: true };
+            const detail = res.status === 400 ? `: ${(await res.text()).slice(0, 200)}` : "";
+            return { ok: false, status: res.status, reason: `HTTP ${res.status}${detail}` };
+        }
+        catch (error) {
+            return { ok: false, reason: error instanceof Error ? error.message : String(error) };
+        }
+    };
+    /** The statuses that mean "this payload", and so the ones worth re-trying one at a time. */
+    const payloadRefusal = (status) => status === 400 || status === 413;
+    for (const chunk of planChunks(opts.records)) {
+        const sent = await post(chunk);
+        if (sent.ok) {
+            result.uploaded.push(...chunk.map((record) => record.eventId));
+            continue;
+        }
+        if (chunk.length > 1 && payloadRefusal(sent.status)) {
+            for (const record of chunk) {
+                const retry = await post([record]);
+                if (retry.ok)
+                    result.uploaded.push(record.eventId);
+                else if (payloadRefusal(retry.status)) {
+                    result.rejected.push(record.eventId);
+                    result.reason ??= `report ${record.eventId}: ${retry.reason ?? "refused"}`;
+                }
+                else {
+                    result.retained.push(record.eventId);
+                    result.reason ??= retry.reason;
+                }
+            }
+            continue;
+        }
+        // 401 is RETAINED on purpose, exactly as parcels retains it: the grant may simply not have been
+        // redeemed on this host yet, and the outbox's own caps bound how long that can go on.
+        if (payloadRefusal(sent.status)) {
+            result.rejected.push(...chunk.map((record) => record.eventId));
+            result.reason ??= sent.reason;
+        }
+        else {
+            result.retained.push(...chunk.map((record) => record.eventId));
+            result.reason ??= sent.reason;
+        }
+    }
+    return result;
+}
+const emptyFlush = () => ({ uploaded: 0, retained: 0, rejected: 0, outboxDropped: 0, notes: [] });
+/**
+ * Ship everything spooled that has a usable grant — INCLUDING BATCHES THIS RUN NEVER TOUCHED.
+ *
+ * This is what makes the channel durable rather than merely persistent. A run that records feedback
+ * and is then killed — the client SIGTERMs the server 2 s after closing stdin, and no signal handler
+ * gets more time than that (see telemetryContext.registerBatchCloser) — leaves its reports on disk.
+ * A LATER run, with the same install and the same grant store, flushes them. `pendingBatchIds` is
+ * why: the flush iterates every batch in the outbox, not just the one currently bound.
+ */
+export async function flushFeedback(opts = {}) {
+    const summary = emptyFlush();
+    const env = opts.env ?? process.env;
+    if (!betaEnabled(env))
+        return summary;
+    const spool = opts.spool === undefined ? defaultFeedbackSpool() : opts.spool;
+    if (!spool)
+        return summary;
+    if (!feedbackUploadEnabled(env)) {
+        const waiting = spool.stats().pendingEvents;
+        if (waiting > 0) {
+            summary.retained = waiting;
+            summary.notes.push(`${waiting} feedback record(s) stay on this machine — CC_MCP_TELEMETRY=0 stops all egress, and that covers this channel.`);
+        }
+        return summary;
+    }
+    const resolve = opts.resolveGrant ?? defaultResolveFeedbackGrant;
+    let batchIds;
+    try {
+        batchIds = spool.pendingBatchIds();
+    }
+    catch {
+        return summary;
+    }
+    for (const batchId of batchIds) {
+        const records = spool.readBatch(opts.limit ?? 200, batchId).map((entry) => entry.event);
+        if (records.length === 0)
+            continue;
+        let grant = null;
+        try {
+            grant = resolve(batchId);
+        }
+        catch {
+            grant = null;
+        }
+        if (!grant) {
+            summary.retained += records.length;
+            continue;
+        }
+        const result = await uploadFeedback({
+            endpoint: grant.endpoint,
+            credential: grant.credential,
+            records,
+            ...(opts.fetchFn ? { fetchFn: opts.fetchFn } : {})
+        });
+        // Retired together, but only the rejected ones count as lost — the same distinction the
+        // telemetry outbox draws, so delivery health reports the gap instead of under-counting.
+        spool.acknowledge([...result.uploaded, ...result.rejected], result.rejected.length);
+        summary.uploaded += result.uploaded.length;
+        summary.rejected += result.rejected.length;
+        summary.retained += result.retained.length;
+        if (result.rejected.length > 0) {
+            summary.notes.push(`${result.rejected.length} feedback record(s) were REFUSED by IN2 and dropped from the outbox (${result.reason ?? "no reason given"}).`);
+        }
+    }
+    if (summary.uploaded > 0)
+        summary.notes.push(`beta feedback uploaded: ${summary.uploaded} record(s)`);
+    if (summary.retained > 0) {
+        summary.notes.push(`${summary.retained} feedback record(s) still queued — they stay in the outbox and go out on a later run under the same batch's grant.`);
+    }
+    const stats = spool.stats();
+    summary.outboxDropped = stats.droppedEvents;
+    if (stats.droppedEvents > 0) {
+        summary.notes.push(`${stats.droppedEvents} feedback record(s) were dropped by the outbox's size/age caps and did NOT reach IN2.`);
+    }
+    return summary;
+}