@a2a-exposed/control-core 0.0.0-stage → 0.7.33

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Telegraphic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,65 @@
-# Temporary Holding Version
+# a2a-exposed
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/a2a-exposed)](https://www.npmjs.com/package/a2a-exposed) [![CI](https://github.com/telegraphic-dev/a2a-exposed/actions/workflows/ci.yml/badge.svg)](https://github.com/telegraphic-dev/a2a-exposed/actions/workflows/ci.yml)
+
+a2a-exposed gives an AI agent a public [A2A](https://a2a-protocol.org) address. A Cloudflare Worker serves the agent card and the JSON-RPC endpoint. Inbound messages become tasks in an inbox. The Worker wakes the agent with a webhook, or the agent checks the inbox on a schedule. The agent reads the inbox and replies with `npx -y a2a-exposed@latest`. The same command sends messages to other A2A agents (1.0 or 0.3).
+
+## Who it's for
+
+Agents that can call out over HTTP and cannot run a public server: hosted assistants, coding agents, routines, and chat bots. Peers discover the card at `https://<host>/.well-known/agent-card.json`, send `SendMessage` with a per-peer token, and read the reply with `GetTask` (or a push notification, when the peer registered one).
+
+## Quick start
+
+Requires Node 22.18+. The skills are installed into the project the agent works in. They do not install the CLI. Every command runs through npx.
+
+1. **Add the skills to the project**
+
+   ```bash
+   npx -y skills add telegraphic-dev/a2a-exposed
+   ```
+
+2. **Deploy an inbox** in your Cloudflare account
+
+   ```bash
+   npx cf auth login --no-browser
+   npx -y a2a-exposed@latest init --hostname agent.example.com --agent-name "My Agent"
+   ```
+
+   Omit `--hostname` to serve on `*.workers.dev`. If you already have a wake URL, put `WAKE_WEBHOOK_URL` and `WAKE_WEBHOOK_KEY` in the environment before `init`. Never pass secrets on the command line.
+
+3. **Check the deployment, then let peers connect**
+
+   ```bash
+   npx -y a2a-exposed@latest status
+   npx -y a2a-exposed@latest pair set-password --web
+   ```
+
+   `status` is read-only and prints the next step. Open the one-time link and choose the approval password yourself. Another agent then runs `npx -y a2a-exposed@latest connect https://agent.example.com`. You approve that request on the `/device` page.
+
+After the skill is in the project, you can ask the agent to set this up. It follows the setup skill. Do not run setup from a Claude Code cloud session: that environment cannot install, tunnel, or reach your Worker. [Getting started](docs/getting-started.md) has Node, skills for other agents, and what to do if setup stops halfway.
+
+## Hosted
+
+[a2a.exposed](https://a2a.exposed) runs the inbox for you. It is free during beta. Install the skill in the project the same way, and use the same `npx -y a2a-exposed@latest` commands to read the inbox and reply. Self-hosting on your own Cloudflare account is the quick start above.
+
+## Docs
+
+| | |
+| --- | --- |
+| [Getting started](docs/getting-started.md) | Skills, Node, first deploy, pairing |
+| [Receiving messages](docs/receiving-messages.md) | Webhooks (main path) and polling (fallback) |
+| [Self-hosting](docs/self-hosting.md) | Cloudflare inbox, workers.dev, tunnel, public façade |
+| [CLI](docs/cli.md) | Commands, flags, config |
+| [MCP](docs/mcp.md) | Remote connector at `/mcp` |
+| [Feedback](docs/feedback.md) | Report a bug or an idea |
+| [Security](docs/security.md) | Tokens, pairing, wakes, façade |
+| [Troubleshooting](docs/troubleshooting.md) | FAQ and common failures |
+| [Upgrading](docs/upgrading.md) | Move an existing inbox forward |
+| [Protocol](docs/protocol.md) | A2A 1.0 and 0.3, OAuth, endpoints |
+| [Control plane](docs/control-plane.md) | Hosted accounts, sign-in, multi-tenant settings |
+
+Changes are listed in [CHANGELOG.md](CHANGELOG.md). Agent workflows live in [`skills/`](skills/a2a-exposed/SKILL.md).
+
+## License
+
+MIT, see [LICENSE](LICENSE). The license does not grant the hosted service's name or logo; see [TRADEMARKS.md](TRADEMARKS.md).

package/control/migrations/0001_auth.sql

@@ -0,0 +1,56 @@
+-- Better Auth 1.7.7 (SQLite) plus invite codes. Append-only: do not edit this file.
+CREATE TABLE IF NOT EXISTS "user" (
+  "id" text not null primary key,
+  "name" text not null,
+  "email" text not null unique,
+  "emailVerified" integer not null,
+  "image" text,
+  "createdAt" date not null,
+  "updatedAt" date not null
+);
+CREATE TABLE IF NOT EXISTS "session" (
+  "id" text not null primary key,
+  "expiresAt" date not null,
+  "token" text not null unique,
+  "createdAt" date not null,
+  "updatedAt" date not null,
+  "ipAddress" text,
+  "userAgent" text,
+  "userId" text not null references "user" ("id") on delete cascade
+);
+CREATE TABLE IF NOT EXISTS "account" (
+  "id" text not null primary key,
+  "accountId" text not null,
+  "providerId" text not null,
+  "userId" text not null references "user" ("id") on delete cascade,
+  "accessToken" text,
+  "refreshToken" text,
+  "idToken" text,
+  "accessTokenExpiresAt" date,
+  "refreshTokenExpiresAt" date,
+  "scope" text,
+  "password" text,
+  "createdAt" date not null,
+  "updatedAt" date not null
+);
+CREATE TABLE IF NOT EXISTS "verification" (
+  "id" text not null primary key,
+  "identifier" text not null,
+  "value" text not null,
+  "expiresAt" date not null,
+  "createdAt" date not null,
+  "updatedAt" date not null
+);
+CREATE INDEX IF NOT EXISTS "session_userId_idx" ON "session" ("userId");
+CREATE INDEX IF NOT EXISTS "account_userId_idx" ON "account" ("userId");
+CREATE INDEX IF NOT EXISTS "verification_identifier_idx" ON "verification" ("identifier");
+
+-- Invite codes for an invite-only deployment. Unused unless INVITES_REQUIRED=1.
+CREATE TABLE IF NOT EXISTS invites (
+  code TEXT PRIMARY KEY,
+  email TEXT,
+  created_at TEXT NOT NULL,
+  expires_at TEXT,
+  used_at TEXT,
+  used_email TEXT
+);

package/control/migrations/0002_tenants.sql

@@ -0,0 +1,25 @@
+-- Tenants and the config outbox. Append-only: do not edit this file.
+-- Control D1 is the only writer. The data plane receives a copy through pushConfig.
+CREATE TABLE IF NOT EXISTS tenants (
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL UNIQUE,
+  owner_account_id TEXT NOT NULL,
+  status TEXT NOT NULL,
+  region TEXT NOT NULL,
+  config_json TEXT NOT NULL,
+  limits_json TEXT NOT NULL,
+  approval_json TEXT NOT NULL,
+  owner_token_hash TEXT NOT NULL,
+  secrets_enc TEXT,
+  config_version INTEGER NOT NULL,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS tenants_owner_idx ON tenants (owner_account_id);
+
+CREATE TABLE IF NOT EXISTS config_outbox (
+  tenant_id TEXT NOT NULL,
+  version INTEGER NOT NULL,
+  created_at TEXT NOT NULL,
+  PRIMARY KEY (tenant_id, version)
+);

package/control/migrations/0003_oidc.sql

@@ -0,0 +1,30 @@
+-- OpenID Connect issuer keys and per-tenant clients. Append-only: do not edit this file.
+-- `jwks` matches Better Auth's JWT plugin (RS256). The private key is encrypted by that plugin.
+CREATE TABLE IF NOT EXISTS "jwks" (
+  "id" text not null primary key,
+  "publicKey" text not null,
+  "privateKey" text not null,
+  "createdAt" date not null,
+  "expiresAt" date,
+  "alg" text,
+  "crv" text
+);
+
+CREATE TABLE IF NOT EXISTS oauth_client (
+  id TEXT PRIMARY KEY,
+  secret_hash TEXT NOT NULL,
+  owner_account_id TEXT NOT NULL,
+  redirect_uris TEXT NOT NULL,
+  created_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS oauth_code (
+  code_hash TEXT PRIMARY KEY,
+  client_id TEXT NOT NULL,
+  user_id TEXT NOT NULL,
+  redirect_uri TEXT NOT NULL,
+  nonce TEXT NOT NULL,
+  challenge TEXT NOT NULL,
+  expires_at TEXT NOT NULL,
+  used_at TEXT
+);

package/control/migrations/0004_device.sql

@@ -0,0 +1,14 @@
+-- Device authorization codes for CLI sign-in (Better Auth device-authorization plugin).
+-- Append-only: do not edit this file.
+CREATE TABLE IF NOT EXISTS "deviceCode" (
+  "id" text not null primary key,
+  "deviceCode" text not null unique,
+  "userCode" text not null unique,
+  "userId" text,
+  "expiresAt" date not null,
+  "status" text not null,
+  "lastPolledAt" date,
+  "pollingInterval" integer,
+  "clientId" text,
+  "scope" text
+);

package/control/migrations/0005_agent_limit.sql

@@ -0,0 +1,11 @@
+-- Free plan: two agents per account. The check runs inside the insert, so two
+-- creates cannot both pass a count taken before either write.
+-- Keep the bound in step with AGENT_LIMIT in src/tenants/create.ts.
+-- Append-only: do not edit this file.
+CREATE TRIGGER IF NOT EXISTS tenants_agent_limit
+BEFORE INSERT ON tenants
+FOR EACH ROW
+WHEN (SELECT COUNT(*) FROM tenants WHERE owner_account_id = NEW.owner_account_id) >= 2
+BEGIN
+  SELECT RAISE(ABORT, 'agent_limit');
+END;

package/control/migrations/0006_agent_limit_account.sql

@@ -0,0 +1,28 @@
+-- Per-account agent limit. Null uses control_settings.free_agent_limit, which the
+-- app sets from FREE_AGENT_LIMIT. Both null means no limit. Replaces the constant
+-- check in 0005 so a higher plan can raise one account without another migration.
+-- Append-only: do not edit this file.
+ALTER TABLE "user" ADD COLUMN agent_limit INTEGER;
+
+CREATE TABLE IF NOT EXISTS control_settings (
+  id INTEGER PRIMARY KEY CHECK (id = 1),
+  free_agent_limit INTEGER
+);
+
+DROP TRIGGER IF EXISTS tenants_agent_limit;
+CREATE TRIGGER tenants_agent_limit
+BEFORE INSERT ON tenants
+FOR EACH ROW
+WHEN COALESCE(
+  (SELECT agent_limit FROM "user" WHERE id = NEW.owner_account_id),
+  (SELECT free_agent_limit FROM control_settings WHERE id = 1)
+) IS NOT NULL
+AND (
+  SELECT COUNT(*) FROM tenants WHERE owner_account_id = NEW.owner_account_id
+) >= COALESCE(
+  (SELECT agent_limit FROM "user" WHERE id = NEW.owner_account_id),
+  (SELECT free_agent_limit FROM control_settings WHERE id = 1)
+)
+BEGIN
+  SELECT RAISE(ABORT, 'agent_limit');
+END;

package/control/migrations/0007_outbox_lock.sql

@@ -0,0 +1,10 @@
+-- One lock for config delivery and agent delete. A flush that already loaded a row must not
+-- write the directory or the tenant object while delete is wiping them, and delete must not
+-- start that wipe while a delivery is still writing. Append-only: do not edit this file.
+CREATE TABLE IF NOT EXISTS control_locks (
+  name TEXT PRIMARY KEY,
+  holder TEXT NOT NULL,
+  expires_ms INTEGER NOT NULL
+);
+INSERT INTO control_locks (name, holder, expires_ms) VALUES ('outbox', '', 0)
+ON CONFLICT(name) DO NOTHING;

package/control/migrations/0008_account_provider.sql

@@ -0,0 +1,18 @@
+-- One external account identity belongs to one user. Two connect callbacks can
+-- both insert the same providerId and accountId. Those rows have to go before
+-- the unique index, or this migration fails and deploy stops. Keep the earliest
+-- row (then the lowest id). The user row stays. Append-only: do not edit this file.
+DELETE FROM "account"
+WHERE "id" NOT IN (
+  SELECT "id" FROM "account" AS "candidate"
+  WHERE NOT EXISTS (
+    SELECT 1 FROM "account" AS "earlier"
+    WHERE "earlier"."providerId" = "candidate"."providerId"
+      AND "earlier"."accountId" = "candidate"."accountId"
+      AND (
+        "earlier"."createdAt" < "candidate"."createdAt"
+        OR ("earlier"."createdAt" = "candidate"."createdAt" AND "earlier"."id" < "candidate"."id")
+      )
+  )
+);
+CREATE UNIQUE INDEX IF NOT EXISTS "account_provider_account_idx" ON "account" ("providerId", "accountId");

package/control/migrations/0009_feedback_rate.sql

@@ -0,0 +1,8 @@
+-- Per-address and per-owner-token counters for POST /api/feedback.
+-- Append-only: do not edit this file.
+CREATE TABLE IF NOT EXISTS feedback_rate (
+  bucket TEXT NOT NULL,
+  window_start INTEGER NOT NULL,
+  count INTEGER NOT NULL,
+  PRIMARY KEY (bucket, window_start)
+);

package/control/migrations/0010_cloudflare_grant.sql

@@ -0,0 +1,14 @@
+-- Setup consent for "Set me up on Cloudflare". refresh_enc is the sealed
+-- refresh token. The access token is not stored. Append-only: do not edit this file.
+CREATE TABLE IF NOT EXISTS cloudflare_grant (
+  "userId" TEXT NOT NULL PRIMARY KEY REFERENCES "user" ("id") ON DELETE CASCADE,
+  "accountId" TEXT NOT NULL,
+  choice TEXT NOT NULL,
+  host TEXT NOT NULL,
+  requested_scope TEXT NOT NULL,
+  granted_scope TEXT,
+  refresh_enc TEXT,
+  access_expires_at TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);

package/control/migrations/0011_cloudflare_inbox.sql

@@ -0,0 +1,16 @@
+-- An inbox this dashboard created in the user's Cloudflare account.
+-- The owner token is stored only as a SHA-256 hash. Append-only: do not edit this file.
+CREATE TABLE IF NOT EXISTS cloudflare_inbox (
+  "userId" TEXT NOT NULL PRIMARY KEY REFERENCES "user" ("id") ON DELETE CASCADE,
+  cf_account_id TEXT NOT NULL,
+  worker_name TEXT NOT NULL,
+  d1_name TEXT NOT NULL,
+  d1_id TEXT,
+  public_url TEXT,
+  owner_token_hash TEXT,
+  host TEXT NOT NULL,
+  hostname TEXT,
+  status TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);

package/control/migrations/0012_cloudflare_inbox_tag.sql

@@ -0,0 +1,4 @@
+-- Value this page stores before upload and writes into the Worker settings.
+-- A later try replaces a script only when that setting still matches.
+-- Append-only: do not edit this file.
+ALTER TABLE cloudflare_inbox ADD COLUMN script_tag TEXT;

package/control/migrations/0013_cloudflare_inbox_wizard.sql

@@ -0,0 +1,7 @@
+-- Wizard progress for an inbox this page creates.
+-- wizard_step is the last step that passed. step_error is a short sanitised note.
+-- workers_subdomain is the account workers.dev name once it is known.
+-- Append-only: do not edit this file.
+ALTER TABLE cloudflare_inbox ADD COLUMN wizard_step TEXT;
+ALTER TABLE cloudflare_inbox ADD COLUMN workers_subdomain TEXT;
+ALTER TABLE cloudflare_inbox ADD COLUMN step_error TEXT;

package/control/migrations/0014_cloudflare_inbox_agent.sql

@@ -0,0 +1,38 @@
+-- An account can have more than one Cloudflare agent. The old primary key was userId.
+-- Those rows keep that value as id. zone_id is the domain this setup attached, when it did.
+-- Append-only: do not edit this file.
+CREATE TABLE cloudflare_inbox_agent (
+  id TEXT NOT NULL PRIMARY KEY,
+  "userId" TEXT NOT NULL REFERENCES "user" ("id") ON DELETE CASCADE,
+  cf_account_id TEXT NOT NULL,
+  worker_name TEXT NOT NULL,
+  d1_name TEXT NOT NULL,
+  d1_id TEXT,
+  public_url TEXT,
+  owner_token_hash TEXT,
+  host TEXT NOT NULL,
+  hostname TEXT,
+  status TEXT NOT NULL,
+  script_tag TEXT,
+  wizard_step TEXT,
+  workers_subdomain TEXT,
+  step_error TEXT,
+  zone_id TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+
+INSERT INTO cloudflare_inbox_agent (
+  id, "userId", cf_account_id, worker_name, d1_name, d1_id, public_url, owner_token_hash,
+  host, hostname, status, script_tag, wizard_step, workers_subdomain, step_error, zone_id,
+  created_at, updated_at
+)
+SELECT
+  "userId", "userId", cf_account_id, worker_name, d1_name, d1_id, public_url, owner_token_hash,
+  host, hostname, status, script_tag, wizard_step, workers_subdomain, step_error, NULL,
+  created_at, updated_at
+FROM cloudflare_inbox;
+
+DROP TABLE cloudflare_inbox;
+ALTER TABLE cloudflare_inbox_agent RENAME TO cloudflare_inbox;
+CREATE INDEX IF NOT EXISTS cloudflare_inbox_user_idx ON cloudflare_inbox ("userId", created_at);