in2-agent-server 0.20260821.185429

package/dist/tools/phase.js

@@ -0,0 +1,249 @@
+// advance_phase / resume_session — the chapter boundary, and the way back into a run that died.
+//
+// ONE TOOL AT THE BOUNDARY DOES THREE THINGS AT ONCE, and they belong together because they are all
+// answers to the same question — "the run just moved; what follows from that?"
+//
+//   1. IT RECORDS THE POSITION. `phases.jsonl` is the only artifact that says where a run had got
+//      to. Everything else in a session directory says what a run PRODUCED, and a chapter entered
+//      but never finished leaves no trace at all.
+//   2. IT SHIPS WHAT HAS HAPPENED SO FAR. `close_batch` was the only flush, and it runs at the end,
+//      so a run that died in the middle shipped nothing — see `flushAtBoundary` in core/telemetry.ts
+//      for the measurement. Eight boundaries precede the end; each one is a free, already-motivated
+//      moment to drain the outbox and upload the transcript.
+//   3. IT HANDS BACK THE NEXT CHAPTER'S INSTRUCTIONS. The resident contract was cut to a skeleton on
+//      measured evidence that clients truncate it at ~2 KB, and the expanded per-step detail had
+//      nowhere to arrive on time. A tool return arrives exactly when the instruction applies. See
+//      `core/chapterInstructions.ts`.
+//
+// WHY NOT SPLIT THEM. Any two of the three without the third is worse than the whole: a ledger
+// nobody has a reason to write is a ledger that goes stale; a flush with no boundary to hang on has
+// to be a timer, which is the design that already fails on a dying process; and instructions handed
+// out on request are instructions the model asks for only when it already knows what it is doing.
+// Binding all three to the boundary is what makes each one happen reliably — the model calls it for
+// the instructions, and the position and the flush ride along.
+//
+// IT NEVER REPLACES `close_batch`. This tool records where a run STANDS; `close_batch` states its
+// terminal RESULT, assembles the closing evidence and ships everything that was waiting on the end.
+// Advancing into `writeback-close` is not closing the batch, and the refusal and the return text
+// both say so — a run that stopped at the last boundary still reads ABANDONED on the dashboard.
+import { z } from "zod";
+import { chapterBrief } from "../core/chapterInstructions.js";
+import { fail, internalError, ok } from "../core/result.js";
+import { CHAPTERS, appendPhaseLedger, isChapter, ledgerHead, newLedgerEntry, planTransition, readPhaseLedger } from "../core/phases.js";
+import { reconstruct, renderReconstruction } from "../core/resume.js";
+import { rebindStoredBatch } from "../core/telemetry.js";
+import { currentBatchContext, emitDomainTelemetryEvent, flushAtBoundary, processTelemetryIdentity } from "../core/telemetryContext.js";
+import { WorkspaceError, fileExists, sessionFile } from "../core/workspace.js";
+import { SessionOrgError, resolveSessionOrg } from "../core/sessionOrg.js";
+import { loadSession } from "./session.js";
+const CHAPTER_LIST = CHAPTERS.join(" -> ");
+export function registerPhaseTools(server) {
+    server.registerTool("advance_phase", {
+        title: "Cross a chapter boundary of the delivery run",
+        description: "CALL THIS AT EVERY CHAPTER BOUNDARY OF A DELIVERY RUN, naming the chapter you just finished and the one you are entering. " +
+            `The nine chapters, in order: ${CHAPTER_LIST}. ` +
+            "RETURNS THE ENTERING CHAPTER'S FULL INSTRUCTIONS — the expanded doctrine for the work you are about to do, which is deliberately NOT in the resident contract (clients truncate that, so it carries only the loop skeleton). Read what comes back and follow it; it is more specific than the playbook's summary of the same step. " +
+            "It also returns a progress line in the operator's language: relay that to them, do not paraphrase harness internals. " +
+            "AND IT SHIPS THE RUN'S EVIDENCE SO FAR — the telemetry outbox, any queued provenance parcels, and the session transcript. That is why calling it matters even on a run you are certain will finish: a run that dies mid-flight has otherwise shipped nothing at all, because the only other flush is at close. " +
+            "Small batches legitimately skip partitioning, parallel-analysis and clarification; naming a further chapter jumps them and is recorded. Every other chapter is load-bearing and skipping it is refused by name. Going backwards is refused. " +
+            "THIS IS NOT close_batch AND NEVER REPLACES IT. This records where the run STANDS; close_batch states the batch's terminal RESULT, writes the closing evidence and ships everything waiting on the end of the run. Advancing into writeback-close is not closing the batch — a run you do not close still reads ABANDONED on the IN2 dashboard.",
+        inputSchema: {
+            sessionId: z.string().describe("The session whose run is moving. The org and the batch are derived from it, as everywhere else."),
+            completed: z
+                .enum(CHAPTERS)
+                .describe(`The chapter you have just FINISHED. One of: ${CHAPTER_LIST}.`),
+            entering: z
+                .enum(CHAPTERS)
+                .describe("The chapter you are entering — normally the next one. Naming a later chapter records the ones in between as SKIPPED, which is legal for partitioning, parallel-analysis and clarification (a batch small enough to analyze inline, or one that raises no genuine fork) and refused for the rest."),
+            note: z
+                .string()
+                .optional()
+                .describe("One line about what this chapter produced or why a skip was taken, recorded on the ledger. A resumed session reads it. Not shown to the operator — the progress line is.")
+        }
+    }, async ({ sessionId, completed, entering, note }) => {
+        try {
+            // Fail before anything is recorded if there is no session to record it against. Creating the
+            // ledger under a session that does not exist would leave a phases.jsonl beside nothing.
+            if (!fileExists(sessionFile(sessionId))) {
+                return fail("SESSION_NOT_FOUND", `No session ${sessionId}. Start one with activate_session {code} (a pasted Campfire code) or create_session, then advance from activation.`);
+            }
+            const ledger = await readPhaseLedger(sessionId);
+            const head = ledgerHead(ledger);
+            const transition = planTransition({ head, completed, entering });
+            if (!transition.ok)
+                return fail(transition.code, transition.message);
+            const context = currentBatchContext();
+            await appendPhaseLedger(newLedgerEntry({
+                kind: "advance",
+                sessionId,
+                completed,
+                entering,
+                skipped: transition.skipped,
+                ...(note ? { note } : {}),
+                ...(processTelemetryIdentity()?.runId ? { runId: processTelemetryIdentity().runId } : {}),
+                ...(context?.batchId ? { batchId: context.batchId } : {})
+            }));
+            // Shape only, exactly like every other domain event: which boundary, and what was skipped.
+            // No note text — the note is the supervisor's prose and belongs on local disk, where the
+            // rest of this run's prose lives.
+            emitDomainTelemetryEvent("run.phase_advanced", {
+                completed,
+                entering,
+                ...(transition.skipped.length > 0 ? { skipped: transition.skipped } : {})
+            }, { stage: "boundary", outcome: entering });
+            // AFTER the ledger append, deliberately. The append is local and synchronous-ish and cannot
+            // fail on a network; the flush is network work that may take seconds. Recording the position
+            // first means a boundary crossed on a machine that then loses its connection still leaves the
+            // ledger correct, which is the artifact a resume depends on.
+            const flush = await flushAtBoundary();
+            const brief = chapterBrief(entering);
+            const text = [
+                `${completed} -> ${entering}${transition.skipped.length > 0 ? `  (skipped: ${transition.skipped.join(", ")})` : ""}`,
+                "",
+                `## ${brief.headline}`,
+                "",
+                brief.instructions,
+                "",
+                "---",
+                "",
+                "RELAY THIS TO THE OPERATOR, in their words, before you start the work above:",
+                `  ${brief.progressLine}`,
+                "",
+                ...(flush
+                    ? ["Evidence shipped at this boundary:", ...flush.notes.map((n) => `  - ${n}`)]
+                    : ["Telemetry is disabled on this install (CC_MCP_TELEMETRY=0) — nothing was shipped, and nothing was expected to be."]),
+                ...(entering === "writeback-close"
+                    ? [
+                        "",
+                        "THIS IS THE LAST CHAPTER, AND CROSSING INTO IT IS NOT CLOSING THE BATCH. `close_batch {sessionId}`",
+                        "is still required, as the LAST tool call of the run, after the writeback — and equally if the run",
+                        "ends badly from here. Nothing else states the batch's result or ships its closing evidence."
+                    ]
+                    : [])
+            ].join("\n");
+            return ok(text, {
+                sessionId,
+                completed,
+                entering,
+                ...(transition.skipped.length > 0 ? { skipped: transition.skipped } : {}),
+                chapter: brief.headline,
+                progressLine: brief.progressLine,
+                shipped: flush?.notes ?? [],
+                batchClosed: false
+            });
+        }
+        catch (error) {
+            if (error instanceof WorkspaceError)
+                return fail(error.code, error.message);
+            return internalError(error);
+        }
+    });
+    server.registerTool("resume_session", {
+        title: "Pick up a delivery run that a previous session left unfinished",
+        description: "READ A DEAD RUN BACK. Given only a sessionId, this reconstructs where the run stands — the chapter it was in and how long ago it stopped, the requirements and which have plans, the analysis brief, the question rounds and whether any are still open, and every wave that reached the org with its verdict — and returns instructions for picking it up. " +
+            "Use it when an operator returns to a run a previous conversation started: a crashed client, a closed window, a session resumed the next morning. Nothing in a session directory records POSITION on its own, so do not infer it from artifacts yourself; a chapter entered but never finished looks exactly like one never entered, and guessing wrong in that direction means deploying work nobody approved. " +
+            "IT CHECKS THE ORG AUTH RATHER THAN ASSUMING IT. An activation-minted token lasts about a day, so a run resumed the next morning usually has a DEAD org even though every artifact is intact. The result says whether the org is reachable and, when it is not, that you must card the operator rather than re-authenticate anything yourself. " +
+            "READ-ONLY: it writes one `resume` line to the phase ledger and changes nothing else. No org call mutates anything, no artifact is rewritten, and the batch is not closed — you still call close_batch at the end of the resumed run.",
+        inputSchema: {
+            sessionId: z.string().describe("The session to pick up. It is the only thing you need; everything else is derived from disk.")
+        }
+    }, async ({ sessionId }) => {
+        try {
+            if (!fileExists(sessionFile(sessionId))) {
+                return fail("SESSION_NOT_FOUND", `No session ${sessionId} on this machine. A session's workspace is local, so a run started on another machine cannot be resumed here — the operator starts a fresh one from Campfire.`);
+            }
+            const state = await reconstruct(sessionId);
+            const auth = await checkAuth(sessionId, state.batchId);
+            await appendPhaseLedger(newLedgerEntry({
+                kind: "resume",
+                sessionId,
+                entering: state.resumeInto,
+                note: auth.usable ? "resumed; org reachable" : `resumed; org NOT reachable (${auth.summary})`,
+                ...(processTelemetryIdentity()?.runId ? { runId: processTelemetryIdentity().runId } : {}),
+                ...(state.batchId ? { batchId: state.batchId } : {})
+            }));
+            emitDomainTelemetryEvent("run.resumed", {
+                chapter: state.resumeInto,
+                ledgerPresent: state.chapter !== null,
+                orgReachable: auth.usable,
+                requirementCount: state.requirements.length,
+                waveCount: state.waves.length,
+                discrepancyCount: state.discrepancies.length
+            }, { stage: "boundary", outcome: auth.usable ? "resumed" : "resumed-no-org" });
+            return ok(renderReconstruction(state, auth), {
+                sessionId,
+                chapter: state.chapter,
+                resumeInto: state.resumeInto,
+                orgReachable: auth.usable,
+                telemetryRebound: auth.telemetryRebound,
+                ...(state.orgAlias ? { orgAlias: state.orgAlias } : {}),
+                ...(state.batchId ? { batchId: state.batchId } : {}),
+                requirements: state.requirements,
+                rounds: state.rounds,
+                waves: state.waves,
+                ...(state.waveGrade ? { waveGrade: state.waveGrade } : {}),
+                ...(state.discrepancies.length > 0 ? { discrepancies: state.discrepancies } : {}),
+                batchClosed: false
+            });
+        }
+        catch (error) {
+            if (error instanceof WorkspaceError)
+                return fail(error.code, error.message);
+            return internalError(error);
+        }
+    });
+}
+/**
+ * IS THIS RUN STILL ABLE TO ACT — asked, never assumed, and asked FIRST.
+ *
+ * THE AUTH QUESTION IS THE ONE A RESUME CANNOT SKIP. Every artifact in a session directory survives
+ * indefinitely; the org token does not. An activation-minted token lasts about a day, so the single
+ * most common resume — an operator returning the next morning — is precisely the case where every
+ * plan, brief and bundle is intact and the org is unreachable. A resume that assumed the old auth
+ * was alive would report a run ready to continue and then fail at the first projection, having spent
+ * the operator's attention getting there.
+ *
+ * So the check is a real read (`resolveSessionOrg` with verification, which resolves the alias
+ * through the CLI) and its failure is a CARD, never a repair. Nothing here re-authenticates: rapid
+ * retries trip Salesforce's integration-user auto-freeze, and the fix — a fresh Campfire activation,
+ * or a login the operator performs — is theirs by design.
+ *
+ * THE SECOND, QUIETER AUTH: the batch GRANT, which is what lets a resumed run ship its evidence.
+ * Activation binds it once and this process never saw that activation, so without a re-bind a
+ * resumed run's `close_batch` reports "no batch bound" and its events and transcript stay on the
+ * machine. `rebindStoredBatch` reads the grant this install was already issued for this batch. It
+ * can fail independently of the org — the grant outlives the org token, or expires while the org
+ * stays fine — so the two are reported as two facts rather than one verdict.
+ */
+async function checkAuth(sessionId, batchId) {
+    const telemetryRebound = batchId ? rebindStoredBatch({ batchId, sessionId }) : false;
+    try {
+        const session = await loadSession(sessionId);
+        const { alias, orgId } = await resolveSessionOrg(session, "target", { verify: true });
+        return {
+            usable: true,
+            telemetryRebound,
+            summary: `alias ${alias} still resolves to org ${orgId} — the session's org auth is alive and this run can read and deploy.`
+        };
+    }
+    catch (error) {
+        if (error instanceof SessionOrgError) {
+            return {
+                usable: false,
+                telemetryRebound,
+                summary: `${error.code} — ${error.message}`
+            };
+        }
+        // Everything else from this path is the org being unreachable: an expired token, a logged-out
+        // alias, an sf CLI that cannot answer. Reported as unusable rather than swallowed, because
+        // "we could not tell" and "it works" must never look the same here.
+        return {
+            usable: false,
+            telemetryRebound,
+            summary: `the session's org could not be reached (${error instanceof Error ? error.message : String(error)}). An activation-minted token lasts about a day, so a run resumed the next morning normally reads this way. The operator re-activates from Campfire for a fresh code, or signs in directly with \`sf org login web --alias <the session alias> --instance-url <their org url>\`. You never re-authenticate an org yourself.`
+        };
+    }
+}
+/** Exported for the doctrine test: every chapter the tool accepts must have a brief behind it. */
+export const ACCEPTED_CHAPTERS = CHAPTERS;
+export { isChapter };

