Skip to main content

capabilities-contract

The capabilities contract as a Python library, in two parts. capabilities_contract.capability is the code every capability shares - the core, store and connections tiers - which each capability binds rather than carries a copy of; see Capability. capabilities_contract.db is the one way the capabilities manager, its capabilities and ContextKit reach the shared PostgreSQL database: resolve which database a project uses, connect bound to its schema, migrate each owner's tables once under a ledger, and report where they stand. It does nothing else: no SQLite, no project registry, no records.

Install

pip install capabilities-contract

Its dependencies are psycopg[binary]>=3.2,<4 and pynacl>=1.5,<2, each imported lazily: import capabilities_contract.db does not import psycopg, only connect, batch, migrate, status, store_major, announce and Follower do, and only sealing or opening a secret of the vault imports PyNaCl. A capability declares it in its PEP 723 header by a version range, so a release inside the range reaches it with no edit of its own:

# /// script
# dependencies = ["capabilities-contract>=0.9,<1"]
# ///

Capability

capabilities_contract.capability holds the code every capability of the capabilities package shares, as three tiers, each one file under capabilities_contract/capability/tiers/: core (the declaration surface - summary, manifest, references, guide, ids - and the file, project and I/O plumbing), store (the records adapter for identifiers, policy, settings, connections and documents, and a store-mode project's records in its store) and connections (the credential cascade and the connection resolver, for a capability that implements connections).

A tier is not a module. bind(namespace, *tiers) executes each named tier, in order, in namespace, which a capability passes as its own globals() where it has defined its declarations:

from capabilities_contract.capability import bind as _contract_bind
_contract_bind(globals(), "core")
_contract_bind(globals(), "store")
_contract_bind(globals(), "connections")

So a tier reads the capability's declarations (NAME, SCOPE, STATE, CRED_KEYS, WRITE_VERBS and the others the package docstring lists) and calls its hooks (_cmd_connections, _inventory, _tables ...) as the capability's own code would, and every name it defines is the capability's: a test that replaces one on the capability's module replaces it for the tier as well. A tier is compiled under the namespace's own from __future__ import annotations, as its text would be were it part of the capability's file.

A capability that declares TITLE, its human name fixed by its author, answers it in its manifest as title, and one that declares LUCIDE_ICON, the Lucide name of its line icon, answers it as lucide_icon; neither appears where it is not declared, and the name a capability is addressed by stays NAME. A capability that declares TRANSLATIONS - an object keyed by language code (ru, et), each an object of an optional title and description, its title and summary in that language - answers it as translations, and it too appears only where declared.

A capability that declares TABLES answers store_major in its manifest: the store major the library it runs on reads (STORE_MAJOR, see Migrate), and owners, every owner its migrate migrates, in order, its own last. Beside its _tables() builder it may define an _owner_tables() hook returning a list of (owner, steps, major, minor): further owners whose tables it migrates, such as a library's tables its own steps reference. migrate migrates those first, in order, then its own, and migrate and migrate status answer for its own owner at the top level as before, with one answer of the same shape per further owner under other_owners; without the hook there is no other_owners and owners names its own alone. Its migrate and migrate status answer to the machine ceiling like any verb, except under the store upgrade (CAPABILITIES_STORE_UPGRADE=1), where a capability quarantined on the machine still migrates its tables; no other verb passes a quarantine.

Before its first read or write of a store, a process running the store tier reads that store's major once (store_major) and refuses a store at another major than STORE_MAJOR: a lower one with store_upgrade_needed, whose hint names capabilities store upgrade and capabilities store upgrade --check, and a higher one with schema_too_new, whose hint names capabilities self-update, then capabilities update. The refusal is a StoreError with that slug, raised where the tier raises a store it cannot reach, so a project's records are never read as empty from a store whose tables moved. An empty store passes, and under the store upgrade (CAPABILITIES_STORE_UPGRADE=1) nothing is refused.

capabilities_contract.capability.store is the store tier as a module of its own, for a process that carries no capability - the capabilities manager, a capability's bundled service, a test. tier_path(tier) gives a tier's file and TIERS names the three.

Which database

resolve_setting(project_root) returns the database setting in force for a process standing in that project, as a Setting, reading and never writing. It asks three levels in order, and the first that answers is used whole, never completed from a lower level:

  1. project - the AGENTKIT_DB_* keys in the project's .env.local and .env, .env.local winning key by key;
  2. environment - the same keys in the process environment;
  3. machine - the machine's store setting file, $XDG_CONFIG_HOME/agentkit/store.json, or ~/.config/agentkit/store.json when XDG_CONFIG_HOME is unset, an agentkit.store.v1 document whose format is the capabilities package's SHEBANG.md, "The store setting". setting_path() gives its absolute path.

A level answers when it sets any AGENTKIT_DB_* key to a non-empty value, or, for the machine level, when the file exists. project_root=None means the process stands in no project, and the project level is not asked.

The keys (KEYS): AGENTKIT_DB_URL, AGENTKIT_DB_HOST, AGENTKIT_DB_PORT (default 5432), AGENTKIT_DB_NAME, AGENTKIT_DB_USER, AGENTKIT_DB_PASSWORD, AGENTKIT_DB_SCHEMA (default agentkit), AGENTKIT_DB_SSLMODE (default require), AGENTKIT_DB_SSLROOTCERT, AGENTKIT_DB_TRANSACTION_HOST, AGENTKIT_DB_TRANSACTION_PORT, AGENTKIT_DB_TRANSACTION_POOLER. Within one level AGENTKIT_DB_URL wins and that level's other keys are ignored, except AGENTKIT_DB_SCHEMA and the three transaction keys, which apply beside a URL.

The store has one address unless a level names a transaction address as well: AGENTKIT_DB_TRANSACTION_HOST and AGENTKIT_DB_TRANSACTION_PORT, or transaction_host and transaction_port in the machine file. It is the same store reached at another endpoint, typically a transaction-mode pooler such as Supabase's on port 6543, and it takes the level's own database, user, password, sslmode and schema; a transaction address naming only a port keeps the session address's host, and one naming only a host keeps its port. The address the level names otherwise is the session address. Setting.has_transaction_address says whether a level named one, that is whether the store's two addresses are named apart, Setting.transaction_kwargs() gives the driver's arguments for it (the session address's when none is named), and the report shows it under transaction. A transaction address alone does not make a level answer whole: a level setting only a transaction key is refused as incomplete, never completed from a lower level. A transaction port is 1-65535, a transaction host has no whitespace, and sslmode disable reaches only a local transaction host.

