@tpsdev-ai/flair 0.30.0 → 0.31.1

package/dist/resources/in-process.js

@@ -0,0 +1,234 @@
+/**
+ * ─── The in-process call seam (one incantation, one place) ───────────────────
+ *
+ * How code running INSIDE the Harper process invokes a flair resource AS a
+ * specific agent — flair's own native MCP handler (resources/mcp-tools.ts), and
+ * any co-located application component that loads flair as a sub-component and
+ * calls it directly instead of over HTTP.
+ *
+ * Three things an in-process caller has to get right, none of which is visible
+ * from a resource's own source and none of which used to fail in a way that
+ * points at the cause:
+ *
+ * 1. **Identity.** Every flair resource resolves its caller through
+ *    resources/agent-auth.ts's `resolveAgentAuth()`, whose FIRST hop is the
+ *    `tpsAgent` annotation the HTTP auth middleware stamps on a verified
+ *    request. There is no HTTP request in-process, so the caller supplies that
+ *    annotation itself — {@link agentContext}.
+ *
+ * 2. **Not accidentally becoming an administrator.** A context with no usable
+ *    agent id resolves to flair's trusted `internal` verdict, which is
+ *    UNFILTERED. See the safety-design block below: this module's API shape is
+ *    built around making that unreachable by accident.
+ *
+ * 3. **Collection binding.** A resource's `post()` — the create path — only
+ *    works on a resource instance Harper has marked as a COLLECTION. That mark
+ *    is a PRIVATE field (`#isCollection`) set inside Harper's own
+ *    `getResource()`; the public `isCollection` is a GETTER WITH NO SETTER on
+ *    `Resource.prototype`. So the obvious `new Cls(undefined, ctx)` +
+ *    `h.isCollection = true` does not "not work" quietly — under ESM (always
+ *    strict mode) the assignment throws
+ *    `TypeError: Cannot set property isCollection ... which has only a getter`,
+ *    and dropping the assignment instead yields
+ *    `405 The <X> does not have a post method implemented` from Harper's base
+ *    `Resource.post()`. {@link collectionResource} is the one supported way in:
+ *    hand `getResource()` an `{ isCollection: true }` option and let Harper set
+ *    its own private field.
+ *
+ * flair itself got (3) wrong in four MCP tool paths before this module existed —
+ * the same mistake a consumer reading only the resource classes would make.
+ *
+ * ─── SAFETY DESIGN: the dangerous thing has to look dangerous ────────────────
+ *
+ * MEASURED, against the real resolver:
+ *
+ *   resolveAgentAuth({ request: { tpsAgent: undefined } })  ->  { kind: "internal" }
+ *   resolveAgentAuth({ request: { tpsAgent: ""        } })  ->  { kind: "internal" }
+ *   allowAdmin({ request: { tpsAgent: undefined } })        ->  true
+ *
+ * `resolveAgentAuth` tests `tpsAgent` for TRUTHINESS, so a missing or empty id
+ * is indistinguishable from "no identity was supplied at all" — and that is the
+ * trusted verdict. The consequence is that the most ordinary application bug
+ * there is — `agentContext(session.agentId)` where the field is undefined, a
+ * typo'd property, a lookup that found nothing — would not fail closed. It
+ * would silently grant unfiltered cross-agent reads and writes, and pass the
+ * admin-only gate on admin-only resources. No error, no 403, no log line.
+ *
+ * That is the same defect class as a check that cannot fail: **the failure mode
+ * of "I forgot the id" must never be "you are now an administrator."** So:
+ *
+ *   - {@link agentContext} THROWS on a missing, empty or blank id. It is always
+ *     a programming error, and an exception is the only outcome that cannot be
+ *     mistaken for success.
+ *   - {@link agentContext} takes NO options. It is structurally incapable of
+ *     producing an admin context, so spreading a caller-influenced object into
+ *     its arguments cannot escalate.
+ *   - Admin is a SEPARATE, NAMED export ({@link adminContext}), and so is the
+ *     unfiltered maintenance verdict ({@link internalContext}). Both are
+ *     greppable: `git grep -n "adminContext\|internalContext"` enumerates every
+ *     privileged call site in a codebase.
+ *   - {@link collectionResource} REQUIRES a context and throws without one, so
+ *     the privileged path can never be reached by leaving an argument off. The
+ *     dangerous path is now the LONGEST path, not the shortest.
+ *
+ * These guards are runtime, not types, on purpose: an embedding application may
+ * be plain JavaScript, where a `string` parameter annotation buys exactly
+ * nothing. test/integration/in-process-agents.test.ts pins both the guards and
+ * the hazard they exist for, against a real Harper.
+ *
+ * ── Deliberately dependency-free ─────────────────────────────────────────────
+ * No `import { databases } from "harper"` (see resources/memory-visibility.ts
+ * for why that import is load-bearing to avoid): these helpers are pure shape,
+ * and an embedding app may want them before any table is resolved.
+ */
+/**
+ * Thrown when an in-process call is built in a way that would have silently
+ * escalated. Its own type so a caller can distinguish "I wired this wrong" from
+ * a resource's business-logic refusal (which arrives as a `Response`, not a
+ * throw).
+ */
+export class InProcessContextError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "InProcessContextError";
+    }
+}
+/** Reject anything that would resolve to the trusted `internal` verdict, or to a nonsense id. */
+function requireAgentId(agentId, fnName) {
+    if (typeof agentId !== "string" || agentId.trim() === "") {
+        const got = agentId === undefined ? "undefined"
+            : agentId === null ? "null"
+                : typeof agentId !== "string" ? `a ${typeof agentId}`
+                    : agentId === "" ? "an empty string"
+                        : "a blank string";
+        throw new InProcessContextError(`${fnName}() requires a non-empty agent id, but received ${got}. ` +
+            "This is refused rather than defaulted because flair resolves a missing or empty " +
+            "tpsAgent to its trusted `internal` verdict, which reads and writes UNFILTERED across " +
+            "every agent and passes the admin-only gate — so returning a context here would have " +
+            "turned a missing id into silent administrator access. Resolve the agent id from your " +
+            "own server-side state before calling, and never from request data.");
+    }
+    return agentId;
+}
+/**
+ * The resource context that makes an in-process call act as ONE SPECIFIC agent.
+ * This is the call an application makes; the other two constructors below are
+ * privileged and deliberately harder to type.
+ *
+ * **`agentId` is asserted, not proven.** flair reads it and acts as that agent:
+ * no signature, no lookup against the `Agent` table, no registration
+ * requirement. That is right for a caller already inside the trust boundary —
+ * it could write the raw table anyway — and it is exactly why the id must come
+ * from YOUR OWN server-side state (the session you authenticated, the job
+ * record you dequeued) and **never from request data**. An agent id that
+ * reaches here from a body field, a query param, or a header you did not verify
+ * yourself is privilege escalation with no error and no trace.
+ *
+ * Throws {@link InProcessContextError} on a missing, empty or blank id — see the
+ * safety-design block at the top of this file for why that is not merely
+ * defensive.
+ *
+ * Takes no options, and in particular no way to ask for admin: use
+ * {@link adminContext} for that, so the escalation is a word you had to type.
+ *
+ * ```ts
+ * const Memory = server.resources.get("Memory").Resource;
+ * const h = await collectionResource(Memory, agentContext("planner"));
+ * const { id } = await h.post({ agentId: "planner", content: "…" });
+ * ```
+ */
+export function agentContext(agentId) {
+    return {
+        request: {
+            tpsAgent: requireAgentId(agentId, "agentContext"),
+            tpsAgentIsAdmin: false,
+        },
+    };
+}
+/**
+ * Like {@link agentContext}, but with flair-admin authority: unfiltered
+ * cross-agent reads, and writes attributed to agents other than this one.
+ *
+ * Asserted, never checked — nothing validates that the named agent is actually
+ * an admin principal. **Treat a call to this exactly as you would a root
+ * shell:** provisioning and maintenance only, never a request handler's
+ * default, and never with an id or a flag derived from anything a caller
+ * supplied.
+ *
+ * It is a separate export rather than an option so that (a) no options object
+ * spread into {@link agentContext} can escalate, and (b) every privileged call
+ * site in a codebase is findable by name.
+ *
+ * Throws {@link InProcessContextError} on a missing, empty or blank id.
+ */
+export function adminContext(agentId) {
+    return {
+        request: {
+            tpsAgent: requireAgentId(agentId, "adminContext"),
+            tpsAgentIsAdmin: true,
+        },
+    };
+}
+/**
+ * The TRUSTED, UNATTRIBUTED, UNFILTERED context — flair's `internal` verdict.
+ * Reads see every agent's private records; writes are owned by nobody.
+ *
+ * This exists for work that is genuinely infrastructure rather than an agent's:
+ * provisioning a principal, a migration, a maintenance sweep. It is the same
+ * verdict a context-less call used to fall into by accident; naming it means an
+ * application can no longer reach it by forgetting an argument, and means
+ * `git grep internalContext` enumerates every place flair or an embedder took
+ * that authority deliberately.
+ *
+ * There is no id to validate: the verdict comes precisely from the ABSENCE of
+ * an identity annotation, so the returned object carries none. The marker field
+ * is inert — it documents intent at a debugger breakpoint and is read by
+ * nothing.
+ *
+ * ```ts
+ * // Registering a principal — infrastructure, not an agent's own write.
+ * const h = await collectionResource(Agent, internalContext());
+ * await h.post({ id, name: id, publicKey });
+ * ```
+ */
+export function internalContext() {
+    return { request: {}, __flairInternal: true };
+}
+/**
+ * A resource instance bound to `context` and marked as a COLLECTION, so its
+ * `post()` (the create path) works — see this module's header for why that mark
+ * cannot be applied from outside Harper.
+ *
+ * `context` is REQUIRED. Passing nothing used to yield the unfiltered
+ * `internal` verdict, which made the privileged path the shortest one to type;
+ * it now throws. Pass {@link agentContext} for an agent's own work,
+ * {@link adminContext} or {@link internalContext} when the authority is
+ * genuinely intended.
+ *
+ * Reads do not need this — `Cls.get(id, context)` and `Cls.search(query,
+ * context)` (Harper's static resource methods) already thread the context and
+ * start their own transaction.
+ *
+ * **They do still need the CONTEXT.** Only the collection binding is
+ * unnecessary for a read, not the identity. `Cls.search(query)` with the second
+ * argument left off does not read "as nobody" — outside a Harper request scope
+ * (a boot hook, a timer, a queue worker, a detached promise) it resolves to the
+ * same trusted `internal` verdict this module exists to keep out of reach, and
+ * returns every agent's private records unfiltered. On that path the resource's
+ * own `allow*` gate is not consulted at all, so nothing else stands in the way.
+ * Pass the context to every call, read or write (flair#936).
+ */
+export async function collectionResource(Cls, context) {
+    if (context == null || typeof context !== "object") {
+        throw new InProcessContextError("collectionResource() requires an explicit context, but received " +
+            (context === undefined ? "undefined" : context === null ? "null" : `a ${typeof context}`) +
+            ". Omitting it would resolve to flair's trusted `internal` verdict — unfiltered reads and " +
+            "unattributed writes across every agent — so the privileged path is never the one you get " +
+            "by leaving an argument off. Pass agentContext(id) to act as an agent, or internalContext() " +
+            "if this really is infrastructure work.");
+    }
+    // `{}` is a sufficient RequestTarget here: getResource() reads only `.id` off
+    // it (undefined ⇒ Harper mints the primary key), and takes the collection
+    // mark from the options argument.
+    return (await Cls.getResource({}, context, { isCollection: true }));
+}

