@zhin.js/harness 0.0.0-stage → 1.0.1

package/lib/policies/groups.js

@@ -0,0 +1,91 @@
+import { inboxMarkers } from './markers.js';
+export function classifyMail(mail, options) {
+    const m = inboxMarkers(mail);
+    if (options.live && m.live)
+        return 'live';
+    if (options.merge && m.mergeable && m.plainText)
+        return 'merge';
+    return 'single';
+}
+export function groupInbox(entries, options) {
+    const maxSenders = Math.max(1, Math.floor(options.merge?.maxSenders ?? 1));
+    const drafts = [];
+    const draftOf = new Map();
+    const byMail = new Map();
+    const findLast = (predicate) => {
+        for (let i = drafts.length - 1; i >= 0; i -= 1)
+            if (predicate(drafts[i]))
+                return drafts[i];
+        return undefined;
+    };
+    const open = (kind, plainText) => {
+        const d = { kind, own: new Set(), plainText };
+        drafts.push(d);
+        return d;
+    };
+    for (const entry of entries) {
+        if (entry.carriedInto !== undefined)
+            continue;
+        const m = inboxMarkers(entry.mail);
+        const kind = classifyMail(entry.mail, options);
+        let d;
+        if (kind === 'live') {
+            d = findLast((g) => g.kind === 'live') ?? open('live', true);
+        }
+        else if (kind === 'merge') {
+            d = findLast((g) => g.kind === 'merge' && g.own.has(m.senderId))
+                ?? findLast((g) => g.kind === 'merge' && g.own.size < maxSenders)
+                ?? open('merge', true);
+        }
+        else {
+            const own = findLast((g) => g.own.has(m.senderId));
+            d = own && own.kind === 'single' && own.plainText && m.plainText ? own : open('single', m.plainText);
+        }
+        d.own.add(m.senderId);
+        draftOf.set(entry, d);
+        byMail.set(entry.mail.id, d);
+    }
+    for (const entry of entries) {
+        if (entry.carriedInto === undefined)
+            continue;
+        const target = byMail.get(entry.carriedInto);
+        if (target) {
+            draftOf.set(entry, target);
+        }
+        else {
+            const d = { kind: 'single', own: new Set([inboxMarkers(entry.mail).senderId]), plainText: inboxMarkers(entry.mail).plainText };
+            draftOf.set(entry, d);
+        }
+    }
+    const order = [];
+    const members = new Map();
+    for (const entry of entries) {
+        const d = draftOf.get(entry);
+        let list = members.get(d);
+        if (!list) {
+            list = [];
+            members.set(d, list);
+            order.push(d);
+        }
+        list.push(entry);
+    }
+    return order.map((d) => {
+        const list = members.get(d);
+        const own = list.filter((e) => e.carriedInto === undefined);
+        const times = (own.length > 0 ? own : list).map((e) => e.postedAt);
+        const senders = [];
+        for (const e of list) {
+            const s = inboxMarkers(e.mail).senderId;
+            if (!senders.includes(s))
+                senders.push(s);
+        }
+        return Object.freeze({
+            kind: d.kind,
+            entries: Object.freeze(list),
+            senders: Object.freeze(senders),
+            plainText: d.plainText,
+            openedAt: Math.min(...times),
+            lastJoinedAt: Math.max(...times),
+        });
+    });
+}

package/lib/policies/index.d.ts

@@ -0,0 +1,5 @@
+export * from './markers.js';
+export * from './groups.js';
+export * from './merge.js';
+export * from './live.js';
+export * from './admission.js';

package/lib/policies/index.js

@@ -0,0 +1,5 @@
+export * from './markers.js';
+export * from './groups.js';
+export * from './merge.js';
+export * from './live.js';
+export * from './admission.js';

