@corenel/harness 0.19.0 → 0.21.0

package/dist/chat/engine.js

@@ -0,0 +1,803 @@
+/* The conversation engine: one instance holds the state of every conversation
+ * it has touched and runs their turns through a host. It never runs the agent
+ * loop itself (that is the host's runLoop) and never reaches a store or a
+ * screen except through the host's methods. */
+import { HOOK_ASK_TOOL, isCheckpointTool } from '@corenel/protocol';
+import { isFoldedTurn, turnsFromSessionMessages } from '../conversation.js';
+import { CHECKPOINT_MARKER } from '../core/compactHistory.js';
+import { dispatchChatEvent } from './events.js';
+import { foldLive } from './liveFold.js';
+import { buildUserMessage, outgoingMessages, userImages, userText } from './messages.js';
+import { ConversationWriter, flagIfUnsaved } from './persist.js';
+import { createRunWatchdog, WATCHDOG_SOFT_MS } from './runWatchdog.js';
+import { stitchTurn } from './stitch.js';
+const SILENT_MSG = 'No response from the gateway in 45s — aborted. Check that you are signed in and the backend is reachable.';
+const TOOL_CAP_MSG = 'A tool ran for over 10 minutes without completing — aborted. The connection to it may have dropped.';
+function emptyState() {
+    return {
+        turns: [], live: null, running: false, error: '', lastStopReason: null, injectedIds: [], runId: null,
+        loaded: false, loadMissed: false, persistedLen: null, saveBlocked: null, mergeTick: 0,
+        pendingCommand: null,
+    };
+}
+/** A session allow is keyed by WHO asked and the tool, so allowing a callee's
+ * write never carries to another callee, or to the caller. */
+/** Asked every time, never a session allow: a checkpoint, and a System One
+ * check or hook ask (its answer is for one tool call only). */
+function askedEveryTime(tool) {
+    return isCheckpointTool(tool) || tool === HOOK_ASK_TOOL;
+}
+function allowKey(agent, tool) {
+    return JSON.stringify([agent ?? '', tool]);
+}
+const messageOf = (e) => String((e instanceof Error && e.message) || e);
+/** host.turnComplete, contained: a host whose handler throws must not skip the
+ * turn's write drain or reject hostTurn. */
+function complete(host, r) {
+    try {
+        host.turnComplete(r);
+    }
+    catch { /* the host's own handler failed; the turn still settles */ }
+}
+const noteId = (prefix) => `${prefix}${Date.now().toString(36)}${Math.random().toString(36).slice(2, 6)}`;
+export function createChat() {
+    const slots = new Map();
+    /* The write queue is one per engine, so writes to a conversation stay in
+     * order whichever call queued them; each write goes to the host last used
+     * for that conversation. */
+    const stores = new Map();
+    const storeFor = (id) => {
+        const s = stores.get(id);
+        if (!s)
+            throw new Error(`no host for conversation ${id}`);
+        return s;
+    };
+    const writer = new ConversationWriter({
+        loadConversation: (id) => storeFor(id).loadConversation(id),
+        writeConversation: (c, opts) => storeFor(c.id).writeConversation(c, opts),
+    });
+    const slotFor = (id) => {
+        let s = slots.get(id);
+        if (!s) {
+            s = { state: emptyState(), abort: null, allowed: new Set(), saves: 0, system: null, injecting: Promise.resolve() };
+            slots.set(id, s);
+        }
+        return s;
+    };
+    /* Forgotten until a load or a turn opens it again: a late write (a command
+     * settling after its chat was closed) must not bring it back. */
+    const forgotten = new Set();
+    // Conversations whose system was reset and not asked again since (R4).
+    const systemResets = new Set();
+    const reopen = (id) => { forgotten.delete(id); };
+    const editable = (id) => (forgotten.has(id) ? null : slotFor(id));
+    /** Queues a save of the conversation as it stands when the write runs. */
+    function save(id, host) {
+        stores.set(id, host);
+        return writer.queue(id, async () => {
+            const slot = slots.get(id);
+            if (!slot)
+                return;
+            slot.saves += 1;
+            const s = slot.state;
+            const before = s.saveBlocked;
+            const { merged } = await writer.persist(id, s, null, slot.system);
+            if (merged || s.saveBlocked !== before)
+                host.stateChanged(id, false);
+        }).catch(() => { });
+    }
+    /** A transcript-only turn (never sent), saved through the queue. A no-op
+     * once the conversation is forgotten: a late event must not bring it back. */
+    function noteTurn(id, host, turn) {
+        const s = editable(id)?.state;
+        if (!s)
+            return turn.id;
+        s.turns = [...s.turns, turn];
+        host.stateChanged(id, false);
+        void save(id, host);
+        return turn.id;
+    }
+    function note(id, host, text, extra) {
+        return noteTurn(id, host, { id: noteId('n'), included: false, messages: [{ role: 'assistant', content: text }], ...extra });
+    }
+    /* The compaction seam: permanent in the transcript, unsent, so it never
+     * describes the compaction back to the model on a later turn. */
+    function noteCheckpoint(id, host, collapsed, body) {
+        const n = collapsed === 1 ? '1 message' : `${collapsed} messages`;
+        return noteTurn(id, host, {
+            id: noteId('n'), included: false,
+            messages: [{ role: 'assistant', content: `${CHECKPOINT_MARKER}${n} collapsed — earlier context is summarized from here` }],
+            ...(body ? { checkpoint: body } : {}),
+        });
+    }
+    /* An injected message shown as the user's turn; the run's own copy is what
+     * gets sent, so this one is not included. */
+    function noteUser(id, host, text) {
+        return noteTurn(id, host, { id: noteId('u'), included: false, messages: [{ role: 'user', content: text }] });
+    }
+    /* R4 reset. The mark lives on the engine, not the slot, so it survives a
+     * forget: until the next turn asks host.system, a load ignores the stored
+     * system. When a store for the id is known, the stored field is removed now
+     * through the write queue, so a restart before the next save cannot read it
+     * back either. The removal is skipped once a newer ask has frozen a system,
+     * and entirely for a host that stores none (`stored: false`). */
+    function resetSystem(id, opts) {
+        systemResets.add(id);
+        const slot = slots.get(id);
+        if (slot)
+            slot.system = null;
+        if (opts?.stored === false)
+            return;
+        const store = stores.get(id);
+        if (!store)
+            return;
+        void writer.queue(id, async () => {
+            if (!systemResets.has(id))
+                return;
+            const c = await store.loadConversation(id);
+            if (!c || c.system === undefined)
+                return;
+            const { system: _dropped, ...rest } = c;
+            await store.writeConversation(rest, { allowTruncate: false });
+        }).catch(() => { });
+    }
+    /** Titles an untitled conversation from its first message; a hand-renamed one is locked. */
+    function queueTitle(id, host, text) {
+        return writer.queue(id, async () => {
+            const c = await host.loadConversation(id);
+            if (c && !c.titleLocked) {
+                await host.writeConversation({ ...c, title: text.slice(0, 48) }, { allowTruncate: false }).catch(() => { });
+                host.stateChanged(id, true);
+            }
+        }).catch(() => { });
+    }
+    async function load(id, host) {
+        if (!id)
+            return;
+        reopen(id);
+        stores.set(id, host);
+        const s = slotFor(id).state;
+        if (s.loaded)
+            return;
+        /* A read that throws is a miss, not an error: the turn still runs,
+         * saveBlocked says it is not kept, and retryLoad reads again. */
+        let stored;
+        try {
+            stored = await host.loadConversation(id);
+        }
+        catch {
+            stored = null;
+        }
+        // A concurrent load landed first and its merge already holds everything.
+        if (s.loaded)
+            return;
+        // Merge, never replace: what this side added before the load comes after it.
+        const pre = s.turns;
+        if (stored) {
+            // A system frozen by an earlier turn is used as stored, without asking the host (R4).
+            const slot = slotFor(id);
+            // A reset not yet followed by a fresh ask means the stored one is stale.
+            if (slot.system === null && !systemResets.has(id) && typeof stored.system === 'string')
+                slot.system = stored.system;
+            s.turns = [...turnsFromSessionMessages(stored.messages), ...pre];
+            s.persistedLen = stored.messages.length;
+            // Only on a hit: a miss stays unloaded so the next ask reads again.
+            s.loaded = true;
+        }
+        s.loadMissed = !stored;
+        if (stored && !pre.length)
+            s.saveBlocked = null;
+        host.stateChanged(id, false);
+        if (stored && pre.length)
+            void save(id, host);
+    }
+    async function retryLoad(id, host) {
+        await load(id, host);
+        const s = slots.get(id)?.state;
+        if (!s?.loaded)
+            return false;
+        await save(id, host);
+        // Global: the conversation list may have dropped this one while it missed.
+        host.stateChanged(id, true);
+        return s.saveBlocked === null;
+    }
+    function inject(id, host, messages, hard) {
+        const s = slots.get(id)?.state;
+        if (!s || !s.running || s.runId == null)
+            return false;
+        return guardedInject(id, s.runId, host, messages, hard, undefined);
+    }
+    /* Accepted now, delivered once the guard allows (R1). Guards run one after
+     * another per conversation, so the order the messages were sent holds. A
+     * refusal, or a guard that throws, delivers nothing and shows the reason;
+     * the host reverts a queued message that onInjected never reports. */
+    function guardedInject(id, runId, host, messages, hard, agent) {
+        const slot = slotFor(id);
+        const deliver = async () => {
+            let verdict;
+            try {
+                verdict = await host.guard({ conversationId: id, ...(agent ? { agent } : {}), kind: 'inject' });
+            }
+            catch (e) {
+                verdict = { allowed: false, guardId: 'guard-error', reason: messageOf(e) };
+            }
+            const live = slots.get(id) === slot;
+            if (verdict.allowed) {
+                // The run it was accepted for has ended while the guard waited: dropped, never delivered elsewhere.
+                if (live && slot.state.running && slot.state.runId === runId)
+                    host.injectInto(runId, messages, hard);
+                return;
+            }
+            if (!live)
+                return;
+            slot.state.error = verdict.reason;
+            host.stateChanged(id, false);
+        };
+        slot.injecting = slot.injecting.then(deliver).catch(() => { });
+        return true;
+    }
+    function run(request, host) {
+        return start(request, host, { kind: 'send' });
+    }
+    function start(request, host, mode) {
+        const ac = new AbortController();
+        let stopRequested;
+        let current = request.conversationId;
+        // The run id this turn's own onStart reported: ChatRun.inject addresses only it (R2).
+        let ownRunId = null;
+        // True once runLoop was called (ChatTurnResult.ran).
+        let ran = false;
+        // turnComplete is called exactly once per turn, whichever way it ends (R3).
+        let completed = false;
+        const finish = (r) => {
+            if (!completed) {
+                completed = true;
+                complete(host, r);
+            }
+            return r;
+        };
+        const kind = mode.kind;
+        let resolveId;
+        const conversationId = new Promise((r) => { resolveId = r; });
+        async function turn() {
+            const text = request.input.text;
+            const images = request.input.images ?? [];
+            const agentCtx = request.agent ? { agent: request.agent } : {};
+            // Refused before anything changed: empty input, or a run already going.
+            const refused = (cid) => {
+                mode.rollback?.();
+                return finish({ conversationId: cid, userTurnId: '', outcome: 'refused', ran: false, kind });
+            };
+            /* Null when the turn may run. A guard that throws is a failed turn, rolled
+             * back exactly like a refusal. */
+            const askGuard = (cid) => host.guard({ conversationId: cid, ...agentCtx, kind: mode.kind }).then((v) => (v.allowed ? null : { outcome: 'refused', error: v.reason }), (e) => ({ outcome: 'failed', error: messageOf(e) }));
+            let id = request.conversationId;
+            if (!text && !images.length)
+                return refused(id);
+            let created = false;
+            if (id == null) {
+                /* A new conversation is guarded BEFORE it exists, so a refused first
+                 * turn creates and writes nothing and its id resolves to null. */
+                const denied = await askGuard(null);
+                if (denied)
+                    return finish({ conversationId: null, userTurnId: '', ...denied, ran: false, kind });
+                try {
+                    id = await host.createConversation(text.slice(0, 48));
+                }
+                catch (e) {
+                    return finish({ conversationId: null, userTurnId: '', outcome: 'failed', error: messageOf(e), ran: false, kind });
+                }
+                created = true;
+                current = id;
+                stores.set(id, host);
+                const fresh = slotFor(id).state;
+                fresh.loaded = true;
+                fresh.persistedLen = 0;
+            }
+            else {
+                reopen(id);
+                /* Busy is refused BEFORE the store is rebound: the running turn's later
+                 * saves must keep going through its own host, not the refused one's. */
+                if (slotFor(id).state.running)
+                    return refused(id);
+                stores.set(id, host);
+                /* The stored chat first (R35): a turn built on the empty pre-load list
+                 * would run with no history and be wiped by the load or never saved. */
+                if (!slotFor(id).state.loaded) {
+                    await load(id, host);
+                    // Another run started while this one waited (R37): nothing happens.
+                    if (slotFor(id).state.running)
+                        return refused(id);
+                }
+            }
+            const cid = id;
+            const slot = slotFor(cid);
+            const s = slot.state;
+            // Only a LOADED empty chat is new; one whose load missed is empty because it was never read.
+            const isFirst = !created && s.loaded && s.turns.length === 0;
+            // A random tail: two turns in one millisecond must not share an id, or a refusal removes both.
+            const userTurn = { id: noteId('t'), included: true, messages: [buildUserMessage(text, images)] };
+            const nextTurns = [...s.turns, userTurn];
+            // Forgotten mid-turn: the turn's late writes must not land on a slot that is gone.
+            const attached = () => slots.get(cid) === slot;
+            /* Transcript-only turns for messages injected mid-run: removed once the
+             * run returns its own copy, promoted if it throws instead. */
+            const injectedTurnIds = [];
+            // The seams THIS run wrote; the last one takes the run's folded view.
+            const seamIds = [];
+            const toolMs = {};
+            const toolChecks = {};
+            const toolHooks = {};
+            let verification;
+            let auditIncomplete;
+            let timedOut = false;
+            // Armed once the guard has allowed the turn; a holder, since closures set it.
+            const watch = { dog: null };
+            // Something waits on a person: the run is waiting, not wedged.
+            const paused = async (ask) => {
+                watch.dog?.pause();
+                try {
+                    return await ask();
+                }
+                finally {
+                    watch.dog?.bump();
+                }
+            };
+            const onEvent = (e) => {
+                watch.dog?.onEvent(e);
+                if (attached()) {
+                    let changed = false;
+                    switch (e.type) {
+                        case 'tool-result':
+                            if (typeof e.durationMs === 'number')
+                                toolMs[e.id] = e.durationMs;
+                            break;
+                        case 'tool-check':
+                            if (e.check.ok)
+                                toolChecks[e.id] = { score: e.check.score, cut: e.check.cut, ...(e.check.outcome ? { outcome: e.check.outcome } : {}) };
+                            // Not scored, but it asked: what the ask led to is kept, with no score.
+                            else if (e.check.outcome)
+                                toolChecks[e.id] = { failed: true, outcome: e.check.outcome };
+                            break;
+                        // The marks only: a blocked result (blockedText) is the host's to keep in memory, never the transcript's.
+                        case 'tool-hooks':
+                            toolHooks[e.id] = {
+                                marks: e.mark.marks.map((m) => ({ name: m.name, action: m.action, outcome: m.outcome })),
+                                ...(e.mark.off ? { off: true } : {}),
+                                ...(e.blockedText !== undefined ? { withheld: true } : {}),
+                            };
+                            break;
+                        case 'checkpoint':
+                            seamIds.push(noteCheckpoint(cid, host, e.collapsed, e.checkpoint));
+                            break;
+                        case 'injected':
+                            injectedTurnIds.push(noteUser(cid, host, e.content));
+                            break;
+                        case 'turn-verified':
+                            verification = e.verification;
+                            break;
+                        case 'audit-incomplete':
+                            auditIncomplete = { lost: e.lost, ...(e.unconfirmed ? { unconfirmed: true } : {}) };
+                            break;
+                        case 'error':
+                            s.error = e.message;
+                            changed = true;
+                            break;
+                        default: break;
+                    }
+                    if (s.live) {
+                        const next = foldLive(s.live, e);
+                        if (next !== s.live) {
+                            s.live = next;
+                            changed = true;
+                        }
+                    }
+                    if (changed)
+                        host.stateChanged(cid, false);
+                }
+                dispatchChatEvent(e, host, { conversationId: cid });
+            };
+            /* Everything from the optimistic patch on runs inside the try below, so
+             * the finally clears `running` whatever throws. */
+            const body = async () => {
+                /* OPTIMISTIC: the turn shows before the guard answers (the guard can be
+                 * a network call). A refusal puts it back; the finally clears the rest. */
+                const seen = slot.saves;
+                Object.assign(s, { turns: nextTurns, error: '', live: { text: '', tools: [] }, running: true, injectedIds: [], lastStopReason: null });
+                // Still not loaded after that retry: this exchange runs but is not kept; say so now.
+                flagIfUnsaved(s);
+                host.stateChanged(cid, true);
+                if (!created) {
+                    const denied = await askGuard(cid);
+                    if (denied) {
+                        s.turns = s.turns.filter((t) => t.id !== userTurn.id);
+                        if (mode.rollback)
+                            mode.rollback();
+                        // A save while the guard waited wrote the turn just removed.
+                        else if (slot.saves !== seen && attached())
+                            void save(cid, host);
+                        s.error = denied.error;
+                        return { conversationId: cid, userTurnId: userTurn.id, ...denied, ran: false, kind };
+                    }
+                }
+                resolveId(cid);
+                /* A stop pressed before the loop starts ends the turn here: a loop handed
+                 * an already-aborted signal would never see the abort. The user turn
+                 * stays, as for a stopped run with no reply. */
+                const stoppedEarly = () => {
+                    if (!ac.signal.aborted)
+                        return null;
+                    if (attached())
+                        void save(cid, host);
+                    return {
+                        conversationId: cid, userTurnId: userTurn.id, outcome: timedOut ? 'failed' : 'stopped',
+                        ...(stopRequested ? { stopReason: stopRequested } : {}), ...(s.error ? { error: s.error } : {}),
+                        ran: false, kind,
+                    };
+                };
+                const early = stoppedEarly();
+                if (early)
+                    return early;
+                if (isFirst && text)
+                    await queueTitle(cid, host, text);
+                const afterTitle = stoppedEarly();
+                if (afterTitle)
+                    return afterTitle;
+                const dog = createRunWatchdog((reason) => {
+                    timedOut = true;
+                    ac.abort();
+                    if (!attached())
+                        return;
+                    s.error = reason === 'tool-hard-cap' ? TOOL_CAP_MSG : SILENT_MSG;
+                    host.stateChanged(cid, false);
+                }, { softMs: WATCHDOG_SOFT_MS });
+                watch.dog = dog;
+                dog.bump();
+                const ctx = { conversationId: cid, ...agentCtx };
+                // Frozen after the first turn (R4): asked only while this conversation holds none.
+                const held = slot.system;
+                const [system, opts] = await Promise.all([held ?? host.system(ctx), host.runOptions(ctx)]);
+                if (held === null && attached() && slot.system === null) {
+                    slot.system = system;
+                    systemResets.delete(cid);
+                }
+                const beforeLoop = stoppedEarly();
+                if (beforeLoop)
+                    return beforeLoop;
+                const control = {
+                    conversationId: cid,
+                    system,
+                    signal: ac.signal,
+                    onEvent,
+                    // The run's id the instant it exists, so inject() has something live to address.
+                    onStart: (runId) => { ownRunId = runId; if (attached())
+                        s.runId = runId; },
+                    onInjected: (ids) => {
+                        if (!attached())
+                            return;
+                        s.injectedIds = [...s.injectedIds, ...ids];
+                        host.stateChanged(cid, false);
+                    },
+                    askPermission: async (req) => {
+                        // A checkpoint or a System One ask is asked every time, whatever the session allowed.
+                        const key = allowKey(req.agent, req.tool);
+                        if (!askedEveryTime(req.tool) && slot.allowed.has(key))
+                            return { allow: true, by: 'session' };
+                        const answer = await paused(() => host.askPermission(cid, req));
+                        if (answer.allow && answer.always && !askedEveryTime(req.tool))
+                            slot.allowed.add(key);
+                        return answer;
+                    },
+                    askUser: (questions) => paused(() => host.askUser(cid, questions, ac.signal)),
+                    reviewEdit: (callId) => paused(() => host.reviewEdit(cid, callId, ac.signal)),
+                    paused,
+                };
+                ran = true;
+                const res = await host.runLoop(outgoingMessages(nextTurns), opts, control);
+                if (attached()) {
+                    s.turns = stitchTurn({
+                        turns: s.turns, userTurnId: userTurn.id, result: { ...res, toolMs: { ...toolMs, ...res.toolMs } },
+                        toolChecks, toolHooks, injectedTurnIds, seamIds, verification, auditIncomplete,
+                    });
+                    s.lastStopReason = res.stopReason;
+                    host.stateChanged(cid, false);
+                    void save(cid, host);
+                }
+                const outcome = timedOut ? 'failed' : ac.signal.aborted ? 'stopped' : 'done';
+                if (outcome === 'done')
+                    host.suggestFollowups({ conversationId: cid, messages: res.messages, signal: ac.signal });
+                return {
+                    conversationId: cid, userTurnId: userTurn.id, outcome, stopReason: res.stopReason,
+                    ...(s.error ? { error: s.error } : {}), ...(res.stats ? { stats: res.stats } : {}),
+                    ran: true, kind,
+                };
+            };
+            slot.abort = ac;
+            let result;
+            try {
+                result = await body();
+            }
+            catch (e) {
+                /* A throw never returns the run's messages, so its copy of every
+                 * injected message dies with it. Promote the transcript-only turns to
+                 * real history, or the correction is silently gone from the next send. */
+                const error = messageOf(e);
+                if (attached()) {
+                    if (injectedTurnIds.length)
+                        s.turns = s.turns.map((t) => (injectedTurnIds.includes(t.id) ? { ...t, included: true } : t));
+                    s.error = error;
+                    void save(cid, host);
+                }
+                result = {
+                    conversationId: cid, userTurnId: userTurn.id, outcome: timedOut || !ac.signal.aborted ? 'failed' : 'stopped',
+                    error, ...(stopRequested ? { stopReason: stopRequested } : {}),
+                    ran, kind,
+                };
+            }
+            finally {
+                watch.dog?.clear();
+                slot.abort = null;
+                s.runId = null;
+                s.running = false;
+                s.live = null;
+                if (attached())
+                    host.stateChanged(cid, true);
+            }
+            finish(result);
+            // Settles after every write this turn queued, so done means saved (or failed to save).
+            await writer.queue(cid, async () => { }).catch(() => { });
+            return result;
+        }
+        const done = turn().then((r) => { resolveId(r.conversationId); return r; }, (e) => {
+            resolveId(current);
+            const r = { conversationId: current, userTurnId: '', outcome: 'failed', error: messageOf(e), ran, kind };
+            finish(r);
+            return r;
+        });
+        return {
+            conversationId,
+            done,
+            stop: (reason) => { stopRequested = reason; ac.abort(); },
+            // Only this turn's own run, and only while it is the conversation's current run (R2).
+            inject: (messages, hard) => {
+                if (current === null || ownRunId === null)
+                    return false;
+                const s = slots.get(current)?.state;
+                if (!s || !s.running || s.runId !== ownRunId)
+                    return false;
+                return guardedInject(current, ownRunId, host, messages, hard, request.agent);
+            },
+        };
+    }
+    function retry(id, turnId, host) {
+        const slot = forgotten.has(id) ? undefined : slots.get(id);
+        const s = slot?.state;
+        const idx = s ? s.turns.findIndex((t) => t.id === turnId) : -1;
+        const first = s && idx >= 0 ? s.turns[idx].messages[0] : undefined;
+        const text = first ? userText(first) : '';
+        const images = first ? userImages(first) : [];
+        if (!slot || !s || s.running || (!text && !images.length)) {
+            const r = { conversationId: id, userTurnId: '', outcome: 'refused', ran: false, kind: 'retry' };
+            complete(host, r);
+            return { conversationId: Promise.resolve(id), done: Promise.resolve(r), stop: () => { }, inject: () => false };
+        }
+        const dropped = s.turns.slice(idx);
+        // By id, not index: a load that lands before the refusal puts stored turns first.
+        const anchor = idx > 0 ? s.turns[idx - 1].id : null;
+        // A save while the guard waits writes the truncated list, or merges stored turns back in.
+        const seen = slot.saves;
+        s.turns = s.turns.slice(0, idx);
+        host.stateChanged(id, false);
+        return start({ conversationId: id, input: { text, images } }, host, {
+            kind: 'retry',
+            // Back where they were; anything noted since stays after them.
+            rollback: () => {
+                if (slots.get(id) !== slot)
+                    return;
+                const now = slot.state.turns;
+                const have = new Set(now.map((t) => t.id));
+                const back = dropped.filter((t) => !have.has(t.id));
+                const found = anchor === null ? 0 : now.findIndex((t) => t.id === anchor) + 1;
+                const at = found > 0 || anchor === null ? found : now.length;
+                slot.state.turns = [...now.slice(0, at), ...back, ...now.slice(at)];
+                if (slot.saves !== seen)
+                    void save(id, host);
+            },
+        });
+    }
+    async function hostTurn(id, text, produce, host) {
+        // turnComplete exactly once, whichever way this ends (R3); ran means produce was called.
+        const refused = () => { complete(host, { conversationId: id, userTurnId: '', outcome: 'refused', ran: false, kind: 'host-turn' }); };
+        if (!text) {
+            refused();
+            return;
+        }
+        reopen(id);
+        stores.set(id, host);
+        const slot = slotFor(id);
+        const s = slot.state;
+        if (s.running) {
+            refused();
+            return;
+        }
+        // As in run: never build on a transcript that has not loaded.
+        if (!s.loaded) {
+            await load(id, host);
+            if (s.running) {
+                refused();
+                return;
+            }
+        }
+        const attached = () => slots.get(id) === slot;
+        const isFirst = s.loaded && s.turns.length === 0;
+        const userTurn = { id: noteId('t'), included: true, messages: [{ role: 'user', content: text }] };
+        const ac = new AbortController();
+        slot.abort = ac;
+        // Optimistic, as in run: the guard can be a network call.
+        Object.assign(s, { turns: [...s.turns, userTurn], error: '', live: { text: '', tools: [] }, running: true });
+        flagIfUnsaved(s);
+        host.stateChanged(id, true);
+        const denied = await host.guard({ conversationId: id, kind: 'host-turn' }).then((v) => (v.allowed ? null : { outcome: 'refused', error: v.reason }), (e) => ({ outcome: 'failed', error: messageOf(e) }));
+        if (denied !== null) {
+            slot.abort = null;
+            if (attached()) {
+                Object.assign(s, { turns: s.turns.filter((t) => t.id !== userTurn.id), running: false, live: null, error: denied.error });
+                host.stateChanged(id, true);
+            }
+            complete(host, { conversationId: id, userTurnId: userTurn.id, ...denied, ran: false, kind: 'host-turn' });
+            return;
+        }
+        let result = { conversationId: id, userTurnId: userTurn.id, outcome: 'done', ran: true, kind: 'host-turn' };
+        try {
+            const content = await produce(ac.signal);
+            if (attached()) {
+                const reply = { role: 'assistant', content };
+                s.turns = s.turns.map((t) => (t.id === userTurn.id ? { ...t, messages: [userTurn.messages[0], reply] } : t));
+                host.stateChanged(id, false);
+                void save(id, host);
+                // Queued behind the save, so the title lands on the stored chat.
+                if (isFirst)
+                    void queueTitle(id, host, text);
+            }
+        }
+        catch (e) {
+            const error = messageOf(e);
+            if (attached())
+                s.error = error;
+            result = { ...result, outcome: ac.signal.aborted ? 'stopped' : 'failed', error };
+        }
+        finally {
+            slot.abort = null;
+            s.running = false;
+            s.live = null;
+            if (attached())
+                host.stateChanged(id, true);
+        }
+        complete(host, result);
+        // Settles after every write this turn queued, as run's done does.
+        await writer.queue(id, async () => { }).catch(() => { });
+    }
+    function toggleInclude(id, host, turnId) {
+        const s = editable(id)?.state;
+        if (!s || isFoldedTurn(s.turns, s.turns.findIndex((t) => t.id === turnId)))
+            return;
+        s.turns = s.turns.map((t) => (t.id === turnId ? { ...t, included: !t.included } : t));
+        host.stateChanged(id, false);
+        void save(id, host);
+    }
+    function clear(id, host) {
+        const s = editable(id)?.state;
+        if (!s)
+            return;
+        s.turns = [];
+        s.error = '';
+        host.stateChanged(id, true);
+        void save(id, host);
+    }
+    function beginCommand(id, command, startedAt) {
+        const s = editable(id)?.state;
+        if (!s)
+            return;
+        s.pendingCommand = { command, startedAt };
+        stores.get(id)?.stateChanged(id, true);
+    }
+    function abandonCommand(id) {
+        const s = slots.get(id)?.state;
+        if (!s?.pendingCommand)
+            return;
+        s.pendingCommand = null;
+        stores.get(id)?.stateChanged(id, true);
+    }
+    /* Written as the message pair a real tool call produces, so the agent can
+     * read it once kept; not included, so it is not paid for on every later
+     * turn until someone keeps it. */
+    function recordCommand(id, host, command, output, ok) {
+        const s = editable(id)?.state;
+        if (!s)
+            return;
+        const callId = `cmd_${Date.now().toString(36)}${Math.random().toString(36).slice(2, 6)}`;
+        const turn = {
+            id: callId,
+            included: false,
+            messages: [
+                {
+                    role: 'assistant',
+                    content: null,
+                    // `ok` rides in the arguments so a kept command tells the model it failed.
+                    tool_calls: [{ id: callId, type: 'function', function: { name: 'console_command', arguments: JSON.stringify({ command, ok }) } }],
+                },
+                { role: 'tool', tool_call_id: callId, content: output || (ok ? '(no output)' : '(failed, no output)') },
+            ],
+        };
+        s.turns = [...s.turns, turn];
+        s.pendingCommand = null;
+        host.stateChanged(id, true);
+        void save(id, host);
+    }
+    function restoreToolResult(id, host, turnId, blobId, content) {
+        const s = editable(id)?.state;
+        if (!s)
+            return false;
+        const marker = `recall_result({ id: "${blobId}" })`;
+        const at = s.turns.findIndex((t) => t.id === turnId);
+        // A folded turn is stood for by the view: content restored into it would never be sent.
+        if (at < 0 || isFoldedTurn(s.turns, at))
+            return false;
+        const idx = s.turns[at].messages.findIndex((m) => m.role === 'tool' && typeof m.content === 'string' && m.content.includes(marker));
+        if (idx < 0)
+            return false;
+        s.turns = s.turns.map((t) => {
+            if (t.id !== turnId)
+                return t;
+            const messages = t.messages.slice();
+            const m = messages[idx];
+            if (m.role === 'tool')
+                messages[idx] = { ...m, content };
+            return { ...t, messages };
+        });
+        host.stateChanged(id, false);
+        void save(id, host);
+        return true;
+    }
+    /* As run does for a conversation it created: loaded, nothing stored, so
+     * its first save writes without reading back a transcript first. */
+    function seedEmpty(id, host) {
+        reopen(id);
+        stores.set(id, host);
+        const s = slotFor(id).state;
+        s.loaded = true;
+        s.persistedLen = 0;
+    }
+    return {
+        run,
+        load,
+        retryLoad,
+        state: (id) => slotFor(id).state,
+        stop: (id) => { slots.get(id)?.abort?.abort(); },
+        inject,
+        retry,
+        hostTurn,
+        note,
+        noteCheckpoint,
+        noteUser,
+        toggleInclude,
+        clear,
+        beginCommand,
+        abandonCommand,
+        recordCommand,
+        restoreToolResult,
+        seedEmpty,
+        save,
+        resetSystem,
+        isAllowed: (id, agent, tool) => !askedEveryTime(tool) && !!slots.get(id)?.allowed.has(allowKey(agent, tool)),
+        allow: (id, agent, tool) => { if (!askedEveryTime(tool))
+            slotFor(id).allowed.add(allowKey(agent, tool)); },
+        forget: (id) => {
+            slots.get(id)?.abort?.abort();
+            slots.delete(id);
+            stores.delete(id);
+            forgotten.add(id);
+        },
+    };
+}
+//# sourceMappingURL=engine.js.map