A store whose one address - no transaction address named - is a known transaction pooler, Supabase's (a host under pooler.supabase.com on port 6543), is transaction-only: every capability works through it, since its transaction connections reach it, and it has no session address, which only speeds up noticing changes (see Changes). Naming its session pooler apart gives it one: the same host on port 5432 as the address, and port 6543 as the transaction port. A level may also declare its one address a transaction pooler of any provider - a self-hosted PgBouncer in pool_mode=transaction, or another provider's transaction-mode pool - with AGENTKIT_DB_TRANSACTION_POOLER set to true (or 1; false and 0 declare nothing), or "transaction_pooler": true in the machine file; such a store is transaction-only exactly as a store whose one address is Supabase's transaction pooler is. Setting.transaction_pooler says whether a level declared it, and the report shows transaction_pooler: true when one did. The declaration is refused as bad_store_setting beside a transaction address named apart, since it is about the one address, and on any value other than those. A library older than 0.38.0 refuses a machine file or a project level carrying it as bad_store_setting, and ignores the key in the process environment, so it is declared only once every tool on the machine reads it. Setting.has_session_address says whether the store has a session address: true when a transaction address is named apart, the address being then the session address, or when its one address is neither declared nor known a transaction pooler. The setting's format is the same either way. A URL is a postgresql:// or postgres:// URL; one that names no sslmode is connected with require. A project file setting a key with the prefix that is not one of these is refused.

The checks are the same at every level: host, database and user with no whitespace, port 1-65535, sslmode one of require, verify-ca, verify-full, or disable for a local host (localhost, a loopback address or a Unix socket directory, which is also what a URL naming no host reaches); disable elsewhere, allow and prefer are refused as sslmode_too_weak; a schema is a lowercase identifier and never public, information_schema or pg_*. A refusal from the project or environment level names the level and the files or variables it read. A machine file of a newer agentkit.store.* version is refused as store_setting_too_new. With no level answering it raises DbError("store_not_configured", ...) with a hint naming the keys and capabilities store set.

Setting.level names the level that answered (LEVELS), and Setting.sources every file, as an absolute path, or variable that supplied a value in force. Setting.report() gives the whole setting for a status or doctor surface with every secret replaced by ***: the password field, or for a URL the parameters libpq reads from it (every parameter libpq's own option table marks as a password, such as password, sslpassword and oauth_client_secret, and the SCRAM keys hidden, sslmode defaulting to require), never the URL's text; a URL libpq cannot parse reports as {"unparseable": true}. Under addresses it names the address each kind of connection dials, as libpq resolves it (a port named nowhere is PGPORT's or 5432, a host named nowhere PGHOST's): {"transaction": {"host", "port"}, "session": {"host", "port"} | null}, transaction the transaction address, or the one address when none is named apart, and session the session address, null for a transaction-only store. The port is a number; for a URL naming several hosts both are libpq's comma-separated lists, and a host libpq leaves to its local default, or a URL it cannot parse, gives null. The repr never shows the password or the URL.

Connect

from capabilities_contract.db import DbError, Step, connect, migrate

conn = connect(application_name="automations", project_root=root)

connect(*, application_name, project_root=None, setting=None, connect_timeout=10, transaction=False, local_settings=None) returns a psycopg 3 connection to the database resolve_setting(project_root) names, or to setting when one is passed, whose search_path is that setting's schema alone, never public, so unqualified names land in that schema. The schema need not exist yet: migrate creates it, in the schema the connection is bound to. A store that does not answer within connect_timeout seconds (CONNECT_TIMEOUT_SECONDS) is refused as store_unreachable. Both ends of the connection send TCP keepalives - after 15 seconds idle, every 5 seconds, giving up after 3 unanswered probes - so the store drops a client that died without closing and the client learns of a store that went away. A keepalive is never sent while data the client sent waits for its acknowledgement, so the client also gives the connection up once what it sent has gone unacknowledged for 20 seconds (libpq's tcp_user_timeout, TCP_USER_TIMEOUT_MILLISECONDS, on a platform whose TCP offers it): a network flow that stopped carrying packets without a FIN or a reset fails in that time as a lost connection, rather than when the store ends the session.

