Hold this session back from the organisation, or hand it back
Marks one conversation private, or hands it back to organisation, which is what every session is until somebody says otherwise. Inside one organisation the team is the default and this mark is the only exception to it.
IT TAKES EFFECT ON THE NEXT READ, from anywhere. Nothing caches the answer: every read of a session asks the stored mark at the moment it is served, so a session marked here disappears from a colleague’s list and their open window’s next request at once, without a restart and without anything being pushed to them.
WHO MAY CALL IT: the session’s owner, always — a person’s own conversation is theirs to hold back — and a member who administers the organisation’s membership, for anybody, because a departed colleague’s work has to be able to come back to the team. Nobody else, and deliberately not the holder of sessions:read-private: that permission exists so a security question can be answered, and it does not extend to changing what everybody else may read.
Marking a session the mark it already carries is not an error: the state asked for holds. Nothing is announced and nothing is written into the transcript — who may read a conversation is a fact about it rather than something that happened in it, and its position in a session list does not move.
Autorizações
Enforced on every transport, with no exempt operation. A person's request — over the default local unix socket exactly as over a TCP listener — must carry a JWT issued by the configured identity provider, which the host verifies itself against that issuer's key set: signature, issuer, expiry, and the person and organisation it names. Requests without a valid one receive 401 NRY-0011. The socket's file permissions are transport and are not an authorisation.
Parâmetros de caminho
The session's id.
Corpo
The visibility to put a session under. One field, required: an omitted field is refused rather than read as "hand it back to the organisation", because a request that did not say which visibility it meant has to be answered rather than guessed for — and the permissive guess would take the mark off a conversation somebody held back. SessionPosture's rule and its reason.
Who inside this organisation may read a session. organisation — every member may, which is the default and what every session is until somebody marks it. private — its owner, plus a member holding sessions:read-private, plus whoever a share of it names.
Two values and no third. There is no "unset": the absence of a mark IS the organisation's, so "nobody said" and "the team may read it" are one fact rather than two, and nothing in this product has a use for a visibility somebody would have to define.
organisation, private Resposta
The session, under the visibility it now holds.
A durable conversation container. Survives the process that created it; archiving hides it from active lists but its transcript remains queryable and exportable forever.
The session's id.
Absolute path of the directory the session works in.
It is a working-directory LABEL and carries no authority. The session's key is id, and whose session it is is recorded by the host from the identity it authenticated the request as — nothing is authorised, looked up or scoped to a tenant by this field. What it is read for is what a directory is for: where the tools are confined, which project's configuration and instruction files apply, and the repository filter on listSessions.
4096Lifecycle: running while a turn executes or normal follow-ups chain; waiting after interrupt when admitted steering or follow-up inputs remain queued; idle only when neither execution nor queued input exists; archived accepts no new work.
idle, running, waiting, archived Which kind of client opened this session, recorded when it was created and never rewritten. Always present: unknown for a session created before this host recorded the datum, which is the honest answer rather than a guessed frontend.
inline, tui, oneshot, api, unknown When this session's own ROW last changed. Eight writes stamp it and nothing else does: its status, its provider and model, its style, its title, its repository, its environment binding, its archival, and the status a restart settles it into.
IT IS NOT A LAST-ACTIVITY CLOCK, and reading it as one is the mistake this description exists to prevent. A transcript entry, a streamed event, a tool call, a summary and a viewed mark all leave it exactly where it was — so a session that is running carries THE MOMENT ITS TURN WAS CLAIMED, not the moment anything last happened in it — and a moment later than that only when one of the other seven writes landed during the turn: a rename mid-turn is allowed and restamps the row, moving this field forward with nothing having happened in the conversation. A caller asking whether a run has gone quiet reads the event stream; read off this field, "nothing for N minutes" is true of every healthy turn that has been running longer than N, and false of a stuck one somebody renamed.
SessionAttention.since carries the same warning for a waiting session, and for the same reason.
Human-readable title.
512The model provider currently in use.
The model currently in use.
The preset of request options this session's turns run under — the name, not the options it stands for, since what a name means is the catalogue's answer and can change while the session's own choice cannot. Absent on a session that never chose one, which is every session running its model at the model's own defaults.
The named response style this session's answers are shaped by — the name, not the prompt it appends, since what a name means is configuration's answer and changes when somebody edits that file while the session's own choice does not. Absent on a session that never chose one, which is every session answering in narya's own voice. Unlike variant it survives a model switch: a style is a fact about how the conversation reads rather than about the model answering it. A client renders this and derives nothing — the names that exist are the host's answer (setSessionStyle refuses the rest).
64One sentence stating what a client could not otherwise know about the model this session opened on or was just moved to, present on the responses to createSession and setSessionModel. Two facts earn it. The first is a model narya chose itself rather than being told to use: no default_model configured and no model previously chosen, so the first provider holding a usable credential answered — or a named model the catalogue no longer carries, for which the provider default was substituted. It names the alternatives that also qualified and how to choose another, because a choice nobody made has to be stated to be a choice at all rather than something that merely happened. The second is a level this session will run without: a model reference may carry one (see the variant field), and an endpoint that does not take the field runs at its own default instead — so a level named at creation or at a switch, or configured beside default_model, is said here rather than quoted in a picker while every request drops it. A client that renders the live event stream rather than the session's transcript has no other road to it. Otherwise absent, including for a model that was simply configured, chosen or named; absent on getSession and listSessions, which report state rather than how it came about.
1024What this session has consumed and cost across every turn it has run — a running total, not the last turn's figure. Carried by getSession and by every row of listSessions, so a client drawing a list of sessions can say what each one has cost without asking per row. Absent on a session that has never completed a turn, and its costUsd is absent whenever any one of that session's turns could not be priced: the sum over only the priced turns is smaller than what the session actually cost, and a figure that quietly understates money is worse than an admitted unknown.
What the newest round of this session's own conversation sent and produced — the LAST turn's figure, not the running total above. Carried by getSession only. It exists because the two are not interchangeable for the one question a reader reopening a long conversation asks: how much room is left before this compacts. That answer is the size of the prompt last sent, and usage above is a sum over every turn the session ever ran, which is a larger number growing without bound and means nothing as a fraction of a context window. The live event stream carries this figure on turn-finished, so a client watching a session has always had it; a client that READ the session had no source for it at all and drew no context figure until it spent a turn of its own. Restoring a recorded reading rather than deriving one is the whole of it — nothing here is computed from the transcript. The newest round of the MAIN lane: a delegation's rounds are another conversation's prompts, and the figure is about the reader's. Absent on a session that has never completed a round, and on one whose rounds all ran on delegates. Its costUsd is that one round's price, absent when the round could not be priced.
Pending steering and follow-up references in durable operation order. Content is intentionally absent; fetch the transcript by entryId.
When the session was branched, the session it branched from.
What a model said this conversation tried and concluded. Absent until somebody asks for it (summarizeSession) — nothing summarises a branch because a rewind moved away from it. A model that answers past this length is trimmed to it, with a marker saying so rather than a sentence that just stops.
4096When the summary was taken. Read against updatedAt it answers whether the summary predates the last thing that happened here.
Whether somebody is there to answer a permission prompt raised here. Absent on a session nobody ever said either way about, which reads as attended — the posture is only ever recorded because somebody stated it (setSessionPosture), never inferred from whether a client happens to be connected.
attended, detached Whether this session pays to keep its provider cache alive while nobody is using it, and the most it may ever spend doing so. Absent on a session nobody ever turned it on for, which is every session until somebody does — warming is off unless somebody asked (setSessionWarming).
When a reader last had this session in front of them (acknowledgeSessionViewed). Read against updatedAt it answers whether anything has happened here since somebody looked, which is what lets a client mark a background conversation as carrying news — and, because the fact is held here rather than in a window, what makes two clients agree about it and makes the answer survive a relaunch. ABSENT on a session nobody has ever viewed, which is not the same as viewed long ago: one has nothing to report, the other has everything that ever happened in it.
How the last turn here ended. It is what lets a client that was not running at the time tell a conversation that finished from one that failed. Absent on a session that has never run a turn. An interrupt is not among the values: somebody was there and stopped it themselves, so it is not news to bring back to them.
finished, failed What this session's provider prompt cache has cost it, from both sides: what letting it expire cost, and what keeping it alive cost. Present only on getSession, and only once one of the two has happened — a session that has never paid for either carries nothing here rather than a pair of zeros.
Where this session's code lives and its commands run, present only when that is somewhere other than the host's own machine. Absent is the ordinary case and says the session runs here — a developer working on their own machine is told nothing, because there is nothing to tell.
The agent's own task list for this session — every item it has written, in the order it wrote them, whatever is in the store right now.
It is here rather than behind a listing of its own because the list is a stored row and every client already reads the session when it attaches, so one optional field costs no round trip and no second operation. A change to the list is announced as task-list, which carries the same whole list for the same reason; this is where a client that was not attached at the time gets it.
Present on getSession only, like lastTurnUsage and cacheSpend and for their reason: a listing that carried it would read every row's tasks to draw a page nobody asked for.
ABSENT MEANS EMPTY, and it cannot mean anything narrower: the store holds rows, so a list nobody ever wrote and a list somebody cleared are the same read. The live stream is where those two differ — a clearing write announces task-list carrying an empty array — and a read that returned [] would be claiming to know which of the two it was looking at.
Who this session belongs to: the identifier of the person the request that created it was authenticated as, inside the organisation this host serves. It is who the session is attributed to and whose allowance its cache warming is billed against.
The host writes it from the authenticated identity and there is no owner field on any create request — its absence there is the rule rather than an omission, because an owner a caller can name is an owner anybody can be, and this value is read later by whoever decides who pays and who may open a private conversation. A request body naming an owner changes nothing.
unclaimed is the one value that is not a person: a store that existed before this host recorded owners, on a machine nobody has signed in on yet. The first sign-in against such a store replaces it everywhere.
Who inside this organisation may read this session. Always present on a host that serves this field, unlike posture beside it: every session HAS a visibility, and the absence of a mark is the organisation's rather than a third state, so there is nothing for an absent field to mean. A client draws the mark from this value and derives nothing — whether a session is held back, and whether this reader may see it at all, are the host's answers.
organisation, private What this conversation is waiting for, when it is waiting for a person. status says waiting and does not say what for.
Carried by every row of listSessions and resolved for the whole page in one read, which is the point of it: a page of a hundred rows is enough to draw a fleet, with no request per row.
ABSENT WHEN THERE IS NOTHING TO SAY, and absent rather than null-shaped: a conversation nobody is being asked about carries no field, not an empty object. It is also absent when the caller may not see the prompt itself — on a conversation somebody marked private, a reader who is not its owner and does not hold the read-private permission sees no attention even though the request behind it exists, because what this field may say is bounded by the same door the ask is behind.