@tpsdev-ai/flair 0.32.0 → 0.34.0

package/dist/resources/dcr-gate.js

@@ -0,0 +1,194 @@
+/**
+ * dcr-gate.ts — who may register an OAuth client (RFC 7591 Dynamic Client
+ * Registration) on flair's own authorization server.
+ *
+ * ── The state this replaces ─────────────────────────────────────────────────
+ * `OAuthRegister.allowCreate()` returned `true` unconditionally and the only
+ * gate in `post()` was a redirect-URI host match. On a publicly-reachable
+ * instance that means anyone can create rows in `OAuthClient` — a durable,
+ * replicated table — as fast as they can send requests, and every one of those
+ * rows is a client_id that will subsequently be honoured by `/OAuthAuthorize`.
+ *
+ * ── Registration is now OFF unless an operator turns it on ──────────────────
+ * `FLAIR_OAUTH_DCR_TOKEN` is the whole interface. Absent — which is every
+ * install that has not deliberately opted in — `POST /OAuthRegister` refuses,
+ * and `/OAuthMetadata` and `/.well-known/oauth-authorization-server` stop
+ * advertising a `registration_endpoint`, because advertising one that refuses
+ * everything is a discovery document that lies.
+ *
+ * ── Why ONE variable and not a mode enum ────────────────────────────────────
+ * There is deliberately no `FLAIR_OAUTH_DCR=open`, and no way to enable
+ * registration without also supplying the credential that guards it. Enabling
+ * and crededentialling are the SAME ACT, so the "on, and open to the internet"
+ * state is not reachable by forgetting an argument — it does not exist in the
+ * configuration space at all. A mode enum plus an optional token would put that
+ * state one typo away, and the difference between the two designs is only
+ * visible on the day someone makes the typo.
+ *
+ * That is also why a token shorter than `MIN_INITIAL_ACCESS_TOKEN_LEN` disables
+ * registration rather than enabling it weakly. A four-character shared secret on
+ * an unauthenticated public endpoint is nearer to open than to closed, and a
+ * control that silently degrades to almost-off is worse than one that is off,
+ * because only one of the two is visible. The refusal is logged, by variable
+ * NAME and minimum length — never the value.
+ *
+ * ── Why a header and not `Authorization: Bearer` ────────────────────────────
+ * RFC 7591 s3.1 presents the initial access token as a Bearer token. That
+ * channel does not work here, and this is measured rather than assumed: Harper's
+ * own auth layer claims every `Authorization: Bearer ...` header for itself and
+ * validates it as a Harper OPERATION token, so a Bearer-carrying request to
+ * `/OAuthRegister` is answered `401 {"error":"invalid token"}` before any code
+ * in resources/ runs. (Probed against a live instance: no header -> 200,
+ * `Bearer <anything>` -> 401, custom header -> 200. Same mechanism documented in
+ * resources/oauth-wellknown.ts's header for the REST surface.) So the token
+ * arrives in `X-Flair-Initial-Access-Token`, which does reach the handler.
+ *
+ * ── This is not the same surface as flair#756's DCR removal ─────────────────
+ * flair#756 disabled Dynamic Client Registration on the `@harperfast/oauth`
+ * plugin's authorization server (`/oauth/mcp/register`) in favour of CIMD, and
+ * deleted the gate-token machinery there. This module is about flair's OWN
+ * OAuth 2.1 AS in resources/OAuth.ts, a separate endpoint that was left open.
+ * The posture is the same one #756 settled on — registration is closed unless
+ * an operator deliberately opens it — arrived at through the mechanism this
+ * endpoint can actually support.
+ */
+import { timingSafeEqual } from "node:crypto";
+/** The header the initial access token arrives in. See the module header. */
+export const INITIAL_ACCESS_TOKEN_HEADER = "x-flair-initial-access-token";
+/**
+ * Shortest initial access token that will enable registration.
+ *
+ * The token guards an unauthenticated, publicly-reachable endpoint, so its only
+ * defence is length. 32 characters of anything reasonable clears any offline
+ * guessing concern; the per-IP rate limit on `/OAuthRegister` covers online
+ * guessing. Anything shorter is refused outright rather than accepted weakly.
+ */
+export const MIN_INITIAL_ACCESS_TOKEN_LEN = 32;
+/**
+ * Longest accepted initial access token.
+ *
+ * A bound is needed because the constant-time comparison below works over
+ * fixed-width buffers; it is set far above any plausible token (508 bytes is
+ * ~15x a 32-byte base64 secret) so it constrains nothing real. A configured
+ * value outside the range disables registration and says so, rather than
+ * failing every comparison silently for a reason no operator could deduce.
+ */
+export const MAX_INITIAL_ACCESS_TOKEN_LEN = 508;
+let warnedBadLength = false;
+/** Test-only: forget the one-shot bad-length warning. */
+export function __resetDcrWarningForTest() {
+    warnedBadLength = false;
+}
+/**
+ * The configured initial access token, or undefined when registration is off.
+ *
+ * Undefined covers all three of: variable unset, variable empty, and variable
+ * too short to be a credential. Callers therefore cannot accidentally treat
+ * "misconfigured" as "open" — there is one value that means enabled and it is a
+ * usable token.
+ */
+export function initialAccessToken() {
+    const raw = (process.env.FLAIR_OAUTH_DCR_TOKEN ?? "").trim();
+    if (raw === "")
+        return undefined;
+    if (raw.length < MIN_INITIAL_ACCESS_TOKEN_LEN || Buffer.byteLength(raw, "utf8") > MAX_INITIAL_ACCESS_TOKEN_LEN) {
+        if (!warnedBadLength) {
+            warnedBadLength = true;
+            console.error(`[oauth-dcr] FLAIR_OAUTH_DCR_TOKEN must be between ${MIN_INITIAL_ACCESS_TOKEN_LEN} and ` +
+                `${MAX_INITIAL_ACCESS_TOKEN_LEN} characters — dynamic client registration stays DISABLED.`);
+        }
+        return undefined;
+    }
+    return raw;
+}
+/** Is `POST /OAuthRegister` open for business on this instance? */
+export function dcrEnabled() {
+    return initialAccessToken() !== undefined;
+}
+/** Width of the comparison buffers: a 4-byte length prefix plus the token bytes. */
+const COMPARE_WIDTH = MAX_INITIAL_ACCESS_TOKEN_LEN + 4;
+/**
+ * Encode a value into a fixed-width buffer as `<uint32 byte length><bytes><zero
+ * padding>`, or null if it does not fit.
+ *
+ * The length prefix is what makes zero-padding safe. Padding alone would make
+ * `"abc"` and `"abc\0"` compare equal, because both pad to the same bytes;
+ * prefixing the length means two buffers are equal exactly when the two inputs
+ * are the same length AND the same bytes.
+ */
+function fixedWidth(value) {
+    const bytes = Buffer.from(value, "utf8");
+    if (bytes.length > MAX_INITIAL_ACCESS_TOKEN_LEN)
+        return null;
+    const buf = Buffer.alloc(COMPARE_WIDTH);
+    buf.writeUInt32BE(bytes.length, 0);
+    bytes.copy(buf, 4);
+    return buf;
+}
+/**
+ * Does the presented token match the configured one?
+ *
+ * Both values are widened to the same fixed-size buffer and compared with
+ * `timingSafeEqual`. Equal width is not a convenience — it is the whole point:
+ *
+ *  - `timingSafeEqual` THROWS on a length mismatch, so handing it the raw values
+ *    would turn the configured token's length into an oracle (throw vs. false).
+ *  - `===` on strings short-circuits at the first differing byte, so it leaks a
+ *    prefix match through timing.
+ *
+ * Fixed-width buffers remove both, and the comparison touches every byte of the
+ * secret regardless of the input.
+ *
+ * DELIBERATELY NOT HASHED. An earlier revision digested both sides to get equal
+ * lengths. That works, but a hash of a credential sitting in an equality check
+ * reads — to a human and to a static analyser alike — as password-at-rest
+ * storage, which invites the obvious "why isn't this a KDF" question. The honest
+ * answer is that a KDF is the wrong primitive here: this is an equality check on
+ * a high-entropy machine credential on an unauthenticated request path, so
+ * deliberate per-request computational cost would be handing an attacker a
+ * cheap amplification lever on the exact endpoint the rate limiter exists to
+ * protect. Padding gets the same constant-time property with no hash to explain
+ * and no cost to exploit.
+ *
+ * Returns false whenever registration is disabled, so a caller cannot reach the
+ * comparison at all.
+ */
+export function initialAccessTokenMatches(presented) {
+    const expected = initialAccessToken();
+    if (expected === undefined)
+        return false;
+    if (typeof presented !== "string" || presented === "")
+        return false;
+    const a = fixedWidth(presented);
+    const b = fixedWidth(expected);
+    // `b` cannot be null — initialAccessToken() already bounds the configured
+    // value — but null-checking both keeps this total rather than relying on that
+    // invariant holding in a future edit.
+    if (a === null || b === null)
+        return false;
+    return timingSafeEqual(a, b);
+}
+/** Read the initial access token off a Harper request. Never logs it. */
+export function presentedInitialAccessToken(request) {
+    const raw = request?.headers?.get?.(INITIAL_ACCESS_TOKEN_HEADER) ??
+        request?.headers?.asObject?.[INITIAL_ACCESS_TOKEN_HEADER] ??
+        undefined;
+    if (typeof raw !== "string")
+        return undefined;
+    const trimmed = raw.trim();
+    return trimmed === "" ? undefined : trimmed;
+}
+/**
+ * The single decision point. `resources/OAuth.ts` calls this before it reads
+ * ANYTHING else off the request — before the redirect-URI check, before any
+ * write — so a caller who is not allowed to register learns nothing about the
+ * server's registration policy beyond the fact that they may not.
+ */
+export function decideRegistration(request) {
+    if (!dcrEnabled())
+        return { allowed: false, reason: "disabled" };
+    if (!initialAccessTokenMatches(presentedInitialAccessToken(request))) {
+        return { allowed: false, reason: "invalid_token" };
+    }
+    return { allowed: true };
+}

