OrbitWake Connectors
Vue d’ensemble
OrbitWake Connectors fournit un runtime contrôlé pour exposer des actions de services externes à OrbitWake. Le runtime actuel gère la découverte des outils, les permissions, les approbations, la portée des ressources, l’activité et l’idempotence.
Runtime actuellement disponible
Dans la build actuelle, le runtime serveur enregistre un connecteur uniquement lorsqu’une connexion utilisable existe pour l’utilisateur.
Le connecteur réellement câblé aujourd’hui est GitHub. Lorsqu’une connexion GitHub valide est chargée, ses actions sont ajoutées au registre runtime. Sans connexion GitHub, ces actions ne sont pas exposées.
Anatomie d’un connecteur
Un connecteur OrbitWake est défini par un identifiant, un nom, une version, un mode d’authentification et une liste d’actions.
Chaque action possède une description, un schéma d’entrée et un niveau de permission. Le registre transforme ensuite les actions des connecteurs actifs en tools qualifiés, par exemple github.read_file ou github.create_pull_request.
| Élément | Rôle |
|---|---|
| Connector ID | Identifie le fournisseur dans le runtime. |
| Action | Décrit une opération disponible sur ce fournisseur. |
| Input schema | Définit la forme des données acceptées par l’action. |
| Permission | Classe l’action en read, write ou sensitive. |
| Auth | Décrit le mode d’authentification du connecteur. |
Permissions : read, write et sensitive
Chaque action est classée dans l’un des trois niveaux de permission du runtime.
| Niveau | Politique par défaut | Exemple GitHub |
|---|---|---|
read | allow | Lire un fichier, rechercher du code, lister des branches. |
write | ask | Créer une branche, créer ou mettre à jour un fichier, ouvrir une PR. |
sensitive | ask | Merger une pull request. |
Une politique explicite peut remplacer ces décisions dans le contexte d’exécution. Une permission peut être autorisée, soumise à approbation ou refusée.
Approbations
Lorsqu’une action write ou sensitive nécessite une approbation, OrbitWake crée une demande liée à l’utilisateur, au workspace, au connecteur, au nom de l’action et au contenu exact de l’entrée.
L’entrée est canonicalisée puis hachée. Une approbation ne peut donc pas être réutilisée pour une autre action ou avec des paramètres différents.
Les approbations actuelles expirent après 10 minutes. Une approbation doit être dans l’état approved, non expirée, correspondre à l’action exacte et ne pas avoir déjà été consommée.
Après utilisation, l’approbation passe à l’état used. Une approbation refusée, expirée ou déjà consommée n’autorise pas l’action.
Portée des ressources
Les permissions déterminent quel type d’action est autorisé. Les resource scopes déterminent sur quelles ressources l’action peut travailler.
Le connecteur GitHub utilise notamment la portée github.repositories. Une liste explicite peut limiter les dépôts accessibles. La valeur * autorise les dépôts disponibles par la connexion GitHub elle-même.
Lorsqu’un dépôt se trouve hors de la portée OrbitWake, l’action échoue avant que le client GitHub n’exécute l’opération demandée.
Découverte des tools disponibles
Le runtime expose seulement les actions des connecteurs enregistrés pour l’utilisateur courant. La liste des tools peut être récupérée depuis la surface backend authentifiée des connecteurs.
Chaque tool retourné contient son nom qualifié, sa description, son niveau de permission et son schéma d’entrée.
Cette découverte dynamique est importante : l’absence d’un connecteur dans le registre signifie que ses tools ne doivent pas être considérés comme disponibles.
Cycle d’exécution
| Étape | Comportement |
|---|---|
| 1. Résolution | OrbitWake cherche le connecteur et l’action dans le registre actif. |
| 2. Activité démarrée | Un événement started est enregistré. |
| 3. Autorisation | Le runtime applique permission, politique et approbation éventuelle. |
| 4. Portée | Le fournisseur peut vérifier que la ressource est autorisée. |
| 5. Exécution | L’action appelle le client du fournisseur. |
| 6. Résultat | Le runtime retourne succès ou erreur normalisée. |
| 7. Activité finale | Le statut final, la durée et l’erreur éventuelle sont enregistrés. |
Journal d’activité
Les exécutions de connecteurs produisent des événements d’activité persistés par workspace et par utilisateur.
Les statuts actuels sont started, approval_required, denied, succeeded et failed.
Un événement peut conserver l’identifiant de requête, le connecteur, l’action, le niveau de permission, les heures de début et de fin, la durée, le code d’erreur et des métadonnées.
La surface backend d’activité limite actuellement les résultats à un maximum de 100 entrées par requête.
Idempotence
Une exécution peut fournir une idempotencyKey. Le runtime combine cette clé avec le connecteur et l’action avant de rechercher un résultat déjà enregistré.
Lorsqu’un résultat correspondant existe encore, il est rejoué sans réexécuter l’opération externe. L’événement d’activité indique alors idempotentReplay: true.
Les résultats d’idempotence actuels expirent après 24 heures.
Erreurs du runtime
Le runtime utilise des erreurs structurées avec un code, un message et un indicateur de possibilité de retry.
| Code | Signification |
|---|---|
CONNECTOR_NOT_FOUND | Le connecteur demandé n’est pas enregistré. |
ACTION_NOT_FOUND | L’action n’existe pas ou n’est pas disponible. |
APPROVAL_REQUIRED | L’action attend une approbation. |
PERMISSION_DENIED | La politique interdit l’action. |
INVALID_APPROVAL | L’approbation est invalide, expirée, utilisée ou ne correspond pas à l’action exacte. |
CONNECTOR_EXECUTION_FAILED | Le fournisseur ou l’action a échoué pendant l’exécution. |
GitHub comme connecteur runtime actuel
GitHub utilise une authentification OAuth/GitHub App côté OrbitWake. La connexion stocke l’installation et le token de manière chiffrée, puis le runtime recharge et rafraîchit le credential lorsque nécessaire.
La build actuelle expose via GitHub des actions de lecture comme lister les dépôts, rechercher du code, lire un fichier, lister branches, PR et issues ; des actions d’écriture comme créer une branche, créer ou mettre à jour un fichier, créer une issue et ouvrir une PR ; et une action sensible pour merger une PR.
La documentation détaillée de GitHub sera traitée dans une page dédiée afin de garder cette vue d’ensemble centrée sur le runtime commun des connecteurs.
Catalogue et disponibilité
Le catalogue public de Connectors présente plusieurs services et catégories. Cette surface est utile pour montrer la direction d’intégration d’OrbitWake, mais la disponibilité technique varie par connecteur.
Ne déduisez jamais qu’un logo ou une carte marketing signifie qu’un backend est actif. La source de vérité pour les tools disponibles est le registre runtime de l’utilisateur connecté.
Les éléments MCP et Custom APIs actuellement visibles sur la page publique sont présentés comme Preview et ne doivent pas encore être documentés comme un workflow de configuration stable.
Limites actuelles
Le runtime serveur réellement câblé dans cette build enregistre actuellement GitHub. Les autres logos du catalogue ne sont pas une preuve d’implémentation backend.
Le système de permissions est générique, mais chaque fournisseur doit encore implémenter ses propres actions, son authentification et ses vérifications de portée.
Les pages détaillées de services Google et des intégrations externes resteront des entrées de recherche jusqu’à ce que leur runtime soit suffisamment stable et vérifiable.
Étapes suivantes
Continuez avec la page GitHub pour voir le premier connecteur runtime actuellement disponible : connexion, dépôts autorisés, lectures, écritures, pull requests et limites.