@fungi.computer/bird-dog 0.2.0 → 0.3.0

package/dist/effect.d.ts

@@ -16,20 +16,44 @@ export declare const BirdDogAgentRecipientReferenceSchema: Schema.Struct<{
     readonly agentId: Schema.String;
     readonly sessionId: Schema.optionalKey<Schema.String>;
 }>;
+/** The Hub's stable system identity for a terminal offline disposition. */
+export declare const BirdDogSystemIdentitySchema: Schema.Struct<{
+    readonly kind: Schema.Literal<"system">;
+    readonly systemId: Schema.Literal<"hub">;
+}>;
 /** The most characters a reply's failure diagnostic may carry. */
 export declare const BIRD_DOG_DIAGNOSTIC_MAX_LENGTH = 200;
+/** The most open items one reply names as waiting on its recipient. */
+export declare const BIRD_DOG_WAITING_MAX_ITEMS = 8;
+/**
+ * One open item of the replying Session that waits on this reply's recipient.
+ * BirdDog carries the three bounded fields; the replying host owns their
+ * meaning and the recipient host owns every decision about them.
+ */
+export declare const BirdDogWaitingItemSchema: Schema.Struct<{
+    readonly itemId: Schema.String;
+    readonly kind: Schema.String;
+    readonly summary: Schema.String;
+}>;
 /**
  * Parser for the settlement facts a reply carries beside its content: the
- * replying Session's command, its exact Watchdog outcome and, for work that did
- * not complete, the Session's bounded terminal diagnostic.
+ * replying Session's command, its exact Watchdog outcome, for work that did
+ * not complete the Session's bounded terminal diagnostic and, when the
+ * replying host names any, the open items now waiting on the recipient.
  */
 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>;
+    readonly waitingOnYou: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+        readonly itemId: Schema.String;
+        readonly kind: Schema.String;
+        readonly summary: Schema.String;
+    }>>>;
 }>;
 /** A terminal delivery failure, correlated by the original mail key only. */
 export declare const BirdDogUndeliverableReasonSchema: Schema.Literals<readonly ["recipient_offline", "recipient_left"]>;
