@zhin.js/harness 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 凉菜
+
+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,9 @@
-# Temporary Holding Version
+# @zhin.js/harness
 
-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.
+ADR 0048 Agent Harness (published as a dependency of `@zhin.js/agent`): actors exchange **mail** inside an **engagement**; every mail carries an **authority** that can only be attenuated and a **budget grant** carved from its parent; a **guard kernel** decides delivery; an **engagement journal** records everything.
+
+See `docs/adr/0048-agent-harness.md`. The shared contracts live in `src/contracts.ts`; each component (authority, budget, guard, journal, mailbox) depends only on them.
+
+## Inbox policies (ADR 0048 H3)
+
+The mailbox serializes turns per `(actor, lane)`; a lane defaults to the engagement, and an IM session can use one lane for every human message it receives. An `InboxPolicy` (`onPost` / `ready` / `staleOf`) decides how queued mails become turns. `createInboxPolicy` (`src/policies/`) carries the IM admission rules that `TurnAdmissionGate` used to own: stop, same-sender supersede, burst coalescing, FIFO between members, merge windows, stale-reply discard and danmaku windows. Clock and timers can be injected.

package/lib/authority.d.ts

@@ -0,0 +1,37 @@
+/**
+ * ADR 0048 §3.4 invariant 1 — authority is only ever attenuated.
+ *
+ * Effective authority of a delegatee = delegator authority ∩ the narrowing
+ * declared at hand-off ∩ the delegatee agent's ceiling. Every function here is
+ * pure: inputs are never mutated and every returned object is frozen.
+ */
+import { type ActorId, type AgentCeiling, type AgentName, type Authority, type AuthorityNarrowing, type Principal, type TrustLevel } from './contracts.js';
+/** Negative when `a` is lower than `b`, 0 when equal, positive when higher. Throws on unknown levels. */
+export declare function compareTrust(a: TrustLevel, b: TrustLevel): number;
+/** The lowest of the given levels. Throws when called with none. */
+export declare function minTrust(...levels: readonly TrustLevel[]): TrustLevel;
+/**
+ * Authority of an engagement's root mail: what the principal may do through
+ * this agent. Approvers are the human principal first, then configured ids.
+ */
+export declare function rootAuthority(principal: Principal, ceiling: AgentCeiling, options?: {
+    readonly approvers?: readonly string[];
+}): Authority;
+/**
+ * Derives the authority handed to `target` by actor `via`. Never widens: a
+ * narrowing asking for more than the parent just gets the intersection.
+ * Principal and approvers are carried over unchanged.
+ */
+export declare function attenuate(parent: Authority, narrowing: AuthorityNarrowing, target: AgentCeiling, via: ActorId): Authority;
+/**
+ * `true` iff `child` is a single, valid attenuation step from `parent`:
+ * same principal and approvers, no wider trust / tools / contacts / egress,
+ * and a chain that extends the parent's by exactly one actor.
+ */
+export declare function isAttenuationOf(child: Authority, parent: Authority): boolean;
+/** Agent name of an actor id: the part before `#`. */
+export declare function agentOf(actor: ActorId): AgentName;
+export declare function canCall(authority: Authority, tool: string): boolean;
+/** Takes an agent name; use `agentOf(actor)` for actor ids. */
+export declare function canContact(authority: Authority, agentName: AgentName): boolean;
+export declare function allowsHost(authority: Authority, host: string): boolean;

package/lib/authority.js

