@deployfoundation/foundation-deploy 0.1.0

package/README.md

@@ -0,0 +1,174 @@
+# `@deployfoundation/foundation-deploy`
+
+The CDK app that deploys one Foundation instance, and `foundation-deploy`, the
+tool an instance's pipeline runs.
+
+Foundation ships **no instance file and no company configuration**. Everything
+that identifies a deployment — account, region, Slack workspace, GitHub org,
+naming prefixes, which integrations are provisioned — lives in an instance YAML
+the deployment's own repository owns. Both halves of this package take the path
+to that file and derive the rest.
+
+## The CDK app
+
+```sh
+cd packages/infra
+bunx cdk synth --all -c instanceFile=../../../my-instance/instance.yaml
+bunx cdk deploy --all -c instanceFile=/abs/path/instance.yaml -c agentImageTag=abc1234
+```
+
+Context keys:
+
+| Key | Meaning |
+| --- | --- |
+| `instanceFile` | **Required.** Path to the instance YAML, absolute or relative to the working directory. |
+| `admins` | CSV of Slack admin ids. Defaults to `admins` in the instance's runtime config. |
+| `alarmEmail` | DLQ alarm subscriber. Defaults to none. |
+| `agentImageTag` | Required when deploying the AgentCore runtime from a local build; a release names the image instead. |
+| `release` | Deploy a published release: `vX.Y.Z`. The manifest is read from `$FOUNDATION_RELEASE_DIR` or the per-version cache directory `foundation-deploy` writes. |
+| `releaseManifest` | Path to a verified release manifest, which is what `foundation-deploy --release` passes. |
+| `releaseBucket` | The Foundation release bucket the manifest's keys live in. Required in release mode (or `FOUNDATION_RELEASE_BUCKET`). |
+| `deployRuntime=false` | Bootstrap phase: every stack except the runtime. |
+| `pipelineInstanceFile` | Where the instance file sits inside the repo a CodePipeline sources, when that differs from the path given here. |
+| `vpcId`, `createVpcEndpoints`, `skipEndpoints`, `agentSubnetIds` | Network escape hatches, unchanged. |
+
+`instance.config` is resolved **relative to the instance file's own directory**,
+so an instance repository whose layout is `.foundation/{instance.yaml,config.yaml}`
+writes `config: config.yaml` and nothing else.
+
+`FOUNDATION_SKIP_BUNDLE=1` swaps every Lambda bundle for an inline stub. It is what the
+tests use and what a synth check on a host without Docker or Bun should use.
+
+## The deploy tool
+
+```sh
+bun run packages/infra/bin/foundation-deploy.ts <command> --instance <path>
+```
+
+| Command | What it does |
+| --- | --- |
+| `deploy` | Build and push the agent image, `cdk deploy --all`, refresh the runtime secret, sync config. |
+| `post-deploy` | Smoke DEFAULT, probe the persistent mount, promote `live`, smoke `live`. |
+| `config:sync` | Upload the runtime config and Foundation's product skills to S3. |
+| `setup` | First-deploy orchestration, idempotent. |
+| `github-app-create` | Create the instance's GitHub App from the shipped manifest template. |
+| `slack-manifest` | Print the instance's Slack app manifest as JSON (the Slack CLI's `get-manifest` hook contract). |
+| `stage-customization` | Validate and stage a tenant-owned runtime config. |
+
+`--instance <path>` is required for every command (or `FOUNDATION_INSTANCE_FILE`
+in a pipeline). There is no instance *name*, no `instances/` directory and no
+default: a deploy that guessed its target would be a deploy into the wrong
+account.
+
+### Deploying a release
+
+```sh
+# an instance repo's whole build step
+npx @deployfoundation/foundation-deploy@$(cat foundation.version) deploy \
+  --instance .foundation/instance.yaml
+```
+
+A copy of the tool installed from npm has no Foundation workspace to build
+from, so it deploys the release matching **its own version**: it fetches
+`releases/vX.Y.Z/manifest.json` from the Foundation release bucket, verifies
+the KMS signature and every artifact's sha256, and only then deploys. In a
+Foundation checkout the same command builds locally, as it always did.
+`--release <vX.Y.Z>`, `--manifest <path|s3://…>` and `--release-bucket <name>`
+override the choice.
+
+Until the release account exists, set `FOUNDATION_RELEASE_KMS_KEY_ARN` to the
+published signing key ARN: the tool ships no default, because trusting the
+wrong key is worse than checking nothing.
+
+### The license check
+
+`deploy` verifies the instance's `license.key` against
+`https://license.foundry41.com/v1/verify` (override with
+`FOUNDATION_LICENSE_ENDPOINT`) before it deploys, sending the key, the
+instance id and the version — nothing else. An instance with no key is
+skipped with a warning. A definite refusal stops the deploy; an unreachable
+endpoint does not, for 30 days, on the verification cached in the instance's
+own `<prefix>/license/last-verified` secret.
+
+The tool never imports the agent package. It runs in a pipeline, not in the
+agent container.
+
+## Artifacts
+
+`src/artifacts.ts` is the single place that decides where the deployed bytes
+come from, and it has two modes:
+
+- **local build** (the default). Every Lambda bundle is built from this
+  checkout at synth with the pinned Bun, and `deploy` builds and pushes the
+  agent image to the instance's own ECR first. A contributor deploys their
+  working tree this way.
+- **release**. `-c release=vX.Y.Z` (or `-c releaseManifest=<path>`) plus
+  `-c releaseBucket=<name>`: each Lambda's code is `Code.fromBucket(...)` on
+  the key the signed manifest names, and the agent image is Foundation's own
+  repository pinned by digest. Nothing is built, so the pipeline needs no
+  Docker, no Bun and no Foundation checkout.
+
+`src/release/manifest.ts` is the manifest itself — schema, builder, the
+canonical bytes a signature covers, and `verifyManifest`, which checks the KMS
+signature **before** any artifact is read and then every artifact's sha256.
+`src/release/kms.ts` is the AWS-facing half. A manifest reaching a synth has
+already been verified by `foundation-deploy`.
+
+## The release account (Foundry 41's own)
+
+`src/stacks/release-account-stack.ts` is the only stack here that is not an
+instance's. It holds what a release is published *from*: the release bucket,
+the `foundation/agent` image repository, the KMS signing key, and the OIDC
+role `.github/workflows/release.yml` assumes on a tag push. Customers appear
+in exactly one place — the account-id list that opens the bucket, the
+repository and the key.
+
+```sh
+cd packages/infra
+bunx cdk --app 'bun run bin/release-account.ts' diff FoundationRelease \
+  -c customerAccountIds=111122223333,444455556666
+bunx cdk --app 'bun run bin/release-account.ts' deploy FoundationRelease \
+  -c customerAccountIds=111122223333,444455556666
+```
+
+Deployed once, by hand, into the release account. Its outputs are the four
+repository variables the release workflow needs (`FOUNDATION_RELEASE_BUCKET`,
+`FOUNDATION_RELEASE_KMS_KEY_ARN`, `FOUNDATION_RELEASE_ROLE_ARN`, and the image
+repository), plus the signing key ARN customers verify against. Adding a
+customer is a redeploy with a longer `customerAccountIds`.
+
+## Publishing
+
+```sh
+bun run --cwd packages/infra build   # dist/, Node target, ESM
+cd packages/infra && npm pack --dry-run
+```
+
+The build bundles the three entry points — the CLI, the CDK app and the
+release-account app — into `dist/`, inlining the workspace packages (which are
+not published) and leaving every declared dependency external, so npm installs
+one `aws-cdk-lib` and both halves of the tool see it. `aws-cdk` itself is a
+dependency, not a devDependency: the tool shells out to the CDK CLI and
+resolves it through this package rather than through PATH.
+
+The tarball carries `dist/`, `src/` (the manifest templates are read from
+there at runtime), the agent image's Dockerfile, the reference buildspec and
+`cdk.json`. It does NOT carry `bin/`: those TypeScript entry points need Bun
+and the workspace, and shipping an app entry that cannot run is how a deploy
+picks the wrong one. `node dist/bin/foundation-deploy.js --help` works from an
+extracted tarball with only the runtime dependencies installed — no Bun, no
+Foundation checkout — which is exactly what an instance's pipeline has.
+
+## Tests
+
+```sh
+bun test packages/infra
+```
+
+They run under `bun test` with the rest of the repo — no jest, no ts-node. The
+snapshot test shells out to `cdk synth` for both fixtures, so it needs the
+workspace installed but no AWS credentials and no Docker.
+
+Fixtures are synthetic (`test/fixtures/`): `acme` turns every integration on,
+`beta` is a minimal instance deployed by CodePipeline. No real company appears
+anywhere in this package.