That is a session connection, to the session address: it binds the schema for its session and may hold session state, as a process holding LISTEN must. With transaction=True, connect returns a transaction connection, to the transaction address, or to the one address when the setting names none, also when that address is a transaction pooler. It carries no session state, so a transaction-mode pooler, which hands the server session to another client after every transaction, serves it correctly: psycopg prepares no statement on it (prepare_threshold=None), the schema is bound with SET LOCAL search_path at the start of every transaction rather than once for the session, also around each statement in autocommit mode, and a statement that would leave state in the session - LISTEN, UNLISTEN, PREPARE, a session SET or RESET, set_config(..., false), a session advisory lock, a cursor WITH HOLD - is refused as session_state before it is sent. Transaction-level state is fine: SET LOCAL, set_config(..., true), pg_advisory_xact_lock. local_settings, a mapping of run-time parameters such as {"statement_timeout": "30000"}, is set beside the schema at the start of every transaction of a transaction connection, and once for the session of a session connection. A transaction connection sends no startup option, which a transaction-mode pooler refuses: each run-time parameter the setting's options or PGOPTIONS names (-c name=value, --name=value) is set for each of its transactions instead, and default_transaction_read_only=on makes each of them read-only; any other startup option is refused as session_state. A transaction connection at a transaction address of its own makes one round trip as it connects, severed when it is not back within connect_timeout, so a pooler that holds the client while the store behind it does not answer is refused as store_unreachable in that time rather than after the pooler's own wait. On a transaction connection, a statement that would open a transaction and is one of its own - any statement in autocommit, or a plain read (SELECT, WITH, VALUES, TABLE or SHOW, naming no write, lock, sequence or setting) at READ COMMITTED - reaches the store in one round trip: the schema binding, the statement and its commit go as one simple query, or as one pipeline when the statement takes parameters, so the store never holds a transaction that waits on the client, and the connection is idle after it, never idle in transaction; a transaction-mode pooler hands the server session on as soon as it answers. A read inside a transaction that is open - a transaction() block, or after a write not yet committed - runs in that transaction, and a write that opens a transaction leaves it open for commit(), as before. A connection set to another isolation level, or to read_only or deferrable, opens a transaction for a read as before. Client-side TCP keepalives apply to both kinds; only a session connection also asks the server to probe it. A server-side (named) cursor is not bound; use client cursors on a transaction connection. migrate and status work on either kind.

A transaction connection is the process's working connection, since it carries nothing from one transaction to the next: the first connect(..., transaction=True) opens it, close() or leaving with ends the loan - rolling back what was not committed and resetting what the borrower changed, such as autocommit or row_factory - and every later connect for the same address is lent that same connection, its schema, local_settings and application_name bound for each of its transactions as that call names them. A short command therefore connects once, and a long-running process keeps one connection for all its work. A loan taken while another is still out gets a working connection of its own; each beyond the first is closed once it has sat idle for 30 seconds (SPARE_IDLE_SECONDS), and every one is closed when the process exits. disconnect() closes the idle ones at once, for a process that is about to wait a long time without the store; disconnect(every=True) closes the lent ones too. A child of fork never uses or closes its parent's. After close() the connection reads as closed and refuses statements, as any closed connection does. A session connection is never lent: each connect without transaction opens one, and its close() closes it.

A working connection the store or the network lost is replaced: as it is lent, one the store closed is noticed without a round trip, and one that sat idle for 10 seconds (PING_AFTER_SECONDS) makes one round trip, cut at the connect timeout, so a connection that stopped answering is not waited on. One the store or the network closed while it was lent is replaced, without a round trip, before a statement that is a transaction of its own is sent on it. A statement that finds its connection gone before anything of its transaction reached the store - the statement that opens a transaction, a statement in autocommit before it is sent, or the start of a transaction() block - runs once more on a new connection in place of the old one. A plain read that is a transaction of its own runs once more on a new connection whenever it loses its connection, while a write in autocommit that was sent is never sent again, since its commit went with it. So does a plain read - SELECT, WITH, VALUES, TABLE or SHOW, naming no write, lock, sequence or setting - in a transaction at READ COMMITTED that has run only plain reads: each such read sees the store as it is when it starts, so it runs on the new connection in a transaction opened again there, with every transaction() block it is inside opened again too, and the commit of a transaction that has only read - commit(), the end of a block, or an autocommit statement's own - is not refused when its connection is gone, since it has nothing to commit. A store that ends the session itself (an administrator's or a shutdown's error) counts as a lost connection. A commit whose answer was lost is never sent again, and a transaction that loses its connection after earlier statements fails as before, since what it did is gone; its rollback() is then not refused, since the store rolled the transaction back with the connection, and the next statement runs on a new connection. A connect that fails before the store answers - refused, reset, timed out - is tried again after a short pause, jittered and doubling, at most 3 times (CONNECT_ATTEMPTS) while connect_timeout is not spent, each try waiting at most half of it; a store that answers with a refusal of its own, such as a wrong password, is not tried again. A process whose store did not answer does not dial it again on every statement: after a transaction connection to an address found no store answering, a further one to that address - a connect, or the replacement of a lost connection - is refused at once as store_unreachable, carrying the last failure as its cause, for a pause drawn between half and all of 1 second (RECONNECT_FIRST_SECONDS), doubling with each failure in a row up to 30 seconds (RECONNECT_LONGEST_SECONDS); the first one after the pause dials again, and one the store answers ends the pause. Each such refusal, and the one of the connect that began the pause, carries the moment the pause ends, on the time.monotonic() clock, as dials_again_at, so a caller that asks again waits for that one schedule rather than keeping a second of its own; a refusal that leaves no pause carries None, and the next connect dials. The pause is kept per process, so the first connect of a process always dials, and a session connection is never paused.

Supabase's transaction pooler - a host under pooler.supabase.com on port 6543 - serves transaction connections, as the transaction address or as a transaction-only store's one address; a transaction connection to it makes the one round trip a transaction address of its own makes as it connects. A session connection to it is refused as transaction_pooler before anything is sent, because session connections cannot work through it. When it is the store's only address, the message says so - the store's only address is a transaction pooler, which keeps no session - and the hint names how to give the store a session address apart: its session pooler, the same host on port 5432, as the address, keeping port 6543 as the transaction port (capabilities store set ... --session-port 5432). When it is the session address beside a transaction address, the hint names its session pooler as the address and port 6543 as the transaction port. A session connection to a store whose one address is declared a transaction pooler is refused as transaction_pooler the same way, and the hint names how to give that store a session address apart.

Batch

from capabilities_contract.db import batch

