@tpsdev-ai/flair 0.2.0

package/dist/resources/A2AAdapter.js

@@ -0,0 +1,474 @@
+import { Resource, databases } from "@harperfast/harper";
+import { access, readFile, readdir } from "node:fs/promises";
+import { constants } from "node:fs";
+import { basename, extname, join } from "node:path";
+const BEADS_ROOT = join(process.env.HOME || "/root", "ops", ".beads");
+const BEADS_ISSUES_DIR = join(BEADS_ROOT, "issues");
+const BEADS_ISSUES_JSONL = join(BEADS_ROOT, "issues.jsonl");
+function rpcResult(id, result) {
+    return { jsonrpc: "2.0", id: id ?? null, result };
+}
+function rpcError(id, code, message, data) {
+    return {
+        jsonrpc: "2.0",
+        id: id ?? null,
+        error: data === undefined ? { code, message } : { code, message, data },
+    };
+}
+function cleanText(value) {
+    return String(value ?? "").trim();
+}
+function truncate(value, max) {
+    return value.length <= max ? value : `${value.slice(0, Math.max(0, max - 1))}…`;
+}
+function firstTextPart(message) {
+    const parts = Array.isArray(message?.parts) ? message.parts : [];
+    for (const part of parts) {
+        const text = cleanText(part?.text);
+        if (text)
+            return text;
+    }
+    return "";
+}
+function stripQuotes(value) {
+    if ((value.startsWith("\"") && value.endsWith("\"")) || (value.startsWith("'") && value.endsWith("'"))) {
+        return value.slice(1, -1);
+    }
+    return value;
+}
+function parseSimpleYamlIssue(raw, fallbackId) {
+    const issue = { id: fallbackId };
+    const lines = raw.split(/\r?\n/);
+    let listKey = null;
+    for (const line of lines) {
+        if (!line.trim() || line.trimStart().startsWith("#"))
+            continue;
+        const itemMatch = line.match(/^\s*-\s*(.+)\s*$/);
+        if (itemMatch && listKey) {
+            const current = issue[listKey];
+            if (!Array.isArray(current))
+                issue[listKey] = [];
+            issue[listKey].push(stripQuotes(itemMatch[1].trim()));
+            continue;
+        }
+        if (/^\s/.test(line))
+            continue;
+        const fieldMatch = line.match(/^([A-Za-z0-9_]+):\s*(.*)\s*$/);
+        if (!fieldMatch) {
+            listKey = null;
+            continue;
+        }
+        const [, key, rawValue] = fieldMatch;
+        if (rawValue === "") {
+            issue[key] = issue[key] ?? "";
+            listKey = key;
+            continue;
+        }
+        if (rawValue === "[]" || rawValue === "[ ]") {
+            issue[key] = [];
+            listKey = null;
+            continue;
+        }
+        if (rawValue === "|" || rawValue === ">") {
+            issue[key] = "";
+            listKey = null;
+            continue;
+        }
+        issue[key] = stripQuotes(rawValue.trim());
+        listKey = null;
+    }
+    if (!issue.id)
+        issue.id = fallbackId;
+    return issue;
+}
+async function pathExists(path) {
+    try {
+        await access(path, constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function readIssuesFromYamlDir() {
+    if (!(await pathExists(BEADS_ISSUES_DIR)))
+        return [];
+    const entries = await readdir(BEADS_ISSUES_DIR, { withFileTypes: true });
+    const out = [];
+    for (const entry of entries) {
+        if (!entry.isFile())
+            continue;
+        const ext = extname(entry.name).toLowerCase();
+        if (ext !== ".yaml" && ext !== ".yml")
+            continue;
+        const fullPath = join(BEADS_ISSUES_DIR, entry.name);
+        const raw = await readFile(fullPath, "utf8");
+        const fallbackId = basename(entry.name, ext);
+        out.push(parseSimpleYamlIssue(raw, fallbackId));
+    }
+    return out;
+}
+async function readIssuesFromJsonl() {
+    if (!(await pathExists(BEADS_ISSUES_JSONL)))
+        return [];
+    const raw = await readFile(BEADS_ISSUES_JSONL, "utf8");
+    const out = [];
+    for (const line of raw.split(/\r?\n/)) {
+        if (!line.trim())
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (parsed?.id)
+                out.push(parsed);
+        }
+        catch {
+            // Ignore malformed lines.
+        }
+    }
+    return out;
+}
+async function readIssue(taskId) {
+    const yamlPath = join(BEADS_ISSUES_DIR, `${taskId}.yaml`);
+    const ymlPath = join(BEADS_ISSUES_DIR, `${taskId}.yml`);
+    for (const candidate of [yamlPath, ymlPath]) {
+        if (await pathExists(candidate)) {
+            const raw = await readFile(candidate, "utf8");
+            return parseSimpleYamlIssue(raw, taskId);
+        }
+    }
+    const jsonlIssues = await readIssuesFromJsonl();
+    return jsonlIssues.find((issue) => issue.id === taskId) ?? null;
+}
+function mapBeadsStatusToA2A(statusRaw) {
+    const status = cleanText(statusRaw).toLowerCase();
+    if (status === "ready" || status === "in_progress" || status === "open" || status === "active" || status === "todo") {
+        return "working";
+    }
+    if (status === "done" || status === "closed" || status === "complete" || status === "completed") {
+        return "completed";
+    }
+    if (status === "blocked") {
+        return "input-required";
+    }
+    if (status === "cancelled" || status === "canceled") {
+        return "canceled";
+    }
+    return "working";
+}
+function taskView(issue) {
+    return {
+        id: issue.id,
+        title: issue.title ?? "",
+        status: mapBeadsStatusToA2A(issue.status),
+        assignee: issue.assignee ?? null,
+        updatedAt: issue.updated_at ?? issue.created_at ?? null,
+    };
+}
+async function taskHistory(taskId) {
+    const history = [];
+    const refId = `bd://${taskId}`;
+    for await (const event of databases.flair.OrgEvent.search()) {
+        if (event?.refId !== refId)
+            continue;
+        const summary = cleanText(event.summary);
+        if (!summary)
+            continue;
+        history.push({
+            createdAt: event.createdAt ?? "",
+            role: "agent",
+            parts: [{ text: summary }],
+        });
+    }
+    history.sort((a, b) => String(a.createdAt).localeCompare(String(b.createdAt)));
+    return history.map(({ role, parts }) => ({ role, parts }));
+}
+function artifactsFromIssue(issue) {
+    const artifacts = [];
+    const notes = cleanText(issue.notes);
+    if (notes) {
+        artifacts.push({ name: "notes", parts: [{ text: notes }] });
+    }
+    return artifacts;
+}
+async function publishOrgEvent(event) {
+    await databases.flair.OrgEvent.put({
+        id: event.id ?? `a2a-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+        authorId: event.authorId ?? "a2a",
+        kind: event.kind,
+        scope: event.scope ?? null,
+        summary: event.summary,
+        detail: event.detail ?? "",
+        targetIds: event.targetIds ?? [],
+        refId: event.refId ?? null,
+        createdAt: event.createdAt ?? new Date().toISOString(),
+    });
+}
+function parseJsonSafe(value) {
+    if (typeof value !== "string" || !value.trim())
+        return null;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return null;
+    }
+}
+function normalizeA2AStatus(statusRaw) {
+    const status = cleanText(statusRaw).toLowerCase();
+    if (!status)
+        return null;
+    if (status === "done" || status === "closed" || status === "complete" || status === "completed")
+        return "completed";
+    if (status === "failed" || status === "error")
+        return "failed";
+    if (status === "cancelled" || status === "canceled")
+        return "canceled";
+    if (status === "working" || status === "in_progress" || status === "open" || status === "active" || status === "todo") {
+        return "working";
+    }
+    return null;
+}
+function inferStatusFromText(textRaw) {
+    const text = cleanText(textRaw).toLowerCase();
+    if (!text)
+        return null;
+    if (text.includes("completed") || text.includes("complete") || text.includes("done"))
+        return "completed";
+    if (text.includes("failed") || text.includes("error"))
+        return "failed";
+    if (text.includes("cancelled") || text.includes("canceled"))
+        return "canceled";
+    if (text.includes("working") || text.includes("started") || text.includes("in progress"))
+        return "working";
+    return null;
+}
+function taskIdFromEvent(event) {
+    const refId = cleanText(event?.refId);
+    if (refId.startsWith("bd://")) {
+        const taskId = cleanText(refId.slice("bd://".length));
+        if (taskId)
+            return taskId;
+    }
+    const detail = parseJsonSafe(event?.detail);
+    const fromDetail = cleanText(detail?.taskId ?? detail?.id ?? detail?.task?.id);
+    if (fromDetail)
+        return fromDetail;
+    return null;
+}
+function statusFromOrgEvent(event) {
+    const detail = parseJsonSafe(event?.detail);
+    return (normalizeA2AStatus(detail?.status) ??
+        normalizeA2AStatus(detail?.task?.status) ??
+        normalizeA2AStatus(event?.status) ??
+        normalizeA2AStatus(event?.kind) ??
+        inferStatusFromText(event?.summary) ??
+        null);
+}
+export class A2AAdapter extends Resource {
+    async get() {
+        const host = process.env.FLAIR_PUBLIC_URL || "http://localhost:9926";
+        return new Response(JSON.stringify({
+            name: "TPS Agent Team",
+            description: "TPS — agent OS for humans and AI agents. Coordinates via Flair.",
+            url: `${host}/a2a`,
+            version: "0.1.0",
+            capabilities: {
+                streaming: true,
+                pushNotifications: false,
+            },
+            defaultInputModes: ["text"],
+            defaultOutputModes: ["text"],
+            skills: [
+                {
+                    id: "task-management",
+                    name: "Task Management",
+                    description: "Create, list, and track tasks via Beads issue tracker",
+                },
+                {
+                    id: "agent-coordination",
+                    name: "Agent Coordination",
+                    description: "Send messages to agents and coordinate work via OrgEvents",
+                },
+            ],
+        }, null, 2), {
+            status: 200,
+            headers: { "Content-Type": "application/json" },
+        });
+    }
+    async post(content, _context) {
+        const body = content;
+        if (!body || typeof body !== "object") {
+            return rpcError(null, -32600, "Invalid Request");
+        }
+        if (body.jsonrpc !== "2.0" || typeof body.method !== "string") {
+            return rpcError(body.id, -32600, "Invalid Request");
+        }
+        const id = body.id ?? null;
+        const params = body.params ?? {};
+        try {
+            if (body.method === "message/stream") {
+                const agentId = cleanText(params.agentId);
+                if (!agentId) {
+                    return rpcError(id, -32602, "Invalid params: agentId is required");
+                }
+                const taskIdHint = cleanText(params.taskId) || null;
+                const encoder = new TextEncoder();
+                const startedAt = Date.now();
+                const timeoutMs = 5 * 60 * 1000;
+                let lastSeen = new Date(startedAt).toISOString();
+                let closed = false;
+                const seenEventIds = new Set();
+                const seenEventQueue = [];
+                const stream = new ReadableStream({
+                    start(controller) {
+                        const writeEvent = (eventName, payload) => {
+                            if (closed)
+                                return;
+                            const frame = `event: ${eventName}\ndata: ${JSON.stringify(payload)}\n\n`;
+                            controller.enqueue(encoder.encode(frame));
+                        };
+                        const closeStream = () => {
+                            if (closed)
+                                return;
+                            closed = true;
+                            clearInterval(pollTimer);
+                            clearTimeout(timeoutTimer);
+                            controller.close();
+                        };
+                        const poll = async () => {
+                            if (closed)
+                                return;
+                            if (Date.now() - startedAt >= timeoutMs) {
+                                closeStream();
+                                return;
+                            }
+                            const catchupUrl = `http://localhost:9926/OrgEventCatchup/${encodeURIComponent(agentId)}?since=${lastSeen}`;
+                            let events = [];
+                            try {
+                                const response = await fetch(catchupUrl);
+                                if (!response.ok)
+                                    return;
+                                const data = await response.json();
+                                if (Array.isArray(data))
+                                    events = data;
+                                else if (Array.isArray(data?.events))
+                                    events = data.events;
+                            }
+                            catch {
+                                return;
+                            }
+                            for (const event of events) {
+                                const eventId = cleanText(event?.id) || `${cleanText(event?.createdAt)}:${cleanText(event?.summary)}`;
+                                if (eventId && seenEventIds.has(eventId))
+                                    continue;
+                                if (eventId) {
+                                    seenEventIds.add(eventId);
+                                    seenEventQueue.push(eventId);
+                                    if (seenEventQueue.length > 500) {
+                                        const removed = seenEventQueue.shift();
+                                        if (removed)
+                                            seenEventIds.delete(removed);
+                                    }
+                                }
+                                const createdAt = cleanText(event?.createdAt);
+                                if (createdAt && createdAt > lastSeen)
+                                    lastSeen = createdAt;
+                                const status = statusFromOrgEvent(event);
+                                if (!status)
+                                    continue;
+                                writeEvent("task.status", rpcResult(id, {
+                                    type: "task",
+                                    task: { id: taskIdFromEvent(event) ?? taskIdHint, status },
+                                }));
+                                if (status === "completed" || status === "failed" || status === "canceled") {
+                                    closeStream();
+                                    return;
+                                }
+                            }
+                        };
+                        const pollTimer = setInterval(() => { void poll(); }, 2000);
+                        const timeoutTimer = setTimeout(() => { closeStream(); }, timeoutMs);
+                        void poll();
+                    },
+                    cancel() { closed = true; },
+                });
+                return new Response(stream, {
+                    headers: { "Content-Type": "text/event-stream", "Cache-Control": "no-cache" },
+                });
+            }
+            if (body.method === "message/send") {
+                const agentId = cleanText(params.agentId);
+                const message = params.message;
+                if (!agentId || !message || typeof message !== "object") {
+                    return rpcError(id, -32602, "Invalid params: agentId and message are required");
+                }
+                const agent = await databases.flair.Agent.get(agentId).catch(() => null);
+                if (!agent) {
+                    return rpcError(id, -32004, "Agent not found", { agentId });
+                }
+                const summary = truncate(firstTextPart(message) || "A2A message received", 200);
+                await publishOrgEvent({
+                    kind: "a2a.message",
+                    scope: agentId,
+                    summary,
+                    detail: JSON.stringify({ message }),
+                    targetIds: [agentId],
+                });
+                return rpcResult(id, {
+                    type: "message",
+                    message: {
+                        role: "agent",
+                        parts: [{ text: "Message received. Task created." }],
+                    },
+                });
+            }
+            if (body.method === "tasks/get") {
+                const taskId = cleanText(params.taskId);
+                if (!taskId)
+                    return rpcError(id, -32602, "Invalid params: taskId is required");
+                const issue = await readIssue(taskId);
+                if (!issue)
+                    return rpcError(id, -32004, "Task not found", { taskId });
+                const history = await taskHistory(taskId);
+                return rpcResult(id, {
+                    type: "task",
+                    task: {
+                        ...taskView(issue),
+                        artifacts: artifactsFromIssue(issue),
+                        history,
+                    },
+                });
+            }
+            if (body.method === "tasks/list") {
+                const yamlIssues = await readIssuesFromYamlDir();
+                const issues = yamlIssues.length > 0 ? yamlIssues : await readIssuesFromJsonl();
+                const agentIdFilter = cleanText(params.agentId).toLowerCase();
+                const statusFilter = cleanText(params.status).toLowerCase();
+                const tasks = issues
+                    .filter((issue) => {
+                    if (agentIdFilter) {
+                        const assignee = cleanText(issue.assignee).toLowerCase();
+                        if (assignee !== agentIdFilter)
+                            return false;
+                    }
+                    if (statusFilter) {
+                        const mapped = mapBeadsStatusToA2A(issue.status).toLowerCase();
+                        if (mapped !== statusFilter)
+                            return false;
+                    }
+                    return true;
+                })
+                    .map((issue) => taskView(issue))
+                    .sort((a, b) => String(b.updatedAt ?? "").localeCompare(String(a.updatedAt ?? "")));
+                return rpcResult(id, { type: "tasks", tasks });
+            }
+            return rpcError(id, -32601, "Method not found");
+        }
+        catch (error) {
+            return rpcError(id, -32000, "Server error", { detail: error?.message ?? String(error) });
+        }
+    }
+}
+// Expose exact lowercase endpoint required by A2A clients: POST /a2a
+export class a2a extends A2AAdapter {
+}