package/lib/policies/live.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Danmaku window (ADR 0038 §5) as an inbox policy part.
+ *
+ * Every danmaku of a lane waits in one window that closes `windowMs` after
+ * its first mail, but never sooner than `minIntervalMs` after the lane's
+ * previous danmaku turn ended. No sender limit; the window keeps the newest
+ * `LIVE_WINDOW_MAX_MESSAGES` mails (older ones are evicted, counted in
+ * `InboxTurnFacts.evicted`), and one turn answers it.
+ */
+import type { InboxEntry, MailId } from '../contracts.js';
+import type { InboxGroup } from './groups.js';
+export interface LiveWindowOptions {
+    /** Answer the window this long after its first danmaku. */
+    readonly windowMs: number;
+    /** Never start a danmaku turn sooner than this after the lane's previous one ended. */
+    readonly minIntervalMs: number;
+}
+/** Danmaku one window keeps for the model; older ones are evicted. */
+export declare const LIVE_WINDOW_MAX_MESSAGES = 100;
+export declare function normalizeLiveWindow(options: LiveWindowOptions): LiveWindowOptions;
+/** When a live group may be answered; `lastLiveEndedAt` = end of the lane's previous danmaku turn. */
+export declare function liveWindowDueAt(group: Pick<InboxGroup, 'openedAt'>, lastLiveEndedAt: number | undefined, options: LiveWindowOptions): number;
+/**
+ * Mails to evict so a live group keeps at most `max` mails: the earliest
+ * sender's oldest mail goes first (as the former gate did), so memory stays
+ * bounded however busy the room is.
+ */
+export declare function liveEvictions(entries: readonly InboxEntry[], max?: number): readonly MailId[];

package/lib/policies/live.js

@@ -0,0 +1,44 @@
+import { inboxMarkers } from './markers.js';
+/** Danmaku one window keeps for the model; older ones are evicted. */
+export const LIVE_WINDOW_MAX_MESSAGES = 100;
+export function normalizeLiveWindow(options) {
+    return Object.freeze({
+        windowMs: Math.max(0, options.windowMs),
+        minIntervalMs: Math.max(0, options.minIntervalMs),
+    });
+}
+/** When a live group may be answered; `lastLiveEndedAt` = end of the lane's previous danmaku turn. */
+export function liveWindowDueAt(group, lastLiveEndedAt, options) {
+    return Math.max(group.openedAt + options.windowMs, lastLiveEndedAt === undefined ? 0 : lastLiveEndedAt + options.minIntervalMs);
+}
+/**
+ * Mails to evict so a live group keeps at most `max` mails: the earliest
+ * sender's oldest mail goes first (as the former gate did), so memory stays
+ * bounded however busy the room is.
+ */
+export function liveEvictions(entries, max = LIVE_WINDOW_MAX_MESSAGES) {
+    const excess = entries.length - Math.max(0, max);
+    if (excess <= 0)
+        return [];
+    const order = [];
+    const by = new Map();
+    for (const e of entries) {
+        const s = inboxMarkers(e.mail).senderId;
+        let list = by.get(s);
+        if (!list) {
+            list = [];
+            by.set(s, list);
+            order.push(s);
+        }
+        list.push(e.mail.id);
+    }
+    const out = [];
+    for (const s of order) {
+        for (const id of by.get(s)) {
+            if (out.length >= excess)
+                return out;
+            out.push(id);
+        }
+    }
+    return out;
+}

package/lib/policies/markers.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Reads the inbox-policy markers of a mail (ADR 0048 H3).
+ *
+ * Only `human` mail carries markers (`MailBody.human`). Every other kind is
+ * an ordinary, non-plain, non-mergeable mail from its transport sender, so
+ * actor / timer / event mail is never merged into, superseded by, or used to
+ * stop a human's turn.
+ */
+import { type Mail } from '../contracts.js';
+export interface InboxMarkers {
+    readonly senderId: string;
+    readonly senderName?: string;
+    readonly text: string;
+    readonly messageId?: string;
+    readonly human: boolean;
+    readonly plainText: boolean;
+    readonly mergeable: boolean;
+    readonly live: boolean;
+    readonly isMaster: boolean;
+    readonly isStop: boolean;
+    readonly unaddressed: boolean;
+}
+export declare function inboxMarkers(mail: Mail): InboxMarkers;

package/lib/policies/markers.js

