@skanl/brambo-session 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SKANL
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,199 @@
+# @skanl/brambo-session
+
+The brambo session: everything `brambo run` does except argv, JSON and exit codes.
+Compose through a kernel, create a workspace, run a prompt under a cancellation
+signal through that kernel's interception waterfall, release and dispose.
+
+The adapter and the workspace provider are **mounted as kernel plugins**, not
+constructed: `createSessionKernel` registers both, seeds the kernel's layered
+configuration from brambo's own documents, and `runSession` consumes the
+`executor` and `workspace` services by name.
+
+Installing `@skanl/brambo-cli` is not required — that is the point of this package. Nor
+is installing `@skanl/brambo-contracts` or `@skanl/brambo-kernel`: every type and helper the
+surface needs is re-exported from here.
+
+```ts
+import { runSession } from '@skanl/brambo-session'
+
+const envelope = await runSession({ prompt: 'list files in this workspace' })
+console.log(envelope.status, envelope.summary)
+```
+
+The returned value is the `ResultEnvelope` `brambo run` prints. Environment
+failures throw instead, carrying a `code` — `BRAMBO_CONTRACT_*` from the workspace
+port, `BRAMBO_KERNEL_*` from a budget refusal:
+
+```ts
+try {
+  await runSession({ prompt: 'list files' })
+} catch (error) {
+  console.error((error as { code?: string }).code)
+}
+```
+
+## What it writes, and what it owns
+
+- **Disk.** Each call creates `<cwd>/.brambo/workspaces/<uuid>`, and the session
+  itself never removes it: `release()` ends a lease and `dispose()` leaves the
+  tree so work survives. Removal is a separate, named capability this package
+  exports — `inspectLocalWorkspaces` / `removeLocalWorkspace` and
+  `inspectWorktrees` / `removeWorktree`, which is what `brambo workspace remove`
+  calls. It is deliberately NOT on the `WorkspaceProvider` port: `dispose()` is
+  documented in five places as preserving state, so making it the removal would
+  invert a published clause.
+- **The provider.** The session disposes whatever `createProvider` returns, on
+  every path. Return a **fresh** provider per session; a pooled one comes back
+  disposed and the next session fails with `BRAMBO_CONTRACT_PROVIDER_DISPOSED`.
+  `createProvider` is **refused** beside a supplied `kernel` — a supplied kernel
+  already carries a provider, and pooling one behind its shared pipeline made the
+  second run fail `BRAMBO_KERNEL_ACTION_INVALID` on a repeated workspace id.
+- **The kernel.** A kernel `runSession` built itself is stopped on every path,
+  which is what runs every mounted plugin's disposer. A kernel you passed in is
+  yours to stop; the session never does, so several sessions can share one.
+- **Interrupts.** There is no default — a library that installs
+  `process.on('SIGINT')` steals the signal from its host. Pass `onInterrupt` to
+  wire your own (`@skanl/brambo-cli` passes its SIGINT/SIGTERM registration).
+
+## Budgets and the record stream
+
+The executor invocation is an action on the **kernel's** waterfall, so
+declarative caps apply to it and every invocation is recorded. `log` receives the
+waterfall's records; the kernel's lifecycle records (manifest validation,
+activation, disposal) stay in the kernel's own stream — build the kernel yourself
+to read those, as the shared-kernel example below does:
+
+```ts
+import { createMemoryLogSink, runSession, SESSION_ACTION_ID } from '@skanl/brambo-session'
+
+const log = createMemoryLogSink()
+try {
+  // A refusal happens BEFORE the executor process is started.
+  await runSession({ prompt: 'do not spawn', log, actionPolicy: { maxInvocations: 0 } })
+} catch {
+  // `drain()` first: an async sink still has records in flight when runSession resolves.
+  await log.drain()
+  console.log(log.records.map((record) => record.event)) // ['action.refused']
+}
+```
+
+Records are subject-scoped to the workspace, so match with
+`record.subject.startsWith(SESSION_ACTION_ID + '#')`.
+
+## Brambo's own configuration
+
+`runSession` reads no files. Hand it the documents instead, and they seed the
+kernel's layered configuration — the ONE composed document both the executor
+selection and every mounted plugin read:
+
+```ts
+import { readExecutorConfigLayers, runSession } from '@skanl/brambo-session'
+
+const configLayers = await readExecutorConfigLayers({ projectDir: process.cwd() })
+await runSession({ prompt: 'list files', configLayers })
+```
+
+`resolveExecutor()` still exists and still answers *which executor*, but a
+selection alone carries no document: `runSession({ executorId })` seeds only
+brambo's defaults and that one choice, so nothing a user wrote reaches a mounted
+plugin. Pass `configLayers` whenever you want the document to configure the run.
+
+Resolution order is `defaults → global → project → agent → invocation`. Naming a
+`cwd` makes the workspace root this invocation's answer; omitting one lets a
+`workspace.rootDir` in the document decide. A key brambo reads and cannot use is
+reported through `onWarning` and never fails the run.
+
+## One kernel, many sessions — one budget
+
+`runSession` builds a kernel per call unless you hand it one. `createSessionKernel`
+builds one you own, and then the pipeline, its caps and its record stream are
+shared by every session on it:
+
+```ts
+import { createMemoryLogSink, createSessionKernel, runSession } from '@skanl/brambo-session'
+
+const log = createMemoryLogSink()
+const kernel = createSessionKernel({
+  log, // the WHOLE kernel stream: activation and disposal, not only the waterfall
+  actionPolicy: { maxTotalCost: 1.5 },
+  executorId: 'codex',
+  onWarning: (message) => console.error(message),
+})
+
+await runSession({ prompt: 'first', kernel })
+// Refused: BRAMBO_KERNEL_COST_CAP_EXCEEDED, before the executor is spawned.
+await runSession({ prompt: 'second', kernel }).catch(() => {})
+await kernel.stop() // disposes every mounted plugin, in reverse order
+```
+
+`createSessionKernel` is the only composition surface this package exposes, and
+that is deliberate: it hands back a started kernel and no plugin factory. A
+`PluginFactory` a caller can invoke with an `ActivationContext` of its own
+construction yields a real vendor adapter wired to the caller's own pipeline, so
+re-exporting the factories put a bypass on the surface of a package whose reason
+to exist is that the executor goes through the waterfall.
+
+A kernel you supply owns its configuration, its plugins, its pipeline, its sink
+and its provider, so `configLayers`, `cwd`, `executorId`, `adapterOptions`,
+`createAdapter`, `createProvider`, `onSelection`, `log` and `actionPolicy` are
+**refused** beside it rather than silently ignored.
+
+## Sandbox and tool-composition seam
+
+SDK hosts may supply a `sandboxProvider`, `toolExecutor`, `toolPolicy`, approval,
+and tool/sandbox event callbacks when composing a session. `executeTool()` is the
+explicit SDK operation that validates the invocation and context, checks the
+provider's declared capability facts, requests host approval, executes through
+the supplied executor, and emits the normalized result.
+
+The boundary is explicit: bind a
+caller-owned sandbox session to `createToolExecutor`, pass `local` or
+`mcp-stdio` exact argv, and dispose the session at the host's lifecycle boundary.
+This is not an arbitrary JavaScript-handler API, and `ToolProvider` discovery is
+not execution authority. The session seam also makes no OS-isolation or concrete
+remote-protocol claim.
+
+**Read the caps honestly.** A run is ADMITTED at `SESSION_ACTION_COST` (a flat 1)
+and then SETTLED against the token figure the executor itself reported, so
+`maxTotalCost` and `maxInvocations` now refuse on **different runs**: one
+claude-code run settles at tens of thousands of tokens, which trips a cost cap
+while the invocation count is still 1, and a cheap run trips an invocation cap
+with the settled cost nowhere near its own limit. The error `code` still says
+which cap fired.
+
+Two ceilings remain, and both are tracked in
+`_bmad-output/implementation-artifacts/deferred-work.md`. `maxConcurrent` is
+still collapsed with the other two for a session that registers one action and
+awaits it — nothing a single `brambo run` does puts two operations in flight. And
+the ESTIMATE is a flat 1 while the settlement is in the vendor's tokens, so a
+host that budgets in tokens should pass its own `cost` through
+`createExecutorPlugin`; brambo will not invent a pre-run token figure.
+
+The settlement is also what the record stream carries: with a policy configured,
+each admitted run emits an `action.estimated` and, if the vendor reported a
+figure, an `action.settled`, so the total is reconstructable from the records
+alone. With no policy set, the stream is exactly what it was before.
+
+### What the session seam means today
+
+The session package re-exports the SDK composition seam, but its current
+executor run path does not contain a tool-call route. Supplying
+`sandboxProvider`, `toolExecutor`, policy, approval, or callbacks therefore
+validates/configures inputs but does not itself create a sandbox or execute a
+tool. A host with an actual tool-call flow should create a provider-owned
+session, call `createToolExecutor(session)`, and dispose it at the host
+lifecycle boundary.
+
+`ToolExecutor` preserves exact argv. A local descriptor such as
+`{ kind: 'local', argv: ['node', 'server.mjs'] }` with `['--config', 'a b']`
+reaches the provider as `['node', 'server.mjs', '--config', 'a b']`; no shell
+parsing or arbitrary JavaScript handler is involved. An `mcp-stdio` descriptor
+uses the same argv and provider-owned framed stdio channel for local MCP.
+
+Policies requiring unproven controls or resource limits fail closed. The
+current local provider evidence is conservative; the remote provider is an
+injected transport adapter, not a bundled protocol. `danger-full-access`
+requires explicit acknowledgement and may emit validated start/completion
+audit events, but neither audit events nor current tests prove OS isolation.
+Repository/provider tests are current-platform evidence. The optional
+Linux/macOS/Windows host-conformance runs have not been claimed as executed.

