@zhin.js/harness 0.0.0-stage → 1.0.1

package/lib/contracts.js

@@ -0,0 +1,86 @@
+/**
+ * ADR 0048 Agent Harness — shared contracts (H1).
+ *
+ * Everything here is plain, serializable data plus the interfaces that the
+ * harness components implement. Components (authority, budget, guard,
+ * journal, mailbox) depend on this file only, never on each other, so they
+ * can be built and tested independently and composed in `harness.ts`.
+ *
+ * Rules that hold across all components:
+ * - No platform (IM) types. Venues are opaque references.
+ * - Every value that crosses a mailbox is JSON-serializable (A2A in H5).
+ * - Pure functions never mutate their inputs; returned objects are frozen.
+ */
+/**
+ * Trust levels, lowest first. Comparisons use this order only; never compare
+ * strings any other way.
+ */
+export const TRUST_LEVELS = ['stranger', 'group_member', 'trusted', 'master'];
+export const ALL = Object.freeze({ kind: 'all' });
+export const NONE = Object.freeze({ kind: 'only', names: Object.freeze([]) });
+export function only(names) {
+    return Object.freeze({ kind: 'only', names: Object.freeze([...new Set(names)].sort()) });
+}
+export function scopeHas(scope, name) {
+    return scope.kind === 'all' || scope.names.includes(name);
+}
+/** Set intersection. `all ∩ x = x`. Result names are sorted and unique. */
+export function intersectScopes(a, b) {
+    if (a.kind === 'all')
+        return b.kind === 'all' ? ALL : only(b.names);
+    if (b.kind === 'all')
+        return only(a.names);
+    const right = new Set(b.names);
+    return only(a.names.filter((name) => right.has(name)));
+}
+/** `true` when every name `inner` allows is also allowed by `outer`. */
+export function scopeWithin(inner, outer) {
+    if (outer.kind === 'all')
+        return true;
+    if (inner.kind === 'all')
+        return false;
+    return inner.names.every((name) => outer.names.includes(name));
+}
+export const BUDGET_KEYS = ['modelCalls', 'tokens', 'wallMs', 'sideEffects'];
+export const DEFAULT_GUARD_LIMITS = Object.freeze({
+    maxDepth: 4,
+    maxFanout: 16,
+    maxPairRoundTrips: 3,
+    maxDuplicates: 2,
+});
+export const DEFAULT_JOURNAL_RETENTION = Object.freeze({
+    maxAgeMs: 30 * 24 * 60 * 60 * 1000,
+    maxEventsPerEngagement: 5000,
+});
+export class JournalFullError extends Error {
+    engagementId;
+    limit;
+    code = 'journal_full';
+    constructor(engagementId, limit) {
+        super(`Engagement ${engagementId} reached the journal limit of ${limit} events`);
+        this.engagementId = engagementId;
+        this.limit = limit;
+        this.name = 'JournalFullError';
+    }
+}
+/** Lane of a mail: `mail.lane`, or its engagement. */
+export function laneOf(mail) {
+    return mail.lane ?? `engagement:${mail.engagementId}`;
+}
+export function mailboxKeyOf(mail) {
+    return { actor: mail.to, lane: laneOf(mail), engagementId: mail.engagementId };
+}
+/**
+ * Stable sender id the inbox policies compare: the human body's `senderId`,
+ * else the principal's id; the actor id for actor mail; `system:<source>`.
+ * Always transport-derived (invariant 6), never read from free text.
+ */
+export function senderOf(mail) {
+    if (mail.body.kind === 'human' && mail.body.senderId)
+        return mail.body.senderId;
+    switch (mail.from.kind) {
+        case 'human': return mail.from.principal.id;
+        case 'actor': return mail.from.actor;
+        default: return `system:${mail.from.source}`;
+    }
+}

package/lib/guard.d.ts