counts, names = batch(conn, [
    "SELECT count(*) FROM automations_runs",
    ("SELECT name FROM automations_jobs WHERE host = %s", (host,)),
])

batch(conn, statements) sends independent statements - each a query, or a (query, params) pair, and each one statement - to the store as one pipeline on a connection from connect, and returns each one's rows in order: a list of rows for a statement that returns rows, an empty list for one that does not. The store answers them all in one round trip, directly or through a transaction-mode pooler. On a transaction connection the schema is bound for them. Where each would be a transaction of its own - in autocommit, or when every one is a plain read - they run as one transaction of their own and leave the connection idle, and a batch of plain reads that loses its connection runs again on a new one; otherwise they run inside the transaction that is open, or the one the first of them opens, which stays open for the caller's commit(). A statement that fails fails the batch with its error, and the statements after it are not run.

Migrate

result = migrate(conn, "automations", [
    Step("0001-runs", "CREATE TABLE automations_runs (id bigint PRIMARY KEY)"),
    ("0002-runs-host", "ALTER TABLE automations_runs ADD COLUMN host text"),
], major=1, minor=1)
for warning in result.warnings:
    print(warning)

migrate(conn, owner, steps, *, major, minor) applies each step that is not yet applied, in order, once. The owner is the tool that owns the tables, a lowercase identifier without underscores. The first call creates the schema and three platform tables in it: schema_ledger(owner, step, checksum, applied_at, library_version), schema_version(owner, major, minor, updated_at) and schema_channel(channel, scope, version), the change versions of Changes; a store whose schema was made before schema_channel existed gets it on the next migrate by a role that may create in the schema, once, under the schema lock, and a role that may not migrates such a store as before, leaving announce and Follower refused as not_migrated until one that may has run. Each step runs in its own transaction under a per-owner advisory lock together with its ledger row, so concurrent processes apply it exactly once. When every step is already applied and the store records the caller's version, it reads that without taking any lock, so a session holding one stops no tool whose tables are in place. Otherwise a lock is tried rather than queued for, so a process that dies while waiting leaves nothing in the queue: after 10 seconds held elsewhere (LOCK_WAIT_SECONDS) migrate refuses with store_busy, and a session that holds a lock and then issues no statement for 5 seconds (LOCK_IDLE_SECONDS) is ended by the server, which frees the lock. It returns a MigrateResult with applied, skipped, warnings, major, minor and core.

One owner, core, is the store's core: the tables any owner's steps may reference. Its tables are the plain nouns of CORE_TABLES (agents, nodes, connections, grants, settings, secrets and the rest), and it names everything its steps create <table> or <table>_* for a table on that list, or core_premig_* for a pre-image it keeps, and no other core_* name. Those names are reserved against every other owner, whatever it is called. For any other owner, migrate first migrates the core's own steps (CORE_STEPS, at CORE_VERSION), so the core is current before the owner's first step, and a refusal of the core's refuses the call before any of the owner's steps; result.core is the core's MigrateResult, or None while CORE_STEPS is empty, when nothing is run or written for the core. A step that references core tables declares the core version it needs, Step(id, sql, core=(major, minor)), and is refused with core_too_old until the store's schema_version records the core at that version or later; the owner's steps before it stay applied.

