@fungi.computer/bird-dog 0.2.0 → 0.2.1

package/dist/effect.d.ts

@@ -16,6 +16,11 @@ 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;
 /**
@@ -69,12 +74,12 @@ 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"]>;
     }>, 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 +97,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 +146,12 @@ 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"]>;
         }>, 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 +169,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 +214,12 @@ 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"]>;
         }>, 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 +237,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<{

package/dist/effect.js

@@ -20,6 +20,11 @@ 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;
 /**
@@ -57,6 +62,14 @@ export const BirdDogReplySchema = Schema.Union([
     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;
@@ -98,13 +111,16 @@ export const BirdDogMailSchema = Schema.Union([
         ...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. */
@@ -177,7 +193,7 @@ 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) => ({

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
@@ -32,7 +37,17 @@ export type BirdDogReply = 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 +58,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 +67,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. */

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.2.0",
+  "version": "0.2.1",
   "author": "Levi <levi@technomancy.dev>",
   "description": "Durable addressed agent mail over generic Watchdog work",
   "type": "module",