@tpsdev-ai/flair-client 0.21.0 → 0.22.0

package/README.md

@@ -16,7 +16,7 @@ npm install @tpsdev-ai/flair-client
 import { FlairClient } from '@tpsdev-ai/flair-client'
 
 const flair = new FlairClient({
-  url: 'http://localhost:9926',   // or remote: https://flair.example.com
+  url: 'http://localhost:19926',   // or remote: https://flair.example.com
   agentId: 'my-agent',
   // keyPath auto-resolved from ~/.flair/keys/my-agent.key
 })
@@ -108,7 +108,7 @@ Or use the Flair CLI directly:
 
 | Option | Env | Default | Description |
 |--------|-----|---------|-------------|
-| `url` | `FLAIR_URL` | `http://localhost:9926` | Flair server URL |
+| `url` | `FLAIR_URL` | `http://localhost:19926` | Flair server URL |
 | `agentId` | `FLAIR_AGENT_ID` | — | Agent identifier |
 | `keyPath` | `FLAIR_KEY_DIR` | auto-resolved | Private key path |
 | `timeoutMs` | — | `10000` | Request timeout |

package/dist/client.d.ts

@@ -7,11 +7,12 @@
  *   const results = await flair.memory.search('that thing')
  *   const ctx = await flair.bootstrap({ maxTokens: 4000 })
  */
