@meffecta/agent 0.0.1

package/scripts/setup-infrastructure.sh

@@ -0,0 +1,263 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# One-time GCP provisioning for a deployment of the agent. Idempotent — safe to re-run.
+# See IMPLEMENTATION.md for the whole set-up, of which this is step 6.
+#
+# Give the agent a GCP project of its OWN, separate from any product project it reads:
+# this project's service account holds project-wide secret access, and the mail refresh
+# tokens here must not be readable by another system's machinery.
+#
+# Prerequisite (once, manual): create the project and link billing —
+#   gcloud projects create <PROJECT> --organization=<ORG_ID>   # or --folder
+#   gcloud billing projects link <PROJECT> --billing-account=<BILLING_ACCOUNT_ID>
+#
+# Which deployment it provisions comes from ./deployment.env (or --config <file>) —
+# see deployment.env.example. Nothing is defaulted to another deployment's project.
+
+. "$(dirname "${BASH_SOURCE[0]}")/lib/deployment.sh"
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --config) CONFIG_FILE="${2:?--config needs a file}"; shift 2 ;;
+    -h|--help) sed -n '4,25p' "$0"; exit 0 ;;
+    *) echo "Unknown argument: $1" >&2; exit 2 ;;
+  esac
+done
+
+require_gcloud
+resolve_deployment
+announce_target "Provisioning infrastructure"
+
+ACCOUNT="${ACCOUNT:-}"
+MEMORY_BUCKET="${PROJECT}-memory"
+AUDIT_BUCKET="${PROJECT}-audit"
+RUNTIME_SA_NAME="agent-runtime"
+RUNTIME_SA="${RUNTIME_SA_NAME}@${PROJECT}.iam.gserviceaccount.com"
+DEPLOY_SA_NAME="github-deployer"
+DEPLOY_SA="${DEPLOY_SA_NAME}@${PROJECT}.iam.gserviceaccount.com"
+# Deploys are not wired to the engine repo's CI: it publishes images to GHCR, and a
+# deployment rolls one out when it chooses (scripts/deploy.sh). The deployer SA +
+# Workload Identity Federation below are therefore optional — provision them only if
+# THIS deployment wants a CI deploy job of its own, from its content repo:
+#   SETUP_CI_DEPLOY=true GITHUB_REPO=meffecta/agent-home ./scripts/setup-infrastructure.sh
+SETUP_CI_DEPLOY="${SETUP_CI_DEPLOY:-false}"
+GITHUB_REPO="${GITHUB_REPO:-meffecta/agent-home}" # owner/repo a CI deploy would run from
+
+# ACCOUNT is optional: unset means whichever account gcloud is currently logged in as.
+GC="gcloud --project=${PROJECT}"
+[ -n "${ACCOUNT}" ] && GC="${GC} --account=${ACCOUNT}"
+
+echo "🔧 Enabling APIs..."
+${GC} services enable \
+  run.googleapis.com \
+  cloudbuild.googleapis.com \
+  artifactregistry.googleapis.com \
+  secretmanager.googleapis.com \
+  iamcredentials.googleapis.com \
+  cloudscheduler.googleapis.com \
+  cloudtasks.googleapis.com \
+  storage.googleapis.com \
+  gmail.googleapis.com \
+  calendar-json.googleapis.com \
+  drive.googleapis.com \
+  sheets.googleapis.com \
+  docs.googleapis.com \
+  slides.googleapis.com \
+  googleads.googleapis.com \
+  searchconsole.googleapis.com \
+  analyticsdata.googleapis.com \
+  iam.googleapis.com
+
+echo "🐳 Artifact Registry repo..."
+if ! ${GC} artifacts repositories describe "${ARTIFACT_REPO}" --location="${REGION}" &>/dev/null; then
+  ${GC} artifacts repositories create "${ARTIFACT_REPO}" --location="${REGION}" --repository-format=docker
+fi
+# The images here are a cache of ghcr.io/meffecta/agent, not an archive, so they are worth
+# expiring — see set-artifact-cleanup.sh for why that is safe and what the policy keeps.
+"$(dirname "${BASH_SOURCE[0]}")/set-artifact-cleanup.sh" ${CONFIG_FILE:+--config "${CONFIG_FILE}"} >/dev/null
+
+# --- Runtime service account (everything the agent itself can do) ---
+if ! ${GC} iam service-accounts describe "${RUNTIME_SA}" &>/dev/null; then
+  echo "🆕 Creating runtime service account: ${RUNTIME_SA}"
+  ${GC} iam service-accounts create "${RUNTIME_SA_NAME}" --display-name="Meffecta Agent"
+  for _ in $(seq 1 12); do
+    ${GC} iam service-accounts describe "${RUNTIME_SA}" &>/dev/null && break
+    sleep 5
+  done
+fi
+
+# --- Buckets: memory (mounted, agent-writable) + audit (write-once, never mounted) ---
+if ! ${GC} storage buckets describe "gs://${MEMORY_BUCKET}" &>/dev/null; then
+  echo "🆕 Creating memory bucket: ${MEMORY_BUCKET}"
+  ${GC} storage buckets create "gs://${MEMORY_BUCKET}" --location="${REGION}" --uniform-bucket-level-access
+fi
+if ! ${GC} storage buckets describe "gs://${AUDIT_BUCKET}" &>/dev/null; then
+  echo "🆕 Creating audit bucket: ${AUDIT_BUCKET} (365d retention)"
+  ${GC} storage buckets create "gs://${AUDIT_BUCKET}" --location="${REGION}" --uniform-bucket-level-access \
+    --retention-period=365d
+fi
+# Cloud Build source staging — only for a deployment that builds images in GCP rather
+# than pulling the published one. Source tarballs are transient, so a 30-day lifecycle
+# keeps it from growing.
+CLOUDBUILD_BUCKET="${PROJECT}-cloudbuild"
+if [ "${SETUP_CI_DEPLOY}" = "true" ] && ! ${GC} storage buckets describe "gs://${CLOUDBUILD_BUCKET}" &>/dev/null; then
+  echo "🆕 Creating Cloud Build staging bucket: ${CLOUDBUILD_BUCKET}"
+  ${GC} storage buckets create "gs://${CLOUDBUILD_BUCKET}" --location="${REGION}" --uniform-bucket-level-access
+  LIFECYCLE_FILE=$(mktemp)
+  printf '{"rule":[{"action":{"type":"Delete"},"condition":{"age":30}}]}' >"${LIFECYCLE_FILE}"
+  ${GC} storage buckets update "gs://${CLOUDBUILD_BUCKET}" --lifecycle-file="${LIFECYCLE_FILE}"
+  rm -f "${LIFECYCLE_FILE}"
+fi
+
+echo "🔐 Runtime IAM..."
+${GC} storage buckets add-iam-policy-binding "gs://${MEMORY_BUCKET}" \
+  --member="serviceAccount:${RUNTIME_SA}" --role="roles/storage.objectAdmin" --quiet >/dev/null
+${GC} storage buckets add-iam-policy-binding "gs://${AUDIT_BUCKET}" \
+  --member="serviceAccount:${RUNTIME_SA}" --role="roles/storage.objectCreator" --quiet >/dev/null
+${GC} projects add-iam-policy-binding "${PROJECT}" \
+  --member="serviceAccount:${RUNTIME_SA}" --role="roles/secretmanager.secretAccessor" --quiet >/dev/null
+
+PROJECT_NUMBER=$(${GC} projects describe "${PROJECT}" --format='value(projectNumber)')
+
+# --- Deployer service account + Workload Identity Federation (optional; see the flag) ---
+if [ "${SETUP_CI_DEPLOY}" = "true" ]; then
+if ! ${GC} iam service-accounts describe "${DEPLOY_SA}" &>/dev/null; then
+  echo "🆕 Creating deployer service account: ${DEPLOY_SA}"
+  ${GC} iam service-accounts create "${DEPLOY_SA_NAME}" --display-name="GitHub Actions deployer"
+  for _ in $(seq 1 12); do
+    ${GC} iam service-accounts describe "${DEPLOY_SA}" &>/dev/null && break
+    sleep 5
+  done
+fi
+for role in roles/run.admin roles/cloudbuild.builds.editor roles/artifactregistry.writer \
+  roles/storage.admin roles/serviceusage.serviceUsageConsumer; do
+  ${GC} projects add-iam-policy-binding "${PROJECT}" \
+    --member="serviceAccount:${DEPLOY_SA}" --role="${role}" --quiet >/dev/null
+done
+# Cloud Build runs as its default SA; the deployer must be allowed to hand work to it,
+# and both must be able to deploy a service that runs as the runtime SA.
+${GC} iam service-accounts add-iam-policy-binding "${RUNTIME_SA}" \
+  --member="serviceAccount:${DEPLOY_SA}" --role="roles/iam.serviceAccountUser" --quiet >/dev/null
+CLOUDBUILD_SA="${PROJECT_NUMBER}-compute@developer.gserviceaccount.com"
+${GC} iam service-accounts add-iam-policy-binding "${RUNTIME_SA}" \
+  --member="serviceAccount:${CLOUDBUILD_SA}" --role="roles/iam.serviceAccountUser" --quiet >/dev/null
+# `gcloud builds submit` runs the build as the default compute SA: the deployer must be
+# allowed to act as it, and it needs to read staged source, push images, and deploy.
+${GC} iam service-accounts add-iam-policy-binding "${CLOUDBUILD_SA}" \
+  --member="serviceAccount:${DEPLOY_SA}" --role="roles/iam.serviceAccountUser" --quiet >/dev/null
+for role in roles/cloudbuild.builds.builder roles/artifactregistry.writer roles/run.admin; do
+  ${GC} projects add-iam-policy-binding "${PROJECT}" \
+    --member="serviceAccount:${CLOUDBUILD_SA}" --role="${role}" --quiet >/dev/null
+done
+
+POOL_ID="github-pool"
+PROVIDER_ID="github-provider"
+if ! ${GC} iam workload-identity-pools describe "${POOL_ID}" --location=global &>/dev/null; then
+  echo "🆕 Creating Workload Identity pool + provider for GitHub Actions..."
+  ${GC} iam workload-identity-pools create "${POOL_ID}" --location=global --display-name="GitHub Actions"
+fi
+if ! ${GC} iam workload-identity-pools providers describe "${PROVIDER_ID}" \
+  --location=global --workload-identity-pool="${POOL_ID}" &>/dev/null; then
+  ${GC} iam workload-identity-pools providers create-oidc "${PROVIDER_ID}" \
+    --location=global --workload-identity-pool="${POOL_ID}" \
+    --display-name="GitHub OIDC" \
+    --issuer-uri="https://token.actions.githubusercontent.com" \
+    --attribute-mapping="google.subject=assertion.sub,attribute.repository=assertion.repository" \
+    --attribute-condition="assertion.repository == '${GITHUB_REPO}'"
+fi
+${GC} iam service-accounts add-iam-policy-binding "${DEPLOY_SA}" \
+  --member="principalSet://iam.googleapis.com/projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/${POOL_ID}/attribute.repository/${GITHUB_REPO}" \
+  --role="roles/iam.workloadIdentityUser" --quiet >/dev/null
+else
+  echo "⏭️  Skipping deployer SA + Workload Identity Federation (SETUP_CI_DEPLOY is not true)."
+fi
+
+# --- Cloud Run service shell (placeholder image; scripts/deploy.sh rolls out a real one) ---
+if ! ${GC} run services describe "${SERVICE}" --region="${REGION}" &>/dev/null; then
+  echo "🆕 Creating Cloud Run service: ${SERVICE}"
+  ${GC} run services deploy "${SERVICE}" --region="${REGION}" \
+    --image="gcr.io/cloudrun/hello" --allow-unauthenticated \
+    --service-account="${RUNTIME_SA}" 2>/dev/null ||
+    ${GC} run deploy "${SERVICE}" --region="${REGION}" \
+      --image="gcr.io/cloudrun/hello" --allow-unauthenticated \
+      --service-account="${RUNTIME_SA}"
+fi
+
+echo "⚙️  Applying service settings (instances, memory volume, env)..."
+VOLUME_FLAGS=()
+if ! ${GC} run services describe "${SERVICE}" --region="${REGION}" --format=yaml 2>/dev/null | grep -q "name: memory"; then
+  VOLUME_FLAGS+=(--add-volume="name=memory,type=cloud-storage,bucket=${MEMORY_BUCKET}" --add-volume-mount="volume=memory,mount-path=/memory")
+fi
+# The runtime shape, from deployment.env (see lib/deployment.sh for the defaults) — the
+# same values deploy.sh re-asserts on every rollout, so the two never disagree.
+#
+# Scale to zero means CPU billed only while a request is open. That is affordable because
+# the service is idle almost all day, and it is only correct because nothing here fires on
+# its own: scripts/setup-scheduler.sh gives the deployment its external triggers, and every
+# run happens inside a request the handler holds open (src/keyed-runs.ts). REQUEST_TIMEOUT
+# is the ceiling on one such held request; --cpu-boost pays for the cold start each wake-up
+# costs, which for this service includes cloning the content repo. MAX_INSTANCES=1 keeps
+# every held request on one instance, which is what makes the engine's serial queue mean
+# anything.
+# The guarded array expansion keeps macOS bash 3.2 (set -u) happy when no flags are needed.
+case "${SCALING}" in
+  scale-to-zero) SCALE_FLAGS=(--min-instances=0 --cpu-throttling --cpu-boost) ;;
+  always-on) SCALE_FLAGS=(--min-instances=1 --no-cpu-throttling) ;;
+  *) echo "Unknown SCALING=\"${SCALING}\" — use scale-to-zero or always-on." >&2; exit 2 ;;
+esac
+${GC} run services update "${SERVICE}" --region="${REGION}" \
+  --service-account="${RUNTIME_SA}" \
+  --max-instances="${MAX_INSTANCES}" \
+  "${SCALE_FLAGS[@]}" \
+  --memory="${MEMORY}" --cpu="${CPU}" --timeout="${REQUEST_TIMEOUT}" \
+  --execution-environment=gen2 \
+  ${VOLUME_FLAGS[@]+"${VOLUME_FLAGS[@]}"} \
+  --update-env-vars="TIMEZONE=${TIMEZONE},AUDIT_BUCKET=${AUDIT_BUCKET}"
+
+echo ""
+echo "============================================================"
+echo "✅ Infrastructure ready. Manual steps:"
+echo ""
+echo "   1. Point this deployment at its content repo — jobs, worlds, SYSTEM.md:"
+echo "        gcloud run services update ${SERVICE} --region ${REGION} --project ${PROJECT} \\"
+echo "          --update-env-vars GIT_REPO_URL=https://github.com/<owner>/<content-repo>.git"
+echo "      GITHUB_TOKEN (below) must be able to clone it, and every repo its jobs name."
+echo ""
+echo "   2. Gmail OAuth (once): in this project's console — OAuth consent screen"
+echo "      (External, PUBLISH to production) + a Desktop-app OAuth client. Then per"
+echo "      account: node scripts/mint-gmail-token.mjs --client-id ... --client-secret ..."
+echo "      [--account <NAME>] [--readonly] (sign in as that account)."
+echo ""
+echo "   3. Create + wire the secrets:"
+echo "        printf '%s' '<value>' | gcloud secrets create <NAME> --data-file=- --project ${PROJECT}"
+echo "        gcloud run services update ${SERVICE} --region ${REGION} --project ${PROJECT} \\"
+echo "          --update-secrets '<NAME>=<NAME>:latest'"
+echo "      Required: AGENT_WEBHOOK_SECRET, CLAUDE_CODE_OAUTH_TOKEN (claude setup-token), GITHUB_TOKEN"
+echo "      Gmail:    GMAIL_CLIENT_ID, GMAIL_CLIENT_SECRET, GMAIL_REFRESH_TOKEN — and one"
+echo "                GMAIL_<NAME>_REFRESH_TOKEN per extra account (e.g. GMAIL_MEVISIO_REFRESH_TOKEN)"
+echo "      Optional: GRAFANA_LOGS_HOST/USERNAME + GRAFANA_API_KEY"
+echo "      Plain vars (--update-env-vars, not secrets): GMAIL_ADDRESS, GMAIL_<NAME>_ADDRESS"
+echo ""
+echo "   4. Roll out an engine image (the engine repo's CI publishes them to GHCR):"
+echo "        PROJECT=${PROJECT} REGION=${REGION} SERVICE=${SERVICE} ./scripts/deploy.sh"
+echo "      (defaults to the newest published image; --tag sha-<short> pins one)"
+echo "      Content changes need no deploy at all — they are live on the next run."
+echo ""
+echo "   5. Give it its triggers — the service scales to zero and fires nothing by itself:"
+echo "        ./scripts/setup-scheduler.sh"
+echo "      Creates the Cloud Tasks queue and one Cloud Scheduler job per cron: in the"
+echo "      content repo, reading the job list from the running service. Needs step 4 done"
+echo "      first, and re-run it whenever those registrations change (deploy.sh then does)."
+if [ "${SETUP_CI_DEPLOY}" = "true" ]; then
+  WIF_PROVIDER="projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/${POOL_ID}/providers/${PROVIDER_ID}"
+  echo ""
+  echo "   6. For a CI deploy from ${GITHUB_REPO} → Settings → Secrets → Actions:"
+  echo "        GCP_WORKLOAD_IDENTITY_PROVIDER = ${WIF_PROVIDER}"
+  echo "        GCP_DEPLOY_SERVICE_ACCOUNT     = ${DEPLOY_SA}"
+fi
+echo ""
+echo "   Inspect everything the agent can do:"
+echo "     gcloud projects get-iam-policy ${PROJECT} --flatten='bindings[].members' \\"
+echo "       --filter='bindings.members:${RUNTIME_SA}'"
+echo "============================================================"

