@namzu/sdk 48.3.1 → 50.0.0

package/dist/runtime/jobs/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/runtime/jobs/registry.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/runtime/jobs/registry.ts"],"names":[],"mappings":"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"}

package/dist/runtime/jobs/registry.js

@@ -1,11 +1,37 @@
-import { spawn } from 'node:child_process';
 import { SANDBOX_KILL_GRACE_MS } from '../../constants/sandbox/index.js';
 import { killTree } from '../../process/kill-tree.js';
-import { hostShellSpawn } from '../../tools/command-shell.js';
+import { describeSpawnFailure, spawnHostShell } from '../../tools/command-shell.js';
 import { scrubInheritedEnv } from '../../tools/env-scrub.js';
-import { awaitWithAbort } from '../../utils/await-with-abort.js';
+import { createHostOutputDecoder } from '../../tools/host-output.js';
+import { subscribeToAbort } from '../../utils/abort.js';
 const DEFAULT_MAX_JOBS_PER_OWNER = 8;
 const DEFAULT_MAX_OUTPUT_BYTES = 1024 * 1024;
+const MAX_CHANNEL_CHUNKS = 4096;
+const MAX_WAIT_RESULT_BYTES = 32 * 1024;
+const MAX_OUTPUT_WAIT_MS = 60 * 60 * 1000;
+/** Starting another observer would exceed its owner's or registry's bound. */
+export class BackgroundJobOutputWaitLimitError extends Error {
+    details;
+    constructor(details) {
+        super(`Background output wait limit ${details.limit} reached for ${details.scope}; finish or cancel an existing wait first.`);
+        this.details = details;
+        this.name = 'BackgroundJobOutputWaitLimitError';
+    }
+}
+/** Start at a complete UTF-8 code point when a byte cap or cursor bisects one. */
+function utf8Start(bytes, start) {
+    let at = start;
+    while (at < bytes.length && ((bytes[at] ?? 0) & 0xc0) === 0x80)
+        at++;
+    return at;
+}
+function outputTail(text, maxBytes) {
+    const bytes = Buffer.from(text);
+    if (bytes.length <= maxBytes)
+        return { text, omitted: 0 };
+    const start = utf8Start(bytes, bytes.length - maxBytes);
+    return { text: bytes.subarray(start).toString('utf8'), omitted: start };
+}
 /** A start that would exceed a declared bound. */
 export class BackgroundJobLimitError extends Error {
     details;
@@ -42,6 +68,8 @@ export class BackgroundJobRegistry {
     jobs = new Map();
     counter = 0;
     exitListeners = new Set();
+    outputWaiters = 0;
+    outputWaitersByOwner = new Map();
     /**
      * Be told when a job ends, whoever owns it. A job outlives the call that
      * started it, so the one thing the model could not do was learn that it
@@ -64,8 +92,45 @@ export class BackgroundJobRegistry {
             }
         }
     }
+    /** A failed remote stop never releases ownership or announces a terminal job. */
+    confirmTermination(entry) {
+        if (entry.terminationAttempt)
+            return entry.terminationAttempt;
+        const terminate = entry.terminateProcess;
+        if (!terminate)
+            return Promise.reject(new Error('The process has no confirmed termination API'));
+        const attempt = Promise.resolve()
+            .then(() => terminate('SIGTERM'))
+            .then(() => {
+            const { recoveryRequired: _recovery, stopError: _error, ...record } = entry.record;
+            entry.record = record;
+            if (entry.closedResult)
+                entry.finalize?.(entry.closedResult.code, entry.closedResult.signal);
+        })
+            .catch((error) => {
+            entry.record = {
+                ...entry.record,
+                recoveryRequired: true,
+                stopError: 'The process provider could not confirm the owned job stopped; retry termination or recover its environment.',
+            };
+            for (const observer of entry.outputObservers)
+                observer();
+            throw error;
+        })
+            .finally(() => {
+            entry.terminationAttempt = undefined;
+        });
+        entry.terminationAttempt = attempt;
+        return attempt;
+    }
     constructor(config = {}) {
         this.config = config;
+        for (const key of ['maxOutputWaiters', 'maxOutputWaitersPerOwner']) {
+            const value = config[key];
+            if (value !== undefined && (!Number.isSafeInteger(value) || value < 1)) {
+                throw new RangeError(`${key} must be a positive safe integer.`);
+            }
+        }
     }
     get maxJobs() {
         return this.config.maxJobsPerOwner ?? DEFAULT_MAX_JOBS_PER_OWNER;
@@ -94,19 +159,19 @@ export class BackgroundJobRegistry {
         // decided should see them. A background job outlives the call that
         // started it, which makes the leak longer-lived, not smaller.
         const inherited = scrubInheritedEnv();
-        // The same shell as a foreground `bash` call, so the permission
-        // rules' reading of the line holds for the job too.
-        const shell = hostShellSpawn(params.command, { ...inherited.env, ...params.env });
+        // The same spawn as a foreground `bash` call, so the permission
+        // rules' reading of the line holds for the job too, and so the two
+        // cannot disagree about how a shell is started on a given platform.
         const started = params.spawn
             ? params.spawn()
             : {
-                child: spawn(shell.file ?? '/bin/sh', shell.file === undefined ? ['-c', params.command] : [...shell.args], {
+                child: spawnHostShell(params.command, {
                     cwd: params.workingDirectory,
-                    env: shell.env,
-                    // Leader of its own process group, which is what `killTree` needs
-                    // to reach the command and everything it forks rather than only the
-                    // wrapping shell. See `process/kill-tree.ts`.
-                    detached: process.platform !== 'win32',
+                    env: { ...inherited.env, ...params.env },
+                    // `detached` makes the child the leader of its own process group
+                    // off Windows, which is what `killTree` needs to reach the command
+                    // and everything it forks rather than only the wrapping shell. See
+                    // `process/kill-tree.ts`.
                     stdio: ['ignore', 'pipe', 'pipe'],
                 }),
             };
@@ -114,8 +179,22 @@ export class BackgroundJobRegistry {
         // Started, not adopted: this process stays the parent for the job's
         // whole life. `unref` would let Node exit with the job still running,
         // which is the orphan this registry exists to prevent.
-        child.stdout?.setEncoding('utf8');
-        child.stderr?.setEncoding('utf8');
+        // Raw bytes, decoded here: a Windows console writes its OEM code page.
+        // A process a sandbox started runs a Linux guest, so it is UTF-8.
+        const decoders = {
+            stdout: createHostOutputDecoder(params.spawn ? { platform: 'linux' } : {}),
+            stderr: createHostOutputDecoder(params.spawn ? { platform: 'linux' } : {}),
+        };
+        let startError;
+        let settleStarted;
+        const startedPromise = new Promise((resolve) => {
+            settleStarted = () => resolve(startError === undefined ? {} : { error: startError });
+        });
+        // A process the host's own spawner started is the host's to vouch for:
+        // it may be remote, and need not emit `spawn` at all.
+        if (params.spawn || child.pid !== undefined)
+            settleStarted();
+        let finalizeEntry;
         const entry = {
             record: {
                 id,
@@ -126,36 +205,62 @@ export class BackgroundJobRegistry {
             },
             child,
             ...(started.kill ? { killProcess: started.kill.bind(started) } : {}),
+            ...(started.terminate ? { terminateProcess: started.terminate.bind(started) } : {}),
             buffer: '',
             produced: 0,
+            outputChunks: [],
+            outputObservers: new Set(),
+            started: startedPromise,
             exit: new Promise((resolve) => {
                 let spawned = child.pid !== undefined;
                 let failedToSpawn = false;
+                let finalized = false;
                 const finalize = (code, signal) => {
+                    if (finalized)
+                        return;
+                    finalized = true;
                     entry.record = {
                         ...entry.record,
                         // A job killed by this registry says `killed`, not
                         // `exited` with a signal a reader has to interpret. The
                         // two are different answers to "why did my job stop".
-                        status: entry.record.status === 'killed' ? 'killed' : 'exited',
+                        status: entry.killRequested || entry.record.status === 'killed' ? 'killed' : 'exited',
                         exitedAt: Date.now(),
                         ...(code === null ? {} : { exitCode: code }),
                         ...(signal ? { signal } : {}),
                     };
                     resolve();
+                    for (const observer of entry.outputObservers)
+                        observer();
                     this.announceExit(entry.record);
                 };
+                finalizeEntry = finalize;
                 child.once('spawn', () => {
                     spawned = true;
+                    settleStarted();
                 });
-                child.on('error', () => {
+                child.on('error', (error) => {
                     // A failed spawn emits both `error` and `close`. Waiting for
                     // `close` also covers errors on an already-running process
                     // (such as a failed kill) without announcing a false exit.
-                    if (!spawned)
-                        failedToSpawn = true;
+                    if (spawned)
+                        return;
+                    failedToSpawn = true;
+                    startError ??= describeSpawnFailure(error, params.workingDirectory);
+                    settleStarted();
                 });
                 child.once('close', (code, signal) => {
+                    for (const stream of ['stdout', 'stderr']) {
+                        const rest = decoders[stream].end();
+                        if (rest)
+                            append(rest, stream);
+                    }
+                    if (failedToSpawn && startError !== undefined) {
+                        // In the output too, so a caller that only reads output (or
+                        // redirects it, as a model does) still learns why it is empty.
+                        append(`${startError}\n`, 'stderr');
+                        entry.record = { ...entry.record, error: startError };
+                    }
                     // The job is the process GROUP, not the shell. A command that
                     // backgrounds its real work (`server &`) exits the shell at
                     // once and leaves the server as the group's survivor; calling
@@ -166,6 +271,14 @@ export class BackgroundJobRegistry {
                     // alive, and ends — with the shell's exit code — when the
                     // group is empty.
                     const exitCode = failedToSpawn ? null : code;
+                    if (entry.terminateProcess) {
+                        entry.closedResult = { code: exitCode, signal };
+                        void this.confirmTermination(entry).catch(() => {
+                            // The retained running record exposes recoveryRequired. A
+                            // later kill retries instead of forgetting the guest tree.
+                        });
+                        return;
+                    }
                     if (entry.record.status !== 'killed' && groupAlive(child.pid)) {
                         const poll = setInterval(() => {
                             if (groupAlive(child.pid))
@@ -180,27 +293,56 @@ export class BackgroundJobRegistry {
                 });
             }),
         };
-        const append = (text) => {
-            entry.produced += Buffer.byteLength(text);
+        entry.finalize = finalizeEntry;
+        const append = (text, stream) => {
+            const chunk = { stream, offset: entry.produced, bytes: Buffer.from(text) };
+            if (chunk.bytes.length === 0)
+                return;
+            entry.produced += chunk.bytes.length;
             entry.buffer += text;
-            const over = Buffer.byteLength(entry.buffer) - this.maxBytes;
-            if (over > 0) {
-                // Oldest first. A cap that dropped the NEWEST bytes would hide
-                // exactly the part a poller is waiting for.
-                //
-                // Nothing accumulates a drop counter here, deliberately. What a
-                // reader needs is how much IT missed, which depends on where its
-                // own offset was — a running total of everything ever dropped
-                // answers a different question, and `read` derives the right one
-                // from `produced` and the retained length.
-                entry.buffer = Buffer.from(entry.buffer).subarray(over).toString('utf8');
+            entry.buffer = outputTail(entry.buffer, this.maxBytes).text;
+            entry.outputChunks.push(chunk);
+            const retainedStart = entry.produced - Buffer.byteLength(entry.buffer);
+            while (entry.outputChunks.length > MAX_CHANNEL_CHUNKS ||
+                (entry.outputChunks[0] &&
+                    entry.outputChunks[0].offset + entry.outputChunks[0].bytes.length <= retainedStart)) {
+                entry.outputChunks.shift();
+            }
+            const first = entry.outputChunks[0];
+            if (first && first.offset < retainedStart) {
+                const skip = utf8Start(first.bytes, retainedStart - first.offset);
+                entry.outputChunks[0] = {
+                    ...first,
+                    offset: first.offset + skip,
+                    bytes: Buffer.from(first.bytes.subarray(skip)),
+                };
             }
+            // Deliver the actual chunk even when its beginning has already fallen
+            // outside retention: an active observer must not miss a fast producer.
+            for (const observer of entry.outputObservers)
+                observer(chunk);
+        };
+        const onData = (stream) => (data) => {
+            const text = typeof data === 'string' ? data : decoders[stream].write(data);
+            if (text)
+                append(text, stream);
         };
-        child.stdout?.on('data', (text) => append(text));
-        child.stderr?.on('data', (text) => append(text));
+        child.stdout?.on('data', onData('stdout'));
+        child.stderr?.on('data', onData('stderr'));
         this.jobs.set(id, entry);
         return entry.record;
     }
+    /**
+     * Resolves once the job's process exists, or once it could not be
+     * created (`error` then says why). Lets a caller report a start that
+     * failed in the same reply that would otherwise say "started".
+     */
+    awaitStarted(id) {
+        const entry = this.jobs.get(id);
+        if (!entry)
+            throw new UnknownBackgroundJobError({ id });
+        return entry.started;
+    }
     /** The record, or throw for an id this registry does not know. */
     get(id) {
         const entry = this.jobs.get(id);
@@ -227,10 +369,187 @@ export class BackgroundJobRegistry {
             throw new UnknownBackgroundJobError({ id });
         if (entry.record.status !== 'running')
             return Promise.resolve(entry.record);
-        // `entry` is the same object the `finalize` closure in `start()`
-        // mutates in place, so reading `entry.record` after `exit` settles
-        // sees the final status — the same trick `kill()` already relies on.
-        return awaitWithAbort(entry.exit.then(() => entry.record), opts.signal);
+        if (!opts.signal) {
+            // Keep the original promise path for callers without cancellation.
+            return entry.exit.then(() => entry.record);
+        }
+        const signal = opts.signal;
+        if (signal.aborted)
+            return Promise.reject(signal.reason);
+        // A Promise.race against entry.exit leaves a continuation on that
+        // never-ending promise after cancellation. An exit listener can instead
+        // be removed as soon as this particular wait is abandoned.
+        return new Promise((resolve, reject) => {
+            let disposeAbort = () => { };
+            const unsubscribe = this.onExit((job) => {
+                if (job.id !== id)
+                    return;
+                unsubscribe();
+                disposeAbort();
+                resolve(job);
+            });
+            disposeAbort = subscribeToAbort(signal, () => {
+                unsubscribe();
+                disposeAbort();
+                reject(signal.reason);
+            });
+        });
+    }
+    /**
+     * Observe a literal in one pipe, including retained output after the cursor.
+     * A marker is evidence of output, not exit intent or service health. Every
+     * observer is independent and bounded; cancellation never stops the job.
+     */
+    waitForOutput(id, opts) {
+        const entry = this.jobs.get(id);
+        if (!entry)
+            throw new UnknownBackgroundJobError({ id });
+        // Capture the admitted condition and clocks once; a caller retaining its
+        // mutable options object cannot alter a bound after validation.
+        const { literal: literalText, stream: requestedStream, fromOffset, timeoutMs, idleTimeoutMs, signal, } = opts;
+        if (typeof literalText !== 'string' ||
+            literalText.length === 0 ||
+            Buffer.byteLength(literalText) > 4096 ||
+            Buffer.from(literalText).toString('utf8') !== literalText) {
+            throw new RangeError('Output literal must be non-empty valid UTF-8, at most 4096 bytes.');
+        }
+        const stream = requestedStream ?? 'either';
+        if (!['stdout', 'stderr', 'either'].includes(stream))
+            throw new RangeError('Unknown output stream.');
+        for (const [name, value] of [
+            ['timeoutMs', timeoutMs],
+            ['idleTimeoutMs', idleTimeoutMs],
+        ]) {
+            if ((name === 'timeoutMs' || value !== undefined) &&
+                (value === undefined ||
+                    !Number.isSafeInteger(value) ||
+                    value < 1 ||
+                    value > MAX_OUTPUT_WAIT_MS)) {
+                throw new RangeError(`${name} must be an integer from 1 through ${MAX_OUTPUT_WAIT_MS}.`);
+            }
+        }
+        const from = fromOffset ?? 0;
+        if (!Number.isSafeInteger(from) || from < 0 || from > entry.produced) {
+            throw new RangeError('fromOffset must be an observed, nonnegative output byte cursor.');
+        }
+        const literal = Buffer.from(literalText);
+        const suffix = { stdout: Buffer.alloc(0), stderr: Buffer.alloc(0) };
+        const match = (chunk) => {
+            if ((stream !== 'either' && stream !== chunk.stream) ||
+                chunk.offset + chunk.bytes.length <= from)
+                return;
+            const skip = utf8Start(chunk.bytes, Math.max(0, from - chunk.offset));
+            const bytes = Buffer.concat([suffix[chunk.stream], chunk.bytes.subarray(skip)]);
+            const found = bytes.indexOf(literal) !== -1;
+            // Only the bytes that can prefix a future match survive each chunk.
+            // Copy so a tiny suffix never retains a large producer buffer.
+            suffix[chunk.stream] = Buffer.from(bytes.subarray(Math.max(0, bytes.length - literal.length + 1)));
+            return found ? chunk.stream : undefined;
+        };
+        let output = '';
+        let cursor = from;
+        let droppedBytes = 0;
+        let omittedOutputBytes = 0;
+        const read = () => {
+            const observed = this.read(id, { fromOffset: cursor });
+            cursor = observed.nextOffset;
+            droppedBytes += observed.droppedBytes;
+            const tail = outputTail(output + observed.chunk, MAX_WAIT_RESULT_BYTES);
+            output = tail.text;
+            omittedOutputBytes += tail.omitted;
+        };
+        read();
+        const retainedStart = entry.produced - Buffer.byteLength(entry.buffer);
+        const searchableStart = entry.outputChunks[0]?.offset ?? entry.produced;
+        const unsearchedBytes = Math.max(0, searchableStart - Math.max(from, retainedStart));
+        const progress = () => ({
+            status: entry.record.status,
+            ...(entry.record.exitCode === undefined ? {} : { exitCode: entry.record.exitCode }),
+            ...(entry.record.error === undefined ? {} : { error: entry.record.error }),
+            output,
+            nextOffset: cursor,
+            droppedBytes,
+            unsearchedBytes,
+            omittedOutputBytes,
+        });
+        if (signal?.aborted)
+            return Promise.resolve({ ...progress(), kind: 'aborted' });
+        // Check synchronously before subscribing. No process event can intervene
+        // in this call stack, so even a marker printed before activation is seen.
+        for (const chunk of entry.outputChunks) {
+            const matchedStream = match(chunk);
+            if (matchedStream)
+                return Promise.resolve({ ...progress(), kind: 'matched', matchedStream });
+        }
+        if (entry.record.status !== 'running') {
+            return Promise.resolve({
+                ...progress(),
+                kind: entry.record.status === 'killed' ? 'stopped' : 'exited',
+            });
+        }
+        const owner = entry.record.owner;
+        const ownerCount = this.outputWaitersByOwner.get(owner) ?? 0;
+        const ownerLimit = this.config.maxOutputWaitersPerOwner ?? 32;
+        const globalLimit = this.config.maxOutputWaiters ?? 256;
+        if (ownerCount >= ownerLimit)
+            throw new BackgroundJobOutputWaitLimitError({ owner, limit: ownerLimit, scope: 'owner' });
+        if (this.outputWaiters >= globalLimit)
+            throw new BackgroundJobOutputWaitLimitError({ owner, limit: globalLimit, scope: 'registry' });
+        this.outputWaiters++;
+        this.outputWaitersByOwner.set(owner, ownerCount + 1);
+        return new Promise((resolve) => {
+            const startedAt = Date.now();
+            let settled = false;
+            let disposeAbort = () => { };
+            let idleTimer;
+            const finish = (result) => {
+                if (settled)
+                    return;
+                settled = true;
+                entry.outputObservers.delete(observe);
+                clearTimeout(wallTimer);
+                clearTimeout(idleTimer);
+                disposeAbort();
+                this.outputWaiters--;
+                const remaining = (this.outputWaitersByOwner.get(owner) ?? 1) - 1;
+                if (remaining === 0)
+                    this.outputWaitersByOwner.delete(owner);
+                else
+                    this.outputWaitersByOwner.set(owner, remaining);
+                resolve(result);
+            };
+            const timeout = (cause) => {
+                read();
+                finish({ ...progress(), kind: 'timeout', cause, elapsedMs: Date.now() - startedAt });
+            };
+            const resetIdle = () => {
+                if (idleTimeoutMs === undefined)
+                    return;
+                clearTimeout(idleTimer);
+                idleTimer = setTimeout(() => timeout('idle'), idleTimeoutMs);
+                idleTimer.unref?.();
+            };
+            const observe = (chunk) => {
+                read();
+                const matchedStream = chunk ? match(chunk) : undefined;
+                if (matchedStream)
+                    finish({ ...progress(), kind: 'matched', matchedStream });
+                else if (entry.record.status !== 'running') {
+                    finish({ ...progress(), kind: entry.record.status === 'killed' ? 'stopped' : 'exited' });
+                }
+                else if (chunk)
+                    resetIdle();
+            };
+            entry.outputObservers.add(observe);
+            const wallTimer = setTimeout(() => timeout('wall'), timeoutMs);
+            wallTimer.unref?.();
+            resetIdle();
+            if (signal)
+                disposeAbort = subscribeToAbort(signal, () => {
+                    read();
+                    finish({ ...progress(), kind: 'aborted' });
+                });
+        });
     }
     /**
      * Output since `fromOffset`, with what the cap dropped stated.
@@ -249,13 +568,16 @@ export class BackgroundJobRegistry {
         // the gap is reported rather than closed over.
         const effective = Math.max(from, bufferStart);
         const skip = Math.max(0, effective - bufferStart);
-        const chunk = Buffer.from(entry.buffer).subarray(skip).toString('utf8');
+        const bytes = Buffer.from(entry.buffer);
+        const aligned = utf8Start(bytes, skip);
+        const chunk = bytes.subarray(aligned).toString('utf8');
         return {
             chunk,
             nextOffset: entry.produced,
-            droppedBytes: Math.max(0, effective - from),
+            droppedBytes: Math.max(0, effective - from) + Math.max(0, aligned - skip),
             status: entry.record.status,
             ...(entry.record.exitCode === undefined ? {} : { exitCode: entry.record.exitCode }),
+            ...(entry.record.error === undefined ? {} : { error: entry.record.error }),
         };
     }
     /** SIGTERM the tree, then SIGKILL after the shared grace period. */
@@ -265,10 +587,18 @@ export class BackgroundJobRegistry {
             throw new UnknownBackgroundJobError({ id });
         if (entry.record.status !== 'running')
             return entry.record;
+        if (entry.terminateProcess) {
+            entry.killRequested = true;
+            await this.confirmTermination(entry);
+            await entry.exit;
+            return entry.record;
+        }
         // Marked before the signal, so the `close` handler that follows can
         // tell a kill from an ordinary exit. Set it after and the race decides
         // which of two different answers a reader gets.
         entry.record = { ...entry.record, status: 'killed' };
+        for (const observer of entry.outputObservers)
+            observer();
         const signal = (sig) => entry.killProcess ? entry.killProcess(sig) : killTree(entry.child, sig);
         signal('SIGTERM');
         const grace = setTimeout(() => signal('SIGKILL'), SANDBOX_KILL_GRACE_MS);
@@ -345,6 +675,10 @@ export function bindOwner(registry, owner, defaults = {}) {
             });
         },
         get: (id) => mine(id),
+        awaitStarted: (id) => {
+            mine(id);
+            return registry.awaitStarted(id);
+        },
         read: (id, opts) => {
             mine(id);
             return registry.read(id, opts ?? {});
@@ -353,6 +687,10 @@ export function bindOwner(registry, owner, defaults = {}) {
             mine(id);
             return registry.waitForExit(id, opts ?? {});
         },
+        waitForOutput: (id, opts) => {
+            mine(id);
+            return registry.waitForOutput(id, opts);
+        },
         ...(defaults.onAwaited
             ? {
                 markAwaited: (id) => {