@animalabs/agent-framework 0.21.1 → 0.22.0

package/dist/src/record-journal.d.ts

@@ -0,0 +1,127 @@
+/**
+ * An append-only journal of typed Chronicle records that does not follow
+ * branch switches.
+ *
+ * Chronicle's branch state — snapshot, tree and log states — rewinds with a
+ * historical rollback (createBranchAt + switchBranch). Typed records do not:
+ * `getRecordIdsByType` enumerates them from every branch, in global order, and
+ * they survive `deleteBranch`, reopen and a hard kill. A journal is for state
+ * that must not rewind with the conversation but should live and die with its
+ * store: what a workspace's disk last agreed with, what reached a recipient,
+ * what became of a suppressed draft.
+ *
+ * Durability. A record append reaches the OS before `append` returns, so it
+ * survives a killed process, while branch-state commits are buffered until
+ * `store.sync()`: a record appended after a state commit can outlive that
+ * commit. Two barriers, each named where it's needed and neither implied by
+ * the `{id, sequence}` an append returns:
+ *  - `afterCommittedState: true` syncs BEFORE appending — for an entry that
+ *    asserts state committed just before it, so the entry can never survive
+ *    without that state;
+ *  - `durable: true` syncs AFTER appending — for an entry that must be on
+ *    stable storage before the caller acts on it (an attempt before its
+ *    outbound request, an intent before its disk effect).
+ *
+ * Checkpoints bound the replay at open: `checkpoint(snapshot)` records the
+ * caller's reduced state together with the last entry it covers, and `load()`
+ * returns the latest checkpoint's snapshot plus only the entries appended
+ * after it. A journal that never checkpoints replays everything. What entries
+ * mean, how they reduce, and when to checkpoint stay with the caller.
+ *
+ * One writer per record type: a checkpoint covers every entry up to the last
+ * one THIS journal loaded or appended, so entries another instance appended
+ * to the same type in between would be covered without being reduced.
+ *
+ * An ambiguous write must be resolved before the journal writes again. Once
+ * `append` or `checkpoint` has handed a record to the store, a failure leaves
+ * a record the caller didn't reduce, or may leave one, and a later checkpoint
+ * would cover it without its ever entering the reducer. There are two kinds:
+ *  - The store's append itself throws. Its record may still be in the store's
+ *    log, outside this process's view of the store: the store writes a
+ *    record to its log, syncs the log every so often, and only then indexes
+ *    the record, which is what `getRecordIdsByType` reads. So a failed sync
+ *    leaves a record that reopening the store will find and no `load()` on
+ *    this store can. Nothing but a reopen rereads the log, so from then on
+ *    every `append` and `checkpoint` throws, for the life of the journal. A
+ *    journal on the store reopened, as at the next start, loads that record
+ *    with its tail for the caller to reduce.
+ *  - A failure after the append returned: a `durable` barrier, or reading
+ *    the id it returned. The record is in this process's view, so every
+ *    further `append` and `checkpoint` throws until `load()` has replayed the
+ *    tail, that record included, for the caller to reduce.
+ * A failure BEFORE the record reaches the store (the `afterCommittedState`
+ * sync) wrote nothing and leaves the journal usable.
+ */
+import type { JsStore } from '@animalabs/chronicle';
+/** Where an appended record landed. Not a durability receipt — see the barriers. */
+export interface JournalRecordRef {
+    /** Chronicle record id: global, increasing in append order. */
+    id: string;
+    /** The record's sequence on the branch current when it was appended. */
+    sequence: number;
+}
+export interface JournalEntry<Entry> extends JournalRecordRef {
+    entry: Entry;
+}
+export interface JournalLoad<Entry, Snapshot> {
+    /** The latest checkpoint's snapshot, or null when none was written. */
+    snapshot: Snapshot | null;
+    /** Every entry appended after that checkpoint, in append order. */
+    entries: Array<JournalEntry<Entry>>;
+}
+export interface AppendOptions {
+    /** `store.sync()` before appending: the entry asserts state committed just before it. */
+    afterCommittedState?: boolean;
+    /** `store.sync()` after appending: the entry must be on stable storage before the caller acts. */
+    durable?: boolean;
+}
+export declare class RecordJournal<Entry, Snapshot = never> {
+    private readonly store;
+    /** Record type of the entries. */
+    readonly type: string;
+    /** Record type of the checkpoints. */
+    readonly checkpointType: string;
+    /** Highest entry id this journal has loaded or appended (0 when none). */
+    private lastEntryId;
+    private sinceCheckpoint;
+    /** Set by a failure after the store's append returned; cleared by load(). */
+    private unreconciled;
+    /** Set when the store's append itself threw: its record may be in the log
+     *  but not in this process's view of the store. Never cleared. */
+    private unreadable;
+    constructor(store: JsStore, opts: {
+        type: string;
+        checkpointType?: string;
+    });
+    /** Entries appended since the last checkpoint (or since load, when there was none). */
+    get entriesSinceCheckpoint(): number;
+    /**
+     * The latest checkpoint and every entry after it, whichever branch each was
+     * appended on. The caller rebuilds its reduced state from exactly these —
+     * at open, and to reconcile after an ambiguous write. Also positions the
+     * journal, so later checkpoints cover what was loaded.
+     */
+    load(): JournalLoad<Entry, Snapshot>;
+    /** True after a failure that load() can resolve, until it has replayed the
+     *  tail. An append that threw inside the store is never resolved here: the
+     *  journal stays unwritable until a journal on the reopened store loads it. */
+    get needsReconcile(): boolean;
+    /** True once an append threw inside the store, for the rest of the
+     *  journal's life. What `load()` returns may then lack that append's record,
+     *  so a caller that decides from the journal's contents can't trust them
+     *  until a journal on the reopened store has loaded it. */
+    get needsReopen(): boolean;
+    /** Append one entry. The returned ref says where it landed, not that it's durable. */
+    append(entry: Entry, opts?: AppendOptions): JournalRecordRef;
+    /**
+     * Record the caller's reduced state as covering every entry this journal has
+     * loaded or appended. Like an entry, it's durable only with `durable`.
+     */
+    checkpoint(snapshot: Snapshot, opts?: {
+        durable?: boolean;
+    }): JournalRecordRef;
+    /** Hand one record to the store; any failure from here on is ambiguous. */
+    private write;
+    private assertReconciled;
+}
+//# sourceMappingURL=record-journal.d.ts.map

