@fungi.computer/bird-dog 0.0.1 → 0.2.0

package/README.md

@@ -163,6 +163,13 @@ schedules an immediate wake and continues from the same place on the next drain.
 receipt under the same key. Replaying the same settlement after a restart finds
 the receipt and does not post the reply again. Keep those receipts as long as
 source settlements can replay. BirdDog does not expire them.
+`hasPendingDelivery(outbox)` reads only whether any reply still awaits a
+delivery attempt, so a host can tell retained receipts and dead letters from
+owed mail.
+
+The Effect mail room's `nextWakeAt()` reads Carrier's earliest owed delivery,
+including future retries. Runtime hosts include that hint in their pending-work
+answer rather than clearing a retry when other runtime work is idle.
 
 **Host ports.** `BirdDog.make` takes four things:
 
@@ -182,11 +189,12 @@ The generated reference is in [docs/api](docs/api/README.md).
   `BirdDogAgentJobPayload`, `BirdDogReply`, `BirdDogOutbox`, `BirdDogOptions`,
   `BirdDogSettlement` and `BirdDogRuntime` types.
 - `@fungi.computer/bird-dog/effect`: `make`, `agentJobFromInput`,
-  `decodeAgentJob`, `settlementReplies`, `boundedDiagnostic`,
-  `BIRD_DOG_DIAGNOSTIC_MAX_LENGTH`, `BirdDogError`, `EffectBirdDogOptions`,
-  `BirdDogEffect` and the schemas `BirdDogAgentReferenceSchema`,
-  `BirdDogReplySchema`, `BirdDogMailSchema`, `BirdDogAgentWorkSchema`,
-  `BirdDogAgentJobPayloadSchema` and `BirdDogAgentJobInputSchema`.
+  `decodeAgentJob`, `settlementReplies`, `hasPendingDelivery`,
+  `boundedDiagnostic`, `BIRD_DOG_DIAGNOSTIC_MAX_LENGTH`, `BirdDogError`,
+  `EffectBirdDogOptions`, `BirdDogEffect` and the schemas
+  `BirdDogAgentReferenceSchema`, `BirdDogReplySchema`, `BirdDogMailSchema`,
+  `BirdDogAgentWorkSchema`, `BirdDogAgentJobPayloadSchema` and
+  `BirdDogAgentJobInputSchema`.
 
 ## Examples and checks
 

package/dist/effect.d.ts

@@ -2,12 +2,20 @@ import type { WatchdogQueuedJob, WatchdogStoredJob } from "@fungi.computer/watch
 import * as Effect from "effect/Effect";
 import * as Schema from "effect/Schema";
 import type { BirdDogAgentJobInput, BirdDogAgentJobPayload, BirdDogMail, BirdDogSettlement } from "./index.js";
+/** The maximum UTF-8 size of one mail body. */
+export declare const BIRD_DOG_MAIL_CONTENT_MAX_BYTES: number;
 /** Parser for an ordinary agent Session address. */
 export declare const BirdDogAgentReferenceSchema: Schema.Struct<{
     readonly kind: Schema.Literal<"agent">;
     readonly agentId: Schema.String;
     readonly sessionId: Schema.String;
 }>;
+/** An addressed Agent may create its first Session when accepting this mail. */
+export declare const BirdDogAgentRecipientReferenceSchema: Schema.Struct<{
+    readonly kind: Schema.Literal<"agent">;
+    readonly agentId: Schema.String;
+    readonly sessionId: Schema.optionalKey<Schema.String>;
+}>;
 /** The most characters a reply's failure diagnostic may carry. */
 export declare const BIRD_DOG_DIAGNOSTIC_MAX_LENGTH = 200;
 /**
@@ -15,11 +23,33 @@ export declare const BIRD_DOG_DIAGNOSTIC_MAX_LENGTH = 200;
  * replying Session's command, its exact Watchdog outcome and, for work that did
  * not complete, the Session's bounded terminal diagnostic.
  */
