@tpsdev-ai/flair 0.31.1 → 0.32.0

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

@@ -0,0 +1,382 @@
+/**
+ * ─── 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;
+    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.
+        return new AdminHandle(this.#server, "_admin");
+    }
+    /**
+     * 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/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.