@alisio/core 0.1.0-alpha.10

package/dist/core/runner.js

@@ -0,0 +1,625 @@
+import { textResult, } from "@alisio/sdk";
+import { checkpointInstructions, estimateTokens, MAX_TRUSTED_WINDOW, parseCheckpointOutput, planCompaction, reduceMessagesToBudget, shouldCompactContext, summarize, summaryMessage, } from "./compaction.js";
+/**
+ * Default cumulative token budget for one run: several context windows (each turn re-sends the
+ * context), clamped; 1M tokens when the window is unknown.
+ */
+export function defaultTokenBudget(contextWindow) {
+    if (!contextWindow || contextWindow <= 0)
+        return 1_000_000;
+    return Math.min(8_000_000, Math.max(400_000, contextWindow * 8));
+}
+/** Extension output appended to history is capped regardless of what hooks return. */
+const MAX_INJECT_CHARS = 24_000;
+/**
+ * Floor for the post-compaction transcript target: retained messages are never reduced below
+ * this many characters, so a pathological session (instructions alone crowding out the limit)
+ * fails with an actionable error instead of silently losing the whole history.
+ */
+const MIN_MESSAGE_BUDGET_FLOOR = 4_000;
+const allowed = (policy, effect) => effect === "read" || effect === "internal" || !!policy[effect];
+export class AgentRunner {
+    options;
+    /** Sessions with an active run or compaction (one at a time per session). */
+    active = new Map();
+    /** Messages queued for a session's next turn (e.g. input for a running child). */
+    inbox = new Map();
+    /** Last provider-reported context size per session and the history length it covered. */
+    reported = new Map();
+    constructor(options) {
+        this.options = options;
+    }
+    /** Current capability policy (may widen when the user approves an effect for the session). */
+    get policy() {
+        return this.options.policy;
+    }
+    /** Whether write/process tools can be approved interactively. */
+    get approvals() {
+        return !!this.options.approve;
+    }
+    /**
+     * Live-update runnable settings so the next `run`/`compact` call honors them without restarting
+     * Alisio. Every patch field is merged over the current options; unrelated settings are kept.
+     */
+    applySettings(patch) {
+        const { compaction, ...rest } = patch;
+        this.options = {
+            ...this.options,
+            ...rest,
+            ...(compaction ? { compaction: { ...this.options.compaction, ...compaction } } : {}),
+        };
+    }
+    emitter(sessionId) {
+        const runId = crypto.randomUUID();
+        let seq = 0;
+        return (type, data) => {
+            const event = {
+                schemaVersion: 1,
+                runId,
+                sessionId,
+                seq: ++seq,
+                type,
+                timestamp: new Date().toISOString(),
+                data,
+            };
+            if (type !== "text_delta" && type !== "tool_progress" && type !== "reasoning_delta")
+                this.options.store.event(sessionId, runId, type, data);
+            try {
+                this.options.onEvent?.(event);
+            }
+            catch {
+                /* An observer cannot invalidate an executed operation. */
+            }
+        };
+    }
+    /** Tools offered to the model under the current policy (and optional run narrowing). */
+    availableTools(run = {}) {
+        const o = this.options;
+        const policy = run.policy ?? o.policy;
+        const approvals = !!o.approve && run.approvals !== false;
+        return o.registry.list().filter((t) => {
+            if (run.toolFilter && !run.toolFilter(t))
+                return false;
+            const effect = t.effect ?? "external";
+            if (allowed(policy, effect))
+                return true;
+            return approvals && (effect === "write" || effect === "process" || effect === "external");
+        });
+    }
+    /** Abort signal of the session's active run, if any (used to cascade cancellation). */
+    signal(sessionId) {
+        return this.active.get(sessionId)?.signal;
+    }
+    isRunning(sessionId) {
+        return this.active.has(sessionId);
+    }
+    /** Aborts the active run (or compaction) of a session. */
+    abort(sessionId, reason = new Error("Cancelled")) {
+        const controller = this.active.get(sessionId);
+        if (!controller)
+            return false;
+        controller.abort(reason);
+        return true;
+    }
+    /** Queues text as a user message for the session's next turn (or next run when idle). */
+    enqueue(sessionId, text) {
+        const queue = this.inbox.get(sessionId) ?? [];
+        queue.push(text.slice(0, 50_000));
+        this.inbox.set(sessionId, queue.slice(-20));
+    }
+    drain(sessionId) {
+        const queue = this.inbox.get(sessionId) ?? [];
+        this.inbox.delete(sessionId);
+        return queue;
+    }
+    claim(sessionId) {
+        if (this.active.has(sessionId))
+            throw new Error("Session is busy; await the current run or cancel it");
+        const controller = new AbortController();
+        this.active.set(sessionId, controller);
+        return controller;
+    }
+    toolsText(tools) {
+        return JSON.stringify(tools.map((t) => ({ name: t.name, schema: t.inputSchema, description: t.description })));
+    }
+    /** Estimated tokens the next request of a session would send. */
+    async estimateContext(sessionId) {
+        const instructions = await this.options.context.instructions(sessionId);
+        return (estimateTokens(instructions) +
+            estimateTokens(this.options.store.messages(sessionId)) +
+            estimateTokens(this.toolsText(this.availableTools())));
+    }
+    /**
+     * The effective context budget the TUI context bar displays. The model window is the total
+     * when known (and not beyond `MAX_TRUSTED_WINDOW`); otherwise the bar reports an honest
+     * unknown (`basis: "unknown"`, no fabricated total). `compactionAt` is the percentage of
+     * `total` where auto-compaction triggers, so the bar turns red exactly where the engine
+     * compacts. The engine's own auto-compaction guardrail still falls back to the char budget
+     * internally (see `shouldCompactContext`) — that fallback is never shown as a fake total.
+     */
+    contextBudget(model) {
+        const window = this.options.contextWindow?.(model);
+        if (window !== undefined && window > 0 && window <= MAX_TRUSTED_WINDOW)
+            return {
+                total: window,
+                basis: "window",
+                compactionAt: Math.round((this.options.compaction?.threshold ?? 0.85) * 100),
+            };
+        return { total: undefined, basis: "unknown", compactionAt: 100 };
+    }
+    /** Change the model used by subsequent turns of a session; recorded in the store. */
+    setModel(sessionId, model) {
+        const id = model.trim();
+        if (!id)
+            throw new Error("Model ID must not be empty");
+        const previous = this.options.store.get(sessionId).model;
+        if (previous === id)
+            return;
+        this.options.store.setModel(sessionId, id);
+        this.reported.delete(sessionId);
+        this.emitter(sessionId)("model_changed", { model: id, previous });
+    }
+    /** Manually compact a session outside a run. */
+    async compact(sessionId, request = {}) {
+        const controller = this.claim(sessionId);
+        const o = this.options;
+        let acquired = false;
+        const timeout = AbortSignal.timeout(o.timeoutMs ?? 300_000);
+        const signal = AbortSignal.any([
+            controller.signal,
+            timeout,
+            ...(request.signal ? [request.signal] : []),
+        ]);
+        try {
+            o.store.acquire(sessionId);
+            acquired = true;
+            o.store.reconcile(sessionId);
+            const session = o.store.get(sessionId);
+            return await this.compactLocked(sessionId, this.emitter(sessionId), session.model, signal, "manual", request.focus);
+        }
+        finally {
+            if (acquired)
+                o.store.release(sessionId);
+            this.active.delete(sessionId);
+        }
+    }
+    async compactLocked(sessionId, emit, model, signal, reason, focus) {
+        const o = this.options;
+        const messages = o.store.messages(sessionId);
+        const plan = planCompaction(messages, { keepTurns: o.compaction?.keepTurns ?? 2 });
+        const before = await this.estimateContext(sessionId);
+        if (!plan) {
+            emit("compaction_skipped", { reason, before, detail: "Not enough history to compact" });
+            return undefined;
+        }
+        emit("compaction_started", { reason, before, messages: plan.summarized.length });
+        const reportFailures = (failures) => {
+            for (const f of failures)
+                emit("plugin_hook_failed", { ...f, continued: true });
+        };
+        try {
+            const ext = o.extensions;
+            const hookInput = { sessionId, reason, messages: plan.summarized, focus };
+            let contribution = {
+                instructions: [],
+                fields: {},
+                failures: [],
+            };
+            if (ext)
+                try {
+                    contribution = await ext.beforeCompact(hookInput);
+                }
+                catch (error) {
+                    contribution.failures.push({
+                        source: "host",
+                        hook: "beforeCompact",
+                        error: String(error),
+                    });
+                }
+            reportFailures(contribution.failures);
+            const fields = Object.fromEntries(Object.entries(contribution.fields).map(([name, f]) => [name, f.description]));
+            const provider = await (o.providerFor?.(o.store.get(sessionId)) ?? o.provider);
+            const { text: raw, truncated: summaryTruncated } = await summarize(provider, {
+                instructions: checkpointInstructions(contribution.instructions, fields),
+                messages: plan.summarized,
+                focus,
+                model,
+                maxOutputTokens: o.compaction?.maxOutputTokens ?? 4096,
+                signal,
+                sessionId,
+            });
+            const output = parseCheckpointOutput(raw, Object.keys(fields));
+            let after = {
+                inject: [],
+                reports: {},
+                failures: [],
+            };
+            if (ext)
+                try {
+                    after = await ext.afterCompact({
+                        ...hookInput,
+                        model,
+                        replaced: plan.cut,
+                        structured: output.structured,
+                        ...(output.checkpoint ? { checkpoint: output.checkpoint } : {}),
+                        checkpointText: output.text,
+                        extracted: output.extracted,
+                    });
+                }
+                catch (error) {
+                    after.failures.push({ source: "host", hook: "afterCompact", error: String(error) });
+                }
+            reportFailures(after.failures);
+            const body = [output.text, ...after.inject.map((x) => x.slice(0, MAX_INJECT_CHARS))]
+                .filter((x) => x.trim())
+                .join("\n\n");
+            const summary = summaryMessage(body, plan.cut);
+            o.store.compact(sessionId, plan.cut, summary);
+            this.reported.delete(sessionId);
+            const afterTokens = await this.estimateContext(sessionId);
+            emit("compaction_completed", {
+                reason,
+                before,
+                after: afterTokens,
+                replaced: plan.cut,
+                structured: output.structured,
+                summarizedTokens: estimateTokens(plan.summarized),
+                checkpointTokens: estimateTokens(summary.text),
+                plugins: after.reports,
+                ...(summaryTruncated ? { partial: true } : {}),
+            });
+            return { replaced: plan.cut, before, after: afterTokens, summary };
+        }
+        catch (error) {
+            emit("compaction_failed", {
+                reason,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            throw error;
+        }
+    }
+    async run(sessionId, prompt, signal, options = {}) {
+        const controller = this.claim(sessionId);
+        const o = this.options, emit = this.emitter(sessionId);
+        const limit = o.maxContextChars ?? 800_000;
+        let tokens = 0, lastText = "", acquired = false;
+        const usageTotal = { input: 0, output: 0 };
+        const timeout = AbortSignal.timeout(options.timeoutMs ?? o.timeoutMs ?? 300_000);
+        const combined = AbortSignal.any([controller.signal, timeout, ...(signal ? [signal] : [])]);
+        const context = options.context ?? o.context;
+        const workspace = options.workspace ?? o.workspace;
+        const policy = options.policy ?? o.policy;
+        const approvals = !!o.approve && options.approvals !== false;
+        const withPersona = async () => {
+            const base = await context.instructions(sessionId);
+            return options.instructions ? `${base}\n\n${options.instructions}` : base;
+        };
+        try {
+            o.store.acquire(sessionId);
+            acquired = true;
+            o.store.reconcile(sessionId);
+            const session = o.store.get(sessionId);
+            const provider = await (o.providerFor?.(session) ?? o.provider);
+            if (session.provider !== provider.id || session.workspace !== workspace)
+                throw new Error("Session provider/workspace mismatch");
+            // The session records the model; switching models is explicit via setModel.
+            const model = session.model;
+            combined.throwIfAborted();
+            if (o.extensions && o.store.messages(sessionId).length === 0) {
+                // New session: extensions may inject budgeted context once, persisted with the session.
+                try {
+                    const start = await o.extensions.sessionStart({
+                        sessionId,
+                        model,
+                        workspace,
+                    });
+                    for (const f of start.failures)
+                        emit("plugin_hook_failed", { ...f, continued: true });
+                    const text = start.inject
+                        .map((x) => x.text.slice(0, MAX_INJECT_CHARS))
+                        .filter((x) => x.trim())
+                        .join("\n\n");
+                    if (text) {
+                        o.store.append(sessionId, { role: "user", text, summary: true });
+                        emit("session_context_injected", {
+                            tokens: estimateTokens(text),
+                            sources: start.inject.map((x) => x.source),
+                        });
+                    }
+                }
+                catch (error) {
+                    emit("plugin_hook_failed", {
+                        source: "host",
+                        hook: "sessionStart",
+                        error: String(error),
+                        continued: true,
+                    });
+                }
+                combined.throwIfAborted();
+            }
+            for (const queued of this.drain(sessionId))
+                o.store.append(sessionId, { role: "user", text: queued });
+            o.store.append(sessionId, {
+                role: "user",
+                text: prompt,
+                ...(options.display ? { display: options.display } : {}),
+                ...(options.attachments?.length ? { attachments: options.attachments } : {}),
+            });
+            emit("run_started", { model });
+            const budget = options.maxTokens ?? o.maxTokens ?? defaultTokenBudget(o.contextWindow?.(model));
+            const compaction = o.compaction ?? {};
+            for (let turn = 0; turn < (options.maxTurns ?? o.maxTurns ?? 20); turn++) {
+                combined.throwIfAborted();
+                // Input queued while the run was working (e.g. a parent's message to a child).
+                if (turn > 0)
+                    for (const queued of this.drain(sessionId))
+                        o.store.append(sessionId, { role: "user", text: queued });
+                let instructions = await withPersona();
+                let messages = o.store.messages(sessionId);
+                const tools = this.availableTools(options);
+                const toolsText = this.toolsText(tools);
+                const chars = () => instructions.length + JSON.stringify(messages).length + toolsText.length;
+                // REDUCIBLE content only (instructions + transcript). The fixed tool catalog
+                // (`toolsText`) is a deployment reality — a huge MCP catalog with dozens of tools is
+                // part of every request regardless of history, so it is deliberately excluded from the
+                // post-compaction hard cap: counting it would reduce a small transcript to near-nothing
+                // and still fake-fail. Oversized catalogs are a `/plugins` decision, not session growth;
+                // auto-compaction above still measures the FULL request (`chars()`), because window
+                // thresholds protect what the model really sees, tools included.
+                const charsConversation = () => instructions.length + JSON.stringify(messages).length;
+                const used = () => {
+                    const last = this.reported.get(sessionId);
+                    return last && last.count <= messages.length
+                        ? last.tokens + estimateTokens(messages.slice(last.count))
+                        : estimateTokens(instructions) + estimateTokens(messages) + estimateTokens(toolsText);
+                };
+                // One effective budget: a known window triggers at `used >= window * threshold`; an
+                // unknown (or absurdly large, see MAX_TRUSTED_WINDOW) window falls back to the char
+                // estimate (`chars / 4 >= maxContextChars / 4`). `maxContextChars` below stays as the
+                // post-compaction hard limit.
+                if (compaction.auto !== false &&
+                    shouldCompactContext(used(), chars(), o.contextWindow?.(model), limit, compaction.threshold ?? 0.85)) {
+                    await this.compactLocked(sessionId, emit, model, combined, "auto");
+                    instructions = await withPersona();
+                    messages = o.store.messages(sessionId);
+                }
+                // A compaction that still leaves the session over the hard limit is reduced in place
+                // instead of failing outright: retained content is clipped against a TOTAL character
+                // target for the transcript (`limit − instructions`), largest items first, tool results
+                // before texts, in descending cap rounds. That also covers sessions with many MEDIUM
+                // results (e.g. MCP outputs of a few thousand chars each) that individually stay under
+                // the per-message caps; roles/callIds/boundaries stay untouched, so the transcript
+                // remains valid and replayable. The hard cap measures ONLY reducible content
+                // (`charsConversation`): the fixed tool catalog (see above) never triggers the error on
+                // its own. The reduction is persisted either way, so the session stays usable for later
+                // prompts. Only if even the reduction floor cannot fit (instructions alone crowd out the
+                // limit) the run fails with an actionable error.
+                if (charsConversation() > limit) {
+                    const targetChars = Math.max(MIN_MESSAGE_BUDGET_FLOOR, limit - instructions.length);
+                    const reduction = reduceMessagesToBudget(messages, targetChars);
+                    if (reduction.truncated > 0) {
+                        o.store.overwrite(sessionId, reduction.messages);
+                        messages = reduction.messages;
+                        emit("context_reduced", { messages: reduction.truncated });
+                    }
+                    if (charsConversation() > limit)
+                        throw new Error(`Context budget exceeded and compaction could not reduce it (approximately ${charsConversation()} characters of conversation; limit ${limit}). Run /compact, trim large tool outputs, start a new session, or disable unneeded MCP servers with /plugins.`);
+                }
+                let completion;
+                let truncated = false;
+                let usage;
+                for await (const e of provider.stream({
+                    instructions,
+                    messages,
+                    tools,
+                    maxOutputTokens: options.maxOutputTokens ?? o.maxOutputTokens ?? 4096,
+                    signal: combined,
+                    model,
+                    sessionId,
+                    ...(o.nativeTools?.length ? { nativeTools: o.nativeTools } : {}),
+                })) {
+                    combined.throwIfAborted();
+                    if (e.type === "text_delta")
+                        emit("text_delta", { delta: e.delta });
+                    else if (e.type === "reasoning_delta")
+                        emit("reasoning_delta", { delta: e.delta });
+                    else {
+                        if (completion)
+                            throw new Error("Provider emitted multiple completions");
+                        completion = e.message;
+                        truncated = e.message.truncated === true;
+                        usage = e.usage;
+                        tokens += (e.usage?.input ?? 0) + (e.usage?.output ?? 0);
+                        usageTotal.input += e.usage?.input ?? 0;
+                        usageTotal.output += e.usage?.output ?? 0;
+                    }
+                }
+                if (!completion)
+                    throw new Error("Provider stream ended without a completed response");
+                const ids = completion.calls.map((c) => c.id);
+                const previousIds = new Set(messages.flatMap((m) => (m.role === "assistant" ? m.calls.map((c) => c.id) : [])));
+                if (ids.some((id) => previousIds.has(id)))
+                    throw new Error("Provider reused a tool call ID across turns");
+                if (new Set(ids).size !== ids.length)
+                    throw new Error("Provider returned duplicate tool call IDs");
+                if (completion.calls.length > 64)
+                    throw new Error("Too many tool calls in one turn");
+                o.store.append(sessionId, completion);
+                if (usage)
+                    this.reported.set(sessionId, {
+                        tokens: usage.input + usage.output,
+                        count: messages.length + 1,
+                    });
+                lastText = completion.text;
+                emit("turn_completed", {
+                    turn: turn + 1,
+                    tokens,
+                    calls: completion.calls.length,
+                    model,
+                    ...(usage ? { usage } : {}),
+                });
+                if (!completion.calls.length) {
+                    const final = {
+                        tokens,
+                        text: lastText,
+                    };
+                    if (truncated) {
+                        // The adapter kept a usable answer, but the token budget cut it off.
+                        emit("response_truncated", {
+                            turn: turn + 1,
+                            maxOutputTokens: options.maxOutputTokens ?? o.maxOutputTokens ?? 4096,
+                        });
+                        final.truncated = true;
+                    }
+                    emit("run_completed", final);
+                    return { sessionId, text: lastText, status: "completed", usage: usageTotal };
+                }
+                const prepared = completion.calls.map((call) => {
+                    try {
+                        const tool = o.registry.get(call.name), input = o.registry.parse(call.name, call.arguments);
+                        return { call, tool, input };
+                    }
+                    catch (error) {
+                        return { call, error: String(error) };
+                    }
+                });
+                // Resolve scopes before tools execute. New nested instructions are attached to the first
+                // read result; state-changing calls return to the model for reconsideration instead.
+                let contextUpdate;
+                const paths = prepared.flatMap((p) => p.tool?.paths?.(p.input ?? {}) ?? []);
+                if (paths.length)
+                    contextUpdate = await context.beforePaths(paths, sessionId);
+                let pendingUpdate = contextUpdate;
+                const execute = async (p) => {
+                    const { call } = p;
+                    let result;
+                    const started = Date.now();
+                    emit("tool_started", { name: call.name, id: call.id, arguments: call.arguments });
+                    try {
+                        combined.throwIfAborted();
+                        if (p.error)
+                            throw new Error(p.error);
+                        if (!p.tool || !p.input)
+                            throw new Error("Invalid tool");
+                        const effect = p.tool.effect ?? "external";
+                        if (contextUpdate && effect !== "read")
+                            throw new Error(`Context changed; reconsider this call before retrying.\n${contextUpdate}`);
+                        if (tokens >= budget)
+                            throw new Error("Token budget exhausted; tool was not executed");
+                        if (options.toolFilter && !options.toolFilter(p.tool))
+                            throw new Error(`Tool ${call.name} is not available in this session`);
+                        if (!allowed(policy, effect)) {
+                            if (!o.approve ||
+                                !approvals ||
+                                (effect !== "write" && effect !== "process" && effect !== "external"))
+                                throw new Error(`Capability denied: ${effect}`);
+                            emit("approval_requested", {
+                                id: call.id,
+                                name: call.name,
+                                effect,
+                                ...(options.label ? { label: options.label } : {}),
+                            });
+                            const decision = await o.approve({
+                                call,
+                                effect,
+                                input: p.input,
+                                signal: combined,
+                                session: sessionId,
+                                ...(options.label ? { label: options.label } : {}),
+                            });
+                            combined.throwIfAborted();
+                            emit("approval_resolved", { id: call.id, name: call.name, effect, decision });
+                            if (decision === "deny")
+                                throw new Error(`Capability ${effect} denied by the user for this call`);
+                            if (decision === "session")
+                                policy[effect] = true;
+                        }
+                        o.store.beginCall(sessionId, call);
+                        result = await p.tool.execute(p.input, {
+                            signal: combined,
+                            workspace,
+                            session: sessionId,
+                            emit: (data) => emit("tool_progress", { id: call.id, data }),
+                            ...(options.label ? { label: options.label } : {}),
+                        });
+                        if (JSON.stringify(result).length > 48_000)
+                            result = textResult(`${JSON.stringify(result).slice(0, 40_000)}\n[tool output truncated]`, result.isError);
+                        if (pendingUpdate && effect === "read") {
+                            result = {
+                                ...result,
+                                content: [
+                                    ...result.content,
+                                    { type: "text", text: `\n<instructions>\n${pendingUpdate}\n</instructions>` },
+                                ],
+                            };
+                            pendingUpdate = undefined;
+                        }
+                        o.store.endCall(sessionId, call, result);
+                    }
+                    catch (error) {
+                        result = textResult(error instanceof Error ? error.message : String(error), true);
+                        // A cancellation after execution may have left effects; journal remains pending.
+                        if (!combined.aborted)
+                            o.store.endCall(sessionId, call, result);
+                    }
+                    emit("tool_completed", {
+                        id: call.id,
+                        name: call.name,
+                        isError: result.isError ?? false,
+                        durationMs: Date.now() - started,
+                        preview: result.content
+                            .map((c) => c.text)
+                            .join("\n")
+                            .slice(0, 2_000),
+                    });
+                    return result;
+                };
+                const results = [];
+                // Bounded parallel batches for consecutive read or explicitly concurrent tools.
+                const parallel = (p) => !!p?.tool && (p.tool.effect === "read" || p.tool.concurrent === true);
+                for (let i = 0; i < prepared.length;) {
+                    const current = prepared[i];
+                    if (!current)
+                        break;
+                    if (parallel(current)) {
+                        const batch = [];
+                        while (i < prepared.length &&
+                            parallel(prepared[i]) &&
+                            batch.length < (o.readConcurrency ?? 4)) {
+                            const p = prepared[i++];
+                            if (p)
+                                batch.push(p);
+                        }
+                        results.push(...(await Promise.all(batch.map(execute))));
+                    }
+                    else {
+                        results.push(await execute(current));
+                        i++;
+                    }
+                    combined.throwIfAborted();
+                }
+                for (let i = 0; i < completion.calls.length; i++) {
+                    const c = completion.calls[i], r = results[i];
+                    if (c && r)
+                        o.store.append(sessionId, { role: "tool", callId: c.id, result: r });
+                }
+                if (tokens >= budget)
+                    throw new Error("Token budget exhausted");
+            }
+            throw new Error("Maximum turns reached");
+        }
+        catch (error) {
+            // On cancellation report the abort reason, not the transport's secondary error.
+            const cause = combined.aborted ? (combined.reason ?? error) : error;
+            emit(combined.aborted ? "run_cancelled" : "run_failed", {
+                error: cause instanceof Error ? cause.message : String(cause),
+            });
+            throw error;
+        }
+        finally {
+            if (acquired)
+                o.store.release(sessionId);
+            this.active.delete(sessionId);
+        }
+    }
+}

package/dist/extensions/registry.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Generic, typed extension registry. Resolution is deterministic and independent of plugin
+ * load order: highest priority, then plugin id (lexicographic), then registration order
+ * within the plugin. Fallbacks (built-in defaults) only win when nothing else is registered.
+ */
+import type { ExtensionPoints } from "@alisio/sdk";
+export interface ExtensionConflict {
+    point: string;
+    /** `plugin/provider` of the chosen provider. */
+    winner: string;
+    losers: string[];
+}
+export declare class ExtensionRegistry {
+    private entries;
+    private seq;
+    register<K extends keyof ExtensionPoints>(point: K, provider: ExtensionPoints[K], options: {
+        plugin: string;
+        priority?: number;
+        fallback?: boolean;
+    }): () => void;
+    private ranked;
+    resolve<K extends keyof ExtensionPoints>(point: K): {
+        provider: ExtensionPoints[K];
+        plugin: string;
+    } | undefined;
+    /** Equal-priority, non-fallback competitors for each point's winning slot. */
+    conflicts(point?: keyof ExtensionPoints): ExtensionConflict[];
+}