package/dist/tools/projection.js

@@ -0,0 +1,172 @@
+import path from "node:path";
+import { existsSync, promises as fs } from "node:fs";
+import { z } from "zod";
+import { fail, internalError, ok } from "../core/result.js";
+import { WorkspaceError } from "../core/workspace.js";
+import { appendReadRecord } from "../core/readsLog.js";
+import { loadSession } from "./session.js";
+import { SessionOrgError, resolveSessionOrg } from "../core/sessionOrg.js";
+import { sessionDir } from "../core/workspace.js";
+import { OrgReaderUnavailableError, createLiveOrgReader } from "../projection/bridge.js";
+import { ScopeTooLargeError } from "../projection/project.js";
+import { runProjection } from "../projection/project.js";
+import { diffProjections, renderDiff } from "../projection/diff.js";
+import { scopeIsEmpty } from "../projection/scope.js";
+const DEFAULT_API_VERSION = "61.0";
+const LABEL_RE = /^[A-Za-z0-9_-]{1,40}$/;
+function timestampLabel() {
+    return new Date().toISOString().replace(/[:.]/g, "-");
+}
+export function registerProjectionTools(server) {
+    server.registerTool("project_org", {
+        description: "READ-ONLY org projection: materialize a scoped slice of an org's metadata into workspace files a model can read, grep, and diff — canonical per-component JSON via the verifier's OWN snapshot readers (the gate's read path, same normalizations), plus MAP.md (the entry point: one line per component with load-bearing facets) and a fail-closed projection.json manifest. Scope = objects (object + fields + validation rules + layout list) and/or prefix (objects matching an API-name prefix) and/or explicit components. Pass compareTo (a prior projection dir) to also emit DIFF.md/diff.json — self-diff of an unchanged org is empty. Use before compiling brownfield requirements: project the touched objects and assert org actuals from the projection.",
+        inputSchema: {
+            sessionId: z
+                .string()
+                .describe("The session to project for. The org comes FROM the session (bound by activate_session / create_session), and the projection is stored under that session's workspace."),
+            scope: z
+                .object({
+                objects: z.array(z.string()).optional().describe("Object API names — each expands to object + custom fields + validation rules + layout list."),
+                prefix: z.string().optional().describe("Object API-name prefix, e.g. CF63_ (SOQL-wildcard-escaped)."),
+                components: z
+                    .array(z.object({ typeName: z.string(), fullName: z.string() }))
+                    .optional()
+                    .describe("Explicit components, e.g. {typeName: Layout, fullName: 'CF63_Intake_Request__c-CF63 Layout'}.")
+            })
+                .describe("At least one of objects/prefix/components."),
+            label: z.string().optional().describe("Directory label [A-Za-z0-9_-]{1,40}; default = timestamp."),
+            compareTo: z.string().optional().describe("Absolute path of a prior projection dir to diff against."),
+            apiVersion: z.string().optional().describe("Metadata API version; default 61.0."),
+            maxComponents: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe("Refuse if the scope resolves beyond this many components (default 250). Raise it only after seeing the refusal's breakdown — a standard object like Account contributes hundreds of custom fields.")
+        }
+    }, async ({ scope, sessionId, label, compareTo, apiVersion, maxComponents }) => {
+        try {
+            const session = await loadSession(sessionId);
+            // Read-only, so the alias check is skipped: a projection of the "wrong" org is harmless and
+            // self-evident in the output, and paying an sf round-trip on every projection is not.
+            // Writes (direct_apply) always verify.
+            const binding = await resolveSessionOrg(session, "target", { verify: false });
+            const targetOrg = binding.alias;
+            const startedAt = Date.now();
+            if (scopeIsEmpty(scope)) {
+                return fail("SCOPE_EMPTY", "Provide at least one of scope.objects, scope.prefix, scope.components.");
+            }
+            if (label && !LABEL_RE.test(label)) {
+                return fail("INVALID_LABEL", `label must match ${LABEL_RE}.`);
+            }
+            if (compareTo && !existsSync(path.join(compareTo, "projection.json"))) {
+                return fail("PROJECTION_NOT_FOUND", `compareTo has no projection.json: ${compareTo}`);
+            }
+            const version = apiVersion?.trim() || DEFAULT_API_VERSION;
+            const dirLabel = label ?? timestampLabel();
+            // sessionId is required now, so the old shared-root fallback was unreachable.
+            const root = path.join(sessionDir(sessionId), "org-projection");
+            const outDir = path.join(root, targetOrg, dirLabel);
+            const reader = await createLiveOrgReader(targetOrg, version);
+            try {
+                await reader.identity();
+            }
+            catch (error) {
+                // Fail-closed: an unreadable org is an error, never an empty projection.
+                return fail("ORG_READ_FAILED", `Cannot read org '${targetOrg}': ${error instanceof Error ? error.message : String(error)}`);
+            }
+            const result = await runProjection(reader, {
+                scope: scope,
+                outDir,
+                orgAlias: targetOrg,
+                apiVersion: version,
+                label: dirLabel,
+                maxComponents
+            });
+            // READ PROVENANCE (R9-R10, R12). A projection materializes each component's full snapshot,
+            // so its access pattern is a BODY read — the strongest thing a contamination report can say
+            // about a component, and the reason enumerating an object is not the same event as this.
+            //
+            // A POINTER, not a component list. The manifest this call just wrote already names every
+            // component with its found flag; copying that into reads.jsonl would duplicate a list that
+            // can run to hundreds of entries per wave and then have to be kept in sync with it. The
+            // read-set carries the path and resolves it when a report needs the members.
+            await appendReadRecord(sessionId, {
+                tool: "project_org",
+                // The manifest records the org id the READER observed; the session binding is what the
+                // rest of the log is keyed on, so they must not be mixed.
+                orgId: binding.orgId ?? null,
+                orgAlias: targetOrg,
+                scope: `projection ${dirLabel}`,
+                pattern: "body",
+                keys: [],
+                manifests: [path.join(outDir, "projection.json")],
+                rows: result.manifest.counts.components,
+                durationMs: Date.now() - startedAt,
+                outcome: "ok"
+            });
+            let diffSummary;
+            const textLines = [
+                `projected ${result.manifest.counts.components} components (${result.manifest.counts.errors} errors) from ${targetOrg} (org ${result.manifest.orgId})`,
+                `map: ${path.join(outDir, "MAP.md")}`,
+                `manifest: ${path.join(outDir, "projection.json")}`
+            ];
+            // Ambiguity rides the RESPONSE, not just MAP.md. The whole failure mode is a supervisor who
+            // never learns a choice was made — leaving the notice in a file they may not open would
+            // reproduce it one layer up.
+            const ambiguities = result.manifest.scopeAmbiguities ?? [];
+            for (const a of ambiguities) {
+                textLines.push(`AMBIGUOUS SCOPE NAME — ${a.typeName}: ${a.requestedName} — ${a.note}`);
+            }
+            if (compareTo) {
+                const diff = await diffProjections(compareTo, outDir);
+                await fs.writeFile(path.join(outDir, "diff.json"), `${JSON.stringify(diff, null, 2)}\n`, "utf8");
+                await fs.writeFile(path.join(outDir, "DIFF.md"), renderDiff(diff), "utf8");
+                diffSummary = {
+                    added: diff.added.length,
+                    removed: diff.removed.length,
+                    changed: diff.changed.length,
+                    diffPath: path.join(outDir, "DIFF.md")
+                };
+                textLines.push(`diff vs ${compareTo}: ${diff.added.length} added, ${diff.removed.length} removed, ${diff.changed.length} changed → ${path.join(outDir, "DIFF.md")}`);
+            }
+            return ok(textLines.join("\n"), {
+                dir: outDir,
+                mapPath: path.join(outDir, "MAP.md"),
+                counts: result.manifest.counts,
+                enumerationErrors: result.manifest.enumerationErrors,
+                ...(ambiguities.length ? { scopeAmbiguities: ambiguities } : {}),
+                ...(diffSummary ? { diff: diffSummary } : {})
+            });
+        }
+        catch (error) {
+            // Name the cost drivers. A bare "too large" would send the supervisor guessing, and the
+            // guess is usually wrong — the expensive entry looks identical to the cheap ones in the
+            // scope they wrote.
+            if (error instanceof ScopeTooLargeError) {
+                const worst = error.breakdown
+                    .filter((o) => o.customFields > 0)
+                    .slice(0, 5)
+                    .map((o) => `  ${o.objectApiName}: ${o.customFields} custom fields`)
+                    .join("\n");
+                return fail("SCOPE_TOO_LARGE", [
+                    `This scope resolves to ${error.total} components, over the ${error.limit} limit.`,
+                    worst ? `Biggest contributors:\n${worst}` : "",
+                    "Each custom field is a separate component. Standard objects such as Account and Contact",
+                    "carry hundreds, so adding one to scope costs far more than it appears to.",
+                    "Narrow the scope to the objects the batch actually touches, or pass maxComponents to",
+                    "raise the limit deliberately."
+                ]
+                    .filter(Boolean)
+                    .join("\n"));
+            }
+            if (error instanceof OrgReaderUnavailableError)
+                return fail("ORG_READER_UNAVAILABLE", error.message);
+            if (error instanceof SessionOrgError)
+                return fail(error.code, error.message);
+            if (error instanceof WorkspaceError)
+                return fail(error.code, error.message);
+            return internalError(error);
+        }
+    });
+}