Connectors
Connectors: a third-party account linked on the gateway's host so a brain tool works (WhatsApp, Gmail, the Dot, feeds, Apple Health, OBS); one row in the gateway's registry joins a setup census row (its state) with what it unlocks, its one action and the steps read from its README at build time; the Admin's Setup section draws them as a Connections card (AdminSetupCensus.connections) and the Glyph's welcome window as a Connections page from <state>/connections/connections.json; the menu says Connect accounts while one waits.
Living doc, checked against the code 2026-11-14
connector.v1 — a connector: an account linked on the gateway’s host, walked in the app
- Status: landed, on by default.
- Scope: a connector is a third-party account linked on the gateway’s host so a brain tool can work: WhatsApp paired with wacli, a Gmail sign-in, the Dot’s worker, the feed list, the Apple Health export, the OBS connection file. Setup happens in the app. Vulpine.app’s welcome window (a Connections page after the permissions) and the Gateway window’s Setup section (a Connections card) walk each one from its live state.
- The plugin point: a connector registers one row in the gateway’s registry
(
crates/voice_gateway/src/connectors.rsREGISTRY) and joins one setup census row that says its state. Neither UI names a connector: both draw whatever rows the gateway sends.
The row
A registered connector says:
| field | what |
|---|---|
id |
the setup census row it joins (whatsapp); that row carries label, state, why and next_step |
unlocks |
what connecting it unlocks, in plain words |
tools |
the brain tools it unlocks (pi_whatsapp) |
action |
the one action, as its button says (Link WhatsApp): it opens the steps |
guide |
the README that walks it, repo-relative (runtime/messages/README.md) |
steps |
that README’s steps, in order |
The steps are read from the README at build time (include_str! and
vulpine_onboarding::connectors::guide_steps). The registry names the README and the headings of the sections that
walk it. A section gives its list items, or its paragraphs when it has no list. An indented code block joins the step
before it as a code span; emphasis and links read as words. There are at most 10 steps, each cut at a word within 480
characters. The README is the one source: an edit there reaches both pages at the next build. Every registered guide
has at least one step and names a file that exists, and every held tool (crates/voice_gateway/src/held_tools.rs)
has a registered connector.
Facts and the adapter’s status
A row may carry facts: labeled plain words that say what the connector does once connected. facts is optional
on both wires; an empty list is left out. A row has at most six facts, a label within 48 characters and its words
within 240. They come from two places, in this order:
- the registry row’s
about(fixed: the feeds’Reads aloud,Adds a feedandCadence); - the adapter’s own status file, which the held tool names (
Statusincrates/voice_gateway/src/held_tools.rs): a JSON object{schema: "vulpine.connector-status.v1", at_unix, fresh_at_unix?, facts: [{label, says}]}, at most 64 KiB, written owner-only by the adapter (tools/feeds/feedctl.pywritesfeeds-status.jsonbeside the feed store at every list change and every refresh:SourcesandLast fetched). The gateway reads it withvulpine_onboarding::connectors::read_status, which cuts each fact to its bounds and drops an empty one; a file of another schema is ignored.
The status file’s fresh_at_unix is the adapter’s last real run. A held tool may give a freshness rule
(Fresh): how old that run may be, why when it is older, and the one next step. A row that is set up and on, whose
last run is older, reads degraded (Not healthy) with that next step. The feeds’ rule is two hours, four of the
refresh timer’s 30-minute passes. A status file with no run yet, or none at all, says nothing; readiness speaks for
those. The bind never reads the status.
States are the census’s closed words. ok is Connected. not_set_up and degraded wait on the person and count in
Vulpine.app’s menu and the pages’ summaries. off is a choice (switched off in the Admin’s Tools section, or no loadout
lists the tool) and is drawn quiet.
Where the rows go
- The Admin reads them in the setup census:
AdminSetupCensus.connections(AdminSetupConnection, optional on the wire). A gateway without connector.v1 sends none and the card is not drawn. Each connection joins the row with the sameid, once:validate_setup_censusrefuses a connection without its row or named twice. The Admin socket’s sanitizer takesunlocksandstepsas prose: a path or an address inside a step hides only that word. The connectors’ rows are drawn in the card, not in the Setup section’s families. - Vulpine.app on the gateway’s Mac reads
<state>/connections/connections.json(vulpine.connections.v1:at_unixand the joined rows). The folder is owner-only and the file is a staging file renamed over. The gateway rewrites it when a row changes and at least every minute; its publisher reads the held tools’ readiness every 10 s. The page isConnectionsView:source(this_mac,staleafter 180 s without a rewrite,elsewherewith no record), the rows,left(waiting),all_setand a summary. Vulpine.app on another Mac finds no record and says where connections are set up. The right-click menu says “Connect accounts…” while every grant is on and a connector waits (welcome_entry’sconnections_left), and the window then opens on the page.
Wire names never contain token. Nothing here links, signs in or writes: the steps say where that happens (a
terminal, a phone, ChatGPT), and the row turns Connected by itself on the next read.
Adding a connector
- Its readiness: a setup census row whose state says whether it is linked (a held tool’s checks in
held_tools.rs, or any census row). - Its README: a section with numbered steps, ending with what the person sees when it worked.
- One
Connectorrow inREGISTRY: the censusid,unlocks,tools,actionand theGuide(the README’s path,include_str!of it, the section headings).
The record Vulpine.app reads carries only rows its publisher reads without the Admin service, which are the held tools’ rows. A connector that joins another census row shows in the Admin only.