@tpsdev-ai/flair 0.2.0

package/dist/resources/MemoryFeed.js

@@ -0,0 +1,41 @@
+import { Resource, databases } from "@harperfast/harper";
+import { computeContentHash, findExistingMemoryByContentHash } from "./memory-feed-lib.js";
+export class FeedMemories extends Resource {
+    async post(content) {
+        const agentId = String(content?.agentId ?? "");
+        const body = String(content?.content ?? "");
+        if (!agentId || !body) {
+            return new Response(JSON.stringify({ error: "agentId and content are required" }), {
+                status: 400,
+                headers: { "Content-Type": "application/json" },
+            });
+        }
+        const now = new Date().toISOString();
+        const contentHash = computeContentHash(agentId, body);
+        const existing = await findExistingMemoryByContentHash(databases.flair.Memory.search(), agentId, contentHash);
+        if (existing)
+            return existing;
+        const record = {
+            ...content,
+            id: content.id ?? `${agentId}-${Date.now()}`,
+            agentId,
+            content: body,
+            contentHash,
+            durability: content.durability ?? "standard",
+            createdAt: content.createdAt ?? now,
+            updatedAt: content.updatedAt ?? now,
+            archived: content.archived ?? false,
+        };
+        await databases.flair.Memory.put(record);
+        return record;
+    }
+    async *connect(target, incomingMessages) {
+        const subscription = await databases.flair.Memory.subscribe(target);
+        if (!incomingMessages) {
+            return subscription;
+        }
+        for await (const event of subscription) {
+            yield event;
+        }
+    }
+}

package/dist/resources/MemoryReflect.js

@@ -0,0 +1,105 @@
+/**
+ * POST /MemoryReflect
+ *
+ * Gathers recent memories for an agent and returns a structured reflection
+ * prompt. The agent feeds the prompt + memories to its LLM and writes
+ * insights back as persistent memories (with derivedFrom linking).
+ *
+ * Request:
+ *   agentId      string   — which agent to reflect on
+ *   scope        string   — "recent" | "tagged" | "all" (default: "recent")
+ *   since        string?  — ISO timestamp lower bound (default: 24h ago)
+ *   maxMemories  number?  — cap (default: 50)
+ *   focus        string?  — "lessons_learned" | "patterns" | "decisions" | "errors" (default: "lessons_learned")
+ *   tag          string?  — required when scope="tagged"
+ *
+ * Response:
+ *   memories       Memory[]   — source memories included in the prompt
+ *   prompt         string     — structured LLM prompt
+ *   suggestedTags  string[]   — tags Flair detected in the source set
+ *   count          number     — number of memories included
+ */
+import { Resource, databases } from "@harperfast/harper";
+import { isAdmin } from "./auth-middleware.js";
+import { patchRecordSilent } from "./table-helpers.js";
+const FOCUS_PROMPTS = {
+    lessons_learned: "Review these memories and identify concrete lessons learned. For each lesson: what happened, what you learned, and how it should change future behavior. Write atomic memories with durability=persistent.",
+    patterns: "Identify recurring patterns across these memories. What themes, approaches, or outcomes appear multiple times? Extract each pattern as a persistent memory.",
+    decisions: "Catalog the key decisions made and their outcomes. For each: what was decided, why, and what resulted. Promote important decisions to persistent.",
+    errors: "Extract errors, bugs, and failures. For each: what failed, root cause, and fix applied. These are high-value persistent memories.",
+};
+export class ReflectMemories extends Resource {
+    async post(data) {
+        const { agentId, scope = "recent", since, maxMemories = 50, focus = "lessons_learned", tag, } = data || {};
+        if (!agentId)
+            return new Response(JSON.stringify({ error: "agentId required" }), { status: 400 });
+        // Auth: agent can only reflect on own memories unless admin
+        const actorId = this.request?.tpsAgent;
+        if (actorId && actorId !== agentId && !(await isAdmin(actorId))) {
+            return new Response(JSON.stringify({ error: "forbidden: can only reflect on own memories" }), { status: 403 });
+        }
+        const sinceDate = since ? new Date(since) : new Date(Date.now() - 24 * 3600_000);
+        const memories = [];
+        for await (const record of databases.flair.Memory.search()) {
+            if (record.agentId !== agentId)
+                continue;
+            if (record.archived)
+                continue;
+            if (record.durability === "permanent")
+                continue; // permanent memories don't need reflection
+            if (scope === "tagged") {
+                if (!tag || !(record.tags ?? []).includes(tag))
+                    continue;
+            }
+            else if (scope === "recent") {
+                if (!record.createdAt || new Date(record.createdAt) < sinceDate)
+                    continue;
+            }
+            // scope="all" passes everything
+            const { embedding, ...rest } = record;
+            memories.push(rest);
+            if (memories.length >= maxMemories)
+                break;
+        }
+        memories.sort((a, b) => (a.createdAt ?? "").localeCompare(b.createdAt ?? ""));
+        // Collect tags present in source memories
+        const tagSet = new Set();
+        for (const m of memories) {
+            for (const t of m.tags ?? [])
+                tagSet.add(t);
+        }
+        // Build prompt
+        const focusText = FOCUS_PROMPTS[focus] ?? FOCUS_PROMPTS.lessons_learned;
+        const memorySummary = memories
+            .map((m, i) => `[${i + 1}] (${m.id}) ${m.createdAt?.slice(0, 10) ?? "?"}: ${m.content.slice(0, 300)}`)
+            .join("\n");
+        const prompt = `# Memory Reflection — ${agentId}
+Focus: ${focus}
+Scope: ${scope} (since ${sinceDate.toISOString()})
+Memories: ${memories.length}
+
+## Task
+${focusText}
+
+## Source Memories
+${memorySummary || "(none)"}
+
+## Instructions
+For each insight:
+1. Write a new memory with durability=persistent
+2. Set derivedFrom=[<source memory ids>]
+3. Set tags from the source memories where relevant
+4. Keep each memory atomic — one insight per record`;
+        // Update lastReflected on source memories (read-modify-write to preserve embeddings)
+        const now = new Date().toISOString();
+        for (const m of memories) {
+            patchRecordSilent(databases.flair.Memory, m.id, { lastReflected: now });
+        }
+        return {
+            memories,
+            prompt,
+            suggestedTags: [...tagSet].slice(0, 20),
+            count: memories.length,
+        };
+    }
+}