package/dist/src/record-journal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-journal.d.ts","sourceRoot":"","sources":["../../src/record-journal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAEpD,oFAAoF;AACpF,MAAM,WAAW,gBAAgB;IAC/B,+DAA+D;IAC/D,EAAE,EAAE,MAAM,CAAC;IACX,wEAAwE;IACxE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,YAAY,CAAC,KAAK,CAAE,SAAQ,gBAAgB;IAC3D,KAAK,EAAE,KAAK,CAAC;CACd;AAED,MAAM,WAAW,WAAW,CAAC,KAAK,EAAE,QAAQ;IAC1C,uEAAuE;IACvE,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC1B,mEAAmE;IACnE,OAAO,EAAE,KAAK,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC;CACrC;AAED,MAAM,WAAW,aAAa;IAC5B,yFAAyF;IACzF,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,kGAAkG;IAClG,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAsBD,qBAAa,aAAa,CAAC,KAAK,EAAE,QAAQ,GAAG,KAAK;IAChD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAU;IAChC,kCAAkC;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sCAAsC;IACtC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,0EAA0E;IAC1E,OAAO,CAAC,WAAW,CAAM;IACzB,OAAO,CAAC,eAAe,CAAK;IAC5B,6EAA6E;IAC7E,OAAO,CAAC,YAAY,CAAsB;IAC1C;sEACkE;IAClE,OAAO,CAAC,UAAU,CAAsB;gBAE5B,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,cAAc,CAAC,EAAE,MAAM,CAAA;KAAE;IAU3E,uFAAuF;IACvF,IAAI,sBAAsB,IAAI,MAAM,CAEnC;IAED;;;;;OAKG;IACH,IAAI,IAAI,WAAW,CAAC,KAAK,EAAE,QAAQ,CAAC;IAiCpC;;mFAE+E;IAC/E,IAAI,cAAc,IAAI,OAAO,CAE5B;IAED;;;+DAG2D;IAC3D,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED,sFAAsF;IACtF,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,GAAE,aAAkB,GAAG,gBAAgB;IAUhE;;;OAGG;IACH,UAAU,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,GAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,gBAAgB;IAQlF,2EAA2E;IAC3E,OAAO,CAAC,KAAK;IAmBb,OAAO,CAAC,gBAAgB;CAezB"}

