@fungi.computer/bird-dog 0.2.1 → 0.3.1

package/README.md

@@ -74,6 +74,7 @@ const room = await BirdDog.make({
 
 // 1. Turn accepted work into a Watchdog job. Hand this to Watchdog's ingest.
 const job = BirdDog.agentJob({
+  delivery: "followUp",
   work: {
     jobId: "job-1",
     sessionId: child.sessionId,
@@ -114,14 +115,14 @@ are 1 to 256 characters. There is no special kind for subagents.
 must identify the request across retries. BirdDog derives every reply key from
 it.
 
-**Agent jobs.** `BirdDog.agentJob({ work, mail? })` validates the input and
-returns a queued Watchdog job. The job's `queue` is the target `sessionId`, its
-lane is `default`, its priority is `0`, and its payload carries the `sessionId`,
-the `commandFactId` and the optional mail. `work.recovery` passes straight
-through to Watchdog's recovery policy. Because it is synchronous, you can call
-it inside an owner transaction and pass the result to Watchdog's
-`transactional.enqueueAcceptedJob`. `BirdDog.decodeAgentJob(job)` parses the
-payload back on the executor side. Watchdog never reads it.
+**Agent jobs.** `BirdDog.agentJob({ work, delivery, mail? })` validates the
+input and returns a queued Watchdog job. The job's `queue` is the target
+`sessionId`, its lane is `default`, its priority is `0`, and its payload carries
+the `sessionId`, the `commandFactId` and the optional mail. `work.recovery`
+passes straight through to Watchdog's recovery policy. Because it is
+synchronous, you can call it inside an owner transaction and pass the result to
+Watchdog's `transactional.enqueueAcceptedJob`. `BirdDog.decodeAgentJob(job)`
+parses the payload back on the executor side. Watchdog never reads it.
 
 **Fan-out.** `fanOut({ job, content, diagnostic? })` takes a settled job, the
 content owed to correspondents and the Session's terminal diagnostic. It writes

package/dist/effect.d.ts

@@ -23,18 +23,37 @@ export declare const BirdDogSystemIdentitySchema: Schema.Struct<{
 }>;
 /** 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"]>;
@@ -44,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"]>;
@@ -63,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">;
@@ -74,6 +100,11 @@ 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>;
+        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;
@@ -146,6 +177,11 @@ 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>;
+            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;
@@ -203,6 +239,7 @@ export declare const BirdDogAgentJobInputSchema: Schema.Struct<{
             readonly maxRecoveries: Schema.Int;
         }>>;
     }>;
+    readonly delivery: Schema.Literals<readonly ["steer", "followUp"]>;
     readonly mail: Schema.optional<Schema.Union<readonly [Schema.Struct<{
         readonly from: Schema.Struct<{
             readonly kind: Schema.Literal<"agent">;
@@ -214,6 +251,11 @@ 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>;
+            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;
@@ -307,9 +349,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

@@ -27,10 +27,23 @@ export const BirdDogSystemIdentitySchema = Schema.Struct({
 });
 /** 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,
@@ -42,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,
@@ -57,6 +72,7 @@ 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,
@@ -106,6 +122,7 @@ 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,
@@ -143,6 +160,7 @@ export const BirdDogAgentJobPayloadSchema = Schema.Struct({
 /** Parser for accepted work entering BirdDog's transactional projection. */
 export const BirdDogAgentJobInputSchema = Schema.Struct({
     work: BirdDogAgentWorkSchema,
+    delivery: Schema.Literals(["steer", "followUp"]),
     mail: Schema.optional(BirdDogMailSchema),
 });
 /** BirdDog could not complete one owned store or transport operation. */
@@ -166,7 +184,7 @@ export const agentJobFromInput = (input) => {
         jobId: accepted.work.jobId,
         queue: accepted.work.sessionId,
         lane: "default",
-        priority: 0,
+        priority: accepted.delivery === "steer" ? 1 : 0,
         payload,
         state: "queued",
     };
@@ -179,13 +197,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" ||
@@ -193,17 +221,29 @@ export function settlementReplies(settlement, createdAt) {
         settlement.diagnostic === undefined
         ? undefined
         : boundedDiagnostic(settlement.diagnostic);
-    const reply = Schema.decodeUnknownSync(SettledBirdDogReplySchema)(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

@@ -33,6 +33,8 @@ 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";
@@ -98,6 +100,7 @@ export type BirdDogAgentJobPayload = Readonly<{
 /** Input for projecting accepted agent work into Watchdog's generic grammar. */
 export type BirdDogAgentJobInput = Readonly<{
     work: BirdDogAgentWork;
+    delivery: "steer" | "followUp";
     mail?: BirdDogMail | undefined;
 }>;
 /** String-backed durable outbox owned by the BirdDog host. */
@@ -125,10 +128,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.
@@ -139,6 +156,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/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.1",
+  "version": "0.3.1",
   "author": "Levi <levi@technomancy.dev>",
   "description": "Durable addressed agent mail over generic Watchdog work",
   "type": "module",