Comment on a work session, waking any agent it mentions
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
Bearer authentication of the form Bearer <token>, where token is your auth token.
Path parameters
Request
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.