@vercel/sandbox 2.0.0-beta.11 → 2.0.0-beta.13

package/dist/command.cjs

@@ -0,0 +1,328 @@
+const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
+const require_api_client = require('./api-client/api-client.cjs');
+require('./api-client/index.cjs');
+const require_get_credentials = require('./utils/get-credentials.cjs');
+const require_resolveSignal = require('./utils/resolveSignal.cjs');
+let __workflow_serde = require("@workflow/serde");
+
+//#region src/command.ts
+/**
+* A command executed in a Sandbox.
+*
+* For detached commands, you can {@link wait} to get a {@link CommandFinished} instance
+* with the populated exit code. For non-detached commands, {@link Sandbox.runCommand}
+* automatically waits and returns a {@link CommandFinished} instance.
+*
+* You can iterate over command output with {@link logs}.
+*
+* @see {@link Sandbox.runCommand} to start a command.
+*
+* @hideconstructor
+*/
+var Command = class Command {
+	/**
+	* Lazily resolve credentials and construct an API client.
+	* @internal
+	*/
+	async ensureClient() {
+		"use step";
+		if (this._client) return this._client;
+		const credentials = await require_get_credentials.getCredentials();
+		this._client = new require_api_client.APIClient({
+			teamId: credentials.teamId,
+			token: credentials.token
+		});
+		return this._client;
+	}
+	/**
+	* ID of the command execution.
+	*/
+	get cmdId() {
+		return this.cmd.id;
+	}
+	get cwd() {
+		return this.cmd.cwd;
+	}
+	get startedAt() {
+		return this.cmd.startedAt;
+	}
+	/**
+	* @param params - Object containing the client, sandbox ID, and command data.
+	* @param params.client - Optional API client. If not provided, will be lazily created using global credentials.
+	* @param params.sessionId - The ID of the session where the command is running.
+	* @param params.cmd - The command data.
+	* @param params.output - Optional cached output to restore (used during deserialization).
+	*/
+	constructor({ client, sessionId, cmd, output }) {
+		this._client = null;
+		this.outputCache = null;
+		this._resolvedOutput = null;
+		this._client = client ?? null;
+		this.sessionId = sessionId;
+		this.cmd = cmd;
+		this.exitCode = cmd.exitCode ?? null;
+		if (output) {
+			this._resolvedOutput = output;
+			this.outputCache = Promise.resolve({
+				stdout: output.stdout,
+				stderr: output.stderr,
+				both: output.stdout + output.stderr
+			});
+		}
+	}
+	/**
+	* Serialize a Command instance to plain data for @workflow/serde.
+	*
+	* @param instance - The Command instance to serialize
+	* @returns A plain object containing the sandbox ID, command data, and output if fetched
+	*/
+	static [__workflow_serde.WORKFLOW_SERIALIZE](instance) {
+		const serialized = {
+			sandboxId: instance.sessionId,
+			cmd: instance.cmd
+		};
+		if (instance._resolvedOutput) serialized.output = instance._resolvedOutput;
+		return serialized;
+	}
+	/**
+	* Deserialize plain data back into a Command instance for @workflow/serde.
+	*
+	* The deserialized instance will lazily create an API client using
+	* OIDC or environment credentials when needed.
+	*
+	* @param data - The serialized command data
+	* @returns The reconstructed Command instance
+	*/
+	static [__workflow_serde.WORKFLOW_DESERIALIZE](data) {
+		return new Command({
+			sessionId: data.sandboxId,
+			cmd: data.cmd,
+			output: data.output
+		});
+	}
+	/**
+	* Iterate over the output of this command.
+	*
+	* ```
+	* for await (const log of cmd.logs()) {
+	*   if (log.stream === "stdout") {
+	*     process.stdout.write(log.data);
+	*   } else {
+	*     process.stderr.write(log.data);
+	*   }
+	* }
+	* ```
+	*
+	* @param opts - Optional parameters.
+	* @param opts.signal - An AbortSignal to cancel log streaming.
+	* @returns An async iterable of log entries from the command output.
+	*
+	* @see {@link Command.stdout}, {@link Command.stderr}, and {@link Command.output}
+	* to access output as a string.
+	*/
+	logs(opts) {
+		if (!this._client) throw new Error("logs() requires an API client. Call an async method first to initialize the client.");
+		return this._client.getLogs({
+			sessionId: this.sessionId,
+			cmdId: this.cmd.id,
+			signal: opts?.signal
+		});
+	}
+	/**
+	* Wait for a command to exit and populate its exit code.
+	*
+	* This method is useful for detached commands where you need to wait
+	* for completion. For non-detached commands, {@link Sandbox.runCommand}
+	* automatically waits and returns a {@link CommandFinished} instance.
+	*
+	* ```
+	* const detachedCmd = await sandbox.runCommand({ cmd: 'sleep', args: ['5'], detached: true });
+	* const result = await detachedCmd.wait();
+	* if (result.exitCode !== 0) {
+	*   console.error("Something went wrong...")
+	* }
+	* ```
+	*
+	* @param params - Optional parameters.
+	* @param params.signal - An AbortSignal to cancel waiting.
+	* @returns A {@link CommandFinished} instance with populated exit code.
+	*/
+	async wait(params) {
+		"use step";
+		const client = await this.ensureClient();
+		params?.signal?.throwIfAborted();
+		const command = await client.getCommand({
+			sessionId: this.sessionId,
+			cmdId: this.cmd.id,
+			wait: true,
+			signal: params?.signal
+		});
+		return new CommandFinished({
+			client,
+			sessionId: this.sessionId,
+			cmd: command.json.command,
+			exitCode: command.json.command.exitCode
+		});
+	}
+	/**
+	* Get cached output, fetching logs only once and reusing for concurrent calls.
+	* This prevents race conditions when stdout() and stderr() are called in parallel.
+	*/
+	async getCachedOutput(opts) {
+		if (!this.outputCache) this.outputCache = (async () => {
+			try {
+				opts?.signal?.throwIfAborted();
+				await this.ensureClient();
+				let stdout = "";
+				let stderr = "";
+				let both = "";
+				for await (const log of this.logs({ signal: opts?.signal })) {
+					both += log.data;
+					if (log.stream === "stdout") stdout += log.data;
+					else stderr += log.data;
+				}
+				this._resolvedOutput = {
+					stdout,
+					stderr
+				};
+				return {
+					stdout,
+					stderr,
+					both
+				};
+			} catch (err) {
+				this.outputCache = null;
+				throw err;
+			}
+		})();
+		return this.outputCache;
+	}
+	/**
+	* Get the output of `stdout`, `stderr`, or both as a string.
+	*
+	* NOTE: This may throw string conversion errors if the command does
+	* not output valid Unicode.
+	*
+	* @param stream - The output stream to read: "stdout", "stderr", or "both".
+	* @param opts - Optional parameters.
+	* @param opts.signal - An AbortSignal to cancel output streaming.
+	* @returns The output of the specified stream(s) as a string.
+	*/
+	async output(stream = "both", opts) {
+		"use step";
+		return (await this.getCachedOutput(opts))[stream];
+	}
+	/**
+	* Get the output of `stdout` as a string.
+	*
+	* NOTE: This may throw string conversion errors if the command does
+	* not output valid Unicode.
+	*
+	* @param opts - Optional parameters.
+	* @param opts.signal - An AbortSignal to cancel output streaming.
+	* @returns The standard output of the command.
+	*/
+	async stdout(opts) {
+		"use step";
+		return this.output("stdout", opts);
+	}
+	/**
+	* Get the output of `stderr` as a string.
+	*
+	* NOTE: This may throw string conversion errors if the command does
+	* not output valid Unicode.
+	*
+	* @param opts - Optional parameters.
+	* @param opts.signal - An AbortSignal to cancel output streaming.
+	* @returns The standard error output of the command.
+	*/
+	async stderr(opts) {
+		"use step";
+		return this.output("stderr", opts);
+	}
+	/**
+	* Kill a running command in a sandbox.
+	*
+	* @param signal - The signal to send the running process. Defaults to SIGTERM.
+	* @param opts - Optional parameters.
+	* @param opts.abortSignal - An AbortSignal to cancel the kill operation.
+	* @returns Promise<void>.
+	*/
+	async kill(signal, opts) {
+		"use step";
+		await (await this.ensureClient()).killCommand({
+			sessionId: this.sessionId,
+			commandId: this.cmd.id,
+			signal: require_resolveSignal.resolveSignal(signal ?? "SIGTERM"),
+			abortSignal: opts?.abortSignal
+		});
+	}
+};
+/**
+* A command that has finished executing.
+*
+* The exit code is immediately available and populated upon creation.
+* Unlike {@link Command}, you don't need to call wait() - the command
+* has already completed execution.
+*
+* @hideconstructor
+*/
+var CommandFinished = class CommandFinished extends Command {
+	/**
+	* @param params - Object containing client, sandbox ID, command data, and exit code.
+	* @param params.client - Optional API client. If not provided, will be lazily created using global credentials.
+	* @param params.sessionId - The ID of the session where the command ran.
+	* @param params.cmd - The command data.
+	* @param params.exitCode - The exit code of the completed command.
+	* @param params.output - Optional cached output to restore (used during deserialization).
+	*/
+	constructor(params) {
+		super({ ...params });
+		this.exitCode = params.exitCode;
+	}
+	/**
+	* Serialize a CommandFinished instance to plain data for @workflow/serde.
+	*
+	* @param instance - The CommandFinished instance to serialize
+	* @returns A plain object containing the sandbox ID, command data, exit code, and output if fetched
+	*/
+	static [__workflow_serde.WORKFLOW_SERIALIZE](instance) {
+		return {
+			...Command[__workflow_serde.WORKFLOW_SERIALIZE](instance),
+			exitCode: instance.exitCode
+		};
+	}
+	/**
+	* Deserialize plain data back into a CommandFinished instance for @workflow/serde.
+	*
+	* The deserialized instance will lazily create an API client using
+	* OIDC or environment credentials when needed.
+	*
+	* @param data - The serialized command finished data
+	* @returns The reconstructed CommandFinished instance
+	*/
+	static [__workflow_serde.WORKFLOW_DESERIALIZE](data) {
+		return new CommandFinished({
+			sessionId: data.sandboxId,
+			cmd: data.cmd,
+			exitCode: data.exitCode,
+			output: data.output
+		});
+	}
+	/**
+	* The wait method is not needed for CommandFinished instances since
+	* the command has already completed and exitCode is populated.
+	*
+	* @deprecated This method is redundant for CommandFinished instances.
+	* The exitCode is already available.
+	* @returns This CommandFinished instance.
+	*/
+	async wait() {
+		return this;
+	}
+};
+
+//#endregion
+exports.Command = Command;
+exports.CommandFinished = CommandFinished;
+//# sourceMappingURL=command.cjs.map

