@tpsdev-ai/flair 0.16.0 → 0.17.0

package/dist/cli.js

@@ -1158,6 +1158,17 @@ export function probeOpenclawPluginVersion(extensionName) {
         return null;
     }
 }
+/**
+ * Whether a package's status line should be printed in the default `flair
+ * upgrade` listing. Suppresses optional-because-openclaw-is-absent lines
+ * (ops-p42n) — pure noise on machines without openclaw — unless `--all`
+ * (showAll) is set. All other statuses always print.
+ */
+export function shouldPrintUpgradeLine(status, showAll) {
+    if (status === "optional" && !showAll)
+        return false;
+    return true;
+}
 /**
  * Order a soul key→count map for display: highest count first, ties broken
  * alphabetically for stable output. Soul entries are keyed identity facts
@@ -5871,7 +5882,13 @@ program
         {
             name: "@tpsdev-ai/flair-mcp",
             kind: "bin",
-            probe: () => probeBinVersion(execFileSync, "flair-mcp"),
+            // Older flair-mcp installs (e.g. 0.10.0) either aren't on PATH or
+            // don't support `--version`, so the bin probe returns null even when
+            // the package IS globally installed (ops-p42n). Fall back to the lib
+            // probe, which require.resolves the package.json from a sibling global
+            // install regardless of PATH or --version support. kind stays "bin" so
+            // it remains npm-upgradeable (npm install -g), not the openclaw path.
+            probe: () => probeBinVersion(execFileSync, "flair-mcp") ?? probeLibVersion("@tpsdev-ai/flair-mcp"),
         },
         {
             name: "@tpsdev-ai/openclaw-flair",
@@ -5909,6 +5926,13 @@ program
                 status = "outdated";
             }
             findings.push({ name, installed, latest, status, kind });
+            // Suppress the line for openclaw plugins that are optional-because-
+            // openclaw-is-absent (ops-p42n): on machines without openclaw the
+            // "○ … not installed (openclaw not detected) → … (install via …)"
+            // line is pure noise. Still print it when openclaw IS installed
+            // (current/outdated) or under --all.
+            if (!shouldPrintUpgradeLine(status, showAll))
+                continue;
             const icon = status === "current" ? "✅"
                 : status === "outdated" ? "⬆️"
                     : status === "optional" ? "○"
@@ -5922,6 +5946,9 @@ program
         }
         catch { /* skip unavailable packages */ }
     }
+    // Scope footer (ops-p42n): make explicit what `flair upgrade` does and
+    // doesn't cover, so "were the others checked?" has a one-line answer.
+    console.log("\nScope: npm-global packages (flair, flair-mcp) + openclaw plugins. Other integrations (pi-flair, langgraph-flair, n8n-nodes-flair, hermes-flair) upgrade in their own ecosystems (pi / pip / n8n).");
     const outdated = findings.filter((f) => f.status === "outdated");
     const missing = findings.filter((f) => f.status === "missing");
     // openclaw plugins upgrade through `openclaw plugins install`, not `npm
@@ -6009,7 +6036,7 @@ program
         }
     }
     else {
-        console.log("\nRun: flair restart  to use the new version");
+        console.log("\nRun: flair restart to use the new version");
     }
 });
 // ─── flair stop ───────────────────────────────────────────────────────────────

package/dist/resources/AdminMemory.js

