Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

refactor: unify sessions — rename pts_ to ses_, remove auto-generated sessions

Bosch944cedf0341d
diff --git a/dashboard/src/activities/AgentActivityWorkspace.tsx b/dashboard/src/activities/AgentActivityWorkspace.tsx
index 3085b534..898ec7e0 100644
--- a/dashboard/src/activities/AgentActivityWorkspace.tsx
+++ b/dashboard/src/activities/AgentActivityWorkspace.tsx
@@ -417,7 +417,7 @@ export default function AgentActivityWorkspace({
const unlabeledPtsKey = useMemo(() => {
const apiIds = new Set(agentSessions.map((s) => s.id));
return derivedSessions
- .filter((s) => s.id.startsWith("pts_") && !apiIds.has(s.id))
+ .filter((s) => s.id.startsWith("ses_") && !apiIds.has(s.id))
.map((s) => s.id)
.sort()
.join(",");
diff --git a/docs/guides/agent-identity.md b/docs/guides/agent-identity.md
index 1546abf0..6281276c 100644
--- a/docs/guides/agent-identity.md
+++ b/docs/guides/agent-identity.md
@@ -89,10 +89,10 @@ Response:
```json
{
- "id": "pts_e6ac8132fe7e7016",
+ "id": "ses_e6ac8132fe7e7016",
"agentId": "bosch",
"label": "research task",
- "sessionToken": "pts_1138f72e77f23c49...",
+ "sessionToken": "ses_1138f72e77f23c49...",
"status": "active"
}
```
@@ -102,7 +102,7 @@ The `sessionToken` is returned exactly once. Store it — PinchTab only persists
### Use a Session
```bash
-export PINCHTAB_SESSION=pts_1138f72e77f23c49...
+export PINCHTAB_SESSION=ses_1138f72e77f23c49...
pinchtab nav https://example.com
pinchtab snap -i -c
pinchtab click e5
@@ -112,7 +112,7 @@ Or pass the header directly:
```bash
curl -X POST http://localhost:9867/navigate \
- -H "Authorization: Session pts_1138f72e77f23c49..." \
+ -H "Authorization: Session ses_1138f72e77f23c49..." \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com"}'
```
@@ -127,11 +127,11 @@ curl http://localhost:9867/api/agent-sessions \
-H "Authorization: Bearer $PINCHTAB_TOKEN"
# Rotate token (old token invalidated, new one returned)
-curl -X POST http://localhost:9867/api/agent-sessions/pts_e6ac8132fe7e7016/rotate \
+curl -X POST http://localhost:9867/api/agent-sessions/ses_e6ac8132fe7e7016/rotate \
-H "Authorization: Bearer $PINCHTAB_TOKEN"
# Revoke
-curl -X POST http://localhost:9867/api/agent-sessions/pts_e6ac8132fe7e7016/revoke \
+curl -X POST http://localhost:9867/api/agent-sessions/ses_e6ac8132fe7e7016/revoke \
-H "Authorization: Bearer $PINCHTAB_TOKEN"
```
diff --git a/docs/reference/sessions.md b/docs/reference/sessions.md
index d33813e2..910159a7 100644
--- a/docs/reference/sessions.md
+++ b/docs/reference/sessions.md
@@ -4,8 +4,8 @@ Agent sessions provide durable, revocable authentication for automated agents. I
## Overview
-- **Session token**: `pts_<48 hex chars>` — high-entropy, never stored raw (only SHA-256 hash persisted)
-- **Session ID**: `pts_<16 hex chars>` — public identifier for management
+- **Session token**: `ses_<48 hex chars>` — high-entropy, never stored raw (only SHA-256 hash persisted)
+- **Session ID**: `ses_<16 hex chars>` — public identifier for management
- **Auth header**: `Authorization: Session <token>`
- **Env var**: `PINCHTAB_SESSION` — CLI auto-detects and uses session auth
@@ -37,7 +37,7 @@ In `config.json`:
## Lifecycle
1. **Create** — via dashboard API: `POST /api/agent-sessions`
-2. **Use** — agent sends `Authorization: Session pts_...` with each request
+2. **Use** — agent sends `Authorization: Session ses_...` with each request
3. **Rotate** — generate a new token, old one invalidated: `POST /api/agent-sessions/{id}/rotate`
4. **Revoke** — permanently disable: `POST /api/agent-sessions/{id}/revoke`
@@ -53,7 +53,7 @@ In `config.json`:
```bash
# Set session token
-export PINCHTAB_SESSION=pts_abc123...
+export PINCHTAB_SESSION=ses_abc123...
# CLI automatically uses session auth
pinchtab snap
diff --git a/internal/activity/activity.go b/internal/activity/activity.go
index 0825b52a..75af9b52 100644
--- a/internal/activity/activity.go
+++ b/internal/activity/activity.go
@@ -2,7 +2,6 @@ package activity
import (
"bufio"
- "crypto/rand"
"crypto/sha256"
"encoding/hex"
"encoding/json"
@@ -16,15 +15,13 @@ import (
)
const (
- defaultSessionIdleTimeout = 30 * time.Minute
- defaultQueryLimit = 200
+ defaultQueryLimit = 200
maxQueryLimit = 1000
defaultRetentionDays = 1
)
type Config struct {
Enabled bool
- SessionIdle time.Duration
RetentionDays int
}
@@ -68,11 +65,6 @@ type Filter struct {
Limit int
}
-type sessionState struct {
- SessionID string
- LastSeen time.Time
-}
-
type Recorder interface {
Enabled() bool
Record(Event) error
@@ -80,12 +72,10 @@ type Recorder interface {
}
type Store struct {
- dir string
- sessionIdleLimit time.Duration
- retentionDays int
+ dir string
+ retentionDays int
- mu sync.Mutex
- sessions map[string]sessionState
+ mu sync.Mutex
}
type noopRecorder struct{}
@@ -94,29 +84,21 @@ func NewRecorder(cfg Config, stateDir string) (Recorder, error) {
if !cfg.Enabled {
return noopRecorder{}, nil
}
- if cfg.SessionIdle <= 0 {
- cfg.SessionIdle = defaultSessionIdleTimeout
- }
- return NewStore(stateDir, cfg.SessionIdle, cfg.RetentionDays)
+ return NewStore(stateDir, cfg.RetentionDays)
}
-func NewStore(stateDir string, sessionIdle time.Duration, retentionDays int) (*Store, error) {
+func NewStore(stateDir string, retentionDays int) (*Store, error) {
activityDir := filepath.Join(stateDir, "activity")
if err := os.MkdirAll(activityDir, 0750); err != nil {
return nil, fmt.Errorf("create activity dir: %w", err)
}
- if sessionIdle <= 0 {
- sessionIdle = defaultSessionIdleTimeout
- }
if retentionDays <= 0 {
return nil, fmt.Errorf("activity retentionDays must be > 0 (got %d)", retentionDays)
}
store := &Store{
- dir: activityDir,
- sessionIdleLimit: sessionIdle,
- retentionDays: retentionDays,
- sessions: make(map[string]sessionState),
+ dir: activityDir,
+ retentionDays: retentionDays,
}
if err := store.pruneExpiredFiles(time.Now().UTC()); err != nil {
return nil, err
@@ -142,9 +124,6 @@ func (s *Store) Record(evt Event) error {
evt.Timestamp = evt.Timestamp.UTC()
}
evt.URL = sanitizeActivityURL(evt.URL)
- if evt.SessionID == "" {
- evt.SessionID = s.sessionIDLocked(evt)
- }
if err := s.pruneExpiredFilesLocked(evt.Timestamp); err != nil {
return err
@@ -286,30 +265,7 @@ func (f Filter) matches(evt Event) bool {
return true
}
-func (s *Store) sessionIDLocked(evt Event) string {
- key := evt.ActorID
- if key == "" {
- key = "agent:" + evt.AgentID
- }
- if key == "" || key == "agent:" {
- return ""
- }
- now := evt.Timestamp
- prev, ok := s.sessions[key]
- if ok && now.Sub(prev.LastSeen) <= s.sessionIdleLimit {
- prev.LastSeen = now
- s.sessions[key] = prev
- return prev.SessionID
- }
-
- sessionID := randomID("ses_")
- s.sessions[key] = sessionState{
- SessionID: sessionID,
- LastSeen: now,
- }
- return sessionID
-}
func FingerprintToken(token string) string {
token = strings.TrimSpace(token)
@@ -413,14 +369,6 @@ func (s *Store) pruneExpiredFilesLocked(now time.Time) error {
return nil
}
-func randomID(prefix string) string {
- b := make([]byte, 4)
- if _, err := rand.Read(b); err != nil {
- return fmt.Sprintf("%s%x", prefix, time.Now().UnixNano()&0xffffffff)
- }
- return prefix + hex.EncodeToString(b)
-}
-
func appendJSONL(path string, line []byte) error {
f, err := os.OpenFile(path, os.O_CREATE|os.O_APPEND|os.O_WRONLY, 0600)
if err != nil {
diff --git a/internal/activity/activity_test.go b/internal/activity/activity_test.go
index 63497512..b00f7f38 100644
--- a/internal/activity/activity_test.go
+++ b/internal/activity/activity_test.go
@@ -10,7 +10,7 @@ import (
)
func TestStoreRecordAndQuery(t *testing.T) {
- store, err := NewStore(t.TempDir(), 30*time.Minute, 1)
+ store, err := NewStore(t.TempDir(), 1)
if err != nil {
t.Fatalf("NewStore: %v", err)
}
@@ -40,7 +40,7 @@ func TestStoreRecordAndQuery(t *testing.T) {
func TestStoreWritesJSONLFile(t *testing.T) {
root := t.TempDir()
- store, err := NewStore(root, 30*time.Minute, 1)
+ store, err := NewStore(root, 1)
if err != nil {
t.Fatalf("NewStore: %v", err)
}
@@ -63,7 +63,7 @@ func TestStoreWritesJSONLFile(t *testing.T) {
func TestStorePartitionsDashboardEventsOutsidePrimaryLog(t *testing.T) {
root := t.TempDir()
- store, err := NewStore(root, 30*time.Minute, 1)
+ store, err := NewStore(root, 1)
if err != nil {
t.Fatalf("NewStore: %v", err)
}
@@ -136,7 +136,7 @@ func TestStorePartitionsDashboardEventsOutsidePrimaryLog(t *testing.T) {
func TestStorePrunesExpiredDailyFiles(t *testing.T) {
root := t.TempDir()
- store, err := NewStore(root, 30*time.Minute, 1)
+ store, err := NewStore(root, 1)
if err != nil {
t.Fatalf("NewStore: %v", err)
}
@@ -186,7 +186,7 @@ func TestNewStorePrunesExpiredDailyFilesOnStartup(t *testing.T) {
t.Fatalf("WriteFile keep: %v", err)
}
- if _, err := NewStore(root, 30*time.Minute, 30); err != nil {
+ if _, err := NewStore(root, 30); err != nil {
t.Fatalf("NewStore: %v", err)
}
@@ -217,7 +217,7 @@ func TestNewStorePrunesExpiredSourceSpecificDailyFilesOnStartup(t *testing.T) {
t.Fatalf("WriteFile keep: %v", err)
}
- if _, err := NewStore(root, 30*time.Minute, 30); err != nil {
+ if _, err := NewStore(root, 30); err != nil {
t.Fatalf("NewStore: %v", err)
}
@@ -240,7 +240,7 @@ func TestNewRecorderDisabledReturnsNoop(t *testing.T) {
}
func TestNewStoreRejectsZeroRetentionDays(t *testing.T) {
- if _, err := NewStore(t.TempDir(), 30*time.Minute, 0); err == nil {
+ if _, err := NewStore(t.TempDir(), 0); err == nil {
t.Fatal("expected NewStore to reject zero retentionDays")
}
}
@@ -259,7 +259,7 @@ func TestClampQueryLimit(t *testing.T) {
func TestStoreRecord_SanitizesURLBeforePersisting(t *testing.T) {
root := t.TempDir()
- store, err := NewStore(root, 30*time.Minute, 1)
+ store, err := NewStore(root, 1)
if err != nil {
t.Fatalf("NewStore: %v", err)
}
diff --git a/internal/agentsession/store.go b/internal/agentsession/store.go
index b88824a3..2534cfce 100644
--- a/internal/agentsession/store.go
+++ b/internal/agentsession/store.go
@@ -388,7 +388,7 @@ func generateSessionID() (string, error) {
if _, err := rand.Read(buf); err != nil {
return "", err
}
- return "pts_" + hex.EncodeToString(buf), nil
+ return "ses_" + hex.EncodeToString(buf), nil
}
func generateToken() (string, error) {
@@ -396,7 +396,7 @@ func generateToken() (string, error) {
if _, err := rand.Read(buf); err != nil {
return "", err
}
- return "pts_" + hex.EncodeToString(buf), nil
+ return "ses_" + hex.EncodeToString(buf), nil
}
func hashToken(token string) [32]byte {
diff --git a/internal/agentsession/store_test.go b/internal/agentsession/store_test.go
index 7c0e136e..81e4a861 100644
--- a/internal/agentsession/store_test.go
+++ b/internal/agentsession/store_test.go
@@ -15,16 +15,16 @@ func TestCreateAndAuthenticate(t *testing.T) {
if err != nil {
t.Fatal(err)
}
- if !strings.HasPrefix(id, "pts_") {
- t.Fatalf("session ID should start with pts_, got %q", id)
+ if !strings.HasPrefix(id, "ses_") {
+ t.Fatalf("session ID should start with ses_, got %q", id)
}
- if !strings.HasPrefix(token, "pts_") {
- t.Fatalf("token should start with pts_, got %q", token)
+ if !strings.HasPrefix(token, "ses_") {
+ t.Fatalf("token should start with ses_, got %q", token)
}
- if len(token) != 4+48 { // pts_ + 48 hex chars
+ if len(token) != 4+48 { // ses_ + 48 hex chars
t.Fatalf("token length should be 52, got %d", len(token))
}
- if len(id) != 4+16 { // pts_ + 16 hex chars
+ if len(id) != 4+16 { // ses_ + 16 hex chars
t.Fatalf("session ID length should be 20, got %d", len(id))
}
@@ -43,7 +43,7 @@ func TestCreateAndAuthenticate(t *testing.T) {
func TestAuthenticateInvalidToken(t *testing.T) {
s := NewStore(Config{Enabled: true})
_, _, _ = s.Create("agent-1", "")
- sess, ok := s.Authenticate("pts_invalidtoken")
+ sess, ok := s.Authenticate("ses_invalidtoken")
if ok || sess != nil {
t.Fatal("expected failed authentication for invalid token")
}
@@ -126,7 +126,7 @@ func TestRevoke(t *testing.T) {
func TestRevokeNotFound(t *testing.T) {
s := NewStore(Config{Enabled: true})
- if s.Revoke("pts_nonexistent") {
+ if s.Revoke("ses_nonexistent") {
t.Fatal("expected revoke to return false for non-existent session")
}
}
@@ -253,7 +253,7 @@ func TestAtomicWrite(t *testing.T) {
t.Fatalf("expected 1 persisted session, got %d", len(store.Sessions))
}
// Verify no raw token in persisted data
- if strings.Contains(string(data), "pts_") && strings.Contains(string(data), `"token"`) {
+ if strings.Contains(string(data), "ses_") && strings.Contains(string(data), `"token"`) {
t.Fatal("raw token found in persisted data")
}
}
diff --git a/internal/authn/request_test.go b/internal/authn/request_test.go
index 12efeaf4..1523844d 100644
--- a/internal/authn/request_test.go
+++ b/internal/authn/request_test.go
@@ -73,20 +73,20 @@ func TestClientIP_FallsBackToRawRemoteAddr(t *testing.T) {
func TestCredentialsFromRequest_SessionAuth(t *testing.T) {
req := httptest.NewRequest("GET", "/", nil)
- req.Header.Set("Authorization", "Session pts_abc123")
+ req.Header.Set("Authorization", "Session ses_abc123")
creds := CredentialsFromRequest(req)
if creds.Method != MethodSession {
t.Fatalf("Method = %q, want %q", creds.Method, MethodSession)
}
- if creds.Value != "pts_abc123" {
- t.Fatalf("Value = %q, want %q", creds.Value, "pts_abc123")
+ if creds.Value != "ses_abc123" {
+ t.Fatalf("Value = %q, want %q", creds.Value, "ses_abc123")
}
}
func TestCredentialsFromRequest_SessionAuthCaseInsensitive(t *testing.T) {
req := httptest.NewRequest("GET", "/", nil)
- req.Header.Set("Authorization", "SESSION pts_token")
+ req.Header.Set("Authorization", "SESSION ses_token")
creds := CredentialsFromRequest(req)
if creds.Method != MethodSession {
diff --git a/internal/cli/apiclient/client.go b/internal/cli/apiclient/client.go
index d0de4a92..d820d37e 100644
--- a/internal/cli/apiclient/client.go
+++ b/internal/cli/apiclient/client.go
@@ -128,7 +128,7 @@ func setAuthHeader(req *http.Request, token string) {
if token == "" {
return
}
- if strings.HasPrefix(token, "pts_") {
+ if strings.HasPrefix(token, "ses_") {
req.Header.Set("Authorization", "Session "+token)
} else {
req.Header.Set("Authorization", "Bearer "+token)
diff --git a/internal/handlers/middleware_test.go b/internal/handlers/middleware_test.go
index 9dbebf95..9b28ef7f 100644
--- a/internal/handlers/middleware_test.go
+++ b/internal/handlers/middleware_test.go
@@ -1025,7 +1025,7 @@ func TestAuthMiddleware_SessionAuthInvalid(t *testing.T) {
}))
req := httptest.NewRequest("GET", "/health", nil)
- req.Header.Set("Authorization", "Session pts_invalidtoken")
+ req.Header.Set("Authorization", "Session ses_invalidtoken")
rr := httptest.NewRecorder()
handler.ServeHTTP(rr, req)
@@ -1045,7 +1045,7 @@ func TestAuthMiddleware_SessionAuthDisabled(t *testing.T) {
}))
req := httptest.NewRequest("GET", "/health", nil)
- req.Header.Set("Authorization", "Session pts_sometoken")
+ req.Header.Set("Authorization", "Session ses_sometoken")
rr := httptest.NewRecorder()
handler.ServeHTTP(rr, req)
diff --git a/internal/server/bridge.go b/internal/server/bridge.go
index bb6a32be..dde65dd6 100644
--- a/internal/server/bridge.go
+++ b/internal/server/bridge.go
@@ -33,7 +33,6 @@ func RunBridgeServer(cfg *config.RuntimeConfig, version string) {
bridgeInstance := bridge.New(context.Background(), nil, cfg)
actStore, err := activity.NewRecorder(activity.Config{
Enabled: cfg.Observability.Activity.Enabled,
- SessionIdle: time.Duration(cfg.Observability.Activity.SessionIdleSec) * time.Second,
RetentionDays: cfg.Observability.Activity.RetentionDays,
}, cfg.ActivityStateDir())
if err != nil {
diff --git a/internal/server/server.go b/internal/server/server.go
index 3e089f66..163759ed 100644
--- a/internal/server/server.go
+++ b/internal/server/server.go
@@ -89,7 +89,6 @@ func RunDashboard(cfg *config.RuntimeConfig, version string) {
})
actStore, err := activity.NewRecorder(activity.Config{
Enabled: cfg.Observability.Activity.Enabled,
- SessionIdle: time.Duration(cfg.Observability.Activity.SessionIdleSec) * time.Second,
RetentionDays: cfg.Observability.Activity.RetentionDays,
}, cfg.ActivityStateDir())
if err != nil {
diff --git a/skills/pinchtab/SKILL.md b/skills/pinchtab/SKILL.md
index 8abef12f..06ce7163 100644
--- a/skills/pinchtab/SKILL.md
+++ b/skills/pinchtab/SKILL.md
@@ -258,7 +258,7 @@ curl -X POST http://localhost:9868/action \
If the server is exposed beyond localhost, require a token and use a dedicated automation profile. See [TRUST.md](./TRUST.md).
-**Agent sessions**: Instead of sharing the server bearer token, each agent can get its own revocable session token. Set `PINCHTAB_SESSION=pts_...` or send `Authorization: Session pts_...`. Create via `POST /api/agent-sessions` with `{"agentId":"...", "label":"..."}`. Sessions have idle timeout (default 12h) and max lifetime (default 24h). Manage with rotate (`POST /api/agent-sessions/{id}/rotate`) and revoke (`POST /api/agent-sessions/{id}/revoke`).
+**Agent sessions**: Instead of sharing the server bearer token, each agent can get its own revocable session token. Set `PINCHTAB_SESSION=ses_...` or send `Authorization: Session ses_...`. Create via `POST /api/agent-sessions` with `{"agentId":"...", "label":"..."}`. Sessions have idle timeout (default 12h) and max lifetime (default 24h). Manage with rotate (`POST /api/agent-sessions/{id}/rotate`) and revoke (`POST /api/agent-sessions/{id}/revoke`).
## Essential Commands
diff --git a/skills/pinchtab/references/api.md b/skills/pinchtab/references/api.md
index 03a7443e..98c41870 100644
--- a/skills/pinchtab/references/api.md
+++ b/skills/pinchtab/references/api.md
@@ -456,7 +456,7 @@ curl -X POST /api/agent-sessions -d '{"agentId":"my-agent","label":"dev"}'
curl /api/agent-sessions
# Get current session (requires Session auth)
-curl -H "Authorization: Session pts_..." /api/agent-sessions/me
+curl -H "Authorization: Session ses_..." /api/agent-sessions/me
# Rotate token
curl -X POST /api/agent-sessions/{id}/rotate
diff --git a/skills/pinchtab/references/env.md b/skills/pinchtab/references/env.md
index 169910c5..ecf32766 100644
--- a/skills/pinchtab/references/env.md
+++ b/skills/pinchtab/references/env.md
@@ -36,7 +36,7 @@ PINCHTAB_TOKEN=...
Or use agent sessions for per-agent identity and revocability:
```bash
-PINCHTAB_SESSION=pts_...
+PINCHTAB_SESSION=ses_...
```
When `PINCHTAB_SESSION` is set, the CLI uses `Authorization: Session <token>` instead of bearer auth. The session maps to a specific agentId server-side and can be revoked independently.