package/dist/command.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"command.cjs","names":["getCredentials","APIClient","WORKFLOW_SERIALIZE","serialized: SerializedCommand","WORKFLOW_DESERIALIZE","resolveSignal"],"sources":["../src/command.ts"],"sourcesContent":["import { WORKFLOW_DESERIALIZE, WORKFLOW_SERIALIZE } from \"@workflow/serde\";\nimport { APIClient, type CommandData } from \"./api-client/index.js\";\nimport { getCredentials } from \"./utils/get-credentials.js\";\nimport { resolveSignal, type Signal } from \"./utils/resolveSignal.js\";\n\n/**\n * Cached output from a command execution.\n */\nexport interface CommandOutput {\n  stdout: string;\n  stderr: string;\n}\n\n/**\n * Serialized representation of a Command for @workflow/serde.\n */\nexport interface SerializedCommand {\n  sandboxId: string;\n  cmd: CommandData;\n  /** Cached output, included if output was fetched before serialization */\n  output?: CommandOutput;\n}\n\n/**\n * Serialized representation of a CommandFinished for @workflow/serde.\n */\nexport interface SerializedCommandFinished extends SerializedCommand {\n  exitCode: number;\n}\n\n/**\n * A command executed in a Sandbox.\n *\n * For detached commands, you can {@link wait} to get a {@link CommandFinished} instance\n * with the populated exit code. For non-detached commands, {@link Sandbox.runCommand}\n * automatically waits and returns a {@link CommandFinished} instance.\n *\n * You can iterate over command output with {@link logs}.\n *\n * @see {@link Sandbox.runCommand} to start a command.\n *\n * @hideconstructor\n */\nexport class Command {\n  /**\n   * Cached API client instance.\n   * @internal\n   */\n  protected _client: APIClient | null = null;\n\n  /**\n   * Lazily resolve credentials and construct an API client.\n   * @internal\n   */\n  protected async ensureClient(): Promise<APIClient> {\n    \"use step\";\n    if (this._client) return this._client;\n    const credentials = await getCredentials();\n    this._client = new APIClient({\n      teamId: credentials.teamId,\n      token: credentials.token,\n    });\n    return this._client;\n  }\n\n  /**\n   * ID of the session this command is running in.\n   */\n  protected sessionId: string;\n\n  /**\n   * Data for the command execution.\n   */\n  protected cmd: CommandData;\n\n  public exitCode: number | null;\n\n  protected outputCache: Promise<{\n    stdout: string;\n    stderr: string;\n    both: string;\n  }> | null = null;\n\n  /**\n   * Synchronously accessible resolved output, populated after output is fetched.\n   * Used for serialization.\n   * @internal\n   */\n  protected _resolvedOutput: CommandOutput | null = null;\n\n  /**\n   * ID of the command execution.\n   */\n  get cmdId() {\n    return this.cmd.id;\n  }\n\n  get cwd() {\n    return this.cmd.cwd;\n  }\n\n  get startedAt() {\n    return this.cmd.startedAt;\n  }\n\n  /**\n   * @param params - Object containing the client, sandbox ID, and command data.\n   * @param params.client - Optional API client. If not provided, will be lazily created using global credentials.\n   * @param params.sessionId - The ID of the session where the command is running.\n   * @param params.cmd - The command data.\n   * @param params.output - Optional cached output to restore (used during deserialization).\n   */\n  constructor({\n    client,\n    sessionId,\n    cmd,\n    output,\n  }: {\n    client?: APIClient;\n    sessionId: string;\n    cmd: CommandData;\n    output?: CommandOutput;\n  }) {\n    this._client = client ?? null;\n    this.sessionId = sessionId;\n    this.cmd = cmd;\n    this.exitCode = cmd.exitCode ?? null;\n    if (output) {\n      this._resolvedOutput = output;\n      // Note: `both` is reconstructed as stdout + stderr concatenation,\n      // which loses the original interleaved order of the streams.\n      this.outputCache = Promise.resolve({\n        stdout: output.stdout,\n        stderr: output.stderr,\n        both: output.stdout + output.stderr,\n      });\n    }\n  }\n\n  /**\n   * Serialize a Command instance to plain data for @workflow/serde.\n   *\n   * @param instance - The Command instance to serialize\n   * @returns A plain object containing the sandbox ID, command data, and output if fetched\n   */\n  static [WORKFLOW_SERIALIZE](instance: Command): SerializedCommand {\n    const serialized: SerializedCommand = {\n      sandboxId: instance.sessionId,\n      cmd: instance.cmd,\n    };\n    if (instance._resolvedOutput) {\n      serialized.output = instance._resolvedOutput;\n    }\n    return serialized;\n  }\n\n  /**\n   * Deserialize plain data back into a Command instance for @workflow/serde.\n   *\n   * The deserialized instance will lazily create an API client using\n   * OIDC or environment credentials when needed.\n   *\n   * @param data - The serialized command data\n   * @returns The reconstructed Command instance\n   */\n  static [WORKFLOW_DESERIALIZE](data: SerializedCommand): Command {\n    return new Command({\n      sessionId: data.sandboxId,\n      cmd: data.cmd,\n      output: data.output,\n    });\n  }\n\n  /**\n   * Iterate over the output of this command.\n   *\n   * ```\n   * for await (const log of cmd.logs()) {\n   *   if (log.stream === \"stdout\") {\n   *     process.stdout.write(log.data);\n   *   } else {\n   *     process.stderr.write(log.data);\n   *   }\n   * }\n   * ```\n   *\n   * @param opts - Optional parameters.\n   * @param opts.signal - An AbortSignal to cancel log streaming.\n   * @returns An async iterable of log entries from the command output.\n   *\n   * @see {@link Command.stdout}, {@link Command.stderr}, and {@link Command.output}\n   * to access output as a string.\n   */\n  logs(opts?: { signal?: AbortSignal }) {\n    if (!this._client) {\n      throw new Error(\n        \"logs() requires an API client. Call an async method first to initialize the client.\",\n      );\n    }\n    return this._client.getLogs({\n      sessionId: this.sessionId,\n      cmdId: this.cmd.id,\n      signal: opts?.signal,\n    });\n  }\n\n  /**\n   * Wait for a command to exit and populate its exit code.\n   *\n   * This method is useful for detached commands where you need to wait\n   * for completion. For non-detached commands, {@link Sandbox.runCommand}\n   * automatically waits and returns a {@link CommandFinished} instance.\n   *\n   * ```\n   * const detachedCmd = await sandbox.runCommand({ cmd: 'sleep', args: ['5'], detached: true });\n   * const result = await detachedCmd.wait();\n   * if (result.exitCode !== 0) {\n   *   console.error(\"Something went wrong...\")\n   * }\n   * ```\n   *\n   * @param params - Optional parameters.\n   * @param params.signal - An AbortSignal to cancel waiting.\n   * @returns A {@link CommandFinished} instance with populated exit code.\n   */\n  async wait(params?: { signal?: AbortSignal }) {\n    \"use step\";\n    const client = await this.ensureClient();\n    params?.signal?.throwIfAborted();\n\n    const command = await client.getCommand({\n      sessionId: this.sessionId,\n      cmdId: this.cmd.id,\n      wait: true,\n      signal: params?.signal,\n    });\n\n    return new CommandFinished({\n      client,\n      sessionId: this.sessionId,\n      cmd: command.json.command,\n      exitCode: command.json.command.exitCode,\n    });\n  }\n\n  /**\n   * Get cached output, fetching logs only once and reusing for concurrent calls.\n   * This prevents race conditions when stdout() and stderr() are called in parallel.\n   */\n  protected async getCachedOutput(opts?: { signal?: AbortSignal }): Promise<{\n    stdout: string;\n    stderr: string;\n    both: string;\n  }> {\n    if (!this.outputCache) {\n      this.outputCache = (async () => {\n        try {\n          opts?.signal?.throwIfAborted();\n          // Ensure the API client is initialized before calling logs(),\n          // since logs() is synchronous and requires _client to be set.\n          await this.ensureClient();\n          let stdout = \"\";\n          let stderr = \"\";\n          let both = \"\";\n          for await (const log of this.logs({ signal: opts?.signal })) {\n            both += log.data;\n            if (log.stream === \"stdout\") {\n              stdout += log.data;\n            } else {\n              stderr += log.data;\n            }\n          }\n          // Store resolved output for serialization\n          this._resolvedOutput = { stdout, stderr };\n          return { stdout, stderr, both };\n        } catch (err) {\n          // Clear the promise so future calls can retry\n          this.outputCache = null;\n          throw err;\n        }\n      })();\n    }\n\n    return this.outputCache;\n  }\n\n  /**\n   * Get the output of `stdout`, `stderr`, or both as a string.\n   *\n   * NOTE: This may throw string conversion errors if the command does\n   * not output valid Unicode.\n   *\n   * @param stream - The output stream to read: \"stdout\", \"stderr\", or \"both\".\n   * @param opts - Optional parameters.\n   * @param opts.signal - An AbortSignal to cancel output streaming.\n   * @returns The output of the specified stream(s) as a string.\n   */\n  async output(\n    stream: \"stdout\" | \"stderr\" | \"both\" = \"both\",\n    opts?: { signal?: AbortSignal },\n  ) {\n    \"use step\";\n    const cached = await this.getCachedOutput(opts);\n    return cached[stream];\n  }\n\n  /**\n   * Get the output of `stdout` as a string.\n   *\n   * NOTE: This may throw string conversion errors if the command does\n   * not output valid Unicode.\n   *\n   * @param opts - Optional parameters.\n   * @param opts.signal - An AbortSignal to cancel output streaming.\n   * @returns The standard output of the command.\n   */\n  async stdout(opts?: { signal?: AbortSignal }) {\n    \"use step\";\n    return this.output(\"stdout\", opts);\n  }\n\n  /**\n   * Get the output of `stderr` as a string.\n   *\n   * NOTE: This may throw string conversion errors if the command does\n   * not output valid Unicode.\n   *\n   * @param opts - Optional parameters.\n   * @param opts.signal - An AbortSignal to cancel output streaming.\n   * @returns The standard error output of the command.\n   */\n  async stderr(opts?: { signal?: AbortSignal }) {\n    \"use step\";\n    return this.output(\"stderr\", opts);\n  }\n\n  /**\n   * Kill a running command in a sandbox.\n   *\n   * @param signal - The signal to send the running process. Defaults to SIGTERM.\n   * @param opts - Optional parameters.\n   * @param opts.abortSignal - An AbortSignal to cancel the kill operation.\n   * @returns Promise<void>.\n   */\n  async kill(signal?: Signal, opts?: { abortSignal?: AbortSignal }) {\n    \"use step\";\n    const client = await this.ensureClient();\n    await client.killCommand({\n      sessionId: this.sessionId,\n      commandId: this.cmd.id,\n      signal: resolveSignal(signal ?? \"SIGTERM\"),\n      abortSignal: opts?.abortSignal,\n    });\n  }\n}\n\n/**\n * A command that has finished executing.\n *\n * The exit code is immediately available and populated upon creation.\n * Unlike {@link Command}, you don't need to call wait() - the command\n * has already completed execution.\n *\n * @hideconstructor\n */\nexport class CommandFinished extends Command {\n  /**\n   * The exit code of the command. This is always populated for\n   * CommandFinished instances.\n   */\n  public exitCode: number;\n\n  /**\n   * @param params - Object containing client, sandbox ID, command data, and exit code.\n   * @param params.client - Optional API client. If not provided, will be lazily created using global credentials.\n   * @param params.sessionId - The ID of the session where the command ran.\n   * @param params.cmd - The command data.\n   * @param params.exitCode - The exit code of the completed command.\n   * @param params.output - Optional cached output to restore (used during deserialization).\n   */\n  constructor(params: {\n    client?: APIClient;\n    sessionId: string;\n    cmd: CommandData;\n    exitCode: number;\n    output?: CommandOutput;\n  }) {\n    super({ ...params });\n    this.exitCode = params.exitCode;\n  }\n\n  /**\n   * Serialize a CommandFinished instance to plain data for @workflow/serde.\n   *\n   * @param instance - The CommandFinished instance to serialize\n   * @returns A plain object containing the sandbox ID, command data, exit code, and output if fetched\n   */\n  static [WORKFLOW_SERIALIZE](\n    instance: CommandFinished,\n  ): SerializedCommandFinished {\n    return {\n      ...Command[WORKFLOW_SERIALIZE](instance),\n      exitCode: instance.exitCode,\n    };\n  }\n\n  /**\n   * Deserialize plain data back into a CommandFinished instance for @workflow/serde.\n   *\n   * The deserialized instance will lazily create an API client using\n   * OIDC or environment credentials when needed.\n   *\n   * @param data - The serialized command finished data\n   * @returns The reconstructed CommandFinished instance\n   */\n  static [WORKFLOW_DESERIALIZE](\n    data: SerializedCommandFinished,\n  ): CommandFinished {\n    return new CommandFinished({\n      sessionId: data.sandboxId,\n      cmd: data.cmd,\n      exitCode: data.exitCode,\n      output: data.output,\n    });\n  }\n\n  /**\n   * The wait method is not needed for CommandFinished instances since\n   * the command has already completed and exitCode is populated.\n   *\n   * @deprecated This method is redundant for CommandFinished instances.\n   * The exitCode is already available.\n   * @returns This CommandFinished instance.\n   */\n  async wait(): Promise<CommandFinished> {\n    return this;\n  }\n}\n"],"mappings":"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"}

