Sessions
Sessions

Set Session Stream Header

Changed on

Rename a session.

name_source says where the name came from: manual (the default) is a person typing one, and automatic is a program proposing one — the agent's rename_session, or the browser's auto-title. An automatic edit is refused with 409 when it would change a name a person controls, unless the body names the exact name and revision it replaces.

It is a query parameter rather than a body field on purpose. The rename_session catalog entry fixes name_source=automatic inside its path and the model fills only the body, so an agent cannot claim a person chose its name.

author is the transitional spelling, hidden from the schema. A warm agent session holds the tool descriptors it opened with, so a sandbox that started under an earlier build of this change can still execute ?author=auto after the service has moved on. Reading it costs one branch and keeps that call on the guarded path; the alternative is a rename that silently claims a person made it. Delete this parameter once no such session can still be alive.

post/sessions/streams/header

Request

  • Base URL
    /api (relative, and the document was published on a file host, not at the API’s origin)
  • URL
    /api/sessions/streams/header
  • Auth
    API key in header Authorization

Query parameters

session_idstring required
name_source'manual' | 'automatic'

Where a session's name came from: a person, or a program.

It governs the name only, never the description, and it is not caller identity — both kinds of request run under the same user credential. manual is a person typing a name. automatic is a program proposing one: the agent's own rename_session, or the browser's auto-title from a first message.

It travels as a query parameter, never in the body, so a model cannot claim a person chose its name: the rename_session catalog entry fixes name_source=automatic inside its own path and the model only ever fills the body.

manual is the default, which is a real trade rather than a free win. An unmarked caller (a script, a service running an older SDK during a rolling deploy) is read as a person, so an automatic name it writes is remembered as person-chosen and the next agent rename of that session is refused until a person renames it. That is the recoverable direction. The other default loses a person's name instead.

Request body

namestring nullable
descriptionstring nullable
replacing_namestring nullable
replacing_revisioninteger nullable

Response

Successful Response

runner_addressstring

The address of the runner pod that ran the stream's last turn. Filled only for a caller that proves it is runner infrastructure; empty when unknown. A routing hint, not proof that the pod is alive.

runner_replica_idstring

The replica id of the runner pod at runner_address. The caller checks it against the pod's health answer before it uses the address, because a dead pod's IP can pass to another pod. Filled under the same condition as runner_address; empty when unknown.

Changes

  • ad74c9933b67Revision changes
    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

  • a28f1d059149Revision changes
    • info

      the response's property default value changed from false to true for the status

    • info

      the response's property default value changed from false to true for the status

    • info

      the response's property default value changed from false to true for the status