mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-27 02:44:50 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Agents need source control access for repository work > - A shared token cannot preserve the responsible person's identity or an agent's dedicated identity > - GitHub App tokens also need durable refresh, repository access checks, and webhook delivery > - Paperclip already has managed connections, encrypted grants, run secret leases, and merge-confirmation behavior > - This pull request extends those systems with GitHub identities instead of adding a parallel credential system > - The benefit is durable GitHub access with explicit identity, repository, runtime, and webhook boundaries ## Linked Issues or Issue Description No public GitHub issue describes this connection change. This description follows the feature request template. **Subsystem affected** Connected Apps, connection grants, secret resolution, native Git runtime setup, webhook processing, and the Apps UI. **Problem or motivation** Users need to connect GitHub once and let agents use the correct GitHub identity. A run should use a dedicated agent account when one exists. Otherwise, it should use the responsible person's account. The connection must survive token expiry, repository access changes, and temporary instance downtime. **Proposed solution** Add user-owned and agent-owned GitHub grants to the existing connection model. Resolve one identity for MCP, Git, `gh`, health checks, and webhook bindings. Store provider tokens in the existing encrypted secret system. Refresh expiring token pairs under the existing lease and compare-and-swap path. Register signed Cloud webhook bindings and process normalized pull request and installation events through a durable local inbox. **Alternatives considered** An organization-wide GitHub token would lose person and agent attribution. Environment variables alone would bypass the managed connection and grant model. A new GitHub-only credential store would duplicate the existing secret and access systems. GitHub App installation tokens and private-key custody remain outside this first version. **Roadmap alignment** This change implements the Connected Apps direction. It also extends the shipped MCP Tool Gateway, per-agent secret access, and action-attribution systems. It does not add a repository catalog. The open repository catalog work in [#11234](https://github.com/paperclipai/paperclip/pull/11234) is related and complementary. ## What Changed - Added agent-owned connection grants and a per-agent credential policy with company and subject constraints. - Added a managed GitHub App method while keeping the personal access token method as an advanced fallback. - Added durable access-token and refresh-token handling with proactive rotation and one automatic recovery after a provider `401`. - Added GitHub identity and installation summaries without storing repository-name lists. - Added signed Cloud webhook binding, event lease, acknowledgement, local idempotency, pull request merge processing, and installation access handling. - Added one identity resolver for MCP, native Git, `gh`, checkout, health checks, and webhook bindings. - Added a class-3 run projection for `GH_TOKEN`, `GITHUB_TOKEN`, a `github.com`-only credential helper, SSH-to-HTTPS rewrite, and GitHub noreply commit attribution. - Added personal and dedicated-agent setup choices plus identity, repository, continuity, and webhook status in the Apps UI. - Added schema migrations, tests, and connection documentation. ## Verification - The current head is fully green in GitHub CI, including build, typecheck, all serialized/general server shards, all browser shards, policy, canary dry run, review, and security checks. - Live staging proof completed with a non-expiring GitHub App user token, selected-repository installation, repository add/remove refresh, managed MCP, native `gh`, HTTPS clone/push/delete, GitHub noreply commit attribution, signed merged-PR webhook acceptance, durable Cloud-to-instance delivery, and installation-access event processing. Temporary branches and temporary repository access were removed afterward. - `pnpm check:token-gates` passed. - `pnpm -r typecheck` passed before and after the rebase onto `origin/master`. - `pnpm build` passed. - The focused connector suite passed 285 tests after the rebase. - The full stable suite passed 5,790 tests and failed 22 tests across 8 general server files. The failures reproduced as shared-runner environment issues. They included `/tmp` versus `/private/tmp`, closed database connections, and invalid high ephemeral ports. The focused connection tests pass in isolation. ## Risks - Migrations add agent grant subjects and a durable connection-event inbox. Migration numbering and safety checks pass. - A raw GitHub user token enters the agent process for Git and `gh`. Per-tool Ask-first controls cannot limit those shell operations. The UI warns users about this boundary. - GitHub App user tokens can be non-expiring. Paperclip performs a continuity check every 30 days, but provider revocation still requires a reconnect. - The webhook path accepts only signed and bounded payloads. It stores a minimal normalized record and no raw provider payload. - GitHub repository permissions remain authoritative. Removed access can make a cached repository count temporarily stale, but runtime access fails immediately. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used OpenAI Codex, `gpt-5.6-sol`, extended reasoning, tool use, code execution, browser control, and multi-file repository editing. The context window size was not provided. ## 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 (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [ ] I have run tests locally and they pass - [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>
217 lines
9.0 KiB
TypeScript
217 lines
9.0 KiB
TypeScript
export { companyService } from "./companies.js";
|
|
export { companyArtifactsService } from "./company-artifacts.js";
|
|
export { companySearchService } from "./company-search.js";
|
|
export { companySearchExtractService } from "./company-search-extract.js";
|
|
export { feedbackService } from "./feedback.js";
|
|
export { companySkillService } from "./company-skills.js";
|
|
export { companySkillPolicyService, normalizeSkillPolicySourceType } from "./company-skill-policy.js";
|
|
export { folderService } from "./folders.js";
|
|
export { agentService, deduplicateAgentName } from "./agents.js";
|
|
export {
|
|
builtInAgentService,
|
|
deriveBuiltInAgentStatus,
|
|
getBuiltInAgentDefinition,
|
|
listBuiltInAgentDefinitions,
|
|
reconcileBuiltInAgentsOnStartup,
|
|
validateBuiltInAgentDefinitions,
|
|
type BuiltInAgentDefinition,
|
|
type BuiltInManagedResourceState,
|
|
type BuiltInManagedResourceStockStatus,
|
|
type BuiltInAgentState,
|
|
type BuiltInAgentStatus,
|
|
} from "./built-in-agents.js";
|
|
export { agentInstructionsService, syncInstructionsBundleConfigFromFilePath } from "./agent-instructions.js";
|
|
export { assetService } from "./assets.js";
|
|
export { documentService, extractLegacyPlanBody } from "./documents.js";
|
|
export { artifactReviewDocumentService } from "./artifact-review-documents.js";
|
|
export { statusCardService } from "./status-cards.js";
|
|
export { finalizeStatusCardsForStalledGeneration } from "./status-card-finalization.js";
|
|
export { documentAnnotationService } from "./document-annotations.js";
|
|
export {
|
|
ISSUE_CONTINUATION_SUMMARY_DOCUMENT_KEY,
|
|
buildContinuationSummaryMarkdown,
|
|
getIssueContinuationSummaryDocument,
|
|
refreshIssueContinuationSummary,
|
|
} from "./issue-continuation-summary.js";
|
|
export { projectService } from "./projects.js";
|
|
export {
|
|
clampIssueListLimit,
|
|
ISSUE_LIST_DEFAULT_LIMIT,
|
|
ISSUE_LIST_MAX_LIMIT,
|
|
issueService,
|
|
type IssueFilters,
|
|
} from "./issues.js";
|
|
export { issueThreadInteractionService } from "./issue-thread-interactions.js";
|
|
export { githubConnectionEventService, type GitHubConnectionEventPollResult } from "./github-connection-events.js";
|
|
export {
|
|
assertIssueReviewVerdictActorAllowed,
|
|
type IssueReviewVerdictActor,
|
|
} from "./issue-review-policy.js";
|
|
export { issueTreeControlService } from "./issue-tree-control.js";
|
|
export { issueApprovalService } from "./issue-approvals.js";
|
|
export { issueReferenceService } from "./issue-references.js";
|
|
export { issueRecoveryActionService } from "./issue-recovery-actions.js";
|
|
export {
|
|
stalledReviewDecisionService,
|
|
type DecideStalledReviewInput,
|
|
type StalledReviewDecisionActor,
|
|
} from "./stalled-review-decisions.js";
|
|
export { taskWatchdogService } from "./task-watchdogs.js";
|
|
export {
|
|
issueIsInTaskWatchdogSubtree,
|
|
resolveTaskWatchdogMutationScope,
|
|
taskWatchdogScopeAllowsIssueMutation,
|
|
} from "./task-watchdog-scope.js";
|
|
export {
|
|
createExternalObjectDetectorRegistry,
|
|
createExternalObjectResolverRegistry,
|
|
externalObjectService,
|
|
type ExternalObjectDetector,
|
|
type ExternalObjectResolver,
|
|
type ExternalObjectResolveResult,
|
|
type ExternalObjectResolverSnapshot,
|
|
} from "./external-objects.js";
|
|
export { goalService } from "./goals.js";
|
|
export { activityService, type ActivityFilters } from "./activity.js";
|
|
export { workTimelineService, normalizeTimelineWindow } from "./work-timeline.js";
|
|
export { attentionService } from "./attention.js";
|
|
export { captureDecisionSnapshot, decisionTrainingService } from "./decision-training.js";
|
|
export { decisionService } from "./decisions.js";
|
|
export { decisionRetentionService } from "./decision-retention.js";
|
|
export type {
|
|
WorkTimelineActor,
|
|
WorkTimelineEdge,
|
|
WorkTimelineEvent,
|
|
WorkTimelineQuery,
|
|
WorkTimelineResult,
|
|
WorkTimelineSpan,
|
|
} from "./work-timeline.js";
|
|
export { approvalService } from "./approvals.js";
|
|
export { budgetService } from "./budgets.js";
|
|
export { secretService } from "./secrets.js";
|
|
export { createRunSecretRedactionRegistry } from "./run-secret-redaction.js";
|
|
export { createSecretProposalsService } from "./secret-proposals.js";
|
|
export { googleSheetsRobotEmailFromEnv, toolAccessService } from "./tool-access.js";
|
|
export {
|
|
createVercelConnectClient,
|
|
vercelConnectIntegrationStatus,
|
|
VercelConnectClientError,
|
|
type VercelConnectClient,
|
|
} from "./vercel-connect.js";
|
|
export { createComposioClient, ComposioApiError, type ComposioClient } from "./composio.js";
|
|
export { smokeLabService } from "./smoke-lab.js";
|
|
export { backfillLegacyToolOAuthTokens } from "./tool-oauth-legacy-backfill.js";
|
|
export { toolAccessPolicyService } from "./tool-access-policy.js";
|
|
export { routineService } from "./routines.js";
|
|
export { costService } from "./costs.js";
|
|
export { financeService } from "./finance.js";
|
|
export { heartbeatService, resolveHeartbeatSchedulingSuppression } from "./heartbeat.js";
|
|
export {
|
|
productivityReviewService,
|
|
PRODUCTIVITY_REVIEW_ORIGIN_KIND,
|
|
} from "./productivity-review.js";
|
|
export { classifyIssueGraphLiveness, type IssueLivenessFinding } from "./recovery/index.js";
|
|
export { dashboardService } from "./dashboard.js";
|
|
export { sidebarBadgeService } from "./sidebar-badges.js";
|
|
export { sidebarPreferenceService } from "./sidebar-preferences.js";
|
|
export { resourceMembershipService, type ResourceMembershipPolicyHook } from "./resource-memberships.js";
|
|
export { inboxDismissalService } from "./inbox-dismissals.js";
|
|
export { accessService } from "./access.js";
|
|
export {
|
|
backfillPrincipalAccessCompatibility,
|
|
ensureHumanRoleDefaultGrants,
|
|
insertMissingPrincipalGrants,
|
|
type PrincipalAccessCompatibilityBackfillStats,
|
|
} from "./principal-access-compatibility.js";
|
|
export { authorizationService } from "./authorization.js";
|
|
export { inboxAgentPolicyService } from "./inbox-agent-policy.js";
|
|
export type {
|
|
AuthorizationAction,
|
|
AuthorizationActor,
|
|
AuthorizationDecision,
|
|
AuthorizationResource,
|
|
} from "./authorization.js";
|
|
export { boardAuthService } from "./board-auth.js";
|
|
export { instanceSettingsService, applyManagedExperimentalOverlay } from "./instance-settings.js";
|
|
export {
|
|
getManagedInstanceConfig,
|
|
managedFeatureKeySet,
|
|
parseManagedConfigEnv,
|
|
MANAGED_CONFIG_ENV_KEY,
|
|
type ManagedEnvironmentSpec,
|
|
type ManagedInstanceConfig,
|
|
} from "./managed-config.js";
|
|
export { bootstrapExecutionPolicyFromEnv } from "./execution-policy-bootstrap.js";
|
|
export { applyManagedEnvironments } from "./managed-environments.js";
|
|
export { buildExportFidelityReport, collectExportFidelityCounts } from "./export-fidelity.js";
|
|
export { companyPortabilityService } from "./company-portability.js";
|
|
export { teamsCatalogService } from "./teams-catalog.js";
|
|
export { environmentService } from "./environments.js";
|
|
export {
|
|
applyCustomImageTemplateToSandboxConfig,
|
|
fingerprintEnvironmentSandboxProviderConfig,
|
|
} from "./environment-custom-image-runtime.js";
|
|
export {
|
|
environmentCustomImageService,
|
|
} from "./environment-custom-images.js";
|
|
export {
|
|
environmentCustomImageTerminalConnectionRegistry,
|
|
environmentCustomImageTerminalSessionStore,
|
|
EnvironmentCustomImageTerminalConnectionRegistry,
|
|
EnvironmentCustomImageTerminalSessionStore,
|
|
parseCustomImageSetupSshCommand,
|
|
type EnvironmentCustomImageTerminalConnectionClose,
|
|
type EnvironmentCustomImageTerminalSessionRecord,
|
|
type MintedEnvironmentCustomImageTerminalSession,
|
|
type ParsedCustomImageSetupSshCommand,
|
|
} from "./environment-custom-image-terminal-sessions.js";
|
|
export { executionWorkspaceService } from "./execution-workspaces.js";
|
|
export { workspaceOperationService } from "./workspace-operations.js";
|
|
export {
|
|
workspaceRuntimeLeaseService,
|
|
buildWorkspaceRuntimeLeaseOwnerKey,
|
|
LEASED_WORKSPACE_RUNTIME_ACTIONS,
|
|
WORKSPACE_RUNTIME_ELIGIBLE_ISSUE_STATUSES,
|
|
WORKSPACE_RUNTIME_LEASE_TTL_MS,
|
|
type WorkspaceRuntimeLeaseClaim,
|
|
type WorkspaceRuntimeLeaseOwner,
|
|
type WorkspaceRuntimeLeaseService,
|
|
} from "./workspace-runtime-leases.js";
|
|
export { workspaceFileResourceService } from "./workspace-file-resources.js";
|
|
export {
|
|
createWorkspaceGitOperationScheduler,
|
|
getWorkspaceGitOperationSchedulerSnapshot,
|
|
workspaceGitOperationScheduler,
|
|
type WorkspaceGitSchedulerSnapshot,
|
|
} from "./workspace-git-operation-scheduler.js";
|
|
export {
|
|
enrichWorkProductMetadataWithDiff,
|
|
workProductService,
|
|
} from "./work-products.js";
|
|
export {
|
|
logActivity,
|
|
persistActivity,
|
|
publishActivity,
|
|
type ActivityPublication,
|
|
type LogActivityInput,
|
|
} from "./activity-log.js";
|
|
export { summarySlotService, SUMMARIZER_BUILT_IN_KEY } from "./summary-slots.js";
|
|
export { notifyHireApproved, type NotifyHireApprovedInput } from "./hire-hook.js";
|
|
export { publishLiveEvent, subscribeCompanyLiveEvents } from "./live-events.js";
|
|
export {
|
|
reconcileCodexLocalManagedHomesOnStartup,
|
|
type CodexAuthReconciliationSummary,
|
|
} from "./codex-auth-reconciliation.js";
|
|
export { reconcilePersistedRuntimeServicesOnStartup, restartDesiredRuntimeServicesOnStartup } from "./workspace-runtime.js";
|
|
export { createStorageServiceFromConfig, getStorageService } from "../storage/index.js";
|
|
export {
|
|
managedAgentProfileService,
|
|
CLAUDE_MANAGED_BETA_VERSION,
|
|
type ManagedAgentProfileInput,
|
|
} from "./managed-agent-profiles.js";
|
|
export {
|
|
remoteAgentProfileService,
|
|
type RemoteAgentProfileInput,
|
|
type RemoteAgentService,
|
|
} from "./remote-agent-profiles.js";
|