package/dist/src/record-journal.js

@@ -0,0 +1,202 @@
+/**
+ * An append-only journal of typed Chronicle records that does not follow
+ * branch switches.
+ *
+ * Chronicle's branch state — snapshot, tree and log states — rewinds with a
+ * historical rollback (createBranchAt + switchBranch). Typed records do not:
+ * `getRecordIdsByType` enumerates them from every branch, in global order, and
+ * they survive `deleteBranch`, reopen and a hard kill. A journal is for state
+ * that must not rewind with the conversation but should live and die with its
+ * store: what a workspace's disk last agreed with, what reached a recipient,
+ * what became of a suppressed draft.
+ *
+ * Durability. A record append reaches the OS before `append` returns, so it
+ * survives a killed process, while branch-state commits are buffered until
+ * `store.sync()`: a record appended after a state commit can outlive that
+ * commit. Two barriers, each named where it's needed and neither implied by
+ * the `{id, sequence}` an append returns:
+ *  - `afterCommittedState: true` syncs BEFORE appending — for an entry that
+ *    asserts state committed just before it, so the entry can never survive
+ *    without that state;
+ *  - `durable: true` syncs AFTER appending — for an entry that must be on
+ *    stable storage before the caller acts on it (an attempt before its
+ *    outbound request, an intent before its disk effect).
+ *
+ * Checkpoints bound the replay at open: `checkpoint(snapshot)` records the
+ * caller's reduced state together with the last entry it covers, and `load()`
+ * returns the latest checkpoint's snapshot plus only the entries appended
+ * after it. A journal that never checkpoints replays everything. What entries
+ * mean, how they reduce, and when to checkpoint stay with the caller.
+ *
+ * One writer per record type: a checkpoint covers every entry up to the last
+ * one THIS journal loaded or appended, so entries another instance appended
+ * to the same type in between would be covered without being reduced.
+ *
+ * An ambiguous write must be resolved before the journal writes again. Once
+ * `append` or `checkpoint` has handed a record to the store, a failure leaves
+ * a record the caller didn't reduce, or may leave one, and a later checkpoint
+ * would cover it without its ever entering the reducer. There are two kinds:
+ *  - The store's append itself throws. Its record may still be in the store's
+ *    log, outside this process's view of the store: the store writes a
+ *    record to its log, syncs the log every so often, and only then indexes
+ *    the record, which is what `getRecordIdsByType` reads. So a failed sync
+ *    leaves a record that reopening the store will find and no `load()` on
+ *    this store can. Nothing but a reopen rereads the log, so from then on
+ *    every `append` and `checkpoint` throws, for the life of the journal. A
+ *    journal on the store reopened, as at the next start, loads that record
+ *    with its tail for the caller to reduce.
+ *  - A failure after the append returned: a `durable` barrier, or reading
+ *    the id it returned. The record is in this process's view, so every
+ *    further `append` and `checkpoint` throws until `load()` has replayed the
+ *    tail, that record included, for the caller to reduce.
+ * A failure BEFORE the record reaches the store (the `afterCommittedState`
+ * sync) wrote nothing and leaves the journal usable.
+ */
+const asError = (err) => (err instanceof Error ? err : new Error(String(err)));
+/** Record ids are decimal strings from one store-wide counter. */
+function idValue(id) {
+    if (!/^\d+$/.test(id))
+        throw new Error(`RecordJournal: unexpected chronicle record id "${id}"`);
+    return BigInt(id);
+}
+function decode(store, id) {
+    const record = store.getRecord(id);
+    if (!record)
+        throw new Error(`RecordJournal: record ${id} is listed but cannot be read`);
+    return { value: JSON.parse(Buffer.from(record.payload).toString('utf-8')), sequence: record.sequence };
+}
+export class RecordJournal {
+    store;
+    /** Record type of the entries. */
+    type;
+    /** Record type of the checkpoints. */
+    checkpointType;
+    /** Highest entry id this journal has loaded or appended (0 when none). */
+    lastEntryId = 0n;
+    sinceCheckpoint = 0;
+    /** Set by a failure after the store's append returned; cleared by load(). */
+    unreconciled = null;
+    /** Set when the store's append itself threw: its record may be in the log
+     *  but not in this process's view of the store. Never cleared. */
+    unreadable = null;
+    constructor(store, opts) {
+        if (!opts.type)
+            throw new Error('RecordJournal: a record type is required');
+        this.store = store;
+        this.type = opts.type;
+        this.checkpointType = opts.checkpointType ?? `${opts.type}/checkpoint`;
+        if (this.checkpointType === this.type) {
+            throw new Error('RecordJournal: entries and checkpoints need distinct record types');
+        }
+    }
+    /** Entries appended since the last checkpoint (or since load, when there was none). */
+    get entriesSinceCheckpoint() {
+        return this.sinceCheckpoint;
+    }
+    /**
+     * The latest checkpoint and every entry after it, whichever branch each was
+     * appended on. The caller rebuilds its reduced state from exactly these —
+     * at open, and to reconcile after an ambiguous write. Also positions the
+     * journal, so later checkpoints cover what was loaded.
+     */
+    load() {
+        let snapshot = null;
+        let through = 0n;
+        let latestCheckpoint = null;
+        let latestCheckpointId = null;
+        for (const id of this.store.getRecordIdsByType(this.checkpointType)) {
+            const value = idValue(id);
+            if (latestCheckpoint === null || value > latestCheckpoint) {
+                latestCheckpoint = value;
+                latestCheckpointId = id;
+            }
+        }
+        if (latestCheckpointId !== null) {
+            const payload = decode(this.store, latestCheckpointId).value;
+            snapshot = payload.snapshot;
+            through = idValue(payload.through);
+        }
+        const tail = this.store.getRecordIdsByType(this.type)
+            .map((id) => ({ id, value: idValue(id) }))
+            .filter(({ value }) => value > through)
+            .sort((a, b) => (a.value < b.value ? -1 : a.value > b.value ? 1 : 0));
+        const entries = tail.map(({ id }) => {
+            const { value, sequence } = decode(this.store, id);
+            return { id, sequence, entry: value };
+        });
+        this.lastEntryId = tail.length > 0 ? tail[tail.length - 1].value : through;
+        this.sinceCheckpoint = entries.length;
+        this.unreconciled = null;
+        return { snapshot, entries };
+    }
+    /** True after a failure that load() can resolve, until it has replayed the
+     *  tail. An append that threw inside the store is never resolved here: the
+     *  journal stays unwritable until a journal on the reopened store loads it. */
+    get needsReconcile() {
+        return this.unreconciled !== null;
+    }
+    /** True once an append threw inside the store, for the rest of the
+     *  journal's life. What `load()` returns may then lack that append's record,
+     *  so a caller that decides from the journal's contents can't trust them
+     *  until a journal on the reopened store has loaded it. */
+    get needsReopen() {
+        return this.unreadable !== null;
+    }
+    /** Append one entry. The returned ref says where it landed, not that it's durable. */
+    append(entry, opts = {}) {
+        this.assertReconciled();
+        if (opts.afterCommittedState)
+            this.store.sync();
+        return this.write(this.type, entry, opts.durable === true, (ref) => {
+            const value = idValue(ref.id);
+            if (value > this.lastEntryId)
+                this.lastEntryId = value;
+            this.sinceCheckpoint++;
+        });
+    }
+    /**
+     * Record the caller's reduced state as covering every entry this journal has
+     * loaded or appended. Like an entry, it's durable only with `durable`.
+     */
+    checkpoint(snapshot, opts = {}) {
+        this.assertReconciled();
+        const payload = { through: this.lastEntryId.toString(), snapshot };
+        return this.write(this.checkpointType, payload, opts.durable === true, () => {
+            this.sinceCheckpoint = 0;
+        });
+    }
+    /** Hand one record to the store; any failure from here on is ambiguous. */
+    write(type, payload, durable, onWritten) {
+        let record;
+        try {
+            record = this.store.appendJson(type, payload);
+        }
+        catch (err) {
+            this.unreadable = asError(err);
+            throw err;
+        }
+        try {
+            const ref = { id: record.id, sequence: record.sequence };
+            onWritten(ref);
+            if (durable)
+                this.store.sync();
+            return ref;
+        }
+        catch (err) {
+            this.unreconciled = asError(err);
+            throw err;
+        }
+    }
+    assertReconciled() {
+        if (this.unreadable) {
+            throw new Error(`RecordJournal(${this.type}): an earlier append failed inside the store ` +
+                `(${this.unreadable.message}), and its record may be in the store's log where this process can't ` +
+                `read it back; nothing more is written until the store is reopened, as at the next start`);
+        }
+        if (this.unreconciled) {
+            throw new Error(`RecordJournal(${this.type}): an earlier write failed after reaching the store ` +
+                `(${this.unreconciled.message}); load() and reduce its tail before writing again`);
+        }
+    }
+}
+//# sourceMappingURL=record-journal.js.map