package/dist/executors.d.ts

@@ -0,0 +1,146 @@
+import { DEFAULT_EXECUTOR_ID, EXECUTOR_CATALOGUE, EXECUTOR_CONFIG_KEY, availableExecutorIds, createExecutorAdapter } from '@skanl/brambo-adapter-cli';
+import type { CliExecutorAdapterOptions, ShippedExecutor } from '@skanl/brambo-adapter-cli';
+import type { ConfigLayer, LayeredConfig } from '@skanl/brambo-kernel';
+export { DEFAULT_EXECUTOR_ID, EXECUTOR_CATALOGUE, EXECUTOR_CONFIG_KEY, availableExecutorIds, createExecutorAdapter, type ShippedExecutor, };
+export type { CliExecutorAdapterOptions };
+/** Brambo's own configuration document for a scope root. */
+export declare function executorConfigPath(scopeDir: string): string;
+export interface ResolveExecutorOptions {
+    /**
+     * Explicit override for this invocation, e.g. `brambo run --executor codex`.
+     * Set as the `invocation` LAYER, so it wins over both documents and is
+     * reported as having done so. Omitted, no invocation layer exists at all.
+     */
+    readonly executorId?: string;
+    /**
+     * Root of the machine scope; `<homeDir>/.brambo/config.json` is the `global`
+     * layer. A SEAM: it defaults to the OS home directory in production and every
+     * test points it at a temp directory, because a suite whose result depends on
+     * the `~/.brambo` of whoever runs it passes and fails for reasons having
+     * nothing to do with the code.
+     */
+    readonly homeDir?: string;
+    /**
+     * Root of the project scope; `<projectDir>/.brambo/config.json` is the
+     * `project` layer. The same seam, defaulting to `process.cwd()`.
+     */
+    readonly projectDir?: string;
+}
+export interface ExecutorSelection {
+    /** The id that won; always a key of `EXECUTOR_CATALOGUE`. */
+    readonly executorId: string;
+    /**
+     * The layer that supplied it, taken from the layered config's OWN `dump()`.
+     * Never recomputed here: provenance derived a second time is how a report
+     * starts disagreeing with the thing it reports on.
+     */
+    readonly layer: ConfigLayer;
+    /**
+     * Every id a selection may name. Here for a host that offers a CHOICE and has
+     * to render one; `@skanl/brambo-cli` does not print it, because on the one path where
+     * a user needs the list — an id brambo has no adapter for — the coded error's
+     * own message already carries it.
+     */
+    readonly available: readonly string[];
+}
+/** One of brambo's own configuration documents, and where it came from. */
+export interface ExecutorConfigDocument {
+    /** The path it was read from, so a layer that rejects it can name the file. */
+    readonly filePath: string;
+    readonly document: unknown;
+}
+/**
+ * Brambo's own documents, READ but not yet composed.
+ *
+ * This exists so the documents are read ONCE per run. Story M3.B made the
+ * kernel's layered configuration the one the mounted plugins read, and the
+ * kernel is constructed inside `runSession` — so a caller that resolved a
+ * selection first and then ran would have read `.brambo/config.json` twice, with
+ * a window between them in which the two could disagree. Handing the SNAPSHOTS
+ * forward closes that window: `seedExecutorConfig` composes them into whichever
+ * configuration is going to be used, and nothing re-reads a file.
+ */
+export interface ExecutorConfigLayers {
+    /**
+     * Values composed UNDER brambo's own built-in default, so any document can
+     * still override them. `@skanl/brambo-session` puts its computed workspace root here
+     * when the caller named no `cwd`, which is what lets a user's
+     * `workspace.rootDir` actually decide the directory.
+     */
+    readonly defaults?: unknown;
+    /** `<homeDir>/.brambo/config.json`, when it exists. */
+    readonly global?: ExecutorConfigDocument;
+    /** `<projectDir>/.brambo/config.json`, when it exists and is not the machine one. */
+    readonly project?: ExecutorConfigDocument;
+    /** This invocation's explicit override, e.g. `brambo run --executor codex`. */
+    readonly invocation?: unknown;
+}
+/**
+ * Reads brambo's own documents into layer snapshots. The ONLY filesystem access
+ * in executor selection.
+ *
+ * A MISSING document is an absent layer. A document that exists and cannot be
+ * used is a coded error — reading a corrupt file and shrugging back to the
+ * default runs a different agent than the user configured, silently, which is
+ * the failure this selection exists to remove.
+ */
+export declare function readExecutorConfigLayers(options?: ResolveExecutorOptions): Promise<ExecutorConfigLayers>;
+/**
+ * Composes brambo's defaults and the given documents into ONE layered
+ * configuration: `defaults` -> `global` -> `project` -> `invocation`.
+ *
+ * The `setLayer` calls are WRAPPED because the kernel's validation is what
+ * rejects a hostile document, and it names the offending KEY rather than the
+ * file: a `__proto__` key in the machine document and in the project document
+ * produced byte-identical stderr naming neither, and an unbounded nesting depth
+ * (~3000 levels) produced a bare `RangeError` carrying no `code` at all — an
+ * UNCODED crash on the exact input class the matrix says must be refused coded.
+ * The kernel's own error travels on as the `cause`, so its code is preserved in
+ * the chain rather than swallowed.
+ *
+ * Since Story M3.B this is what seeds the KERNEL's configuration, so the mounted
+ * plugins and the executor selection read one composed document rather than two.
+ */
+/**
+ * A key brambo READ off disk and refused to admit into its layer, with what it
+ * is running instead.
+ *
+ * Typed rather than logged, because AD-5 is "typed absence over silence" and its
+ * opposite of IGNORED is TYPED AND REPORTED, not FATAL. The guard this replaces
+ * read that as a binary -- "REFUSED rather than ignored, per AD-5" -- and made a
+ * cloned repository able to deny service to the machine owner's own selection.
+ * `using` is `undefined` when nothing else selects one, which is a different
+ * sentence and has to stay tellable apart.
+ */
+export interface DeclinedConfigKey {
+    readonly key: 'method';
+    /** What the project document recommended, verbatim. */
+    readonly specifier: string;
+    /** The document that recommended it, so the notice can name the file. */
+    readonly filePath: string;
+    /** What decides instead, taken from the COMPOSED view rather than guessed. */
+    readonly using: string | undefined;
+}
+export declare function seedExecutorConfig(config: LayeredConfig, layers?: ExecutorConfigLayers): DeclinedConfigKey | undefined;
+/**
+ * The selection an already-seeded configuration decides, with the layer that
+ * decided it. Pure: it reads the composed view and touches no file.
+ */
+export declare function selectExecutor(config: LayeredConfig): ExecutorSelection;
+/**
+ * Which executor this run uses, resolved through the kernel's layered
+ * configuration: `defaults` -> `global` -> `project` -> `invocation`.
+ *
+ * This — not `runSession` — is what reads the filesystem. A session primitive
+ * whose behaviour depends on files under the running user's home is not usable
+ * from a host that already knows what it wants, and it would make every existing
+ * `brambo run` test depend on the `~/.brambo` of whoever ran the suite.
+ *
+ * Ships from `@skanl/brambo-session` beside `runSession`, so FR-29 holds: a third party
+ * imports this package and gets the selection AND the run, with no CLI involved.
+ *
+ * `brambo run` does NOT call this: it reads the layers once and hands them to
+ * `runSession`, which seeds the KERNEL's configuration and selects from that one
+ * composed document. The three steps are exactly the three this function performs.
+ */
+export declare function resolveExecutor(options?: ResolveExecutorOptions): Promise<ExecutorSelection>;