yasyf/orca

Workers Orca

Chargez d'abord les guides correspondant à la version : orca skills get orca-cli et orca skills get orchestration. Cette compétence définit le point d'entrée du worker et le contrat de retour de source.

Chaque commande orca orchestration ici transmet --full : depuis Orca 1.4.246, elle affiche une vue concise sans lui, ce qui supprime les champs que ces étapes lisent. orca-worker-launch.sh et orca-reclaim.py, sur le PATH via le dossier bin/ de ce plugin, passent --full --json eux-mêmes. Exécutez les deux depuis la racine du checkout.

Valeurs du dépôt

Un dépôt qui lance des workers enregistre .orca.json à sa racine, et les deux outils le lisent depuis le répertoire de travail :

{
  "ccRemote": "tools/cc-remote/bin/cc-remote",
  "ccRemoteConfig": "tools/cc-remote/config.yaml",
  "repo": "<orca-repository-id>",
  "baseBranch": "origin/main",
  "sparse": [".agents", ".claude"]
}

Clé	Variable d'environnement qu'elle remplit	Route
ccRemote	WORKER_CC_REMOTE, la CLI cc-remote, un chemin depuis la racine du checkout ou un nom sur le PATH	Sprite, et orca-reclaim.py
ccRemoteConfig	CC_REMOTE_CONFIG, la configuration cc-remote, depuis la racine du checkout	Sprite, et orca-reclaim.py
repo	WORKER_REPO, l'identifiant du dépôt Orca	locale
baseBranch	WORKER_BASE_BRANCH, la branche à partir de laquelle un worktree local commence	locale
sparse	mène à WORKER_SPARSE, le cône sparse du worktree local	locale

Une variable d'environnement définie prévaut sur sa clé, et WORKER_SPARSE ajoute des répertoires après le cône du fichier. Chaque clé est facultative, et un dépôt sans .orca.json passe lui-même les variables.

Lancer un worker

Les workers d'implémentation et de test utilisent par défaut un workspace d'agents Sprite préinstallé inutilisé. Le lanceur le réclame exclusivement, rafraîchit la référence demandée de manière superficielle, prépare l'agent et attache la tâche native en une seule invocation. Lorsqu'aucun workspace inutilisé compatible n'est prêt, il crée le workspace de la lane. Chaque allocation démarre un remplissage d'arrière-plan fini vers la configuration orca.pool.ready, de sorte que les lancements successifs réclament des workspaces chauds. Les workers réclamés restent réclamés après l'achèvement ; la réutilisation d'un agent retenu nécessite un nouveau Dispatch natif explicite.

Un nom de lane Sprite a au plus 55 lettres minuscules, chiffres et tirets, et commence par une lettre ou un chiffre :

WORKER_RUN="<owned-run-id>" WORKER_REF=<branch> \
  orca-worker-launch.sh "<lane>" "<model>" "<effort>" "<brief.md>"

Exécutez ceci depuis le terminal qui possède déjà le Run natif nommé. Le script vérifie cette liaison avant l'allocation, appelle cc-remote orca prepare --warm une fois, puis démarre le worker inactif préparé avec un worker-start natif sur le serveur Orca du Sprite, réutilisant son terminal et son worktree préparés. La préparation copie le brief complet sur la VM et enregistre son hash, sa longueur et le HEAD de checkout réel. La première tâche est un pointeur indiquant au worker de lire et vérifier ce fichier.

La préparation démarre le runtime Orca du Sprite via sa CLI orca, et Orca 1.4.224 le sert sur son serveur géré, orcad. La tâche préparée enregistre la construction de ce serveur comme managedServer, lue à partir de l'événement prêt que orca serve --json affiche. Le script ne démarre rien lorsque le champ est manquant, ce qui signifie qu'Orca est retombé sur Electron. La raison d'Orca est la ligne [serve] dans ~/.cc-remote/orca/serve.log sur le Sprite.

Le lanceur exécute la CLI nommée par WORKER_CC_REMOTE ou ccRemote contre la configuration CC_REMOTE_CONFIG ou ccRemoteConfig. Sans CLI définie, il exécute cc-remote depuis le PATH, où le PATH d'une session longue ou une installation Homebrew plus récente peut contenir une autre version. Un dépôt qui épingle sa version nomme donc son wrapper dans ccRemote. Un lancement Sprite sans configuration refuse avant l'allocation.

