@namzu/sdk 32.0.0 → 33.0.0

package/dist/execution/local.js

@@ -1,7 +1,14 @@
 import { spawn } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { resolve } from 'node:path';
+import { killTree } from '../process/kill-tree.js';
+import { subscribeToAbort } from '../utils/abort.js';
 import { BaseExecutionContext } from './base.js';
+import { BoundedTailCapture } from './output.js';
+const LOCAL_COMMAND_DEFAULT_TIMEOUT_MS = 30_000;
+const LOCAL_COMMAND_KILL_GRACE_MS = 3_000;
+const LOCAL_COMMAND_DEFAULT_MAX_OUTPUT_BYTES = 4 * 1024 * 1024;
+const LOCAL_COMMAND_HARD_MAX_OUTPUT_BYTES = 64 * 1024 * 1024;
 export class LocalExecutionContext extends BaseExecutionContext {
     id;
     environment = 'local';
@@ -10,6 +17,14 @@ export class LocalExecutionContext extends BaseExecutionContext {
     envVars;
     capabilities;
     shell;
+    maxOutputBytes;
+    /**
+     * Constructor-created contexts are intentionally executable before
+     * `initialize()`: `createCommandGate()` has always used that public path.
+     * Teardown closes admission synchronously; an explicit initialize reopens it.
+     */
+    acceptsCommands = true;
+    activeCommands = new Set();
     constructor(options) {
         super(options.log);
         this.id = options.id;
@@ -18,6 +33,13 @@ export class LocalExecutionContext extends BaseExecutionContext {
         this.envVars = options.envVars ?? {};
         this.capabilities = options.capabilities ?? ['filesystem', 'process', 'shell'];
         this.shell = options.shell;
+        const maxOutputBytes = options.maxOutputBytes ?? LOCAL_COMMAND_DEFAULT_MAX_OUTPUT_BYTES;
+        if (!Number.isSafeInteger(maxOutputBytes) ||
+            maxOutputBytes <= 0 ||
+            maxOutputBytes > LOCAL_COMMAND_HARD_MAX_OUTPUT_BYTES) {
+            throw new RangeError(`The value of "maxOutputBytes" is out of range. It must be a positive safe integer no greater than ${LOCAL_COMMAND_HARD_MAX_OUTPUT_BYTES}. Received ${maxOutputBytes}`);
+        }
+        this.maxOutputBytes = maxOutputBytes;
     }
     async doInitialize() {
         if (!existsSync(this.cwd)) {
@@ -25,7 +47,21 @@ export class LocalExecutionContext extends BaseExecutionContext {
         }
         this.log.info('Local context initialized', { 'namzu.execution.cwd': this.cwd });
     }
-    async doTeardown() { }
+    onInitializationStarted() {
+        this.acceptsCommands = false;
+    }
+    onInitializationCommitted() {
+        this.acceptsCommands = true;
+    }
+    onTeardownRequested() {
+        this.acceptsCommands = false;
+    }
+    async doTeardown() {
+        const admitted = [...this.activeCommands];
+        for (const operation of admitted)
+            operation.cancel('teardown');
+        await Promise.all(admitted.map((operation) => operation.closed));
+    }
     getCwd() {
         return this.cwd;
     }
@@ -55,56 +91,145 @@ export class LocalExecutionContext extends BaseExecutionContext {
         return this.capabilities.includes(cap);
     }
     async executeCommand(command, args = [], options) {
+        if (!this.acceptsCommands) {
+            throw new Error(`Local execution context "${this.id}" is tearing down or torn down. Call initialize() before executing another command.`);
+        }
         if (!this.hasCapability('process') && !this.hasCapability('shell')) {
             return {
                 exitCode: 1,
                 stdout: '',
                 stderr: 'Command execution not available: context lacks process/shell capability',
+                stdoutTruncated: false,
+                stderrTruncated: false,
                 durationMs: 0,
             };
         }
         const cwd = options?.cwd ? resolve(this.cwd, options.cwd) : this.cwd;
         const env = { ...process.env, ...this.envVars, ...options?.env };
-        const timeoutMs = options?.timeoutMs ?? 30_000;
+        const timeoutMs = options?.timeoutMs ?? LOCAL_COMMAND_DEFAULT_TIMEOUT_MS;
+        if (!Number.isInteger(timeoutMs) || timeoutMs < 0) {
+            throw new RangeError(`The value of "timeoutMs" is out of range. It must be an unsigned integer. Received ${timeoutMs}`);
+        }
         // node's spawn() only keeps argv separation when it execs the binary directly;
         // with shell enabled it re-joins command+args into one unescaped string and hands
         // it to sh/cmd.exe, so any caller-supplied arg becomes shell syntax rather than a
         // literal value. Since `command`/`args` here are whatever a tool call passed in,
         // shell interpretation must be an explicit opt-in, never the silent default.
         const shell = options?.shell ?? this.shell ?? false;
-        return new Promise((resolvePromise) => {
+        const callerSignal = options?.signal;
+        if (callerSignal?.aborted) {
+            return {
+                exitCode: null,
+                stdout: '',
+                stderr: '',
+                stdoutTruncated: false,
+                stderrTruncated: false,
+                durationMs: 0,
+                termination: { origin: 'caller', admitted: false },
+            };
+        }
+        let operation;
+        const result = new Promise((resolvePromise) => {
             const start = performance.now();
             const proc = spawn(command, args, {
                 cwd,
                 env,
                 shell,
-                timeout: timeoutMs,
+                // POSIX process-group ownership is the strongest boundary available
+                // to this host execution context. Windows uses taskkill /T in
+                // `killTree`; neither path relies on Node's direct-child timeout.
+                detached: process.platform !== 'win32',
             });
-            let stdout = '';
-            let stderr = '';
+            const stdout = new BoundedTailCapture(this.maxOutputBytes);
+            const stderr = new BoundedTailCapture(this.maxOutputBytes);
+            let spawnError;
+            let cancellation;
+            let escalation;
+            let deadline;
+            let disposeCallerAbort;
+            let settled = false;
+            const terminate = (signal) => {
+                killTree(proc, signal);
+            };
+            const cancel = (origin) => {
+                if (settled || cancellation !== undefined)
+                    return;
+                cancellation = origin;
+                terminate('SIGTERM');
+                escalation = setTimeout(() => {
+                    escalation = undefined;
+                    terminate('SIGKILL');
+                }, LOCAL_COMMAND_KILL_GRACE_MS);
+                escalation.unref?.();
+            };
+            let resolveClosed;
+            const closed = new Promise((resolveClose) => {
+                resolveClosed = resolveClose;
+            });
+            operation = { cancel, closed };
+            this.activeCommands.add(operation);
+            if (timeoutMs > 0) {
+                deadline = setTimeout(() => cancel('deadline'), timeoutMs);
+                deadline.unref?.();
+            }
             proc.stdout?.on('data', (data) => {
-                stdout += data.toString();
+                stdout.push(data);
             });
             proc.stderr?.on('data', (data) => {
-                stderr += data.toString();
+                stderr.push(data);
             });
-            proc.on('close', (code) => {
-                resolvePromise({
-                    exitCode: code ?? 1,
-                    stdout,
-                    stderr,
-                    durationMs: Math.round(performance.now() - start),
-                });
+            proc.once('error', (err) => {
+                // `close` follows `error` and is the point at which inherited stdio
+                // has drained. Releasing ownership here would strand a descendant
+                // which still holds those descriptors.
+                spawnError = err;
             });
-            proc.on('error', (err) => {
+            proc.once('close', (code, signal) => {
+                if (settled)
+                    return;
+                settled = true;
+                disposeCallerAbort?.();
+                if (deadline !== undefined)
+                    clearTimeout(deadline);
+                if (escalation !== undefined) {
+                    clearTimeout(escalation);
+                    escalation = undefined;
+                    // Do not retain a numeric process-group id for a later timer after
+                    // close: the host can reuse it. Force the cancellation boundary now.
+                    terminate('SIGKILL');
+                }
+                this.activeCommands.delete(operation);
+                resolveClosed?.();
+                if (spawnError !== undefined) {
+                    if (stderr.retainedBytes > 0)
+                        stderr.push(Buffer.from('\n'));
+                    stderr.push(Buffer.from(spawnError.message));
+                }
                 resolvePromise({
-                    exitCode: 1,
-                    stdout,
-                    stderr: err.message,
+                    exitCode: spawnError === undefined ? code : 1,
+                    stdout: stdout.text,
+                    stderr: stderr.text,
+                    stdoutTruncated: stdout.truncated,
+                    stderrTruncated: stderr.truncated,
                     durationMs: Math.round(performance.now() - start),
+                    ...(cancellation === undefined
+                        ? {}
+                        : {
+                            termination: {
+                                origin: cancellation === 'deadline' ? 'timeout' : cancellation,
+                                admitted: true,
+                                ...(signal === null ? {} : { signal }),
+                            },
+                        }),
                 });
             });
+            if (callerSignal !== undefined) {
+                disposeCallerAbort = subscribeToAbort(callerSignal, () => cancel('caller'));
+                if (callerSignal.aborted)
+                    cancel('caller');
+            }
         });
+        return result;
     }
     toConfig() {
         return {
@@ -115,6 +240,7 @@ export class LocalExecutionContext extends BaseExecutionContext {
             envVars: this.envVars,
             capabilities: this.capabilities,
             shell: this.shell,
+            maxOutputBytes: this.maxOutputBytes,
         };
     }
 }

package/dist/execution/local.js.map

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

package/dist/execution/output.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Retain the newest bytes of one command-output stream under a hard bound.
+ *
+ * Bytes stay undecoded until the command closes, so a UTF-8 code point split
+ * across ordinary stream chunks is not corrupted. The backing store grows
+ * geometrically up to the configured cap and becomes a ring only when output
+ * crosses it; no incoming chunk is retained by reference.
+ */
+export declare class BoundedTailCapture {
+    private readonly capBytes;
+    private storage;
+    private start;
+    private length;
+    private lostBytes;
+    constructor(capBytes: number);
+    push(chunk: Buffer): void;
+    /** Ordered copy of the retained raw bytes. */
+    get bytes(): Buffer;
+    get text(): string;
+    get truncated(): boolean;
+    /** Diagnostic invariant used by the internal killing observers. */
+    get retainedBytes(): number;
+    /** Diagnostic invariant used by the internal killing observers. */
+    get allocatedBytes(): number;
+    private ensureCapacity;
+}
+//# sourceMappingURL=output.d.ts.map

package/dist/execution/output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../../src/execution/output.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,qBAAa,kBAAkB;IAMlB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IALrC,OAAO,CAAC,OAAO,CAAkB;IACjC,OAAO,CAAC,KAAK,CAAI;IACjB,OAAO,CAAC,MAAM,CAAI;IAClB,OAAO,CAAC,SAAS,CAAQ;gBAEI,QAAQ,EAAE,MAAM;IAM7C,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IA8BzB,8CAA8C;IAC9C,IAAI,KAAK,IAAI,MAAM,CAOlB;IAED,IAAI,IAAI,IAAI,MAAM,CAcjB;IAED,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,mEAAmE;IACnE,IAAI,aAAa,IAAI,MAAM,CAE1B;IAED,mEAAmE;IACnE,IAAI,cAAc,IAAI,MAAM,CAE3B;IAED,OAAO,CAAC,cAAc;CAatB"}

package/dist/execution/output.js

@@ -0,0 +1,105 @@
+/**
+ * Retain the newest bytes of one command-output stream under a hard bound.
+ *
+ * Bytes stay undecoded until the command closes, so a UTF-8 code point split
+ * across ordinary stream chunks is not corrupted. The backing store grows
+ * geometrically up to the configured cap and becomes a ring only when output
+ * crosses it; no incoming chunk is retained by reference.
+ */
+export class BoundedTailCapture {
+    capBytes;
+    storage = Buffer.alloc(0);
+    start = 0;
+    length = 0;
+    lostBytes = false;
+    constructor(capBytes) {
+        this.capBytes = capBytes;
+        if (!Number.isSafeInteger(capBytes) || capBytes <= 0) {
+            throw new RangeError('BoundedTailCapture capBytes must be a positive safe integer');
+        }
+    }
+    push(chunk) {
+        if (chunk.length === 0)
+            return;
+        if (chunk.length >= this.capBytes) {
+            if (chunk.length > this.capBytes || this.length > 0)
+                this.lostBytes = true;
+            this.ensureCapacity(this.capBytes);
+            chunk.copy(this.storage, 0, chunk.length - this.capBytes);
+            this.start = 0;
+            this.length = this.capBytes;
+            return;
+        }
+        const combinedLength = this.length + chunk.length;
+        if (combinedLength <= this.capBytes) {
+            this.ensureCapacity(combinedLength);
+            chunk.copy(this.storage, this.length);
+            this.length = combinedLength;
+            return;
+        }
+        this.lostBytes = true;
+        this.ensureCapacity(this.capBytes);
+        const end = (this.start + this.length) % this.capBytes;
+        const first = Math.min(chunk.length, this.capBytes - end);
+        chunk.copy(this.storage, end, 0, first);
+        if (first < chunk.length)
+            chunk.copy(this.storage, 0, first);
+        this.start = (this.start + combinedLength - this.capBytes) % this.capBytes;
+        this.length = this.capBytes;
+    }
+    /** Ordered copy of the retained raw bytes. */
+    get bytes() {
+        const ordered = Buffer.allocUnsafe(this.length);
+        if (this.length === 0)
+            return ordered;
+        const first = Math.min(this.length, this.storage.length - this.start);
+        this.storage.copy(ordered, 0, this.start, this.start + first);
+        if (first < this.length)
+            this.storage.copy(ordered, first, 0, this.length - first);
+        return ordered;
+    }
+    get text() {
+        const ordered = this.bytes;
+        let offset = 0;
+        // Tail eviction can leave continuation bytes from a valid UTF-8 code
+        // point at the new left edge. They are an artifact of the cut, not an
+        // authored replacement character, so discard only that partial prefix.
+        if (this.lostBytes) {
+            while (offset < ordered.length) {
+                const firstByte = ordered[offset];
+                if (firstByte === undefined || (firstByte & 0xc0) !== 0x80)
+                    break;
+                offset++;
+            }
+        }
+        return ordered.toString('utf8', offset);
+    }
+    get truncated() {
+        return this.lostBytes;
+    }
+    /** Diagnostic invariant used by the internal killing observers. */
+    get retainedBytes() {
+        return this.length;
+    }
+    /** Diagnostic invariant used by the internal killing observers. */
+    get allocatedBytes() {
+        return this.storage.length;
+    }
+    ensureCapacity(required) {
+        if (this.storage.length >= required)
+            return;
+        let capacity = Math.max(1, this.storage.length);
+        while (capacity < required)
+            capacity = Math.min(this.capBytes, capacity * 2);
+        const grown = Buffer.allocUnsafe(capacity);
+        if (this.length > 0) {
+            const first = Math.min(this.length, this.storage.length - this.start);
+            this.storage.copy(grown, 0, this.start, this.start + first);
+            if (first < this.length)
+                this.storage.copy(grown, first, 0, this.length - first);
+        }
+        this.storage = grown;
+        this.start = 0;
+    }
+}
+//# sourceMappingURL=output.js.map

package/dist/execution/output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.js","sourceRoot":"","sources":["../../src/execution/output.ts"],"names":[],"mappings":"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"}

package/dist/execution/remote.d.ts

@@ -1,22 +1,35 @@
-import type { CommandOptions, CommandResult, ExecutionCapability, ExecutionEnvironment, RemoteCommandHandler, RemoteExecutionContextConfig, RemoteTarget } from '../types/connector/index.js';
+import type { CommandExecutor, CommandOptions, CommandResult, ExecutionCapability, ExecutionEnvironment, RemoteCommandHandler, RemoteExecutionContextConfig, RemoteTarget } from '../types/connector/index.js';
 import type { Logger } from '../utils/logger.js';
 import { BaseExecutionContext } from './base.js';
 export interface RemoteExecutionContextOptions {
     id: string;
     target: RemoteTarget;
     capabilities?: ExecutionCapability[];
+    /**
+     * Executes a command while preserving its argument boundaries at Namzu's
+     * remote seam. A downstream executor may still interpret `shell` according
+     * to its own target.
+     */
+    commandExecutor?: CommandExecutor;
+    /** @deprecated Use `commandExecutor`. */
     commandHandler?: RemoteCommandHandler;
     log?: Logger;
 }
-export declare class RemoteExecutionContext extends BaseExecutionContext {
+export declare class RemoteExecutionContext extends BaseExecutionContext implements CommandExecutor {
     readonly id: string;
     readonly environment: ExecutionEnvironment;
     private target;
     private connected;
     private capabilities;
+    private commandExecutor;
     private commandHandler;
+    private lifecycleAdmissionsOpen;
+    private readonly activeCommands;
     constructor(options: RemoteExecutionContextOptions);
     protected doInitialize(): Promise<void>;
+    protected onInitializationStarted(): void;
+    protected onInitializationCommitted(): void;
+    protected onTeardownRequested(): void;
     protected doTeardown(): Promise<void>;
     connect(): Promise<void>;
     disconnect(): Promise<void>;
@@ -25,9 +38,20 @@ export declare class RemoteExecutionContext extends BaseExecutionContext {
     getConnectionString(): string;
     getCapabilities(): ExecutionCapability[];
     hasCapability(cap: ExecutionCapability): boolean;
+    setCommandExecutor(executor: CommandExecutor): void;
+    /** @deprecated Use `setCommandExecutor()`. */
     setCommandHandler(handler: RemoteCommandHandler): void;
+    executeCommand(command: string, args?: string[], options?: CommandOptions): Promise<CommandResult>;
+    /**
+     * @deprecated Use `executeCommand()` so command arguments retain their
+     * boundaries at Namzu's remote execution seam.
+     */
     executeRemote(command: string, options?: CommandOptions): Promise<CommandResult>;
     toConfig(): RemoteExecutionContextConfig;
     private validateTarget;
+    private admitCommand;
+    private assertCancellationUnsupported;
+    private assertIdleForDisconnect;
+    private trackCommand;
 }
 //# sourceMappingURL=remote.d.ts.map

package/dist/execution/remote.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"remote.d.ts","sourceRoot":"","sources":["../../src/execution/remote.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,cAAc,EACd,aAAa,EACb,mBAAmB,EACnB,oBAAoB,EACpB,oBAAoB,EACpB,4BAA4B,EAC5B,YAAY,EACZ,MAAM,6BAA6B,CAAA;AACpC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAA;AAChD,OAAO,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAA;AAEhD,MAAM,WAAW,6BAA6B;IAC7C,EAAE,EAAE,MAAM,CAAA;IACV,MAAM,EAAE,YAAY,CAAA;IACpB,YAAY,CAAC,EAAE,mBAAmB,EAAE,CAAA;IACpC,cAAc,CAAC,EAAE,oBAAoB,CAAA;IACrC,GAAG,CAAC,EAAE,MAAM,CAAA;CACZ;AAED,qBAAa,sBAAuB,SAAQ,oBAAoB;IAC/D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,WAAW,EAAE,oBAAoB,CAAW;IAErD,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,SAAS,CAAQ;IACzB,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,cAAc,CAAkC;gBAE5C,OAAO,EAAE,6BAA6B;cAQlC,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;cAQ7B,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAWrC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAcxB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAWjC,WAAW,IAAI,OAAO;IAItB,SAAS,IAAI,YAAY;IAIzB,mBAAmB,IAAI,MAAM;IAK7B,eAAe,IAAI,mBAAmB,EAAE;IAIxC,aAAa,CAAC,GAAG,EAAE,mBAAmB,GAAG,OAAO;IAIhD,iBAAiB,CAAC,OAAO,EAAE,oBAAoB,GAAG,IAAI;IAIhD,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IAYtF,QAAQ,IAAI,4BAA4B;IASxC,OAAO,CAAC,cAAc;CAQtB"}
+{"version":3,"file":"remote.d.ts","sourceRoot":"","sources":["../../src/execution/remote.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,eAAe,EACf,cAAc,EACd,aAAa,EACb,mBAAmB,EACnB,oBAAoB,EACpB,oBAAoB,EACpB,4BAA4B,EAC5B,YAAY,EACZ,MAAM,6BAA6B,CAAA;AACpC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAA;AAChD,OAAO,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAA;AAGhD,MAAM,WAAW,6BAA6B;IAC7C,EAAE,EAAE,MAAM,CAAA;IACV,MAAM,EAAE,YAAY,CAAA;IACpB,YAAY,CAAC,EAAE,mBAAmB,EAAE,CAAA;IACpC;;;;OAIG;IACH,eAAe,CAAC,EAAE,eAAe,CAAA;IACjC,yCAAyC;IACzC,cAAc,CAAC,EAAE,oBAAoB,CAAA;IACrC,GAAG,CAAC,EAAE,MAAM,CAAA;CACZ;AAED,qBAAa,sBAAuB,SAAQ,oBAAqB,YAAW,eAAe;IAC1F,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,WAAW,EAAE,oBAAoB,CAAW;IAErD,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,SAAS,CAAQ;IACzB,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,eAAe,CAA6B;IACpD,OAAO,CAAC,cAAc,CAAkC;IACxD,OAAO,CAAC,uBAAuB,CAAO;IACtC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAoB;gBAEvC,OAAO,EAAE,6BAA6B;cASlC,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;cAQ1B,uBAAuB,IAAI,IAAI;cAI/B,yBAAyB,IAAI,IAAI;cAIjC,mBAAmB,IAAI,IAAI;cAI9B,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAKrC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAoBxB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAYjC,WAAW,IAAI,OAAO;IAItB,SAAS,IAAI,YAAY;IAIzB,mBAAmB,IAAI,MAAM;IAK7B,eAAe,IAAI,mBAAmB,EAAE;IAIxC,aAAa,CAAC,GAAG,EAAE,mBAAmB,GAAG,OAAO;IAIhD,kBAAkB,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI;IAInD,8CAA8C;IAC9C,iBAAiB,CAAC,OAAO,EAAE,oBAAoB,GAAG,IAAI;IAIhD,cAAc,CACnB,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,MAAM,EAAO,EACnB,OAAO,CAAC,EAAE,cAAc,GACtB,OAAO,CAAC,aAAa,CAAC;IAmBzB;;;OAGG;IACG,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IAStF,QAAQ,IAAI,4BAA4B;IASxC,OAAO,CAAC,cAAc;IAStB,OAAO,CAAC,YAAY;IAapB,OAAO,CAAC,6BAA6B;IAIrC,OAAO,CAAC,uBAAuB;IAM/B,OAAO,CAAC,YAAY;CA0BpB"}

package/dist/execution/remote.js

@@ -1,16 +1,21 @@
 import { BaseExecutionContext } from './base.js';
+import { CommandCancellationUnsupportedError, RemoteExecutionBusyError } from './errors.js';
 export class RemoteExecutionContext extends BaseExecutionContext {
     id;
     environment = 'remote';
     target;
     connected = false;
     capabilities;
+    commandExecutor;
     commandHandler;
+    lifecycleAdmissionsOpen = true;
+    activeCommands = new Set();
     constructor(options) {
         super(options.log);
         this.id = options.id;
         this.target = options.target;
         this.capabilities = options.capabilities ?? ['network'];
+        this.commandExecutor = options.commandExecutor;
         this.commandHandler = options.commandHandler;
     }
     async doInitialize() {
@@ -20,17 +25,25 @@ export class RemoteExecutionContext extends BaseExecutionContext {
             'namzu.execution.target_host': this.target.host,
         });
     }
+    onInitializationStarted() {
+        this.lifecycleAdmissionsOpen = false;
+    }
+    onInitializationCommitted() {
+        this.lifecycleAdmissionsOpen = true;
+    }
+    onTeardownRequested() {
+        this.lifecycleAdmissionsOpen = false;
+    }
     async doTeardown() {
-        if (this.connected) {
-            this.connected = false;
-            this.emit({
-                type: 'remote_disconnected',
-                contextId: this.id,
-                host: this.target.host,
-            });
-        }
+        this.assertIdleForDisconnect();
+        await this.disconnect();
     }
     async connect() {
+        if (!this.lifecycleAdmissionsOpen) {
+            throw new Error(`Remote execution context "${this.id}" cannot connect until initialization commits after teardown or failed initialization.`);
+        }
+        if (this.connected)
+            return;
         this.connected = true;
         this.emit({
             type: 'remote_connected',
@@ -46,6 +59,7 @@ export class RemoteExecutionContext extends BaseExecutionContext {
     async disconnect() {
         if (!this.connected)
             return;
+        this.assertIdleForDisconnect();
         this.connected = false;
         this.emit({
             type: 'remote_disconnected',
@@ -70,17 +84,32 @@ export class RemoteExecutionContext extends BaseExecutionContext {
     hasCapability(cap) {
         return this.capabilities.includes(cap);
     }
+    setCommandExecutor(executor) {
+        this.commandExecutor = executor;
+    }
+    /** @deprecated Use `setCommandExecutor()`. */
     setCommandHandler(handler) {
         this.commandHandler = handler;
     }
-    async executeRemote(command, options) {
-        if (!this.commandHandler) {
-            throw new Error(`No remote command handler configured for context "${this.id}". Set one via setCommandHandler() before calling executeRemote().`);
-        }
-        if (!this.connected) {
-            throw new Error(`Remote context "${this.id}" is not connected. Call connect() first.`);
+    async executeCommand(command, args = [], options) {
+        if (this.commandExecutor) {
+            const executor = this.admitCommand(this.commandExecutor, `No remote command executor configured for context "${this.id}". Set one via setCommandExecutor() before calling executeCommand().`);
+            this.assertCancellationUnsupported(options?.signal);
+            return this.trackCommand(() => executor.executeCommand(command, args, options));
         }
-        return this.commandHandler.executeRemote(command, options);
+        const handler = this.admitCommand(this.commandHandler, `No remote command executor configured for context "${this.id}". Set one via setCommandExecutor() before calling executeCommand().`);
+        this.assertCancellationUnsupported(options?.signal);
+        const fullCommand = args.length > 0 ? `${command} ${args.join(' ')}` : command;
+        return this.trackCommand(() => handler.executeRemote(fullCommand, options));
+    }
+    /**
+     * @deprecated Use `executeCommand()` so command arguments retain their
+     * boundaries at Namzu's remote execution seam.
+     */
+    async executeRemote(command, options) {
+        const handler = this.admitCommand(this.commandHandler, `No remote command handler configured for context "${this.id}". Set one via setCommandHandler() before calling executeRemote().`);
+        this.assertCancellationUnsupported(options?.signal);
+        return this.trackCommand(() => handler.executeRemote(command, options));
     }
     toConfig() {
         return {
@@ -98,5 +127,47 @@ export class RemoteExecutionContext extends BaseExecutionContext {
             throw new Error(`Unsupported remote target type: "${target.type}"`);
         }
     }
+    admitCommand(implementation, missingMessage) {
+        if (implementation === undefined)
+            throw new Error(missingMessage);
+        if (!this.lifecycleAdmissionsOpen) {
+            throw new Error(`Remote execution context "${this.id}" is initializing, tearing down, or torn down. Wait for initialization to commit before executing another command.`);
+        }
+        if (!this.connected) {
+            throw new Error(`Remote context "${this.id}" is not connected. Call connect() first.`);
+        }
+        return implementation;
+    }
+    assertCancellationUnsupported(signal) {
+        if (signal !== undefined)
+            throw new CommandCancellationUnsupportedError(this.id);
+    }
+    assertIdleForDisconnect() {
+        if (this.activeCommands.size > 0) {
+            throw new RemoteExecutionBusyError(this.id, this.activeCommands.size);
+        }
+    }
+    trackCommand(invoke) {
+        const ownership = Symbol('remote-command');
+        this.activeCommands.add(ownership);
+        const release = () => {
+            this.activeCommands.delete(ownership);
+        };
+        let operation;
+        try {
+            operation = Promise.resolve(invoke());
+        }
+        catch (error) {
+            release();
+            return Promise.reject(error);
+        }
+        return operation.then((result) => {
+            release();
+            return result;
+        }, (error) => {
+            release();
+            throw error;
+        });
+    }
 }
 //# sourceMappingURL=remote.js.map