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

package/lib/index.js

@@ -143,6 +143,44 @@ export const ProviderConfig = z.object({
   capabilitiesCacheMs: z.number().default(60_000),
   /** Retain per-invocation working directories for post-mortem inspection. */
   keepWorkingDirectory: z.boolean().default(false),
+  /**
+   * Actions served from a KEPT Blender process instead of one process each (SPEC §20 M6).
+   *
+   * EMPTY BY DEFAULT, AND THAT IS THE HONEST DEFAULT — MEASURED, not cautious. Turning it on for
+   * `get_capabilities` and `compile_scene` made three acceptance suites fail, and they were right:
+   * a kept session has a NARROWER CONTRACT than a batch invocation. It does not capture per-request
+   * stdout (the capture cap and the flood test have nothing to read), a per-request deadline does not
+   * kill the process (the deadline test found a Blender still in the process table), and it holds its
+   * working directory for as long as it lives (the M0 probe found temp directories left behind).
+   *
+   * None of that is a bug in the session; it is a different shape with different promises. But a
+   * default that silently swaps one set of promises for another is exactly the kind of change this
+   * repository's suites exist to catch, so the fast path is OPT IN: an operator who wants it names the
+   * actions, and the actions that are safe for it are the pure, short ones — `get_capabilities` and
+   * `compile_scene`. MEASURED with it on: three operations cost 832 ms instead of 2594 ms, in one
+   * process instead of three (`milestone-status.md` §212.6).
+   *
+   * The RENDERS are not safe for it in any configuration: cancelling one must kill exactly that
+   * render, and the only way this provider can do that is to end the process — which, on an ATTACHED
+   * Blender, is the user's own session.
+   */
+  sessionActions: z.array(z.string()).default([]),
+  /** How long a kept session may sit idle before it is closed. */
+  sessionIdleMs: z.number().default(60_000),
+  /**
+   * The socket a Blender bridge is listening on, when the operator wants the session actions served by
+   * THE USER'S OWN BLENDER rather than one this provider spawns (SPEC §20 M6 "Live Bridge").
+   *
+   * Empty means "spawn one", which is what every deployment did before this key existed. Setting it is
+   * how a user says *use the Blender I already have open* — and the difference is not speed, it is that
+   * they can watch the operations happen in the window they are looking at.
+   *
+   * A CONFIGURED SOCKET THAT DOES NOT ANSWER IS AN ERROR, not a fallback to spawning. Silently doing
+   * something else than what was asked is the failure mode this repository keeps paying for: the user
+   * would see operations succeed and never learn that their Blender was not the one doing them. The
+   * refusal names the add-on, because that is what has to be enabled.
+   */
+  sessionSocket: z.string().default(''),
 })
 
 /**
@@ -434,7 +472,7 @@ class BlenderSession {
   /**
    * Run one action in the live process.
    *
-   * @param {{ action: string, payload?: object, jobId?: string }} request
+   * @param {{ action: string, payload?: object, args?: string[], jobId?: string }} request
    * @param {{ signal?: AbortSignal }} [options]
    * @returns {Promise<object>} the envelope bootstrap.py built for it.
    */
