A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
Model client identity on host attachments (#11214)
Trevor Manz705115cb758e
diff --git a/marimo/_core/protocol.py b/marimo/_core/protocol.pyindex c895da9ab8..82c63454ae 100644--- a/marimo/_core/protocol.py+++ b/marimo/_core/protocol.py@@ -549,20 +549,32 @@ class Attachment(Struct, frozen=True):kind: Annotated[str,Meta(- description="What kind of thing is attached, such as `browser`, `editor`, or `agent`. Clients accept kinds they do not recognize."+ description="What kind of thing is attached, supplied by `Marimo-Attachment-Kind`, such as `browser`, `editor`, or `agent`. Defaults to `client` when the header is omitted. Clients accept kinds they do not recognize."),]name: (Annotated[str,Meta(- description="A label to show people, such as the browser or editor's name. Null when there is none."+ description="A label to show people, supplied by `Marimo-Attachment-Name`, such as the browser or editor's name. Null when the header is omitted or empty."),]| None)notebook_id: NotebookIdsince: Annotated[datetime, Meta(description="When it attached.")]+ identity: (+ Annotated[+ str,+ Meta(+ description="The opaque client identity supplied by `Marimo-Attachment-Identity`.\nOmitted when none was supplied. Consumers can group attachments\nwith the same identity within a host. It does not identify an\nindividual connection or change its lifetime.\n",+ max_length=128,+ min_length=1,+ pattern="^[!-~]+$",+ ),+ ]+ | UnsetType+ ) = UNSETclass AttachmentMessage(Struct, frozen=True):diff --git a/protocols/host/fixtures/attachments.sse b/protocols/host/fixtures/attachments.ssenew file mode 100644index 0000000000..48da9a0ca8--- /dev/null+++ b/protocols/host/fixtures/attachments.sse@@ -0,0 +1,18 @@+event: attachment+data: {"attachment":{"id":"a1","notebook_id":"n1","identity":"agent-123","kind":"agent","name":"Notebook CLI","since":"2026-10-01T09:20:00Z"}}++event: attachment+data: {"attachment":{"id":"a2","notebook_id":"n1","identity":"agent-123","kind":"agent","name":"Notebook CLI","since":"2026-10-01T09:20:01Z"}}++id: 100+event: ready+data: {}++id: 101+event: attachment.removed+data: {"id":"a1","time":"2026-10-01T09:20:02Z"}++id: 102+event: attachment+data: {"attachment":{"id":"a3","notebook_id":"n1","identity":"agent-123","kind":"agent","name":"Notebook CLI","since":"2026-10-01T09:20:03Z"},"time":"2026-10-01T09:20:03Z"}+diff --git a/protocols/host/openapi.yaml b/protocols/host/openapi.yamlindex 5d9ffdc0e9..b12a55c3eb 100644--- a/protocols/host/openapi.yaml+++ b/protocols/host/openapi.yaml@@ -190,8 +190,13 @@ paths:Opening this stream attaches the client to the notebook. Anattachment appears on both streams while the connection is open- and is removed when it closes. The snapshot includes every run- that is not yet completed, with its executions and items, plus+ and is removed when it closes. Every opening, including a reconnect,+ creates a separate attachment. The optional+ `Marimo-Attachment-Identity` header supplies its `identity` so+ consumers can group connections from the same client. A shared+ identity does not merge attachments or extend their lifetimes.+ The snapshot includes every run that is not yet completed, with+ its executions and items, plusany completed results the host retains. Result retention isindependent of replay history. Removed objects are absent fromsnapshots; a resumable stream carries their removal events.@@ -209,6 +214,9 @@ paths:- $ref: '#/components/parameters/Types'- $ref: '#/components/parameters/RunFilter'- $ref: '#/components/parameters/LastEventId'+ - $ref: '#/components/parameters/AttachmentIdentity'+ - $ref: '#/components/parameters/AttachmentKind'+ - $ref: '#/components/parameters/AttachmentName'responses:'200':description: The notebook, then changes, as server-sent events.@@ -562,6 +570,46 @@ components:own loopback interface, and clients never follow redirects, so thetoken never leaves the machine.parameters:+ AttachmentIdentity:+ name: Marimo-Attachment-Identity+ in: header+ required: false+ description: |+ An opaque client identity, copied to the attachment's `identity`.+ Clients can reuse it across streams and reconnects so consumers+ can group their attachments within a host. It is descriptive data,+ not an authentication credential or an idempotency key. Every+ stream still creates its own attachment. Invalid values receive+ a 400 `invalid-request` response.+ schema:+ type: string+ minLength: 1+ maxLength: 128+ pattern: '^[!-~]+$'+ AttachmentKind:+ name: Marimo-Attachment-Kind+ in: header+ required: false+ description: |+ What kind of client is attached, such as `browser`, `editor`, or+ `agent`. Copied to the attachment's `kind`; omitted means `client`.+ Hosts accept kinds they do not recognize. Values must contain one+ or more lowercase ASCII letters, digits, or hyphens; invalid values+ receive a 400 `invalid-request` response.+ schema:+ type: string+ pattern: '^[a-z0-9-]+$'+ default: client+ AttachmentName:+ name: Marimo-Attachment-Name+ in: header+ required: false+ description: |+ A human-readable label copied to the attachment's `name`, such as+ `Notebook CLI`. Omitted or empty means the attachment's name is+ null. The value must be at most 256 bytes when encoded as UTF-8;+ longer values receive a 400 `invalid-request` response.+ schema: { type: string }IdempotencyKey:name: Idempotency-Keyin: header@@ -856,17 +904,28 @@ components:An attachment is a consumer connected to a notebook, such as abrowser tab, an editor, or an agent. Opening the notebook's streamcreates one. It is removed when that connection closes, and not- when the notebook's runtime stops or restarts.+ when the notebook's runtime stops or restarts. Each stream has its+ own attachment, even when several share a client identity.required: [id, notebook_id, kind, name, since]properties:id: { $ref: '#/components/schemas/AttachmentId' }notebook_id: { $ref: '#/components/schemas/NotebookId' }+ identity:+ type: string+ minLength: 1+ maxLength: 128+ pattern: '^[!-~]+$'+ description: |+ The opaque client identity supplied by `Marimo-Attachment-Identity`.+ Omitted when none was supplied. Consumers can group attachments+ with the same identity within a host. It does not identify an+ individual connection or change its lifetime.kind:type: string- description: What kind of thing is attached, such as `browser`, `editor`, or `agent`. Clients accept kinds they do not recognize.+ description: What kind of thing is attached, supplied by `Marimo-Attachment-Kind`, such as `browser`, `editor`, or `agent`. Defaults to `client` when the header is omitted. Clients accept kinds they do not recognize.name:type: [string, 'null']- description: A label to show people, such as the browser or editor's name. Null when there is none.+ description: A label to show people, supplied by `Marimo-Attachment-Name`, such as the browser or editor's name. Null when the header is omitted or empty.since:type: stringformat: date-timediff --git a/protocols/host/spec.md b/protocols/host/spec.mdindex 03b98c6c82..2281e50c35 100644--- a/protocols/host/spec.md+++ b/protocols/host/spec.md@@ -97,9 +97,19 @@ choosing how it is stored and which operations each client can use. Severalclients can share a notebook while only some are permitted to edit or save it.An **attachment** represents a client's connection to a notebook. It belongs to-the notebook and remains connected across runtime restarts. Stopping a runtime-ends its active work and loses its Python state, while the document and retained-results remain available to clients.+the notebook and remains connected across runtime restarts. Each opening of a+notebook's event stream MUST create a separate attachment, removed when that+connection closes, including when reconnecting with `Last-Event-ID`.++When opening a stream, clients MAY supply `Marimo-Attachment-Identity`,+`Marimo-Attachment-Kind`, and `Marimo-Attachment-Name`. Hosts expose these as+`identity`, `kind`, and `name` on the attachment, as defined in the OpenAPI+schema. Consumers can use a shared identity to group attachments from the same+client across streams and reconnects. Each attachment still has its own id and+lifetime; identity does not merge connections or keep an attachment alive.++Stopping a runtime ends its active work and loses its Python state, while the+document and retained results remain available to clients.### Runs and results