Skip to navigation

Comment on a work session, waking any agent it mentions

View as Markdown

Starts one turn per mentioned agent, then appends the caller’s comment entry to the timeline — in that order, so turn_started holds the lower seq. The comment is appended WHATEVER the turns answer: a human’s message is always an entry (spec §5.4). An agent that refuses is named in refused with its reason, and a system entry below the comment says so on the timeline; the call still answers 201, with turns carrying only the turns that started ([] when none did). A refused agent still joins the session’s roster, so it shows in the right rail. A turn is scoped to the SESSION’s working set plus whatever this comment attaches in fileIds, so a caller never re-sends the session’s own files. An attachment JOINS that working set for good — it appears in the session’s files, in the right rail and in every later turn’s scope, instead of living for one turn and vanishing (R9-05). A session file that was deleted is left out of the turn’s scope but stays in the session’s files; a system entry names the agents that work without it. The appended comment carries startedTurnIds naming every turn it started, because those turns are written first and therefore hold a LOWER seq — that field is the causal link a timeline reader orders by. Every id in fileIds must exist and be readable by the caller (space:read on the space it lives in), otherwise 404. A mention of an agent that is still working steers its live turn when the scope is unchanged, and starts a SECOND turn (its own frozen snapshot) when it adds a file. Authorization: work_session:comment on the session, OR space:contribute on one of its linked spaces; a desk session is writable only by its owner. Any denial is 404. mentions mixes agent ids, agent handles and member user ids, and each is RESOLVED: a member (confirmed against the org directory) gets an inbox row, a published agent takes a turn whose capability belt (space type, creatable space types, delegable agents, resolved connectors) is resolved HERE as the caller and frozen into that turn’s run snapshot — one grant per turn. A mention that is neither is dropped and returned in unresolvedMentions so the composer can flag an unknown @name; a mention of a real but unpublished or archived agent is 422 agent_not_published. Responds 201 { data: { entry, turns, unresolvedMentions, refused } }.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

sessionIdstringRequired

Request

This endpoint expects an object.
textstringRequired1-4000 characters
requestIdstringOptionalformat: "uuid"
threadIdstringOptional1-128 characters
mentionslist of stringsOptionalDefaults to []
fileIdslist of stringsOptional

Files this comment ATTACHES. The turn runs on the session’s working set plus these, so re-sending the session’s own files is never necessary; a file that is new to the session widens the scope and starts a successor turn instead of steering the live one.

Response

The appended entry and the turns it started.
dataobject

Errors

400
Bad Request Error
404
Not Found Error
409
Conflict Error
422
Unprocessable Entity Error