package/agent-image/Dockerfile

@@ -0,0 +1,254 @@
+# Foundation agent container for Bedrock AgentCore Runtime.
+#
+# AgentCore contract: an HTTP server on :8080 exposing POST /invocations and
+# GET /ping. Runs as a non-root user; scratch space is the session microVM's
+# ephemeral filesystem (dies with the session).
+#
+# Build from the FOUNDATION ROOT:
+#   docker build -f packages/infra/agent-image/Dockerfile .
+#
+# Pins (binding):
+#   - Bun 1.4.0   (omp's engines floor is `>=1.3.14`; pinned exact to the
+#     version that WRITES this repo's bun.lock — 1.3.14 cannot read a
+#     lockfileVersion 2 lockfile and fails the install below outright)
+#   - omp @oh-my-pi/pi-coding-agent@18.1.14 (all @oh-my-pi/pi-*@18.1.14 in
+#     lockstep; the EXACT-pin shape is enforced below against
+#     packages/agent/package.json, and the frozen lockfile pins the version itself)
+#   - Python 3.10+ for the omp `eval` tool (the bun base is trixie: 3.13)
+#   - gh 2.97.0, built from source with Go (see the gh-build stage)
+#
+# Secrets bootstrap: the container receives ONE pointer env var,
+# RUNTIME_SECRET_ID. At start, server.ts fetches that JSON secret from Secrets
+# Manager, setdefaults each key into process env (explicit env wins), and logs
+# ONLY the number of keys loaded — never key names or values.
+
+# gh version is shared by the builder stage and the runtime stage.
+# 2.71.0+ required: older gh hard-fails `gh pr view/create` under App
+# installation tokens after GitHub removed classic-Projects projectCards
+# (cli/cli#10714) — the error text mimics a permissions failure.
+ARG GH_VERSION=2.97.0
+
+# GLOBAL build args: an ARG consumed by a `FROM` must be declared BEFORE the
+# first stage. Declared after one, it belongs to that stage's scope and
+# resolves to the empty string ("base name should not be blank").
+#
+# BUN_IMAGE defaults to Docker Hub so a plain local `docker build` works with
+# no ECR access; a deploy pipeline can override it with a mirrored tag to stay
+# clear of Docker Hub's anonymous rate limit.
+ARG BUN_IMAGE=oven/bun:1.4.0-slim
+# GH_IMAGE: where the gh BINARY comes from. The default names the `gh-source`
+# stage below, so a local build compiles it; an override points at a prebuilt
+# image, and under BuildKit an unreferenced stage never runs — which takes the
+# clone and the Go module download out of the build entirely.
+ARG GH_IMAGE=gh-source
+
+# --- gh builder -------------------------------------------------------------
+# gh is BUILT, not downloaded: image scanners read the Go toolchain and module
+# versions embedded in the binary, and upstream's release artifact carries
+# whatever versions it was built with — only a rebuild can move those.
+# CGO is off and GOARCH comes from TARGETARCH, so the output is a static
+# binary for the target arch. Pulled from AWS's mirror of the Docker official
+# images rather than Docker Hub (no anonymous rate limit, no credentials).
+#
+# `--platform=$BUILDPLATFORM` pins the toolchain to the *builder's* own
+# architecture so the Go compile runs natively and cross-compiles via GOARCH,
+# instead of running under emulation on an x86 host. BUILDPLATFORM (like
+# TARGETARCH below) requires BuildKit, which Docker Desktop and the GitHub
+# runners use by default.
+FROM --platform=$BUILDPLATFORM public.ecr.aws/docker/library/golang:1.26.6-trixie AS gh-build
+ARG GH_VERSION
+# Auto-populated by buildx; the default keeps a plain `docker build` working.
+ARG TARGETARCH=arm64
+RUN git clone --depth=1 --branch "v${GH_VERSION}" https://github.com/cli/cli.git /src
+WORKDIR /src
+# x/mod v0.40.0 is the fix line; it also carries x/crypto, x/net, x/text and
+# x/tools forward. grpc v1.83.2 clears CVE-2026-84304 (unauthenticated remote
+# OOM via fragmented HTTP/2 DATA frames). `tidy` reconciles go.sum.
+RUN go get golang.org/x/mod@v0.40.0 google.golang.org/grpc@v1.83.2 \
+    && go mod tidy
+# VCS stamping stays ON: editing go.mod makes the tree dirty, so the module
+# records as `v2.97.0+dirty` — mildly ugly, but it keeps the version in the
+# binary's build info. `-buildvcs=false` would record `(devel)` and hide any
+# future cli/cli module CVE from scanners entirely.
+RUN CGO_ENABLED=0 GOOS=linux GOARCH="${TARGETARCH}" go build -trimpath \
+        -ldflags "-s -w -X github.com/cli/cli/v2/internal/build.Version=v${GH_VERSION}" \
+        -o /out/gh ./cmd/gh
+
+# The publishable shape of the above: JUST the static binary, on scratch, so a
+# mirror image and the local fallback are the same artifact built by the same
+# instructions.
+FROM scratch AS gh-source
+COPY --from=gh-build /out/gh /out/gh
+
+# --- AWS CLI builder --------------------------------------------------------
+# AWS CLI v2 from Amazon's official installer, in its own stage so the zip,
+# unzip and the installer's scratch files never reach the runtime layer.
+# v2 (not Debian's `awscli`, which is the Python v1 line) because the profile
+# below uses `credential_process`, and because v2 is the CLI every AWS doc and
+# every skill will assume. Installed size is ~230 MB; see
+# docs/capabilities/aws-readonly.md for the trade-off.
+FROM ${BUN_IMAGE} AS awscli-build
+ARG TARGETARCH=arm64
+RUN export DEBIAN_FRONTEND=noninteractive \
+    && apt-get update \
+    && apt-get install -y --no-install-recommends curl unzip ca-certificates \
+    && case "${TARGETARCH}" in \
+         arm64) AWS_ARCH=aarch64 ;; \
+         amd64) AWS_ARCH=x86_64 ;; \
+         *) echo "unsupported TARGETARCH ${TARGETARCH}" && exit 1 ;; \
+       esac \
+    && curl -fsSL "https://awscli.amazonaws.com/awscli-exe-linux-${AWS_ARCH}.zip" -o /tmp/awscliv2.zip \
+    && unzip -q /tmp/awscliv2.zip -d /tmp \
+    && /tmp/aws/install --install-dir /opt/aws-cli --bin-dir /opt/aws-cli/bin \
+    && rm -rf /tmp/aws /tmp/awscliv2.zip /var/lib/apt/lists/*
+
+# Resolve whichever of the two GH_IMAGE names. `COPY --from=gh-provider`
+# below is what makes the choice load-bearing.
+FROM ${GH_IMAGE} AS gh-provider
+
+# --- runtime ----------------------------------------------------------------
+FROM ${BUN_IMAGE}
+
+ARG FOUNDATION_GITHUB_APP_ID=0
+
+# NOTE: AWS_EC2_METADATA_DISABLED must NOT be set container-wide: AgentCore
+# vends the execution role's credentials via an IMDS-style metadata endpoint,
+# and disabling it globally leaves the container with no credentials at all.
+# AWS_EC2_METADATA_SERVICE_ENDPOINT: AgentCore serves those credentials on an
+# IMDS-compatible endpoint but exposes none of the env signals omp's
+# credential probe checks — without this pointer the omp Bedrock provider
+# refuses with "No API key found". The real IMDS control is the tool policy
+# denying 169.254.169.254, not an env var a raw curl could ignore.
+ENV AWS_EC2_METADATA_SERVICE_ENDPOINT=http://169.254.169.254 \
+    NODE_ENV=production \
+    PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    # omp env sheet: relocate the agent base to the baked container dir
+    # (models.yml/materialized config land where omp's registry reads them;
+    # ambient files like history.db stay off ~) and pin the fail-hard
+    # security overlay.
+    PI_CODING_AGENT_DIR=/opt/sky/omp-agent \
+    PI_CONFIG_FILES=/opt/sky/omp-agent/security-overlay.yml \
+    PI_NO_TITLE=1 \
+    PI_NO_PTY=1
+
+# Python for the omp eval tool (kernelMode "per-call"). The bun base is trixie
+# (Debian 13), which ships 3.13 — over the 3.10+ floor. ca-certificates for
+# TLS to Slack. curl: the git credential helper and the gh wrapper talk to the
+# loopback broker with it. poppler-utils supplies `pdftotext`, the ONLY way a
+# PDF dropped in a thread becomes readable text (files.ts shells out to it
+# rather than adding a PDF parser dependency); missing here, every PDF
+# silently degrades to a path the model cannot open.
+#
+# `upgrade` (not just `install`) is what picks up Debian security patches for
+# packages the base image baked in — without it, glibc/systemd/libcap2/liblzma5
+# stay at whatever oven/bun published. Naming the --only-upgrade set also
+# changes this layer's hash, so a rebuild re-fetches patches rather than
+# reusing a stale cached layer.
+RUN export DEBIAN_FRONTEND=noninteractive \
+    && apt-get update \
+    && apt-get upgrade -y \
+    && apt-get install -y --only-upgrade \
+        libc6 libc-bin libsystemd0 libudev1 libcap2 liblzma5 sed \
+    && apt-get install -y --no-install-recommends \
+        python3 python3-venv python3-pip ca-certificates git curl \
+        poppler-utils \
+    && ln -sf /usr/bin/python3 /usr/local/bin/python \
+    && rm -rf /var/lib/apt/lists/*
+
+# --- Ambient GitHub (github-broker.ts) --------------------------------------
+# gh CLI as /opt/sky/bin/gh-real (from the gh-provider stage above), fronted
+# by a wrapper that injects the broker's short-lived token as GH_TOKEN. git
+# authenticates through the `sky` credential helper wired in /etc/gitconfig,
+# so plain `git clone` and `gh pr create` work in the sandbox with no
+# model-facing credential tools.
+RUN mkdir -p /opt/sky/bin
+COPY --from=gh-provider /out/gh /opt/sky/bin/gh-real
+RUN /opt/sky/bin/gh-real --version
+COPY packages/infra/agent-image/bin/git-credential-sky \
+     packages/infra/agent-image/bin/gh \
+     packages/infra/agent-image/bin/aws \
+     /opt/sky/bin/
+# System-level gitconfig: github.com credentials come from the helper (git
+# resolves `helper = sky` to git-credential-sky on PATH). useHttpPath makes
+# git send the repo path in the credential request, so the helper sees which
+# repo is being authenticated. Commits attribute to the App bot identity:
+# <app-id>+<app-slug>[bot] is what links a commit to the GitHub App.
+RUN chmod 0755 /opt/sky/bin/git-credential-sky /opt/sky/bin/gh /opt/sky/bin/aws /opt/sky/bin/gh-real \
+    && printf '[credential "https://github.com"]\n\thelper = sky\n\tuseHttpPath = true\n[user]\n\tname = sky[bot]\n\temail = %s+sky[bot]@users.noreply.github.com\n' "${FOUNDATION_GITHUB_APP_ID}" > /etc/gitconfig
+# --- Ambient AWS (aws-broker.ts) --------------------------------------------
+# AWS CLI v2 as /opt/sky/bin/aws-real, fronted by the wrapper copied above.
+# /opt/sky/aws is where server.ts WRITES the generated profile file at boot,
+# one profile per configured read-only role; it is created here (owned by the
+# runtime user) because the container cannot mkdir under a root-owned /opt.
+COPY --from=awscli-build /opt/aws-cli /opt/aws-cli
+RUN ln -s /opt/aws-cli/v2/current/bin/aws /opt/sky/bin/aws-real \
+    && /opt/sky/bin/aws-real --version \
+    && mkdir -p /opt/sky/aws
+
+# /opt/sky/bin FIRST so `gh` and `aws` resolve to the wrappers, never the real
+# binaries.
+ENV PATH="/opt/sky/bin:${PATH}"
+
+# Non-root runtime user.
+RUN groupadd --gid 10001 sky \
+    && useradd --uid 10001 --gid 10001 --create-home --shell /usr/sbin/nologin sky
+
+WORKDIR /app
+
+# Workspace install with the frozen lockfile (the build context is the repo
+# root). Workspaces the agent does not run are copied as their MANIFEST ONLY:
+# `bun install --frozen-lockfile` fails with `Workspace not found` if the
+# directory is absent, and this satisfies resolution without shipping source.
+COPY package.json bun.lock bunfig.toml tsconfig.json ./
+# Every workspace the agent actually runs, in full. `bun install
+# --frozen-lockfile` fails with `Workspace not found` if a workspace the
+# lockfile names is absent, so the ones this image does NOT run are copied as
+# their MANIFEST ONLY: enough to satisfy resolution, without shipping source.
+COPY packages/core/ ./packages/core/
+COPY packages/connectors/ ./packages/connectors/
+COPY packages/runtime/ ./packages/runtime/
+COPY packages/capability-otter/ ./packages/capability-otter/
+COPY packages/capability-knock/ ./packages/capability-knock/
+COPY packages/capability-browser/ ./packages/capability-browser/
+COPY packages/capability-email/ ./packages/capability-email/
+COPY packages/capability-crm/ ./packages/capability-crm/
+COPY packages/capability-upwork/ ./packages/capability-upwork/
+COPY packages/agent/ ./packages/agent/
+# Manifest only: the gateway and every proxy are Lambdas, the newsletter is a
+# Lambda service, and the infra package is the CDK app a pipeline runs. None of
+# them executes in this container.
+COPY packages/testing/package.json ./packages/testing/package.json
+COPY packages/gateway/package.json ./packages/gateway/package.json
+COPY packages/newsletter/package.json ./packages/newsletter/package.json
+COPY packages/infra/package.json ./packages/infra/package.json
+
+# Enforce the pin's SHAPE before installing — an EXACT version, no ^/~ range.
+# Deliberately not a literal version: asserting one breaks the image build the
+# first time the pin is legitimately bumped, and package.json plus
+# --frozen-lockfile already pin the version itself.
+RUN grep -qE '"@oh-my-pi/pi-coding-agent": "[0-9]+\.[0-9]+\.[0-9]+"' packages/agent/package.json \
+    || (echo "FATAL: packages/agent must pin @oh-my-pi/pi-coding-agent to an EXACT version (no ^/~)" && exit 1)
+RUN bun install --frozen-lockfile --production
+
+# The microVM's writable workspace (repo clones, and the memory/skills
+# materialization target /workspace/.omp/).
+RUN mkdir -p /workspace && chown sky:sky /workspace
+
+# Baked omp agent base: the fail-hard security overlay, an INTENTIONAL empty
+# AGENTS.md (shadows any ambient user-level context file), and ownership for
+# the runtime user — the materializer writes models.yml here at session build
+# and would EACCES on an un-created, root-owned /opt path.
+COPY packages/infra/agent-image/security-overlay.yml /opt/sky/omp-agent/security-overlay.yml
+RUN touch /opt/sky/omp-agent/AGENTS.md \
+    && chown -R sky:sky /opt/sky/omp-agent /opt/sky/aws
+
+USER sky:sky
+
+EXPOSE 8080
+
+# Entrypoint contract (packages/agent): server.ts starts the :8080
+# /invocations + /ping server, runs the RUNTIME_SECRET_ID bootstrap (key COUNT
+# logged only), and dispatches handleAgentInvocation — including
+# {"_smoke_test": true}.
+CMD ["bun", "run", "packages/agent/src/server.ts"]

package/agent-image/bin/aws

@@ -0,0 +1,36 @@
+#!/bin/sh
+# aws wrapper for the ambient AWS path (aws-broker.ts).
+#
+# Defaults AWS_PROFILE to `self` for THIS CHILD ONLY and execs the real CLI.
+# The profile lives in the generated /opt/sky/aws/config, where its
+# `credential_process` fetches short-lived credentials for an assumed
+# READ-ONLY role from the loopback broker. `aws --profile <label>` reaches
+# any other account the instance has been given a role in.
+#
+# WHY A WRAPPER, and not `ENV AWS_PROFILE=self` in the Dockerfile: the agent
+# process shares its environment with every subprocess, and its OWN AWS SDK
+# clients (DynamoDB, S3, Secrets Manager, SQS) resolve credentials from that
+# same environment. A global AWS_PROFILE would route those WRITES through a
+# read-only role — and route the broker's own AssumeRole call back into the
+# broker. AWS_CONFIG_FILE is exported globally instead, which is safe because
+# the generated file declares no `[default]` profile: the SDK's ini step
+# finds nothing there and falls through to the execution role, as before.
+#
+# An explicit AWS_PROFILE in the environment wins (never overridden), so
+# `AWS_PROFILE=client-acme aws s3 ls` works too.
+#
+# This instance has no read-only role at all: the `aws-readonly` capability is off,
+# or no role is configured. Say so once, plainly, instead of letting every
+# command fail as an obscure credential error.
+if [ "${FOUNDATION_AWS_DISABLED:-}" = "1" ]; then
+  echo "AWS is not connected on this instance." >&2
+  exit 1
+fi
+
+# Overridable ONLY so the wrapper can be tested against a stub CLI;
+# production always uses the image's real binary.
+AWS_REAL="${FOUNDATION_AWS_REAL:-/opt/sky/bin/aws-real}"
+
+AWS_PROFILE="${AWS_PROFILE:-self}" \
+  AWS_CONFIG_FILE="${AWS_CONFIG_FILE:-/opt/sky/aws/config}" \
+  exec "$AWS_REAL" "$@"

package/agent-image/bin/gh

@@ -0,0 +1,193 @@
+#!/bin/sh
+# gh wrapper for the ambient GitHub path (github-broker.ts).
+#
+# Fetches a fresh short-lived installation token from the loopback broker
+# and execs the real gh with GH_TOKEN set, so `gh pr create`, `gh pr checks`,
+# `gh run view`, `gh api`, etc. authenticate as the channel's GitHub App.
+# The broker responds with two lines (token, then UNIX-epoch expiry) — the
+# wrapper takes line 1 only; per-invocation fetch means expiry never
+# matters here. GH_TOKEN lives ONLY in the child's env (the server scrubs
+# any inherited GitHub tokens at start). Without a broker (channel without
+# the github connector) gh runs unauthenticated — public reads still work,
+# writes fail loudly.
+#
+# REPO SCOPING: when the repository in play is knowable — an explicit GH_REPO,
+# else the checkout's github.com origin, else (fallbacks, 2026-08-30) a
+# `-R`/`--repo` flag or the `repos/<owner>/<name>/...` prefix of a `gh api`
+# endpoint — it is passed to the broker as `repo=owner/name` so the minted
+# token covers that repo ONLY, not every repo the channel can reach. A
+# repo-less READ (`gh api /orgs/...`, `gh auth status`) sends nothing and
+# gets the channel-wide token, as before.
+#
+# REPO-LESS WRITES are REFUSED (2026-08-30): a write served the channel-wide
+# token could touch every granted repo, not just the one in play. Only this
+# wrapper sees the verb — the broker sees a credential request — so the
+# wrapper classifies the invocation (`gh api` with a mutating -X/--method,
+# or body fields which imply POST; or a mutating subcommand) and, when no
+# repository could be resolved, declares it to the broker (`write=1`, which
+# refuses and logs it) and exits with a "set GH_REPO" error instead of
+# running the command. NOTE: `gh api graphql` counts as a write (it is a
+# POST and can mutate) — set GH_REPO to use it.
+#
+# An explicit GH_TOKEN in the environment wins (never overridden).
+
+# Overridable ONLY so the refusal/scoping paths can be tested against a stub
+# broker and a stub gh binary (dev-runner has the same seam); production
+# always uses the loopback default and the image's real gh.
+# This instance has no GitHub at all: the `github` capability is off, or no GitHub
+# App secret is configured. Say so once, plainly, instead of letting every
+# command fail as an obscure auth error.
+if [ "${FOUNDATION_GITHUB_DISABLED:-}" = "1" ]; then
+  echo "GitHub is not connected on this instance." >&2
+  exit 1
+fi
+
+BROKER_URL="${FOUNDATION_GH_BROKER_URL:-http://127.0.0.1:7791/git-credential}"
+GH_REAL="${FOUNDATION_GH_REAL:-/opt/sky/bin/gh-real}"
+
+# First positional token of a `gh api` invocation ($1 is "api"): the
+# endpoint. Flags that take a value are skipped WITH their value so an
+# argument like `-f state=closed` is never mistaken for the endpoint.
+api_endpoint() {
+  shift # the leading "api"
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      -X|--method|-f|-F|--field|--raw-field|-H|--header|-q|--jq|-t|--template|--input|--cache|--hostname|-p|--preview)
+        shift
+        [ $# -gt 0 ] && shift
+        ;;
+      -*) shift ;;
+      *) printf '%s' "$1"; return 0 ;;
+    esac
+  done
+  return 1
+}
+
+if [ -z "$GH_TOKEN" ] && [ -z "$GITHUB_TOKEN" ]; then
+  cmd="$1"
+
+  # --- classify write intent (only the wrapper can: the broker never sees
+  # the verb). Unknown/new subcommands classify as reads — the broker's
+  # grant intersection and GitHub's own permission checks still bound them.
+  is_write=""
+  if [ "$cmd" = "api" ]; then
+    method=""
+    has_body=""
+    want_method=""
+    for arg in "$@"; do
+      if [ -n "$want_method" ]; then method="$arg"; want_method=""; continue; fi
+      case "$arg" in
+        -X|--method) want_method=1 ;;
+        --method=*) method="${arg#--method=}" ;;
+        -X?*) method="${arg#-X}"; method="${method#=}" ;;
+        -f|-F|--field|--raw-field|--input|--field=*|--raw-field=*|--input=*|-f?*|-F?*) has_body=1 ;;
+      esac
+    done
+    if [ -n "$method" ]; then
+      case "$method" in
+        [Gg][Ee][Tt]|[Hh][Ee][Aa][Dd]) ;;
+        *) is_write=1 ;;
+      esac
+    elif [ -n "$has_body" ]; then
+      is_write=1 # gh api implies POST when body fields are supplied
+    fi
+  else
+    case "$cmd" in
+      ''|-*|auth|browse|search|status|config|alias|completion|help|version) ;;
+      *)
+        case "$2" in
+          create|delete|edit|merge|close|reopen|comment|review|ready|lock|unlock|transfer|develop|pin|unpin|upload|delete-asset|set|remove|rename|archive|unarchive|sync|enable|disable|cancel|rerun|run|dismiss|approve|update-branch|fork|link|unlink|mark-template|deploy) is_write=1 ;;
+        esac
+        ;;
+    esac
+  fi
+
+  # --- resolve the repository in play. GH_REPO, then the checkout's origin
+  # (both as before — a repo resolved yesterday is scoped identically today),
+  # then the fallbacks: -R/--repo, and a `repos/<owner>/<name>` api endpoint.
+  repo="$GH_REPO"
+  if [ -z "$repo" ]; then
+    origin="$(git config --get remote.origin.url 2>/dev/null)"
+    case "$origin" in
+      https://github.com/*) repo="${origin#https://github.com/}" ;;
+      git@github.com:*) repo="${origin#git@github.com:}" ;;
+      ssh://git@github.com/*) repo="${origin#ssh://git@github.com/}" ;;
+    esac
+    repo="${repo%.git}"
+  fi
+  if [ -z "$repo" ]; then
+    flag_repo=""
+    want_repo=""
+    for arg in "$@"; do
+      if [ -n "$want_repo" ]; then flag_repo="$arg"; want_repo=""; continue; fi
+      case "$arg" in
+        -R|--repo) want_repo=1 ;;
+        --repo=*) flag_repo="${arg#--repo=}" ;;
+        -R?*) flag_repo="${arg#-R}"; flag_repo="${flag_repo#=}" ;;
+      esac
+    done
+    case "$flag_repo" in
+      https://github.com/*) flag_repo="${flag_repo#https://github.com/}" ;;
+      github.com/*) flag_repo="${flag_repo#github.com/}" ;;
+    esac
+    flag_repo="${flag_repo%.git}"
+    case "$flag_repo" in
+      */*/*) ;; # HOST/OWNER/NAME on some other host — not brokered
+      */*) repo="$flag_repo" ;;
+    esac
+  fi
+  if [ -z "$repo" ] && [ "$cmd" = "api" ]; then
+    endpoint="$(api_endpoint "$@")"
+    endpoint="${endpoint%%\?*}"
+    endpoint="${endpoint#/}"
+    case "$endpoint" in
+      repos/*/*)
+        rest="${endpoint#repos/}"
+        owner="${rest%%/*}"
+        rest="${rest#*/}"
+        name="${rest%%/*}"
+        repo="$owner/$name"
+        ;;
+    esac
+  fi
+
+  query=""
+  case "$repo" in
+    '' | *[!A-Za-z0-9._/-]*) ;;
+    */*) query="?repo=$repo" ;;
+  esac
+
+  # FAIL CLOSED on a repo-less write: the channel-wide token must never back
+  # a mutation. The probe (`write=1`) lets the broker log and refuse it
+  # server-side; only connection-refused (curl rc=7: no broker = channel
+  # without the github connector) falls through to anonymous gh, whose
+  # writes fail at GitHub exactly as before.
+  if [ -n "$is_write" ] && [ -z "$query" ]; then
+    curl -fsS --max-time 25 --retry 2 --retry-connrefused "$BROKER_URL?write=1" >/dev/null 2>&1
+    if [ $? -ne 7 ]; then
+      echo "gh: refusing a GitHub write with no resolved repository — set GH_REPO=owner/name (or pass -R owner/name, or run inside the repository checkout) so the credential can be scoped to that one repo" >&2
+      exit 1
+    fi
+    exec "$GH_REAL" "$@"
+  fi
+
+  # FAIL CLOSED when the broker exists but misbehaves (2026-08-16): an
+  # unauthenticated fallthrough turns a broker hiccup into a misleading
+  # GitHub 404 ("PR not found") that models mistake for a missing PR or a
+  # sandbox limitation. Only connection-refused (curl rc=7: no broker =
+  # channel without the github connector) falls through to anonymous.
+  response="$(curl -fsS --max-time 25 --retry 2 --retry-connrefused "$BROKER_URL$query" 2>/dev/null)"
+  rc=$?
+  if [ $rc -eq 0 ]; then
+    token="$(printf '%s\n' "$response" | head -n 1)"
+    if [ -n "$token" ]; then
+      GH_TOKEN="$token" exec "$GH_REAL" "$@"
+    fi
+    echo "gh: credential broker returned an empty token — transient; retry shortly" >&2
+    exit 1
+  elif [ $rc -ne 7 ]; then
+    echo "gh: could not obtain GitHub credentials from broker (curl exit $rc) — transient; retry shortly" >&2
+    exit 1
+  fi
+fi
+exec "$GH_REAL" "$@"