@@ -451,6 +489,11 @@ class BlenderSession {
       jobId,
       action: request.action,
       ...(request.payload !== undefined ? { payload: request.payload } : {}),
+      // PER-REQUEST ARGUMENTS. A session's argv is fixed when the process starts, and the actions that
+      // matter need flags (`--scene-spec`, `--output`, …), so the request carries its own and
+      // bootstrap.py parses them with the same parser the process used. MEASURED: without this, every
+      // real action failed inside a session with "requires --scene-spec".
+      ...(Array.isArray(request.args) ? { args: request.args } : {}),
     }
 
     const answered = new Promise((resolve, reject) => {
@@ -518,6 +561,10 @@ export default class LocalBlenderRuntime extends Service {
   /** @type {Map<string, import('@deepblend/dsh-blender-contracts').BlenderCapabilities>} */
   _capabilitiesCache = new Map()
 
+  /** The kept Blender for `sessionActions`, and the timer that closes it when it goes quiet. */
+  _session = null
+  _sessionTimer = null
+
   /**
    * @param {import('@deepseek-ai/cordis').Context} ctx
    * @param {import('z').infer<typeof ProviderConfig>} config - validated by schemastery before construction.
@@ -531,6 +578,11 @@ export default class LocalBlenderRuntime extends Service {
     this.bootstrapPath = this._resolveBootstrapPath(config.bootstrapPath)
     /** Resolved once: the host must be configured with the same value. */
     this.workspaceRoot = resolveWorkspaceRoot(config.workspaceRoot)
+    // A KEPT SESSION IS A PROCESS THIS ROW OWNS, so it is disposed with the row rather than left for
+    // the host's exit path to find: a plugin that is unloaded must not leave a Blender behind.
+    ctx.effect(() => () => {
+      this.closeSession().catch(() => {})
+    }, 'deepblend kept session teardown')
   }
 
   /**
@@ -901,6 +953,51 @@ export default class LocalBlenderRuntime extends Service {
     return session
   }
 
+  /**
+   * The kept session, opened on first use and closed when it has been idle.
+   *
+   * A SESSION IS NOT A CACHE. It is a Blender process holding a loaded scene, so it is closed on a
+   * timer rather than kept forever: an operator who runs one compile and walks away should not find a
+   * Blender still resident an hour later. The timer is refreshed by use and cleared on disposal.
+   */
+  async _keptSession() {
+    if (this._session !== null && !this._session.closed) return this._session
+    const socket = this.config.sessionSocket
+    // THE USER'S BLENDER, when they have named one. `attachSession` owns the refusal and its message;
+    // this only decides which of the two transports the configured actions travel over.
+    this._session = typeof socket === 'string' && socket.length > 0
+      ? await this.attachSession(socket)
+      : await this.openSession()
+    return this._session
+  }
+
+  _touchSession() {
+    if (this._sessionTimer !== null) clearTimeout(this._sessionTimer)
+    this._sessionTimer = setTimeout(() => {
+      // NEVER CLOSE UNDER A REQUEST. MEASURED: the first version closed on the timer alone, and a
+      // compile that was still running when the idle window expired was rejected with "closed by its
+      // caller" — the session ended a request that had done nothing wrong. Idle means idle.
+      if (this._session !== null && this._session.waiting.size > 0) {
+        this._touchSession()
+        return
+      }
+      const session = this._session
+      this._session = null
+      this._sessionTimer = null
+      session?.close?.().catch(() => {})
+    }, this.config.sessionIdleMs)
+    if (typeof this._sessionTimer.unref === 'function') this._sessionTimer.unref()
+  }
+
+  /** Close the kept session now, if there is one. */
+  async closeSession() {
+    if (this._sessionTimer !== null) clearTimeout(this._sessionTimer)
+    this._sessionTimer = null
+    const session = this._session
+    this._session = null
+    if (session !== null) await session.close().catch(() => {})
+  }
+
   async runBootstrap(request, options = {}) {
     const action = request?.action
     if (typeof action !== 'string' || action.length === 0) {
@@ -914,6 +1011,28 @@ export default class LocalBlenderRuntime extends Service {
       )
     }
 
+    // THE SESSION PATH, for the actions configured to use one. It returns the SAME outcome shape the
+    // batch path returns — a caller must not be able to tell which one served it, or the two paths
+    // would drift into two behaviours with one name.
+    if (this.config.sessionActions.includes(action) && options.session !== false) {
+      const session = await this._keptSession()
+      this._touchSession()
+      const startedAt = Date.now()
+      const envelope = await session.run({
+        action,
+        ...(request.payload !== undefined ? { payload: request.payload } : {}),
+        ...(Array.isArray(options.args) ? { args: options.args } : {}),
+      }, { signal: options.signal })
+      return {
+        envelope,
+        stdout: '',
+        stderr: '',
+        exitCode: envelope.status === 'error' ? 1 : 0,
+        durationMs: Date.now() - startedAt,
+        workingDirectory: session.directory ?? null,
+      }
+    }
+
     const resolvedExecutable = await this.resolveBlenderExecutable({ signal: options.signal })
     if (resolvedExecutable.error !== null || resolvedExecutable.resolved === null) {
       throw resolvedExecutable.error ?? new BlenderError(
@@ -1264,7 +1383,14 @@ export default class LocalBlenderRuntime extends Service {
    * @returns {Promise<{report: object, envelope: object, durationMs: number, stdout: string, stderr: string}>}
    */
   async compileScene(request) {
-    const outputBlend = 'result.blend'
+    // AN ABSOLUTE, PER-REQUEST OUTPUT PATH, and it is what lets the same action run in either
+    // transport. MEASURED: this used to be the relative `'result.blend'`, which was safe only because
+    // the batch path gives every invocation its own working directory — a session has ONE directory
+    // for every request, so two compiles would write the same file and the caller would be handed a
+    // checkpoint that belonged to a different one. Passing the path explicitly removes the dependency
+    // on a working directory that a kept process does not have per request.
+    const { directory: requestDirectory } = this._createWorkingDirectory()
+    const outputBlend = join(requestDirectory, 'result.blend')
     if (typeof request?.sceneSpecPath !== 'string' || request.sceneSpecPath.length === 0) {
       throw new BlenderError(
         BlenderErrorCode.SCENE_SPEC_INVALID,
@@ -1282,10 +1408,18 @@ export default class LocalBlenderRuntime extends Service {
         signal: request.signal,
         args,
         projectRoot: request.projectRoot,
-        onWorkingDirectory: request.onWorkingDirectory,
+        // NOT `onWorkingDirectory` here: the callback has to name the directory that HOLDS the
+        // checkpoint, and that is this method's own (`runBootstrap` would name its invocation
+        // directory, which in a session is a different one). One owner for one path.
       },
     )
 
+    // The caller moves the checkpoint somewhere durable before this directory goes away, which is what
+    // lets a compile failure leave no trace in the project.
+    if (typeof request.onWorkingDirectory === 'function') {
+      await request.onWorkingDirectory({ directory: requestDirectory, envelope: run.envelope, jobId: request.jobId })
+    }
+
     const report = run.envelope.result ?? {}
     return {
       report,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepblend/dsh-blender-provider-local",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "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.5"
+    "@deepblend/dsh-blender-contracts": "0.2.7"
   },
   "license": "MIT",
   "repository": {

package/python/bootstrap.py

@@ -429,6 +429,15 @@ def _as_int(value):
         raise ActionError("BLENDER_SCRIPT_ERROR", '"%s" is not an integer' % (value,))
 
 
+# The options a REQUEST may carry, which is the batch path's own list: a session request that names a
+# flag the batch path knows must work, and one it does not must fail the same way.
+KNOWN_SESSION_OPTIONS = (
+    "--request", "--result", "--scene-spec", "--blend", "--output-blend",
+    "--output", "--camera", "--engine", "--width", "--height", "--samples",
+    "--frame", "--profile", "--project-root", "--save-on-failure", "--views",
+    "--frames", "--events", "--proc",
+)
+
 ACTIONS = {
     "get_capabilities": action_get_capabilities,
     "compile_scene": action_compile_scene,
@@ -552,6 +561,27 @@ def _session_dispatch(request, options):
             "detail": {"action": action, "supported": list(SUPPORTED_ACTIONS)},
         }, [], [])
 
+    # PER-REQUEST ARGUMENTS, merged over the process's own.
+    #
+    # MEASURED, and it made sessions useless for the actions that matter: `compile_scene` needs
+    # `--scene-spec`, `render_preview` needs `--output`, and the batch path passes those as extra
+    # argv — but a session's argv is fixed when the process starts, so the first attempt at reusing a
+    # process dropped every one of them and every real action failed with "requires --scene-spec".
+    #
+    # The fix is not to restart the process with new flags (that is the batch path) but to let a
+    # request carry its own, parsed by the SAME parser the process used: one parser, so a flag that
+    # works in batch mode works here, including the failure for an unknown one.
+    options = options
+    if isinstance(request.get("args"), list):
+        extra, unknown = parse_args(["--"] + [str(token) for token in request["args"]], KNOWN_SESSION_OPTIONS)
+        if unknown:
+            return build_envelope(job_id, action, None, {
+                "code": "BLENDER_SCRIPT_ERROR",
+                "message": "unrecognised arguments: %s" % (", ".join(unknown),),
+            }, [], [])
+        options = dict(options)
+        options.update(extra)
+
     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.