bird-dog

Import

Import

import * as api from "@fungi.computer/bird-dog";

Exports

Kind	Export	Description
Ttype alias	BirdDogAgentReference	An ordinary agent Session address. Relationships between agents live elsewhere.
Ttype alias	BirdDogAgentRecipientReference	An addressed Agent whose first Session may be created on acceptance.
Ttype alias	BirdDogSystemIdentity	The Hub’s stable system identity for a terminal offline disposition.
Ttype alias	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.
Ttype alias	BirdDogAgentReply	Facts an Agent may author; the Hub owns recipient-offline disposition.
Ttype alias	BirdDogMail	Addressed correspondence. Agents author ordinary replies and recipient-left notices; only the Hub system authors recipient-offline dispositions.
Ttype alias	BirdDogMeta	Opaque JSON a host attached to the work; BirdDog only carries it.
Ttype alias	BirdDogAgentWork	The accepted Session work BirdDog points at from an opaque Watchdog job.
Ttype alias	BirdDogAgentJobPayload	Typed payload whose meaning belongs to BirdDog, never Watchdog.
Ttype alias	BirdDogAgentJobInput	Input for projecting accepted agent work into Watchdog’s generic grammar.
Ttype alias	BirdDogOutbox	String-backed durable outbox owned by the BirdDog host.
Ttype alias	BirdDogOptions	Host ports for BirdDog’s durable mail delivery.
Ttype alias	BirdDogDelegator	Who sent a Session its work first: the mail that opened the relationship. agentId is the Session’s own Agent, the author of every report.
Ttype alias	BirdDogSettlement	Completed generic work plus the content owed to its correspondents.
Ttype alias	BirdDogWaitingItem	One open item named by a reply as waiting on its recipient.
Ttype alias	BirdDogRuntime	Durable reply delivery behind the mail-room interface.
Ttype alias	BirdDogApi	BirdDog’s small synchronous translation interface for owner transactions.
constconstant	BirdDog	Agent-aware mail translation over Watchdog’s payload-blind job grammar.
fnfunction	undeliverableReply()	Construct the one stable system reply correlated to the exact sent letter.

BirdDogAgentReferenceTtype alias

Signature

type BirdDogAgentReference = Readonly<{
  kind: "agent";
  agentId: string;
  sessionId: string;
}>;

An ordinary agent Session address. Relationships between agents live elsewhere.

---

BirdDogAgentRecipientReferenceTtype alias

Signature

type BirdDogAgentRecipientReference = Readonly<{
  kind: "agent";
  agentId: string;
  sessionId?: string;
}>;

An addressed Agent whose first Session may be created on acceptance.

---

BirdDogSystemIdentityTtype alias

Signature

type BirdDogSystemIdentity = Readonly<{
  kind: "system";
  systemId: "hub";
}>;

The Hub’s stable system identity for a terminal offline disposition.

---

BirdDogReplyTtype alias

Signature

type BirdDogReply =
  | Readonly<{
      commandId: string;
      outcome: "accepted";
    }>
  | Readonly<{
      commandId: string;
      outcome:
        | "completed"
        | "failed"
        | "interrupted"
        | "cancelled"
        | "outcome_unknown";
      diagnostic?: string;
      waitingOnYou?: readonly BirdDogWaitingItem[];
    }>
  | Readonly<{
      outcome: "undeliverable";
      reason: "recipient_offline" | "recipient_left";
    }>;

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.

---

BirdDogAgentReplyTtype alias

Signature

type BirdDogAgentReply =
  | Exclude<
      BirdDogReply,
      {
        outcome: "undeliverable";
      }
    >
  | Readonly<{
      outcome: "undeliverable";
      reason: "recipient_left";
    }>;

Facts an Agent may author; the Hub owns recipient-offline disposition.

---

BirdDogMailTtype alias

Signature

