@corenel/harness 0.1.0 → 0.3.2

package/dist/api/mirror.js

@@ -0,0 +1,204 @@
+import { LeaseConflict } from './client';
+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":"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"}

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/conversation.d.ts

@@ -15,15 +15,4 @@ export interface ConversationTurn {
     /** Token/cost/latency for the assistant response, once the turn settles. */
     stats?: TurnStats;
 }
-export declare function getTurns(): ConversationTurn[];
-/** React-style setter: accepts a value or an updater. */
-export declare function setTurns(next: ConversationTurn[] | ((prev: ConversationTurn[]) => ConversationTurn[])): void;
-/** Toggle a turn's include flag (warm-context inclusion — before compression). */
-export declare function toggleInclude(id: string): void;
-/** Subscribe a component to the live turns. */
-export declare function useConversation(): {
-    turns: ConversationTurn[];
-    setTurns: typeof setTurns;
-    toggleInclude: typeof toggleInclude;
-};
 //# sourceMappingURL=conversation.d.ts.map

package/dist/conversation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"conversation.d.ts","sourceRoot":"","sources":["../conversation.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,mCAAmC,CAAC;AAEpF,qFAAqF;AACrF,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;+EAC+E;AAC/E,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,0BAA0B,EAAE,CAAC;IACvC,4EAA4E;IAC5E,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB;AAMD,wBAAgB,QAAQ,IAAI,gBAAgB,EAAE,CAAkB;AAEhE,yDAAyD;AACzD,wBAAgB,QAAQ,CAAC,IAAI,EAAE,gBAAgB,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,gBAAgB,EAAE,KAAK,gBAAgB,EAAE,CAAC,GAAG,IAAI,CAG5G;AAED,kFAAkF;AAClF,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAE9C;AAED,+CAA+C;AAC/C,wBAAgB,eAAe,IAAI;IACjC,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAC1B,QAAQ,EAAE,OAAO,QAAQ,CAAC;IAC1B,aAAa,EAAE,OAAO,aAAa,CAAC;CACrC,CAIA"}
+{"version":3,"file":"conversation.d.ts","sourceRoot":"","sources":["../conversation.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,mCAAmC,CAAC;AAEpF,qFAAqF;AACrF,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;+EAC+E;AAC/E,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,0BAA0B,EAAE,CAAC;IACvC,4EAA4E;IAC5E,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB"}

package/dist/conversation.js

@@ -1,25 +1,2 @@
-/* Shared conversation store — the assistant's live turns, lifted out of AgentPanel
- * so sibling surfaces (the Context Manager dock panel) can read them and toggle
- * include/exclude. Module-level + reactive (same pattern as lib/usage, recall).
- * Session load/save still lives in AgentPanel; this is just the live buffer. */
-import { useEffect, useReducer } from 'react';
-let turns = [];
-const listeners = new Set();
-const notify = () => { listeners.forEach((fn) => fn()); };
-export function getTurns() { return turns; }
-/** React-style setter: accepts a value or an updater. */
-export function setTurns(next) {
-    turns = typeof next === 'function' ? next(turns) : next;
-    notify();
-}
-/** Toggle a turn's include flag (warm-context inclusion — before compression). */
-export function toggleInclude(id) {
-    setTurns((t) => t.map((x) => (x.id === id ? { ...x, included: !x.included } : x)));
-}
-/** Subscribe a component to the live turns. */
-export function useConversation() {
-    const [, force] = useReducer((x) => x + 1, 0);
-    useEffect(() => { listeners.add(force); return () => { listeners.delete(force); }; }, []);
-    return { turns, setTurns, toggleInclude };
-}
+export {};
 //# sourceMappingURL=conversation.js.map

package/dist/conversation.js.map

@@ -1 +1 @@
-{"version":3,"file":"conversation.js","sourceRoot":"","sources":["../conversation.ts"],"names":[],"mappings":"AAAA;;;gFAGgF;AAChF,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAqB9C,IAAI,KAAK,GAAuB,EAAE,CAAC;AACnC,MAAM,SAAS,GAAG,IAAI,GAAG,EAAc,CAAC;AACxC,MAAM,MAAM,GAAG,GAAS,EAAE,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;AAEhE,MAAM,UAAU,QAAQ,KAAyB,OAAO,KAAK,CAAC,CAAC,CAAC;AAEhE,yDAAyD;AACzD,MAAM,UAAU,QAAQ,CAAC,IAA6E;IACpG,KAAK,GAAG,OAAO,IAAI,KAAK,UAAU,CAAC,CAAC,CAAE,IAAsD,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC3G,MAAM,EAAE,CAAC;AACX,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,aAAa,CAAC,EAAU;IACtC,QAAQ,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACrF,CAAC;AAED,+CAA+C;AAC/C,MAAM,UAAU,eAAe;IAK7B,MAAM,CAAC,EAAE,KAAK,CAAC,GAAG,UAAU,CAAC,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IACtD,SAAS,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,GAAG,EAAE,GAAG,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAC1F,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,CAAC;AAC5C,CAAC"}
+{"version":3,"file":"conversation.js","sourceRoot":"","sources":["../conversation.ts"],"names":[],"mappings":""}

package/dist/core/budget.d.ts

@@ -0,0 +1,40 @@
+export interface RunConstraints {
+    maxUsd?: number;
+    maxTokens?: number;
+    maxMs?: number;
+}
+export interface BudgetState {
+    usd: number;
+    tokens: number;
+    ms: number;
+}
+export interface Breach {
+    kind: 'usd' | 'tokens' | 'ms';
+    spent: number;
+    limit: number;
+}
+export declare class BudgetMeter {
+    private readonly constraints;
+    private readonly nowFn;
+    private usd;
+    private tokens;
+    private readonly start;
+    constructor(constraints: RunConstraints, nowFn: () => number);
+    add(usage: {
+        inTok?: number;
+        outTok?: number;
+        cost?: number;
+    }): void;
+    state(): BudgetState;
+    breach(): Breach | null;
+    willExceed(projUsd: number, projTokens: number): boolean;
+}
+/** What the agent does when a run budget is breached (the agent-surface
+ * vocabulary; the strategy runner has its own ladder/degrade/replan/stop). */
+export type AgentBreachAction = 'ask' | 'stop' | 'warn' | 'degrade';
+/** RunConstraints plus the agent's breach policy — the shape every agent
+ * surface persists and every runtime merges per run. */
+export interface AgentConstraints extends RunConstraints {
+    onBreach?: AgentBreachAction;
+}
+//# sourceMappingURL=budget.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"budget.d.ts","sourceRoot":"","sources":["../../core/budget.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,cAAc;IAAG,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE;AACvF,MAAM,WAAW,WAAW;IAAG,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE;AACxE,MAAM,WAAW,MAAM;IAAG,IAAI,EAAE,KAAK,GAAG,QAAQ,GAAG,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE;AAEvF,qBAAa,WAAW;IAMpB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,KAAK;IANxB,OAAO,CAAC,GAAG,CAAK;IAChB,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;gBAGZ,WAAW,EAAE,cAAc,EAC3B,KAAK,EAAE,MAAM,MAAM;IAKtC,GAAG,CAAC,KAAK,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAKpE,KAAK,IAAI,WAAW;IAIpB,MAAM,IAAI,MAAM,GAAG,IAAI;IASvB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO;CAMzD;AAED;8EAC8E;AAC9E,MAAM,MAAM,iBAAiB,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;AACpE;wDACwD;AACxD,MAAM,WAAW,gBAAiB,SAAQ,cAAc;IAAG,QAAQ,CAAC,EAAE,iBAAiB,CAAA;CAAE"}

package/dist/core/budget.js

@@ -0,0 +1,62 @@
+export class BudgetMeter {
+    constructor(constraints, nowFn) {
+        Object.defineProperty(this, "constraints", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: constraints
+        });
+        Object.defineProperty(this, "nowFn", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: nowFn
+        });
+        Object.defineProperty(this, "usd", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        Object.defineProperty(this, "tokens", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        Object.defineProperty(this, "start", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.start = nowFn();
+    }
+    add(usage) {
+        this.tokens += (usage.inTok || 0) + (usage.outTok || 0);
+        this.usd += usage.cost || 0;
+    }
+    state() {
+        return { usd: this.usd, tokens: this.tokens, ms: this.nowFn() - this.start };
+    }
+    breach() {
+        const { maxUsd, maxTokens, maxMs } = this.constraints;
+        const s = this.state();
+        if (maxUsd != null && s.usd > maxUsd)
+            return { kind: 'usd', spent: s.usd, limit: maxUsd };
+        if (maxTokens != null && s.tokens > maxTokens)
+            return { kind: 'tokens', spent: s.tokens, limit: maxTokens };
+        if (maxMs != null && s.ms > maxMs)
+            return { kind: 'ms', spent: s.ms, limit: maxMs };
+        return null;
+    }
+    willExceed(projUsd, projTokens) {
+        const { maxUsd, maxTokens } = this.constraints;
+        if (maxUsd != null && this.usd + projUsd > maxUsd)
+            return true;
+        if (maxTokens != null && this.tokens + projTokens > maxTokens)
+            return true;
+        return false;
+    }
+}
+//# sourceMappingURL=budget.js.map

package/dist/core/budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.js","sourceRoot":"","sources":["../../core/budget.ts"],"names":[],"mappings":"AAUA,MAAM,OAAO,WAAW;IAKtB,YACmB,WAA2B,EAC3B,KAAmB;QADpC;;;;mBAAiB,WAAW;WAAgB;QAC5C;;;;mBAAiB,KAAK;WAAc;QAN9B;;;;mBAAM,CAAC;WAAC;QACR;;;;mBAAS,CAAC;WAAC;QACF;;;;;WAAc;QAM7B,IAAI,CAAC,KAAK,GAAG,KAAK,EAAE,CAAC;IACvB,CAAC;IAED,GAAG,CAAC,KAAyD;QAC3D,IAAI,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC;QACxD,IAAI,CAAC,GAAG,IAAI,KAAK,CAAC,IAAI,IAAI,CAAC,CAAC;IAC9B,CAAC;IAED,KAAK;QACH,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,EAAE,EAAE,IAAI,CAAC,KAAK,EAAE,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;IAC/E,CAAC;IAED,MAAM;QACJ,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,IAAI,CAAC,WAAW,CAAC;QACtD,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;QACvB,IAAI,MAAM,IAAI,IAAI,IAAI,CAAC,CAAC,GAAG,GAAG,MAAM;YAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;QAC1F,IAAI,SAAS,IAAI,IAAI,IAAI,CAAC,CAAC,MAAM,GAAG,SAAS;YAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;QAC5G,IAAI,KAAK,IAAI,IAAI,IAAI,CAAC,CAAC,EAAE,GAAG,KAAK;YAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;QACpF,OAAO,IAAI,CAAC;IACd,CAAC;IAED,UAAU,CAAC,OAAe,EAAE,UAAkB;QAC5C,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,IAAI,CAAC,WAAW,CAAC;QAC/C,IAAI,MAAM,IAAI,IAAI,IAAI,IAAI,CAAC,GAAG,GAAG,OAAO,GAAG,MAAM;YAAE,OAAO,IAAI,CAAC;QAC/D,IAAI,SAAS,IAAI,IAAI,IAAI,IAAI,CAAC,MAAM,GAAG,UAAU,GAAG,SAAS;YAAE,OAAO,IAAI,CAAC;QAC3E,OAAO,KAAK,CAAC;IACf,CAAC;CACF"}

package/dist/core/loop.d.ts

@@ -1,12 +1,16 @@
 import type OpenAI from 'openai';
 import type { ChatCompletionMessageParam } from 'openai/resources/chat/completions';
 import type { AgentTool, ToolContext, AgentEvent, Usage } from '@corenel/protocol';
+import { type RecoveryConfig } from './recovery';
 import type { Policy } from '@corenel/protocol';
 import type { PermissionService } from '../guardrail/permission-service';
 import { type CompressionConfig } from '../compression';
 export interface RunAgentArgs {
     client: OpenAI;
     model: string;
+    /** Resolve the model fresh each turn — lets the host degrade to a cheaper
+     * model mid-run. Omit for a fixed `model`. */
+    getModel?: () => string;
     system?: string;
     messages: ChatCompletionMessageParam[];
     tools: AgentTool[];
@@ -18,6 +22,13 @@ export interface RunAgentArgs {
     permission?: PermissionService;
     /** Context-compression config (rung-1 offload). Omit to disable. */
     compression?: CompressionConfig;
+    /** Intra-run self-healing budget (stream-retry + tool-steer). Omit for defaults. */
+    recovery?: Partial<RecoveryConfig>;
+    /** 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;
 }