@fungi.computer/bird-dog 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jamstack Consulting LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,259 @@
-# Temporary Holding Version
+# BirdDog (`@fungi.computer/bird-dog`)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+BirdDog is a durable mail room for AI agents. One agent sends work to another
+agent's session, the work runs as a [Watchdog](../watchdog/README.md) job, and
+when that job settles BirdDog delivers the reply to everyone on the envelope's
+`replyTo` list. Replies sit in a durable outbox and retry on a bounded schedule
+until the recipient accepts them.
+
+It does two jobs:
+
+- It translates addressed agent work into an opaque Watchdog job, and decodes
+  that job's payload back after Watchdog claims it.
+- It fans out replies when the job settles, stores them in your outbox, and
+  delivers them with retries through Carrier's Post outbox
+  ([`@fungi.computer/carrier/post`](../carrier/README.md)).
+
+Every sender and recipient is an ordinary agent session. A parent and a child
+agent are both plain agents to BirdDog. Their relationship lives in your code,
+and all agent work uses Watchdog's `default` lane. You own storage, transport,
+the clock and wake scheduling. BirdDog owns the envelope format, the reply keys
+and the retry schedule.
+
+## Install or set up
+
+```sh
+npm install @fungi.computer/bird-dog
+```
+
+BirdDog is ESM-only. It depends on `@fungi.computer/watchdog`,
+`@fungi.computer/carrier` and `effect`, which npm installs for you. It does no
+I/O of its own, so it runs in Node, Cloudflare Workers or any runtime that can
+give it an outbox and a `post` function.
+
+Entrypoints:
+
+- `@fungi.computer/bird-dog`: the Promise API on `BirdDog` and its types.
+- `@fungi.computer/bird-dog/effect`: the Effect-native mail room (`make`),
+  `settlementReplies`, the Effect Schema parsers and `BirdDogError`.
+  `settlementReplies` builds the same reply envelopes for a host-owned Post
+  transport.
+
+## Quick start
+
+This sends work from a parent agent to a child agent, settles it, and delivers
+the reply. The outbox uses Carrier’s deterministic memory helper, and `post`
+prints the reply instead of sending it anywhere.
+
+```ts
+import { BirdDog, type BirdDogMail } from "@fungi.computer/bird-dog";
+import { createMemoryOutbox } from "@fungi.computer/carrier/testing";
+
+const parent = {
+  kind: "agent",
+  agentId: "parent",
+  sessionId: "parent-session",
+} as const;
+const child = {
+  kind: "agent",
+  agentId: "child",
+  sessionId: "child-session",
+} as const;
+
+const room = await BirdDog.make({
+  outbox: createMemoryOutbox(),
+  post: async (mail: BirdDogMail) => {
+    console.log(`to ${mail.to.agentId}:\n${mail.content}`);
+    return true; // the recipient accepted it
+  },
+  scheduleWake: async (at) => {
+    console.log(`wake me at ${at}`);
+  },
+  now: () => Date.now(),
+});
+
+// 1. Turn accepted work into a Watchdog job. Hand this to Watchdog's ingest.
+const job = BirdDog.agentJob({
+  work: {
+    jobId: "job-1",
+    sessionId: child.sessionId,
+    commandFactId: "command-1",
+  },
+  mail: {
+    key: "delegation-1",
+    to: child,
+    from: parent,
+    replyTo: [parent],
+    content: "Find out why the build is red",
+    createdAt: Date.now(),
+  },
+});
+
+// 2. Your Watchdog executor decodes the payload and runs the child's work.
+const payload = BirdDog.decodeAgentJob(job);
+console.log(payload.work.commandFactId); // "command-1"
+
+// 3. When Watchdog settles the job, queue the replies, then deliver them.
+await room.fanOut({
+  job: { ...job, state: "settled", outcome: "completed" },
+  content: "A test fixture was missing. Fixed it.",
+});
+await room.drainOutbox();
+```
+
+In a real host, the settled job comes from Watchdog's `tick()` result and
+`drainOutbox()` runs from the wake you scheduled.
+
+## Core concepts
+
+**Addresses.** An agent address is `{ kind: "agent", agentId, sessionId }`. IDs
+are 1 to 256 characters. There is no special kind for subagents.
+
+**Mail.** A `BirdDogMail` has a stable `key`, a `to` and `from` address, a
+`replyTo` list, string `content` and a `createdAt` time in milliseconds. The key
+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.
+
+**Fan-out.** `fanOut({ job, content, diagnostic? })` takes a settled job, the
+content owed to correspondents and the Session's terminal diagnostic. It writes
+one reply per `replyTo` address into the outbox, keyed
+`outbox:<mail key>:reply:<index>`, then schedules one wake for the earliest.
+Each reply's `from` is the mail's recipient, its `content` is your content
+verbatim (or, when it is empty,
+`The delegated work ended <outcome> without reply text.`, so a reply is always
+admissible text), and its typed `reply` field carries the settlement facts:
+
+```ts
+{
+  commandId: "command-1", // the settled work's commandFactId
+  outcome: "failed", // the exact Watchdog outcome
+  diagnostic: "provider_error: 401 Authorization: Bearer [redacted]",
+}
+```
+
+`outcome` is exactly the job's: `completed`, `failed`, `interrupted`,
+`cancelled` or `outcome_unknown`. Only `failed`, `interrupted` and
+`outcome_unknown` replies carry a diagnostic. `boundedDiagnostic` makes it one
+line, masks credential-shaped values (authorization-scheme credentials, named
+keys, tokens, secrets and passwords, and long letter-and-digit runs), then cuts
+it to `BIRD_DOG_DIAGNOSTIC_MAX_LENGTH` (200) characters. A `cancelled` job
+delivers the supplied cancellation result as its content. A settlement's `meta`
+is for your own fan-out wrapper, such as naming who cancelled; replies never
+carry it. A job without mail sends nothing.
+
+The recipient's host owns authentication and presentation. It trusts the `reply`
+facts only after checking the reply against the mail it sent, then decides who
+authors the line and how its model sees it.
+
+**Draining.** `drainOutbox()` reads one page of up to 64 outbox rows and calls
+`post` for each due reply. `post` returns `true` when the recipient accepts the
+mail. A `false` or a throw schedules a retry. If more rows remain, BirdDog
+schedules an immediate wake and continues from the same place on the next drain.
+
+**Receipts.** A delivered reply's row is replaced by a compact completion
+receipt under the same key. Replaying the same settlement after a restart finds
+the receipt and does not post the reply again. Keep those receipts as long as
+source settlements can replay. BirdDog does not expire them.
+
+**Host ports.** `BirdDog.make` takes four things:
+
+- `outbox`: string rows with `put`, `read`, ordered `list(limit, afterKey?)` and
+  `delete`. Use the same key ordering for sorting and the exclusive `afterKey`
+  filter so paging cannot skip or repeat rows.
+- `post(mail)`: delivers one reply and reports acceptance.
+- `scheduleWake(at)`: arms a durable timer for `drainOutbox`.
+- `now()`: the current time in milliseconds.
+
+## API reference
+
+The generated reference is in [docs/api](docs/api/README.md).
+
+- `@fungi.computer/bird-dog`: `BirdDog` with `agentJob`, `decodeAgentJob` and
+  `make`, plus the `BirdDogMail`, `BirdDogAgentReference`, `BirdDogAgentWork`,
+  `BirdDogAgentJobPayload`, `BirdDogReply`, `BirdDogOutbox`, `BirdDogOptions`,
+  `BirdDogSettlement` and `BirdDogRuntime` types.
+- `@fungi.computer/bird-dog/effect`: `make`, `agentJobFromInput`,
+  `decodeAgentJob`, `settlementReplies`, `boundedDiagnostic`,
+  `BIRD_DOG_DIAGNOSTIC_MAX_LENGTH`, `BirdDogError`, `EffectBirdDogOptions`,
+  `BirdDogEffect` and the schemas `BirdDogAgentReferenceSchema`,
+  `BirdDogReplySchema`, `BirdDogMailSchema`, `BirdDogAgentWorkSchema`,
+  `BirdDogAgentJobPayloadSchema` and `BirdDogAgentJobInputSchema`.
+
+## Examples and checks
+
+The Effect entrypoint takes the same ports as Effect values:
+
+```ts
+import * as Effect from "effect/Effect";
+import { make } from "@fungi.computer/bird-dog/effect";
+
+const room = await Effect.runPromise(
+  make({
+    outbox: {
+      put: () => Effect.void,
+      read: () => Effect.succeed(undefined),
+      list: () => Effect.succeed([]),
+      delete: () => Effect.void,
+    },
+    post: () => Effect.succeed(true),
+    scheduleWake: () => Effect.void,
+    now: () => Date.now(),
+  }),
+);
+await Effect.runPromise(room.drainOutbox());
+```
+
+Use the schemas to parse mail that arrives from outside your process:
+
+```ts
+import * as Schema from "effect/Schema";
+import { BirdDogMailSchema } from "@fungi.computer/bird-dog/effect";
+
+const mail = Schema.decodeUnknownSync(BirdDogMailSchema)(JSON.parse(body));
+```
+
+The package tests cover job translation, payload decoding, replayed settlement
+after a restart, explicit cancellation replies, exact failure outcomes with
+bounded and redacted diagnostics, retry re-arming after reopen, bounded paging
+past full pages, retry exhaustion, receipt walks, wake failure after fan-out,
+and parity between the Promise and Effect schemas. From the package directory:
+
+```sh
+pnpm test
+```
+
+## Limits and errors
+
+- **Retry schedule.** A failed delivery retries after 2 seconds, doubling each
+  time, capped at 5 minutes. After 20 attempts the reply is exhausted. Its row
+  stays in the outbox, and BirdDog stops posting it and stops waking for it.
+- **At-least-once.** If the recipient accepts a reply but recording the receipt
+  fails, the retry uses the same mail key. Recipients must admit a repeated key
+  idempotently.
+- **Malformed rows.** A row that does not parse is deleted during a drain. A
+  malformed row met during fan-out fails that fan-out.
+- **Fan-out writes first.** Every reply is persisted before the wake is
+  scheduled. If `scheduleWake` fails, `fanOut` rejects but the replies are
+  already in the outbox, so replaying the settlement is safe.
+- **Invalid input.** `agentJob` and `decodeAgentJob` throw a schema error on
+  input that does not match. `fanOut` rejects with
+  `BirdDogError("invalid agent job payload")` for a job whose payload is not
+  BirdDog's.
+- **Host failures.** The Promise mail room wraps a failing port in a
+  `BirdDogError` and keeps your original error as its `cause`. The messages are
+  `outbox read failed`, `outbox write failed`, `outbox delete failed`,
+  `mail transport failed` and `wake scheduling failed`. A `post` that throws
+  during a drain is logged and retried, not rethrown.
+
+## Contribute and license
+
+BirdDog is MIT licensed. See [LICENSE](./LICENSE).

