attach

Rôle et comportement

Ouvre le terminal interactif de la CLI d’un agent dans une sandbox allouée pour cet appel, puis renvoie le statut de sortie et les commits de la session. Le statut 0 applique la politique de branche et ferme la sandbox ; un statut non nul ou un échec la ferme et conserve le worktree. Le processus de l’agent a un délai de 86400000 (24 heures).

Exemple complet et règles détaillées.

Paramètres et propriétés

• optionsRequis
  SandboxOptions & AttachOptions & RequiredAgent
  Réglages de la sandbox (dépôt, branche, provider, hooks) combinés avec l’agent CLI, le brief, la continuation et les flux du terminal.
• options.includeUncommittedOptionnel
  boolean | undefined
  Providers distants uniquement : envoie aussi les modifications non commitées du worktree géré et ses fichiers non suivis et non ignorés, false par défaut. Sans cette option, la synchronisation échoue avec le code workspace quand la sandbox touche l’un de ces fichiers, ce qui inclut toute entrée de copies non ignorée par un .gitignore commité.
• options.agentOptionnel
  CliAgent | CustomAgent | ReplayAgent
  Agent par défaut de dispatch(), resume(), fork() et attach() sur cette sandbox ; l’agent d’une opération le remplace. Sur un provider distant avec bootstrap actif, son premier candidat est installé à l’allocation ; attach() refuse un agent de secours sur tous les providers.
• options.sandboxProviderOptionnel
  SandboxProvider | undefined
  Provider qui alloue l’environnement, createDockerSandboxProvider() par défaut. Un provider distant exige une branche named ou integrate et prend integrate par défaut.
• options.workspaceOptionnel
  Workspace | undefined
  Workspace ouvert dans lequel travailler, issu d’openWorkspace() ; close() le laisse ouvert. Le combiner avec repository, branch, copies ou storageQuota, ou passer un workspace déjà lié à une sandbox ouverte, échoue avec le code configuration.
• options.hooksOptionnel
  LifecycleHooks | undefined
  Commandes de préparation, chacune tenue de sortir avec 0 avant son deadlineMs, 600000 par défaut (10 minutes) : workspaceReady sur l’hôte une fois un nouveau worktree créé, puis hostReady (hôte, dans l’ordre) et sandboxReady (sandbox, toutes ensemble) en parallèle ; une sortie non nulle fait échouer la préparation avec le code process. Avec un workspace fourni, workspaceReady ne s’exécute pas et les hooks donnés ici remplacent les hostReady et sandboxReady du workspace.
• options.signalOptionnel
  AbortSignal | undefined
  Son annulation interrompt la préparation de la sandbox : allocation, amorçage du dépôt, installation de l’agent et hooks de préparation. createSandbox() cesse de le surveiller une fois la sandbox renvoyée.
• options.loggingOptionnel
  Logging | undefined
  Journal de chaque dispatch sur cette sandbox, par défaut un journal local sous .outpost/storage ; stdout affiche la progression à la place, false le désactive, et un objet règle transporter, verbose et replayable. Le logging propre d’un dispatch le remplace.
• options.bootstrapOptionnel
  boolean | undefined
  Installe dans une sandbox distante un agent CLI intégré absent, dans sa version épinglée, avant sa première utilisation ; true par défaut. Les providers montés et hôte n’installent rien : le CLI doit être dans l’image ou sur l’hôte.
• options.conversationHomeOptionnel
  string | undefined
  Répertoire de l’hôte utilisé à la place de votre répertoire personnel pour stocker et retrouver les conversations natives capturées. Par défaut : votre répertoire personnel pour les transcriptions Claude et Codex, le dépôt pour les bundles de session Copilot et Kimi.
• options.recoveryTransportOptionnel
  Transport | undefined
  Providers distants uniquement : avant l’application des modifications rapatriées, archive la sauvegarde de l’hôte dans ce transport en plus de .outpost/recovery. Les archives survivent à la sandbox.
• options.activityTransportOptionnel
  Transport | undefined
  Transport de l’enregistrement d’activité de cette sandbox, par défaut le stockage local sous .outpost/storage. L’enregistrement est supprimé après une fermeture propre et conservé avec une phase d’échec quand le nettoyage échoue.
• options.observationOptionnel
  ObservationHub | undefined
  Hub qui reçoit les opérations Git, de copie, de hook, d’intégration et de nettoyage de ce workspace. L’appelant en reste propriétaire ; le workspace ne le ferme jamais.
• options.storageQuotaOptionnel
  Omit<StorageReservationOptions, "signal"> | undefined
  Admission de stockage vérifiée avant l’ouverture du workspace : réserve reserveBytes et échoue avec le code configuration si l’usage sous .outpost plus les réservations actives dépasseraient maxBytes. La réservation est libérée à la fermeture du workspace.
• options.repositoryOptionnel
  string | undefined
  Chemin dans le checkout Git hôte, par défaut le répertoire de travail du processus. Outpost travaille depuis le répertoire racine du checkout ; un répertoire indisponible échoue avec le code workspace.
• options.branchOptionnel
  BranchPolicy | undefined
  Politique de branche : current, named ou integrate. { mode: “current” } par défaut ; createSandbox() et dispatch() sur un provider distant utilisent integrate par défaut.
• options.copiesOptionnel
  readonly string[] | undefined
  Fichiers ou dossiers relatifs au dépôt, copiés depuis le checkout hôte dans le nouveau worktree avant workspaceReady ; les entrées absentes sont ignorées. Exige named ou integrate, et les chemins absolus, avec .. ou .git échouent avec le code configuration. Une copie non suivie ou ignorée fait conserver le worktree à la fermeture. Sur un provider distant sans includeUncommitted, une copie non ignorée par un .gitignore commité fait échouer la première synchronisation avec le code workspace.
• options.limitsOptionnel
  StageLimits | undefined
  Délais en millisecondes de copie, de préparation Git, de collecte des commits et d’intégration. Au-delà, l’étape échoue avec le code timeout, ou conflict pour l’intégration.
• options.labelOptionnel
  string | undefined
  Nom utilisé dans la branche integrate (outpost/<label>-<id>), le dossier du worktree sous .outpost/workspaces et le journal d’échec au démarrage ; mis en minuscules, autres caractères remplacés par -, tronqué à 48.
• options.askOptionnel
  VariableQuestion | undefined
  Fournit chaque variable {{name}} laissée sans valeur par un brief fichier, un appel par nom, avant l’ouverture du terminal. Sans ce callback, Outpost pose la question dans le terminal de l’hôte et rejette avec le code configuration quand stdin n’est pas un TTY.
• options.briefOptionnel
  Brief | undefined
  Premier message confié à l’agent : texte littéral ou brief lu depuis un fichier. Sans brief, le terminal s’ouvre sans message.
• options.continuationOptionnel
  { readonly id: string; readonly fork?: boolean; } | undefined
  Conversation native à rouvrir, par identifiant ; fork: true ouvre une copie et laisse l’originale intacte. Rejette avec le code configuration si l’agent ne sait pas reprendre ou bifurquer.
• options.terminalOptionnel
  { readonly input?: Readable; readonly output?: Writable; readonly error?: Writable; } | undefined
  Flux utilisés à la place du terminal de l’hôte : input alimente l’agent, output et error reçoivent ce qu’il écrit. Omis, l’agent lit et écrit sur stdin et stdout du processus hôte.

Retour

Promise<AttachResult>

Signature

export declare function attach(
  options: SandboxOptions & AttachOptions & RequiredAgent,
): Promise<AttachResult>;

Contrats associés

• AttachOptions
• AttachResult
• RequiredAgent
• SandboxOptions