package/dist/src/record-journal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-journal.js","sourceRoot":"","sources":["../../src/record-journal.ts"],"names":[],"mappings":"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"}

package/dist/src/shutdown.d.ts

@@ -0,0 +1,13 @@
+/** No implicit deadline: the caller owns the module/child shutdown contract. */
+export declare const DEFAULT_SHUTDOWN_TIMEOUT_MS: number | undefined;
+export declare function validateShutdownTimeout(timeoutMs: number | undefined): void;
+export declare class ShutdownTimeoutError extends AggregateError {
+    readonly pending: string[];
+    constructor(pending: string[], timeoutMs: number, failures: unknown[]);
+}
+export declare function shutdownErrorMessage(error: unknown): string;
+export declare function waitForShutdown(attempts: Array<{
+    label: string;
+    promise: Promise<void>;
+}>, timeoutMs: number | undefined): Promise<void>;
+//# sourceMappingURL=shutdown.d.ts.map

package/dist/src/shutdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shutdown.d.ts","sourceRoot":"","sources":["../../src/shutdown.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,eAAO,MAAM,2BAA2B,EAAE,MAAM,GAAG,SAAqB,CAAC;AAEzE,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAK3E;AAED,qBAAa,oBAAqB,SAAQ,cAAc;IAC1C,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE;gBAAjB,OAAO,EAAE,MAAM,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE;CAM/E;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAE3D;AAED,wBAAsB,eAAe,CACnC,QAAQ,EAAE,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAAC,EAAE,SAAS,EAAE,MAAM,GAAG,SAAS,GACxF,OAAO,CAAC,IAAI,CAAC,CAuBf"}

