Inspect reads used by adaptive tests — dedicated helpers and product APIs tests already fetch
Adaptive tests in tests/manual/ sometimes need to read state the
visible UI does not prove. Search this page first. Reuse a listed
path. Do not invent a second helper for the same question.
Two kinds:
| Kind | Auth | When to add cronSecret: true |
|---|---|---|
| Helper | Session + Bearer CRON_SECRET | Always. Dumps internal state the app does not call. |
| Product read | Session (or guest cookie) only | Never. The live app already uses this path. |
Create a new helper only when nothing below answers the question.
Use /create-helper-endpoint and .cursor/rules/helper-endpoints.mdc.
Never print CRON_SECRET. Do not curl with copied cookies. Do not
Distil, promote, or settle from a helper.
POST /api/z-agent/my/rooms/:roomId/settle is a write. Many prompts
forbid it. It is not a helper. Body flags: guard and arvist (default
true) run quiet-chain work now; simulateNewDealQuiet: true stamps the room
past the new-offer quiet period and ends the current sitting (same as
seven days of silence) so ZLY-1934 tests need not wait a week
(see Sibling rooms).
route() flag: Util Server Package.
| Path | Kind | What a test uses it for | Prompts |
|---|---|---|---|
GET /api/z-agent/my/account-memory | Helper | Durable account facts after Personalize | zly-1897-update-agent-immediate-memory.md, personalize-answers-apply-on-zlink.md |
GET /api/z-agent/my/rooms/:roomId/memory | Helper | Seeded host facts; quiet / newDealFork inspect | zly-1897-update-agent-immediate-memory.md, zly-1934-quiet-new-offer-or-continuation.md, personalize-answers-apply-on-zlink.md |
GET /api/z-agent/my/rooms/:roomId/created-memories | Product | Distil writes for the Memory created chip; diagnosis if the chip is missing | zly-1897-update-agent-immediate-memory.md, personalize-answers-apply-on-zlink.md |
GET /api/z-agent/my/room | Product | Resolve the talent home roomId | zly-1897-update-agent-immediate-memory.md, onboarding-correction-updates-memory.md, personalize-answers-apply-on-zlink.md |
GET /api/z-agent/my/conversations | Product | Newest deal row / inbox list | zly-1897-update-agent-immediate-memory.md, personalize-answers-apply-on-zlink.md |
GET /api/z-agent/my/rooms/:roomId/full-transcript | Product | Talent-visible deal transcript (marker / guest turns) | zlink-guest-messages-not-lost.md |
GET /api/z-agent/my/rooms/:roomId/brand-transcript | Product | Brand-pane transcript only (sibling of full-transcript) | — |
GET /api/z-agent/visitor/rooms | Product | Guest room view, stored user turns, login-hold | zlink-guest-messages-not-lost.md, brand-login-required-error.md |
GET /api/z-agent/my/campaign | Product | Whether a campaign name + /c/ URL persisted | launch-campaign.md |
GET /api/z-agent/onboarding/room | Product | Onboarding room / beat load | onboarding-message-order-scrambled-on-reload.md |
GET /api/account/z-link | Product | Live public link while Agent Links is still loading | update-agent-full-z-link.md, personalize-answers-apply-on-zlink.md |
GET / PUT /api/account/social-links | Product | Saved social links on Profile | profile-social-links-imdb-spotify.md |
Session + Authorization: Bearer $CRON_SECRET. Cookie alone → 401.
Purpose: Prove Arvist has already promoted standing facts into durable account memory (default voice seed, Personalize rules) — not only the home chat sitting.
Endpoint: GET /api/z-agent/my/account-memory
Auth: Session + Bearer CRON_SECRET
Query:
| Param | Description |
|---|---|
since | Optional ISO time. updatedSince is true only when the document is newer. |
Response:
| Field | Description |
|---|---|
updatedAt | Last durable write, or null |
updatedSince | True when since was sent and the document is newer |
facts | User-facing leaves (path, value) |
Implementation:
apps/zooly-app/app/api/z-agent/my/account-memory/route.tsgetOwnAccountDurableMemory in packages/z-agent/srv/src/account-durable-memory.tsUsed by: tests/manual/zly-1897-update-agent-immediate-memory.md,
tests/manual/personalize-answers-apply-on-zlink.md
Purpose: Prove a room the talent can already open was seeded with standing host facts (for example a new Z-Link deal sitting).
Endpoint: GET /api/z-agent/my/rooms/:roomId/memory
Auth: Session + Bearer CRON_SECRET
Params: roomId — room the caller can open in Conversations
Response:
| Field | Description |
|---|---|
roomKind | Room kind (for example deal) |
hostSyncedAt | When the host seat was last stamped as seeded or merged |
facts | User-facing leaves (seeded host facts use host.* paths) |
lastParticipantMessageAt | Latest human chat time, or null |
isQuiet | True when that time is older than the new-offer quiet period (or the settle simulate-quiet stamp) |
quietDays | Quiet period in days (Z_AGENT_NEW_OFFER_QUIET_DAYS, default 7) |
newDealForkPending | Open new-vs-continuation / booked-change ask, or null |
distil | DistilMem summary: ran, latestRunAt, latestError, updateCount. Distinguishes never-ran vs crash. |
arvist | Same shape for promotion runs on this room |
Implementation:
apps/zooly-app/app/api/z-agent/my/rooms/[roomId]/memory/route.tsgetOwnedRoomMemory in packages/z-agent/srv/src/room-memory-inspect.tsUsed by: tests/manual/zly-1897-update-agent-immediate-memory.md,
tests/manual/zly-1934-quiet-new-offer-or-continuation.md,
tests/manual/personalize-answers-apply-on-zlink.md.
Session (or guest) only. Do not add cronSecret. The app owns these.
Purpose: Facts Distil just wrote, for the live Memory created chip. Tests also poll this if the chip never appears.
Endpoint: GET /api/z-agent/my/rooms/:roomId/created-memories
Query: after — ISO time of the turn; only Distil after this is listed
Response: latestRunAt, latestError, latestErrorAt, ran, memories[] (path, value). ran: false means Distil never started after after. latestError without latestRunAt means Distil crashed (the chip will not appear).
Implementation: apps/zooly-app/app/api/z-agent/my/rooms/[roomId]/created-memories/route.ts — listCreatedMemories
Used by: tests/manual/zly-1897-update-agent-immediate-memory.md (diagnosis),
tests/manual/personalize-answers-apply-on-zlink.md. Resolve roomId via Home room first when Personalize has no room in the URL.
PATCH on the same path is the chip edit/discard — product write, not a helper.
Purpose: The talent’s home sitting. Tests use roomId to call
created-memories or settle (when a prompt allows settle).
Endpoint: GET /api/z-agent/my/room
Response: includes roomId, displayName, messages
Implementation: apps/zooly-app/app/api/z-agent/my/room/route.ts — ensureHostRoom / openHostRoom
Used by: tests/manual/zly-1897-update-agent-immediate-memory.md, tests/manual/onboarding-correction-updates-memory.md, tests/manual/personalize-answers-apply-on-zlink.md
Purpose: List sittings. Tests take the newest kind === "deal" row
for roomId / hasOffer.
Endpoint: GET /api/z-agent/my/conversations
Response: array, newest first; rows include kind, roomId, hasOffer
Implementation: apps/zooly-app/app/api/z-agent/my/conversations/route.ts — listInboxConversations
Used by: tests/manual/zly-1897-update-agent-immediate-memory.md
Purpose: Every sitting the talent may read in a deal room (brand pane plus talent pane when they hold that seat). Tests confirm guest messages reached the talent.
Endpoint: GET /api/z-agent/my/rooms/:roomId/full-transcript
Implementation: apps/zooly-app/app/api/z-agent/my/rooms/[roomId]/full-transcript/route.ts — getInboxDealTranscript
Used by: tests/manual/zlink-guest-messages-not-lost.md
Brand-pane only: GET /api/z-agent/my/rooms/:roomId/brand-transcript
(getInboxBrandTranscript). Same auth. No tests/manual prompt names it
yet; prefer full-transcript when the talent must see guest turns.
Purpose: Guest (or signed-in visitor) deal sitting. Tests count stored
user turns and the login-hold (loginRequired, loginRequiredReason).
Endpoint: GET /api/z-agent/visitor/rooms
Query: slug required; roomId, preview, campaign optional
Auth: optional — session or guest cookie
Implementation: apps/zooly-app/app/api/z-agent/visitor/rooms/route.ts — openVisitorDealRoomForZLink
Used by: tests/manual/zlink-guest-messages-not-lost.md, tests/manual/brand-login-required-error.md
Purpose: Launch-a-campaign setup room plus the committed campaign
(name + share URL). campaign: null means commit did not persist.
Endpoint: GET /api/z-agent/my/campaign
Implementation: apps/zooly-app/app/api/z-agent/my/campaign/route.ts — getMyCampaign
Used by: tests/manual/launch-campaign.md
Purpose: Landing-flow interview room (and beat load). Tests inspect this when first-ask or message order looks stuck.
Endpoint: GET /api/z-agent/onboarding/room
Query: service required; roomId optional
Auth: optional (guest cookie on first contact)
Implementation: apps/zooly-app/app/api/z-agent/onboarding/room/route.ts — resolveOnboardingRoom
Used by: tests/manual/onboarding-message-order-scrambled-on-reload.md
Purpose: Live public link while Agent Links is still loading.
Endpoint: GET /api/account/z-link
Implementation: apps/zooly-app/app/api/account/z-link/route.ts
Used by: tests/manual/update-agent-full-z-link.md,
tests/manual/personalize-answers-apply-on-zlink.md
Purpose: Profile socials. Tests GET then PUT through the visible
form; inspect the PUT if save fails.
Endpoint: GET / PUT /api/account/social-links
Implementation: apps/zooly-app/app/api/account/social-links/route.ts
Used by: tests/manual/profile-social-links-imdb-spotify.md
If you add a helper or a test starts fetching another inspect path, append a catalog section and a row in the index.