fauna-api 0.0.0-stage → 1.0.676

package/dist/src/ant/timeline.js

@@ -0,0 +1,1025 @@
+import { AntFormat } from "./format.js";
+import { FileNode, GraphEdge, GraphNode, XNode, LinkedInNode, } from "./graph.js";
+import { Ant } from "./index.js";
+export { GraphNode, StartNode, TextNode, WebsiteNode, FileNode, XNode, LinkedInNode, GraphEdge, } from "./graph.js";
+import { Room, connect as connectServer } from "../shared/server.js";
+import { connectRoom } from "../parrot/room.js";
+import { fromAccessCode } from "../drive.js";
+import * as Drive from "../drive.js";
+import IsoWebSocket from "isomorphic-ws";
+async function fileRef(authorization, file) {
+    let ready = file;
+    if (!ready.online) {
+        const dest = `tmp/${crypto.randomUUID()}-${ready.name}`;
+        const bytes = await ready.download();
+        ready = Drive.fromBytes(authorization, dest, ready.contentType, bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes));
+        await ready.upload();
+    }
+    const authz = ready.authorization;
+    if ("accessCode" in authz) {
+        return { type: "FILE", name: ready.name, contentType: ready.contentType, accessCode: authz.accessCode };
+    }
+    return {
+        type: "FILE",
+        name: ready.name,
+        contentType: ready.contentType,
+        path: authz.path,
+        ...(authz.group ? { group: authz.group } : {}),
+    };
+}
+/** Answer a persona's call to one of the caller's tools; one it doesn't have comes back declined. */
+function answerClientTool(ws, tools, call) {
+    const tool = tools.find((t) => t.function.name === call.name);
+    void Promise.resolve(tool ? tool.evaluate(call.args ?? {}) : JSON.stringify({ declined: true }))
+        .catch(() => JSON.stringify({ declined: true }))
+        .then((result) => {
+        try {
+            ws.send(JSON.stringify({ event: "tool_result", id: call.id, result: String(result) }));
+        }
+        catch { /* closed */ }
+    });
+}
+async function serializeMessages(authorization, messages) {
+    return Promise.all(messages.map(async (message) => ({
+        parts: await Promise.all(message.parts.map(async (part) => part.type === "FILE" ? await fileRef(authorization, part.file) : part)),
+        role: message.role,
+    })));
+}
+// ─── Catalog ─────────────────────────────────────────────────────────────────
+export async function listTimelines(authorization, opts) {
+    const response = await fetch(`${Ant.getURL()}/timelines`, {
+        method: "GET",
+        headers: {
+            Authorization: "email" in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`,
+            ...(opts?.group ? { Group: opts.group.id } : {}),
+        },
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+    return await response.json();
+}
+/** Create a timeline. `repository` (the owner's) is the computer its personas start from. */
+export async function createTimeline(authorization, name, opts) {
+    const response = await fetch(`${Ant.getURL()}/timelines`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: "email" in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`,
+            ...(opts?.group ? { Group: opts.group.id } : {}),
+        },
+        body: JSON.stringify({
+            name,
+            ...(opts?.audience?.length ? { audience: opts.audience } : {}),
+            ...(opts?.repository ? { repository: opts.repository.id } : {}),
+        }),
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+    return await response.json();
+}
+export async function deleteTimeline(authorization, id, opts) {
+    const response = await fetch(`${Ant.getURL()}/timeline`, {
+        method: "DELETE",
+        headers: {
+            Authorization: "email" in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`,
+            ...(opts?.group ? { Group: opts.group.id } : {}),
+            Timeline: id,
+        },
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+}
+export async function renameTimeline(authorization, id, name, opts) {
+    const response = await fetch(`${Ant.getURL()}/timeline/rename`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: "email" in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`,
+            ...(opts?.group ? { Group: opts.group.id } : {}),
+            Timeline: id,
+        },
+        body: JSON.stringify({ name }),
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+}
+export async function getTrust(authorization, timelineId, opts) {
+    const response = await fetch(`${Ant.getURL()}/timeline/trust`, {
+        method: "GET",
+        headers: {
+            Authorization: "email" in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`,
+            ...(opts?.accessCode
+                ? { "Access-Code": opts.accessCode }
+                : { Timeline: timelineId, ...(opts?.group ? { Group: opts.group.id } : {}) }),
+        },
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+    return await response.json();
+}
+export class Poll {
+    constructor(id, goal, query, results = null) {
+        Object.defineProperty(this, "id", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "goal", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "query", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "results", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.id = id;
+        this.goal = goal;
+        this.query = query;
+        this.results = results;
+    }
+    static fromJSON(json) {
+        const raw = json.query;
+        const formats = Array.isArray(raw)
+            ? raw.map((q) => (q && typeof q === "object" && "type" in q ? AntFormat.fromJSON(q) : q))
+            : raw && typeof raw === "object" && "type" in raw
+                ? [AntFormat.fromJSON(raw)]
+                : [];
+        return new Poll(json.id, json.goal ?? "", formats, json.results ?? null);
+    }
+    toJSON() {
+        return {
+            id: this.id,
+            goal: this.goal,
+            query: this.query.map((f) => f.toJSON()),
+            results: this.results,
+        };
+    }
+}
+export class Run {
+    constructor(wire) {
+        Object.defineProperty(this, "id", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "pollId", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "iteration", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "status", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "trajectories", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "polls", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "progress", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "agentIds", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "reach", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "startedAt", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "finishedAt", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "error", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.id = wire.id;
+        this.pollId = wire.pollId;
+        this.iteration = wire.iteration ?? 0;
+        this.status = normalizeRunStatus(wire.status);
+        this.trajectories = Array.isArray(wire.trajectories) ? wire.trajectories : [];
+        this.polls = wire.polls ?? undefined;
+        this.progress = wire.progress
+            ?? (wire.polls && typeof wire.polls === "object" ? wire.polls.progress : undefined)
+            ?? undefined;
+        this.agentIds = wire.agentIds ?? [];
+        this.reach = wire.reach && typeof wire.reach === "object" ? wire.reach : undefined;
+        this.startedAt = wire.startedAt ?? 0;
+        this.finishedAt = wire.finishedAt;
+        this.error = wire.error;
+    }
+}
+function normalizeRunStatus(raw) {
+    const value = String(raw ?? "").toUpperCase();
+    if (value === "QUEUED" || value === "RUNNING" || value === "DONE" || value === "ABORTED" || value === "FAILED") {
+        return value;
+    }
+    if (value === "PENDING" || value === "ABORTING")
+        return "RUNNING";
+    return "QUEUED";
+}
+export function runIsActive(status) {
+    const value = normalizeRunStatus(status);
+    return value === "QUEUED" || value === "RUNNING";
+}
+export class Agent {
+    constructor(parent, id, persona, repository = null) {
+        Object.defineProperty(this, "parent", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "id", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "persona", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** A repository picked in this agent's own chat, used directly; null when it follows the timeline's. */
+        Object.defineProperty(this, "repository", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.parent = parent;
+        this.id = id;
+        this.persona = persona;
+        this.repository = repository;
+    }
+    static fromJSON(json, parent) {
+        const repository = typeof json?.repository === "number" && json.repository > 0 ? json.repository : null;
+        return new Agent(parent, String(json.id), json.persona ?? {}, repository);
+    }
+    /** Pick a repository for this agent's chats (used directly), or null to follow the timeline's again. */
+    setRepository(repository) {
+        this.parent.post({ event: "set-agent-repository", agentId: this.id, repository: repository ? repository.id : null });
+    }
+    /** Lazily mint/open this agent's Parrot ChatRoom. */
+    async getChat(hooks) {
+        return this.parent.openChat(this.id, hooks);
+    }
+    async observe(content) {
+        const auth = this.parent.authorization;
+        return observeAgent(auth.authorization, this.parent.timelineId, this.id, content, "accessCode" in auth
+            ? { accessCode: auth.accessCode }
+            : auth.group
+                ? { group: { id: auth.group } }
+                : undefined);
+    }
+    /** Stream a reply as this agent, under the room's own authorization. `tools` answer the persona's calls to them. */
+    generate(messages, opts) {
+        const auth = this.parent.authorization;
+        return generateAgent(auth.authorization, this.parent.timelineId, this.id, messages, "accessCode" in auth
+            ? { accessCode: auth.accessCode, signal: opts?.signal, tools: opts?.tools }
+            : { ...(auth.group ? { group: { id: auth.group } } : {}), signal: opts?.signal, tools: opts?.tools });
+    }
+    toJSON() {
+        return { id: this.id, persona: this.persona };
+    }
+}
+// ─── Live room ───────────────────────────────────────────────────────────────
+export class TimelineRoom extends Room {
+    constructor(endpoint, ws, authorization, id) {
+        super(endpoint, ws, authorization, id);
+        /** Client-facing timeline id within the current principal. */
+        Object.defineProperty(this, "timelineId", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "name", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "agents", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "polls", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "runs", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "nodes", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "edges", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Short-lived Drive codes for file nodes (hydrate + upload + remint). */
+        Object.defineProperty(this, "fileAccessCodes", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "trustEdges", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "status", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Set when the timeline is deleted while this room is open. */
+        Object.defineProperty(this, "removed", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** The owner's Termite repository personas start from, by id; null when it has none. */
+        Object.defineProperty(this, "repository", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Who owns the timeline: `credentials:{id}` or `group:{id}`. */
+        Object.defineProperty(this, "owner", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "repositoryWatchers", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Set()
+        });
+        this.timelineId = id;
+        this.name = "";
+        this.repository = null;
+        this.owner = "";
+        this.agents = new Map();
+        this.polls = new Map();
+        this.runs = new Map();
+        this.nodes = new Map();
+        this.edges = new Map();
+        this.fileAccessCodes = new Map();
+        this.trustEdges = new Map();
+        this.status = "IDLE";
+        this.removed = false;
+    }
+    /** The group that owns the timeline, whose repositories it takes; undefined for a person's. */
+    get group() {
+        const match = /^group:(\d+)$/.exec(this.owner);
+        return match ? { id: match[1] } : undefined;
+    }
+    /** Attach one of the owner's repositories, or null to detach. Personas' chat forks of the old one are deleted. */
+    async setRepository(repository) {
+        this.post({ event: "set-repository", repository: repository ? repository.id : null });
+    }
+    /** Hear about every repository change, from anyone in the room. Returns a function that stops listening. */
+    watchRepository(listener) {
+        this.repositoryWatchers.add(listener);
+        return () => { this.repositoryWatchers.delete(listener); };
+    }
+    applyRepository(raw) {
+        const repository = typeof raw === "number" && raw > 0 ? raw : null;
+        if (repository === this.repository)
+            return;
+        this.repository = repository;
+        for (const listener of this.repositoryWatchers)
+            listener(repository);
+    }
+    /**
+     * The trust graph a run ended with: the timeline's graph as the run started,
+     * plus everything it changed. `trustEdges` is the graph every run starts from.
+     */
+    async runTrust(runId) {
+        const auth = this.authorization;
+        const response = await fetch(`${Ant.getURL()}/timeline/run?runId=${encodeURIComponent(runId)}`, {
+            method: "GET",
+            headers: {
+                Authorization: "email" in auth.authorization ? `Token ${auth.authorization.token}` : `ApiKey ${auth.authorization.id}`,
+                ...("accessCode" in auth
+                    ? { "Access-Code": auth.accessCode }
+                    : { Timeline: this.timelineId, ...(auth.group ? { Group: auth.group } : {}) }),
+            },
+        });
+        if (!response.ok)
+            throw new Error(await response.text());
+        const run = await response.json();
+        return (Array.isArray(run?.overlay) ? run.overlay : []).filter((e) => e?.from && e?.to && e.weight > 0);
+    }
+    hydrate(state) {
+        this.timelineId = state?.id ?? this.timelineId;
+        this.name = state?.name ?? this.name;
+        this.owner = typeof state?.owner === "string" ? state.owner : this.owner;
+        this.applyRepository(state?.repository);
+        this.status = state?.status ?? "IDLE";
+        this.agents.clear();
+        for (const a of state?.agents ?? []) {
+            this.agents.set(a.id, Agent.fromJSON(a, this));
+        }
+        this.polls.clear();
+        for (const p of state?.polls ?? []) {
+            this.polls.set(p.id, Poll.fromJSON(p));
+        }
+        this.runs.clear();
+        for (const r of state?.runs ?? []) {
+            this.runs.set(r.id, new Run(r));
+        }
+        this.nodes.clear();
+        for (const n of state?.graph?.nodes ?? []) {
+            if (n?.id)
+                this.nodes.set(n.id, GraphNode.fromJSON(n));
+        }
+        this.edges.clear();
+        for (const e of state?.graph?.edges ?? []) {
+            if (e?.id)
+                this.edges.set(e.id, GraphEdge.fromJSON(e));
+        }
+        this.fileAccessCodes.clear();
+        this.trustEdges.clear();
+        for (const e of state?.trustEdges ?? []) {
+            if (e?.from && e?.to && e.weight > 0) {
+                this.trustEdges.set(`${e.from}->${e.to}`, e);
+            }
+        }
+        const codes = state?.fileAccessCodes ?? {};
+        for (const [nodeId, meta] of Object.entries(codes)) {
+            const m = meta;
+            if (m?.code)
+                this.fileAccessCodes.set(nodeId, m);
+        }
+        for (const nodeId of this.fileAccessCodes.keys())
+            this.attachDriveFile(nodeId);
+    }
+    attachDriveFile(nodeId) {
+        const meta = this.fileAccessCodes.get(nodeId);
+        const node = this.nodes.get(nodeId);
+        if (!meta?.code || !node)
+            return;
+        const file = fromAccessCode(this.authorization.authorization, meta.code, {
+            name: meta.name,
+            contentType: meta.contentType,
+        });
+        if (node instanceof FileNode)
+            node.file = file;
+        if (node instanceof XNode || node instanceof LinkedInNode) {
+            if (node.media[0])
+                node.media[0] = file;
+            else
+                node.media = [file];
+        }
+    }
+    handleEvent(packet) {
+        switch (packet.event) {
+            case "upsert-agent": {
+                const a = packet.agent ?? packet.data?.agent ?? packet.data;
+                if (a?.id)
+                    this.agents.set(a.id, Agent.fromJSON(a, this));
+                break;
+            }
+            case "remove-agent": {
+                const id = packet.id ?? packet.data?.id;
+                if (id)
+                    this.agents.delete(id);
+                break;
+            }
+            case "upsert-poll": {
+                const p = packet.poll ?? packet.data?.poll ?? packet.data;
+                if (p?.id)
+                    this.polls.set(p.id, Poll.fromJSON(p));
+                break;
+            }
+            case "remove-poll": {
+                const id = packet.id ?? packet.data?.id;
+                if (id)
+                    this.polls.delete(id);
+                break;
+            }
+            case "upsert-run":
+            case "run-status": {
+                const r = packet.run ?? packet.data?.run ?? packet.data;
+                if (r?.id)
+                    this.runs.set(r.id, new Run(r));
+                break;
+            }
+            case "remove-run": {
+                const id = packet.id ?? packet.data?.id;
+                if (id)
+                    this.runs.delete(id);
+                break;
+            }
+            case "status": {
+                this.status = packet.status ?? packet.data?.status ?? this.status;
+                break;
+            }
+            case "update-timeline": {
+                const timeline = packet.timeline ?? packet.data?.timeline;
+                if (timeline?.name)
+                    this.name = timeline.name;
+                if (timeline && "repository" in timeline)
+                    this.applyRepository(timeline.repository);
+                break;
+            }
+            case "timeline-removed": {
+                this.removed = true;
+                break;
+            }
+            case "upsert-graph-node": {
+                const n = packet.node ?? packet.data?.node ?? packet.data;
+                const accessCode = (packet.accessCode ?? packet.data?.accessCode);
+                if (n?.id) {
+                    const prev = this.nodes.get(n.id);
+                    const incoming = GraphNode.fromJSON(n);
+                    if (prev instanceof FileNode && incoming instanceof FileNode) {
+                        incoming.file = incoming.file ?? prev.file;
+                        incoming.wirePath = incoming.wirePath || prev.wirePath;
+                    }
+                    if ((prev instanceof XNode || prev instanceof LinkedInNode)
+                        && (incoming instanceof XNode || incoming instanceof LinkedInNode)) {
+                        if (!incoming.media.length && prev.media.length)
+                            incoming.media = prev.media;
+                    }
+                    this.nodes.set(n.id, incoming);
+                }
+                if (accessCode?.code && n?.id) {
+                    this.fileAccessCodes.set(n.id, accessCode);
+                    this.attachDriveFile(n.id);
+                    break;
+                }
+                const node = n?.id ? this.nodes.get(n.id) : undefined;
+                const needsFile = node instanceof FileNode
+                    || ((node instanceof XNode || node instanceof LinkedInNode) && (node.wirePath || node.media[0]));
+                if (needsFile && node && !this.fileAccessCodes.has(node.id)) {
+                    return this.remintFileAccessCode(node.id).then(() => undefined);
+                }
+                break;
+            }
+            case "remove-graph-node": {
+                const id = packet.id ?? packet.data?.id;
+                if (id) {
+                    this.nodes.delete(id);
+                    this.fileAccessCodes.delete(id);
+                    for (const [eid, edge] of [...this.edges]) {
+                        if (edge.fromNodeId === id || edge.toNodeId === id)
+                            this.edges.delete(eid);
+                    }
+                }
+                break;
+            }
+            case "upsert-graph-edge": {
+                const e = packet.edge ?? packet.data?.edge ?? packet.data;
+                if (e?.id)
+                    this.edges.set(e.id, GraphEdge.fromJSON(e));
+                break;
+            }
+            case "remove-graph-edge": {
+                const id = packet.id ?? packet.data?.id;
+                if (id)
+                    this.edges.delete(id);
+                break;
+            }
+            case "upsert-trust-edge": {
+                const e = packet.edge ?? packet.data?.edge ?? packet.data;
+                if (e?.from && e?.to && e.weight > 0)
+                    this.trustEdges.set(`${e.from}->${e.to}`, e);
+                break;
+            }
+            case "remove-trust-edge": {
+                const from = packet.from ?? packet.data?.from;
+                const to = packet.to ?? packet.data?.to;
+                if (from && to)
+                    this.trustEdges.delete(`${from}->${to}`);
+                break;
+            }
+        }
+    }
+    upsertGraphNode(node) {
+        const prev = this.nodes.get(node.id);
+        const next = node instanceof GraphNode ? node.clone() : GraphNode.fromJSON(node);
+        if (prev instanceof FileNode && next instanceof FileNode) {
+            next.file = next.file ?? prev.file;
+            next.wirePath = next.wirePath || prev.wirePath;
+        }
+        this.nodes.set(next.id, next);
+        this.post({ event: "upsert-graph-node", node: next.toJSON() });
+        return next;
+    }
+    removeGraphNode(id) {
+        if (id === "start")
+            return;
+        this.nodes.delete(id);
+        this.fileAccessCodes.delete(id);
+        for (const [eid, edge] of [...this.edges]) {
+            if (edge.fromNodeId === id || edge.toNodeId === id)
+                this.edges.delete(eid);
+        }
+        this.post({ event: "remove-graph-node", id });
+    }
+    upsertGraphEdge(edge) {
+        const next = edge instanceof GraphEdge ? edge : GraphEdge.fromJSON(edge);
+        this.edges.set(next.id, next);
+        this.post({ event: "upsert-graph-edge", edge: next.toJSON() });
+        return next;
+    }
+    removeGraphEdge(id) {
+        this.edges.delete(id);
+        this.post({ event: "remove-graph-edge", id });
+    }
+    /** Upload bytes to the host drive and create/update a durable file node. */
+    async uploadFileNode(file, opts) {
+        const contentType = opts.contentType || "application/octet-stream";
+        const body = file instanceof Blob
+            ? file
+            : file instanceof ArrayBuffer
+                ? new Uint8Array(file)
+                : file;
+        const auth = this.authorization;
+        const response = await fetch(`${Ant.getURL()}/timeline/graph/file`, {
+            method: "POST",
+            headers: {
+                Authorization: "email" in auth.authorization ? `Token ${auth.authorization.token}` : `ApiKey ${auth.authorization.id}`,
+                ...("accessCode" in auth
+                    ? { "Access-Code": auth.accessCode }
+                    : { Timeline: this.timelineId, ...(auth.group ? { Group: auth.group } : {}) }),
+                "Content-Type": contentType,
+                Filename: opts.name,
+                X: String(opts.x),
+                Y: String(opts.y),
+                ...(opts.nodeId ? { "Node-Id": opts.nodeId } : {}),
+                ...(opts.kind ? { Kind: opts.kind } : {}),
+            },
+            body: body,
+        });
+        if (!response.ok)
+            throw new Error(await response.text());
+        const json = await response.json();
+        const fileHandle = fromAccessCode(this.authorization.authorization, json.accessCode.code, {
+            name: json.accessCode.name,
+            contentType: json.accessCode.contentType,
+        });
+        const node = GraphNode.fromJSON(json.node, fileHandle);
+        this.nodes.set(node.id, node);
+        this.fileAccessCodes.set(node.id, json.accessCode);
+        return { node, accessCode: json.accessCode };
+    }
+    async remintFileAccessCode(nodeId) {
+        const auth = this.authorization;
+        const response = await fetch(`${Ant.getURL()}/timeline/graph/file/access-code`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: "email" in auth.authorization ? `Token ${auth.authorization.token}` : `ApiKey ${auth.authorization.id}`,
+                ...("accessCode" in auth
+                    ? { "Access-Code": auth.accessCode }
+                    : { Timeline: this.timelineId, ...(auth.group ? { Group: auth.group } : {}) }),
+            },
+            body: JSON.stringify({ nodeId }),
+        });
+        if (!response.ok)
+            throw new Error(await response.text());
+        const meta = await response.json();
+        this.fileAccessCodes.set(nodeId, meta);
+        this.attachDriveFile(nodeId);
+        return meta;
+    }
+    /** Build a Drive.File handle for a graph file node (remints if needed). */
+    async fileForNode(nodeId) {
+        let meta = this.fileAccessCodes.get(nodeId);
+        if (!meta?.code)
+            meta = await this.remintFileAccessCode(nodeId);
+        return fromAccessCode(this.authorization.authorization, meta.code, {
+            name: meta.name,
+            contentType: meta.contentType,
+        });
+    }
+    /** Remint if needed and return the short-lived Drive access code for a file node.
+     *  Viewer URL opening stays in the app layer (avoids importing Fauna into ant/). */
+    async openGraphFile(nodeId) {
+        let meta = this.fileAccessCodes.get(nodeId);
+        if (!meta?.code)
+            meta = await this.remintFileAccessCode(nodeId);
+        return meta;
+    }
+    upsertAgent(identity) {
+        const preferred = String(identity?.id ?? "").trim();
+        let id = preferred && !this.agents.has(preferred) ? preferred : "";
+        if (!id) {
+            let n = 0;
+            while (this.agents.has(String(n)))
+                n++;
+            id = String(n);
+        }
+        const agent = new Agent(this, id, identity);
+        this.agents.set(agent.id, agent);
+        this.post({ event: "upsert-agent", agent: agent.toJSON() });
+        return agent;
+    }
+    removeAgent(id) {
+        this.agents.delete(id);
+        this.post({ event: "remove-agent", id });
+    }
+    upsertPoll(goal, query) {
+        let id = 0;
+        while (this.polls.has(String(id)))
+            id++;
+        const poll = new Poll(String(id), goal, query);
+        this.polls.set(poll.id, poll);
+        this.post({ event: "upsert-poll", poll: poll.toJSON() });
+        return poll;
+    }
+    removePoll(id) {
+        this.polls.delete(id);
+        this.post({ event: "remove-poll", id });
+    }
+    /** Create the poll and queue its run in one request. Resolves the run id;
+     *  the run itself arrives through the room's `upsert-run` delta. */
+    async startRun(goal, query) {
+        const auth = this.authorization;
+        const response = await fetch(`${Ant.getURL()}/timeline/run`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: "email" in auth.authorization ? `Token ${auth.authorization.token}` : `ApiKey ${auth.authorization.id}`,
+                ...("accessCode" in auth
+                    ? { "Access-Code": auth.accessCode }
+                    : { Timeline: this.timelineId, ...(auth.group ? { Group: auth.group } : {}) }),
+            },
+            body: JSON.stringify({ goal, query: query.map((f) => f.toJSON()) }),
+        });
+        if (!response.ok)
+            throw new Error(await response.text());
+        const { runId } = await response.json();
+        return runId;
+    }
+    async abortRun(runId) {
+        const auth = this.authorization;
+        const response = await fetch(`${Ant.getURL()}/timeline/run/abort`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: "email" in auth.authorization ? `Token ${auth.authorization.token}` : `ApiKey ${auth.authorization.id}`,
+                ...("accessCode" in auth
+                    ? { "Access-Code": auth.accessCode }
+                    : { Timeline: this.timelineId, ...(auth.group ? { Group: auth.group } : {}) }),
+            },
+            body: JSON.stringify({ runId }),
+        });
+        if (!response.ok)
+            throw new Error(await response.text());
+    }
+    /** Lazily mint/open the architect Parrot ChatRoom. */
+    async getChat(hooks) {
+        return this.openChat("", hooks);
+    }
+    /**
+     * Ensure a Parrot chat (architect when `agentId` is empty) and connect live.
+     * Timeline members join by reference (non-guest); access-code guests use the
+     * short-lived code so leave/reap semantics stay correct.
+     */
+    async openChat(agentId, hooks) {
+        const auth = this.authorization;
+        const response = await fetch(`${Ant.getURL()}/timeline/chat/ensure`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: "email" in auth.authorization ? `Token ${auth.authorization.token}` : `ApiKey ${auth.authorization.id}`,
+                ...("accessCode" in auth
+                    ? { "Access-Code": auth.accessCode }
+                    : { Timeline: this.timelineId, ...(auth.group ? { Group: auth.group } : {}) }),
+            },
+            body: JSON.stringify({ agentId: agentId || "" }),
+        });
+        if (!response.ok)
+            throw new Error(await response.text());
+        const { chatId, reference, code } = await response.json();
+        if (!chatId || !code)
+            throw new Error("Invalid ensure response.");
+        const guest = "accessCode" in this.authorization;
+        const target = guest
+            ? { code }
+            : { reference: reference || `parrot:chat:${chatId}` };
+        const { room, self } = await connectRoom(this.authorization.authorization, target, hooks ?? {});
+        return { room, self, chatId };
+    }
+    /**
+     * Connect to an owned timeline.
+     * Principal is resolved server-side from auth (+ optional Group).
+     * `Server` carries only the timeline id for own/group; grant joins may
+     * pass a full `principalId:timelineId` via opts.server when needed.
+     */
+    static async connect(authorization, target, opts) {
+        const server = opts?.server ?? target.id;
+        let room;
+        const user = opts?.hooks ?? {};
+        const self = await connectServer({ authorization, server, ...(opts?.group ? { group: opts.group.id } : {}) }, `${Ant.getURL()}/timeline`, {
+            ...user,
+            createRoom: (endpoint, ws, a, id, state) => {
+                room = (user.createRoom?.(endpoint, ws, a, id, state)
+                    ?? new TimelineRoom(endpoint, ws, a, id));
+                return room;
+            },
+            onConnection: (r, state) => {
+                r.hydrate(state);
+                user.onConnection?.(r, state);
+            },
+            onEvent: (r, packet) => applyTimelineEvent(r, packet, user),
+        });
+        return { room, self };
+    }
+    static async join(authorization, target, hooks) {
+        let room;
+        const user = hooks ?? {};
+        const self = await connectServer({ authorization, accessCode: target.accessCode }, `${Ant.getURL()}/timeline`, {
+            ...user,
+            createRoom: (endpoint, ws, a, id, state) => {
+                room = (user.createRoom?.(endpoint, ws, a, id, state)
+                    ?? new TimelineRoom(endpoint, ws, a, id));
+                return room;
+            },
+            onConnection: (r, state) => {
+                r.hydrate(state);
+                user.onConnection?.(r, state);
+            },
+            onEvent: (r, packet) => applyTimelineEvent(r, packet, user),
+        });
+        return { room, self };
+    }
+}
+/** Apply a domain frame; if handleEvent remints a file code, notify again after. */
+function applyTimelineEvent(room, packet, user) {
+    const handled = room.handleEvent(packet);
+    const notify = () => user.onEvent?.(room, packet) ?? true;
+    if (handled && typeof handled.then === "function") {
+        notify();
+        void handled.then(notify);
+        return true;
+    }
+    return notify();
+}
+/** Write a standalone fact onto this agent's Parrot graph (`ant/timelines/…/memory`). */
+export async function observeAgent(authorization, timelineId, agentId, content, opts) {
+    const response = await fetch(`${Ant.getURL()}/timeline/agent/observe`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: "email" in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`,
+            ...(opts?.accessCode
+                ? { "Access-Code": opts.accessCode }
+                : { Timeline: timelineId, ...(opts?.group ? { Group: opts.group.id } : {}) }),
+        },
+        body: JSON.stringify({ agentId, content }),
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+    return await response.json();
+}
+/**
+ * Stream a persona reply for one agent (Gemini Flash + medium thinking + memories).
+ * Parrot-compatible StreamEvents for UI.Chat generate mode, plus `tool` and
+ * `tool-result` events for the persona's own tools. `tools` are answered here
+ * when the persona calls them, like `use_desktop` asking for a computer.
+ */
+export async function* generateAgent(authorization, timelineId, agentId, messages, opts) {
+    const wsURL = Ant.getURL().replace("https://", "wss://").replace("http://", "ws://");
+    const authHeaders = {
+        Authorization: "email" in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`,
+        ...(opts?.accessCode
+            ? { "Access-Code": opts.accessCode }
+            : { Timeline: timelineId, ...(opts?.group ? { Group: opts.group.id } : {}) }),
+    };
+    const ws = new IsoWebSocket(`${wsURL}/timeline/agent/generate?authorization=${encodeURIComponent(JSON.stringify(authHeaders))}`);
+    const onAbort = () => { try {
+        ws.close();
+    }
+    catch { /* noop */ } };
+    if (opts?.signal) {
+        if (opts.signal.aborted)
+            onAbort();
+        else
+            opts.signal.addEventListener("abort", onAbort);
+    }
+    try {
+        await new Promise((resolve, reject) => {
+            ws.onopen = () => resolve();
+            ws.onerror = () => reject(new Error("WebSocket connection failed"));
+        });
+        if (opts?.signal?.aborted)
+            return;
+        const serializedMessages = await serializeMessages(authorization, messages);
+        const clientTools = opts?.tools ?? [];
+        ws.send(JSON.stringify({ event: "generate", agentId, messages: serializedMessages, tools: clientTools.map((t) => t.function) }));
+        ws.send(JSON.stringify({ event: "start" }));
+        const eventQueue = [];
+        let resolveNext;
+        let done = false;
+        ws.onmessage = (msg) => {
+            try {
+                const event = JSON.parse(String(msg.data));
+                if (event?.event === "tool_call") {
+                    answerClientTool(ws, clientTools, event);
+                    return;
+                }
+                eventQueue.push(event);
+                resolveNext?.();
+            }
+            catch { /* ignore */ }
+        };
+        ws.onclose = () => { done = true; resolveNext?.(); };
+        ws.onerror = () => { done = true; resolveNext?.(); };
+        while (true) {
+            if (eventQueue.length > 0) {
+                const event = eventQueue.shift();
+                yield event;
+                if (event.event === "done" || event.event === "error")
+                    break;
+            }
+            else if (done) {
+                break;
+            }
+            else {
+                await new Promise((resolve) => { resolveNext = resolve; });
+            }
+        }
+    }
+    finally {
+        opts?.signal?.removeEventListener("abort", onAbort);
+        try {
+            ws.close();
+        }
+        catch { /* noop */ }
+    }
+}