Files
claw-code-parity/worker-protocol/openapi.yaml
T
Wylabb 9e9d440770
Build Claw Telegram / build (push) Successful in 5m39s
Build Claw Telegram / cleanup (push) Successful in 8s
Decouple gateway protocol from Rust runtime types
Move all worker-facing record types (TaskListRecord, RuntimeTaskRecord,
TeamRecord, MailboxSummary, FeedItemRecord, LibraryAppRecord, etc.)
into protocol-owned mirrors in records.rs. The gateway and worker_client
now use these protocol types instead of importing from the runtime crate.

Add worker-protocol/ with OpenAPI spec and JSON schemas as the
language-neutral contract authority for the gateway-worker boundary.
This is the migration surface for the TS worker replacement.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-07 20:12:16 +02:00

954 lines
24 KiB
YAML

openapi: 3.1.0
info:
title: Claw Worker Protocol
version: 0.1.0
description: >
Language-neutral HTTP/SSE contract between the Rust gateway and the worker
process. This is the migration boundary for the Rust gateway plus
TypeScript worker architecture.
servers:
- url: http://worker
paths:
/healthz:
get:
operationId: healthz
responses:
"200":
description: Worker is healthy
/v1/status:
get:
operationId: getStatus
responses:
"200":
description: Session status
content:
application/json:
schema:
$ref: "#/components/schemas/WorkerStatusResponse"
/v1/session/reset:
post:
operationId: resetSession
responses:
"204":
description: Session reset
/v1/turns:
post:
operationId: submitTurn
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/WorkerTurnRequest"
responses:
"200":
description: Turn accepted
content:
application/json:
schema:
$ref: "#/components/schemas/WorkerTurnAccepted"
/v1/turns/{turn_id}/events:
get:
operationId: streamTurnEvents
parameters:
- $ref: "#/components/parameters/TurnId"
responses:
"200":
description: SSE stream of worker turn events
content:
text/event-stream:
schema:
type: string
/v1/turns/{turn_id}/approval:
post:
operationId: resolveTurnApproval
parameters:
- $ref: "#/components/parameters/TurnId"
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/TurnApprovalRequest"
responses:
"204":
description: Approval applied
/v1/turns/{turn_id}/cancel:
post:
operationId: cancelTurn
parameters:
- $ref: "#/components/parameters/TurnId"
responses:
"204":
description: Turn cancelled
/v1/turns/{turn_id}/files/{file_id}:
get:
operationId: fetchGeneratedFile
parameters:
- $ref: "#/components/parameters/TurnId"
- $ref: "#/components/parameters/FileId"
responses:
"200":
description: Generated file bytes
content:
application/octet-stream:
schema:
type: string
format: binary
/v1/tasks:
get:
operationId: listTasks
responses:
"200":
description: Task list snapshot
content:
application/json:
schema:
$ref: "#/components/schemas/WorkerTaskListResponse"
/v1/tasks/{task_id}:
get:
operationId: getTask
parameters:
- $ref: "#/components/parameters/TaskId"
responses:
"200":
description: Task snapshot
content:
application/json:
schema:
$ref: "#/components/schemas/WorkerTaskSnapshotResponse"
/v1/tasks/{task_id}/stop:
post:
operationId: stopTask
parameters:
- $ref: "#/components/parameters/TaskId"
responses:
"204":
description: Task stop requested
/v1/team:
get:
operationId: getTeam
responses:
"200":
description: Team snapshot
content:
application/json:
schema:
$ref: "#/components/schemas/WorkerTeamSnapshotResponse"
/v1/agents:
get:
operationId: listAgents
responses:
"200":
description: Agent runtime list
content:
application/json:
schema:
$ref: "#/components/schemas/WorkerAgentListResponse"
/v1/agents/{agent_id}:
get:
operationId: getAgent
parameters:
- $ref: "#/components/parameters/AgentId"
responses:
"200":
description: Agent runtime snapshot
content:
application/json:
schema:
$ref: "#/components/schemas/RuntimeTaskRecord"
/v1/background-approvals:
get:
operationId: listBackgroundApprovals
responses:
"200":
description: Background approvals
content:
application/json:
schema:
$ref: "#/components/schemas/WorkerBackgroundApprovalListResponse"
/v1/background-approvals/{approval_id}:
post:
operationId: resolveBackgroundApproval
parameters:
- $ref: "#/components/parameters/ApprovalId"
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/TurnApprovalRequest"
responses:
"204":
description: Background approval applied
/v1/background-approvals/{approval_id}/notified:
post:
operationId: markBackgroundApprovalNotified
parameters:
- $ref: "#/components/parameters/ApprovalId"
responses:
"204":
description: Background approval notification acknowledged
/v1/mailbox:
get:
operationId: getMailbox
responses:
"200":
description: Mailbox summary
content:
application/json:
schema:
$ref: "#/components/schemas/WorkerMailboxSummaryResponse"
/v1/mailbox/pending/{recipient}:
get:
operationId: getPendingMailboxMessages
parameters:
- $ref: "#/components/parameters/Recipient"
responses:
"200":
description: Pending mailbox messages
content:
application/json:
schema:
$ref: "#/components/schemas/WorkerMailboxPendingResponse"
/v1/feed:
get:
operationId: listFeed
parameters:
- in: query
name: turn_id
required: false
schema:
type: string
responses:
"200":
description: Feed items
content:
application/json:
schema:
$ref: "#/components/schemas/WorkerFeedListResponse"
/v1/feed/{feed_item_id}:
get:
operationId: getFeedItem
parameters:
- $ref: "#/components/parameters/FeedItemId"
responses:
"200":
description: Feed item snapshot
content:
application/json:
schema:
$ref: "#/components/schemas/WorkerFeedItemResponse"
/v1/feed/{feed_item_id}/file:
get:
operationId: fetchFeedFile
parameters:
- $ref: "#/components/parameters/FeedItemId"
responses:
"200":
description: Feed payload bytes
content:
application/octet-stream:
schema:
type: string
format: binary
/v1/feed/{feed_item_id}/make-app:
post:
operationId: packageFeedItem
parameters:
- $ref: "#/components/parameters/FeedItemId"
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/AppPackageRequest"
responses:
"200":
description: App create/update result
content:
application/json:
schema:
$ref: "#/components/schemas/WorkerAppPackageResponse"
/v1/apps:
get:
operationId: listApps
responses:
"200":
description: Library apps
content:
application/json:
schema:
$ref: "#/components/schemas/WorkerAppListResponse"
/v1/apps/{app_id}:
get:
operationId: getApp
parameters:
- $ref: "#/components/parameters/AppId"
responses:
"200":
description: App snapshot
content:
application/json:
schema:
$ref: "#/components/schemas/WorkerAppSnapshotResponse"
/v1/apps/{app_id}/version:
get:
operationId: getAppVersion
parameters:
- $ref: "#/components/parameters/AppId"
responses:
"200":
description: App current version
content:
application/json:
schema:
$ref: "#/components/schemas/WorkerAppVersionResponse"
/v1/apps/{app_id}/history:
get:
operationId: getAppHistory
parameters:
- $ref: "#/components/parameters/AppId"
responses:
"200":
description: App publish history
content:
application/json:
schema:
$ref: "#/components/schemas/WorkerAppHistoryResponse"
/v1/apps/{app_id}/launch:
post:
operationId: launchApp
parameters:
- $ref: "#/components/parameters/AppId"
responses:
"200":
description: App launch side effect
content:
application/json:
schema:
$ref: "#/components/schemas/WorkerAppSnapshotResponse"
/v1/apps/{app_id}/open-workspace:
post:
operationId: openAppWorkspace
parameters:
- $ref: "#/components/parameters/AppId"
responses:
"200":
description: App workspace snapshot
content:
application/json:
schema:
$ref: "#/components/schemas/WorkerAppWorkspaceResponse"
/v1/apps/{app_id}/publish:
post:
operationId: publishAppWorkspace
parameters:
- $ref: "#/components/parameters/AppId"
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/AppPublishRequest"
responses:
"200":
description: App publish result
content:
application/json:
schema:
$ref: "#/components/schemas/WorkerAppPublishResponse"
/v1/apps/{app_id}/archive:
post:
operationId: archiveApp
parameters:
- $ref: "#/components/parameters/AppId"
responses:
"204":
description: App archived
/v1/apps/{app_id}/worktree-status:
get:
operationId: getAppWorktreeStatus
parameters:
- $ref: "#/components/parameters/AppId"
responses:
"200":
description: App worktree snapshot
content:
application/json:
schema:
$ref: "#/components/schemas/WorkerAppWorkspaceResponse"
/v1/apps/{app_id}/files/{path}:
get:
operationId: fetchAppFile
parameters:
- $ref: "#/components/parameters/AppId"
- in: path
name: path
required: true
schema:
type: string
responses:
"200":
description: App bundle file bytes
content:
application/octet-stream:
schema:
type: string
format: binary
components:
parameters:
TurnId:
in: path
name: turn_id
required: true
schema:
type: string
TaskId:
in: path
name: task_id
required: true
schema:
type: string
AgentId:
in: path
name: agent_id
required: true
schema:
type: string
ApprovalId:
in: path
name: approval_id
required: true
schema:
type: string
Recipient:
in: path
name: recipient
required: true
schema:
type: string
FeedItemId:
in: path
name: feed_item_id
required: true
schema:
type: string
AppId:
in: path
name: app_id
required: true
schema:
type: string
FileId:
in: path
name: file_id
required: true
schema:
type: string
schemas:
TurnSource:
type: object
required:
- channel
- sender_id
properties:
channel:
type: string
sender_id:
type: string
chat_id:
type: string
display_name:
type: string
InboundAttachment:
type: object
required:
- file_name
- kind
- data_base64
properties:
file_name:
type: string
kind:
type: string
enum: [photo, document]
media_type:
type: string
data_base64:
type: string
WorkerTurnRequest:
type: object
required:
- prompt
- source
properties:
prompt:
type: string
source:
$ref: "#/components/schemas/TurnSource"
attachments:
type: array
items:
$ref: "#/components/schemas/InboundAttachment"
WorkerTurnAccepted:
type: object
required: [turn_id]
properties:
turn_id:
type: string
ApprovalRequestPayload:
type: object
required:
- approval_id
- tool_name
- input
- current_mode
- required_mode
properties:
approval_id:
type: string
tool_name:
type: string
input:
type: string
current_mode:
type: string
required_mode:
type: string
reason:
type: string
WorkerApprovalDecision:
oneOf:
- type: object
required: [decision]
properties:
decision:
type: string
enum:
- approve_once
- approve_tool_for_session
- approve_all_for_session
- cancel_turn
- type: object
required: [decision, reason]
properties:
decision:
type: string
enum: [deny]
reason:
type: string
TurnApprovalRequest:
type: object
required:
- approval_id
- decision
properties:
approval_id:
type: string
decision:
$ref: "#/components/schemas/WorkerApprovalDecision"
GeneratedFileDescriptor:
type: object
required:
- file_id
- file_name
- size_bytes
- is_image
properties:
file_id:
type: string
file_name:
type: string
media_type:
type: string
size_bytes:
type: integer
minimum: 0
is_image:
type: boolean
TaskListRecord:
type: object
additionalProperties: true
RuntimeTaskRecord:
type: object
additionalProperties: true
TeamRecord:
type: object
additionalProperties: true
MailboxMessage:
type: object
additionalProperties: true
MailboxSummary:
type: object
additionalProperties: true
BackgroundApprovalRecord:
type: object
additionalProperties: true
FeedItemRecord:
type: object
additionalProperties: true
LibraryAppRecord:
type: object
additionalProperties: true
LibraryAppVersionRecord:
type: object
additionalProperties: true
AppPackageRequest:
type: object
required: [feed_item_id]
properties:
feed_item_id:
type: string
requested_app_id:
type: string
title:
type: string
description:
type: string
AppPublishRequest:
type: object
required: [message]
properties:
message:
type: string
AppPackageResult:
type: object
required: [app, created]
properties:
app:
$ref: "#/components/schemas/LibraryAppRecord"
created:
type: boolean
AppWorkspaceRecord:
type: object
additionalProperties: true
AppPublishResult:
type: object
required: [app, workspace]
properties:
app:
$ref: "#/components/schemas/LibraryAppRecord"
workspace:
$ref: "#/components/schemas/AppWorkspaceRecord"
AppHistoryResponse:
type: object
additionalProperties: true
WorkerStatusResponse:
type: object
required:
- profile_id
- message_count
- model
- permission_mode
- default_cwd
- busy
- task_list_id
properties:
profile_id:
type: string
message_count:
type: integer
minimum: 0
model:
type: string
permission_mode:
type: string
default_cwd:
type: string
busy:
type: boolean
task_list_id:
type: string
active_team:
type: string
WorkerTaskListResponse:
type: object
required: [task_list_id, tasks]
properties:
task_list_id:
type: string
tasks:
type: array
items:
$ref: "#/components/schemas/TaskListRecord"
WorkerTaskSnapshotResponse:
type: object
properties:
task:
$ref: "#/components/schemas/TaskListRecord"
runtime_task:
$ref: "#/components/schemas/RuntimeTaskRecord"
WorkerTeamSnapshotResponse:
type: object
required: [task_list_id]
properties:
team:
$ref: "#/components/schemas/TeamRecord"
task_list_id:
type: string
WorkerAgentListResponse:
type: object
required: [agents]
properties:
agents:
type: array
items:
$ref: "#/components/schemas/RuntimeTaskRecord"
WorkerMailboxSummaryResponse:
type: object
required: [mailbox]
properties:
mailbox:
$ref: "#/components/schemas/MailboxSummary"
WorkerMailboxPendingResponse:
type: object
required: [messages]
properties:
messages:
type: array
items:
$ref: "#/components/schemas/MailboxMessage"
WorkerBackgroundApprovalListResponse:
type: object
required: [approvals]
properties:
approvals:
type: array
items:
$ref: "#/components/schemas/BackgroundApprovalRecord"
WorkerFeedListResponse:
type: object
required: [items]
properties:
items:
type: array
items:
$ref: "#/components/schemas/FeedItemRecord"
state_root:
type: string
warnings:
type: array
items:
type: string
WorkerFeedItemResponse:
type: object
properties:
item:
$ref: "#/components/schemas/FeedItemRecord"
state_root:
type: string
WorkerAppListResponse:
type: object
required: [apps]
properties:
apps:
type: array
items:
$ref: "#/components/schemas/LibraryAppRecord"
state_root:
type: string
warnings:
type: array
items:
type: string
WorkerAppSnapshotResponse:
type: object
properties:
app:
$ref: "#/components/schemas/LibraryAppRecord"
state_root:
type: string
WorkerAppVersionResponse:
type: object
properties:
version:
$ref: "#/components/schemas/LibraryAppVersionRecord"
WorkerAppPackageResponse:
type: object
properties:
result:
$ref: "#/components/schemas/AppPackageResult"
WorkerAppWorkspaceResponse:
type: object
properties:
workspace:
$ref: "#/components/schemas/AppWorkspaceRecord"
WorkerAppPublishResponse:
type: object
properties:
result:
$ref: "#/components/schemas/AppPublishResult"
WorkerAppHistoryResponse:
type: object
properties:
history:
$ref: "#/components/schemas/AppHistoryResponse"
WorkerTeamCreatedEvent:
type: object
required:
- team
- task_list_id
- team_file_path
properties:
team:
$ref: "#/components/schemas/TeamRecord"
task_list_id:
type: string
team_file_path:
type: string
WorkerMailboxMessageEvent:
type: object
required:
- team_name
- sender
- count
properties:
team_name:
type: string
sender:
type: string
count:
type: integer
minimum: 0
recipients:
type: array
items:
type: string
summary:
type: string
WorkerTurnEvent:
oneOf:
- type: object
required: [type, delta]
properties:
type:
const: assistant_text_delta
delta:
type: string
- type: object
required: [type, id, name, input]
properties:
type:
const: tool_use
id:
type: string
name:
type: string
input:
type: string
- type: object
required: [type, tool_use_id, tool_name, output, is_error]
properties:
type:
const: tool_result
tool_use_id:
type: string
tool_name:
type: string
output:
type: string
is_error:
type: boolean
- type: object
required: [type, request]
properties:
type:
const: approval_requested
request:
$ref: "#/components/schemas/ApprovalRequestPayload"
- type: object
required: [type, removed_message_count]
properties:
type:
const: auto_compaction
removed_message_count:
type: integer
minimum: 0
- type: object
required: [type, task_list_id, task]
properties:
type:
const: task_created
task_list_id:
type: string
task:
$ref: "#/components/schemas/TaskListRecord"
- type: object
required: [type, task_list_id, task]
properties:
type:
const: task_updated
task_list_id:
type: string
task:
$ref: "#/components/schemas/TaskListRecord"
- type: object
required: [type, task]
properties:
type:
const: task_stopped
task:
$ref: "#/components/schemas/RuntimeTaskRecord"
- type: object
required: [type, agent]
properties:
type:
const: agent_spawned
agent:
$ref: "#/components/schemas/RuntimeTaskRecord"
- type: object
required: [type, team]
properties:
type:
const: team_created
team:
$ref: "#/components/schemas/WorkerTeamCreatedEvent"
- type: object
required: [type, team_name]
properties:
type:
const: team_deleted
team_name:
type: string
- type: object
required: [type, message]
properties:
type:
const: mailbox_message
message:
$ref: "#/components/schemas/WorkerMailboxMessageEvent"
- type: object
required:
- type
- final_text
- iterations
- input_tokens
- output_tokens
- generated_files
properties:
type:
const: completed
final_text:
type: string
iterations:
type: integer
minimum: 0
input_tokens:
type: integer
minimum: 0
output_tokens:
type: integer
minimum: 0
generated_files:
type: array
items:
$ref: "#/components/schemas/GeneratedFileDescriptor"
- type: object
required: [type, message]
properties:
type:
const: failed
message:
type: string