@tpsdev-ai/flair 0.2.0

package/resources/memory-feed-lib.ts

@@ -0,0 +1,22 @@
+import { createHash } from "node:crypto";
+
+export function computeContentHash(agentId: string, content: string): string {
+  return createHash("sha256")
+    .update(`${agentId}${content}`)
+    .digest("hex")
+    .slice(0, 16);
+}
+
+export async function findExistingMemoryByContentHash(
+  records: AsyncIterable<any> | Iterable<any>,
+  agentId: string,
+  contentHash: string,
+): Promise<any | null> {
+  for await (const record of records) {
+    if (record?.agentId === agentId && record?.contentHash === contentHash) {
+      return record;
+    }
+  }
+
+  return null;
+}

package/resources/table-helpers.ts

@@ -0,0 +1,46 @@
+/**
+ * Safe read-modify-write helper for Harper tables.
+ *
+ * Harper's `put()` is FULL RECORD REPLACEMENT. If you pass a partial
+ * object, all missing fields (including embeddings!) are permanently
+ * deleted. This helper ensures you always read the full record first.
+ *
+ * Usage:
+ *   import { patchRecord } from "./table-helpers.js";
+ *   await patchRecord(tables.Memory, id, { lastReflected: now });
+ */
+
+export async function patchRecord(
+  table: any,
+  id: string,
+  patch: Record<string, unknown>,
+): Promise<void> {
+  const existing = await table.get(id);
+  if (!existing) throw new Error(`Record ${id} not found`);
+  await table.put({ ...existing, ...patch });
+}
+
+/**
+ * Fire-and-forget variant — swallows errors silently.
+ * Use for best-effort metadata updates (lastReflected, lastRetrieved, etc.)
+ * where a failure should never break the calling request.
+ */
+export function patchRecordSilent(
+  table: any,
+  id: string,
+  patch: Record<string, unknown>,
+): void {
+  patchRecord(table, id, patch).catch(() => {});
+}
+
+// ── RULE ──────────────────────────────────────────────────────────────────────
+// Never call `tables.X.put(partial)` directly anywhere in Flair resources.
+// Harper put() = FULL RECORD REPLACEMENT. Missing fields are deleted permanently.
+// Always use patchRecord() or patchRecordSilent().
+// ─────────────────────────────────────────────────────────────────────────────
+
+// ── RULE ──────────────────────────────────────────────────────────────────────
+// Never call `tables.X.put(partial)` directly anywhere in Flair resources.
+// Harper put() = FULL RECORD REPLACEMENT. Missing fields are deleted permanently.
+// Always use patchRecord() or patchRecordSilent().
+// ─────────────────────────────────────────────────────────────────────────────

package/schemas/agent.graphql

@@ -0,0 +1,22 @@
+type Agent @table(database: "flair") @export {
+  id: ID @primaryKey
+  name: String!
+  role: String
+  type: String @indexed
+  publicKey: String!
+  createdAt: String!
+  updatedAt: String
+}
+
+type Integration @table(database: "flair") @export {
+  id: ID @primaryKey
+  agentId: String! @indexed
+  platform: String! @indexed
+  username: String
+  userId: String
+  email: String
+  encryptedCredential: String
+  metadata: String
+  createdAt: String!
+  updatedAt: String
+}

package/schemas/event.graphql

@@ -0,0 +1,12 @@
+type OrgEvent @table(database: "flair") @export {
+  id: ID @primaryKey
+  authorId: String! @indexed
+  kind: String! @indexed
+  scope: String @indexed
+  summary: String!
+  detail: String
+  targetIds: [String] @indexed
+  refId: String @indexed
+  createdAt: String! @indexed
+  expiresAt: String @indexed
+}

package/schemas/memory.graphql

@@ -0,0 +1,50 @@
+type Memory @table(database: "flair") {
+  id: ID @primaryKey
+  agentId: String! @indexed
+  content: String!
+  contentHash: String @indexed
+  visibility: String
+  embedding: [Float] @indexed(type: "HNSW")
+  tags: [String] @indexed
+  durability: String @indexed
+  source: String
+  createdAt: String! @indexed
+  updatedAt: String
+  expiresAt: String @indexed
+  retrievalCount: Int
+  lastRetrieved: String
+  promotionStatus: String   # null | "pending" | "approved" | "rejected"
+  promotedAt: String
+  promotedBy: String        # authenticated agentId who approved
+  archived: Boolean @indexed
+  archivedAt: String
+  archivedBy: String        # authenticated agentId who archived
+  # Learning pipeline fields
+  parentId: String          # link to related memory
+  derivedFrom: [String]     # source memory IDs this was reflected from
+  sessionId: String @indexed  # originating session
+  lastReflected: String     # ISO timestamp of last reflection pass
+  supersedes: String @indexed  # ID of memory this one replaces (version chain)
+  subject: String @indexed     # entity this memory is about (person, service, project)
+}
+
+type Soul @table(database: "flair") {
+  id: ID @primaryKey
+  agentId: String! @indexed
+  key: String! @indexed
+  value: String!
+  priority: String              # critical | high | standard | low (skill governance)
+  metadata: String              # JSON blob (skill governance: source, version, hash, etc.)
+  durability: String @indexed
+  createdAt: String!
+  updatedAt: String
+}
+
+type MemoryGrant @table(database: "flair") @export {
+  id: ID @primaryKey
+  ownerId: String!
+  granteeId: String!
+  scope: String!
+  filter: String
+  createdAt: String
+}

package/schemas/schema.graphql

@@ -0,0 +1,41 @@
+
+# ─── Observatory tables ───────────────────────────────────────────────────────
+
+type ObsOffice @table(database: "flair") @export {
+  id: ID @primaryKey        # e.g. "rockit"
+  name: String!
+  publicKey: String!        # Ed25519 hex public key for auth verification
+  status: String @indexed   # "online" | "offline" | "degraded"
+  lastSeen: String
+  agentCount: Int
+  createdAt: String!
+  updatedAt: String
+}
+
+type ObsAgentSnapshot @table(database: "flair") @export {
+  id: ID @primaryKey        # "{officeId}:{agentId}"
+  officeId: String! @indexed
+  agentId: String! @indexed
+  name: String
+  role: String
+  type: String              # "agent" | "human"
+  model: String
+  status: String @indexed   # "active" | "idle" | "offline"
+  currentTask: String
+  lastActivity: String
+  lastHeartbeat: String
+  updatedAt: String!
+}
+
+type ObsEventFeed @table(database: "flair") @export {
+  id: ID @primaryKey        # "{officeId}:{eventId}"
+  officeId: String! @indexed
+  kind: String! @indexed
+  authorId: String! @indexed
+  summary: String!
+  refId: String @indexed
+  scope: String @indexed
+  createdAt: String! @indexed
+  receivedAt: String!
+  expiresAt: String @indexed
+}

package/schemas/workspace.graphql

@@ -0,0 +1,14 @@
+type WorkspaceState @table(database: "flair") @export {
+  id: ID @primaryKey
+  agentId: String! @indexed
+  ref: String!
+  label: String @indexed
+  provider: String!
+  timestamp: String! @indexed
+  metadata: String
+  taskId: String @indexed
+  phase: String @indexed
+  summary: String
+  filesChanged: [String]
+  createdAt: String!
+}