type BirdDogMail =
  | Readonly<{
      key: string;
      to: BirdDogAgentRecipientReference;
      replyTo: readonly BirdDogAgentReference[];
      content: string;
      createdAt: number;
      meta?: BirdDogMeta;
      from: BirdDogAgentReference;
      reply?: BirdDogAgentReply;
    }>
  | Readonly<{
      key: string;
      to: BirdDogAgentRecipientReference;
      replyTo: readonly BirdDogAgentReference[];
      content: string;
      createdAt: number;
      meta?: BirdDogMeta;
      from: BirdDogSystemIdentity;
      reply: Readonly<{
        outcome: "undeliverable";
        reason: "recipient_offline";
      }>;
    }>;

Addressed correspondence. Agents author ordinary replies and recipient-left notices; only the Hub system authors recipient-offline dispositions.

---

BirdDogMetaTtype alias

Signature

type BirdDogMeta = typeof Schema.Json.Type;

Opaque JSON a host attached to the work; BirdDog only carries it.

---

BirdDogAgentWorkTtype alias

Signature

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.

---

BirdDogAgentJobPayloadTtype alias

Signature

type BirdDogAgentJobPayload = Readonly<{
  work: Readonly<{
    sessionId: string;
    commandFactId: string;
  }>;
  mail?: BirdDogMail;
}>;

Typed payload whose meaning belongs to BirdDog, never Watchdog.

---

BirdDogAgentJobInputTtype alias

Signature

type BirdDogAgentJobInput = Readonly<{
  work: BirdDogAgentWork;
  mail?: BirdDogMail;
}>;

Input for projecting accepted agent work into Watchdog’s generic grammar.

---

BirdDogOutboxTtype alias

Signature

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.

---

BirdDogOptionsTtype alias

Signature

type BirdDogOptions = Readonly<{
  outbox: BirdDogOutbox;
  post: (mail) => Promise<boolean>;
  scheduleWake: (at) => Promise<void>;
  now: () => number;
}>;

Host ports for BirdDog’s durable mail delivery.

---

BirdDogDelegatorTtype alias

Signature

type BirdDogDelegator = Readonly<{
  key: string;
  agentId: string;
  replyTo: readonly BirdDogAgentReference[];
}>;

Who sent a Session its work first: the mail that opened the relationship. agentId is the Session’s own Agent, the author of every report.

---

BirdDogSettlementTtype alias

Signature

type BirdDogSettlement = Readonly<{
  job: WatchdogSettledJob;
  content: string;
  delegator?: BirdDogDelegator;
  diagnostic?: string;
  meta?: BirdDogMeta;
  waitingOnYou?: readonly BirdDogWaitingItem[];
}>;

Completed generic work plus the content owed to its correspondents.

---

BirdDogWaitingItemTtype alias

Signature

type BirdDogWaitingItem = Readonly<{
  itemId: string;
  kind: string;
  summary: string;
}>;

One open item named by a reply as waiting on its recipient.

---

BirdDogRuntimeTtype alias

Signature

type BirdDogRuntime = Readonly<{
  fanOut: (settlement) => Promise<void>;
  drainOutbox: () => Promise<void>;
}>;

Durable reply delivery behind the mail-room interface.

---

BirdDogApiTtype alias

Signature

type BirdDogApi = Readonly<{
  agentJob: (input) => WatchdogQueuedJob;
  decodeAgentJob: (job) => BirdDogAgentJobPayload;
  make: (options) => Promise<BirdDogRuntime>;
}>;

BirdDog’s small synchronous translation interface for owner transactions.

BirdDogconstconstant

Signature

const BirdDog: BirdDogApi;

Agent-aware mail translation over Watchdog’s payload-blind job grammar.

undeliverableReply()fnfunction

Signature

function undeliverableReply(original, createdAt): BirdDogMail;

Construct the one stable system reply correlated to the exact sent letter.

Parameters

Parameter	Type
original	BirdDogMail
createdAt	number

Returns

BirdDogMail