add ts sdk

Author: zhongwen666

docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.11.x/User Guides/commit.md

@@ -178,3 +178,35 @@ async def commit_and_wait(sandbox):
 ```
 
 当调用方不希望等待，或需要自行控制轮询逻辑时，可直接使用 `commit_async()`。该方法返回任务的初始状态，后续状态通过 `get_commit_status()` 查询。
+
+## TypeScript SDK
+
+使用 `commit()` 发起任务并等待最终状态。该方法内部调用 `commitAsync()`，并轮询 `getCommitStatus()`。`timeout` 和 `interval` 参数的单位为秒，默认值分别为 `180` 和 `2`。
+
+```typescript
+import { CommitPhase } from 'rl-rock';
+
+async function commitAndWait(sandbox) {
+  const status = await sandbox.commit(
+    'registry.example.com/team/app:v1',
+    'registry-user',
+    'registry-password',
+    180,
+    2
+  );
+  if (!status) {
+    throw new Error('sandbox_id 未设置');
+  }
+
+  if (status.phase === CommitPhase.FAILED) {
+    throw new Error(
+      `commit 失败: code=${status.errorCode}, ` +
+      `stage=${status.failedStage}, message=${status.errorMessage}`
+    );
+  }
+
+  console.log(`镜像推送成功: ${status.imageTag}`);
+}
+```
+
+超时只会停止 SDK 端的等待，不会取消 worker 上已经运行的任务。调用方需要自行控制轮询时可使用 `commitAsync()`，之后通过 `getCommitStatus()` 查询任务状态。

docs/versioned_docs/version-1.11.x/User Guides/commit.md

@@ -178,3 +178,35 @@ async def commit_and_wait(sandbox):
 ```
 
 Use `commit_async()` directly when the caller must not wait or needs custom polling behavior. Its return value is the initial task status; call `get_commit_status()` to query subsequent status.
+
+## TypeScript SDK
+
+Use `commit()` to start the task and wait for its final status. It calls `commitAsync()` internally and polls `getCommitStatus()`. The `timeout` and `interval` arguments use seconds and default to `180` and `2`.
+
+```typescript
+import { CommitPhase } from 'rl-rock';
+
+async function commitAndWait(sandbox) {
+  const status = await sandbox.commit(
+    'registry.example.com/team/app:v1',
+    'registry-user',
+    'registry-password',
+    180,
+    2
+  );
+  if (!status) {
+    throw new Error('sandbox_id is not set');
+  }
+
+  if (status.phase === CommitPhase.FAILED) {
+    throw new Error(
+      `commit failed: code=${status.errorCode}, ` +
+      `stage=${status.failedStage}, message=${status.errorMessage}`
+    );
+  }
+
+  console.log(`image pushed: ${status.imageTag}`);
+}
+```
+
+A timeout only stops the SDK from waiting; it does not cancel the worker task. Use `commitAsync()` when the caller needs to control polling, and call `getCommitStatus()` to query the task later.

rock/ts-sdk/src/sandbox/client.test.ts

@@ -1172,4 +1172,85 @@ describe('uploadByPath() with uploadMode', () => {
 
     expect(result).toBeDefined();
   });
-});
+});
+
+describe('Sandbox commit()', () => {
+  afterEach(() => {
+    jest.useRealTimers();
+  });
+
+  test('starts an asynchronous commit and polls until completion', async () => {
+    jest.useFakeTimers();
+    const sandbox = new Sandbox({ image: 'test:latest' });
+    const running = {
+      sandboxId: 'sandbox-1',
+      imageTag: 'registry.example/app:v1',
+      phase: 'RUNNING' as const,
+      startedAt: '2026-01-01T00:00:00Z',
+      completedAt: null,
+      exitCode: null,
+      failedStage: null,
+      errorCode: null,
+      errorMessage: null,
+    };
+    const succeeded = {
+      ...running,
+      phase: 'SUCCEEDED' as const,
+      completedAt: '2026-01-01T00:00:05Z',
+      exitCode: 0,
+    };
+    const commitAsync = jest.spyOn(sandbox, 'commitAsync').mockResolvedValue(running);
+    const getCommitStatus = jest.spyOn(sandbox, 'getCommitStatus').mockResolvedValue(succeeded);
+
+    const resultPromise = sandbox.commit(
+      'registry.example/app:v1',
+      'registry-user',
+      'registry-password',
+      10,
+      0.25
+    );
+    await Promise.resolve();
+    await jest.advanceTimersByTimeAsync(250);
+
+    await expect(resultPromise).resolves.toEqual(succeeded);
+    expect(commitAsync).toHaveBeenCalledWith(
+      'registry.example/app:v1',
+      'registry-user',
+      'registry-password'
+    );
+    expect(getCommitStatus).toHaveBeenCalledTimes(1);
+  });
+
+  test('uses the default interval and rejects when the default timeout expires', async () => {
+    jest.useFakeTimers();
+    const sandbox = new Sandbox({ image: 'test:latest' });
+    const running = {
+      sandboxId: 'sandbox-1',
+      imageTag: 'registry.example/app:v1',
+      phase: 'RUNNING' as const,
+      startedAt: '2026-01-01T00:00:00Z',
+      completedAt: null,
+      exitCode: null,
+      failedStage: null,
+      errorCode: null,
+      errorMessage: null,
+    };
+    jest.spyOn(sandbox, 'commitAsync').mockResolvedValue(running);
+    const getCommitStatus = jest.spyOn(sandbox, 'getCommitStatus').mockResolvedValue(running);
+
+    const resultPromise = sandbox.commit(
+      'registry.example/app:v1',
+      'registry-user',
+      'registry-password'
+    );
+    const rejection = expect(resultPromise).rejects.toThrow('Commit timed out after 180 seconds');
+    await Promise.resolve();
+    await jest.advanceTimersByTimeAsync(1999);
+    expect(getCommitStatus).not.toHaveBeenCalled();
+    await jest.advanceTimersByTimeAsync(1);
+    expect(getCommitStatus).toHaveBeenCalledTimes(1);
+    await jest.advanceTimersByTimeAsync(178000);
+
+    await rejection;
+  });
+});