package/dist/resources/mcp-handler.js

@@ -26,6 +26,7 @@
 import { databases } from "harper";
 import { randomBytes } from "node:crypto";
 import { TOOLS, listToolDefs } from "./mcp-tools.js";
+import { agentRecordIsAdmin } from "./agent-admin.js";
 // The MCP protocol revision we implement (initialize handshake).
 const PROTOCOL_VERSION = "2025-06-18";
 const JSON_HEADERS = { "content-type": "application/json" };
@@ -157,14 +158,23 @@ async function jitProvisionPrincipal(sub) {
     return principalId;
 }
 /**
- * Is this Principal a flair admin? Reads the Agent record's `admin`/`role`
- * fields. A MCP-OAuth agent is NON-admin unless an operator has explicitly
- * marked its Agent record admin — the MCP surface never elevates on its own.
+ * Is this Principal a flair admin? A MCP-OAuth agent is NON-admin unless an
+ * operator has explicitly marked its Agent record admin — the MCP surface never
+ * elevates on its own.
+ *
+ * flair#941: this used to OR the two admin fields together while the primary
+ * HTTP gate (resources/agent-auth.ts's isAdmin) read only `role`, so the same
+ * record could be an administrator here and an ordinary agent there. It now
+ * resolves through the one shared predicate, so both surfaces answer
+ * identically. A record carrying `admin: true` alone — which no flair write
+ * path produces, and which was never an admin on the HTTP gate — is no longer
+ * an admin here either; see resources/agent-admin.ts for the remedy. This
+ * surface is gated behind FLAIR_MCP_OAUTH and is default-OFF.
  */
 async function isAgentAdmin(principalId) {
     try {
         const agent = await databases.flair.Agent.get(principalId);
-        return agent?.admin === true || agent?.role === "admin";
+        return agentRecordIsAdmin(agent);
     }
     catch {
         return false;

package/dist/resources/mcp-tools.js

@@ -36,6 +36,7 @@
  * slice.
  */
 import { resolveVersion } from "./version.js";
+import { agentContext, adminContext, collectionResource } from "./in-process.js";
 const H = {};
 const LOADERS = {
     SemanticSearch: async () => (await import("./SemanticSearch.js")).SemanticSearch,
@@ -78,16 +79,22 @@ export function __setHandlers(overrides) {
  * agent, never anonymous, never a header re-verify.
  */
 function delegationContext(agent) {
-    return {
-        request: {
-            tpsAgent: agent.agentId,
-            tpsAgentIsAdmin: agent.isAdmin,
-            headers: {
-                get: (k) => (k.toLowerCase() === "x-tps-agent" ? agent.agentId : undefined),
-            },
-        },
-        user: undefined,
+    // Shape single-sourced from resources/in-process.ts — the same context an
+    // embedding Harper app builds to act as one of its agents — plus the
+    // `x-tps-agent` header shim the delegated handlers' own header-reading paths
+    // expect.
+    //
+    // The admin branch is spelled out rather than passed as a flag: adminContext()
+    // is the greppable name for "this call carries flair-admin authority". Both
+    // constructors THROW on an empty agent id, which is the outcome we want here —
+    // a token that resolved to no principal must fail the tool call, never fall
+    // through to flair's unfiltered `internal` verdict.
+    const ctx = agent.isAdmin ? adminContext(agent.agentId) : agentContext(agent.agentId);
+    ctx.request.headers = {
+        get: (k) => (k.toLowerCase() === "x-tps-agent" ? agent.agentId : undefined),
     };
+    ctx.user = undefined;
+    return ctx;
 }
 /**
  * Unwrap a handler return value into a plain object/string for the MCP result.
@@ -128,8 +135,7 @@ async function memorySearch(agent, args) {
 }
 async function memoryStore(agent, args) {
     const Cls = await handler("Memory");
-    const h = new Cls(undefined, delegationContext(agent));
-    h.isCollection = true;
+    const h = await collectionResource(Cls, delegationContext(agent));
     // agentId is the RESOLVED agent — Memory.post also re-checks ownership via
     // resolveAgentAuth, so a mismatched body agentId would 403 anyway; we set it
     // to the verified id so the write is correctly owned.
@@ -204,8 +210,10 @@ async function memoryUpdate(agent, args) {
         // version's provenance records which client authored this update.
         if (agent.clientId)
             record.claimedClient = agent.clientId;
-        h.isCollection = true;
-        return unwrap(await h.post(record));
+        // A create needs a COLLECTION-bound instance (see resources/in-process.ts);
+        // `h` above is the by-id handle the get()/put() branches use.
+        const coll = await collectionResource(Cls, delegationContext(agent));
+        return unwrap(await coll.post(record));
     }
     const merged = { ...existing, content, updatedAt: new Date().toISOString() };
     delete merged.embedding;
@@ -281,8 +289,7 @@ async function soulGet(agent, args) {
 }
 async function workspaceSet(agent, args) {
     const Cls = await handler("WorkspaceState");
-    const h = new Cls(undefined, delegationContext(agent));
-    h.isCollection = true;
+    const h = await collectionResource(Cls, delegationContext(agent));
     // No agentId in the body — WorkspaceState.post attributes the record to the
     // authenticated identity (from the context), never the body. Same no-forge
     // contract as the flair-mcp stdio tool.
@@ -304,8 +311,7 @@ async function workspaceSet(agent, args) {
 }
 async function orgEvent(agent, args) {
     const Cls = await handler("OrgEvent");
-    const h = new Cls(undefined, delegationContext(agent));
-    h.isCollection = true;
+    const h = await collectionResource(Cls, delegationContext(agent));
     // No authorId in the body — OrgEvent.post attributes to the authenticated
     // identity, never the body (no forging as another agent).
     const body = { kind: args?.kind, summary: args?.summary };

package/dist/resources/migration-boot.js

@@ -25,20 +25,43 @@
  * `runMigrationCycle` itself never throws (see runner.ts's module doc) —
  * the `.catch()` below is pure defense-in-depth so a bug there can never
  * take down the process either.
+ *
+ * ─── flair#812: this path must never fail silently ────────────────────────
+ * `runMigrationCycle` REPORTS why a cycle didn't run (`{ ran: false, reason
+ * }`) — it does not log it, because it is a library. This file, the only
+ * caller, previously DISCARDED that value, which is what turned a
+ * recoverable environment problem into an invisible one: on a provisioned
+ * install where `~/.flair/data` isn't creatable, the runner's very first
+ * step (`acquireMigrationLock` → `mkdirSync`) threw `EACCES`, the runner
+ * caught it and returned `reason: "lock error: ..."`, and nothing anywhere
+ * said a word. `.migrations/state.json` was never written, no
+ * `[flair-migrations]` marker ever appeared, and EVERY migration — shipped
+ * and future — was skipped on that instance forever.
+ *
+ * So: the data dir is now resolved to a candidate PROVEN writable before
+ * the cycle is handed one (resources/migrations/data-dir.ts), and every
+ * non-benign outcome — an unresolvable data dir, tables that never became
+ * ready, a runner-reported failure, an unexpected throw — is BOTH logged
+ * with a `[flair-migrations]` marker AND recorded as a `failed` progress
+ * entry per registered migration. That progress entry is what makes the
+ * condition visible where an operator will actually meet it:
+ * `/HealthDetail` (with a warning), `flair doctor`'s Migrations section
+ * (counted as an issue) and `flair quality`'s `instance.migrationsClean`.
+ *
+ * The one deliberately-quiet outcome is `single-flight` — another thread or
+ * process holds the lock and is running the cycle. That is the guard doing
+ * its job, not a failure, and Harper boots N worker threads that each load
+ * this module; logging it would emit N-1 scary lines on every healthy boot.
  */
 import { databases } from "harper";
-import { homedir } from "node:os";
 import { existsSync, readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { buildRegistry } from "./migrations/registry.js";
 import { runMigrationCycle } from "./migrations/runner.js";
-import { seedIdleProgress } from "./migrations/progress.js";
+import { markIdleMigrationsFailed, seedIdleProgress, setCyclePhase } from "./migrations/progress.js";
+import { describeUnresolvableDataDir, resolveWritableMigrationDataDir, } from "./migrations/data-dir.js";
 import { getMode } from "./embeddings-provider.js";
-/** Same dataDir resolution as resources/health.ts's disk section. */
-export function resolveMigrationDataDir() {
-    return process.env.HDB_ROOT ?? join(homedir(), ".flair", "data");
-}
 /** Same "resolve the running package's own version" idiom as resources/health.ts. */
 export function resolveRunningVersion() {
     try {
@@ -103,6 +126,26 @@ async function waitForEmbeddingsSettled(maxWaitMs = 8_500, intervalMs = 150) {
         await new Promise((r) => setTimeout(r, intervalMs));
     }
 }
+/**
+ * Records a boot-path failure everywhere an operator might look: the
+ * process log (with the `[flair-migrations]` marker the runbook greps for),
+ * the cycle status (`lastCycleError`, surfaced by `/HealthDetail` and named
+ * by `flair doctor`), and a `failed` entry for each migration that never
+ * started — because a boot path that cannot run is not a per-migration
+ * problem, it is an instance-wide one, and `flair doctor` / `flair quality`
+ * read per-migration state.
+ *
+ * `failed` (not `halted`) is deliberate for these: nothing was attempted
+ * against the corpus, so there is no halted work to resume. And the marking
+ * deliberately touches only migrations still `idle` — see
+ * `markIdleMigrationsFailed` for why overwriting a terminal state would be
+ * a downgrade rather than extra information.
+ */
+function reportBootFailure(registry, reason) {
+    console.error(`[flair-migrations] ${reason}`);
+    setCyclePhase("done", reason);
+    markIdleMigrationsFailed(registry.list().map((m) => m.id), reason);
+}
 let scheduled = false;
 export function scheduleMigrationBoot() {
     if (scheduled)
@@ -110,30 +153,57 @@ export function scheduleMigrationBoot() {
     scheduled = true;
     const registry = buildRegistry();
     seedIdleProgress(registry.list().map((m) => m.id));
+    // Proof-of-life, set SYNCHRONOUSLY at module load: from here on,
+    // `cyclePhase === "idle"` means this module never loaded at all — the
+    // one hypothesis flair#812 could not otherwise rule out from the outside.
+    setCyclePhase("scheduled");
     setImmediate(() => {
         void (async () => {
             const ready = await waitForTablesReady();
             if (!ready) {
-                console.error("[flair-migrations] Memory/Relationship tables never became ready — skipping this boot's migration cycle (will retry next boot)");
+                reportBootFailure(registry, "Memory/Relationship tables never became ready within 30s — this boot's migration cycle was skipped (it retries on the next restart)");
                 return;
             }
             await waitForEmbeddingsSettled();
+            // Resolve a data dir PROVEN writable before handing one to the runner
+            // — the runner's first act is to take a file lock there, and a
+            // failure at that point is reported back rather than thrown, which is
+            // precisely how flair#812 stayed invisible. See data-dir.ts.
+            const resolved = resolveWritableMigrationDataDir();
+            if (!resolved.dataDir) {
+                reportBootFailure(registry, describeUnresolvableDataDir(resolved.tried));
+                return;
+            }
             try {
-                await runMigrationCycle({
+                const result = await runMigrationCycle({
                     registry,
                     getTable,
-                    dataDir: resolveMigrationDataDir(),
+                    dataDir: resolved.dataDir,
                     runningVersion: resolveRunningVersion(),
                 });
+                // `nothing pending` is the healthy no-op; `single-flight` is the
+                // lock guard working as designed on a multi-threaded boot. Anything
+                // else is a cycle that WANTED to run and couldn't, and must be loud.
+                if (!result.ran && result.reason && !isBenignSkip(result.reason)) {
+                    reportBootFailure(registry, `migration cycle did not run: ${result.reason}`);
+                }
             }
             catch (err) {
                 // Defense-in-depth only — runMigrationCycle is documented to never
                 // throw. A boot-path exception must never surface here regardless.
-                console.error(`[flair-migrations] unexpected error from runMigrationCycle: ${err?.message ?? String(err)}`);
+                reportBootFailure(registry, `unexpected error from runMigrationCycle: ${err?.message ?? String(err)}`);
             }
         })();
     });
 }
+/**
+ * The two `{ ran: false }` reasons that are NOT failures: nothing was
+ * pending, or another holder is already running the cycle. Matched on the
+ * prefixes runner.ts constructs (`"nothing pending"`, `"single-flight: …"`).
+ */
+export function isBenignSkip(reason) {
+    return reason === "nothing pending" || reason.startsWith("single-flight:");
+}
 // Test-only reset so a unit/integration test can re-trigger scheduling
 // within the same process (never used in production — a real process only
 // ever boots once).