@corenel/harness 0.2.0 → 0.4.0

package/dist/api/mirror.js

@@ -0,0 +1,204 @@
+import { LeaseConflict } from './client.js';
+const blank = () => ({
+    pushedIndex: 0, lastPushedAt: 0, lastError: '', authoritative: false, epoch: 0,
+});
+export class SessionMirror {
+    constructor(deps) {
+        Object.defineProperty(this, "deps", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: deps
+        });
+        Object.defineProperty(this, "state", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        /** local session id -> the id this backend knows it by. Two namespaces, and
+         * assuming they are one is a silent 404 on every push. */
+        Object.defineProperty(this, "remoteIds", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        Object.defineProperty(this, "now", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.now = deps.now ?? Date.now;
+    }
+    /**
+     * The backend's id for a local session, creating the record if this is the
+     * first time it has been mentioned.
+     *
+     * Idempotent on the server, so a reconnect finds the session it was already
+     * pushing to rather than opening a second one beside it and splitting the log.
+     */
+    async remoteId(sessionId) {
+        const known = this.remoteIds.get(sessionId);
+        if (known)
+            return known;
+        const found = await this.deps.client.findByLocalId(sessionId);
+        if (found) {
+            this.remoteIds.set(sessionId, found._id);
+            return found._id;
+        }
+        try {
+            const created = await this.deps.client.createSession({ localId: sessionId, location: 'local' });
+            this.remoteIds.set(sessionId, created._id);
+            return created._id;
+        }
+        catch (err) {
+            // A SANDBOX credential cannot create sessions, on purpose: the user
+            // provisions the session and the credential together, and the machine
+            // finds them. Saying that plainly beats reporting the raw 401, which reads
+            // like a broken credential rather than a missing session.
+            const status = err.status;
+            if (status === 401 || status === 403) {
+                throw new Error(`no session on the backend for "${sessionId}", and this credential may not create one — `
+                    + 'provision the session first, or use a user credential');
+            }
+            throw err;
+        }
+    }
+    status(sessionId) {
+        return { ...(this.state.get(sessionId) ?? blank()) };
+    }
+    set(sessionId, patch) {
+        const next = { ...(this.state.get(sessionId) ?? blank()), ...patch };
+        this.state.set(sessionId, next);
+        return { ...next };
+    }
+    /**
+     * Claim authority for this machine.
+     *
+     * Reads the current epoch and takes the next one. Losing the race is a normal
+     * answer, not an error: another machine holds the session, and what this one
+     * does about that is a decision for the caller (usually: stop, and offer the
+     * user a demote).
+     */
+    async claim(sessionId) {
+        try {
+            const remote = await this.remoteId(sessionId);
+            const current = await this.deps.client.getSession(remote);
+            const lease = await this.deps.client.acquireLease(remote, current.epoch, this.deps.holder);
+            this.deps.log?.(`mirror: took authority for ${sessionId} at epoch ${lease.epoch}`);
+            return { ok: true, status: this.set(sessionId, { authoritative: true, epoch: lease.epoch, lastError: '' }) };
+        }
+        catch (err) {
+            const lost = err instanceof LeaseConflict;
+            const message = err instanceof Error ? err.message : String(err);
+            this.deps.log?.(`mirror: could not take authority for ${sessionId}: ${message}`);
+            return {
+                ok: false,
+                status: this.set(sessionId, {
+                    authoritative: false,
+                    ...(lost ? { epoch: err.currentEpoch } : {}),
+                    lastError: message,
+                }),
+            };
+        }
+    }
+    /** Give authority up, so another machine can take it without waiting for an
+     * expiry that does not exist. Best-effort like everything else here. */
+    async release(sessionId) {
+        const s = this.status(sessionId);
+        if (!s.authoritative)
+            return;
+        try {
+            const epoch = await this.deps.client.releaseLease(await this.remoteId(sessionId), s.epoch);
+            this.set(sessionId, { authoritative: false, epoch });
+        }
+        catch (err) {
+            // A failed release is not worth surfacing: the next holder's acquire will
+            // supersede this epoch anyway. That is the whole point of a monotonic
+            // counter over a flag.
+            this.set(sessionId, { authoritative: false, lastError: err instanceof Error ? err.message : String(err) });
+        }
+    }
+    /**
+     * Push everything the mirror has not seen.
+     *
+     * Resumes from the recorded cursor, so an interrupted push costs a retry rather
+     * than a re-upload of the whole log. Resolves either way — a caller in the
+     * middle of an agent turn must never have to handle this throwing.
+     */
+    async push(sessionId) {
+        const before = this.status(sessionId);
+        if (!before.authoritative) {
+            // Pushing without authority would overwrite whichever machine is actually
+            // running the session. Refusing is the correct behaviour, not a limitation.
+            return { ok: false, pushed: 0, status: this.set(sessionId, { lastError: 'not the authoritative holder' }) };
+        }
+        try {
+            const remote = await this.remoteId(sessionId);
+            const { entries, nextIndex } = await this.deps.local.entriesSince(sessionId, before.pushedIndex);
+            if (entries.length) {
+                await this.deps.client.appendTimeline(remote, before.epoch, entries);
+            }
+            const head = await this.deps.local.head(sessionId);
+            if (head)
+                await this.deps.client.putHead(remote, before.epoch, head);
+            return {
+                ok: true,
+                pushed: entries.length,
+                status: this.set(sessionId, {
+                    pushedIndex: Math.max(before.pushedIndex, nextIndex),
+                    lastPushedAt: this.now(),
+                    lastError: '',
+                }),
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            const lostAuthority = err instanceof LeaseConflict;
+            if (lostAuthority) {
+                // Someone else took the session. This machine's copy is a stale branch
+                // now, and continuing to push would be fighting over a session it no
+                // longer holds. Stop, and let the caller decide what to tell the user.
+                this.deps.log?.(`mirror: lost authority for ${sessionId}; stopping`);
+                return {
+                    ok: false,
+                    pushed: 0,
+                    lostAuthority: true,
+                    status: this.set(sessionId, {
+                        authoritative: false,
+                        epoch: err.currentEpoch,
+                        lastError: 'another machine took this session',
+                    }),
+                };
+            }
+            this.deps.log?.(`mirror: push failed for ${sessionId}: ${message}`);
+            return { ok: false, pushed: 0, status: this.set(sessionId, { lastError: message }) };
+        }
+    }
+    /**
+     * Read the mirror.
+     *
+     * RETURNS the remote state; it does not write anything locally. What to do with
+     * a remote copy — restore it, merge it, show it read-only — belongs to whoever
+     * owns the local store, and a mirror that silently overwrote local state would
+     * have made itself the original.
+     */
+    async pull(sessionId, since = 0) {
+        try {
+            const { entries, nextIndex } = await this.deps.client.readTimeline(await this.remoteId(sessionId), since);
+            return { ok: true, entries, nextIndex, error: '' };
+        }
+        catch (err) {
+            return { ok: false, entries: [], nextIndex: 0, error: err instanceof Error ? err.message : String(err) };
+        }
+    }
+    /** Forget local bookkeeping for a session — after a destroy, or when this
+     * machine stops caring about it. Does not touch the remote copy. */
+    forget(sessionId) {
+        this.state.delete(sessionId);
+        this.remoteIds.delete(sessionId);
+    }
+}
+//# sourceMappingURL=mirror.js.map

package/dist/api/mirror.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mirror.js","sourceRoot":"","sources":["../../api/mirror.ts"],"names":[],"mappings":"AAgCA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AA4CzC,MAAM,KAAK,GAAG,GAAiB,EAAE,CAAC,CAAC;IACjC,WAAW,EAAE,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,SAAS,EAAE,EAAE,EAAE,aAAa,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;CAC/E,CAAC,CAAC;AAEH,MAAM,OAAO,aAAa;IAOxB,YAA6B,IAAuB;QAAxC;;;;mBAAiB,IAAI;WAAmB;QANnC;;;;mBAAQ,IAAI,GAAG,EAAwB;WAAC;QACzD;kEAC0D;QACzC;;;;mBAAY,IAAI,GAAG,EAAkB;WAAC;QACtC;;;;;WAAkB;QAGjC,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC;IAClC,CAAC;IAED;;;;;;OAMG;IACK,KAAK,CAAC,QAAQ,CAAC,SAAiB;QACtC,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC5C,IAAI,KAAK;YAAE,OAAO,KAAK,CAAC;QAExB,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC;QAC9D,IAAI,KAAK,EAAE,CAAC;YACV,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;YACzC,OAAO,KAAK,CAAC,GAAG,CAAC;QACnB,CAAC;QAED,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC;YAChG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;YAC3C,OAAO,OAAO,CAAC,GAAG,CAAC;QACrB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,oEAAoE;YACpE,sEAAsE;YACtE,2EAA2E;YAC3E,0DAA0D;YAC1D,MAAM,MAAM,GAAI,GAA2B,CAAC,MAAM,CAAC;YACnD,IAAI,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;gBACrC,MAAM,IAAI,KAAK,CACb,kCAAkC,SAAS,8CAA8C;sBACvF,uDAAuD,CAC1D,CAAC;YACJ,CAAC;YACD,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC;IAED,MAAM,CAAC,SAAiB;QACtB,OAAO,EAAE,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,KAAK,EAAE,CAAC,EAAE,CAAC;IACvD,CAAC;IAEO,GAAG,CAAC,SAAiB,EAAE,KAA4B;QACzD,MAAM,IAAI,GAAG,EAAE,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,KAAK,EAAE,CAAC,EAAE,GAAG,KAAK,EAAE,CAAC;QACrE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;QAChC,OAAO,EAAE,GAAG,IAAI,EAAE,CAAC;IACrB,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,KAAK,CAAC,SAAiB;QAC3B,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;YAC9C,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;YAC1D,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YAC3F,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,8BAA8B,SAAS,aAAa,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC;YACnF,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC;QAC/G,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,GAAG,GAAG,YAAY,aAAa,CAAC;YAC1C,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACjE,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,wCAAwC,SAAS,KAAK,OAAO,EAAE,CAAC,CAAC;YACjF,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE;oBAC1B,aAAa,EAAE,KAAK;oBACpB,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,KAAK,EAAG,GAAqB,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;oBAC/D,SAAS,EAAE,OAAO;iBACnB,CAAC;aACH,CAAC;QACJ,CAAC;IACH,CAAC;IAED;4EACwE;IACxE,KAAK,CAAC,OAAO,CAAC,SAAiB;QAC7B,MAAM,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QACjC,IAAI,CAAC,CAAC,CAAC,aAAa;YAAE,OAAO;QAC7B,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,MAAM,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC;YAC3F,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,EAAE,aAAa,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;QACvD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,0EAA0E;YAC1E,sEAAsE;YACtE,uBAAuB;YACvB,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,EAAE,aAAa,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC7G,CAAC;IACH,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,IAAI,CAAC,SAAiB;QAC1B,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QACtC,IAAI,CAAC,MAAM,CAAC,aAAa,EAAE,CAAC;YAC1B,0EAA0E;YAC1E,4EAA4E;YAC5E,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,8BAA8B,EAAE,CAAC,EAAE,CAAC;QAC9G,CAAC;QAED,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;YAC9C,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,SAAS,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC;YACjG,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;gBACnB,MAAM,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;YACvE,CAAC;YACD,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YACnD,IAAI,IAAI;gBAAE,MAAM,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;YAErE,OAAO;gBACL,EAAE,EAAE,IAAI;gBACR,MAAM,EAAE,OAAO,CAAC,MAAM;gBACtB,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE;oBAC1B,WAAW,EAAE,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,WAAW,EAAE,SAAS,CAAC;oBACpD,YAAY,EAAE,IAAI,CAAC,GAAG,EAAE;oBACxB,SAAS,EAAE,EAAE;iBACd,CAAC;aACH,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACjE,MAAM,aAAa,GAAG,GAAG,YAAY,aAAa,CAAC;YACnD,IAAI,aAAa,EAAE,CAAC;gBAClB,uEAAuE;gBACvE,qEAAqE;gBACrE,uEAAuE;gBACvE,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,8BAA8B,SAAS,YAAY,CAAC,CAAC;gBACrE,OAAO;oBACL,EAAE,EAAE,KAAK;oBACT,MAAM,EAAE,CAAC;oBACT,aAAa,EAAE,IAAI;oBACnB,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE;wBAC1B,aAAa,EAAE,KAAK;wBACpB,KAAK,EAAG,GAAqB,CAAC,YAAY;wBAC1C,SAAS,EAAE,mCAAmC;qBAC/C,CAAC;iBACH,CAAC;YACJ,CAAC;YACD,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,2BAA2B,SAAS,KAAK,OAAO,EAAE,CAAC,CAAC;YACpE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;QACvF,CAAC;IACH,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,IAAI,CAAC,SAAiB,EAAE,KAAK,GAAG,CAAC;QACrC,IAAI,CAAC;YACH,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,MAAM,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,KAAK,CAAC,CAAC;YAC1G,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;QACrD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,SAAS,EAAE,CAAC,EAAE,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;QAC3G,CAAC;IACH,CAAC;IAED;wEACoE;IACpE,MAAM,CAAC,SAAiB;QACtB,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAC7B,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACnC,CAAC;CACF"}

package/dist/api/mirrorScheduler.d.ts

@@ -0,0 +1,56 @@
+import type { PushResult } from './mirror';
+/** Just enough of SessionMirror to schedule against — so a test needs no client. */
+export interface SchedulableMirror {
+    push(sessionId: string): Promise<PushResult>;
+}
+export interface MirrorSchedulerDeps {
+    mirror: SchedulableMirror;
+    /** Quiet period after the last write before pushing. */
+    debounceMs?: number;
+    /** How far behind the mirror may fall while writes keep coming. */
+    maxWaitMs?: number;
+    /** Wait after a failed push before trying again. Doubles, to a cap. */
+    retryMs?: number;
+    maxRetryMs?: number;
+    setTimer?: (fn: () => void, ms: number) => unknown;
+    clearTimer?: (handle: unknown) => void;
+    now?: () => number;
+    log?: (line: string) => void;
+}
+export declare class MirrorScheduler {
+    private readonly deps;
+    private readonly pending;
+    private readonly cfg;
+    private readonly setTimer;
+    private readonly clearTimer;
+    private readonly now;
+    constructor(deps: MirrorSchedulerDeps);
+    private slot;
+    private disarm;
+    /**
+     * Work happened; push soon.
+     *
+     * Cheap and synchronous — this is called from the write path, and the write
+     * path must never wait on the mirror.
+     */
+    touch(sessionId: string): void;
+    /**
+     * Push now and wait for the result.
+     *
+     * For pause, handoff and shutdown — the moments where "shortly" is not good
+     * enough because the machine may be about to stop being the one that has the
+     * session.
+     */
+    flush(sessionId: string): Promise<PushResult>;
+    /** Flush every session with work outstanding — shutdown, or a demote of the
+     * whole machine. Runs them together; one failure does not stop the others. */
+    flushAll(): Promise<Record<string, PushResult>>;
+    private run;
+    /** Whether a push is scheduled or in flight. */
+    pending_(sessionId: string): boolean;
+    /** Stop scheduling for a session and forget it — a destroy, or a handoff that
+     * has already flushed. */
+    stop(sessionId: string): void;
+    dispose(): void;
+}
+//# sourceMappingURL=mirrorScheduler.d.ts.map

package/dist/api/mirrorScheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mirrorScheduler.d.ts","sourceRoot":"","sources":["../../api/mirrorScheduler.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE3C,oFAAoF;AACpF,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CAC9C;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,iBAAiB,CAAC;IAC1B,wDAAwD;IACxD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC;IACnD,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IACvC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9B;AAgBD,qBAAa,eAAe;IAOd,OAAO,CAAC,QAAQ,CAAC,IAAI;IANjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA8B;IACtD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAkB;IACtC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA0C;IACnE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA4B;IACvD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;gBAEN,IAAI,EAAE,mBAAmB;IAYtD,OAAO,CAAC,IAAI;IASZ,OAAO,CAAC,MAAM;IAOd;;;;;OAKG;IACH,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAqB9B;;;;;;OAMG;IACG,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAMnD;kFAC8E;IACxE,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;YAMvC,GAAG;IA2CjB,gDAAgD;IAChD,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAKpC;8BAC0B;IAC1B,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAO7B,OAAO,IAAI,IAAI;CAIhB"}

package/dist/api/mirrorScheduler.js

@@ -0,0 +1,167 @@
+const DEFAULTS = { debounceMs: 2000, maxWaitMs: 15000, retryMs: 5000, maxRetryMs: 60000 };
+export class MirrorScheduler {
+    constructor(deps) {
+        Object.defineProperty(this, "deps", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: deps
+        });
+        Object.defineProperty(this, "pending", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        Object.defineProperty(this, "cfg", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "setTimer", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "clearTimer", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "now", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.cfg = {
+            debounceMs: deps.debounceMs ?? DEFAULTS.debounceMs,
+            maxWaitMs: deps.maxWaitMs ?? DEFAULTS.maxWaitMs,
+            retryMs: deps.retryMs ?? DEFAULTS.retryMs,
+            maxRetryMs: deps.maxRetryMs ?? DEFAULTS.maxRetryMs,
+        };
+        this.setTimer = deps.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
+        this.clearTimer = deps.clearTimer ?? ((h) => clearTimeout(h));
+        this.now = deps.now ?? Date.now;
+    }
+    slot(sessionId) {
+        let p = this.pending.get(sessionId);
+        if (!p) {
+            p = { handle: null, firstDirtyAt: 0, running: false, dirtyAgain: false, retryMs: this.cfg.retryMs, stopped: false };
+            this.pending.set(sessionId, p);
+        }
+        return p;
+    }
+    disarm(p) {
+        if (p.handle !== null) {
+            this.clearTimer(p.handle);
+            p.handle = null;
+        }
+    }
+    /**
+     * Work happened; push soon.
+     *
+     * Cheap and synchronous — this is called from the write path, and the write
+     * path must never wait on the mirror.
+     */
+    touch(sessionId) {
+        const p = this.slot(sessionId);
+        if (p.stopped)
+            return;
+        if (p.running) {
+            // Do not overlap pushes for one session: the second would race the first's
+            // cursor advance and could re-send or skip entries.
+            p.dirtyAgain = true;
+            return;
+        }
+        if (!p.firstDirtyAt)
+            p.firstDirtyAt = this.now();
+        this.disarm(p);
+        // The ceiling wins over the quiet period: a busy session must not defer its
+        // push forever just because it never goes quiet.
+        const elapsed = this.now() - p.firstDirtyAt;
+        const wait = Math.max(0, Math.min(this.cfg.debounceMs, this.cfg.maxWaitMs - elapsed));
+        p.handle = this.setTimer(() => { void this.run(sessionId); }, wait);
+    }
+    /**
+     * Push now and wait for the result.
+     *
+     * For pause, handoff and shutdown — the moments where "shortly" is not good
+     * enough because the machine may be about to stop being the one that has the
+     * session.
+     */
+    async flush(sessionId) {
+        const p = this.slot(sessionId);
+        this.disarm(p);
+        return this.run(sessionId, { force: true });
+    }
+    /** Flush every session with work outstanding — shutdown, or a demote of the
+     * whole machine. Runs them together; one failure does not stop the others. */
+    async flushAll() {
+        const ids = [...this.pending.keys()];
+        const results = await Promise.all(ids.map(async (id) => [id, await this.flush(id)]));
+        return Object.fromEntries(results);
+    }
+    async run(sessionId, opts = {}) {
+        const p = this.slot(sessionId);
+        if (p.stopped && !opts.force) {
+            return { ok: false, pushed: 0, status: { pushedIndex: 0, lastPushedAt: 0, lastError: 'stopped', authoritative: false, epoch: 0 } };
+        }
+        p.running = true;
+        this.disarm(p);
+        try {
+            const result = await this.deps.mirror.push(sessionId);
+            if (result.lostAuthority) {
+                // Another machine has the session. Stop — do not retry, do not re-arm.
+                this.deps.log?.(`mirror: authority lost for ${sessionId}; scheduler stopped`);
+                p.stopped = true;
+                p.dirtyAgain = false;
+                p.firstDirtyAt = 0;
+                return result;
+            }
+            if (result.ok) {
+                p.retryMs = this.cfg.retryMs;
+                p.firstDirtyAt = 0;
+                // Work that arrived mid-push has not been sent; schedule another round.
+                if (p.dirtyAgain) {
+                    p.dirtyAgain = false;
+                    p.running = false;
+                    this.touch(sessionId);
+                    return result;
+                }
+                return result;
+            }
+            // A transient failure. Back off rather than hammering a server that is
+            // already unhappy, and keep the dirty state so nothing is dropped.
+            p.handle = this.setTimer(() => { void this.run(sessionId); }, p.retryMs);
+            p.retryMs = Math.min(p.retryMs * 2, this.cfg.maxRetryMs);
+            return result;
+        }
+        finally {
+            p.running = false;
+        }
+    }
+    /** Whether a push is scheduled or in flight. */
+    pending_(sessionId) {
+        const p = this.pending.get(sessionId);
+        return !!p && (p.handle !== null || p.running || p.dirtyAgain);
+    }
+    /** Stop scheduling for a session and forget it — a destroy, or a handoff that
+     * has already flushed. */
+    stop(sessionId) {
+        const p = this.pending.get(sessionId);
+        if (!p)
+            return;
+        this.disarm(p);
+        this.pending.delete(sessionId);
+    }
+    dispose() {
+        for (const [, p] of this.pending)
+            this.disarm(p);
+        this.pending.clear();
+    }
+}
+//# sourceMappingURL=mirrorScheduler.js.map

package/dist/api/mirrorScheduler.js.map

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

package/dist/compression.d.ts

@@ -1,9 +1,23 @@
 import type { CompressionMode, OffloadRef } from '@corenel/protocol';
-export type { CompressionMode, CompressionConfig, OffloadRef } from '@corenel/protocol';
+export type { CompressionMode, CompressionConfig, CompressionStrategy, OffloadRef } from '@corenel/protocol';
 /** How much of an offloaded output to keep inline as a preview. */
 export declare const PREVIEW_BYTES = 800;
 /** Threshold for a given fill ratio (0–1). As the window fills, offload sooner. */
 export declare function effectiveThreshold(mode: CompressionMode, fill?: number): number;
+export declare const OFFLOAD_MARKER_PREFIX = "[offloaded tool result \u00B7 ";
+/** True if `content` is already a formatOffloadRef() pointer — i.e. this
+ * result was already offloaded and must not be recorded/rewritten again. */
+export declare function isOffloadPointer(content: string): boolean;
+/** The blob id (and recorded byte count) a formatOffloadRef() pointer carries,
+ * for a caller that needs to read the real content back — e.g. a restored
+ * transcript row recognizing a persisted pointer as still-offloaded (see
+ * @corenel/term's persist.ts). Returns `null` for anything that isn't a
+ * pointer, or a pointer whose tail doesn't parse (never thrown on — this can
+ * be read back out of a session log written by an older/different format). */
+export declare function parseOffloadPointer(content: string): {
+    id: string;
+    bytes: number;
+} | null;
 /** The self-describing reference that replaces a large output in the history.
  * Carries enough (tool, size, preview, recall instruction) for the model to
  * decide whether to pull the full content back. */

package/dist/compression.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compression.d.ts","sourceRoot":"","sources":["../compression.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACrE,YAAY,EAAE,eAAe,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAExF,mEAAmE;AACnE,eAAO,MAAM,aAAa,MAAM,CAAC;AAOjC,mFAAmF;AACnF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,eAAe,EAAE,IAAI,SAAI,GAAG,MAAM,CAI1E;AAED;;mDAEmD;AACnD,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,CAGxD"}
+{"version":3,"file":"compression.d.ts","sourceRoot":"","sources":["../compression.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACrE,YAAY,EAAE,eAAe,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE7G,mEAAmE;AACnE,eAAO,MAAM,aAAa,MAAM,CAAC;AAOjC,mFAAmF;AACnF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,eAAe,EAAE,IAAI,SAAI,GAAG,MAAM,CAI1E;AAQD,eAAO,MAAM,qBAAqB,mCAA8B,CAAC;AAEjE;4EAC4E;AAC5E,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEzD;AAOD;;;;;8EAK8E;AAC9E,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAMzF;AAED;;mDAEmD;AACnD,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,CAGxD"}

package/dist/compression.js

@@ -17,11 +17,42 @@ export function effectiveThreshold(mode, fill = 0) {
     const factor = fill < 0.5 ? 1 : fill < 0.7 ? 0.7 : fill < 0.85 ? 0.5 : 0.35;
     return Math.max(FLOOR[mode], Math.round(BASE[mode] * factor));
 }
+// The stable, load-bearing prefix every formatOffloadRef() output starts with.
+// Exported (not just used internally) so any pass that needs to recognize an
+// ALREADY-offloaded message — the deferred strategy's history-compaction pass
+// in loop.ts is the first caller — checks this instead of re-deriving it or
+// loose-matching a substring that could coincidentally appear in real tool
+// output. Keep formatOffloadRef's head in sync with this if either changes.
+export const OFFLOAD_MARKER_PREFIX = '[offloaded tool result · ';
+/** True if `content` is already a formatOffloadRef() pointer — i.e. this
+ * result was already offloaded and must not be recorded/rewritten again. */
+export function isOffloadPointer(content) {
+    return content.startsWith(OFFLOAD_MARKER_PREFIX);
+}
+// Matches the `{bytes} bytes · recall the full content with recall_result({ id: "{id}" })`
+// tail formatOffloadRef() writes. Kept beside it so there is exactly one place
+// that knows both directions of the pointer format.
+const POINTER_TAIL_RE = /· ([\d,]+) bytes · recall the full content with recall_result\(\{ id: "([^"]+)" \}\)/;
+/** The blob id (and recorded byte count) a formatOffloadRef() pointer carries,
+ * for a caller that needs to read the real content back — e.g. a restored
+ * transcript row recognizing a persisted pointer as still-offloaded (see
+ * @corenel/term's persist.ts). Returns `null` for anything that isn't a
+ * pointer, or a pointer whose tail doesn't parse (never thrown on — this can
+ * be read back out of a session log written by an older/different format). */
+export function parseOffloadPointer(content) {
+    if (!isOffloadPointer(content))
+        return null;
+    const m = POINTER_TAIL_RE.exec(content);
+    if (!m)
+        return null;
+    const bytes = Number(m[1].replace(/,/g, ''));
+    return { id: m[2], bytes: Number.isFinite(bytes) ? bytes : 0 };
+}
 /** The self-describing reference that replaces a large output in the history.
  * Carries enough (tool, size, preview, recall instruction) for the model to
  * decide whether to pull the full content back. */
 export function formatOffloadRef(ref) {
-    const head = `[offloaded tool result · ${ref.toolName} · ${ref.bytes.toLocaleString()} bytes · recall the full content with recall_result({ id: "${ref.id}" })]`;
+    const head = `${OFFLOAD_MARKER_PREFIX}${ref.toolName} · ${ref.bytes.toLocaleString()} bytes · recall the full content with recall_result({ id: "${ref.id}" })]`;
     return ref.preview ? `${head}\n--- preview ---\n${ref.preview}${ref.bytes > ref.preview.length ? '\n…(truncated)' : ''}` : head;
 }
 //# sourceMappingURL=compression.js.map

package/dist/compression.js.map

@@ -1 +1 @@
-{"version":3,"file":"compression.js","sourceRoot":"","sources":["../compression.ts"],"names":[],"mappings":"AAAA;;;;;yFAKyF;AAOzF,mEAAmE;AACnE,MAAM,CAAC,MAAM,aAAa,GAAG,GAAG,CAAC;AAEjC,+EAA+E;AAC/E,8BAA8B;AAC9B,MAAM,IAAI,GAAoC,EAAE,GAAG,EAAE,QAAQ,EAAE,YAAY,EAAE,KAAM,EAAE,QAAQ,EAAE,KAAM,EAAE,UAAU,EAAE,IAAK,EAAE,CAAC;AAC3H,MAAM,KAAK,GAAoC,EAAE,GAAG,EAAE,QAAQ,EAAE,YAAY,EAAE,IAAK,EAAE,QAAQ,EAAE,IAAK,EAAE,UAAU,EAAE,IAAK,EAAE,CAAC;AAE1H,mFAAmF;AACnF,MAAM,UAAU,kBAAkB,CAAC,IAAqB,EAAE,IAAI,GAAG,CAAC;IAChE,IAAI,IAAI,KAAK,KAAK;QAAE,OAAO,QAAQ,CAAC;IACpC,MAAM,MAAM,GAAG,IAAI,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;IAC5E,OAAO,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC;AAChE,CAAC;AAED;;mDAEmD;AACnD,MAAM,UAAU,gBAAgB,CAAC,GAAe;IAC9C,MAAM,IAAI,GAAG,4BAA4B,GAAG,CAAC,QAAQ,MAAM,GAAG,CAAC,KAAK,CAAC,cAAc,EAAE,8DAA8D,GAAG,CAAC,EAAE,OAAO,CAAC;IACjK,OAAO,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,sBAAsB,GAAG,CAAC,OAAO,GAAG,GAAG,CAAC,KAAK,GAAG,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AAClI,CAAC"}
+{"version":3,"file":"compression.js","sourceRoot":"","sources":["../compression.ts"],"names":[],"mappings":"AAAA;;;;;yFAKyF;AAOzF,mEAAmE;AACnE,MAAM,CAAC,MAAM,aAAa,GAAG,GAAG,CAAC;AAEjC,+EAA+E;AAC/E,8BAA8B;AAC9B,MAAM,IAAI,GAAoC,EAAE,GAAG,EAAE,QAAQ,EAAE,YAAY,EAAE,KAAM,EAAE,QAAQ,EAAE,KAAM,EAAE,UAAU,EAAE,IAAK,EAAE,CAAC;AAC3H,MAAM,KAAK,GAAoC,EAAE,GAAG,EAAE,QAAQ,EAAE,YAAY,EAAE,IAAK,EAAE,QAAQ,EAAE,IAAK,EAAE,UAAU,EAAE,IAAK,EAAE,CAAC;AAE1H,mFAAmF;AACnF,MAAM,UAAU,kBAAkB,CAAC,IAAqB,EAAE,IAAI,GAAG,CAAC;IAChE,IAAI,IAAI,KAAK,KAAK;QAAE,OAAO,QAAQ,CAAC;IACpC,MAAM,MAAM,GAAG,IAAI,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;IAC5E,OAAO,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC;AAChE,CAAC;AAED,+EAA+E;AAC/E,6EAA6E;AAC7E,8EAA8E;AAC9E,4EAA4E;AAC5E,2EAA2E;AAC3E,4EAA4E;AAC5E,MAAM,CAAC,MAAM,qBAAqB,GAAG,2BAA2B,CAAC;AAEjE;4EAC4E;AAC5E,MAAM,UAAU,gBAAgB,CAAC,OAAe;IAC9C,OAAO,OAAO,CAAC,UAAU,CAAC,qBAAqB,CAAC,CAAC;AACnD,CAAC;AAED,2FAA2F;AAC3F,+EAA+E;AAC/E,oDAAoD;AACpD,MAAM,eAAe,GAAG,sFAAsF,CAAC;AAE/G;;;;;8EAK8E;AAC9E,MAAM,UAAU,mBAAmB,CAAC,OAAe;IACjD,IAAI,CAAC,gBAAgB,CAAC,OAAO,CAAC;QAAE,OAAO,IAAI,CAAC;IAC5C,MAAM,CAAC,GAAG,eAAe,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACxC,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACpB,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC;IAC7C,OAAO,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AACjE,CAAC;AAED;;mDAEmD;AACnD,MAAM,UAAU,gBAAgB,CAAC,GAAe;IAC9C,MAAM,IAAI,GAAG,GAAG,qBAAqB,GAAG,GAAG,CAAC,QAAQ,MAAM,GAAG,CAAC,KAAK,CAAC,cAAc,EAAE,8DAA8D,GAAG,CAAC,EAAE,OAAO,CAAC;IAChK,OAAO,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,sBAAsB,GAAG,CAAC,OAAO,GAAG,GAAG,CAAC,KAAK,GAAG,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AAClI,CAAC"}

package/dist/core/loop.d.ts

@@ -20,6 +20,16 @@ export interface RunAgentArgs {
     policy?: Policy;
     /** Per-tool permission resolver. When omitted, tools run without an approval gate. */
     permission?: PermissionService;
+    /** Customize the tool-result text a refused tool call gets. The kernel is
+     * host-agnostic and cannot know WHY a decision came back "deny" — a real
+     * person declining an interactive prompt, and a non-interactive host that
+     * has nobody to ask, are both just "deny" by the time they reach here. The
+     * default wording ("denied by the user") is only honest for the former;
+     * a host that fails closed with no prompt at all (see `run`/`run-agent` in
+     * @corenel/cli) should supply this so the model — and whoever reads the
+     * transcript — hears the actual cause and the actual remedy, not a claim
+     * that a person was asked and said no when nobody was asked anything. */
+    describePermissionDenial?: (toolName: string) => string;
     /** Context-compression config (rung-1 offload). Omit to disable. */
     compression?: CompressionConfig;
     /** Intra-run self-healing budget (stream-retry + tool-steer). Omit for defaults. */
@@ -27,6 +37,8 @@ export interface RunAgentArgs {
     /** Optional output-token ceiling forwarded to the model on every turn (reasoning
      * + visible output combined for reasoning models). Omit to leave output unbounded. */
     maxCompletionTokens?: number;
+    /** Sampling temperature, already vetted by the caller for model support. */
+    temperature?: number;
     signal?: AbortSignal;
     onEvent?: (e: AgentEvent) => void;
 }

package/dist/core/loop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loop.d.ts","sourceRoot":"","sources":["../../core/loop.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AACjC,OAAO,KAAK,EAAE,0BAA0B,EAAsB,MAAM,mCAAmC,CAAC;AACxG,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAEnF,OAAO,EACY,KAAK,cAAc,EAErC,MAAM,YAAY,CAAC;AAMpB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACzE,OAAO,EAAwC,KAAK,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAG9F,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd;kDAC8C;IAC9C,QAAQ,CAAC,EAAE,MAAM,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,0BAA0B,EAAE,CAAC;IACvC,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,OAAO,EAAE,WAAW,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oFAAoF;IACpF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sFAAsF;IACtF,UAAU,CAAC,EAAE,iBAAiB,CAAC;IAC/B,oEAAoE;IACpE,WAAW,CAAC,EAAE,iBAAiB,CAAC;IAChC,oFAAoF;IACpF,QAAQ,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;IACnC;0FACsF;IACtF,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,UAAU,KAAK,IAAI,CAAC;CACnC;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,0BAA0B,EAAE,CAAC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,KAAK,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,wBAAsB,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,cAAc,CAAC,CAsQ1E"}
+{"version":3,"file":"loop.d.ts","sourceRoot":"","sources":["../../core/loop.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AACjC,OAAO,KAAK,EAAE,0BAA0B,EAAsB,MAAM,mCAAmC,CAAC;AACxG,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,UAAU,EAAE,KAAK,EAA4B,MAAM,mBAAmB,CAAC;AAE7G,OAAO,EACY,KAAK,cAAc,EAErC,MAAM,YAAY,CAAC;AAMpB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACzE,OAAO,EAA0D,KAAK,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAGhH,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd;kDAC8C;IAC9C,QAAQ,CAAC,EAAE,MAAM,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,0BAA0B,EAAE,CAAC;IACvC,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,OAAO,EAAE,WAAW,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oFAAoF;IACpF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sFAAsF;IACtF,UAAU,CAAC,EAAE,iBAAiB,CAAC;IAC/B;;;;;;;;6EAQyE;IACzE,wBAAwB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;IACxD,oEAAoE;IACpE,WAAW,CAAC,EAAE,iBAAiB,CAAC;IAChC,oFAAoF;IACpF,QAAQ,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;IACnC;0FACsF;IACtF,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,UAAU,KAAK,IAAI,CAAC;CACnC;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,0BAA0B,EAAE,CAAC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,KAAK,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,wBAAsB,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,cAAc,CAAC,CA2U1E"}