@@ -0,0 +1,42 @@
+/**
+ * Reads the inbox-policy markers of a mail (ADR 0048 H3).
+ *
+ * Only `human` mail carries markers (`MailBody.human`). Every other kind is
+ * an ordinary, non-plain, non-mergeable mail from its transport sender, so
+ * actor / timer / event mail is never merged into, superseded by, or used to
+ * stop a human's turn.
+ */
+import { senderOf } from '../contracts.js';
+function textOf(mail) {
+    const body = mail.body;
+    switch (body.kind) {
+        case 'human': return body.text;
+        case 'ask': return body.question;
+        case 'delegate': return body.brief;
+        case 'tell': return body.content;
+        case 'result': return body.content;
+        case 'timer': return body.content;
+        default: return '';
+    }
+}
+export function inboxMarkers(mail) {
+    const senderId = senderOf(mail);
+    const text = textOf(mail);
+    const body = mail.body;
+    if (body.kind !== 'human') {
+        return { senderId, text, human: false, plainText: false, mergeable: false, live: false, isMaster: false, isStop: false, unaddressed: false };
+    }
+    return {
+        senderId,
+        ...(body.senderName ? { senderName: body.senderName } : {}),
+        text,
+        ...(body.messageId ? { messageId: body.messageId } : {}),
+        human: true,
+        plainText: body.plainText === true,
+        mergeable: body.mergeable === true,
+        live: body.live === true,
+        isMaster: body.isMaster === true,
+        isStop: body.isStop === true,
+        unaddressed: body.unaddressed === true,
+    };
+}

package/lib/policies/merge.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Merge window (ADR 0038 §1) as an inbox policy part, plus the helpers a
+ * merged turn needs (ADR 0048 H3, Q2).
+ *
+ * A merge group is answered once it went quiet for `quietMs` or, at the
+ * latest, `maxWaitMs` after it opened. Q2 (accepted): a merged batch runs in
+ * its first mail's engagement; its principal is the first human sender; its
+ * authority is the intersection of every sender's authority. These helpers
+ * are exposed now; wiring them into the IM turn is PR-2.
+ */
+import { type Authority, type Mail, type Principal } from '../contracts.js';
+import type { InboxGroup } from './groups.js';
+export interface MergeWindowOptions {
+    /** Flush once no new mail joined the window for this long. */
+    readonly quietMs: number;
+    /** Flush at the latest this long after the window opened. */
+    readonly maxWaitMs: number;
+    /** Senders one window may hold; further senders open the next window. */
+    readonly maxSenders: number;
+}
+export declare function normalizeMergeWindow(options: MergeWindowOptions): MergeWindowOptions;
+/** When a merge group may be answered. */
+export declare function mergeWindowDueAt(group: Pick<InboxGroup, 'openedAt' | 'lastJoinedAt'>, options: MergeWindowOptions): number;
+/** One sender's mails in a batch, in arrival order. */
+export interface InboxParticipant {
+    readonly senderId: string;
+    readonly senderName?: string;
+    readonly texts: readonly string[];
+    /** Platform message ids behind `texts`, when known. */
+    readonly messageIds?: readonly string[];
+    readonly mails: readonly Mail[];
+}
+/** Groups a batch by sender, senders in order of their first mail. */
+export declare function participantsOf(batch: readonly Mail[]): readonly InboxParticipant[];
+/**
+ * One sender: their texts joined by newlines. Several senders: one
+ * `name: text` line per sender so the model can tell who asked what.
+ */
+export declare function renderInboxText(participants: readonly InboxParticipant[]): string;
+/** Q2: the principal of a merged batch is its first human sender. */
+export declare function firstHumanPrincipal(batch: readonly Mail[]): Principal | undefined;
+/**
+ * Q2: the authority of a merged batch is the intersection of its mails'
+ * authorities (trust = lowest, tools / contacts / egress hosts = common,
+ * network only when everyone has it). Principal, approvers and chain stay
+ * those of the first human mail (approvals go to that principal), so the
+ * result never exceeds any sender's authority.
+ */
+export declare function mergedAuthority(batch: readonly Mail[]): Authority | undefined;

package/lib/policies/merge.js