package/dist/resources/OrgEvent.js

@@ -0,0 +1,43 @@
+/**
+ * OrgEvent.ts — Harper table resource for org-wide activity events.
+ *
+ * Auth: Ed25519 middleware sets request.tpsAgent.
+ * Write: authorId must match authenticated agent (or admin).
+ * Read: any authenticated participant can read (org-scoped).
+ */
+import { databases } from "@harperfast/harper";
+export class OrgEvent extends databases.flair.OrgEvent {
+    async post(content, context) {
+        const agentId = context?.request?.tpsAgent;
+        // authorId must match authenticated agent (unless admin)
+        if (agentId && !context?.request?.tpsAgentIsAdmin && content.authorId !== agentId) {
+            return new Response(JSON.stringify({ error: "forbidden: authorId must match authenticated agent" }), { status: 403, headers: { "Content-Type": "application/json" } });
+        }
+        // Generate composite ID if not provided
+        if (!content.id) {
+            content.id = `${content.authorId}-${Date.now()}`;
+        }
+        content.createdAt = new Date().toISOString();
+        // Harper 5: table resources use put() for create/upsert (post() removed)
+        return databases.flair.OrgEvent.put(content);
+    }
+    async put(content, context) {
+        const agentId = context?.request?.tpsAgent;
+        if (agentId && !context?.request?.tpsAgentIsAdmin && content.authorId !== agentId) {
+            return new Response(JSON.stringify({ error: "forbidden: authorId must match authenticated agent" }), { status: 403, headers: { "Content-Type": "application/json" } });
+        }
+        return databases.flair.OrgEvent.put(content);
+    }
+    async delete(id, context) {
+        const agentId = context?.request?.tpsAgent;
+        if (!agentId)
+            return super.delete(id, context);
+        const record = await this.get(id);
+        if (!record)
+            return super.delete(id, context);
+        if (!context?.request?.tpsAgentIsAdmin && record.authorId !== agentId) {
+            return new Response(JSON.stringify({ error: "forbidden: cannot delete events authored by another agent" }), { status: 403, headers: { "Content-Type": "application/json" } });
+        }
+        return super.delete(id, context);
+    }
+}