@@ -0,0 +1,25 @@
+/**
+ * ADR 0048 §3.4 Guard Kernel — mail admission (H1).
+ *
+ * `admitMail` is pure: it reads the mail, the engagement graph and the
+ * context, and returns the first denial in a fixed order (or allow). It never
+ * looks at prompt text except to normalize content for duplicate detection.
+ *
+ * Order (first failure wins):
+ * 1. engagement known            → `unknown_engagement`
+ * 2. causation (invariant 3)     → `missing_causation`
+ * 3. authority (invariant 1)     → `authority_not_attenuated` / `missing_causation` (forged result / signal)
+ * 4. contacts and acceptance     → `contact_not_allowed` / `not_accepted_by_target`
+ * 5. depth (invariant 5)         → `depth_exceeded`             (escalates)
+ * 6. fanout                      → `fanout_exceeded`            (escalates)
+ * 7. pair round trips            → `pair_round_trips_exceeded`  (escalates)
+ * 8. duplicates                  → `duplicate_mail`             (escalates)
+ */
+import { type Authority, type Engagement, type EngagementGraphView, type GuardKernel, type Mail } from './contracts.js';
+export interface GuardKernelOptions {
+    /** `true` when `child` grants nothing beyond `parent` (supplied by the authority module). */
+    isAttenuationOf(child: Authority, parent: Authority): boolean;
+}
+/** Builds a read-only, id-indexed view over an engagement's admitted mails. */
+export declare function createEngagementGraph(engagement: Engagement, mails: readonly Mail[]): EngagementGraphView;
+export declare function createGuardKernel(options: GuardKernelOptions): GuardKernel;

package/lib/guard.js

