@tpsdev-ai/flair 0.2.0

package/resources/OrgEventCatchup.ts

@@ -0,0 +1,89 @@
+/**
+ * OrgEventCatchup.ts — Custom resource for filtered event retrieval.
+ *
+ * GET /OrgEventCatchup/{participantId}?since=<ISO timestamp>
+ *
+ * Returns events where:
+ *   - targetIds includes participantId OR targetIds is empty/null
+ *   - createdAt >= since
+ * Sorted by createdAt ascending (oldest first for in-order processing).
+ * Limit 50 events max.
+ */
+
+import { Resource, databases } from "@harperfast/harper";
+
+export class OrgEventCatchup extends Resource {
+  // HarperDB calls get(pathInfo, context) where pathInfo is the URL segment after /OrgEventCatchup/
+  async get(pathInfo?: any) {
+    const request = (this as any).request;
+    const callerAgent = request?.tpsAgent;
+    const callerIsAdmin = request?.tpsAgentIsAdmin === true;
+
+    // Harper routes /OrgEventCatchup/{id} with pathInfo.id as the path segment
+    const participantId: string | null =
+      (typeof pathInfo === "object" && pathInfo !== null ? (pathInfo as any).id : null) ??
+      (typeof pathInfo === "string" ? pathInfo : null) ??
+      (this as any).getId?.() ??
+      null;
+
+    if (!participantId) {
+      return new Response(
+        JSON.stringify({ error: "participantId required in path: GET /OrgEventCatchup/{participantId}" }),
+        { status: 400, headers: { "Content-Type": "application/json" } },
+      );
+    }
+
+    // Auth: requesting agent must match participantId (or admin)
+    if (callerAgent && !callerIsAdmin && callerAgent !== participantId) {
+      return new Response(
+        JSON.stringify({ error: "forbidden: can only fetch events for yourself" }),
+        { status: 403, headers: { "Content-Type": "application/json" } },
+      );
+    }
+
+    // Harper parses query params into pathInfo.conditions array:
+    // e.g. ?since=value → conditions: [{attribute:"since", value:"...", comparator:"equals"}]
+    // pathInfo.id is the URL path segment (participantId).
+    const since: string | null =
+      (typeof pathInfo === "object" && pathInfo !== null
+        ? (pathInfo as any).conditions?.find((c: any) => c.attribute === "since")?.value ?? null
+        : null);
+    if (!since) {
+      return new Response(
+        JSON.stringify({ error: "since query parameter required (ISO timestamp)" }),
+        { status: 400, headers: { "Content-Type": "application/json" } },
+      );
+    }
+
+    const sinceDate = new Date(since);
+    if (isNaN(sinceDate.getTime())) {
+      return new Response(
+        JSON.stringify({ error: "invalid since timestamp" }),
+        { status: 400, headers: { "Content-Type": "application/json" } },
+      );
+    }
+
+    // Query all OrgEvents and filter in-memory
+    const results: any[] = [];
+    for await (const event of (databases as any).flair.OrgEvent.search()) {
+      // Filter by createdAt >= since
+      if (!event.createdAt || event.createdAt < since) continue;
+
+      // Filter by targetIds: includes participantId OR empty/null
+      const targets = event.targetIds;
+      const isTargeted = !targets || targets.length === 0 || targets.includes(participantId);
+      if (!isTargeted) continue;
+
+      // Skip expired events
+      if (event.expiresAt && new Date(event.expiresAt) < new Date()) continue;
+
+      results.push(event);
+    }
+
+    // Sort ascending by createdAt (oldest first)
+    results.sort((a: any, b: any) => (a.createdAt || "").localeCompare(b.createdAt || ""));
+
+    // Limit to 50
+    return results.slice(0, 50);
+  }
+}

package/resources/OrgEventMaintenance.ts

