feat(core): add multi-account pool with automatic rate-limit failover

packages/api/src/api/contracts.ts

@@ -282,6 +282,32 @@ export type FederationInboxResult =
  readonly subscription: FollowSubscription
  }
 
+// CHANGE: add account pool API types for multi-account management
+// WHY: expose account pool CRUD and status via the API
+// QUOTE(ТЗ): "Сделать возможность регистрировать много аккаунтов"
+// REF: issue-213
+// PURITY: CORE
+// COMPLEXITY: O(1)
+export type AccountPoolProvider = "claude" | "codex" | "gemini"
+
+export type AddAccountRequest = {
+ readonly provider: AccountPoolProvider
+ readonly label: string
+}
+
+export type RemoveAccountRequest = {
+ readonly provider: AccountPoolProvider
+ readonly label: string
+}
+
+export type AccountPoolSummary = {
+ readonly provider: AccountPoolProvider
+ readonly total: number
+ readonly available: number
+ readonly coolingDown: number
+ readonly activeLabel: string | undefined
+}
+
 export type ApiEventType =
  | "snapshot"
  | "project.created"

packages/api/src/api/schema.ts

@@ -98,6 +98,26 @@ export const CreateAgentRequestSchema = Schema.Struct({
  label: OptionalString
 })
 