package/dist/resources/in-process-api.js

@@ -327,6 +327,7 @@ class InternalAgentTable {
  */
 export class Flair {
     #server;
+    #adminHandle;
     constructor(server) {
         this.#server = server;
     }
@@ -350,7 +351,10 @@ export class Flair {
         // AdminHandle requires an agentId for attribution. We use a sentinel
         // that makes the admin identity visible in audit logs. The caller
         // should use a real admin agent id when possible.
-        return new AdminHandle(this.#server, "_admin");
+        // Cached: the getter returns the same handle on every access so
+        // flair.admin === flair.admin is true (flair#981).
+        this.#adminHandle ??= new AdminHandle(this.#server, "_admin");
+        return this.#adminHandle;
     }
     /**
      * Internal operations — trusted, unattributed, unfiltered.

package/dist/resources/mcp-handler.js

@@ -27,9 +27,92 @@ import { databases } from "harper";
 import { randomBytes } from "node:crypto";
 import { TOOLS, listToolDefs } from "./mcp-tools.js";
 import { agentRecordIsAdmin } from "./agent-admin.js";
+import { resolveVersion } from "./version.js";
 // The MCP protocol revision we implement (initialize handshake).
 const PROTOCOL_VERSION = "2025-06-18";
+// ─── Body size cap ───────────────────────────────────────────────────────────
+//
+// flair#1033 — the /mcp handler reads the entire request body into memory with
+// no size limit. Harper's HTTP layer imposes no cap on this path (the handler
+// is registered via srv.http() which goes through Harper's own HTTP chain, not
+// Fastify's 1 GB bodyLimit or the contentTypes handler's configurable 10 MB
+// default). /mcp is the first surface reachable by an open population of OAuth
+// clients rather than by Ed25519 agents we provisioned, so the reachability
+// story is materially different from the identical pattern on any other route.
+//
+// 256 KB is ~100x headroom over any legitimate MCP JSON-RPC request (a
+// memory_store with a large content field is a few KB; even a batch of 100
+// would be well under this). It is small enough that an attacker cannot
+// meaningfully consume memory through this path.
+const MAX_MCP_BODY_SIZE = 256 * 1024; // 256 KB
 const JSON_HEADERS = { "content-type": "application/json" };
+// ─── Body size cap helpers ───────────────────────────────────────────────────
+/**
+ * Read the request body into a string, enforcing a hard byte cap.
+ *
+ * Two-phase enforcement:
+ *   1. Content-Length check (reject before reading a single byte when the
+ *      client declares an oversized body).
+ *   2. Streaming read with a cap (catches chunked transfer encoding where
+ *      Content-Length is absent, and a client that lies about its declared
+ *      length).
+ *
+ * Handles three request shapes:
+ *   - Production: Harper Request with async-iterable `request.body` (RequestBody
+ *     wrapping Node IncomingMessage).
+ *   - Test doubles: `request.text()` as a function (returns pre-built string),
+ *     or `request.body` as a plain string.
+ *
+ * Throws an error with `code: "BODY_TOO_LARGE"` when the cap is exceeded, so
+ * the caller can distinguish a size rejection from a parse failure.
+ */
+async function readBodyCapped(request, maxBytes) {
+    // Phase 1: trust-but-verify the declared Content-Length.
+    const contentLength = request?.headers?.get?.("content-length");
+    if (contentLength != null) {
+        const declared = Number(contentLength);
+        if (!Number.isFinite(declared) || declared < 0) {
+            throw Object.assign(new Error(`invalid Content-Length: ${contentLength}`), { code: "BODY_TOO_LARGE" });
+        }
+        if (declared > maxBytes) {
+            throw Object.assign(new Error(`request body too large: ${declared} bytes exceeds ${maxBytes}-byte limit`), { code: "BODY_TOO_LARGE" });
+        }
+    }
+    // Phase 2: read with a cap.
+    const body = request.body;
+    // Test double: body is already a plain string.
+    if (typeof body === "string") {
+        if (Buffer.byteLength(body) > maxBytes) {
+            throw Object.assign(new Error(`request body too large: exceeds ${maxBytes}-byte limit`), { code: "BODY_TOO_LARGE" });
+        }
+        return body;
+    }
+    // Test double: request.text() is provided as a function (returns a string).
+    if (typeof request.text === "function") {
+        const text = await request.text();
+        if (typeof text === "string" && Buffer.byteLength(text) > maxBytes) {
+            throw Object.assign(new Error(`request body too large: exceeds ${maxBytes}-byte limit`), { code: "BODY_TOO_LARGE" });
+        }
+        return text;
+    }
+    // Production: Harper Request.body is a RequestBody (async-iterable, wraps
+    // Node IncomingMessage). Read chunk by chunk with a running cap.
+    if (body && typeof body[Symbol.asyncIterator] === "function") {
+        const chunks = [];
+        let total = 0;
+        for await (const chunk of body) {
+            const buf = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+            total += buf.length;
+            if (total > maxBytes) {
+                throw Object.assign(new Error(`request body too large: exceeds ${maxBytes}-byte limit`), { code: "BODY_TOO_LARGE" });
+            }
+            chunks.push(buf);
+        }
+        return Buffer.concat(chunks).toString("utf-8");
+    }
+    // Fallback: body is absent or an unrecognised shape.
+    return String(body ?? "");
+}
 // ─── JSON-RPC helpers ────────────────────────────────────────────────────────
 function rpcResult(id, result) {
     return { status: 200, headers: JSON_HEADERS, body: JSON.stringify({ jsonrpc: "2.0", id, result }) };
@@ -195,13 +278,17 @@ export async function mcpHandler(request) {
     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.
+    // Parse the JSON-RPC body with a size cap. Harper's Request wraps a Node
+    // stream — read text, but never unbounded.
     let msg;
     try {
-        const text = typeof request.text === "function" ? await request.text() : request.body;
+        const text = await readBodyCapped(request, MAX_MCP_BODY_SIZE);
         msg = typeof text === "string" ? JSON.parse(text) : text;
     }
-    catch {
+    catch (err) {
+        if (err?.code === "BODY_TOO_LARGE") {
+            return rpcError(null, -32000, err.message, 413);
+        }
         return rpcError(null, -32700, "parse error: invalid JSON");
     }
     if (!msg || typeof msg !== "object" || msg.jsonrpc !== "2.0" || typeof msg.method !== "string") {
@@ -213,7 +300,7 @@ export async function mcpHandler(request) {
             return rpcResult(id, {
                 protocolVersion: PROTOCOL_VERSION,
                 capabilities: { tools: {} },
-                serverInfo: { name: "flair", version: "0.1.0" },
+                serverInfo: { name: "flair", version: resolveVersion() },
             });
         // Notifications (no id) — acknowledge with 202-ish empty 200; MCP clients send
         // `notifications/initialized` after initialize.

package/dist/resources/mcp-oauth.js

@@ -19,14 +19,73 @@
  */
 import * as harper from "harper";
 import { mcpOAuthEnabled, mcpAuthConfig } from "./mcp-oauth-flag.js";
+import { checkMcpRateLimit } from "./rate-limit.js";
+/**
+ * Initial value: no route has been registered yet, which is literally true until
+ * `registerMcpOAuthRoute` runs — a reader between module load and registration
+ * would get a 404 from `/mcp`, so reporting "not mounted" is accurate rather
+ * than merely safe. It also stays correct for an embedder that sets
+ * FLAIR_MCP_NO_AUTOSTART and never calls the registration function.
+ */
+let routeState = {
+    mounted: false,
+    status: "Not mounted",
+    reason: "MCP route registration has not run.",
+};
+/** Read the mount decision the router recorded. */
+export function mcpRouteState() {
+    return routeState;
+}
+/**
+ * Record a decision and return its `mounted` value. Every `return` in
+ * `registerMcpOAuthRoute` goes through here, so a branch cannot decide the
+ * route's fate without publishing that decision.
+ */
+function decide(state) {
+    routeState = state;
+    return state.mounted;
+}
 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;
 }
+/**
+ * Wrap the /mcp handler in the per-subject rate limit.
+ *
+ * Placed INSIDE `withMCPAuth` — i.e. the guard runs first and this runs second —
+ * so the key is the RS256-verified `sub` from the token rather than a network
+ * address. That is the identity worth limiting on for an authenticated surface:
+ * it is the authorization server's own assertion, it survives the caller
+ * changing address, and it is exactly the thing "a valid token can hammer the
+ * tools" is about. Authentication is not a rate limit.
+ *
+ * The consequence of that placement, stated rather than left implicit: requests
+ * bearing an INVALID token are rejected by `withMCPAuth` before this runs and so
+ * are not counted here. Those cost one JWT verification against a locally-cached
+ * key and touch no flair table or tool, which is a materially cheaper path than
+ * a tool call — but it is not zero, and it is not throttled at this layer.
+ *
+ * Exported for tests: the limiter's behaviour is asserted directly on this
+ * wrapper, without needing the plugin present.
+ */
+export function rateLimitedMcpHandler(handler) {
+    return async (request) => {
+        const limited = checkMcpRateLimit(request);
+        if (limited)
+            return limited;
+        return handler(request);
+    };
+}
 export async function registerMcpOAuthRoute(deps = {}) {
-    if (!mcpOAuthEnabled())
-        return false; // OFF → no route, no import, no side effects.
+    if (!mcpOAuthEnabled()) {
+        // OFF → no route, no import, no side effects.
+        return decide({
+            mounted: false,
+            status: "Not enabled",
+            reason: "Set FLAIR_MCP_OAUTH=1 (and an issuer) to serve MCP over HTTP.",
+        });
+    }
     const config = mcpAuthConfig();
     if (!config) {
         // Flag on but issuer unset → we cannot safely pin iss/aud. Do NOT mount an
@@ -34,7 +93,11 @@ export async function registerMcpOAuthRoute(deps = {}) {
         // 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;
+        return decide({
+            mounted: false,
+            status: "Not mounted",
+            reason: "FLAIR_MCP_OAUTH is on but no issuer is configured — set FLAIR_MCP_ISSUER (or FLAIR_PUBLIC_URL).",
+        });
     }
     let withMCPAuth;
     try {
@@ -42,11 +105,22 @@ export async function registerMcpOAuthRoute(deps = {}) {
     }
     catch (err) {
         console.error("[mcp-oauth] @harperfast/oauth not available — /mcp NOT mounted: " + (err?.message ?? err));
-        return false;
+        // The underlying error text stays in the log rather than being carried into
+        // an operator-facing string: it is arbitrary text from a dependency, and the
+        // admin page is HTML.
+        return decide({
+            mounted: false,
+            status: "Not mounted",
+            reason: "The @harperfast/oauth plugin could not be loaded — see the server log.",
+        });
     }
     if (typeof withMCPAuth !== "function") {
         console.error("[mcp-oauth] @harperfast/oauth has no withMCPAuth export — /mcp NOT mounted.");
-        return false;
+        return decide({
+            mounted: false,
+            status: "Not mounted",
+            reason: "The @harperfast/oauth plugin has no withMCPAuth export — see the server log.",
+        });
     }
     // Resolve the handler lazily (injected in tests; real module otherwise) — see
     // the top-of-file note on why it isn't a static import.
@@ -60,11 +134,11 @@ export async function registerMcpOAuthRoute(deps = {}) {
     // 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(handler, {
+    srv.http(withMCPAuth(rateLimitedMcpHandler(handler), {
         getConfig: () => mcpAuthConfig(),
     }), { urlPath: "/mcp" });
     console.error(`[mcp-oauth] /mcp mounted (OAuth-guarded); issuer=${config.issuer}`);
-    return true;
+    return decide({ mounted: true });
 }
 // Fire-and-forget at module load. Any failure is contained inside
 // registerMcpOAuthRoute (it logs and returns) so it can never crash flair boot.
@@ -81,6 +155,14 @@ export async function registerMcpOAuthRoute(deps = {}) {
 // deployment.)
 if (process.env.FLAIR_MCP_NO_AUTOSTART == null) {
     void registerMcpOAuthRoute().catch((err) => {
+        // A throw escaping registerMcpOAuthRoute means the mount never happened, so
+        // record that too — otherwise mcpRouteState() would keep reporting whatever
+        // the last completed decision was.
+        decide({
+            mounted: false,
+            status: "Not mounted",
+            reason: "MCP route registration failed — see the server log.",
+        });
         console.error("[mcp-oauth] route registration failed (surface not mounted): " + (err?.message ?? err));
     });
 }

package/dist/resources/mcp-tools.js

@@ -159,6 +159,37 @@ async function memoryStore(agent, args) {
     // id post-commit through the shared usage ledger).
     if (Array.isArray(args?.usedMemoryIds))
         body.usedMemoryIds = args.usedMemoryIds;
+    // flair#991 writer-controlled sharing intent. Forwarded ONLY when the caller
+    // actually supplied it, so an omitted visibility delegates a byte-identical
+    // body and Memory.post() applies its durability-keyed default.
+    //
+    // ── Why an unrecognized value is REJECTED, not dropped and not passed on ──
+    // `visibility` is a free-form String in schemas/memory.graphql, and the read
+    // scope asks `isPrivateVisibility()` — an exact match on the literal
+    // "private" — so EVERY other string, typos included, reads as non-private
+    // and is returned to every agent on the instance. Both of the softer
+    // options therefore fail in the unsafe direction:
+    //   - forwarding it: `visibility: "prvate"` persists a row the caller
+    //     believes is owner-only and that every agent can in fact read;
+    //   - silently dropping it: falls back to the durability-keyed default,
+    //     which for a permanent/persistent write is `shared` — same outcome,
+    //     with no argument left in the record to explain it.
+    // A misspelled argument must never widen who can read a memory, so the tool
+    // call fails and says so. The allowlist is deliberately not derived from
+    // isPrivateVisibility(): that predicate must stay "is it exactly private"
+    // for the no-visibility-field migration invariant (see
+    // resources/memory-visibility.ts), which is a READ-side rule and cannot
+    // double as a WRITE-side allowlist.
+    if (args?.visibility !== undefined && args?.visibility !== null) {
+        if (args.visibility !== "private" && args.visibility !== "shared") {
+            return {
+                error: "invalid_visibility",
+                status: 400,
+                message: `visibility must be "private" or "shared" (got: ${JSON.stringify(args.visibility)}). Omit it to use the durability-keyed default: permanent/persistent -> shared, standard/ephemeral -> private.`,
+            };
+        }
+        body.visibility = args.visibility;
+    }
     return unwrap(await h.post(body));
 }
 /**
@@ -407,6 +438,15 @@ export const TOOLS = {
                     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" },
+                    visibility: {
+                        type: "string",
+                        enum: ["private", "shared"],
+                        description: "Writer-controlled sharing intent. Omit to use the server's durability-keyed default: " +
+                            "permanent/persistent -> shared, standard/ephemeral -> private. " +
+                            "private — owner-only, never visible to another agent, even one holding a memory grant. " +
+                            "shared — visible to the owner and every other agent on this instance. " +
+                            "The visibility the write actually landed on is returned in the result.",
+                    },
                     usedMemoryIds: { type: "array", items: { type: "string" }, description: "IDs of memories that informed this write (citation-on-write). Credited via the same deduped usage ledger as record_usage. Optional." },
                 },
                 required: ["content"],