---
name: code-agent-contract
description: Checklist of the platform contract every FindAgent CODE agent must meet (six entry tools, findagent.json v1.2, skills[] and example_prompts, default-deny egress, credential slots as declarations, autobuild safety for Node and Python, display-only MCP UI panel) plus the submit-flow traps already hit. Use when building, reviewing or debugging a code agent that will not build, serves no tools, or never unlocks Submit.
---

# Code agent contract

## Contract

1. **Six entry tools**, all declared in `findagent.json` `skills[]` AND answered: `plan_inputs`, `open_form`, `run_form`, `run_full`, `list_capabilities`, `discover_intent`. A missing required argument answers `needs_input` naming the slot. The platform draws the form panel from the first three.
2. **`findagent.json` v1.2** at the repo root (a DXT `manifest.json` alone is read through an inferred contract that drops credential hosts): `schema_version "1.2"`, `kind "code-bundle"`, `name`, `entrypoint {path}`, `runtime {kind, version}` (node 22/24, python 3.13; Node 20 is not offered), `mcp {mode, command, args}`, `allowed_hosts[]` (top level in v1.2), `skills[]` (at most 40; id/name/description per tool, description at most 500 characters because the served tool list cuts there; each tool's typed `input_schema`), `example_prompts[]` (1-5), `serve` (`hosted` and/or `local`), `ui {path}`.
3. **Egress is default-deny.** `allowed_hosts` lists every host the code calls and nothing else. A host the caller chooses cannot be declared: take content as input instead.
4. **Credentials are declarations** (`credential_slots`: ref, label, `allowed_hosts` or `install_host`, `required`). A required slot not yet attached makes the gateway offer only `setup_credentials`, and a run with a required slot the buyer never saved is refused before the sandbox starts, for every tool; `required: false` keeps a tool usable without it.
5. **Autobuild**: the Node sandbox installs with npm (`npm ci` only for a committed `package-lock.json` / `npm-shrinkwrap.json`; `pnpm-lock.yaml` and `yarn.lock` are NOT read), so pin exact versions in `package.json`, use `npm run <script>` as `build_command`, no tracked `pnpm-workspace.yaml`, no PEM header in any file; Python needs `requirements.txt` with pinned, non-compiled dependencies and prebuilt panel HTML; stdout belongs to the MCP stream (log to stderr).
6. **Panel**: display-only or answers with `ui/message`; it never calls tools. No `ui.domain`, closed CSP, light and dark, usable at 390px.
7. **Agent memory (optional).** When `FINDAGENT_MEMORY_FILE` is set, read it FIRST (a path relative to the working directory; the file holds the JSON text; it is not set on a first run or when the memory is empty, so treat a missing variable as no memory). `FINDAGENT_MEMORY` (the same JSON as an environment variable) is only a fallback and is ABSENT for large memory: the sandbox environment has a hard limit of 4096 bytes, and credentials plus platform variables above about 4000 bytes are refused before the sandbox starts (`code_bundle_env_too_large`, creator-facing). Return a `__memory` object in the structured result to replace the memory: under 64 KB or the write is rejected and the old memory is kept; one user and one agent, hosted only, never a secret; keep caches bounded (newest N, a size cap). The platform strips `__memory` from what anyone sees.
8. **Versions.** A new version is a re-pull (`findagent_new_version` / `findagent_repull` / the dashboard), patch bump by default; the live version keeps serving until review approves it; an update that adds a credential slot, a slot host, a destructive tool or a changed `auth_scheme` is held until each connected buyer acknowledges it. A re-pull keeps the `skills[]` ids and typed `input_schema` that `findagent.json` declares; read the stored tool list once afterwards.
9. **A complete repo.** `findagent.json` plus a DXT `manifest.json`, `README.md`, `LICENSE`, `SECURITY.md`, `CHANGELOG.md`, the assistant entry files, the four MCP client configs, a CI workflow and tests. The template's `scripts/init_agent.py` creates the set and `scripts/check_repo_files.py` verifies it; the list is `scripts/repo-files.json`.

## Traps and gate

Traps seen on real submissions: category words that pulled an agent toward Legal and Agriculture (put the discipline in `tags`; the wizard now pre-selects only strong matches and you still pick a Discipline and a sub-discipline); `skills[]` missing so the agent served no tools; a `manifest.json` with no `findagent.json` (preflight warns, the declared hosts are lost); a `pnpm-lock.yaml` assumed to pin the sandbox install. Run `npx --yes @findagent/cli@0.4.1 check <repo>` (the whole-repo check), then the live stdio test. Start from https://github.com/FindAgent/agent-template.