Claude Agent Teams: Refactor sessions to support multi-repository (0..N repos)

[Connoropolous]

Summary

• CyrusAgentSession now carries repositoryIds: string[] directly — supporting 0, 1, or N repositories per session
• EdgeWorker consolidates from a per-repo Map<string, AgentSessionManager> to a single global agentSessionManager with an ActivitySinkResolver callback
• RepositoryRouter returns repositories: RepositoryConfig[] (plural); issueRepositoryCache, getCachedRepository, restoreIssueRepositoryCache removed entirely
• PersistenceManager introduces v4.0 flat format with migration from v2.0→v4.0 and v3.0→v4.0
• All handler signatures, event emissions, and method params updated from singular to plural

Guided Tour

Layer 1: Data Model (packages/core)

Start here — these define the new shape of everything.

1. CyrusAgentSession.ts — repositoryIds: string[] added, issueId removed
2. config-types.ts — Handler callbacks: repository → repositories, repositoryId → repositoryIds
3. PersistenceManager.ts — New SerializableEdgeWorkerState (flat), v2→v4 and v3→v4 migration logic

Layer 2: Architecture (packages/edge-worker/src)

These are the structural changes that make multi-repo possible.

4. AgentSessionManager.ts — New ActivitySinkResolver type; constructor takes resolver callback instead of fixed sink; createLinearAgentSession/createChatSession accept repositoryIds
5. RepositoryRouter.ts — RepositoryRoutingResult.repositories (plural); selectRepositoriesFromResponse; cache removed
6. types.ts — EdgeWorkerEvents emit repositoryIds: string[]
7. prompt-assembly/types.ts — PromptAssemblyInput.repositories (was singular)

Layer 3: EdgeWorker (the big one)

8. EdgeWorker.ts — Single agentSessionManager created in constructor with resolver; resolveRepositories() helper; findSessionByIssueId() replaces cache lookups; all webhook handlers, serialization, and event emissions updated

Layer 4: Service Methods (mechanical wrapping)

9. PromptBuilder.ts — 6 methods: repository → repositories, extract [0]! internally
10. RunnerSelectionService.ts — buildAllowedTools/buildDisallowedTools: same pattern
11. ActivityPoster.ts — 6 methods: repositoryId → repositoryIds
12. GitService.ts — createGitWorktree: repository → repositories

Layer 5: Consumers

13. ChatSessionHandler.ts — Passes () => noopSink and [] for repositoryIds
14. WorkerService.ts (CLI) — Handler signatures and event log messages updated

Layer 6: Tests (17 files)

15. PersistenceManager.migration.test.ts — 9 tests covering v2→v4, v3→v4, v4 direct, error cases
16. RepositoryRouter.test.ts — Cache tests removed, assertions updated for plural
17. AgentSessionManager.*.test.ts (5 files) — Constructor and method signature updates
18. EdgeWorker.*.test.ts (11 files) — Singular manager mock, removed cache references, issueId → issueContext
19. GitService.test.ts — Array wrapping

Eliminated Patterns (grep-verified zero matches in src/)

• agentSessionManagers (old per-repo Map)
• getCachedRepository / getIssueRepositoryCache / restoreIssueRepositoryCache
• selectRepositoryFromResponse (singular)
• routingResult.repository (singular)
• session.issueId (deprecated field)

Test plan

• pnpm build — 15/15 packages clean
• pnpm typecheck — 15/15 packages clean
• pnpm --filter cyrus-core test:run — 44/44 tests pass
• pnpm --filter cyrus-edge-worker test:run — 536/536 test assertions pass (26 pre-existing EACCES uncaught exceptions from /tmp/test-cyrus-home/logs/ owned by agentops — identical on main)
• pnpm test:packages:run — all package test assertions pass (gemini-runner has same pre-existing EACCES issue)
• F1 test drive to validate end-to-end

🤖 Generated with Claude Code

[cursor]

You have run out of free Bugbot PR reviews for this billing cycle. This will reset on April 3.

To receive reviews on all of your PRs, visit the Cursor dashboard to activate Pro and start your 14-day free trial.

