Sessions

Bucky uses a unified session system to maintain conversation context across platforms. A single work item can span Slack, Jira, and GitHub while sharing the same session history.

Session architecture

Sessions are UUID-based and managed by Google ADK (Agent Development Kit). A SessionIndex table maps platform-specific identifiers to canonical session UUIDs:

Platform	Index key format	Example
Slack	slack:<channel>:<thread_ts>	slack:C01ABC:1234567890.123456
Jira	jira:<issueKey>	jira:AD-1234
GitHub	github:<owner/repo>#<number>	github:fetch-rewards/my-service#42

Cross-platform continuity

When a user starts a conversation in Slack and Bucky creates a Jira ticket and GitHub issue, all three are linked to the same session:

1. Slack message creates a new session with index key slack:channel:ts
2. create_jira_ticket tool registers jira:AD-1234 → same session UUID
3. create_github_issue tool registers github:owner/repo#42 → same session UUID

Future events on any of these surfaces resolve to the same session, so the agent has full conversation context regardless of which platform the follow-up comes from.

Session persistence

Environment	Storage	Details
Production	Aurora PostgreSQL via GORM	Tables auto-migrated on startup
Local dev	In-memory	Falls back when DATABASE_HOST is unset

Sessions expire after 30 days of inactivity.

Workflow callbacks

When a Claude session completes, the report-session-outcome action POSTs results to the agent’s callback endpoint. The agent uses the session index to find linked channels and routes responses in this priority order:

1. Jira — if the session has a linked Jira ticket, post a comment there
2. Slack — if the session has a linked Slack thread, post a message there
3. GitHub — fall back to commenting on the GitHub issue

Pending sessions

The run_claude_session tool dispatches async Claude sessions and records a PendingSession mapping the workflow UUID back to the originating ADK session. When the workflow completes and calls back, the agent resumes the correct session with the results.

Pending sessions expire after 1 hour.

Note

The session index uses first-writer-wins (ON CONFLICT DO NOTHING) upsert semantics, so the first event to register a platform key owns the mapping.