diff --git a/docs/superpowers/plans/2026-11-15-aws-phase6.md b/docs/superpowers/plans/2026-11-15-aws-phase6.md new file mode 100644 index 0000000..90d1ade --- /dev/null +++ b/docs/superpowers/plans/2026-11-15-aws-phase6.md @@ -0,0 +1,121 @@ +# AWS Host Phase 6 Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Finish the Fargate workspace feature set: EFS storage, Copy-at-connect, setup scripts, a cost estimate, and the four phase 5 deferrals (port mappings, LLM gateway sidecar, the admin's maximum workspace lifetime, quieter WIP and clone handling). + +**Architecture:** Everything builds on phase 5's shapes: one secret per project carries all project data (P1); the task definition gains a second EFS volume (EFS mode) and an optional `gateway` sidecar container; the entrypoint's `aws` mode gains a setup-script runner, a lifetime cap and a re-runnable "apply credentials" script for Copy-at-connect; the app follows clone and setup progress through the agent after connecting, forwards port mappings over the existing socat-over-attach tunnel, and prices a workspace from the AWS Pricing API. + +**Tech Stack:** Rust (aws-sdk-ecs/-efs/-secretsmanager, + aws-sdk-pricing), OpenTofu (environment module), bash entrypoint and container scripts, React/TS. + +**Spec:** `docs/superpowers/specs/2026-11-13-aws-ecs-host-design.md` (Storage, Secrets and uploads → Copy at connect, Snapshots → setup script, Multi-user accounts → Cost visibility, Lifecycle → idle auto-stop "the admin's maximum lifetime is a hard cap", Feature compatibility → port mappings and LLM gateway sidecar). Phase 5's rulings P1–P9 and R1–R11 (spec "Phase 5: rulings") still bind. + +## Decisions this plan makes (rulings) + +- **Q1. EFS mode uses a second access point mounted at `/workspace`.** Root `/triple-c///workspace` would nest inside the home access point, so it gets a sibling root: `/triple-c-workspaces//`, POSIX 1000:1000, 0700, on the user's own file system. Hybrid's home access point and symlinks stay as they are; EFS = Hybrid + `/workspace` on EFS. Store-owned field `workspace_access_point_id`. Switching EFS → Hybrid/Ephemeral leaves the workspace access point (and its files) in place until "Remove AWS resources" removes it, said in the UI. +- **Q2. Copy-at-connect keeps settings, moves credentials.** With `secrets_delivery: CopyAtConnect` the project secret still carries non-credential project data (P1) and the agent token; it drops `TRIPLEC_FILES` and every credential env pair (`SECRET_ENV_KEYS` and all custom env values). After each connect the app uploads the files to `/tmp/.host-ssh` / `/tmp/.host-ca` and an env file to `/dev/shm/triple-c/connect.env` (root, 0600) through the agent, then runs a new root script `triple-c-apply-connect` (CA install, SSH merge, git credential helper — the entrypoint's own functions, moved into `/usr/local/lib/triple-c/entrypoint-lib.sh` so both call the same code) and re-runs the clone for repos that failed. Terminal sessions the app opens add the connect env to their `ExecSpec.env`. Scheduled jobs while the app is closed don't get credentials (spec says so; the UI says so). The spec's "persist to EFS" opt-in is **not** built. +- **Q3. Setup script: AWS only, run as `claude` after the clone, before the workspace counts as ready.** Stored in `AwsWorkspaceConfig.setup_script` (≤ 32 KiB), delivered as payload key `TRIPLEC_SETUP_SCRIPT` (P1). The entrypoint writes it to `/run/triple-c-setup/script`, runs `bash -e` as `claude` (who has sudo for apt) with a 30-minute timeout after the background clone finishes, logging to `/run/triple-c-setup/log` and writing `/run/triple-c-setup/status` (`running` | `ok` | `failed `). The idle watcher treats a running setup like a running clone. +- **Q4. Start follows clone and setup.** After "Connecting…", the start command polls one new agent-side status read (`triple-c-workspace-status`, JSON of clone + setup state) every 2 s and emits each new state/log line as `container-progress` ("Cloning repos… (1/3)", "Running setup script…", last log line), until both are done or 35 minutes pass. A failed clone or setup does not fail the start: the project is Running and a warning toast carries the last lines. Project Home Overview shows the same status for AWS projects (still cloning / setup failed). +- **Q5. Cost estimate from the Pricing API, cached a day.** `pricing:GetProducts` (Resource `*`; the API has no resource-level permissions) goes into `workspace-user-tasks.json`. Prices come from the `AmazonECS` service code in `us-east-1`, filtered to the region and Fargate vCPU-hours / GB-hours / ephemeral storage GB-hours for x86 and ARM; cached on disk per region for 24 h. Spot isn't in the Pricing API: the UI shows the on-demand figure with "Spot is usually up to 70% cheaper". EFS storage isn't per-hour and isn't estimated. Shown in HostSection (as you configure) and Project Home Overview (while running). Denied or offline → "Estimate unavailable", never an error. +- **Q6. Port mappings reuse the auth bridge's tunnel.** `auth_bridge::tunnel` already forwards a host loopback port into the container over socat-over-attach, which works through the agent. Generalise `PortForward::bind` to take a host port and a container port. AWS mappings bind **loopback only** (Docker binds 0.0.0.0; the UI says so), TCP only (UDP refused for AWS projects), opened after connect and closed on stop/exit. No new `/v1/tunnel` client. +- **Q7. LLM gateway as a sidecar, opt-in per project.** `AwsWorkspaceConfig.gateway_sidecar: bool`. When on, the task definition adds a non-essential `gateway` container running the app's pinned LiteLLM image (`docker::gateway` registry ref, digest-pinned), with `memoryReservation` 512 MiB; its config YAML and keys arrive as payload keys `TRIPLEC_GATEWAY_CONFIG`, `TRIPLEC_GATEWAY_API_KEY`, `TRIPLEC_GATEWAY_MASTER_KEY` (rendered with the same `render_config` as Docker, keys via `os.environ/…` references) and the container's command writes the config to `/tmp` and starts LiteLLM on `127.0.0.1:4000`. The project must use the OpenAI-compatible backend; the app then points `ANTHROPIC_BASE_URL` at `http://127.0.0.1:4000` and `ANTHROPIC_AUTH_TOKEN` at the master key, regardless of the base URL typed for local use. The task's CPU/memory must leave room: the minimum for a sidecar project is 1 vCPU / 2 GiB (validated). +- **Q8. Lifetime cap is enforced inside the workspace (advisory), set per environment.** Environment module variable `max_workspace_hours` (0 = no cap, default 0) → record field `max_workspace_hours` (record schema stays 1; unknown-field tolerant parser already); `ENVIRONMENT_MODULE_VERSION` 1 → 2 so existing environments show "Update available". The app passes `TRIPLEC_MAX_LIFETIME_MINUTES`; the idle watcher stops the task when it's reached — WIP push first (best effort, 90 s), then stop even if the push failed — with exit status 76 (`StopKind::LifetimeCap`, toast "Stopped: the environment's maximum workspace lifetime"). The UI shows the cap in HostSection. **This is advisory**: a workspace user has sudo inside their own task and could disable it. Server-side enforcement (a scheduled Lambda that stops old tasks) is listed as a follow-up, not built. **← needs your OK in review.** +- **Q9. One WIP branch per task run, updated in place.** The branch becomes `triple-c/wip/-` (stamp written by the entrypoint at start into `/run/triple-c/run-id`; Docker/no-task fallback keeps today's per-push stamp); later pushes in the same run overwrite it (`+` refspec — the branch is ours alone), and a push whose tree equals the last one pushed for that repo in this run is skipped (tree hash kept in `/run/triple-c/wip-last/`). + +## Global Constraints + +- Everything in the phase 5 Global Constraints still holds (no `aws_config::defaults`; three tag keys only; names built in `aws/tofu_modules.rs`; no project data in task definitions — P1; container `workspace`; health check unchanged; the CPU/memory table incl. 256 → 512, 1024 or 2048 MiB; host/ boundary tests; policy + checks + README together, ≤ 6,144 characters each; three-part command registration; serde defaults with TS mirrors; live tests only through the scratchpad `awsx` wrapper, everything cleaned up, total spend cap $10). +- Docker behaviour unchanged unless a task says otherwise; every entrypoint addition gated on `TRIPLEC_HOST=aws`. +- New payload keys use the `TRIPLEC_` prefix (reserved since phase 5) and stay under the 64 KiB secret cap; the sizes add up (setup script ≤ 32 KiB + gateway config ≤ 8 KiB), so the cap error must name what is large. +- Root-run entrypoint code never follows a link the `claude` user controls (phase 5 hardening rule). + +## Review Focus + +1. A Copy-at-connect project started while the app is closed (scheduler) or before the first connect: private clones fail cleanly, the workspace still starts, and connecting later clones them — Task 6. +2. A setup script that hangs or needs input: bounded by its timeout, stdin is `/dev/null`, the start finishes with a warning, idle stop still works afterwards — Task 4. +3. A project switched between Hybrid and EFS with repos already present: no silent data loss, the UI says where the old files are — Task 3. +4. Two port mappings to the same host port, or a host port already in use on this machine: a clear per-mapping error; the other mappings still work — Task 7. +5. Pricing API slow/denied/offline: the config UI never blocks or errors — Task 9. + +--- + +### Task 1: Model and payload keys + +**Files:** `app/src-tauri/src/models/project.rs`, `app/src/lib/types.ts`, `app/src/lib/awsWorkspace.ts`, `app/src-tauri/src/commands/project_commands.rs` (store-owned fields), `storage/projects_store.rs`. + +**Interfaces — Produces:** `StorageMode::Efs`; `SecretsDelivery { SecretsManager (default), CopyAtConnect }`; `AwsWorkspaceConfig.{secrets_delivery, setup_script: Option, gateway_sidecar: bool, workspace_access_point_id: Option}` (last one store-owned; `set_aws_runtime` gains it); `validate_aws_workspace` additions: setup script ≤ 32,768 bytes and no NUL; `gateway_sidecar` requires cpu ≥ 1024 and memory ≥ 2048; TS mirrors. +- [ ] Tests: old JSON loads (`secrets_delivery` = SecretsManager, `gateway_sidecar` false, `setup_script` None); `efs` round-trips; script size limit; sidecar minimum; `workspace_access_point_id` survives `update_project`. +- [ ] Commit `feat(aws): phase 6 project settings`. + +### Task 2: Environment lifetime cap (module + record) + +**Files:** `aws/terraform/environment/{variables.tf,main.tf}`, `aws/terraform/environment/.terraform.lock.hcl` (unchanged unless providers move), `app/src-tauri/src/aws/{tofu_modules.rs,environments.rs}` (+ tests), `app/src/components/settings/hosts/DeployEnvironmentModal.tsx`, `aws/README.md`. + +**Interfaces — Produces:** variable `max_workspace_hours` (number, default 0, validation 0–168); record field `max_workspace_hours`; `EnvironmentInfo.max_workspace_hours: u32` (absent → 0); `environment_vars(env, region, &NetworkChoice, max_hours: u32)`; `ENVIRONMENT_MODULE_VERSION = 2` and `locals.template_version = 2`; deploy/update modal field "Maximum workspace lifetime (hours, 0 = none)". +- [ ] Tests: parser accepts a record without the field (0) and with it; rejects > 168; the HCL/const pinning tests updated (record field list, template version, variable); a v1 record now reads as UpdateAvailable. +- [ ] Commit `feat(aws): environments can cap workspace lifetime`. + +### Task 3: EFS storage mode + +**Files:** `aws/workspace.rs` (+ tests), `aws/tofu_modules.rs` (`workspace_access_point_root`), `aws/runtime.rs` (removal), `host/aws_host.rs` (wait for both access points), `commands/project_commands.rs` (`remove_aws_resources` and remove flow), `HostSection.tsx`, `ConfirmRemoveModal.tsx`, `awsWorkspace.ts` (`hasSavedFiles`). + +**Interfaces — Produces:** `workspace_access_point_root(owner_key, project_id) -> String` = `/triple-c-workspaces//`; `WorkspacePlan.workspace_access_point_id: Option`; second volume `workspace` mounted at `/workspace` when storage is Efs; `PreparedWorkspace.workspace_access_point_id`; removal with `discard_data` deletes both access points; the EFS segment enabled with the hint "Everything in /workspace survives a stop; git and builds are slower over NFS". +- [ ] Tests: Efs request has both volumes and mount points (home at `/mnt/triple-c-home`, workspace at `/workspace`), Hybrid unchanged (fingerprint of a Hybrid plan identical to before this task), the workspace access point is reused by root+owner+project tags, removal deletes both, switching Efs → Hybrid keeps `workspace_access_point_id` and the UI note. +- [ ] Commit `feat(aws): EFS storage mode`. + +### Task 4: Container: setup script, lifetime cap, WIP per run, status script + +**Files:** `container/entrypoint.sh`, `container/triple-c-idle-watch`, `container/triple-c-wip-push`, new `container/triple-c-workspace-status`, `container/Dockerfile` (COPY), `app/src-tauri/src/docker/aws_mode_tests.rs`, `app/src-tauri/src/aws/tasks.rs` (`LIFETIME_EXIT_CODE = 76`, `StopKind::LifetimeCap`). + +**Interfaces — Produces (env contract):** `TRIPLEC_SETUP_SCRIPT` (Q3), `TRIPLEC_MAX_LIFETIME_MINUTES` (absent = none); `/run/triple-c/run-id` = `-`; `triple-c-workspace-status` prints one JSON object `{"clone":{"done":bool,"repos":[{"folder","state"}]},"setup":{"state":"none|running|ok|failed","code":int|null,"tail":[last 20 lines]}}`; WIP branch per Q9. +- [ ] Tests (bash, existing harness): setup runs after clone `done`, as claude, stdin `/dev/null`, timeout kills a hang and records `failed 124`; idle watcher not idle while setup `running`; lifetime reached → WIP push attempted, then TERM with exit 76 even if the push failed; two pushes in one run update the same branch and an unchanged tree is skipped; status JSON shape for none/running/ok/failed; Docker mode untouched (gating test). +- [ ] `docker build ./container` (amd64) succeeds. +- [ ] Commit `feat(container): setup script, lifetime cap and one WIP branch per run`. + +### Task 5: App: payload, start follow, status UI + +**Files:** `aws/workspace.rs` (payload keys), `host/aws_host.rs` (`follow_workspace_status`), `commands/project_commands.rs` (new command `aws_workspace_status(project_id)`), `lib.rs`, `capabilities/default.json`, `tauri-commands.ts`, `components/projects/home/OverviewTab.tsx` (AWS status card), `hooks/useProjectActions.ts` (warning toast). + +**Interfaces — Consumes:** Task 1 fields, Task 2 `EnvironmentInfo.max_workspace_hours`, Task 4 status JSON. **Produces:** payload adds `TRIPLEC_SETUP_SCRIPT`, `TRIPLEC_MAX_LIFETIME_MINUTES`; `WorkspaceStatus` (Rust + TS mirror of the JSON); start emits progress per Q4 and returns `Ok` with a warning field when clone/setup failed (extend the start result or emit a `workspace-warning` event — pick one, document it in the report). +- [ ] Tests: payload contains/omits the keys; the size error names the setup script when it's the large part; follow loop (fake target returning a scripted status sequence, paused time) emits the expected progress strings, stops at done, times out at 35 min; Overview renders cloning/failed states. +- [ ] Commit `feat(aws): follow clone and setup when a workspace starts`. + +### Task 6: Copy-at-connect + +**Files:** `container/entrypoint.sh` (+ new `container/triple-c-apply-connect`, shared `container/entrypoint-lib.sh` installed at `/usr/local/lib/triple-c/`), `container/Dockerfile`, `aws/workspace.rs` (payload split), `host/aws_host.rs` (post-connect push), `commands/terminal_commands.rs` + `web_terminal/ws_handler.rs` (connect env for AWS sessions), `HostSection.tsx` (choice + warnings), tests in `docker/aws_mode_tests.rs`, `aws/workspace/tests.rs`, `host/aws_host/tests.rs`. + +**Interfaces — Produces:** `connect_credentials(project, settings) -> ConnectBundle { files: Vec<(String, Vec)>, env: Vec<(String,String)> }` (same sources as phase 5's `workspace_files` + the credential env pairs); `push_connect_bundle(target, bundle)` (uploads as root, then runs `triple-c-apply-connect`); payload for CopyAtConnect omits `TRIPLEC_FILES` and every credential key; `triple-c-apply-connect` sources `connect.env` only for itself and the clone retry, never exports it into the agent's snapshot. +- [ ] Tests: CopyAtConnect payload has no `TRIPLEC_FILES`, no `SECRET_ENV_KEYS`, no custom env values, still has the agent token and settings; `triple-c-apply-connect` installs a CA and merges SSH from freshly uploaded dirs and retries only failed clones; terminal ExecSpec for an AWS CopyAtConnect project carries the env and a SecretsManager one doesn't; the moved entrypoint functions still pass their existing tests (Docker parity). +- [ ] Commit `feat(aws): copy credentials at connect instead of storing them`. + +### Task 7: Port mappings on AWS + +**Files:** `auth_bridge/tunnel.rs` (`PortForward::bind(container, host_port, container_port, family)`), new `host/port_forwards.rs` (per-project set, open after connect, close on stop/exit/registry close), `commands/project_commands.rs`, `models/project.rs` (AWS: TCP only), `components/projects/home/config/AccessSection.tsx` + `PortMappingsEditor.tsx` (enabled on AWS with "localhost only on this machine"). + +**Interfaces — Produces:** `port_forwards::open_for(project_id, &ContainerTarget, &[PortMapping]) -> Vec }>`, `port_forwards::close(project_id)`; results surfaced as a warning toast for the failed ones. +- [ ] Tests: two mappings, one host port busy → one error, one working forward (real loopback sockets + a fake target, as the auth bridge tests do); UDP mapping refused for an AWS project; Docker path and auth bridge behaviour unchanged (existing tests). +- [ ] Commit `feat(aws): forward port mappings to AWS workspaces`. + +### Task 8: LLM gateway sidecar + +**Files:** `docker/gateway.rs` (export `registry_image_ref`, `render_config` usable without Docker), `aws/workspace.rs` (sidecar container, payload keys, fingerprint), `docker/workspace_env.rs` or `host/aws_host.rs` (base URL/auth override when the sidecar is on), `ModelSection.tsx` / `HostSection.tsx` (toggle "Run Triple-C's LLM gateway in the workspace", requires OpenAI-compatible backend and gateway models configured in Settings). + +**Interfaces — Produces:** container `gateway` (essential false, image = digest-pinned LiteLLM ref, command writes `$TRIPLEC_GATEWAY_CONFIG` to `/tmp/litellm.yaml` then `litellm --config /tmp/litellm.yaml --host 127.0.0.1 --port 4000`, `memoryReservation` 512, same awslogs group with stream prefix `…/gateway`); workspace env `ANTHROPIC_BASE_URL=http://127.0.0.1:4000`, `ANTHROPIC_AUTH_TOKEN=` when on. +- [ ] Tests: request with sidecar has two containers and the gateway gets only its three secret keys; workspace env overrides; validation refuses the toggle without gateway models / with a non-OpenAI-compatible backend; Hybrid fingerprint unchanged when the toggle is off. +- [ ] Commit `feat(aws): optional LLM gateway sidecar`. + +### Task 9: Cost estimate + +**Files:** `Cargo.toml` (+ `aws-sdk-pricing`, same features), new `aws/pricing.rs` (+ tests), `aws/policies/workspace-user-tasks.json` + `aws/policies.rs` checks + `aws/README.md`, new command `aws_cost_estimate(project_id | config)`, `HostSection.tsx`, `OverviewTab.tsx`. + +**Interfaces — Produces:** `FargateRates { vcpu_hour: f64, gb_hour: f64, storage_gb_hour: f64 }` per (region, arch); `estimate(cfg: &AwsWorkspaceConfig, rates) -> HourlyEstimate { usd_per_hour, note_spot: bool }` (ephemeral billed above 20 GiB); disk cache `/triple-c/aws-pricing/.json` with fetched-at, 24 h TTL; a `PricingApi` trait with fake for tests. +- [ ] Tests: estimate arithmetic for a few configs (pinned rates); cache hit/expiry; parse of a recorded `GetProducts` price-list JSON fixture (x86 + ARM rows); denied/timeout → `None`; policy checks for `pricing:GetProducts`. +- [ ] Commit `feat(aws): estimated hourly cost per workspace`. + +### Task 10: Live verification + +Extend `aws::live_tests::a_fargate_workspace_round_trips` (or add a second ignored test) and run it via `scripts/aws-e2e-workspace.sh`: an EFS project with a setup script (`sudo apt-get install -y jq` then a marker) and a lifetime cap set on the environment (verify the value reaches the task's environment; the cap's firing is covered by Task 4's unit tests, not waited for live); a port mapping reaching an HTTP server in the workspace; the gateway sidecar starting (health on 127.0.0.1:4000 from inside the workspace; no real model call); a Copy-at-connect start followed by a private-clone retry with a deploy key is out of scope (no credentials) — exercise the apply script with a CA file instead; one cost estimate fetched. Record results in `aws/README.md` and the spec; final inventory clean; spend recorded (< $2). + +### Task 11: Docs + +Spec: phase 6 done, rulings Q1–Q9 (and any execution rulings), Data model updated; `CLAUDE.md` (`aws/`, `host/`, container sections: second access point, Copy-at-connect script and its "never into the agent snapshot" rule, setup runner, lifetime exit code, port forwards on AWS, sidecar); `aws/README.md` (pricing permission, lifetime cap, sizes).