Deferred tool result

App backend có thể defer kết quả của chính tool call hiện tại mà không tạo user message hay bắt model gọi lại tool. Core chỉ hiểu operation id và app data opaque; login, approval, payment, device pairing hay workflow nào khác đều là logic app.

JSON

{
  "_sota": {
    "deferredToolResult": {
      "operationId": "app-defined-globally-unique-id",
      "data": { "anyAppOwnedValue": true }
    }
  }
}

Core đăng ký exact run, tool call, tool name, app installation và environment sau id đó. Nó stream output-pending cho tool surface tương ứng và thêm cùng item vào pendingToolResults của exact composer panel. Model chưa nhận tool result.

YAML

coreToolGrants:
  - tool: core.app-operations.complete
    scope: write
  # Chỉ khi cần job callback token sống lâu hơn:
  - tool: core.tokens.issueJobCallback
    scope: write

App backend gửi callback tới Core origin. Bearer value là delegated capability nhận từ header x-sota-core-token của invocation gốc.

Code

POST /v1/app-operations/app-defined-globally-unique-id/complete
Authorization: Bearer <delegated-token>
Content-Type: application/json

{
  "status": "completed",
  "result": { "events": [] }
}

Dùng status: "failed" cùng error tùy ý để reject. Completion atomically trở thành result của tool call gốc và cùng agent run tiếp tục. Tool call song song có operation id riêng; model step chỉ tiếp tục khi tất cả call trong step đã settle.

JSON

{
  "status": "failed",
  "error": {
    "code": "ACTION_NOT_COMPLETED",
    "message": "The requested action was not completed"
  }
}

Grant core.app-operations.complete:write cho app backend.
Operation id phải được trim, dài 1–200 ký tự và globally unique theo tool call; retry completion giống hệt nhau là idempotent.
Registration xảy ra sau khi Core nhận deferred response, vì vậy retry app_operation_not_found với bounded backoff.
Nếu callback có thể lâu hơn delegation token 60 giây, đổi sang job callback token khi invocation gốc còn valid, lưu token an toàn và gửi job id trong x-sota-job-id.
Giữ data nhỏ và không có secret: Core không hiểu nó nhưng nó chủ động được expose tới client. App UI phải narrow shape trước khi dùng.
Primitive hiện tại gắn với live run. Stop hoặc steer run làm operation còn pending fail bằng operation_cancelled. App phải tự quản expiry và complete failed; đây không phải background job queue.