@@ -0,0 +1,37 @@
+/**
+ * OrgEventMaintenance.ts — Maintenance worker for expired OrgEvents.
+ *
+ * POST /OrgEventMaintenance/ — deletes all records where expiresAt < now.
+ * Auth: admin only.
+ */
+
+import { Resource, databases } from "@harperfast/harper";
+
+export class OrgEventMaintenance extends Resource {
+  async post(_data: any, context?: any) {
+    // Admin-only
+    if (!context?.request?.tpsAgentIsAdmin) {
+      return new Response(
+        JSON.stringify({ error: "forbidden: admin only" }),
+        { status: 403, headers: { "Content-Type": "application/json" } },
+      );
+    }
+
+    const now = new Date().toISOString();
+    const toDelete: string[] = [];
+
+    for await (const event of (databases as any).flair.OrgEvent.search()) {
+      if (event.expiresAt && event.expiresAt < now) {
+        toDelete.push(event.id);
+      }
+    }
+
+    for (const id of toDelete) {
+      try {
+        await (databases as any).flair.OrgEvent.delete(id);
+      } catch {}
+    }
+
+    return { deleted: toDelete.length };
+  }
+}

package/resources/SemanticSearch.ts

@@ -0,0 +1,157 @@
+import { Resource, databases } from "@harperfast/harper";
+import { getEmbedding, getMode } from "./embeddings-provider.js";
+import { patchRecord } from "./table-helpers.js";
+
+function cosineSimilarity(a: number[], b: number[]): number {
+  let dot = 0;
+  const len = Math.min(a.length, b.length);
+  for (let i = 0; i < len; i++) dot += a[i] * b[i];
+  return dot;
+}
+
+// ─── Temporal Decay + Relevance Scoring ─────────────────────────────────────
+
+const DURABILITY_WEIGHTS: Record<string, number> = {
+  permanent: 1.0,
+  persistent: 0.9,
+  standard: 0.7,
+  ephemeral: 0.4,
+};
+
+// Half-life in days for exponential decay per durability level
+const DECAY_HALF_LIFE_DAYS: Record<string, number> = {
+  permanent: Infinity, // never decays
+  persistent: 90,
+  standard: 30,
+  ephemeral: 7,
+};
+
+function recencyFactor(createdAt: string, durability: string): number {
+  const halfLife = DECAY_HALF_LIFE_DAYS[durability] ?? 30;
+  if (halfLife === Infinity) return 1.0;
+  const ageDays = (Date.now() - Date.parse(createdAt)) / (1000 * 60 * 60 * 24);
+  const lambda = Math.LN2 / halfLife;
+  return Math.exp(-lambda * ageDays);
+}
+
+function retrievalBoost(retrievalCount: number): number {
+  if (!retrievalCount || retrievalCount <= 0) return 1.0;
+  return 1.0 + 0.1 * Math.log2(retrievalCount); // gentle boost: 10 retrievals → ~1.33x
+}
+
+function compositeScore(
+  semanticScore: number,
+  record: { durability?: string; createdAt?: string; retrievalCount?: number; supersedes?: string },
+): number {
+  const durability = record.durability ?? "standard";
+  const dWeight = DURABILITY_WEIGHTS[durability] ?? 0.7;
+  const rFactor = record.createdAt ? recencyFactor(record.createdAt, durability) : 1.0;
+  const rBoost = retrievalBoost(record.retrievalCount ?? 0);
+  return semanticScore * dWeight * rFactor * rBoost;
+}
+
+export class SemanticSearch extends Resource {
+  async post(data: any) {
+    const { agentId, q, queryEmbedding, tag, subject, subjects, limit = 10, includeSuperseded = false, scoring = "composite" } = data || {};
+    const subjectFilter = subjects
+      ? new Set((subjects as string[]).map((s: string) => s.toLowerCase()))
+      : subject
+        ? new Set([(subject as string).toLowerCase()])
+        : null;
+
+    // Defense-in-depth: verify agentId matches authenticated agent.
+    // The middleware already enforces this for non-admins, but double-check here
+    // so direct Harper API calls (e.g., admin scripts) are also scoped correctly.
+    const authenticatedAgent: string | undefined = (this as any).request?.headers?.get?.("x-tps-agent");
+    const callerIsAdmin: boolean = (this as any).request?.tpsAgentIsAdmin === true;
+    if (authenticatedAgent && !callerIsAdmin && agentId && agentId !== authenticatedAgent) {
+      return new Response(JSON.stringify({
+        error: "forbidden: agentId must match authenticated agent",
+      }), { status: 403, headers: { "Content-Type": "application/json" } });
+    }
+
+    // Determine searchable agent IDs (own + granted)
+    const searchAgentIds = new Set<string>();
+    if (agentId) searchAgentIds.add(agentId);
+
+    if (agentId) {
+      try {
+        for await (const grant of (databases as any).flair.MemoryGrant.search({
+          conditions: [{ attribute: "granteeId", comparator: "equals", value: agentId }],
+        })) {
+          if (grant.scope === "search" || grant.scope === "read") {
+            searchAgentIds.add(grant.ownerId);
+          }
+        }
+      } catch { /* MemoryGrant may not exist */ }
+    }
+
+    // Generate query embedding
+    let qEmb = queryEmbedding;
+    if (!qEmb && q) {
+      if (getMode() !== "none") {
+        try { qEmb = await getEmbedding(String(q).slice(0, 500)); } catch {}
+      }
+    }
+
+    const results: any[] = [];
+
+    // Iterate ALL memories, filter by agent ID set
+    for await (const record of (databases as any).flair.Memory.search()) {
+      // Filter by agent
+      if (searchAgentIds.size > 0 && !searchAgentIds.has(record.agentId)) {
+        if (record.visibility !== "office") continue;
+      }
+
+      if (record.archived === true) continue; // soft-deleted — excluded from search by default
+      if (record.expiresAt && Date.parse(record.expiresAt) < Date.now()) continue;
+      if (tag && !(record.tags || []).includes(tag)) continue;
+      if (subjectFilter && record.subject && !subjectFilter.has(String(record.subject).toLowerCase())) continue;
+
+      let rawScore = 0;
+      if (q && String(record.content || "").toLowerCase().includes(String(q).toLowerCase())) {
+        rawScore += 0.5;
+      }
+      if (qEmb && record.embedding && qEmb.length === record.embedding.length) {
+        rawScore += cosineSimilarity(qEmb, record.embedding);
+      }
+      if (q && rawScore === 0) continue;
+
+      // Apply composite scoring (temporal decay + durability + retrieval boost)
+      const finalScore = scoring === "raw" ? rawScore : compositeScore(rawScore, record);
+
+      const { embedding, ...rest } = record;
+      results.push({
+        ...rest,
+        _score: Math.round(finalScore * 1000) / 1000,
+        _rawScore: scoring !== "raw" ? Math.round(rawScore * 1000) / 1000 : undefined,
+        _source: record.agentId !== agentId ? record.agentId : undefined,
+      });
+    }
+
+    // Build superseded set and filter (unless caller opts in to see full history)
+    let filteredResults = results;
+    if (!includeSuperseded) {
+      const supersededIds = new Set<string>();
+      for (const r of results) {
+        if (r.supersedes) supersededIds.add(r.supersedes);
+      }
+      filteredResults = results.filter((r: any) => !supersededIds.has(r.id));
+    }
+
+    filteredResults.sort((a: any, b: any) => b._score - a._score);
+    const topResults = filteredResults.slice(0, limit);
+
+    // Async hit tracking — don't block the response
+    // Use patchRecord to avoid wiping other fields (embedding, content, etc.)
+    const now = new Date().toISOString();
+    for (const r of topResults) {
+      patchRecord((databases as any).flair.Memory, r.id, {
+        retrievalCount: (r.retrievalCount || 0) + 1,
+        lastRetrieved: now,
+      }).catch(() => {});
+    }
+
+    return { results: topResults };
+  }
+}

