in2-agent-server 0.20260821.185429

package/dist/tools/session.js

@@ -0,0 +1,313 @@
+import path from "node:path";
+import { promises as fs } from "node:fs";
+import { z } from "zod";
+import { semanticContentHash } from "../core/semanticHash.js";
+import { opaqueId, isoNow } from "../core/ids.js";
+import { decodeHtmlEntities } from "../core/richText.js";
+import { ok, fail, internalError } from "../core/result.js";
+import { REPO_ROOT } from "../core/paths.js";
+import { runProcess, sfCliEnv } from "../core/spawn.js";
+import { sfQueryTruncation } from "../core/sfQuery.js";
+import { WorkspaceError, ensureDir, fileExists, readJson, requirementDir, sessionDir, sessionFile, writeJsonAtomic, writeTextAtomic } from "../core/workspace.js";
+export const SESSION_SCHEMA_VERSION = "cc-session-v1";
+let cachedCommit = null;
+export async function producerIdentity() {
+    if (!cachedCommit) {
+        const run = await runProcess("git", ["rev-parse", "HEAD"], {
+            cwd: REPO_ROOT,
+            timeoutMs: 10_000
+        });
+        const commit = run.exitCode === 0 ? run.stdout.trim() : "";
+        cachedCommit = /^[a-f0-9]{7,64}$/.test(commit) ? commit : "a000000";
+    }
+    return { name: "cc-mcp-server", version: "0.1.0", monorepoCommit: cachedCommit };
+}
+export async function loadSession(sessionId) {
+    const file = sessionFile(sessionId);
+    if (!fileExists(file)) {
+        throw new WorkspaceError("SESSION_NOT_FOUND", `No session at ${file}. Call create_session first.`);
+    }
+    return readJson(file);
+}
+export function requirementsIndexFile(sessionId) {
+    return path.join(sessionDir(sessionId), "requirements", "index.json");
+}
+export async function loadRequirementsIndex(sessionId) {
+    const file = requirementsIndexFile(sessionId);
+    return fileExists(file) ? readJson(file) : [];
+}
+// Campfire requirement Name / EXT alias (EXT-15342 <-> REQ-15342).
+const CAMPFIRE_NAME_RE = /^(REQ|EXT)-\d{1,10}$/;
+// Markup out, entities decoded ONCE — the shared decoder, so this read agrees with what the
+// campfire writer escaped. The sequential-replace form it replaced decoded twice: a stored
+// `&amp;lt;` came back as `<` rather than as the literal `&lt;` the record actually holds.
+function stripRichText(value) {
+    if (!value)
+        return "";
+    return decodeHtmlEntities(value
+        .replace(/<br\s*\/?>/gi, "\n")
+        .replace(/<\/(p|div|li|h[1-6])>/gi, "\n")
+        .replace(/<[^>]+>/g, ""))
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+}
+export function composeCampfireProse(record) {
+    const parts = [];
+    const title = stripRichText(record.Requirement_Name__c) || record.Name;
+    parts.push(`# ${title}`);
+    const persona = stripRichText(record.User_Story__c);
+    const action = stripRichText(record.User_Story_Action__c);
+    const suchThat = stripRichText(record.User_Story_Such_That__c);
+    if (persona || action || suchThat) {
+        parts.push(`As a ${persona || "user"}, I want to ${action || "(unspecified)"}${suchThat ? `, such that ${suchThat}` : ""}.`);
+    }
+    const description = stripRichText(record.User_Story_Description__c);
+    if (description)
+        parts.push(description);
+    // Solution design summary LEADS the content (the richest, now-primary design field).
+    // Requirement_Details__c is the legacy equivalent — normally only one is populated, but if a
+    // record carries both (older authoring), the design summary leads and details follow.
+    const designSummary = stripRichText(record.Solution_Design_Summary__c);
+    if (designSummary)
+        parts.push(`Solution design: ${designSummary}`);
+    const details = stripRichText(record.Requirement_Details__c);
+    if (details)
+        parts.push(`Details: ${details}`);
+    const given = stripRichText(record.Acceptance_Criteria_Given__c);
+    const when = stripRichText(record.Acceptance_Criteria_When__c);
+    const then = stripRichText(record.Acceptance_Criteria_Then__c);
+    if (given || when || then) {
+        parts.push(["Acceptance criteria:", given ? `- Given: ${given}` : "", when ? `- When: ${when}` : "", then ? `- Then: ${then}` : ""]
+            .filter(Boolean)
+            .join("\n"));
+    }
+    const solution = stripRichText(record.Solution_Details__c);
+    if (solution)
+        parts.push(`Solution notes: ${solution}`);
+    // Defensive: empty on all current + Bruce-corpus records, but kept for older requirements.
+    const expected = stripRichText(record.Expected_Results__c);
+    if (expected)
+        parts.push(`Expected results: ${expected}`);
+    const prereq = stripRichText(record.Pre_Requisite__c);
+    if (prereq)
+        parts.push(`Pre-requisite: ${prereq}`);
+    return `${parts.join("\n\n")}\n`;
+}
+export const CAMPFIRE_FIELDS = [
+    "Id",
+    "Name",
+    "Requirement_Name__c",
+    "User_Story__c",
+    "User_Story_Action__c",
+    "User_Story_Such_That__c",
+    "User_Story_Description__c",
+    "Acceptance_Criteria_Given__c",
+    "Acceptance_Criteria_When__c",
+    "Acceptance_Criteria_Then__c",
+    "Solution_Design_Summary__c",
+    // Legacy content field (zDEPRECATED label, empty on recent records) — still authored by
+    // some older users, so we query it and include it when present.
+    "Requirement_Details__c",
+    "Solution_Details__c",
+    // Defensive tail — empty on all current + Bruce-corpus records (2026-07-24 audit), kept for
+    // older requirements.
+    "Expected_Results__c",
+    "Pre_Requisite__c"
+];
+// Shared by import_requirements and activate_session. Extracted rather than copied so a
+// Campfire-started session and a locally-imported one produce byte-identical workspace state —
+// two implementations of this would drift, and the drift would be invisible until a delivery
+// behaved differently depending on how the session was started.
+export async function importRequirementEntries(sessionId, session, entries) {
+    const index = await loadRequirementsIndex(sessionId);
+    const byExtId = new Map(index.map((entry) => [entry.extId, entry]));
+    const imported = [];
+    for (const entry of entries) {
+        const dir = requirementDir(sessionId, entry.extId);
+        const sourcePath = path.join(dir, "source", "requirement.md");
+        const requirementId = opaqueId("req", { extId: entry.extId, sessionId: session.sessionId });
+        const inputContentHash = semanticContentHash({ text: entry.text });
+        const requirementRevisionId = opaqueId("reqrev", {
+            extId: entry.extId,
+            contentHash: inputContentHash
+        });
+        await writeTextAtomic(sourcePath, entry.text);
+        const meta = {
+            extId: entry.extId,
+            title: entry.title,
+            requirementId,
+            requirementRevisionId,
+            inputContentHash,
+            ...(entry.campfireId ? { campfireId: entry.campfireId } : {}),
+            importedAt: isoNow()
+        };
+        await writeJsonAtomic(path.join(dir, "source", "meta.json"), meta);
+        const indexEntry = {
+            extId: entry.extId,
+            title: entry.title,
+            requirementId,
+            requirementRevisionId,
+            inputContentHash,
+            sourcePath
+        };
+        byExtId.set(entry.extId, indexEntry);
+        imported.push(indexEntry);
+    }
+    const nextIndex = [...byExtId.values()].sort((a, b) => a.extId.localeCompare(b.extId));
+    await writeJsonAtomic(requirementsIndexFile(sessionId), nextIndex);
+    return imported;
+}
+export function registerSessionTools(server) {
+    server.registerTool("create_session", {
+        description: "Create (or idempotently reopen) a cc-mcp session workspace. Binds a sessionId, a requirement-batch revision id, and optionally a target org {alias, orgId}. Pure filesystem; touches no org.",
+        inputSchema: {
+            sessionId: z
+                .string()
+                .optional()
+                .describe("Session id matching ^[A-Za-z][A-Za-z0-9_-]{5,127}$. Generated when omitted."),
+            targetOrgAlias: z.string().optional().describe("sf CLI alias for the target org (e.g. int-mock-org)."),
+            targetOrgId: z
+                .string()
+                .optional()
+                .describe("15/18-char Salesforce Org ID. Defaults to T-Pinto when an alias is given without an id.")
+        }
+    }, async ({ sessionId, targetOrgAlias, targetOrgId }) => {
+        try {
+            const id = sessionId?.trim() ||
+                opaqueId("ses", { at: isoNow(), entropy: Math.random() });
+            const file = sessionFile(id);
+            if (fileExists(file)) {
+                const existing = await readJson(file);
+                if (targetOrgAlias && existing.targetOrg && existing.targetOrg.alias !== targetOrgAlias) {
+                    return fail("SESSION_ORG_CONFLICT", `Session ${id} is already bound to org alias ${existing.targetOrg.alias}; refusing to rebind to ${targetOrgAlias}.`);
+                }
+                return ok(`session ${id} already exists (reopened)`, { session: existing });
+            }
+            const record = {
+                schemaVersion: SESSION_SCHEMA_VERSION,
+                sessionId: id,
+                requirementBatchRevisionId: opaqueId("rbrev", { sessionId: id }),
+                targetOrg: targetOrgAlias
+                    ? { alias: targetOrgAlias, orgId: targetOrgId ?? "00Dfn00000BFjbBEAT" }
+                    : null,
+                producer: await producerIdentity(),
+                createdAt: isoNow()
+            };
+            await ensureDir(sessionDir(id));
+            await writeJsonAtomic(file, record);
+            return ok(`session ${id} created\nworkspace: ${sessionDir(id)}\nbatchRevision: ${record.requirementBatchRevisionId}\ntargetOrg: ${record.targetOrg ? `${record.targetOrg.alias} (${record.targetOrg.orgId})` : "unbound"}`, { session: record });
+        }
+        catch (error) {
+            if (error instanceof WorkspaceError)
+                return fail(error.code, error.message);
+            return internalError(error);
+        }
+    });
+    server.registerTool("import_requirements", {
+        description: "Materialize requirement prose into the session workspace (source/requirement.md + meta.json per extId) and update the requirements index. Sources: inline text entries, a corpus directory of <extId>.md files, and/or a LIVE Campfire pull (read-only SOQL against the consultant org: composes prose led by the Solution Design Summary — the consultant's actual design, or the legacy Requirement Details for older records — plus the user-story + description, Given/When/Then, and solution notes; EXT-15342 maps to Campfire Name REQ-15342).",
+        inputSchema: {
+            sessionId: z.string(),
+            requirements: z
+                .array(z.object({
+                extId: z.string().describe("External requirement id, e.g. EXT-9101."),
+                title: z.string(),
+                text: z.string().optional().describe("Requirement prose (inline)."),
+                path: z.string().optional().describe("Absolute path to a prose file (alternative to text).")
+            }))
+                .optional(),
+            corpusDir: z
+                .string()
+                .optional()
+                .describe("ESCAPE HATCH: directory of <extId>.md files to import wholesale. A genuine external path — requirements come from OUTSIDE the session, so unlike every other path input there is nothing to derive it from. Prefer `campfire` for a live pull."),
+            campfire: z
+                .object({
+                consultantOrg: z
+                    .string()
+                    .describe("sf CLI alias of the Campfire consultant org (e.g. vfppartial). Read-only."),
+                names: z
+                    .array(z.string())
+                    .nonempty()
+                    .describe("Campfire requirement Names (REQ-15342) or EXT aliases (EXT-15342).")
+            })
+                .optional()
+        }
+    }, async ({ sessionId, requirements, corpusDir, campfire }) => {
+        try {
+            const session = await loadSession(sessionId);
+            const entries = [];
+            if (campfire) {
+                const reqNames = [];
+                for (const raw of campfire.names) {
+                    const name = raw.trim();
+                    if (!CAMPFIRE_NAME_RE.test(name)) {
+                        return fail("INVALID_CAMPFIRE_NAME", `${JSON.stringify(raw)} is not REQ-#### or EXT-####.`);
+                    }
+                    reqNames.push(name.replace(/^EXT-/, "REQ-"));
+                }
+                const soql = `SELECT ${CAMPFIRE_FIELDS.join(", ")} FROM Campfire_Requirement__c WHERE Name IN (${[...new Set(reqNames)].map((name) => `'${name}'`).join(", ")}) ORDER BY Name`;
+                const run = await runProcess("sf", ["data", "query", "-q", soql, "--target-org", campfire.consultantOrg, "--json"], { env: sfCliEnv(), timeoutMs: 90_000 });
+                if (run.exitCode !== 0) {
+                    return fail("CAMPFIRE_READ_FAILED", `Campfire SOQL exited ${run.exitCode}. Fail-closed — nothing imported.\n${run.stderr.slice(-400) || run.stdout.slice(-400)}`);
+                }
+                const parsed = JSON.parse(run.stdout);
+                const truncation = sfQueryTruncation(parsed);
+                if (truncation) {
+                    // A capped read here would import a SUBSET of the named requirements while the
+                    // missing-name check below vouched for completeness of whatever arrived. All-or-nothing.
+                    return fail("CAMPFIRE_READ_TRUNCATED", `${truncation} Nothing imported (all-or-nothing).`);
+                }
+                const records = parsed.result?.records ?? [];
+                const foundNames = new Set(records.map((record) => record.Name));
+                const missing = reqNames.filter((name) => !foundNames.has(name));
+                if (missing.length > 0) {
+                    return fail("CAMPFIRE_REQUIREMENTS_MISSING", `Not found in ${campfire.consultantOrg}: ${missing.join(", ")}. Nothing imported (all-or-nothing).`);
+                }
+                for (const record of records) {
+                    entries.push({
+                        extId: record.Name.replace(/^REQ-/, "EXT-"),
+                        title: stripRichText(record.Requirement_Name__c) || record.Name,
+                        text: composeCampfireProse(record),
+                        campfireId: record.Id
+                    });
+                }
+            }
+            for (const requirement of requirements ?? []) {
+                let text = requirement.text;
+                if (!text && requirement.path) {
+                    text = await fs.readFile(path.resolve(requirement.path), "utf8");
+                }
+                if (!text || !text.trim()) {
+                    return fail("EMPTY_REQUIREMENT", `Requirement ${requirement.extId} has neither inline text nor a readable path.`);
+                }
+                entries.push({ extId: requirement.extId, title: requirement.title, text });
+            }
+            if (corpusDir) {
+                const dir = path.resolve(corpusDir);
+                const files = (await fs.readdir(dir)).filter((name) => name.endsWith(".md"));
+                for (const name of files) {
+                    const text = await fs.readFile(path.join(dir, name), "utf8");
+                    const extId = name.replace(/\.md$/, "");
+                    entries.push({ extId, title: extId, text });
+                }
+            }
+            if (entries.length === 0) {
+                return fail("NO_REQUIREMENTS", "Nothing to import: provide requirements[] and/or corpusDir.");
+            }
+            // Importing FROM Campfire is what proves which consultant org this session belongs to, so
+            // it is where the binding is recorded. Every later Campfire write then derives the org from
+            // the session instead of trusting an alias restated per call.
+            if (campfire && session.campfireOrg?.alias !== campfire.consultantOrg) {
+                session.campfireOrg = { alias: campfire.consultantOrg };
+                await writeJsonAtomic(sessionFile(sessionId), session);
+            }
+            const imported = await importRequirementEntries(sessionId, session, entries);
+            const lines = imported.map((entry) => `${entry.extId}\t${entry.requirementId}\t${entry.requirementRevisionId}`);
+            return ok(`imported ${imported.length} requirement(s) into session ${sessionId}\nextId\trequirementId\trequirementRevisionId\n${lines.join("\n")}`, { imported: imported, indexSize: (await loadRequirementsIndex(sessionId)).length });
+        }
+        catch (error) {
+            if (error instanceof WorkspaceError)
+                return fail(error.code, error.message);
+            return internalError(error);
+        }
+    });
+}

