dsh-openwrite 0.2.27 → 0.2.33

package/packages/openwrite-bridge/lib/managed-runtime.js

@@ -13,7 +13,7 @@ export class UnsupportedRuntimePlatformError extends Error {
     code = 'RUNTIME_PLATFORM_UNSUPPORTED';
     status = 503;
     constructor(platform) {
-        super(`OpenWrite Studio managed runtime is unavailable on ${platform}. Configure the bridge with mode: external and baseUrl pointing to a supported Studio server; see docs/INSTALL.md#external-studio. File tools that do not require Studio remain available.`);
+        super(`OpenWrite Studio managed runtime is unavailable on ${platform}. Set pythonPath or OPENWRITE_PYTHON to a prepared Python interpreter, or configure the bridge with mode: external and baseUrl pointing to a supported Studio server; see docs/INSTALL.md#external-studio. File tools that do not require Studio remain available.`);
         this.platform = platform;
         this.name = 'UnsupportedRuntimePlatformError';
     }
@@ -22,6 +22,8 @@ export const DEFAULT_RESTART_LIMIT = 5;
 export const DEFAULT_BACKOFF_MS = [1_000, 2_000, 4_000, 8_000, 16_000];
 /** Budget for the per-request liveness probe of a previously-ready backend. */
 const HEALTH_PROBE_TIMEOUT_MS = 1_500;
+/** Second, longer budget for an ambiguous probe before calling it `unknown`. */
+const HEALTH_PROBE_RETRY_MS = 8_000;
 /** A download with no progress for this long is cut and retried on the next source. */
 const DOWNLOAD_IDLE_TIMEOUT_MS = 30_000;
 /** The backend stderr log on disk keeps only the newest chunk. */
@@ -181,9 +183,17 @@ export class ManagedRuntime {
     wait;
     restartLimit;
     backoffMs;
+    pythonPath;
+    pythonModulePaths;
+    hostLlm;
+    hostWeb;
     constructor(root, artifacts, options = {}) {
         this.root = root;
         this.artifacts = artifacts;
+        this.pythonPath = options.pythonPath?.trim() || process.env['OPENWRITE_PYTHON']?.trim() || undefined;
+        this.pythonModulePaths = [...(options.pythonModulePaths ?? [])];
+        this.hostLlm = options.hostLlm;
+        this.hostWeb = options.hostWeb;
         this.spawnFn = options.spawn ?? spawn;
         this.wait = options.delay ?? delay;
         this.restartLimit = options.restartLimit ?? DEFAULT_RESTART_LIMIT;
@@ -191,7 +201,9 @@ export class ManagedRuntime {
     }
     status() { return { ...this.state }; }
     update(phase, message, extra = {}) {
-        this.state = { phase, message, ...extra };
+        const recoveryError = this.recovered && ['recovering', 'waiting', 'downloading', 'installing'].includes(phase)
+            ? this.state.error : undefined;
+        this.state = { phase, message, ...(recoveryError ? { error: recoveryError } : {}), ...extra };
     }
     ensure() {
         if (this.closed)
@@ -239,7 +251,12 @@ export class ManagedRuntime {
      * forcefully and pushed through the normal recovery path.
      */
     async verifyConnection(connection) {
-        if (await this.probeHealth(connection)) {
+        const liveness = await this.probeLiveness(connection);
+        // Only a *confirmed* dead backend justifies tearing it down. A probe that
+        // merely timed out is ambiguous — a backend busy running chapter_write or
+        // review answers /api/health late — and killing it destroys exactly the
+        // in-flight work this recovery path exists to protect.
+        if (liveness === 'alive') {
             if (this.closed)
                 throw new Error('OpenWrite was removed');
             const current = this.connection;
@@ -247,6 +264,14 @@ export class ManagedRuntime {
                 return current;
             return this.queueRestart();
         }
+        if (liveness === 'unknown') {
+            // Keep serving the cached connection and let the real request decide; a
+            // slow health answer is not a reason to invalidate a working backend.
+            const current = this.connection;
+            if (current)
+                return current;
+            return this.queueRestart();
+        }
         if (this.connection !== connection)
             return this.queueRestart();
         this.connection = undefined;
@@ -261,22 +286,76 @@ export class ManagedRuntime {
         this.update('recovering', 'The writing backend is unresponsive; recovering');
         return this.queueRestart();
     }
-    /** Short-timeout liveness probe; false covers exit, refusal, hang, and auth drift. */
-    async probeHealth(connection) {
-        const child = this.child;
-        if (!child || child.exitCode !== null || child.signalCode !== null)
-            return false;
+    /**
+     * The host relay coordinates, if the host offers one.
+     *
+     * A relay that cannot be reached is not a startup failure: Core still runs,
+     * it simply has no host models to offer. The failure is silent on purpose —
+     * the relay's own diagnostics belong to the host, not to the backend boot.
+     */
+    async resolveHostLlm() {
+        if (this.hostLlm === undefined)
+            return undefined;
         try {
-            const response = await fetch(connection.baseUrl + '/api/health', {
-                headers: { Authorization: `Bearer ${connection.token}` },
-                signal: AbortSignal.timeout(HEALTH_PROBE_TIMEOUT_MS),
-            });
-            return response.ok;
+            const resolved = await this.hostLlm();
+            if (resolved === undefined || resolved === null)
+                return undefined;
+            if (typeof resolved.url !== 'string' || resolved.url === '')
+                return undefined;
+            if (typeof resolved.token !== 'string' || resolved.token === '')
+                return undefined;
+            return { url: resolved.url, token: resolved.token };
         }
         catch {
-            return false;
+            return undefined;
         }
     }
+    async resolveHostWeb() {
+        if (this.hostWeb === undefined)
+            return undefined;
+        try {
+            const resolved = await this.hostWeb();
+            if (resolved === undefined)
+                return undefined;
+            return { url: resolved.url, token: resolved.token };
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Liveness with three outcomes. `dead` is only returned on positive evidence —
+     * the child exited, or the connection was refused, or health answered
+     * non-ok (auth drift). A probe that timed out returns `unknown`, because a
+     * busy backend is indistinguishable from a hung one at a 1.5 s deadline and
+     * killing the former destroys in-flight work.
+     */
+    async probeLiveness(connection) {
+        const child = this.child;
+        if (!child || child.exitCode !== null || child.signalCode !== null)
+            return 'dead';
+        for (const budget of [HEALTH_PROBE_TIMEOUT_MS, HEALTH_PROBE_RETRY_MS]) {
+            try {
+                const response = await fetch(connection.baseUrl + '/api/health', {
+                    headers: { Authorization: `Bearer ${connection.token}` },
+                    signal: AbortSignal.timeout(budget),
+                });
+                return response.ok ? 'alive' : 'dead';
+            }
+            catch (error) {
+                // A refusal or a dead socket is positive evidence; anything else (the
+                // timeout we just imposed, DNS, reset) is not.
+                const code = error.code
+                    ?? error.cause?.code;
+                if (code === 'ECONNREFUSED' || code === 'ENOTFOUND' || code === 'EAI_AGAIN')
+                    return 'dead';
+                if (error instanceof Error && error.name === 'TimeoutError')
+                    continue;
+                return 'dead';
+            }
+        }
+        return 'unknown';
+    }
     async cancel() {
         this.cancelEpoch += 1;
         this.allowRevive = false;
@@ -528,7 +607,7 @@ export class ManagedRuntime {
     async command(executable, args, signal) {
         signal.throwIfAborted();
         const child = this.spawnFn(executable, args, { cwd: this.root, detached: process.platform !== 'win32', windowsHide: true,
-            env: buildChildEnv(process.env, { UV_CACHE_DIR: join(this.root, 'cache', 'uv'), UV_PYTHON_DOWNLOADS: 'never', UV_NO_CONFIG: '1' }),
+            env: buildChildEnv(process.env, { ...this.pythonLibraryEnv(), UV_CACHE_DIR: join(this.root, 'cache', 'uv'), UV_PYTHON_DOWNLOADS: 'never', UV_NO_CONFIG: '1' }),
             stdio: ['ignore', 'ignore', 'pipe'] });
         let failure = '';
         child.stderr?.on('data', bytes => { failure = (failure + String(bytes)).slice(-2000); });
@@ -545,6 +624,10 @@ export class ManagedRuntime {
             signal.removeEventListener('abort', abort);
         }
     }
+    /** Shared Android/embedded Python may need its host's native-library search paths. */
+    pythonLibraryEnv() {
+        return this.pythonPath ? Object.fromEntries(['LD_LIBRARY_PATH', 'DYLD_LIBRARY_PATH', 'DYLD_FALLBACK_LIBRARY_PATH'].map(key => [key, process.env[key]])) : {};
+    }
     async lock(signal) {
         for (;;) {
             signal.throwIfAborted();
@@ -565,7 +648,13 @@ export class ManagedRuntime {
     async prepare(signal) {
         const manifest = JSON.parse(await readFile(join(this.artifacts, 'runtime-manifest.json'), 'utf8'));
         const platform = manifest.platforms[`${process.platform}-${process.arch}`];
-        if (!platform)
+        if (this.pythonPath && !isAbsolute(this.pythonPath))
+            throw new Error('pythonPath / OPENWRITE_PYTHON must be an absolute path to a Python executable, without command-line arguments');
+        if (this.pythonModulePaths.length && !this.pythonPath)
+            throw new Error('pythonModulePaths requires pythonPath or OPENWRITE_PYTHON');
+        if (this.pythonModulePaths.some(path => !isAbsolute(path)))
+            throw new Error('pythonModulePaths must contain absolute dependency directory paths');
+        if (!this.pythonPath && !platform)
             throw new UnsupportedRuntimePlatformError(`${process.platform}/${process.arch}`);
         if (!manifest.wheel || !manifest.requirements)
             throw new Error('The package is missing Core or dependency checksums');
@@ -582,30 +671,73 @@ export class ManagedRuntime {
         const unlock = await this.lock(signal);
         let python;
         try {
-            const generation = createHash('sha256').update(JSON.stringify(manifest)).digest('hex').slice(0, 24);
+            const generation = createHash('sha256').update(JSON.stringify(manifest))
+                .update(this.pythonPath ? JSON.stringify({ pythonPath: this.pythonPath, pythonModulePaths: this.pythonModulePaths }) : '').digest('hex').slice(0, 24);
             const destination = join(this.root, 'environments', generation);
-            python = join(destination, process.platform === 'win32' ? 'Scripts/python.exe' : 'bin/python');
-            if (await readFile(join(destination, '.complete'), 'utf8').catch(() => '') !== generation) {
-                const uv = await this.extract(platform.uv, signal);
-                const basePython = await this.extract(platform.python, signal);
-                this.update('installing', 'Installing isolated dependencies; first use may take several minutes');
-                await rm(destination, { recursive: true, force: true });
+            let coreRoot;
+            if (this.pythonPath) {
+                python = this.pythonPath;
+                coreRoot = join(destination, 'core');
+                const complete = await readFile(join(destination, '.complete'), 'utf8').catch(() => '') === generation;
                 try {
-                    await this.command(uv, ['venv', '--python', basePython, destination], signal);
-                    await this.command(uv, ['pip', 'sync', '--python', python, '--require-hashes', '--only-binary', ':all:',
-                        ...(manifest.dependency_wheels?.length ? ['--find-links', join(this.artifacts, 'wheels')] : []), requirements], signal);
-                    await this.command(uv, ['pip', 'install', '--python', python, '--no-deps', wheel], signal);
-                    await this.command(python, ['-I', '-c', 'from tools.studio_http import health_payload; from tools.studio import create_server; assert health_payload()["contract_version"] == 1'], signal);
-                    await writeFile(join(destination, '.complete'), generation);
+                    if (!complete) {
+                        await rm(destination, { recursive: true, force: true });
+                        await mkdir(coreRoot, { recursive: true });
+                        // Core is a pure-Python wheel. Install only its verified contents in
+                        // our directory: no pip/uv, dependency resolution, or author-site writes.
+                        for (const [name, bytes] of Object.entries(unzipSync(await readFile(wheel)))) {
+                            signal.throwIfAborted();
+                            const target = resolve(coreRoot, name);
+                            if (isAbsolute(name) || !target.startsWith(coreRoot + sep))
+                                throw new Error('Invalid Core wheel path');
+                            if (name.endsWith('/'))
+                                await mkdir(target, { recursive: true });
+                            else {
+                                await mkdir(dirname(target), { recursive: true });
+                                await writeFile(target, bytes);
+                            }
+                        }
+                    }
+                    this.update('installing', 'Checking the supplied Python and its dependencies; no runtime downloads');
+                    await this.command(python, ['-I', '-B', '-X', 'utf8', '-c',
+                        'import json, sys; assert sys.version_info >= (3, 10), "Python >=3.10 is required"; sys.path[:0] = json.loads(sys.argv[1]); from tools.studio_http import health_payload; from tools.studio import create_server; h = health_payload(); assert h["core_version"] == sys.argv[2] and h["contract_version"] == int(sys.argv[3]), "Core version or API mismatch"',
+                        JSON.stringify([coreRoot, ...this.pythonModulePaths]), manifest.core_version, String(manifest.contract_version)], AbortSignal.any([signal, AbortSignal.timeout(120_000)]));
+                    if (!complete)
+                        await writeFile(join(destination, '.complete'), generation);
                 }
                 catch (error) {
+                    if (!complete)
+                        await rm(destination, { recursive: true, force: true });
+                    signal.throwIfAborted();
+                    throw new Error(`Supplied Python is not ready: ${sanitizeDiagnostic(error instanceof Error ? error.message : String(error))}. Prepare its dependencies first; see docs/INSTALL.md#bring-your-own-python. No uv or Python download was attempted.`);
+                }
+            }
+            else {
+                if (!platform)
+                    throw new UnsupportedRuntimePlatformError(`${process.platform}/${process.arch}`);
+                python = join(destination, process.platform === 'win32' ? 'Scripts/python.exe' : 'bin/python');
+                if (await readFile(join(destination, '.complete'), 'utf8').catch(() => '') !== generation) {
+                    const uv = await this.extract(platform.uv, signal);
+                    const basePython = await this.extract(platform.python, signal);
+                    this.update('installing', 'Installing isolated dependencies; first use may take several minutes');
                     await rm(destination, { recursive: true, force: true });
-                    throw error;
+                    try {
+                        await this.command(uv, ['venv', '--python', basePython, destination], signal);
+                        await this.command(uv, ['pip', 'sync', '--python', python, '--require-hashes', '--only-binary', ':all:',
+                            ...(manifest.dependency_wheels?.length ? ['--find-links', join(this.artifacts, 'wheels')] : []), requirements], signal);
+                        await this.command(uv, ['pip', 'install', '--python', python, '--no-deps', wheel], signal);
+                        await this.command(python, ['-I', '-c', 'from tools.studio_http import health_payload; from tools.studio import create_server; assert health_payload()["contract_version"] == 1'], signal);
+                        await writeFile(join(destination, '.complete'), generation);
+                    }
+                    catch (error) {
+                        await rm(destination, { recursive: true, force: true });
+                        throw error;
+                    }
                 }
             }
             signal.throwIfAborted();
             this.update(this.recovered ? 'recovering' : 'starting', this.recovered ? 'Recovering the writing environment' : 'Starting the writing environment');
-            const connection = await this.start(python, manifest, signal);
+            const connection = await this.start(python, manifest, signal, coreRoot);
             const pending = join(this.root, 'active.' + randomUUID() + '.json');
             try {
                 await writeFile(pending, JSON.stringify({ generation, coreVersion: manifest.core_version }));
@@ -626,16 +758,19 @@ export class ManagedRuntime {
             await unlock();
         }
     }
-    async start(python, manifest, signal) {
+    async start(python, manifest, signal, coreRoot) {
         signal.throwIfAborted();
         const token = randomBytes(32).toString('hex');
         const generation = ++this.generation;
         // Windows defaults redirected stdout to its legacy locale encoding. Core
         // initialization logs and manuscript paths are Unicode; -I ignores Python
         // environment options, so set UTF-8 explicitly on the interpreter as well.
-        const child = this.spawnFn(python, ['-I', '-X', 'utf8', '-u', '-m', 'tools.managed_runtime'], {
+        const launch = coreRoot
+            ? ['-c', 'import json, runpy, sys; sys.path[:0] = json.loads(sys.argv[1]); sys.argv = sys.argv[2:]; runpy.run_module(sys.argv[0], run_name="__main__", alter_sys=True)', JSON.stringify([coreRoot, ...this.pythonModulePaths]), 'tools.managed_runtime']
+            : ['-m', 'tools.managed_runtime'];
+        const child = this.spawnFn(python, ['-I', ...(coreRoot ? ['-B'] : []), '-X', 'utf8', '-u', ...launch], {
             cwd: this.root, detached: process.platform !== 'win32', windowsHide: true, stdio: ['pipe', 'pipe', 'pipe'],
-            env: buildChildEnv(process.env, { PYTHONNOUSERSITE: '1', PYTHONUTF8: '1' }),
+            env: buildChildEnv(process.env, { ...this.pythonLibraryEnv(), PYTHONNOUSERSITE: '1', PYTHONUTF8: '1' }),
         });
         this.child = child;
         // Mirror stderr to state/logs/backend.log (last 64 KiB): a stuck backend
@@ -678,7 +813,16 @@ export class ManagedRuntime {
             signal.addEventListener('abort', abort, { once: true });
             let port;
             try {
-                child.stdin.write(JSON.stringify({ token, state_dir: join(this.root, 'state') }) + '\n');
+                const handshake = { token, state_dir: join(this.root, 'state') };
+                // The relay address is ephemeral, so it is resolved per start and
+                // never cached: a stale URL would point Core at a dead port.
+                const hostLlm = await this.resolveHostLlm();
+                if (hostLlm !== undefined)
+                    handshake['host_llm'] = hostLlm;
+                const hostWeb = await this.resolveHostWeb();
+                if (hostWeb !== undefined)
+                    handshake['host_web'] = hostWeb;
+                child.stdin.write(JSON.stringify(handshake) + '\n');
                 port = await ready;
             }
             finally {

package/packages/openwrite-bridge/lib/tool-policy.js

@@ -1,18 +1,19 @@
+// Only unconditionally read-only tools belong here. An action-dispatching tool
+// must NOT be listed: `reads` short-circuits before `readActions`, so a merged
+// family placed here has all of its mutating actions (delete, configure,
+// save_routes) classified as reads and run under a read-only sandbox or plan
+// mode. `novel_model_profiles` / `novel_embedding_profiles` were listed here by
+// mistake after the 95→56 merge; their read-only actions are in `readActions`.
 const reads = new Set([
-    'novel_embedding_profiles', 'novel_status', 'novel_review_framework', 'novel_trace_list',
-    'novel_context_preview', 'novel_outline_read', 'novel_reading_order', 'novel_reading_packet',
-    'novel_chapter_work', 'novel_scene_structure', 'novel_chapter_scenes', 'novel_scene_migration_preview',
-    'novel_assets_list', 'novel_search', 'novel_doc_read', 'novel_asset_read', 'novel_revisions_list',
-    'novel_revision_get', 'novel_tasks_list', 'novel_continuity', 'novel_diagnostics',
-    'novel_research_status', 'novel_research_report', 'novel_model_profiles',
-    'novel_manuscript_acceptance', 'novel_export_preflight',
-    'novel_manuscript_metrics', 'novel_outline_audit',
+    'novel_status', 'novel_review_framework', 'novel_trace_list',
+    'novel_context_preview', 'novel_outline_read', 'novel_reading_packet',
+    'novel_chapter_work', 'novel_chapter_scenes', 'novel_search', 'novel_continuity', 'novel_diagnostics',
+    'novel_research_status', 'novel_research_report',
+    'novel_manuscript_acceptance', 'novel_manuscript_metrics', 'novel_outline_audit',
 ]);
 const generates = new Set([
-    'novel_write_chapter', 'novel_review_chapter', 'novel_multi_write', 'novel_task_create',
-    'novel_task_retry', 'novel_task_confirm', 'novel_revision_create_selection',
-    'novel_revision_create_from_review', 'novel_revision_regenerate', 'novel_settle_backfill',
-    'novel_model_test', 'novel_model_embedding_test',
+    'novel_write_chapter', 'novel_review_chapter', 'novel_multi_write',
+    'novel_revision_regenerate', 'novel_settle_backfill',
 ]);
 const readActions = {
     novel_writing_assets: ['get'],
@@ -25,16 +26,42 @@ const readActions = {
     novel_reference_library_action: ['list', 'status', 'profile'],
     novel_runtime_skill_action: ['list', 'diagnose', 'resolve'],
     novel_rule_action: ['status'],
+    // Merged tools: the read-only actions of each family.
+    novel_task: ['get', 'list'],
+    novel_revision: ['list', 'get'],
+    novel_assets: ['list', 'read'],
+    novel_assets_package: ['preview'],
+    novel_doc: ['read'],
+    novel_scene: ['structure'],
+    novel_scene_migration: ['preview'],
+    novel_reading_order: ['get'],
+    novel_export: ['preflight'],
+    // `download` is NOT here: it writes a local file (mkdir + writeFile under
+    // outputDir), so classifying it as a read would let a read-only sandbox or plan
+    // mode write bytes to disk — the same class of mistake as the assets-package
+    // export. Its archive_op read variants are covered by the write classification
+    // being fail-closed rather than permissive.
+    novel_model_profiles: ['list', 'test'],
+    novel_embedding_profiles: ['list', 'test'],
+};
+/** Merged tools whose creating/generating actions replace the old per-tool names. */
+const generateActions = {
+    novel_task: ['create', 'retry', 'confirm'],
+    novel_revision: ['create'],
 };
 /** Unknown and preview operations fail closed: previews can persist confirmation records. */
 export function novelEffect(name, args) {
     if (reads.has(name))
         return 'read';
     const values = args && typeof args === 'object' ? args : {};
+    if (name === 'novel_write_chapter' && values.dry_run === true)
+        return 'read';
     if (readActions[name]?.includes(String(values.action)))
         return 'read';
     if (name === 'novel_model_benchmark' && values.action === 'run')
         return 'generate';
+    if (generateActions[name]?.includes(String(values.action)))
+        return 'generate';
     return generates.has(name) ? 'generate' : 'write';
 }
 export function novelPolicyDenial(ctx, execution) {