Agent-First PSQL v0.6.1: Embedded Skill Installer and SQLSTATE on Connect

Agent-First PSQL v0.6.1 is a focused follow-up to v0.6 that closes two gaps for agents: how the skill arrives on a machine, and how connection failures are reported.

The skill ships inside the binary

v0.6 added skills/agent-first-psql.md so coding agents could load afpsql’s operating guidance — but the file still had to be copied into the right place by hand for each agent target.

v0.6.1 makes that one command:

afpsql skill status
afpsql skill install
afpsql skill status

The skill markdown is embedded in the binary. install writes it to the per-agent locations Claude Code and Codex look at, tags the file with a generated-by header, and status reports installed and valid for each target. uninstall removes only files afpsql itself wrote — a third-party skill that happens to share the same name is left alone unless --force is passed.

The binary is now the single source of truth. Upgrading afpsql and re-running skill install is the same gesture as updating the permission and session rules an agent operates under.

connect_failed keeps SQLSTATE, message, detail, and hint

Before v0.6.1, query-time PostgreSQL errors carried sqlstate alongside message, detail, and hint, but a connection-time rejection collapsed into a single prose error string. An agent that saw connect_failed had to guess whether the cause was a bad password, a missing role, a missing database, a capacity limit, or a server still starting up.

v0.6.1 preserves the PostgreSQL diagnostics on connect_failed:

{
  "type": "error",
  "error_code": "connect_failed",
  "error": "connect failed: password authentication failed for user \"app\"",
  "sqlstate": "28P01",
  "message": "password authentication failed for user \"app\"",
  "hint": "password authentication failed; check --user and --password-secret-env PGPASSWORD, or use an authentication method accepted by pg_hba.conf",
  "retryable": false
}

sqlstate lets an agent route the failure without reading prose: 28P01 → bad password, 28000 with “role … does not exist” → wrong user, 3D000 → wrong database, 53300 → too many connections, 57P03 → server not accepting yet. retryable is set from the SQLSTATE class — 08*, 57P03, 53300, 53400, 58000, 58030 are retryable; auth, role, and database mistakes are not. Non-PostgreSQL connect failures (sandbox blocks, missing sockets, SSH transport misuse) still carry an actionable hint but do not invent a SQLSTATE they did not have.

Skill guidance: fewer preflights, one retry on sandbox block

The embedded skill text was tightened in two places agents kept tripping on:

• Skip the routine afpsql --help preflight before known query forms. The CLI contract is stable; spending a turn re-reading help before every query is wasted motion.
• When a local connection is blocked by sandbox or OS policy, retry once with explicit approval before changing --host, --user, or the SQL. The old reflex was to alter connection parameters and try again, which masked the real cause (a policy decision, not a config mistake).

Synopsis: “read-only by default”

The project synopsis changed from “safe by default” to “read-only by default”. “Safe” described a feeling. The write boundary is the actual contract: native CLI and pipe mode default to PostgreSQL read-only transactions, and writes require explicit --permission write or --permission ssh-write.

Adoption

brew install agentfirstkit/tap/afpsql   # macOS / Linux
cargo install agent-first-psql          # any platform

afpsql skill install
afpsql skill status

For the v0.6 design and SSH transport that this release builds on, see the v0.6 release post.