@deepblend/dsh-blender-provider-local 0.2.3 → 0.2.5

package/lib/index.js

@@ -21,6 +21,7 @@
 
 import { spawnSync } from 'node:child_process'
 import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import net from 'node:net'
 import { readFile } from 'node:fs/promises'
 import { delimiter, isAbsolute, join, resolve, sep } from 'node:path'
 import { randomUUID } from 'node:crypto'
@@ -154,6 +155,352 @@ export const ProviderConfig = z.object({
  * @property {string} workingDirectory
  */
 
+/** How long an attached Blender gets to say hello before the attach is called a failure. */
+const ATTACH_READY_MS = 10_000
+
+/**
+ * Connect to a Unix socket, with a deadline.
+ *
+ * The add-on may be starting when the product asks — a user enables it and the product is already
+ * polling — so this retries inside one deadline rather than failing on the first refusal.
+ *
+ * @param {string} socketPath
+ * @param {number} timeoutMs
+ * @returns {Promise<import('node:net').Socket>}
+ */
+async function connect(socketPath, timeoutMs) {
+  const deadline = Date.now() + Math.min(timeoutMs, 10_000)
+  let lastError = null
+  for (;;) {
+    const socket = await new Promise(resolve => {
+      const candidate = net.connect(socketPath)
+      candidate.once('connect', () => resolve(candidate))
+      candidate.once('error', error => {
+        lastError = error
+        candidate.destroy()
+        resolve(null)
+      })
+    })
+    if (socket !== null) return socket
+    if (Date.now() >= deadline) throw lastError ?? new Error('no answer')
+    await new Promise(settle => setTimeout(settle, 250))
+  }
+}
+
+/**
+ * A live Blender, presented as one shape whatever carries the bytes.
+ *
+ * WHY THE SEAM EXISTS. A session can be carried two ways, and both are real: the process this
+ * provider SPAWNS (`--background`, pipes on stdin/stdout) and the Blender a USER is looking at (the
+ * add-on's socket). The conversation — the handshake, the per-request deadline, matching an answer to
+ * its request — is identical, and the only thing that differs is who owns the other end. Writing it
+ * twice would mean two places to fix the next bug in the deadline, and the second one would be the
+ * one nobody runs.
+ *
+ * The subprocess adapter and the socket adapter below are the whole of the difference.
+ */
+class SubprocessTransport {
+  /** @param {object} handle from `ctx.subprocess.spawn` */
+  constructor(handle) {
+    this.handle = handle
+    this.read = handle.stdout
+    this.onExit = callback => handle.done?.then?.(() => callback({}), () => callback({}))
+    this.pid = null
+  }
+
+  write(text) {
+    this.handle.stdin.write(text)
+  }
+
+  end() {
+    try {
+      this.handle.stdin.end()
+    } catch {
+      // Already gone; the exit callback is what decides.
+    }
+  }
+
+  /** Wait for the process to be gone, bounded. */
+  async settle(graceMs) {
+    try {
+      await this.handle.waitForExit?.(graceMs)
+    } catch {
+      // A process that had to be terminated is still a settled one.
+    }
+  }
+}
+
+class SocketTransport {
+  /**
+   * @param {import('node:net').Socket} socket
+   * @param {{ pid?: number|null }} [info]
+   */
+  constructor(socket, info = {}) {
+    this.socket = socket
+    this.read = socket
+    // The pid is the ATTACHED Blender's own, from its handshake — never this process's. A product that
+    // reported its own pid here would make "which Blender answered" unanswerable, which is the one
+    // question an attach exists to answer.
+    this.pid = info.pid ?? null
+    this.exitCallbacks = []
+    socket.on('close', () => {
+      for (const callback of this.exitCallbacks) callback({})
+    })
+    socket.on('error', () => {
+      // An error closes the socket, and the close handler reports it. Swallowing it here keeps a
+      // broken pipe from becoming an unhandled 'error' event, which would take the host down.
+    })
+  }
+
+  onExit(callback) {
+    this.exitCallbacks.push(callback)
+  }
+
+  write(text) {
+    this.socket.write(text)
+  }
+
+  end() {
+    try {
+      this.socket.end()
+    } catch {
+      // Already closed.
+    }
+  }
+
+  async settle() {
+    this.socket.destroy()
+  }
+}
+
+/**
+ * One live Blender process, serving requests until it is closed (SPEC §20 M6).
+ *
+ * The class exists so the SESSION's own lifecycle — the handshake, the per-request deadline, the
+ * "the process is gone" answer, and the shutdown — is one object with one state, rather than a set of
+ * promises the provider keeps in a map. Everything about an individual action still belongs to
+ * `bootstrap.py`'s `ACTIONS`; this only carries the conversation.
+ *
+ * LINE PROTOCOL. bootstrap.py writes one JSON document per line to stdout, and it already did before
+ * sessions existed: `report_progress` sends `{"type": "progress", …}` (SPEC §9.3) and a session sends
+ * `{"kind": "ready"|"result"|"bye", …}`. The two are distinguishable BY PARSING rather than by
+ * pattern-matching prose, which is the property that made progress lines safe to add in the first
+ * place.
+ */
+class BlenderSession {
+  /**
+   * @param {{ transport: SubprocessTransport|SocketTransport, directory: string|null, jobId: string, timeoutMs: number, onClose: () => void }} input
+   */
+  constructor(input) {
+    this.transport = input.transport
+    this.handle = input.transport.handle ?? null
+    this.directory = input.directory
+    this.jobId = input.jobId
+    this.timeoutMs = input.timeoutMs
+    this.onClose = input.onClose
+    // THE HANDLE HAS NO `pid`, MEASURED: its keys are `stdin`, `stdout`, `stderr`, `collected`,
+    // `done`, `terminate`, `terminateForHostExit`, `waitForExit`. So the pid comes from the process
+    // itself, in the `ready` line bootstrap.py opens with — which is better evidence anyway, because
+    // it is the pid the script believes it is rather than the one the spawn returned.
+    this.pid = input.transport.pid ?? null
+    /** @type {Map<string, {resolve: Function, reject: Function, timer: object}>} */
+    this.waiting = new Map()
+    this.progress = []
+    /** Whether the process said goodbye before it went: the difference between a shutdown and a death. */
+    this.saidBye = false
+    this.stderr = ''
+    this.closed = false
+    this.readyPromise = null
+    this.readyResolve = null
+    this.readyReject = null
+    this.readySettled = false
+    this._read()
+  }
+
+  /**
+   * Resolve when the other end has announced itself — reject if it dies first, or says nothing.
+   *
+   * THE DEADLINE IS THE POINT, and a mutation found it missing: with the handshake removed from the
+   * bridge, `attachSession` connected successfully and then waited FOREVER, because the socket stayed
+   * open and simply never spoke. A hang is worse than either a success or a coded failure — it has no
+   * message, no code, and no end — and this repository's rule is that a failure has to be a branchable
+   * result. The same deadline that bounds a request bounds the opening of the conversation.
+   */
+  ready(timeoutMs = this.timeoutMs) {
+    if (this.readyPromise === null) {
+      this.readyPromise = new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+          if (this.readySettled) return
+          this.readySettled = true
+          reject(new BlenderError(
+            BlenderErrorCode.TIMEOUT,
+            `The Blender session (pid ${this.pid ?? 'unknown'}) connected but never announced itself within ${timeoutMs} ms.`,
+            { detail: { pid: this.pid, timeoutMs } },
+          ))
+        }, timeoutMs)
+        if (typeof timer.unref === 'function') timer.unref()
+        this.readyResolve = value => {
+          clearTimeout(timer)
+          this.readySettled = true
+          resolve(value)
+        }
+        this.readyReject = error => {
+          clearTimeout(timer)
+          this.readySettled = true
+          reject(error)
+        }
+      })
+    }
+    return this.readyPromise
+  }
+
+  /** Read stdout line by line for the life of the process. */
+  _read() {
+    const stream = this.transport.read
+    if (stream === undefined || stream === null) {
+      this._fail(new BlenderError(BlenderErrorCode.SPAWN_FAILED, 'the session has no stdout stream to read'))
+      return
+    }
+    let buffer = ''
+    stream.on('data', chunk => {
+      buffer += chunk.toString('utf8')
+      let index = buffer.indexOf('\n')
+      while (index >= 0) {
+        const line = buffer.slice(0, index).trim()
+        buffer = buffer.slice(index + 1)
+        if (line.length > 0) this._line(line)
+        index = buffer.indexOf('\n')
+      }
+    })
+    this.handle?.stderr?.on?.('data', chunk => {
+      // Bounded: stderr is evidence for a failure, not a log to keep.
+      this.stderr = (this.stderr + chunk.toString('utf8')).slice(-8192)
+    })
+    // THE TRANSPORT REPORTS THE END, whatever the end means: for a spawned process the handle's
+    // `done` promise, for a socket its 'close'. Neither carries a code — the failure below says what
+    // is knowable, which is that the session ended without answering.
+    this.transport.onExit(info => this._exited(info))
+  }
+
+  _line(line) {
+    let document
+    try {
+      document = JSON.parse(line)
+    } catch {
+      // Blender itself prints to stdout; anything that is not a JSON document is not ours.
+      return
+    }
+    if (document?.type === 'progress') {
+      this.progress.push(document)
+      return
+    }
+    if (document?.kind === 'ready') {
+      if (typeof document.pid === 'number') this.pid = document.pid
+      this.readyResolve?.(this)
+      return
+    }
+    if (document?.kind === 'bye') {
+      this.saidBye = true
+      return
+    }
+    const jobId = document?.jobId
+    const pending = typeof jobId === 'string' ? this.waiting.get(jobId) : undefined
+    if (pending === undefined) return
+    clearTimeout(pending.timer)
+    this.waiting.delete(jobId)
+    pending.resolve(document)
+  }
+
+  _fail(error) {
+    this.readyReject?.(error)
+    for (const [, pending] of this.waiting) {
+      clearTimeout(pending.timer)
+      pending.reject(error)
+    }
+    this.waiting.clear()
+  }
+
+  _exited(info) {
+    if (this.closed) return
+    this.closed = true
+    const detail = this.stderr.trim().length > 0 ? ` stderr: ${this.stderr.trim().slice(-500)}` : ''
+    this._fail(new BlenderError(
+      BlenderErrorCode.NONZERO_EXIT,
+      `the Blender session (pid ${this.pid ?? 'unknown'}) ended before answering${info?.code === undefined ? '' : ` (exit ${info.code})`}.${detail}`,
+      { detail: { pid: this.pid, code: info?.code ?? null, signal: info?.signal ?? null } },
+    ))
+  }
+
+  /**
+   * Run one action in the live process.
+   *
+   * @param {{ action: string, payload?: object, jobId?: string }} request
+   * @param {{ signal?: AbortSignal }} [options]
+   * @returns {Promise<object>} the envelope bootstrap.py built for it.
+   */
+  async run(request, options = {}) {
+    if (this.closed) {
+      throw new BlenderError(
+        BlenderErrorCode.NONZERO_EXIT,
+        `the Blender session (pid ${this.pid ?? 'unknown'}) is closed, so "${request?.action}" was not sent.`,
+      )
+    }
+    const jobId = typeof request.jobId === 'string' && request.jobId.length > 0 ? request.jobId : `${this.jobId}-${this.waiting.size + 1}`
+    const document = {
+      protocolVersion: BLENDER_PROTOCOL_VERSION,
+      jobId,
+      action: request.action,
+      ...(request.payload !== undefined ? { payload: request.payload } : {}),
+    }
+
+    const answered = new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.waiting.delete(jobId)
+        reject(new BlenderError(
+          BlenderErrorCode.TIMEOUT,
+          `the Blender session did not answer "${request.action}" within ${this.timeoutMs} ms.`,
+          { detail: { jobId, action: request.action, pid: this.pid } },
+        ))
+      }, this.timeoutMs)
+      if (typeof timer.unref === 'function') timer.unref()
+      this.waiting.set(jobId, { resolve, reject, timer })
+      if (options.signal !== undefined) {
+        options.signal.addEventListener('abort', () => {
+          if (!this.waiting.has(jobId)) return
+          clearTimeout(timer)
+          this.waiting.delete(jobId)
+          reject(new BlenderError(
+            BlenderErrorCode.ABORTED,
+            `"${request.action}" was aborted before the Blender session answered.`,
+            { detail: { jobId, action: request.action, pid: this.pid } },
+          ))
+        }, { once: true })
+      }
+    })
+
+    this.transport.write(`${JSON.stringify(document)}\n`)
+    return answered
+  }
+
+  /** Ask the process to stop, and wait for it. Idempotent. */
+  async close() {
+    if (this.closed) return
+    try {
+      this.transport.write(`${JSON.stringify({ action: 'shutdown' })}\n`)
+      this.transport.end()
+    } catch {
+      // The other end may already be gone; the settle below is what decides.
+    }
+    await this.transport.settle(TERMINATE_GRACE_MS)
+    this.closed = true
+    this._fail(new BlenderError(
+      BlenderErrorCode.ABORTED,
+      `the Blender session (pid ${this.pid ?? 'unknown'}) was closed by its caller.`,
+    ))
+    this.onClose()
+  }
+}
+
 /**
  * Local Blender provider.
  *
@@ -419,6 +766,141 @@ export default class LocalBlenderRuntime extends Service {
    * }} [options]
    * @returns {Promise<BootstrapRunOutcome>}
    */