@@ -0,0 +1,213 @@
+/**
+ * ADR 0048 §3.4 Guard Kernel — mail admission (H1).
+ *
+ * `admitMail` is pure: it reads the mail, the engagement graph and the
+ * context, and returns the first denial in a fixed order (or allow). It never
+ * looks at prompt text except to normalize content for duplicate detection.
+ *
+ * Order (first failure wins):
+ * 1. engagement known            → `unknown_engagement`
+ * 2. causation (invariant 3)     → `missing_causation`
+ * 3. authority (invariant 1)     → `authority_not_attenuated` / `missing_causation` (forged result / signal)
+ * 4. contacts and acceptance     → `contact_not_allowed` / `not_accepted_by_target`
+ * 5. depth (invariant 5)         → `depth_exceeded`             (escalates)
+ * 6. fanout                      → `fanout_exceeded`            (escalates)
+ * 7. pair round trips            → `pair_round_trips_exceeded`  (escalates)
+ * 8. duplicates                  → `duplicate_mail`             (escalates)
+ */
+import { scopeHas, } from './contracts.js';
+const ALLOW = Object.freeze({ allow: true });
+function deny(code, reason, escalate = false) {
+    return Object.freeze({ allow: false, code, reason, escalate });
+}
+/** Builds a read-only, id-indexed view over an engagement's admitted mails. */
+export function createEngagementGraph(engagement, mails) {
+    const list = Object.freeze([...mails]);
+    const byId = new Map();
+    for (const mail of list) {
+        if (!byId.has(mail.id))
+            byId.set(mail.id, mail);
+    }
+    return Object.freeze({
+        engagement,
+        mails: list,
+        get: (id) => byId.get(id),
+    });
+}
+/** Agent definition name of an actor id (`<agent>` or `<agent>#<instance>`). */
+function agentOf(actor) {
+    const hash = actor.indexOf('#');
+    return hash === -1 ? actor : actor.slice(0, hash);
+}
+function describeSender(from) {
+    switch (from.kind) {
+        case 'actor':
+            return `actor ${from.actor}`;
+        case 'human':
+            return `human ${from.principal.id}`;
+        case 'system':
+            return `system ${from.source}`;
+    }
+}
+function senderKey(from) {
+    switch (from.kind) {
+        case 'actor':
+            return `actor:${from.actor}`;
+        case 'human':
+            return `human:${from.principal.id}`;
+        case 'system':
+            return `system:${from.source}`;
+    }
+}
+function isAskOrDelegate(mail) {
+    return mail.kind === 'ask' || mail.kind === 'delegate';
+}
+function isHop(mail) {
+    return mail.from.kind === 'actor' && isAskOrDelegate(mail);
+}
+function normalize(text) {
+    return text.trim().replace(/\s+/g, ' ').toLowerCase();
+}
+/** Text compared for duplicate detection; `undefined` for kinds that are not checked. */
+function contentOf(mail) {
+    switch (mail.body.kind) {
+        case 'ask':
+            return normalize(mail.body.question);
+        case 'delegate':
+            return normalize(mail.body.brief);
+        case 'tell':
+            return normalize(mail.body.content);
+        default:
+            return undefined;
+    }
+}
+/** Number of actor-sent ask/delegate hops from `mail` back to the root, including `mail`. */
+function depthOf(mail, graph) {
+    let depth = 0;
+    const seen = new Set();
+    let current = mail;
+    while (current && !seen.has(current.id)) {
+        seen.add(current.id);
+        if (isHop(current))
+            depth += 1;
+        current = current.causationId === undefined ? undefined : graph.get(current.causationId);
+    }
+    return depth;
+}
+function checkResult(mail, sender, graph) {
+    if (mail.body.kind !== 'result')
+        return undefined;
+    const original = graph.get(mail.body.inReplyTo);
+    if (!original) {
+        return deny('missing_causation', `Result ${mail.id} from actor ${sender} replies to unknown mail ${mail.body.inReplyTo}`);
+    }
+    if (!isAskOrDelegate(original)) {
+        return deny('missing_causation', `Result ${mail.id} from actor ${sender} replies to ${original.kind} mail ${original.id}, not an ask or delegate`);
+    }
+    if (original.to !== sender) {
+        return deny('missing_causation', `Result ${mail.id} from actor ${sender} replies to mail ${original.id} that was addressed to ${original.to}`);
+    }
+    const rootActor = graph.get(graph.engagement.rootMailId)?.to;
+    const sentByTarget = original.from.kind === 'actor' ? original.from.actor === mail.to : mail.to === rootActor;
+    if (!sentByTarget) {
+        return deny('missing_causation', `Result ${mail.id} from actor ${sender} is addressed to ${mail.to}, but mail ${original.id} was sent by ${describeSender(original.from)}`);
+    }
+    return undefined;
+}
+export function createGuardKernel(options) {
+    const { isAttenuationOf } = options;
+    function admitMail(mail, ctx) {
+        const { graph, limits, targetCeiling, senderAuthority } = ctx;
+        const who = describeSender(mail.from);
+        // 1. Engagement
+        if (!graph) {
+            return deny('unknown_engagement', `Mail ${mail.id} from ${who} names unknown engagement ${mail.engagementId}`);
+        }
+        if (mail.engagementId !== graph.engagement.id) {
+            return deny('unknown_engagement', `Mail ${mail.id} from ${who} names engagement ${mail.engagementId}, but was routed into ${graph.engagement.id}`);
+        }
+        // 2. Causation (invariant 3)
+        if (mail.causationId === undefined) {
+            if (mail.id !== graph.engagement.rootMailId) {
+                return deny('missing_causation', `Mail ${mail.id} from ${who} to ${mail.to} has no causation and is not the root mail of engagement ${graph.engagement.id}`);
+            }
+        }
+        else if (!graph.get(mail.causationId)) {
+            return deny('missing_causation', `Mail ${mail.id} from ${who} to ${mail.to} cites unknown causation ${mail.causationId}`);
+        }
+        // 3. Authority (invariant 1); results and signals are checked structurally instead
+        if (mail.from.kind === 'actor') {
+            const sender = mail.from.actor;
+            if (mail.body.kind === 'result') {
+                const forged = checkResult(mail, sender, graph);
+                if (forged)
+                    return forged;
+            }
+            else if (mail.body.kind === 'signal') {
+                if (!graph.get(mail.body.target)) {
+                    return deny('missing_causation', `Signal ${mail.id} from actor ${sender} targets unknown mail ${mail.body.target}`);
+                }
+            }
+            else if (!senderAuthority
+                || !isAttenuationOf(mail.authority, senderAuthority)
+                || mail.authority.chain.at(-1) !== sender) {
+                return deny('authority_not_attenuated', senderAuthority
+                    ? `Mail ${mail.id} from actor ${sender} to ${mail.to} carries authority wider than the sender's own`
+                    : `Mail ${mail.id} from actor ${sender} to ${mail.to} has no sender authority to attenuate from`);
+            }
+        }
+        // 4. Contacts and target acceptance
+        const targetAgent = agentOf(mail.to);
+        const contactKind = mail.kind === 'ask' || mail.kind === 'delegate' || mail.kind === 'tell';
+        if (mail.from.kind === 'actor' && contactKind) {
+            // senderAuthority is present here: step 3 denied otherwise.
+            if (!senderAuthority || !scopeHas(senderAuthority.contacts, targetAgent)) {
+                return deny('contact_not_allowed', `Actor ${mail.from.actor} may not contact agent ${targetAgent} (not in its contacts)`);
+            }
+            const fromAgent = agentOf(mail.from.actor);
+            if (!scopeHas(targetCeiling.acceptsFrom, fromAgent)) {
+                return deny('not_accepted_by_target', `Agent ${targetAgent} does not accept ${mail.kind} mail from agent ${fromAgent}`);
+            }
+        }
+        else if (mail.from.kind === 'human' && mail.kind === 'human') {
+            if (!scopeHas(targetCeiling.acceptsFrom, 'human')) {
+                return deny('not_accepted_by_target', `Agent ${targetAgent} does not accept mail from humans (sender ${mail.from.principal.id})`);
+            }
+        }
+        // 5–7 apply to ask / delegate only
+        if (isAskOrDelegate(mail)) {
+            // 5. Depth (invariant 5)
+            const depth = depthOf(mail, graph);
+            if (depth > limits.maxDepth) {
+                return deny('depth_exceeded', `${mail.kind} from ${who} to ${mail.to} would reach delegation depth ${depth}, above the limit of ${limits.maxDepth}`, true);
+            }
+            // 6. Fanout
+            const fanout = graph.mails.filter(isAskOrDelegate).length + 1;
+            if (fanout > limits.maxFanout) {
+                return deny('fanout_exceeded', `${mail.kind} from ${who} to ${mail.to} would be ask/delegate #${fanout} in engagement ${graph.engagement.id}, above the limit of ${limits.maxFanout}`, true);
+            }
+            // 7. Pair round trips
+            if (mail.from.kind === 'actor') {
+                const a = mail.from.actor;
+                const b = mail.to;
+                const exchanged = graph.mails.filter((m) => isAskOrDelegate(m) &&
+                    m.from.kind === 'actor' &&
+                    ((m.from.actor === a && m.to === b) || (m.from.actor === b && m.to === a))).length;
+                if (exchanged + 1 > limits.maxPairRoundTrips) {
+                    return deny('pair_round_trips_exceeded', `Actors ${a} and ${b} would exchange ask/delegate #${exchanged + 1}, above the limit of ${limits.maxPairRoundTrips}`, true);
+                }
+            }
+        }
+        // 8. Duplicates
+        const content = contentOf(mail);
+        if (content !== undefined) {
+            const key = senderKey(mail.from);
+            const sent = graph.mails.filter((m) => m.kind === mail.kind && m.to === mail.to && senderKey(m.from) === key && contentOf(m) === content).length;
+            if (sent + 1 > limits.maxDuplicates) {
+                return deny('duplicate_mail', `${who} would send the same ${mail.kind} to ${mail.to} ${sent + 1} times, above the limit of ${limits.maxDuplicates}`, true);
+            }
+        }
+        return ALLOW;
+    }
+    return Object.freeze({ admitMail });
+}