cc-remote prépare un Sprite uniquement lorsque la CLI est la version exacte du orca.bootstrap_helper de la configuration ; un correctif plus récent échoue comme un plus ancien, donc l'épingle CLI et l'assistant évoluent ensemble lors d'un changement d'épingle. Avant l'allocation, le lanceur compare la version qu'affiche la CLI sélectionnée avec la bootstrapHelper.version du agents-payload.json à côté de la configuration, liens résolus, et refuse une différence, nommant les deux. cc-remote effectue la même vérification lui-même, mais une réclamation chaude l'atteint après que le spare est réclamé, et ce spare reste alors réclamé comme ayant échoué. Une configuration sans agents-payload.json à côté d'elle laisse la vérification à cc-remote.

Lorsqu'une version signée fraîchement installée bloque lors de son premier lancement sur un Mac, récupérez-la vous-même. Il s'agit d'une récupération d'installation, jamais d'une question pour le propriétaire. Vérifiez que l'exécutable sélectionné est la version signée, supprimez com.apple.quarantine de ce seul fichier, et réessayez sa commande de version :

exe="$(readlink -f "<selected-executable>")"
codesign --verify --strict --check-notarization --verbose=2 \
  -R='notarized and certificate leaf[subject.OU] = "SXKCTF23Q2"' "$exe" &&
  xattr -d com.apple.quarantine "$exe"
"<selected-cc-remote>" version

xattr affiche No such xattr lorsque l'attribut est déjà absent. Ne transmettez jamais -r, ne nommez pas un répertoire, et ne modifiez pas la politique système de Gatekeeper.

Le lanceur ne transmet pas --config. Il exporte CC_REMOTE_CONFIG vers cc-remote sous forme de chemin absolu, et une valeur relative se résout depuis le répertoire de l'appelant. La configuration sélectionnée nomme le dépôt que le Sprite vérifie. WORKER_REPO sélectionne uniquement un dépôt Orca local ; le définir sur la route Sprite refuse avant une tentative ou une allocation. Le lanceur ne mappe pas un ID de dépôt local vers un dépôt distant.

Fournissez une autre paire binaire/configuration, comme un exécuteur qui conserve une version tandis que son checkout évolue, comme ceci :

WORKER_CC_REMOTE=/absolute/path/to/cc-remote \
CC_REMOTE_CONFIG=/absolute/path/to/config.yaml \
WORKER_RUN="<owned-run-id>" WORKER_REF=<branch> \
  orca-worker-launch.sh "<lane>" opus xhigh "<brief.md>"

WORKER_REF nomme une branche ou un tag distant et est transmis tel quel ; lorsqu'il est omis, la configuration fournit sa référence. WORKER_BASE_BRANCH appartient à la route de worktree locale explicite. Ne le transmettez pas comme branche distante, ne supprimez pas de préfixes arbitraires et ne remplacez pas la référence demandée par un ID de commit provenant d'une pré-recherche locale. Le baseCommit de l'enregistrement préparé est t la base réelle de la VM. Définir WORKER_BASE_BRANCH sur la route distante refuse ; WORKER_REF et WORKER_EXPECT_BASE refusent sur la route locale.

Un mouvement de branche ordinaire est valide. Définissez WORKER_EXPECT_BASE uniquement lorsque la tâche nécessite une base exacte. Fournissez un ID de commit complet de 40 ou 64 caractères en minuscules. Le lanceur le compare après la préparation ; une non-concordance conserve le worker inactif préparé et s'arrête avant worker-start. Cette comparaison ne sélectionne pas le checkout. La préparation n'a pas d'option de checkout par commit exact séparée, et un nom de branche ou de tag reste une référence même si son orthographe ressemble à de l'hexadécimal.

Préservez le modèle et l'effort sélectionnés. WORKER_SERVICE_TIER transmet un niveau de service Codex explicite inchangé ; il refuse avec un modèle Claude. Le niveau rapide est réservé aux lanes d'incident uniquement : WORKER_SERVICE_TIER=fast refuse sauf si WORKER_INCIDENT=1. Sans niveau, le lanceur ne transmet aucun indicateur de niveau de service, et codex s'exécute sur le niveau standard.