The core is the manager's tables, at core version 2.0: agents, nodes, agent_nodes, node_states, node_updates, node_logins, node_login_expectations, node_logs, node_sessions, node_session_expectations, connections, grants, policies, settings, settings_changes, settings_documents, identifiers, secrets, service_instances, service_leases, store_state and reference_versions. A column that holds an agent is agent_id, and a connection's owner is owner_agent_id. Up to 0.41.0 the same tables were owner capabilities at schema version 1.23, named capabilities_* with their agent in project_id (capabilities_contract.db._legacy keeps those steps, the library's and the two the manager added, as history). The core's first step, 0039-core, takes a store from wherever it stands: it runs each of those steps the store's ledger does not record - all of them on a fresh store - then renames every table, column, index, constraint, sequence, trigger and function in place, keeping every row and moving the pre-images capabilities_premig_* to core_premig_*, recreates each function whose body named what moved, and words the comments for the new names. The step raises the core to major 2 (Step(..., major=2)), so on a store already in use it runs only under the store upgrade (capabilities store upgrade), and STORE_MAJOR was 2 until core 3.0. On a store that held the old tables it leaves a refusing stub under each old name, with the old columns, whose every read fails naming the new table and capabilities self-update, then capabilities update, so a release that still reads capabilities_* is refused rather than reading no rows; a fresh store gets none. A fresh store and one moved this way end with the same catalog, the stubs apart. The ledger's rows of owner capabilities become the core's, and schema_version keeps a row for owner capabilities at major 2 beside the core's, so a release that still migrates owner capabilities (0.41.0 and older) refuses the store with schema_too_new instead of making its tables again. The channels the core's triggers raise keep their names, capabilities_vault and capabilities_node_update.

At core version 3.0 every connection has an opaque id. The core's second step, 0040-connection-ids (Step(..., major=3), so a store in use takes it only under the store upgrade, and STORE_MAJOR was 3 until core 4.0), gives each row of connections an id - twelve lowercase hex characters, minted by the store where a writer gives none, unique across the store, its primary key, and never changed (a trigger refuses an update of it) - and makes label what every connection is called: its former name where it had no label, not null, unique within its capability, and never any connection's id, so a word names a connection by its id, else by its label, and never two. Every core reference holds the id, with a foreign key to connections (id): grants.connection_id, node_sessions.connection_id and node_session_expectations.connection_id (the rows go with the connection; a session, or the owner's word on one, of a connection only a machine's files hold keeps that connection's key in file_connection instead, exactly one of the two set, and each table is unique on (agent_id, node, capability, coalesce(connection_id, file_connection))), nodes.coolify_connection_id and its copy in agent_nodes (set null when the connection goes, the node kept; a node made through a connection the machine lent, which no row holds, keeps that connection's address in coolify_address), settings.connection_id and identifiers.ref_connection_id. A top-level connection setting naming a connection of its own capability by its name or label holds its id; a node session or expectation naming no connection the store holds keeps the name it held in file_connection. node_sessions_put and node_expectation_set take a connection key and keep it as connection_id where the store holds that id for the capability, as file_connection otherwise. connections.name and every column that held a name are dropped; the pre-image core_premig_connection_names (id, capability, name, label) (CONNECTION_NAMES_TABLE) keeps each connection's former name and the label it had, written by that step alone, for other owners' steps converting their own columns (Step(..., core=(3, 0))) and for a capability finding state it kept under the name. A fresh store and one moved from core 2.0 end with the same catalog.

At core version 4.0 every agent, node and connection reference is a foreign key that says what its parent takes with it. The core's third step, 0041-keys (Step(..., major=4), so STORE_MAJOR is 4 and a store in use takes it only under the store upgrade), keys every core agent and node column: a row the agent or node owns goes with it (ON DELETE CASCADE), and settings_changes.node, a record of where a change was made, keeps its row and loses the node (ON DELETE SET NULL); the keys of agent_nodes and the node_* tables lose ON UPDATE CASCADE. agents.id and nodes.id refuse an update (triggers agents_id, nodes_id), as connections.id does, and agents, nodes and connections refuse a DELETE (triggers agents_delete, nodes_delete, connections_delete) unless the transaction-local setting store.deleting_agent, store.deleting_node or store.deleting_connection names the row, a comma-separated list of ids; a connection is also deleted with the agent that owns it. db.deleting(conn, parent, *ids) sets it for the open transaction, and clears it with no ids; it first runs the transaction's pending deferred triggers (SET CONSTRAINTS ALL IMMEDIATE), so a deferred notify trigger fires outside the setting for the statements before it and inside it for the cascade. The store tier's connection removal calls it around its delete. The step also makes the functions every owner's own keys step and guards call: store_state_keys(owner, keys) takes {table, column, parent, class} rows (class cascade, set null or restrict), makes each column's key in its class NOT VALID, settles every reference to an agent, node or connection the store does not hold by that class under the deleting settings - each changed row kept as it was in <owner>_premig_m9 (source, op, row, saved_at) - and validates every key, refusing the step where a restrict column or another parent names a missing row; store_state_cascade(table, op, old, new) answers whether a delete or an update of a row is the cascade of such a deliberate delete and nothing else, which a history guard admits (the core's settings_changes_append_only and reference_versions_guard do); and store_state_deleting(), under which a notify trigger stays quiet (the core's secrets_announce does). A step of another owner that calls them declares core=(4, 0). A Step also reads as its (step id, sql) pair.

At core version 4.1 every connection records when it was created. The core's fourth step, 0042-connection-created-at, is a minor step (no major), so it is applied wherever the core is at major 4, outside the store upgrade, and a release that knows core 4.0 reads a store at 4.1 as a newer minor with a warning. It adds connections.created_at timestamptz, which a trigger (connections_created_at) sets on every insert to the inserting transaction's time, over whatever the writer gave, and keeps on every update, so an edit, a rename or any other write leaves it as it was and nothing fills it in. A row the store held before the step stays null: no moment it could be given would be true. A connection imported from files has the moment its row was made. StoreRecords.connection_created(capability) answers each connection's moment by id as ISO text, read through the row's JSON so a store at core 4.0 answers null for every row, and a capability's connections report carries it on each connection as created_at, null for a connection kept in files or older than the step.

At core version 4.2 an agent can be archived, and nothing starts for it then. The core's fifth step, 0043-agent-archived, is a minor step (no major), applied wherever the core is at major 4, outside the store upgrade; a release that knows core 4.1 reads a store at 4.2 as a newer minor with a warning. It adds agents.archived_at timestamptz and agents.archived_by text (the actor as user@node, never the empty string), both null for an agent in use; the capabilities manager stamps them once it has checked, under a row lock on the agent, that nothing of it runs, and clears them on restore. A system agent never carries the mark (constraint agents_archived_system). The step makes the one function every owner's guard calls, agents_archived_refuse(agent text) RETURNS void: it takes FOR SHARE on the agent's row, which conflicts with the lock an archiving transaction holds from its check to its stamp (FOR UPDATE, or the FOR NO KEY UPDATE of its UPDATE), as a foreign key's FOR KEY SHARE does not, so a guarded write either waits for the archive and is then refused or holds it back and is then seen by its check; where the agent is archived it raises SQLSTATE 23R01 (capabilities_contract.db.AGENT_ARCHIVED_SQLSTATE; class 23, so psycopg raises an IntegrityError, never the OperationalError of a lost connection) with a message beginning agent_archived: (AGENT_ARCHIVED_CODE), the archive's moment and actor in its detail. A null agent and one the store does not hold pass, the latter left to the foreign key. The core guards its own tables through the trigger function agents_archived_row(): an insert or update of policies that leaves the row placing a service (service true; trigger policies_unarchived, which fires after policies_service_follows), every insert of service_leases (BEFORE INSERT, so a lease upsert that takes or renews is refused) and every insert of service_instances except one recording stopping (the supervisor writes its row through an upsert). Unplacing (service false), deleting a placement, releasing a lease, recording stopping and dropping an instance row stay allowed. An owner guards a table of its own in a minor step that declares core=(4, 2), with a trigger function of its own name, LANGUAGE plpgsql SET search_path FROM CURRENT, that runs PERFORM agents_archived_refuse(NEW.agent_id); RETURN NEW; - or passes the agent another row names, such as (SELECT agent_id FROM tasks_tasks WHERE id = NEW.task_id) - attached BEFORE INSERT ... FOR EACH ROW. agent_archived(conn, agent_id) in the store tier answers {archived_at, archived_by} or None, read through the row's JSON so a store at core 4.1 answers None, and a capability refuses a write of an archived agent with exit 4 agent_archived: a write is what the read-only switch refuses, so _gate refuses setting up, starting, running and reloading the project's service and joining a machine service, and every other writer is refused where it consults _read_only_gate - a verb in WRITE_VERBS through _write_gate, a record write, a capability's own write. Reading, help, doctor, discovery and stopping a service still work; migrate, machine administration and a machine service's own --machine call act for no agent. A project with no store, a store that does not answer or one at core 4.1 is not refused.

The tiers follow. A resolved connection's entry carries id and label; _select_connection matches a word against the id, then the label, then the address field, and reads a default pointer holding either. In the store a connection written under a word that names none is added labelled with it and its id minted (the adapter's set answers the id), and a grant, a default pointer, a removal and a rename name their connection by id or label. A new connection's env keys fill {ID} from the label it is added under, and a key is the connection's own when it is the one its label or its former name gives. _connection_state_dir(base, cid) answers base / cid, first moving state a capability kept under the connection's former name there, once and saying so on stderr, never over a path that exists; _connection_former_name(cid) answers that name. <capability> ids set <label> --connection <id|label> writes an identifier standing for a connection: its value the id, and ref_connection_id beside it in the store. A settings row written to the store carries connection_id where one of its path segments, else its value, is a connection's id. Files keep a connection under its key, which is its id and its label.

