popagent

public

Latest change b6d33c15415ad98991d8aaafd44b4b993d19db65 - Add popagent settings-patch and document agent step-budget mechanics by AkurAI Build

---
name: popagent-contract-change
description: Change popagent backend routes, agent tools, lifecycle hooks, tasks, model behavior, or shared API contracts safely. Use for server-side observable behavior and cross-layer DTO changes.
---

# Popagent contract change

Read `../../../AGENTS_AGENT.md` and `../../../AGENTS_RULES.md`. Also read each domain file touched by the change: `../../../AGENTS_HOOKS.md`, `../../../AGENTS_MEMORY.md`, `../../../AGENTS_DOCUMENTATION.md`, `../../../AGENTS_CHANNELS.md`, `../../../AGENTS_BROWSER.md`, or `../../../AGENTS_OBSERVABILITY.md`. Read `../../../AGENTS_UI.md` for client-visible contracts.

1. Locate the current implementation and its owning contract test before editing. For Mastra agent topology, delegation, workflows, or skills, read the matching current page from `https://mastra.ai/llms.txt` and verify the installed `@mastra/core` type declarations before choosing an API.
2. Reuse wire DTOs from `src/api-types.ts`; do not redeclare response shapes in React code.
3. Runtime behavior that is database-backed configuration — model routing, supervisor/specialist step ceilings, tool concurrency, delegation bounds, task concurrency and timing — is tuned on the running instance, not by editing code or the seed migration. Read it with `popagent settings <section>` and change individual fields with `popagent settings-patch <section> <json>`; a bare `settings-update` replaces the whole section. Change the seeded values in `src/agent-runtime-settings.sql` only when fresh installs should differ, and never as a way to alter the running instance.
4. Preserve request validation, workspace/resource containment, request-context snapshots, abort propagation, redaction, and hook failure-mode behavior relevant to the path.
5. Use red-green-refactor for every observable contract: write and run the narrow failing test first, implement only enough to pass it, then refactor while green.
6. Run the narrow owning test, then affected tests and `bunx tsc --noEmit`. Run `bun test` once before handoff when required local services are available.
7. Live model and shared-service scenarios run only in the documented environment. Do not weaken deterministic tests merely because an integration dependency is unavailable.
8. Update the relevant `AGENTS_*.md` domain file in the same change and remove superseded facts.

For backend route-table changes, remember that the managed service requires a restart during authorized live validation; UI hot reload is not evidence that a backend route was replaced.