package/dist/command.d.cts

@@ -0,0 +1,289 @@
+import { CommandData } from "./api-client/validators.cjs";
+import { APIClient } from "./api-client/api-client.cjs";
+import { Signal } from "./utils/resolveSignal.cjs";
+import { WORKFLOW_DESERIALIZE, WORKFLOW_SERIALIZE } from "@workflow/serde";
+
+//#region src/command.d.ts
+/**
+ * Cached output from a command execution.
+ */
+interface CommandOutput {
+  stdout: string;
+  stderr: string;
+}
+/**
+ * Serialized representation of a Command for @workflow/serde.
+ */
+interface SerializedCommand {
+  sandboxId: string;
+  cmd: CommandData;
+  /** Cached output, included if output was fetched before serialization */
+  output?: CommandOutput;
+}
+/**
+ * Serialized representation of a CommandFinished for @workflow/serde.
+ */
+interface SerializedCommandFinished extends SerializedCommand {
+  exitCode: number;
+}
+/**
+ * A command executed in a Sandbox.
+ *
+ * For detached commands, you can {@link wait} to get a {@link CommandFinished} instance
+ * with the populated exit code. For non-detached commands, {@link Sandbox.runCommand}
+ * automatically waits and returns a {@link CommandFinished} instance.
+ *
+ * You can iterate over command output with {@link logs}.
+ *
+ * @see {@link Sandbox.runCommand} to start a command.
+ *
+ * @hideconstructor
+ */
+declare class Command {
+  /**
+   * Cached API client instance.
+   * @internal
+   */
+  protected _client: APIClient | null;
+  /**
+   * Lazily resolve credentials and construct an API client.
+   * @internal
+   */
+  protected ensureClient(): Promise<APIClient>;
+  /**
+   * ID of the session this command is running in.
+   */
+  protected sessionId: string;
+  /**
+   * Data for the command execution.
+   */
+  protected cmd: CommandData;
+  exitCode: number | null;
+  protected outputCache: Promise<{
+    stdout: string;
+    stderr: string;
+    both: string;
+  }> | null;
+  /**
+   * Synchronously accessible resolved output, populated after output is fetched.
+   * Used for serialization.
+   * @internal
+   */
+  protected _resolvedOutput: CommandOutput | null;
+  /**
+   * ID of the command execution.
+   */
+  get cmdId(): string;
+  get cwd(): string;
+  get startedAt(): number;
+  /**
+   * @param params - Object containing the client, sandbox ID, and command data.
+   * @param params.client - Optional API client. If not provided, will be lazily created using global credentials.
+   * @param params.sessionId - The ID of the session where the command is running.
+   * @param params.cmd - The command data.
+   * @param params.output - Optional cached output to restore (used during deserialization).
+   */
+  constructor({
+    client,
+    sessionId,
+    cmd,
+    output
+  }: {
+    client?: APIClient;
+    sessionId: string;
+    cmd: CommandData;
+    output?: CommandOutput;
+  });
+  /**
+   * Serialize a Command instance to plain data for @workflow/serde.
+   *
+   * @param instance - The Command instance to serialize
+   * @returns A plain object containing the sandbox ID, command data, and output if fetched
+   */
+  static [WORKFLOW_SERIALIZE](instance: Command): SerializedCommand;
+  /**
+   * Deserialize plain data back into a Command instance for @workflow/serde.
+   *
+   * The deserialized instance will lazily create an API client using
+   * OIDC or environment credentials when needed.
+   *
+   * @param data - The serialized command data
+   * @returns The reconstructed Command instance
+   */
+  static [WORKFLOW_DESERIALIZE](data: SerializedCommand): Command;
+  /**
+   * Iterate over the output of this command.
+   *
+   * ```
+   * for await (const log of cmd.logs()) {
+   *   if (log.stream === "stdout") {
+   *     process.stdout.write(log.data);
+   *   } else {
+   *     process.stderr.write(log.data);
+   *   }
+   * }
+   * ```
+   *
+   * @param opts - Optional parameters.
+   * @param opts.signal - An AbortSignal to cancel log streaming.
+   * @returns An async iterable of log entries from the command output.
+   *
+   * @see {@link Command.stdout}, {@link Command.stderr}, and {@link Command.output}
+   * to access output as a string.
+   */
+  logs(opts?: {
+    signal?: AbortSignal;
+  }): AsyncGenerator<{
+    data: string;
+    stream: "stdout";
+  } | {
+    data: string;
+    stream: "stderr";
+  }, void, void> & Disposable & {
+    close(): void;
+  };
+  /**
+   * Wait for a command to exit and populate its exit code.
+   *
+   * This method is useful for detached commands where you need to wait
+   * for completion. For non-detached commands, {@link Sandbox.runCommand}
+   * automatically waits and returns a {@link CommandFinished} instance.
+   *
+   * ```
+   * const detachedCmd = await sandbox.runCommand({ cmd: 'sleep', args: ['5'], detached: true });
+   * const result = await detachedCmd.wait();
+   * if (result.exitCode !== 0) {
+   *   console.error("Something went wrong...")
+   * }
+   * ```
+   *
+   * @param params - Optional parameters.
+   * @param params.signal - An AbortSignal to cancel waiting.
+   * @returns A {@link CommandFinished} instance with populated exit code.
+   */
+  wait(params?: {
+    signal?: AbortSignal;
+  }): Promise<CommandFinished>;
+  /**
+   * Get cached output, fetching logs only once and reusing for concurrent calls.
+   * This prevents race conditions when stdout() and stderr() are called in parallel.
+   */
+  protected getCachedOutput(opts?: {
+    signal?: AbortSignal;
+  }): Promise<{
+    stdout: string;
+    stderr: string;
+    both: string;
+  }>;
+  /**
+   * Get the output of `stdout`, `stderr`, or both as a string.
+   *
+   * NOTE: This may throw string conversion errors if the command does
+   * not output valid Unicode.
+   *
+   * @param stream - The output stream to read: "stdout", "stderr", or "both".
+   * @param opts - Optional parameters.
+   * @param opts.signal - An AbortSignal to cancel output streaming.
+   * @returns The output of the specified stream(s) as a string.
+   */
+  output(stream?: "stdout" | "stderr" | "both", opts?: {
+    signal?: AbortSignal;
+  }): Promise<string>;
+  /**
+   * Get the output of `stdout` as a string.
+   *
+   * NOTE: This may throw string conversion errors if the command does
+   * not output valid Unicode.
+   *
+   * @param opts - Optional parameters.
+   * @param opts.signal - An AbortSignal to cancel output streaming.
+   * @returns The standard output of the command.
+   */
+  stdout(opts?: {
+    signal?: AbortSignal;
+  }): Promise<string>;
+  /**
+   * Get the output of `stderr` as a string.
+   *
+   * NOTE: This may throw string conversion errors if the command does
+   * not output valid Unicode.
+   *
+   * @param opts - Optional parameters.
+   * @param opts.signal - An AbortSignal to cancel output streaming.
+   * @returns The standard error output of the command.
+   */
+  stderr(opts?: {
+    signal?: AbortSignal;
+  }): Promise<string>;
+  /**
+   * Kill a running command in a sandbox.
+   *
+   * @param signal - The signal to send the running process. Defaults to SIGTERM.
+   * @param opts - Optional parameters.
+   * @param opts.abortSignal - An AbortSignal to cancel the kill operation.
+   * @returns Promise<void>.
+   */
+  kill(signal?: Signal, opts?: {
+    abortSignal?: AbortSignal;
+  }): Promise<void>;
+}
+/**
+ * A command that has finished executing.
+ *
+ * The exit code is immediately available and populated upon creation.
+ * Unlike {@link Command}, you don't need to call wait() - the command
+ * has already completed execution.
+ *
+ * @hideconstructor
+ */
+declare class CommandFinished extends Command {
+  /**
+   * The exit code of the command. This is always populated for
+   * CommandFinished instances.
+   */
+  exitCode: number;
+  /**
+   * @param params - Object containing client, sandbox ID, command data, and exit code.
+   * @param params.client - Optional API client. If not provided, will be lazily created using global credentials.
+   * @param params.sessionId - The ID of the session where the command ran.
+   * @param params.cmd - The command data.
+   * @param params.exitCode - The exit code of the completed command.
+   * @param params.output - Optional cached output to restore (used during deserialization).
+   */
+  constructor(params: {
+    client?: APIClient;
+    sessionId: string;
+    cmd: CommandData;
+    exitCode: number;
+    output?: CommandOutput;
+  });
+  /**
+   * Serialize a CommandFinished instance to plain data for @workflow/serde.
+   *
+   * @param instance - The CommandFinished instance to serialize
+   * @returns A plain object containing the sandbox ID, command data, exit code, and output if fetched
+   */
+  static [WORKFLOW_SERIALIZE](instance: CommandFinished): SerializedCommandFinished;
+  /**
+   * Deserialize plain data back into a CommandFinished instance for @workflow/serde.
+   *
+   * The deserialized instance will lazily create an API client using
+   * OIDC or environment credentials when needed.
+   *
+   * @param data - The serialized command finished data
+   * @returns The reconstructed CommandFinished instance
+   */
+  static [WORKFLOW_DESERIALIZE](data: SerializedCommandFinished): CommandFinished;
+  /**
+   * The wait method is not needed for CommandFinished instances since
+   * the command has already completed and exitCode is populated.
+   *
+   * @deprecated This method is redundant for CommandFinished instances.
+   * The exitCode is already available.
+   * @returns This CommandFinished instance.
+   */
+  wait(): Promise<CommandFinished>;
+}
+//#endregion
+export { Command, CommandFinished, CommandOutput, SerializedCommand, SerializedCommandFinished };
+//# sourceMappingURL=command.d.cts.map