非同期タスク | LMSP 1.0 ドラフト

7.1 タスクの作成

クライアントは、実行したいレスポンスリクエストをタスクエンベロープで包んで POST することでタスクを作成する。Idempotency-Key ヘッダーを付けることを推奨する（9.2 節）。

POST /lmsp/v1/tasks
Authorization: Bearer <token>
Idempotency-Key: 01J8M7C4Y3N5P8R2T6V9X1Z4BH

{
  "type": "response",
  "input": {
    "model": "qwen3:14b-q4_k_m",
    "input": [
      {
        "type": "message",
        "role": "user",
        "content": [
          {
            "type": "input_text",
            "text": "Write a long report."
          }
        ]
      }
    ]
  },
  "on_restart": "fail"
}

フィールド	必須	意味
`type`	はい	`response`。1.0 で唯一のタスクタイプ。
`input`	はい	`POST /lmsp/v1/responses` とまったく同じレスポンスリクエスト。その `stream` フィールドは無視される。
`on_restart`	いいえ	`fail`（既定）、`retry`、`resume`。7.5 節を参照。

サービスは、応答する前にタスクを永続化しなければならない。その後、次を返す。

HTTP/1.1 202 Accepted

{
  "id": "task_01J8M8R5X3V7B2N4Q9T1W6Y0ZC",
  "object": "task",
  "type": "response",
  "status": "queued",
  "created_at": 1794200100,
  "updated_at": 1794200100,
  "response_id": "resp_01J8M8R5X4B9D2F6H1K3N7Q0ZW",
  "events_url": "/lmsp/v1/tasks/task_01J8M8R5X3V7B2N4Q9T1W6Y0ZC/events",
  "on_restart": "fail",
  "response": null,
  "error": null
}

タスクのフィールド	意味
`id`	タスク識別子。例: `task_...`。
`object`	常に `"task"`。
`type`	`response`。
`status`	現在の状態（7.2 節）。
`created_at`, `updated_at`	Unix エポックからの秒数で表した時刻。
`response_id`	タスクが生成するレスポンスの ID。タスクの作成時に割り当てられる。
`events_url`	イベントストリームのパス。`event_resume` 機能が `true` のときに存在する。
`on_restart`	タスクの再起動ポリシー。
`response`	`status` が `succeeded` になるとレスポンスオブジェクト、それ以外は `null`。
`error`	`status` が `failed` のときは problem オブジェクト（9.3 節）、それ以外は `null`。

GET /lmsp/v1/tasks/{task_id} はタスクオブジェクトを返す。イベントストリームを使わないクライアントは、このエンドポイントをポーリングする。未知の ID では 404 と task_not_found を返す。完了したタスクは次のようになる。

{
  "id": "task_01J8M8R5X3V7B2N4Q9T1W6Y0ZC",
  "object": "task",
  "type": "response",
  "status": "succeeded",
  "created_at": 1794200100,
  "updated_at": 1794200162,
  "response_id": "resp_01J8M8R5X4B9D2F6H1K3N7Q0ZW",
  "events_url": "/lmsp/v1/tasks/task_01J8M8R5X3V7B2N4Q9T1W6Y0ZC/events",
  "on_restart": "fail",
  "response": {
    "id": "resp_01J8M8R5X4B9D2F6H1K3N7Q0ZW",
    "object": "response",
    "created_at": 1794200100,
    "status": "completed",
    "model": "qwen3:14b-q4_k_m",
    "output": [
      {
        "id": "msg_01J8M8R6A2C5E8G1J4M7P0S3VY",
        "type": "message",
        "role": "assistant",
        "content": [
          {
            "type": "output_text",
            "text": "Local model services make on-device inference a shared, discoverable utility..."
          }
        ]
      }
    ],
    "usage": {
      "input_tokens": 12,
      "output_tokens": 1480,
      "total_tokens": 1492
    },
    "error": null,
    "incomplete_details": null
  },
  "error": null
}

7.2 状態遷移

queued --> loading --> running --> succeeded
  |           |           |
  |           |           +--> failed
  |           |           +--> cancelling --> cancelled
  |           +--------------> failed
  +--------------------------> cancelled

状態	意味	次の状態
`queued`	受理され永続化済みで、開始を待っている。	`loading`、`cancelled`、`failed`
`loading`	モデルをロード中。	`running`、`cancelling`、`failed`
`running`	モデルが生成中。	`succeeded`、`failed`、`cancelling`
`cancelling`	キャンセルが要求されたが、バックエンドはまだ停止していない。	`cancelled`
`succeeded`	終端。レスポンスは完了している。	なし
`failed`	終端。	なし
`cancelled`	終端。	なし

終端状態は succeeded、failed、cancelled である。終端状態のタスクは、再び変化してはならない。レスポンスが incomplete で終わるタスク（たとえばトークン上限による）は succeeded である。

すべての遷移はアトミックであるため、タスクがキャンセルと完了の両方になることはない。先にコミットされた遷移が有効になる。

7.3 キャンセル

POST /lmsp/v1/tasks/{task_id}/cancel

サービスは 200 OK と現在のタスクオブジェクトを返す。queued のタスクは直ちに cancelled になる。loading または running のタスクは、バックエンドが停止するまで cancelling となり、その後 cancelled になる。

キャンセルは冪等でなければならない。すでに cancelling または cancelled のタスクをキャンセルしても、現在のタスクが返され、新しいエラーは生じない。

すでに succeeded または failed のタスクをキャンセルすると、409 と task_not_cancelable で応答する。未知の ID では 404 と task_not_found を返す。

7.4 イベントストリーム

GET /lmsp/v1/tasks/{task_id}/events
Accept: text/event-stream

このエンドポイントは任意である。event_resume 機能が true のときに利用できる。

イベントは、タスクが生成するレスポンスについての、6.3 節のレスポンスイベントである。番号付けと再開は6.4 節に従う。
ストリームは、タスクの受理時に記録される response.created で始まる。結果に対応する最終イベントを 1 つ送って終わる。response.completed、response.incomplete、response.failed、response.cancelled のいずれかである。
遅れて接続したクライアントは、まず取り逃したイベントを受け取り、その後でライブのイベントを受け取る。サービスは最終イベントの後にストリームを閉じる。
イベントは保持期間の間、保存される（11.2 節）。それより古いイベントを要求すると、410 Gone と event_history_expired が返る。

7.5 再起動時の動作

on_restart は、サービスの再起動時に未完了のタスクをどう扱うかを示す。

値	動作
`fail`	既定。サービスは未完了のタスクを `failed` とし、エラーコードは `server_restarted` とする。
`retry`	サービスはタスクを最初からもう一度実行する。
`resume`	サービスはスナップショットから続行する。これが許されるのは、バックエンドが再開可能なスナップショットに明示的に対応している場合だけである。そうでない場合、作成リクエストは `400` と `unsupported_capability` で拒否される。

サービスの再起動時に cancelling だったタスクは、ポリシーにかかわらず、キャンセルを完了して cancelled になる。

retry を既定にすることは推奨しない。タスクがすでにツールを実行していたり、外部への副作用を生じていたりする可能性があるためである。retry を選ぶクライアントは、Idempotency-Key と組み合わせ、かつツール呼び出しを冪等にしなければならない。