package/dist/src/shutdown.js

@@ -0,0 +1,46 @@
+/** No implicit deadline: the caller owns the module/child shutdown contract. */
+export const DEFAULT_SHUTDOWN_TIMEOUT_MS = undefined;
+export function validateShutdownTimeout(timeoutMs) {
+    if (timeoutMs === undefined)
+        return;
+    if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 2147483647) {
+        throw new RangeError('Shutdown timeout must be an integer from 1 to 2147483647 ms');
+    }
+}
+export class ShutdownTimeoutError extends AggregateError {
+    pending;
+    constructor(pending, timeoutMs, failures) {
+        super([...failures, new Error(`Shutdown timed out after ${timeoutMs} ms; pending: ${pending.join(', ')}`)], `Shutdown timed out after ${timeoutMs} ms; pending: ${pending.join(', ')}` +
+            (failures.length ? `; failures: ${failures.map(shutdownErrorMessage).join('; ')}` : ''));
+        this.pending = pending;
+        this.name = 'ShutdownTimeoutError';
+    }
+}
+export function shutdownErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export async function waitForShutdown(attempts, timeoutMs) {
+    validateShutdownTimeout(timeoutMs);
+    const pending = new Set(attempts.map((_, index) => index));
+    const failures = new Map();
+    const settled = Promise.all(attempts.map(({ promise }, index) => promise.then(() => { pending.delete(index); }, error => { failures.set(index, error); pending.delete(index); })));
+    let timer;
+    try {
+        if (timeoutMs === undefined)
+            await settled;
+        else
+            await Promise.race([settled, new Promise((_, reject) => {
+                    timer = setTimeout(() => reject(new ShutdownTimeoutError([...pending].map(index => attempts[index].label), timeoutMs, [...failures.values()])), timeoutMs);
+                })]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+    const errors = [...failures.values()];
+    if (errors.length === 1)
+        throw errors[0];
+    if (errors.length > 1)
+        throw new AggregateError(errors, `Shutdown failed: ${errors.map(shutdownErrorMessage).join('; ')}`);
+}
+//# sourceMappingURL=shutdown.js.map

package/dist/src/shutdown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shutdown.js","sourceRoot":"","sources":["../../src/shutdown.ts"],"names":[],"mappings":"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"}

package/dist/src/silent-heartbeat.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Stored-row handling for silent heartbeat ticks.
+ *
+ * A silent tick stores no prompt row (#216): its reply is written straight
+ * after whatever the window held before it — often the previous assistant
+ * message, since a suppressed tick leaves no delivery receipt behind. The
+ * wire formatter merges consecutive same-role messages, so without a turn
+ * between them the tick would read as an unprompted continuation of the
+ * earlier response and one assistant message would carry signed thinking
+ * from two separate responses (a provider 400 when it is the latest
+ * assistant message; see `Agent.addAssistantResponse`).
+ *
+ * Every row a tick writes is therefore stamped with `metadata.silentHeartbeat`
+ * and, at request-build time only, a terse user turn is rendered immediately
+ * before the first of the tick's rows that survives compilation. The
+ * separator is never stored and its position is a function of the stamped
+ * rows alone, so every compile renders it in the same place (the tick's own
+ * request ends on the same turn), which keeps the prompt-cache prefix
+ * stable — unlike a per-compile injection that re-anchors to the newest user
+ * message.
+ *
+ * Known limit: compiled messages carry no store provenance, so a stored row
+ * is recognised only by structural identity the provider made unique
+ * (tool_use ids, thinking signatures). A tick reply with neither — unsigned
+ * and tool-free — gets no separator and still merges as before. Without
+ * signed thinking that merge carries no provider-rejection risk; it is only
+ * a misreading. Reply text is deliberately never used as identity: identical
+ * replies ("all quiet") would collide, and an ordinary reply with the same
+ * text could take a tick's separator and rewrite cached history. Exact
+ * matching for every row would need the compile result to expose each
+ * message's source rows.
+ */
+import type { ContentBlock, NormalizedMessage } from '@animalabs/membrane';
+/** Request-only separator text. Constant on purpose: it carries no time or
+ * id, so it is byte-identical on every compile. */
+export declare const SILENT_HEARTBEAT_SEPARATOR = "[heartbeat tick]";
+/** Identity of one authenticated silent heartbeat tick. */
+export interface SilentHeartbeatTick {
+    /** The MCPL push event that woke the tick. A broadcast tick reaches every
+     * resident with the same id. */
+    eventId: string;
+    /** The MCPL server that sent it. */
+    serverId: string;
+}
+/** `metadata.silentHeartbeat` on every row a tick's turn writes. Residents
+ * share one message slot, so the stamp names the agent whose turn wrote it
+ * (tool_result rows are stored as `user`). */
+export interface SilentHeartbeatStamp extends SilentHeartbeatTick {
+    agentName: string;
+}
+/** The tick stamp on a stored row's metadata, if any. */
+export declare function silentHeartbeatOf(metadata: unknown): SilentHeartbeatStamp | undefined;
+export declare function silentHeartbeatSeparatorTurn(): NormalizedMessage;
+export interface StoredRowLike {
+    participant: string;
+    content: ContentBlock[];
+    metadata?: unknown;
+}
+export interface SilentTickIndex {
+    /** Identity key of every assistant row this agent stored during a tick → tick event id. */
+    rows: Map<string, string>;
+    /** Ticks this agent has already stored rows for (its own, not another resident's). */
+    started: Set<string>;
+}
+/** Index the rows this agent stored during silent ticks. */
+export declare function indexSilentTickRows(stored: readonly StoredRowLike[], agentName: string): SilentTickIndex;
+/**
+ * Insert the separator turn immediately before the first surviving row of
+ * each tick in a compiled window — the tick's first row when it is rendered,
+ * otherwise whichever later row a strategy kept. Rows folded into summaries
+ * simply do not match; ordinary messages pass through untouched.
+ */
+export declare function separateSilentHeartbeatTicks(messages: NormalizedMessage[], rows: ReadonlyMap<string, string>, agentName: string): NormalizedMessage[];
+//# sourceMappingURL=silent-heartbeat.d.ts.map

package/dist/src/silent-heartbeat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"silent-heartbeat.d.ts","sourceRoot":"","sources":["../../src/silent-heartbeat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAE3E;mDACmD;AACnD,eAAO,MAAM,0BAA0B,qBAAqB,CAAC;AAE7D,2DAA2D;AAC3D,MAAM,WAAW,mBAAmB;IAClC;oCACgC;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,oCAAoC;IACpC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;8CAE8C;AAC9C,MAAM,WAAW,oBAAqB,SAAQ,mBAAmB;IAC/D,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,yDAAyD;AACzD,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,OAAO,GAAG,oBAAoB,GAAG,SAAS,CAOrF;AAED,wBAAgB,4BAA4B,IAAI,iBAAiB,CAEhE;AAsBD,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,2FAA2F;IAC3F,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1B,sFAAsF;IACtF,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACtB;AAED,4DAA4D;AAC5D,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,aAAa,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,eAAe,CAWxG;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,iBAAiB,EAAE,EAC7B,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,EACjC,SAAS,EAAE,MAAM,GAChB,iBAAiB,EAAE,CAerB"}

package/dist/src/silent-heartbeat.js

@@ -0,0 +1,77 @@
+/** Request-only separator text. Constant on purpose: it carries no time or
+ * id, so it is byte-identical on every compile. */
+export const SILENT_HEARTBEAT_SEPARATOR = '[heartbeat tick]';
+/** The tick stamp on a stored row's metadata, if any. */
+export function silentHeartbeatOf(metadata) {
+    const stamp = metadata?.silentHeartbeat;
+    if (!stamp || typeof stamp !== 'object')
+        return undefined;
+    const { eventId, serverId, agentName } = stamp;
+    return typeof eventId === 'string' && typeof serverId === 'string' && typeof agentName === 'string'
+        ? { eventId, serverId, agentName }
+        : undefined;
+}
+export function silentHeartbeatSeparatorTurn() {
+    return { participant: 'user', content: [{ type: 'text', text: SILENT_HEARTBEAT_SEPARATOR }] };
+}
+/**
+ * Structural identity of one stored response wherever a compile renders it:
+ * tool_use ids and thinking signatures, which the provider made unique and
+ * strategies keep verbatim (the same identity the tool-result guard relies
+ * on). Text is never read, so request-build sanitizing (blank text blocks
+ * stripped) cannot make a stored row and its compiled copy disagree.
+ */
+function identityKeys(content) {
+    const keys = [];
+    for (const block of content) {
+        if (block.type === 'tool_use' && typeof block.id === 'string' && block.id)
+            keys.push(`tool_use:${block.id}`);
+        else if (block.type === 'thinking' && typeof block.signature === 'string' && block.signature) {
+            keys.push(`thinking:${block.signature}`);
+        }
+        else if (block.type === 'redacted_thinking' && typeof block.data === 'string' && block.data) {
+            keys.push(`redacted:${block.data}`);
+        }
+    }
+    return keys;
+}
+/** Index the rows this agent stored during silent ticks. */
+export function indexSilentTickRows(stored, agentName) {
+    const rows = new Map();
+    const started = new Set();
+    for (const row of stored) {
+        const stamp = silentHeartbeatOf(row.metadata);
+        if (!stamp || stamp.agentName !== agentName)
+            continue;
+        started.add(stamp.eventId);
+        if (row.participant !== agentName)
+            continue;
+        for (const key of identityKeys(row.content))
+            rows.set(key, stamp.eventId);
+    }
+    return { rows, started };
+}
+/**
+ * Insert the separator turn immediately before the first surviving row of
+ * each tick in a compiled window — the tick's first row when it is rendered,
+ * otherwise whichever later row a strategy kept. Rows folded into summaries
+ * simply do not match; ordinary messages pass through untouched.
+ */
+export function separateSilentHeartbeatTicks(messages, rows, agentName) {
+    if (rows.size === 0)
+        return messages;
+    const separated = new Set();
+    const out = [];
+    for (const message of messages) {
+        if (message.participant === agentName) {
+            const eventId = identityKeys(message.content).map((key) => rows.get(key)).find((id) => id !== undefined);
+            if (eventId !== undefined && !separated.has(eventId)) {
+                separated.add(eventId);
+                out.push(silentHeartbeatSeparatorTurn());
+            }
+        }
+        out.push(message);
+    }
+    return out;
+}
+//# sourceMappingURL=silent-heartbeat.js.map

package/dist/src/silent-heartbeat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"silent-heartbeat.js","sourceRoot":"","sources":["../../src/silent-heartbeat.ts"],"names":[],"mappings":"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"}

package/dist/src/tool-presentation.d.ts

@@ -0,0 +1,50 @@
+import type { ToolDefinition, ToolResult } from './types/events.js';
+export interface ToolPresentationConfig {
+    /** Absolute path to shared editable JSON. Missing file means no overrides. */
+    path: string;
+    /** Reserved generated workspace path, e.g. board/tool-catalogue.md. */
+    cataloguePath: string;
+    /** Optional description-only profiles, bound to a registered component source. */
+    defaults?: {
+        source: string;
+        path: string;
+    }[];
+}
+export interface ToolOverride {
+    description?: string;
+    visible?: boolean;
+}
+export interface PresentationDocument {
+    version: 1;
+    tools: Record<string, ToolOverride>;
+}
+export interface PresentationSnapshot {
+    revision: string;
+    source: string;
+    cataloguePath: string;
+    diagnostics: string[];
+    available: ToolDefinition[];
+    advertised: ToolDefinition[];
+    entries: {
+        name: string;
+        source: string;
+        visible: boolean;
+        originalDescription: string;
+        description: string;
+        descriptionSource?: string;
+        inputSchema: ToolDefinition['inputSchema'];
+    }[];
+}
+export declare const isPresentationTool: (name: string) => boolean;
+export declare function parsePresentation(raw: string): PresentationDocument;
+export declare function presentationTools(path: string): ToolDefinition[];
+/** Per-agent presentation; files are the sole persistent source, independent of editor identity. */
+export declare class ToolPresentation {
+    readonly config: ToolPresentationConfig;
+    constructor(config: ToolPresentationConfig);
+    private read;
+    resolve(tools: ToolDefinition[], sources?: ReadonlyMap<string, string>): PresentationSnapshot;
+    edit(tool: string, input: unknown, available: ToolDefinition[]): ToolResult;
+}
+export declare function renderCatalogue(snapshot: PresentationSnapshot): string;
+//# sourceMappingURL=tool-presentation.d.ts.map

package/dist/src/tool-presentation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-presentation.d.ts","sourceRoot":"","sources":["../../src/tool-presentation.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpE,MAAM,WAAW,sBAAsB;IACrC,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,aAAa,EAAE,MAAM,CAAC;IACtB,kFAAkF;IAClF,QAAQ,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC/C;AACD,MAAM,WAAW,YAAY;IAAG,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE;AACzE,MAAM,WAAW,oBAAoB;IAAG,OAAO,EAAE,CAAC,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;CAAE;AACzF,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,SAAS,EAAE,cAAc,EAAE,CAAC;IAC5B,UAAU,EAAE,cAAc,EAAE,CAAC;IAC7B,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAC;QAAC,mBAAmB,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,cAAc,CAAC,aAAa,CAAC,CAAA;KAAE,EAAE,CAAC;CACzL;AAGD,eAAO,MAAM,kBAAkB,GAAI,MAAM,MAAM,KAAG,OAA4E,CAAC;AAG/H,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,oBAAoB,CAanE;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,EAAE,CAQhE;AAED,oGAAoG;AACpG,qBAAa,gBAAgB;IACf,QAAQ,CAAC,MAAM,EAAE,sBAAsB;gBAA9B,MAAM,EAAE,sBAAsB;IACnD,OAAO,CAAC,IAAI;IAcZ,OAAO,CAAC,KAAK,EAAE,cAAc,EAAE,EAAE,OAAO,GAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAa,GAAG,oBAAoB;IAwCxG,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,GAAG,UAAU;CAqC5E;AACD,wBAAgB,eAAe,CAAC,QAAQ,EAAE,oBAAoB,GAAG,MAAM,CAuCtE"}