+// CHANGE: add account pool request schemas
+// WHY: validate API requests for multi-account pool management
+// REF: issue-213
+// PURITY: CORE
+// COMPLEXITY: O(1)
+export const AccountPoolProviderSchema = Schema.Literal("claude", "codex", "gemini")
+
+export const AddAccountRequestSchema = Schema.Struct({
+ provider: AccountPoolProviderSchema,
+ label: Schema.String
+})
+
+export const RemoveAccountRequestSchema = Schema.Struct({
+ provider: AccountPoolProviderSchema,
+ label: Schema.String
+})
+
+export type AddAccountRequestInput = Schema.Schema.Type<typeof AddAccountRequestSchema>
+export type RemoveAccountRequestInput = Schema.Schema.Type<typeof RemoveAccountRequestSchema>
+
 export const CreateFollowRequestSchema = Schema.Struct({
  actor: OptionalString,
  object: Schema.String,

packages/api/src/http.ts

@@ -12,6 +12,7 @@ import { renderError, type AppError } from "@effect-template/lib/usecases/errors
 
 import { ApiAuthRequiredError, ApiBadRequestError, ApiConflictError, ApiInternalError, ApiNotFoundError, describeUnknown } from "./api/errors.js"
 import {
+ AddAccountRequestSchema,
  ApplyAllRequestSchema,
  CodexAuthImportRequestSchema,
  CodexAuthLoginRequestSchema,
@@ -21,6 +22,7 @@ import {
  CreateProjectRequestSchema,
  GithubAuthLoginRequestSchema,
  GithubAuthLogoutRequestSchema,
+ RemoveAccountRequestSchema,
  StateCommitRequestSchema,
  StateInitRequestSchema,
  StateSyncRequestSchema,
@@ -36,6 +38,15 @@ import {
  readGithubAuthStatus
 } from "./services/auth.js"
 import { streamCodexAuthLogin } from "./services/auth-codex-login-stream.js"
+import {
+ addPoolAccount,
+ clearAccountCooldown,
+ getPoolSummary,
+ listAllPoolAccounts,
+ listPoolAccounts,
+ removePoolAccount,
+ selectNextPoolAccount
+} from "./services/account-pool.js"
 import { getAgent, getAgentAttachInfo, listAgents, readAgentLogs, startAgent, stopAgent } from "./services/agents.js"
 import { latestProjectCursor, listProjectEventsSince } from "./services/events.js"
 import {
@@ -415,7 +426,63 @@ export const makeRouter = () => {
  )
  )
 
- const withState = base.pipe(
+ const withAccountPool = base.pipe(
+ HttpRouter.get(
+ "/account-pool",
+ Effect.sync(() => ({ accounts: listAllPoolAccounts() })).pipe(
+ Effect.flatMap((payload) => jsonResponse(payload, 200)),
+ Effect.catchAll(errorResponse)
+ )
+ ),
+ HttpRouter.get(
+ "/account-pool/:provider",
+ HttpRouter.schemaParams(Schema.Struct({ provider: Schema.Literal("claude", "codex", "gemini") })).pipe(
+ Effect.flatMap(({ provider }) =>
+ jsonResponse({
+ accounts: listPoolAccounts(provider),
+ summary: getPoolSummary(provider)
+ }, 200)
+ ),
+ Effect.catchAll(errorResponse)
+ )
+ ),
+ HttpRouter.post(
+ "/account-pool/add",
+ Effect.gen(function*(_) {
+ const request = yield* _(HttpServerRequest.schemaBodyJson(AddAccountRequestSchema))
+ const state = addPoolAccount(request.provider, request.label)
+ return yield* _(jsonResponse({ ok: true, state }, 201))
+ }).pipe(Effect.catchAll(errorResponse))
+ ),
+ HttpRouter.post(
+ "/account-pool/remove",
+ Effect.gen(function*(_) {
+ const request = yield* _(HttpServerRequest.schemaBodyJson(RemoveAccountRequestSchema))
+ const state = removePoolAccount(request.provider, request.label)
+ return yield* _(jsonResponse({ ok: true, state }, 200))
+ }).pipe(Effect.catchAll(errorResponse))
+ ),
+ HttpRouter.post(
+ "/account-pool/next",
+ Effect.gen(function*(_) {
+ const request = yield* _(HttpServerRequest.schemaBodyJson(
+ Schema.Struct({ provider: Schema.Literal("claude", "codex", "gemini") })
+ ))
+ const account = selectNextPoolAccount(request.provider)
+ return yield* _(jsonResponse({ account: account ?? null }, 200))
+ }).pipe(Effect.catchAll(errorResponse))
+ ),
+ HttpRouter.post(
+ "/account-pool/clear-cooldown",
+ Effect.gen(function*(_) {
+ const request = yield* _(HttpServerRequest.schemaBodyJson(RemoveAccountRequestSchema))
+ const state = clearAccountCooldown(request.provider, request.label)
+ return yield* _(jsonResponse({ ok: true, state }, 200))
+ }).pipe(Effect.catchAll(errorResponse))
+ )
+ )
+
+ const withState = withAccountPool.pipe(
  HttpRouter.get(
  "/state/path",
  readStatePathOutput().pipe(

packages/api/src/program.ts

@@ -4,6 +4,7 @@ import { Console, Effect, Layer, Option } from "effect"
 import { createServer } from "node:http"
 
 import { makeRouter } from "./http.js"
+import { initializeAccountPool } from "./services/account-pool.js"
 import { initializeAgentState } from "./services/agents.js"
 import { startOutboxPolling } from "./services/federation.js"
 
@@ -49,6 +50,11 @@ export const program = (() => {
  return Effect.scoped(
  Console.log(`docker-git api boot port=${port}`).pipe(
  Effect.zipRight(initializeAgentState()),
+ Effect.zipRight(
+ Effect.tryPromise({ try: () => initializeAccountPool(), catch: () => new Error("account pool init failed") }).pipe(
+ Effect.catchAll(() => Effect.void)
+ )
+ ),
  Effect.zipRight(
  Console.log(`docker-git outbox polling interval=${pollingInterval}ms`)
  ),

packages/api/src/services/account-pool.ts

@@ -0,0 +1,162 @@
+// CHANGE: add API-level account pool service with persistence and rate-limit monitoring
+// WHY: enable automatic switching between registered accounts when one hits API rate limits
+// QUOTE(ТЗ): "Сделать возможность регистрировать много аккаунтов codex, claude code и когда на одном лимиты закаончиваются он переходит на другой аккаунт"
+// REF: issue-213
+// SOURCE: n/a
+// FORMAT THEOREM: ∀op ∈ PoolOperation: op(state) → persist(nextState) ∧ consistent(nextState)
+// PURITY: SHELL
+// EFFECT: Effect<Result, ApiError>
+// INVARIANT: pool state is persisted to disk after every mutation; in-memory state is source of truth
+// COMPLEXITY: O(n) per operation where n = total accounts
+
+import { defaultProjectsRoot } from "@effect-template/lib/usecases/path-helpers"
+import type {
+ AccountPoolProvider,
+ AccountPoolState,
+ AccountEntry,
+ RateLimitEvent
+} from "@effect-template/lib/core/account-pool-domain"
+import {
+ addAccount,
+ removeAccount,
+ markRateLimited,
+ clearCooldown,
+ selectNextAvailable,
+ advanceActiveIndex,
+ listAccounts,
+ listAllAccounts,
+ poolSummary,
+ emptyPoolState
+} from "@effect-template/lib/usecases/account-pool"
+import { detectRateLimit } from "@effect-template/lib/usecases/rate-limit-detector"
+import { promises as fs } from "node:fs"
+import { join } from "node:path"
+
+let poolState: AccountPoolState = emptyPoolState(new Date().toISOString())
+let initialized = false
+
+const nowIso = (): string => new Date().toISOString()
+
+const stateFilePath = (): string =>
+ join(defaultProjectsRoot(process.cwd()), ".orch", "state", "account-pool.json")
+
+const persistState = async (): Promise<void> => {
+ const filePath = stateFilePath()
+ await fs.mkdir(join(filePath, ".."), { recursive: true })
+ await fs.writeFile(filePath, JSON.stringify(poolState, null, 2), "utf8")
+}
+
+const persistBestEffort = (): void => {
+ void persistState().catch(() => {
+ // best effort
+ })
+}
+
+export const initializeAccountPool = async (): Promise<void> => {
+ if (initialized) {
+ return
+ }
+
+ const filePath = stateFilePath()
+ const exists = await fs.stat(filePath).then(() => true).catch(() => false)
+ if (exists) {
+ const raw = await fs.readFile(filePath, "utf8")
+ const parsed = JSON.parse(raw) as AccountPoolState
+ poolState = {
+ pools: parsed.pools ?? [],
+ updatedAt: parsed.updatedAt ?? nowIso()
+ }
+ }
+
+ initialized = true
+}
+
+export const addPoolAccount = (
+ provider: AccountPoolProvider,
+ label: string
+): AccountPoolState => {
+ const now = nowIso()
+ poolState = addAccount(poolState, provider, label, now)
+ persistBestEffort()
+ return poolState
+}
+
+export const removePoolAccount = (
+ provider: AccountPoolProvider,
+ label: string
+): AccountPoolState => {
+ const now = nowIso()
+ poolState = removeAccount(poolState, provider, label, now)
+ persistBestEffort()
+ return poolState
+}
+
+export const markAccountRateLimited = (
+ event: RateLimitEvent
+): AccountPoolState => {
+ const now = nowIso()
+ poolState = markRateLimited(poolState, event, now)
+ persistBestEffort()
+ return poolState
+}
+
+export const clearAccountCooldown = (
+ provider: AccountPoolProvider,
+ label: string
+): AccountPoolState => {
+ const now = nowIso()
+ poolState = clearCooldown(poolState, provider, label, now)
+ persistBestEffort()
+ return poolState
+}
+
+export const selectNextPoolAccount = (
+ provider: AccountPoolProvider
+): AccountEntry | undefined => {
+ const now = nowIso()
+ const account = selectNextAvailable(poolState, provider, now)
+ if (account !== undefined) {
+ poolState = advanceActiveIndex(poolState, provider, now)
+ persistBestEffort()
+ }
+ return account
+}
+
+export const listPoolAccounts = (
+ provider: AccountPoolProvider
+): ReadonlyArray<AccountEntry> =>
+ listAccounts(poolState, provider)
+
+export const listAllPoolAccounts = (): ReadonlyArray<AccountEntry> =>
+ listAllAccounts(poolState)
+
+export const getPoolSummary = (
+ provider: AccountPoolProvider
+): {
+ readonly total: number
+ readonly available: number
+ readonly coolingDown: number
+ readonly activeLabel: string | undefined
+} => poolSummary(poolState, provider, nowIso())
+
+export const getPoolState = (): AccountPoolState => poolState
+
+/**
+ * Check an agent output line for rate-limit signals.
+ * If a rate-limit is detected, marks the account as rate-limited
+ * and returns the event for the caller to act upon.
+ *
+ * @effect mutates poolState on detection
+ */
+export const checkLineForRateLimit = (
+ provider: AccountPoolProvider,
+ label: string,
+ line: string
+): RateLimitEvent | undefined => {
+ const now = nowIso()
+ const event = detectRateLimit(provider, label, line, now)
+ if (event !== undefined) {
+ markAccountRateLimited(event)
+ }
+ return event
+}