package/dist/resources/OrgEventCatchup.js

@@ -0,0 +1,65 @@
+/**
+ * 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) {
+        const request = this.request;
+        const callerAgent = request?.tpsAgent;
+        const callerIsAdmin = request?.tpsAgentIsAdmin === true;
+        // Harper routes /OrgEventCatchup/{id} with pathInfo.id as the path segment
+        const participantId = (typeof pathInfo === "object" && pathInfo !== null ? pathInfo.id : null) ??
+            (typeof pathInfo === "string" ? pathInfo : null) ??
+            this.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 = (typeof pathInfo === "object" && pathInfo !== null
+            ? pathInfo.conditions?.find((c) => 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 = [];
+        for await (const event of databases.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, b) => (a.createdAt || "").localeCompare(b.createdAt || ""));
+        // Limit to 50
+        return results.slice(0, 50);
+    }
+}

package/dist/resources/OrgEventMaintenance.js

@@ -0,0 +1,29 @@
+/**
+ * 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, context) {
+        // 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 = [];
+        for await (const event of databases.flair.OrgEvent.search()) {
+            if (event.expiresAt && event.expiresAt < now) {
+                toDelete.push(event.id);
+            }
+        }
+        for (const id of toDelete) {
+            try {
+                await databases.flair.OrgEvent.delete(id);
+            }
+            catch { }
+        }
+        return { deleted: toDelete.length };
+    }
+}

package/dist/resources/SemanticSearch.js

@@ -0,0 +1,147 @@
+import { Resource, databases } from "@harperfast/harper";
+import { getEmbedding, getMode } from "./embeddings-provider.js";
+import { patchRecord } from "./table-helpers.js";
+function cosineSimilarity(a, b) {
+    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 = {
+    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 = {
+    permanent: Infinity, // never decays
+    persistent: 90,
+    standard: 30,
+    ephemeral: 7,
+};
+function recencyFactor(createdAt, durability) {
+    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) {
+    if (!retrievalCount || retrievalCount <= 0)
+        return 1.0;
+    return 1.0 + 0.1 * Math.log2(retrievalCount); // gentle boost: 10 retrievals → ~1.33x
+}
+function compositeScore(semanticScore, record) {
+    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) {
+        const { agentId, q, queryEmbedding, tag, subject, subjects, limit = 10, includeSuperseded = false, scoring = "composite" } = data || {};
+        const subjectFilter = subjects
+            ? new Set(subjects.map((s) => s.toLowerCase()))
+            : subject
+                ? new Set([subject.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 = this.request?.headers?.get?.("x-tps-agent");
+        const callerIsAdmin = this.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();
+        if (agentId)
+            searchAgentIds.add(agentId);
+        if (agentId) {
+            try {
+                for await (const grant of databases.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 = [];
+        // Iterate ALL memories, filter by agent ID set
+        for await (const record of databases.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();
+            for (const r of results) {
+                if (r.supersedes)
+                    supersededIds.add(r.supersedes);
+            }
+            filteredResults = results.filter((r) => !supersededIds.has(r.id));
+        }
+        filteredResults.sort((a, b) => 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.flair.Memory, r.id, {
+                retrievalCount: (r.retrievalCount || 0) + 1,
+                lastRetrieved: now,
+            }).catch(() => { });
+        }
+        return { results: topResults };
+    }
+}

package/dist/resources/SkillScan.js

@@ -0,0 +1,101 @@
+import { Resource } from "@harperfast/harper";
+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) {
+    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, context) {
+        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 = [];
+        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/dist/resources/Soul.js

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

package/dist/resources/SoulFeed.js

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

package/dist/resources/WorkspaceLatest.js

@@ -0,0 +1,45 @@
+/**
+ * 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) {
+        const request = this.context?.request ?? this.request;
+        const callerAgent = request?.tpsAgent;
+        const callerIsAdmin = request?.tpsAgentIsAdmin === true;
+        // Extract agentId from path: /WorkspaceLatest/{agentId}
+        const agentId = (typeof pathInfo === "string" ? pathInfo : null) ??
+            this.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 = null;
+        try {
+            const results = databases.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) {
+            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;
+    }
+}