rock/ts-sdk/src/sandbox/client.ts

@@ -120,7 +120,13 @@ export abstract class AbstractSandbox {
   abstract delete(): Promise<void>;
   abstract restart(): Promise<void>;
   abstract archive(): Promise<void>;
-  abstract commit(imageTag: string, username: string, password: string): Promise<CommandResponse | undefined>;
+  abstract commit(
+    imageTag: string,
+    username: string,
+    password: string,
+    timeout?: number,
+    interval?: number
+  ): Promise<CommitStatusResponse | undefined>;
   abstract commitAsync(imageTag: string, username: string, password: string): Promise<CommitStatusResponse | undefined>;
   abstract getCommitStatus(): Promise<CommitStatusResponse | undefined>;
   abstract attach(sandboxId: string): Promise<void>;
@@ -511,32 +517,56 @@ export class Sandbox extends AbstractSandbox {
   }
 
   /**
-   * Commit the sandbox container as a new Docker image.
+   * Commit the sandbox container as a new Docker image and wait for completion.
    *
    * @param imageTag - Tag for the new image (e.g., "my-image:v1")
    * @param username - Registry username for authentication
    * @param password - Registry password for authentication
-   * @returns CommandResponse with stdout, stderr, and exit_code from the commit operation,
-   *          or undefined if sandbox_id is not set.
+   * @param timeout - Maximum total wait time in seconds
+   * @param interval - Delay between status queries in seconds
+   * @returns Final task status, or undefined if sandbox_id is not set.
    */
-  async commit(imageTag: string, username: string, password: string): Promise<CommandResponse | undefined> {
-    if (!this.sandboxId) {
-      return;
-    }
-    const url = `${this.url}/commit`;
-    const headers = this.buildHeaders();
-    const data = {
-      sandboxId: this.sandboxId,
-      imageTag,
-      username,
-      password,
+  async commit(
+    imageTag: string,
+    username: string,
+    password: string,
+    timeout: number = 180,
+    interval: number = 2
+  ): Promise<CommitStatusResponse | undefined> {
+    const deadline = Date.now() + timeout * 1000;
+    const timeoutError = (): Error => new Error(`Commit timed out after ${timeout} seconds`);
+    const waitWithTimeout = async <T>(operation: Promise<T>): Promise<T> => {
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) {
+        throw timeoutError();
+      }
+
+      let timeoutId: ReturnType<typeof setTimeout> | undefined;
+      try {
+        return await Promise.race([
+          operation,
+          new Promise<never>((_, reject) => {
+            timeoutId = setTimeout(() => reject(timeoutError()), remaining);
+          }),
+        ]);
+      } finally {
+        clearTimeout(timeoutId);
+      }
     };
-    const response = await HttpUtils.post<CommandResponse & { code?: number }>(url, headers, data);
-    logger.debug(`Commit sandbox response: ${JSON.stringify(response)}`);
-    if (response.status !== 'Success') {
-      throw new Error(`Failed to execute command: ${JSON.stringify(response)}`);
+
+    let status = await waitWithTimeout(this.commitAsync(imageTag, username, password));
+    while (status?.phase === 'RUNNING') {
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) {
+        throw timeoutError();
+      }
+      await sleep(Math.min(interval * 1000, remaining));
+      if (Date.now() >= deadline) {
+        throw timeoutError();
+      }
+      status = await waitWithTimeout(this.getCommitStatus());
     }
-    return CommandResponseSchema.parse(response.result);
+    return status;
   }
 
   /**