-import type { FlairClientConfig, Memory, MemoryType, Durability, Visibility, SoulEntry, SearchResult, BootstrapResult } from "./types.js";
+import type { FlairClientConfig, Memory, MemoryType, Durability, Visibility, SoulEntry, SearchResult, BootstrapResult, Relationship } from "./types.js";
 export declare class FlairClient {
     readonly url: string;
     readonly agentId: string;
     readonly memory: MemoryApi;
+    readonly relationship: RelationshipApi;
     readonly soul: SoulApi;
     private privateKey;
     private keyResolved;
@@ -128,6 +129,92 @@ declare class MemoryApi {
     /** Delete a memory. */
     delete(id: string): Promise<void>;
 }
+/**
+ * Canonical, per-owner, deterministic Relationship id (relationship-write-path,
+ * K&S-approved refinement) — `base64url(SHA-256(lowercased agentId+subject+
+ * predicate+object))`, truncated to the first 16 bytes (22 base64url chars,
+ * 128-bit collision resistance). A REAL cryptographic hash on purpose
+ * (`crypto.createHash('sha256')`, NOT `Bun.hash` or any weak/platform-specific
+ * hash) — Sherlock: blocks intentional collision attacks; Kern: portable if
+ * flair ever runs on another runtime.
+ *
+ * Hashes ONLY the triple-identity fields (agentId + subject + predicate +
+ * object) — deliberately EXCLUDES confidence/validFrom/validTo/source, so
+ * re-asserting the SAME triple with different mutable fields always maps to
+ * the SAME id. Because Relationship.put() is a PUT-by-primary-key (Harper
+ * table semantics — see resources/Relationship.ts), writing to that same id
+ * again is a natural upsert: mutable fields update, the id stays stable, no
+ * pre-insert query and no race. Fields are joined with a NUL separator before
+ * hashing (not naive string concatenation) so e.g. agentId="a"+subject="bc"
+ * can never hash identically to agentId="ab"+subject="c" — free-text
+ * subject/predicate/object have no natural delimiter of their own.
+ *
+ * `agentId` is folded into the hash so the canonical id is PER-OWNER — two
+ * different agents asserting the identical (subject, predicate, object)
+ * triple get two different ids, never a cross-agent collision/overwrite (the
+ * write path also stamps `agentId` from the server-verified auth verdict,
+ * never the body — see resources/Relationship.ts's put() — so even a
+ * maliciously-crafted URL id can't make a foreign agent's row visible to the
+ * wrong owner; it can only self-collide with the calling agent's own rows).
+ *
+ * Exported (not just used internally by RelationshipApi.write()) so the CLI's
+ * mirrored implementation (src/cli.ts's `relationship add` command, which
+ * cannot import this workspace package into the published `@tpsdev-ai/flair`
+ * CLI bundle — same reasoning as its Memory-id-generation mirroring) can be
+ * cross-checked against this one in tests, and so any other integration
+ * package can compute the same id a relationship will land at without a
+ * round-trip.
+ */
+export declare function canonicalRelationshipId(agentId: string, subject: string, predicate: string, object: string): string;
+declare class RelationshipApi {
+    private client;
+    constructor(client: FlairClient);
+    /**
+     * Assert (write) a relationship triple: "record that <subject> <predicate>
+     * <object>". Always writes to the canonical id (canonicalRelationshipId
+     * above), so:
+     *
+     *   (a) Re-asserting the SAME triple (same subject/predicate/object, same
+     *       agentId) UPSERTS the existing row — mutable fields (confidence,
+     *       validFrom/validTo, source) update, the id and createdAt-derived
+     *       identity stay stable. No duplicate rows from re-assertion.
+     *   (b) A CONTRADICTING triple with the same subject/predicate/object but a
+     *       different `validTo` OVERWRITES the prior row's validTo too (the
+     *       old value is lost) — acceptable: the graph wants the CURRENT state
+     *       of a relationship, not a full history chain (Memory's
+     *       supersedes-chain is overkill here).
+     *   (c) A DIFFERENT predicate (e.g. "nathan manages flair" superseded by
+     *       "nathan advises flair") hashes to a DIFFERENT id — a NEW row, and
+     *       the OLD triple is NOT auto-closed. To contradict a prior
+     *       relationship under a different predicate, set its `validTo` (via a
+     *       second write with the OLD subject/predicate/object) or delete it,
+     *       THEN write the new one.
+     *
+     * Never suppresses the write (same invariant as MemoryApi.write() — see
+     * flair#526's history for why "found something similar, don't write" is
+     * the wrong default): dedup here is pure upsert-by-canonical-id, not a
+     * near-duplicate signal.
+     */
+    write(input: {
+        subject: string;
+        predicate: string;
+        object: string;
+        /** 0.0–1.0, how certain (1.0 = explicitly stated). Server default: 1.0. */
+        confidence?: number;
+        /** ISO timestamp — when this relationship became true. Server default: now. */
+        validFrom?: string;
+        /** ISO timestamp — when it ended. Leave unset for an active relationship;
+         *  set it on a prior write to close out a relationship you're contradicting. */
+        validTo?: string;
+        /** Where this was learned (memory ID, conversation, etc.). */
+        source?: string;
+    }): Promise<Relationship>;
+    /** Get a relationship by canonical id (or any id, e.g. one openclaw wrote
+     *  under its own convention). Returns null on 404 (not found / not yours). */
+    get(id: string): Promise<Relationship | null>;
+    /** Delete a relationship by id. */
+    delete(id: string): Promise<void>;
+}
 declare class SoulApi {
     private client;
     constructor(client: FlairClient);

package/dist/client.js

@@ -7,7 +7,7 @@
  *   const results = await flair.memory.search('that thing')
  *   const ctx = await flair.bootstrap({ maxTokens: 4000 })
  */
-import { createPrivateKey } from "node:crypto";
+import { createHash, createPrivateKey } from "node:crypto";
 import { loadPrivateKey, resolveKeyPath, signRequest } from "./auth.js";
 const DEFAULT_URL = "http://localhost:19926";
 const DEFAULT_TIMEOUT = 30_000;
@@ -15,6 +15,7 @@ export class FlairClient {
     url;
     agentId;
     memory;
+    relationship;
     soul;
     privateKey = null;
     keyResolved = false;
@@ -37,6 +38,7 @@ export class FlairClient {
             this.basicAuth = `Basic ${Buffer.from(`${adminUser}:${adminPass}`).toString("base64")}`;
         }
         this.memory = new MemoryApi(this);
+        this.relationship = new RelationshipApi(this);
         this.soul = new SoulApi(this);
     }
     resolveKey() {
@@ -285,6 +287,114 @@ class MemoryApi {
         await this.client.request("DELETE", `/Memory/${id}`);
     }
 }
+// ─── Relationship API ───────────────────────────────────────────────────────
+/**
+ * Canonical, per-owner, deterministic Relationship id (relationship-write-path,
+ * K&S-approved refinement) — `base64url(SHA-256(lowercased agentId+subject+
+ * predicate+object))`, truncated to the first 16 bytes (22 base64url chars,
+ * 128-bit collision resistance). A REAL cryptographic hash on purpose
+ * (`crypto.createHash('sha256')`, NOT `Bun.hash` or any weak/platform-specific
+ * hash) — Sherlock: blocks intentional collision attacks; Kern: portable if
+ * flair ever runs on another runtime.
+ *
+ * Hashes ONLY the triple-identity fields (agentId + subject + predicate +
+ * object) — deliberately EXCLUDES confidence/validFrom/validTo/source, so
+ * re-asserting the SAME triple with different mutable fields always maps to
+ * the SAME id. Because Relationship.put() is a PUT-by-primary-key (Harper
+ * table semantics — see resources/Relationship.ts), writing to that same id
+ * again is a natural upsert: mutable fields update, the id stays stable, no
+ * pre-insert query and no race. Fields are joined with a NUL separator before
+ * hashing (not naive string concatenation) so e.g. agentId="a"+subject="bc"
+ * can never hash identically to agentId="ab"+subject="c" — free-text
+ * subject/predicate/object have no natural delimiter of their own.
+ *
+ * `agentId` is folded into the hash so the canonical id is PER-OWNER — two
+ * different agents asserting the identical (subject, predicate, object)
+ * triple get two different ids, never a cross-agent collision/overwrite (the
+ * write path also stamps `agentId` from the server-verified auth verdict,
+ * never the body — see resources/Relationship.ts's put() — so even a
+ * maliciously-crafted URL id can't make a foreign agent's row visible to the
+ * wrong owner; it can only self-collide with the calling agent's own rows).
+ *
+ * Exported (not just used internally by RelationshipApi.write()) so the CLI's
+ * mirrored implementation (src/cli.ts's `relationship add` command, which
+ * cannot import this workspace package into the published `@tpsdev-ai/flair`
+ * CLI bundle — same reasoning as its Memory-id-generation mirroring) can be
+ * cross-checked against this one in tests, and so any other integration
+ * package can compute the same id a relationship will land at without a
+ * round-trip.
+ */
+export function canonicalRelationshipId(agentId, subject, predicate, object) {
+    const material = [agentId, subject, predicate, object].join("\u0000").toLowerCase();
+    return createHash("sha256").update(material, "utf8").digest().subarray(0, 16).toString("base64url");
+}
+class RelationshipApi {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Assert (write) a relationship triple: "record that <subject> <predicate>
+     * <object>". Always writes to the canonical id (canonicalRelationshipId
+     * above), so:
+     *
+     *   (a) Re-asserting the SAME triple (same subject/predicate/object, same
+     *       agentId) UPSERTS the existing row — mutable fields (confidence,
+     *       validFrom/validTo, source) update, the id and createdAt-derived
+     *       identity stay stable. No duplicate rows from re-assertion.
+     *   (b) A CONTRADICTING triple with the same subject/predicate/object but a
+     *       different `validTo` OVERWRITES the prior row's validTo too (the
+     *       old value is lost) — acceptable: the graph wants the CURRENT state
+     *       of a relationship, not a full history chain (Memory's
+     *       supersedes-chain is overkill here).
+     *   (c) A DIFFERENT predicate (e.g. "nathan manages flair" superseded by
+     *       "nathan advises flair") hashes to a DIFFERENT id — a NEW row, and
+     *       the OLD triple is NOT auto-closed. To contradict a prior
+     *       relationship under a different predicate, set its `validTo` (via a
+     *       second write with the OLD subject/predicate/object) or delete it,
+     *       THEN write the new one.
+     *
+     * Never suppresses the write (same invariant as MemoryApi.write() — see
+     * flair#526's history for why "found something similar, don't write" is
+     * the wrong default): dedup here is pure upsert-by-canonical-id, not a
+     * near-duplicate signal.
+     */
+    async write(input) {
+        const id = canonicalRelationshipId(this.client.agentId, input.subject, input.predicate, input.object);
+        const record = {
+            id,
+            subject: input.subject,
+            predicate: input.predicate,
+            object: input.object,
+        };
+        if (input.confidence !== undefined)
+            record.confidence = input.confidence;
+        if (input.validFrom !== undefined)
+            record.validFrom = input.validFrom;
+        if (input.validTo !== undefined)
+            record.validTo = input.validTo;
+        if (input.source !== undefined)
+            record.source = input.source;
+        const response = await this.client.request("PUT", `/Relationship/${id}`, record);
+        return { ...record, id, agentId: this.client.agentId, ...(response ?? {}) };
+    }
+    /** Get a relationship by canonical id (or any id, e.g. one openclaw wrote
+     *  under its own convention). Returns null on 404 (not found / not yours). */
+    async get(id) {
+        try {
+            return await this.client.request("GET", `/Relationship/${id}`);
+        }
+        catch (e) {
+            if (e instanceof FlairError && e.status === 404)
+                return null;
+            throw e;
+        }
+    }
+    /** Delete a relationship by id. */
+    async delete(id) {
+        await this.client.request("DELETE", `/Relationship/${id}`);
+    }
+}
 // ─── Soul API ───────────────────────────────────────────────────────────────
 class SoulApi {
     client;

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-export { FlairClient, FlairError } from "./client.js";
+export { FlairClient, FlairError, canonicalRelationshipId } from "./client.js";
 export { loadPrivateKey, resolveKeyPath, signRequest } from "./auth.js";
-export type { FlairClientConfig, Memory, MemoryType, Durability, Visibility, SoulEntry, SearchResult, BootstrapResult, } from "./types.js";
+export type { FlairClientConfig, Memory, MemoryType, Durability, Visibility, SoulEntry, SearchResult, BootstrapResult, Relationship, } from "./types.js";

package/dist/index.js

@@ -1,2 +1,2 @@
-export { FlairClient, FlairError } from "./client.js";
+export { FlairClient, FlairError, canonicalRelationshipId } from "./client.js";
 export { loadPrivateKey, resolveKeyPath, signRequest } from "./auth.js";

package/dist/types.d.ts

@@ -54,6 +54,36 @@ export interface Memory {
      */
     deduped?: boolean;
 }
+/**
+ * An entity-to-entity relationship triple (subject/predicate/object), with
+ * temporal validity and per-owner canonical dedup (see RelationshipApi.write()
+ * in client.ts for the canonical-id scheme). Free-text, lowercased on write —
+ * NOT the attention-plane `type:value` entity vocabulary, NOT memory-id FKs.
+ */
+export interface Relationship {
+    id: string;
+    agentId: string;
+    subject: string;
+    predicate: string;
+    object: string;
+    /** ISO timestamp — when this relationship became true. */
+    validFrom?: string;
+    /** ISO timestamp — when it ended (absent/null = still active). */
+    validTo?: string;
+    /** 0.0–1.0, how certain (1.0 = explicitly stated). Defaults server-side to 1.0. */
+    confidence?: number;
+    /** Where this was learned (memory ID, conversation, etc.). */
+    source?: string;
+    createdAt: string;
+    updatedAt?: string;
+    /** JSON blob, same shape as Memory.provenance — { v, verified: { agentId,
+     *  timestamp }, claimed?: { model } }. Absent on rows written before this
+     *  field existed (migration-equivalence: additive/nullable). */
+    provenance?: string;
+    /** Always true after a successful write() — the server never suppresses a
+     *  relationship write. */
+    written?: boolean;
+}
 /** A soul entry (persistent personality/values). */
 export interface SoulEntry {
     id: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair-client",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "Lightweight client for Flair — identity, memory, and soul for AI agents. Zero heavy dependencies.",
   "type": "module",
   "main": "dist/index.js",