Automation research session (planner · worker · critic)¶
Every hosted automation run is one research session, shaped like a person working a deal with an assistant: the planner reads the deal and the playbooks and asks for the next thing; the worker does it in a single continuous conversation; the critic is the quality check at the end — when the planner says done it verifies what was saved and either says "that's fine" or sends one fix ("good — but we forgot the HOA fee") before the brief. Requires GEMINI_API_KEY on the automation worker.
Trigger fields:
| Field | Meaning |
|---|---|
goal |
import | research | refresh | underwrite |
kind |
refresh only — the deal-tab request (see Goals) |
comps_kinds |
Resolved comp kinds; gates paid STR tools |
_engine |
research_session |
playbook_key stays for quotas/UI (analyze_address vs deal_tab_refresh).
Roles¶
| Role | Who | Tools | Decides |
|---|---|---|---|
| Planner | Gemini agent with its own conversation for the run | Read-only deal tools + docs (get_deal, find_deals_by_address, list_deal_*, get_agent_manual, search_docs, …) |
The next request to the worker, done, or pause — on import also use_deal / import_listing. Reads the playbooks once and remembers them. |
| Worker | Gemini agent, one conversation for the whole run | Full MCP catalog minus guardrails (below) | How to do each request; saves through the same MCP write tools external agents use. Remembers what it already fetched. |
| Critic | Gemini agent with its own conversation for the run | Same read-only set as the planner | Runs only at the done gate (no per-turn review): accept, follow_up (one fix sent to the worker, max 2 per run, then the brief names what is still open), or pause. Sees the run's work log; verifies saved records instead of trusting summaries. |
| Hooks | Code | — | Platform follow-ups keyed on what the worker touched (below). |
| Brief | Gemini, once at the end | — | Human-facing summary → result_summary. Names open risks; never mutates money fields. |
Hard rules: the planner never researches; the critic never picks the roadmap; guardrails are code, not prompts.
Control loop¶
flowchart LR
planner[Planner reads deal + playbooks] -->|request| worker[Worker session]
worker --> hooks[Hooks: platform follow-ups]
hooks --> planner
planner -->|done| rails[Code rails]
rails -->|missing bar| worker
rails --> gate[Critic done gate]
gate -->|follow_up| worker
gate -->|accept| brief[Brief]
planner -->|pause| human[Human]
gate -->|pause| human
- Import opening (code): with no deal linked, code looks up the run's address / listing URL (
find_deals_for_locator, the same matcher asfind_deals_by_address). Exactly one certain match (address= same street + unit + ZIP, orlisting_url) → the run links that deal (use_dealsetup: restore from the archive, reopennew/passed/watch/blocked→researching, seed focus strategies, attach the requested listing URL when it is for this house, strip other-address URLs, auction pause) and continues asresearch. No match → the platform listing fetch (get_listing, shared fact cache) adds the deal. Onlypossiblematches → the planner decides withuse_deal/import_listing(several plausible deals →pause). If the portal lookup finds nothing, the planner asks the worker to find the listing and add it withadd_manual_lead. Ingest dedupe on address / URL still backs this up. - Fact phase (code,
import/research, once per run): before the planner's first ask, independent fact steps run in parallel — first the listing refresh from the shared fact cache (existing deals; photos only when the deal has none), then linking the area chain (neighborhood → zip → city → county → metro), then in parallel: market trends (ensure_deal_trends; AirROI only when STR is in focus), assessed value / tax history and the listing price history (both read from the cached listing — no extra scrape), and one comps step per kind the focus strategies need (rent → Zillow rentals, sale → Zillow sold in the last year with a size band, STR → AirROI; kinds with comps fresher than 30 days are skipped; one search at the default radius, widened once when thin; cached 7 days in the shared fact cache; saved comps are pre-screened and the LLM confirms which count), and growth drivers when the deal has no active ones (get_growth_drivers: level-specific web searches for every linked area in parallel — local projects for the neighborhood / ZIP, development / jobs / rezoning for the city, infrastructure / jobs for the county, employers / transit for the metro — then one LLM grading call per the growth-drivers playbook that tags each driver with the smallest area it affects (market_id); every driver must cite a returned URL; searches cached 14 days per area, graded drivers per area chain) — then estimates — when a strategy's comps are too thin (fewer than 3 rent / sold / STR comps pass the screen) one wider comps search per thin kind runs first (rent 10 mi, sold 8 mi, STR 6 mi; in parallel), thenfill_deal_uw_inputssets empty rent (median of screened rent comps), ARV (3+ screened sold comps, method priority + disagreement gate), nightly rate / occupancy (STR comps) and listing / trend defaults, then rescore (the preliminary score). The planner's first message lists what each step saved and what is still missing; it should not ask the worker to re-scrape the listing or re-run trends unless a fact looks wrong. - Auto import ends here. For
goal=import, once code settled the deal and the fact phase ran, the run skips the planner / worker / critic loop: code records anaction_neededhandoff for any distressed-sale conditions (qa_flags.distress_conditions) not already covered, then the brief names what was filled and what is still open (thin comps, missing fix-up costs, teardown signals, growth drivers) for a follow-upresearchrun. Only an import code could not settle (listing not found on the portals, ambiguous existing deals) enters the loop — and it still ends with facts + brief once the deal is known.research/underwrite/refreshkeep the loop below. - Planner gets the goal brief, the user's request (
refresh), run settings, the deal snapshot (data_gaps,qa_flags, research context), what happened since its last decision, and the remaining budget. - Worker handles the request as a new user message in its conversation.
attach_photosputs gallery images in that message for condition / gallery work. - Hooks run after every worker turn (see below).
- No per-turn review. After the hooks, the planner sees the worker's report and decides the next task. Quality is checked once, at the done gate (step 8).
- On planner
done, code rails run first (each at most once): foreign listing URLs → remove them; disclosed repairs with no fix-up costs → estimate CapEx (with photos);import/researchwith soft gapmissing_growth_drivers→ research a growth driver; distressed-sale conditions (qa_flags.distress_conditions: short sale, pre-foreclosure / foreclosure, REO, probate, auction) with no matching open handoff → record anaction_neededhandoff of what a person must verify;underwritewith those conditions and statusranked→ re-check against the distress override. Then the critic's done gate.
Discrete steps. Each planner request is one task (one topic, one thing to save) — each worker turn has a hard model-call limit and bundled requests run out of it (run ac69e73d: "auction terms and 78750 rent comps" failed twice and paused). Code sends a request that lists two or more numbered tasks back to the planner once to pick the most important one. The end-of-run quality check names one fix at a time. When a turn runs out of model calls, the planner is told and asks for anything left as separate requests.
Memory (lessons across runs)¶
Runs used to repeat the same mistakes. Each workspace now has an automation memory (app/memory/): short notes that expire on their own (lesson 60 d, source tip 90 d, area fact 30 d, not found 7 d; a note seen again gets more time), linked to entities — tool:<name>, goal:<goal>, area:<level>:<code> from the deal's areas, source:<host>, topic:<word> — and full-text searchable. Stored in Redis 8 (built-in query engine, index idx:memory); falls back to in-process when search is unavailable. Workspace-scoped — memories never cross workspaces.
- Captured in code: a failed tool call (not timeouts / rate limits), paired with the later call of the same tool that worked ("do this instead"); a request that ran out of model calls; a planner request that bundled tasks; a fix the end-of-run quality check had to send back.
- Recalled up front: lessons linked to the run's goal, the deal's areas and the worker's tools go into the planner's first message and the worker's first instruction.
- Worker tools (automation only, not MCP):
recall_memories(query, tool?),remember(text, kind, about[], source_url?),forget_memory(memory_id)for a lesson that turned out wrong. - A memory is a lead, not a fact — numbers from memory are re-checked at their source before they go on a deal.
Hooks (deterministic)¶
| Worker touched | Code runs |
|---|---|
add_manual_lead (import) |
Link the run to the deal, new → researching, seed focus strategies from the trigger, redevelop detection, strip other-address listing URLs, vision gallery clean-up, pause for auction / auction date ("Auction needs title review") |
add_deal_attachment_url(s) |
Vision keep/drop on the listing gallery (drop faces, other homes, maps, logos) |
Money inputs (update_deal, comps, appraisal/tax, repair items, OpEx items, update_deal_property) |
reconcile_uw_after_fill: clear unsupported rent/ARV, sync derived inputs, rescore |
Worker guardrails (code)¶
- Denied everywhere: automation-run tools (no recursion), workspace settings (UW defaults, financing profiles), cross-deal bulk writes, market-snapshot overrides, contact-directory admin (merge/delete/promote), buyer outreach (buyer CRUD, links, shares, messages).
- Firecrawl:
scrape,search,map,parseonly. importonly:add_manual_lead.underwriteonly:update_deal_status,advance_deal, scenario create/fork/select/apply,match_deal_buyers.- STR only (
strincomps_kinds): AirROI, VRBO (AirDNA only when configured) — paid.
Goals¶
| Goal | Entry | Done when |
|---|---|---|
import |
Auto import / create_automation_run(address\|listing_url) |
Go/no-go ready package for human review (listing facts, photos, trends, tax, comps, strategy money inputs, ≥1 active growth driver) |
research |
Deal Research / create_automation_run(goal=research, deal_id) |
Same ready-package bar (no ingest) |
refresh |
Deal-tab research buttons / create_automation_run(deal_id, kind) |
The tab's request is satisfied, or what remains needs a human |
underwrite |
Deal Underwrite / create_automation_run(goal=underwrite, deal_id) |
Underwrite + scenarios playbooks satisfied (thesis, dry-run advance_deal, buyer-fit gate), or pause |
Refresh kind → request: listing_property (price, status, facts, write-up, attributes, HOA, agent) · listing_photos (full gallery) · listing_details (both, plus every portal URL) · listing_history (timeline events) · trends_ensure · appraisal_tax · comps · uw_fill · growth_drivers · capex · opex.
import / research / refresh never set deal status or call advance_deal — those tools are not even available outside underwrite.
Comps kinds (cost)¶
comps_kinds resolves from (in order) the request, income_strategies, then deal strategy_intent / income_strategy: LTR → rent · STR → str · flip/wholesale/redevelop → sale · primary → all three. STR-only paid tools are removed from the worker unless str is in scope.
Config¶
| Env | Default | Meaning |
|---|---|---|
AUTOMATION_PLANNER_MAX_STEPS |
12 | Max worker turns per run — includes quality-check fixes |
AUTOMATION_MAX_PLANNER_TURNS |
24 | Max planner decisions per run |
AUTOMATION_RUN_TIMEOUT_SECS |
2400 | Wall-clock cap per run |
AUTOMATION_PHASE_TIMEOUT_SECS |
900 | Time limit for one worker / reviewer turn |
Hitting a run cap pauses the run (with a brief) instead of failing it; review, then restart.
Context & token use: on long runs, older tool results are replaced with a placeholder and older history is summarized once so the run can keep going. Playbooks (get_agent_manual, read_doc) are never cleared. Each worker turn and each planner/critic decision has a model-call cap; hitting it ends the turn cleanly, and a planner/critic that hits it without deciding is asked once more to decide. Tool errors go back to the model as text.
Nothing the models read is truncated: tool results, tool and field descriptions, the worker's reports to the planner, and the deal snapshot (write-up, all comments, handoffs, listing links, prior runs) arrive whole — a cut result silently hides data (run a4fd8dd2 cut get_deal and the underwrite playbook mid-JSON). Context size is managed only after use, by clearing and summarization above. Tool schemas are only made Gemini-compatible (e.g. field titles dropped) and are sent first on every call, so they are cache hits after the first. metrics.llm.cached_input_tokens shows how much input the cache served; set AUTOMATION_LLM_USD_PER_MTOK_CACHED_INPUT for the discounted estimate. The full transcript stays in steps_json; workspace-wide lists (list_deals, list_markets, list_buyers) are not given to the worker.
Exactly-once execution: a worker must claim a run (lease_owner / lease_expires_at) before executing it and renews the lease on a heartbeat (AUTOMATION_LEASE_TTL_SECS, default 300). A redelivered queue message for a run with a live lease is skipped, so a run longer than the queue visibility timeout is never executed twice. Each worker sweeps every AUTOMATION_SWEEP_INTERVAL_SECS: runs whose lease expired (worker died) fail with "stopped responding — restart"; queued rows untouched for AUTOMATION_REQUEUE_AFTER_SECS (and <24h old) are re-enqueued.
Run metrics: automation_runs.metrics (REST/MCP metrics) rolls up LLM calls, input/output tokens and latency per role (worker, planner, critic, brief, vision), MCP tool calls/errors/latency per tool, and paid calls (apify, airroi, firecrawl). Each worker turn in steps_json carries its own usage. est_llm_cost_usd appears only when AUTOMATION_LLM_USD_PER_MTOK_INPUT / _OUTPUT are set. started_at − created_at = queue wait. Paid calls made by platform code outside agent tools (import bootstrap fetch, trends refresh) are not counted yet.
Steps in steps_json¶
| Step | Meaning |
|---|---|
existing_deal |
Import linked to a deal the workspace already had (planner use_deal); the run continues as research |
import_listing |
Platform listing fetch (import) — one child row per portal tried (running → completed / failed / skipped + what it found), updated live |
plan_N |
Planner decision — reasoning + read-only checks in agent_log, then Next: <label> — <request>, Stop — …, Pause — …, or on import Use the existing deal — … / Look up the listing — … |
turn_N |
One worker turn: label, instruction, agent_log (full transcript), tool_calls, usage |
critic_N |
Critic verdict — reasoning + verification tool calls in agent_log, then Pass — …, Follow-up — …, Pause — … |
Assistant entries in agent_log carry thinking — Gemini's thought summary for that model call (why it is about to call a tool, what it concluded) — alongside content (the visible reply). The UI shows it above the tool rows so a run reads as reasoning → action → result. Planner, critic and brief steps are opened as running before they decide, and their thoughts / read-only checks stream in live (each event publishes an AutomationRunUpdated), then the decision line completes the same step.
| brief_1 | End-of-run brief |
MCP / REST¶
One entrypoint for every goal — MCP create_automation_run / REST POST /api/automation-runs — then poll get_automation_run. Restart (restart_automation_run) rebuilds the same request from the stored run.
| Goal | Body |
|---|---|
import |
exactly one of address / listing_url; optional income_strategies, deal_purpose |
research / underwrite |
deal_id; optional income_strategies, comps_kinds |
refresh |
deal_id + kind |
Reading runs over MCP: a finished run's steps_json is often 1M+ characters, so MCP returns it trimmed. list_deal_automation_runs defaults to detail="summary" (run fields + one line per step, no steps_json); get_automation_run defaults to detail="steps" (steps without agent_log / tool_calls). Read a transcript one step at a time: get_automation_run(run_id, detail="log", steps="turn_3") (drops thinking and tool outputs) or detail="full". REST (the web UI) still returns the full run.
goal may be omitted: kind implies refresh, a locator implies import. Common: aggressiveness. Quotas: import counts against the Quick Analyze cap; deal goals against the tab-refresh cap.