One plugin surface

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "acme",
  "version": "1.0.0",
  "description": "…",
  "license": "MIT",

  "extensions": {
    "sh.superset": {

      "interface": { "displayName": "Acme", "category": "Productivity", "icon": "acme" },

      // ── where the server is ──────────────────────────────────────
      // exactly one of `url` (remote) or `module` (bundled index.mjs).
      // Both speak MCP 2026-07-28. Nothing else differs.
      "server": {
        "url": "https://mcp.acme.com/mcp"
        // or: "module": "server/index.mjs"  → publish adds integrity + ref
      },

      // ── how it connects ──────────────────────────────────────────
      // a list, not a singleton: a plugin may need more than one
      // credential — per audience, or bot + user. See §05.
      "connection": {
        "scope": "org",                       // org | user
        "identity": { "tool": "get_self", "id": "$.org.id", "label": "$.org.name" }
        // no authorization_url / token_url / scopes / requires_env:
        // RFC 9728 discovery is the path. `legacyOauth` is the exception.
      },

      // ── what it emits ────────────────────────────────────────────
      "events": {
        "ingress": {
          "path": "acme",                     // POST /api/plugins/acme/events
          "verify": { "scheme": "hmac-sha256", "header": "X-Acme-Signature",
                      "prefix": "sha256=", "over": "{body}",
                      "secret": "connection.config.webhook_secret" },
          "eventId": "$.id",                  // dedup key
          "account": "$.org_id"               // → connections.external_account_id
          // normalization is always the server module's superset_normalize_event
        },
        "lifecycle": { "register": true, "renewEveryHours": 144 },  // optional; see §05

        "triggers": [
          { "event": "issue.created", "title": "Issue created",
            "filters": [
              { "name": "team", "label": "Team", "attribute": "teamId",
                "options": { "tool": "list_teams", "id": "$.id", "label": "$.name" } }
            ] }
        ]
      }
    }
  }
}

// plugins/<name>/src/index.ts — the only entrypoint a plugin needs
export async function handle(
  request: JsonRpcRequest,        // server/discover | tools/list | tools/call
  ctx: { headers: Headers },      // Authorization: Bearer …  — same as remote
): Promise<JsonRpcResponse>

plugins/acme/
├── plugin.json          // §02 — declaration only
├── src/index.ts         // tools + superset_* handlers
├── server/index.mjs     // built by `superset plugins build`, committed
└── skills/…/SKILL.md    // optional

superset plugins create acme      // scaffold
superset plugins publish acme     // bump, rebuild, rewrite generated manifests
git tag acme@1.0.0                // the tag is the release

{ "events": [ {
    "eventTypes": ["comment.created", "comment.mentioned"],  // one delivery, many names
    "externalEventId": "e02c…",
    "resourceKey": "notion:page_9f2b",        // runs debounce per subject
    "title": "Re: Q4 planning",
    "url": "https://…",
    "actor": { "id": "u_44", "label": "Priya", "isExternal": false },
    "attributes": { "teamId": "t_1", "labelIds": ["l_3"], "assigneeId": "u_9" },
    "payload": { "…" }                       // delivery + fetched context, for the prompt
} ] }

automation_triggers
  kind         -- now only: schedule | webhook | plugin
  plugin_name  text    -- non-null exactly when kind = 'plugin'
  event        text    -- the manifest trigger's `event`
  config       jsonb   -- { filters: { team: TriggerScope, … } }
  -- dispatcher indexes untouched: (next_run_at) where kind='schedule',
  -- (organization_id, kind). The kind↔config CHECK is replaced.

connections  -- integration_connections ∪ plugin_connections
  owner_kind   text   -- 'user' | 'org', from manifest connection.scope
  issuer, resource  -- the real OAuth key: two plugins on one server share a row
  external_account_id, external_account_label, scopes[], config,
  access_token, refresh_token, token_expires_at, disconnected_at
  unique (owner_kind, coalesce(organization_id, user_id), issuer, resource,
          external_account_id) where disconnected_at is null

automation_events   provider → plugin_name; integration_connection_id → connection_id;
                    + attributes jsonb  -- re-dispatch without re-normalizing
ingest.webhook_events  provider: integration_provider → text

"connection": [
  { "id": "bot",  "scope": "org",   "authorizeParam": "scope",
    "scopes": ["app_mentions:read", "chat:write", "links:read", "links:write", "…"],
    "token": "$.access_token",
    "identity": { "id": "$.team.id", "label": "$.team.name" } },

  { "id": "user", "scope": "user",  "authorizeParam": "user_scope",
    "scopes": ["channels:history", "search:read", "chat:write", "…"],
    "token": "$.authed_user.access_token",
    "identity": { "tool": "auth_test", "id": "$.user_id" } }
]
// one authorize: ?scope=…&user_scope=…   → one POST oauth.v2.access → two rows

