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

package/docs/api/index.md

@@ -0,0 +1,205 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/bird-dog**](README.md)
+
+---
+
+[@fungi.computer/bird-dog](README.md) / index
+
+# index
+
+## Type Aliases
+
+### BirdDogAgentReference
+
+```ts
+type BirdDogAgentReference = Readonly<{
+  kind: "agent";
+  agentId: string;
+  sessionId: string;
+}>;
+```
+
+An ordinary agent Session address. Relationships between agents live elsewhere.
+
+---
+
+### BirdDogMail
+
+```ts
+type BirdDogMail = Readonly<{
+  key: string;
+  to: BirdDogAgentReference;
+  from: BirdDogAgentReference;
+  replyTo: readonly BirdDogAgentReference[];
+  content: string;
+  createdAt: number;
+  meta?: BirdDogMeta;
+  reply?: BirdDogReply;
+}>;
+```
+
+Addressed agent correspondence carried with durable work when a reply is owed.
+
+---
+
+### BirdDogReply
+
+```ts
+type BirdDogReply = Readonly<{
+  commandId: string;
+  outcome:
+    "completed" | "failed" | "interrupted" | "cancelled" | "outcome_unknown";
+  diagnostic?: string;
+}>;
+```
+
+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.
+
+---
+
+### BirdDogMeta
+
+```ts
+type BirdDogMeta = typeof Schema.Json.Type;
+```
+
+Opaque JSON a host attached to the work; BirdDog only carries it.
+
+---
+
+### BirdDogAgentWork
+
+```ts
+type BirdDogAgentWork = Readonly<{
+  jobId: string;
+  sessionId: string;
+  commandFactId: string;
+  recovery?: Readonly<{
+    maxRecoveries: number;
+  }>;
+}>;
+```
+
+The accepted Session work BirdDog points at from an opaque Watchdog job.
+
+---
+
+### BirdDogAgentJobPayload
+
+```ts
+type BirdDogAgentJobPayload = Readonly<{
+  work: Readonly<{
+    sessionId: string;
+    commandFactId: string;
+  }>;
+  mail?: BirdDogMail;
+}>;
+```
+
+Typed payload whose meaning belongs to BirdDog, never Watchdog.
+
+---
+
+### BirdDogAgentJobInput
+
+```ts
+type BirdDogAgentJobInput = Readonly<{
+  work: BirdDogAgentWork;
+  mail?: BirdDogMail;
+}>;
+```
+
+Input for projecting accepted agent work into Watchdog's generic grammar.
+
+---
+
+### BirdDogOutbox
+
+```ts
+type BirdDogOutbox = Readonly<{
+  put: (key, value) => Promise<void>;
+  read: (key) => Promise<string | undefined>;
+  list: (
+    limit,
+    afterKey?,
+  ) => Promise<
+    readonly Readonly<{
+      key: string;
+      value: string;
+    }>[]
+  >;
+  delete: (key) => Promise<void>;
+}>;
+```
+
+String-backed durable outbox owned by the BirdDog host.
+
+---
+
+### BirdDogOptions
+
+```ts
+type BirdDogOptions = Readonly<{
+  outbox: BirdDogOutbox;
+  post: (mail) => Promise<boolean>;
+  scheduleWake: (at) => Promise<void>;
+  now: () => number;
+}>;
+```
+
+Host ports for BirdDog's durable mail delivery.
+
+---
+
+### BirdDogSettlement
+
+```ts
+type BirdDogSettlement = Readonly<{
+  job: WatchdogSettledJob;
+  content: string;
+  diagnostic?: string;
+  meta?: BirdDogMeta;
+}>;
+```
+
+Completed generic work plus the content owed to its correspondents.
+
+---
+
+### BirdDogRuntime
+
+```ts
+type BirdDogRuntime = Readonly<{
+  fanOut: (settlement) => Promise<void>;
+  drainOutbox: () => Promise<void>;
+}>;
+```
+
+Durable reply delivery behind the mail-room interface.
+
+---
+
+### BirdDogApi
+
+```ts
+type BirdDogApi = Readonly<{
+  agentJob: (input) => WatchdogQueuedJob;
+  decodeAgentJob: (job) => BirdDogAgentJobPayload;
+  make: (options) => Promise<BirdDogRuntime>;
+}>;
+```
+
+BirdDog's small synchronous translation interface for owner transactions.
+
+## Variables
+
+### BirdDog
+
+```ts
+const BirdDog: BirdDogApi;
+```
+
+Agent-aware mail translation over Watchdog's payload-blind job grammar.

package/package.json

@@ -1,6 +1,67 @@
 {
   "name": "@fungi.computer/bird-dog",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.1",
+  "author": "Levi <levi@technomancy.dev>",
+  "description": "Durable addressed agent mail over generic Watchdog work",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./effect": {
+      "types": "./dist/effect.d.ts",
+      "import": "./dist/effect.js"
+    }
+  },
+  "files": [
+    "dist",
+    "docs/api",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@fungi.computer/carrier": "0.0.1",
+    "@fungi.computer/watchdog": "0.0.1",
+    "effect": "4.0.2"
+  },
+  "devDependencies": {
+    "@types/node": "24.13.3",
+    "typescript": "5.9.3",
+    "vitest": "4.1.11"
+  },
+  "botanical": {
+    "role": "package",
+    "operations": {
+      "lint": "required",
+      "typecheck": "required",
+      "build": "required",
+      "test": "required",
+      "docs": "required",
+      "pack": "required",
+      "smoke": "required",
+      "stranger": "required"
+    }
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fungi-computer/bird-dog.git"
+  },
+  "scripts": {
+    "lint": "eslint src test --max-warnings=0 && ../../node_modules/.bin/oxlint --config ../../oxlint.config.ts --deny-warnings src test",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "build": "pnpm run clean && tsc -p tsconfig.build.json",
+    "clean": "node --input-type=module --eval \"import { rm } from 'node:fs/promises'; await rm('dist', { recursive: true, force: true });\"",
+    "test": "vitest run",
+    "docs": "tsx ../../tooling/repository/src/docs/cli.ts check --root ../..",
+    "docs:write": "tsx ../../tooling/repository/src/docs/cli.ts write --root ../..",
+    "pack": "mkdir -p ../../.botanical/bird-dog-pack && pnpm pack --pack-destination ../../.botanical/bird-dog-pack",
+    "smoke": "node --input-type=module -e \"import('./dist/index.js').then(({BirdDog}) => { if (!BirdDog) process.exit(1); })\"",
+    "stranger": "tsx ../../tooling/repository/src/artifacts/cli.ts --repo-root ../.. .",
+    "format:check": "node ../../tooling/repository/scripts/format-package-check.mjs",
+    "lint:anti-slop": "node ../../tooling/repository/scripts/lint-package-anti-slop.mjs"
+  }
 }