🚨 this is going to be a wild ride, so stay tuned! 🚨 started with a one-shot prompt that ran for 24 hours. next i'm going to carve this chunk of rock into a handy dandy production-ready SDR agent that integrates with hubspot. (not accepting PRs for the foreseeable future)
An audit-first SDR (sales development) agent MVP. The model is Jido for decisions, Ash for governance, Oban for durable execution, Postgres as the system of record, and Phoenix LiveView for operator control. Every step the agent takes can be reconstructed from Postgres, the audit chain is hash-linked and verifiable, and every outbound message needs a human approval bound to the exact revision. Delivery is local capture only.
All data is fictional (*.example.test, *.test domains). This is a local
demo, not a hosted service.
- Nix with flakes, plus direnv with nix-direnv. The
toolchain is pinned in
devenv.nixandflake.lock: Elixir 1.20.4, OTP 29 and PostgreSQL 18. - Ports 5520 (Postgres) and 4120 (Phoenix) must be free:
lsof -nP -iTCP:5520 -sTCP:LISTEN. - Optional: a local Grafana with Tempo for trace links
(
http://localhost:3000, Tempo datasource uidtempo, OTLP/HTTP on127.0.0.1:4318). The app runs without it.
direnv allow # enter the devenv shell (Mix deps live in .devenv/state)
devenv up # start Postgres on 127.0.0.1:5520 (leave it running)
mix deps.get
mix assets.setup # one-time download of the pinned asset binariesmix assets.setup downloads tailwind 4.3.0 from GitHub releases and
esbuild 0.25.4 from the npm registry. Both versions are pinned in
config/config.exs. This is the only network step besides mix deps.get.
Run it once while online. If it is skipped, the dev server's asset watchers
download the binaries on first start.
bin/demo reset --yes && bin/demo seed && bin/demo runThen open http://localhost:4120. Run bin/demo status in another terminal
at any time.
| Command | What it does |
|---|---|
bin/demo reset --yes |
Drops, creates and migrates sdr_agent_dev. Destructive, so it needs --yes, and it refuses while anything is connected to the database (a server on any port, IEx, psql). The drop is never forced. |
bin/demo seed |
Seeds the fictional ICP, campaign, 10 accounts and contacts with leads, 3 operators and one suppression. It also registers the pinned audit-anchor public key (docs/audit/anchor-signing-key.pub) so anchoring works after a reset. Idempotent. |
bin/demo run |
Checks that the port is free and the database is reachable, migrated and seeded, then starts Phoenix on PORT (default 4120). |
bin/demo predeliver |
Runs fixture lead 01 (Brightpath Freight Systems) through research, qualification and drafting, and prints the /drafts/… path of the draft awaiting review. It never approves: every outbound message needs a human approval (ADR-0001 Tier 0). Idempotent; a re-run reports the stage (awaiting review, queued, deferred, captured). |
bin/demo status |
Shows the database, migrations, server, Oban queues and job counts, leads by status, drafts awaiting review, captured messages, whether the signing key is registered, and the audit chain verification. |
bin/demo refuses to run against anything except the local demo database: it
needs MIX_ENV=dev (or unset), no DATABASE_URL, and a Repo of
sdr_agent_dev on localhost/127.0.0.1:5520. The --test flag is for the
script's own tests only. It uses a separate throw-away database.
The campaign's quiet hours start at 18:00 America/Denver. To show a captured email after that, prepare before 18:00:
- With
bin/demo runserving, runbin/demo predeliver. It prints the/drafts/…path of lead 01's draft. - Sign in as the reviewer, open that draft and approve it yourself. This
also rehearses the demo. The server's delivery queue captures the email
within seconds, and
bin/demo predeliver(re-run) or the draft page then shows "captured".
During the demo, walk through lead 01's evidence, the approved draft and its captured message. Assign a second qualifying lead (02, 03, 09 or 10) live to show the agent working. An approval made inside quiet hours is deferred by the send gate, which is itself worth showing.
Three operators are seeded: admin@example.test, reviewer@example.test and
auditor@example.test. Their passwords are fixtures in
lib/sdr_agent/demo/fixtures.ex (users/0). They are dev and test data, and
seeding is refused in other environments.
The steps below use the element ids from the console, so the same path can be scripted.
- Sign in as the reviewer at
/sign-in. The Dashboard shows the pipeline: 10 leads, of which 1 is stopped because Harborline Routing is suppressed. - Leads → Brightpath Freight Systems (lead 01). Click Assign to agent
(
#assign-lead). Using the deterministic fake model, the agent researches fixture sources, extracts evidence, qualifies the lead, and drafts an email. The page updates live as each step commits:#lead-runs,#qualificationand#lead-drafts. - Open the run (
/runs/:id) to see every decision, model invocation and tool call. It also updates live. - Review queue (
/review) now lists the draft. Open it (/drafts/:id). Click a highlighted sentence to see the evidence claim and source quote behind it. - Optionally edit the draft (
#edit-toggle). This creates a new human revision with an AI-vs-human diff. - Approve (
#approve-form). The approval binds the revision id and content hash shown on screen. If the draft changed in the meantime, the page says so (#newer-revision) and the domain refuses the stale verdict. The delivery is queued, captured by the local capture adapter, and its receipts and exact RFC 5322 message appear on the draft page ("Captured message"). - Runs & operations (
/operations) shows the durable work and anything that needs attention. - Sign in as the admin or auditor and open Audit (
/audit) for the hash-chained timeline. Click Verify chain (#verify-chain) and open payloads (/audit/payloads/:sha256). Every auditor view is itself recorded as an AuditAccess.
Replies are simulated by signed, deduplicated webhooks. After a lead's email
is captured, mix sdr.demo.reply (S9) posts a reply for it to the running server's
webhook, for example mix sdr.demo.reply --lead 01 --kind interested or
--kind unsubscribe. An interested reply lands in the hand-off queue, and an
unsubscribe suppresses the recipient and stops the lead.
bin/demo status # includes the chain verification result
bin/with-secrets SDR_AUDIT_ANCHOR_PRIVATE_KEY -- mix sdr.audit.export --lead <LEAD_ID>
mix sdr.audit.verify audit-export-lead-<LEAD_ID>.json # pinned key set: docs/audit/trusted-keys.jsonThe export task needs the Ed25519 anchor key, which only bin/with-secrets
provides (sops). The verifier needs no secret. Anchoring runs every minute
when the server has the key: bin/with-secrets SDR_AUDIT_ANCHOR_PRIVATE_KEY -- bin/demo run. Without the key, anchoring does not run, and the chain itself
still verifies. Offline (for example on conference Wi-Fi), set
SDR_ANCHOR_SINKS=file (anchors go to tmp/audit-anchors) or none. The
default git+ots pushes to the private anchors repository and the
OpenTimestamps calendars.
Every console page with a trace id links to Grafana Explore on Tempo
(http://localhost:3000, datasource tempo). You can change both with
config :sdr_agent, SdrAgentWeb.Trace, grafana_url: ..., datasource_uid: ....
In dev the app exports OTLP/HTTP to 127.0.0.1:4318, with prompt and
completion content as span events (synthetic data only, per ADR-0005).
- Model: a deterministic fake model by default
(
SdrAgent.AI.ModelProvider.Fake), so the demo needs no account or network. - Research sources: fixture CRM, search and web providers. Nothing is fetched from the internet.
- Email: local capture only (
CaptureAdapter). No adapter or configuration can reach a real recipient, and a test enforces that. - Replies: simulated, signed (HMAC) and deduplicated webhooks (S9).
- Real: the Jido agent and flows, Ash policies, Oban jobs, the hash-chained audit ledger and its verification, approval binding, suppression, quotas and quiet hours.
The ClaudeCLI provider (ADR-0004) calls Claude Code through
llm-proxy-shim, using your own local Claude Code login. It is for a
personal local demo only: never hosted, shared or multi-user traffic.
Status (R0-02): the pin can be built and inspected now; ordinary real
model use is not available yet. Every real call is refused before any
reservation or launch (real_model_staged) until the reviewed model
profiles, owner call grants and witness work land (stories R0-03, C9 and
R0-07). Development, tests and the demo use the deterministic fake.
The app runs its own pinned Claude Code build (nix/app-claude-cli.nix,
on the nixpkgs locked in flake.lock), never claude from PATH, so
updating your own Claude Code does not change what the app runs. The
reviewed build is recorded per platform in nix/app-claude-cli.identity
(store path and sha256 of bin/claude-code; only aarch64-darwin today).
Build it, which also keeps it and the previous build alive with GC roots
under .gcroots/, and inspect it:
bin/app-claude-cli-root # prints /nix/store/...-app-claude-cli-<version>/bin/claude-codeSelecting the provider boots the app with the pinned CLI configured, shown on the Admin page, while calls stay refused:
SDR_MODEL_PROVIDER=claude_cli bin/demo runbin/demo run builds (or finds) the pinned CLI with bin/app-claude-cli-root
and sets SDR_CLAUDE_CLI_BIN for you. Starting Phoenix directly needs it set
by hand:
SDR_MODEL_PROVIDER=claude_cli SDR_CLAUDE_CLI_BIN="$(bin/app-claude-cli-root)" mix phx.serverSDR_CLAUDE_CLI_BIN must be exactly the recorded store path for this
platform, with the recorded sha256 (checked once at boot); unset or
anything else refuses boot. If the build is later removed, the app refuses
calls until you rebuild it; there is no fallback to another CLI or to the
fake.
This starts one supervised ClaudeCLI server (one call at a time). The Admin
page shows the provider, the model (opus → claude-opus-5-5), the
reviewed Claude Code version, the pinned CLI path, the refusal reason and
the last init attestation. SDR_CLAUDE_CLI_TIMEOUT_MS sets the per-call
timeout (default 240000). The provider is accepted in development only:
the test suite and production refuse to boot with it. If a run needs
ClaudeCLI while it refuses calls, the run fails with an attention item; it
never falls back to the fake model.
Budgets still apply: 20 model calls per run and 200 per UTC day.
bin/calibration-console serves the test-seam build from its own fixed,
persistent database, sdr_agent_calibration, so the owner can create the
single G-R0 calibration grant there (R0-07 readiness packet, section 3). It
is not the demo and makes no model call:
bin/calibration-console check # the plan: database, listener, provider; no server, no database
read -rs PW; printf '%s\n' "$PW" | \
bin/calibration-console bootstrap-admin --email you@example.test --display-name You --password-stdin
unset PW
bin/calibration-console serve # http://127.0.0.1:4124: sign-in and /admin onlyIt refuses any other database (a DATABASE_URL, a non-local host, a port
other than 5520), any MIX_ENV but test, any PORT but 4124 and any
model provider but the fake. It listens on 127.0.0.1:4124 only, creates the
database if it is absent and runs pending migrations, and has no reset, drop
or seed command. Every page except sign-in and /admin answers 404 there.
serve refuses until the assets are built (mix assets.build).
It never uses the checked-in test session and token secrets. Its own are
generated on first use into ~/.local/state/sdr-agent/calibration/secrets
(directory 0700, file 0600) by whichever command runs first, check
included, and reused afterwards; it refuses to run if that file or
directory is a symlink, not yours, or readable by group or others. Never
commit or share that file. The console's session cookie is its own
(_sdr_agent_calibration_key), so signing in on 127.0.0.1:4124 does not
sign you out of the app on port 4120 in the same browser, or the reverse.
bin/demo runsays the port is in use. Runlsof -nP -iTCP:4120 -sTCP:LISTENand stop that process, or usePORT=4122 bin/demo run.bin/demonever picks another port silently.- The database is unreachable. Start Postgres with
devenv up.bin/demo statusshows the connection error. - Migrations are pending or the tenant is not seeded. Run
bin/demo reset --yes && bin/demo seed. - Tailwind or daisyUI does not resolve, or icons are missing. Run
mix assets.setuponce while online, thenmix assets.build. Asset paths come fromMIX_DEPS_PATHandMIX_BUILD_ROOTunder devenv, so run Mix inside the devenv shell. - A delivery stays pending. The campaign honours quiet hours from 18:00
to 08:00 America/Denver, and a daily cap of 25. The send gate defers until
the window opens, and the deferral is recorded as a
send_gatedecision in the audit timeline. - Anchoring errors in the log. The anchor key is not set. See "Audit verification and export" above.
mix testcovers the golden path (LiveViewTest and HTTP smoke), Postgres-only reconstruction, crash recovery, hermetic configuration and the secret scan.- Real browser (local only, never against the dev server):
bin/demo --test reset --yes && bin/demo --test seed && bin/demo --test serve, thennode test/browser/golden_path_smoke.mjs(Node 22 or later, local Chrome). The script first checks the server's attestation (tmp/smoke/attestation-<port>.json, written by the serve command) and refuses port 4120, any server that does not attest, and any database that is not a throw-away_demoone.
bin/verify # format, compile --warnings-as-errors, tests
mix ash.codegen --check && mix credoParallel worktrees share the devenv Postgres: run tests with a partition, for
example MIX_TEST_PARTITION=_s13 mix test. Architecture decisions are in
docs/adr/, and slice notes are in notes/features/.