+  /**
+   * Open a LIVE SESSION: one Blender process that answers many requests (SPEC §20 M6).
+   *
+   * WHY THIS EXISTS. Every other method here is one process per operation —
+   * `blender --background --factory-startup --python bootstrap.py -- --request … --result …` —
+   * which loads the scene, does the thing, and exits. That is right for a render and wrong for a
+   * conversation: opening a scene costs seconds, and a caller that compiles, previews and compiles
+   * again pays it every time. MEASURED on this machine: `get_capabilities` alone is ~1.4 s of
+   * process start, and `compile_scene` on the demo project is dominated by scene load.
+   *
+   * WHAT IT IS NOT. This is the TRANSPORT half of the M6 item, not the item: the GUI attach — the
+   * user's own Blender, with the add-on, so they can watch it work — is the next thing on that list.
+   * What this establishes is what everything else rests on: one Blender, many operations, each one
+   * attributable to a pid and each one able to fail on its own.
+   *
+   * THE PROTOCOL is bootstrap.py's own, unchanged: the same request document shape, the same
+   * `ACTIONS` table, the same envelope. A second implementation of "what does compile_scene do"
+   * would be a second answer to that question, so there is only ever one.
+   *
+   * @param {{ cwd?: string, args?: string[], signal?: AbortSignal }} [options]
+   * @returns {Promise<{ pid: number|null, run: (request: object, options?: object) => Promise<object>, close: () => Promise<void> }>}
+   */
+  async openSession(options = {}) {
+    if (!existsSync(this.bootstrapPath)) {
+      throw new BlenderError(
+        BlenderErrorCode.BOOTSTRAP_MISSING,
+        `bootstrap.py not found at ${this.bootstrapPath}.`,
+      )
+    }
+    const resolvedExecutable = await this.resolveBlenderExecutable({ signal: options.signal })
+    if (resolvedExecutable.error !== null || resolvedExecutable.resolved === null) {
+      throw resolvedExecutable.error ?? new BlenderError(
+        BlenderErrorCode.NOT_FOUND,
+        `Blender executable could not be resolved from "${resolvedExecutable.requested}".`,
+      )
+    }
+
+    const { jobId, directory } = this._createWorkingDirectory()
+    const argv = [
+      resolvedExecutable.resolved,
+      '--background',
+      '--factory-startup',
+      '--python',
+      this.bootstrapPath,
+      '--',
+      // `--session=1` rather than a bare `--session`: `parse_args` reads `--opt value` PAIRS, so a
+      // valueless flag would swallow the next token as its value. The session needs no value, so it
+      // carries the smallest one that cannot be mistaken for something else.
+      '--session=1',
+      ...(options.args ?? []),
+    ]
+
+    const handle = this.ctx.subprocess.spawn({
+      argv,
+      cwd: options.cwd ?? directory,
+      stdio: {
+        // THE DIFFERENCE FROM EVERY OTHER CALL IN THIS FILE. Batch mode ignores stdin and collects
+        // stdout into a bounded tail; a session needs both as live pipes, because the conversation
+        // IS the pipes.
+        stdin: 'pipe',
+        stdout: 'pipe',
+        stderr: { maxBytes: this.config.maxOutputBytes, spill: { maxBytes: this.config.maxSpillBytes } },
+      },
+      graceMs: TERMINATE_GRACE_MS,
+      signal: options.signal,
+    })
+
+    const session = new BlenderSession({
+      transport: new SubprocessTransport(handle),
+      directory,
+      jobId,
+      timeoutMs: this.config.timeoutMs,
+      onClose: () => this._cleanup(directory),
+    })
+    await session.ready()
+    return session
+  }
+
+  /**
+   * Attach to a Blender that is ALREADY RUNNING — the user's own, with the add-on (SPEC §20 M6).
+   *
+   * THE OTHER HALF OF THE LIVE BRIDGE. `openSession()` spawns a Blender nobody can see; this one talks
+   * to the Blender on the user's screen, so the operations happen in the window they are looking at.
+   * The conversation is identical — same protocol, same envelopes, same per-request deadline — because
+   * both go through `BlenderSession`; the only difference is who owns the other end of the bytes.
+   *
+   * The pid in the handshake is the ATTACHED Blender's own, and it is what makes "which Blender
+   * answered this" answerable. A product that reported its own pid here would make that question
+   * unanswerable, which is the one question an attach exists to answer.
+   *
+   * @param {string} socketPath
+   * @param {{ timeoutMs?: number }} [options]
+   * @returns {Promise<{ pid: number|null, run: Function, close: Function }>}
+   */
+  async attachSession(socketPath, options = {}) {
+    if (typeof socketPath !== 'string' || socketPath.length === 0) {
+      throw new BlenderError(
+        BlenderErrorCode.RUNTIME_UNAVAILABLE,
+        'Attaching needs the socket path the Blender add-on is listening on.',
+      )
+    }
+    if (!existsSync(socketPath)) {
+      throw new BlenderError(
+        BlenderErrorCode.RUNTIME_UNAVAILABLE,
+        `Nothing is listening at ${socketPath}. Enable the DeepBlend bridge add-on in Blender ` +
+          '(View3D > Sidebar > DeepBlend), or start one headless with ' +
+          '`blender --background --python deepblend_bridge.py -- --socket <path>`.',
+        { detail: { socketPath } },
+      )
+    }
+
+    const socket = await connect(socketPath, options.timeoutMs ?? this.config.timeoutMs).catch(cause => {
+      throw new BlenderError(
+        BlenderErrorCode.RUNTIME_UNAVAILABLE,
+        `The Blender bridge at ${socketPath} could not be reached: ${cause?.message ?? 'unknown failure'}.`,
+        { detail: { socketPath } },
+      )
+    })
+
+    const session = new BlenderSession({
+      transport: new SocketTransport(socket),
+      directory: null,
+      jobId: `attach-${randomUUID()}`,
+      timeoutMs: this.config.timeoutMs,
+      onClose: () => {},
+    })
+    // A SHORTER DEADLINE THAN A SPAWN, and the difference is real rather than a preference: a spawned
+    // Blender legitimately takes a second or two to boot, while an add-on that is already serving
+    // answers the handshake immediately. MEASURED: with the provider's own 180 s timeout, a peer that
+    // connected and said nothing took 180 s to report — long enough that a user would conclude the
+    // product had hung.
+    await session.ready(ATTACH_READY_MS)
+    return session
+  }
+
   async runBootstrap(request, options = {}) {
     const action = request?.action
     if (typeof action !== 'string' || action.length === 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepblend/dsh-blender-provider-local",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "type": "module",
   "description": "Local Blender Provider: the BlenderRuntime Service over ctx.subprocess (batch execution).",
   "main": "lib/index.js",
@@ -11,7 +11,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@deepblend/dsh-blender-contracts": "0.2.3"
+    "@deepblend/dsh-blender-contracts": "0.2.5"
   },
   "license": "MIT",
   "repository": {

package/python/bootstrap.py

@@ -492,6 +492,114 @@ def scene_fingerprint(spec, objects):
 # --------------------------------------------------------------------------------------
 
 
+# ---------------------------------------------------------------------------
+# Session mode (SPEC §20 M6 "Blender Live Bridge")
+#
+# WHY THIS EXISTS. Every operation in this product is one process: `blender --background
+# --factory-startup --python bootstrap.py -- --request … --result …`, which loads the scene,
+# does the thing, and exits. That is the right shape for a render and the wrong one for a
+# CONVERSATION: opening a scene costs seconds, and a caller that compiles, then previews, then
+# compiles again pays it every time.
+#
+# Session mode is the same dispatch with the process kept open: one JSON request per line on
+# stdin, one JSON envelope per line on stdout, until EOF or an explicit shutdown. Nothing about
+# an individual action changes — `ACTIONS`, the protocol check and the envelope are the same
+# ones the batch path uses, because a second implementation of "what does compile_scene do"
+# would be a second answer to that question.
+#
+# WHAT IT IS NOT (yet). This is the TRANSPORT half of the M6 item, not the whole item: the
+# GUI attach — the user's own Blender, with the add-on, so they can watch it work — is the
+# next item on that list. What this proves is the part everything else rests on: one Blender,
+# many operations, each one attributable to a pid and each one able to fail on its own.
+# ---------------------------------------------------------------------------
+
+
+def _session_line(payload):
+    """One compact JSON line, flushed, because the caller is waiting on it."""
+    sys.stdout.write(json.dumps(payload, ensure_ascii=False) + "\n")
+    sys.stdout.flush()
+
+
+def _session_dispatch(request, options):
+    """The batch dispatch, applied to one line of a session.
+
+    Deliberately the same checks in the same order as `main()`: a session request that names an
+    unknown action must fail exactly as a batch request would, or the two paths would disagree
+    about the protocol and only one of them would be tested.
+    """
+    if not isinstance(request, dict):
+        return build_envelope(None, None, None, {
+            "code": "BLENDER_SCRIPT_ERROR",
+            "message": "the request document must be a JSON object",
+        }, [], [])
+
+    job_id = request.get("jobId")
+    action = request.get("action")
+
+    if request.get("protocolVersion") != PROTOCOL_VERSION:
+        return build_envelope(job_id, action, None, {
+            "code": "BLENDER_PROTOCOL_VERSION_MISMATCH",
+            "message": 'request declares protocolVersion "%s", expected "%s"'
+            % (request.get("protocolVersion"), PROTOCOL_VERSION),
+        }, [], [])
+
+    handler = ACTIONS.get(action)
+    if handler is None:
+        return build_envelope(job_id, action, None, {
+            "code": "BLENDER_UNSUPPORTED_ACTION",
+            "message": 'bootstrap.py does not implement action "%s"; supported actions are %s'
+            % (action, ", ".join(SUPPORTED_ACTIONS)),
+            "detail": {"action": action, "supported": list(SUPPORTED_ACTIONS)},
+        }, [], [])
+
+    eprint("session action=%s job=%s" % (action, job_id))
+    # Same claim as the batch path: every request is attributable to this pid, so a session that
+    # dies mid-action leaves the same evidence an interrupted render does.
+    write_process_identity(
+        options.get("proc"),
+        job_id,
+        action,
+        attempt_token=_attempt_token_from_plan(action, options),
+    )
+    try:
+        payload, warnings, notices = handler(request, options)
+        return build_envelope(job_id, action, payload, None, warnings, notices)
+    except Exception as exc:
+        return build_envelope(job_id, action, None, {
+            "code": getattr(exc, "code", "BLENDER_SCRIPT_ERROR"),
+            "message": error_text(exc),
+        }, [], [])
+
+
+def run_session(options):
+    """Serve requests until stdin ends or a caller asks to stop.
+
+    EXIT CODE IS ABOUT THE SESSION, NOT THE ACTIONS: an action that fails is reported in its own
+    envelope and the session carries on, because a caller that wanted the process to stop would
+    have closed the pipe. Only the session's own health can end it non-zero.
+    """
+    _session_line({"kind": "ready", "protocolVersion": PROTOCOL_VERSION, "pid": os.getpid()})
+    for line in sys.stdin:
+        text = line.strip()
+        if text == "":
+            continue
+        try:
+            request = json.loads(text)
+        except Exception as exc:
+            _session_line(build_envelope(None, None, None, {
+                "code": "BLENDER_SCRIPT_ERROR",
+                "message": "the request line is not valid JSON: %s" % (error_text(exc),),
+            }, [], []))
+            continue
+        if isinstance(request, dict) and request.get("action") == "shutdown":
+            _session_line({"kind": "bye", "pid": os.getpid()})
+            return 0
+        envelope = _session_dispatch(request, options)
+        envelope["kind"] = "result"
+        _session_line(envelope)
+    return 0
+
+
 def main():
     argv = sys.argv
     options, unknown = parse_args(
@@ -500,10 +608,15 @@ def main():
             "--request", "--result", "--scene-spec", "--blend", "--output-blend",
             "--output", "--camera", "--engine", "--width", "--height", "--samples",
             "--frame", "--profile", "--project-root", "--save-on-failure", "--views",
-            "--frames", "--events", "--proc",
+            "--frames", "--events", "--proc", "--session",
         ),
     )
 
+    # SESSION MODE FIRST: it shares every check below, so it must not fall through to the batch
+    # path's `--result` requirement (a session has no result file; its answers go to stdout).
+    if options.get("session") is not None:
+        return run_session(options)
+
     request_path = options.get("request")
     result_path = options.get("result")
     if result_path is None:

package/python/deepblend_bridge.py

@@ -0,0 +1,306 @@
+"""DeepBlend Studio — the Blender-side bridge (SPEC §20 M6 "Blender Add-on" / "Live Bridge").
+
+WHAT THIS IS
+------------
+One file with two entry points, and that is deliberate:
+
+* **As a Blender add-on** (the GUI case): the user installs it, enables it, and their own Blender
+  opens a local socket and shows a panel saying whether DeepBlend is attached. Every operation then
+  runs in the Blender they are LOOKING AT, which is the whole point of the M6 item — the batch round
+  trip stops being the only shape.
+* **As a headless server** (the case a test can drive): `blender --background --python
+  deepblend_bridge.py -- --socket <path>` serves exactly the same protocol with no GUI at all.
+
+Two entry points rather than two files, because the protocol and the dispatch are one thing: a second
+copy for the headless case would be a second answer to "what does compile_scene do", and it would rot
+first because nothing runs it.
+
+WHAT IT REUSES
+--------------
+`bootstrap.py`'s dispatch, unchanged: the same `ACTIONS` table, the same protocol-version check, the
+same envelope builder, the same per-request process identity. This file adds a TRANSPORT (a socket)
+and a GUI (a panel), not a second implementation.
+
+THE PROTOCOL is the session protocol, one JSON document per line: the product sends
+`{protocolVersion, jobId, action, payload?}`, this answers with the envelope bootstrap.py builds.
+`{"action": "shutdown"}` closes the connection.
+
+Owner: DeepBlend Studio — SPEC §20 M6
+"""
+
+import json
+import os
+import socket
+import sys
+import threading
+
+import bpy  # noqa: F401  — present in Blender; the import is what makes this an add-on module
+
+def _find_bootstrap():
+    """Import `bootstrap` from wherever it actually is, or say what to set.
+
+    MEASURED PROBLEM, and it is the user's case rather than the test's: Blender COPIES an add-on into
+    its own add-ons directory, so the file that lands there is this one ALONE — `bootstrap.py` is not
+    beside it, and `import bootstrap` fails. The headless entry point never sees this, because there
+    the file still sits in the package.
+
+    So the search is: beside me (headless), then the directory an operator points at, then the one a
+    user can paste into the add-on's preferences. When all three miss, the failure names the setting
+    instead of raising an ImportError into a panel that shows nothing.
+    """
+    candidates = [os.path.dirname(os.path.abspath(__file__))]
+    configured = os.environ.get("DEEPBLEND_BOOTSTRAP_DIR", "")
+    if configured:
+        candidates.append(configured)
+    try:
+        preferences = bpy.context.preferences.addons[__name__].preferences
+        if getattr(preferences, "bootstrap_dir", ""):
+            candidates.insert(0, preferences.bootstrap_dir)
+    except Exception:
+        # No preferences yet (headless, or before registration): the other two are enough.
+        pass
+
+    for candidate in candidates:
+        if candidate and os.path.exists(os.path.join(candidate, "bootstrap.py")):
+            if candidate not in sys.path:
+                sys.path.insert(0, candidate)
+            import bootstrap  # noqa: F401
+            return sys.modules["bootstrap"]
+    return None
+
+
+bootstrap = _find_bootstrap()
+BOOTSTRAP_PROBLEM = None if bootstrap is not None else (
+    "bootstrap.py was not found. Set DEEPBLEND_BOOTSTRAP_DIR to the provider package's python "
+    "directory (…/provider-local/python), or paste it into this add-on's preferences."
+)
+
+bl_info = {
+    "name": "DeepBlend Studio Bridge",
+    "author": "DeepBlend Studio",
+    "version": (0, 2, 4),
+    "blender": (4, 0, 0),
+    "location": "View3D > Sidebar > DeepBlend",
+    "description": "Serve DeepBlend operations inside this Blender, so the product drives the window you are looking at",
+    "category": "Scene",
+}
+
+# The default socket path. One per workspace, so two stores on one machine do not collide — and the
+# product passes its own path when it starts the headless server, so this default is only what the
+# add-on uses when a user enables it with no configuration.
+DEFAULT_SOCKET = os.path.join(os.path.expanduser("~"), ".deepblend-bridge.sock")
+
+
+class _Bridge:
+    """The serving state: one socket, one thread, and the last thing that happened."""
+
+    def __init__(self, socket_path, options=None):
+        self.socket_path = socket_path
+        self.options = options or {}
+        self.server = None
+        self.thread = None
+        self.requests = 0
+        self.last_action = None
+        self.last_error = None
+        self.connected = False
+
+    # -- lifecycle ---------------------------------------------------------
+
+    def start(self):
+        if os.path.exists(self.socket_path):
+            # A socket file left by a process that died. Refusing to start would leave the user with
+            # no way forward except deleting a file they cannot see, so it is replaced — the same
+            # decision the render job's recovery path makes about a stale pid file.
+            os.unlink(self.socket_path)
+        self.server = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        self.server.bind(self.socket_path)
+        self.server.listen(4)
+        self.thread = threading.Thread(target=self._serve, name="deepblend-bridge", daemon=True)
+        self.thread.start()
+
+    def stop(self):
+        try:
+            if self.server is not None:
+                self.server.close()
+        except Exception:
+            pass
+        self.server = None
+        try:
+            if os.path.exists(self.socket_path):
+                os.unlink(self.socket_path)
+        except Exception:
+            pass
+
+    # -- serving -----------------------------------------------------------
+
+    def _serve(self):
+        while self.server is not None:
+            try:
+                connection, _ = self.server.accept()
+            except Exception:
+                return
+            self.connected = True
+            try:
+                self._converse(connection)
+            except Exception as exc:
+                self.last_error = bootstrap.error_text(exc)
+            finally:
+                self.connected = False
+                try:
+                    connection.close()
+                except Exception:
+                    pass
+
+    def _converse(self, connection):
+        """One connection: a handshake, then a line in and an envelope out, until the peer stops.
+
+        THE HANDSHAKE IS THE SESSION PROTOCOL'S OWN, and it took a hang to notice it was missing: the
+        headless entry point printed `{"kind": "ready"}` to stdout at startup, and a CONNECTION got
+        nothing — so the product's `BlenderSession.ready()` waited forever on a peer that was already
+        serving. A transport that answers the same conversation has to open it the same way.
+        """
+        connection.sendall((json.dumps({"kind": "ready", "pid": os.getpid(), "socket": self.socket_path}) + "\n").encode("utf-8"))
+        buffer = b""
+        while True:
+            chunk = connection.recv(65536)
+            if not chunk:
+                return
+            buffer += chunk
+            while b"\n" in buffer:
+                line, buffer = buffer.split(b"\n", 1)
+                text = line.decode("utf-8", "replace").strip()
+                if text == "":
+                    continue
+                try:
+                    request = json.loads(text)
+                except Exception as exc:
+                    answer = bootstrap.build_envelope(None, None, None, {
+                        "code": "BLENDER_SCRIPT_ERROR",
+                        "message": "the request line is not valid JSON: %s" % (bootstrap.error_text(exc),),
+                    }, [], [])
+                else:
+                    if isinstance(request, dict) and request.get("action") == "shutdown":
+                        connection.sendall((json.dumps({"kind": "bye", "pid": os.getpid()}) + "\n").encode("utf-8"))
+                        return
+                    self.requests += 1
+                    self.last_action = request.get("action") if isinstance(request, dict) else None
+                    answer = bootstrap._session_dispatch(request, self.options)
+                answer["kind"] = "result"
+                connection.sendall((json.dumps(answer, ensure_ascii=False) + "\n").encode("utf-8"))
+
+    # -- what the panel shows ----------------------------------------------
+
+    def status(self):
+        if self.server is None:
+            return "off"
+        return "attached" if self.connected else "listening on %s" % (self.socket_path,)
+
+
+_BRIDGE = None
+
+
+class DeepBlendBridgePreferences(bpy.types.AddonPreferences):
+    """Where the user points the add-on at the package, because Blender copies add-ons alone."""
+
+    bl_idname = __name__
+
+    bootstrap_dir: bpy.props.StringProperty(  # type: ignore[valid-type]
+        name="bootstrap.py directory",
+        description="The provider package's python directory (…/provider-local/python)",
+        default="",
+        subtype="DIR_PATH",
+    )
+
+    def draw(self, context):
+        layout = self.layout
+        layout.prop(self, "bootstrap_dir")
+        if BOOTSTRAP_PROBLEM is not None:
+            layout.label(text=BOOTSTRAP_PROBLEM, icon="ERROR")
+
+
+class DEEPBLEND_PT_bridge(bpy.types.Panel):
+    """The panel, because an add-on a user cannot see is an add-on they will not trust."""
+
+    bl_label = "DeepBlend Studio"
+    bl_idname = "DEEPBLEND_PT_bridge"
+    bl_space_type = "VIEW_3D"
+    bl_region_type = "UI"
+    bl_category = "DeepBlend"
+
+    def draw(self, context):
+        layout = self.layout
+        if BOOTSTRAP_PROBLEM is not None:
+            layout.label(text="bootstrap.py not found", icon="ERROR")
+            layout.label(text="Set it in this add-on's preferences")
+            return
+        if _BRIDGE is None:
+            layout.label(text="Bridge is not running", icon="ERROR")
+            return
+        layout.label(text="Status: %s" % (_BRIDGE.status(),))
+        layout.label(text="Socket: %s" % (os.path.basename(_BRIDGE.socket_path),))
+        layout.label(text="Operations served: %d" % (_BRIDGE.requests,))
+        if _BRIDGE.last_action is not None:
+            layout.label(text="Last: %s" % (_BRIDGE.last_action,))
+        if _BRIDGE.last_error is not None:
+            layout.label(text="Last error: %s" % (_BRIDGE.last_error[:60],), icon="ERROR")
+
+
+def register():
+    global _BRIDGE
+    socket_path = os.environ.get("DEEPBLEND_BRIDGE_SOCKET", DEFAULT_SOCKET)
+    _BRIDGE = _Bridge(socket_path)
+    try:
+        _BRIDGE.start()
+    except Exception as exc:
+        # A bridge that cannot listen must not stop Blender from starting: the user's session is more
+        # important than this panel, and the panel says what went wrong.
+        _BRIDGE.last_error = bootstrap.error_text(exc)
+    bpy.utils.register_class(DeepBlendBridgePreferences)
+    bpy.utils.register_class(DEEPBLEND_PT_bridge)
+
+
+def unregister():
+    global _BRIDGE
+    bpy.utils.unregister_class(DEEPBLEND_PT_bridge)
+    bpy.utils.unregister_class(DeepBlendBridgePreferences)
+    if _BRIDGE is not None:
+        _BRIDGE.stop()
+    _BRIDGE = None
+
+
+def main():
+    """Headless entry point: serve until the process is asked to stop."""
+    argv = sys.argv
+    options = {}
+    if "--" in argv:
+        tokens = argv[argv.index("--") + 1:]
+        index = 0
+        while index < len(tokens):
+            if tokens[index] == "--socket" and index + 1 < len(tokens):
+                options["socket"] = tokens[index + 1]
+                index += 2
+                continue
+            index += 1
+    socket_path = options.get("socket", DEFAULT_SOCKET)
+
+    if bootstrap is None:
+        print(json.dumps({"kind": "error", "message": BOOTSTRAP_PROBLEM}), flush=True)
+        return 2
+
+    global _BRIDGE
+    _BRIDGE = _Bridge(socket_path, {"proc": None})
+    _BRIDGE.start()
+    print(json.dumps({"kind": "ready", "pid": os.getpid(), "socket": socket_path}), flush=True)
+    try:
+        # The serve thread is a daemon, so this loop is what keeps the process alive. A SIGTERM (or
+        # the product closing the socket and asking for shutdown) ends it.
+        _BRIDGE.thread.join()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        _BRIDGE.stop()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())