+/** Parser for a terminal delivery failure reply. */
 export declare const UndeliverableBirdDogReplySchema: Schema.Struct<{
     readonly outcome: Schema.Literal<"undeliverable">;
     readonly reason: Schema.Literals<readonly ["recipient_offline", "recipient_left"]>;
@@ -39,10 +63,16 @@ export declare const AcceptedBirdDogReplySchema: Schema.Struct<{
     readonly outcome: Schema.Literal<"accepted">;
     readonly commandId: Schema.String;
 }>;
+/** Parser for any reply: settled, accepted or undeliverable. */
 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>;
+    readonly waitingOnYou: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+        readonly itemId: Schema.String;
+        readonly kind: Schema.String;
+        readonly summary: Schema.String;
+    }>>>;
 }>, Schema.Struct<{
     readonly outcome: Schema.Literal<"undeliverable">;
     readonly reason: Schema.Literals<readonly ["recipient_offline", "recipient_left"]>;
@@ -58,6 +88,7 @@ export declare const BirdDogReplySchema: Schema.Union<readonly [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 mail, from an Agent or from the Hub system. */
 export declare const BirdDogMailSchema: Schema.Union<readonly [Schema.Struct<{
     readonly from: Schema.Struct<{
         readonly kind: Schema.Literal<"agent">;
@@ -69,12 +100,17 @@ export declare const BirdDogMailSchema: 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"]>;
+        readonly waitingOnYou: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+            readonly itemId: Schema.String;
+            readonly kind: Schema.String;
+            readonly summary: Schema.String;
+        }>>>;
     }>, Schema.Struct<{
         readonly outcome: Schema.Literal<"accepted">;
         readonly commandId: Schema.String;
+    }>, Schema.Struct<{
+        readonly outcome: Schema.Literal<"undeliverable">;
+        readonly reason: Schema.Literal<"recipient_left">;
     }>]>>;
     readonly key: Schema.String;
     readonly to: Schema.Struct<{
@@ -92,14 +128,13 @@ export declare const BirdDogMailSchema: Schema.Union<readonly [Schema.Struct<{
     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>;
+        readonly kind: Schema.Literal<"system">;
+        readonly systemId: Schema.Literal<"hub">;
     }>;
-    /** An unstarted recipient can only author an undeliverable reply. */
+    /** Only the Hub may author this offline disposition. */
     readonly reply: Schema.Struct<{
         readonly outcome: Schema.Literal<"undeliverable">;
-        readonly reason: Schema.Literals<readonly ["recipient_offline", "recipient_left"]>;
+        readonly reason: Schema.Literal<"recipient_offline">;
     }>;
     readonly key: Schema.String;
     readonly to: Schema.Struct<{
@@ -142,12 +177,17 @@ export declare const BirdDogAgentJobPayloadSchema: 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"]>;
+            readonly waitingOnYou: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+                readonly itemId: Schema.String;
+                readonly kind: Schema.String;
+                readonly summary: Schema.String;
+            }>>>;
         }>, Schema.Struct<{
             readonly outcome: Schema.Literal<"accepted">;
             readonly commandId: Schema.String;
+        }>, Schema.Struct<{
+            readonly outcome: Schema.Literal<"undeliverable">;
+            readonly reason: Schema.Literal<"recipient_left">;
         }>]>>;
         readonly key: Schema.String;
         readonly to: Schema.Struct<{
@@ -165,14 +205,13 @@ export declare const BirdDogAgentJobPayloadSchema: Schema.Struct<{
         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>;
+            readonly kind: Schema.Literal<"system">;
+            readonly systemId: Schema.Literal<"hub">;
         }>;
-        /** An unstarted recipient can only author an undeliverable reply. */
+        /** Only the Hub may author this offline disposition. */
         readonly reply: Schema.Struct<{
             readonly outcome: Schema.Literal<"undeliverable">;
-            readonly reason: Schema.Literals<readonly ["recipient_offline", "recipient_left"]>;
+            readonly reason: Schema.Literal<"recipient_offline">;
         }>;
         readonly key: Schema.String;
         readonly to: Schema.Struct<{
@@ -211,12 +250,17 @@ export declare const BirdDogAgentJobInputSchema: 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"]>;
+            readonly waitingOnYou: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+                readonly itemId: Schema.String;
+                readonly kind: Schema.String;
+                readonly summary: Schema.String;
+            }>>>;
         }>, Schema.Struct<{
             readonly outcome: Schema.Literal<"accepted">;
             readonly commandId: Schema.String;
+        }>, Schema.Struct<{
+            readonly outcome: Schema.Literal<"undeliverable">;
+            readonly reason: Schema.Literal<"recipient_left">;
         }>]>>;
         readonly key: Schema.String;
         readonly to: Schema.Struct<{
@@ -234,14 +278,13 @@ export declare const BirdDogAgentJobInputSchema: Schema.Struct<{
         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>;
+            readonly kind: Schema.Literal<"system">;
+            readonly systemId: Schema.Literal<"hub">;
         }>;
-        /** An unstarted recipient can only author an undeliverable reply. */
+        /** Only the Hub may author this offline disposition. */
         readonly reply: Schema.Struct<{
             readonly outcome: Schema.Literal<"undeliverable">;
-            readonly reason: Schema.Literals<readonly ["recipient_offline", "recipient_left"]>;
+            readonly reason: Schema.Literal<"recipient_offline">;
         }>;
         readonly key: Schema.String;
         readonly to: Schema.Struct<{
@@ -305,9 +348,15 @@ export declare const decodeAgentJob: (job: WatchdogStoredJob) => BirdDogAgentJob
 /**
  * Build the replies owed by one settlement for a host-owned Post transport.
  * Each reply carries the settled content verbatim (or, when there is none, one
- * sentence naming the outcome, so the reply is always admissible text) and its
- * settlement facts as typed fields; the recipient's host authenticates them and decides how they
- * are presented. A reply never carries the settled work's host metadata.
+ * sentence naming the outcome and its diagnostic, so the reply is always
+ * admissible text) and its settlement facts as typed fields; the recipient's
+ * host authenticates them and decides how they are presented. A reply never
+ * carries the settled work's host metadata.
+ *
+ * Work a delegator's mail admitted replies to that mail under its `:reply:`
+ * key. Any other settled work, whatever started its turn, is a report to the
+ * Session's delegator of record, when the host names one (it does so once the
+ * Session is idle), under the delegator mail's `:report:` key.
  */
 export declare function settlementReplies(settlement: BirdDogSettlement, createdAt: number): readonly BirdDogMail[];
 /** Build the recipient's one stable acceptance notice for one original mail. */

package/dist/effect.js

@@ -20,12 +20,30 @@ export const BirdDogAgentRecipientReferenceSchema = Schema.Struct({
     agentId: Identifier,
     sessionId: Schema.optionalKey(Identifier),
 });
+/** The Hub's stable system identity for a terminal offline disposition. */
+export const BirdDogSystemIdentitySchema = Schema.Struct({
+    kind: Schema.Literal("system"),
+    systemId: Schema.Literal("hub"),
+});
 /** The most characters a reply's failure diagnostic may carry. */
 export const BIRD_DOG_DIAGNOSTIC_MAX_LENGTH = 200;
+/** The most open items one reply names as waiting on its recipient. */
+export const BIRD_DOG_WAITING_MAX_ITEMS = 8;
+/**
+ * One open item of the replying Session that waits on this reply's recipient.
+ * BirdDog carries the three bounded fields; the replying host owns their
+ * meaning and the recipient host owns every decision about them.
+ */
+export const BirdDogWaitingItemSchema = Schema.Struct({
+    itemId: Identifier,
+    kind: Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(64)),
+    summary: Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(200)),
+});
 /**
  * Parser for the settlement facts a reply carries beside its content: the
- * replying Session's command, its exact Watchdog outcome and, for work that did
- * not complete, the Session's bounded terminal diagnostic.
+ * replying Session's command, its exact Watchdog outcome, for work that did
+ * not complete the Session's bounded terminal diagnostic and, when the
+ * replying host names any, the open items now waiting on the recipient.
  */
 export const SettledBirdDogReplySchema = Schema.Struct({
     commandId: Identifier,
@@ -37,12 +55,14 @@ export const SettledBirdDogReplySchema = Schema.Struct({
         "outcome_unknown",
     ]),
     diagnostic: Schema.optionalKey(Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(BIRD_DOG_DIAGNOSTIC_MAX_LENGTH))),
+    waitingOnYou: Schema.optionalKey(Schema.Array(BirdDogWaitingItemSchema).check(Schema.isMinLength(1), Schema.isMaxLength(BIRD_DOG_WAITING_MAX_ITEMS))),
 });
 /** A terminal delivery failure, correlated by the original mail key only. */
 export const BirdDogUndeliverableReasonSchema = Schema.Literals([
     "recipient_offline",
     "recipient_left",
 ]);