Utilisez WORKER_LOCAL=1 pour une racine locale, qui exécute Opus, ou pour un travail extrêmement sensible autorisé par la racine, le seul cas pour Fable :

WORKER_RUN="<owned-run-id>" WORKER_LOCAL=1 \
  orca-worker-launch.sh "<lane>" opus xhigh "<brief.md>"

La route locale refuse sans dépôt et branche de base, provenant de WORKER_REPO et WORKER_BASE_BRANCH ou repo et baseBranch.

Le worktree local est nommé <lane>-<first 8 hex of the Run id's SHA-256>, donc deux Runs ne coupent jamais un même nom. Un deuxième lancement pour cette lane dans le même Run reprend son worktree actif ; lorsque le worktree qu'une tentative antérieure a coupé est disparu, le lancement refuse, car un nom n'est jamais coupé deux fois.

Un nouveau worktree local est sparse sur sparse suivi des répertoires nommés par WORKER_SPARSE, séparés par des espaces, et est un checkout complet lorsque les deux sont vides. Le lanceur affiche la commande d'élargissement. Le brief d'une lane sparse porte "cette lane est sparse : élargissez avec git sparse-checkout add <dir> avant de lire en dehors".

Un WORKER_LOCAL non défini ou vide sélectionne Sprite ; toute autre valeur non vide refuse. La route locale démarre uniquement Claude et refuse les modèles Codex. Fable distant refuse avant la préparation ; il ne se transforme jamais en lancement local ou en un modèle différent. Claude local conserve l'authentification interactive existante et le comportement de contournement limité à la tâche. Il démarre réduit sous lane_env et lane_settings, sans mise à jour automatique, watcher ~/.claude natif, animation, télémétrie ou ligne de statut, et lane_denied_tools l'empêche de s'arrêter sur un humain. Les sessions interactives et claude plugin update mettent toujours à jour le cache de plugins. Définissez CLAUDE_LANE_SETTINGS sur un objet JSON pour ajouter des paramètres locaux.

Démarrez uniquement les serveurs du Model Context Protocol nommés dans la liste d'autorisation de la tâche. Sur Sprite, WORKER_MCP_CONFIG transmet un objet JSON en ligne pour Claude ou une table TOML en ligne pour Codex au --mcp-config de prepare ; ce n'est pas un chemin de fichier local. Sur la route locale, la valeur suit la syntaxe --mcp-config de Claude.

Claude et Codex distants utilisent des clés API dédiées des callbacks configurés de cc-remote. Claude utilise l'authentification d'environnement API normale ; ses processus d'outils ordinaires peuvent hériter de ces clés. Pour Codex, la CLI épinglée exclut OPENAI_API_KEY, CODEX_API_KEY, ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN et CLAUDE_CODE_OAUTH_TOKEN des outils shell intégrés. L'acteur et ses hooks natifs conservent l'environnement nécessaire pour les appels API. Ces exclusions ne fournissent aucune isolation de processus ou de système de fichiers en mode contournement.

Conservez les identifiants API dans l'acteur distant et ses descendants autorisés. Les évaluateurs de hook locaux à l'acteur peuvent passer des clés sélectionnées à des enfants inférence de courte durée. Gardez les clés hors des démons hook résidents, des images, des artefacts, des journaux, des fichiers partagés et de la configuration globale. Ne définissez pas de variables de clé API globalement, ne remplacez pas l'authentification interactive locale et ne copiez pas de jetons d'actualisation OAuth ou de caches d'authentification entiers vers un worker.

Chaque brief réclame <brief-stem>.worker à côté du brief. Pour /briefs/lane-a.md, c'est /briefs/lane-a.worker. Un répertoire existant, lien, tentative échouée ou <brief-stem>.dispatch.json hérité refuse la relecture. Le répertoire enregistre request.json avec la route, le modèle, l'effort, le niveau, la référence, la base attendue facultative et le hash/taille du brief local demandés.

