Preview URL を使ってはいけない理由

Signal Foundry を agent や CLI から使うとき、Preview URL を正規の base URL として扱わないでください。

何が問題か

• canonical な接続先ではない
• Preview 側の認証や保護に引っかかることがある
• 意図した環境の API / data contract とずれることがある
• 401 404 network_error に見える失敗を作りやすい

つまり、Preview URL は「ブラウザで確認する URL」であって、agent が継続利用する API base URL ではありません。

PR smoke だけ Preview を使う場合

PR の route smoke では、Vercel Deployment Protection を automation 用 bypass header で通します。通常の CLI 接続先は production のままにし、smoke script だけ Preview URL を使います。

SIGNAL_FOUNDRY_VERCEL_PROTECTION_BYPASS=<vercel-bypass-secret> \
  pnpm --filter scripts sf:cli-preview-smoke -- --pr <pr-number>

この script は .vercel/.env.preview.local または .vercel/.env.preview.pulled の Preview Supabase 設定を使い、identity smoke に必要な fixture を upsert した上で一時 API key を作成し、smoke 後に削除します。production の API key を Preview に流用しません。

secret を shell history に残したくない場合は、ローカルの ~/.config/signal-foundry/vercel-preview.env に SIGNAL_FOUNDRY_VERCEL_PROTECTION_BYPASS=... を置き、chmod 600 にしてください。この file は repository に commit しません。

正しく使う接続先

sf auth setup --base-url https://signal-foundry.app

いま Preview URL を使っているか確認する

sf auth show --json

ここで effectiveBaseUrl が Preview URL なら、切り替えてください。

切り替え手順

sf auth setup --base-url https://signal-foundry.app
sf auth show --json

job ごとに設定を分けたいなら、config path も分けてください。

export SIGNAL_FOUNDRY_CONFIG_PATH="$PWD/.signal-foundry/config.json"

失敗の見え方

Preview URL 問題は、次のように見えることがあります。

• 404 not_found
• 401 のような認証失敗
• HTML が返ってきて CLI が期待した JSON でない

原因が分かりにくいので、まず sf auth show --json で effectiveBaseUrl を見るのが最短です。