@@ -0,0 +1,101 @@
+/**
+ * Merge window (ADR 0038 §1) as an inbox policy part, plus the helpers a
+ * merged turn needs (ADR 0048 H3, Q2).
+ *
+ * A merge group is answered once it went quiet for `quietMs` or, at the
+ * latest, `maxWaitMs` after it opened. Q2 (accepted): a merged batch runs in
+ * its first mail's engagement; its principal is the first human sender; its
+ * authority is the intersection of every sender's authority. These helpers
+ * are exposed now; wiring them into the IM turn is PR-2.
+ */
+import { intersectScopes } from '../contracts.js';
+import { minTrust } from '../authority.js';
+import { inboxMarkers } from './markers.js';
+export function normalizeMergeWindow(options) {
+    return Object.freeze({
+        quietMs: Math.max(0, options.quietMs),
+        maxWaitMs: Math.max(0, options.maxWaitMs),
+        maxSenders: Math.max(1, Math.floor(options.maxSenders)),
+    });
+}
+/** When a merge group may be answered. */
+export function mergeWindowDueAt(group, options) {
+    return Math.min(group.lastJoinedAt + options.quietMs, group.openedAt + options.maxWaitMs);
+}
+/** Groups a batch by sender, senders in order of their first mail. */
+export function participantsOf(batch) {
+    const order = [];
+    const by = new Map();
+    for (const mail of batch) {
+        const m = inboxMarkers(mail);
+        let p = by.get(m.senderId);
+        if (!p) {
+            p = { ...(m.senderName ? { senderName: m.senderName } : {}), texts: [], messageIds: [], mails: [] };
+            by.set(m.senderId, p);
+            order.push(m.senderId);
+        }
+        if (!p.senderName && m.senderName)
+            p.senderName = m.senderName;
+        p.texts.push(m.text);
+        if (m.messageId)
+            p.messageIds.push(m.messageId);
+        p.mails.push(mail);
+    }
+    return Object.freeze(order.map((senderId) => {
+        const p = by.get(senderId);
+        return Object.freeze({
+            senderId,
+            ...(p.senderName ? { senderName: p.senderName } : {}),
+            texts: Object.freeze(p.texts),
+            ...(p.messageIds.length > 0 ? { messageIds: Object.freeze(p.messageIds) } : {}),
+            mails: Object.freeze(p.mails),
+        });
+    }));
+}
+/**
+ * One sender: their texts joined by newlines. Several senders: one
+ * `name: text` line per sender so the model can tell who asked what.
+ */
+export function renderInboxText(participants) {
+    const lines = (p) => p.texts.filter((text) => text.trim());
+    if (participants.length === 1)
+        return lines(participants[0]).join('\n');
+    return participants
+        .map((p) => ({ name: p.senderName?.trim() || p.senderId, texts: lines(p) }))
+        .filter((p) => p.texts.length > 0)
+        .map((p) => `${p.name}: ${p.texts.join('\n')}`)
+        .join('\n');
+}
+/** Q2: the principal of a merged batch is its first human sender. */
+export function firstHumanPrincipal(batch) {
+    for (const mail of batch)
+        if (mail.from.kind === 'human')
+            return mail.from.principal;
+    return undefined;
+}
+/**
+ * Q2: the authority of a merged batch is the intersection of its mails'
+ * authorities (trust = lowest, tools / contacts / egress hosts = common,
+ * network only when everyone has it). Principal, approvers and chain stay
+ * those of the first human mail (approvals go to that principal), so the
+ * result never exceeds any sender's authority.
+ */
+export function mergedAuthority(batch) {
+    if (batch.length === 0)
+        return undefined;
+    const lead = batch.find((mail) => mail.from.kind === 'human') ?? batch[0];
+    const all = batch.map((mail) => mail.authority);
+    const base = lead.authority;
+    return Object.freeze({
+        principal: base.principal,
+        trust: minTrust(...all.map((a) => a.trust)),
+        tools: all.reduce((scope, a) => intersectScopes(scope, a.tools), base.tools),
+        contacts: all.reduce((scope, a) => intersectScopes(scope, a.contacts), base.contacts),
+        egress: Object.freeze({
+            network: all.every((a) => a.egress.network),
+            hosts: all.reduce((scope, a) => intersectScopes(scope, a.egress.hosts), base.egress.hosts),
+        }),
+        approvers: base.approvers,
+        chain: base.chain,
+    });
+}

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@zhin.js/harness",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.1",
+  "description": "ADR 0048 Agent Harness: actors, mail, engagements, attenuated authority, budgets and the guard kernel",
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js"
+    }
+  },
+  "files": [
+    "lib",
+    "README.md"
+  ],
+  "devDependencies": {
+    "@types/node": "^26.1.2",
+    "typescript": "^6.0.3",
+    "@zhin.js/database": "1.1.7"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zhinjs/zhin.git",
+    "directory": "packages/im/harness"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "license": "MIT",
+  "private": false,
+  "scripts": {
+    "build": "tsc",
+    "clean": "rimraf lib",
+    "test": "vitest run --root ../../.. packages/im/harness/tests"
+  }
 }