@@ -0,0 +1,161 @@
+/**
+ * ADR 0048 §3.4 invariant 1 — authority is only ever attenuated.
+ *
+ * Effective authority of a delegatee = delegator authority ∩ the narrowing
+ * declared at hand-off ∩ the delegatee agent's ceiling. Every function here is
+ * pure: inputs are never mutated and every returned object is frozen.
+ */
+import { ALL, TRUST_LEVELS, intersectScopes, scopeHas, scopeWithin, } from './contracts.js';
+// ---------------------------------------------------------------------------
+// Trust
+// ---------------------------------------------------------------------------
+function trustRank(level) {
+    const rank = TRUST_LEVELS.indexOf(level);
+    if (rank < 0)
+        throw new TypeError(`Unknown trust level: ${String(level)}`);
+    return rank;
+}
+function isTrustLevel(value) {
+    return typeof value === 'string' && TRUST_LEVELS.includes(value);
+}
+/** Negative when `a` is lower than `b`, 0 when equal, positive when higher. Throws on unknown levels. */
+export function compareTrust(a, b) {
+    return trustRank(a) - trustRank(b);
+}
+/** The lowest of the given levels. Throws when called with none. */
+export function minTrust(...levels) {
+    if (levels.length === 0)
+        throw new TypeError('minTrust requires at least one level');
+    let lowest = levels[0];
+    for (const level of levels) {
+        if (compareTrust(level, lowest) < 0)
+            lowest = level;
+    }
+    trustRank(lowest);
+    return lowest;
+}
+// ---------------------------------------------------------------------------
+// Construction
+// ---------------------------------------------------------------------------
+function freezeScope(scope) {
+    return intersectScopes(scope, ALL);
+}
+function freezePrincipal(principal) {
+    return Object.freeze({
+        kind: principal.kind,
+        id: principal.id,
+        trust: principal.trust,
+        ...(principal.venue ? { venue: Object.freeze({ kind: principal.venue.kind, id: principal.venue.id }) } : {}),
+    });
+}
+function freezeEgress(network, hosts) {
+    return Object.freeze({ network, hosts: freezeScope(hosts) });
+}
+function dedupe(ids) {
+    return Object.freeze([...new Set(ids)]);
+}
+/**
+ * Authority of an engagement's root mail: what the principal may do through
+ * this agent. Approvers are the human principal first, then configured ids.
+ */
+export function rootAuthority(principal, ceiling, options = {}) {
+    const approvers = [...(principal.kind === 'human' ? [principal.id] : []), ...(options.approvers ?? [])];
+    return Object.freeze({
+        principal: freezePrincipal(principal),
+        trust: minTrust(principal.trust, ceiling.maxTrust),
+        tools: freezeScope(ceiling.tools),
+        contacts: freezeScope(ceiling.contacts),
+        egress: freezeEgress(ceiling.egress.network, ceiling.egress.hosts),
+        approvers: dedupe(approvers),
+        chain: Object.freeze([]),
+    });
+}
+/**
+ * Derives the authority handed to `target` by actor `via`. Never widens: a
+ * narrowing asking for more than the parent just gets the intersection.
+ * Principal and approvers are carried over unchanged.
+ */
+export function attenuate(parent, narrowing, target, via) {
+    const tools = intersectScopes(intersectScopes(parent.tools, narrowing.tools ?? ALL), target.tools);
+    const contacts = intersectScopes(intersectScopes(parent.contacts, narrowing.contacts ?? ALL), target.contacts);
+    const trust = minTrust(parent.trust, narrowing.trust ?? parent.trust, target.maxTrust);
+    const network = parent.egress.network && (narrowing.egress?.network ?? true) && target.egress.network;
+    const hosts = intersectScopes(intersectScopes(parent.egress.hosts, narrowing.egress?.hosts ?? ALL), target.egress.hosts);
+    return Object.freeze({
+        principal: freezePrincipal(parent.principal),
+        trust,
+        tools,
+        contacts,
+        egress: freezeEgress(network, hosts),
+        approvers: Object.freeze([...parent.approvers]),
+        chain: Object.freeze([...parent.chain, via]),
+    });
+}
+// ---------------------------------------------------------------------------
+// Verification (called by the guard kernel)
+// ---------------------------------------------------------------------------
+function sameJson(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null)
+        return false;
+    if (Array.isArray(a) !== Array.isArray(b))
+        return false;
+    const aKeys = Object.keys(a).filter((key) => a[key] !== undefined);
+    const bKeys = Object.keys(b).filter((key) => b[key] !== undefined);
+    if (aKeys.length !== bKeys.length)
+        return false;
+    return aKeys.every((key) => Object.prototype.hasOwnProperty.call(b, key) &&
+        sameJson(a[key], b[key]));
+}
+function sameList(a, b) {
+    return a.length === b.length && a.every((value, index) => value === b[index]);
+}
+/**
+ * `true` iff `child` is a single, valid attenuation step from `parent`:
+ * same principal and approvers, no wider trust / tools / contacts / egress,
+ * and a chain that extends the parent's by exactly one actor.
+ */
+export function isAttenuationOf(child, parent) {
+    if (!isTrustLevel(child.trust) || !isTrustLevel(parent.trust))
+        return false;
+    if (!isTrustLevel(child.principal.trust))
+        return false;
+    if (!sameJson(child.principal, parent.principal))
+        return false;
+    if (!sameList(child.approvers, parent.approvers))
+        return false;
+    if (compareTrust(child.trust, parent.trust) > 0)
+        return false;
+    if (compareTrust(child.trust, child.principal.trust) > 0)
+        return false;
+    if (!scopeWithin(child.tools, parent.tools))
+        return false;
+    if (!scopeWithin(child.contacts, parent.contacts))
+        return false;
+    if (child.egress.network && !parent.egress.network)
+        return false;
+    if (!scopeWithin(child.egress.hosts, parent.egress.hosts))
+        return false;
+    if (child.chain.length !== parent.chain.length + 1)
+        return false;
+    return parent.chain.every((actor, index) => child.chain[index] === actor);
+}
+// ---------------------------------------------------------------------------
+// Queries
+// ---------------------------------------------------------------------------
+/** Agent name of an actor id: the part before `#`. */
+export function agentOf(actor) {
+    const hash = actor.indexOf('#');
+    return hash < 0 ? actor : actor.slice(0, hash);
+}
+export function canCall(authority, tool) {
+    return scopeHas(authority.tools, tool);
+}
+/** Takes an agent name; use `agentOf(actor)` for actor ids. */
+export function canContact(authority, agentName) {
+    return scopeHas(authority.contacts, agentName);
+}
+export function allowsHost(authority, host) {
+    return authority.egress.network && scopeHas(authority.egress.hosts, host);
+}