[Connoropolous]

Guided Tour

Read in this order. Each section builds on the previous.

---

Stop 1: The New Data Model

packages/core/src/CyrusAgentSession.ts

The single most important change. CyrusAgentSession gains:

repositoryIds: string[]  // 0 = standalone, 1 = standard, N = multi-repo

The deprecated issueId field is removed — use issueContext?.issueId instead.

packages/core/src/config-types.ts

Handler callbacks go plural:

• createWorkspace(issue, repository) → createWorkspace(issue, repositories)
• onSessionStart(id, issue, repositoryId) → onSessionStart(id, issue, repositoryIds)
• Same for onSessionEnd, onClaudeMessage

---

Stop 2: Persistence & Migration

packages/core/src/PersistenceManager.ts

Before (v2/v3): Sessions nested under repo ID keys:

agentSessions[repoId][sessionId] = session

After (v4): Flat — sessions carry their own repo association:

agentSessions[sessionId] = { ...session, repositoryIds: [repoId] }

Migration functions: migrateV2ToV4(), migrateV3ToV4(). The issueRepositoryCache field is dropped entirely.

packages/core/test/PersistenceManager.migration.test.ts

9 tests proving both migration paths and edge cases.

---

Stop 3: The Architecture Pivot

packages/edge-worker/src/AgentSessionManager.ts

New exported type:

export type ActivitySinkResolver = (repositoryIds: string[]) => IActivitySink;

Constructor takes this resolver instead of a fixed sink. Methods createLinearAgentSession and createChatSession now accept repositoryIds: string[].

packages/edge-worker/src/RepositoryRouter.ts

The routing result changes from:

{ type: "selected", repository: repo }      // old
{ type: "selected", repositories: [repo] }  // new

Deleted: issueRepositoryCache, getCachedRepository(), restoreIssueRepositoryCache(), getIssueRepositoryCache().
Renamed: selectRepositoryFromResponse → selectRepositoriesFromResponse.

packages/edge-worker/src/types.ts

All EdgeWorkerEvents now emit repositoryIds: string[] instead of repositoryId: string.

---

Stop 4: EdgeWorker.ts (the big diff)

packages/edge-worker/src/EdgeWorker.ts

Key structural changes:

1. Line ~168: agentSessionManagers: Map → agentSessionManager!: AgentSessionManager (singular)
2. Lines ~309-340: Single manager created in constructor with ActivitySinkResolver that looks up issue trackers dynamically
3. New helpers: resolveRepositories(repositoryIds) and findSessionByIssueId(issueId) replace cache lookups
4. Webhook handlers: Use findSessionByIssueId + resolveRepositories instead of getCachedRepository
5. Serialization: serializeMappings/restoreMappings use flat v4.0 format
6. All call sites: Singular repository wrapped in [repository] when calling refactored methods; repositoryId wrapped in [repositoryId] for ActivityPoster calls

---

Stop 5: Service Methods (mechanical changes)

These all follow the same pattern: parameter goes from singular to array, first element extracted with ! assertion, all existing logic unchanged.

• PromptBuilder.ts — 6 methods
• RunnerSelectionService.ts — 2 methods
• ActivityPoster.ts — 6 methods
• GitService.ts — 1 method

---

Stop 6: Consumers

• ChatSessionHandler.ts — Passes noop sink resolver and empty [] repositoryIds
• apps/cli/src/services/WorkerService.ts — Handler signatures and event log messages

---

Stop 7: Tests (17 files)

Migration tests — PersistenceManager.migration.test.ts (9 tests: v2→v4, v3→v4, direct v4, errors)

Router tests — RepositoryRouter.test.ts (cache tests removed, assertions for repositories[0])

ASM tests (5 files) — Constructor: mockSink → () => mockSink; method calls add [] repositoryIds

EdgeWorker tests (11 files) — Mocks updated from per-repo manager map to singular; removed getIssueRepositoryCache refs; session.issueId → session.issueContext

GitService test — createGitWorktree(issue, repo) → createGitWorktree(issue, [repo])

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: cd6fd8695e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".