package/dist/effect.d.ts

@@ -0,0 +1,191 @@
+import type { WatchdogQueuedJob, WatchdogStoredJob } from "@fungi.computer/watchdog";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import type { BirdDogAgentJobInput, BirdDogAgentJobPayload, BirdDogMail, BirdDogSettlement } from "./index.js";
+/** 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;
+}>;
+/** The most characters a reply's failure diagnostic may carry. */
+export declare const BIRD_DOG_DIAGNOSTIC_MAX_LENGTH = 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.
+ */
+export declare const BirdDogReplySchema: Schema.Struct<{
+    readonly commandId: Schema.String;
+    readonly outcome: Schema.Literals<readonly ["completed", "failed", "interrupted", "cancelled", "outcome_unknown"]>;
+    readonly diagnostic: Schema.optionalKey<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
+ * characters and line breaks become single spaces, so the text cannot shape
+ * the reply around it, and credential-shaped values are masked before the
+ * 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<{
+    readonly key: Schema.String;
+    readonly to: Schema.Struct<{
+        readonly kind: Schema.Literal<"agent">;
+        readonly agentId: Schema.String;
+        readonly sessionId: Schema.String;
+    }>;
+    readonly from: Schema.Struct<{
+        readonly kind: Schema.Literal<"agent">;
+        readonly agentId: Schema.String;
+        readonly sessionId: Schema.String;
+    }>;
+    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;
+    /** 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;
+    readonly sessionId: Schema.String;
+    readonly commandFactId: Schema.String;
+    readonly recovery: Schema.optional<Schema.Struct<{
+        readonly maxRecoveries: Schema.Int;
+    }>>;
+}>;
+/** Parser for the payload that Watchdog stores without interpretation. */
+export declare const BirdDogAgentJobPayloadSchema: Schema.Struct<{
+    readonly work: Schema.Struct<{
+        readonly sessionId: Schema.String;
+        readonly commandFactId: Schema.String;
+    }>;
+    readonly mail: Schema.optional<Schema.Struct<{
+        readonly key: Schema.String;
+        readonly to: Schema.Struct<{
+            readonly kind: Schema.Literal<"agent">;
+            readonly agentId: Schema.String;
+            readonly sessionId: Schema.String;
+        }>;
+        readonly from: Schema.Struct<{
+            readonly kind: Schema.Literal<"agent">;
+            readonly agentId: Schema.String;
+            readonly sessionId: Schema.String;
+        }>;
+        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;
+        /** 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<{
+    readonly work: Schema.Struct<{
+        readonly jobId: Schema.String;
+        readonly sessionId: Schema.String;
+        readonly commandFactId: Schema.String;
+        readonly recovery: Schema.optional<Schema.Struct<{
+            readonly maxRecoveries: Schema.Int;
+        }>>;
+    }>;
+    readonly mail: Schema.optional<Schema.Struct<{
+        readonly key: Schema.String;
+        readonly to: Schema.Struct<{
+            readonly kind: Schema.Literal<"agent">;
+            readonly agentId: Schema.String;
+            readonly sessionId: Schema.String;
+        }>;
+        readonly from: Schema.Struct<{
+            readonly kind: Schema.Literal<"agent">;
+            readonly agentId: Schema.String;
+            readonly sessionId: Schema.String;
+        }>;
+        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;
+        /** 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 {
+    /** Stable discriminator for BirdDog-owned effect failures. */
+    readonly _tag: "BirdDogError";
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Effect host ports for the durable mail room. */
+export type EffectBirdDogOptions = Readonly<{
+    outbox: Readonly<{
+        /** Store one encoded mail row under its durable key. */
+        put: (key: string, value: string) => Effect.Effect<void, BirdDogError>;
+        /** Read one encoded mail row, if it exists. */
+        read: (key: string) => Effect.Effect<string | undefined, BirdDogError>;
+        /** Read an ordered page of encoded mail rows. */
+        list: (limit: number, afterKey?: string) => Effect.Effect<readonly Readonly<{
+            key: string;
+            value: string;
+        }>[], BirdDogError>;
+        /** Remove an invalid encoded row; completed deliveries retain receipts. */
+        delete: (key: string) => Effect.Effect<void, BirdDogError>;
+    }>;
+    /** Deliver one reply mail and report whether it was accepted. */
+    post: (mail: BirdDogMail) => Effect.Effect<boolean, BirdDogError>;
+    /** Arrange a future wake for pending delivery work. */
+    scheduleWake: (at: number) => Effect.Effect<void, BirdDogError>;
+    /** Return the host's current wall-clock time in milliseconds. */
+    now: () => number;
+}>;
+/** Effect-native durable reply delivery. */
+export type BirdDogEffect = Readonly<{
+    /** Queue replies owed by a settled agent job. */
+    fanOut: (settlement: BirdDogSettlement) => Effect.Effect<void, BirdDogError>;
+    /** Deliver due replies and schedule any required retry wake. */
+    drainOutbox: () => Effect.Effect<void, BirdDogError>;
+}>;
+/** Validate and translate agent work into Watchdog's opaque job grammar. */
+export declare const agentJobFromInput: (input: BirdDogAgentJobInput) => WatchdogQueuedJob;
+/** Decode the opaque payload at BirdDog's side of the Watchdog seam. */
+export declare const decodeAgentJob: (job: WatchdogStoredJob) => BirdDogAgentJobPayload;
+/**
+ * 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.
+ */
+export declare function settlementReplies(settlement: BirdDogSettlement, createdAt: number): readonly BirdDogMail[];
+/** Construct BirdDog's Effect-native mail room over Post's shared outbox. */
+export declare const make: (options: EffectBirdDogOptions) => Effect.Effect<BirdDogEffect>;

package/dist/effect.js

@@ -0,0 +1,181 @@
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import { makePostOutbox } from "@fungi.computer/carrier/post";
+const Identifier = Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(256));
+/** Parser for an ordinary agent Session address. */
+export const BirdDogAgentReferenceSchema = Schema.Struct({
+    kind: Schema.Literal("agent"),
+    agentId: Identifier,
+    sessionId: Identifier,
+});
+/** The most characters a reply's failure diagnostic may carry. */
+export const BIRD_DOG_DIAGNOSTIC_MAX_LENGTH = 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.
+ */
+export const BirdDogReplySchema = Schema.Struct({
+    commandId: Identifier,
+    outcome: Schema.Literals([
+        "completed",
+        "failed",
+        "interrupted",
+        "cancelled",
+        "outcome_unknown",
+    ]),
+    diagnostic: Schema.optionalKey(Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(BIRD_DOG_DIAGNOSTIC_MAX_LENGTH))),
+});
+const REDACTED = "[redacted]";
+// An authorization scheme's credential, e.g. `Bearer <token>`.
+const schemeCredential = /\b(bearer|basic)\s+[^\s"',;]+/giu;
+// A named credential's value, e.g. `api_key=<value>` or `"token": "<value>"`.
+const namedCredential = /\b((?:api[_-]?key|access[_-]?token|refresh[_-]?token|token|secret|password|authorization)["']?\s*[:=]\s*["']?)(?!(?:bearer|basic)\s)[^\s"',;&]+/giu;
+// A long opaque run of letters and digits, the shape of a key or token.
+const opaqueToken = /[A-Za-z0-9][\w-]{23,}/gu;
+function redactCredentials(text) {
+    return text
+        .replace(schemeCredential, `$1 ${REDACTED}`)
+        .replace(namedCredential, `$1${REDACTED}`)
+        .replace(opaqueToken, (token) => /\d/u.test(token) && /[A-Za-z]/u.test(token) ? REDACTED : token);
+}
+/**
+ * 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
+ * characters and line breaks become single spaces, so the text cannot shape
+ * the reply around it, and credential-shaped values are masked before the
+ * line is cut, so a cut never exposes part of one.
+ */
+export function boundedDiagnostic(text) {
+    const line = redactCredentials(text.replace(/[\p{Cc}\p{Zl}\p{Zp}\s]+/gu, " ").trim())
+        .slice(0, BIRD_DOG_DIAGNOSTIC_MAX_LENGTH)
+        .trimEnd();
+    return line.length === 0 ? undefined : line;
+}
+/** Parser for addressed agent correspondence. */
+export const BirdDogMailSchema = Schema.Struct({
+    key: Identifier,
+    to: BirdDogAgentReferenceSchema,
+    from: BirdDogAgentReferenceSchema,
+    replyTo: Schema.Array(BirdDogAgentReferenceSchema),
+    content: Schema.String,
+    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),
+});
+/** Parser for accepted Session work. */
+export const BirdDogAgentWorkSchema = Schema.Struct({
+    jobId: Identifier,
+    sessionId: Identifier,
+    commandFactId: Identifier,
+    recovery: Schema.optional(Schema.Struct({
+        maxRecoveries: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
+    })),
+});
+/** Parser for the payload that Watchdog stores without interpretation. */
+export const BirdDogAgentJobPayloadSchema = Schema.Struct({
+    work: Schema.Struct({
+        sessionId: Identifier,
+        commandFactId: Identifier,
+    }),
+    mail: Schema.optional(BirdDogMailSchema),
+});
+/** Parser for accepted work entering BirdDog's transactional projection. */
+export const BirdDogAgentJobInputSchema = Schema.Struct({
+    work: BirdDogAgentWorkSchema,
+    mail: Schema.optional(BirdDogMailSchema),
+});
+/** BirdDog could not complete one owned store or transport operation. */
+export class BirdDogError extends Error {
+    /** Stable discriminator for BirdDog-owned effect failures. */
+    _tag = "BirdDogError";
+    constructor(message, options) {
+        super(message, options);
+        this.name = "BirdDogError";
+    }
+}
+/** Validate and translate agent work into Watchdog's opaque job grammar. */
+export const agentJobFromInput = (input) => {
+    const accepted = Schema.decodeUnknownSync(BirdDogAgentJobInputSchema)(input);
+    const work = {
+        sessionId: accepted.work.sessionId,
+        commandFactId: accepted.work.commandFactId,
+    };
+    const payload = accepted.mail === undefined ? { work } : { work, mail: accepted.mail };
+    const job = {
+        jobId: accepted.work.jobId,
+        queue: accepted.work.sessionId,
+        lane: "default",
+        priority: 0,
+        payload,
+        state: "queued",
+    };
+    return accepted.work.recovery === undefined
+        ? job
+        : { ...job, recovery: accepted.work.recovery };
+};
+/** Decode the opaque payload at BirdDog's side of the Watchdog seam. */
+export const decodeAgentJob = (job) => Schema.decodeUnknownSync(BirdDogAgentJobPayloadSchema)(job.payload);
+/**
+ * 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.
+ */
+export function settlementReplies(settlement, createdAt) {
+    const { work, mail } = decodeAgentJob(settlement.job);
+    if (mail === undefined)
+        return [];
+    const outcome = settlement.job.outcome;
+    const diagnostic = outcome === "completed" ||
+        outcome === "cancelled" ||
+        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)}`,
+        to: destination,
+        from: mail.to,
+        replyTo: [],
+        content: settlement.content.length > 0
+            ? settlement.content
+            : `The delegated work ended ${outcome} without reply text.`,
+        createdAt,
+        reply,
+    }));
+}
+/** Construct BirdDog's Effect-native mail room over Post's shared outbox. */
+export const make = (options) => {
+    const post = makePostOutbox({
+        message: BirdDogMailSchema,
+        key: (mail) => `outbox:${mail.key}`,
+        outbox: options.outbox,
+        deliver: options.post,
+        scheduleWake: options.scheduleWake,
+        now: options.now,
+        invalidRow: () => new BirdDogError("invalid outbox row"),
+        encodingFailed: () => new BirdDogError("could not encode outbox row"),
+    });
+    const fanOut = (settlement) => Effect.gen(function* () {
+        const createdAt = options.now();
+        const replies = yield* Effect.try({
+            try: () => settlementReplies(settlement, createdAt),
+            catch: () => new BirdDogError("invalid agent job payload"),
+        });
+        let wake;
+        for (const reply of replies) {
+            const hint = yield* post.enqueue(reply, createdAt);
+            if (hint !== undefined)
+                wake = wake === undefined ? hint : Math.min(wake, hint);
+        }
+        if (wake !== undefined)
+            yield* options.scheduleWake(wake);
+    });
+    return Effect.succeed({ fanOut, drainOutbox: post.drain });
+};