@fungi.computer/oyster 0.4.1 → 0.5.0

package/dist/build/candidate-cli.mjs

@@ -21740,6 +21740,10 @@ var BirdDogAgentRecipientReferenceSchema = Struct({
   agentId: Identifier,
   sessionId: optionalKey2(Identifier)
 });
+var BirdDogSystemIdentitySchema = Struct({
+  kind: Literal2("system"),
+  systemId: Literal2("hub")
+});
 var BIRD_DOG_DIAGNOSTIC_MAX_LENGTH = 200;
 var SettledBirdDogReplySchema = Struct({
   commandId: Identifier,
@@ -21769,6 +21773,14 @@ var BirdDogReplySchema = Union2([
   UndeliverableBirdDogReplySchema,
   AcceptedBirdDogReplySchema
 ]);
+var BirdDogAgentReplySchema = Union2([
+  SettledBirdDogReplySchema,
+  AcceptedBirdDogReplySchema,
+  Struct({
+    outcome: Literal2("undeliverable"),
+    reason: Literal2("recipient_left")
+  })
+]);
 var REDACTED = "[redacted]";
 var schemeCredential = /\b(bearer|basic)\s+[^\s"',;]+/giu;
 var namedCredential = /\b((?:api[_-]?key|access[_-]?token|refresh[_-]?token|token|secret|password|authorization)["']?\s*[:=]\s*["']?)(?!(?:bearer|basic)\s)[^\s"',;&]+/giu;
@@ -21794,13 +21806,16 @@ var BirdDogMailSchema = Union2([
     ...BirdDogMailFields,
     from: BirdDogAgentReferenceSchema,
     /** Settlement or acceptance facts, present only on a reply. */
-    reply: optionalKey2(BirdDogReplySchema)
+    reply: optionalKey2(BirdDogAgentReplySchema)
   }),
   Struct({
     ...BirdDogMailFields,
-    from: BirdDogAgentRecipientReferenceSchema,
-    /** An unstarted recipient can only author an undeliverable reply. */
-    reply: UndeliverableBirdDogReplySchema
+    from: BirdDogSystemIdentitySchema,
+    /** Only the Hub may author this offline disposition. */
+    reply: Struct({
+      outcome: Literal2("undeliverable"),
+      reason: Literal2("recipient_offline")
+    })
   })
 ]);
 var BirdDogAgentWorkSchema = Struct({

package/dist/channels/binding.d.ts

@@ -0,0 +1,63 @@
+import { z } from "zod";
+/** The runtime needs a binding, not a Team or an authority projection. */
+export type ConversationBinding = Readonly<{
+    bindingId: string;
+    lifecycle: "active" | "suspended";
+    selector: Readonly<{
+        provider: "event";
+        target: "new" | "named";
+        verifier: "fungi-v1" | "github" | "secret-url";
+        eventsPerMinute: number;
+    }> | Readonly<{
+        provider: "web" | "discord" | "email" | "game";
+    }>;
+    /** Zod's optional binding projection may carry an explicit undefined. */
+    limits?: BindingLimits | undefined;
+}>;
+/** Per-party edge limits applied before any work is accepted. */
+export declare const bindingLimitsSchema: z.ZodObject<{
+    messagesPerPartyPerDay: z.ZodNumber;
+    charsPerMessage: z.ZodNumber;
+    newPartiesPerHour: z.ZodNumber;
+}, z.core.$strict>;
+/** Per-binding edge limits. */
+export type BindingLimits = z.infer<typeof bindingLimitsSchema>;
+/** Edge limits of a binding whose owner set none. */
+export declare const DEFAULT_BINDING_LIMITS: BindingLimits;
+/**
+ * How long a GitHub body digest keeps a changed-id replay out: the verifiers'
+ * signed-timestamp skew (Veil's `WEBHOOK_SIGNATURE_MAX_SKEW_SECONDS`; a test
+ * pins them equal). GitHub signs no timestamp, so this window is the bound.
+ */
+export declare const EVENT_REPLAY_WINDOW_SECONDS = 300;
+/** The edge limits one binding runs under: its owner's, else its kind's default. */
+export declare function limitsOf(binding: ConversationBinding): BindingLimits;
+export declare const discordSnowflakeSchema: z.ZodString;
+/** The party on the other side of a channel conversation; never a member. */
+export declare const channelPartySchema: 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">;
+/** One channel party. */
+export type ChannelParty = z.infer<typeof channelPartySchema>;
+/** Short human label for a party, used in author metadata and owner rows. */
+export declare function partyLabel(party: ChannelParty): string;

package/dist/channels/binding.js

@@ -0,0 +1,85 @@
+import { z } from "zod";
+import { channelIds } from "./ids.js";
+/** Per-party edge limits applied before any work is accepted. */
+export const bindingLimitsSchema = z.strictObject({
+    messagesPerPartyPerDay: z.number().int().min(1).max(10_000),
+    charsPerMessage: z.number().int().min(1).max(16_000),
+    newPartiesPerHour: z.number().int().min(1).max(100_000),
+});
+/** Edge limits of a binding whose owner set none. */
+export const DEFAULT_BINDING_LIMITS = Object.freeze({
+    messagesPerPartyPerDay: 30,
+    charsPerMessage: 4_000,
+    newPartiesPerHour: 200,
+});
+/**
+ * Edge limits of an incoming-events binding whose owner set none. Events are
+ * not people: `eventsPerMinute` bounds intake, so the
+ * per-party and new-party limits sit at their ceilings, and one event may
+ * carry the longest message intake accepts.
+ */
+const DEFAULT_EVENT_LIMITS = Object.freeze({
+    messagesPerPartyPerDay: 10_000,
+    charsPerMessage: 16_000,
+    newPartiesPerHour: 100_000,
+});
+/**
+ * How long a GitHub body digest keeps a changed-id replay out: the verifiers'
+ * signed-timestamp skew (Veil's `WEBHOOK_SIGNATURE_MAX_SKEW_SECONDS`; a test
+ * pins them equal). GitHub signs no timestamp, so this window is the bound.
+ */
+export const EVENT_REPLAY_WINDOW_SECONDS = 300;
+/** The edge limits one binding runs under: its owner's, else its kind's default. */
+export function limitsOf(binding) {
+    return (binding.limits ??
+        (binding.selector.provider === "event"
+            ? DEFAULT_EVENT_LIMITS
+            : DEFAULT_BINDING_LIMITS));
+}
+export const discordSnowflakeSchema = z.string().regex(/^\d{17,20}$/u);
+/** The party on the other side of a channel conversation; never a member. */
+export const channelPartySchema = z.discriminatedUnion("kind", [
+    z.strictObject({
+        kind: z.literal("visitor"),
+        visitorId: z
+            .string()
+            .refine((value) => channelIds.visitor.is(value), "Invalid visitor"),
+    }),
+    z.strictObject({
+        kind: z.literal("discord-user"),
+        guildId: discordSnowflakeSchema,
+        userId: discordSnowflakeSchema,
+    }),
+    z.strictObject({
+        kind: z.literal("email-sender"),
+        address: z.email(),
+        dmarc: z.enum(["pass", "fail", "none"]),
+    }),
+    z.strictObject({
+        kind: z.literal("player"),
+        worldId: z.string().min(1).max(160),
+        playerId: z.string().min(1).max(160),
+    }),
+    z.strictObject({
+        kind: z.literal("source"),
+        /** The sender's declared source identity, such as `github`. */
+        source: z.string().regex(/^[a-z0-9][a-z0-9._-]{0,63}$/u),
+    }),
+]);
+/** Short human label for a party, used in author metadata and owner rows. */
+export function partyLabel(party) {
+    switch (party.kind) {
+        case "visitor":
+            return `Visitor ${party.visitorId.slice(-4)}`;
+        case "discord-user":
+            return `Discord user ${party.userId}`;
+        case "email-sender":
+            return party.dmarc === "pass"
+                ? party.address
+                : `${party.address} (unverified)`;
+        case "player":
+            return `Player ${party.playerId}`;
+        case "source":
+            return party.source;
+    }
+}

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 {};