Multi-session daemon
One core-agent daemon serves multiple concurrent sessions belonging to different users — each with its own identity, ACL, permission grants, instruction overlays, and audit attribution. Multi-session is opt-in and strictly backward-compatible: deployments that don’t enable it see identical single-user behavior.
This page covers when to turn it on, how to configure it, and what isolation guarantees the substrate gives you. Design background: docs/multi-session-design.md in the repo.
When to use it
Section titled “When to use it”The single-user “one process per user per pod” model is fine for personal interactive sessions and per-tenant pod-per-user K8s deployments. Reach for multi-session when one or more of these is true:
- Multi-tenant platform-agent deployments. A platform team wants every engineer to have their own session(s) in a shared daemon, without each one needing their own pod.
- Shared chat-channel sessions. A Slack/GChat/Teams bot fronts a session that channel members collectively contribute to; per-prompt attribution needs to thread through audit logs and per-caller MCP credentials.
- Multi-session-per-user workflows. A single user driving multiple parallel agent sessions from a chat-bot front-end (different threads, different tasks) wants those to be genuinely independent — separate context, separate permission grants, separate plan-first state.
- Operator + agent separation in headless deployments. An alerting system POSTs
/injecton behalf of multiple downstream operators; today’s single bearer token can’t distinguish them.
If none apply, leave multi-session off — the configuration surface is small but non-zero.
Enabling it
Section titled “Enabling it”Multi-session is configured under attach.multi_session in .agents/config.json. Minimum usable shape:
{ "version": 1, "attach": { "listen": ":7777", "multi_session": { "enabled": true, "auth": { "kind": "bearer_table", "table_file": "/etc/core-agent/users.json" }, "admin_identities": ["ops@example.com"] } }}When enabled: true, every request entering the attach listener resolves to a Caller via the configured Authenticator. The Caller threads through:
- per-session ACL enforcement (only the owner / viewers / contributors / admins can see or write to a session)
- the eventlog metadata sidecar (every event row carries
caller+ optionalproxy_byso audit queries are “who did what”) - the per-caller instruction overlay path (each user can have their own
.agents/directory layered on top of the daemon-wide instructions) - outbound MCP tool calls (servers that inspect the caller can use it for downstream IAM / 3LO credentials)
users.json — the bearer table
Section titled “users.json — the bearer table”The static user table is the v2.4-shipped Authenticator. OIDC / JWT / mTLS / K8s ServiceAccount are designed but deferred.
{ "version": 1, "users": [ { "identity": "alice@example.com", "token_sha256": "5912db5fe837c1e3...", "labels": { "team": "platform" } }, { "identity": "bob@example.com", "token_sha256": "5ef3557e4c215bd1...", "labels": { "team": "infra" } }, { "identity": "sa:cron-runner", "token_sha256": "853ffc2afc310f22...", "labels": { "kind": "service" } } ]}Each row stores token_sha256, the hex SHA-256 of the bearer token its holder presents. The table never holds the token itself, so reading it yields nothing a request can authenticate with (#1213). The daemon hashes each presented token and compares digests in constant time. Produce a row’s value with core-agent auth hash-token, which reads the token from stdin and never from the command line, where it would land in shell history and the process list:
printf '%s' "$ALICE_TOKEN" | core-agent auth hash-token# 64 hex characters: paste into alice's "token_sha256"On a terminal, core-agent auth hash-token prompts without echoing. It refuses input with whitespace in it (two lines, padding), because that digest would match nothing a client sends.
The digest hides only a token too random to guess: anyone holding it can hash candidate tokens and compare. Mint tokens with openssl rand -hex 32 (256 bits), and hash-token warns about anything shorter than 32 characters. That’s also why it’s a plain SHA-256 rather than bcrypt or argon2: those slow down guessing a human’s password, which a random token doesn’t need, and they’d add their cost to every authenticated request.
Plaintext rows still load. A row may carry the older "token": "<plaintext>" instead. It authenticates exactly as before, but startup warns, naming every identity still stored that way (never the token):
core-agent: warning: users file /etc/core-agent/users.json stores a plaintext bearer token for: bob@example.com. Anyone who can read the file, including the agent's bash when it runs as this daemon's user, can authenticate with what it finds there. Replace each "token" with "token_sha256": printf '%s' "$TOKEN" | core-agent auth hash-token (#1213)The startup summary counts them too (multi-session auth: bearer_table, 3 users (1 with a plaintext token), ...). Migrating a row doesn’t change its token: hash the token the holder already has, and replace the field. A row sets exactly one of token and token_sha256. Two rows with the same token are rejected whichever field each uses, because the loader compares digests. Load errors never quote either value.
Daemons from before this change reject a token_sha256 row as an unknown field. Hash the table only once every daemon that reads it has been upgraded.
File-mode requirement: when every row in a users.json table uses token_sha256 (no plaintext token rows), mode 0644 or stricter (0640, 0600, 0444, 0400) is accepted because reading the file yields no usable credential — allowing a hashed users.json to be staged via an AX Workspace spec.files entry or a Kubernetes ConfigMap (#1483, #1485). Whenever any row carries a plaintext token, mode 0600 or stricter (0400), or 0640/0440 when the owning group is one the daemon process belongs to, is required. Group write or execute and world write or execute are rejected in every case. Failing this is a startup error, not a warning — bearer tokens deserve the same posture as a private SSH key.
The group-read carve-out exists because Kubernetes leaves no alternative. fsGroup is the standard way to give a non-root pod read access to a Secret volume, and it unconditionally sets group-read on every file in that volume — so a Secret mounted at defaultMode: 0400 arrives as 0440 and a blanket rejection fails by construction. The membership test is the whole security argument: group-read widens access to members of the owning group and to nobody else, so when the daemon is already one of those members the bit grants no read it did not already hold. Supplementary groups count, because fsGroup without runAsGroup lands the gid there rather than on the primary. When the daemon is not a member, the load still fails, and the error names the gid on both sides:
auth: users file "/etc/core-agent/users.json" has mode 0440 and is group-owned bygid 2000, which this process (gid 65532) is not a member of; use 0600, or set theKubernetes fsGroup to a group the container runs asGenerate tokens with whatever your secret manager uses; the loader has no opinion as long as the table gets the digest. A simple bootstrap, which hands each token to its holder and keeps only the digest:
for who in alice bob ops sa-cron; do tok=$(openssl rand -hex 32) echo "$who token (give to $who): $tok" echo "$who token_sha256 (put in users.json): $(printf '%s' "$tok" | core-agent auth hash-token)"donedev/tools/gen-users-json in the repository writes a whole hashed table the same way.
One credential: token_identity
Section titled “One credential: token_identity”A daemon with a single client credential, its attach token, can skip the table file. auth.token_identity serves that token as a one-row table:
"multi_session": { "enabled": true, "auth": { "token_identity": "switchboard" }}A request presenting the token from --attach-token (or --attach-token-file) authenticates as switchboard. Sessions work as with a table: POST /sessions creates sessions it owns, ACLs apply, and admin_identities can name it. The row holds the token’s SHA-256, like a token_sha256 row. It is meant for deployments with nowhere to keep a 0600 file, such as an AX task, whose environment and files end up in the sandbox’s template and snapshots.
token_identity and table_file are mutually exclusive, and the daemon refuses to start an attach listener with token_identity but no attach token. By default the one row attributes every turn to that identity. When proxy_identities includes the token_identity and proxy_unprovisioned: true is set (for example "proxy_identities": ["switchboard"], "proxy_unprovisioned": true), that proxy caller may also assert downstream end-user identities via X-Asserted-Caller without pre-provisioning them in a users.json table; unprovisioned asserted identities receive no labels and no admin privileges (#1485). Single-user daemons that pass --attach-token without enabling multi_session also serve POST /sessions (stamping sessions with default_identity, "anon" by default).
Keeping the table away from the agent
Section titled “Keeping the table away from the agent”File modes keep users.json from other users. They don’t keep it from the agent, which runs as the daemon’s user. Any plaintext token in the table answers permission prompts and can inject work under its holder’s identity, so an agent that reads a plaintext table can approve its own calls, and one that writes the table can add its own row for the next boot (#1201).
Hashing closes the read route completely. When every row stores token_sha256, the agent can read the whole table and learn nothing it can authenticate with (#1213). It needs no extra privilege in the pod or on the host. It does nothing about writing the table. Mount it read-only (a Kubernetes Secret volume already is), or make it unwritable by the daemon’s user. The measures below still apply, and are what protect a table that still has plaintext rows:
-
Agent file tools are refused on the table, in every permission mode including yolo, and nobody can approve it. That covers
read_file,write_file,edit_file,delete_file,grep,glob,read_many_files,json_query,view_file_outline,list_dirandstat. It holds for any path that is the table now: a symlink, a hard link, or the new file after a Kubernetes Secret update. Directory walks skip it. The table is protected whenevertable_fileis set, even withmulti_session.enabledoff. -
Instruction files can’t include it. An
@includeof the table, or anAGENTS.d/entry that links to it, fails the load and names the file. Without this, an agent with nothing butwrite_filecould editAGENTS.mdand get every token in the next session’s prompt. -
A
bashcommand that names the table directly is refused too. That means its absolute path, its resolved path, or its path relative to the working directory. This is a seatbelt, not a boundary:cdplus a bare name, a glob or a variable still reach it. The gate sees a command string, not the files the shell opens. Hook commands go through the same check, so a hook that names the table is refused as well. -
The daemon is made non-dumpable whenever
table_fileis set, because the table stays in its memory. Same mechanism as for withheld env credentials. -
Startup warns when the daemon’s user can read the table and either
bashis registered or the table sits inside the agent’s path scope:core-agent: warning: credential file /etc/core-agent/users.json is readable by the user this daemon runs as, and so by the agent's bash, ...
For a table with plaintext rows, only hashing them or the operating system can close the bash route. On a multi-session daemon, hash every row, or disable the shell ("tools": {"disable": ["bash"]}), or arrange that the daemon’s user can’t read the file once the daemon has loaded it. The readable-table warning above doesn’t look at whether the rows are hashed, so a fully hashed table still triggers it. In every case, mount the table outside the project tree, where directory listings won’t show it to the model.
Don’t run the daemon as root with CAP_SYS_PTRACE either. Every process the agent starts would inherit it and could read the table straight out of the daemon’s memory. Startup warns about this too.
Authorization model
Section titled “Authorization model”Every session has an ACL with three roles. Authorization is per-action, not per-resource — the matrix is intentionally compact:
| Admin | Owner | Viewers | Contributors | |
|---|---|---|---|---|
SessionList | ✓ | ✓ | ✓ | ✓ |
SessionRead | ✓ | ✓ | ✓ | ✓ |
SessionWrite | ✓ | ✓ | ✓ | |
SessionAdmin | ✓ | ✓ | ||
DaemonAdmin | ✓ |
- Admin identities (
admin_identitiesin config) bypass every check. Use sparingly. - Owner — the identity that created the session. Full access except
DaemonAdmin. - Contributors — can inject and use existing grants, can’t modify the ACL. Used for shared sessions where multiple identities take turns (e.g., a Slack channel where every member can DM the agent).
- Viewers — read-only. Can stream events and read state; can’t inject.
Denied requests return 404, not 403. This is intentional — hiding the existence of unauthorized sessions prevents an attacker from enumerating session IDs through differential responses. Audit logs on the server side capture the real reason.
Setting the ACL
Section titled “Setting the ACL”The owner and admins can populate the two lists over HTTP, either at creation or afterwards:
POST /sessions → {"viewers": [...], "contributors": [...]}PATCH /sessions/{sid}/acl → {"viewers": [...], "contributors": [...]}GET /sessions/{sid}/acl → {"owner":..., "viewers": [...], "contributors": [...]}Both verbs on /acl require SessionAdmin, including the read — the ACL names the other people on a session, so a contributor listing their co-responders is a disclosure with no reason to happen. On PATCH, an omitted list is left alone and [] clears it; ownership is not transferable through either endpoint. Full semantics in the attach HTTP reference.
Before protocol 1.10.0 there was no such route: the lists were enforced everywhere but settable nowhere, so every session was effectively owner-plus-admins.
Anonymous and default identity
Section titled “Anonymous and default identity”default_identity(default"anon") — the Caller stamped on requests that don’t carry a credential. Used by single-user mode (where it’s the only identity) and as the AllowAnonymous fallback when multi-session is on.allow_anonymous(defaultfalse) — whentrue, unauthenticated requests resolve to the DefaultCaller instead of returning 401. Dangerous in shared environments — every unauthenticated request becomes the same identity. Leave it off unless you’re running on a trusted internal network and explicitly want that posture.
Shared-session pattern (chat-bot integration)
Section titled “Shared-session pattern (chat-bot integration)”A common ask: a Slack/GChat/Teams bot fronts ONE session that the whole channel contributes to. The bot authenticates as itself; each per-channel message asserts the human user’s identity so audit logs and per-caller MCP credentials attribute to the human, not the bot.
The substrate supports this via the proxy role + X-Asserted-Caller header:
POST /sessions/incident-channel/injectAuthorization: Bearer tok_slack_bot_...X-Asserted-Caller: alice@example.comContent-Type: application/json
{"message": "investigate the 5xx spike on checkout-svc"}Configuration:
{ "attach": { "multi_session": { "enabled": true, "auth": { "kind": "bearer_table", "table_file": "/etc/core-agent/users.json" }, "admin_identities": ["ops@example.com"], "proxy_identities": ["sa:slack-bot", "sa:gchat-bot"], "asserted_caller_header": "X-Asserted-Caller" } }}The proxy_identities allowlist is what makes this safe — a compromised bot can only assert identities that the operator has provisioned in users.json, and the audit log records BOTH identities (caller=alice@… + proxy_by=sa:slack-bot) on every event in the turn.
Rules:
- Default is no proxy capability. Identities not in
proxy_identitiesget 401 if they try to useX-Asserted-Caller. - By default (
proxy_unprovisioned: falsewithtable_file), the asserted identity must exist in the user table (401 "asserted-caller header rejected: identity is not provisioned"). Set"proxy_unprovisioned": truealongsideproxy_identities(or useauth.token_identitywithproxy_identities) when the front-door proxy is the source of truth for end-user identities (for example a Slack or Google Chat switchboard assertingU12345orusers/1234567890); unprovisioned asserted callers get no labels and never inheritadmin_identitiesprivileges, and malformed header values (whitespace, control characters, invalid UTF-8, or> 256bytes) are rejected with401 "asserted-caller header rejected: identity is invalid". - Asserted-caller headers from non-proxy callers are logged (forensic trail) and rejected.
Per-session isolation guarantees
Section titled “Per-session isolation guarantees”When multi-session is enabled, each session gets a derived sub-gate with its own:
- Permission grants (
sessionAllow/sessionAllowTools/sessionAllowVerbs) — alice’s/allow write_file allow-sessiondoesn’t grant bob’s session anything. - Plan-first flag (
planRecorded) — alice’srecord_plandoesn’t unblock bob’s mutating tools.POST /sessions/{sid}/slash/replanrevokes against that session’s sub-gate and archives only the plan that session recorded; alice’s/replannames bob’s newer artifact and leaves it alone, since.agents/plans/is process-global. (Before v2.9 the hub left this closure unwired, so every session-created/replananswered501and only the daemon’s own startup session could revoke.) - Approval audit (
approvals) — per-session interactive-decision log. - Runtime allow / deny patterns: alice’s
/allowor/deny, or herPOST /sessions/{sid}/perms/allow|deny, changes her session only. Configured patterns still apply in every session, a session’s deny narrows a configured allow, and a session’s allow can’t lift a configured deny. Adding an allow pattern takes the session owner or an admin; a contributor can add deny patterns. By default on a multi-session daemon, non-admin callers cannot addbashor unprefixed (any-tool) allow patterns unlessattach.multi_session.allow_non_admin_bash: trueis set (#1355). Runtime patterns live on the session’s in-memory gate, so an idle eviction followed by a resume, or a daemon restart, drops them; a deny that must hold belongs in config. (Before #1176 these went into the shared policy, so a contributor on one session could add*and auto-allow calls in every other session.) - Permission mode: alice changing her session’s mode with the TUI chip or with
POST /sessions/{sid}/perms/mode(owner or admin only) doesn’t change bob’s session’s mode. On a multi-session daemon, switching a session toyolorequires a daemon admin (admin_identities) by default unlessattach.multi_session.allow_non_admin_yolo: trueis set (#1355). - Prompter — each session’s UI hooks (TUI broker, HTTP prompt stream) are independent. Approving a
bashprompt on a multi-session daemon requires a daemon admin by default unlessattach.multi_session.allow_non_admin_bash: trueis set (#1355). - Background subagents — each session gets its own subagent manager, so a subagent spawned from alice’s session runs behind alice’s sub-gate, branches off alice’s session in the eventlog, and reports back into alice’s turn.
GET /sessions/{sid}/subagentsreturns that session’s roster, and evicting the session tears its subagents down. (Before v2.9 a daemon-created session had no manager at all:spawn_agentwas present but bound to the daemon’s, so the roster read empty and spawns ran under the daemon-wide gate.) - Declarative subagents, both doors — a subagent declared in
subagents[]is callable two ways: asynchronously asspawn_agent {agent: "cluster"}, and synchronously as a tool literally namedcluster. A daemon-created session gets both, the same as the daemon’s own session. The subagent itself is built once at startup and shared — a rooted subagent’s MCP servers are not stood up again per tenant — but the tool wrapping it is per-session, so a delegation runs behind the delegating tenant’s sub-gate and lands in that tenant’s branch of the eventlog. (Before v2.9 tenant sessions got the asynchronous door only.)
What is NOT isolated across sessions (conversation isolation, not OS/execution isolation):
- OS user, working directory, and filesystem. Multi-session isolates conversations, ACLs, and in-memory permission grants — not process execution, until per-session sandboxing (#651) lands. Every tool call across every session executes as the daemon’s OS UID against the same working directory and can reach any file the daemon’s user can read or write (including the shared SQLite session database when SQLite is used). For that reason, non-admin callers on a multi-session daemon cannot select
yolomode or approvebashexecution in their own session unless a daemon admin approves it or the operator explicitly setsattach.multi_session.allow_non_admin_yolo: true/attach.multi_session.allow_non_admin_bash: true(#1355). permissions.allow/permissions.denypatterns from config.- An “allow always” answer to a prompt: it installs the pattern in the shared policy (or path scope, for a path) and persists it, and persisted grants load for every session after a restart. “Always” means beyond this session, so it takes a daemon admin (
admin_identities). Anyone else’s “allow always”, the session owner’s included, is applied as “allow for this session” (#1179). See Who can allow always.
Per-caller instruction overlays
Section titled “Per-caller instruction overlays”Each Caller can have their own .agents/ directory layered on top of the daemon-wide instructions:
/var/lib/core-agent/users/ <-- attach.multi_session.users_dir├── alice@example.com/│ └── .agents/│ ├── AGENTS.md <-- alice's role-shaped overlay│ └── AGENTS.d/│ └── 01-incident-runbook.md└── bob@example.com/ └── .agents/ └── AGENTS.md <-- bob's overlayConfiguration:
{ "attach": { "multi_session": { "enabled": true, "users_dir": "/var/lib/core-agent/users/" } }}The overlay loader runs the same @include + AGENTS.d/ semantics as the project-scope loader (see Instruction loader). Missing overlay directories are silently skipped — provision overlays for the callers who need them; the rest fall back to the daemon-wide instructions.
Path safety: Caller identities containing /, \, or .. (such as Google Chat’s users/1234567890) are rejected by instruction.LoadForSession and treated by session creation as having no per-caller overlay. Email-shaped (alice@example.com) and service-account-marker (sa:slack-bot) identities map to <users_dir>/<identity>/.agents/.
Audit log
Section titled “Audit log”Every event written to the eventlog carries a Metadata sidecar with:
| Key | Value |
|---|---|
caller | Effective Caller.Identity (e.g. alice@example.com) |
proxy_by | Proxying identity, when the call went through the proxy path (e.g. sa:slack-bot). Omitted otherwise. |
Query directly via SQL: each agent_eventlog row has a Metadata TEXT column carrying the sidecar JSON. “Who did what in this shared channel session” becomes:
SELECT seq, author, metadataFROM agent_eventlogWHERE session_id = ?ORDER BY seq;In single-user deployments, the metadata column is empty for every row — no behavior change on disk or wire.
Migration story
Section titled “Migration story”Three phases for an operator moving from single-user to multi-user:
- Stay single-user — no change.
multi_session.enabled: false(the default). - Enable with a static user table — generate tokens (e.g. via
dev/tools/gen-users-json), populateusers.jsonat mode0600, hand them to operators. Each operator loads their token into an env var and runscore-agent-tui --token-env ALICE_TOKEN <attach-url>(the--token-envflag takes an env-var name, not the value itself). The flag order doesn’t matter — both--token-env NAME http://hostandhttp://host --token-env NAMEwork. Sessions they create are owned by them; they can only see their own. - Switch to OIDC / mTLS / K8s SA (when shipped, v2.5+) — change
auth.kindto the new value; tokens come from the IDP. Users / sessions unchanged.
A core-agent users migrate CLI is out of scope for v2.4 — operators with existing single-user data either keep using single-user mode or accept that legacy sessions become “unowned” (admin-only-accessible) when they enable multi-session.
Session resume (v2.5+)
Section titled “Session resume (v2.5+)”Sessions created via POST /sessions survive daemon restarts. A TUI reconnecting after core-agent restarts (config change, image upgrade, K8s pod replacement, crash) resumes transparently — same SessionID, same conversation history, same ACL. No --new-session fallback, no lost context.
How it works
Section titled “How it works”Every RegisterOwned call writes a row to agent_session_acl (a new GORM table sharing the eventlog’s database). The row carries (app, user, sid, owner, viewers, contributors, created_at, last_touched_at). On daemon restart the in-memory registry is empty, but the row persists. The next Lookup for that session misses the memory map, calls the resumer, reads the row, reconstructs the agent under the same triple, and installs it in the registry. ADK’s session.Service reads the same eventlog and reattaches the prior conversation history automatically. If the restart caught a turn mid-tool-call, the history is healed on the next turn — see Sessions → Interrupted tool calls are repaired automatically.
Cost: one DB query + one agent.New on the first reconnect (~50 ms typically). Subsequent requests hit the memory registry directly.
Concurrent resume of the same session is deduplicated — two TUIs reconnecting simultaneously trigger exactly one resumer call and share the resulting *Entry.
Idle eviction
Section titled “Idle eviction”Once sessions persist, the registry would grow unboundedly without eviction. A background sweep evicts entries idle past session_idle_timeout; the ACL row stays on disk, so the next Lookup lazily re-resumes them.
Configuration knob (under attach.multi_session):
| Value | Meaning |
|---|---|
omitted / "" | default 24h |
"0s" | disabled — sessions stay in memory forever (tiny local-dev daemons) |
"6h", "30m", "7d" | parsed via time.ParseDuration |
Example:
{ "attach": { "multi_session": { "enabled": true, "session_idle_timeout": "6h" } }}What counts as activity (keeps a session non-idle):
- A memory-hit Lookup — every authenticated event-stream request, every inject, every wake.
- Any event pumped by the broadcaster — including autonomous agent work (long tool calls, background compaction). A busy agent is never idle.
What doesn’t count:
- Time spent evicted — an evicted session’s disk timestamp only bumps when it’s re-resumed.
Trade-off: a session stuck in a broken retry loop keeps broadcasting events, so it stays non-idle. Kill it with /interrupt (v2.4+) or DELETE /sessions/<sid> (v2.7+). The bootstrap default session is refused with 403 — restart the daemon to reset it.
What resumes vs. what doesn’t
Section titled “What resumes vs. what doesn’t”Resumes:
- Sessions created via
POST /sessions(and any future path that callsRegisterOwnedwith a real Owner). - The persisted ACL, verbatim — Owner, Viewers, Contributors all restore.
- The conversation history from the eventlog.
Doesn’t resume:
- Legacy
Registersessions (no Owner, no ACL row). Consistent with “ACL row exists ⟺ session is resumable.” Startup-time agents in single-user deployments use this path; they behave the same across restart as they always have. - In-flight tool calls if the daemon crashed mid-turn. ADK picks up at the last committed event; whatever the agent was doing at the moment of crash is lost. Turn-boundary crash recovery is a separate concern (design non-goal).
- Sessions on a different daemon. Cross-daemon migration is out of scope.
GET /sessions after restart
Section titled “GET /sessions after restart”The list handler union-dedupes in-memory entries with persisted-only ACL rows the caller can read. Alice reconnecting after restart sees her sessions immediately — clicking in triggers the resume. Status field on each entry distinguishes "active" (in memory) from "idle" (persisted-only); LastTouchedAt supplies “last activity” ordering.
Failure modes
Section titled “Failure modes”- 404 on Lookup — no in-memory entry AND no persisted ACL row. Either the session never existed, was created via legacy
Register, or its row was hand-deleted. Same 404 surface as pre-v2.5, so operators reading old runbooks aren’t surprised. - 500 on Lookup — resume attempted but the factory failed (MCP server hiccup, ADC token refresh blip, downstream API rate-limit). Body carries the underlying cause. Retry usually succeeds. The 404 vs 500 distinction is deliberately narrow — the body never distinguishes “session doesn’t exist” from “factory failed” beyond the status code, so attackers can’t probe SessionIDs to learn which are persisted.
Backward compat
Section titled “Backward compat”- Existing v2.4 deployments upgrade cleanly. The
agent_session_acltable auto-migrates on daemon start; it starts empty. Pre-upgrade sessions in the eventlog have no ACL row → they’re admin-only-accessible after upgrade (matching v2.4 legacy behavior). New sessions created post-upgrade write ACL rows and resume normally. - Single-user deployments see zero behavior change. Resume machinery only wires when
multi_session.enabled: true. - Operators who want the pre-v2.5 “in-memory only” behavior can set
session_idle_timeout: "0s"— the sweep never runs, the ACL rows still get written for GET /sessions completeness, but nothing gets kicked out of memory.
Design detail: docs/session-resume-design.md in the repo.
In-place session switching (v2.6+ / core-tui v0.10.0)
Section titled “In-place session switching (v2.6+ / core-tui v0.10.0)”Prior versions required an exit-and-relaunch cycle to hop between sessions: q out of the TUI, re-launch, pick a different session from the startup picker. Painful when a single incident spawned N parallel triage sessions (v2.6 GKE-troubleshoot drive: 4+ sessions per incident, ~5-8 relaunch cycles).
With core-agent bumped to core-tui v0.10.0 the remote TUI (core-agent-tui) exposes two new slashes:
/switch [<sid>]— enumerate sessions viaGET /sessions, open an in-chat picker (or direct-jump when the operator types the sid). Chat wipes; the local SSE reader closes; the outgoing daemon session keeps running for later re-attach./new— POST/sessions, then detach + reattach to the fresh session in place. Companion for the “give me a clean slate” flow; previously requiredq+core-agent-tui --new-session.
The daemon-side lifecycle is unchanged — sessions detach cleanly, per-caller ACLs are still enforced on the new attach, session resume (§ Session resume) applies to the outgoing session verbatim.
Design details in core-tui issues #48 (SlashResult.SwitchTo API) and #53 (/switch UX). Adapter wiring in this repo lives in internal/coretuiremote/capabilities.go (Sessions / SwitchToSession).
For the operator-facing walkthrough — worked example, auth propagation, when-to-use-what table — see Attach TUI § Multi-daemon workflow.
Cross-daemon switching (v2.7+ / issue #246)
Section titled “Cross-daemon switching (v2.7+ / issue #246)”The v2.6 landing was scoped to sessions on one daemon — the daemon the TUI connected to at startup. Operators running multiple daemons (or peer-registered fleets discoverable via GET /peers) still had to q out and re-launch core-agent-tui <other-daemon-url> to hop daemons.
v2.7 (adapter wired via coretuiremote.NewWithClientFactory in cmd/core-agent-tui/main.go) closes that gap:
/switchpicker now includes peer sessions. Local sessions come first (unchanged); peer sessions follow, each row tagged[peer:<name>]in the Display and with the peer’s endpoint URL in the Description. Enter attaches in place — chat wipes and reopens against the peer’s session. The adapter’sclientFactoryclosure captures the operator’s startup--authmode +--token-env, so peer clients authenticate the same way the startup client did (audience-bound per endpoint for--auth=google-id-token)./attach <url>— escape hatch whenGET /peersis empty on the current daemon, or the operator wants to reach an unregistered daemon. Two forms:/attach <daemon-url>— enumerates that daemon’s sessions into a system message; operator picks a sid and reissues./attach <daemon-url> <sid>— direct-jump in place.
Peer fan-out is parallel with a 5s per-peer timeout (mirrors the startup picker’s budget); peers that error or time out are silently dropped so one bad peer doesn’t take down the whole picker.
Auth caveats:
- Peers that don’t share the operator’s auth policy (different bearer token, different IAM identity) will fail the peer’s
ListSessionsfan-out and drop from the picker without a chat error. Operators can still/attach <url>explicitly to see the failure surface. - Per-peer auth config (
--peer-auth peer-name=bearer-token) isn’t shipped in v2.7. Follow-up if the operator population requests it.
Design details in core-tui issue #56 (deferred text-input Dialog primitive, for a possible future inline endpoint-typing UX) and core-agent issue #246.
Recipe
Section titled “Recipe”See examples/multi-session-bearer/ in the repo for a minimum-viable two-user starter you can run locally in five minutes.
What’s not in v2.4
Section titled “What’s not in v2.4”Designed but explicitly deferred:
- OIDC / JWT / mTLS / K8s ServiceAccount Authenticators (interfaces only — bearer-table is the v2.4 implementation).
- Per-user quotas (tokens, cost, requests).
- User-management CLI (
core-agent users add/remove). Editusers.jsondirectly. - Cross-daemon session migration. Sessions live in the daemon process that created them.
- Per-session policy / path-scope carve-outs (the shared-substrate limitation noted above).
- IDP federation across daemons (an SSO concern, not core-agent’s).