315 lines
10 KiB
YAML
315 lines
10 KiB
YAML
openapi: 3.0.3
|
|
info:
|
|
title: AIOS Task Plane API
|
|
version: 1.0.0
|
|
description: >
|
|
Durable control-plane APIs for task orchestration with fail-closed policy.
|
|
Every POST operation requires bearerAuth; read-only GET operations may be
|
|
exposed according to the surrounding runtime policy.
|
|
servers:
|
|
- url: /
|
|
paths:
|
|
/tasks:
|
|
get:
|
|
summary: List tasks
|
|
responses:
|
|
"200":
|
|
description: Task list
|
|
post:
|
|
security: [ { bearerAuth: [] } ]
|
|
summary: Create task
|
|
parameters:
|
|
- in: header
|
|
name: Idempotency-Key
|
|
required: false
|
|
schema:
|
|
type: string
|
|
minLength: 1
|
|
maxLength: 128
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/TaskPlan"
|
|
responses:
|
|
"201": { description: Created }
|
|
"400": { description: Bad request }
|
|
"401": { description: Unauthorized }
|
|
"403": { description: Forbidden }
|
|
"409": { description: Conflict }
|
|
"413": { description: Payload too large }
|
|
"423": { description: Execution or resource locked }
|
|
"503": { description: Authentication or service unavailable }
|
|
/tasks/{task_id}:
|
|
get:
|
|
summary: Get task
|
|
parameters:
|
|
- $ref: "#/components/parameters/TaskId"
|
|
responses:
|
|
"200": { description: OK }
|
|
"404": { description: Not found }
|
|
/tasks/{task_id}/claim:
|
|
post:
|
|
security: [ { bearerAuth: [] } ]
|
|
summary: Claim a task
|
|
parameters:
|
|
- $ref: "#/components/parameters/TaskId"
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/TaskClaimRequest"
|
|
responses:
|
|
"200": { description: Claimed }
|
|
"401": { description: Unauthorized }
|
|
"403": { description: Forbidden }
|
|
"404": { description: Not found }
|
|
"409": { description: Conflict }
|
|
"423": { description: Execution disabled }
|
|
/tasks/{task_id}/heartbeat:
|
|
post:
|
|
security: [ { bearerAuth: [] } ]
|
|
summary: Renew task claim lease
|
|
parameters: [ $ref: "#/components/parameters/TaskId" ]
|
|
responses:
|
|
"200": { description: Leased }
|
|
"400": { description: Bad request }
|
|
"401": { description: Unauthorized }
|
|
"403": { description: Forbidden }
|
|
"404": { description: Task or claim not found }
|
|
"409": { description: Claim conflict }
|
|
"413": { description: Payload too large }
|
|
"423": { description: Lease or execution locked }
|
|
"503": { description: Service unavailable }
|
|
/tasks/{task_id}/progress:
|
|
post:
|
|
security: [ { bearerAuth: [] } ]
|
|
summary: Report task progress
|
|
parameters: [ $ref: "#/components/parameters/TaskId" ]
|
|
responses:
|
|
"200": { description: Progress saved }
|
|
"400": { description: Bad request }
|
|
"401": { description: Unauthorized }
|
|
"403": { description: Forbidden }
|
|
"404": { description: Task or claim not found }
|
|
"409": { description: Claim conflict }
|
|
"413": { description: Payload too large }
|
|
"423": { description: Lease or execution locked }
|
|
"503": { description: Service unavailable }
|
|
/tasks/{task_id}/result:
|
|
post:
|
|
security: [ { bearerAuth: [] } ]
|
|
summary: Submit task result
|
|
parameters: [ $ref: "#/components/parameters/TaskId" ]
|
|
responses:
|
|
"200": { description: Result accepted }
|
|
"400": { description: Bad request }
|
|
"401": { description: Unauthorized }
|
|
"403": { description: Result policy rejected }
|
|
"404": { description: Task or claim not found }
|
|
"409": { description: Duplicate or mismatched result }
|
|
"413": { description: Payload too large }
|
|
"423": { description: Lease or execution locked }
|
|
"503": { description: Verification service unavailable }
|
|
/tasks/{task_id}/fail:
|
|
post:
|
|
security: [ { bearerAuth: [] } ]
|
|
summary: Mark task failed
|
|
parameters: [ $ref: "#/components/parameters/TaskId" ]
|
|
responses:
|
|
"200": { description: Failure recorded }
|
|
"400": { description: Bad request }
|
|
"401": { description: Unauthorized }
|
|
"403": { description: Forbidden }
|
|
"404": { description: Task or claim not found }
|
|
"409": { description: Claim conflict }
|
|
"413": { description: Payload too large }
|
|
"423": { description: Lease or execution locked }
|
|
"503": { description: Service unavailable }
|
|
/tasks/{task_id}/cancel:
|
|
post:
|
|
security: [ { bearerAuth: [] } ]
|
|
summary: Cancel task
|
|
parameters: [ $ref: "#/components/parameters/TaskId" ]
|
|
responses:
|
|
"200": { description: Cancelled }
|
|
"400": { description: Bad request }
|
|
"401": { description: Unauthorized }
|
|
"403": { description: Forbidden }
|
|
"404": { description: Task not found }
|
|
"409": { description: Revision or state conflict }
|
|
"413": { description: Payload too large }
|
|
"423": { description: Resource locked }
|
|
"503": { description: Service unavailable }
|
|
/tasks/{task_id}/delegate:
|
|
post:
|
|
security: [ { bearerAuth: [] } ]
|
|
summary: Delegate task
|
|
parameters: [ $ref: "#/components/parameters/TaskId" ]
|
|
responses:
|
|
"200": { description: Delegated }
|
|
"400": { description: Bad request }
|
|
"401": { description: Unauthorized }
|
|
"403": { description: Forbidden }
|
|
"404": { description: Parent task not found }
|
|
"409": { description: Conflict }
|
|
"413": { description: Payload too large }
|
|
"423": { description: Execution locked }
|
|
"503": { description: Service unavailable }
|
|
/workers/register:
|
|
post:
|
|
security: [ { bearerAuth: [] } ]
|
|
summary: Register worker
|
|
responses:
|
|
"201": { description: Worker registered }
|
|
"400": { description: Bad request }
|
|
"401": { description: Unauthorized }
|
|
"403": { description: Worker identity mismatch }
|
|
"409": { description: Registration conflict }
|
|
"413": { description: Payload too large }
|
|
"423": { description: Resource locked }
|
|
"503": { description: Service unavailable }
|
|
/workers/{worker_id}/heartbeat:
|
|
post:
|
|
security: [ { bearerAuth: [] } ]
|
|
summary: Worker heartbeat
|
|
parameters: [ $ref: "#/components/parameters/WorkerId" ]
|
|
responses:
|
|
"200": { description: Heartbeat accepted }
|
|
"400": { description: Bad request }
|
|
"401": { description: Unauthorized }
|
|
"403": { description: Forbidden }
|
|
"404": { description: Worker not found }
|
|
"409": { description: Worker state conflict }
|
|
"413": { description: Payload too large }
|
|
"423": { description: Worker locked }
|
|
"503": { description: Service unavailable }
|
|
/workers:
|
|
get:
|
|
summary: List workers
|
|
responses:
|
|
"200": { description: Worker list }
|
|
/workers/{worker_id}:
|
|
get:
|
|
summary: Get worker
|
|
parameters: [ $ref: "#/components/parameters/WorkerId" ]
|
|
responses:
|
|
"200": { description: Worker details }
|
|
/tasks/{task_id}/events:
|
|
get:
|
|
summary: Task events
|
|
parameters: [ $ref: "#/components/parameters/TaskId" ]
|
|
responses:
|
|
"200": { description: Event list }
|
|
/tasks/{task_id}/evidence:
|
|
get:
|
|
summary: Task evidence
|
|
parameters: [ $ref: "#/components/parameters/TaskId" ]
|
|
responses:
|
|
"200": { description: Evidence list }
|
|
/tasks/{task_id}/children:
|
|
get:
|
|
summary: Task child tasks
|
|
parameters: [ $ref: "#/components/parameters/TaskId" ]
|
|
responses:
|
|
"200": { description: Child list }
|
|
components:
|
|
securitySchemes:
|
|
bearerAuth:
|
|
type: http
|
|
scheme: bearer
|
|
bearerFormat: opaque
|
|
parameters:
|
|
TaskId:
|
|
name: task_id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
minLength: 1
|
|
maxLength: 128
|
|
pattern: '^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$'
|
|
WorkerId:
|
|
name: worker_id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
minLength: 1
|
|
maxLength: 128
|
|
pattern: '^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$'
|
|
schemas:
|
|
TaskPlan:
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
schema_version: { type: integer, enum: [1] }
|
|
task_id:
|
|
type: string
|
|
minLength: 1
|
|
maxLength: 128
|
|
pattern: '^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$'
|
|
task_type:
|
|
type: string
|
|
minLength: 1
|
|
maxLength: 128
|
|
pattern: '^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$'
|
|
issuer: { type: object }
|
|
intent: { type: string, maxLength: 16384 }
|
|
required_capabilities:
|
|
type: array
|
|
maxItems: 128
|
|
items: { type: string }
|
|
preferred_workers:
|
|
type: array
|
|
maxItems: 64
|
|
items: { type: string }
|
|
risk: { type: string, enum: [low, medium, high] }
|
|
approval_policy:
|
|
type: string
|
|
maxLength: 128
|
|
dependencies:
|
|
type: array
|
|
maxItems: 128
|
|
items: { type: string }
|
|
max_delegation_depth: { type: integer, minimum: 0, maximum: 32 }
|
|
budgets:
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
time_seconds: { type: integer, minimum: 0 }
|
|
attempts: { type: integer, minimum: 0 }
|
|
tokens: { type: integer, minimum: 0 }
|
|
cost: { type: number, minimum: 0 }
|
|
evidence_requirements:
|
|
type: array
|
|
maxItems: 128
|
|
items: { type: string }
|
|
parent_task_id:
|
|
type: string
|
|
maxLength: 128
|
|
correlation_id:
|
|
type: string
|
|
maxLength: 128
|
|
metadata:
|
|
type: object
|
|
TaskClaimRequest:
|
|
type: object
|
|
additionalProperties: false
|
|
required: [worker_id, actor_identity]
|
|
properties:
|
|
worker_id:
|
|
type: string
|
|
maxLength: 128
|
|
pattern: '^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$'
|
|
lease_seconds:
|
|
type: integer
|
|
minimum: 1
|
|
maximum: 3600
|
|
actor_identity:
|
|
type: string
|
|
minLength: 1
|
|
maxLength: 512
|