Connectors

​

Run a connector behind the gateway

reversi-connectors manifests github --format yaml > manifests/github.yaml

export GITHUB_TOKEN=...   # credentials come from the environment, never from flags
reversi-gateway --manifests ./manifests --data ./reversi-data \
  --upstream-cmd reversi-connectors --upstream-arg serve --upstream-arg github

reversi rollback <run> --compensator-cmd "reversi-connectors compensate --root ."

import { allConnectors, compensatorFor } from "@multimindlab/reversi-connectors";

const connectors = allConnectors({ fs: { root: "./work" }, github: { token: process.env.GITHUB_TOKEN! } });
// also: gitlab, teams, linear, jira, gcalendar, postgres, aws, gcp, azure, kubernetes
const registry = Registry.from(connectors.flatMap((c) => c.manifests));
// ... run.call({ tool, args, reason, execute: (a) => connectors[0].tools[tool](a, {}) })
await run.rollback({ compensate: compensatorFor(connectors) });

​

Filesystem (fs)

​

GitHub (github)

• Issues cannot be deleted through the API, so undoing create_issue closes it. The issue stays visible.
• github.delete_branch is declared idempotent because it must be callable as a compensation. That also means an agent that deletes a branch itself is not undone by rollback. Leave github:branch:delete out of the agent’s scope; compensations run outside the agent’s scope.
• Recreating a deleted branch needs its SHA, which the connector does not keep.

​

Slack (slack)

• A bot can only delete messages it posted, and the workspace may forbid deletion. Then rollback reports the step as failed.
• People may have replied or seen the message before it is deleted.
• If the bot had already reacted with the same emoji, add_reaction succeeds without changing anything, and rollback still removes that reaction.

​

Stripe (stripe)

• Refunds move money and cannot be recalled. Rollback lists them as unrecoverable and a human must approve each one.
• A payment intent that has already succeeded cannot be canceled; rollback fails that step. Create intents unconfirmed and confirm them outside the agent.
• A deleted Stripe customer cannot be restored, and its saved payment methods are gone. Rollback only deletes customers the run created.

​

GitLab (gitlab)

• The issue is closed, not deleted (as with GitHub): it stays visible in the project.
• gitlab.delete_branch is idempotent so it can run as a compensation; an agent that calls it itself is not undone. Keep gitlab:branch:delete out of the agent’s scope. Protected branches cannot be deleted without the Maintainer role.

​

Microsoft Teams (teams)

• Posting needs a signed-in user (delegated token). A service principal with only application permissions cannot use teams.post_message.
• softDelete marks the message deleted; members still see a “message deleted” placeholder in the channel, and the message remains in compliance exports. It is not a purge.
• People may have read or replied to the message before it is deleted.
• The Graph endpoints and permissions above are implemented from Microsoft’s documentation and tested against a fake; they have not been run against a live tenant.

​

Linear (linear)

• An archived issue still exists; it is hidden from boards and can be restored in the Linear UI. Linear sends notifications when an issue is created, and archiving does not recall them.
• GraphQL errors come back with HTTP 200 or 400; both are treated as failures. “Entity not found” counts as success for the two compensations, since the goal (the thing is gone) is met.

​

Jira (jira)

• Deleting an issue cannot be undone and the issue key number is not reused. jira.delete_issue is idempotent only so it can run as a compensation; keep jira:issues:delete out of the agent’s scope. Jira refuses to delete an issue that has subtasks.
• If the workflow has no transition back to the previous status, jira.restore_status fails and the rollback reports the step as failed. The issue history shows both transitions, and workflow post-functions (assignee changes, resolutions, notifications) run each time.

​

Google Calendar (gcalendar)

• Attendees are not managed by this connector, and nothing is emailed. If you need invitations, do that outside the agent.
• A deleted event goes to the calendar’s trash for a while but is not restored by rollback of create_event; it is deleted.
• Someone editing the event between update_event and rollback has those edits to the same fields overwritten by the restore.

​

Postgres (postgres)

• Table, schema and column names must match ^[A-Za-z_][A-Za-z0-9_]{0,62}$ and are always double-quoted.
• Every value is a bound parameter ($1, $2, …). No value is ever written into SQL text. The tests assert the exact SQL and parameters.

• insert_row runs INSERT INTO "t" ("a","b") VALUES ($1,$2) RETURNING "id" (the key column is id unless key_column says otherwise) and returns the key.
• update_row runs one transaction: BEGIN, SELECT of the old values of the columns being set with FOR UPDATE, UPDATE, COMMIT. It returns the old values; restore_row sets them back.
• query takes one SELECT or WITH statement with $n placeholders and values. It runs between BEGIN READ ONLY and ROLLBACK, so a write hidden in a WITH is refused by the server. Statements containing ; are rejected up front because a multi-statement string sent without parameters would run outside the guard. At most 1000 rows come back.
• Objects and arrays are bound as JSON text (for json and jsonb columns). Binary columns are not supported.
• A server error carries its SQLSTATE (Postgres error 42501: ...) and the transaction is rolled back. A lost connection after a write was sent is EffectUncertainError.

