@eir-labs/coltrane 0.24.28 → 0.24.30

package/dist/src/reside_backing.js

@@ -0,0 +1,243 @@
+/**
+ * WHERE THE SEAT LIVES — the residency backing seam.
+ *
+ * `reside` is platform-agnostic at THIS level. The engine ships the port, the selector, a local
+ * file-backed provider, a shape-check for a hand-built one, and the refusals. It ships no hosted
+ * provider of its own: a deployment injects that, the way `deps.queueGig` and
+ * `deps.mintVenueCredential` are injected. The last law in tests/spec_reside_backing.test.ts greps
+ * this file and reside.ts for platform-specific symbols, so "the engine has no platform" is a
+ * property a test can break rather than a claim in a comment.
+ *
+ * THE SELECTOR IS selectQueueBacking'S SHAPE, ONE TABLE OVER (src/local_queue.ts:153), and that is
+ * deliberate reuse of a policy this repo already argued out:
+ *   • it answers from key PRESENCE, never from a credential's value;
+ *   • two backings configured is a CONFLICT — which store owns a seat is not a thing to guess, and
+ *     a precedence order would silently prefer one operator's intent over another's;
+ *   • nothing configured names every door, so the operator learns the choices from the refusal.
+ * The one addition is a third door — a module you wrote yourself — because "local" and "hand built"
+ * are different things: one is a file layout the engine understands, the other is your code.
+ *
+ * SCOPE. This seam is about the SEAT — the four operations that move a residency row. The channel,
+ * the cortex and the work-order hands are separate axes and are supplied per-deployment regardless
+ * of where the seat lives; folding them in here would make a local seat imply a local model.
+ */
+import { readFileSync, writeFileSync, readdirSync, mkdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { DRAIN_VARS } from "./local_queue.js";
+/** The local file-backed roster's root. Its PRESENCE selects the local backing. */
+export const RESIDENCY_DIR_VAR = "COLTRANE_RESIDENCY_DIR";
+/** A module you wrote, exporting the four seat operations. Its PRESENCE selects the module backing. */
+export const RESIDENCY_MODULE_VAR = "COLTRANE_RESIDENCY_MODULE";
+/** Checked IN THIS ORDER, so a refusal names the first thing a hand-built backing forgot. */
+export const SEAT_MEMBERS = ["claim", "heartbeat", "release", "cursorAdvance"];
+/** How long a local claim holds before another box may take the seat. Mirrors the hosted lease. */
+const LOCAL_LEASE_MS = 30 * 60 * 1000;
+export function selectResidencyBacking(env) {
+    const dirRaw = env[RESIDENCY_DIR_VAR];
+    const modRaw = env[RESIDENCY_MODULE_VAR];
+    const localPresent = typeof dirRaw === "string" && dirRaw.length > 0;
+    const modulePresent = typeof modRaw === "string" && modRaw.length > 0;
+    const keys = Object.keys(env);
+    const hostedPresent = DRAIN_VARS.some((v) => keys.includes(v));
+    const chosen = [
+        localPresent ? RESIDENCY_DIR_VAR : null,
+        modulePresent ? RESIDENCY_MODULE_VAR : null,
+        hostedPresent ? "the hosted drain environment" : null,
+    ].filter((x) => x !== null);
+    if (chosen.length > 1) {
+        return {
+            backing: "conflict",
+            why: `${chosen.join(" and ")} are all configured — refusing to guess which backing owns the seat. Two boxes reading one roster both dispatch.`,
+        };
+    }
+    if (localPresent)
+        return { backing: "local", root: dirRaw };
+    if (modulePresent)
+        return { backing: "module", spec: modRaw };
+    if (hostedPresent)
+        return { backing: "hosted" };
+    return {
+        backing: "none",
+        why: `no residency backing configured — set ${RESIDENCY_DIR_VAR} for a local file-backed roster, ` +
+            `${RESIDENCY_MODULE_VAR} for a backing you wrote yourself, or the hosted drain environment ` +
+            `for a hosted seat (whose provider the deployment injects).`,
+    };
+}
+/** Every seat member present and callable, or the name of the first that is not. */
+function missingMember(candidate) {
+    if (!candidate)
+        return SEAT_MEMBERS[0];
+    for (const m of SEAT_MEMBERS) {
+        if (typeof candidate[m] !== "function")
+            return m;
+    }
+    return null;
+}
+/**
+ * Resolve a choice to a usable seat, or refuse naming what is missing. A hosted choice resolves ONLY
+ * to what a deployment injected — the engine will not conjure one, which is the whole of its
+ * platform-agnosticism. `injected.module` is accepted so a hand-built backing can be handed in
+ * directly (and so a law can drive one without writing a file).
+ */
+export async function resolveSeatBacking(choice, injected = {}) {
+    if (choice.backing === "conflict") {
+        return { ok: false, refusal: "backing_conflict", seam: "backing", message: choice.why };
+    }
+    if (choice.backing === "none") {
+        return { ok: false, refusal: "no_backend", seam: "backing", message: choice.why };
+    }
+    if (choice.backing === "local") {
+        return { ok: true, seat: fileSeatBacking(choice.root), backing: "local" };
+    }
+    if (choice.backing === "module") {
+        let candidate = injected.module;
+        if (!candidate) {
+            try {
+                const mod = (await import(choice.spec));
+                candidate = typeof mod.residencyBacking === "function" ? mod.residencyBacking() : mod.default;
+            }
+            catch (e) {
+                return {
+                    ok: false,
+                    refusal: "no_backend",
+                    seam: "module",
+                    message: `${RESIDENCY_MODULE_VAR}=${choice.spec} could not be loaded: ${e instanceof Error ? e.message : String(e)}`,
+                };
+            }
+        }
+        const missing = missingMember(candidate);
+        if (missing) {
+            return {
+                ok: false,
+                refusal: "no_backend",
+                seam: missing,
+                message: `the hand-built backing has no ${missing}() — a seat needs all of ${SEAT_MEMBERS.join(", ")}. A partial backing is refused rather than half-used.`,
+            };
+        }
+        return { ok: true, seat: candidate, backing: "module" };
+    }
+    // hosted — and the engine ships nothing for it ON PURPOSE.
+    const missing = missingMember(injected.hosted);
+    if (missing) {
+        return {
+            ok: false,
+            refusal: "no_backend",
+            seam: "hosted",
+            message: `the hosted backing is supplied by the DEPLOYMENT, not by the engine — inject it (parallel ` +
+                `to deps.queueGig / deps.mintVenueCredential). The engine ships the port, the local backing ` +
+                `and the refusals; it deliberately holds no hosted provider of its own.`,
+        };
+    }
+    return { ok: true, seat: injected.hosted, backing: "hosted" };
+}
+/**
+ * The fence check, and the reason the local backing has one at all: a backing laxer than the store it
+ * stands in for lets a bug pass locally and fail only in production. Refused with the name the
+ * ENGINE already uses for this rule (stale_fence, src/residency.ts:268) rather than a second name
+ * for one invariant.
+ */
+function assertFence(root, id, fence) {
+    const row = readRow(root, id);
+    if (Number(fence) < Number(row.fence)) {
+        throw new Error(`stale_fence: a stale fence on residency ${id} — the lease was re-claimed, or this box never held it. Claim again.`);
+    }
+    return row;
+}
+function rowPath(root, id) {
+    return join(root, `${id}.json`);
+}
+function readRow(root, id) {
+    return JSON.parse(readFileSync(rowPath(root, id), "utf8"));
+}
+function writeRow(root, row) {
+    mkdirSync(root, { recursive: true });
+    writeFileSync(rowPath(root, row.residency_id), JSON.stringify(row, null, 2) + "\n");
+}
+/** Put one seat on a local roster so there is something to claim. The local counterpart of seating. */
+export async function fileSeatSeed(root, seed) {
+    const row = {
+        residency_id: randomUUID(),
+        agent_slug: seed.agent_slug,
+        org: seed.org,
+        venue_slug: seed.venue_slug,
+        channel_id: seed.channel_id,
+        session_id: null,
+        status: "unseated",
+        cursor: 0,
+        host: null,
+        lease_until: 0,
+        hands: [],
+        fence: 0,
+    };
+    writeRow(root, row);
+    return row.residency_id;
+}
+/**
+ * A real seat on disk — not a stub. It holds a lease (so two boxes cannot both claim one roster) and
+ * it refuses a cursor regression, because a local backing that were laxer than the hosted one it
+ * stands in for would let a bug pass locally and fail only in production.
+ */
+export function fileSeatBacking(root) {
+    const now = () => Date.now();
+    return {
+        claim: async (which) => {
+            if (!existsSync(root))
+                return null;
+            const ids = readdirSync(root).filter((f) => f.endsWith(".json")).map((f) => f.slice(0, -5));
+            for (const id of ids) {
+                if (which !== "any" && id !== which)
+                    continue;
+                const row = readRow(root, id);
+                // A live lease is another box's seat. An expired one is reclaimable, so a crashed runner
+                // never wedges the roster.
+                if (row.host !== null && row.lease_until > now())
+                    continue;
+                row.host = "local";
+                row.status = "seated";
+                row.lease_until = now() + LOCAL_LEASE_MS;
+                // A NEW grant gets a NEW grip. This is what makes a re-claim by the SAME box distinguishable
+                // from its own expired grant — the failure an instance name cannot see.
+                row.fence = (row.fence ?? 0) + 1;
+                writeRow(root, row);
+                return {
+                    residency_id: row.residency_id,
+                    agent_slug: row.agent_slug,
+                    org: row.org,
+                    venue_slug: row.venue_slug,
+                    channel_id: row.channel_id,
+                    session_id: row.session_id,
+                    cursor: row.cursor,
+                    // A local seat is not a minted credential and must never read as one.
+                    lease_token: `local:${row.residency_id}`,
+                    fence: String(row.fence),
+                    gig_id: null,
+                    may_dispatch: ["*"],
+                    hands: row.hands,
+                };
+            }
+            return null;
+        },
+        heartbeat: async (id, fence) => {
+            const row = assertFence(root, id, fence);
+            row.lease_until = now() + LOCAL_LEASE_MS;
+            writeRow(root, row);
+        },
+        release: async (id, fence, status) => {
+            const row = assertFence(root, id, fence);
+            row.status = status;
+            row.host = null;
+            writeRow(root, row);
+        },
+        cursorAdvance: async (id, fence, n) => {
+            const row = assertFence(root, id, fence);
+            if (n < row.cursor) {
+                throw new Error(`cursor_regression: ${n} is behind the seat's cursor ${row.cursor} — a cursor only ever moves forward.`);
+            }
+            row.cursor = n;
+            writeRow(root, row);
+            return row.cursor;
+        },
+    };
+}
+//# sourceMappingURL=reside_backing.js.map

package/dist/src/reside_backing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reside_backing.js","sourceRoot":"","sources":["../../src/reside_backing.ts"],"names":[],"mappings":"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"}

package/dist/src/residency.d.ts

@@ -141,9 +141,13 @@ export declare function admitVenueCredential(venue: VenueLike, credentialClass:
  */
 export declare function bootResidency(spec: ResidencySpec, deps: BootDeps): BootResult;
 /**
- * The `reside` verb REUSES work's gig path — it does not fork the drain's five-variable env contract.
- * Missing COLTRANE_STORE_URL / COLTRANE_STORE_ANON is a usage refusal (exit 2), the same door work
- * uses (src/cli.ts:241-248). The gig itself is workOnce, re-exported above as residencyGigPath; the
- * store/channel wiring is a deployment seam the laws inject rather than assert here.
+ * The `reside` verb lives in src/reside.ts, with the loop it starts, and is re-exported here so the
+ * residency surface stays one import for its callers (law I20/O14 reads it from this module).
+ *
+ * It used to be a three-line stub RIGHT HERE — and that was the defect. It honoured the env contract
+ * and returned the right exit code, and `src/cli.ts`'s KNOWN table had no "reside" in it, so nothing
+ * on earth could call it: a law proved the mechanism worked while `coltrane reside` answered
+ * `unknown command`. The verb now starts a real loop and the CLI mounts it; tests/spec_reside_cli.test.ts
+ * asserts the MOUNT rather than the symbol, so this cannot quietly come undone again.
  */
-export declare function runReside(_argv: readonly string[], io: unknown): Promise<number>;
+export { runReside } from "./reside.js";

package/dist/src/residency.js

@@ -268,16 +268,16 @@ export function bootResidency(spec, deps) {
     deps.seatRow(rec);
     return { ok: true, rec };
 }
+// ── The verb mirrors work's env + exit contract (I20) ──────────────────────────────────────────────
 /**
- * The `reside` verb REUSES work's gig path — it does not fork the drain's five-variable env contract.
- * Missing COLTRANE_STORE_URL / COLTRANE_STORE_ANON is a usage refusal (exit 2), the same door work
- * uses (src/cli.ts:241-248). The gig itself is workOnce, re-exported above as residencyGigPath; the
- * store/channel wiring is a deployment seam the laws inject rather than assert here.
+ * The `reside` verb lives in src/reside.ts, with the loop it starts, and is re-exported here so the
+ * residency surface stays one import for its callers (law I20/O14 reads it from this module).
+ *
+ * It used to be a three-line stub RIGHT HERE — and that was the defect. It honoured the env contract
+ * and returned the right exit code, and `src/cli.ts`'s KNOWN table had no "reside" in it, so nothing
+ * on earth could call it: a law proved the mechanism worked while `coltrane reside` answered
+ * `unknown command`. The verb now starts a real loop and the CLI mounts it; tests/spec_reside_cli.test.ts
+ * asserts the MOUNT rather than the symbol, so this cannot quietly come undone again.
  */
-export async function runReside(_argv, io) {
-    const env = io?.env ?? {};
-    if (!env["COLTRANE_STORE_URL"] || !env["COLTRANE_STORE_ANON"])
-        return 2;
-    return 0;
-}
+export { runReside } from "./reside.js";
 //# sourceMappingURL=residency.js.map

package/dist/src/residency.js.map

@@ -1 +1 @@
-{"version":3,"file":"residency.js","sourceRoot":"","sources":["../../src/residency.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"residency.js","sourceRoot":"","sources":["../../src/residency.ts"],"names":[],"mappings":"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"}

package/dist/src/server.js

@@ -3578,7 +3578,13 @@ async function callSurfaceTool(slug, args, deps) {
 export function createToolSurface(deps) {
     return MCP_TOOLS.map((t) => ({
         name: t.slug,
-        description: `${t.category} tool`,
+        // The tool's OWN description (src/mcp.ts TOOL_DESCRIPTIONS), not a string computed from its
+        // category. This line used to be `${t.category} tool`, which meant every client — stdio and
+        // hosted alike — saw all 54 verbs described as "run tool" / "build tool" / "understand tool".
+        // The description is the field a model reads to pick a verb, so the surface was offering
+        // fifty-four choices and five distinct hints. It never looked unfinished, because it was
+        // computed: a missing description was indistinguishable from a written one.
+        description: t.description,
         input_schema: t.input_schema,
         call: (args) => callSurfaceTool(t.slug, args, deps),
     }));