It refuses with a DbError, rolling the step back: an applied step whose SQL changed (checksum_mismatch); a step that creates a relation, index, sequence, type, function, collation, statistics object or schema not named <owner> or <owner>_* inside the configured schema, or named schema_ledger, schema_version or schema_channel, or named for the core by an owner other than core (naming_law); a step that declares a core version the store's core has not reached (core_too_old); a step that fails or ends its own transaction (step_failed). A step cannot use statements that refuse a transaction, such as CREATE INDEX CONCURRENTLY.

The version rule lets tools at different releases share one database. When the store records a newer major for the owner than the caller's major, migrate refuses with schema_too_new before applying anything, and the hint names the commands that catch the code up: capabilities self-update, then capabilities update. When it records the same major with a newer minor, it proceeds and adds a warning to result.warnings, keeping the stored version. When it records an older major than the caller's, migrate refuses as below. Otherwise it records the caller's version.

A schema major crosses only through the store upgrade, a procedure a person starts with capabilities store upgrade; a minor change applies by itself. A step that raises its owner to a new major says so, Step(id, sql, major=2). Outside the upgrade, migrate refuses with store_upgrade_needed before applying or recording anything for the owner when a pending step is marked major and the store is not empty, or when the store records a major for the owner older than the caller's major; the message names the owner, the major the store holds and the one the code wants, and the hint names capabilities store upgrade as the one way to cross and capabilities store upgrade --check as what says what it will do. The core's own pass is governed by the same rule. An empty store - no schema_version table, or no row in it - takes every step, major steps included, judged as it was when the call began, so a new install takes the newest. The upgrade procedure is recognised by CAPABILITIES_STORE_UPGRADE=1 in the environment (UPGRADE_ENV; upgrading() reads it); under it migrate applies major steps and records the higher major. Nothing in the library sets it.

The store's major is the major schema_version records for core. A store with rows there but no core row is at store major 1, which is also the major recorded for core in the rule above, and an empty store has none. STORE_MAJOR is the store major this library's own steps read: CORE_VERSION[0] once CORE_STEPS holds steps, else 1. store_major(conn) reads the store's in one statement, without a lock and changing nothing (in a savepoint when the caller holds a transaction), as a StoreMajor(major, since): major is None for an empty store, and since is when the latest major step of CORE_STEPS was applied, else None.

A major step that renames or drops a table may leave a refusing stub under the old name, so code that still reads it fails with a message saying what to run rather than with a missing table. moved_stub(old_name, columns, message) returns the SQL: a view under old_name with the old columns - each a name, typed text, or a (name, sql_type) pair - that holds no data, whose every read fails with an error carrying message, and that takes no write. The naming law admits such a view, under a name that held a relation in the schema before the step, only inside a step marked major.

Changes

from capabilities_contract.db import Follower, announce, connect

with connect(application_name="automations", project_root=root, transaction=True) as conn:
    conn.execute("UPDATE automations_jobs SET paused = true WHERE name = %s", (name,))
    announce(conn, "automations_jobs", project_id)
    conn.commit()

with Follower([("automations_jobs", project_id), "automations_runs"],
              application_name="automations", project_root=root) as follower:
    follower.run(lambda moved: reload(moved), stop=stopping)

A change other processes must see is announced as a version, and a process follows it by polling, so neither side needs a session for it: both work on the process's working connection, directly or through a transaction-mode pooler. Where the setting names the store's two addresses apart, a follower also listens on a session connection of its own, so a change wakes it at once rather than at its next poll. The store keeps one version per channel and scope in the platform table schema_channel; a pair that was never announced has version 0. A channel is a lowercase identifier of at most 63 characters, conventionally <owner>_<event>, and a scope is a non-empty string naming what the change is about, such as a project id.

announce(conn, channel, scope) raises that pair's version by one and returns the new version. A writer calls it inside its own transaction, after the change it announces, on a connection from connect: the raise is committed with the change and rolled back with it, so a follower never sees a raise whose change did not happen. The same statement notifies channel with scope as the payload (pg_notify; a scope longer than a notification carries is sent as an empty payload), which the store sends when the transaction commits and never when it rolls back, and which reaches a listener through a transaction-mode pooler as well. It is one statement, one round trip. The pair's row stays locked until the writer's transaction ends, so writers announcing the same pair take turns at it: announce last, just before the commit, so that each holds it for the shortest time.