package/dist/resources/Agent.js

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

package/dist/resources/AgentCard.js

@@ -0,0 +1,45 @@
+import { Resource, databases } from "@harperfast/harper";
+function readSoulKind(entry) {
+    return String(entry.kind ?? entry.key ?? "").trim().toLowerCase();
+}
+function readSoulContent(entry) {
+    return String(entry.content ?? entry.value ?? "").trim();
+}
+export class AgentCard extends Resource {
+    async get(pathInfo) {
+        const agentId = (typeof pathInfo === "string" ? pathInfo : null) ??
+            this.getId?.() ??
+            null;
+        if (!agentId) {
+            return new Response(JSON.stringify({ error: "agentId required in path: GET /AgentCard/{agentId}" }), { status: 400, headers: { "Content-Type": "application/json" } });
+        }
+        const agent = await databases.flair.Agent.get(agentId).catch(() => null);
+        if (!agent) {
+            return new Response(JSON.stringify({ error: "agent_not_found", agentId }), {
+                status: 404,
+                headers: { "Content-Type": "application/json" },
+            });
+        }
+        const souls = [];
+        for await (const row of databases.flair.Soul.search()) {
+            if (row?.agentId === agentId)
+                souls.push(row);
+        }
+        const descriptionEntry = souls.find((s) => readSoulKind(s) === "description" && readSoulContent(s)) ??
+            souls.find((s) => readSoulContent(s));
+        const skills = souls
+            .filter((s) => readSoulKind(s) === "capability")
+            .map((s) => readSoulContent(s))
+            .filter(Boolean);
+        return {
+            name: String(agent.name ?? agent.id ?? agentId),
+            description: descriptionEntry ? readSoulContent(descriptionEntry) : "",
+            url: String(agent.url ?? ""),
+            version: String(agent.version ?? "1.0.0"),
+            capabilities: agent.capabilities && typeof agent.capabilities === "object" ? agent.capabilities : {},
+            skills,
+            defaultInputModes: ["text"],
+            defaultOutputModes: ["text"],
+        };
+    }
+}

