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

package/dist/index.d.ts

@@ -0,0 +1,116 @@
+import type * as Schema from "effect/Schema";
+import type { WatchdogQueuedJob, WatchdogSettledJob, WatchdogStoredJob } from "@fungi.computer/watchdog";
+/** An ordinary agent Session address. Relationships between agents live elsewhere. */
+export type BirdDogAgentReference = Readonly<{
+    kind: "agent";
+    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;
+}>;
+/**
+ * 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.
+ */
+export type BirdDogReply = 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;
+}>;
+/** 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. */
+export type BirdDogAgentWork = Readonly<{
+    jobId: string;
+    sessionId: string;
+    commandFactId: string;
+    recovery?: Readonly<{
+        maxRecoveries: number;
+    }> | undefined;
+}>;
+/** Typed payload whose meaning belongs to BirdDog, never Watchdog. */
+export type BirdDogAgentJobPayload = Readonly<{
+    work: Readonly<{
+        sessionId: string;
+        commandFactId: string;
+    }>;
+    mail?: BirdDogMail | undefined;
+}>;
+/** Input for projecting accepted agent work into Watchdog's generic grammar. */
+export type BirdDogAgentJobInput = Readonly<{
+    work: BirdDogAgentWork;
+    mail?: BirdDogMail | undefined;
+}>;
+/** String-backed durable outbox owned by the BirdDog host. */
+export type BirdDogOutbox = Readonly<{
+    /** Store one encoded mail row under its durable key. */
+    put: (key: string, value: string) => Promise<void>;
+    /** Read one encoded mail row, if it exists. */
+    read: (key: string) => Promise<string | undefined>;
+    /** Read an ordered page of encoded mail rows. */
+    list: (limit: number, afterKey?: string) => Promise<readonly Readonly<{
+        key: string;
+        value: string;
+    }>[]>;
+    /** Remove an invalid encoded row; completed deliveries retain receipts. */
+    delete: (key: string) => Promise<void>;
+}>;
+/** Host ports for BirdDog's durable mail delivery. */
+export type BirdDogOptions = Readonly<{
+    /** Durable store for pending reply mail. */
+    outbox: BirdDogOutbox;
+    /** Deliver one reply mail and report whether it was accepted. */
+    post: (mail: BirdDogMail) => Promise<boolean>;
+    /** Arrange a future wake for pending delivery work. */
+    scheduleWake: (at: number) => Promise<void>;
+    /** Return the host's current wall-clock time in milliseconds. */
+    now: () => number;
+}>;
+/** Completed generic work plus the content owed to its correspondents. */
+export type BirdDogSettlement = Readonly<{
+    job: WatchdogSettledJob;
+    content: string;
+    /**
+     * The Session's recorded terminal diagnostic. Replies carry it, bounded by
+     * `boundedDiagnostic`, only for failed, interrupted and outcome_unknown work.
+     */
+    diagnostic?: string;
+    /**
+     * The settled work's host metadata, for the host's own fan-out wrapper (for
+     * example, naming who cancelled). Replies never carry it.
+     */
+    meta?: BirdDogMeta;
+}>;
+/** Durable reply delivery behind the mail-room interface. */
+export type BirdDogRuntime = Readonly<{
+    /** Queue replies owed by a settled agent job. */
+    fanOut: (settlement: BirdDogSettlement) => Promise<void>;
+    /** Deliver due replies and schedule any required retry wake. */
+    drainOutbox: () => Promise<void>;
+}>;
+/** BirdDog's small synchronous translation interface for owner transactions. */
+export type BirdDogApi = Readonly<{
+    /** Validate and translate accepted agent work into one opaque Watchdog job. */
+    agentJob: (input: BirdDogAgentJobInput) => WatchdogQueuedJob;
+    /** Decode one generic Watchdog job into BirdDog-owned agent work. */
+    decodeAgentJob: (job: WatchdogStoredJob) => BirdDogAgentJobPayload;
+    /** Construct the durable reply mail room. */
+    make: (options: BirdDogOptions) => Promise<BirdDogRuntime>;
+}>;
+/** Agent-aware mail translation over Watchdog's payload-blind job grammar. */
+export declare const BirdDog: BirdDogApi;