package/lib/budget.d.ts

@@ -0,0 +1,48 @@
+/**
+ * In-memory conserved budget ledger (ADR 0048 §3.4 invariant 2).
+ *
+ * Semantics, per budget key:
+ * - consumed(g)  = g.ownSpent + Σ rolledUp(closed child), where
+ *                  rolledUp(c) = min(consumed(c), granted(c)).
+ *                  Overspend beyond a grant stays visible on that grant's own
+ *                  snapshot but never inflates the parent's accounting, so
+ *                  a subtree can never consume more than it was granted
+ *                  from above (conservation).
+ * - reserved(g)  = Σ granted(c) over OPEN children c.
+ * - remaining(g) = granted(g) - consumed(g) - reserved(g)  (may go negative
+ *                  after an overspending charge).
+ * - Snapshot: `spent` = consumed(g) (own + closed children), `reservedForChildren`
+ *   = reserved(g), `remaining` as above.
+ *
+ * grant(): requested keys above the parent's remaining fail whole with
+ * `budget_exceeded` (no partial grant, no clamping). Omitted keys default to
+ * floor(parent remaining / 2), never below 0. The child's granted amount is
+ * reserved on the parent immediately.
+ *
+ * charge(): always records the usage on an open grant; reports
+ * `budget_exceeded` (with the exhausted keys) when any remaining < 0.
+ *
+ * close(): closes open descendants first (deepest first), then the grant.
+ * The parent's reservation is released and the child's consumed amount is
+ * rolled up, i.e. unspent returns to the parent. Idempotent.
+ */
+import { type BudgetAmounts, type BudgetLedger, type BudgetResult, type BudgetSnapshot, type GrantId } from './contracts.js';
+export interface InMemoryBudgetLedgerOptions {
+    readonly idFactory?: () => GrantId;
+}
+export declare class InMemoryBudgetLedger implements BudgetLedger {
+    private readonly nodes;
+    private readonly idFactory;
+    constructor(options?: InMemoryBudgetLedgerOptions);
+    openRoot(amounts: BudgetAmounts): GrantId;
+    grant(parentId: GrantId, request: Partial<BudgetAmounts>): BudgetResult<GrantId>;
+    charge(grantId: GrantId, usage: Partial<BudgetAmounts>): BudgetResult<BudgetSnapshot>;
+    close(grantId: GrantId): BudgetResult<BudgetSnapshot>;
+    snapshot(grantId: GrantId): BudgetSnapshot | undefined;
+    private create;
+    private closeNode;
+    private consumed;
+    private reserved;
+    private remaining;
+    private snap;
+}

