@skanl/brambo-session 0.1.1

package/dist/run-session.js

@@ -0,0 +1,523 @@
+import { createExecutorPlugin, EXECUTOR_CONFIG_KEY, EXECUTOR_SERVICE } from '@skanl/brambo-adapter-cli';
+import { BramboError, BRAMBO_ERROR_CODES, validateSandboxCapabilities, validateSandboxPolicy, validateToolExecutionContext, validateToolInvocation, } from '@skanl/brambo-contracts';
+import { createKernel, createMemoryLogSink, deepMerge, } from '@skanl/brambo-kernel';
+import { WORKSPACE_CONFIG_KEY, WORKSPACE_CONFIG_WARNING_EVENT, WORKSPACE_SERVICE, } from '@skanl/brambo-workspace-local';
+import { seedExecutorConfig, selectExecutor, } from './executors.js';
+import { DEFAULT_WORKSPACE_PROVIDER_ID, WORKSPACE_PROVIDER_CONFIG_KEY, createSelectedWorkspacePlugin, selectWorkspaceProvider, worktreeStateDir, } from './workspaces.js';
+import { assertMethodMayMount, resolveMethod, selectMethod, swapMethod } from './methods.js';
+/**
+ * The PREFIX every session invocation is recorded under. The registered id is
+ * `${SESSION_ACTION_ID}#${workspace.id}`, not this constant: a pipeline rejects a
+ * duplicate registration, and since Story M3.B the pipeline belongs to the
+ * KERNEL rather than to the session, so two sessions sharing one kernel really
+ * do register into the same set of ids. Scoping to the workspace is what keeps
+ * them distinguishable — and workspace ids are UUIDs on the default provider.
+ *
+ * Exported because a reader of the record stream needs the same string the
+ * pipeline wrote; match with `subject.startsWith(SESSION_ACTION_ID + '#')`.
+ */
+export const SESSION_ACTION_ID = 'session.executor-run';
+/**
+ * What one executor run is ADMITTED at, before the vendor says what it spent.
+ *
+ * The upgrade path the previous note named is now built. Story M3.C gave the
+ * pipeline settlement — an action is admitted on this estimate and reconciled
+ * against the executor's own reported usage when the run resolves — so within a
+ * single session `maxTotalCost` and `maxInvocations` finally refuse on DIFFERENT
+ * runs: one run of claude-code settles at tens of thousands of tokens, so a cost
+ * cap fires while the invocation count is still 1, and an invocation cap fires
+ * while the settled cost is far under its own limit.
+ *
+ * ponytail: this stays a flat 1 on purpose, and it is the last piece of the old
+ * collapse still standing. Brambo may not invent a pre-run token figure — no
+ * estimating, no tokenizer, that is the whole point of settling instead — and
+ * raising it to a token-scale placeholder would silently redefine every cap
+ * already written against "1 = one run". A host that budgets in tokens builds
+ * its own kernel (`createSessionKernel`) and can pass its own estimate through
+ * `createExecutorPlugin({ cost })`; the settlement corrects it either way. What
+ * remains open: a run whose vendor reports nothing is charged this 1, so a
+ * session against such an executor is still capped by count rather than by
+ * spend (deferred-work.md).
+ */
+export const SESSION_ACTION_COST = 1;
+function sameToolPolicy(left, right) {
+    const canonical = (value) => {
+        if (value === undefined)
+            return '';
+        if (value === null || typeof value !== 'object')
+            return JSON.stringify(value);
+        if (Array.isArray(value))
+            return `[${value.map(canonical).join(',')}]`;
+        return `{${Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, item]) => `${JSON.stringify(key)}:${canonical(item)}`).join(',')}}`;
+    };
+    return left.version === right.version
+        && left.mode === right.mode
+        && left.workspaceRoot === right.workspaceRoot
+        && left.allowDangerous === right.allowDangerous
+        && canonical(left.requiredCapabilities) === canonical(right.requiredCapabilities)
+        && canonical(left.resourceLimits) === canonical(right.resourceLimits);
+}
+/**
+ * Executes one validated tool through the supplied ToolExecutor.
+ *
+ * This is deliberately separate from `runSession`: executor runs are vendor
+ * sessions, while tool calls are host-controlled SDK operations. The helper
+ * makes the approval boundary executable without teaching the kernel about
+ * tools, processes, filesystems, or sandbox backends.
+ */
+export async function executeTool(options) {
+    const invocation = validateToolInvocation(options.invocation);
+    const context = validateToolExecutionContext(options.context);
+    const executor = options.toolExecutor;
+    if (executor === undefined) {
+        throw new BramboError(BRAMBO_ERROR_CODES.sandboxUnavailable, 'tool execution requires a ToolExecutor');
+    }
+    if (options.toolPolicy !== undefined) {
+        const policy = validateSandboxPolicy(options.toolPolicy);
+        if (!sameToolPolicy(policy, context.policy)) {
+            throw new BramboError(BRAMBO_ERROR_CODES.sandboxRequestInvalid, 'tool policy does not match execution context');
+        }
+    }
+    if (options.sandboxProvider !== undefined) {
+        validateSandboxCapabilities(context.policy, options.sandboxProvider.capabilities);
+    }
+    if (options.approveTool !== undefined && !(await options.approveTool({ invocation, context }))) {
+        throw new BramboError(BRAMBO_ERROR_CODES.sandboxDenied, 'tool invocation was denied by the host');
+    }
+    const result = await executor.execute(invocation, context);
+    options.onToolExecution?.({ invocation, context, result });
+    return result;
+}
+/**
+ * Options that only mean something for a kernel this session builds itself.
+ *
+ * `cwd` and `onSelection` joined the list on review: both were accepted and
+ * silently ignored beside a supplied kernel (`onSelection` calls measured at 0),
+ * which is the exact behaviour the refusal rule above exists to forbid.
+ */
+const KERNEL_OWNED_OPTIONS = [
+    'configLayers',
+    'cwd',
+    'executorId',
+    'adapterOptions',
+    'createAdapter',
+    'createProvider',
+    'onSelection',
+    'log',
+    'actionPolicy',
+];
+async function contained(action) {
+    try {
+        await action();
+    }
+    catch {
+        // Cleanup must never mask the primary envelope/error or crash the exit path.
+    }
+}
+/**
+ * Validate only the policy/capability relationship that is knowable without a
+ * tool invocation. Provider selection, session creation and execution remain
+ * absent until the session receives a tool call to route.
+ */
+function validateToolComposition(options) {
+    const { sandboxProvider, toolPolicy } = options;
+    if (toolPolicy === undefined)
+        return;
+    const policy = validateSandboxPolicy(toolPolicy);
+    if (sandboxProvider === undefined)
+        return;
+    const providerId = sandboxProvider.id;
+    const capabilities = validateSandboxCapabilities(policy, sandboxProvider.capabilities);
+    if (providerId !== capabilities.providerId) {
+        throw new BramboError(BRAMBO_ERROR_CODES.sandboxCapabilityUnavailable, `sandbox provider id '${providerId}' does not match its capability facts '${capabilities.providerId}'`);
+    }
+}
+/**
+ * The sink a session-owned kernel records into.
+ *
+ * `SessionOptions.log` is documented — and pinned by three suites — as the
+ * WATERFALL's sink, and the kernel's stream carries lifecycle transitions too.
+ * Forwarding the whole stream would redefine a published option; forwarding
+ * nothing would delete the trail. So the caller's sink receives exactly the
+ * waterfall, the kernel keeps its complete stream, and a caller who wants the
+ * complete one supplies the kernel instead.
+ */
+function waterfallSink(caller) {
+    const own = createMemoryLogSink();
+    if (caller === undefined)
+        return own;
+    return {
+        record(entry) {
+            own.record(entry);
+            if (entry.event.startsWith('action.'))
+                caller.record(entry);
+        },
+        async drain() {
+            await own.drain();
+            await caller.drain();
+        },
+        get state() {
+            return caller.state;
+        },
+    };
+}
+function serviceMissing(service, detail) {
+    // AD-5: a consumed service that never activated reads as `{ kind: 'absent' }`
+    // and its USE SITE raises a named, coded error. `undefined` reaching a call
+    // site is the failure the typed-absent value exists to make impossible, and a
+    // bare "cannot read property of undefined" names neither the service nor the
+    // plugin that owed it.
+    return new BramboError(BRAMBO_ERROR_CODES.kernelServiceNotProvided, `brambo's kernel provides no '${service}' service: ${detail}`);
+}
+/** What a contained start failure has to say for itself, plugin by plugin. */
+function describeFailures(failures) {
+    return failures.map((failure) => `${failure.pluginId}: ${failure.error.message}`).join('; ');
+}
+/**
+ * A kernel with brambo's two plugins mounted, its configuration seeded from
+ * brambo's own documents, and its plugins started.
+ *
+ * This is the ONE composition. `runSession` calls it when no kernel is passed,
+ * and a host that wants several sessions to share one pipeline, one budget and
+ * one record stream calls it directly and passes the result as
+ * `SessionOptions.kernel`.
+ *
+ * It exists as a single named surface on purpose. `@skanl/brambo-session` briefly
+ * re-exported `createKernel` and both plugin FACTORIES so a host could assemble
+ * this itself, and that was a hole rather than a convenience: a `PluginFactory`
+ * invoked with an `ActivationContext` of the caller's own construction hands
+ * back a real vendor adapter wired to the caller's own pipeline, so the bypass
+ * surface of a session-only consumer went from nothing to one. Handing back a
+ * started kernel gives a host the capability without the factory.
+ *
+ * Throws before anything is constructed for a selection brambo has no adapter
+ * for, and stops the kernel again if any plugin fails to activate.
+ */
+export function createSessionKernel(options = {}) {
+    const { cwd, executorId, configLayers, adapterOptions, createAdapter, log, actionPolicy, onSelection, onWarning, } = options;
+    validateToolComposition(options);
+    // The KERNEL's sink, unfiltered: a host that builds its own kernel is exactly
+    // the caller who wants the lifecycle transitions too, and it is where the AD-4
+    // ordering proof reads its stream. `runSession` hands this a sink already
+    // narrowed to the waterfall, because `SessionOptions.log` means that and is
+    // pinned to it by three suites.
+    const kernel = createKernel({ log, actionPolicy });
+    try {
+        // Subscribed BEFORE anything activates: a plugin emits its configuration
+        // warnings during activation, synchronously, and a listener attached after
+        // `start()` would receive none of them.
+        if (onWarning !== undefined) {
+            kernel.bus.subscribe('global', (event) => {
+                if (event.type !== WORKSPACE_CONFIG_WARNING_EVENT)
+                    return;
+                onWarning(`configuration ignored: '${event.payload.key}' ${event.payload.detail}`);
+            });
+        }
+        // ONE layered configuration, and it is the kernel's: executor selection and
+        // every mounted plugin read the same composed document, by layer. The
+        // session's own workspace root enters as a LAYER rather than as a plugin
+        // option — `invocation` when the caller named a cwd, `defaults` when it did
+        // not — so a `workspace.rootDir` in the project document decides in exactly
+        // the case a layered configuration says it should.
+        const projectRoot = cwd ?? process.cwd();
+        const workspaceRoot = { [WORKSPACE_CONFIG_KEY]: { rootDir: worktreeStateDir(projectRoot) } };
+        // Brambo's built-in workspace provider is a LAYER too, and the same layer the
+        // executor's default lives in — which is what makes "nothing configured" a
+        // reportable provenance (`defaults`) rather than an invisible branch, and
+        // what lets `selectWorkspaceProvider` take value and layer from one entry.
+        // Composed OVER a caller's `defaults` exactly as `seedExecutorConfig` does
+        // with the executor default: a caller that wants another provider says so in
+        // a narrower layer.
+        const workspaceProvider = {
+            [WORKSPACE_CONFIG_KEY]: { [WORKSPACE_PROVIDER_CONFIG_KEY]: DEFAULT_WORKSPACE_PROVIDER_ID },
+        };
+        let invocation = { ...configLayers?.invocation };
+        if (executorId !== undefined)
+            invocation[EXECUTOR_CONFIG_KEY] = executorId.trim();
+        // `deepMerge`, not `Object.assign`. The assign is SHALLOW, so it replaced the
+        // caller's whole `workspace` subtree with brambo's `{ rootDir }` — invisible
+        // while the subtree had one key, and a silently dropped `workspace.provider`
+        // the moment it had two: a host naming both a `cwd` and a provider in the
+        // narrowest layer would have run in a workspace it did not ask for. `rootDir`
+        // still wins, because a named `cwd` is this invocation's answer.
+        if (cwd !== undefined)
+            invocation = deepMerge(invocation, workspaceRoot);
+        const declined = seedExecutorConfig(kernel.config, {
+            ...configLayers,
+            defaults: deepMerge((cwd === undefined ? workspaceRoot : configLayers?.defaults) ?? {}, workspaceProvider),
+            ...(Object.keys(invocation).length === 0 ? {} : { invocation }),
+        });
+        // A METHOD THE PROJECT RECOMMENDED AND BRAMBO DID NOT ADMIT, said out loud on
+        // the channel that already exists for exactly this. Its own comment at the
+        // CLI end settled the question this reuses: "A configuration key brambo read
+        // and could not use. Reported, never fatal: one forward-looking key in
+        // `~/.brambo/config.json` used to fail every run on the machine, and silence
+        // would have been the other wrong answer."
+        //
+        // NOT on the bus. `WORKSPACE_CONFIG_WARNING_EVENT` is spelled
+        // `workspace.config.ignored` and is declared twice, once in each workspace
+        // plugin; routing a METHOD through it would smear that vocabulary across a
+        // key no workspace owns, which is the divergence correction-01 exists to
+        // remove. `onWarning` is the seam; the bus is one plugin's way of reaching it.
+        if (onWarning !== undefined && declined !== undefined) {
+            onWarning(`configuration ignored: '${declined.key}' — '${declined.specifier}' in '${declined.filePath}' is a recommendation, not a selection: brambo never mounts a method a project directory names, because running it is running that project's code. ${declined.using === undefined
+                ? 'Running with no method.'
+                : `Using '${declined.using}' instead.`} To adopt it on this machine, run \`brambo swap method ${declined.specifier}\` from that directory`);
+        }
+        // Resolved BEFORE anything is constructed, beside the prompt check and for
+        // the same reason: an invalid request must cost no mkdir. An `executorId`
+        // the catalogue does not hold used to be rejected AFTER `provider.create()`,
+        // leaving a workspace directory on disk that nothing removes.
+        const selection = selectExecutor(kernel.config);
+        if (onSelection !== undefined) {
+            try {
+                onSelection(selection);
+            }
+            catch {
+                // A reporter is an observer; an observer must not fail the run.
+            }
+        }
+        const executor = createExecutorPlugin({ createAdapter, adapterOptions, cost: SESSION_ACTION_COST });
+        // The MOUNT. Selected from the same composed document the executor was
+        // selected from, one entry, value and layer together — so the plugin that
+        // gets registered and the provider the document names cannot diverge. The
+        // package is otherwise unreachable from the product: this line is the whole
+        // of Story 4.2's reachability claim, and `packages/session/test/guard.test.ts`
+        // is red until it exists.
+        const workspace = createSelectedWorkspacePlugin(selectWorkspaceProvider(kernel.config).providerId, {
+            repoPath: projectRoot,
+        });
+        kernel.register(executor.manifest, executor.factory);
+        kernel.register(workspace.manifest, workspace.factory);
+        const started = kernel.start();
+        if (started.failures.length > 0) {
+            // Contained by the kernel — every OTHER plugin still activated — and
+            // surfaced here, naming each plugin that failed. Swallowing it would let a
+            // `{ kind: 'absent' }` reach a use site with no explanation of why.
+            throw new BramboError(BRAMBO_ERROR_CODES.kernelPluginStartFailed, `brambo's kernel could not activate every plugin this session needs (${describeFailures(started.failures)})`);
+        }
+        return kernel;
+    }
+    catch (error) {
+        // The one place a constructed kernel could have been abandoned. Nothing has
+        // activated on most of these paths, so nothing leaks — but "most" is not a
+        // guarantee, and `stop()` is idempotent.
+        void kernel.stop().catch(() => { });
+        throw error;
+    }
+}
+/**
+ * One brambo session: compose through a kernel, create a workspace, run the
+ * prompt under a cancellation signal through the kernel's interception
+ * waterfall, then release and dispose whatever happened.
+ *
+ * This is the composition `brambo run` performs, and it lives here rather than in
+ * `@skanl/brambo-cli` so a third party gets it by importing packages (PRD §2, ROADMAP-01
+ * Correction A). The CLI adds argv parsing, JSON formatting and exit codes on top
+ * and nothing else.
+ *
+ * Since Story M3.B the adapter and the provider are MOUNTED, not constructed:
+ * `createExecutorPlugin` and `createWorkspacePlugin` are registered on a kernel,
+ * their configuration comes from one composed document, and their services are
+ * consumed by name. What that buys beyond hygiene: the executor invocation is an
+ * action on the KERNEL's pipeline, so a host that shares one kernel across
+ * sessions shares one budget — and the observability log exists before any
+ * plugin loads, which `loadPlugins`' required sink parameter makes a type error
+ * to violate rather than a comment.
+ *
+ * The honest scope of the no-bypass claim: neither the kernel nor the `executor`
+ * service exports a path around the waterfall. Any package may still import
+ * `@skanl/brambo-adapter-cli` and drive a vendor adapter itself, and a caller that keeps
+ * a reference to the adapter it passed to `createAdapter` can invoke it after a
+ * refusal. Both are recorded as open in deferred-work.md.
+ *
+ * SIDE EFFECT: the mounted provider creates a directory per session under
+ * `<cwd>/.brambo/workspaces/<uuid>` and NOTHING removes it. `release()` ends a
+ * lease and `dispose()` deliberately leaves the tree in place so work survives —
+ * retention is the caller's problem (deferred-work.md).
+ *
+ * Failure surfaces as a throw (a coded `BramboError` from the workspace port or
+ * from a plugin that never activated, a coded `BramboKernelError` from a refusal,
+ * or whatever the adapter threw), because an envelope is what an executor RAN
+ * produces — returning a synthetic one for a workspace that never existed would
+ * make the two indistinguishable.
+ */
+export async function runSession(options) {
+    // Every field read ONCE, here, before the first await. `provider.create()` hands
+    // control back to the caller's event loop, so a live read afterwards is a TOCTOU
+    // hole: an accessor answering a benign prompt now and a hostile one later gets
+    // the hostile one executed. The kernel closes exactly this hole at `register`
+    // and says so; a session that read `options.prompt` inside the operation closure
+    // would hand it straight back.
+    const { prompt, cwd, executorId, configLayers, adapterOptions, createAdapter, createProvider, onInterrupt, onSelection, onWarning, log, actionPolicy, kernel: suppliedKernel, sandboxProvider, toolExecutor, toolPolicy, approveTool, onToolExecution, onSandboxEvent, } = options;
+    // Before anything is constructed or written: an invalid request must cost no
+    // mkdir. The predicate, the code and the message are the contracts package's
+    // own (`runRequestIssues` + `throwSchemaViolation`), so this rejects exactly
+    // what the adapter would have rejected — earlier, not differently.
+    if (typeof prompt !== 'string' || prompt.trim().length === 0) {
+        throw new BramboError(BRAMBO_ERROR_CODES.contractEnvelopeInvalid, "schema violation: 'prompt' must be a non-empty string");
+    }
+    const owned = {
+        configLayers,
+        cwd,
+        executorId,
+        adapterOptions,
+        createAdapter,
+        createProvider,
+        onSelection,
+        log,
+        actionPolicy,
+    };
+    if (suppliedKernel !== undefined) {
+        const conflicting = KERNEL_OWNED_OPTIONS.filter((name) => owned[name] !== undefined);
+        if (conflicting.length > 0) {
+            throw new BramboError(BRAMBO_ERROR_CODES.contractEnvelopeInvalid, `schema violation: a supplied 'kernel' owns its configuration, its plugins, its pipeline and its sink, so ${conflicting
+                .map((name) => `'${name}'`)
+                .join(', ')} cannot also be given here`);
+        }
+    }
+    // A caller-owned kernel bypasses `createSessionKernel`, so the composition
+    // boundary still validates its policy/provider pairing here. Tool calls are
+    // explicit `executeTool` operations and are not implicit side effects of a
+    // vendor session run.
+    const toolComposition = {
+        ...(sandboxProvider === undefined ? {} : { sandboxProvider }),
+        ...(toolExecutor === undefined ? {} : { toolExecutor }),
+        ...(toolPolicy === undefined ? {} : { toolPolicy }),
+        ...(approveTool === undefined ? {} : { approveTool }),
+        ...(onToolExecution === undefined ? {} : { onToolExecution }),
+        ...(onSandboxEvent === undefined ? {} : { onSandboxEvent }),
+    };
+    if (suppliedKernel !== undefined)
+        validateToolComposition(toolComposition);
+    const kernel = suppliedKernel ??
+        createSessionKernel({
+            cwd,
+            executorId,
+            configLayers,
+            adapterOptions,
+            createAdapter,
+            log: waterfallSink(log),
+            actionPolicy,
+            onSelection,
+            onWarning,
+            ...toolComposition,
+        });
+    const stopKernel = suppliedKernel === undefined ? () => kernel.stop() : undefined;
+    let executor;
+    let provider;
+    let disposeProvider = false;
+    try {
+        const resolved = kernel.getService(EXECUTOR_SERVICE);
+        if (resolved.kind !== 'provided') {
+            throw serviceMissing(EXECUTOR_SERVICE, 'mount an executor plugin (`createExecutorPlugin` from @skanl/brambo-adapter-cli) before running a session on this kernel');
+        }
+        executor = resolved.value;
+        if (createProvider === undefined) {
+            const workspace = kernel.getService(WORKSPACE_SERVICE);
+            if (workspace.kind !== 'provided') {
+                throw serviceMissing(WORKSPACE_SERVICE, 'mount a workspace plugin (`createSessionKernel` mounts one) before running a session on this kernel');
+            }
+            provider = workspace.value;
+        }
+        else {
+            // The seam, and with it the ownership: a provider this session created is
+            // a provider this session disposes. Refused beside a supplied kernel (see
+            // `SessionOptions.kernel`), so this only ever runs for a kernel the
+            // session built and will stop.
+            provider = createProvider();
+            disposeProvider = true;
+        }
+    }
+    catch (error) {
+        if (stopKernel !== undefined)
+            await contained(stopKernel);
+        throw error;
+    }
+    // The selected methodology, mounted for this session (FR-28 / UJ-3).
+    //
+    // Read from the kernel's ALREADY COMPOSED configuration rather than from disk
+    // again, so the method and the executor are decided by one layer resolution
+    // and cannot disagree about which document won.
+    //
+    // A failure here FAILS THE RUN. A broken method selection that fell through to
+    // "no method" would run a different methodology than the document names,
+    // silently — the same failure `selectExecutor` refuses for the executor, and
+    // the reason `resolveMethod` is coded rather than optional. No selection at
+    // all is the ordinary v1 state and costs nothing.
+    let method;
+    try {
+        const selected = selectMethod(kernel.config);
+        if (selected !== undefined) {
+            // BEFORE the import, and that ordering is the whole guarantee: after
+            // `resolveMethod` the module's top-level code has already run.
+            assertMethodMayMount(selected);
+            method = await swapMethod(undefined, await resolveMethod(selected.specifier, cwd ?? process.cwd()));
+        }
+    }
+    catch (error) {
+        if (disposeProvider)
+            await contained(() => provider.dispose());
+        if (stopKernel !== undefined)
+            await contained(stopKernel);
+        throw error;
+    }
+    let handle;
+    try {
+        handle = await provider.create();
+    }
+    catch (error) {
+        if (method !== undefined)
+            await contained(() => method.deactivate());
+        // Nothing was leased, so there is nothing to release — but the provider was
+        // obtained and owns whatever it allocated before it failed.
+        if (disposeProvider)
+            await contained(() => provider.dispose());
+        if (stopKernel !== undefined)
+            await contained(stopKernel);
+        throw error;
+    }
+    const controller = new AbortController();
+    // Initialised to the noop and only then replaced, because everything from the
+    // lease onwards has to unwind through the `finally`: registering OUTSIDE the
+    // try meant a throwing `onInterrupt` leaked the handle and the provider whole.
+    let removeSignalHandler = () => { };
+    try {
+        removeSignalHandler = onInterrupt?.(() => controller.abort()) ?? removeSignalHandler;
+        // The ONLY way this package can reach an executor. The service closed over
+        // the adapter and hands back no `run` of its own — what it registers is an
+        // action on the KERNEL's pipeline, scoped to the workspace so two sessions
+        // sharing one kernel stay distinguishable in the record stream. A provider
+        // handing back an id a log record rejects fails CLOSED at registration,
+        // before anything is charged.
+        return await executor.run(`${SESSION_ACTION_ID}#${handle.id}`, {
+            prompt,
+            workspace: handle,
+            signal: controller.signal,
+        });
+    }
+    finally {
+        // Order is load-bearing and matches what `brambo run` has always done:
+        // unregister first so a signal arriving during cleanup cannot abort a
+        // controller nobody is watching, then release the lease, then dispose. ALL
+        // of them are contained: a bare deregistration replaced a successful
+        // envelope with its own rejection AND skipped the rest, which is the failure
+        // this block exists to prevent.
+        await contained(() => removeSignalHandler());
+        await contained(() => provider.release(handle));
+        if (disposeProvider)
+            await contained(() => provider.dispose());
+        // The method unmounts BEFORE the kernel stops and AFTER the workspace is
+        // released: its onDeactivate may touch what it materialised, and a teardown
+        // running against a half-disposed session is the failure this ordering
+        // exists to prevent. Contained like every other step here.
+        if (method !== undefined)
+            await contained(() => method.deactivate());
+        // A kernel this session BUILT is a kernel this session stops, which is what
+        // runs every mounted plugin's disposer — the mounted provider's included. A
+        // kernel the caller supplied is the caller's to stop, or two sessions on one
+        // kernel would leave the first one's cleanup disposing the second's provider.
+        if (stopKernel !== undefined)
+            await contained(stopKernel);
+    }
+}

package/dist/tool-executor.d.ts

@@ -0,0 +1,4 @@
+import type { ToolExecutor } from '@skanl/brambo-contracts';
+import type { ResolvedSandboxSession } from '@skanl/brambo-sandbox';
+import type { RemoteMcpClient } from './remote-mcp.ts';
+export declare function createToolExecutor(session: ResolvedSandboxSession, remoteMcpClient?: RemoteMcpClient): ToolExecutor;