DottaandPaperclip
0e0b63e5a5
## Thinking Path > - Paperclip manages AI agents and their work. > - AI Connections separate account access from models and harnesses. > - A pool must act as one connection while retaining each task’s account. > - Core must enforce member access and preserve session and recovery rules. > - A plugin supplies rotation policy without receiving credentials. > - This change adds durable routing and native connector setup and management. ## Linked Issues or Issue Description **Subsystem affected** AI Connections, Connectors, plugins, run dispatch, and session compatibility. **Problem or motivation** Operators need to rotate new tasks across saved accounts while each task keeps its account and session. Pool setup must fit the existing connector catalog and account workflow. **Proposed solution** Add an experimental router binding, a capability-gated plugin hook, and transactional task pins. Plugins declare native pooled connectors through `aiConnectionRouter`. Core hosts the existing-account picker, ordering step, and account settings. Related usage contract: #14936. Companion private plugin: https://github.com/paperclipai/paperclip-cloud/pull/643. **Roadmap alignment** This extends Apps and AI Connections. Core supplies generic enforcement and native connector UI; the private plugin owns rotation and quota policy. The prior duplicate search found no matching router implementation. ## What Changed - Add a router binding without changing existing concrete bindings. Keep the instance flag and new pools disabled by default. Require manual operator configuration. Show no routing toggle in Experimental settings on either open-source or Cloud installs, even after routing is enabled. - Persist company-scoped pools, one shared cursor per pool, and pins keyed by company, pool, agent, and task. Commit pins and cursor advances together with revision checks and bounded retries. Persist run-ID affinity before allocation. - Pass only authorized metadata and normalized usage to plugins. Core retains credential handling, member access checks, runtime qualification, and recovery evidence. Probe outside locks with a shared 15-second budget and freshness cache. - Resolve routing before credential preparation and backend selection. Preserve pins through turns, session resets, removed members, and quota waits. Retain admitted recovery after disable or uninstall. - Separate credential session epochs from token generations. Verified refresh preserves the epoch; reconnect and manual replacement change it. Include the credential slot ID in session and usage-cache identity, so reconnecting an indexed legacy account invalidates its old session even when both epochs are zero. - Validate pool member installations before accepting saved-agent bindings and recheck compatibility when the harness changes. Install only authorized members in the new-agent transaction and record their IDs in local activity. Pool membership cannot install a restricted shared connection. - Preserve pool bindings when agents hire teammates through either creation API or native caller runtime inheritance. Block stale manager credential references; retain explicit child authentication precedence and reject incompatible inherited pools. - Add native connector registration through plugin metadata. Reuse the Connectors catalog, setup header, account header, sidebar, dialogs, and usage display. Setup selects and orders saved connections. Advanced settings hold usage rules and member runtime defaults. New-account setup opens in another tab. - Use revision-checked pool archival from the Connectors catalog and account page. Keep task pins, cursors, recovery evidence, and underlying connections. Reject ordinary connection updates or removals that bypass pool revisions. - Add pool selectors, composer models, override notes, quota status, run details, activity records, and local run-log records. Keep session-adoption copy minimal. - Show **Used by** below the pool connections. List current company agents with shared avatars and profile links. Include paused agents; exclude terminated agents and agents using another pool. - Add Core stories for the generic connector workflow and runtime surfaces. Cloud stories reuse these production routes and tokens through a preview-only alias. ## Verification - Final head `73cb953bca30ed83e4505dd820edd9b5edffd28b`: full workspace `pnpm -r typecheck`, `pnpm build`, and `pnpm check:token-gates` pass locally. - All 422 focused connector/settings/shared-contract/migration tests and all 156 database-backed AI connection, hiring, reconnect, and durable-routing cases pass (69 hiring cases rerun after the final auth-precedence fix). The merged shared contract retains connection instructions and pool metadata. The pool migration is generated at sequence 0299 after the latest upstream migrations; this PR makes no lockfile changes. - All four full-app Playwright tests pass on the final head after a cold restart and migration, against the installed private plugin and isolated database, with no route or pool-API mocks. They cover hidden routing controls after manual opt-in, native pool creation, ordering, membership edits, rename, paused defaults, enabling/save/refresh persistence, stale edits, cancellation/removal, preserved underlying accounts, unavailable routers, and Used by avatars and profile links. Exact command: `PAPERCLIP_CONNECTION_POOL_E2E=1 AI_CONNECTIONS_TEST_COMPANY_ID=a37b9625-5ecf-4e29-8081-04df3d6e7d6f AI_CONNECTIONS_TEST_URL=http://127.0.0.1:3108 pnpm exec playwright test --config tests/ai-connections-app/playwright.config.ts connection-pools.spec.ts`. - [Native setup, ordering, and management screenshots](https://github.com/paperclipai/paperclip/pull/14967#issuecomment-6006976278) address the review follow-up. [Earlier selector, quota, and run-detail screenshots](https://github.com/paperclipai/paperclip/pull/14967#issuecomment-5971537316) show the runtime surfaces. Core previews: `pnpm --filter @paperclipai/ui storybook`, then **Connectors / Pool host** or **AI Connections / Connection pools**. Cloud owns its host-backed plugin stories; both repositories’ Operator Setup Required story assertions pass. - Live acceptance used OpenAI/Codex and Anthropic/Claude ACPX, resumed both exact sessions after restart, preserved pinned accounts through explicit reset and controlled quota deferral/recovery, and committed only two allocations across fourteen runs. A later UI-created task test again rotated OpenAI then Anthropic and resumed OpenAI through follow-up/restart/quota recovery. That later Anthropic execution was blocked by its saved OAuth token expiring (provider 401). No live usage probes ran. - The full local `pnpm test:run` was attempted earlier and did not complete because of macOS embedded PostgreSQL bootstrap/shared-memory failures and the 40,000-file Git fixture timeout. The focused database suites above now pass; full-suite verification is provided by the split CI lanes. The preceding CI run had one runtime readiness timeout; it passes locally both alone and inside the larger runtime suite. That larger local suite also encountered an embedded PostgreSQL setup failure and two macOS temporary-path alias assertions; those two assertions pass with canonical TMPDIR=/private/tmp. All final-head CI checks are terminal green, including full general/serialized server suites, Runner checks, browser E2E shards, canary verification, build, and typecheck. Greptile is 5/5 on that exact head with no unresolved threads. ## Risks - The migration adds routing tables and a credential epoch column. Install the private plugin only with the compatible Core contract. - Routing and each pool require opt-in. Production distribution and fleet defaults remain unchanged. - Unknown usage stays eligible. Known pinned exhaustion waits; revoked access requires operator repair. - Legacy adapters require compatible members. Runner model and effort overrides remain limited by qualified backend support. ## Model Used OpenAI GPT-6 through Codex, with reasoning, repository editing, code execution, and browser testing. The exact deployment model ID and context window are not exposed in this session. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes:` / `Closes:` / `Refs:` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links - [x] My branch name describes the change and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass (targeted suites; full-suite limitations are reported above) - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
8.3 KiB
Experimental AI connection routers
AI routers are virtual, company-scoped connections owned by a capability-gated
plugin (ai.connections.route). The instance flag enableAiConnectionRouters
defaults to false. Pools also default to disabled. The host must implement this
contract; the plugin's minimum version alone does not establish compatibility.
Routing has no visible enable control in Experimental settings on either
self-hosted or Cloud instances, even after an operator enables it. Self-hosted
operators can set enableAiConnectionRouters through the instance-admin
PATCH /api/instance/settings/experimental API. Cloud operators use the existing
fleet or per-stack managed feature configuration. Installing a plugin does not
enable routing; enabling routing does not enable individual pools.
The host authorizes members using the ordinary company, user, sharing, install,
health and harness checks. Saving a binding or changing its harness requires
at least one usable member for that agent. New-agent creation installs only
members authorized by the ordinary personal-owner or shared-install policy,
in the same transaction as the agent. Pool membership cannot install a
restricted shared connection. It sends authorized metadata and sanitized usage
observations to onRouteAiConnection. The plugin proposes an opaque member ID;
it cannot receive credentials or expand authorization. Pure round robin does
not probe usage. Usage-aware selection has a shared 15-second probe budget,
60-second freshness cache and ordinary grant/secret freshness invalidation.
Concurrent starts share an in-flight probe for the same grant and credential
freshness. Each caller retains its selection deadline.
One cursor spans all agents in a pool. An allocation transaction locks the
cursor, checks config and cursor revisions, rechecks authorization, and writes
the task pin and cursor advance together. Pins use company, pool, agent and the
existing task key (including __heartbeat__). Wakes without a task key retain
the original run ID as an affinity key in retry context. Conflicts retry at most
20 times; contention beyond that returns an actionable conflict.
Pins snapshot the concrete binding and member profile. Removing or editing a member affects future allocations. Composer changes can change a supported model or effort, with a note on fallback, but never the account or harness. Session reset and compaction retain the pin. Revocation requires operator repair. Authentication repair uses the failed run’s durable concrete allocation and current member permissions; reconnect-and-continue preserves the agent’s pool binding. Changing the agent’s pool invalidates the old repair card. A pre-existing managed session can adopt its saved account when it is an eligible member; otherwise the operator must explicitly reset the session.
Credential ai_session_epoch changes on reconnect or manual rotation. Only
verified runtime refresh write-back preserves it. Session fingerprints use the
secret ID and epoch while authentication failure attribution still uses the
token generation. A reconnect that replaces an indexed legacy secret changes
the session identity even when both secret epochs are zero.
Adopting a valid account preserves a session only when the complete effective
configuration matches a prior fingerprint. Core can bridge binding-only agent
revisions (up to 20) and unchanged legacy token identities at epoch zero. Changes
to other settings, explicit resets, and credential replacement retain their
existing reset behavior; no fingerprint category is exempted.
Native recovery retains concrete routing evidence and can finish after the
router flag or plugin is disabled or uninstalled; it revalidates underlying
account access and never makes a new allocation.
The private Cloud plugin owns round-robin and quota policy. Its manifest declares
aiConnectionRouter: { name, description } alongside ai.connections.route.
Core adds that connector to the regular catalog and hosts its setup and account
management using authenticated, company-scoped pool APIs. No separate plugin
page or sidebar entry is needed. New allocations over
the chosen threshold wait; known exhaustion defers pinned turns. The deferred
run schedules ai_connection_pool_wait without spending the failure retry
budget, and the UI labels that retry as Pool exhausted.
Operators choose Connectors → AI connection pool → Add connection pool, select existing accounts, arrange their order, and create a paused connection. The normal account page supports rename, member changes, enabling, and removal. Used by lists the company’s non-terminated agents configured to use the pool, with their avatars and links to their profiles. Paused agents remain listed. Optional usage and runtime defaults live under Advanced. Creating another account opens the normal catalog in a new tab so the pool draft stays intact. The catalog marks experimental-disabled or unavailable plugins as unavailable.
Deletion uses
DELETE /api/companies/:companyId/ai-connection-pools/:poolId with the current
expectedRevision. Core disables and archives the virtual connection, retaining
its task pins, cursor and run records. It rejects stale edits and new allocations;
already admitted runs keep their concrete recovery evidence. Cleanup remains
available when experimental routing or the plugin is disabled. The catalog captures the reviewed pool revision before showing its removal
confirmation and uses the pool endpoint. Ordinary connection update and removal
endpoints reject pools so they cannot bypass configuration revisions. Non-managers
see the permission requirement without making a denied management request.
Configuration and committed selection are recorded in activity records. Runs record the selected member/profile and override notes in the local run log and recovery context. These records stay in the instance database.
Tests: cd server && pnpm exec vitest run src/__tests__/ai-connection-router.test.ts
plus the existing AI connection, retry accounting, run-dispatch and UI suites.
UI review in Storybook
Run pnpm --filter @paperclipai/ui storybook from Core, then open
AI Connections / Connection pools. The 16 stories use production components
for pool selection, legacy-session adoption, unavailable/read-only selections,
mixed-provider composer models and effort, mobile composer settings, usage waits,
run selections and override notes, and scheduled retries.
AllCoreSurfaces provides an overview; individual stories expose the expanded
menus and adoption dialog. Run pnpm --filter @paperclipai/ui build-storybook
to build the preview.
Pool configuration stories belong to the private Cloud plugin's own Storybook
in extensions/plugin-connection-pool/storybook/. Both previews use fictional
accounts; they do not call live providers or mutate a Paperclip instance.
Core also owns Connectors / Pool host stories for the generic native
extension. The overview links to Cloud's In Connectors preview on port 6010;
its stories mount these same production routes, header, sidebar and tokens.
Full Setup And Management exercises the complete catalog-to-pool journey.
Both previews include Operator Setup Required for a manually disabled host.
Full-app browser acceptance
Install the compatible plugin into an isolated, loopback local_trusted instance,
enable the experimental flag, and use a company named for an E2E or test drive
with two saved, authorized AI accounts. Run:
PAPERCLIP_CONNECTION_POOL_E2E=1 \
AI_CONNECTIONS_TEST_URL=http://127.0.0.1:3100 \
AI_CONNECTIONS_TEST_COMPANY_ID=<test-company-id> \
pnpm exec playwright test --config tests/ai-connections-app/playwright.config.ts connection-pools.spec.ts
These opt-in tests exercise the shipped app, installed plugin and database without mocking browser routes or pool APIs. They cover catalog navigation, setup, ordering, paused defaults, rename, member changes, refresh persistence, stale edits and removal. They verify that an operator-enabled host still offers no Experimental control for routing. With a test agent already bound to a saved pool, they also verify the Used by list, avatars and profile links. Cleanup archives only the test's own pool and verifies that existing accounts and pools remain intact. This suite does not execute agents or probe live usage; provider and restart acceptance remain separate gated test drives.