@fungi.computer/bird-dog 0.1.0 → 0.2.1

package/dist/effect.d.ts

@@ -2,12 +2,25 @@ 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 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;
 /**
@@ -15,11 +28,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 +63,53 @@ 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<"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<{
         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<"system">;
+        readonly systemId: Schema.Literal<"hub">;
+    }>;
+    /** Only the Hub may author this offline disposition. */
+    readonly reply: Schema.Struct<{
+        readonly outcome: Schema.Literal<"undeliverable">;
+        readonly reason: Schema.Literal<"recipient_offline">;
+    }>;
+    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 +118,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 +135,53 @@ 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<"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<{
             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<"system">;
+            readonly systemId: Schema.Literal<"hub">;
+        }>;
+        /** Only the Hub may author this offline disposition. */
+        readonly reply: Schema.Struct<{
+            readonly outcome: Schema.Literal<"undeliverable">;
+            readonly reason: Schema.Literal<"recipient_offline">;
+        }>;
+        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 +190,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 +203,53 @@ 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<"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<{
             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<"system">;
+            readonly systemId: Schema.Literal<"hub">;
+        }>;
+        /** Only the Hub may author this offline disposition. */
+        readonly reply: Schema.Struct<{
+            readonly outcome: Schema.Literal<"undeliverable">;
+            readonly reason: Schema.Literal<"recipient_offline">;
+        }>;
+        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 +258,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,6 +293,8 @@ 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. */
@@ -189,6 +312,8 @@ 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.

package/dist/effect.js

@@ -2,12 +2,29 @@ import * as Effect from "effect/Effect";
 import * as Schema from "effect/Schema";
 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 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;
 /**
@@ -15,7 +32,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 +43,33 @@ 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 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;
@@ -53,18 +97,32 @@ 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(BirdDogAgentReplySchema),
+    }),
+    Schema.Struct({
+        ...BirdDogMailFields,
+        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. */
 export const BirdDogAgentWorkSchema = Schema.Struct({
     jobId: Identifier,
@@ -135,13 +193,13 @@ export function settlementReplies(settlement, createdAt) {
         settlement.diagnostic === undefined
         ? undefined
         : boundedDiagnostic(settlement.diagnostic);
-    const reply = Schema.decodeUnknownSync(BirdDogReplySchema)(diagnostic === undefined
+    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)}`,
         to: destination,
-        from: mail.to,
+        from: { ...mail.to, sessionId: work.sessionId },
         replyTo: [],
         content: settlement.content.length > 0
             ? settlement.content
@@ -150,6 +208,24 @@ 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.
@@ -182,8 +258,16 @@ export const make = (options) => {
         if (wake !== undefined)
             yield* options.scheduleWake(wake);
     });
+    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,16 @@ 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;
+}>;
+/** 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
@@ -25,13 +23,59 @@ 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";
+}>;
+/** 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;
+    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?: BirdDogAgentReply;
+}> | Readonly<{
+    key: string;
+    to: BirdDogAgentRecipientReference;
+    replyTo: readonly BirdDogAgentReference[];
+    content: string;
+    createdAt: number;
+    /** The sender's opaque host metadata; BirdDog never reads it. */
+    meta?: BirdDogMeta;
+    /** 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. */

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/package.json

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