package/resources/SkillScan.ts

@@ -0,0 +1,146 @@
+import { Resource } from "@harperfast/harper";
+
+/**
+ * POST /SkillScan/
+ *
+ * Static analysis of skill content for security violations.
+ * Scans for shell commands, network calls, fs writes, env access,
+ * encoded payloads, zero-width chars, and homoglyphs.
+ *
+ * Request:  { content: string }
+ * Response: { safe, violations, riskLevel }
+ *
+ * Auth: any authenticated agent (read-only analysis).
+ * Size limit: 8KB (8192 bytes).
+ */
+
+interface Violation {
+  type: string;
+  line: number;
+  content: string;
+}
+
+type RiskLevel = "low" | "medium" | "high" | "critical";
+
+const SHELL_PATTERNS = [
+  { regex: /\bexec\s*\(/, type: "shell_command" },
+  { regex: /\bspawn\s*\(/, type: "shell_command" },
+  { regex: /\bsystem\s*\(/, type: "shell_command" },
+  { regex: /`[^`]*`/, type: "shell_backtick" },
+  { regex: /\bchild_process\b/, type: "shell_command" },
+];
+
+const NETWORK_PATTERNS = [
+  { regex: /\bfetch\s*\(/, type: "network_call" },
+  { regex: /\bcurl\b/, type: "network_call" },
+  { regex: /https?:\/\//, type: "url_reference" },
+  { regex: /\bXMLHttpRequest\b/, type: "network_call" },
+  { regex: /\baxios\b/, type: "network_call" },
+];
+
+const FS_PATTERNS = [
+  { regex: /\bfs\.write/, type: "fs_write" },
+  { regex: /\bwriteFile/, type: "fs_write" },
+  { regex: />[>]?\s*[\/~]/, type: "fs_redirect" },
+];
+
+const ENV_PATTERNS = [
+  { regex: /\bprocess\.env\b/, type: "env_access" },
+  { regex: /\$ENV\b/, type: "env_access" },
+  { regex: /\$\{?\w+\}?/, type: "env_variable" },
+];
+
+const ENCODING_PATTERNS = [
+  { regex: /\batob\s*\(/, type: "base64_decode" },
+  { regex: /\bbtoa\s*\(/, type: "base64_encode" },
+  { regex: /Buffer\.from\s*\([^)]*,\s*['"]base64['"]/, type: "base64_decode" },
+  { regex: /Buffer\.from\s*\([^)]*,\s*['"]hex['"]/, type: "hex_decode" },
+  { regex: /\\x[0-9a-fA-F]{2}/, type: "hex_escape" },
+  { regex: /\\u200[b-f]|\\u2060|\\ufeff/, type: "zero_width_char" },
+];
+
+// Unicode zero-width and homoglyph detection (raw chars)
+const UNICODE_PATTERNS = [
+  { regex: /[\u200B-\u200F\u2060\uFEFF]/, type: "zero_width_char" },
+  { regex: /[\u0410-\u044F]/, type: "cyrillic_homoglyph" },  // Cyrillic chars that look like Latin
+];
+
+const ALL_PATTERNS = [
+  ...SHELL_PATTERNS,
+  ...NETWORK_PATTERNS,
+  ...FS_PATTERNS,
+  ...ENV_PATTERNS,
+  ...ENCODING_PATTERNS,
+  ...UNICODE_PATTERNS,
+];
+
+function assessRisk(violations: Violation[]): RiskLevel {
+  if (violations.length === 0) return "low";
+
+  const types = new Set(violations.map((v) => v.type));
+  const hasShell = types.has("shell_command") || types.has("shell_backtick");
+  const hasNetwork = types.has("network_call");
+  const hasFs = types.has("fs_write") || types.has("fs_redirect");
+  const hasZeroWidth = types.has("zero_width_char");
+  const hasHomoglyph = types.has("cyrillic_homoglyph");
+
+  // Critical: shell + encoding, or zero-width/homoglyph obfuscation
+  if ((hasShell && (types.has("base64_decode") || types.has("hex_decode"))) ||
+      hasZeroWidth || hasHomoglyph) {
+    return "critical";
+  }
+
+  // High: direct shell commands or fs writes
+  if (hasShell || hasFs) return "high";
+
+  // Medium: network calls or encoding without shell
+  if (hasNetwork || types.has("base64_decode") || types.has("hex_decode")) return "medium";
+
+  return "low";
+}
+
+export class SkillScan extends Resource {
+  async post(data: any, context?: any) {
+    const { content } = data || {};
+
+    if (!content || typeof content !== "string") {
+      return new Response(
+        JSON.stringify({ error: "content (string) required" }),
+        { status: 400, headers: { "Content-Type": "application/json" } },
+      );
+    }
+
+    // 8KB size limit
+    const byteLength = new TextEncoder().encode(content).length;
+    if (byteLength > 8192) {
+      return new Response(
+        JSON.stringify({ error: `Content exceeds 8KB limit (${byteLength} bytes)` }),
+        { status: 413, headers: { "Content-Type": "application/json" } },
+      );
+    }
+
+    const lines = content.split("\n");
+    const violations: Violation[] = [];
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      for (const pattern of ALL_PATTERNS) {
+        if (pattern.regex.test(line)) {
+          violations.push({
+            type: pattern.type,
+            line: i + 1,
+            content: line.trim().slice(0, 200),
+          });
+        }
+      }
+    }
+
+    const riskLevel = assessRisk(violations);
+
+    return {
+      safe: violations.length === 0,
+      violations,
+      riskLevel,
+    };
+  }
+}

package/resources/Soul.ts

@@ -0,0 +1,10 @@
+import { databases } from "@harperfast/harper";
+
+export class Soul extends (databases as any).flair.Soul {
+  async post(content: any, context?: any) {
+    content.durability ||= "permanent";
+    content.createdAt = new Date().toISOString();
+    content.updatedAt = content.createdAt;
+    return super.post(content, context);
+  }
+}

package/resources/SoulFeed.ts

@@ -0,0 +1,15 @@
+import { Resource, databases } from '@harperfast/harper';
+
+export class FeedSouls extends Resource {
+  async *connect(target: any, incomingMessages: any) {
+    const subscription = await (databases as any).flair.Soul.subscribe(target);
+    
+    if (!incomingMessages) {
+      return subscription;
+    }
+
+    for await (const event of subscription) {
+      yield event;
+    }
+  }
+}

package/resources/WorkspaceLatest.ts

@@ -0,0 +1,66 @@
+/**
+ * WorkspaceLatest.ts — Custom resource returning the most recent WorkspaceState for an agent.
+ *
+ * GET /WorkspaceLatest/{agentId} — returns most recent WorkspaceState record.
+ * Auth: requesting agent must match agentId in path (or be admin).
+ */
+
+import { Resource, databases } from "@harperfast/harper";
+
+export class WorkspaceLatest extends Resource {
+  async get(pathInfo?: any) {
+    const request = (this as any).context?.request ?? (this as any).request;
+    const callerAgent = request?.tpsAgent;
+    const callerIsAdmin = request?.tpsAgentIsAdmin === true;
+
+    // Extract agentId from path: /WorkspaceLatest/{agentId}
+    const agentId =
+      (typeof pathInfo === "string" ? pathInfo : null) ??
+      (this as any).getId?.() ??
+      null;
+
+    if (!agentId) {
+      return new Response(
+        JSON.stringify({ error: "agentId required in path: GET /WorkspaceLatest/{agentId}" }),
+        { status: 400, headers: { "Content-Type": "application/json" } },
+      );
+    }
+
+    // Auth: requesting agent must match path agentId (or admin)
+    if (callerAgent && !callerIsAdmin && callerAgent !== agentId) {
+      return new Response(
+        JSON.stringify({ error: "forbidden: cannot read workspace state for another agent" }),
+        { status: 403, headers: { "Content-Type": "application/json" } },
+      );
+    }
+
+    // Query WorkspaceState table for this agent, sorted by timestamp desc
+    let latest: any = null;
+    try {
+      const results = (databases as any).flair.WorkspaceState.search({
+        conditions: [{ attribute: "agentId", comparator: "equals", value: agentId }],
+        sort: { attribute: "timestamp", descending: true },
+        limit: 1,
+      });
+
+      for await (const row of results) {
+        latest = row;
+        break;
+      }
+    } catch (err: any) {
+      return new Response(
+        JSON.stringify({ error: "workspace_state_query_failed", detail: err.message }),
+        { status: 500, headers: { "Content-Type": "application/json" } },
+      );
+    }
+
+    if (!latest) {
+      return new Response(
+        JSON.stringify({ error: "no_workspace_state_found", agentId }),
+        { status: 404, headers: { "Content-Type": "application/json" } },
+      );
+    }
+
+    return latest;
+  }
+}

package/resources/WorkspaceState.ts

@@ -0,0 +1,102 @@
+/**
+ * WorkspaceState.ts — Harper table resource for workspace state records (OPS-47 Phase 2)
+ *
+ * Auth: Ed25519 middleware sets request.tpsAgent. Agent can only read/write own records.
+ * Pattern follows Memory.ts — extends Harper auto-generated table class.
+ *
+ * Note: Harper's static methods call instance methods with positional args only.
+ * Use this.getContext() to access request context (tpsAgent, tpsAgentIsAdmin).
+ */
+
+import { databases } from "@harperfast/harper";
+import { isAdmin } from "./auth-middleware.js";
+
+export class WorkspaceState extends (databases as any).flair.WorkspaceState {
+  /**
+   * Helper to extract auth info from Harper's Resource instance context.
+   */
+  private _authInfo() {
+    const ctx = (this as any).getContext?.();
+    const request = ctx?.request ?? ctx;
+    return {
+      agentId: request?.tpsAgent as string | undefined,
+      isAdmin: request?.tpsAgentIsAdmin as boolean ?? false,
+    };
+  }
+
+  /**
+   * Override search() to scope collection GETs to the authenticated agent's
+   * own workspace state records. Admin agents see all records.
+   */
+  async search(query?: any) {
+    const { agentId: authAgent, isAdmin: isAdminAgent } = this._authInfo();
+
+    if (!authAgent || isAdminAgent) {
+      return super.search(query);
+    }
+
+    const agentIdCondition = { attribute: "agentId", comparator: "equals", value: authAgent };
+
+    // Harper passes `query` as a request target object (with pathname, id, isCollection, etc.)
+    // Inject scope condition into its `.conditions` array so Table.search() processes it correctly.
+    if (query && typeof query === "object" && !Array.isArray(query)) {
+      const existing = query.conditions ?? [];
+      query.conditions = Array.isArray(existing)
+        ? [agentIdCondition, ...existing]
+        : [agentIdCondition, existing];
+      return super.search(query);
+    }
+
+    const conditions = Array.isArray(query) && query.length > 0
+      ? [agentIdCondition, ...query]
+      : [agentIdCondition];
+    return super.search(conditions);
+  }
+
+  async post(content: any) {
+    const { agentId, isAdmin: isAdminAgent } = this._authInfo();
+
+    // Agent-scoped: agentId in body must match authenticated agent
+    if (agentId && !isAdminAgent && content.agentId !== agentId) {
+      return new Response(
+        JSON.stringify({ error: "forbidden: cannot write workspace state for another agent" }),
+        { status: 403, headers: { "Content-Type": "application/json" } },
+      );
+    }
+
+    content.createdAt = new Date().toISOString();
+    content.timestamp ||= content.createdAt;
+
+    return super.post(content);
+  }
+
+  async put(content: any) {
+    const { agentId, isAdmin: isAdminAgent } = this._authInfo();
+
+    if (agentId && !isAdminAgent && content.agentId !== agentId) {
+      return new Response(
+        JSON.stringify({ error: "forbidden: cannot write workspace state for another agent" }),
+        { status: 403, headers: { "Content-Type": "application/json" } },
+      );
+    }
+
+    return super.put(content);
+  }
+
+  async delete(id: any) {
+    const { agentId, isAdmin: isAdminAgent } = this._authInfo();
+    if (!agentId) return super.delete(id);
+
+    const record = await this.get(id);
+    if (!record) return super.delete(id);
+
+    if (!isAdminAgent && record.agentId !== agentId) {
+      return new Response(
+        JSON.stringify({ error: "forbidden: cannot delete workspace state for another agent" }),
+        { status: 403, headers: { "Content-Type": "application/json" } },
+      );
+    }
+
+    return super.delete(id);
+  }
+}