+/** Parser for a terminal delivery failure reply. */
 export const UndeliverableBirdDogReplySchema = Schema.Struct({
     outcome: Schema.Literal("undeliverable"),
     reason: BirdDogUndeliverableReasonSchema,
@@ -52,11 +72,20 @@ export const AcceptedBirdDogReplySchema = Schema.Struct({
     outcome: Schema.Literal("accepted"),
     commandId: Identifier,
 });
+/** Parser for any reply: settled, accepted or undeliverable. */
 export const BirdDogReplySchema = Schema.Union([
     SettledBirdDogReplySchema,
     UndeliverableBirdDogReplySchema,
     AcceptedBirdDogReplySchema,
 ]);
+const BirdDogAgentReplySchema = Schema.Union([
+    SettledBirdDogReplySchema,
+    AcceptedBirdDogReplySchema,
+    Schema.Struct({
+        outcome: Schema.Literal("undeliverable"),
+        reason: Schema.Literal("recipient_left"),
+    }),
+]);
 const REDACTED = "[redacted]";
 // An authorization scheme's credential, e.g. `Bearer <token>`.
 const schemeCredential = /\b(bearer|basic)\s+[^\s"',;]+/giu;
@@ -93,18 +122,22 @@ const BirdDogMailFields = {
     /** The sender's opaque host metadata; BirdDog never reads it. */
     meta: Schema.optionalKey(Schema.Json),
 };
+/** Parser for addressed Agent mail, from an Agent or from the Hub system. */
 export const BirdDogMailSchema = Schema.Union([
     Schema.Struct({
         ...BirdDogMailFields,
         from: BirdDogAgentReferenceSchema,
         /** Settlement or acceptance facts, present only on a reply. */
-        reply: Schema.optionalKey(BirdDogReplySchema),
+        reply: Schema.optionalKey(BirdDogAgentReplySchema),
     }),
     Schema.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: Schema.Struct({
+            outcome: Schema.Literal("undeliverable"),
+            reason: Schema.Literal("recipient_offline"),
+        }),
     }),
 ]);
 /** Parser for accepted Session work. */
@@ -163,13 +196,23 @@ export const decodeAgentJob = (job) => Schema.decodeUnknownSync(BirdDogAgentJobP
 /**
  * Build the replies owed by one settlement for a host-owned Post transport.
  * Each reply carries the settled content verbatim (or, when there is none, one
- * sentence naming the outcome, so the reply is always admissible text) and its
- * settlement facts as typed fields; the recipient's host authenticates them and decides how they
- * are presented. A reply never carries the settled work's host metadata.
+ * sentence naming the outcome and its diagnostic, so the reply is always
+ * admissible text) and its settlement facts as typed fields; the recipient's
+ * host authenticates them and decides how they are presented. A reply never
+ * carries the settled work's host metadata.
+ *
+ * Work a delegator's mail admitted replies to that mail under its `:reply:`
+ * key. Any other settled work, whatever started its turn, is a report to the
+ * Session's delegator of record, when the host names one (it does so once the
+ * Session is idle), under the delegator mail's `:report:` key.
  */
 export function settlementReplies(settlement, createdAt) {
     const { work, mail } = decodeAgentJob(settlement.job);
-    if (mail === undefined)
+    const answered = mail !== undefined && mail.replyTo.length > 0;
+    const owed = answered
+        ? { key: mail.key, agentId: mail.to.agentId, replyTo: mail.replyTo }
+        : settlement.delegator;
+    if (owed === undefined)
         return [];
     const outcome = settlement.job.outcome;
     const diagnostic = outcome === "completed" ||
@@ -177,17 +220,29 @@ export function settlementReplies(settlement, createdAt) {
         settlement.diagnostic === undefined
         ? undefined
         : boundedDiagnostic(settlement.diagnostic);
-    const reply = Schema.decodeUnknownSync(BirdDogReplySchema)(diagnostic === undefined
-        ? { commandId: work.commandFactId, outcome }
-        : { commandId: work.commandFactId, outcome, diagnostic });
-    return mail.replyTo.map((destination, index) => ({
-        key: `${mail.key}:reply:${String(index)}`,
+    const facts = { commandId: work.commandFactId, outcome };
+    if (diagnostic !== undefined)
+        facts.diagnostic = diagnostic;
+    if (settlement.waitingOnYou !== undefined &&
+        settlement.waitingOnYou.length > 0)
+        facts.waitingOnYou = settlement.waitingOnYou;
+    const reply = Schema.decodeUnknownSync(SettledBirdDogReplySchema)(facts);
+    return owed.replyTo.map((destination, index) => ({
+        key: answered
+            ? `${owed.key}:reply:${String(index)}`
+            : `${owed.key}:report:${work.commandFactId}:${String(index)}`,
         to: destination,
-        from: { ...mail.to, sessionId: work.sessionId },
+        from: {
+            kind: "agent",
+            agentId: owed.agentId,
+            sessionId: work.sessionId,
+        },
         replyTo: [],
         content: settlement.content.length > 0
             ? settlement.content
-            : `The delegated work ended ${outcome} without reply text.`,
+            : `The delegated work ended ${outcome}${diagnostic === undefined
+                ? " without reply text."
+                : `: ${diagnostic}`}`,
         createdAt,
         reply,
     }));

package/dist/index.d.ts

@@ -12,6 +12,11 @@ export type BirdDogAgentRecipientReference = Readonly<{
     agentId: string;
     sessionId?: string;
 }>;
+/** The Hub's stable system identity for a terminal offline disposition. */
+export type BirdDogSystemIdentity = Readonly<{
+    kind: "system";
+    systemId: "hub";
+}>;
 /**
  * What a reply reports about the settled work beside its content. The
  * recipient's host trusts these facts only after it authenticates the reply
@@ -28,11 +33,23 @@ export type BirdDogReply = Readonly<{
     outcome: "completed" | "failed" | "interrupted" | "cancelled" | "outcome_unknown";
     /** Bounded terminal diagnostic for work that did not complete or cancel. */
     diagnostic?: string;
+    /** Open items of the replying Session that now wait on this recipient. */
+    waitingOnYou?: readonly BirdDogWaitingItem[];
 }> | Readonly<{
     outcome: "undeliverable";
     reason: "recipient_offline" | "recipient_left";
 }>;
-/** Addressed mail; an unstarted Agent may author only an undeliverable reply. */
+/** Facts an Agent may author; the Hub owns recipient-offline disposition. */
+export type BirdDogAgentReply = Exclude<BirdDogReply, {
+    outcome: "undeliverable";
+}> | Readonly<{
+    outcome: "undeliverable";
+    reason: "recipient_left";
+}>;
+/**
+ * Addressed correspondence. Agents author ordinary replies and recipient-left
+ * notices; only the Hub system authors recipient-offline dispositions.
+ */
 export type BirdDogMail = Readonly<{
     key: string;
     to: BirdDogAgentRecipientReference;
@@ -43,7 +60,7 @@ export type BirdDogMail = Readonly<{
     meta?: BirdDogMeta;
     from: BirdDogAgentReference;
     /** Settlement or acceptance facts, present only on a reply. */
-    reply?: BirdDogReply;
+    reply?: BirdDogAgentReply;
 }> | Readonly<{
     key: string;
     to: BirdDogAgentRecipientReference;
@@ -52,12 +69,15 @@ export type BirdDogMail = Readonly<{
     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, {
+    /** The Hub owns offline disposition authorship, not the recipient. */
+    from: BirdDogSystemIdentity;
+    reply: Readonly<{
         outcome: "undeliverable";
+        reason: "recipient_offline";
     }>;
 }>;
+/** Construct the one stable system reply correlated to the exact sent letter. */
+export declare function undeliverableReply(original: BirdDogMail, createdAt: number): BirdDogMail;
 /** Opaque JSON a host attached to the work; BirdDog only carries it. */
 export type BirdDogMeta = typeof Schema.Json.Type;
 /** The accepted Session work BirdDog points at from an opaque Watchdog job. */
@@ -107,10 +127,24 @@ export type BirdDogOptions = Readonly<{
     /** Return the host's current wall-clock time in milliseconds. */
     now: () => number;
 }>;
+/**
+ * Who sent a Session its work first: the mail that opened the relationship.
+ * `agentId` is the Session's own Agent, the author of every report.
+ */
+export type BirdDogDelegator = Readonly<{
+    key: string;
+    agentId: string;
+    replyTo: readonly BirdDogAgentReference[];
+}>;
 /** Completed generic work plus the content owed to its correspondents. */
 export type BirdDogSettlement = Readonly<{
     job: WatchdogSettledJob;
     content: string;
+    /**
+     * The Session's delegator of record, named only when this settlement leaves
+     * the Session idle. Work without a replying mail of its own reports to it.
+     */
+    delegator?: BirdDogDelegator;
     /**
      * The Session's recorded terminal diagnostic. Replies carry it, bounded by
      * `boundedDiagnostic`, only for failed, interrupted and outcome_unknown work.
@@ -121,6 +155,17 @@ export type BirdDogSettlement = Readonly<{
      * example, naming who cancelled). Replies never carry it.
      */
     meta?: BirdDogMeta;
+    /**
+     * Open items of the settled Session that now wait on the correspondent this
+     * work came from. Replies carry them beside the settlement facts.
+     */
+    waitingOnYou?: readonly BirdDogWaitingItem[];
+}>;
+/** One open item named by a reply as waiting on its recipient. */
+export type BirdDogWaitingItem = Readonly<{
+    itemId: string;
+    kind: string;
+    summary: string;
 }>;
 /** Durable reply delivery behind the mail-room interface. */
 export type BirdDogRuntime = Readonly<{

package/dist/index.js

@@ -1,5 +1,19 @@
 import { agentJobFromInput, decodeAgentJob } from "./effect.js";
 import { createPromiseBirdDog } from "./internal/promise-mail-room.js";
+/** Construct the one stable system reply correlated to the exact sent letter. */
+export function undeliverableReply(original, createdAt) {
+    if (original.reply !== undefined || original.from.kind !== "agent")
+        throw new Error("A reply cannot receive another undeliverable disposition");
+    return {
+        key: `${original.key}:reply:0`,
+        from: { kind: "system", systemId: "hub" },
+        to: original.from,
+        replyTo: [],
+        content: "undeliverable",
+        createdAt,
+        reply: { outcome: "undeliverable", reason: "recipient_offline" },
+    };
+}
 /** Agent-aware mail translation over Watchdog's payload-blind job grammar. */
 export const BirdDog = Object.freeze({
     agentJob: agentJobFromInput,

package/docs/api/effect.md

@@ -89,6 +89,7 @@ Effect host ports for the durable mail room.
 ```ts
 type BirdDogEffect = Readonly<{
   fanOut: (settlement) => Effect.Effect<void, BirdDogError>;
+  postMail?: (mail) => Effect.Effect<void, BirdDogError>;
   drainOutbox: () => Effect.Effect<void, BirdDogError>;
   nextWakeAt: () => Effect.Effect<number | undefined, BirdDogError>;
 }>;
@@ -98,6 +99,16 @@ Effect-native durable reply delivery.
 
 ## Variables
 
+### BIRD\_DOG\_MAIL\_CONTENT\_MAX\_BYTES
+
+```ts
+const BIRD_DOG_MAIL_CONTENT_MAX_BYTES: number;
+```
+
+The maximum UTF-8 size of one mail body.
+
+---
+
 ### BirdDogAgentReferenceSchema
 
 ```ts
@@ -112,6 +123,33 @@ Parser for an ordinary agent Session address.
 
 ---
 
+### BirdDogAgentRecipientReferenceSchema
+
+```ts
+const BirdDogAgentRecipientReferenceSchema: Struct<{
+  kind: Literal<"agent">;
+  agentId: String;
+  sessionId: optionalKey<String>;
+}>;
+```
+
+An addressed Agent may create its first Session when accepting this mail.
+
+---
+
+### BirdDogSystemIdentitySchema
+
+```ts
+const BirdDogSystemIdentitySchema: Struct<{
+  kind: Literal<"system">;
+  systemId: Literal<"hub">;
+}>;
+```
+
+The Hub's stable system identity for a terminal offline disposition.
+
+---
+
 ### BIRD\_DOG\_DIAGNOSTIC\_MAX\_LENGTH
 
 ```ts
@@ -122,10 +160,36 @@ The most characters a reply's failure diagnostic may carry.
 
 ---
 
-### BirdDogReplySchema
+### BIRD\_DOG\_WAITING\_MAX\_ITEMS
 
 ```ts
-const BirdDogReplySchema: Struct<{
+const BIRD_DOG_WAITING_MAX_ITEMS: 8 = 8;
+```
+
+The most open items one reply names as waiting on its recipient.
+
+---
+
+### BirdDogWaitingItemSchema
+
+```ts
+const BirdDogWaitingItemSchema: Struct<{
+  itemId: String;
+  kind: String;
+  summary: String;
+}>;
+```
+
+One open item of the replying Session that waits on this reply's recipient.
+BirdDog carries the three bounded fields; the replying host owns their meaning
+and the recipient host owns every decision about them.
+
+---
+
+### SettledBirdDogReplySchema
+
+```ts
+const SettledBirdDogReplySchema: Struct<{
   commandId: String;
   outcome: Literals<
     readonly [
@@ -137,41 +201,68 @@ const BirdDogReplySchema: Struct<{
     ]
   >;
   diagnostic: optionalKey<String>;
+  waitingOnYou: optionalKey<
+    $Array<
+      Struct<{
+        itemId: String;
+        kind: String;
+        summary: String;
+      }>
+    >
+  >;
 }>;
 ```
 
 Parser for the settlement facts a reply carries beside its content: the replying
-Session's command, its exact Watchdog outcome and, for work that did not
-complete, the Session's bounded terminal diagnostic.
+Session's command, its exact Watchdog outcome, for work that did not complete
+the Session's bounded terminal diagnostic and, when the replying host names any,
+the open items now waiting on the recipient.
 
 ---
 
-### BirdDogMailSchema
+### BirdDogUndeliverableReasonSchema
 
 ```ts
-const BirdDogMailSchema: Struct<{
-  key: String;
-  to: Struct<{
-    kind: Literal<"agent">;
-    agentId: String;
-    sessionId: String;
-  }>;
-  from: Struct<{
-    kind: Literal<"agent">;
-    agentId: String;
-    sessionId: String;
-  }>;
-  replyTo: $Array<
-    Struct<{
-      kind: Literal<"agent">;
-      agentId: String;
-      sessionId: String;
-    }>
-  >;
-  content: String;
-  createdAt: Number;
-  meta: optionalKey<Codec<Json, Json, never, never>>;
-  reply: optionalKey<
+const BirdDogUndeliverableReasonSchema: Literals<
+  readonly ["recipient_offline", "recipient_left"]
+>;
+```
+
+A terminal delivery failure, correlated by the original mail key only.
+
+---
+
+### UndeliverableBirdDogReplySchema
+
+```ts
+const UndeliverableBirdDogReplySchema: Struct<{
+  outcome: Literal<"undeliverable">;
+  reason: Literals<readonly ["recipient_offline", "recipient_left"]>;
+}>;
+```
+
+Parser for a terminal delivery failure reply.
+
+---
+
+### AcceptedBirdDogReplySchema
+
+```ts
+const AcceptedBirdDogReplySchema: Struct<{
+  outcome: Literal<"accepted">;
+  commandId: String;
+}>;
+```
+
+Recipient acceptance, before the command has settled.
+
+---
+
+### BirdDogReplySchema
+
+```ts
+const BirdDogReplySchema: Union<
+  readonly [
     Struct<{
       commandId: String;
       outcome: Literals<
@@ -184,12 +275,94 @@ const BirdDogMailSchema: Struct<{
         ]
       >;
       diagnostic: optionalKey<String>;
-    }>
-  >;
-}>;
+      waitingOnYou: optionalKey<
+        $Array<
+          Struct<{
+            itemId: String;
+            kind: String;
+            summary: String;
+          }>
+        >
+      >;
+    }>,
+    Struct<{
+      outcome: Literal<"undeliverable">;
+      reason: Literals<readonly ["recipient_offline", "recipient_left"]>;
+    }>,
+    Struct<{
+      outcome: Literal<"accepted">;
+      commandId: String;
+    }>,
+  ]
+>;
+```
+
+Parser for any reply: settled, accepted or undeliverable.
+
+---
+
+### BirdDogMailSchema
+
+```ts
+const BirdDogMailSchema: Union<readonly [Struct<{
+  key: String;
+  to: Struct<{
+     kind: Literal<"agent">;
+     agentId: String;
+     sessionId: optionalKey<String>;
+  }>;
+  replyTo: $Array<Struct<{
+     kind: Literal<"agent">;
+     agentId: String;
+     sessionId: String;
+  }>>;
+  content: String;
+  createdAt: Number;
+  meta: optionalKey<Codec<Json, Json, never, never>>;
+  from: Struct<{
+     kind: Literal<"agent">;
+     agentId: String;
+     sessionId: String;
+  }>;
+  reply: optionalKey<Union<readonly [Struct<{
+     commandId: String;
+     outcome: Literals<readonly [..., ..., ..., ..., ...]>;
+     diagnostic: optionalKey<String>;
+     waitingOnYou: optionalKey<$Array<...>>;
+   }>, Struct<{
+     outcome: Literal<"accepted">;
+     commandId: String;
+   }>, Struct<{
+     outcome: Literal<"undeliverable">;
+     reason: Literal<"recipient_left">;
+  }>]>>;
+}>, Struct<{
+  key: String;
+  to: Struct<{
+     kind: Literal<"agent">;
+     agentId: String;
+     sessionId: optionalKey<String>;
+  }>;
+  replyTo: $Array<Struct<{
+     kind: Literal<"agent">;
+     agentId: String;
+     sessionId: String;
+  }>>;
+  content: String;
+  createdAt: Number;
+  meta: optionalKey<Codec<Json, Json, never, never>>;
+  from: Struct<{
+     kind: Literal<"system">;
+     systemId: Literal<"hub">;
+  }>;
+  reply: Struct<{
+     outcome: Literal<"undeliverable">;
+     reason: Literal<"recipient_offline">;
+  }>;
+}>]>;
 ```
 
-Parser for addressed agent correspondence.
+Parser for addressed Agent mail, from an Agent or from the Hub system.
 
 ---
 
@@ -217,49 +390,54 @@ Parser for accepted Session work.
 ```ts
 const BirdDogAgentJobPayloadSchema: Struct<{
   work: Struct<{
-    sessionId: String;
-    commandFactId: String;
+     sessionId: String;
+     commandFactId: String;
   }>;
-  mail: optional<
-    Struct<{
-      key: String;
-      to: Struct<{
+  mail: optional<Union<readonly [Struct<{
+     key: String;
+     to: Struct<{
         kind: Literal<"agent">;
         agentId: String;
+        sessionId: optionalKey<String>;
+     }>;
+     replyTo: $Array<Struct<{
+        kind: Literal<...>;
+        agentId: String;
         sessionId: String;
-      }>;
-      from: Struct<{
+     }>>;
+     content: String;
+     createdAt: Number;
+     meta: optionalKey<Codec<Json, Json, never, never>>;
+     from: Struct<{
         kind: Literal<"agent">;
         agentId: String;
         sessionId: String;
-      }>;
-      replyTo: $Array<
-        Struct<{
-          kind: Literal<"agent">;
-          agentId: String;
-          sessionId: String;
-        }>
-      >;
-      content: String;
-      createdAt: Number;
-      meta: optionalKey<Codec<Json, Json, never, never>>;
-      reply: optionalKey<
-        Struct<{
-          commandId: String;
-          outcome: Literals<
-            readonly [
-              "completed",
-              "failed",
-              "interrupted",
-              "cancelled",
-              "outcome_unknown",
-            ]
-          >;
-          diagnostic: optionalKey<String>;
-        }>
-      >;
-    }>
-  >;
+     }>;
+     reply: optionalKey<Union<readonly [Struct<...>, Struct<...>, Struct<...>]>>;
+   }>, Struct<{
+     key: String;
+     to: Struct<{
+        kind: Literal<"agent">;
+        agentId: String;
+        sessionId: optionalKey<String>;
+     }>;
+     replyTo: $Array<Struct<{
+        kind: Literal<...>;
+        agentId: String;
+        sessionId: String;
+     }>>;
+     content: String;
+     createdAt: Number;
+     meta: optionalKey<Codec<Json, Json, never, never>>;
+     from: Struct<{
+        kind: Literal<"system">;
+        systemId: Literal<"hub">;
+     }>;
+     reply: Struct<{
+        outcome: Literal<"undeliverable">;
+        reason: Literal<"recipient_offline">;
+     }>;
+  }>]>>;
 }>;
 ```
 
@@ -272,55 +450,58 @@ Parser for the payload that Watchdog stores without interpretation.
 ```ts
 const BirdDogAgentJobInputSchema: Struct<{
   work: Struct<{
-    jobId: String;
-    sessionId: String;
-    commandFactId: String;
-    recovery: optional<
-      Struct<{
+     jobId: String;
+     sessionId: String;
+     commandFactId: String;
+     recovery: optional<Struct<{
         maxRecoveries: Int;
-      }>
-    >;
+     }>>;
   }>;
-  mail: optional<
-    Struct<{
-      key: String;
-      to: Struct<{
+  mail: optional<Union<readonly [Struct<{
+     key: String;
+     to: Struct<{
         kind: Literal<"agent">;
         agentId: String;
+        sessionId: optionalKey<String>;
+     }>;
+     replyTo: $Array<Struct<{
+        kind: Literal<...>;
+        agentId: String;
         sessionId: String;
-      }>;
-      from: Struct<{
+     }>>;
+     content: String;
+     createdAt: Number;
+     meta: optionalKey<Codec<Json, Json, never, never>>;
+     from: Struct<{
         kind: Literal<"agent">;
         agentId: String;
         sessionId: String;
-      }>;
-      replyTo: $Array<
-        Struct<{
-          kind: Literal<"agent">;
-          agentId: String;
-          sessionId: String;
-        }>
-      >;
-      content: String;
-      createdAt: Number;
-      meta: optionalKey<Codec<Json, Json, never, never>>;
-      reply: optionalKey<
-        Struct<{
-          commandId: String;
-          outcome: Literals<
-            readonly [
-              "completed",
-              "failed",
-              "interrupted",
-              "cancelled",
-              "outcome_unknown",
-            ]
-          >;
-          diagnostic: optionalKey<String>;
-        }>
-      >;
-    }>
-  >;
+     }>;
+     reply: optionalKey<Union<readonly [Struct<...>, Struct<...>, Struct<...>]>>;
+   }>, Struct<{
+     key: String;
+     to: Struct<{
+        kind: Literal<"agent">;
+        agentId: String;
+        sessionId: optionalKey<String>;
+     }>;
+     replyTo: $Array<Struct<{
+        kind: Literal<...>;
+        agentId: String;
+        sessionId: String;
+     }>>;
+     content: String;
+     createdAt: Number;
+     meta: optionalKey<Codec<Json, Json, never, never>>;
+     from: Struct<{
+        kind: Literal<"system">;
+        systemId: Literal<"hub">;
+     }>;
+     reply: Struct<{
+        outcome: Literal<"undeliverable">;
+        reason: Literal<"recipient_offline">;
+     }>;
+  }>]>>;
 }>;
 ```
 
@@ -406,35 +587,20 @@ Decode the opaque payload at BirdDog's side of the Watchdog seam.
 ### settlementReplies()
 
 ```ts
-function settlementReplies(
-  settlement,
-  createdAt,
-): readonly Readonly<{
-  key: string;
-  to: BirdDogAgentReference;
-  from: BirdDogAgentReference;
-  replyTo: readonly Readonly<{
-    kind: "agent";
-    agentId: string;
-    sessionId: string;
-  }>[];
-  content: string;
-  createdAt: number;
-  meta?: Json;
-  reply?: Readonly<{
-    commandId: string;
-    outcome:
-      "failed" | "completed" | "interrupted" | "cancelled" | "outcome_unknown";
-    diagnostic?: string;
-  }>;
-}>[];
+function settlementReplies(settlement, createdAt): readonly BirdDogMail[];
 ```
 
 Build the replies owed by one settlement for a host-owned Post transport. Each
 reply carries the settled content verbatim (or, when there is none, one sentence
-naming the outcome, so the reply is always admissible text) and its settlement
-facts as typed fields; the recipient's host authenticates them and decides how
-they are presented. A reply never carries the settled work's host metadata.
+naming the outcome and its diagnostic, so the reply is always admissible text)
+and its settlement facts as typed fields; the recipient's host authenticates
+them and decides how they are presented. A reply never carries the settled
+work's host metadata.
+
+Work a delegator's mail admitted replies to that mail under its `:reply:` key.
+Any other settled work, whatever started its turn, is a report to the Session's
+delegator of record, when the host names one (it does so once the Session is
+idle), under the delegator mail's `:report:` key.
 
 #### Parameters
 
@@ -445,14 +611,30 @@ they are presented. A reply never carries the settled work's host metadata.
 
 #### Returns
 
-readonly `Readonly`\<\{ `key`: `string`; `to`:
-[`BirdDogAgentReference`](index.md#birddogagentreference); `from`:
-[`BirdDogAgentReference`](index.md#birddogagentreference); `replyTo`: readonly
-`Readonly`\<\{ `kind`: `"agent"`; `agentId`: `string`; `sessionId`: `string`;
-\}\>[]; `content`: `string`; `createdAt`: `number`; `meta?`: `Json`; `reply?`:
-`Readonly`\<\{ `commandId`: `string`; `outcome`: `"failed"` \| `"completed"` \|
-`"interrupted"` \| `"cancelled"` \| `"outcome_unknown"`; `diagnostic?`:
-`string`; \}\>; \}\>[]
+readonly [`BirdDogMail`](index.md#birddogmail)[]
+
+---
+
+### acceptedNotice()
+
+```ts
+function acceptedNotice(mail, sessionId, commandId, createdAt): BirdDogMail;
+```
+
+Build the recipient's one stable acceptance notice for one original mail.
+
+#### Parameters
+
+| Parameter   | Type                                  |
+| ----------- | ------------------------------------- |
+| `mail`      | [`BirdDogMail`](index.md#birddogmail) |
+| `sessionId` | `string`                              |
+| `commandId` | `string`                              |
+| `createdAt` | `number`                              |
+
+#### Returns
+
+[`BirdDogMail`](index.md#birddogmail)
 
 ---
 
@@ -483,6 +665,7 @@ Delivered receipts and exhausted dead letters stay but owe nothing.
 function make(options): Effect<
   Readonly<{
     fanOut: (settlement) => Effect<void, BirdDogError>;
+    postMail?: (mail) => Effect<void, BirdDogError>;
     drainOutbox: () => Effect<void, BirdDogError>;
     nextWakeAt: () => Effect<number | undefined, BirdDogError>;
   }>
@@ -500,6 +683,7 @@ Construct BirdDog's Effect-native mail room over Post's shared outbox.
 #### Returns
 
 `Effect`\<`Readonly`\<\{ `fanOut`: (`settlement`) => `Effect`\<`void`,
+[`BirdDogError`](#birddogerror)\>; `postMail?`: (`mail`) => `Effect`\<`void`,
 [`BirdDogError`](#birddogerror)\>; `drainOutbox`: () => `Effect`\<`void`,
 [`BirdDogError`](#birddogerror)\>; `nextWakeAt`: () => `Effect`\<`number` \|
 `undefined`, [`BirdDogError`](#birddogerror)\>; \}\>\>

package/docs/api/index.md

@@ -24,42 +24,118 @@ An ordinary agent Session address. Relationships between agents live elsewhere.
 
 ---
 
-### BirdDogMail
+### BirdDogAgentRecipientReference
 
 ```ts
-type BirdDogMail = Readonly<{
-  key: string;
-  to: BirdDogAgentReference;
-  from: BirdDogAgentReference;
-  replyTo: readonly BirdDogAgentReference[];
-  content: string;
-  createdAt: number;
-  meta?: BirdDogMeta;
-  reply?: BirdDogReply;
+type BirdDogAgentRecipientReference = Readonly<{
+  kind: "agent";
+  agentId: string;
+  sessionId?: string;
 }>;
 ```
 
-Addressed agent correspondence carried with durable work when a reply is owed.
+An addressed Agent whose first Session may be created on acceptance.
 
 ---
 
-### BirdDogReply
+### BirdDogSystemIdentity
 
 ```ts
-type BirdDogReply = Readonly<{
-  commandId: string;
-  outcome:
-    "completed" | "failed" | "interrupted" | "cancelled" | "outcome_unknown";
-  diagnostic?: string;
+type BirdDogSystemIdentity = Readonly<{
+  kind: "system";
+  systemId: "hub";
 }>;
 ```
 
+The Hub's stable system identity for a terminal offline disposition.
+
+---
+
+### BirdDogReply
+
+```ts
+type BirdDogReply =
+  | Readonly<{
+      commandId: string;
+      outcome: "accepted";
+    }>
+  | Readonly<{
+      commandId: string;
+      outcome:
+        | "completed"
+        | "failed"
+        | "interrupted"
+        | "cancelled"
+        | "outcome_unknown";
+      diagnostic?: string;
+      waitingOnYou?: readonly BirdDogWaitingItem[];
+    }>
+  | Readonly<{
+      outcome: "undeliverable";
+      reason: "recipient_offline" | "recipient_left";
+    }>;
+```
+
 What a reply reports about the settled work beside its content. The recipient's
 host trusts these facts only after it authenticates the reply against the mail
 it sent.
 
 ---
 
+### BirdDogAgentReply
+
+```ts
+type BirdDogAgentReply =
+  | Exclude<
+      BirdDogReply,
+      {
+        outcome: "undeliverable";
+      }
+    >
+  | Readonly<{
+      outcome: "undeliverable";
+      reason: "recipient_left";
+    }>;
+```
+
+Facts an Agent may author; the Hub owns recipient-offline disposition.
+
+---
+
+### BirdDogMail
+
+```ts
+type BirdDogMail =
+  | Readonly<{
+      key: string;
+      to: BirdDogAgentRecipientReference;
+      replyTo: readonly BirdDogAgentReference[];
+      content: string;
+      createdAt: number;
+      meta?: BirdDogMeta;
+      from: BirdDogAgentReference;
+      reply?: BirdDogAgentReply;
+    }>
+  | Readonly<{
+      key: string;
+      to: BirdDogAgentRecipientReference;
+      replyTo: readonly BirdDogAgentReference[];
+      content: string;
+      createdAt: number;
+      meta?: BirdDogMeta;
+      from: BirdDogSystemIdentity;
+      reply: Readonly<{
+        outcome: "undeliverable";
+        reason: "recipient_offline";
+      }>;
+    }>;
+```
+
+Addressed correspondence. Agents author ordinary replies and recipient-left
+notices; only the Hub system authors recipient-offline dispositions.
+
+---
+
 ### BirdDogMeta
 
 ```ts
@@ -154,14 +230,31 @@ Host ports for BirdDog's durable mail delivery.
 
 ---
 
+### BirdDogDelegator
+
+```ts
+type BirdDogDelegator = Readonly<{
+  key: string;
+  agentId: string;
+  replyTo: readonly BirdDogAgentReference[];
+}>;
+```
+
+Who sent a Session its work first: the mail that opened the relationship.
+`agentId` is the Session's own Agent, the author of every report.
+
+---
+
 ### BirdDogSettlement
 
 ```ts
 type BirdDogSettlement = Readonly<{
   job: WatchdogSettledJob;
   content: string;
+  delegator?: BirdDogDelegator;
   diagnostic?: string;
   meta?: BirdDogMeta;
+  waitingOnYou?: readonly BirdDogWaitingItem[];
 }>;
 ```
 
@@ -169,6 +262,20 @@ Completed generic work plus the content owed to its correspondents.
 
 ---
 
+### BirdDogWaitingItem
+
+```ts
+type BirdDogWaitingItem = Readonly<{
+  itemId: string;
+  kind: string;
+  summary: string;
+}>;
+```
+
+One open item named by a reply as waiting on its recipient.
+
+---
+
 ### BirdDogRuntime
 
 ```ts
@@ -203,3 +310,24 @@ const BirdDog: BirdDogApi;
 ```
 
 Agent-aware mail translation over Watchdog's payload-blind job grammar.
+
+## Functions
+
+### undeliverableReply()
+
+```ts
+function undeliverableReply(original, createdAt): BirdDogMail;
+```
+
+Construct the one stable system reply correlated to the exact sent letter.
+
+#### Parameters
+
+| Parameter   | Type                          |
+| ----------- | ----------------------------- |
+| `original`  | [`BirdDogMail`](#birddogmail) |
+| `createdAt` | `number`                      |
+
+#### Returns
+
+[`BirdDogMail`](#birddogmail)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fungi.computer/bird-dog",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "author": "Levi <levi@technomancy.dev>",
   "description": "Durable addressed agent mail over generic Watchdog work",
   "type": "module",