Follower(follow, *, application_name, project_root=None, setting=None, seen=None) follows each item of follow, a (channel, scope) pair or a channel alone, which means every scope of that channel. read(conn=None) returns every followed version as the store holds it now, keyed by (channel, scope), in one query and one round trip on the process's working connection, whatever the number of channels. Given conn, a connection from connect the process already works on and keeps lent, it reads on that one instead and leaves it open, in whatever transaction it was in, so a process that holds its working connection follows without a second. poll(conn=None) takes conn the same way and returns only the versions that moved since the previous poll, with their new values; the first poll returns every version it reads, unless seen - the seen property of an earlier follower, the versions it last read - is given, when it returns only those that moved since then. A follower that was not polling for a while, or whose process was down and started again with its seen, therefore gets every pair that moved meanwhile on its first poll, once, with its latest version.

wait(seconds, stop=None) returns False after seconds, or as soon as the threading.Event stop is set, and returns True earlier, as soon as the store notifies one of the followed channels. It listens only where the setting names the store's two addresses apart (Setting.has_transaction_address): on a session connection of its own, opened at the first wait, which LISTENs on the followed channel names, whatever their scopes. With one address - a direct store or a transaction-only one - it waits out the time and opens no connection, so following is polling alone, as before. A listener that cannot be opened, or is lost, never fails a wait and never costs a change: the wait waits out its time, the next poll sees what moved, and the listener is tried again no more often than every 30 seconds. A notification sent before the listener opened is not seen; the next poll sees its change. close() closes the listener, and a follower used as a context manager closes it as the block ends; a later wait opens it again.

run(on_change, *, interval=1.0, stop=None) polls every interval seconds (FOLLOW_INTERVAL_SECONDS) until the threading.Event stop is set, and calls on_change with what moved: once for the first poll even when nothing moved, so the caller reads its state after the versions it starts from and misses nothing that changes later, and afterwards only when something moved. Between polls it waits with wait, so where the store's two addresses are named apart a notified channel is polled at once; it opens the listener before its first poll and closes it as it returns. A poll that finds the store unreachable is tried again at the next interval, and the first one that reaches it reports everything that moved meanwhile. A store whose schema has no schema_channel yet is refused as not_migrated.

Vault

capabilities_contract.vault keeps each agent's secrets in its store, sealed with the agent's own key. The key is AGENT_ENCRYPTION_KEY (KEY_ENV): 32 random bytes as URL-safe base64 without padding, 43 characters (generate_key, parse_key, which refuses anything else as bad_key without echoing it). key_source(project_root) finds it in the project's .env.local, then its .env, then the machine's $XDG_CONFIG_HOME/capabilities/shared.env (shared_env_path()), then the process environment, and agent_key parses what it found. The store never holds a key: fingerprint(key), a SHA-256 over it, is what agents.vault_key and each row's key_fingerprint keep.

seal(key, agent_id, name, value) seals a value with XChaCha20-Poly1305 (libsodium, through PyNaCl) under a fresh 24-byte nonce, the agent id and the name bound as associated data, so a sealed value moved to another agent or name does not open; unseal answers None for anything that does not open. Each secret is a row of secrets (agent_id, name, ciphertext, key_fingerprint, updated_at, updated_by), migrated with the contract's other tables; a trigger raises the channel capabilities_vault (VAULT_CHANNEL) for the agent in schema_channel on every change to a row or to the agent's vault_key. put, remove, rows, recorded_key, record_key and sealed_under_other read and write it on a connection the caller holds; a row whose fingerprint is not the key's is unreadable, kept until it is set again or removed.

reader(project_root, agent_id) is the process's Reader of that agent's vault, or None where no key is set. Reader.seed(rows, version) takes what round_trip(agent_id) reads - the sealed rows and the channel version, two statements to send beside others in one batch - and get(name) answers a value, opening only the names asked for and keeping what it opened in memory only; without a seed it reads them itself, and asked again after CHECK_SECONDS it reads the channel version and rereads the rows only when it moved. A store it cannot read raises VaultError("vault_unreadable", "the vault could not be read: ..."), which stands for RETRY_SECONDS. The connections tier asks it as the credential cascade's first tier, before the project's .env files, the machine's files and the process environment, which still answer every name it does not hold; the store tier seeds it from the round trip that reads a project's connections.

Every key also gives its agent a public sealing key: public_key(key), the X25519 public key of a scalar derived from the key apart from its fingerprint, which public_text writes as 43 characters of URL-safe base64 and parse_public reads back. publish(conn, agent_id, key) writes it to agents.vault_public_key where the row records that key's fingerprint, and the store clears it whenever vault_key changes without it, so no writer seals for a key the agent no longer holds; the key itself still never enters the store. seal_for(public, agent_id, name, value) seals a value for that public key by a writer that holds no key of the agent's - an ephemeral X25519 key agreed with it gives the XChaCha20-Poly1305 key, the agent id and the name bound as before, format byte 2 - and unseal opens either format with the agent's key, so a reader reads such a row as any other. recipients(conn, agent_ids) answers each registered agent's fingerprint and public key, and put_for keeps a value sealed for one under its fingerprint. share(project_root, writer, values, agents, *, replace, application_name, updated_by) seals values into the vault of each of agents in one transaction - the writer's own under its key, every other one's for its public key - leaving a name an agent already holds as it is where replace is false, and answers {sealed: {agent: {name: "created" | "replaced"}}, unchanged, unpublished, unregistered, hint}: an agent whose public key is not published is named, never skipped in silence. It is how a connection the store shares carries its secret in the vault of every agent granted it.

