送信

メッセージ 1 つがターン 1 つである。同じセッションのメッセージは、同じ worker、同じ作業ツリー、同じ Claude Code の会話で順に実行される。scope は sessions:write である。SDK の例は SDK のインストールで作った werft クライアントを、HTTP API の例はサーバーのアドレス API とキー KEY のシェル変数を使う。例の GATE-SPEC {…} メッセージは、開発用サーバーの fake モデルが読むスクリプトである(開始)。

セッションを 1 つ用意する見出しのリンクをコピー

const created = await werft.sessions.create({
  profile_id: "claude-coding-local",
  repository_id: "sample-app",
  message: 'GATE-SPEC {"id":"m1","steps":[],"final":"ready"}',
});
const sessionId = created.session_id;

送信する見出しのリンクをコピー

const sent = await werft.sessions.messages.send(sessionId, {
  message:
    'GATE-SPEC {"id":"m2","steps":[{"tool":"Bash","input":{"command":"ls","description":"list files"}}],"final":"listed"}',
});
console.log(sent);

{
  turn_id: '2',
  receipt_id: '…',
  receipt_status: 'accepted'
}

レスポンスは 202 である。前のターンがまだ実行中なら、新しいターンは queued で待機し、順番が来たら実行される。

• message は UTF-8 で 32,768 バイトまでである。超えると 413 になる。
• 1 つのセッションに溜められる待機中の入力は、デフォルトで 20 個である。超えると 429 になる。
• Idempotency-Key が必要である。レスポンスを受け取れなかったときは、同じキーと同じ本文でもう一度送る。ターンは 1 回だけ作られる。SDK はキーを作って付け、再試行にも同じキーを使う。

結果を読む見出しのリンクをコピー

import { waitForTurn } from "@werft-ai/sdk";

const turn = await waitForTurn(werft, sessionId, sent.turn_id, {
  signal: AbortSignal.timeout(5 * 60_000),
});
console.log(`turn ${turn.turn_id}: ${turn.status}`);

turn 2: completed

ターンが終わったかどうかは、この status だけで判断する。5 つの値のどれかであれば終了している。completed は、エンジンがターンを正常に終えたという意味であり、依頼した作業をすべて終えたという意味ではない。モデルがツールを 1 つ呼んだだけで応答を終えても、ツールがエラーを受け取っても completed である。作業ができたかどうかは、ストリーミングの assistant・tool_result イベントを読んで判断し、不十分なら同じセッションに次のメッセージを送る。

送信できないとき見出しのリンクをコピー

SDK では、下のレスポンスが APIError として届き、isApiError(error, "SESSION_PAUSED") のように判別する。409 は SDK が再送しない。

次のステップ見出しのリンクをコピー

• ストリーミングの受信: ターンの実行中に進行状況を見る
• 添付