package/dist/index.js

@@ -0,0 +1,8 @@
+import { agentJobFromInput, decodeAgentJob } from "./effect.js";
+import { createPromiseBirdDog } from "./internal/promise-mail-room.js";
+/** Agent-aware mail translation over Watchdog's payload-blind job grammar. */
+export const BirdDog = Object.freeze({
+    agentJob: agentJobFromInput,
+    decodeAgentJob,
+    make: createPromiseBirdDog,
+});

package/dist/internal/promise-mail-room.d.ts

@@ -0,0 +1,3 @@
+import type { BirdDogApi } from "../index.js";
+/** Lift Promise host ports once into BirdDog's Effect-owned mail room. */
+export declare const createPromiseBirdDog: BirdDogApi["make"];

package/dist/internal/promise-mail-room.js

@@ -0,0 +1,51 @@
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Option from "effect/Option";
+import { BirdDogError, make } from "../effect.js";
+const runPromise = (effect) => Effect.runPromiseExit(effect).then((exit) => {
+    if (Exit.isSuccess(exit))
+        return exit.value;
+    const failure = Option.getOrUndefined(Cause.findErrorOption(exit.cause));
+    return Promise.reject(failure instanceof Error ? failure : new BirdDogError("mail room failed"));
+});
+/** Lift Promise host ports once into BirdDog's Effect-owned mail room. */
+export const createPromiseBirdDog = async (options) => {
+    const readOutbox = options.outbox.read;
+    const readPort = {
+        read: (key) => Effect.tryPromise({
+            try: () => readOutbox(key),
+            catch: (cause) => new BirdDogError("outbox read failed", { cause }),
+        }),
+    };
+    const runtime = await Effect.runPromise(make({
+        outbox: {
+            ...readPort,
+            put: (key, value) => Effect.tryPromise({
+                try: () => options.outbox.put(key, value),
+                catch: (cause) => new BirdDogError("outbox write failed", { cause }),
+            }),
+            list: (limit, afterKey) => Effect.tryPromise({
+                try: () => options.outbox.list(limit, afterKey),
+                catch: (cause) => new BirdDogError("outbox read failed", { cause }),
+            }),
+            delete: (key) => Effect.tryPromise({
+                try: () => options.outbox.delete(key),
+                catch: (cause) => new BirdDogError("outbox delete failed", { cause }),
+            }),
+        },
+        post: (mail) => Effect.tryPromise({
+            try: () => options.post(mail),
+            catch: (cause) => new BirdDogError("mail transport failed", { cause }),
+        }),
+        scheduleWake: (at) => Effect.tryPromise({
+            try: () => options.scheduleWake(at),
+            catch: (cause) => new BirdDogError("wake scheduling failed", { cause }),
+        }),
+        now: options.now,
+    }));
+    return Object.freeze({
+        fanOut: (settlement) => runPromise(runtime.fanOut(settlement)),
+        drainOutbox: () => runPromise(runtime.drainOutbox()),
+    });
+};

package/docs/api/README.md

@@ -0,0 +1,14 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+**@fungi.computer/bird-dog**
+
+---
+
+# @fungi.computer/bird-dog
+
+## Modules
+
+| Module              | Description |
+| ------------------- | ----------- |
+| [effect](effect.md) | -           |
+| [index](index.md)   | -           |

package/docs/api/effect.md

