Session Types
These are the types behind $.session and the session.* events.
They describe the data a mod reads about a session, such as its messages, its context size, and its cost.
Pages
| Page | What is in it |
|---|---|
| Session Context and Append Types | Context to Session: the context breakdown types and the append and attach types. |
| Session Compact, Detach, Measure, and Messages Types | Session to Session: compact, context usage, cost, cron, detach, end, identity, measure, and messages types. |
| Session Receive, Send, and Usage Types | Session to Session: rate limit, receive, repo, resume, send, start, usage, and version types. |
Example
The first call reads usage data. The second call sends text to another session and tells you if it arrived.
const { startedAt, context, rateLimits, cost } = await $.session.usage();
const { isDelivered, reason } = await $.session.send({ to, text });
Types without Fields
These types are aliases, unions, or plain shapes. Each row gives its use and its shape.
| Type | Status | What it is for | Shape and limits |
|---|---|---|---|
Context | Documented: An official docs page names this item. | How a context breakdown is counted: full counts with the token-count API for each category. summary counts from the usage of the last response and local estimates. | Alias of 'summary' | 'full'. The get_ of the SDK takes the same two words as its detail. |
Context | Documented: An official docs page names this item. | What a breakdown row is. Branch on this, never on the name of the row. | Alias of 'used' | 'free' | 'buffer' | 'deferred'. deferred rows are tool schemas that load on demand and sit outside the window. |
Context | Documented: An official docs page names this item. | How the window that the breakdown measures against was settled. /context prints its Auto- line from this. | Alias of 'env' | 'settings' | 'clientdata' | 'experiment' | 'model-. Names who set the compaction window. auto is the own limit of the model. |
Session | Documented: An official docs page names this item. | Which door a row came in by, decided from the row alone. It is a closed set, pinned on the event, and the key that a matcher narrows on. | Alias of the twelve door names ('prompt', 'command', 'response', 'note', 'queue', and more). queue is the text of a message queue record, not a row of the conversation. |
Session | Documented: An official docs page names this item. | What a session. hook returns and what next(e) resolves to: the compaction ({ messages, tokens) or a skip. | Alias of Session. There is no summary string: the summary is a message. Used by session., $.. |
Session | Documented: An official docs page names this item. | Who compacts: the / of the person (manual), the engine at its threshold or on a prompt too long (auto), a plugin, or a precompute. | Alias of 'manual' | 'auto' | 'plugin' | 'precompute'. precompute installs nothing. Its result is kept for the next compaction. |
Session | Documented: An official docs page names this item. | Why a client left the roster: detach means it said so (ui_detach). end means the session ended with it still attached. | Alias of 'detach' | 'end'. |
Session | Documented: An official docs page names this item. | Why the session ended: the own reason of the classic SessionEnd hook, word for word. | Alias of Classic. Why the session ended, such as prompt_, clear, resume, logout, or other. |
Session | Documented: An official docs page names this item. | What $. resolves to: the conversation of the agent as ApiMessage, or { deny } (SessionMessagesDeny). | Alias of Api. Array. tells the two apart. Without agent it is always the messages. |
Session | Documented: An official docs page names this item. | $.: the rows of the main conversation with no argument, its Messages API form with { as:, the rows of an agent with agent, or deny. | Alias of five call signatures. The shape of the answer depends on the arguments: none, as:, agent, or both. Used by $.. |
Session | Documented: An official docs page names this item. | What $. resolves to: the messages (SessionMessage), or { deny } (SessionMessagesDeny). | Alias of Session. Without agent it is always the messages. With an id that the session cannot read, it is the deny. Array. tells the two apart. |
Session | Documented: An official docs page names this item. | What the { value } of a session. hook holds, for any call: the rows (SessionMessage), the Messages API form (ApiMessage), or { deny }. | Alias of Session. Used by session.. |