package/lib/harness.d.ts

@@ -0,0 +1,197 @@
+/**
+ * ADR 0048 Agent Harness — composition (H1).
+ *
+ * Wires the components behind the contracts: every mail is attenuated,
+ * funded from its sender's grant, admitted by the guard kernel, journaled,
+ * and only then posted to the mailbox. The agent layer supplies the turn
+ * runner and calls `send` from its collaboration tools.
+ *
+ * Semantics:
+ * - `ask` is synchronous for the asker: `send` resolves with the target's
+ *   reply; the reply is journaled as a `result` mail but not posted to the
+ *   asker's mailbox (the asker's turn is still running and consumes it).
+ * - `delegate` is asynchronous: `send` resolves once the work is admitted;
+ *   the target's reply is posted to the delegator's mailbox as a `result`
+ *   mail, which wakes it with a new turn.
+ * - `tell` expects nothing back.
+ * - An `ask` whose target is (transitively) waiting on the asker would
+ *   deadlock the serial mailbox; it is denied as `wait_cycle` and escalated.
+ * - A denial with `escalate: true` freezes the whole engagement: an
+ *   `escalated` event is journaled, `onEscalate` is called once so the host
+ *   can ask the principal, every outstanding ask / delegate is cancelled
+ *   (askers get a `cancelled` reply), and later sends are denied as `frozen`.
+ * - An engagement closes when it has no running or queued turns and no
+ *   outstanding ask / delegate; its root grant is closed then.
+ * - Inbound mail (`human` / `timer` / `event`) enters through `deliver`
+ *   (`open` is the same call): it opens an engagement and posts the root mail
+ *   into the entry actor's inbox lane (D1). The inbox policy (`inbox.policy`,
+ *   D2) decides what the mail does to that lane, also while a turn of the
+ *   lane is running (mid-turn): queue, merge, supersede the running turn,
+ *   stop it, or reject. Every turn of every actor runs inside the mailbox;
+ *   there is no externally running root turn (H3, Q6).
+ * - A merged batch (Q2) may span several engagements (one per human
+ *   message); each engagement is accounted for by its own mails.
+ * - A `result` for a mail that ran on an explicit lane returns on that lane,
+ *   so delegated results wait for the lane's running turn (the root turn)
+ *   instead of running beside it.
+ */
+import { type ActorId, type ActorTurnResult, type ActorTurnRunner, type AgentCeiling, type AgentName, type Authority, type AuthorityNarrowing, type BoardEntry, type BoardReadFilter, type BoardWriteInput, type BudgetAmounts, type BudgetLedger, type BudgetResult, type BudgetSnapshot, type Engagement, type EngagementGraphView, type EngagementId, type EngagementJournal, type FollowUpInput, type GuardDenyCode, type GuardKernel, type GuardLimits, type Mail, type MailBody, type MailId, type Mailbox, type InboxDropReason, type InboxPolicy, type InboxRejectCode, type InboxSetTimer, type MailboxOptions, type PostResult, type Principal, type RemoteMailTransport, type SendAck, type VenueRef } from './contracts.js';
+export type HarnessDenyCode = GuardDenyCode | InboxRejectCode | 'unknown_agent' | 'wait_cycle' | 'budget_exceeded' | 'closed' | 'frozen';
+export type SendOutcome = {
+    readonly ok: true;
+    readonly accepted?: true;
+    readonly mailId?: MailId;
+    readonly mail: Mail;
+    readonly reply?: {
+        readonly status: ActorTurnResult['status'];
+        readonly content: string;
+    };
+    readonly result?: {
+        readonly status: ActorTurnResult['status'] | 'rejected';
+        readonly content: string;
+    };
+} | {
+    readonly ok: false;
+    readonly accepted?: false;
+    readonly mailId?: MailId;
+    readonly mail?: Mail;
+    readonly code: HarnessDenyCode;
+    readonly reason: string;
+    readonly escalated: boolean;
+    readonly reply?: {
+        readonly status: ActorTurnResult['status'];
+        readonly content: string;
+    };
+    readonly result?: {
+        readonly status: ActorTurnResult['status'] | 'rejected';
+        readonly content: string;
+    };
+};
+export interface SendRequest {
+    readonly kind: 'ask' | 'delegate' | 'tell';
+    readonly to: ActorId;
+    readonly text: string;
+    readonly narrowing?: AuthorityNarrowing;
+    readonly budget?: Partial<BudgetAmounts>;
+    /** For `delegate`: what the delegator expects back. */
+    readonly deliverable?: string;
+    /** Optional timeout (ms) for remote transport calls. */
+    readonly timeoutMs?: number;
+}
+export interface OpenEngagementInput {
+    readonly principal: Principal;
+    /** Actor that receives the root mail (the venue's entry actor). */
+    readonly entry: ActorId;
+    readonly body: Extract<MailBody, {
+        kind: 'human' | 'timer' | 'event';
+    }>;
+    readonly budget: BudgetAmounts;
+    readonly approvers?: readonly string[];
+    readonly venue?: VenueRef;
+    /**
+     * Serial lane of the root mail inside the entry actor's inbox (D1): the IM
+     * session key for human and scene-event mail, `timer:<jobId>` for timers,
+     * `event:<source>` for webhooks. Omitted = the engagement's own lane.
+     */
+    readonly lane?: string;
+    /**
+     * Called synchronously with the admitted root mail right before it is
+     * posted. The inbox may start its turn in the next microtask, before
+     * `deliver` resolves, so a host that correlates turns with its own
+     * callers registers the mail here.
+     */
+    readonly onPosting?: (root: Mail) => void;
+}
+/** How the inbox took an inbound mail. `stopped`: it was a stop request and was consumed. */
+export type DeliverDisposition = Extract<PostResult, {
+    accepted: true;
+}>['disposition'];
+export type OpenOutcome = {
+    readonly ok: true;
+    readonly engagement: Engagement;
+    readonly root: Mail;
+    readonly disposition: DeliverDisposition;
+    /** 1-based queue position; 0 when consumed (`stopped`). */
+    readonly position: number;
+} | {
+    readonly ok: false;
+    readonly code: HarnessDenyCode;
+    readonly reason: string;
+};
+/** `deliver` and `open` are the same call. */
+export type DeliverOutcome = OpenOutcome;
+export interface EscalationNotice {
+    readonly engagement: Engagement;
+    readonly mail: Mail;
+    readonly code: HarnessDenyCode;
+    readonly reason: string;
+}
+export interface HarnessOptions {
+    readonly guard: GuardKernel;
+    readonly ledger: BudgetLedger;
+    readonly journal: EngagementJournal;
+    readonly createMailbox: (options: MailboxOptions) => Mailbox;
+    /**
+     * Agent definitions' ceilings; `undefined` = unknown agent. `engagementId`
+     * names the engagement asking, so a long-lived host can resolve agents per
+     * engagement (the directory of the turn that opened it).
+     */
+    readonly ceilingOf: (agent: AgentName, engagementId: EngagementId) => AgentCeiling | undefined;
+    readonly rootAuthority: (principal: Principal, ceiling: AgentCeiling, options?: {
+        approvers?: readonly string[];
+    }) => Authority;
+    readonly attenuate: (parent: Authority, narrowing: AuthorityNarrowing, target: AgentCeiling, via: ActorId) => Authority;
+    /** Runs one actor turn; the agent layer calls `harness.send` / `harness.charge` from inside it. */
+    readonly runTurn: ActorTurnRunner;
+    readonly limits?: GuardLimits;
+    readonly maxConcurrentTurns?: number;
+    readonly maxQueuedPerKey?: number;
+    /** Inbox scheduling (H3): policy (D2), queue TTL and the timer / clock windows use. */
+    readonly inbox?: Readonly<{
+        policy?: InboxPolicy;
+        queueTtlMs?: number;
+        now?: () => number;
+        setTimer?: InboxSetTimer;
+    }>;
+    readonly clock?: () => number;
+    readonly newId?: () => string;
+    readonly remoteTransport?: RemoteMailTransport;
+    readonly onEscalate?: (notice: EscalationNotice) => void | Promise<void>;
+    /** Called once when an engagement closed (after `engagement_closed` was journaled). */
+    readonly onEngagementClosed?: (engagement: Engagement) => void;
+    readonly onError?: (error: unknown) => void;
+}
+export type CreateHarnessOptions = HarnessOptions;
+export interface Harness {
+    /**
+     * Delivers an inbound mail (`human` / `timer` / `event`): opens its
+     * engagement and posts the root mail to the entry actor's inbox lane. May be
+     * called at any time, including while a turn of that lane is running
+     * (mid-turn delivery): the inbox policy then decides whether the new mail
+     * queues, merges, supersedes or stops the running turn (whose stale reply
+     * must then not be sent; see `ActorTurnControl.staleCheck`).
+     */
+    deliver(input: OpenEngagementInput): Promise<DeliverOutcome>;
+    /** Same as `deliver`. */
+    open(input: OpenEngagementInput): Promise<OpenOutcome>;
+    /** Remaining budget of the grant `current` runs on. */
+    remaining(current: Mail): BudgetAmounts | undefined;
+    /** Called by collaboration tools while `current` (the mail being processed) is running. */
+    send(from: ActorId, current: Mail, request: SendRequest): Promise<SendOutcome>;
+    /** Follows up on previously delegated / asked work within the same engagement. */
+    followUp(input: FollowUpInput): Promise<SendAck>;
+    /** Writes an artifact, note, or todo item to the engagement's shared blackboard. */
+    writeBoard(engagementId: EngagementId, input: BoardWriteInput): Promise<BoardEntry>;
+    /** Reads entries from the engagement's shared blackboard, reconstructing from journal if needed. */
+    readBoard(engagementId: EngagementId, filter?: BoardReadFilter): Promise<readonly BoardEntry[]>;
+    /** Records model / tool usage against the grant of `current`. */
+    charge(current: Mail, usage: Partial<BudgetAmounts>): Promise<BudgetResult<BudgetSnapshot>>;
+    cancel(mailId: MailId, reason?: string): boolean;
+    /** Drops every queued mail of `senderId` on one lane of `actor` (reported `cancelled` with `reason`). */
+    cancelSender(actor: ActorId, lane: string, senderId: string, reason?: InboxDropReason): number;
+    engagement(id: EngagementId): Engagement | undefined;
+    graph(id: EngagementId): EngagementGraphView | undefined;
+    idle(): Promise<void>;
+    close(reason?: string): Promise<void>;
+}
+export declare function createHarness(options: HarnessOptions): Harness;