package/dist/tools/update.js

@@ -0,0 +1,82 @@
+// update_server — check, and apply.
+//
+// It exists at all because the consultant cannot fix a stale install themselves: they did not
+// choose the version, they cannot see it, and the symptom of running an old one is a tool behaving
+// subtly wrong rather than anything that announces itself. The supervisor is the only party in the
+// loop who can notice and act, so it gets a tool rather than the operator getting instructions.
+//
+// It is ONE tool because "is there an update?" and "install it" are two halves of one decision the
+// same caller makes seconds apart. What the old split bought — that asking can never install — is
+// a property of the default: `apply` is off, so the read-only half is what you get by omission and
+// the writing half has to be named.
+//
+// THE HOT SWAP IS GONE (2026-08-21). Applying installs via `npm install -g` and the running
+// session keeps the build it loaded — the result says so plainly. What survives from the swap era
+// is the timing doctrine: never apply mid-batch (an in-place install can hand a later lazy import
+// a different build's module); activation and close are the safe edges, and activation already
+// handles both automatically.
+import { z } from "zod";
+import { fail, ok } from "../core/result.js";
+import { installedVersion } from "../core/install.js";
+import { checkForUpdate, installUpdate } from "../core/update.js";
+export function registerUpdateTools(server) {
+    server.registerTool("update_server", {
+        title: "Check for a newer IN2 server, and optionally install it",
+        description: "The whole self-update lifecycle. READ-ONLY BY DEFAULT: with `apply` omitted this only compares the running install against the version published on npm, changes nothing, and never throws — an offline machine reports updateAvailable:false with a reason. `apply: true` runs `npm install -g` for the published version. The install lands on disk for the NEXT conversation; this session keeps running the build it started with, and the result says so. It refuses on an install npm does not manage (a repo checkout updates with git, not npm). activate_session already checks, and close_batch installs a pending update after the evidence ships — so call this directly only to re-check mid-session, to repair an install with `force`, or when a result told you to.",
+        inputSchema: {
+            apply: z
+                .boolean()
+                .optional()
+                .describe("Install the published version with `npm install -g`. OFF by default — a check must never change what is installed."),
+            force: z
+                .boolean()
+                .optional()
+                .describe("Reinstall even when the published version is not newer. For recovering a damaged install. Only meaningful with apply:true.")
+        }
+    }, async ({ apply, force }) => {
+        const current = installedVersion();
+        if (!apply) {
+            const check = await checkForUpdate();
+            const lines = [`installed ${check.currentVersion}`];
+            if (check.latestVersion)
+                lines.push(`published ${check.latestVersion}`);
+            lines.push(check.updateAvailable
+                ? check.managed
+                    ? "update available — call this tool again with { apply: true } to install it for the next conversation"
+                    : "update available, but this install is not npm-managed (a checkout updates with git pull, not this tool)"
+                : "up to date");
+            if (check.reason)
+                lines.push(`note: ${check.reason}`);
+            return ok(lines.join("\n"), { ...check, applied: false });
+        }
+        const result = await installUpdate({ force: Boolean(force) });
+        if (!result.ok) {
+            if (result.failure === "not-managed") {
+                return fail("UPDATE_NOT_MANAGED", "This server is not running from an npm install, so `npm install -g` would not change what this machine runs. A repo checkout updates with git pull; anything else needs reinstalling by hand.");
+            }
+            return fail("UPDATE_FAILED", `${result.error ?? "unknown error"} — nothing was changed; this server is still on ${current}.`);
+        }
+        if (!result.updated) {
+            return ok(`already on ${current}; published version is ${result.toVersion}. Nothing to do.`, {
+                currentVersion: current,
+                latestVersion: result.toVersion,
+                updated: false,
+                applied: true
+            });
+        }
+        return ok([
+            `installed ${result.toVersion} (was ${current})`,
+            // Stated every time because it is the one fact a reader will otherwise assume the other
+            // way: an install that succeeded did NOT change this conversation's tools.
+            "THIS conversation is still running the old build — an npm install cannot replace code a running process has loaded.",
+            "A NEW conversation starts on the new version. If you are mid-batch, finish it first; do not re-run this tool."
+        ].join("\n"), {
+            currentVersion: current,
+            previousVersion: current,
+            latestVersion: result.toVersion,
+            updated: true,
+            applied: true,
+            restartRequired: true
+        });
+    });
+}