write(project_root, agent_id, values, *, application_name, updated_by) seals each value into the agent's vault under the key project_root resolves, in one transaction of its own, recording the key's fingerprint where the agent has none yet and publishing its public sealing key, and answers {name: "created" | "replaced"}; it writes nothing where it refuses, as key_missing, bad_key, agent_unregistered, key_mismatch or vault_unwritable. delete(project_root, agent_id, names, *, application_name) removes rows, which needs no key, and answers the names that were there. Both make the process's readers of that agent read again, so a value written is the value read back. They are how the connections tier's connection add and setup set keep a secret in the vault by default - writing a file only with --file, at the machine's scope where no grantee's vault takes it, or where no vault takes it, and saying why (vault_skipped) - and how connection remove and setup unset take it out again. connection add of a new connection also seals the values the machine holds for it, and connection seal [<id>] [--share] writes into each existing connection the values it resolves from the project's and the machine's files, sealed into the vault, without writing over what a vault holds; a value only the process environment holds is left there (not_sealed), and with --share a connection the store shares reaches another agent's vault only under the keys that are the connection's own, never under a name another connection or a setup field may read (not_shared). Every capability that carries the connections tier renders the cascade in its help as Where a secret resolves. render_text and parse_text write and read the vault as KEY=value text, a value a plain line would not carry back whole as a JSON string.

Status

from capabilities_contract.db import status

report = status(conn, "automations", steps, major=1, minor=1)
print(report.state, report.pending)

status(conn, owner, steps, *, major, minor) reports what migrate would do with the same arguments, changing nothing and taking no lock, so it answers while another session holds one. It returns a MigrateStatus with state, major and minor (the caller's), stored_major and stored_minor (the store's, or None), and the step ids under applied, pending and changed, plus warnings. state is current when every step is applied and the store records the caller's version or a newer minor (which adds a warning), pending when migrate has something to apply or record, and checksum_mismatch, schema_too_new or upgrade_needed (where migrate refuses store_upgrade_needed) when migrate would refuse. store_major(conn) reports the store's major, as Migrate says.

Bodies

from capabilities_contract.bodies import body_digest, check_body, materialise

path = materialise(script_body, state_dir / "bodies")
subprocess.run([str(path)], check=True)

capabilities_contract.bodies is the one way a stored executable script body - an automation's script_body, a stored tasks hook - is run. It imports nothing outside the standard library. body_digest(body) is the sha256 hex digest of the body's UTF-8 bytes. check_body(body) raises ValueError unless the body is a str starting with #!. materialise(body, directory) checks the body, makes the directory with mode 0700 (and its parents) when it is missing, and returns <directory>/<body_digest(body)>, an executable file holding the body: a regular file already there with the same content and mode 0700 is reused, and anything else at that path is replaced atomically by a file written beside it, chmodded 0700 and moved into place with os.replace. A process running the file never sees it partial, and processes materialising the same body at once each return the whole file.

Errors

Every failure is a DbError with slug (stable, for the caller to map to an exit code), message, hint (possibly None) and dials_again_at, the time.monotonic() moment from which a transaction connect to the same address dials again after a store_unreachable refusal that left it paused (see Connect), else None. Slugs: store_not_configured, store_not_postgres, store_setting_unreadable, store_setting_too_new, bad_store_setting, sslmode_too_weak, bad_schema_name, store_unreachable, transaction_pooler, session_state, driver_missing, bad_application_name, bad_owner, bad_version, bad_step, connection_busy, checksum_mismatch, naming_law, core_too_old, step_failed, schema_too_new, store_upgrade_needed, store_busy, bad_channel, bad_scope, bad_follow, bad_interval, not_migrated.

Development

uv venv && uv pip install -e ".[dev]"
uv run pytest

The suite starts a throwaway PostgreSQL cluster with TLS under a temporary directory (initdb and pg_ctl on PATH, or in $PG_BIN) on a random port. Set CAPABILITIES_CONTRACT_TEST_URL to a TLS-enabled server's admin URL to run it against that server instead, as CI does. The transaction-pooler tests run when CAPABILITIES_CONTRACT_TEST_PGBOUNCER names a pgbouncer executable: they put it in front of the test cluster in pool_mode=transaction with one server connection. The tests that compare the machine file reader with the manager's own run only when CAPABILITIES_STORE_TIER names a store tier module such as capabilities_contract/capability/store.py; otherwise they skip.

Metadata

Release files for capabilities-contract 0.50.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for capabilities-contract 0.50.0
File Size Uploaded Provenance Actions
capabilities_contract-0.50.0.tar.gz 246.4 kB With provenance Details for capabilities_contract-0.50.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for capabilities-contract 0.50.0
File Interpreter ABI Platform Actions
capabilities_contract-0.50.0-py3-none-any.whl Python 3 none any Details for capabilities_contract-0.50.0-py3-none-any.whl

Total release size: 489.7 kB

Release files / capabilities_contract-0.50.0.tar.gz

Download URL capabilities_contract-0.50.0.tar.gz
Size 246.4 kB
Tags Source
SHA-256 checksum
How to use checksums
cce3bddab1b91da9e681c6818996799dd616bfbf83fb87054967f5224635e2a4
BLAKE2b-256 checksum
How to use checksums
2170808e0975c6af220ca28bff871cb8b9fd1d715c4c72776f0f64f7aba32169
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Release files / capabilities_contract-0.50.0-py3-none-any.whl

Download URL capabilities_contract-0.50.0-py3-none-any.whl
Size 243.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3faf6d9175c2e1a6053603c560196c95f5cccf971d8b8a6a2fbfcf6fb54c119d
BLAKE2b-256 checksum
How to use checksums
a24665230e5dd9230cda68eea262c63639bfb6da8042d3b24e304745172270a0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Security for capabilities-contract 0.50.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for capabilities_contract-0.50.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.50.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page