• READ ONLY stops writes to tables, not every side effect: nextval(), advisory locks and functions from extensions still run. Grant the role only what it needs.
• Rollback of insert_row deletes the row, but sequences stay advanced (gaps in serial ids), triggers and ON DELETE CASCADE rules run, and rows other transactions linked to it meanwhile are affected.
• restore_row writes the old values back, so updated_at-style triggers fire again and any change by others to those columns since is overwritten.
• postgres.delete_row deletes data for good. It is idempotent so it can run as a compensation; keep postgres:rows:delete out of the agent’s scope.

​

Amazon S3 (aws)

• Backup objects are kept (that is what makes the restore repeatable). Add a lifecycle rule that expires .reversi-backups/.
• Copies use CopyObject, which is limited to 5 GiB per object; larger objects fail.
• There is no precondition on S3 writes here, so a writer racing between the backup and the write can have its change restored over. The Cloud Storage and Blob Storage connectors guard this with generation and ETag preconditions.
• Bucket event notifications, replication and versioning react to every write, copy and delete the connector makes.
• .reversi-backups/ keys cannot be written or deleted through the tools and are hidden from list_objects.

​

Google Cloud Storage (gcp)

​

Azure Blob Storage (azure)

​

Kubernetes (kubernetes)

• scale_deployment reads the current replica count through the scale subresource, scales with a merge patch, and returns previous_replicas; rollback sets it back.
• create_configmap fails with 409 if the name exists, so rollback never deletes an object it did not create. Rollback deletes with a UID precondition, so a different ConfigMap that later took the same name is left alone (the 409 is treated as success).
• rollout_restart stamps the pod template annotation kubectl.kubernetes.io/restartedAt, like kubectl rollout restart. Pods are replaced, so it is declared irreversible and always needs approval. delete_pod likewise.

​

Certification

• fs, Retry: the local filesystem has no network transport that can fail transiently; errors are definite
• fs, Permission denial: access control is the operating system’s; the connector confines paths to its root instead (covered in filesystem.test.ts)
• fs, Timeout: local file operations have no network wait to time out
• fs, Redaction: the connector holds no credential
• All connectors, Dependency block: no tool manifest declares requires

​

Manifest drift

import { connectorSchemaHashes, detectManifestDrift } from "@multimindlab/reversi-connectors";

const baseline = connectorSchemaHashes(connector);          // store this
// later, after upgrading the package:
const drift = detectManifestDrift(connector.manifests, connector.inputSchemas, baseline);
if (drift.changed.length) throw new Error(`tool schemas changed: ${drift.changed.join(", ")}`);

​

Honest limits of the certification

• Everything is tested against fakes, not live services. Each fake is written from the vendor’s API documentation. If a real service behaves differently from its fake, the suite cannot tell. The first run against a real account is the real test; start with a throwaway project, bucket or database.
• An HTTP 5xx on a write is reported as an HTTP error naming the status, not as EffectUncertainError. The server answered, so the connector treats the call as failed. Only a lost connection or a timeout is uncertain. For a gateway timeout (502, 504) the write may in fact have been applied; check before retrying.
• Compensations that leave residue: GitHub and GitLab issues are closed, not deleted; Stripe payment intents are canceled, not removed; Linear issues are archived; Teams messages become soft-deleted placeholders; S3, Cloud Storage and Blob Storage keep .reversi-backups/ copies; the filesystem keeps its backup directory; Postgres sequences stay advanced; a Jira rollback leaves two transitions in the issue history. Where a fake backend does not return to its exact prior state after rollback, the fixture overrides the comparison in code (restored, or a fingerprint that ignores backups), so the difference is stated rather than hidden. Residue the fakes do not model (Jira history, Postgres sequences, notifications) is documented here but not tested.
• Irreversible tools are certified only for what they can be: Stripe refunds, kubernetes.rollout_restart and kubernetes.delete_pod are checked for forward behaviour, failure, retry, permission, timeout and redaction. They have no compensation, so rollback reports them unrecoverable.
• Concurrent writers. The restore tools put back what the connector saw. Someone else changing the same thing between the call and the rollback is overwritten, except where a precondition guards it (Cloud Storage generations, Blob Storage ETags, Kubernetes UIDs, Postgres row locks during update_row).