AGENTS.md
+5 −6
https://raw.githubusercontent.com/colinhallett/message-cp/HEAD/AGENTS.md
− message-cp is a small server for a few people's agents, reached over stdio on its own machine or over HTTPS, with a handful to a few dozen agents per account. Agents and messages belong to accounts, and nothing may cross between accounts: a finding that one account can see or affect another account's data is always blocking. Other scale, paging or permission concerns are weighed against that scale:− - A file that code in `src/` writes a token or key into, or that a command `src/` prints tells someone to write one into, ends up readable only by its owner even when it already exists. A mode option or `umask 077` sets the mode only of a file the write creates; a file already there keeps its mode. So the write creates the file exclusively and never replaces one already there, as `writeTokenFile` in `src/init.ts` does (`openSync(file, "wx", 0o600)`); or it removes the file first, as `saveListenT− - SQL you add or change inside an `.immediate()` transaction, and a `DELETE` you add or change whose `ON DELETE CASCADE` or foreign key reaches a child table, holds SQLite's write lock while it runs. Check its plan with `EXPLAIN QUERY PLAN` against a database made by `openDb` before opening the PR, and put the plan lines in the PR description. Follow a cascade through every level: in `src/db.ts`, `webhook_deliveries.message_id` cascades from `messages` and is found through `webhook_deliveries_by− - Rules for a paged read (`LIMIT ? OFFSET ?`) over a history table and for a table whose row ids the API, the dashboard or a tool hands out (`INTEGER PRIMARY KEY AUTOINCREMENT`, rebuilding an existing table) are in `docs/agent-rules/sql.md`. Read it before adding or changing such a read or table.− - Rules for request paths in `src/http.ts` (body, hold and outbound caps), for code that accepts a URL from a flag, environment variable or file (in `src/cli.ts`, `src/connect.ts`, `src/init.ts`, `src/wait.ts`, `scripts/` and `ops/*.sh`), and for commands that code in `src/` prints for a person or agent to paste are in `docs/agent-rules/http-and-cli.md`. Read it before changing any of them.− - A tool that acts as the caller passes the caller's registration down, from `session.requireAgent()` in `src/server.ts` (the caller's `Identity` from `src/agents.ts`, plus its name), not just the name from `session.require()`; `unregister` with no name, which passes `session.registration` as `own`, does the same. A statement that reads or changes the caller's own state finds its row by `id`, `registered_at` and `instance` (with `removed_at IS NULL`), never by name, inside the same transaction a+ message-cp is a small server for a few people's agents, reached over stdio on its own machine or over HTTPS, with a handful to a few dozen agents per account. Agents and messages belong to accounts, and nothing may cross between accounts: a finding that one account can see or affect another account's data is always blocking. An agent's or person's name is unique only within its account, ignoring case (`agents.name` in `src/db.ts`), and every `message-cp` command that takes `--account` and acts o+ - Rules for SQL that holds SQLite's write lock (inside `.immediate()`, or a `DELETE` whose cascade reaches a child table), for a paged read (`LIMIT ? OFFSET ?`) over a history table and for a table whose row ids the API, the dashboard or a tool hands out are in `docs/agent-rules/sql.md`. Read it before adding or changing SQL in `src/`, or `SCHEMA` and `migrate` in `src/db.ts`.+ - Rules for request paths in `src/http.ts` (body, hold and outbound caps), for code that accepts a URL from a flag, environment variable or file (in `src/cli.ts`, `src/connect.ts`, `src/init.ts`, `src/wait.ts`, `scripts/` and `ops/*.sh`), for commands that code in `src/` prints for a person or agent to paste, and for files that code in `src/` writes a token or key into, or prints a command to write one into, are in `docs/agent-rules/http-and-cli.md`. Read it before changing any of them.+ - Rules for a tool that acts as the caller and for a statement that reads or changes the caller's own state (finding the caller by its `Identity`, not its name, and where matching by name stays right) are in `docs/agent-rules/caller-identity.md`. Read it before adding or changing a tool in `src/server.ts` or such a statement in `src/agents.ts`, `src/messages.ts` or `src/channels.ts`.+ A test that starts `src/index.ts` (the stdio server) as a child process builds the child's `env` from `process.env` without `MESSAGE_CP_AGENT` and `MESSAGE_CP_AGENT_KEY`, as "reports package.json's version to a client over stdio" in `test/version.test.ts` does, and sets either one only on purpose. `registerFromEnv` in `src/agents.ts` refuses one without the other, so a child that inherits a shell's lone `MESSAGE_CP_AGENT_KEY` exits before the test starts.