in2-agent-server 0.20260821.185429

package/dist/tools/closeBatch.js

@@ -0,0 +1,154 @@
+import { z } from "zod";
+import { fail, internalError, ok } from "../core/result.js";
+import { WorkspaceError } from "../core/workspace.js";
+import { SessionOrgError, resolveSessionOrg } from "../core/sessionOrg.js";
+import { closeBatchTelemetry } from "../core/telemetryContext.js";
+import { batchReportArtifacts, composeBatchReport, renderBatchReport, writeBatchReportArtifacts } from "../direct/batchReport.js";
+import { renderOperatorPage } from "../direct/operatorPage.js";
+import { installPendingUpdate } from "../core/update.js";
+import { loadRequirementsIndex, loadSession } from "./session.js";
+import { composeCloseText } from "./closeText.js";
+/**
+ * THE EXPLICIT END OF A BATCH.
+ *
+ * Before this tool existed, a batch had no end — five subsystems in `core/telemetry.ts` each
+ * guessed at one with `process.once("beforeExit", …)`, and the guess was wrong in production:
+ * 7 batches, 0 terminal; 0 transcripts uploaded; no session ever produced a contamination report.
+ *
+ * Measured cause (see `registerBatchCloser` in core/telemetryContext.ts): the MCP client closes
+ * stdin, waits 2000 ms, then SIGTERMs. `beforeExit` fires only if the event loop drains inside that
+ * window — one still-ref'd handle and it never fires at all — and no signal handler gets more time.
+ * Every step that mattered was network work that could not finish in two seconds.
+ *
+ * So finalization happens HERE instead, in a tool call, while the server is alive and unhurried,
+ * and the artifacts are RETURNED rather than only written — a report the supervisor cannot read is
+ * a report that does not reach the operator.
+ */
+export function registerCloseBatchTools(server) {
+    server.registerTool("close_batch", {
+        description: "END THE BATCH. Call this ONCE, as the LAST tool call of a delivery run, after the final wave and any Campfire writeback — including when the run ended badly (waves rejected, blocked, or abandoned). " +
+            "It is the only thing that gives a batch an end: it states the batch's terminal result to the ledger, assembles and writes the closing evidence, and ships everything that was waiting on the end of the run (provenance parcels, the session transcript, any unflushed events). " +
+            "Nothing else does this. A run that is never closed reads as ABANDONED on the IN2 dashboard no matter how well it went, and its evidence never leaves the machine. " +
+            "RETURNS the technical spine for the operator's end-results page: the COMPUTED summary counts (`scope`: how many configurations were planned, how many the org read-back proved, how many still need a person, and the automation rate) plus per-wave verdicts and rollback coverage, batch-level findings, the delivery log with its drift explanations, and the contamination report. " +
+            "USE `scope` VERBATIM for the page's summary panel — do NOT re-count configurations from the evidence bundles. Those numbers are derived once, at Configuration Item grain, from what the approved plans asked for; a hand-derived second count is how a run reported 205 components as 94 configurations. A null `scope` means this batch never recorded what it was asked for: say the rate is unavailable rather than printing a zero. " +
+            "RETURNS `operatorPage`: the operator's results page, ALREADY RENDERED. Paste it verbatim as the top of your reply and write only what belongs below it — the manual steps, rollback, notes and the technical section. Do NOT recompose it, reorder it, or re-count anything in it; it is derived from the same numbers `scope` reports, and a hand-written second version is how the page came to differ on every run. " +
+            "Local-only evidence: the report names components, and component identity never enters the ledger. Safe to call more than once — the batch closes at most once per server process and later calls return the same result. " +
+            "This is the ONLY correct way to end a run; do not rely on the session simply stopping.",
+        inputSchema: {
+            sessionId: z
+                .string()
+                .describe("The session whose batch to close. The org is derived from the session, exactly as it is for every other org-touching tool — there is no org to name and none to get wrong.")
+        }
+    }, async ({ sessionId }) => {
+        try {
+            const session = await loadSession(sessionId);
+            const { alias, orgId } = await resolveSessionOrg(session, "target", { verify: false });
+            if (!orgId) {
+                return fail("ORG_NOT_BOUND", `Session ${sessionId} is bound to alias ${JSON.stringify(alias)} but recorded no Org ID, and both the mirror and the read-set are org-keyed. Re-bind the session (activate_session, or create_session { targetOrgAlias, targetOrgId }).`);
+            }
+            // Order matters, and it is the opposite of what it looks like.
+            //
+            // The report is composed and written FIRST, from this tool's own arguments, so the operator
+            // gets it even if shipping fails entirely — a local artifact is worth more than a network
+            // round-trip. The telemetry closer then runs the same report writer again behind its own
+            // once-guard, which is a no-op re-render rather than a second computation of anything sent.
+            const report = await composeBatchReport({
+                sessionId,
+                orgId,
+                ...(alias ? { orgAlias: alias } : {})
+            });
+            const rendered = renderBatchReport(report);
+            const written = await writeBatchReportArtifacts(report, rendered);
+            // FAIL-OPEN, like every other piece of closing bookkeeping. A missing requirements index
+            // costs the page its titles, never the close its result — `close_batch` must still close
+            // when everything else has gone wrong, and that guard is not negotiable.
+            //
+            // BUT NOT SILENTLY. A bare `catch { operatorPage = "" }` turned any renderer throw into an
+            // empty page with no note anywhere: the operator saw a close with no summary and no reason
+            // for its absence, and a later reader had nothing to find. The failure is now carried out
+            // as a closing note, which reaches both the returned text and the payload, without ever
+            // reaching the return value's success.
+            let operatorPage = "";
+            let pageFailure = null;
+            try {
+                operatorPage = renderOperatorPage(report, await loadRequirementsIndex(sessionId));
+            }
+            catch (error) {
+                operatorPage = "";
+                pageFailure =
+                    `the operator's results page could NOT be rendered (${error instanceof Error ? error.message : String(error)}) — ` +
+                        `the batch still closed and every count below is intact. State the result and the \`scope\` counts in plain language; do not reconstruct the page by hand.`;
+            }
+            // Ship. Awaited, unlike every exit hook this replaces, so what follows is a statement about
+            // what happened rather than a hope about what might.
+            const outcome = await closeBatchTelemetry();
+            // The update activation deferred. AFTER the evidence has shipped, deliberately: this is
+            // the last tool call of the run, nothing will lazily import another module, and an
+            // `npm install -g` that replaces dist under this process can no longer skew anything. The
+            // next session starts on the new version with no one asked to do anything — the reason
+            // activation stopped asking (QA rounds 1-2: every "update available" notice was ignored).
+            // Fail-open like everything else here: a failed install is a note, never a failed close.
+            const updateInstalled = await installPendingUpdate().catch(() => undefined);
+            const updateNote = !updateInstalled
+                ? []
+                : updateInstalled.ok && updateInstalled.updated
+                    ? [
+                        `server updated to ${updateInstalled.toVersion} (this run was on ${updateInstalled.fromVersion}) — the NEXT conversation runs the new version; this one is done either way.`
+                    ]
+                    : updateInstalled.ok
+                        ? []
+                        : [`a pending server update could not be installed (${updateInstalled.error ?? "unknown error"}) — the next activation will retry.`];
+            const artifacts = batchReportArtifacts(sessionId);
+            const shipping = [
+                ...(outcome
+                    ? outcome.notes
+                    : ["telemetry is disabled on this install (CC_MCP_TELEMETRY=0) — nothing was sent, and nothing was expected to be"]),
+                ...updateNote,
+                // FIRST-CLASS, not appended as an afterthought: this is the note that explains an empty
+                // `operatorPage`, and it must survive into the payload as well as the text.
+                ...(pageFailure ? [pageFailure] : [])
+            ];
+            const text = composeCloseText({
+                operatorPage,
+                rendered,
+                artifactPath: artifacts.markdown,
+                written: written !== null,
+                shipping
+            });
+            // The mirror (ok()'s `text`) carries the operator page a SECOND time here — once inside
+            // the paste fence, once under `operatorPage`. Deliberate, reviewed 2026-08-21: this fires
+            // once per run, and the fence-with-page-inside is the deliverable whose verbatim relay
+            // exists because hand re-derivation miscounted a results page twice (QA rounds 1 and 2).
+            // Slimming the mirrored text to a pointer would reopen exactly that. direct_history made
+            // the opposite call (text overridden to a pointer) because its duplicate is an uncapped
+            // git patch on a tool called many times a run.
+            return ok(text, {
+                sessionId,
+                orgId,
+                result: report.result,
+                // THE FOUR COUNTS, COMPUTED. The page's summary panel is composed from these rather than
+                // hand-derived from evidence bundles at the end of a long run — which is how QA round 1
+                // item 24 happened (205 components reported as 94 configurations) and QA round 2 repeated
+                // it. `null` means this batch never recorded what it was asked for: state no rate, never
+                // a zero one.
+                scope: report.scope,
+                // The finished page, for a client that would rather render than parse.
+                operatorPage,
+                deliveredWaves: report.deliveredWaves,
+                problemWaves: report.problemWaves,
+                practiceRuns: report.practiceRuns,
+                findings: report.findings,
+                artifacts: written ? artifacts : null,
+                closed: outcome?.finalized ?? false,
+                shipping
+            });
+        }
+        catch (error) {
+            if (error instanceof SessionOrgError)
+                return fail(error.code, error.message);
+            if (error instanceof WorkspaceError)
+                return fail(error.code, error.message);
+            return internalError(error);
+        }
+    });
+}

