Add ask_human and the inbox with batched responses and delivery to agents
This commit is contained in:
Ian Gulliver
@@ -206,6 +206,62 @@ paths:
|
||||
"404": { $ref: "#/components/responses/Error" }
|
||||
"409": { $ref: "#/components/responses/Error" }
|
||||
|
||||
/api/inbox:
|
||||
get:
|
||||
operationId: listInbox
|
||||
description: >
|
||||
Inbox items, highest priority first (blocked, gate, review, fyi), then oldest first.
|
||||
Filters narrow the one query to a project's or a task's view.
|
||||
parameters:
|
||||
- { name: project_id, in: query, required: false, schema: { type: string } }
|
||||
- { name: task_id, in: query, required: false, schema: { type: string } }
|
||||
- { name: state, in: query, required: false, schema: { $ref: "#/components/schemas/InboxState" } }
|
||||
- { name: include_snoozed, in: query, required: false, schema: { type: boolean } }
|
||||
responses:
|
||||
"200":
|
||||
description: Matching items with their responses. Defaults to open, unsnoozed items.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: array
|
||||
items: { $ref: "#/components/schemas/InboxItem" }
|
||||
|
||||
/api/inbox/{itemId}:
|
||||
parameters:
|
||||
- { name: itemId, in: path, required: true, schema: { type: string } }
|
||||
get:
|
||||
operationId: getInboxItem
|
||||
responses:
|
||||
"200":
|
||||
description: The item with its responses.
|
||||
content:
|
||||
application/json:
|
||||
schema: { $ref: "#/components/schemas/InboxItem" }
|
||||
"404": { $ref: "#/components/responses/Error" }
|
||||
|
||||
/api/inbox/responses:
|
||||
post:
|
||||
operationId: respondInbox
|
||||
description: >
|
||||
Answers one or more items in one submission. Answers reach the agent as one message once
|
||||
it is idle and none of its blocking questions are unanswered.
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema: { $ref: "#/components/schemas/InboxRespond" }
|
||||
responses:
|
||||
"200":
|
||||
description: The updated items.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: array
|
||||
items: { $ref: "#/components/schemas/InboxItem" }
|
||||
"400": { $ref: "#/components/responses/Error" }
|
||||
"404": { $ref: "#/components/responses/Error" }
|
||||
"409": { $ref: "#/components/responses/Error" }
|
||||
|
||||
/api/events:
|
||||
get:
|
||||
operationId: streamEvents
|
||||
@@ -330,6 +386,96 @@ components:
|
||||
properties:
|
||||
text: { type: string }
|
||||
|
||||
Attachment:
|
||||
type: object
|
||||
required: [kind]
|
||||
properties:
|
||||
kind: { type: string, enum: [file, diff, image, diagram, task, snapshot, url] }
|
||||
path: { type: string, description: "file: repo-relative path." }
|
||||
start_line: { type: integer }
|
||||
end_line: { type: integer }
|
||||
ref: { type: string, description: "diff: git revision range." }
|
||||
url: { type: string }
|
||||
mermaid: { type: string, description: "diagram: Mermaid source." }
|
||||
image: { type: string, description: "image: data URL." }
|
||||
task_id: { type: string }
|
||||
snapshot_id: { type: string }
|
||||
caption: { type: string }
|
||||
|
||||
InboxState:
|
||||
type: string
|
||||
enum: [open, answered, redirected, dismissed, superseded]
|
||||
|
||||
InboxItem:
|
||||
type: object
|
||||
required: [id, project_id, task_id, agent_session_id, thread_id, kind, priority, blocking, payload, state, created_at, responses]
|
||||
properties:
|
||||
id: { type: string }
|
||||
project_id: { type: string }
|
||||
task_id: { type: string }
|
||||
agent_session_id: { type: string }
|
||||
thread_id: { type: string }
|
||||
kind: { type: string, enum: [question, report, session_error] }
|
||||
priority: { type: string, enum: [blocked, gate, review, fyi] }
|
||||
blocking: { type: boolean }
|
||||
payload:
|
||||
type: object
|
||||
description: >
|
||||
question: question, why_blocked, options, recommended_option, attachments.
|
||||
report: done, open_questions, next_steps, risks, deviations.
|
||||
session_error: error.
|
||||
state: { $ref: "#/components/schemas/InboxState" }
|
||||
snoozed_until: { type: string, format: date-time }
|
||||
created_at: { type: string, format: date-time }
|
||||
resolved_by: { type: string }
|
||||
resolved_at: { type: string, format: date-time }
|
||||
responses:
|
||||
type: array
|
||||
items: { $ref: "#/components/schemas/InboxResponse" }
|
||||
|
||||
InboxResponseType:
|
||||
type: string
|
||||
enum: [option, free_form, redirect, question, snooze, dismiss]
|
||||
|
||||
InboxResponse:
|
||||
type: object
|
||||
required: [id, item_id, user, type, attachments, created_at]
|
||||
properties:
|
||||
id: { type: string }
|
||||
item_id: { type: string }
|
||||
user: { type: string }
|
||||
type: { $ref: "#/components/schemas/InboxResponseType" }
|
||||
option: { type: string }
|
||||
text: { type: string }
|
||||
attachments:
|
||||
type: array
|
||||
items: { $ref: "#/components/schemas/Attachment" }
|
||||
snooze_until: { type: string, format: date-time }
|
||||
created_at: { type: string, format: date-time }
|
||||
delivered_at: { type: string, format: date-time }
|
||||
|
||||
InboxResponseCreate:
|
||||
type: object
|
||||
required: [item_id, type]
|
||||
properties:
|
||||
item_id: { type: string }
|
||||
type: { $ref: "#/components/schemas/InboxResponseType" }
|
||||
option: { type: string, description: "option: one of the question's options." }
|
||||
text: { type: string, description: "Required for free_form, redirect, question; an optional note on option." }
|
||||
attachments:
|
||||
type: array
|
||||
items: { $ref: "#/components/schemas/Attachment" }
|
||||
snooze_until: { type: string, format: date-time, description: "snooze: when the item reappears." }
|
||||
|
||||
InboxRespond:
|
||||
type: object
|
||||
required: [responses]
|
||||
properties:
|
||||
responses:
|
||||
type: array
|
||||
minItems: 1
|
||||
items: { $ref: "#/components/schemas/InboxResponseCreate" }
|
||||
|
||||
Event:
|
||||
type: object
|
||||
required: [seq, kind, actor, payload, created_at]
|
||||
|
||||
Reference in New Issue
Block a user