> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ja/llms.txt

# SandboxProcessManager

**追加バージョン：** `@mastra/core@1.7.0`

Sandbox のバックグラウンドプロセスを管理する抽象基底クラスです。プロセスの起動、一覧取得、PID によるハンドル取得、終了のためのメソッドを提供します。

[`BlaxelSandbox`](https://mastra.zisheng.pro/ja/reference/workspace/blaxel-sandbox)、[`DaytonaSandbox`](https://mastra.zisheng.pro/ja/reference/workspace/daytona-sandbox)、[`E2BSandbox`](https://mastra.zisheng.pro/ja/reference/workspace/e2b-sandbox)、[`ModalSandbox`](https://mastra.zisheng.pro/ja/reference/workspace/modal-sandbox)、[`LocalSandbox`](https://mastra.zisheng.pro/ja/reference/workspace/local-sandbox) には、いずれもプロセスマネージャーが組み込まれています。カスタム Sandbox Provider を構築する場合を除き、このクラスを直接インスタンス化する必要はありません。

## 使用例

Sandbox の `processes` プロパティからプロセスマネージャーにアクセスします。

```typescript
import { LocalSandbox } from '@mastra/core/workspace'

const sandbox = new LocalSandbox({ workingDirectory: './workspace' })
await sandbox.start()

// Spawn a background process
const handle = await sandbox.processes.spawn('node server.js', {
  env: { PORT: '3000' },
  onStdout: data => console.log(data),
})

// List all tracked processes
const procs = await sandbox.processes.list()

// Get a handle by PID
const proc = await sandbox.processes.get(handle.pid)

// Kill a process
await sandbox.processes.kill(handle.pid)
```

## メソッド

### `spawn(command, options?)`

バックグラウンドプロセスを起動します。プロセスの終了を待たず、すぐに `ProcessHandle` を返します。

```typescript
const handle = await sandbox.processes.spawn('npm run dev', {
  cwd: '/app',
  env: { NODE_ENV: 'development' },
  onStdout: data => console.log(data),
})
```

**パラメーター：**

**command** (`string`): 実行するコマンド。シェルによって解釈されます。

**options** (`SpawnProcessOptions`): 起動するプロセスの任意設定。

**options.timeout** (`number`): タイムアウト（ミリ秒）。超過するとプロセスを終了します。

**options.env** (`NodeJS.ProcessEnv`): プロセスの環境変数。

**options.cwd** (`string`): プロセスの作業ディレクトリ。

**options.onStdout** (`(data: string) => void`): stdout チャンク用のコールバック。データの到着時に呼び出されます。

**options.onStderr** (`(data: string) => void`): stderr チャンク用のコールバック。データの到着時に呼び出されます。

**options.abortSignal** (`AbortSignal`): プロセスを中断するシグナル。中断時にプロセスを終了します。

**戻り値：** `Promise<ProcessHandle>`

### `list()`

追跡中のプロセスをすべて一覧表示します。PID、実行状態、終了コードを含む各プロセスの情報を返します。

```typescript
const procs = await sandbox.processes.list()
for (const proc of procs) {
  console.log(proc.pid, proc.running, proc.exitCode)
}
```

**戻り値：** `Promise<ProcessInfo[]>`

### `get(pid)`

PID を指定してプロセスのハンドルを取得します。プロセスが見つからないか、すでに破棄されている場合は `undefined` を返します。

```typescript
const handle = await sandbox.processes.get(1234)
if (handle) {
  console.log(handle.stdout)
  await handle.kill()
}
```

**戻り値：** `Promise<ProcessHandle | undefined>`

### `kill(pid)`

PID を指定してプロセスを終了します。プロセスが終了するまで待機してから返ります。終了できた場合は `true`、見つからない場合は `false` を返します。

```typescript
const killed = await sandbox.processes.kill(handle.pid)
```

**戻り値：** `Promise<boolean>`

## `ProcessInfo`

`list()` が返す、追跡中のプロセスに関する情報です。

**pid** (`number`): プロセス ID。

**command** (`string`): 実行されたコマンド。

**running** (`boolean`): プロセスがまだ実行中かどうか。

**exitCode** (`number`): プロセスが終了した場合の終了コード。

***

## `ProcessHandle`

起動したバックグラウンドプロセスのハンドルです。出力の読み取り、stdin の送信、完了待機、プロセス終了のためのメソッドを提供します。

`ProcessHandle` インスタンスを直接作成する必要はありません。`spawn()` と `get()` から返されます。

### 使用例

```typescript
const handle = await sandbox.processes.spawn('npm run dev', {
  onStdout: data => console.log(data),
})

// Read accumulated output
console.log(handle.pid)
console.log(handle.stdout)
console.log(handle.stderr)
console.log(handle.exitCode) // undefined while running

// Wait for completion
const result = await handle.wait()

// Send stdin
await handle.sendStdin('input data\n')

// Kill the process
await handle.kill()
```

### プロパティ

**pid** (`number`): プロセス ID。

**stdout** (`string`): これまでに蓄積された stdout 出力。

**stderr** (`string`): これまでに蓄積された stderr 出力。

**exitCode** (`number | undefined`): 終了コード。プロセスの実行中は undefined です。

**command** (`string | undefined`): 起動されたコマンド。プロセスマネージャーによって自動設定されます。

**reader** (`Readable`): stdout の読み取り可能ストリーム。stdio で通信する LSP や JSON-RPC などのプロトコルに利用できます。

**writer** (`Writable`): stdin への書き込み可能ストリーム。stdio で通信する LSP や JSON-RPC などのプロトコルに利用できます。

### メソッド

#### `wait(options?)`

プロセスが終了するまで待機し、結果を返します。待機中の出力をストリーミングするには、任意で `onStdout`／`onStderr` コールバックを渡します。`wait()` が解決するとコールバックは自動的に削除されます。

```typescript
// Simple wait
const result = await handle.wait()
console.log(result.success, result.exitCode, result.stdout)

// Wait with streaming
const result = await handle.wait({
  onStdout: data => process.stdout.write(data),
  onStderr: data => process.stderr.write(data),
})
```

**パラメーター：**

**options** (`WaitOptions`): 待機時の任意設定。

**options.onStdout** (`(data: string) => void`): 待機中の stdout チャンク用コールバック。

**options.onStderr** (`(data: string) => void`): 待機中の stderr チャンク用コールバック。

**戻り値：** `Promise<CommandResult>`

`CommandResult` オブジェクトには次の値が含まれます。

**success** (`boolean`): 終了コードが0の場合は true。

**exitCode** (`number`): 数値の終了コード。

**stdout** (`string`): stdout の完全な出力。

**stderr** (`string`): stderr の完全な出力。

**executionTimeMs** (`number`): 実行時間（ミリ秒）。

**timedOut** (`boolean`): タイムアウトによってプロセスが終了された場合は true。

**killed** (`boolean`): シグナルによってプロセスが終了された場合は true。

#### `kill()`

プロセスを終了します。終了できた場合は `true`、すでに終了していた場合は `false` を返します。

```typescript
const killed = await handle.kill()
```

**戻り値：** `Promise<boolean>`

#### `sendStdin(data)`

プロセスの stdin にデータを送信します。プロセスがすでに終了しているか stdin を利用できない場合はスローします。

```typescript
await handle.sendStdin('console.log("hello")\n')
```

**戻り値：** `Promise<void>`

## ストリーム相互運用

`ProcessHandle` は、LSP や JSON-RPC など Node.js ストリームベースのプロトコルと統合するための `reader` と `writer` プロパティを公開します。

```typescript
import {
  createMessageConnection,
  StreamMessageReader,
  StreamMessageWriter,
} from 'vscode-jsonrpc/node'

const handle = await sandbox.processes.spawn('typescript-language-server --stdio')

const connection = createMessageConnection(
  new StreamMessageReader(handle.reader),
  new StreamMessageWriter(handle.writer),
)
connection.listen()
```

## カスタムプロセスマネージャーの構築

カスタム Sandbox Provider のプロセスマネージャーを構築するには、`SandboxProcessManager` を拡張して `spawn()` と `list()` を実装します。基底クラスが各メソッドを `ensureRunning()` で自動的にラップするため、プロセス操作の前に Sandbox が起動します。

```typescript
import { SandboxProcessManager, ProcessHandle } from '@mastra/core/workspace'
import type { ProcessInfo, SpawnProcessOptions } from '@mastra/core/workspace'

class MyProcessManager extends SandboxProcessManager<MySandbox> {
  async spawn(command: string, options: SpawnProcessOptions = {}): Promise<ProcessHandle> {
    // Your spawn implementation
    const handle = new MyProcessHandle(/* ... */)
    this._tracked.set(handle.pid, handle)
    return handle
  }

  async list(): Promise<ProcessInfo[]> {
    return Array.from(this._tracked.values()).map(handle => ({
      pid: handle.pid,
      running: handle.exitCode === undefined,
      exitCode: handle.exitCode,
    }))
  }
}
```

`MastraSandbox` の `processes` オプションを介して、プロセスマネージャーを Sandbox に渡します。

```typescript
class MySandbox extends MastraSandbox {
  constructor() {
    super({
      name: 'MySandbox',
      processes: new MyProcessManager(),
    })
  }
}
```

プロセスマネージャーを指定すると、`MastraSandbox` は `spawn()` と `wait()` を使用するデフォルトの `executeCommand` 実装を自動作成するため、両方を実装する必要はありません。

## 関連項目

- [Sandbox](https://mastra.zisheng.pro/ja/docs/workspace/sandbox)
- [WorkspaceSandbox インターフェース](https://mastra.zisheng.pro/ja/reference/workspace/sandbox)
- [LocalSandbox リファレンス](https://mastra.zisheng.pro/ja/reference/workspace/local-sandbox)
- [E2BSandbox リファレンス](https://mastra.zisheng.pro/ja/reference/workspace/e2b-sandbox)
- [DaytonaSandbox リファレンス](https://mastra.zisheng.pro/ja/reference/workspace/daytona-sandbox)