package/dist/tools/closeText.js

@@ -0,0 +1,35 @@
+// HOW A CLOSE READS, ASSEMBLED.
+//
+// Extracted from the `close_batch` handler so the branch that matters — whether the operator's
+// finished page leads the result or is absent entirely — is reachable from a test without a
+// session, an org, or a workspace on disk.
+export function composeCloseText(input) {
+    return [
+        // THE OPERATOR'S PAGE, FINISHED. It leads because the supervisor reads this result top down,
+        // and the technical spine below it used to be the first thing found — which is how the page
+        // came to be re-derived by hand on every run.
+        ...(input.operatorPage
+            ? [
+                `=== PASTE THE BLOCK BELOW VERBATIM AS THE OPERATOR'S RESULTS PAGE ===`,
+                ``,
+                input.operatorPage,
+                ``,
+                `=== END OF BLOCK. Everything below is yours, not the operator's: write the "Still to do" items, rollback, notes and the technical section beneath the pasted block. ===`,
+                ``,
+                `---`,
+                ``
+            ]
+            : []),
+        input.rendered,
+        ``,
+        `---`,
+        ``,
+        `## Batch close`,
+        ``,
+        input.written
+            ? `Evidence written to ${input.artifactPath} (and batch-report.json beside it).`
+            : `Evidence could NOT be written to ${input.artifactPath} — the report above is the only copy.`,
+        ``,
+        ...input.shipping.map((note) => `- ${note}`)
+    ].join("\n");
+}