La route distante conserve les fichiers bruts allocation.json, prepare.err et prepare.status. Elle valide la lane demandée, le workspace réel, la référence demandée, le type d'allocation, le HEAD de la tâche, l'agent, le brief, l'environnement, le terminal et le worktree <repoId>::<projectRoot> avant d'extraire la tâche dans prepared.json. Elle exécute ensuite worker-start avec --on l'environnement préparé, --worktree id:<worktreeId> et --terminal le terminal préparé. Les deux routes conservent worker-start.json, worker-start.err et worker-start.status. Gardez ces fichiers quel que soit le résultat.

Le succès nécessite que worker-start se termine avec zéro et un reçu indiquant ok, l'état ready, le Run possédé, et des ID de tâche et de Dispatch imprimables. Les ID dans un reçu échoué ne le rendent pas prêt. Le succès imprime une ligne JSON avec les champs state, task, dispatch, terminal et worktree.

Sur Sprite, le JSON nomme également lane, le workspace réel et allocation (warm ou created). terminal est prepared.terminal et worktree est prepared.projectRoot, le checkout sur la VM. Utilisez ce workspace réel pour les appels cc-remote orca collect ultérieurs. Un démarrage échoué ou non prouvé n'imprime aucun JSON de succès et conserve la tentative sans nouvelle tentative ni nettoyage.

Préparer et attacher séparément

Utilisez la CLI et la configuration sélectionnées décrites ci-dessus lorsque la préparation et l'attachement de la première tâche nécessitent une inspection séparée. Cet exemple explicite de Sprite agents frais retourne une tâche préparée simple :

"<selected-cc-remote>" orca prepare "<lane>" --config "<configured-yaml>" \
  --provider sprites --profile agents --agent claude \
  --model claude-opus-5-5 --effort xhigh --ref "<branch-or-tag>" \
  --brief-file "<complete-brief.md>" >"<new-prepared.json>"

La préparation démarre l'agent sélectionné et s'arrête à l'inactivité native sans envoyer sa tâche. Exigez que la commande se termine avec zéro, prepared:true, le modèle/effort demandé, le baseCommit réel et le hash et la taille exacts du brief avant l'attachement. Pour une affectation Codex, préservez le type d'agent, le modèle, l'effort et le niveau de service explicite demandés. Gardez les identifiants API dans les callbacks configurés limités au processus.

Depuis le coordinateur qui possède déjà le Run, attachez une fois avec les champs de l'enregistrement préparé et un nouveau fichier de reçu :

orca orchestration worker-start --run "<owned-run-id>" --on "<environment>" \
  --worktree "id:<worktreeId>" --terminal "<terminal>" --task-title "<lane>" \
  --spec "Lane <lane> : lisez le brief complet à <brief.path>, vérifiez que son SHA-256 est <brief.sha256> et que sa taille est de <brief.bytes> octets, puis suivez-le exactement." \
  --full --json >"<new-receipt.json>"

Ceci réutilise le terminal et le worktree préparés et crée la tâche native avec un pointeur vers le brief complet. Ne transmettez pas d'agent, de modèle, d'effort ou de niveau de service, afin que le processus préparé conserve les siens. Le reçu prêt nomme la tâche et le Dispatch. Le propriétaire de la boîte de réception existante gère leurs messages ; n'envoyez pas de second pointeur de tâche ni ne démarrez un autre consommateur. En cas d'achèvement accepté, conservez la session et utilisez le contrat de retour de source et de collecte. Conservez les reçus pour chaque résultat. Un échec de création fraîche peut exécuter le rollback normal de la CLI ; signalez les ressources réelles restantes et ne rejouez jamais une tentative ambiguë.

Premier worker sur un workspace enregistré

La version 0.15.0 ajoute --existing en mode préparation uniquement pour un premier worker sur le workspace enregistré exact et le checkout conservé :

"<selected-cc-remote>" orca prepare "<recorded-workspace>" --existing \
  --config "<same-config>" --provider sprites --profile agents --agent claude \
  --model claude-opus-5-5 --effort xhigh --ref "<branch-or-tag>" \
  --brief-file "<complete-brief.md>" >"<new-prepared.json>"

(Traduit partiellement car le contenu original était tronqué.)