fauna-api 0.0.0-stage → 1.0.676

package/dist/src/ant/chat.js

@@ -0,0 +1,467 @@
+import { Ant } from "./index.js";
+import { Room, connect as connectServer } from "../shared/server.js";
+import { connectRoom } from "../parrot/room.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 } : {}),
+    };
+}
+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,
+    })));
+}
+/** 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 */ }
+    });
+}
+export async function listChats(authorization, opts) {
+    const response = await fetch(`${Ant.getURL()}/chats`, {
+        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());
+    const rows = await response.json();
+    return (Array.isArray(rows) ? rows : []).map((row) => ({
+        ...row,
+        last: row.last ? { ...row.last, createdAt: new Date(row.last.createdAt) } : null,
+    }));
+}
+/** Create a chat. `repository` (the owner's) is the computer its personas start from. */
+export async function createChat(authorization, name, opts) {
+    const response = await fetch(`${Ant.getURL()}/chats`, {
+        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 deleteChat(authorization, id, opts) {
+    const response = await fetch(`${Ant.getURL()}/chat`, {
+        method: "DELETE",
+        headers: {
+            Authorization: "email" in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`,
+            ...(opts?.group ? { Group: opts.group.id } : {}),
+            Chat: id,
+        },
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+}
+export async function moveChatToGroup(authorization, id, groupId) {
+    const response = await fetch(`${Ant.getURL()}/chat/move`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: "email" in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`,
+            Chat: id,
+        },
+        body: JSON.stringify({ groupId }),
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+    return await response.json();
+}
+export async function renameChat(authorization, id, name, opts) {
+    const response = await fetch(`${Ant.getURL()}/chat/rename`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: "email" in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`,
+            ...(opts?.group ? { Group: opts.group.id } : {}),
+            Chat: id,
+        },
+        body: JSON.stringify({ name }),
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+}
+// ─── Domain ──────────────────────────────────────────────────────────────────
+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 for this agent, used directly; null when it follows the chat'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;
+    }
+    /** Pick a repository for this agent (used directly), or null to follow the chat's again. */
+    setRepository(repository) {
+        this.parent.post({ event: "set-agent-repository", agentId: this.id, repository: repository ? repository.id : null });
+    }
+    async observe(content) {
+        const auth = this.parent.authorization;
+        return observeAgent(auth.authorization, this.parent.chatId, 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.chatId, 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 };
+    }
+    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);
+    }
+}
+export class AntChatRoom extends Room {
+    constructor(endpoint, ws, authorization, id) {
+        super(endpoint, ws, authorization, id);
+        Object.defineProperty(this, "chatId", {
+            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
+        });
+        /** 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 chat: `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.chatId = id;
+        this.name = "";
+        this.agents = new Map();
+        this.repository = null;
+        this.owner = "";
+    }
+    /** The group that owns the chat, 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' 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);
+    }
+    hydrate(state) {
+        this.chatId = state?.id ?? this.chatId;
+        if (typeof state?.name === "string")
+            this.name = state.name;
+        if (typeof state?.owner === "string")
+            this.owner = state.owner;
+        this.applyRepository(state?.repository);
+        this.agents.clear();
+        for (const a of state?.agents ?? []) {
+            const agent = Agent.fromJSON(a, this);
+            this.agents.set(agent.id, agent);
+        }
+    }
+    handleEvent(packet) {
+        switch (packet?.event) {
+            case "upsert-agent": {
+                const agent = Agent.fromJSON(packet.data?.agent ?? packet.agent, this);
+                this.agents.set(agent.id, agent);
+                return true;
+            }
+            case "remove-agent": {
+                const id = String(packet.data?.id ?? packet.id ?? "");
+                if (id)
+                    this.agents.delete(id);
+                return true;
+            }
+            case "update-chat": {
+                const chat = packet.data?.chat ?? packet.chat;
+                if (typeof chat?.name === "string")
+                    this.name = chat.name;
+                if (chat && "repository" in chat)
+                    this.applyRepository(chat.repository);
+                return true;
+            }
+            default:
+                return false;
+        }
+    }
+    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 });
+    }
+    /** Lazily mint/open the architect Parrot ChatRoom. */
+    async getChat(hooks) {
+        const auth = this.authorization;
+        const response = await fetch(`${Ant.getURL()}/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 }
+                    : { Chat: this.chatId, ...(auth.group ? { Group: auth.group } : {}) }),
+            },
+            body: JSON.stringify({}),
+        });
+        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 };
+    }
+    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()}/chat`, {
+            ...user,
+            createRoom: (endpoint, ws, a, id, state) => {
+                room = (user.createRoom?.(endpoint, ws, a, id, state)
+                    ?? new AntChatRoom(endpoint, ws, a, id));
+                return room;
+            },
+            onConnection: (r, state) => {
+                r.hydrate(state);
+                user.onConnection?.(r, state);
+            },
+            onEvent: (r, packet) => {
+                const handled = r.handleEvent(packet);
+                return user.onEvent?.(r, packet) ?? Boolean(handled);
+            },
+        });
+        return { room, self };
+    }
+    static async join(authorization, target, hooks) {
+        let room;
+        const user = hooks ?? {};
+        const self = await connectServer({ authorization, accessCode: target.accessCode }, `${Ant.getURL()}/chat`, {
+            ...user,
+            createRoom: (endpoint, ws, a, id, state) => {
+                room = (user.createRoom?.(endpoint, ws, a, id, state)
+                    ?? new AntChatRoom(endpoint, ws, a, id));
+                return room;
+            },
+            onConnection: (r, state) => {
+                r.hydrate(state);
+                user.onConnection?.(r, state);
+            },
+            onEvent: (r, packet) => {
+                const handled = r.handleEvent(packet);
+                return user.onEvent?.(r, packet) ?? Boolean(handled);
+            },
+        });
+        return { room, self };
+    }
+}
+/** Write a standalone fact onto this agent's Parrot graph (`ant/chats/…/memory`). */
+export async function observeAgent(authorization, chatId, agentId, content, opts) {
+    const response = await fetch(`${Ant.getURL()}/chat/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 }
+                : { Chat: chatId, ...(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 chat agent (memories under ant/chats/…), with
+ * `tool` and `tool-result` events for its own tools. `tools` are answered here
+ * when the persona calls them, like `use_desktop` asking for a computer.
+ */
+export async function* generateAgent(authorization, chatId, 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 }
+            : { Chat: chatId, ...(opts?.group ? { Group: opts.group.id } : {}) }),
+    };
+    const ws = new IsoWebSocket(`${wsURL}/chat/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 */ }
+    }
+}
+// Alias for plan naming.
+export { AntChatRoom as ChatRoom };

package/dist/src/ant/format.d.ts

@@ -0,0 +1,40 @@
+import { CategoricalFormat, Format } from "../parrot/format.js";
+import type { Stimuli } from "./graph.js";
+export declare const X_ACTIONS: readonly ["Did not dwell", "Dwell", "Like", "Reply", "Repost", "Quote", "Photo expand", "Video open", "Video quality view", "Click", "Open link", "Quoted click", "Quoted video view", "Profile", "Follow", "Share", "Share via DM", "Copy link", "Not interested", "Mute", "Block", "Report"];
+/** Phoenix default weights (param.rs). Copy link is the tile max. */
+export declare const X_WEIGHTS: Record<string, number>;
+export declare const LINKEDIN_ACTIONS: readonly ["Skip", "Click", "Long dwell", "Like", "Comment", "Share"];
+/** Not official. Feed SR does not publish numbers. Share is the tile max. */
+export declare const LINKEDIN_WEIGHTS: Record<string, number>;
+export declare abstract class AntFormat extends CategoricalFormat {
+    abstract readonly weights: Record<string, number>;
+    maxWeight(): number;
+    /** Phoenix style: Σ w_a * (count_a / n). Signed. Empty bucket is NaN. */
+    score(counts: Record<string, number>): number;
+    static fromJSON(json: any): Format<any>;
+    static forKind(kind: Stimuli): AntFormat[];
+}
+export declare class XFormat extends AntFormat {
+    readonly weights: Record<string, number>;
+    constructor();
+    clone(): XFormat;
+    toJSON(): {
+        type: string;
+        weights: Record<string, number>;
+        instruction: string;
+        categories: string[];
+        answer: string | undefined;
+    };
+}
+export declare class LinkedInFormat extends AntFormat {
+    readonly weights: Record<string, number>;
+    constructor();
+    clone(): LinkedInFormat;
+    toJSON(): {
+        type: string;
+        weights: Record<string, number>;
+        instruction: string;
+        categories: string[];
+        answer: string | undefined;
+    };
+}

package/dist/src/ant/format.js

@@ -0,0 +1,143 @@
+import { CategoricalFormat, Format } from "../parrot/format.js";
+// Phoenix discrete heads from home-mixer/params/param.rs (product words).
+// Field names in comments. Skip post_unexplored and continuous dwell seconds.
+const X_INSTRUCTION = "You are a viewer on X For You. Phoenix predicts the probability of each action below. Pick the one action you would take. Favorite is Like. Copy link, reply, quote, and share via DM are the strong positive heads. Report, mute, block, and not interested are the negative heads. Did not dwell means you skip the card.";
+export const X_ACTIONS = [
+    "Did not dwell",
+    "Dwell",
+    "Like",
+    "Reply",
+    "Repost",
+    "Quote",
+    "Photo expand",
+    "Video open",
+    "Video quality view",
+    "Click",
+    "Open link",
+    "Quoted click",
+    "Quoted video view",
+    "Profile",
+    "Follow",
+    "Share",
+    "Share via DM",
+    "Copy link",
+    "Not interested",
+    "Mute",
+    "Block",
+    "Report",
+];
+/** Phoenix default weights (param.rs). Copy link is the tile max. */
+export const X_WEIGHTS = {
+    "Did not dwell": -0.02, // not_dwelled
+    "Dwell": 0.05, // dwell
+    "Like": 0.5, // favorite
+    "Reply": 5, // reply
+    "Repost": 1, // retweet
+    "Quote": 5, // quote
+    "Photo expand": 0.05, // photo_expand
+    "Video open": 0.07, // video_open
+    "Video quality view": 0, // vqv
+    "Click": 0.4, // click
+    "Open link": 0.2, // open_link
+    "Quoted click": 0.05, // quoted_click
+    "Quoted video view": 0, // quoted_vqv
+    "Profile": 0, // profile_click
+    "Follow": 4, // follow_author
+    "Share": 2, // share
+    "Share via DM": 5, // share_via_dm
+    "Copy link": 20, // share_via_copy_link
+    "Not interested": -43.2, // not_interested
+    "Mute": -58.8, // mute_author
+    "Block": -31.2, // block_author
+    "Report": -234, // report
+};
+const LINKEDIN_INSTRUCTION = "You are a member in the LinkedIn feed. Feed SR predicts skip, click, and long dwell on one tower and like, comment, and share on the other. Those scores are blended to rank the post. Pick the one action you would take. Long dwell means you stay past the type threshold. Skip means you scroll past. Weights below are ours, not LinkedIn production numbers.";
+export const LINKEDIN_ACTIONS = [
+    "Skip",
+    "Click",
+    "Long dwell",
+    "Like",
+    "Comment",
+    "Share",
+];
+/** Not official. Feed SR does not publish numbers. Share is the tile max. */
+export const LINKEDIN_WEIGHTS = {
+    "Skip": 0,
+    "Click": 1,
+    "Like": 1,
+    "Long dwell": 2,
+    "Comment": 2,
+    "Share": 3,
+};
+export class AntFormat extends CategoricalFormat {
+    maxWeight() {
+        return Math.max(0, ...Object.values(this.weights));
+    }
+    /** Phoenix style: Σ w_a * (count_a / n). Signed. Empty bucket is NaN. */
+    score(counts) {
+        let n = 0;
+        let sum = 0;
+        for (const [label, w] of Object.entries(this.weights)) {
+            const c = counts[label] ?? 0;
+            n += c;
+            sum += w * c;
+        }
+        return n === 0 ? Number.NaN : sum / n;
+    }
+    static fromJSON(json) {
+        if (json?.type === "x") {
+            const format = new XFormat();
+            if (json.answer != null)
+                format.answer(json.answer);
+            return format;
+        }
+        if (json?.type === "linkedin") {
+            const format = new LinkedInFormat();
+            if (json.answer != null)
+                format.answer(json.answer);
+            return format;
+        }
+        return Format.fromJSON(json);
+    }
+    static forKind(kind) {
+        if (kind === "x")
+            return [new XFormat()];
+        if (kind === "linkedin")
+            return [new LinkedInFormat()];
+        return [];
+    }
+}
+export class XFormat extends AntFormat {
+    constructor() {
+        super(X_INSTRUCTION, [...X_ACTIONS]);
+        Object.defineProperty(this, "weights", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: X_WEIGHTS
+        });
+    }
+    clone() {
+        return new XFormat();
+    }
+    toJSON() {
+        return { ...super.toJSON(), type: "x", weights: this.weights };
+    }
+}
+export class LinkedInFormat extends AntFormat {
+    constructor() {
+        super(LINKEDIN_INSTRUCTION, [...LINKEDIN_ACTIONS]);
+        Object.defineProperty(this, "weights", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: LINKEDIN_WEIGHTS
+        });
+    }
+    clone() {
+        return new LinkedInFormat();
+    }
+    toJSON() {
+        return { ...super.toJSON(), type: "linkedin", weights: this.weights };
+    }
+}