package/scripts/setup-scheduler.sh

@@ -0,0 +1,287 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Give one deployment its external triggers, so its Cloud Run service can scale to zero and
+# bill CPU only while a request is open.
+#
+# An agent that drives itself needs an instance that is always awake — a timer on a
+# throttled CPU either misfires or never fires at all, and a job started in the background
+# of a response dies with it. So under `--cpu-throttling` every piece of work has to arrive
+# as a request instead. This script creates the things that send them:
+#
+#   1. A Cloud Tasks queue. It carries the triggers that must be answered immediately —
+#      webhooks, manual runs, a follow-up due in three days — back to the service as
+#      requests it can hold. The runtime service account gets enqueuer on it, and the
+#      service gets AGENT_TASKS_QUEUE + AGENT_PUBLIC_URL, which together are what put the
+#      engine in this mode.
+#   2. One Cloud Scheduler job per `cron:` in the content repo, POSTing
+#      /jobs/<name>/run?source=scheduler. Stale ones are deleted.
+#   3. A housekeeping sweep, POSTing /internal/sweep: due follow-ups, runs a dead process
+#      left behind, and the watched inboxes. Its cadence is the inbox poll interval when
+#      any job watches an inbox, hourly otherwise.
+#
+# Both retry with short backoff up to 4 times, and each attempt may take up to 1780s: the
+# handler answers 503 when a run outlives its attempt and the retry re-attaches to that same
+# run (src/keyed-runs.ts), so the chain of attempts is what keeps CPU on a long job. Four
+# attempts of ~28 minutes cover the longest run with room for a genuine failure.
+#
+# The job list comes from the running service (GET /jobs), which is the only thing that
+# knows it: the engine ships no jobs, and registrations are read from a boot-time clone of
+# the content repo. So the service must be deployed and healthy before this runs — and it
+# has to run again whenever those registrations change, which is exactly when the service
+# is restarted for them anyway. scripts/deploy.sh does it automatically.
+#
+# Usage:
+#   scripts/setup-scheduler.sh              # from the content repo (./deployment.env)
+#   scripts/setup-scheduler.sh --dry-run    # print what it would create, change nothing
+#
+# Which deployment: ./deployment.env, or --config <file>. See deployment.env.example.
+
+. "$(dirname "${BASH_SOURCE[0]}")/lib/deployment.sh"
+
+DRY_RUN=false
+QUEUE_NAME=""
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --config) CONFIG_FILE="${2:?--config needs a file}"; shift 2 ;;
+    --queue) QUEUE_NAME="${2:?--queue needs a value}"; shift 2 ;;
+    --dry-run) DRY_RUN=true; shift ;;
+    -h|--help) sed -n '3,38p' "$0"; exit 0 ;;
+    *) echo "Unknown argument: $1" >&2; exit 2 ;;
+  esac
+done
+
+require_gcloud
+command -v python3 >/dev/null || { echo "python3 is required." >&2; exit 1; }
+resolve_deployment
+announce_target "Wiring external triggers for ${SERVICE}"
+
+QUEUE="${QUEUE_NAME:-${SERVICE}-runs}"
+QUEUE_PATH="projects/${PROJECT}/locations/${REGION}/queues/${QUEUE}"
+JOB_PREFIX="${SERVICE}-job-"
+SWEEP_JOB="${SERVICE}-sweep"
+ATTEMPT_DEADLINE="1780s"
+
+GC="gcloud --project=${PROJECT}"
+[ -n "${ACCOUNT:-}" ] && GC="${GC} --account=${ACCOUNT}"
+
+# The triggers authenticate with the webhook secret, so it necessarily appears in the
+# arguments of the calls that create them — and gcloud echoes the arguments back when it
+# rejects one. Everything this script prints goes through here first.
+redact() {
+  if [ -n "${WEBHOOK_SECRET:-}" ]; then
+    printf '%s\n' "${1//${WEBHOOK_SECRET}/<secret>}"
+  else
+    printf '%s\n' "$1"
+  fi
+}
+
+# Every mutating gcloud call goes through here: --dry-run turns the whole script into a
+# description of itself. stdin is closed so a gcloud call inside a read loop cannot swallow
+# the lines the loop has not read yet. Output is captured rather than streamed so a failure
+# can be redacted before it reaches the terminal.
+run() {
+  if [ "${DRY_RUN}" = true ]; then
+    redact "   (dry run) $*"
+    return 0
+  fi
+  local out
+  if out=$("$@" </dev/null 2>&1); then
+    [ -n "${out}" ] && redact "${out}"
+    return 0
+  fi
+  redact "${out}" >&2
+  return 1
+}
+
+echo "🔧 Enabling APIs..."
+run ${GC} services enable cloudscheduler.googleapis.com cloudtasks.googleapis.com --quiet
+
+echo "🔎 Reading the deployed service..."
+SERVICE_JSON=$(${GC} run services describe "${SERVICE}" --region="${REGION}" --format=json) || {
+  echo "Could not describe ${SERVICE} in ${PROJECT}/${REGION} — deploy the engine first." >&2
+  exit 1
+}
+
+svc_field() {
+  python3 -c "
+import json, sys
+svc = json.loads(sys.stdin.read())
+spec = svc['spec']['template']['spec']
+env = {e['name']: e for e in spec['containers'][0].get('env', [])}
+what = sys.argv[1]
+if what == 'url':
+    print((env.get('AGENT_PUBLIC_URL', {}).get('value')) or svc['status']['url'])
+elif what == 'sa':
+    print(spec.get('serviceAccountName') or '')
+elif what == 'scaling':
+    ann = svc['spec']['template']['metadata'].get('annotations', {})
+    print('{}\t{}'.format(ann.get('autoscaling.knative.dev/minScale', '0'),
+                          ann.get('run.googleapis.com/cpu-throttling', 'true')))
+else:
+    e = env.get(what, {})
+    if e.get('value'):
+        print('value\t' + e['value'])
+    else:
+        ref = e.get('valueFrom', {}).get('secretKeyRef', {})
+        print('secret\t{}\t{}'.format(ref.get('name', ''), ref.get('key') or 'latest'))
+" "$1"
+}
+
+AGENT_URL=$(printf '%s' "${SERVICE_JSON}" | svc_field url)
+RUNTIME_SA=$(printf '%s' "${SERVICE_JSON}" | svc_field sa)
+if [ -z "${RUNTIME_SA}" ]; then
+  PROJECT_NUMBER=$(${GC} projects describe "${PROJECT}" --format='value(projectNumber)')
+  RUNTIME_SA="${PROJECT_NUMBER}-compute@developer.gserviceaccount.com"
+fi
+
+# The triggers authenticate with the same bearer token as everything else on this API, so
+# the secret has to be resolved — it is normally a Secret Manager reference on the service.
+SECRET_REF=$(printf '%s' "${SERVICE_JSON}" | svc_field AGENT_WEBHOOK_SECRET)
+IFS=$'\t' read -r SECRET_KIND SECRET_A SECRET_B <<<"${SECRET_REF}"
+if [ "${SECRET_KIND}" = "value" ]; then
+  WEBHOOK_SECRET="${SECRET_A}"
+elif [ "${SECRET_KIND}" = "secret" ] && [ -n "${SECRET_A}" ]; then
+  WEBHOOK_SECRET=$(${GC} secrets versions access "${SECRET_B}" --secret="${SECRET_A}")
+else
+  echo "Could not resolve AGENT_WEBHOOK_SECRET from ${SERVICE} — is it set on the service?" >&2
+  echo "  scripts/set-secret.sh AGENT_WEBHOOK_SECRET --random" >&2
+  exit 1
+fi
+[ -n "${WEBHOOK_SECRET}" ] || { echo "AGENT_WEBHOOK_SECRET resolved empty — refusing to create triggers that would 401." >&2; exit 1; }
+
+echo "   url:     ${AGENT_URL}"
+echo "   runtime: ${RUNTIME_SA}"
+
+IFS=$'\t' read -r MIN_SCALE CPU_THROTTLING <<<"$(printf '%s' "${SERVICE_JSON}" | svc_field scaling)"
+if [ "${MIN_SCALE}" != "0" ] || [ "${CPU_THROTTLING}" = "false" ]; then
+  cat >&2 <<EOF
+
+⚠️  ${SERVICE} still runs always-on (min-instances=${MIN_SCALE}, cpu-throttling=${CPU_THROTTLING}).
+   External triggers work either way, but the saving does not arrive until the service
+   scales to zero — and until then in-process timers and Cloud Scheduler would BOTH fire,
+   so every cron runs twice. The shape lives in deployment.env and deploy.sh asserts it:
+
+     SCALING=scale-to-zero        # in deployment.env, then
+     scripts/deploy.sh            # rolls it out (--dry-run to see the shape first)
+
+EOF
+fi
+
+echo "📥 Cloud Tasks queue ${QUEUE}..."
+if ! ${GC} tasks queues describe "${QUEUE}" --location="${REGION}" >/dev/null 2>&1; then
+  run ${GC} tasks queues create "${QUEUE}" --location="${REGION}" --quiet
+fi
+# max-concurrent-dispatches leaves room for several held attempts at once; the engine's own
+# queue is serial, so this bounds requests waiting, not jobs running.
+run ${GC} tasks queues update "${QUEUE}" --location="${REGION}" \
+  --max-attempts=4 --min-backoff=5s --max-backoff=30s --max-doublings=2 \
+  --max-concurrent-dispatches=8 --max-dispatches-per-second=2 --quiet
+run ${GC} tasks queues add-iam-policy-binding "${QUEUE}" --location="${REGION}" \
+  --member="serviceAccount:${RUNTIME_SA}" --role="roles/cloudtasks.enqueuer" --quiet
+
+CURRENT_QUEUE=$(printf '%s' "${SERVICE_JSON}" | svc_field AGENT_TASKS_QUEUE | cut -f2)
+CURRENT_URL=$(printf '%s' "${SERVICE_JSON}" | svc_field AGENT_PUBLIC_URL | cut -f2)
+if [ "${CURRENT_QUEUE}" != "${QUEUE_PATH}" ] || [ "${CURRENT_URL}" != "${AGENT_URL}" ]; then
+  echo "⚙️  Switching ${SERVICE} to external triggers (new revision)..."
+  run ${GC} run services update "${SERVICE}" --region="${REGION}" \
+    --update-env-vars="AGENT_TASKS_QUEUE=${QUEUE_PATH},AGENT_PUBLIC_URL=${AGENT_URL}" --quiet
+fi
+
+echo "📋 Reading the job list from ${AGENT_URL}/jobs..."
+JOBS_JSON=$(curl -fsS --max-time 300 -H "Authorization: Bearer ${WEBHOOK_SECRET}" "${AGENT_URL}/jobs") || {
+  cat >&2 <<EOF
+Could not read ${AGENT_URL}/jobs.
+
+The engine is the only thing that knows which jobs exist — it reads them from a boot-time
+clone of the content repo. So the service has to be deployed and healthy first:
+
+    curl -fsS ${AGENT_URL}/health
+    scripts/deploy.sh
+
+A first request after a scale-to-zero idle also has to wait out a cold start, which
+includes cloning the content repo.
+EOF
+  exit 1
+}
+
+# name<TAB>cron for every job that declares one. A disabled job keeps its trigger: whether
+# it runs is re-read from the content repo per run, which is what makes `disabled: true`
+# push-effective rather than a redeploy.
+CRON_JOBS=$(printf '%s' "${JOBS_JSON}" | python3 -c "
+import json, sys
+for job in json.load(sys.stdin):
+    if job.get('cron'):
+        print('{}\t{}'.format(job['name'], job['cron']))
+")
+WATCHES_INBOX=$(printf '%s' "${JOBS_JSON}" | python3 -c "
+import json, sys
+print('yes' if any(j.get('inbox') for j in json.load(sys.stdin)) else 'no')
+")
+
+HEADERS="Content-Type=application/json,Authorization=Bearer ${WEBHOOK_SECRET}"
+
+# `create http` takes --headers; `update http` insists on --update-headers for the same
+# thing. Everything else about the two calls is identical.
+upsert_job() {
+  local name="$1" schedule="$2" uri="$3"
+  local common=(
+    --location="${REGION}"
+    --schedule="${schedule}" --time-zone="${TIMEZONE}"
+    --uri="${uri}" --http-method=POST --message-body={}
+    --attempt-deadline="${ATTEMPT_DEADLINE}"
+    --max-retry-attempts=4 --min-backoff=5s --max-backoff=30s --max-doublings=2
+    --quiet
+  )
+  if ${GC} scheduler jobs describe "${name}" --location="${REGION}" >/dev/null 2>&1; then
+    run ${GC} scheduler jobs update http "${name}" "${common[@]}" --update-headers="${HEADERS}" >/dev/null
+    echo "   updated ${name}  [${schedule}]"
+  else
+    run ${GC} scheduler jobs create http "${name}" "${common[@]}" --headers="${HEADERS}" >/dev/null
+    echo "   created ${name}  [${schedule}]"
+  fi
+}
+
+echo "⏰ Cloud Scheduler jobs..."
+WANTED=""
+while IFS=$'\t' read -r name cron; do
+  [ -z "${name}" ] && continue
+  WANTED="${WANTED} ${JOB_PREFIX}${name}"
+  upsert_job "${JOB_PREFIX}${name}" "${cron}" "${AGENT_URL}/jobs/${name}/run?source=scheduler"
+done <<<"${CRON_JOBS}"
+
+# An inbox is only as fresh as the sweep that checks it, so the sweep inherits the poll
+# interval when one is being watched. With no inbox job there is nothing time-sensitive left
+# in it — due follow-ups get their own task — so hourly is enough.
+if [ "${WATCHES_INBOX}" = "yes" ]; then
+  POLL_SECONDS=$(printf '%s' "${SERVICE_JSON}" | svc_field AGENT_INBOX_POLL_SECONDS | cut -f2)
+  POLL_MINUTES=$(( (${POLL_SECONDS:-300} + 59) / 60 ))
+  [ "${POLL_MINUTES}" -lt 1 ] && POLL_MINUTES=1
+  if [ "${POLL_MINUTES}" -ge 60 ]; then
+    SWEEP_SCHEDULE="17 * * * *"
+  else
+    SWEEP_SCHEDULE="*/${POLL_MINUTES} * * * *"
+  fi
+else
+  SWEEP_SCHEDULE="17 * * * *"
+fi
+upsert_job "${SWEEP_JOB}" "${SWEEP_SCHEDULE}" "${AGENT_URL}/internal/sweep"
+
+EXISTING=$(${GC} scheduler jobs list --location="${REGION}" --format='value(ID)' | grep "^${JOB_PREFIX}" || true)
+for existing in ${EXISTING}; do
+  keep=false
+  for wanted in ${WANTED}; do
+    [ "${existing}" = "${wanted}" ] && keep=true
+  done
+  if [ "${keep}" = false ]; then
+    run ${GC} scheduler jobs delete "${existing}" --location="${REGION}" --quiet
+    echo "   deleted ${existing} (no job declares it any more)"
+  fi
+done
+
+COUNT=$(printf '%s' "${WANTED}" | wc -w | tr -d ' ')
+echo ""
+echo "✅ ${COUNT} cron trigger(s) + ${SWEEP_JOB} [${SWEEP_SCHEDULE}] in place."
+echo "   Inspect: gcloud scheduler jobs list --project ${PROJECT} --location ${REGION}"
+echo "   Sweep now: gcloud scheduler jobs run ${SWEEP_JOB} --project ${PROJECT} --location ${REGION}"

package/scripts/update-tooling.sh

@@ -0,0 +1,117 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Refresh this deployment's operator tooling from a published engine image.
+#
+# The engine's source repo is private; the image is not. Everything an operator needs —
+# these scripts, the set-up guide, the config template — ships inside
+# ghcr.io/meffecta/agent, so a deployment run by someone outside Meffecta gets its tooling
+# from the same public artifact it gets its engine from, and never needs the source.
+#
+# The tooling belongs in your content repo, committed next to jobs/ and deployment.env.
+# That is what makes a fresh clone of that repo enough to operate the deployment, and it
+# means `git diff` after this shows exactly what changed in the tooling between engine
+# versions — worth a glance before you deploy the matching image.
+#
+# Getting it the first time, when you have no scripts yet (from your content repo):
+#
+#   cid=$(docker create ghcr.io/meffecta/agent:latest) \
+#     && docker cp "$cid:/app/scripts" . \
+#     && docker rm "$cid" >/dev/null
+#
+# That is this script's job, done by hand once. Afterwards:
+#
+#   scripts/update-tooling.sh                  # match the newest published engine
+#   scripts/update-tooling.sh --tag sha-558a144  # match a specific one, e.g. what you run
+#   scripts/update-tooling.sh --dry-run        # show what would change, touch nothing
+#
+# Needs docker, which the default deploy path needs anyway (it mirrors the image into your
+# Artifact Registry). A deployment using an AR remote repository instead still needs it
+# here — once per engine version, rather than once per deploy.
+
+GHCR_IMAGE="${GHCR_IMAGE:-ghcr.io/meffecta/agent}"
+TAG="latest"
+IMAGE=""
+DRY_RUN=false
+DEST="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --tag) TAG="${2:?--tag needs a value}"; shift 2 ;;
+    --image) IMAGE="${2:?--image needs a value}"; shift 2 ;;
+    --into) DEST="${2:?--into needs a directory}"; shift 2 ;;
+    --dry-run) DRY_RUN=true; shift ;;
+    -h|--help) sed -n '3,30p' "$0"; exit 0 ;;
+    *) echo "Unknown argument: $1" >&2; exit 2 ;;
+  esac
+done
+
+command -v docker >/dev/null || {
+  echo "docker is required to read the engine image." >&2
+  exit 1
+}
+[ -n "${IMAGE}" ] || IMAGE="${GHCR_IMAGE}:${TAG}"
+
+echo "▶ Updating operator tooling"
+echo "   from: ${IMAGE}"
+echo "   into: ${DEST}"
+echo ""
+
+TMP="$(mktemp -d)"
+trap 'rm -rf "${TMP}"' EXIT
+
+# --platform pins the amd64 image Cloud Run runs; nothing here executes it, and naming
+# it keeps docker from warning about the mismatch on an arm64 laptop.
+docker pull --quiet --platform linux/amd64 "${IMAGE}" >/dev/null || {
+  echo "Could not pull ${IMAGE}. The engine image is public, so check the tag exists and" >&2
+  echo "that this host can reach ghcr.io." >&2
+  exit 1
+}
+
+CID="$(docker create --platform linux/amd64 "${IMAGE}")"
+# `docker cp` copies out as the host user, so nothing depends on the uid inside the image.
+docker cp "${CID}:/app/scripts" "${TMP}/scripts" >/dev/null
+for doc in IMPLEMENTATION.md ARCHITECTURE.md deployment.env.example; do
+  docker cp "${CID}:/app/${doc}" "${TMP}/scripts/${doc}" >/dev/null 2>&1 || true
+done
+docker rm "${CID}" >/dev/null
+
+CHANGED=0
+NEW=0
+for file in "${TMP}/scripts"/* "${TMP}/scripts"/*/*; do
+  [ -f "${file}" ] || continue
+  rel="${file#"${TMP}/scripts/"}"
+  if [ ! -f "${DEST}/${rel}" ]; then
+    echo "   + ${rel}"
+    NEW=$((NEW + 1))
+  elif ! cmp -s "${file}" "${DEST}/${rel}"; then
+    echo "   ~ ${rel}"
+    CHANGED=$((CHANGED + 1))
+  fi
+done
+
+# Anything here that the image does not carry: yours, or left over from an older engine.
+# Reported rather than removed — this directory is in your repo, not the engine's.
+for file in "${DEST}"/*.sh "${DEST}"/*.mjs; do
+  [ -f "${file}" ] || continue
+  rel="$(basename "${file}")"
+  [ -f "${TMP}/scripts/${rel}" ] || echo "   ? ${rel} (not in this engine version — yours to keep or delete)"
+done
+
+if [ "${NEW}" -eq 0 ] && [ "${CHANGED}" -eq 0 ]; then
+  echo "   already up to date"
+  exit 0
+fi
+
+echo ""
+echo "   ${NEW} new, ${CHANGED} changed"
+if [ "${DRY_RUN}" = true ]; then
+  echo "   (dry run: nothing was changed)"
+  exit 0
+fi
+
+# This script is one of the files being overwritten, and bash reads a script as it runs it.
+# exec hands the process over so nothing further is read from the file underneath us.
+echo "✅ Updated. Review with \`git diff\`, then deploy the matching engine:"
+echo "     scripts/deploy.sh${TAG:+ --tag ${TAG}}"
+exec cp -R "${TMP}/scripts/." "${DEST}/"