79a958ec26
- instance.brand (env AGNES_INSTANCE_BRAND, default "Agnes") + instance.workspace_dir replace hard-coded "Agnes" / "~/Agnes" across /home, /setup, /setup-advanced, /login, /install, /me/debug, and the Claude Code clipboard setup script. Terraform-friendly env override; defaults preserve existing Agnes branding. - Explicit "create workspace folder" step on /home (OS-tabbed mkdir+cd) + same step baked into the clipboard script as step 2. Drops the implicit assumption that `agnes init --workspace .` lands in a sensibly-cd'd shell. - Final "Restart Claude Code" step in the setup script (unconditional, between connectors and Confirm) so freshly-installed plugins, MCP servers, and SessionStart hooks load on the next Claude Code session. - Asana reverted from hosted Remote MCP back to PAT + raw REST against app.asana.com/api/1.0. MCP envelope shape consumed ~5x tokens per call; the PAT path lets the agent read flat REST fields. Existing MCP registration is detected and the user is asked whether to remove it (default Y, with benefits listed: token cost, no third-party hop, no OAuth refresh dance, deterministic envelope shape). - Atlassian connector instructs picking the longest API-token expiry (today "1 year") to cut re-mint friction. No public query-parameter hook exists on id.atlassian.com to pre-select expiry, so the prompt documents the manual click and acknowledges that limitation. - Uniform ✅ / ❌ per-connector marker contract (Asana, GWS, Atlassian) for the Confirm summary to grep. Each connector now ends with a Claude-driven end-to-end test that uses Claude Code's own bash to exercise the stored credential and prints "✅ <Connector> integration verified — ..." (or the failure variant).
910 lines
45 KiB
Python
910 lines
45 KiB
Python
"""Single source of truth for the "Setup a new Claude Code" clipboard payload.
|
|
|
|
Both the JS-embedded clipboard renderer (`_claude_setup_instructions.jinja`)
|
|
and the read-only HTML preview on the dashboard and /install pages consume
|
|
these lines. Keep it in Python so there is exactly ONE place that edits.
|
|
|
|
Placeholders `{server_url}`, `{token}`, `{wheel_filename}`, and `{server_host}`
|
|
are substituted at render time. `{wheel_filename}` and `{server_host}` are
|
|
pre-substituted server-side via `resolve_lines()`; `{server_url}` and
|
|
`{token}` survive into the JS template and are filled in at click time.
|
|
|
|
`{wheel_filename}` is server-pre-substituted because `uv tool install`
|
|
validates the PEP 427 filename *in the URL path* before fetching, so a
|
|
stable alias like `agnes.whl` fails with "Must have a version" — we need
|
|
the real versioned filename inlined.
|
|
|
|
`{server_host}` is server-pre-substituted because the `git config` and
|
|
`claude plugin marketplace add` lines need the bare host (no scheme), and
|
|
the click-time JS only knows the full origin (`{server_url}`).
|
|
|
|
## Cross-platform trust strategy (when `ca_pem` is supplied)
|
|
|
|
The trust block (step 0) is the load-bearing piece. Three things bit us in
|
|
practice and the design here exists to dodge each one:
|
|
|
|
1. **rustls rejects the Agnes leaf cert as `CaUsedAsEndEntity`.** The Agnes
|
|
server's self-signed cert is simultaneously its own CA (basicConstraints
|
|
`CA:TRUE`) AND the leaf served on the wire — a setup OpenSSL tolerates
|
|
but webpki/rustls strictly refuses. So `uv tool install <https-url>`
|
|
never works against the Agnes wheel endpoint. We download the wheel via
|
|
curl first (curl uses OpenSSL, accepts the cert), then `uv tool install
|
|
--native-tls --force <local-file>` lets rustls reuse the OS trust store
|
|
for PyPI dependency resolution. No HTTPS hop through rustls touches the
|
|
Agnes host.
|
|
|
|
2. **`SSL_CERT_FILE` REPLACES the trust store, it doesn't append.** Pointing
|
|
it at `~/.agnes/ca.pem` alone breaks every Python tool that needs to
|
|
reach a public host (PyPI, GitHub) — `da` works fine because it only
|
|
talks to Agnes, but `uv run --with <pkg>` immediately fails with
|
|
`UnknownIssuer`. We materialize a combined bundle at
|
|
`~/.agnes/ca-bundle.pem` (system roots + Agnes CA) and point all
|
|
`SSL_CERT_FILE` / `REQUESTS_CA_BUNDLE` / `GIT_SSL_CAINFO` at it.
|
|
`NODE_EXTRA_CA_CERTS` keeps pointing at just `ca.pem` because Node's
|
|
semantics is *additive* (appends to bundled roots), so a single-cert
|
|
file is correct there.
|
|
|
|
3. **Bun-compiled `claude` (Windows + macOS distributions) ignores every
|
|
CA env var AND the OS trust store for marketplace HTTPS.** On macOS
|
|
arm64 the binary at `~/.local/bin/claude` is a Mach-O with a `__BUN`
|
|
segment (single-file `bun build --compile`); on Windows claude.exe is
|
|
the same shape. `strings` shows the binary recognizes
|
|
`NODE_EXTRA_CA_CERTS`, `SSL_CERT_FILE`, `REQUESTS_CA_BUNDLE`,
|
|
`CURL_CA_BUNDLE` (including a "NODE_EXTRA_CA_CERTS detected" log
|
|
string), but in practice the values never reach the TLS context — a
|
|
known limitation of Bun's compiled-binary HTTPS path. Registering the
|
|
cert in the OS trust store (Windows: `certutil -user -addstore Root`;
|
|
macOS: `security add-trusted-cert`; Linux: `update-ca-certificates` /
|
|
`update-ca-trust`) doesn't fix it on Windows or macOS either — the
|
|
binary's bundled CA list isn't refreshable from the OS store.
|
|
|
|
So the marketplace step always uses system `git clone` regardless of
|
|
platform — system git honors `GIT_SSL_CAINFO` from the combined bundle
|
|
in step 0(d). We tried having Linux attempt direct HTTPS first (where
|
|
node-based claude DOES respect `NODE_EXTRA_CA_CERTS`), but `claude
|
|
plugin marketplace add <https-url>` is broken end-to-end on every
|
|
distribution: it does succeed at downloading the marketplace.json, but
|
|
stores it as a single file. The plugin entries' `source: "./plugins/<name>"`
|
|
paths are then resolved as local filesystem paths against that file's
|
|
parent dir — and the plugin tree obviously isn't there. Only the clone
|
|
path produces a real directory tree that `plugin install` can read.
|
|
|
|
The OS trust-store registration in (c) is still done on all three
|
|
platforms because it's needed for *non-claude* native tools — e.g.
|
|
the system git fetch path itself (Schannel on Windows, Security
|
|
framework on macOS) trusts via the OS store, not via env vars.
|
|
|
|
Marketplace refresh: after the initial clone, `agnes refresh-marketplace`
|
|
incrementally `git pull`s against the same clone and runs `claude plugin
|
|
marketplace update agnes`. Credentials are injected per-pull via a
|
|
one-shot git credential helper (PAT from `~/.config/agnes/token.json`)
|
|
so the cloned repo's `origin` URL stays PAT-free at rest. The
|
|
SessionStart hook (installed by `agnes init`) calls refresh-marketplace
|
|
on every Claude Code session so changes server-side propagate
|
|
automatically.
|
|
|
|
## Step ordering
|
|
|
|
The numbered steps are arranged so that:
|
|
- All installation work (CLI, plugins) happens first, in one go.
|
|
- `agnes init` is mandatory — it bundles auth, workspace bootstrap,
|
|
CLAUDE.md fetch, and Claude Code SessionStart/End hooks into one
|
|
non-interactive call. Replaces the old `agnes auth import-token` +
|
|
`agnes auth whoami` pair.
|
|
- `agnes diagnose` runs late so it doubles as a final smoke test after
|
|
plugins are in place, instead of gating them. It is also the last
|
|
step before Confirm — the whole prompt is non-interactive, no
|
|
decision questions for the user.
|
|
|
|
Layout:
|
|
0 TLS trust block (only when ca_pem is supplied)
|
|
1 Install CLI
|
|
2 agnes init (auth + workspace bootstrap)
|
|
3 agnes catalog (smoke verify)
|
|
4 Pre-flight: git + claude
|
|
5 Marketplace (always, even with empty served stack)
|
|
6 MCP servers (Atlassian Remote MCP)
|
|
7 Diagnose
|
|
8 Confirm
|
|
|
|
The combined-bundle source uses a fallback chain so the prompt still works
|
|
on machines without the system Python `certifi`: we try (a) `python3 -c
|
|
'import certifi'`, (b) the platform's curl/openssl bundle path, (c)
|
|
`uv run --with certifi` as a network last-resort. The user explicitly
|
|
permitted that fallback chain — it's not improvising-around-a-TLS-error.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
# Marketplace name as published by app.marketplace_server.packager.
|
|
# Hard-coded here (rather than imported) to keep this module dependency-free
|
|
# and trivially testable. If the value ever drifts, the regression test
|
|
# below catches it.
|
|
_MARKETPLACE_NAME = "agnes"
|
|
|
|
|
|
def _tls_trust_block(ca_pem: str) -> list[str]:
|
|
"""Step 0 — cross-platform TLS trust bootstrap for the Agnes server.
|
|
|
|
Emitted only when the server has a non-publicly-trusted cert. Does four
|
|
things in a single numbered block (see module docstring for the full
|
|
rationale):
|
|
|
|
(a) Detect platform (Windows Git Bash / macOS / Linux) and pick the
|
|
shell rc file that the user's login shell actually reads.
|
|
`$SHELL`-driven, NOT existence-of-rc-driven — old setups put a
|
|
legacy `.bashrc` next to a default zsh shell on macOS, and the
|
|
`[ -f .bashrc ]` heuristic silently writes to the wrong file.
|
|
(b) Write the cert PEM to `~/.agnes/ca.pem` via single-quoted heredoc
|
|
(so `$` / backtick chars in real-world certs never shell-expand).
|
|
(c) Register the cert in the OS trust store (so native binaries that
|
|
bypass our env vars — claude.exe, system git's Schannel backend,
|
|
Python apps using `truststore` — still trust the host).
|
|
Idempotent: re-running just re-affirms the entry.
|
|
(d) Build a *combined* CA bundle (system roots + Agnes CA) at
|
|
`~/.agnes/ca-bundle.pem`, with a fallback chain for the system
|
|
roots source. Persist `SSL_CERT_FILE` / `REQUESTS_CA_BUNDLE` /
|
|
`GIT_SSL_CAINFO` pointing at the bundle, plus
|
|
`NODE_EXTRA_CA_CERTS` pointing at just `ca.pem` (Node
|
|
appends-not-replaces). Persistence is idempotent via a grep
|
|
guard for the `AGNES_CA_PEM_TRUST` marker.
|
|
"""
|
|
pem = ca_pem.strip()
|
|
lines: list[str] = [
|
|
"0) Trust the Agnes TLS certificate — cross-platform setup for a self-signed / private-CA host.",
|
|
"",
|
|
" (a) Detect platform + pick the shell rc file your login shell actually reads.",
|
|
" Driven by $SHELL + uname (NOT by which rc files happen to exist on disk).",
|
|
"",
|
|
" case \"$(uname -s)\" in",
|
|
" Darwin) PLATFORM=macos ;;",
|
|
" Linux) PLATFORM=linux ;;",
|
|
" MINGW*|MSYS*|CYGWIN*) PLATFORM=windows ;;",
|
|
" *) echo \"Unsupported OS: $(uname -s)\" >&2; exit 1 ;;",
|
|
" esac",
|
|
" SHELL_NAME=\"$(basename \"${SHELL:-bash}\")\"",
|
|
" case \"${SHELL_NAME}:${PLATFORM}\" in",
|
|
" zsh:*) RC=\"$HOME/.zshrc\" ;;",
|
|
" bash:macos) RC=\"$HOME/.bash_profile\" ;;",
|
|
" bash:windows|bash:linux) RC=\"$HOME/.bashrc\" ;;",
|
|
" *) RC=\"$HOME/.profile\" ;;",
|
|
" esac",
|
|
" echo \"Platform: $PLATFORM, shell: $SHELL_NAME, rc: $RC\"",
|
|
"",
|
|
" (b) Write the cert (single-quoted heredoc so $/backticks in the body don't expand):",
|
|
"",
|
|
" mkdir -p ~/.agnes",
|
|
" cat > ~/.agnes/ca.pem <<'AGNES_CA_PEM'",
|
|
]
|
|
# PEM body is flush-left: `<<'DELIM'` heredocs preserve leading whitespace,
|
|
# and any indent inside the cert breaks `openssl x509` / Python ssl parsers.
|
|
lines.extend(pem.splitlines())
|
|
lines.extend([
|
|
"AGNES_CA_PEM",
|
|
"",
|
|
" (c) Register the cert in the OS trust store. Native binaries (claude.exe,",
|
|
" system git's Schannel/Security.framework backends) read the OS store",
|
|
" and ignore our env vars — without this, the later marketplace `git",
|
|
" clone` (when plugins are configured) and any user-side git/native",
|
|
" tooling against the Agnes host will fail.",
|
|
" No admin rights needed (user-store only). Idempotent.",
|
|
"",
|
|
" case \"$PLATFORM\" in",
|
|
" windows)",
|
|
" WIN_CA=\"$(cygpath -w ~/.agnes/ca.pem)\"",
|
|
" certutil.exe -user -addstore \"Root\" \"$WIN_CA\"",
|
|
" ;;",
|
|
" macos)",
|
|
" # Will prompt once for the keychain password.",
|
|
" security add-trusted-cert -r trustRoot \\",
|
|
" -k \"$HOME/Library/Keychains/login.keychain-db\" \\",
|
|
" ~/.agnes/ca.pem",
|
|
" ;;",
|
|
" linux)",
|
|
" if command -v update-ca-certificates >/dev/null 2>&1; then",
|
|
" sudo cp ~/.agnes/ca.pem /usr/local/share/ca-certificates/agnes.crt",
|
|
" sudo update-ca-certificates",
|
|
" elif command -v update-ca-trust >/dev/null 2>&1; then",
|
|
" sudo cp ~/.agnes/ca.pem /etc/pki/ca-trust/source/anchors/agnes.crt",
|
|
" sudo update-ca-trust",
|
|
" else",
|
|
" echo \"WARN: install ~/.agnes/ca.pem into your distro's trust store manually\" >&2",
|
|
" fi",
|
|
" ;;",
|
|
" esac",
|
|
"",
|
|
" (d) Build a COMBINED CA bundle (system roots + Agnes CA) for Python tools",
|
|
" and curl. SSL_CERT_FILE *replaces* the trust store, so pointing it at",
|
|
" the Agnes CA alone would break public hosts (PyPI etc.). Source the",
|
|
" system roots from a fallback chain — the first source that produces",
|
|
" a non-empty, existing path wins. Don't abort on the first miss; that's",
|
|
" what the chain is for.",
|
|
"",
|
|
" CERTIFI_PATH=\"$(python3 -c 'import certifi; print(certifi.where())' 2>/dev/null || true)\"",
|
|
" [ -z \"$CERTIFI_PATH\" ] && CERTIFI_PATH=\"$(python -c 'import certifi; print(certifi.where())' 2>/dev/null || true)\"",
|
|
" if [ -z \"$CERTIFI_PATH\" ]; then",
|
|
" for p in /mingw64/ssl/certs/ca-bundle.crt /usr/ssl/certs/ca-bundle.crt \\",
|
|
" /etc/ssl/certs/ca-certificates.crt /etc/pki/tls/certs/ca-bundle.crt \\",
|
|
" /etc/ssl/cert.pem; do",
|
|
" [ -f \"$p\" ] && CERTIFI_PATH=\"$p\" && break",
|
|
" done",
|
|
" fi",
|
|
" if [ -z \"$CERTIFI_PATH\" ]; then",
|
|
" CERTIFI_PATH=\"$(uv run --native-tls --with certifi --no-project python -c 'import certifi; print(certifi.where())' 2>/dev/null || true)\"",
|
|
" fi",
|
|
" if [ -z \"$CERTIFI_PATH\" ] || [ ! -f \"$CERTIFI_PATH\" ]; then",
|
|
" echo \"ERROR: locate a system CA bundle. Install Python 3 + certifi and re-run.\" >&2",
|
|
" exit 1",
|
|
" fi",
|
|
" echo \"Base CA bundle: $CERTIFI_PATH\"",
|
|
" cat \"$CERTIFI_PATH\" ~/.agnes/ca.pem > ~/.agnes/ca-bundle.pem",
|
|
"",
|
|
" (e) Persist env vars in the rc file picked in (a). Idempotent — won't",
|
|
" duplicate on re-run thanks to the AGNES_CA_PEM_TRUST grep guard.",
|
|
" Note the asymmetry: SSL_CERT_FILE (and REQUESTS_CA_BUNDLE, GIT_SSL_CAINFO)",
|
|
" point at the COMBINED bundle because those tools REPLACE trust.",
|
|
" NODE_EXTRA_CA_CERTS points at just ca.pem because Node APPENDS to its",
|
|
" bundled roots.",
|
|
"",
|
|
" if ! grep -q 'AGNES_CA_PEM_TRUST' \"$RC\" 2>/dev/null; then",
|
|
" cat >> \"$RC\" <<'AGNES_RC_BLOCK'",
|
|
"# AGNES_CA_PEM_TRUST — added by Agnes setup",
|
|
"# Combined bundle (system roots + Agnes CA) for tools that REPLACE trust:",
|
|
"export SSL_CERT_FILE=\"$HOME/.agnes/ca-bundle.pem\"",
|
|
"export REQUESTS_CA_BUNDLE=\"$HOME/.agnes/ca-bundle.pem\"",
|
|
"export GIT_SSL_CAINFO=\"$HOME/.agnes/ca-bundle.pem\"",
|
|
"# Single-cert file for Node (APPENDS to bundled roots):",
|
|
"export NODE_EXTRA_CA_CERTS=\"$HOME/.agnes/ca.pem\"",
|
|
"export PATH=\"$HOME/.local/bin:$PATH\"",
|
|
"AGNES_RC_BLOCK",
|
|
" fi",
|
|
" # Apply for THIS shell too:",
|
|
" export SSL_CERT_FILE=\"$HOME/.agnes/ca-bundle.pem\"",
|
|
" export REQUESTS_CA_BUNDLE=\"$HOME/.agnes/ca-bundle.pem\"",
|
|
" export GIT_SSL_CAINFO=\"$HOME/.agnes/ca-bundle.pem\"",
|
|
" export NODE_EXTRA_CA_CERTS=\"$HOME/.agnes/ca.pem\"",
|
|
" export PATH=\"$HOME/.local/bin:$PATH\"",
|
|
"",
|
|
" IMPORTANT for the Bash tool: env vars do NOT persist between separate",
|
|
" Bash invocations. Re-export the four lines above (SSL_CERT_FILE,",
|
|
" REQUESTS_CA_BUNDLE, GIT_SSL_CAINFO, NODE_EXTRA_CA_CERTS) plus PATH at",
|
|
" the top of every later step's bash block that talks to Agnes.",
|
|
"",
|
|
])
|
|
return lines
|
|
|
|
|
|
def _install_cli_lines(*, has_ca: bool, server_url_placeholder: str = "{server_url}") -> list[str]:
|
|
"""Step 1 — install the `agnes` CLI.
|
|
|
|
When the trust block was emitted (`has_ca=True`), we MUST avoid
|
|
`uv tool install <https-url>` against the Agnes wheel endpoint:
|
|
rustls rejects the Agnes leaf cert with `CaUsedAsEndEntity`, regardless
|
|
of `--native-tls` (the rejection is at chain validation, not at trust
|
|
lookup — putting the cert in the OS store doesn't fix it). Solution:
|
|
download the wheel with `curl --cacert` (curl uses OpenSSL, no rustls),
|
|
then `uv tool install --native-tls` from the local file. PyPI deps
|
|
still resolve over HTTPS, but `--native-tls` makes uv use the OS trust
|
|
store for that path, which is fine because PyPI's CA chain is public.
|
|
|
|
When `has_ca=False`, we trust the server's cert is publicly valid, so
|
|
the simple direct install works.
|
|
"""
|
|
if has_ca:
|
|
return [
|
|
"1) Install the CLI.",
|
|
" The Agnes server's self-signed cert trips rustls' CaUsedAsEndEntity check,",
|
|
" so direct `uv tool install <https-url>` against the wheel endpoint fails",
|
|
" (even with --native-tls). Workaround: curl-then-local-install.",
|
|
"",
|
|
" If uv is missing first:",
|
|
" curl -LsSf https://astral.sh/uv/install.sh | sh",
|
|
" export PATH=\"$HOME/.local/bin:$PATH\"",
|
|
"",
|
|
" WHEEL=/tmp/{wheel_filename}",
|
|
f" curl -fsSL --cacert ~/.agnes/ca.pem -o \"$WHEEL\" {server_url_placeholder}/cli/wheel/{{wheel_filename}}",
|
|
" uv tool install --native-tls --force \"$WHEEL\"",
|
|
"",
|
|
" If `agnes --version` fails after install because ~/.local/bin is not on PATH:",
|
|
" export PATH=\"$HOME/.local/bin:$PATH\"",
|
|
" # persist: append the same line to your ~/.zshrc or ~/.bashrc",
|
|
" # (the trust block in step 0 already does this for you on first run).",
|
|
]
|
|
return [
|
|
"1) Install the CLI:",
|
|
f" uv tool install --force {server_url_placeholder}/cli/wheel/{{wheel_filename}}",
|
|
"",
|
|
" If uv is not installed yet:",
|
|
" curl -LsSf https://astral.sh/uv/install.sh | sh",
|
|
"",
|
|
" If `agnes --version` fails after install because ~/.local/bin is not on PATH:",
|
|
" export PATH=\"$HOME/.local/bin:$PATH\"",
|
|
" # persist: append the same line to your ~/.zshrc or ~/.bashrc",
|
|
]
|
|
|
|
|
|
def _init_lines(server_url_placeholder: str = "{server_url}") -> list[str]:
|
|
"""Steps 2-4 — workspace folder bootstrap, then `agnes init` + smoke verify.
|
|
|
|
Step 2 (new) explicitly creates the workspace folder and cd's into it.
|
|
Previously the script assumed Claude Code was already cd'd to a sensible
|
|
location and ran `agnes init --workspace .` against whatever that
|
|
happened to be. With the new explicit mkdir+cd the workspace path is
|
|
deterministic — `~/{workspace_dir}` — and the visible /home step block
|
|
+ this scripted step stay in lockstep.
|
|
|
|
`{workspace_dir}` and `{instance_brand}` are placeholders pre-substituted
|
|
by :func:`resolve_lines` from the operator-configured brand. Defaults
|
|
keep `~/Agnes` behavior for instances that don't set the brand knob.
|
|
|
|
`agnes init` is the workspace-rails delivery mechanism for everyone:
|
|
it authenticates with the PAT, fetches CLAUDE.md (RBAC-filtered),
|
|
writes AGNES_WORKSPACE.md (human-facing docs), installs Claude Code
|
|
SessionStart/End hooks (auto-refresh), and runs an initial `agnes pull`
|
|
so DuckDB views are ready. Subsumes the legacy `agnes auth import-token`
|
|
+ `agnes auth whoami` pair — `init` already verifies the PAT against
|
|
`/api/catalog/tables` internally, and `agnes catalog` then doubles as
|
|
a smoke verify of the data plane.
|
|
|
|
The PAT minted by `/setup` is `general` scope with a 90 d TTL, so the
|
|
init call will succeed for the operator's whole 90 d window without
|
|
re-clicking "Generate prompt".
|
|
"""
|
|
return [
|
|
"",
|
|
"2) Create the workspace folder in the user's home directory and cd into it:",
|
|
" # POSIX (macOS / Linux / WSL):",
|
|
" mkdir -p \"$HOME/{workspace_dir}\" && cd \"$HOME/{workspace_dir}\"",
|
|
" # Windows (PowerShell) — only run if the user is on Windows:",
|
|
" # New-Item -ItemType Directory -Force -Path \"$HOME\\{workspace_dir}\" | Out-Null",
|
|
" # Set-Location \"$HOME\\{workspace_dir}\"",
|
|
"",
|
|
" The remaining steps run inside this directory.",
|
|
"",
|
|
"3) Bootstrap your {instance_brand} workspace in this directory:",
|
|
f" agnes init --server-url \"{server_url_placeholder}\" --token \"{{token}}\" --workspace .",
|
|
"",
|
|
" This authenticates with the PAT, fetches your CLAUDE.md (RBAC-filtered),",
|
|
" writes AGNES_WORKSPACE.md (human-facing docs), installs Claude Code",
|
|
" SessionStart/End hooks (auto-refresh), and runs an initial `agnes pull`",
|
|
" so your DuckDB views are ready.",
|
|
"",
|
|
"4) Verify the data is queryable:",
|
|
" agnes catalog",
|
|
"",
|
|
" This should list the tables your account has grants for. Empty list",
|
|
" means your admin hasn't granted you access yet — contact them.",
|
|
"",
|
|
" Tip: type `/agnes-private` inside any Claude Code session to mark it",
|
|
" private — its transcript is skipped by `agnes push` (audit-logged to",
|
|
" `.claude/agnes-sessions-private-skipped.txt`). The statusbar shows",
|
|
" `🔒 agnes-private` while you're in a private session.",
|
|
]
|
|
|
|
|
|
def _diagnose_lines(*, diagnose_num: str) -> list[str]:
|
|
"""Diagnose step — runs AFTER the marketplace + MCP blocks.
|
|
|
|
Putting it last (instead of right after `whoami`) means it doubles as
|
|
a server-health smoke test that runs once everything else is in place,
|
|
not as a gate before them.
|
|
|
|
The bundled `agnes skills` knowledge base (markdown documents listable
|
|
via `agnes skills list` / readable via `agnes skills show <name>`) is
|
|
intentionally NOT surfaced as its own setup step (#242 dropped that
|
|
interactive prompt). Discovery happens organically when CLAUDE.md or
|
|
another skill references a specific entry (see the
|
|
`agnes skills show agnes-data-querying` mention in the CLAUDE.md
|
|
template's BigQuery section). Bulk-copying every skill into
|
|
`~/.claude/skills/agnes/` at setup time was an opinion question with
|
|
no obvious right answer; on-demand lookup is the one-size-fits-all
|
|
default.
|
|
"""
|
|
return [
|
|
"",
|
|
f"{diagnose_num}) Run diagnostics:",
|
|
" agnes diagnose",
|
|
"",
|
|
" This should print \"Overall: healthy\". `db_schema: unknown` and",
|
|
" `data: 0 tables` are NORMAL in two cases:",
|
|
" - fresh install (no tables registered yet), and",
|
|
" - non-admin roles (e.g. `analyst`) that don't have grants to read",
|
|
" the system schema even on populated instances.",
|
|
" Only flag actual yellow/red checks (api / duckdb_state / users).",
|
|
]
|
|
|
|
|
|
def _connectors_block(
|
|
step_num: str,
|
|
connector_prompts: dict[str, str],
|
|
*,
|
|
confirm_step_num: str,
|
|
) -> list[str]:
|
|
"""Per-connector interactive ask + inline prompt. Last interactive
|
|
step before Confirm.
|
|
|
|
Defaults to install (Y) — the user has to actively type "no" to skip.
|
|
Rationale: when the operator provisions a shared GWS OAuth app
|
|
(AGNES_GWS_CLIENT_ID + AGNES_GWS_CLIENT_SECRET), the GWS path runs
|
|
in ~2 minutes with zero GCP clickops; Asana + Atlassian only need
|
|
the user's own API token from their respective developer consoles —
|
|
which they need either way to use the tool. Default-install matches
|
|
"wire everything up" — the common path.
|
|
|
|
Each connector's prompt body comes verbatim from
|
|
``app/web/connector_prompts.py`` — same source the /home tile cards
|
|
render, so editing one place updates both surfaces. The prompts
|
|
themselves are idempotent (each has its own step-0 precheck) so
|
|
re-runs short-circuit cleanly.
|
|
|
|
Connectors are presented in the order they appear in the
|
|
``connector_prompts`` dict — the caller controls ordering by how
|
|
they build the dict. Today that's asana → gws → atlassian, matching
|
|
the /home tile order.
|
|
"""
|
|
lines = [
|
|
"",
|
|
f"{step_num}) Connect the user's tools (last interactive ask before Confirm):",
|
|
"",
|
|
" For each tool below, ask the user verbatim: \"Set up <NAME> now? (Y/n)\".",
|
|
" Treat empty/Enter as YES — the default is install. Only skip when the",
|
|
" user types an explicit \"no\" / \"n\" / \"skip\". Wait for each answer",
|
|
" before moving to the next. The prompts below are idempotent and",
|
|
" safe to re-run if anything goes sideways.",
|
|
"",
|
|
]
|
|
# Stable ordering — let the dict iteration order win (Python 3.7+ insertion-ordered).
|
|
# Caller controls which connectors are present; we just iterate.
|
|
sub_letters = "abcdefghij"
|
|
for i, (slug, body) in enumerate(connector_prompts.items()):
|
|
# Display name is sourced from the registry so the ask phrasing stays
|
|
# in lockstep with what /home renders.
|
|
from app.web.connector_prompts import CONNECTORS # local import — avoids module-load cycles
|
|
display = next((c.display_name for c in CONNECTORS if c.slug == slug), slug)
|
|
desc = next((c.description for c in CONNECTORS if c.slug == slug), "")
|
|
lines.append(f" {sub_letters[i]}) {display} — {desc}")
|
|
lines.append(f" Ask: \"Set up {display} now? (Y/n)\"")
|
|
lines.append(" If yes (default) — follow this inline prompt verbatim:")
|
|
lines.append("")
|
|
# Indent the prompt body two spaces so it visually nests under the
|
|
# ask. Empty lines stay empty (no trailing whitespace).
|
|
for body_line in body.split("\n"):
|
|
lines.append(f" {body_line}" if body_line else "")
|
|
lines.append("")
|
|
lines.extend([
|
|
f" After all asks (regardless of answers) continue to step {confirm_step_num}.",
|
|
])
|
|
return lines
|
|
|
|
|
|
def _restart_claude_lines(step_num: str) -> list[str]:
|
|
"""Final 'restart Claude Code' instruction emitted immediately before
|
|
Confirm. Marketplace plugins, MCP server registrations, and the
|
|
SessionStart hooks installed during init only load on the next
|
|
Claude Code session — without this step the user sits inside the
|
|
setup session with stale state and re-discovers the requirement
|
|
later. The marketplace step's trailer already mentions /exit
|
|
+ claude conditionally; this is the unconditional equivalent so
|
|
every path (with or without plugins) ends on the same cue.
|
|
"""
|
|
return [
|
|
"",
|
|
f"{step_num}) Restart Claude Code so every plugin, MCP server, and SessionStart hook installed above actually loads:",
|
|
" Tell me to type `/exit` (or close the Claude Code session entirely), then run `claude` again from this same `~/{workspace_dir}` directory.",
|
|
" The next session boots with all marketplace plugins, every connector's keychain entries / OAuth grants, and the agnes-welcome + refresh-marketplace SessionStart hooks active. This is the last action before the Confirm summary — once I'm back in Claude Code, setup is complete.",
|
|
]
|
|
|
|
|
|
def _finale_lines(*, confirm_step_num: str, has_ca: bool) -> list[str]:
|
|
"""Final Confirm step. Bullets it asks the assistant to report on must
|
|
only reference earlier steps that were actually emitted, otherwise the
|
|
assistant either hallucinates an answer or asks the user about a
|
|
non-existent step. The CA-bundle-source bullet only makes sense when
|
|
the trust block ran (`has_ca`). The marketplace clone bullet is
|
|
unconditional now — preflight + marketplace are always emitted (Fix B
|
|
in the 2026-05-10 init-report response). Init + catalog + diagnose +
|
|
skills + connectors + version always render, so their bullets are
|
|
unconditional. The per-connector ✅/❌ bullet exploits the uniform
|
|
output contract every connector prompt emits on its verify step —
|
|
the assistant scans its own prior output for those markers instead
|
|
of re-running probes."""
|
|
bullets = [
|
|
" - `agnes --version` output",
|
|
" - First few lines of `agnes catalog` (tables you can see)",
|
|
" - Confirmation that `./CLAUDE.md` and `./AGNES_WORKSPACE.md` exist",
|
|
" - Confirmation that `./.claude/settings.json` contains SessionStart/End hooks",
|
|
" - The `agnes diagnose` overall status",
|
|
" - Whether skills were copied or left on-demand",
|
|
" - Confirmation that `~/.agnes/marketplace/.git/` exists "
|
|
"(the marketplace clone) and that any granted plugins installed",
|
|
" - For each connector (Asana, Google Workspace, Atlassian): "
|
|
"the verbatim ✅ or ❌ line that the connector's verify step "
|
|
"emitted earlier in this session (e.g. `✅ Asana ready — connected "
|
|
"as Vojtech Rysanek. 2 workspace(s) visible.` or `❌ Atlassian setup "
|
|
"failed: ...`). If the user declined a connector, say declined.",
|
|
]
|
|
if has_ca:
|
|
bullets.append(
|
|
" - Which CA bundle source got picked in step 0(d) "
|
|
"(system Python certifi / system curl bundle / uv-fetched)"
|
|
)
|
|
return [
|
|
f"{confirm_step_num}) Confirm:",
|
|
" Tell me \"{instance_brand} workspace is ready\" and summarize:",
|
|
*bullets,
|
|
]
|
|
|
|
|
|
def _preflight_block(step_num: str) -> list[str]:
|
|
"""Pre-flight check — runs before the marketplace clone.
|
|
|
|
`claude plugin marketplace add` (and our git-clone fallback) shells out
|
|
to `git`, AND the marketplace step calls `claude` itself, so a missing
|
|
binary on either side fails the step with a confusing error. We check
|
|
both here so the user gets a single clear "install X" message instead
|
|
of debugging a downstream error.
|
|
|
|
Cross-platform install commands cover the three supported workstation
|
|
OSes:
|
|
- macOS: Homebrew (`brew install git`). The Xcode CLT bundle also
|
|
ships git; we prefer brew because it's non-interactive.
|
|
- Windows: winget (`winget install --id Git.Git -e ...`). Bundled
|
|
with Windows 10 1809+ and Windows 11; non-interactive with --silent.
|
|
- Linux: apt or dnf, depending on distro family.
|
|
|
|
For `claude` we point at the official platform installer docs rather
|
|
than vendoring an install one-liner — Anthropic ships per-platform
|
|
installers (npm on Linux, native binary on macOS/Windows) and the
|
|
canonical instructions live at https://docs.claude.com/claude-code.
|
|
|
|
`step_num` is parameterized because step ordering shifted between
|
|
layouts (the marketplace block now runs before diagnose/skills, so
|
|
preflight + marketplace are steps 4-5 instead of 6-7).
|
|
"""
|
|
return [
|
|
"",
|
|
f"{step_num}) Make sure git and claude are installed (required for the marketplace clone):",
|
|
" git --version",
|
|
" claude --version",
|
|
"",
|
|
" If `git --version` fails (\"command not found\" or similar), install git:",
|
|
" - macOS: brew install git",
|
|
" - Windows: winget install --id Git.Git -e --source winget --silent",
|
|
" - Linux: sudo apt-get install git OR sudo dnf install git",
|
|
"",
|
|
" If `claude --version` fails, install Claude Code:",
|
|
" - npm (Linux / WSL): npm i -g @anthropic-ai/claude-code",
|
|
" - macOS / Windows native installer: see https://docs.claude.com/claude-code",
|
|
"",
|
|
" Then re-run both `--version` checks to confirm before continuing.",
|
|
]
|
|
|
|
|
|
def _marketplace_block(
|
|
plugin_install_names: list[str],
|
|
step_num: str,
|
|
) -> list[str]:
|
|
"""Build the marketplace + plugin-install block.
|
|
|
|
`plugin_install_names` may be empty: registering the per-user
|
|
marketplace clone with Claude Code is useful even when the operator
|
|
has zero plugin grants, because it pre-wires the SessionStart hook
|
|
and the grant flow — admin grants land on the next Claude Code
|
|
session without re-running setup. The block copy adapts for the
|
|
empty case so the comment-bullet doesn't promise plugin installs
|
|
that won't happen.
|
|
|
|
`step_num` is parameterized because step ordering shifted between
|
|
layouts (this block now runs before diagnose/skills, so it's step 5
|
|
instead of the old step 7).
|
|
|
|
The whole block is one CLI invocation: ``agnes refresh-marketplace
|
|
--bootstrap``. The CLI handles clone + PAT-strip + chmod + register-
|
|
with-Claude + auto-install-from-manifest internally. This is what
|
|
used to be a 15-line shell sequence inline; pulling it into the CLI
|
|
bought:
|
|
|
|
1. **Claude Code permission gate friendliness.** The agent-driven
|
|
onboarding flow inside Claude Code denies ``rm -rf`` by default;
|
|
the inline script tripped on it. Wrapping the destructive prep
|
|
inside agnes lets the CLI's already-trusted permission grant
|
|
cover it (Python ``shutil.rmtree`` doesn't pattern-match the
|
|
shell ``rm -rf`` block).
|
|
2. **Idempotence without inline ``rm``.** Re-running the install
|
|
prompt over an existing clone now does fetch+reset under the
|
|
hood (no destructive cleanup needed). The prompt's "safe to
|
|
re-run" promise holds without forcing the operator to delete
|
|
anything by hand.
|
|
3. **One source of truth.** ``agnes refresh-marketplace`` is also
|
|
the SessionStart hook command, so install + refresh share the
|
|
same code path — version-aware reconcile, hook JSON output,
|
|
credential helper PAT injection, all consistent.
|
|
|
|
Why always clone (with the CLI doing it) instead of trying direct
|
|
HTTPS marketplace add first? ``claude plugin marketplace add
|
|
<https-url>`` does succeed against our ``/marketplace.git/`` endpoint
|
|
(returns 200 + JSON), but Claude Code stores the response as a
|
|
single-file marketplace and resolves plugin ``source:
|
|
"./plugins/<name>"`` paths as local filesystem refs — so the
|
|
subsequent ``claude plugin install`` looks for plugin trees at
|
|
``<marketplace-dir>/plugins/<name>/`` and 404s because the dir is a
|
|
file. Only the git-clone path produces a real directory tree with
|
|
plugin contents in place. Broken end-to-end on every Claude Code
|
|
distribution; cloning is the only reliable install path.
|
|
|
|
TLS handling for the in-binary ``git clone`` is fully covered by the
|
|
cross-platform trust block (step 0) when the server's cert needs
|
|
bootstrapping (`ca_pem` non-empty), and by the OS trust store when
|
|
the cert is publicly-trusted. There used to be a legacy fallback
|
|
here that emitted a host-scoped ``git config http.<host>.sslVerify
|
|
false`` line for the ``AGNES_DEBUG_AUTH`` path; that's gone — it
|
|
masked operator misconfigurations (a ``self_signed_tls=True``
|
|
instance without ``/data/state/certs/fullchain.pem`` on disk) and
|
|
its ``sslVerify=false`` shell command tripped Claude Code auto-mode
|
|
classifiers. Operators serving a self-signed or private-CA cert
|
|
must place the fullchain at ``AGNES_TLS_FULLCHAIN_PATH`` (default
|
|
``/data/state/certs/fullchain.pem``) so step 0 can read it via
|
|
``_read_agnes_ca_pem``.
|
|
"""
|
|
has_plugins = bool(plugin_install_names)
|
|
header = (
|
|
"Register the Agnes Claude Code marketplace and install plugins:"
|
|
if has_plugins
|
|
else "Register the Agnes Claude Code marketplace (no plugins granted yet):"
|
|
)
|
|
bullet_5 = (
|
|
" # 5. install every plugin listed in the served manifest"
|
|
if has_plugins
|
|
else " # 5. (no plugins to install — your account has zero grants)"
|
|
)
|
|
if has_plugins:
|
|
trailer = [
|
|
" These run non-interactively. After they finish, tell the user to /exit",
|
|
" and run `claude` again so the new plugins load. From then on, the",
|
|
" SessionStart hook keeps the marketplace clone in sync via",
|
|
" `agnes refresh-marketplace --quiet` on every Claude Code session.",
|
|
]
|
|
else:
|
|
trailer = [
|
|
" Your account has no plugin grants right now, but registering the",
|
|
" marketplace anyway pre-wires the SessionStart hook. When an admin",
|
|
" grants you a plugin later, `agnes refresh-marketplace` (run by the",
|
|
" hook on every Claude Code session) will install it automatically —",
|
|
" no need to re-run this setup script.",
|
|
]
|
|
return [
|
|
"",
|
|
f"{step_num}) {header}",
|
|
" # `agnes refresh-marketplace --bootstrap` does:",
|
|
" # 1. clone the per-user marketplace bare repo to ~/.agnes/marketplace",
|
|
" # 2. strip the PAT from the cloned origin URL (refreshes use a",
|
|
" # per-invocation git credential helper, not the URL)",
|
|
" # 3. best-effort chmod 700/600 on POSIX (no-op on Windows NTFS)",
|
|
" # 4. `claude plugin marketplace add ~/.agnes/marketplace`",
|
|
bullet_5,
|
|
" # Idempotent — re-runs over an existing clone do fetch+reset+reconcile",
|
|
" # via the same path the SessionStart hook uses.",
|
|
" agnes refresh-marketplace --bootstrap || {",
|
|
" echo \"ERROR: agnes refresh-marketplace --bootstrap failed\" >&2",
|
|
" exit 1",
|
|
" }",
|
|
"",
|
|
*trailer,
|
|
]
|
|
|
|
|
|
|
|
|
|
def _preamble_lines(*, has_ca: bool) -> list[str]:
|
|
"""Header that opens the prompt before the numbered steps. The
|
|
`step 0(d) fallback chain` reference is only emitted when the trust
|
|
block actually exists (`has_ca`); without it the line points at a
|
|
non-existent step. The "don't disable TLS verification" advice itself
|
|
stays unconditional — it's good guidance regardless of whether the
|
|
server runs with a private CA."""
|
|
lines = [
|
|
"Set up the {instance_brand} CLI on this machine.",
|
|
"",
|
|
"Server: {server_url}",
|
|
"Personal access token: {token}",
|
|
"(Just generated; treat it as a secret.)",
|
|
"",
|
|
"Run these, in order. The script is idempotent — safe to re-run if a step",
|
|
"fails partway through. If a step fails with an unfamiliar error, paste the",
|
|
"exact error back and stop. Do NOT improvise around TLS errors by disabling",
|
|
"verification (`-k`, `NODE_TLS_REJECT_UNAUTHORIZED=0`,",
|
|
"`git -c http.sslVerify=false`, etc.) — those are dead ends that hide the",
|
|
"real problem.",
|
|
]
|
|
if has_ca:
|
|
lines.append(
|
|
"The fallback chain inside step 0(d) is documented and OK to "
|
|
"use; that's what fallback chains are for."
|
|
)
|
|
lines.append("")
|
|
return lines
|
|
|
|
|
|
def _step_numbers(*, has_connectors: bool = True) -> dict[str, str]:
|
|
"""Compute the step numbers for the unified layout.
|
|
|
|
Returns a dict keyed by logical step name; values are stringified
|
|
1-based step numbers (preserving the existing string-based helper API
|
|
so call sites stay diff-minimal).
|
|
|
|
Steps (always emitted): install (1), mkdir/cd (2), init (3),
|
|
catalog (4), preflight (5), marketplace (6), diagnose (7),
|
|
connectors (8), restart_claude (9), confirm (10). Preflight +
|
|
marketplace + connectors + restart_claude are always-on:
|
|
- Marketplace registration is useful even when the operator has
|
|
zero plugin grants (SessionStart hook reconciles future grants
|
|
automatically).
|
|
- Connectors (Asana / GWS / Atlassian) are per-connector default-yes
|
|
asks — the user can decline each individually, so always-emitting
|
|
the block costs nothing for users who skip everything. The
|
|
Atlassian Remote MCP registration (`claude mcp add ...`) used to
|
|
be its own step 6 but moved INTO the Atlassian connector's
|
|
prompt body (atlassian_prompt() in app.web.connector_prompts) so
|
|
everything Atlassian-related lives in one group — both the
|
|
/home Atlassian tile and the inlined Atlassian sub-block in the
|
|
setup script emit the same `claude mcp add` line as part of the
|
|
standard connector setup.
|
|
|
|
The interactive "Skills" step that previously sat between diagnose
|
|
and Confirm was deleted in #242 — on-demand `agnes skills show
|
|
<name>` is the one-size-fits-all default; bulk-copying every skill
|
|
into ``~/.claude/skills/agnes/`` was an opinion question without an
|
|
obvious right answer.
|
|
|
|
`has_connectors` is kept as a parameter for future flexibility
|
|
(default True). When set False, the connectors step is skipped and
|
|
Confirm shifts down to step 7.
|
|
|
|
Step-0 (TLS trust block) sits outside this numbering — it is gated by
|
|
has_ca and has its own "0)" header rendered inside the trust block
|
|
helper.
|
|
"""
|
|
n = 5
|
|
preflight = str(n); n += 1
|
|
marketplace = str(n); n += 1
|
|
diagnose = str(n); n += 1
|
|
connectors = str(n) if has_connectors else ""
|
|
if has_connectors:
|
|
n += 1
|
|
restart_claude = str(n); n += 1
|
|
confirm = str(n)
|
|
return {
|
|
"preflight": preflight,
|
|
"marketplace": marketplace,
|
|
"diagnose": diagnose,
|
|
"connectors": connectors,
|
|
"restart_claude": restart_claude,
|
|
"confirm": confirm,
|
|
}
|
|
|
|
|
|
def resolve_lines(
|
|
wheel_filename: str,
|
|
*,
|
|
plugin_install_names: list[str] | None = None,
|
|
server_host: str = "",
|
|
ca_pem: str | None = None,
|
|
connector_prompts: dict[str, str] | None = None,
|
|
instance_brand: str = "Agnes",
|
|
workspace_dir: str = "Agnes",
|
|
) -> list[str]:
|
|
"""Return the template lines with server-side placeholders substituted.
|
|
|
|
Pre-substitutes `{wheel_filename}` and `{server_host}`. Leaves
|
|
`{server_url}` and `{token}` as placeholders for click-time JS
|
|
substitution (or for `render_setup_instructions()` below).
|
|
|
|
`ca_pem` (PEM-encoded fullchain of the Agnes server's TLS cert) gates
|
|
the cross-platform step-0 trust-bootstrap block AND switches step 1 to
|
|
the curl-then-local-install pattern AND switches step 5 to the
|
|
platform-aware marketplace strategy. Caller decides whether the cert
|
|
needs the bootstrap (typically: skip for publicly-trusted certs like
|
|
Let's Encrypt, emit for self-signed or private corp CA).
|
|
|
|
`connector_prompts` is a dict {slug: prompt_text} sourced from
|
|
:func:`app.web.connector_prompts.all_connector_prompts`. When empty
|
|
or None we fall back to the module's defaults (no operator GWS OAuth
|
|
credentials baked in — the unconfigured GCP-walkthrough branch
|
|
renders). Both the /home tiles and this setup script consume the
|
|
same dict so the prompt text stays in lockstep across surfaces.
|
|
|
|
Fallback: callers pass `"agnes.whl"` when no wheel is present on disk.
|
|
The resulting URL (`/cli/wheel/agnes.whl`) will 404 at download time, but
|
|
the instruction text still renders so operators can see the snippet shape
|
|
and diagnose the missing wheel on the server.
|
|
"""
|
|
names = list(plugin_install_names or [])
|
|
has_ca = bool(ca_pem and ca_pem.strip())
|
|
|
|
# Lazy default for connector_prompts. Imported inline so the
|
|
# setup_instructions module stays import-light when callers don't
|
|
# actually emit the connectors block (tests that hit a single helper
|
|
# don't pay the cost of loading the prompt strings).
|
|
if not connector_prompts:
|
|
from app.web.connector_prompts import all_connector_prompts
|
|
connector_prompts = all_connector_prompts()
|
|
|
|
# Step layout. Preflight + marketplace + MCP go BEFORE diagnose;
|
|
# connectors is the LAST interactive ask before Confirm — once plugins
|
|
# + MCP + diagnose are settled, the only remaining work is plugging
|
|
# the user's tools (Asana / GWS / Atlassian). The Skills step that
|
|
# used to sit between diagnose and Confirm was deleted in #242
|
|
# (on-demand `agnes skills show <name>` is the default;
|
|
# bulk-copying skills was an opinion question).
|
|
steps = _step_numbers(has_connectors=True)
|
|
|
|
lines: list[str] = []
|
|
if has_ca:
|
|
lines.extend(_tls_trust_block(ca_pem)) # type: ignore[arg-type]
|
|
lines.extend(_preamble_lines(has_ca=has_ca))
|
|
lines.extend(_install_cli_lines(has_ca=has_ca)) # 1
|
|
lines.extend(_init_lines()) # 2, 3
|
|
lines.extend(_preflight_block(steps["preflight"])) # 4
|
|
lines.extend(_marketplace_block(names, step_num=steps["marketplace"])) # 5
|
|
# Standalone MCP step used to live here — moved INTO the Atlassian
|
|
# connector's prompt body in step 7 so all Atlassian setup is grouped
|
|
# together.
|
|
lines.extend(_diagnose_lines(diagnose_num=steps["diagnose"])) # 6
|
|
# Connectors are the LAST interactive ask before the restart-claude
|
|
# cue. Per-connector default-yes — empty/Enter is install, explicit
|
|
# "no" skips.
|
|
lines.extend(_connectors_block(
|
|
steps["connectors"], connector_prompts,
|
|
confirm_step_num=steps["confirm"],
|
|
))
|
|
# Restart-claude lands between connectors and confirm so the user
|
|
# picks up freshly-registered plugins / MCP servers / hooks on the
|
|
# next session — without this every path silently expected the user
|
|
# to know they had to re-launch.
|
|
lines.extend(_restart_claude_lines(steps["restart_claude"]))
|
|
lines.append("")
|
|
lines.extend(_finale_lines(
|
|
confirm_step_num=steps["confirm"],
|
|
has_ca=has_ca,
|
|
))
|
|
|
|
return [
|
|
line
|
|
.replace("{wheel_filename}", wheel_filename)
|
|
.replace("{server_host}", server_host)
|
|
.replace("{workspace_dir}", workspace_dir)
|
|
.replace("{instance_brand}", instance_brand)
|
|
for line in lines
|
|
]
|
|
|
|
|
|
def render_setup_instructions(
|
|
server_url: str,
|
|
token: str,
|
|
wheel_filename: str = "agnes.whl",
|
|
*,
|
|
plugin_install_names: list[str] | None = None,
|
|
server_host: str = "",
|
|
ca_pem: str | None = None,
|
|
connector_prompts: dict[str, str] | None = None,
|
|
instance_brand: str = "Agnes",
|
|
workspace_dir: str = "Agnes",
|
|
) -> str:
|
|
"""Render the setup instructions as a single string.
|
|
|
|
Used server-side for tests and any non-JS rendering path. The browser
|
|
clipboard flow uses the JS renderer embedded in the Jinja partial; both
|
|
must produce byte-identical output for a given (server_url, token,
|
|
wheel, plugins, host, ca_pem, connector_prompts, brand, workspace_dir) tuple.
|
|
"""
|
|
lines = resolve_lines(
|
|
wheel_filename,
|
|
plugin_install_names=plugin_install_names,
|
|
server_host=server_host,
|
|
ca_pem=ca_pem,
|
|
connector_prompts=connector_prompts,
|
|
instance_brand=instance_brand,
|
|
workspace_dir=workspace_dir,
|
|
)
|
|
text = "\n".join(lines)
|
|
return text.replace("{server_url}", server_url).replace("{token}", token)
|