SandboxProcessManager
追加バージョン： @mastra/core@1.7.0
Sandbox のバックグラウンドプロセスを管理する抽象基底クラスです。プロセスの起動、一覧取得、PID によるハンドル取得、終了のためのメソッドを提供します。
BlaxelSandbox、DaytonaSandbox、E2BSandbox、ModalSandbox、LocalSandbox には、いずれもプロセスマネージャーが組み込まれています。カスタム Sandbox Provider を構築する場合を除き、このクラスを直接インスタンス化する必要はありません。
使用例使用例への直接リンク
Sandbox の processes プロパティからプロセスマネージャーにアクセスします。
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?)spawncommand-optionsへの直接リンク
バックグラウンドプロセスを起動します。プロセスの終了を待たず、すぐに ProcessHandle を返します。
const handle = await sandbox.processes.spawn('npm run dev', {
cwd: '/app',
env: { NODE_ENV: 'development' },
onStdout: data => console.log(data),
})
パラメーター：
command:
options?:
timeout?:
env?:
cwd?:
onStdout?:
onStderr?:
abortSignal?:
戻り値： Promise<ProcessHandle>
list()listへの直接リンク
追跡中のプロセスをすべて一覧表示します。PID、実行状態、終了コードを含む各プロセスの情報を返します。
const procs = await sandbox.processes.list()
for (const proc of procs) {
console.log(proc.pid, proc.running, proc.exitCode)
}
戻り値： Promise<ProcessInfo[]>
get(pid)getpidへの直接リンク
PID を指定してプロセスのハンドルを取得します。プロセスが見つからないか、すでに破棄されている場合は undefined を返します。
const handle = await sandbox.processes.get(1234)
if (handle) {
console.log(handle.stdout)
await handle.kill()
}
戻り値： Promise<ProcessHandle | undefined>
kill(pid)killpidへの直接リンク
PID を指定してプロセスを終了します。プロセスが終了するまで待機してから返ります。終了できた場合は true、見つからない場合は false を返します。
const killed = await sandbox.processes.kill(handle.pid)
戻り値： Promise<boolean>
ProcessInfoprocessinfoへの直接リンク
list() が返す、追跡中のプロセスに関する情報です。
pid:
command?:
running:
exitCode?:
ProcessHandleprocesshandleへの直接リンク
起動したバックグラウンドプロセスのハンドルです。出力の読み取り、stdin の送信、完了待機、プロセス終了のためのメソッドを提供します。
ProcessHandle インスタンスを直接作成する必要はありません。spawn() と get() から返されます。
使用例使用例への直接リンク
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:
stdout:
stderr:
exitCode:
command:
reader:
writer:
メソッドメソッドへの直接リンク
wait(options?)waitoptionsへの直接リンク
プロセスが終了するまで待機し、結果を返します。待機中の出力をストリーミングするには、任意で onStdout／onStderr コールバックを渡します。wait() が解決するとコールバックは自動的に削除されます。
// 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?:
onStdout?:
onStderr?:
戻り値： Promise<CommandResult>
CommandResult オブジェクトには次の値が含まれます。
success:
exitCode:
stdout:
stderr:
executionTimeMs:
timedOut?:
killed?:
kill()killへの直接リンク
プロセスを終了します。終了できた場合は true、すでに終了していた場合は false を返します。
const killed = await handle.kill()
戻り値： Promise<boolean>
sendStdin(data)sendstdindataへの直接リンク
プロセスの stdin にデータを送信します。プロセスがすでに終了しているか stdin を利用できない場合はスローします。
await handle.sendStdin('console.log("hello")\n')
戻り値： Promise<void>
ストリーム相互運用ストリーム相互運用への直接リンク
ProcessHandle は、LSP や JSON-RPC など Node.js ストリームベースのプロトコルと統合するための reader と writer プロパティを公開します。
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 が起動します。
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 に渡します。
class MySandbox extends MastraSandbox {
constructor() {
super({
name: 'MySandbox',
processes: new MyProcessManager(),
})
}
}
プロセスマネージャーを指定すると、MastraSandbox は spawn() と wait() を使用するデフォルトの executeCommand 実装を自動作成するため、両方を実装する必要はありません。