compose-multi-session

command
v3.1.0-dev.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 2, 2026 License: Apache-2.0 Imports: 18 Imported by: 0

README

compose-multi-session — a multi-session daemon from pkg/compose

The #386 story: everything cmd/core-agent wires for its multi-session daemon is reachable as library composition helpers, so an embedder builds the same substrate without re-implementing the CLI. This example assembles the full stack — bearer auth, persistent permission grants, per-caller session factory, ACL-backed resume — and then drives it over HTTP as two identities.

What this shows

  • compose.BuildMultiSessionAuthn — a users.json bearer table (mode 0600 required) becomes the per-request auth.Authenticator. Its rows store token_sha256 (auth.HashToken), never the token itself, so reading the table yields nothing that authenticates (#1213).
  • permissions.New + gate.SetGrantStore(&permissions.ConfigGrantStore{...}) — an ask-mode check prompts, a scripted prompter answers allow always, and the grant persists into .agents/config.json (permissions.allow), surviving restarts.
  • gate.ProtectCredentialFiles(usersPath): a gate built with permissions.New rather than permissions.FromConfig doesn't know about the bearer table, so the example registers it. Without that call, the agent's file tools could read the tokens that answer its own permission prompts (#1201). BuildMultiSessionAuthn already keeps the table out of @include.
  • compose.SessionFactoryDeps + BuildSessionFactory / BuildSessionResumer — POST /sessions mints a fresh agent per caller (own sub-gate, own tracker, own wake loop); the resumer reconstructs evicted sessions from the persisted ACL store.
  • attach.NewServer with MultiSessionEnabled: true — per-session ACL enforcement: a stranger's read is a 404, not 403, so session existence never leaks.

Run it

go run ./examples/compose-multi-session

Hermetic: echo mock model, loopback listener, temp dirs, throwaway tokens. Exits 0 after a clean shutdown.

Key APIs

Concern API
authn compose.BuildMultiSessionAuthn(config.MultiSessionConfig{...})
grants permissions.Gate.SetGrantStore, permissions.ConfigGrantStore
sessions compose.SessionFactoryDeps, BuildSessionFactory, BuildSessionResumer
ACL persistence attach.NewSessionACLStore(ctx, handle.DB), attach.NewSessionRegistryWithStore
listener attach.Options{Authenticator, MultiSessionEnabled, SessionFactory, Resumer}

What you should see

  prompt: bash wants "git status" -> answering "allow always"
  persisted to .agents/config.json: permissions.allow = ["bash:git status"]
alice: POST /sessions -> 019f...
bob:   POST /sessions -> 019f...
alice: GET /sessions -> 1 session(s): [...]
bob:   GET alice's /status -> 404 (denied reads as not-found)
alice: POST .../inject -> 200 (wake loop runs the turn)

Note the gotcha the example handles for you: state-changing attach endpoints require Content-Type: application/json even on bodyless requests (CSRF protection).

Next pointers

  • The config-only flavor of the same deployment (run the real CLI): examples/multi-session-bearer.
  • Single-session library embedding: examples/attach-daemon.
  • Design rationale: docs/multi-session-design.md, docs/compose-extraction-design.md, docs/session-resume-design.md.

Documentation

Overview

Example: assemble a multi-session attach daemon from pkg/compose — the #386 story. Instead of re-implementing cmd/core-agent's wiring, a library consumer builds the same substrate from the composition helpers:

  • compose.BuildMultiSessionAuthn — bearer-table users.json -> per-request auth.Authenticator; the rows store token_sha256 (auth.HashToken), not the tokens
  • permissions.New + Gate.SetGrantStore(&permissions.ConfigGrantStore) — an "allow always" prompt answer persists into .agents/config.json (demonstrated with a scripted prompter)
  • compose.SessionFactoryDeps + BuildSessionFactory / BuildSessionResumer — fresh per-caller agents on POST /sessions, resumable from the persisted ACL store after eviction/restart
  • attach.NewServer with MultiSessionEnabled — per-session ACLs: bob cannot even see alice's session (404, not 403, by design)

The demo then drives the daemon over plain HTTP as two bearer identities (alice + bob) and shows creation, isolation, and inject.

go run ./examples/compose-multi-session

Hermetic: echo mock model, loopback listener, temp dirs, throwaway tokens. No credentials, no network beyond 127.0.0.1.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL