@skanl/brambo-session 0.1.1

package/dist/run-session.d.ts

@@ -0,0 +1,300 @@
+import type { CliExecutorAdapterOptions } from '@skanl/brambo-adapter-cli';
+import type { ExecutorAdapter, ResultEnvelope, SandboxPolicy, SandboxProvider, ToolExecutionContext, ToolExecutor, ToolInvocation, ToolResult, WorkspaceProvider } from '@skanl/brambo-contracts';
+import { type ActionPolicy, type LogSink, type BramboKernel } from '@skanl/brambo-kernel';
+import { type ExecutorConfigLayers, type ExecutorSelection } from './executors.ts';
+/**
+ * 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 declare 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 declare const SESSION_ACTION_COST = 1;
+/** The request `executeTool` puts before the host's approval boundary. */
+export interface ToolApprovalRequest {
+    readonly invocation: ToolInvocation;
+    readonly context: ToolExecutionContext;
+}
+/** The host decides whether a normalized tool invocation may proceed. */
+export type ToolApproval = (request: ToolApprovalRequest) => boolean | Promise<boolean>;
+/** A completed normalized tool invocation, for host-owned observation. */
+export interface ToolExecutionEvent extends ToolApprovalRequest {
+    readonly result: ToolResult;
+}
+/** Options for one host-approved SDK tool invocation. */
+export interface ExecuteToolOptions extends ToolCompositionOptions {
+    readonly invocation: ToolInvocation;
+    readonly context: ToolExecutionContext;
+}
+/**
+ * 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 declare function executeTool(options: ExecuteToolOptions): Promise<ToolResult>;
+/** A lifecycle event emitted when a sandbox-backed SDK flow selects a provider. */
+export interface SandboxEvent {
+    readonly type: 'provider-selected' | 'session-created' | 'session-disposed';
+    readonly providerId: string;
+    readonly policy: SandboxPolicy;
+}
+/**
+ * Tool composition dependencies for the SDK execution boundary. `runSession`
+ * remains a vendor-run lifecycle; `executeTool` routes explicit host-approved
+ * invocations without making the vendor executor or kernel a tool registry.
+ */
+export interface ToolCompositionOptions {
+    readonly sandboxProvider?: SandboxProvider;
+    readonly toolExecutor?: ToolExecutor;
+    readonly toolPolicy?: SandboxPolicy;
+    readonly approveTool?: ToolApproval;
+    readonly onToolExecution?: (event: ToolExecutionEvent) => void;
+    readonly onSandboxEvent?: (event: SandboxEvent) => void;
+}
+export interface SessionOptions extends ToolCompositionOptions {
+    /** Handed to the executor verbatim; rejected before anything is created if it is blank. */
+    readonly prompt: string;
+    /** Root the mounted workspace plugin builds `.brambo/workspaces` under. Defaults to `process.cwd()`. */
+    readonly cwd?: string;
+    /**
+     * Which shipped adapter runs the prompt, by catalogue id (`executors.ts`).
+     * Omitted, the selection comes from `configLayers` and then from brambo's
+     * built-in default LAYER — the default is a lookup like every other id, so no
+     * path here constructs a vendor adapter by name.
+     *
+     * Set as the `invocation` layer of the kernel's configuration, so it wins over
+     * every document and is reported as having done so.
+     */
+    readonly executorId?: string;
+    /**
+     * Brambo's own configuration documents, ALREADY READ (`readExecutorConfigLayers`).
+     *
+     * This is what seeds the kernel's layered configuration, so the mounted
+     * plugins and the executor selection read one composed document. It is DATA,
+     * never a path: a session primitive that read files under the running user's
+     * home would be unusable from a host that already knows what it wants, and it
+     * would make every `brambo run` test depend on whoever ran the suite. Omitted,
+     * only brambo's `defaults` layer and `executorId` apply.
+     */
+    readonly configLayers?: ExecutorConfigLayers;
+    /**
+     * Options handed to the SELECTED adapter: a child-process spawner, or a binary
+     * path that overrides the trait's command. Ignored when `createAdapter` is
+     * supplied, because then the caller built the adapter itself.
+     *
+     * This is the seam that makes `executorId` provable end to end — a fake
+     * spawner here exercises selection, catalogue lookup and vendor argv on the
+     * PRODUCTION path, where injecting `createAdapter` bypasses the very wiring
+     * under test. It is also what gives an embedding host a way to point brambo at
+     * a binary that is not on PATH.
+     */
+    readonly adapterOptions?: CliExecutorAdapterOptions;
+    /**
+     * Adapter seam; tests and embedding hosts inject their own. When supplied it
+     * WINS over `executorId` and `adapterOptions`: the caller handed brambo the
+     * executor, so brambo did not select one. The invocation still travels the
+     * kernel's waterfall — the seam decides WHICH executor runs, never WHETHER the
+     * pipeline sees it.
+     */
+    readonly createAdapter?: () => ExecutorAdapter;
+    /**
+     * Workspace provider seam. Omitted, the provider comes from the kernel's
+     * mounted `workspace` plugin, which is what `brambo run` uses.
+     *
+     * OWNERSHIP: the session disposes whatever this returns, on every path. Hand
+     * back a FRESH provider per session — returning a pooled or long-lived one
+     * leaves it disposed, and the next session against it fails with
+     * `BRAMBO_CONTRACT_PROVIDER_DISPOSED` (pinned by a test, because the obvious
+     * reason to inject a provider is to pool workspaces). A provider obtained from
+     * the kernel is NOT disposed here: it belongs to the plugin, and the kernel
+     * disposes it at `stop()`.
+     */
+    readonly createProvider?: () => WorkspaceProvider;
+    /**
+     * Signal-registration seam: register a handler for interrupt/termination and
+     * return its disposer. Deliberately has NO default — a library that installs
+     * `process.on('SIGINT')` steals the signal from whatever host embedded it, so
+     * the process owner supplies this. `@skanl/brambo-cli` passes its SIGINT/SIGTERM
+     * wiring here; an SDK caller with its own cancellation passes its own.
+     */
+    readonly onInterrupt?: (handler: () => void) => () => void;
+    /**
+     * Told which executor was selected and which layer decided it, BEFORE anything
+     * is constructed. `brambo run` prints that line on stderr; a host that offers a
+     * choice renders it however it likes.
+     *
+     * A throw here is contained: a reporter is an observer, and an observer must
+     * not be able to fail a run it was only watching.
+     */
+    readonly onSelection?: (selection: ExecutorSelection) => void;
+    /**
+     * Told about a configuration key brambo READ and could not use — an unknown key
+     * inside a mounted plugin's subtree, or a subtree of the wrong shape.
+     *
+     * These are reported and survived rather than fatal, and this is the seam that
+     * keeps "reported" from meaning "emitted where nobody looks". `brambo run`
+     * prints them on stderr. Measured before it existed: a single forward-looking
+     * key in `~/.brambo/config.json` failed every run on the machine with
+     * `BRAMBO_KERNEL_PLUGIN_START_FAILED`. Contained, like `onSelection`.
+     */
+    readonly onWarning?: (message: string) => void;
+    /**
+     * Where the interception waterfall's records go. Omitted, the session builds
+     * an in-memory sink it then drops — the waterfall still runs, its trail is
+     * simply unread.
+     *
+     * The WATERFALL's, not the kernel's whole stream: the kernel this session owns
+     * also records manifest validation, activation and disposal, and those stay in
+     * the kernel's own sink. A caller who wants the complete stream builds the
+     * kernel itself (`createKernel({ log })`) and passes it as `kernel`.
+     *
+     * ponytail: the caller owns the sink they pass, draining included. A sink whose
+     * write is async still has records in flight when this resolves; `await
+     * sink.drain()` before reading `sink.records`.
+     */
+    readonly log?: LogSink;
+    /**
+     * Declarative caps for this session's kernel pipeline (AD-10). Omitted, nothing
+     * is capped, which is what keeps `brambo run` behaviour-neutral. A violation is
+     * refused BEFORE the executor runs and surfaces as a coded `BramboKernelError`.
+     *
+     * Per KERNEL, so a host that shares one kernel across sessions caps all of
+     * them together — which is the whole reason `kernel` exists as an option.
+     */
+    readonly actionPolicy?: ActionPolicy;
+    /**
+     * A kernel this session should COMPOSE THROUGH instead of building its own.
+     *
+     * OWNERSHIP: the caller owns it — the caller mounted its plugins, seeded its
+     * configuration and must `stop()` it; this session never does, so several
+     * sessions can share one pipeline and one budget. That sharing is the point:
+     * a cap only means something while every invocation it is supposed to bound
+     * goes through the same pipeline.
+     *
+     * Every option that would configure a kernel, choose its executor, place its
+     * workspaces or report on any of that is REFUSED alongside it rather than
+     * ignored, because a budget or an executor selection that silently did nothing
+     * is worse than one that was rejected. `createProvider` is refused too: it
+     * exists for pooling, pooling gives a stable workspace id, a stable workspace
+     * id gives a stable ACTION id, and a kernel-owned pipeline never retires one —
+     * so the second run failed `BRAMBO_KERNEL_ACTION_INVALID` on a shared kernel.
+     * A supplied kernel already carries a workspace provider; that is the point.
+     */
+    readonly kernel?: BramboKernel;
+}
+export interface SessionKernelOptions extends ToolCompositionOptions {
+    /**
+     * Root the workspace plugin builds `.brambo/workspaces` under. NAMED or not is
+     * load-bearing: named, it is this invocation's answer and wins over every
+     * document; omitted, `process.cwd()` supplies a DEFAULTS layer that a
+     * `workspace.rootDir` in the user's document overrides. Anything else would
+     * make the layered configuration decorative for the one object-namespaced
+     * plugin brambo mounts — measured: a valid configured `rootDir` was validated
+     * and then always discarded.
+     */
+    readonly cwd?: string;
+    /** Explicit executor selection for this invocation; the `invocation` layer. */
+    readonly executorId?: string;
+    /** Brambo's own documents, already read (`readExecutorConfigLayers`). */
+    readonly configLayers?: ExecutorConfigLayers;
+    /** Options handed to the selected adapter. */
+    readonly adapterOptions?: CliExecutorAdapterOptions;
+    /** Adapter seam; wins over the selection, and still runs through the waterfall. */
+    readonly createAdapter?: () => ExecutorAdapter;
+    /** Where the KERNEL's whole record stream goes — lifecycle transitions included. */
+    readonly log?: LogSink;
+    /** Declarative caps for this kernel's pipeline, shared by every session on it. */
+    readonly actionPolicy?: ActionPolicy;
+    /** See `SessionOptions.onSelection`; called before any plugin is registered. */
+    readonly onSelection?: (selection: ExecutorSelection) => void;
+    /** See `SessionOptions.onWarning`. */
+    readonly onWarning?: (message: string) => void;
+}
+/**
+ * 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 declare function createSessionKernel(options?: SessionKernelOptions): BramboKernel;
+/**
+ * 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 declare function runSession(options: SessionOptions): Promise<ResultEnvelope>;