@@ -22,7 +22,12 @@ import { layout, htmlResponse, esc } from "./admin-layout.js";
  */
 export class AdminMemory extends Resource {
     async get() {
-        const request = this.request;
+        // Harper v5 does not populate this.request on Resource subclasses —
+        // getContext() is the only reliable path (ops-sal4: the previous
+        // `(this as any).request` read was always undefined, so query params
+        // (?id=, ?q=, ?subject=, ?limit=) were always ignored).
+        const ctx = this.getContext?.();
+        const request = ctx?.request ?? ctx;
         const url = new URL(request?.url ?? "http://localhost", "http://localhost");
         const id = url.searchParams.get("id") ?? "";
         if (id) {

package/dist/resources/AgentSeed.js

@@ -39,7 +39,14 @@ export class AgentSeed extends Resource {
         return allowAdmin(this.getContext?.());
     }
     async post(data) {
-        const actorId = this.request?.tpsAgent;
+        // Harper v5 does not populate this.request on Resource subclasses —
+        // getContext() is the only reliable path (ops-sal4: the previous
+        // `(this as any).request` read was always undefined, so actorId was always
+        // undefined and this belt-and-suspenders check fail-closed every request,
+        // even from a real admin already verified by allowCreate()).
+        const ctx = this.getContext?.();
+        const request = ctx?.request ?? ctx;
+        const actorId = request?.tpsAgent;
         if (!actorId || !(await isAdmin(actorId))) {
             return new Response(JSON.stringify({ error: "forbidden: admin only" }), { status: 403 });
         }

package/dist/resources/IngestEvents.js

@@ -63,7 +63,13 @@ export class IngestEvents extends Resource {
         return true;
     }
     async post(body, context) {
-        const request = this.request;
+        // Harper v5 does not populate this.request on Resource subclasses —
+        // getContext() is the only reliable path (ops-sal4: the previous
+        // `(this as any).request` read was always undefined, so authHeader was
+        // always undefined and every request 401'd before reaching the office
+        // Ed25519 signature check below).
+        const ctx = this.getContext?.();
+        const request = ctx?.request ?? ctx;
         const authHeader = request?.headers?.get?.("authorization") ?? request?.headers?.authorization;
         // Parse and validate body
         let payload;

package/dist/resources/MemoryBootstrap.js

@@ -2,6 +2,7 @@ import { Resource, databases } from "@harperfast/harper";
 import { allowVerified } from "./agent-auth.js";
 import { getEmbedding } from "./embeddings-provider.js";
 import { wrapUntrusted } from "./content-safety.js";
+import { isTeammate, formatTeamLine } from "./memory-bootstrap-lib.js";
 /**
  * POST /MemoryBootstrap
  *
@@ -13,6 +14,9 @@ import { wrapUntrusted } from "./content-safety.js";
  *   4. Task-relevant memories (semantic search if currentTask provided)
  *   5. Relationship context (active relationships for mentioned entities)
  *   6. Predicted context (based on channel/surface/subject hints)
+ *   7. Team roster (other active agents in this office + a search-first nudge —
+ *      bootstrap only ever loads the caller's own memories, so this is the one
+ *      place agents learn teammates' findings exist without a separate call)
  *
  * Prediction: when context signals (channel, surface, subjects) are provided,
  * the bootstrap loads more aggressively — Flair is fast enough that the
@@ -80,6 +84,7 @@ export class BootstrapMemories extends Resource {
         const sections = {
             soul: [],
             skills: [],
+            team: [],
             permanent: [],
             recent: [],
             predicted: [],
@@ -172,6 +177,32 @@ export class BootstrapMemories extends Resource {
                 sections.skills.push(line);
             }
         }
+        // --- 1c. Team roster + cross-agent search nudge ---
+        // Bootstrap only ever loads the caller's OWN soul/memories (every query
+        // below filters record.agentId === agentId). Nothing here tells the agent
+        // that teammates exist or that their findings are one memory_search away
+        // — so agents never think to check before re-investigating something a
+        // teammate already solved. This section is fixed-cost (no query text to
+        // format per agent) so it's cheap enough to always include, not budgeted.
+        //
+        // Permissive kind/status checks are DELIBERATE: Agent.ts registration
+        // defaults both (`kind ||= "agent"`, `status ||= "active"`), so pre-1.0
+        // records missing either field are legacy agents/active — a strict
+        // `!== "agent"` check would silently drop them. Assumes single-tenant
+        // (one instance = one office); grant-filtered roster is the multi-tenant follow-up.
+        try {
+            const teammateIds = [];
+            for await (const record of databases.flair.Agent.search()) {
+                if (isTeammate(record, agentId))
+                    teammateIds.push(record.id);
+            }
+            const line = formatTeamLine(teammateIds);
+            if (line)
+                sections.team.push(line);
+        }
+        catch {
+            // Agent table may not exist in older / standalone deployments
+        }
         // --- 2. Permanent memories (always included, highest priority) ---
         const allMemories = [];
         for await (const record of databases.flair.Memory.search()) {
@@ -379,6 +410,9 @@ export class BootstrapMemories extends Resource {
         if (sections.skills.length > 0) {
             parts.push("## Active Skills\n" + sections.skills.join("\n"));
         }
+        if (sections.team.length > 0) {
+            parts.push("## Team\n" + sections.team.join("\n"));
+        }
         if (sections.permanent.length > 0) {
             parts.push("## Core Principles\n" + sections.permanent.join("\n"));
         }
@@ -405,6 +439,7 @@ export class BootstrapMemories extends Resource {
             sections: {
                 soul: sections.soul.length,
                 skills: sections.skills.length,
+                team: sections.team.length,
                 permanent: sections.permanent.length,
                 recent: sections.recent.length,
                 predicted: sections.predicted.length,

package/dist/resources/OAuth.js

@@ -1,6 +1,7 @@
 import { Resource, databases } from "@harperfast/harper";
 import { createHash, randomBytes } from "node:crypto";
 import { handleJwtBearerGrant } from "./XAA.js";
+import { resolveAgentAuth } from "./agent-auth.js";
 /**
  * OAuth 2.1 Authorization Server for Flair.
  *
@@ -121,7 +122,12 @@ export class OAuthAuthorize extends Resource {
     async get() {
         // In 1.0, this returns a simple HTML consent page.
         // The user (Nathan) approves or denies, which POSTs back.
-        const request = this.request;
+        // Harper v5 does not populate this.request on Resource subclasses —
+        // getContext() is the only reliable path (ops-sal4: the previous
+        // `(this as any).request` read was always undefined, so query params were
+        // always empty).
+        const ctx = this.getContext?.();
+        const request = ctx?.request ?? ctx;
         const url = new URL(request?.url ?? "http://localhost", "http://localhost");
         const clientId = url.searchParams.get("client_id") ?? "";
         const redirectUri = url.searchParams.get("redirect_uri") ?? "";
@@ -193,9 +199,29 @@ ${scope.split(" ").map((s) => `<div class="scope">${s}</div>`).join("")}
             const params = new URLSearchParams({ error: "access_denied", state });
             return Response.redirect(`${redirectUri}?${params}`, 302);
         }
-        // Determine authenticated principal
-        const request = this.request;
-        const principalId = request?.tpsAgent ?? "admin";
+        // Determine authenticated principal. Harper v5 does not populate
+        // this.request on Resource subclasses, so `(this as any).request?.tpsAgent`
+        // was always undefined and this ALWAYS fell back to the hardcoded "admin" —
+        // every approved consent grant was minted for the admin principal
+        // regardless of who actually approved it (ops-sal4 identity spoof).
+        // resolveAgentAuth(getContext()) resolves Basic super_user/admin auth to
+        // { kind: "agent", agentId: username, isAdmin: true } (see agent-auth.ts).
+        // We do NOT silently fall back to "admin" on an unresolved principal — if
+        // no principal can be resolved, that's an error state, not an admin grant.
+        //
+        // SECURITY REVIEW (Sherlock): is resolving the approving principal via
+        // resolveAgentAuth the correct policy for "who may approve OAuth consent"
+        // in 1.0 — i.e. must the approver be Basic-authenticated as super_user/
+        // admin, or should any verified (non-admin) agent be able to approve its
+        // own consent grant? The previous code always resolved to "admin" for
+        // every caller, so this is a genuine policy decision, not just a bug fix.
+        const auth = await resolveAgentAuth(this.getContext?.());
+        if (auth.kind !== "agent") {
+            return new Response(JSON.stringify({ error: "authentication required" }), {
+                status: 401, headers: { "content-type": "application/json" },
+            });
+        }
+        const principalId = auth.agentId;
         // Generate authorization code
         const code = randomBytes(32).toString("base64url");
         const now = nowISO();

package/dist/resources/OrgEventCatchup.js

@@ -10,7 +10,7 @@
  * Limit 50 events max.
  */
 import { Resource, databases } from "@harperfast/harper";
-import { allowVerified } from "./agent-auth.js";
+import { allowVerified, resolveAgentAuth } from "./agent-auth.js";
 export class OrgEventCatchup extends Resource {
     // Self-authorize via the Ed25519 agent verify (auth reshape removes the gate's
     // admin elevation). Any verified agent may catch up; participant scoping is in
@@ -21,9 +21,12 @@ export class OrgEventCatchup extends Resource {
     }
     // HarperDB calls get(pathInfo, context) where pathInfo is the URL segment after /OrgEventCatchup/
     async get(pathInfo) {
-        const request = this.request;
-        const callerAgent = request?.tpsAgent;
-        const callerIsAdmin = request?.tpsAgentIsAdmin === true;
+        // Harper v5 does not populate this.request on Resource subclasses —
+        // getContext() is the only reliable path to the gate's tpsAgent/
+        // tpsAgentIsAdmin annotations (ops-sal4: the previous `(this as
+        // any).request` read was always undefined, so the ownership check below
+        // never ran — fail-open cross-agent read).
+        const auth = await resolveAgentAuth(this.getContext?.());
         // Harper routes /OrgEventCatchup/{id} with pathInfo.id as the path segment
         const participantId = (typeof pathInfo === "object" && pathInfo !== null ? pathInfo.id : null) ??
             (typeof pathInfo === "string" ? pathInfo : null) ??
@@ -32,8 +35,13 @@ export class OrgEventCatchup extends Resource {
         if (!participantId) {
             return new Response(JSON.stringify({ error: "participantId required in path: GET /OrgEventCatchup/{participantId}" }), { status: 400, headers: { "Content-Type": "application/json" } });
         }
-        // Auth: requesting agent must match participantId (or admin)
-        if (callerAgent && !callerIsAdmin && callerAgent !== participantId) {
+        // Auth: internal calls and admins pass unfiltered; a verified agent may only
+        // fetch its own catchup feed; anonymous is denied. allowRead() already
+        // blocks anonymous HTTP, but this handler must fail closed on its own too.
+        if (auth.kind === "anonymous") {
+            return new Response(JSON.stringify({ error: "forbidden: can only fetch events for yourself" }), { status: 403, headers: { "Content-Type": "application/json" } });
+        }
+        if (auth.kind === "agent" && !auth.isAdmin && auth.agentId !== participantId) {
             return new Response(JSON.stringify({ error: "forbidden: can only fetch events for yourself" }), { status: 403, headers: { "Content-Type": "application/json" } });
         }
         // Harper parses query params into pathInfo.conditions array:

package/dist/resources/WorkspaceLatest.js

@@ -5,7 +5,7 @@
  * Auth: requesting agent must match agentId in path (or be admin).
  */
 import { Resource, databases } from "@harperfast/harper";
-import { allowVerified } from "./agent-auth.js";
+import { allowVerified, resolveAgentAuth } from "./agent-auth.js";
 export class WorkspaceLatest extends Resource {
     // Self-authorize via the Ed25519 agent verify (auth reshape removes the gate's
     // admin elevation). Any verified agent may read; the path-vs-agent ownership
@@ -14,9 +14,13 @@ export class WorkspaceLatest extends Resource {
         return allowVerified(this.getContext?.());
     }
     async get(pathInfo) {
-        const request = this.context?.request ?? this.request;
-        const callerAgent = request?.tpsAgent;
-        const callerIsAdmin = request?.tpsAgentIsAdmin === true;
+        // Harper v5 does not populate this.context / this.request on Resource
+        // subclasses — getContext() is the only reliable path to the gate's
+        // tpsAgent/tpsAgentIsAdmin annotations (ops-sal4: the previous
+        // `(this as any).context?.request ?? (this as any).request` read was always
+        // undefined, so the ownership check below never ran — fail-open cross-agent
+        // read).
+        const auth = await resolveAgentAuth(this.getContext?.());
         // Extract agentId from path: /WorkspaceLatest/{agentId}
         const agentId = (typeof pathInfo === "string" ? pathInfo : null) ??
             this.getId?.() ??
@@ -24,8 +28,13 @@ export class WorkspaceLatest extends Resource {
         if (!agentId) {
             return new Response(JSON.stringify({ error: "agentId required in path: GET /WorkspaceLatest/{agentId}" }), { status: 400, headers: { "Content-Type": "application/json" } });
         }
-        // Auth: requesting agent must match path agentId (or admin)
-        if (callerAgent && !callerIsAdmin && callerAgent !== agentId) {
+        // Auth: internal calls and admins pass unfiltered; a verified agent may only
+        // read its own workspace state; anonymous is denied. allowRead() already
+        // blocks anonymous HTTP, but this handler must fail closed on its own too.
+        if (auth.kind === "anonymous") {
+            return new Response(JSON.stringify({ error: "forbidden: cannot read workspace state for another agent" }), { status: 403, headers: { "Content-Type": "application/json" } });
+        }
+        if (auth.kind === "agent" && !auth.isAdmin && auth.agentId !== agentId) {
             return new Response(JSON.stringify({ error: "forbidden: cannot read workspace state for another agent" }), { status: 403, headers: { "Content-Type": "application/json" } });
         }
         // Query WorkspaceState table for this agent, sorted by timestamp desc

package/dist/resources/mcp-handler.js

@@ -0,0 +1,248 @@
+/**
+ * mcp-handler.ts — the Model-2 custom MCP protocol handler.
+ *
+ * A minimal in-process MCP (JSON-RPC 2.0) handler serving the 9 curated flair
+ * tools over Streamable HTTP. It is wrapped by `@harperfast/oauth`'s
+ * `withMCPAuth` (see mcp-oauth.ts), which fails closed on any missing/invalid
+ * Bearer token BEFORE this handler runs and, on success, sets
+ * `request.mcp = { sub, client_id, aud, scope }` (verified RS256 JWT claims).
+ *
+ * ── This handler's job ──────────────────────────────────────────────────────
+ *   1. Parse the JSON-RPC request (initialize / tools/list / tools/call / ping).
+ *   2. For tools/call: resolve `request.mcp.sub` → a flair `Agent` id via the
+ *      `Credential(kind:"idp", idpSubject=sub)` lookup, JIT-provisioning a
+ *      Principal+Credential the first time IF the trust anchor allows it.
+ *   3. Establish the flair scoping context and invoke the tool, which delegates
+ *      to the existing resource handler (per-agent scoping enforced there).
+ *
+ * /mcp is its OWN dispatch chain (urlPath subroute) — flair's default
+ * auth-middleware does NOT run here, so this handler is solely responsible for
+ * turning the verified token into a scoped flair identity.
+ *
+ * ── Return shape ────────────────────────────────────────────────────────────
+ * Harper HTTP listeners return `{ status, body, headers? }`. MCP messages are
+ * JSON-RPC 2.0, so we serialize the JSON-RPC response object as the body.
+ */
+import { databases } from "@harperfast/harper";
+import { randomBytes } from "node:crypto";
+import { TOOLS, listToolDefs } from "./mcp-tools.js";
+// The MCP protocol revision we implement (initialize handshake).
+const PROTOCOL_VERSION = "2025-06-18";
+const JSON_HEADERS = { "content-type": "application/json" };
+// ─── JSON-RPC helpers ────────────────────────────────────────────────────────
+function rpcResult(id, result) {
+    return { status: 200, headers: JSON_HEADERS, body: JSON.stringify({ jsonrpc: "2.0", id, result }) };
+}
+function rpcError(id, code, message, httpStatus = 200) {
+    return {
+        status: httpStatus,
+        headers: JSON_HEADERS,
+        body: JSON.stringify({ jsonrpc: "2.0", id: id ?? null, error: { code, message } }),
+    };
+}
+// ─── sub → Agent resolution ─────────────────────────────────────────────────
+/**
+ * Should an unknown IdP subject be JIT-provisioned into a new Principal+
+ * Credential? Gated by an explicit, auditable trust anchor — an OPEN JIT-provision
+ * means anyone who can obtain a token (which requires passing the AS's own login
+ * + DCR gate) auto-materializes a flair agent. That is the Sherlock req-4 boundary
+ * on the resolution side: provisioning is a deliberate decision, not a default.
+ *
+ * `FLAIR_MCP_JIT_PROVISION` — truthy ("1"/"true"/"yes"/"on") enables it. Default
+ * OFF: an unknown subject is denied (the operator must pre-provision the
+ * Agent+Credential, or explicitly opt into JIT). This composes with the AS-side
+ * DCR gate (initialAccessToken) — both must be deliberately opened.
+ */
+function jitProvisionEnabled() {
+    const raw = (process.env.FLAIR_MCP_JIT_PROVISION ?? "").trim().toLowerCase();
+    return raw === "1" || raw === "true" || raw === "yes" || raw === "on";
+}
+/**
+ * Resolve the OAuth token `sub` to a flair `Agent` (Principal) id.
+ *
+ * Lookup: `Credential` where `kind === "idp"` AND `idpSubject === sub`. The
+ * Credential's `principalId` is the Agent id. This is the SAME credential surface
+ * XAA's ID-JAG path uses (resources/XAA.ts resolveOrCreatePrincipal) — one
+ * identity model, keyed on the IdP subject.
+ *
+ * Returns:
+ *   - `{ agentId, isAdmin }` when a Credential maps the sub to an Agent.
+ *   - null when no Credential maps the sub AND JIT-provisioning is disabled or
+ *     failed → the handler denies the tool call (sub is unresolvable).
+ */
+export async function resolveAgentFromSub(sub) {
+    if (!sub)
+        return null;
+    // 1. Existing IdP credential → its principalId is the Agent id.
+    try {
+        for await (const cred of databases.flair.Credential.search({
+            conditions: [
+                { attribute: "kind", comparator: "equals", value: "idp" },
+                { attribute: "idpSubject", comparator: "equals", value: sub },
+            ],
+        })) {
+            if (cred?.principalId && cred.status !== "revoked") {
+                // Touch lastUsedAt (best-effort; a failure here must not deny a valid call).
+                try {
+                    await databases.flair.Credential.put({ ...cred, lastUsedAt: new Date().toISOString() });
+                }
+                catch { /* non-fatal */ }
+                return { agentId: String(cred.principalId), isAdmin: await isAgentAdmin(cred.principalId) };
+            }
+        }
+    }
+    catch { /* Credential table empty / search error → fall through to JIT/deny */ }
+    // 2. No mapping. JIT-provision only behind the explicit trust anchor.
+    if (!jitProvisionEnabled())
+        return null;
+    try {
+        const principalId = await jitProvisionPrincipal(sub);
+        // A JIT-provisioned principal is a fresh, non-admin agent by construction.
+        return { agentId: principalId, isAdmin: false };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * JIT-provision a Principal (Agent record) + an IdP Credential from a verified
+ * token subject. Mirrors XAA.resolveOrCreatePrincipal's provisioning shape (the
+ * `Credential.kind:"idp"` + `idpSubject` surface) but keyed on the MCP token sub.
+ * The created agent is non-admin, `kind:"agent"`, unverified trust tier.
+ */
+async function jitProvisionPrincipal(sub) {
+    const now = new Date().toISOString();
+    const principalId = `agt_mcp_${sub.replace(/[^a-zA-Z0-9]/g, "_").slice(0, 24)}_${randomBytes(4).toString("hex")}`;
+    await databases.flair.Agent.put({
+        id: principalId,
+        name: principalId,
+        displayName: principalId,
+        kind: "agent",
+        type: "agent",
+        status: "active",
+        // Placeholder public key — an MCP-OAuth agent authenticates via bearer token,
+        // not an Ed25519 signing key. Marks provenance without forging a real key.
+        publicKey: `mcp-oauth:${sub}`,
+        defaultTrustTier: "unverified",
+        admin: false,
+        createdAt: now,
+        updatedAt: now,
+    });
+    await databases.flair.Credential.put({
+        id: `cred_mcp_${randomBytes(8).toString("hex")}`,
+        principalId,
+        kind: "idp",
+        label: "MCP OAuth (native /mcp)",
+        status: "active",
+        idpProvider: "mcp-oauth",
+        idpSubject: sub,
+        createdAt: now,
+        lastUsedAt: now,
+    });
+    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.
+ */
+async function isAgentAdmin(principalId) {
+    try {
+        const agent = await databases.flair.Agent.get(principalId);
+        return agent?.admin === true || agent?.role === "admin";
+    }
+    catch {
+        return false;
+    }
+}
+// ─── MCP protocol dispatch ───────────────────────────────────────────────────
+/**
+ * The custom /mcp handler. `withMCPAuth` guarantees `request.mcp` is present here
+ * (it fails closed before us on a missing/invalid token), so we read the verified
+ * `sub` directly. Handles a single JSON-RPC request per POST (the minimal
+ * Streamable-HTTP shape the curated surface needs; batching is not used by the
+ * MCP clients we target).
+ */
+export async function mcpHandler(request) {
+    // MCP is a POST-only JSON-RPC surface. A GET (e.g. an SSE stream open) is not
+    // part of the curated request/response tool flow — reject cleanly.
+    const method = String(request?.method ?? "POST").toUpperCase();
+    if (method !== "POST") {
+        return rpcError(null, -32600, "method not allowed: /mcp accepts JSON-RPC POST only", 405);
+    }
+    // Parse the JSON-RPC body. Harper's Request wraps a Node stream — read text.
+    let msg;
+    try {
+        const text = typeof request.text === "function" ? await request.text() : request.body;
+        msg = typeof text === "string" ? JSON.parse(text) : text;
+    }
+    catch {
+        return rpcError(null, -32700, "parse error: invalid JSON");
+    }
+    if (!msg || typeof msg !== "object" || msg.jsonrpc !== "2.0" || typeof msg.method !== "string") {
+        return rpcError(msg?.id ?? null, -32600, "invalid request: expected JSON-RPC 2.0");
+    }
+    const { id, method: rpcMethod, params } = msg;
+    switch (rpcMethod) {
+        case "initialize":
+            return rpcResult(id, {
+                protocolVersion: PROTOCOL_VERSION,
+                capabilities: { tools: {} },
+                serverInfo: { name: "flair", version: "0.1.0" },
+            });
+        // Notifications (no id) — acknowledge with 202-ish empty 200; MCP clients send
+        // `notifications/initialized` after initialize.
+        case "notifications/initialized":
+            return { status: 200, headers: JSON_HEADERS, body: "" };
+        case "ping":
+            return rpcResult(id, {});
+        case "tools/list":
+            return rpcResult(id, { tools: listToolDefs() });
+        case "tools/call":
+            return handleToolCall(request, id, params);
+        default:
+            return rpcError(id, -32601, `method not found: ${rpcMethod}`);
+    }
+}
+/**
+ * tools/call: resolve the token sub → flair Agent, then dispatch to the curated
+ * tool. An unresolvable sub is DENIED (not silently run as anonymous or admin).
+ */
+async function handleToolCall(request, id, params) {
+    const toolName = params?.name;
+    const args = params?.arguments ?? {};
+    const entry = toolName ? TOOLS[toolName] : undefined;
+    if (!entry) {
+        return rpcError(id, -32602, `unknown tool: ${toolName ?? "(none)"}`);
+    }
+    // withMCPAuth guarantees request.mcp on success. Defense-in-depth: if it's
+    // somehow absent, deny (never run a tool without a verified sub).
+    const sub = request?.mcp?.sub;
+    if (!sub) {
+        return rpcError(id, -32001, "unauthorized: no verified token subject");
+    }
+    const agent = await resolveAgentFromSub(String(sub));
+    if (!agent) {
+        // Sub verified by the AS but not mapped to a flair Agent (and JIT disabled /
+        // failed). Deny — do NOT fall back to anonymous or admin.
+        return rpcError(id, -32001, "forbidden: token subject is not a provisioned flair agent");
+    }
+    try {
+        const result = await entry.impl(agent, args);
+        // MCP tools/call result: content blocks. Surface the handler's JSON payload
+        // as a text block (structuredContent carries the raw object for programmatic
+        // clients). A handler-level error object (from unwrap of a Response) is
+        // reported as an MCP tool error (isError) rather than a JSON-RPC error, so
+        // the client sees the structured message.
+        const text = typeof result === "string" ? result : JSON.stringify(result);
+        const isError = !!(result && typeof result === "object" && "error" in result && "status" in result);
+        return rpcResult(id, {
+            content: [{ type: "text", text }],
+            structuredContent: typeof result === "object" ? result : { value: result },
+            isError,
+        });
+    }
+    catch (err) {
+        return rpcError(id, -32000, `tool execution failed: ${err?.message ?? String(err)}`);
+    }
+}

package/dist/resources/mcp-oauth-flag.js

@@ -0,0 +1,84 @@
+/**
+ * mcp-oauth-flag.ts — the feature flag + AS config for the native-MCP OAuth
+ * surface (FLAIR-NATIVE-MCP-OAUTH, Model 2).
+ *
+ * Model 2 = a CUSTOM in-process `/mcp` JSON-RPC handler wrapped with
+ * `@harperfast/oauth`'s `withMCPAuth` (a fail-closed Bearer-token guard). It is
+ * DISTINCT from the native-application-MCP surface (design A / the
+ * `native-mcp-surface` branch's `static mcpTools`) — Model 2 does not use
+ * Harper's native MCP transport at all, so it is not blocked by the Harper
+ * native-MCP timing/worker gating gaps. The curated 9 tools are curated
+ * BY CONSTRUCTION (the handler only implements those 9).
+ *
+ * ── Default-OFF ─────────────────────────────────────────────────────────────
+ * The whole surface is gated behind `FLAIR_MCP_OAUTH`, default-OFF. When off:
+ *   - NO `/mcp` route is registered (mcpOAuthResource() early-returns).
+ *   - The `@harperfast/oauth` authorization-server config is NOT injected.
+ *   - flair's default auth chain is byte-identical to today.
+ * There is zero prod-behavior change until an operator explicitly opts in AND
+ * Sherlock signs off on live enablement.
+ *
+ * NOTE — separate flag from the native-MCP surface: `FLAIR_MCP_ENABLED` gates the
+ * design-A native surface (other branch); `FLAIR_MCP_OAUTH` gates THIS Model-2
+ * OAuth-guarded custom handler. They are independent flags for independent
+ * mechanisms; neither implies the other.
+ */
+/**
+ * Is the Model-2 OAuth-guarded /mcp surface enabled? Default-OFF.
+ *
+ * Read from `FLAIR_MCP_OAUTH` — truthy values: "1", "true", "yes", "on"
+ * (case-insensitive). Anything else (incl. unset / empty) → OFF.
+ */
+export function mcpOAuthEnabled() {
+    const raw = (process.env.FLAIR_MCP_OAUTH ?? "").trim().toLowerCase();
+    return raw === "1" || raw === "true" || raw === "yes" || raw === "on";
+}
+/**
+ * The public origin the authorization server pins `iss` (and, via it, `aud`) to.
+ * REQUIRED when the surface is enabled — the @harperfast/oauth plugin refuses to
+ * start without `mcp.issuer`, and pinning it (rather than letting it float with
+ * the client-controlled Host header) is the audience-confusion defense called
+ * out in the plugin's production checklist.
+ *
+ * Configurable via `FLAIR_MCP_ISSUER` (fall back to `FLAIR_PUBLIC_URL`, which the
+ * XAA token path already uses as the canonical public base). No hardcoded
+ * default — an operator turning the flag on MUST set the public origin.
+ */
+export function mcpIssuer() {
+    const raw = (process.env.FLAIR_MCP_ISSUER ?? process.env.FLAIR_PUBLIC_URL ?? "").trim();
+    return raw || undefined;
+}
+/**
+ * The RFC-8707 resource identifier tokens are audience-bound to. This is the
+ * public URL of the `/mcp` endpoint itself: `<issuer>/mcp`. `withMCPAuth`
+ * verifies the `aud` claim equals this, so the token minted for flair's `/mcp`
+ * cannot be replayed against a different resource server.
+ */
+export function mcpResource() {
+    const iss = mcpIssuer();
+    if (!iss)
+        return undefined;
+    return `${iss.replace(/\/+$/, "")}/mcp`;
+}
+/**
+ * `getConfig` payload injected into `withMCPAuth` so it verifies against the
+ * exact issuer/resource the authorization-server component mints tokens with —
+ * required because flair's `/mcp` handler and the @harperfast/oauth plugin may
+ * resolve different `node_modules` copies (docs/mcp-oauth.md §"Using withMCPAuth
+ * from a different component"), in which case the wrapper's live-config lookup
+ * reads `undefined` and fails closed. Pinning it here makes the iss/aud checks
+ * match the minted tokens.
+ *
+ * Returns undefined when the surface is off or the issuer is unset (the wrapper
+ * then denies — never serves a guarded route unconfigured, which is the safe
+ * failure mode).
+ */
+export function mcpAuthConfig() {
+    if (!mcpOAuthEnabled())
+        return undefined;
+    const issuer = mcpIssuer();
+    const resource = mcpResource();
+    if (!issuer || !resource)
+        return undefined;
+    return { enabled: true, issuer, resource };
+}

package/dist/resources/mcp-oauth.js

@@ -0,0 +1,84 @@
+/**
+ * mcp-oauth.ts — registers the Model-2 OAuth-guarded /mcp surface.
+ *
+ * Wraps the custom `mcpHandler` (mcp-handler.ts) with `@harperfast/oauth`'s
+ * `withMCPAuth` (a fail-closed Bearer-token guard) and mounts it on the `/mcp`
+ * urlPath subroute — its OWN dispatch chain, so flair's default auth-middleware
+ * never runs for /mcp and can't clobber the Bearer challenge.
+ *
+ * ── Default-OFF (byte-identical when off) ───────────────────────────────────
+ * The route is registered ONLY when `FLAIR_MCP_OAUTH` is truthy. When off, this
+ * module does NOTHING at load — no `server.http` call, no `@harperfast/oauth`
+ * import, no config injection. flair's default auth chain and prod behavior are
+ * unchanged. This is the no-op contract the flag guarantees.
+ *
+ * The `@harperfast/oauth` authorization-server config itself (providers, mcp.*,
+ * DCR gating) lives in `config.yaml` under the `@harperfast/oauth` key, but is
+ * only meaningful when an operator has set the issuer + enabled the flag (see
+ * docs). The plugin serves DCR / authorize / token / JWKS / discovery.
+ */
+import * as harper from "@harperfast/harper";
+import { mcpOAuthEnabled, mcpAuthConfig } from "./mcp-oauth-flag.js";
+import { mcpHandler } from "./mcp-handler.js";
+async function defaultLoadWithMCPAuth() {
+    // Dynamic import so the dep is only required when the surface is enabled.
+    const mod = (await import("@harperfast/oauth"));
+    return mod.withMCPAuth;
+}
+export async function registerMcpOAuthRoute(deps = {}) {
+    if (!mcpOAuthEnabled())
+        return false; // OFF → no route, no import, no side effects.
+    const config = mcpAuthConfig();
+    if (!config) {
+        // Flag on but issuer unset → we cannot safely pin iss/aud. Do NOT mount an
+        // unconfigured guard (withMCPAuth would fail closed anyway, but not mounting
+        // is the clearer signal). Log and bail — the operator must set FLAIR_MCP_ISSUER.
+        console.error("[mcp-oauth] FLAIR_MCP_OAUTH is on but no issuer configured " +
+            "(set FLAIR_MCP_ISSUER or FLAIR_PUBLIC_URL) — /mcp NOT mounted.");
+        return false;
+    }
+    let withMCPAuth;
+    try {
+        withMCPAuth = await (deps.loadWithMCPAuth ?? defaultLoadWithMCPAuth)();
+    }
+    catch (err) {
+        console.error("[mcp-oauth] @harperfast/oauth not available — /mcp NOT mounted: " + (err?.message ?? err));
+        return false;
+    }
+    if (typeof withMCPAuth !== "function") {
+        console.error("[mcp-oauth] @harperfast/oauth has no withMCPAuth export — /mcp NOT mounted.");
+        return false;
+    }
+    // Read `server` lazily off the namespace (it's a runtime global on the Harper
+    // module, not a static named export) so this module links cleanly even where a
+    // stub build of @harperfast/harper lacks the export.
+    const srv = deps.server ?? (harper.server);
+    // Primary registration: urlPath subroute → own chain (flair's auth-middleware
+    // does not run here). `getConfig` pins iss/resource to the AS's values so the
+    // wrapper's iss/aud checks match the minted tokens even if this component
+    // resolves a different node_modules copy of the plugin (docs/mcp-oauth.md
+    // §"Using withMCPAuth from a different component").
+    srv.http(withMCPAuth(mcpHandler, {
+        getConfig: () => mcpAuthConfig(),
+    }), { urlPath: "/mcp" });
+    console.error(`[mcp-oauth] /mcp mounted (OAuth-guarded); issuer=${config.issuer}`);
+    return true;
+}
+// Fire-and-forget at module load. Any failure is contained inside
+// registerMcpOAuthRoute (it logs and returns) so it can never crash flair boot.
+// When the flag is off it returns immediately without importing the plugin or
+// touching `server` — the byte-identical no-op contract.
+//
+// Skipped ONLY when a test explicitly opts out via FLAIR_MCP_NO_AUTOSTART, so
+// importing this module in a unit test doesn't trigger the real plugin/handler
+// import chain under a partial harper mock (registration is exercised directly
+// via the exported fn). Production never sets this, so boot behavior is
+// unchanged — and when the flag is off, registerMcpOAuthRoute() is a no-op
+// regardless. (bun test runs under Node's runtime here via the harper toolchain;
+// we don't gate on the runtime to avoid disabling the feature in a bun-hosted
+// deployment.)
+if (process.env.FLAIR_MCP_NO_AUTOSTART == null) {
+    void registerMcpOAuthRoute().catch((err) => {
+        console.error("[mcp-oauth] route registration failed (surface not mounted): " + (err?.message ?? err));
+    });
+}

package/dist/resources/mcp-tools.js

@@ -0,0 +1,347 @@
+/**
+ * mcp-tools.ts — the 9 curated flair tools for the Model-2 custom /mcp handler.
+ *
+ * Curated BY CONSTRUCTION: this module implements exactly the 9 tools that the
+ * `@tpsdev-ai/flair-mcp` stdio proxy exposes, each a thin wrapper over the
+ * existing flair Resource handler. No business logic is re-implemented — the
+ * wrapped handlers (Memory / SemanticSearch / BootstrapMemories / Soul /
+ * WorkspaceState / OrgEvent) enforce per-agent scoping/ownership via
+ * `resolveAgentAuth(getContext())`, so the MCP surface inherits the SAME security
+ * model as the signed-REST path. There is no raw CRUD surface — the only way to
+ * reach the datastore through /mcp is via one of these 9 semantic tools.
+ *
+ *   memory_search · memory_store · memory_get · memory_delete · bootstrap ·
+ *   soul_set · soul_get · flair_workspace_set · flair_orgevent
+ *
+ * ── The scoping seam ────────────────────────────────────────────────────────
+ * The /mcp handler resolves the OAuth token's `sub` → a flair `Agent` id, then
+ * calls a tool with a `ResolvedAgent { agentId, isAdmin }`. Each tool builds a
+ * flair-shaped Resource context (`delegationContext`) carrying `request.tpsAgent`
+ * + `request.tpsAgentIsAdmin`, so the wrapped handler scopes to the verified
+ * agent exactly as an Ed25519-signed REST call would. Identity ALWAYS comes from
+ * the resolved agent, never from the tool arguments — an agent can only act as
+ * itself (no forging of agentId / authorId in the body).
+ */
+const H = {};
+const LOADERS = {
+    SemanticSearch: async () => (await import("./SemanticSearch.js")).SemanticSearch,
+    Memory: async () => (await import("./Memory.js")).Memory,
+    BootstrapMemories: async () => (await import("./MemoryBootstrap.js")).BootstrapMemories,
+    Soul: async () => (await import("./Soul.js")).Soul,
+    WorkspaceState: async () => (await import("./WorkspaceState.js")).WorkspaceState,
+    OrgEvent: async () => (await import("./OrgEvent.js")).OrgEvent,
+};
+/** Resolve a handler class — from the test override if set, else lazy-load + cache. */
+async function handler(key) {
+    if (H[key])
+        return H[key];
+    const cls = await LOADERS[key]();
+    H[key] = cls;
+    return cls;
+}
+/** TEST-ONLY: override the delegated handler classes. Returns a restore fn. */
+export function __setHandlers(overrides) {
+    const prev = { ...H };
+    Object.assign(H, overrides);
+    return () => {
+        for (const k of Object.keys(H))
+            delete H[k];
+        Object.assign(H, prev);
+    };
+}
+/**
+ * Build a flair-shaped Resource context for a delegated handler call. The
+ * handlers read identity via `resolveAgentAuth(getContext())`, which checks
+ * `context.request.tpsAgent` / `tpsAgentIsAdmin`. We construct exactly that shape
+ * so the wrapped handler scopes to the verified agent — identical to the
+ * signed-REST path. `headers.get("x-tps-agent")` is provided for handler paths
+ * that read the header directly (e.g. MemoryBootstrap fallback).
+ *
+ * Critically: `tpsAnonymous` is NOT set and no Authorization header is present,
+ * so `resolveAgentAuth` takes the `tpsAgent` annotation branch — a verified
+ * 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,
+    };
+}
+/**
+ * Unwrap a handler return value into a plain object/string for the MCP result.
+ * Handlers may return a `Response` (the 401/403/400 guards) — surface its JSON
+ * body (and status) so the client sees the structured error rather than an
+ * opaque object. A thrown handler error propagates to the caller (the handler
+ * maps it to a JSON-RPC error).
+ */
+async function unwrap(value) {
+    if (value && typeof value === "object" && typeof value.json === "function" && "status" in value) {
+        try {
+            const body = await value.json();
+            return { error: body?.error ?? "request failed", status: value.status, ...body };
+        }
+        catch {
+            return { error: "request failed", status: value.status };
+        }
+    }
+    return value;
+}
+// ── Tool implementations (thin wrappers over existing handlers) ──────────────
+//
+// Each takes the resolved agent + the parsed tool arguments and returns a plain
+// JSON-serializable value. Identity is taken from `agent`, never from `args`.
+async function memorySearch(agent, args) {
+    const Cls = await handler("SemanticSearch");
+    const h = new Cls(undefined, delegationContext(agent));
+    return unwrap(await h.post({ q: args?.query, limit: args?.limit ?? 5 }));
+}
+async function memoryStore(agent, args) {
+    const Cls = await handler("Memory");
+    const h = new Cls(undefined, delegationContext(agent));
+    h.isCollection = true;
+    // 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.
+    return unwrap(await h.post({
+        agentId: agent.agentId,
+        content: args?.content,
+        type: args?.type ?? "session",
+        durability: args?.durability ?? "standard",
+        tags: args?.tags,
+    }));
+}
+async function memoryGet(agent, args) {
+    const Cls = await handler("Memory");
+    const h = new Cls(undefined, delegationContext(agent));
+    return unwrap(await h.get(args?.id));
+}
+async function memoryDelete(agent, args) {
+    const Cls = await handler("Memory");
+    const h = new Cls(undefined, delegationContext(agent));
+    return unwrap(await h.delete(args?.id));
+}
+async function bootstrap(agent, args) {
+    const Cls = await handler("BootstrapMemories");
+    const h = new Cls(undefined, delegationContext(agent));
+    return unwrap(await h.post({
+        agentId: agent.agentId,
+        maxTokens: args?.maxTokens ?? 4000,
+        currentTask: args?.currentTask,
+        channel: args?.channel,
+        surface: args?.surface,
+        subjects: args?.subjects,
+    }));
+}
+async function soulSet(agent, args) {
+    const Cls = await handler("Soul");
+    const h = new Cls(undefined, delegationContext(agent));
+    // Soul records are keyed `id = agentId:key` (see flair-client SoulApi.set and
+    // schemas/memory.graphql). Use PUT with the explicit id so soul_get's
+    // `${agentId}:${key}` lookup finds it — a plain post() would mint a random id
+    // and orphan the entry from get(). Soul.put enforces write ownership via
+    // resolveAgentAuth (non-admin can only write agentId === self).
+    const id = `${agent.agentId}:${args?.key}`;
+    return unwrap(await h.put({
+        id,
+        agentId: agent.agentId,
+        key: args?.key,
+        value: args?.value,
+    }));
+}
+async function soulGet(agent, args) {
+    const Cls = await handler("Soul");
+    const h = new Cls(undefined, delegationContext(agent));
+    return unwrap(await h.get(`${agent.agentId}:${args?.key}`));
+}
+async function workspaceSet(agent, args) {
+    const Cls = await handler("WorkspaceState");
+    const h = new Cls(undefined, delegationContext(agent));
+    h.isCollection = true;
+    // 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.
+    const body = {
+        id: `${agent.agentId}:${args?.ref}`,
+        ref: args?.ref,
+        provider: args?.provider ?? "mcp",
+        timestamp: new Date().toISOString(),
+    };
+    if (args?.label)
+        body.label = args.label;
+    if (args?.task)
+        body.taskId = args.task;
+    if (args?.phase)
+        body.phase = args.phase;
+    if (args?.summary)
+        body.summary = args.summary;
+    return unwrap(await h.post(body));
+}
+async function orgEvent(agent, args) {
+    const Cls = await handler("OrgEvent");
+    const h = new Cls(undefined, delegationContext(agent));
+    h.isCollection = true;
+    // 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 };
+    if (args?.detail)
+        body.detail = args.detail;
+    if (args?.scope)
+        body.scope = args.scope;
+    if (Array.isArray(args?.targets) && args.targets.length > 0)
+        body.targetIds = args.targets;
+    return unwrap(await h.post(body));
+}
+export const TOOLS = {
+    memory_search: {
+        def: {
+            name: "memory_search",
+            description: "Search memories by meaning. Understands temporal queries like 'what happened today'. Scoped to your agent's own + granted memories.",
+            annotations: { readOnlyHint: true },
+            inputSchema: {
+                type: "object",
+                properties: {
+                    query: { type: "string", description: "Search query — natural language, semantic matching" },
+                    limit: { type: "number", description: "Max results (default 5)" },
+                },
+                required: ["query"],
+            },
+        },
+        impl: memorySearch,
+    },
+    memory_store: {
+        def: {
+            name: "memory_store",
+            description: "Save information to persistent memory. Use for lessons, decisions, preferences, facts. Attributed to your authenticated agent.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    content: { type: "string", description: "What to remember" },
+                    type: { type: "string", enum: ["session", "lesson", "decision", "preference", "fact", "goal"], description: "Memory type (default session)" },
+                    durability: { type: "string", enum: ["permanent", "persistent", "standard", "ephemeral"], description: "permanent > persistent > standard > ephemeral (default standard)" },
+                    tags: { type: "array", items: { type: "string" }, description: "Tag strings" },
+                },
+                required: ["content"],
+            },
+        },
+        impl: memoryStore,
+    },
+    memory_get: {
+        def: {
+            name: "memory_get",
+            description: "Retrieve a specific memory by ID.",
+            annotations: { readOnlyHint: true },
+            inputSchema: {
+                type: "object",
+                properties: { id: { type: "string", description: "Memory ID" } },
+                required: ["id"],
+            },
+        },
+        impl: memoryGet,
+    },
+    memory_delete: {
+        def: {
+            name: "memory_delete",
+            description: "Delete a memory by ID. You can only delete your own memories.",
+            annotations: { destructiveHint: true },
+            inputSchema: {
+                type: "object",
+                properties: { id: { type: "string", description: "Memory ID to delete" } },
+                required: ["id"],
+            },
+        },
+        impl: memoryDelete,
+    },
+    bootstrap: {
+        def: {
+            name: "bootstrap",
+            description: "Get session context: soul + memories + predicted context. Run at session start. Pass subjects for predictive loading.",
+            annotations: { readOnlyHint: true },
+            inputSchema: {
+                type: "object",
+                properties: {
+                    maxTokens: { type: "number", description: "Max tokens in output (default 4000)" },
+                    currentTask: { type: "string", description: "Current task — enables semantic search for relevant memories" },
+                    channel: { type: "string", description: "Channel name (discord, tps-mail, claude-code)" },
+                    surface: { type: "string", description: "Surface name (tps-build, tps-review, cli-session)" },
+                    subjects: { type: "array", items: { type: "string" }, description: "Entity names to preload context for" },
+                },
+            },
+        },
+        impl: bootstrap,
+    },
+    soul_set: {
+        def: {
+            name: "soul_set",
+            description: "Set a personality or project context entry. Included in every bootstrap.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    key: { type: "string", description: "Entry key (e.g. 'role', 'standards', 'project')" },
+                    value: { type: "string", description: "Entry value" },
+                },
+                required: ["key", "value"],
+            },
+        },
+        impl: soulSet,
+    },
+    soul_get: {
+        def: {
+            name: "soul_get",
+            description: "Get a personality or project context entry.",
+            annotations: { readOnlyHint: true },
+            inputSchema: {
+                type: "object",
+                properties: { key: { type: "string", description: "Entry key" } },
+                required: ["key"],
+            },
+        },
+        impl: soulGet,
+    },
+    flair_workspace_set: {
+        def: {
+            name: "flair_workspace_set",
+            description: "Set your agent's current workspace state in the Office Space coordination layer. Attributed to you — you can only write your own state.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    ref: { type: "string", description: "Workspace ref — branch, worktree, or task ref" },
+                    label: { type: "string", description: "Human-readable label" },
+                    provider: { type: "string", description: "Provider/runtime (default mcp)" },
+                    task: { type: "string", description: "Task/issue id" },
+                    phase: { type: "string", description: "Current phase (design, implement, review)" },
+                    summary: { type: "string", description: "Short summary of current state" },
+                },
+                required: ["ref"],
+            },
+        },
+        impl: workspaceSet,
+    },
+    flair_orgevent: {
+        def: {
+            name: "flair_orgevent",
+            description: "Publish an org-wide coordination event (claim/release/status) to the Office Space. Attributed to you — you cannot publish as another agent.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    kind: { type: "string", description: "Event kind (coord.claim, coord.release, status)" },
+                    summary: { type: "string", description: "Short summary of the event" },
+                    detail: { type: "string", description: "Longer detail payload" },
+                    scope: { type: "string", description: "Scope (an agent id, repo, or 'org')" },
+                    targets: { type: "array", items: { type: "string" }, description: "Recipient agent ids" },
+                },
+                required: ["kind", "summary"],
+            },
+        },
+        impl: orgEvent,
+    },
+};
+/** The tool definitions for a tools/list response (exactly the 9 curated tools). */
+export function listToolDefs() {
+    return Object.values(TOOLS).map((t) => t.def);
+}

package/dist/resources/memory-bootstrap-lib.js

@@ -0,0 +1,42 @@
+// ─── MemoryBootstrap — pure evaluation logic ────────────────────────────────
+// Pure helpers extracted from MemoryBootstrap.ts (section 1c, PR #549) so they
+// can be unit-tested directly. Importing MemoryBootstrap.ts pulls in the
+// Harper runtime (`databases` / `Resource`, storage init) and can't run
+// outside a live Harper; this module has no Harper dependency, so
+// test/unit/bootstrap-team.test.ts exercises the real shipped code.
+import { wrapUntrusted } from "./content-safety.js";
+/**
+ * Is `record` a live teammate of `callerId` for roster purposes?
+ *
+ * Permissive by design: pre-1.0 Agent records may not have `kind`/`status` at
+ * all (Agent.ts registration only started defaulting both — `kind ||= "agent"`,
+ * `status ||= "active"` — from the 1.0 auth reshape onward). A missing field
+ * means "legacy agent, active", not "unknown, exclude" — so we only exclude on
+ * an explicit non-matching value, never on absence.
+ */
+export function isTeammate(record, callerId) {
+    if (record.id === callerId)
+        return false;
+    if (record.kind && record.kind !== "agent")
+        return false;
+    if (record.status && record.status !== "active")
+        return false;
+    return true;
+}
+/**
+ * Format the "## Team" roster line for a list of teammate ids, or `null`
+ * when the roster is empty (caller should omit the section entirely).
+ *
+ * Teammate ids are registrant-chosen strings, not something Flair controls —
+ * they're untrusted the same way memory content is, so only the id list goes
+ * through wrapUntrusted; the surrounding instructional text is trusted and
+ * stays outside the wrap.
+ */
+export function formatTeamLine(teammateIds) {
+    if (teammateIds.length === 0)
+        return null;
+    const plural = teammateIds.length === 1 ? "agent shares" : "agents share";
+    return (`${teammateIds.length} other ${plural} this Flair office (${wrapUntrusted(teammateIds.join(", "))}). ` +
+        `Before deep-diving an unfamiliar problem, search their memories for related work — ` +
+        `\`memory_search\` covers any agent you hold a search grant from.`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Identity, memory, and soul for AI agents. Cryptographic identity (Ed25519), semantic memory with local embeddings, and persistent personality — all in a single process.",
   "type": "module",
   "license": "Apache-2.0",
@@ -56,6 +56,7 @@
   },
   "dependencies": {
     "@harperfast/harper": "5.1.14",
+    "@harperfast/oauth": "2.1.0",
     "@types/js-yaml": "4.0.9",
     "commander": "14.0.3",
     "harper-fabric-embeddings": "0.2.3",