@tpsdev-ai/flair 0.31.1 → 0.33.0

package/dist/resources/Memory.js

@@ -243,8 +243,27 @@ async function runDedupGate(ctx, content) {
     return findConservativeDedupMatch(ctx, content.agentId, content.content, embedding, cosineThreshold, lexicalThreshold);
 }
 /** Build the final write response: always `written: true`, always includes
- *  `id`, and layers the dedup collision signal on top when present. Never a
- *  code path where a match suppresses these base fields. */
+ *  `id`, `visibility`, and layers the dedup collision signal on top when
+ *  present. Never a code path where a match suppresses these base fields.
+ *
+ *  ── Why `visibility` is in the write response (flair#991) ──────────────────
+ *  Visibility is the one field on a memory the caller most often does NOT
+ *  set and yet most needs to know: the durability-keyed default above stamps
+ *  `private` for a bare write and `shared` for a permanent/persistent one, so
+ *  "who can read this" is decided by a rule the writer never typed. Returning
+ *  it makes the landed value observable on EVERY write surface at once —
+ *  `flair memory add`'s printed JSON, the REST response, the native /mcp
+ *  `memory_store` result, and packages/flair-mcp's `effectiveVisibility` line
+ *  (which read this field all along and had nothing to read, so it always
+ *  rendered "(server default)").
+ *
+ *  Read from `content`, not from `base`: `content.visibility` is the value
+ *  that was actually persisted a few lines earlier, and assigning after the
+ *  `...base` spread means the persisted value wins over anything the storage
+ *  layer echoes back. Omitted (not `null`) when unset, which happens only on
+ *  the put()-over-an-existing-record path where a partial merge carried no
+ *  visibility — reporting `null` there would read as "no one but the owner",
+ *  the opposite of what an absent field means to `isPrivateVisibility()`. */
 function buildWriteResponse(content, result, dedupMatch) {
     const base = result && typeof result === "object" && !Array.isArray(result) ? result : {};
     const response = {
@@ -253,6 +272,9 @@ function buildWriteResponse(content, result, dedupMatch) {
         written: true,
         deduplicated: !!dedupMatch,
     };
+    if (content.visibility !== undefined && content.visibility !== null) {
+        response.visibility = content.visibility;
+    }
     if (dedupMatch) {
         response.matchedId = dedupMatch.matchedId;
         response.matchConfidence = { cosine: dedupMatch.cosine, lexical: dedupMatch.lexical };

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

@@ -0,0 +1,386 @@
+/**
+ * ─── Public in-process API (flair#956) ───────────────────────────────────────
+ *
+ * The facade that hides four internal implementation details a Harper engineer
+ * should never have to learn:
+ *
+ *   1. A deep import path into our dist/
+ *   2. That server.resources is keyed by REST path with no leading slash
+ *   3. That the registry entry wraps the class in .Resource
+ *   4. That creates need collectionResource() while reads do not
+ *
+ * And collapses the agentId double-pass (context + body) into one.
+ *
+ * ```ts
+ * import { Flair } from "@tpsdev-ai/flair";
+ * const flair = new Flair(server);
+ * const planner = flair.as("planner");
+ * await planner.memory.write("deploy runs at 0200 UTC");
+ * ```
+ *
+ * The facade does NOT hide the security boundary. In-process identity is
+ * asserted, not verified — co-location IS the grant. flair.as(id) requires a
+ * non-empty id (runtime throw). flair.admin and flair.internal are separate,
+ * greppable properties. The docs say plainly: build the context from your own
+ * server-side state, never from request data.
+ *
+ * ── Internal implementation ─────────────────────────────────────────────────
+ * Every operation delegates to the existing primitives in ./in-process.js
+ * (agentContext, adminContext, internalContext, collectionResource). The facade
+ * is additive — existing code using the raw seam continues to work.
+ */
+import { agentContext, adminContext, internalContext, collectionResource, InProcessContextError, } from "./in-process.js";
+// ─── Re-export for the "./server" entry point ────────────────────────────────
+export { agentContext, adminContext, internalContext, collectionResource, InProcessContextError };
+// ─── Resource resolution ─────────────────────────────────────────────────────
+/**
+ * Resolve a Flair resource class from the Harper server registry.
+ * Throws with a helpful message listing available resources if not found.
+ */
+function resolveResource(server, name) {
+    const entry = server.resources.get?.(name) ?? server.resources.getMatch?.(name);
+    if (!entry?.Resource) {
+        const keys = [...server.resources.keys()].sort();
+        const available = keys.length > 0 ? keys.join(", ") : "(none)";
+        throw new Error(`Flair is not loaded in this Harper instance.\n` +
+            `The '${name}' resource was not found in the registry.\n` +
+            `Available: [${available}]\n` +
+            `Make sure @tpsdev-ai/flair is installed as a component of this instance.`);
+    }
+    return entry.Resource;
+}
+// ─── AgentHandle ─────────────────────────────────────────────────────────────
+/**
+ * A handle that carries agent identity and scopes every operation to that agent.
+ *
+ * Returned by {@link Flair.as}. The agentId is validated at construction time
+ * (runtime, not types) — missing, empty, blank, or non-string throws
+ * {@link InProcessContextError}.
+ *
+ * **Security:** in-process identity is asserted, not verified. Build the
+ * agentId from your own server-side state, never from request data.
+ */
+export class AgentHandle {
+    agentId;
+    #server;
+    #ctx;
+    constructor(server, agentId) {
+        this.#server = server;
+        this.agentId = agentId;
+        // Throws InProcessContextError on missing/empty/blank id — see
+        // resources/in-process.ts's safety-design block for why this is
+        // not merely defensive.
+        this.#ctx = agentContext(agentId);
+    }
+    /** Memory operations scoped to this agent. */
+    get memory() {
+        return new AgentMemory(this.#server, this.#ctx, this.agentId);
+    }
+    /**
+     * Semantic search scoped to this agent.
+     *
+     * ```ts
+     * const hits = await planner.recall("deploy schedule", { limit: 5 });
+     * ```
+     */
+    async recall(query, opts) {
+        const Cls = resolveResource(this.#server, "SemanticSearch");
+        const h = new Cls(undefined, this.#ctx);
+        const body = { q: query, limit: opts?.limit ?? 5 };
+        if (opts?.includeTrust === true)
+            body.includeTrust = true;
+        if (opts?.abstain === true)
+            body.abstain = true;
+        if (opts?.scoring)
+            body.scoring = opts.scoring;
+        if (opts?.minScore !== undefined)
+            body.minScore = opts.minScore;
+        if (opts?.since)
+            body.since = opts.since;
+        if (opts?.asOf)
+            body.asOf = opts.asOf;
+        if (opts?.tag)
+            body.tag = opts.tag;
+        if (opts?.subject)
+            body.subject = opts.subject;
+        if (opts?.subjects)
+            body.subjects = opts.subjects;
+        return unwrap(await h.post(body));
+    }
+}
+// ─── AgentMemory (per-agent memory operations) ───────────────────────────────
+class AgentMemory {
+    #server;
+    #ctx;
+    #agentId;
+    constructor(server, ctx, agentId) {
+        this.#server = server;
+        this.#ctx = ctx;
+        this.#agentId = agentId;
+    }
+    /**
+     * Write a memory as this agent.
+     *
+     * The agentId is stamped from the handle's context — the caller never
+     * passes it, and any agentId in opts is overwritten. This collapses the
+     * double-pass (context + body) into one.
+     */
+    async write(content, opts) {
+        const Cls = resolveResource(this.#server, "Memory");
+        const h = await collectionResource(Cls, this.#ctx);
+        const body = {
+            agentId: this.#agentId,
+            content,
+        };
+        if (opts?.durability)
+            body.durability = opts.durability;
+        if (opts?.visibility)
+            body.visibility = opts.visibility;
+        if (opts?.tags)
+            body.tags = opts.tags;
+        if (opts?.type)
+            body.type = opts.type;
+        if (opts?.id)
+            body.id = opts.id;
+        return unwrap(await h.post(body));
+    }
+    /** Get a memory by id, scoped to this agent. */
+    async get(id) {
+        const Cls = resolveResource(this.#server, "Memory");
+        const h = new Cls(undefined, this.#ctx);
+        return unwrap(await h.get(id));
+    }
+    /**
+     * Search memories scoped to this agent.
+     *
+     * Delegates to Memory.search() which applies the agent's read scope
+     * (own memories + granted owners' shared memories).
+     */
+    async search(opts) {
+        const Cls = resolveResource(this.#server, "Memory");
+        const h = new Cls(undefined, this.#ctx);
+        const conditions = [];
+        if (opts?.tags) {
+            for (const tag of opts.tags) {
+                conditions.push({ search_attribute: "tags", search_type: "contains", search_value: tag });
+            }
+        }
+        if (opts?.type) {
+            conditions.push({ search_attribute: "type", search_type: "equals", search_value: opts.type });
+        }
+        if (opts?.durability) {
+            conditions.push({ search_attribute: "durability", search_type: "equals", search_value: opts.durability });
+        }
+        if (opts?.visibility) {
+            conditions.push({ search_attribute: "visibility", search_type: "equals", search_value: opts.visibility });
+        }
+        const query = conditions.length > 0 ? { conditions, operator: "and" } : undefined;
+        return unwrap(await h.search(query));
+    }
+}
+// ─── AdminHandle ─────────────────────────────────────────────────────────────
+/**
+ * Flair-admin operations — unfiltered reads, cross-agent writes.
+ *
+ * **This is a root shell.** Every call site is greppable via
+ * `git grep "flair.admin"`. Use for provisioning and maintenance only,
+ * never as a request handler's default.
+ *
+ * The admin agentId is validated at construction time (same guard as
+ * {@link AgentHandle}).
+ */
+export class AdminHandle {
+    agentId;
+    #server;
+    #ctx;
+    constructor(server, agentId) {
+        this.#server = server;
+        this.agentId = agentId;
+        this.#ctx = adminContext(agentId);
+    }
+    /**
+     * Register an agent through the Agent resource (full Principal shape).
+     *
+     * ```ts
+     * await flair.admin.registerAgent("planner", { publicKey: "pending" });
+     * ```
+     */
+    async registerAgent(id, opts) {
+        const Cls = resolveResource(this.#server, "Agent");
+        const h = await collectionResource(Cls, this.#ctx);
+        const body = {
+            id,
+            name: id,
+            displayName: opts?.displayName ?? id,
+            publicKey: opts?.publicKey ?? "pending",
+            runtime: opts?.runtime ?? "headless",
+        };
+        if (opts?.admin === true)
+            body.admin = true;
+        return unwrap(await h.post(body));
+    }
+    /** Memory operations with admin authority (unfiltered reads, cross-agent writes). */
+    get memory() {
+        return new AdminMemory(this.#server, this.#ctx, this.agentId);
+    }
+}
+// ─── AdminMemory ─────────────────────────────────────────────────────────────
+class AdminMemory {
+    #server;
+    #ctx;
+    #agentId;
+    constructor(server, ctx, agentId) {
+        this.#server = server;
+        this.#ctx = ctx;
+        this.#agentId = agentId;
+    }
+    /** Read any memory by id, unfiltered. */
+    async get(id) {
+        const Cls = resolveResource(this.#server, "Memory");
+        const h = new Cls(undefined, this.#ctx);
+        return unwrap(await h.get(id));
+    }
+    /**
+     * Write a memory attributed to another agent.
+     *
+     * ```ts
+     * await flair.admin.memory.write("researcher", "provisioned memory", { visibility: "shared" });
+     * ```
+     */
+    async write(asAgentId, content, opts) {
+        const Cls = resolveResource(this.#server, "Memory");
+        // Use adminContext for the acting admin, but stamp the target agentId
+        // on the body so the memory is owned by the target agent.
+        const h = await collectionResource(Cls, this.#ctx);
+        const body = {
+            agentId: asAgentId,
+            content,
+        };
+        if (opts?.durability)
+            body.durability = opts.durability;
+        if (opts?.visibility)
+            body.visibility = opts.visibility;
+        if (opts?.tags)
+            body.tags = opts.tags;
+        if (opts?.type)
+            body.type = opts.type;
+        if (opts?.id)
+            body.id = opts.id;
+        return unwrap(await h.post(body));
+    }
+}
+// ─── InternalHandle ──────────────────────────────────────────────────────────
+/**
+ * Trusted, unattributed, unfiltered operations — Flair's `internal` verdict.
+ *
+ * Reads see every agent's private records; writes are owned by nobody.
+ * This exists for work that is genuinely infrastructure: provisioning a
+ * principal, a migration, a maintenance sweep.
+ *
+ * Every call site is greppable via `git grep "flair.internal"`.
+ */
+export class InternalHandle {
+    #server;
+    #ctx;
+    constructor(server) {
+        this.#server = server;
+        this.#ctx = internalContext();
+    }
+    /** Raw Agent table access for provisioning. */
+    get agentTable() {
+        return new InternalAgentTable(this.#server, this.#ctx);
+    }
+}
+// ─── InternalAgentTable ──────────────────────────────────────────────────────
+class InternalAgentTable {
+    #server;
+    #ctx;
+    constructor(server, ctx) {
+        this.#server = server;
+        this.#ctx = ctx;
+    }
+    /** Write directly to the Agent resource (bypasses admin gate via internal context). */
+    async put(record) {
+        const Cls = resolveResource(this.#server, "Agent");
+        const h = await collectionResource(Cls, this.#ctx);
+        return unwrap(await h.post(record));
+    }
+}
+// ─── Flair (the facade) ──────────────────────────────────────────────────────
+/**
+ * The public in-process API for Flair embedded in a Harper app.
+ *
+ * One handle per Harper instance. Resolves resources lazily on first use.
+ *
+ * ```ts
+ * import { Flair } from "@tpsdev-ai/flair";
+ * const flair = new Flair(server);
+ * const planner = flair.as("planner");
+ * await planner.memory.write("deploy runs at 0200 UTC");
+ * ```
+ *
+ * **Security:** In-process identity is asserted, not verified — co-location
+ * IS the grant. Build the agentId from your own server-side state, never
+ * from request data. `flair.as(id)` requires a non-empty id (runtime throw).
+ * `flair.admin` and `flair.internal` are separate, greppable properties for
+ * deliberate escalation.
+ */
+export class Flair {
+    #server;
+    #adminHandle;
+    constructor(server) {
+        this.#server = server;
+    }
+    /**
+     * Return a handle that acts as the given agent.
+     *
+     * The agentId is runtime-validated: missing, empty, blank, or non-string
+     * throws {@link InProcessContextError}. Build it from your own server-side
+     * state, never from request data.
+     */
+    as(agentId) {
+        return new AgentHandle(this.#server, agentId);
+    }
+    /**
+     * Admin operations — unfiltered reads, cross-agent writes.
+     *
+     * **This is a root shell.** Every call site is greppable via
+     * `git grep "flair.admin"`. Use for provisioning and maintenance only.
+     */
+    get admin() {
+        // 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.
+        // 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.
+     *
+     * Every call site is greppable via `git grep "flair.internal"`.
+     * Use for infrastructure work only: provisioning, migrations, maintenance.
+     */
+    get internal() {
+        return new InternalHandle(this.#server);
+    }
+}
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+/**
+ * Unwrap a handler return value into a plain object.
+ * Handlers may return a `Response` (the 401/403/400 guards) — surface its
+ * JSON body so the caller sees the structured error rather than an opaque object.
+ */
+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;
+}

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"],

package/docs/deployment-shapes.md

@@ -0,0 +1,35 @@
+# Which Flair deployment shape are you in?
+
+Flair runs in one of three shapes. Pick yours and follow only that path.
+
+| You want to... | Shape | Start here |
+|---|---|---|
+| Run Flair on your own machine or VPS. `flair init` installs Harper, creates your agent identity, and you're running. | **Standalone local** | [standalone-local.md](standalone-local.md) |
+| Run Flair on [Harper Fabric](https://www.harperdb.io/) — managed hosting, multi-region replication, no shell on the node. You deploy a component; agents connect over HTTPS. | **Hosted on Fabric** | [hosted-on-fabric.md](hosted-on-fabric.md) |
+| Load Flair into a Harper instance you already run. In-process calls — no HTTP, no second process, no key to distribute. Over HTTP it is one memory API among many. | **Embedded in a Harper app** | [embedding-in-a-harper-app.md](embedding-in-a-harper-app.md) |
+
+---
+
+## What changes across shapes
+
+Not everything is the same. The critical differences:
+
+### Identity
+
+- **Standalone local & Fabric (over HTTP):** Agents authenticate with Ed25519-signed requests. Each agent holds a private key and signs `agentId:timestamp:nonce:METHOD:/path` on every request. The server verifies the signature against the agent's registered public key.
+- **Embedded (in-process):** Identity is **asserted**, not verified. You pass the agent id via the call context — `agentContext("mybot")` — and Flair acts as that agent. No key, no signature, no `Agent`-table lookup. Co-location *is* the trust boundary: a caller inside the same Harper instance could write the storage tables directly anyway, so demanding a signature from same-process code would be theatre. **Never build the context from request data** — that is privilege escalation with no error and no trace.
+
+### Upgrade
+
+- **Standalone local:** `flair upgrade` — install, restart, verify, rollback-on-failure in one step.
+- **Hosted on Fabric:** `flair upgrade --target <fabric-url>` — resolves the target version, stages a clean deployable, and pushes it. Fabric has no `flair upgrade` equivalent to the local path; redeploy the component.
+- **Embedded:** Flair follows your host app's dependency lifecycle. When you update `@tpsdev-ai/flair` in your app's `package.json` and redeploy, Flair upgrades with the rest. There is no `flair upgrade` — it's a component, not a standalone process.
+
+### Federation
+
+- **Standalone local & Fabric:** Available. Hub-and-spoke sync with pairing tokens, signed requests, and originator enforcement. The CLI drives pairing (`flair federation pair`).
+- **Embedded:** Pairing is **CLI-only** today — it requires shell access on the node ([flair#947](https://github.com/tpsdev-ai/flair/issues/947)). If your deployment has no shell, federation is not available.
+
+### `@export`
+
+`@export` on a GraphQL schema means **REST exposure only** — it does not mean replication. `Memory` has no `@export` and still replicates in a Harper Fabric cluster (replication is per-database, not per-export). This is a genuine and easily-inverted trap: do not assume `@export` controls sync or that the absence of `@export` means "not replicated."

package/docs/deployment.md

@@ -192,10 +192,10 @@ Set these in the Flair process environment (`~/Library/LaunchAgents/ai.tpsdev.fl
 
 ```bash
 # Backup all data (agents, memories, souls)
-flair backup > ~/flair-backup-$(date +%Y%m%d).json
+flair backup --output ~/flair-backup-$(date +%Y%m%d).json --admin-pass-file ~/.flair/admin-pass
 
 # Restore to a fresh instance
-flair restore < ~/flair-backup-20260405.json
+flair restore ~/flair-backup-20260405.json
 ```
 
 Always backup before upgrades.