@fungi.computer/oyster 0.4.0 → 0.5.0

package/dist/channels/conversations.d.ts

@@ -0,0 +1,235 @@
+import { z } from "zod";
+import { type FungiAuthor, type AuthorMeta, type MessageMetaValue } from "@fungi.computer/agar/agents";
+import { type Handoff } from "@fungi.computer/agar/channels";
+import { type ConversationBinding, type ChannelParty } from "./binding.js";
+export type HandoffEvent = Readonly<{
+    expectedVersion: number;
+}> & (Readonly<{
+    kind: "request";
+    reason: string;
+    at: number;
+}> | Readonly<{
+    kind: "take_over";
+    member: FungiAuthor;
+    confirm: boolean;
+    at: number;
+}> | Readonly<{
+    kind: "hand_back";
+    memberId: string;
+    confirm: boolean;
+}> | Readonly<{
+    kind: "dismiss";
+}>);
+export type HandoffTransition = Readonly<{
+    kind: "ok";
+    handoff: Handoff;
+}> | Readonly<{
+    kind: "conflict" | "confirmation_required" | "not_holder" | "not_found";
+}>;
+/** Decide one handoff; persistence, notifications and cancellation stay with the owner. */
+export declare function transitionHandoff(current: Handoff | null, event: HandoffEvent): HandoffTransition;
+export type ConversationSql = Readonly<{
+    exec: (statement: string, ...bindings: (ArrayBuffer | string | number | null)[]) => Readonly<{
+        toArray: () => readonly unknown[];
+    }>;
+}>;
+/** One verified inbound event from a provider edge. */
+declare const inboundEventSchema: z.ZodObject<{
+    bindingId: z.ZodString;
+    conversation: z.ZodString;
+    eventId: z.ZodString;
+    party: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"visitor">;
+        visitorId: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"discord-user">;
+        guildId: z.ZodString;
+        userId: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"email-sender">;
+        address: z.ZodEmail;
+        dmarc: z.ZodEnum<{
+            none: "none";
+            pass: "pass";
+            fail: "fail";
+        }>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"player">;
+        worldId: z.ZodString;
+        playerId: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"source">;
+        source: z.ZodString;
+    }, z.core.$strict>], "kind">;
+    text: z.ZodString;
+    sourceRequestId: z.ZodOptional<z.ZodLazy<z.ZodString>>;
+    bodyDigest: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** One verified inbound event. */
+export type InboundEvent = z.infer<typeof inboundEventSchema>;
+/** Channel events and composer requests do not share the Session owner's key space. */
+export declare function channelRequestId(bindingId: string, eventId: string): string;
+/** Closed intake result; "said no" is distinct from "couldn't answer". */
+export type IntakeResult = Readonly<{
+    kind: "accepted";
+    sessionId: string;
+    commandId: string;
+    delivery: "new" | "replay";
+}> | Readonly<{
+    /** Held for a person: recorded as a party line, no run started. */
+    kind: "held";
+    sessionId: string;
+    delivery: "new" | "replay";
+}> | Readonly<{
+    kind: "denied";
+    reason: "unmapped" | "suspended" | "banned" | "too_long" | "party_daily_limit" | "new_party_limit" | "rate_limited" | "event_conflict";
+}>;
+/** One channel conversation row, as owner surfaces label it. */
+export type ChannelConversation = Readonly<{
+    bindingId: string;
+    conversation: string;
+    sessionId: string;
+    party: ChannelParty;
+    label: string;
+    createdAt: number;
+    lastEventAt: number;
+    handoff: Handoff;
+}>;
+export type ChannelHandoffResult = Readonly<{
+    kind: "ok";
+    conversation: ChannelConversation;
+}> | Exclude<HandoffTransition, {
+    kind: "ok";
+}>;
+type ChannelTakeoverReceipt = Readonly<{
+    version: number;
+    memberId: string;
+    memberName: string;
+    previousMemberId: string | null;
+    at: number;
+}>;
+/** Payload-free event metadata for a Team member's channel log. */
+export type ChannelEventReceipt = Readonly<{
+    eventId: string;
+    receivedAt: number;
+    status: "pending" | "accepted" | "held";
+    size: number;
+    sessionId: string;
+}>;
+/** Only the withdrawal outcomes a channel visitor can observe. */
+export type ChannelWithdrawResult = Readonly<{
+    status: "unknown";
+}> | Readonly<{
+    status: "accepted";
+    commandId: string;
+    sessionId?: string;
+}>;
+/** Only the pending fields a channel visitor can read. */
+export type ChannelPendingPrompt = Readonly<{
+    requestId: string;
+    commandId: string;
+    text: string;
+    meta?: MessageMetaValue | undefined;
+    delivery: "steer" | "followUp";
+    images?: readonly Readonly<{
+        type: "image";
+        data: string;
+        mimeType: string;
+    }>[] | undefined;
+}>;
+/** The channel's narrow Session port; hosts translate to their durable client. */
+export type SessionDoor = Readonly<{
+    withdraw: (sessionId: string, requestId: string) => Promise<ChannelWithdrawResult>;
+    latestPending: (sessionId: string, visitor: FungiAuthor) => Promise<ChannelPendingPrompt | null>;
+    createSession: (requestId: string) => Promise<string>;
+    /** Deliver this conversation Session's tool grants to the runtime. */
+    deliverGrants: (sessionId: string) => void;
+    prompt: (sessionId: string, input: Readonly<{
+        requestId: string;
+        text: string;
+        meta: AuthorMeta & Readonly<{
+            sourceRequestId?: string;
+        }>;
+    }>) => Promise<Readonly<{
+        commandId: string;
+    }>>;
+    /** Record one run-free operator or party line (Shiitake `operator`). */
+    line: (sessionId: string, input: Readonly<{
+        requestId: string;
+        text: string;
+    }> & (Readonly<{
+        author: "operator";
+        identity: FungiAuthor;
+    }> | Readonly<{
+        author: "party";
+        meta: AuthorMeta & Readonly<{
+            sourceRequestId?: string;
+        }>;
+    }>)) => Promise<void>;
+    /** Only a matching, contract-closed request clears a visitor reservation. */
+    errorKind: (error: Error, requestId: string) => "closed_request" | null;
+}>;
+export declare function createChannelConversations(options: Readonly<{
+    sql: ConversationSql;
+    transactionSync: <T>(body: () => T) => T;
+    binding: (bindingId: string) => ConversationBinding | null;
+    door: Pick<SessionDoor, "createSession" | "deliverGrants" | "prompt" | "line" | "errorKind">;
+    now: () => number;
+    /** Commit hook for accepted work, in the acceptance transaction. */
+    onAccepted?: (accepted: Readonly<{
+        binding: ConversationBinding;
+        event: InboundEvent;
+        sessionId: string;
+        commandId: string;
+    }>) => void;
+}>): {
+    ensure: () => void;
+    open: (binding: ConversationBinding, conversation: string, party: ChannelParty) => Promise<Readonly<{
+        kind: "open";
+        conversation: ChannelConversation;
+    }> | Readonly<{
+        kind: "denied";
+        reason: "new_party_limit" | "banned";
+    }>>;
+    receive: (rawEvent: InboundEvent) => Promise<IntakeResult>;
+    /** A visitor bearer may never resolve another conversation's intake key. */
+    visitorEventConflict: (bindingId: string, visitorId: string, eventId: string) => boolean;
+    ban: (bindingId: string, conversation: string) => void;
+    list: (bindingId?: string) => readonly ChannelConversation[];
+    recentEvents: (bindingId: string) => readonly ChannelEventReceipt[];
+    requestHandoff: (sessionId: string, reason: string) => ChannelHandoffResult;
+    captureTurn: (sessionId: string, commandId: string) => void;
+    turnIsCurrent: (sessionId: string, commandId: string) => boolean;
+    deliverAgentReply: (sessionId: string, commandId: string, reply: Readonly<{
+        kind: "message";
+        messageId: string;
+    }> | Readonly<{
+        kind: "settlement";
+    }>) => boolean;
+    dueNotifications: (now: number) => readonly ChannelConversation[];
+    nextNotification: () => number | null;
+    scheduleNotification: (sessionId: string, dueAt: number | null) => void;
+    handoffOpen: (sessionId: string, version: number) => boolean;
+    takeOver: (sessionId: string, member: FungiAuthor, expectedVersion: number, confirm: boolean) => ChannelHandoffResult;
+    handBack: (sessionId: string, memberId: string, expectedVersion: number, confirm: boolean) => ChannelHandoffResult;
+    dismiss: (sessionId: string, expectedVersion: number) => ChannelHandoffResult;
+    takeovers: (sessionId: string) => readonly ChannelTakeoverReceipt[];
+    expired: (now: number, retentionMs: (bindingId: string) => number) => readonly ChannelConversation[];
+    nextExpiry: (retentionMs: (bindingId: string) => number) => number | null;
+    forget: (conversation: ChannelConversation) => void;
+    find: (bindingId: string, conversation: string) => Readonly<{
+        bindingId: string;
+        conversation: string;
+        sessionId: string;
+        party: ChannelParty;
+        label: string;
+        createdAt: number;
+        lastEventAt: number;
+        handoff: Handoff;
+    }> | null;
+    sessionConversation: (sessionId: string) => ChannelConversation | null;
+    sessionIds: () => readonly string[];
+};
+/** AgentDO's channel conversation owner. */
+export type ChannelConversations = ReturnType<typeof createChannelConversations>;
+export {};