@@ -0,0 +1,481 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/bird-dog**](README.md)
+
+---
+
+[@fungi.computer/bird-dog](README.md) / effect
+
+# effect
+
+## Classes
+
+### BirdDogError
+
+BirdDog could not complete one owned store or transport operation.
+
+#### Extends
+
+- `Error`
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new BirdDogError(message, options?): BirdDogError;
+```
+
+###### Parameters
+
+| Parameter  | Type           |
+| ---------- | -------------- |
+| `message`  | `string`       |
+| `options?` | `ErrorOptions` |
+
+###### Returns
+
+[`BirdDogError`](#birddogerror)
+
+###### Overrides
+
+```ts
+Error.constructor;
+```
+
+#### Properties
+
+##### \_tag
+
+```ts
+readonly _tag: "BirdDogError";
+```
+
+Stable discriminator for BirdDog-owned effect failures.
+
+## Type Aliases
+
+### EffectBirdDogOptions
+
+```ts
+type EffectBirdDogOptions = Readonly<{
+  outbox: Readonly<{
+    put: (key, value) => Effect.Effect<void, BirdDogError>;
+    read: (key) => Effect.Effect<string | undefined, BirdDogError>;
+    list: (
+      limit,
+      afterKey?,
+    ) => Effect.Effect<
+      readonly Readonly<{
+        key: string;
+        value: string;
+      }>[],
+      BirdDogError
+    >;
+    delete: (key) => Effect.Effect<void, BirdDogError>;
+  }>;
+  post: (mail) => Effect.Effect<boolean, BirdDogError>;
+  scheduleWake: (at) => Effect.Effect<void, BirdDogError>;
+  now: () => number;
+}>;
+```
+
+Effect host ports for the durable mail room.
+
+---
+
+### BirdDogEffect
+
+```ts
+type BirdDogEffect = Readonly<{
+  fanOut: (settlement) => Effect.Effect<void, BirdDogError>;
+  drainOutbox: () => Effect.Effect<void, BirdDogError>;
+}>;
+```
+
+Effect-native durable reply delivery.
+
+## Variables
+
+### BirdDogAgentReferenceSchema
+
+```ts
+const BirdDogAgentReferenceSchema: Struct<{
+  kind: Literal<"agent">;
+  agentId: String;
+  sessionId: String;
+}>;
+```
+
+Parser for an ordinary agent Session address.
+
+---
+
+### BIRD\_DOG\_DIAGNOSTIC\_MAX\_LENGTH
+
+```ts
+const BIRD_DOG_DIAGNOSTIC_MAX_LENGTH: 200 = 200;
+```
+
+The most characters a reply's failure diagnostic may carry.
+
+---
+
+### BirdDogReplySchema
+
+```ts
+const BirdDogReplySchema: Struct<{
+  commandId: String;
+  outcome: Literals<
+    readonly [
+      "completed",
+      "failed",
+      "interrupted",
+      "cancelled",
+      "outcome_unknown",
+    ]
+  >;
+  diagnostic: optionalKey<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.
+
+---
+
+### BirdDogMailSchema
+
+```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<
+    Struct<{
+      commandId: String;
+      outcome: Literals<
+        readonly [
+          "completed",
+          "failed",
+          "interrupted",
+          "cancelled",
+          "outcome_unknown",
+        ]
+      >;
+      diagnostic: optionalKey<String>;
+    }>
+  >;
+}>;
+```
+
+Parser for addressed agent correspondence.
+
+---
+
+### BirdDogAgentWorkSchema
+
+```ts
+const BirdDogAgentWorkSchema: Struct<{
+  jobId: String;
+  sessionId: String;
+  commandFactId: String;
+  recovery: optional<
+    Struct<{
+      maxRecoveries: Int;
+    }>
+  >;
+}>;
+```
+
+Parser for accepted Session work.
+
+---
+
+### BirdDogAgentJobPayloadSchema
+
+```ts
+const BirdDogAgentJobPayloadSchema: Struct<{
+  work: Struct<{
+    sessionId: String;
+    commandFactId: String;
+  }>;
+  mail: optional<
+    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<
+        Struct<{
+          commandId: String;
+          outcome: Literals<
+            readonly [
+              "completed",
+              "failed",
+              "interrupted",
+              "cancelled",
+              "outcome_unknown",
+            ]
+          >;
+          diagnostic: optionalKey<String>;
+        }>
+      >;
+    }>
+  >;
+}>;
+```
+
+Parser for the payload that Watchdog stores without interpretation.
+
+---
+
+### BirdDogAgentJobInputSchema
+
+```ts
+const BirdDogAgentJobInputSchema: Struct<{
+  work: Struct<{
+    jobId: String;
+    sessionId: String;
+    commandFactId: String;
+    recovery: optional<
+      Struct<{
+        maxRecoveries: Int;
+      }>
+    >;
+  }>;
+  mail: optional<
+    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<
+        Struct<{
+          commandId: String;
+          outcome: Literals<
+            readonly [
+              "completed",
+              "failed",
+              "interrupted",
+              "cancelled",
+              "outcome_unknown",
+            ]
+          >;
+          diagnostic: optionalKey<String>;
+        }>
+      >;
+    }>
+  >;
+}>;
+```
+
+Parser for accepted work entering BirdDog's transactional projection.
+
+## Functions
+
+### boundedDiagnostic()
+
+```ts
+function boundedDiagnostic(text): string | undefined;
+```
+
+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.
+
+#### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `text`    | `string` |
+
+#### Returns
+
+`string` \| `undefined`
+
+---
+
+### agentJobFromInput()
+
+```ts
+function agentJobFromInput(input): object;
+```
+
+Validate and translate agent work into Watchdog's opaque job grammar.
+
+#### Parameters
+
+| Parameter | Type                                                    |
+| --------- | ------------------------------------------------------- |
+| `input`   | [`BirdDogAgentJobInput`](index.md#birddogagentjobinput) |
+
+#### Returns
+
+`object`
+
+| Name                     | Type       |
+| ------------------------ | ---------- |
+| `state`                  | `"queued"` |
+| `jobId`                  | `string`   |
+| `queue`                  | `string`   |
+| `lane`                   | `string`   |
+| `priority`               | `number`   |
+| `payload`                | `unknown`  |
+| `recovery?`              | `object`   |
+| `recovery.maxRecoveries` | `number`   |
+
+---
+
+### decodeAgentJob()
+
+```ts
+function decodeAgentJob(job): BirdDogAgentJobPayload;
+```
+
+Decode the opaque payload at BirdDog's side of the Watchdog seam.
+
+#### Parameters
+
+| Parameter | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `job`     | \| \{ `state`: `"queued"`; `jobId`: `string`; `queue`: `string`; `lane`: `string`; `priority`: `number`; `payload`: `unknown`; `recovery?`: \{ `maxRecoveries`: `number`; \}; \} \| \{ `state`: `"running"`; `jobId`: `string`; `queue`: `string`; `lane`: `string`; `priority`: `number`; `payload`: `unknown`; `recovery?`: \{ `maxRecoveries`: `number`; \}; \} \| \{ `state`: `"settled"`; `outcome`: `"failed"` \| `"completed"` \| `"interrupted"` \| `"cancelled"` \| `"outcome_unknown"`; `failureReason?`: `string`; `jobId`: `string`; `queue`: `string`; `lane`: `string`; `priority`: `number`; `payload`: `unknown`; `recovery?`: \{ `maxRecoveries`: `number`; \}; \} |
+
+#### Returns
+
+[`BirdDogAgentJobPayload`](index.md#birddogagentjobpayload)
+
+---
+
+### 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;
+  }>;
+}>[];
+```
+
+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.
+
+#### Parameters
+
+| Parameter    | Type                                              |
+| ------------ | ------------------------------------------------- |
+| `settlement` | [`BirdDogSettlement`](index.md#birddogsettlement) |
+| `createdAt`  | `number`                                          |
+
+#### 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`; \}\>; \}\>[]
+
+---
+
+### make()
+
+```ts
+function make(options): Effect<
+  Readonly<{
+    fanOut: (settlement) => Effect<void, BirdDogError>;
+    drainOutbox: () => Effect<void, BirdDogError>;
+  }>
+>;
+```
+
+Construct BirdDog's Effect-native mail room over Post's shared outbox.
+
+#### Parameters
+
+| Parameter | Type                                            |
+| --------- | ----------------------------------------------- |
+| `options` | [`EffectBirdDogOptions`](#effectbirddogoptions) |
+
+#### Returns
+
+`Effect`\<`Readonly`\<\{ `fanOut`: (`settlement`) => `Effect`\<`void`,
+[`BirdDogError`](#birddogerror)\>; `drainOutbox`: () => `Effect`\<`void`,
+[`BirdDogError`](#birddogerror)\>; \}\>\>