package/dist/resources/AgentSeed.js

@@ -0,0 +1,111 @@
+/**
+ * POST /AgentSeed
+ *
+ * Auto-seeds a new agent with soul entries and starter memories.
+ * Called by `tps agent create` after local key generation.
+ *
+ * Request:
+ *   agentId          string   — agent identifier
+ *   displayName      string?  — human-readable name (defaults to agentId)
+ *   role             string?  — "admin" | "agent" (default: "agent")
+ *   soulTemplate     object?  — key:value pairs for Soul table (merged with defaults)
+ *   starterMemories  array?   — [{content, tags?, durability?}] (defaults if omitted)
+ *
+ * Response:
+ *   { agent, soulEntries, memories }
+ *
+ * Auth: admin only.
+ */
+import { Resource, databases } from "@harperfast/harper";
+import { isAdmin } from "./auth-middleware.js";
+const DEFAULT_SOUL_KEYS = (agentId, displayName, role, now) => ({
+    name: displayName,
+    role,
+    created: now,
+    status: "active",
+});
+const DEFAULT_MEMORIES = (agentId, now) => [
+    {
+        content: `Agent ${agentId} initialized. No prior context.`,
+        tags: ["onboarding", "system"],
+        durability: "persistent",
+    },
+];
+export class AgentSeed extends Resource {
+    async post(data) {
+        const actorId = this.request?.tpsAgent;
+        if (!actorId || !(await isAdmin(actorId))) {
+            return new Response(JSON.stringify({ error: "forbidden: admin only" }), { status: 403 });
+        }
+        const { agentId, displayName, role = "agent", soulTemplate, starterMemories } = data || {};
+        if (!agentId)
+            return new Response(JSON.stringify({ error: "agentId required" }), { status: 400 });
+        if (!/^[a-zA-Z0-9_-]{1,64}$/.test(agentId)) {
+            return new Response(JSON.stringify({ error: "invalid agentId" }), { status: 400 });
+        }
+        const now = new Date().toISOString();
+        const name = displayName || agentId;
+        // ── Agent record ──────────────────────────────────────────────────────────
+        const existingAgent = await databases.flair.Agent.get(agentId).catch(() => null);
+        let agent = existingAgent;
+        if (!existingAgent) {
+            agent = { id: agentId, name, role, publicKey: "pending", createdAt: now, updatedAt: now };
+            await databases.flair.Agent.put(agent);
+        }
+        // ── Soul entries ──────────────────────────────────────────────────────────
+        const defaults = DEFAULT_SOUL_KEYS(agentId, name, role, now);
+        const merged = { ...defaults, ...(soulTemplate || {}) };
+        const soulEntries = [];
+        for (const [key, value] of Object.entries(merged)) {
+            const id = `${agentId}:${key}`;
+            const existing = await databases.flair.Soul.get(id);
+            if (existing) {
+                soulEntries.push(existing); // skip — don't overwrite existing soul entries
+                continue;
+            }
+            const entry = { id, agentId, key, value: String(value), durability: "permanent", createdAt: now, updatedAt: now };
+            await databases.flair.Soul.put(entry);
+            soulEntries.push(entry);
+        }
+        // ── Starter memories ──────────────────────────────────────────────────────
+        const memDefs = starterMemories && starterMemories.length > 0
+            ? starterMemories
+            : DEFAULT_MEMORIES(agentId, now);
+        const memories = [];
+        // Only seed memories if this is a first-time seed (none tagged onboarding yet)
+        const hasOnboardingMemory = await (async () => {
+            for await (const m of databases.flair.Memory.search()) {
+                if (m.agentId === agentId && (m.tags ?? []).includes("onboarding"))
+                    return true;
+            }
+            return false;
+        })();
+        if (hasOnboardingMemory) {
+            // Re-seed: return existing onboarding memories without writing new ones
+            for await (const m of databases.flair.Memory.search()) {
+                if (m.agentId === agentId && (m.tags ?? []).includes("onboarding"))
+                    memories.push(m);
+            }
+        }
+        else {
+            for (let i = 0; i < memDefs.length; i++) {
+                const def = memDefs[i];
+                const id = `seed-${agentId}-${i}-${Date.now()}`;
+                const record = {
+                    id,
+                    agentId,
+                    content: def.content,
+                    durability: def.durability ?? "persistent",
+                    tags: def.tags ?? ["onboarding"],
+                    source: "seed",
+                    createdAt: now,
+                    updatedAt: now,
+                    archived: false,
+                };
+                await databases.flair.Memory.put(record);
+                memories.push(record);
+            }
+        } // end !hasOnboardingMemory
+        return { agent, soulEntries, memories };
+    }
+}