npm - @elie-laloum/outpost - Versions diffs - 1.1.2 → 1.1.3 - Mend

@elie-laloum/outpost 1.1.2 → 1.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

package/docs/api.md DELETED Viewed

@@ -1,147 +0,0 @@
-# API reference
-## Domain and ownership
-`Workspace` owns a Git checkout and its lock. `Sandbox` owns a running environment attached to exactly one workspace. `dispatch` is one agent job, potentially containing several turns. `Task<T>` is one typed workflow node. A native conversation belongs to an agent and can outlive both workspace and sandbox.
-| Entry point              | Lifetime                                                                               |
-| ------------------------ | -------------------------------------------------------------------------------------- |
-| `dispatch(options)`      | Creates and closes its own sandbox; closes its workspace unless supplied.              |
-| `attach(options)`        | Opens a terminal session, synchronizes changes and closes owned resources.             |
-| `createSandbox(options)` | Returns a warm handle with `dispatch`, `resume`, `fork`, `attach`, `command`, `close`. |
-| `openWorkspace(options)` | Returns a workspace with `dispatch`, `sandbox`, `attach`, `integrate`, `close`.        |
-Sandbox and workspace handles implement `Symbol.asyncDispose` for `await using`. Explicit `close()` is supported and idempotent. Close the sandbox before closing a separately owned workspace. A warm sandbox rejects overlapping operations. Separate workspaces hold separate locks; automatic merges hold a host-branch merge lock.
-## WorkspaceOptions
-| Field              | Type / default                        | Meaning                                                    |
-| ------------------ | ------------------------------------- | ---------------------------------------------------------- |
-| `repository`       | `string`, current directory           | Repository root or a directory inside it.                  |
-| `branch`           | `BranchPolicy`, `{ mode: "current" }` | Checkout, named worktree, or temporary integration branch. |
-| `copies`           | `readonly string[]`                   | Repository-relative inputs copied before workspace hooks.  |
-| `limits.copyMs`    | `number`, 60000                       | Copy deadline.                                             |
-| `limits.gitMs`     | `number`, 30000                       | Git setup operation deadline.                              |
-| `limits.collectMs` | `number`, 30000                       | Commit collection deadline.                                |
-| `limits.mergeMs`   | `number`, 30000                       | Host merge deadline.                                       |
-Branch variants:
-```ts
-type BranchPolicy =
-  | { mode: "current" }
-  | { mode: "named"; name: string; from?: string }
-  | { mode: "integrate"; from?: string };
-```
-`from` accepts a Git commit-ish and is resolved before branch creation. An existing named branch is reused. Managed worktrees live under `.outpost/workspaces`. A branch checked out outside its managed location is not moved. Integration requires an attached host branch and never switches the host checkout. Dirty worktrees survive close; `close({ preserve: true })` also retains clean ones. Inspect the returned `retainedDirectory`.
-## SandboxOptions
-Includes `WorkspaceOptions`, plus:
-| Field              | Meaning                                                                                                                                         |
-| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| `agent`            | Default `AgentAdapter` for warm operations; optional on `createSandbox`, required on one-shot `dispatch`/`attach`. Use `codex()` or `claude()`. |
-| `provider`         | `SandboxProvider`; defaults to `docker()`.                                                                                                      |
-| `workspace`        | Existing workspace. Cannot be combined with `repository`, `branch` or `copies`.                                                                 |
-| `hooks`            | `workspaceReady`, `hostReady`, `sandboxReady` command arrays.                                                                                   |
-| `signal`           | Cancels provisioning. In one-shot calls, also cancels execution.                                                                                |
-| `logging`          | `false`, `"stdout"`, or `{ file?, verbose? }`; default generated JSONL file.                                                                    |
-| `bootstrap`        | Remote agent installation when absent; defaults to `true`.                                                                                      |
-| `conversationHome` | Host directory containing `.claude`/`.codex`; defaults to OS home.                                                                              |
-Hook order is copies → `workspaceReady` on host → provider acquisition/synchronization → concurrent `hostReady` and `sandboxReady`. Host commands run sequentially. Sandbox commands run concurrently. Failure aborts sibling hooks and waits for their cleanup. `openWorkspace({ hooks })` runs `workspaceReady` immediately and passes the remaining hooks to later sandboxes without repeating it. Commands may choose a directory, environment and timeout. Sandbox commands can request `elevated: true` on providers supporting elevation. Host execution does not elevate privileges.
-## DispatchOptions
-| Field          | Default / meaning                                                                             |
-| -------------- | --------------------------------------------------------------------------------------------- |
-| `brief`        | Required `{ text }` or `{ file, values? }`.                                                   |
-| `agent`        | Overrides the warm sandbox's default adapter for this job, including its model and variables. |
-| `logging`      | Overrides the sandbox's logging policy for this job.                                          |
-| `label`        | Optional label included in journal records and generated log filenames.                       |
-| `passes`       | Positive integer, default 1. Maximum agent turns when no response validator is supplied.      |
-| `until`        | String or strings; default `<outpost>done</outpost>`. Empty array disables markers.           |
-| `idleMs`       | 600000; maximum silence before completion. Any output refreshes it.                           |
-| `settleMs`     | 60000; grace period after completion, refreshed by output.                                    |
-| `deadlineMs`   | 3600000; hard deadline for each agent command.                                                |
-| `expansionMs`  | 30000; deadline for each embedded prompt command.                                             |
-| `signal`       | Cancels this operation, preserving a warm sandbox.                                            |
-| `continuation` | `{ id, fork? }`; native resume or conversation fork.                                          |
-| `response`     | A `ResponseSpec<T>` produced by `response.text/json`.                                         |
-| `observe`      | Receives normalized events; exceptions cannot fail the job.                                   |
-| `warn`         | Receives nonfatal warnings; exceptions cannot fail the job.                                   |
-Resume and structured output require `passes: 1`. A one-shot continuation validates the host transcript before allocating an environment. Warm continuations reuse sessions already present, otherwise importing the host transcript.
-`DispatchResult<T>` contains `text`, `value`, `turns`, `usage`, `completed`, optional `completion`, `conversation`, `transcript`, `log`, `branch`, `directory`, `commits`, optional `retainedDirectory`, and `resume`/`fork` methods. `value` is inferred from the response validator. Without a validator it is `undefined`. Usage contains raw `input`, `cached` (cache read), optional `cacheCreated` (cache creation) and `output` token counts. Claude transcript usage takes the final assistant message, independently from streamed totals. Costs are not estimated.
-Each turn contains `text`, `status`, `durationMs`, `usage`, and optional `conversation` and `transcript`. Commits contain their original `oid` and `subject`. A budget exhausted without a completion marker returns `completed: false`; process failures throw.
-## Agent settings
-```ts
-codex({
-  model: "your-model",
-  reasoning: "high",
-  approvalReviewer: "auto_review",
-  saveConversations: true,
-  variables: {},
-});
-claude({
-  model: "sonnet",
-  reasoning: "high",
-  permissions: "acceptEdits",
-  saveConversations: true,
-  variables: {},
-});
-```
-Model is optional; the installed CLI chooses its default. Codex reasoning accepts `low`, `medium`, `high`, `xhigh`. Claude also accepts `max`. Actual model support is determined by the CLI/provider. Claude permission modes are `default`, `acceptEdits`, `plan`, `auto`, `dontAsk`, `bypassPermissions`.
-Noninteractive defaults avoid permission prompts because the outer sandbox is responsible for isolation. Codex can instead use the auto-review approval reviewer. Interactive commands use native terminal behavior and native session resume/fork commands.
-Events are a discriminated union with `kind`: `phase`, `prompt`, `text`, `result`, `tool`, `conversation`, `usage`, `summary`, `warning`, `failure`, `finished`, `raw`. Every public observation adds a one-based `pass` and ISO timestamp `at`. Protocol noise is retained as `raw`. Adapters implement `request(input): Command` and `events(line): AgentEvent[]`; a custom adapter can omit native conversation support.
-## Command and attachment
-```ts
-const result = await sandbox.command({
-  executable: "npm",
-  arguments: ["test"],
-  directory: "/workspace",
-  variables: { CI: "true" },
-  deadlineMs: 120_000,
-  retain: 65_536,
-  observe(channel, text) {
-    process.stdout.write(text);
-  },
-});
-```
-Arguments are passed directly, without implicit shell expansion. For shell syntax, explicitly invoke `sh -c` (inside Linux sandboxes) or the host shell. Default directory is the sandbox workspace. `stdin` supplies a string. `interactive` inherits terminal input/output by default; `terminal: { input?, output?, error? }` supplies caller-owned streams. Raw mode and cursor visibility are restored after attachment. `retain` bounds the captured tail of each stream; observers receive all output. `CommandResult` contains `status`, `stdout`, `stderr`.
-`attach({ agent?, brief?, continuation?, signal?, ask?, terminal? })` uses the adapter's terminal mode. Missing file-prompt variables are requested once per variable through the TTY or the optional async `ask(name)` callback. Existing values are preserved. Docker, Podman and host support attachment. Remote cloud adapters reject it explicitly. Both warm and one-shot results include commits, branch and workspace directory. The top-level result additionally returns disposal information.
-## Errors and recovery
-`OutpostError` has a machine-readable `code`, frozen `details`, `recovery`, and optional `cause`. `recoveryDetails(error)` retrieves recovery metadata for native errors and cancellation reasons as well, preserving their original identity. Codes: `configuration`, `process`, `timeout`, `aborted`, `workspace`, `conflict`, `prompt`, `response`, `session`, `provider`. Multiple failures can surface as `AggregateError` without losing the original causes.
-`ResponseError` adds `tag`, optional `raw` and `recovery`. Recovery records include the conversation and workspace; after collection they also include commits, transcript and log. Native main-transcript capture failure fails the dispatch. Child transcript capture errors only warn.
-Remote recovery directories contain Git bundles, binary patches and copied untracked files. A failed synchronization reports its recovery path. Do not delete it before inspecting the failure. See [Operations](operations.md).
-## Additional 1.1 contracts
-- `WorkspaceOptions.label` names generated branches and workspace directories; `hooks` and `signal` are available on standalone workspaces.
-- `SandboxOptions.includeUncommitted` explicitly seeds remote patches and untracked files; the default is committed history only.
-- `DispatchOptions.idleWarningMs` defaults to 60000; `diagnostic(message)` receives expansion-size estimates. Relative file briefs use the caller's cwd.
-- `AgentAdapter.resumable` declares repair capability. `storage?: ConversationStore` supplies locate/capture/restore; `transcriptUsage?(text)` extracts authoritative usage.
-- `conversations.native(format)` returns a store. Helpers include `locate`, `capture`, `restore`, `rewrite`, `projectKey`, `claudePath`, `directory` and `destination`.
-- Cold `DispatchResult.resume/fork` accepts `ContinuationOptions`, including a new branch, provider and lifecycle hooks. `WarmDispatchResult` accepts dispatch settings only.
-- `TransferOptions` contains optional `signal` and `deadlineMs`. `SandboxLease.upload/download` accept it as a third argument. Orchestration uses `limits.copyMs`, with a 120000 ms transfer default.
-- `reporter` renders observations with label, verbose, quiet and custom writer settings.
-- `campaign`, `CampaignOptions`, `CampaignResult`, `CampaignEvent`, `IssueOutcome`, `Issue`, `Assignment` and `Backlog` define issue delivery. See the [workflow guide](workflows.md#issue-campaigns).
-- `githubBacklog` and `beadsBacklog` accept `directory`, `label` and `deadlineMs`. Their commands receive declared project environment values.

package/docs/architecture.fr.md DELETED Viewed

@@ -1,37 +0,0 @@
-# Architecture
-[English](architecture.md)
-Outpost utilise des ports et des adapters. Le domaine décrit les capacités ; les services applicatifs coordonnent leur utilisation. Les agents et les providers de sandbox implémentent des contrats indépendants.
-| Couche              | Responsabilité                                                          |
-| ------------------- | ----------------------------------------------------------------------- |
-| `domain`            | Contrats, règles, prompts, réponses, graphes et exécution des workflows |
-| `adapters/agents`   | Commandes et protocoles propres à Claude et Codex                       |
-| `adapters/backlogs` | Accès aux issues GitHub et Beads                                        |
-| `providers`         | Allocation, commandes, transferts et libération des sandboxes           |
-| `infrastructure`    | Git, processus, fichiers, conversations et journaux                     |
-| `application`       | Cycle de vie, dispatch, campagnes et synchronisation distante           |
-| `cli`               | Commandes, initialisation et images                                     |
-Les contrats nommés et les types objets sont placés dans des fichiers `*.types.ts`, sans initialisation à l’exécution. Les paramètres par défaut, options reconnues, recettes et limites partagées sont placés dans des fichiers `*.constants.ts`. Les variables locales et valeurs calculées restent dans leur opération.
-Les points d’entrée publics sont conservés. Les façades `providers/agents.ts`, `application/outpost.ts` et `domain/ports.ts` réexportent les implémentations et contrats ; les services internes importent directement leurs dépendances.
-## Responsabilités
-- Chaque agent possède un adapter, un constructeur de commande et un décodeur d’événements. Des registres de handlers remplacent le dispatch conditionnel des protocoles. Un événement inconnu reste une observation brute.
-- Les conversations constituent un port distinct. Les stratégies Claude et Codex portent leurs conventions de stockage ; capture, restauration, recherche et réécriture sont séparées.
-- Le workspace possède son état Git. La préparation du sandbox, les opérations exclusives, le dispatch, le terminal et la fermeture ont chacun un service dédié.
-- L’exécution d’un tour, l’accumulation des événements et la surveillance des délais sont séparées. L’agrégation de consommation est une règle commune du domaine.
-- Les providers composent leurs services de préparation, commandes et transferts. Docker et Podman partagent la mécanique du moteur de conteneurs.
-- La synchronisation distante suit quatre étapes : téléchargement, validation, sauvegarde puis application. Le coordinateur conserve la révision synchronisée et les informations de récupération.
-- Les workflows séparent validation du graphe, état d’exécution, tentatives d’une tâche et ordonnancement. Les campagnes composent planification, traitement d’une issue et intégration vérifiée avant clôture.
-## Extension et vérification
-Un nouvel agent implémente `AgentAdapter` dans son propre module. Un nouveau backend implémente `SandboxProvider` et `SandboxLease`, avec annulation, délais de transfert et libération idempotente. Les contrats existants restent compatibles.
-`npm run check` vérifie l’architecture, les types, les tests unitaires et fonctionnels et la compilation. `npm run coverage` impose 80 % sur les lignes, branches et fonctions. Les modules de types, effacés à l’exécution, sont contrôlés par TypeScript et le test consommateur du package. Les handlers CLI entrent dans la couverture ; seul le point d’entrée du processus est exclu.
-La CI refuse les dépendances entre couches dans le mauvais sens, les contrats déclarés hors des fichiers de types, l’initialisation à l’exécution dans ces fichiers, les chaînes de branches alternatives et les déclarations inutilisées. Elle vérifie aussi les trois systèmes, Docker, Podman et le package installé. Le respect du SRP reste également un travail de revue.

package/docs/architecture.md DELETED Viewed

@@ -1,57 +0,0 @@
-# Architecture
-[Français](architecture.fr.md)
-Outpost uses ports and adapters. Domain contracts describe capabilities; application services coordinate their use. Concrete agents and sandbox providers implement independent ports. A new agent does not require changes to sandbox allocation, and a new provider does not require changes to agent protocols.
-| Layer               | Owns                                                                                | Dependencies                                   |
-| ------------------- | ----------------------------------------------------------------------------------- | ---------------------------------------------- |
-| `domain`            | Contracts, validation, prompts, responses, task graphs and workflow execution rules | Domain and Node primitives                     |
-| `adapters/agents`   | Claude/Codex command construction and event translation                             | Domain and infrastructure                      |
-| `adapters/backlogs` | GitHub/Beads issue access                                                           | Domain and infrastructure                      |
-| `providers`         | Sandbox allocation, commands, transfers and disposal                                | Domain, infrastructure and provider services   |
-| `infrastructure`    | Git, processes, files, native transcript storage and logging                        | Domain and infrastructure                      |
-| `application`       | Resource ownership, use cases, campaigns and remote synchronization                 | Domain, adapters, providers and infrastructure |
-| `cli`               | Argument handling, onboarding and image commands                                    | Application and adapters                       |
-## Contracts and configuration
-Named contracts and object type declarations live in dedicated `*.types.ts` files next to their owner. These modules have no runtime initialization. Configuration defaults, supported options, recipes and shared limits belong in `*.constants.ts` files. Local variables and computed values stay with their operation.
-The public facade remains `src/index.ts`, with the existing `providers/*` package subpaths. Compatibility facades such as `providers/agents.ts`, `application/outpost.ts` and `domain/ports.ts` re-export implementations or contracts. Internal services import their dependencies directly.
-## Agents and conversations
-Each agent has its own factory, request builder and event decoder in `adapters/agents`. The factory composes these capabilities into `AgentAdapter`. Protocol decoding uses event-handler registries; unknown events remain raw observations.
-`ConversationStore` is a separate port. Native stores delegate filesystem conventions to Claude and Codex layout strategies. Capture, restore, discovery and structural transcript rewriting have separate services. A custom store can be supplied without changing the execution pipeline.
-## Resource lifecycle
-`application/workspace.ts` owns the host workspace. `sandbox-provision.ts` acquires and prepares a provider lease. `sandbox.ts` composes dispatch, attachment and command operations; `operation-gate.ts` enforces exclusive ownership and waits for active work during closure.
-`sandbox-dispatch.ts` owns the dispatch transaction: execution, transcript capture, synchronization, journal closure and recovery metadata. `agent-turn.ts` supervises one process; `agent-output.ts` accumulates protocol output; `activity-watchdog.ts` owns timers. Usage aggregation is a domain operation shared by warm and cold execution.
-Workspaces and sandboxes retain separate lifetimes. Cold passes allocate separate environments; warm operations reuse a lease. Cancellation, continuation, hook ordering and recovery remain part of the contract.
-## Providers and Git
-Docker and Podman share the container adapter while preflight, allocation arguments, mounts, invocation and file transfers have separate modules. Vercel and Daytona compose dedicated command and transfer services. Optional SDK loading stays in the corresponding provider entry point.
-Git infrastructure separates repository preparation, locking, managed worktree allocation, remote refresh, history collection and lease disposal. Dirty or detached worktrees remain recoverable.
-Remote synchronization follows explicit stages: download changes, validate them, back up host state, then apply changes. These services retain overlap checks, concurrent-edit detection and recovery artifacts. The coordinator owns the last synchronized revision and decides whether cleanup is safe.
-## Workflows and campaigns
-Workflow graph validation, execution state, task retries and dependency scheduling are separate domain services. Task identity controls access to dependency values. Observer errors cannot alter execution outcomes.
-Campaign orchestration composes a planner, an issue worker and an integration service. A worker implements and reviews one issue; integration verifies commits before tracker closure. The campaign owns cycle limits and outcome aggregation.
-## Extending and validating
-To add an agent, implement `AgentAdapter` in its own module, with request and event contracts tested independently. Add a conversation layout or custom store when native continuation is supported. To add a sandbox backend, implement `SandboxProvider` and `SandboxLease`, including cancellation, transfer deadlines and idempotent disposal.
-Run `npm run check` for architecture checks, type checking, unit/functional tests and the build. `npm run coverage` enforces 80% lines, branches and functions. Type-only modules are excluded from runtime coverage because TypeScript erases them; type checking and the packed consumer test validate their contracts. CLI command handlers are covered; only the process entry wrapper is excluded.
-CI rejects reversed layer dependencies, inline contract declarations, runtime initialization in type modules, chained alternative branches and unused implementation declarations. Multi-platform checks, real Docker/Podman tests and a packed-package consumer exercise the supported boundaries. These checks support architectural review; they do not mechanically prove SRP.

package/docs/migration-1.1.fr.md DELETED Viewed

@@ -1,44 +0,0 @@
-# Migrer vers la version 1.1
-La version 1.1 complète les campagnes par issue et corrige plusieurs contrats d’exécution. Voici les changements visibles depuis la version 1.0.
-| Domaine            | Comportement en 1.1                                                                                                                                                   |
-| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Boucle ponctuelle  | Chaque passe de `dispatch` acquiert une nouvelle sandbox. Utilisez `createSandbox()` pour conserver un environnement entre les passes.                                |
-| Variables          | Seul `.outpost/.env` est lu. Une valeur non vide du fichier est prioritaire ; une déclaration vide reprend la valeur du processus.                                    |
-| Prompts            | Les chemins relatifs partent du répertoire de l’appelant, même lorsque `repository` désigne un autre dossier.                                                         |
-| Hooks              | `workspaceReady` intervient dès l’ouverture du workspace. Les hooks hôte sont séquentiels ; ceux de la sandbox sont concurrents.                                      |
-| Copies             | Une entrée absente est ignorée. Les autres erreurs de copie restent bloquantes.                                                                                       |
-| Cloud              | Les commits sont envoyés par défaut. `includeUncommitted: true` ajoute les modifications et fichiers non suivis. Les copies demandées explicitement sont transférées. |
-| Branche distante   | Sans politique explicite, un workspace d’intégration est créé.                                                                                                        |
-| Tokens Claude      | `input`, `cached` et `cacheCreated` distinguent entrée non cachée, lecture et création du cache.                                                                      |
-| Événements         | `pass` et `at` identifient chaque observation. Les lignes brutes accompagnent les événements normalisés.                                                              |
-| Journaux           | Un fichier explicite est complété sans écrasement. `logging: "stdout"` affiche une progression lisible.                                                               |
-| Reprise            | Un résultat ponctuel accepte une nouvelle branche, un fournisseur et des hooks. Un résultat chaud conserve sa sandbox.                                                |
-| Réponse structurée | La balise et la capacité de réparation sont validées avant allocation. Un bloc Markdown JSON peut apparaître dans la balise.                                          |
-Le marqueur par défaut reste `<outpost>done</outpost>`. Les adaptateurs natifs restent Codex et Claude Code.
-## Campagnes et starters
-`campaign` utilise `Backlog.list/get/close`, recharge les issues à chaque cycle et ne les ferme qu’après intégration des commits dans la branche hôte. Le connecteur GitHub pagine les résultats et applique son label. Beads doit être installé sur l’hôte ; sa recette de conteneur générée inclut aussi `bd`.
-Les paramètres du starter sont `cycles`, `concurrency`, `implementationPasses` et `reviewPasses`. `planner: false` traite les issues disponibles dans l’ordre ; `reviewer: false` désactive la revue. Les rôles `planner`, `reviewer` et `merger` acceptent des adaptateurs distincts pour choisir les modèles. Les règles de développement se trouvent dans `.outpost/STANDARDS.md`.
-Un échec d’implémentation est enregistré sans interrompre les issues indépendantes. Un cycle sans commit s’arrête. Un échec de fusion conserve le travail et ne ferme aucune issue concernée. Si la fermeture chez le tracker échoue après une fusion réussie, vérifiez son état avant de relancer la campagne.
-`init` ne remplace jamais les fichiers existants : adoptez le nouveau starter manuellement ou générez-le dans un autre dossier.
-## Diagnostic et récupération
-`recoveryDetails(error)` fournit les chemins, commits et journaux disponibles sans remplacer la raison d’annulation. Un échec de préparation nettoie le workspace s’il est propre ; le travail modifié et les artefacts d’une synchronisation échouée sont conservés. Les transferts réussis sont nettoyés à la fermeture.
-`reporter({ label, verbose, quiet, write })` produit un observateur lisible. `idleWarningMs` règle les avertissements d’inactivité ; `diagnostic` reçoit l’estimation de taille des expansions de prompt. Cette estimation n’est pas un compteur de facturation.
-## Extensions
-Un adaptateur peut fournir `storage: ConversationStore`, `resumable` et `transcriptUsage`. Le service `conversations` expose chemins, recherche, capture, restauration et réécriture sélective. Chaque tour expose son propre chemin `transcript`.
-Les transferts acceptent `{ signal, deadlineMs }` ; `limits.copyMs` borne leur attente. Un fournisseur personnalisé doit réellement respecter l’annulation pour empêcher des écritures tardives. `Command.terminal` accepte les flux de l’appelant et `attach.ask` complète les variables de prompt manquantes sans terminal interactif.
-La CI vérifie Linux, Windows, macOS, Docker et Podman. Les contrats Vercel/Daytona sont testés avec des doubles SDK. Une authentification modèle et des comptes cloud distincts restent nécessaires pour les essais réels correspondants.

package/docs/migration-1.1.md DELETED Viewed

@@ -1,38 +0,0 @@
-# Migrating to 1.1
-Version 1.1 completes the issue campaign layer and corrects execution contracts. Review these observable changes when upgrading from 1.0.
-| Area              | 1.1 behavior                                                                                                                                     |
-| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Cold loops        | Each pass acquires a fresh sandbox. Use an explicit `createSandbox()` for warm multi-pass execution.                                             |
-| Environment       | Only `.outpost/.env` is loaded. Nonempty file values win; empty declarations inherit the process. Declare every key needed inside a sandbox.     |
-| Prompt files      | Relative paths resolve from the caller's working directory, even if `repository` points elsewhere.                                               |
-| Hooks             | `workspaceReady` runs at workspace creation. Host hooks are sequential; sandbox hooks run concurrently.                                          |
-| Optional inputs   | Missing `copies` entries are skipped. Other copy errors still fail.                                                                              |
-| Remote input      | Only commits are seeded by default. `includeUncommitted: true` opts into patch/untracked transfer. Selected `copies` are always explicit inputs. |
-| Remote default    | An omitted branch policy creates an integration workspace.                                                                                       |
-| Claude usage      | `input` contains uncached input; `cached` and `cacheCreated` remain separate counters.                                                           |
-| Observations      | Every public event has `pass` and `at`. Raw lines accompany normalized events. New phase, summary, result and warning events are available.      |
-| Journals          | Explicit files append across runs. `logging: "stdout"` renders human-readable progress.                                                          |
-| Continuations     | Cold result methods accept branch/provider/hook overrides. Warm result methods retain their existing sandbox and reject sandbox reconfiguration. |
-| Structured output | Opening tags and repair capability are checked before provisioning. JSON can use a Markdown code fence inside its tag.                           |
-The default completion marker remains `<outpost>done</outpost>`. Native adapters remain Codex and Claude Code.
-## Campaigns
-Regenerate starters in a new directory or manually adopt `campaign`; `init` never overwrites existing files. Campaigns use `Backlog.list/get/close`, refresh the backlog every cycle and close issues only after their commits reach the host branch. The GitHub connector paginates and applies its configured label. Beads runs on the host and must be installed there; its generated container recipe also includes `bd`.
-Set `cycles`, `concurrency`, `implementationPasses` and `reviewPasses` in the starter. `planner: false` takes ready issues in order. `reviewer: false` skips review. Set separate adapters for `planner`, `reviewer` and `merger` to choose different models.
-## Recovery and observability
-`recoveryDetails(error)` returns available branch, directory, commits, transcript and log information. It preserves cancellation reason identity. A preparation failure removes a clean owned workspace; changed workspaces and failed remote recovery files survive. Successful remote transfer staging is cleaned at close.
-`reporter({ label, verbose, quiet, write })` creates a public observation callback. `idleWarningMs` controls periodic inactivity messages; `diagnostic` receives estimated token sizes of prompt command expansions. Estimates are not billing counts.
-## Extension ports
-Custom agents can provide `storage: ConversationStore`, `resumable`, and `transcriptUsage`. `conversations` exposes native path, search, capture, restore and selective rewrite helpers. Per-turn results expose their own `transcript` path.
-Transfers accept optional `{ signal, deadlineMs }`. `limits.copyMs` bounds orchestration transfers. A custom provider must honor cancellation itself to prevent background side effects. `Command.terminal` accepts caller-owned input/output/error streams; `attach.ask` supplies missing file-prompt variables without a TTY.

package/docs/operations.md DELETED Viewed

@@ -1,101 +0,0 @@
-# Operations and releases
-## Repository topology
-GitLab is the writable source of truth:
-```text
-https://gitlab.elielaloum.com/elielaloum/outpost.git
-    push mirror → https://github.com/elie-laloum/outpost.git
-                       GitHub Actions → packages and releases
-```
-Create commits and tags on GitLab. The push mirror includes branches and tags and preserves divergent refs rather than silently overwriting them. Do not merge changes directly on GitHub; bring contributions back to GitLab. Mirror credentials belong in GitLab's protected mirror configuration, never in tracked files or local remote URLs.
-## Install a released archive
-Download the `.tgz` from [GitHub Releases](https://github.com/elie-laloum/outpost/releases), then:
-```sh
-npm install --save-dev ./elie-laloum-outpost-1.1.2.tgz
-npx outpost --help
-```
-The archive includes JavaScript, declarations, source maps, EN/FR READMEs and the license. Main imports and local/container providers have no mandatory runtime npm dependencies. Cloud SDK peers are optional and installed only when needed.
-For GitHub Packages, configure the scope in your project's `.npmrc`:
-```ini
-@elie-laloum:registry=https://npm.pkg.github.com
-```
-Authenticate to that registry using an appropriate package-read token or your organization's supported authentication flow, then install `@elie-laloum/outpost`. GitHub Packages can require authentication even for public packages. Do not commit authentication tokens. The public release archive avoids registry authentication.
-## Local development
-```sh
-npm ci
-npm run typecheck
-npm test
-npm run coverage
-npm run build
-npm run test:package
-npm run format:check
-```
-Tests use temporary Git repositories and fixture agents, so unit/functional tests require no paid model access. `test:package` installs the actual archive in a separate temporary project and checks imports and initialization. `test:container` requires `OUTPOST_CONTAINER_ENGINE=docker` or `podman` and an `outpost-ci:latest` image generated by the CLI.
-The CI matrix covers Linux, Windows and macOS. Docker and Podman jobs build the generated image, verify both native CLIs, edit/commit through mounted Git, round-trip binary files and nested directories, verify file-mount parent permissions, test output/environment handling and verify cancellation does not destroy the warm sandbox or leave a delayed writer alive. SDK contract tests cover Vercel and Daytona without provisioning cloud resources.
-Live model/cloud tests require separate provider credentials. Contract tests and CLI compatibility checks do not prove availability or model behavior in a specific paid account. Pin custom images and use account-specific smoke tests before broad deployment.
-## Release procedure
-1. Change `package.json` and `package-lock.json` to the intended stable version and update `CHANGELOG.md` on GitLab.
-2. Wait for GitHub CI on that mirrored commit to pass.
-3. Create `v<version>` on GitLab at that exact commit.
-4. The mirrored tag starts `Release`. It verifies the version, runs the complete reusable CI workflow, builds the package and publishes to GitHub Packages using its short-lived `GITHUB_TOKEN`.
-5. The workflow creates a GitHub release with the installable tarball. Confirm the package and release point to the expected version.
-The publishing job has `packages: write` and `contents: write`; ordinary CI only has `contents: read`. Checkout does not persist credentials. No long-lived package-publishing token is needed for GitHub Packages.
-For GitHub Packages, the release job sets the archive's repository metadata to the GitHub mirror so package permissions attach to that workflow repository. The tracked source manifest, writable repository and tag creation remain on GitLab.
-Optional npm publication is disabled until repository variable `NPM_PUBLISH` is `true`. Before enabling it, configure the npm package's trusted publisher for GitHub owner `elie-laloum`, repository `outpost`, workflow `release.yml`. The job uses OIDC and provenance. Account/namespace ownership and the registry's initial package setup must be completed by an authorized npm account. Enabling a variable alone does not establish that trust.
-Published package versions are immutable. If a release fails after publication, inspect the registry before rerunning to avoid duplicate publication errors; use a new patch version for changed content. Never move a released tag.
-## Recovery
-Every failure should retain enough context to inspect the workspace. `OutpostError.details` includes available paths; `recoveryDetails(error)` includes collected conversation, commit, log and workspace information without changing the error identity. Clean workspaces are removed after startup failure; dirty ones are retained. Dirty managed worktrees remain under `.outpost/workspaces`, and named branches remain after clean worktree removal.
-Remote transfer folders under `.outpost/recovery` may contain:
-- `initial.bundle` / `commits.bundle`: Git objects with original history.
-- `initial.patch` / `remote.patch` / `previous.patch`: binary-capable worktree changes.
-- `previous-index.patch`: the prior staged changes.
-- `incoming/` / `previous-files/`: untracked file copies.
-- `state.json`: synchronization endpoints and file lists.
-Inspect these before attempting recovery. Fetch a bundle into a separate recovery clone and review the patch there before applying it to valuable work. An incomplete network transfer is not guaranteed to contain every remote file; the original error identifies the failed stage. Keep the cloud sandbox accessible when performing custom manual recovery.
-Lock files record their owner PID. Active locks reject conflicting workspace use; dead owners can be recovered automatically. If a PID has been reused, verify ownership before manually deleting a lock. Avoid editing a local workspace while its remote sandbox is active.
-## Logs and credentials
-Logs are JSONL under `.outpost/logs`; prompts, text, tool events, conversation IDs and usage are recorded. Verbose mode additionally retains raw protocol events. Native transcripts use the agent's own host storage. Files can contain private data; choose retention and backup policies accordingly. Runtime folders are ignored by Git. Successful remote transfer staging is removed at closure; failed recovery artifacts and native transcripts are retained. Explicit `await sandbox.close()` is the reliable shutdown path. SIGINT/SIGTERM await registered cleanup; `process.exit()` can only perform synchronous cleanup, including container removal. Asynchronous cloud cleanup cannot be guaranteed during a forced process exit.
-Use `.outpost/.env` for task-specific secrets and `.env.example` for names only. Explicitly mount authentication files only when needed, preferably read-only. Container environment values are transported through per-command aliases, preserving the engine's own host environment and keeping values out of command arguments.
-## Troubleshooting
-| Symptom                                    | Check                                                                                      |
-| ------------------------------------------ | ------------------------------------------------------------------------------------------ |
-| Image not found or UID mismatch            | Build with the same engine, image name and UID/GID used by the provider.                   |
-| Podman cannot write the worktree           | Verify rootless user namespaces, host permissions and SELinux labels.                      |
-| Agent not authenticated                    | Check the agent API key/OAuth variable or its explicitly mounted native auth file.         |
-| Cold resume cannot find a transcript       | Confirm agent, conversation ID and `conversationHome`; capture must have succeeded.        |
-| Host changed during remote execution       | Preserve the recovery folder, resolve local edits and inspect incoming history separately. |
-| Workflow never finishes after cancellation | Ensure custom task callbacks and custom providers honor their `AbortSignal`.               |
-| Native CLI rejects a flag                  | Compare installed versions with exported `agentVersions`; rebuild a stale image.           |
-| No GitHub CI after a GitLab push           | Inspect the GitLab push mirror status and its token permissions.                           |

package/docs/providers.md DELETED Viewed

@@ -1,119 +0,0 @@
-# Sandbox providers
-| Provider       | Placement     | Terminal | File transfer     | Requirement                           |
-| -------------- | ------------- | -------- | ----------------- | ------------------------------------- |
-| Docker         | Mounted       | Yes      | Files/directories | Running Docker daemon                 |
-| Podman         | Mounted       | Yes      | Files/directories | Running Podman engine                 |
-| Host `local()` | Host checkout | Yes      | Files/directories | Native agent installed                |
-| Vercel         | Remote        | No       | Files/directories | `@vercel/sandbox`, Vercel credentials |
-| Daytona        | Remote        | No       | Files/directories | `@daytona/sdk`, Daytona credentials   |
-## Docker and Podman
-```ts
-import { docker } from "@elie-laloum/outpost/providers/docker";
-const provider = docker({
-  image: "outpost:my-repository",
-  user: { uid: 1000, gid: 1000 },
-  volumes: [
-    {
-      source: "~/.config/example",
-      target: "/home/agent/.config/example",
-      readOnly: true,
-    },
-  ],
-  networks: ["development"],
-  groups: [1000],
-  devices: [],
-  cpus: 2,
-  memoryMb: 4096,
-  label: "z",
-  retain: 65_536,
-  variables: {},
-});
-```
-`podman()` accepts the same options. Default image is `outpost:<normalized-repository-directory>`. Build it with the CLI. Default UID/GID match the host on POSIX and use 1000 on Windows. The image preflight reports numeric UID mismatches when the user was not explicitly overridden. Podman supports `userns: "keep-id" | false` and maps explicit UIDs/GIDs. macOS checks that Podman Machine is running. Mount sources support `~`, relative and absolute paths, and files. Relative targets resolve under `/workspace`; `~` and `~/...` resolve under the agent home. Individual file mounts must target the home: mount a directory for other destinations. Their parents are prepared for the agent UID/GID. Linux mounts use SELinux `z` by default; choose `Z` for a private label or `false` to omit labels. Windows/macOS use bind-mount syntax.
-Containers have a private ephemeral home, dropped capabilities, no-new-privileges and an init process. Only selected mounts and Git metadata are exposed. Git paths are remapped so Windows worktree pointers remain usable inside Linux. Credentials are passed through environment names rather than command-line values. A command-specific process group allows cancellation without destroying the warm environment.
-The generated image contains Git, Node.js, Python, shell utilities and both agent CLIs. Modify the Dockerfile/Containerfile to install project tools. `outpost image build --file custom.Dockerfile --image custom:tag --uid 1000 --gid 1000` selects an alternative recipe. `outpost image remove` removes only the selected image.
-## Explicit host execution
-```ts
-import { local } from "@elie-laloum/outpost/providers/local";
-const result = await dispatch({
-  agent: codex(),
-  provider: local(),
-  brief: { text: "Inspect the project." },
-});
-```
-This is unisolated execution using your OS account and environment. Install/authenticate the CLI on the host. Outpost never silently falls back to host execution if a container fails. The host adapter does not elevate privileges.
-## Vercel
-```sh
-npm install @vercel/sandbox
-```
-```ts
-import { vercel } from "@elie-laloum/outpost/providers/vercel";
-const provider = vercel({
-  create: { timeout: 30 * 60 * 1000 },
-  variables: { OPENAI_API_KEY: process.env.OPENAI_API_KEY! },
-});
-```
-`create` accepts the installed SDK's sandbox-creation options, including credentials, runtime/image, networking and resources. Credential discovery follows the SDK. `root` can override the remote workspace directory; `retain` controls captured output tails. The provider discovers the actual remote home. Outpost installs the chosen agent in a user-writable prefix if it is missing; set `bootstrap: false` on `createSandbox`/`dispatch` when managing tools yourself.
-## Daytona
-```sh
-npm install @daytona/sdk
-```
-```ts
-import { daytona } from "@elie-laloum/outpost/providers/daytona";
-const provider = daytona({
-  connection: { apiKey: process.env.DAYTONA_API_KEY },
-  create: { language: "typescript" },
-});
-```
-`connection` is the SDK client configuration. `create` accepts an image/snapshot sandbox configuration. The remote environment must provide Node.js, npm, Git, `sh` and `setsid`. `root`, `variables`, and `retain` are available. Native process sessions stream both output channels and are cleaned up after each invocation. Cancellation terminates only the command process group.
-## Remote Git transport
-Remote workspaces default to temporary integration branches and start from committed Git history. `includeUncommitted: true` explicitly sends the host patch and untracked files. Otherwise pre-existing host edits are preserved and overlapping remote edits are rejected before local mutation. Selected copied inputs are uploaded too. Each dispatch, command or terminal completion synchronizes back. New commits retain their object IDs, authors, timestamps and parent relationships. Repeated synchronization handles uncommitted work later becoming committed without duplicating commits.
-Outpost compares host state with its last synchronized state. Concurrent local edits cause a recovery error. Before applying remote changes it saves patches, untracked files and incoming commits in `.outpost/recovery`. Rewritten/non-fast-forward remote history is rejected. Relative transfer paths are validated, and local symlink-parent traversal is rejected.
-## Custom providers
-`mountedProvider({ name, variables?, acquire })` and `remoteProvider({ name, variables?, acquire })` wrap your own backend. `acquire(context)` receives repository/workspace paths, Git metadata directories, resolved variables and a signal. Return a `SandboxLease`:
-```ts
-interface SandboxLease {
-  root: string;
-  home: string;
-  invoke(command: Command): Promise<CommandResult>;
-  upload(
-    source: string,
-    destination: string,
-    options?: TransferOptions,
-  ): Promise<void>;
-  download(
-    source: string,
-    destination: string,
-    options?: TransferOptions,
-  ): Promise<void>;
-  release(): Promise<void>;
-}
-```
-`invoke` must stream output to `observe`, respect abort/deadline, and leave the lease reusable after cancellation. `release` must be idempotent. Transfer options contain `signal` and `deadlineMs`; custom transfers must stop writing after cancellation. Outpost bounds the wait, but cannot forcibly cancel arbitrary user callbacks. Cloud SDK requests already sent may finish remotely; built-in downloads check cancellation before writing returned bytes. Remote providers must support Git and file transfer; Outpost performs synchronization through those capabilities. Interactive support is optional but unsupported calls must fail clearly. Cloud factories also accept an optional connection factory for contract tests or custom SDK wiring.