{
  "name": "linear", "version": "2.0.0", "license": "MIT",
  "description": "Plan and build products: create, search and update Linear issues.",
  "extensions": { "sh.superset": {

    "interface": { "displayName": "Linear", "category": "Productivity", "icon": "linear" },

    "server": {
      "url": "https://mcp.linear.app/mcp",      // agent-facing tools: theirs
      "module": "server/index.mjs"            // superset_* tools: ours
    },

    "connection": {
      "scope": "org",
      "identity": { "tool": "get_viewer",
                     "id": "$.organization.id", "label": "$.organization.name" }
      // mcp.linear.app advertises PRM + CIMD, so nothing else is needed.
      // PLUGIN_LINEAR_CLIENT_ID / _SECRET stay deleted.
    },

    "events": {
      "ingress": {
        "path": "linear",
        "verify": { "scheme": "hmac-sha256", "header": "linear-signature",
                    "over": "{body}", "secret": "env.LINEAR_WEBHOOK_SECRET",
                    "replayWindowSeconds": 60 },
        "eventId": "$.webhookId",
        "account": "$.organizationId"
      },
      // app-level webhook configured once in Linear's dashboard — no lifecycle block

      "triggers": [
        { "event": "issue.status_changed", "title": "Issue moved to a status",
          "filters": [
            { "name": "teams",    "attribute": "teamId",
              "options": { "tool": "list_teams" } },
            { "name": "projects", "attribute": "projectId",
              "options": { "tool": "list_projects" } },
            { "name": "labels",   "attribute": "labelIds",
              "options": { "tool": "list_labels" } },
            { "name": "toStatus", "attribute": "toStateId",
              "options": { "tool": "list_workflow_states" } },
            { "name": "assignee", "attribute": "assigneeId",
              "options": { "tool": "list_users" } }
          ] },
        { "event": "comment.created", "title": "Comment on an issue",
          "filters": [ { "name": "teams", "attribute": "teamId",
                         "options": { "tool": "list_teams" } } ] }
      ]
    }
  } }
}

{
  "name": "gmail", "version": "2.0.0", "license": "MIT",
  "extensions": { "sh.superset": {

    "interface": { "displayName": "Gmail", "category": "Communication", "icon": "gmail" },

    "server": { "module": "server/index.mjs" },   // integrity + ref added by publish

    "connection": {
      "scope": "user",                            // a mailbox is one person's
      "identity": { "tool": "get_profile", "id": "$.emailAddress" },

      // accounts.google.com implements neither PRM nor CIMD — the
      // documented exception, and check:plugins warns if a server that
      // DOES advertise PRM still ships one of these.
      "legacyOauth": {
        "issuer": "https://accounts.google.com",
        "requiresEnv": ["PLUGIN_GOOGLE_CLIENT_ID", "PLUGIN_GOOGLE_CLIENT_SECRET"],
        "scopes": ["https://www.googleapis.com/auth/gmail.modify", "…"],
        "authorizationParams": { "access_type": "offline", "prompt": "consent" }
      }
    },

    "events": {
      "ingress": {
        "path": "gmail",
        // Pub/Sub push: a Google-signed JWT against a rotating JWKS, not an
        // HMAC over the body. Declarative verification cannot express it.
        "verify": { "scheme": "tool" },
        "eventId": "$.message.messageId",
        "account": "$.message.attributes.emailAddress"
      },
      // watches expire after 7 days; this is what replaces jobs/renew-watches
      "lifecycle": { "register": true, "renewEveryHours": 144 },

      "triggers": [
        { "event": "message.received", "title": "New mail arrives",
          "filters": [
            { "name": "labels", "attribute": "labelIds",
              "options": { "tool": "list_labels" } },
            { "name": "from",   "attribute": "fromAddress", "free": true }
          ] }
      ]
    }
  } }
}

// plugins/gmail/src/index.ts — one module, both callers
export async function handle(request, ctx) {
  const token = bearer(ctx.headers);              // same injection as remote

  switch (request.method) {
    case "server/discover":
      return ok({ capabilities: { tools: {},
        extensions: { "sh.superset/events": {} } } });   // how ingest knows

    case "tools/list":
      // superset_* tools are filtered out unless the caller is ingest
      return ok({ tools: agentTools(ctx), ttlMs: 3_600_000 });

    case "tools/call": {
      const { name, arguments: args } = request.params;
      switch (name) {
        case "superset_verify_delivery":
          return ok(await verifyPubSubJwt(args.headers, args.body));

        case "superset_normalize_event": {
          // the historyId means nothing without a history walk — the same
          // walk apps/api/.../google/lib/syncMailbox.ts does today
          const msgs = await historySince(token, args.body.historyId);
          return ok({ events: msgs.map(toNormalizedEvent) });
        }

        case "superset_register_delivery":
          return ok(await users.watch(token, { topicName: args.topic }));
        case "superset_renew_delivery":
          return ok(await users.watch(token, { topicName: args.topic }));

        default:
          return ok(await callTool(name, args, token));   // today's handlers, unchanged
      }
    }
  }
}