@lkyhfx/dsh-bb-repl 0.0.0-stage → 0.1.1

package/bb-src/domain/runtime.clj

@@ -0,0 +1,103 @@
+(ns domain.runtime
+  "Session-scoped runtime observability, loaded automatically by bb-repl.
+
+  This namespace answers the questions a persistent-REPL agent actually has:
+  where does the workspace live, which definitions already exist, what does
+  each mounted domain report, and how do I deliberately drop a broken session.
+  It is a thin layer over babashka.fs / babashka.process: no policy of its own."
+  (:require [babashka.fs :as fs]
+            [babashka.process :as p]
+            [clojure.string :as str])
+  (:import [java.io File]))
+
+(def ^:private workspace-root
+  (let [root (System/getenv "DSH_BB_WORKSPACE_ROOT")]
+    (when (str/blank? root)
+      (throw (ex-info "Workspace root not set by DSH" {:code :missing-root})))
+    (.toPath (.getCanonicalFile (File. root)))))
+
+(defonce ^:private registry (atom {}))
+
+(defn register!
+  "Register one mounted domain. Called by the bb-repl host, not by the agent."
+  [{:keys [id version state-version instructions status]}]
+  (swap! registry assoc id (cond-> {:id id
+                                   :version (str version)
+                                   :state-version (str state-version)
+                                   :instructions (str instructions)}
+                            status (assoc :status status)))
+  id)
+
+(defn workspace
+  "Absolute path of the workspace this session is scoped to.
+  Raw Babashka process/fs calls start in a private scratch directory;
+  pass (workspace) explicitly as :dir / fs/path when you need the project."
+  []
+  (str workspace-root))
+
+(defn path
+  "Join workspace-relative segments into an absolute path without touching disk."
+  [& segments]
+  (str (apply fs/path (str workspace-root) (map str segments))))
+
+(defn shell
+  "Run a command with the workspace as working directory.
+  (shell {:out :string} \"git\" \"status\" \"--short\")"
+  [opts & args]
+  (apply p/shell (merge {:dir (str workspace-root)} opts) args))
+
+(defn domains
+  "Ids of the domain namespaces mounted into this session."
+  []
+  (vec (sort (keys @registry))))
+
+(defn- user-var?
+  [n]
+  (let [s (name n)]
+    (and (not (str/starts-with? s "*")) (not (str/starts-with? s "->")))))
+
+(defn vars
+  "Agent-defined public vars in the user namespace, with arglists and docstrings.
+  Use this before redefining something that may already exist."
+  []
+  (->> (ns-publics 'user)
+       (filter (fn [[n _]] (user-var? n)))
+       (map (fn [[n v]]
+              (let [m (meta v)]
+                (cond-> {:name n}
+                  (:arglists m) (assoc :arglists (:arglists m))
+                  (:doc m) (assoc :doc (:doc m))))))
+       (sort-by :name)
+       vec))
+
+(defn status
+  "One map with the workspace, the mounted domains, each domain's own counters,
+  and how many definitions this session currently holds. Read-only."
+  []
+  {:workspace (str workspace-root)
+   :domains (into (sorted-map)
+                  (map (fn [[id d]] [id (if-let [f (:status d)] (f) {:version (:version d)})])
+                       @registry))
+   :defs (count (vars))})
+
+(defn help
+  "Domain API guide. No argument lists every mounted domain; a domain id
+  (:code / \"code\") prints that domain's guide."
+  ([] (into (sorted-map)
+            (map (fn [[id d]] [id {:version (:version d)
+                                   :state-version (:state-version d)
+                                   :instructions (:instructions d)}]))
+            @registry))
+  ([id]
+   (let [d (get @registry (if (keyword? id) (name id) (str id)))]
+     (when-not d (throw (ex-info (str "Unknown domain " id) {:domains (domains)})))
+     (:instructions d))))
+
+(defn reset!
+  "Deliberately discard this session: definitions, atoms and domain counters.
+  The host starts a fresh interpreter on the next call. Use it when the REPL
+  holds state you know to be wrong, instead of working around it."
+  ([] (reset! "requested by the agent"))
+  ([reason]
+   (throw (ex-info (str "DSH_BB_RESET: " (or reason "requested by the agent"))
+                   {:code :dsh.bb/reset-requested :reason (str reason)}))))

package/cordis.patch.yml

@@ -0,0 +1,38 @@
+# Bundle patch for the dsh-bb-repl stack.
+#
+# `dsh plugin --profile <name> add @lkyhfx/dsh-bb-repl` appends this package to
+# `dsh.profile.bundles`, so this layer mounts the stack without editing the
+# profile patch by hand.
+#
+# The group isolates `bbDomain`: each Agent stack sees its own domain registry,
+# so a child domain plugin cannot leak its manifest into another group.
+#
+# This layer does NOT remove the existing persistent-bash / persistent-pwsh
+# tool. Disable those rows in your profile patch or Agent preset if you want
+# `bb_eval` to be the only shell the model sees.
+#
+# Config knobs (all optional, defaults shown):
+#   bbExecutable   bb       Babashka executable name or absolute path
+#   timeoutMs      120000   per-eval timeout; a timeout resets the session
+#   startupMs      12000    interpreter start budget
+#   maxOutputChars 16000    output clipping budget
+#   sandbox        inherit  'inherit' goes through ctx.sandbox under the
+#                           session's ctx.sandboxPolicy and fails closed when no
+#                           backend exists; 'off' runs unconfined (tests only)
+- insert:
+    - id: bb-domain-stack
+      name: cordis:group
+      group: true
+      isolate:
+        bbDomain: true
+      config:
+        - id: bb-repl
+          name: '@lkyhfx/dsh-bb-repl'
+          config:
+            bbExecutable: bb
+            timeoutMs: 120000
+            startupMs: 12000
+            maxOutputChars: 16000
+            sandbox: inherit
+        - id: bb-code
+          name: '@lkyhfx/dsh-bb-domain-code'

package/package.json

@@ -1,6 +1,25 @@
 {
   "name": "@lkyhfx/dsh-bb-repl",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "DSH Cordis plugin: owner-scoped persistent Babashka nREPL tool (bb_eval)",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": ["src", "bb-src", "cordis.patch.yml"],
+  "keywords": ["dsh", "cordis", "babashka", "nrepl", "clojure", "repl"],
+  "repository": {"type": "git", "url": "git+https://github.com/lkyhfx/dsh-bb-repl.git", "directory": "packages/repl"},
+  "publishConfig": {"access": "public"},
+  "dsh": {"bundle": {"patch": "./cordis.patch.yml"}},
+  "dependencies": {
+    "@deepseek-ai/schemastery": "*",
+    "@lkyhfx/dsh-bb-domain-code": "^0.1.1"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "*",
+    "@deepseek-ai/dsh-tools": "*"
+  }
+}

package/src/env.js

@@ -0,0 +1,37 @@
+/** Child environment policy for the Babashka runtime. */
+
+// Same credential-shaped scrub the DSH subprocess seam applies to every child
+// (`SENSITIVE_ENV_PATTERN` in @deepseek-ai/dsh-subprocess): the interpreter must
+// not expose the host's API keys to agent-authored Clojure.
+const SENSITIVE_ENV_PATTERN = /KEY|PASSWORD|SECRET|TOKEN/i
+const DSH_ENV_PREFIX = 'DSH_'
+
+/**
+ * The parent environment minus credential-shaped names and minus every `DSH_*`
+ * name. PATH, HOME, locale and proxy variables survive so `bb`, `rg`, `git` and
+ * `diff` keep working; Harness identity and credentials never leak implicitly.
+ * Harness-owned facts are re-added explicitly by the caller.
+ */
+export function scrubbedChildEnv(parent = process.env) {
+  const env = {}
+  for (const [key, value] of Object.entries(parent)) {
+    if (value === undefined) continue
+    if (SENSITIVE_ENV_PATTERN.test(key)) continue
+    if (key.toUpperCase().startsWith(DSH_ENV_PREFIX)) continue
+    env[key] = value
+  }
+  return env
+}
+
+/** Explicit, non-secret facts this runtime hands to its Babashka child. */
+export function runtimeChildEnv({ workspace, scratch, port }) {
+  return {
+    ...scrubbedChildEnv(),
+    DSH_BB_WORKSPACE_ROOT: workspace,
+    DSH_BB_SCRATCH: scratch,
+    DSH_BB_NREPL_PORT: String(port),
+    PAGER: 'cat',
+    GIT_PAGER: 'cat',
+    NO_COLOR: '1',
+  }
+}

package/src/index.js

@@ -0,0 +1,221 @@
+/** DSH Cordis plugin: one owner-scoped persistent Babashka nREPL tool. */
+import { resolve } from 'node:path'
+import z from '@deepseek-ai/schemastery'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { DomainSessions } from './sessions.js'
+
+export const name = 'bb-repl'
+// `sandbox` and `sandboxPolicy` are resolved through ctx.get at each session
+// start rather than injected: they are optional (config `sandbox: 'off'` runs
+// unconfined for tests and for deployments that accept that), and Cordis'
+// array `inject` can only express required services.
+export const inject = ['tools', 'workingDirectory']
+
+const GUIDE = `Execute Clojure programs in a persistent Babashka REPL isolated to this Agent.
+
+PERSISTENCE:
+- Functions defined with defn and values defined with def persist across calls
+  in the same Agent session.
+- let bindings are local to one expression; they do not survive a call.
+- Use defonce and atoms when mutable persistent state is actually required.
+- Inspect existing definitions before recreating them: (domain/vars).
+- Ordinary Clojure evaluation errors do NOT reset the REPL: a var defined
+  before the error is still there, so fix the form and keep going.
+- Timeouts, cancellations, transport failures and incompatible domain updates
+  DO reset the session. The call result says "session reset" or "session
+  rebuilt" when that happened, and then nothing is left but domain state.
+- Inspect (domain/status) or (domain/vars) whenever state is uncertain.
+
+COMPOSITION:
+- Compose domain primitives with let, do, ->, ->>, map, filter, reduce and the
+  rest of clojure.core.
+- Prefer one evaluation for a predictable multi-step task; return a compact
+  final value, not bulk file content.
+- Reuse functions and intermediate results across calls instead of repeating
+  searches and reads.
+- Use domain primitives for workspace file operations; they carry the guards.
+
+DISCOVERY:
+- (domain/status) -> workspace, mounted domains, their counters, def count.
+- (domain/help) or (domain/help :code) -> the domain API guides.
+- (domain/vars) -> agent-defined vars with arglists and docstrings.
+- (code/status) -> code-domain counters and workspace.
+- (meta #'code/search) -> signature and docstring of one primitive.
+
+STATE RESET:
+- (domain/reset! "why") deliberately discards this session's definitions and
+  starts a fresh interpreter on the next call. Prefer it over working around
+  known-bad state.
+
+SAFETY:
+- Clojure is dynamically typed; type errors surface at runtime.
+- Code runs with the configured runtime permissions. Never perform
+  unauthorized destructive operations.`
+
+export const Config = z.object({
+  bbExecutable: z.string().default('bb'),
+  timeoutMs: z.number().default(120000),
+  startupMs: z.number().default(12000),
+  maxOutputChars: z.number().default(16000),
+  sandbox: z.union([z.const('inherit'), z.const('off')]).default('inherit'),
+  description: z.string().default(GUIDE),
+})
+
+const clip = (s, n) => s.length <= n ? s : `${s.slice(0, n)}\n[Output truncated; narrow your query]`
+
+export function apply(ctx, config = {}) {
+  const cfg = {
+    bbExecutable: config.bbExecutable ?? 'bb',
+    timeoutMs: config.timeoutMs ?? 120000,
+    startupMs: config.startupMs ?? 12000,
+    maxOutputChars: config.maxOutputChars ?? 16000,
+    sandbox: config.sandbox ?? 'inherit',
+    description: config.description ?? GUIDE,
+  }
+  for (const field of ['timeoutMs', 'startupMs', 'maxOutputChars']) {
+    if (!Number.isSafeInteger(cfg[field]) || cfg[field] < 1) throw new Error(`bb-repl: invalid ${field}`)
+  }
+  if (cfg.sandbox !== 'inherit' && cfg.sandbox !== 'off') throw new Error('bb-repl: sandbox must be "inherit" or "off"')
+
+  const modules = new Map()
+
+  const policyService = () => ctx.get?.('sandboxPolicy') ?? ctx.sandboxPolicy
+  const sandboxService = () => ctx.get?.('sandbox') ?? ctx.sandbox
+
+  /**
+   * The session's file-effect policy, or a synthetic one when confinement is off.
+   *
+   * `key` is the reuse identity of a live interpreter: it covers every input
+   * that changes what the *running* process is allowed to touch, so a revoked or
+   * widened grant can never be served by a process started under the old one.
+   * DSH's `SandboxExecutionPolicy` carries `additionalWritableRoots` and
+   * `sessionId` besides mode/root, so both are part of the key.
+   */
+  const resolvePolicy = (owner, workspace) => {
+    if (cfg.sandbox === 'off') return { mode: 'danger-full-access', key: 'unconfined' }
+    const service = policyService()
+    if (!service) {
+      throw new Error('bb-repl: sandbox mode "inherit" requires ctx.sandboxPolicy; mount @deepseek-ai/dsh-sandbox-policy or set config sandbox: "off"')
+    }
+    const resolved = service.resolve({ session: owner.session })
+    // The Agent's working directory IS the workspace-write boundary; the policy
+    // root is only the agentless fallback, matching ctx.sandboxPolicy semantics.
+    const root = resolve(workspace ?? resolved.workspaceRoot)
+    const extraRoots = [...new Set((resolved.additionalWritableRoots ?? []).map(r => resolve(r)))].sort()
+    const sessionId = resolved.sessionId === undefined ? '' : String(resolved.sessionId)
+    const key = [resolved.mode, root, ...extraRoots, sessionId].join('\u0000')
+    return { ...resolved, workspaceRoot: root, additionalWritableRoots: extraRoots, key }
+  }
+
+  /**
+   * Wrap the interpreter argv under the session's policy, mirroring the DSH
+   * sandbox contract: `danger-full-access` spawns the original argv, any other
+   * mode must be enforced or the start fails closed.
+   */
+  const confineArgv = async ({ argv, workspaceRoot, owner, policy, signal }) => {
+    const resolved = policy ?? resolvePolicy(owner, workspaceRoot)
+    if (resolved.mode === 'danger-full-access') return { argv, policy: resolved }
+    const sandbox = sandboxService()
+    if (!sandbox) {
+      throw new Error(`bb-repl: sandbox mode "${resolved.mode}" is requested but no sandbox backend is usable in this composition; refusing to run Babashka unconfined. Set config sandbox: "off" only if you accept unconfined code execution.`)
+    }
+    const confined = await sandbox.confine(argv, { ...resolved, mode: resolved.mode }, signal)
+    if (!confined?.argv?.length) throw new Error('bb-repl: sandbox returned an empty argv')
+    return { argv: confined.argv, policy: resolved, enforcement: confined.enforcement }
+  }
+
+  const sessions = new DomainSessions({
+    bbExecutable: cfg.bbExecutable,
+    timeoutMs: cfg.timeoutMs,
+    startupMs: cfg.startupMs,
+    modules: () => [...modules.values()],
+    onLog: message => ctx.logger.warn(message),
+    confine: confineArgv,
+    policyFor: resolvePolicy,
+  })
+
+  let disposeTool
+  const buildDescription = () => [
+    cfg.description,
+    ...[...modules.values()].map(m => `DOMAIN ${m.id}:\n${m.instructions}`),
+  ].join('\n\n')
+
+  const bindTool = () => {
+    disposeTool?.()
+    disposeTool = ctx.tools.register(defineTool({
+      name: 'bb_eval',
+      description: buildDescription(),
+      parameters: {
+        code: { type: 'string', required: true, description: 'Clojure forms to execute in the persistent Babashka session.' },
+      },
+      output: {
+        schema: { type: 'string' },
+        render: (_args, value) => [{ type: 'text', text: value }],
+      },
+      async execute(args, exec) {
+        if (typeof args.code !== 'string' || !args.code.trim()) throw new Error('code is required')
+        if (!exec.agent) throw new Error('bb_eval requires an owning Agent')
+        const workspace = await ctx.workingDirectory.ensure(exec.agent, exec.signal)
+        try {
+          const result = await sessions.evaluate(exec.agent, workspace, args.code, exec.signal)
+          const notes = result.notes ?? []
+          const body = [
+            notes.length ? `runtime:\n${notes.join('\n')}` : '',
+            result.out ? `stdout:\n${result.out}` : '',
+            result.value ? `value:\n${result.value}` : '',
+            result.err ? `stderr:\n${result.err}` : '',
+            result.exception ? `exception: ${result.exception}` : '',
+            result.error ? `error: ${result.error.code}` : '',
+            `status: ${result.ok ? 'ok' : 'error'}`,
+          ].filter(Boolean).join('\n')
+          return clip(body, cfg.maxOutputChars)
+        } catch (error) {
+          if (exec.signal.aborted) return '' // Host handles ABORTED.
+          const notes = error.notes?.length ? ` (${error.notes.join('; ')})` : ''
+          throw new Error(`Babashka runtime: ${error.message}${notes}. The session was reset; re-run with a fresh interpreter.`)
+        }
+      },
+      presentCall: args => ({ card: 'terminal', title: args.code.slice(0, 160) }),
+    }))
+  }
+
+  const registry = {
+    /**
+     * Register one domain manifest. A changed `version`/`stateVersion` for an
+     * already mounted id replaces it: live sessions rebuild before the next
+     * evaluation and the tool description is rebound.
+     */
+    register(manifest) {
+      const required = ['id', 'instructions']
+      for (const field of required) {
+        if (!manifest?.[field]) throw new Error(`Domain manifest requires ${required.join(', ')}`)
+      }
+      if (!manifest.classpath && !manifest.init) throw new Error(`Domain ${manifest.id} requires classpath or init`)
+      const next = {
+        ...manifest,
+        version: manifest.version ?? '0.0.0',
+        stateVersion: manifest.stateVersion ?? 0,
+      }
+      const previous = modules.get(next.id)
+      if (previous && previous.version === next.version && previous.stateVersion === next.stateVersion
+        && previous.classpath === next.classpath && previous.init === next.init
+        && previous.instructions === next.instructions) {
+        throw new Error(`Duplicate Babashka domain: ${next.id}@${next.version}`)
+      }
+      modules.set(next.id, next)
+      bindTool() // Tool description doubles as the SKILL.md-equivalent guide.
+      return () => {
+        if (modules.get(next.id) === next) modules.delete(next.id)
+        bindTool()
+      }
+    },
+    list: () => [...modules.values()].map(({ id, version, stateVersion, instructions }) => ({ id, version, stateVersion, instructions })),
+  }
+
+  ctx.provide('bbDomain', registry)
+  bindTool()
+  ctx.effect(() => async () => {
+    disposeTool?.()
+    await sessions.close()
+  }, 'bb-repl owner session cleanup')
+}

package/src/nrepl.js

@@ -0,0 +1,221 @@
+import net from 'node:net'
+import { randomUUID } from 'node:crypto'
+
+// Minimal bencode implementation for the nREPL wire protocol. No runtime deps.
+export function encode(value) {
+  if (typeof value === 'number') return Buffer.from(`i${value}e`)
+  if (typeof value === 'string') {
+    const b = Buffer.from(value, 'utf8')
+    return Buffer.concat([Buffer.from(`${b.length}:`), b])
+  }
+  if (Array.isArray(value)) return Buffer.concat([Buffer.from('l'), ...value.map(encode), Buffer.from('e')])
+  if (value && typeof value === 'object') {
+    const chunks = [Buffer.from('d')]
+    for (const key of Object.keys(value).sort()) {
+      if (value[key] === undefined || value[key] === null) continue
+      chunks.push(encode(key), encode(value[key]))
+    }
+    return Buffer.concat([...chunks, Buffer.from('e')])
+  }
+  throw new TypeError('Unsupported bencode value')
+}
+
+const MORE = Symbol('incomplete bencode frame')
+
+/** Text bytes one nREPL response contributes to a request's accumulated output. */
+function responseBytes(item) {
+  let total = 0
+  for (const field of ['out', 'err', 'value', 'ex']) {
+    const text = item[field]
+    if (typeof text === 'string') total += Buffer.byteLength(text)
+  }
+  return total
+}
+
+function parse(input, from = 0) {
+  if (from >= input.length) throw MORE
+  const marker = input[from]
+  if (marker === 105) { // i
+    const end = input.indexOf(101, from + 1)
+    if (end < 0) throw MORE
+    const raw = input.toString('ascii', from + 1, end)
+    if (!/^-?(0|[1-9][0-9]*)$/.test(raw)) throw new Error('Invalid bencode integer')
+    return [Number(raw), end + 1]
+  }
+  if (marker === 108 || marker === 100) { // l or d
+    const entries = []
+    let next = from + 1
+    while (true) {
+      if (next >= input.length) throw MORE
+      if (input[next] === 101) break
+      const [item, end] = parse(input, next)
+      entries.push(item)
+      next = end
+    }
+    if (marker === 108) return [entries, next + 1]
+    if (entries.length % 2 !== 0) throw new Error('Odd number of bencode dictionary entries')
+    const dict = {}
+    for (let i = 0; i < entries.length; i += 2) {
+      if (typeof entries[i] !== 'string' || ['__proto__', 'prototype', 'constructor'].includes(entries[i])) {
+        throw new Error('Invalid bencode dictionary key')
+      }
+      dict[entries[i]] = entries[i + 1]
+    }
+    return [dict, next + 1]
+  }
+  if (marker >= 48 && marker <= 57) {
+    const colon = input.indexOf(58, from)
+    if (colon < 0) throw MORE
+    const raw = input.toString('ascii', from, colon)
+    if (!/^(0|[1-9][0-9]*)$/.test(raw)) throw new Error('Invalid bencode string length')
+    const count = Number(raw)
+    if (!Number.isSafeInteger(count) || count > 32 * 1024 * 1024) throw new Error('nREPL string exceeds limit')
+    const end = colon + 1 + count
+    if (end > input.length) throw MORE
+    return [input.toString('utf8', colon + 1, end), end]
+  }
+  throw new Error('Invalid bencode marker')
+}
+
+export function decodeFrames(buffer) {
+  const results = []
+  let pos = 0
+  while (pos < buffer.length) {
+    try {
+      const [message, end] = parse(buffer, pos)
+      results.push(message)
+      pos = end
+    } catch (error) {
+      if (error === MORE) break
+      throw error
+    }
+  }
+  return { messages: results, rest: buffer.subarray(pos) }
+}
+
+// nREPL status values that mean the evaluation did not complete.
+const FAILURES = ['eval-error', 'namespace-not-found', 'error', 'unknown-op', 'session-missing']
+
+export class NReplClient {
+  /**
+   * @param socket - the connected nREPL socket.
+   * @param maxBufferBytes - cap for undecoded bytes waiting in the frame buffer.
+   * @param maxResponseBytes - cap for the text accumulated across the responses
+   *   of ONE request. Without it a program that keeps printing never finishes
+   *   collecting, because the caps on the frame buffer and on the final tool
+   *   output both apply only after the whole reply has been buffered.
+   */
+  constructor(socket, maxBufferBytes = 16 * 1024 * 1024, maxResponseBytes = 4 * 1024 * 1024) {
+    this.socket = socket
+    this.maxBufferBytes = maxBufferBytes
+    this.maxResponseBytes = maxResponseBytes
+    this.buffer = Buffer.alloc(0)
+    this.pending = new Map()
+    socket.on('data', bytes => this.onData(bytes))
+    socket.on('error', err => this.failAll(err))
+    socket.on('close', () => this.failAll(new Error('nREPL socket closed')))
+  }
+
+  /**
+   * Connect to an nREPL endpoint.
+   * @param port - loopback port the server listens on.
+   * @param signal - optional cancellation while connecting.
+   * @param options - optional `maxBufferBytes` / `maxResponseBytes` overrides.
+   */
+  static async connect(port, signal, options = {}) {
+    return await new Promise((resolve, reject) => {
+      const socket = net.createConnection({ host: '127.0.0.1', port })
+      let settled = false
+      const cleanup = () => signal?.removeEventListener('abort', onAbort)
+      const done = (fn, value) => {
+        if (settled) return
+        settled = true
+        cleanup()
+        fn(value)
+      }
+      const onAbort = () => {
+        socket.destroy()
+        done(reject, signal.reason ?? new Error('Aborted'))
+      }
+      signal?.addEventListener('abort', onAbort, { once: true })
+      socket.once('connect', () => done(resolve, new NReplClient(socket, options.maxBufferBytes, options.maxResponseBytes)))
+      socket.once('error', e => done(reject, e))
+      if (signal?.aborted) onAbort()
+    })
+  }
+
+  onData(data) {
+    try {
+      this.buffer = Buffer.concat([this.buffer, data])
+      if (this.buffer.length > this.maxBufferBytes) throw new Error('nREPL response exceeds buffer limit')
+      const { messages, rest } = decodeFrames(this.buffer)
+      this.buffer = Buffer.from(rest)
+      for (const item of messages) {
+        const wait = this.pending.get(item.id)
+        if (!wait) continue
+        wait.parts.push(item)
+        wait.bytes += responseBytes(item)
+        if (wait.bytes > this.maxResponseBytes) {
+          // Stop the flood for good: this request cannot be salvaged and the
+          // interpreter's state is unknown, so the caller resets the session.
+          this.pending.delete(item.id)
+          const error = new Error(`nREPL response exceeded ${this.maxResponseBytes} bytes; evaluation aborted`)
+          error.code = 'NREPL_OUTPUT_LIMIT'
+          error.truncated = true
+          wait.reject(error)
+          this.socket.destroy(error)
+          this.failAll(error)
+          return
+        }
+        if (Array.isArray(item.status) && item.status.includes('done')) {
+          this.pending.delete(item.id)
+          wait.resolve(wait.parts)
+        }
+      }
+    } catch (err) {
+      this.socket.destroy(err)
+      this.failAll(err)
+    }
+  }
+
+  failAll(error) {
+    for (const item of this.pending.values()) item.reject(error)
+    this.pending.clear()
+  }
+
+  request(fields) {
+    const id = randomUUID()
+    return new Promise((resolve, reject) => {
+      if (this.socket.destroyed) return reject(new Error('nREPL connection is closed'))
+      this.pending.set(id, { resolve, reject, parts: [], bytes: 0 })
+      try { this.socket.write(encode({ ...fields, id })) }
+      catch (e) { this.pending.delete(id); reject(e) }
+    })
+  }
+
+  async cloneSession() {
+    const responses = await this.request({ op: 'clone' })
+    const session = responses.find(x => x['new-session'])?.['new-session']
+    if (!session) throw new Error('nREPL server did not return a session id')
+    return session
+  }
+
+  async eval(session, code) {
+    const responses = await this.request({ op: 'eval', session, code })
+    const statuses = responses.flatMap(x => Array.isArray(x.status) ? x.status : [])
+    const failure = statuses.find(x => FAILURES.includes(x))
+    const err = responses.map(x => x.err ?? '').join('')
+    return {
+      ok: failure === undefined,
+      value: responses.filter(x => typeof x.value === 'string').map(x => x.value).join('\n'),
+      out: responses.map(x => x.out ?? '').join(''),
+      err,
+      exception: responses.find(x => x.ex)?.ex,
+      status: [...new Set(statuses)],
+      // Machine-readable failure identity, so callers do not have to parse text.
+      error: failure === undefined ? undefined : { code: failure, message: err.trim().split('\n')[0] ?? '' },
+    }
+  }
+
+  close() { this.socket.destroy() }
+}

package/src/sessions.js

@@ -0,0 +1,475 @@
+import { spawn } from 'node:child_process'
+import { createServer } from 'node:net'
+import { tmpdir } from 'node:os'
+import { dirname, join, delimiter, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { mkdtemp, readdir, readFile, rm } from 'node:fs/promises'
+import { NReplClient } from './nrepl.js'
+import { runtimeChildEnv } from './env.js'
+
+// domain.runtime ships with this package; a caller may add more, never less.
+const runtimeClasspath = resolve(dirname(fileURLToPath(import.meta.url)), '../bb-src')
+
+const sleep = ms => new Promise(r => setTimeout(r, ms))
+
+/** How long a session may take to die after SIGTERM before SIGKILL. */
+const TERM_GRACE_MS = 1500
+const GROUP_POLL_MS = 50
+
+/**
+ * Check whether the interpreter's process group still contains a runnable
+ * process. Linux /proc lets us ignore zombies (they cannot execute or write).
+ * Other POSIX systems use kill(0) against the group; Windows can only observe
+ * the direct child here.
+ */
+async function processGroupAlive(proc) {
+  if (!proc.pid) return false
+  if (process.platform === 'win32') return proc.exitCode === null && proc.signalCode === null
+  if (proc.exitCode === null && proc.signalCode === null) return true
+  if (process.platform === 'linux') {
+    try {
+      const pids = (await readdir('/proc')).filter(pid => /^\d+$/.test(pid))
+      const stats = await Promise.all(pids.map(pid =>
+        readFile(`/proc/${pid}/stat`, 'utf8').catch(() => null)))
+      let inspected = false
+      for (const stat of stats) {
+        if (!stat) continue
+        inspected = true
+        const close = stat.lastIndexOf(')')
+        if (close < 0) continue
+        const fields = stat.slice(close + 2).trim().split(/\s+/)
+        if (Number(fields[2]) === proc.pid && fields[0] !== 'Z' && fields[0] !== 'X') return true
+      }
+      if (inspected) return false
+    } catch {
+      // /proc may be unavailable in restricted containers; use kill(0) below.
+    }
+  }
+  try {
+    process.kill(-proc.pid, 0)
+    return true
+  } catch (error) {
+    if (error.code === 'ESRCH') return false
+    if (error.code === 'EPERM') return true
+    throw error
+  }
+}
+
+/** Signal the whole POSIX process group, even if its original leader has exited. */
+function signalTree(proc, signal) {
+  if (process.platform !== 'win32' && proc.pid) {
+    try { process.kill(-proc.pid, signal) }
+    catch (error) { if (error.code !== 'ESRCH') throw error }
+    return
+  }
+  if (proc.exitCode === null && proc.signalCode === null) {
+    try { proc.kill(signal) } catch (error) {
+      if (error.code !== 'ESRCH') throw error
+    }
+  }
+}
+
+/** Wait for the process group (not merely its leader) to stop running. */
+async function waitForTreeExit(proc, graceMs) {
+  const deadline = Date.now() + graceMs
+  while (await processGroupAlive(proc)) {
+    if (Date.now() >= deadline) return false
+    await sleep(GROUP_POLL_MS)
+  }
+  return true
+}
+
+/**
+ * Terminate one interpreter's process group: SIGTERM, wait for every runnable
+ * member to exit, then SIGKILL any survivors. The main child exiting is not
+ * sufficient: background children may outlive it.
+ */
+async function terminateTree(proc, onLog) {
+  if (!await processGroupAlive(proc)) return
+  signalTree(proc, 'SIGTERM')
+  if (await waitForTreeExit(proc, TERM_GRACE_MS)) return
+  onLog?.('Babashka process group still had live members after SIGTERM; sending SIGKILL')
+  signalTree(proc, 'SIGKILL')
+  if (!await waitForTreeExit(proc, TERM_GRACE_MS)) {
+    throw new Error('Babashka process group could not be terminated; refusing to start a new session')
+  }
+}
+const q = value => JSON.stringify(value) // strings use Clojure-compatible JSON escaping
+
+/** Stable identity of a mounted domain implementation, used to detect hot swaps. */
+const signature = m => [m.version ?? '', m.stateVersion ?? '', m.classpath ?? '', m.init ?? ''].join('\u0000')
+const label = m => `${m.id}@${m.version ?? '0.0.0'}`
+
+async function freeLocalPort() {
+  const server = createServer()
+  try {
+    await new Promise((resolve, reject) => {
+      server.once('error', reject)
+      server.listen(0, '127.0.0.1', resolve)
+    })
+    return server.address().port
+  } finally { await new Promise(r => server.close(r)) }
+}
+
+/**
+ * Per-Agent Babashka + nREPL sessions.
+ *
+ * Everything about *how* the child process is launched (sandbox confinement,
+ * environment policy) is supplied by the plugin: this class only decides when a
+ * session starts, which domains it carries, and when it must be rebuilt.
+ */
+export class DomainSessions {
+  constructor({
+    bbExecutable = 'bb', startupMs = 12000, timeoutMs = 120000, moduleSyncMs,
+    runtimeClasspath: extraRuntimeClasspath = '', modules, onLog = () => {}, confine, policyFor,
+  }) {
+    this.bbExecutable = bbExecutable
+    this.startupMs = startupMs
+    this.timeoutMs = timeoutMs
+    // Hot-loading a domain runs real Clojure before the user code deadline
+    // starts; bound it so a domain that hangs cannot block the Agent forever.
+    this.moduleSyncMs = moduleSyncMs ?? Math.min(startupMs, 30000)
+    this.runtimeClasspath = [runtimeClasspath, extraRuntimeClasspath].filter(Boolean).join(delimiter)
+    this.modules = modules
+    this.onLog = onLog
+    this.confine = confine
+    // Resolved per evaluation so a session-mode change rebuilds the process.
+    this.policyFor = policyFor
+    this.live = new Map()
+    this.pending = new WeakMap()
+    this.queues = new WeakMap()
+    this.creating = new Set()
+    // Owners already wired to a lifecycle cleanup; a rebuilt session must not
+    // register a second disposer for the same Agent.
+    this.owned = new WeakSet()
+    this.disposed = false
+  }
+
+  spawnArgv(manifests, port) {
+    const classpath = [this.runtimeClasspath, ...manifests.map(m => m.classpath)].filter(Boolean).join(delimiter)
+    return [this.bbExecutable, ...(classpath ? ['--classpath', classpath] : []), 'nrepl-server', `127.0.0.1:${port}`]
+  }
+
+  /** Register a mounted domain with domain.runtime so the Agent can inspect it. */
+  domainRegistration(m) {
+    const fields = [
+      `:id ${q(m.id)}`,
+      `:version ${q(String(m.version ?? '0.0.0'))}`,
+      `:state-version ${q(String(m.stateVersion ?? 0))}`,
+      `:instructions ${q(m.instructions)}`,
+    ]
+    if (m.statusVar) fields.push(`:status (requiring-resolve '${m.statusVar})`)
+    return `(domain.runtime/register! {${fields.join(' ')}})`
+  }
+
+  async start(owner, workspace, signal, policy) {
+    if (this.disposed) throw new Error('Babashka runtime disposed')
+    signal?.throwIfAborted()
+    const scratch = await mkdtemp(join(tmpdir(), 'dsh-bb-'))
+    const port = await freeLocalPort()
+    const manifests = this.modules()
+    const argv = this.spawnArgv(manifests, port)
+    let launched = { argv, policy: policy ?? { mode: 'danger-full-access' } }
+    try {
+      if (this.confine) launched = await this.confine({ argv, workspaceRoot: resolve(workspace), owner, policy, signal })
+      signal?.throwIfAborted()
+    } catch (error) {
+      await rm(scratch, { recursive: true, force: true })
+      throw error
+    }
+    const proc = spawn(launched.argv[0], launched.argv.slice(1), {
+      cwd: scratch,
+      env: runtimeChildEnv({ workspace: resolve(workspace), scratch, port }),
+      stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true,
+      // Own process group, so termination reaches the JVM and every child it
+      // forked (rg, git, diff, shells) instead of just the JVM.
+      detached: process.platform !== 'win32',
+    })
+    let startupLog = ''
+    let exitError
+    const append = data => { startupLog = (startupLog + String(data)).slice(-4000) }
+    proc.stdout.on('data', append)
+    proc.stderr.on('data', append)
+    proc.on('error', err => { exitError = err })
+    proc.on('exit', (code, sig) => { exitError = new Error(`Babashka exited (code ${code}, signal ${sig})`) })
+    const session = {
+      proc, client: undefined, sessionId: '', workspace: resolve(workspace), scratch,
+      modules: new Map(), policyKey: policy?.key ?? 'unconfined', sandbox: launched.policy ?? null,
+      enforcement: launched.enforcement,
+    }
+    // An unexpected leader exit does not prove its children are gone. Run the
+    // same process-group shutdown path used by reset() before releasing scratch.
+    proc.once('exit', () => {
+      void this.stopSession(owner, session).catch(error => this.onLog(String(error?.message ?? error)))
+    })
+    let client
+    try {
+      const deadline = Date.now() + this.startupMs
+      while (Date.now() < deadline) {
+        if (signal?.aborted) throw signal.reason ?? new Error('Cancelled')
+        if (exitError) throw exitError
+        try { client = await NReplClient.connect(port, signal); break }
+        catch (e) { if (signal?.aborted) throw e; await sleep(80) }
+      }
+      if (!client) throw new Error(`nREPL startup timeout: ${startupLog}`)
+      session.client = client
+      await this.bounded(async () => {
+        session.sessionId = await client.cloneSession()
+        const init = [
+          // `domain` is the session runtime facade; the alias lives in the
+          // session's own namespace so the Agent can call (domain/status).
+          `(require '[domain.runtime :as domain])`,
+          ...manifests.map(m => m.init).filter(Boolean),
+          ...manifests.map(m => this.domainRegistration(m)),
+          ':ready',
+        ]
+        const res = await client.eval(session.sessionId, `(do ${init.join(' ')})`)
+        if (!res.ok) throw new Error(`Domain namespace initialization failed: ${res.err || res.exception || res.status.join(', ')}`)
+        for (const m of manifests) session.modules.set(m.id, { signature: signature(m), version: m.version })
+      }, this.startupMs, 'nREPL session initialization', signal)
+      if (proc.exitCode !== null || proc.signalCode !== null || session.reaped) {
+        throw exitError ?? new Error('Babashka exited during session initialization')
+      }
+      this.live.set(owner, session)
+      if (!this.owned.has(owner)) {
+        this.owned.add(owner)
+        owner.ctx?.effect?.(() => () => { void this.reset(owner).catch(error => this.onLog(String(error?.message ?? error))) }, 'dsh-bb owner session cleanup')
+      }
+      return session
+    } catch (error) {
+      client?.close()
+      const message = `${error.message}${startupLog ? `\n${startupLog}` : ''}`
+      try {
+        await this.stopSession(owner, session)
+      } catch (cleanupError) {
+        // Keep an unkillable session registered: ensure() will retry cleanup and
+        // must never start another interpreter beside this unknown process group.
+        this.live.set(owner, session)
+        throw new Error(`${message}; cleanup failed: ${cleanupError.message}`)
+      }
+      throw new Error(message)
+    }
+  }
+
+  /** Stop a session once; concurrent exit/reset paths share the same promise. */
+  async stopSession(owner, session) {
+    if (session.cleanupPromise) return session.cleanupPromise
+    const cleanup = (async () => {
+      session.client?.close()
+      await terminateTree(session.proc, this.onLog)
+      await this.reap(owner, session)
+    })()
+    session.cleanupPromise = cleanup
+    try {
+      await cleanup
+    } catch (error) {
+      session.cleanupPromise = undefined
+      // Quarantine the owner until a later call can confirm the group is gone.
+      if (!this.live.has(owner) || this.live.get(owner) === session) this.live.set(owner, session)
+      throw error
+    }
+  }
+  /** Release one session's resources exactly once, whatever killed the process. */
+  async reap(owner, session) {
+    if (session.reaped) return
+    session.reaped = true
+    if (this.live.get(owner) === session) this.live.delete(owner)
+    session.client?.close()
+    await rm(session.scratch, { recursive: true, force: true }).catch(e => this.onLog(String(e)))
+  }
+
+  /**
+   * Run `work` under a deadline and an abort signal.
+   * Used for module synchronization, which must not outlive a tool call.
+   */
+  async bounded(work, ms, label, signal) {
+    signal?.throwIfAborted()
+    let timer
+    let aborted
+    const deadline = new Promise((_, reject) => {
+      timer = setTimeout(() => reject(new Error(`${label} timed out`)), ms)
+      aborted = () => reject(signal?.reason ?? new Error(`${label} aborted`))
+      signal?.addEventListener('abort', aborted, { once: true })
+      if (signal?.aborted) aborted()
+    })
+    try {
+      // Defer work until after the abort listener is installed.
+      return await Promise.race([Promise.resolve().then(work), deadline])
+    } finally {
+      clearTimeout(timer)
+      signal?.removeEventListener('abort', aborted)
+    }
+  }
+
+  async ensure(owner, workspace, signal, policy) {
+    const existing = this.live.get(owner)
+    if (existing) {
+      const mustStop = existing.cleanupPromise || existing.proc.killed
+        || existing.proc.exitCode !== null || existing.proc.signalCode !== null
+        || existing.workspace !== resolve(workspace)
+        || existing.policyKey !== (policy?.key ?? 'unconfined')
+      if (mustStop) await this.stopSession(owner, existing)
+      else return existing
+    }
+    const pending = this.pending.get(owner)
+    if (pending) return pending
+    const creation = this.start(owner, workspace, signal, policy).finally(() => {
+      this.pending.delete(owner)
+      this.creating.delete(creation)
+    })
+    this.creating.add(creation)
+    this.pending.set(owner, creation)
+    return creation
+  }
+
+  /**
+   * Reconcile the live session with the currently registered domains.
+   * - new domain: add classpath and load it, keeping session state;
+   * - changed or removed domain: report a rebuild so the caller resets before
+   *   evaluating, instead of failing the call and making the Agent retry.
+   */
+  async syncModules(session) {
+    const active = new Map(this.modules().map(m => [m.id, m]))
+    const removed = [...session.modules.keys()].filter(id => !active.has(id))
+    const changed = [...active.values()].filter(m => {
+      const known = session.modules.get(m.id)
+      return known && known.signature !== signature(m)
+    })
+    if (removed.length || changed.length) {
+      const parts = []
+      if (removed.length) parts.push(`removed ${removed.join(', ')}`)
+      if (changed.length) {
+        parts.push(changed.map(m => `${m.id} changed to ${m.version ?? '0.0.0'} (state version ${m.stateVersion ?? 0})`).join(', '))
+      }
+      return { reset: parts.join('; '), added: [] }
+    }
+    const added = [...active.values()].filter(m => !session.modules.has(m.id))
+    for (const m of added) {
+      if (m.classpath) {
+        const res = await session.client.eval(session.sessionId,
+          `(do (require 'babashka.classpath) (babashka.classpath/add-classpath ${q(m.classpath)}) :classpath-added)`)
+        if (!res.ok) throw new Error(`Cannot hot-load classpath ${m.id}: ${res.err}`)
+      }
+      if (m.init) {
+        const res = await session.client.eval(session.sessionId, m.init)
+        if (!res.ok) throw new Error(`Cannot hot-load domain ${m.id}: ${res.err}`)
+      }
+      const reg = await session.client.eval(session.sessionId, this.domainRegistration(m))
+      if (!reg.ok) throw new Error(`Cannot register domain ${m.id}: ${reg.err}`)
+      session.modules.set(m.id, { signature: signature(m), version: m.version })
+    }
+    return { reset: null, added: added.map(m => label(m)) }
+  }
+
+  /** Reset detection for a session the Agent deliberately discarded (domain.runtime/reset!). */
+  static isResetRequest(result) {
+    const text = [result?.err, result?.exception, result?.out].filter(Boolean).join('\n')
+    return /DSH_BB_RESET:/.test(text)
+  }
+
+  async evaluate(owner, workspace, code, signal, explicitPolicy) {
+    const prior = this.queues.get(owner) ?? Promise.resolve()
+    const work = prior.then(async () => {
+      if (signal?.aborted) throw signal.reason ?? new Error('Cancelled')
+      const policy = explicitPolicy ?? this.policyFor?.(owner, workspace)
+      const notes = []
+      const syncOnce = async session => this.bounded(
+        () => this.syncModules(session), this.moduleSyncMs, 'Domain synchronization', signal)
+      let session
+      let sync
+      try {
+        session = await this.ensure(owner, workspace, signal, policy)
+        sync = await syncOnce(session)
+        if (sync.reset) {
+          notes.push(`session rebuilt: ${sync.reset}`)
+          await this.reset(owner)
+          session = await this.ensure(owner, workspace, signal, policy)
+          sync = await syncOnce(session)
+        }
+      } catch (error) {
+        // Promise.race does not cancel a timed-out module init. Closing its
+        // nREPL socket and killing the process group is the cancellation.
+        let reset = false
+        try {
+          await this.reset(owner)
+          reset = true
+        } catch (resetError) {
+          error.message = `${error.message} (${resetError.message})`
+        }
+        notes.push(reset
+          ? 'session reset: domain synchronization failed'
+          : 'session cleanup failed; owner quarantined')
+        error.notes = notes
+        throw error
+      }
+      if (sync.added.length) notes.push(`domain hot-loaded: ${sync.added.join(', ')}`)
+      let timeoutId
+      let aborted
+      try {
+        const result = await Promise.race([
+          session.client.eval(session.sessionId, code),
+          new Promise((_, reject) => {
+            timeoutId = setTimeout(() => reject(new Error('Babashka evaluation timed out')), this.timeoutMs)
+            aborted = () => reject(signal?.reason ?? new Error('Evaluation aborted'))
+            signal?.addEventListener('abort', aborted, { once: true })
+            if (signal?.aborted) aborted()
+          }),
+        ])
+        if (!result.ok && DomainSessions.isResetRequest(result)) {
+          await this.reset(owner)
+          notes.push('session reset: requested by domain.runtime/reset!')
+          return { ...result, notes, sessionReset: true }
+        }
+        return { ...result, notes: [...notes, ...(result.notes ?? [])], sessionReset: false }
+      } catch (error) {
+        // Timeout, abort or any transport failure leaves unknown interpreter state.
+        let reset = false
+        try {
+          await this.reset(owner)
+          reset = true
+        } catch (resetError) {
+          error.message = `${error.message} (${resetError.message})`
+        }
+        notes.push(reset
+          ? 'session reset: previous interpreter state discarded'
+          : 'session cleanup failed; owner quarantined')
+        error.notes = notes
+        throw error
+      } finally {
+        clearTimeout(timeoutId)
+        signal?.removeEventListener('abort', aborted)
+      }
+    })
+    const tail = work.then(() => {}, () => {})
+    this.queues.set(owner, tail)
+    try { return await work } finally { if (this.queues.get(owner) === tail) this.queues.delete(owner) }
+  }
+
+  /**
+   * Stop one Agent's interpreter and wait until it is really gone.
+   *
+   * The nREPL socket is closed first so an in-flight evaluation cannot deliver
+   * more output, then the whole process group is terminated and awaited. Only
+   * after the exit is confirmed do we delete the scratch directory and let the
+   * next call start a fresh process: overlapping writers are the failure this
+   * ordering exists to prevent.
+   */
+  async reset(owner) {
+    const session = this.live.get(owner)
+    if (!session) return
+    try {
+      await this.stopSession(owner, session)
+    } catch (error) {
+      // Keep the session quarantined when any process-group member survives.
+      this.onLog(String(error?.message ?? error))
+      throw error
+    }
+  }
+
+  async close() {
+    this.disposed = true
+    await Promise.allSettled([...this.creating])
+    await Promise.allSettled([...new Set([...this.live.keys()])].map(owner => this.reset(owner)))
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.