-export declare const BirdDogReplySchema: Schema.Struct<{
+export declare const SettledBirdDogReplySchema: Schema.Struct<{
     readonly commandId: Schema.String;
     readonly outcome: Schema.Literals<readonly ["completed", "failed", "interrupted", "cancelled", "outcome_unknown"]>;
     readonly diagnostic: Schema.optionalKey<Schema.String>;
 }>;
+/** A terminal delivery failure, correlated by the original mail key only. */
+export declare const BirdDogUndeliverableReasonSchema: Schema.Literals<readonly ["recipient_offline", "recipient_left"]>;
+export declare const UndeliverableBirdDogReplySchema: Schema.Struct<{
+    readonly outcome: Schema.Literal<"undeliverable">;
+    readonly reason: Schema.Literals<readonly ["recipient_offline", "recipient_left"]>;
+}>;
+/** Recipient acceptance, before the command has settled. */
+export declare const AcceptedBirdDogReplySchema: Schema.Struct<{
+    readonly outcome: Schema.Literal<"accepted">;
+    readonly commandId: Schema.String;
+}>;
+export declare const BirdDogReplySchema: Schema.Union<readonly [Schema.Struct<{
+    readonly commandId: Schema.String;
+    readonly outcome: Schema.Literals<readonly ["completed", "failed", "interrupted", "cancelled", "outcome_unknown"]>;
+    readonly diagnostic: Schema.optionalKey<Schema.String>;
+}>, Schema.Struct<{
+    readonly outcome: Schema.Literal<"undeliverable">;
+    readonly reason: Schema.Literals<readonly ["recipient_offline", "recipient_left"]>;
+}>, Schema.Struct<{
+    readonly outcome: Schema.Literal<"accepted">;
+    readonly commandId: Schema.String;
+}>]>;
 /**
  * One secret-safe line of at most `BIRD_DOG_DIAGNOSTIC_MAX_LENGTH` characters
  * from a Session's terminal diagnostic, or nothing when it is blank. Control
@@ -28,18 +58,54 @@ export declare const BirdDogReplySchema: Schema.Struct<{
  * line is cut, so a cut never exposes part of one.
  */
 export declare function boundedDiagnostic(text: string): string | undefined;
-/** Parser for addressed agent correspondence. */
-export declare const BirdDogMailSchema: Schema.Struct<{
+export declare const BirdDogMailSchema: Schema.Union<readonly [Schema.Struct<{
+    readonly from: Schema.Struct<{
+        readonly kind: Schema.Literal<"agent">;
+        readonly agentId: Schema.String;
+        readonly sessionId: Schema.String;
+    }>;
+    /** Settlement or acceptance facts, present only on a reply. */
+    readonly reply: Schema.optionalKey<Schema.Union<readonly [Schema.Struct<{
+        readonly commandId: Schema.String;
+        readonly outcome: Schema.Literals<readonly ["completed", "failed", "interrupted", "cancelled", "outcome_unknown"]>;
+        readonly diagnostic: Schema.optionalKey<Schema.String>;
+    }>, Schema.Struct<{
+        readonly outcome: Schema.Literal<"undeliverable">;
+        readonly reason: Schema.Literals<readonly ["recipient_offline", "recipient_left"]>;
+    }>, Schema.Struct<{
+        readonly outcome: Schema.Literal<"accepted">;
+        readonly commandId: Schema.String;
+    }>]>>;
     readonly key: Schema.String;
     readonly to: Schema.Struct<{
         readonly kind: Schema.Literal<"agent">;
         readonly agentId: Schema.String;
-        readonly sessionId: Schema.String;
+        readonly sessionId: Schema.optionalKey<Schema.String>;
     }>;
-    readonly from: Schema.Struct<{
+    readonly replyTo: Schema.$Array<Schema.Struct<{
         readonly kind: Schema.Literal<"agent">;
         readonly agentId: Schema.String;
         readonly sessionId: Schema.String;
+    }>>;
+    readonly content: Schema.String;
+    readonly createdAt: Schema.Number;
+    readonly meta: Schema.optionalKey<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+}>, Schema.Struct<{
+    readonly from: Schema.Struct<{
+        readonly kind: Schema.Literal<"agent">;
+        readonly agentId: Schema.String;
+        readonly sessionId: Schema.optionalKey<Schema.String>;
+    }>;
+    /** An unstarted recipient can only author an undeliverable reply. */
+    readonly reply: Schema.Struct<{
+        readonly outcome: Schema.Literal<"undeliverable">;
+        readonly reason: Schema.Literals<readonly ["recipient_offline", "recipient_left"]>;
+    }>;
+    readonly key: Schema.String;
+    readonly to: Schema.Struct<{
+        readonly kind: Schema.Literal<"agent">;
+        readonly agentId: Schema.String;
+        readonly sessionId: Schema.optionalKey<Schema.String>;
     }>;
     readonly replyTo: Schema.$Array<Schema.Struct<{
         readonly kind: Schema.Literal<"agent">;
@@ -48,15 +114,8 @@ export declare const BirdDogMailSchema: Schema.Struct<{
     }>>;
     readonly content: Schema.String;
     readonly createdAt: Schema.Number;
-    /** The sender's opaque host metadata; BirdDog never reads it. */
     readonly meta: Schema.optionalKey<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
-    /** Settlement facts, present only on a reply BirdDog built. */
-    readonly reply: Schema.optionalKey<Schema.Struct<{
-        readonly commandId: Schema.String;
-        readonly outcome: Schema.Literals<readonly ["completed", "failed", "interrupted", "cancelled", "outcome_unknown"]>;
-        readonly diagnostic: Schema.optionalKey<Schema.String>;
-    }>>;
-}>;
+}>]>;
 /** Parser for accepted Session work. */
 export declare const BirdDogAgentWorkSchema: Schema.Struct<{
     readonly jobId: Schema.String;
@@ -72,17 +131,54 @@ export declare const BirdDogAgentJobPayloadSchema: Schema.Struct<{
         readonly sessionId: Schema.String;
         readonly commandFactId: Schema.String;
     }>;
-    readonly mail: Schema.optional<Schema.Struct<{
+    readonly mail: Schema.optional<Schema.Union<readonly [Schema.Struct<{
+        readonly from: Schema.Struct<{
+            readonly kind: Schema.Literal<"agent">;
+            readonly agentId: Schema.String;
+            readonly sessionId: Schema.String;
+        }>;
+        /** Settlement or acceptance facts, present only on a reply. */
+        readonly reply: Schema.optionalKey<Schema.Union<readonly [Schema.Struct<{
+            readonly commandId: Schema.String;
+            readonly outcome: Schema.Literals<readonly ["completed", "failed", "interrupted", "cancelled", "outcome_unknown"]>;
+            readonly diagnostic: Schema.optionalKey<Schema.String>;
+        }>, Schema.Struct<{
+            readonly outcome: Schema.Literal<"undeliverable">;
+            readonly reason: Schema.Literals<readonly ["recipient_offline", "recipient_left"]>;
+        }>, Schema.Struct<{
+            readonly outcome: Schema.Literal<"accepted">;
+            readonly commandId: Schema.String;
+        }>]>>;
         readonly key: Schema.String;
         readonly to: Schema.Struct<{
             readonly kind: Schema.Literal<"agent">;
             readonly agentId: Schema.String;
-            readonly sessionId: Schema.String;
+            readonly sessionId: Schema.optionalKey<Schema.String>;
         }>;
-        readonly from: Schema.Struct<{
+        readonly replyTo: Schema.$Array<Schema.Struct<{
             readonly kind: Schema.Literal<"agent">;
             readonly agentId: Schema.String;
             readonly sessionId: Schema.String;
+        }>>;
+        readonly content: Schema.String;
+        readonly createdAt: Schema.Number;
+        readonly meta: Schema.optionalKey<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+    }>, Schema.Struct<{
+        readonly from: Schema.Struct<{
+            readonly kind: Schema.Literal<"agent">;
+            readonly agentId: Schema.String;
+            readonly sessionId: Schema.optionalKey<Schema.String>;
+        }>;
+        /** An unstarted recipient can only author an undeliverable reply. */
+        readonly reply: Schema.Struct<{
+            readonly outcome: Schema.Literal<"undeliverable">;
+            readonly reason: Schema.Literals<readonly ["recipient_offline", "recipient_left"]>;
+        }>;
+        readonly key: Schema.String;
+        readonly to: Schema.Struct<{
+            readonly kind: Schema.Literal<"agent">;
+            readonly agentId: Schema.String;
+            readonly sessionId: Schema.optionalKey<Schema.String>;
         }>;
         readonly replyTo: Schema.$Array<Schema.Struct<{
             readonly kind: Schema.Literal<"agent">;
@@ -91,15 +187,8 @@ export declare const BirdDogAgentJobPayloadSchema: Schema.Struct<{
         }>>;
         readonly content: Schema.String;
         readonly createdAt: Schema.Number;
-        /** The sender's opaque host metadata; BirdDog never reads it. */
         readonly meta: Schema.optionalKey<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
-        /** Settlement facts, present only on a reply BirdDog built. */
-        readonly reply: Schema.optionalKey<Schema.Struct<{
-            readonly commandId: Schema.String;
-            readonly outcome: Schema.Literals<readonly ["completed", "failed", "interrupted", "cancelled", "outcome_unknown"]>;
-            readonly diagnostic: Schema.optionalKey<Schema.String>;
-        }>>;
-    }>>;
+    }>]>>;
 }>;
 /** Parser for accepted work entering BirdDog's transactional projection. */
 export declare const BirdDogAgentJobInputSchema: Schema.Struct<{
@@ -111,17 +200,54 @@ export declare const BirdDogAgentJobInputSchema: Schema.Struct<{
             readonly maxRecoveries: Schema.Int;
         }>>;
     }>;
-    readonly mail: Schema.optional<Schema.Struct<{
+    readonly mail: Schema.optional<Schema.Union<readonly [Schema.Struct<{
+        readonly from: Schema.Struct<{
+            readonly kind: Schema.Literal<"agent">;
+            readonly agentId: Schema.String;
+            readonly sessionId: Schema.String;
+        }>;
+        /** Settlement or acceptance facts, present only on a reply. */
+        readonly reply: Schema.optionalKey<Schema.Union<readonly [Schema.Struct<{
+            readonly commandId: Schema.String;
+            readonly outcome: Schema.Literals<readonly ["completed", "failed", "interrupted", "cancelled", "outcome_unknown"]>;
+            readonly diagnostic: Schema.optionalKey<Schema.String>;
+        }>, Schema.Struct<{
+            readonly outcome: Schema.Literal<"undeliverable">;
+            readonly reason: Schema.Literals<readonly ["recipient_offline", "recipient_left"]>;
+        }>, Schema.Struct<{
+            readonly outcome: Schema.Literal<"accepted">;
+            readonly commandId: Schema.String;
+        }>]>>;
         readonly key: Schema.String;
         readonly to: Schema.Struct<{
             readonly kind: Schema.Literal<"agent">;
             readonly agentId: Schema.String;
-            readonly sessionId: Schema.String;
+            readonly sessionId: Schema.optionalKey<Schema.String>;
         }>;
-        readonly from: Schema.Struct<{
+        readonly replyTo: Schema.$Array<Schema.Struct<{
             readonly kind: Schema.Literal<"agent">;
             readonly agentId: Schema.String;
             readonly sessionId: Schema.String;
+        }>>;
+        readonly content: Schema.String;
+        readonly createdAt: Schema.Number;
+        readonly meta: Schema.optionalKey<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+    }>, Schema.Struct<{
+        readonly from: Schema.Struct<{
+            readonly kind: Schema.Literal<"agent">;
+            readonly agentId: Schema.String;
+            readonly sessionId: Schema.optionalKey<Schema.String>;
+        }>;
+        /** An unstarted recipient can only author an undeliverable reply. */
+        readonly reply: Schema.Struct<{
+            readonly outcome: Schema.Literal<"undeliverable">;
+            readonly reason: Schema.Literals<readonly ["recipient_offline", "recipient_left"]>;
+        }>;
+        readonly key: Schema.String;
+        readonly to: Schema.Struct<{
+            readonly kind: Schema.Literal<"agent">;
+            readonly agentId: Schema.String;
+            readonly sessionId: Schema.optionalKey<Schema.String>;
         }>;
         readonly replyTo: Schema.$Array<Schema.Struct<{
             readonly kind: Schema.Literal<"agent">;
@@ -130,15 +256,8 @@ export declare const BirdDogAgentJobInputSchema: Schema.Struct<{
         }>>;
         readonly content: Schema.String;
         readonly createdAt: Schema.Number;
-        /** The sender's opaque host metadata; BirdDog never reads it. */
         readonly meta: Schema.optionalKey<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
-        /** Settlement facts, present only on a reply BirdDog built. */
-        readonly reply: Schema.optionalKey<Schema.Struct<{
-            readonly commandId: Schema.String;
-            readonly outcome: Schema.Literals<readonly ["completed", "failed", "interrupted", "cancelled", "outcome_unknown"]>;
-            readonly diagnostic: Schema.optionalKey<Schema.String>;
-        }>>;
-    }>>;
+    }>]>>;
 }>;
 /** BirdDog could not complete one owned store or transport operation. */
 export declare class BirdDogError extends Error {
@@ -172,8 +291,12 @@ export type EffectBirdDogOptions = Readonly<{
 export type BirdDogEffect = Readonly<{
     /** Queue replies owed by a settled agent job. */
     fanOut: (settlement: BirdDogSettlement) => Effect.Effect<void, BirdDogError>;
+    /** Durably queue one authored mail item in this Agent's existing outbox. */
+    postMail?: ((mail: BirdDogMail) => Effect.Effect<void, BirdDogError>) | undefined;
     /** Deliver due replies and schedule any required retry wake. */
     drainOutbox: () => Effect.Effect<void, BirdDogError>;
+    /** Earliest owed reply delivery, including retries; absent after delivery. */
+    nextWakeAt: () => Effect.Effect<number | undefined, BirdDogError>;
 }>;
 /** Validate and translate agent work into Watchdog's opaque job grammar. */
 export declare const agentJobFromInput: (input: BirdDogAgentJobInput) => WatchdogQueuedJob;
@@ -187,5 +310,12 @@ export declare const decodeAgentJob: (job: WatchdogStoredJob) => BirdDogAgentJob
  * are presented. A reply never carries the settled work's host metadata.
  */
 export declare function settlementReplies(settlement: BirdDogSettlement, createdAt: number): readonly BirdDogMail[];
+/** Build the recipient's one stable acceptance notice for one original mail. */
+export declare function acceptedNotice(mail: BirdDogMail, sessionId: string, commandId: string, createdAt: number): BirdDogMail;
+/**
+ * Whether this mail room's outbox still owes any reply a delivery attempt.
+ * Delivered receipts and exhausted dead letters stay but owe nothing.
+ */
+export declare const hasPendingDelivery: (outbox: Pick<EffectBirdDogOptions["outbox"], "list">) => Effect.Effect<boolean, BirdDogError>;
 /** Construct BirdDog's Effect-native mail room over Post's shared outbox. */
 export declare const make: (options: EffectBirdDogOptions) => Effect.Effect<BirdDogEffect>;

package/dist/effect.js

@@ -1,13 +1,25 @@
 import * as Effect from "effect/Effect";
 import * as Schema from "effect/Schema";
-import { makePostOutbox } from "@fungi.computer/carrier/post";
+import { makePostOutbox, postOutboxPending, } from "@fungi.computer/carrier/post";
 const Identifier = Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(256));
+/** The maximum UTF-8 size of one mail body. */
+export const BIRD_DOG_MAIL_CONTENT_MAX_BYTES = 256 * 1024;
+const MailContent = Schema.String.check(Schema.makeFilter((content) => new TextEncoder().encode(content).byteLength <=
+    BIRD_DOG_MAIL_CONTENT_MAX_BYTES, {
+    message: `Mail content must be at most ${String(BIRD_DOG_MAIL_CONTENT_MAX_BYTES)} UTF-8 bytes`,
+}));
 /** Parser for an ordinary agent Session address. */
 export const BirdDogAgentReferenceSchema = Schema.Struct({
     kind: Schema.Literal("agent"),
     agentId: Identifier,
     sessionId: Identifier,
 });
+/** An addressed Agent may create its first Session when accepting this mail. */
+export const BirdDogAgentRecipientReferenceSchema = Schema.Struct({
+    kind: Schema.Literal("agent"),
+    agentId: Identifier,
+    sessionId: Schema.optionalKey(Identifier),
+});
 /** The most characters a reply's failure diagnostic may carry. */
 export const BIRD_DOG_DIAGNOSTIC_MAX_LENGTH = 200;
 /**
@@ -15,7 +27,7 @@ export const BIRD_DOG_DIAGNOSTIC_MAX_LENGTH = 200;
  * replying Session's command, its exact Watchdog outcome and, for work that did
  * not complete, the Session's bounded terminal diagnostic.
  */
-export const BirdDogReplySchema = Schema.Struct({
+export const SettledBirdDogReplySchema = Schema.Struct({
     commandId: Identifier,
     outcome: Schema.Literals([
         "completed",
@@ -26,6 +38,25 @@ export const BirdDogReplySchema = Schema.Struct({
     ]),
     diagnostic: Schema.optionalKey(Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(BIRD_DOG_DIAGNOSTIC_MAX_LENGTH))),
 });
+/** A terminal delivery failure, correlated by the original mail key only. */
+export const BirdDogUndeliverableReasonSchema = Schema.Literals([
+    "recipient_offline",
+    "recipient_left",
+]);
+export const UndeliverableBirdDogReplySchema = Schema.Struct({
+    outcome: Schema.Literal("undeliverable"),
+    reason: BirdDogUndeliverableReasonSchema,
+});
+/** Recipient acceptance, before the command has settled. */
+export const AcceptedBirdDogReplySchema = Schema.Struct({
+    outcome: Schema.Literal("accepted"),
+    commandId: Identifier,
+});
+export const BirdDogReplySchema = Schema.Union([
+    SettledBirdDogReplySchema,
+    UndeliverableBirdDogReplySchema,
+    AcceptedBirdDogReplySchema,
+]);
 const REDACTED = "[redacted]";
 // An authorization scheme's credential, e.g. `Bearer <token>`.
 const schemeCredential = /\b(bearer|basic)\s+[^\s"',;]+/giu;
@@ -53,18 +84,29 @@ export function boundedDiagnostic(text) {
     return line.length === 0 ? undefined : line;
 }
 /** Parser for addressed agent correspondence. */
-export const BirdDogMailSchema = Schema.Struct({
+const BirdDogMailFields = {
     key: Identifier,
-    to: BirdDogAgentReferenceSchema,
-    from: BirdDogAgentReferenceSchema,
+    to: BirdDogAgentRecipientReferenceSchema,
     replyTo: Schema.Array(BirdDogAgentReferenceSchema),
-    content: Schema.String,
+    content: MailContent,
     createdAt: Schema.Number.check(Schema.isGreaterThanOrEqualTo(0)),
     /** The sender's opaque host metadata; BirdDog never reads it. */
     meta: Schema.optionalKey(Schema.Json),
-    /** Settlement facts, present only on a reply BirdDog built. */
-    reply: Schema.optionalKey(BirdDogReplySchema),
-});
+};
+export const BirdDogMailSchema = Schema.Union([
+    Schema.Struct({
+        ...BirdDogMailFields,
+        from: BirdDogAgentReferenceSchema,
+        /** Settlement or acceptance facts, present only on a reply. */
+        reply: Schema.optionalKey(BirdDogReplySchema),
+    }),
+    Schema.Struct({
+        ...BirdDogMailFields,
+        from: BirdDogAgentRecipientReferenceSchema,
+        /** An unstarted recipient can only author an undeliverable reply. */
+        reply: UndeliverableBirdDogReplySchema,
+    }),
+]);
 /** Parser for accepted Session work. */
 export const BirdDogAgentWorkSchema = Schema.Struct({
     jobId: Identifier,
@@ -141,7 +183,7 @@ export function settlementReplies(settlement, createdAt) {
     return mail.replyTo.map((destination, index) => ({
         key: `${mail.key}:reply:${String(index)}`,
         to: destination,
-        from: mail.to,
+        from: { ...mail.to, sessionId: work.sessionId },
         replyTo: [],
         content: settlement.content.length > 0
             ? settlement.content
@@ -150,6 +192,29 @@ export function settlementReplies(settlement, createdAt) {
         reply,
     }));
 }
+/** Build the recipient's one stable acceptance notice for one original mail. */
+export function acceptedNotice(mail, sessionId, commandId, createdAt) {
+    const recipientSession = Schema.decodeUnknownSync(Identifier)(sessionId);
+    const sender = Schema.decodeUnknownSync(BirdDogAgentReferenceSchema)(mail.from);
+    const reply = Schema.decodeUnknownSync(AcceptedBirdDogReplySchema)({
+        outcome: "accepted",
+        commandId,
+    });
+    return {
+        key: `${mail.key}:accepted`,
+        to: sender,
+        from: { ...mail.to, sessionId: recipientSession },
+        replyTo: [],
+        content: "Work accepted.",
+        createdAt,
+        reply,
+    };
+}
+/**
+ * Whether this mail room's outbox still owes any reply a delivery attempt.
+ * Delivered receipts and exhausted dead letters stay but owe nothing.
+ */
+export const hasPendingDelivery = (outbox) => postOutboxPending({ message: BirdDogMailSchema, outbox });
 /** Construct BirdDog's Effect-native mail room over Post's shared outbox. */
 export const make = (options) => {
     const post = makePostOutbox({
@@ -177,5 +242,17 @@ export const make = (options) => {
         if (wake !== undefined)
             yield* options.scheduleWake(wake);
     });
-    return Effect.succeed({ fanOut, drainOutbox: post.drain });
+    const postMail = (mail) => Effect.gen(function* () {
+        const createdAt = options.now();
+        const hint = yield* post.enqueue(mail, createdAt);
+        if (hint !== undefined)
+            yield* options.scheduleWake(hint);
+        return;
+    });
+    return Effect.succeed({
+        fanOut,
+        postMail,
+        drainOutbox: post.drain,
+        nextWakeAt: post.nextWakeAt,
+    });
 };

package/dist/index.d.ts

@@ -6,18 +6,11 @@ export type BirdDogAgentReference = Readonly<{
     agentId: string;
     sessionId: string;
 }>;
-/** Addressed agent correspondence carried with durable work when a reply is owed. */
-export type BirdDogMail = Readonly<{
-    key: string;
-    to: BirdDogAgentReference;
-    from: BirdDogAgentReference;
-    replyTo: readonly BirdDogAgentReference[];
-    content: string;
-    createdAt: number;
-    /** The sender's opaque host metadata; BirdDog never reads it. */
-    meta?: BirdDogMeta;
-    /** Settlement facts, present only on a reply BirdDog built. */
-    reply?: BirdDogReply;
+/** An addressed Agent whose first Session may be created on acceptance. */
+export type BirdDogAgentRecipientReference = Readonly<{
+    kind: "agent";
+    agentId: string;
+    sessionId?: string;
 }>;
 /**
  * What a reply reports about the settled work beside its content. The
@@ -25,12 +18,45 @@ export type BirdDogMail = Readonly<{
  * against the mail it sent.
  */
 export type BirdDogReply = Readonly<{
+    /** The recipient accepted the work into the named Session. */
+    commandId: string;
+    outcome: "accepted";
+}> | Readonly<{
     /** The replying Session's accepted command: the sender's receipt `commandId`. */
     commandId: string;
     /** The exact Watchdog outcome; failures are never collapsed. */
     outcome: "completed" | "failed" | "interrupted" | "cancelled" | "outcome_unknown";
     /** Bounded terminal diagnostic for work that did not complete or cancel. */
     diagnostic?: string;
+}> | Readonly<{
+    outcome: "undeliverable";
+    reason: "recipient_offline" | "recipient_left";
+}>;
+/** Addressed mail; an unstarted Agent may author only an undeliverable reply. */
+export type BirdDogMail = Readonly<{
+    key: string;
+    to: BirdDogAgentRecipientReference;
+    replyTo: readonly BirdDogAgentReference[];
+    content: string;
+    createdAt: number;
+    /** The sender's opaque host metadata; BirdDog never reads it. */
+    meta?: BirdDogMeta;
+    from: BirdDogAgentReference;
+    /** Settlement or acceptance facts, present only on a reply. */
+    reply?: BirdDogReply;
+}> | Readonly<{
+    key: string;
+    to: BirdDogAgentRecipientReference;
+    replyTo: readonly BirdDogAgentReference[];
+    content: string;
+    createdAt: number;
+    /** The sender's opaque host metadata; BirdDog never reads it. */
+    meta?: BirdDogMeta;
+    /** No Session exists when a never-started recipient is undeliverable. */
+    from: BirdDogAgentRecipientReference;
+    reply: Extract<BirdDogReply, {
+        outcome: "undeliverable";
+    }>;
 }>;
 /** Opaque JSON a host attached to the work; BirdDog only carries it. */
 export type BirdDogMeta = typeof Schema.Json.Type;

package/docs/api/effect.md

@@ -90,6 +90,7 @@ Effect host ports for the durable mail room.
 type BirdDogEffect = Readonly<{
   fanOut: (settlement) => Effect.Effect<void, BirdDogError>;
   drainOutbox: () => Effect.Effect<void, BirdDogError>;
+  nextWakeAt: () => Effect.Effect<number | undefined, BirdDogError>;
 }>;
 ```
 
@@ -455,6 +456,27 @@ readonly `Readonly`\<\{ `key`: `string`; `to`:
 
 ---
 
+### hasPendingDelivery()
+
+```ts
+function hasPendingDelivery(outbox): Effect<boolean, BirdDogError>;
+```
+
+Whether this mail room's outbox still owes any reply a delivery attempt.
+Delivered receipts and exhausted dead letters stay but owe nothing.
+
+#### Parameters
+
+| Parameter | Type                                                                              |
+| --------- | --------------------------------------------------------------------------------- |
+| `outbox`  | `Pick`\<[`EffectBirdDogOptions`](#effectbirddogoptions)\[`"outbox"`\], `"list"`\> |
+
+#### Returns
+
+`Effect`\<`boolean`, [`BirdDogError`](#birddogerror)\>
+
+---
+
 ### make()
 
 ```ts
@@ -462,6 +484,7 @@ function make(options): Effect<
   Readonly<{
     fanOut: (settlement) => Effect<void, BirdDogError>;
     drainOutbox: () => Effect<void, BirdDogError>;
+    nextWakeAt: () => Effect<number | undefined, BirdDogError>;
   }>
 >;
 ```
@@ -478,4 +501,5 @@ Construct BirdDog's Effect-native mail room over Post's shared outbox.
 
 `Effect`\<`Readonly`\<\{ `fanOut`: (`settlement`) => `Effect`\<`void`,
 [`BirdDogError`](#birddogerror)\>; `drainOutbox`: () => `Effect`\<`void`,
-[`BirdDogError`](#birddogerror)\>; \}\>\>
+[`BirdDogError`](#birddogerror)\>; `nextWakeAt`: () => `Effect`\<`number` \|
+`undefined`, [`BirdDogError`](#birddogerror)\>; \}\>\>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fungi.computer/bird-dog",
-  "version": "0.0.1",
+  "version": "0.2.0",
   "author": "Levi <levi@technomancy.dev>",
   "description": "Durable addressed agent mail over generic Watchdog work",
   "type": "module",
@@ -23,8 +23,8 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@fungi.computer/carrier": "0.0.1",
-    "@fungi.computer/watchdog": "0.0.1",
+    "@fungi.computer/carrier": "0.2.0",
+    "@fungi.computer/watchdog": "0.1.0",
     "effect": "4.0.2"
   },
   "devDependencies": {