package/lib/budget.js

@@ -0,0 +1,154 @@
+/**
+ * In-memory conserved budget ledger (ADR 0048 §3.4 invariant 2).
+ *
+ * Semantics, per budget key:
+ * - consumed(g)  = g.ownSpent + Σ rolledUp(closed child), where
+ *                  rolledUp(c) = min(consumed(c), granted(c)).
+ *                  Overspend beyond a grant stays visible on that grant's own
+ *                  snapshot but never inflates the parent's accounting, so
+ *                  a subtree can never consume more than it was granted
+ *                  from above (conservation).
+ * - reserved(g)  = Σ granted(c) over OPEN children c.
+ * - remaining(g) = granted(g) - consumed(g) - reserved(g)  (may go negative
+ *                  after an overspending charge).
+ * - Snapshot: `spent` = consumed(g) (own + closed children), `reservedForChildren`
+ *   = reserved(g), `remaining` as above.
+ *
+ * grant(): requested keys above the parent's remaining fail whole with
+ * `budget_exceeded` (no partial grant, no clamping). Omitted keys default to
+ * floor(parent remaining / 2), never below 0. The child's granted amount is
+ * reserved on the parent immediately.
+ *
+ * charge(): always records the usage on an open grant; reports
+ * `budget_exceeded` (with the exhausted keys) when any remaining < 0.
+ *
+ * close(): closes open descendants first (deepest first), then the grant.
+ * The parent's reservation is released and the child's consumed amount is
+ * rolled up, i.e. unspent returns to the parent. Idempotent.
+ */
+import { BUDGET_KEYS, } from './contracts.js';
+const zero = () => ({ modelCalls: 0, tokens: 0, wallMs: 0, sideEffects: 0 });
+const valid = (n) => typeof n === 'number' && Number.isFinite(n) && n >= 0;
+export class InMemoryBudgetLedger {
+    nodes = new Map();
+    idFactory;
+    constructor(options = {}) {
+        let n = 0;
+        this.idFactory = options.idFactory ?? (() => `g${++n}`);
+    }
+    openRoot(amounts) {
+        for (const k of BUDGET_KEYS) {
+            if (!valid(amounts?.[k]))
+                throw new TypeError(`invalid budget amount for ${k}: ${String(amounts?.[k])}`);
+        }
+        return this.create(undefined, { ...amounts }).id;
+    }
+    grant(parentId, request) {
+        const parent = this.nodes.get(parentId);
+        if (!parent)
+            return fail('unknown_grant', `unknown grant ${parentId}`);
+        if (parent.closed)
+            return fail('grant_closed', `grant ${parentId} is closed`);
+        const bad = invalidKey(request);
+        if (bad)
+            return fail('invalid_amount', `invalid amount for ${bad}`);
+        const rem = this.remaining(parent);
+        const exhausted = BUDGET_KEYS.filter((k) => request[k] !== undefined && request[k] > rem[k]);
+        if (exhausted.length > 0) {
+            return fail('budget_exceeded', `requested more than parent remaining for: ${exhausted.join(', ')}`, exhausted);
+        }
+        const amounts = zero();
+        for (const k of BUDGET_KEYS)
+            amounts[k] = request[k] ?? Math.max(0, Math.floor(rem[k] / 2));
+        return { ok: true, value: this.create(parent, amounts).id };
+    }
+    charge(grantId, usage) {
+        const node = this.nodes.get(grantId);
+        if (!node)
+            return fail('unknown_grant', `unknown grant ${grantId}`);
+        const bad = invalidKey(usage);
+        if (bad)
+            return fail('invalid_amount', `invalid amount for ${bad}`);
+        if (node.closed)
+            return fail('grant_closed', `grant ${grantId} is closed`);
+        for (const k of BUDGET_KEYS)
+            node.ownSpent[k] += usage[k] ?? 0;
+        const rem = this.remaining(node);
+        const exhausted = BUDGET_KEYS.filter((k) => rem[k] < 0);
+        if (exhausted.length > 0) {
+            return fail('budget_exceeded', `budget exceeded for: ${exhausted.join(', ')}`, exhausted);
+        }
+        return { ok: true, value: this.snap(node) };
+    }
+    close(grantId) {
+        const node = this.nodes.get(grantId);
+        if (!node)
+            return fail('unknown_grant', `unknown grant ${grantId}`);
+        this.closeNode(node);
+        return { ok: true, value: this.snap(node) };
+    }
+    snapshot(grantId) {
+        const node = this.nodes.get(grantId);
+        return node ? this.snap(node) : undefined;
+    }
+    create(parent, granted) {
+        const id = this.idFactory();
+        const node = { id, parent, granted, ownSpent: zero(), rolledUp: zero(), children: [], closed: false };
+        this.nodes.set(id, node);
+        parent?.children.push(node);
+        return node;
+    }
+    closeNode(node) {
+        if (node.closed)
+            return;
+        for (const child of node.children)
+            this.closeNode(child);
+        node.closed = true;
+        if (node.parent) {
+            const consumed = this.consumed(node);
+            for (const k of BUDGET_KEYS)
+                node.parent.rolledUp[k] += Math.min(consumed[k], node.granted[k]);
+        }
+    }
+    consumed(node) {
+        const out = zero();
+        for (const k of BUDGET_KEYS)
+            out[k] = node.ownSpent[k] + node.rolledUp[k];
+        return out;
+    }
+    reserved(node) {
+        const out = zero();
+        for (const c of node.children)
+            if (!c.closed)
+                for (const k of BUDGET_KEYS)
+                    out[k] += c.granted[k];
+        return out;
+    }
+    remaining(node) {
+        const c = this.consumed(node);
+        const r = this.reserved(node);
+        const out = zero();
+        for (const k of BUDGET_KEYS)
+            out[k] = node.granted[k] - c[k] - r[k];
+        return out;
+    }
+    snap(node) {
+        return Object.freeze({
+            grantId: node.id,
+            ...(node.parent ? { parentId: node.parent.id } : {}),
+            granted: Object.freeze({ ...node.granted }),
+            spent: Object.freeze(this.consumed(node)),
+            reservedForChildren: Object.freeze(this.reserved(node)),
+            remaining: Object.freeze(this.remaining(node)),
+            closed: node.closed,
+        });
+    }
+}
+function invalidKey(amounts) {
+    if (amounts === null || typeof amounts !== 'object')
+        return BUDGET_KEYS[0];
+    return BUDGET_KEYS.find((k) => amounts[k] !== undefined && !valid(amounts[k]));
+}
+function fail(code, message, exhausted) {
+    return exhausted ? { ok: false, code, exhausted, message } : { ok: false, code, message };
+}