switchroom 0.13.2 → 0.13.4

package/telegram-plugin/uat/scenarios/bridge-flap-resilience-dm.test.ts

@@ -0,0 +1,166 @@
+/**
+ * Bridge-flap resilience scenario — regression guard for #1613 / #1616.
+ *
+ * ## The bug this guards
+ *
+ * The handoff-briefing summarizer shells out to a headless `claude -p`
+ * once per turn (handoff Stop hook). Before #1616 it ran without
+ * `--strict-mcp-config`, so it auto-discovered the agent's project
+ * `.mcp.json` and started every MCP server in it — including
+ * `switchroom-telegram`. That spun up a *second* telegram bridge
+ * process which registered against the same gateway socket as the
+ * live agent's real bridge; the two collided under the gateway's
+ * register-race close, producing an A↔B "bridge reconnect race" flap
+ * every ~2s for the ~7-9s the `claude -p` lived. The handoff hook
+ * fires every turn, so did the flap. A turn whose completion landed
+ * inside a flap burst could have its `turn_end` signal eaten — the
+ * agent looked wedged for that turn.
+ *
+ * The fix (#1616): the summarizer passes `--strict-mcp-config`, so
+ * the headless `claude -p` loads zero MCP servers and never spawns a
+ * competing bridge. The structural guard against a new offending
+ * callsite is `tests/bridge-flap-regression-guard.test.ts`; this
+ * scenario is the behavioural backstop.
+ *
+ * ## What this scenario asserts (root-cause-agnostic by design)
+ *
+ * The checks are symptom-based, so they catch a flap reintroduced by
+ * ANY future change — not only a regression of #1616:
+ *
+ * 1. Send a handful of DMs in succession — each drives a turn (and a
+ *    handoff-hook fire). **Primary assertion:** every DM gets a reply
+ *    within budget. Directly catches both the flap (eats turn_end)
+ *    and the wedge (a zero-bridge gap strands the inbound).
+ * 2. **Forensic assertion:** inspect the agent's gateway-supervisor.log
+ *    over the test window and assert the `bridge disconnected` density
+ *    stays BELOW a flap threshold. One healthy persistent bridge
+ *    produces only a trickle of disconnects; a sustained reconnect
+ *    race produces dozens in tight ~2s bursts.
+ *
+ * ## Why the log inspection
+ *
+ * A flap is a server-side phenomenon that does not always surface as
+ * a missed reply (a burst can self-heal in ~20-30s). The `bridge
+ * disconnected` count is the transport-agnostic flap symptom. This
+ * scenario shells into the agent container via `docker exec` to read
+ * the gateway log; if docker is unavailable the log assertion is
+ * skipped with a warning and the responsiveness checks still run.
+ *
+ * ## Tolerances
+ *
+ * - `DISCONNECT_FLAP_THRESHOLD` is the max acceptable `bridge
+ *   disconnected` count over the window. Post-#1616 a healthy ~4-turn
+ *   run sits well under 16 (measured ~8-13, including anonymous
+ *   probe-connection churn); a sustained flap is 20-40+. 16 sits
+ *   comfortably in the gap.
+ */
+
+import { describe, expect, it } from "vitest";
+import { execSync } from "node:child_process";
+import { spinUp } from "../harness.js";
+import type { ObservedMessage } from "../driver.js";
+
+const AGENT = "test-harness";
+const CONTAINER = `switchroom-${AGENT}`;
+const GATEWAY_LOG = "/var/log/switchroom/gateway-supervisor.log";
+
+const DM_COUNT = 4;
+const PER_DM_TIMEOUT_MS = 30_000;
+const OVERALL_DEADLINE_MS = 180_000;
+
+// Post-#1616 a healthy ~4-turn run logs ~8-13 `bridge disconnected`
+// lines (one persistent bridge + anonymous probe-connection churn).
+// A sustained A↔B flap produces 20-40+ in tight ~2s bursts. 16 sits
+// in the gap.
+const DISCONNECT_FLAP_THRESHOLD = 16;
+
+/** Total line count of the agent's gateway-supervisor.log, or null if
+ *  the container/log is unreachable (CI without the container). */
+function gatewayLogLineCount(): number | null {
+  try {
+    const out = execSync(
+      `docker exec ${CONTAINER} sh -lc 'wc -l < ${GATEWAY_LOG}'`,
+      { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] },
+    );
+    return parseInt(out.trim(), 10);
+  } catch {
+    return null;
+  }
+}
+
+/** Count `bridge disconnected` lines after `sinceLine` in the log. */
+function disconnectCountSince(sinceLine: number): number | null {
+  try {
+    const out = execSync(
+      `docker exec ${CONTAINER} sh -lc ` +
+        `'awk "NR>${sinceLine}" ${GATEWAY_LOG} | grep -c "bridge disconnected" || true'`,
+      { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] },
+    );
+    return parseInt(out.trim(), 10);
+  } catch {
+    return null;
+  }
+}
+
+describe("uat: bridge-flap resilience — agent stays responsive, gateway does not flap", () => {
+  it(
+    "every DM gets a reply and the gateway does not flap across turns",
+    async () => {
+      const baselineLine = gatewayLogLineCount();
+      const sc = await spinUp({ agent: AGENT });
+      try {
+        const overallDeadline = Date.now() + OVERALL_DEADLINE_MS;
+
+        for (let i = 1; i <= DM_COUNT; i++) {
+          await sc.sendDM(`flap-resilience probe ${i}/${DM_COUNT}: reply with OK${i}`);
+
+          const remaining = Math.min(
+            PER_DM_TIMEOUT_MS,
+            overallDeadline - Date.now(),
+          );
+          expect(
+            remaining,
+            `overall deadline hit before DM ${i} — earlier turns were too slow`,
+          ).toBeGreaterThan(0);
+
+          const reply = await sc.expectMessage(
+            (m: ObservedMessage) => m.fromBot && !m.edited,
+            { from: "bot", timeout: remaining },
+          );
+          expect(
+            reply.text.length,
+            `DM ${i}/${DM_COUNT} produced an empty reply — a flap may have ` +
+              `eaten the turn_end signal`,
+          ).toBeGreaterThan(0);
+        }
+
+        // Responsiveness held for all DM_COUNT turns. Now check the
+        // server-side flap signal.
+        if (baselineLine == null) {
+          console.warn(
+            "[bridge-flap-resilience] docker exec unavailable — skipping " +
+              "the gateway-log flap assertion; responsiveness checks passed.",
+          );
+          return;
+        }
+
+        const disconnectCount = disconnectCountSince(baselineLine);
+        expect(
+          disconnectCount,
+          "could not read gateway log after the run — container went away",
+        ).not.toBeNull();
+        expect(
+          disconnectCount as number,
+          `gateway logged ${disconnectCount} "bridge disconnected" lines across ` +
+            `${DM_COUNT} turns — at/above the flap threshold ` +
+            `(${DISCONNECT_FLAP_THRESHOLD}). A parasitic bridge is racing the ` +
+            `live one — check for a headless 'claude -p' spawned without ` +
+            `--strict-mcp-config (#1613/#1616).`,
+        ).toBeLessThan(DISCONNECT_FLAP_THRESHOLD);
+      } finally {
+        await sc.tearDown();
+      }
+    },
+    OVERALL_DEADLINE_MS + 30_000,
+  );
+});

package/skills/buildkite-agent-infrastructure/SKILL.md

@@ -1,321 +0,0 @@
----
-name: buildkite-agent-infrastructure
-description: >
-  Buildkite cluster / organization / platform administration. Whenever
-  the user's message starts with the phrase "In Buildkite cluster
-  admin," — regardless of what follows — use this skill; that prefix
-  is a hard trigger that wins over `buildkite-api`, `buildkite-cli`,
-  and `buildkite-agent-runtime`. Provision and govern Buildkite CI
-  infrastructure: creating clusters, creating queues, scaling queues,
-  setting up hosted agents, right-sizing instance shapes, optimizing
-  CI costs, managing agent tokens, managing cluster secrets,
-  configuring SSO, setting up SAML, setting up audit logging, creating
-  pipeline templates, and standardizing pipelines across teams. Use
-  when the user says, verbatim: "set up SAML", "manage agent tokens",
-  "configure SSO", "set up audit logging", "Let's configure SSO.",
-  "I need to configure SSO.", "Could you scale queues for me?",
-  "Scale queues, please.", "scale queues", "Create a queue, please.",
-  "Create a cluster, please.", "set up hosted agents", "manage
-  cluster secrets", "right-size instance shapes", "optimize CI
-  costs", "standardize pipelines across teams", "create a pipeline
-  template", "configure agents", and typo'd variants like "manage
-  clusetr secrets", "configuree agents", "set up hostted agents".
-  Anything about buildkite-agent.cfg, agent tags, agent tokens, cluster
-  queues, hosted agent instance shapes, pipeline templates, audit
-  events, SSO/SAML providers, queue wait time, agent lifecycle hooks,
-  or Buildkite platform governance fires this skill — even when the
-  request mentions GraphQL or API calls (the rival `buildkite-api` is
-  for generic webhook/pagination/scripting, NOT for SSO/queue/cluster
-  admin which always belongs here).
-  Do NOT use when the user is calling `buildkite-agent <subcommand>` from
-  inside a running step (token use, artifact upload, annotate) — that's
-  `buildkite-agent-runtime`; or when the user just wants cluster CLI
-  shortcuts like `bk cluster ...` — that's `buildkite-cli`.
----
-
-# Buildkite Platform Engineering
-
-Provision and govern Buildkite CI infrastructure at scale: clusters, queues, hosted agent sizing, secrets, agent tokens, self-hosted configuration, lifecycle hooks, pipeline templates, audit logging, SSO/SAML, and cost optimization.
-
-## Quick Start
-
-Create a cluster with a hosted queue to get builds running immediately. **Start with hosted agents unless there is a specific reason to self-host** (GPU workloads, on-prem, custom hardware). Self-hosted queues require provisioning your own agents; builds hang "scheduled" until agents connect.
-
-All GraphQL mutations go to `https://graphql.buildkite.com/v1` with a Bearer token:
-
-```bash
-curl -sS -X POST "https://graphql.buildkite.com/v1" \
-  -H "Authorization: Bearer $BUILDKITE_API_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"query": "<GRAPHQL_QUERY_OR_MUTATION>", "variables": { ... }}'
-```
-
-**Step 1:** Get the organization ID: `query { organization(slug: "my-org") { id } }`
-
-**Step 2:** Create a cluster:
-
-```graphql
-mutation {
-  clusterCreate(input: {
-    organizationId: "org-id"
-    name: "Production"
-    description: "Production CI cluster"
-    emoji: ":rocket:"
-    color: "#14CC80"
-  }) { cluster { id uuid name } }
-}
-```
-
-**Step 3:** Create a hosted queue with a specific instance shape:
-
-```graphql
-mutation {
-  clusterQueueCreate(input: {
-    organizationId: "org-id"
-    clusterId: "cluster-id"
-    key: "linux-large"
-    description: "Linux 8 vCPU / 32 GB for heavy compilation"
-    hostedAgents: { instanceShape: LINUX_AMD64_8X32 }
-  }) { clusterQueue { id key } }
-}
-```
-
-**Step 4:** Create a pipeline in the cluster via GraphQL `pipelineCreate` or the REST API, then trigger a build.
-
-> For pipeline creation via REST and GraphQL, see the **buildkite-api** skill.
-
-> For pipeline YAML syntax including `agents:` routing and `secrets:` access, see the **buildkite-pipelines** skill.
-> For `bk cluster` CLI commands, see the **buildkite-cli** skill.
-
-## Clusters
-
-A cluster is the top-level container for queues, agent tokens, and secrets. Every organization starts with one default cluster; create additional clusters to isolate workloads (e.g., production vs. staging, team-specific).
-
-### Create a cluster
-
-```bash
-curl -s -X POST "https://api.buildkite.com/v2/organizations/my-org/clusters" \
-  -H "Authorization: Bearer $BUILDKITE_API_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "name": "Backend",
-    "description": "Backend team CI cluster",
-    "emoji": ":gear:",
-    "color": "#0B79CE"
-  }'
-```
-
-Fields: `name` (required), `description`, `emoji`, `color`, `default_queue_id` (optional).
-
-> For full REST and GraphQL API reference, see the **buildkite-api** skill.
-
-## Queues and Hosted Agents
-
-Queues route builds to agents. **Hosted queues** (Buildkite-managed compute) are the recommended starting point — builds run immediately. **Self-hosted queues** require connecting your own agents; builds remain "scheduled" until agents connect.
-
-Create queues with the `clusterQueueCreate` GraphQL mutation (shown in Quick Start above). To create a **self-hosted queue**, omit `hostedAgents`. Self-hosted agents connect by targeting the queue key in their configuration.
-
-### Instance shapes and sizing guide
-
-Full list: `references/instance-shapes.md`. Quick sizing:
-
-| Workload | Shape |
-|----------|-------|
-| Linting, unit tests | `LINUX_AMD64_2X4` |
-| Monorepos, multi-service | `LINUX_AMD64_4X16` |
-| Heavy compilation (C++, Rust) | `LINUX_AMD64_8X32` |
-| Docker builds, ML prep | `LINUX_AMD64_16X64` |
-| iOS / macOS | `MACOS_M4_6X28` or `MACOS_M4_12X56` |
-
-Start with the smallest shape that keeps builds under target time. Scale up if queue wait exceeds 2 minutes.
-
-### Queue design patterns
-
-- **Keep 1-2 static instances in the default queue** — avoids cold-start latency on pipeline uploads
-- **Retire oldest agents first during scale-down** — preserves warm caches
-- **Trial pattern** — test new shapes/architectures on a separate queue before migrating
-- **Tag builds with metadata** for cost attribution by queue or team
-
-Temporarily pause dispatch to a queue for maintenance or cost control using `clusterQueuePauseDispatch` / `clusterQueueResumeDispatch` GraphQL mutations. See `references/graphql-mutations.md` for examples.
-
-## Cluster Secrets
-
-Cluster secrets are encrypted, cluster-scoped values accessible from pipeline steps. They replace hardcoded credentials and environment-hook-based secret injection. Create, update, and rotate secrets via the REST API at `/v2/organizations/{org}/clusters/{cluster_id}/secrets`.
-
-### Secret key constraints
-
-| Rule | Detail |
-|------|--------|
-| Must start with | A letter (A-Z, a-z) |
-| Allowed characters | Letters, numbers, underscores only |
-| Prohibited prefixes | `buildkite`, `bk` (reserved) |
-| Max key length | 255 characters |
-| Max value size | 8 KB |
-
-### Access policies
-
-Restrict which pipelines and branches can access a secret by adding a `policy` object with `claims`. Available claim types: `pipeline_slug`, `build_branch`, `build_creator`, `build_source`, `build_creator_team`, `cluster_queue_key`. Claims support `*` wildcards. See [Buildkite Secrets docs](https://buildkite.com/docs/pipelines/security/secrets/buildkite-secrets.md) for policy examples.
-
-Value rotation uses a separate endpoint (`PUT .../secrets/{id}/value`) from description/policy updates (`PUT .../secrets/{id}`).
-
-> For `secrets:` YAML syntax, see the **buildkite-pipelines** skill. For `buildkite-agent secret get`, see the **buildkite-agent-runtime** skill.
-
-## Agent Tokens
-
-Agent tokens authenticate agents connecting to a cluster. Each token is scoped to a single cluster.
-
-### Create a token
-
-```bash
-curl -s -X POST "https://api.buildkite.com/v2/organizations/my-org/clusters/$CLUSTER_ID/tokens" \
-  -H "Authorization: Bearer $BUILDKITE_API_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "description": "Backend CI agents - production",
-    "allowed_ip_addresses": "10.0.0.0/8"
-  }'
-```
-
-| Field | Required | Description |
-|-------|----------|-------------|
-| `description` | Yes | Human-readable token description |
-| `allowed_ip_addresses` | No | Comma-separated CIDR ranges restricting agent connections |
-| `expires_at` | No | ISO 8601 expiry timestamp |
-
-The token value is only returned at creation time. Store it in a secrets manager immediately.
-
-## Self-Hosted Agents and Lifecycle Hooks
-
-Self-hosted agents run on your own infrastructure, configured via `buildkite-agent.cfg`. Prefer clustered agents for new deployments — they provide secret scoping, queue isolation, and better organizational control. For full configuration reference, `buildkite-agent.cfg` examples, and clustered vs. unclustered agent details, see `references/self-hosted-agents.md`.
-
-Agent lifecycle hooks execute at specific points during job execution: `environment` → `pre-checkout` → `checkout` → `post-checkout` → `pre-command` → `command` → `post-command` → `pre-exit` → `pre-artifact`. Agent-level hooks run first, then repository hooks, then plugin hooks. For hook details and examples, see `references/self-hosted-agents.md`.
-
-### Hosted agent caching behavior
-
-**Cache volumes on hosted agents are non-deterministic** — jobs may or may not get a warm cache. Treat cache volumes as performance accelerators, not guarantees. Cache volumes are **pipeline-scoped** (not shared across pipelines). For deterministic caching, use Docker images with pre-built dependencies instead. Git mirrors can be enabled via cache volumes to accelerate checkout; mount `.git/lfs/objects` in cache volumes and pre-install `git-lfs` in the agent image.
-
-### Hosted agent checkout performance
-
-Buildkite's default checkout **prioritizes completeness over speed** — it may be noticeably slower than GitHub Actions for the same repo. Optimize with the Sparse Checkout plugin (monorepos), Git mirrors (frequent builds), or the Git Shallow Clone plugin (repos where full history is unnecessary).
-
-### Hosted agent custom hooks
-
-Hosted agents support custom hooks via a custom agent image. Add hooks in a Dockerfile:
-
-```dockerfile
-FROM buildkite/agent:latest
-
-ENV BUILDKITE_ADDITIONAL_HOOKS_PATHS=/custom/hooks
-COPY ./hooks/*.sh /custom/hooks/
-RUN chmod +x /custom/hooks/*.sh
-```
-
-### Hosted agent pre-installed tools
-
-Linux hosted agents include: `bash`, `curl`, `wget`, `git`, `docker`, `python3`, `jq`.
-
-**`nvm` is NOT pre-installed.** Do not source `~/.nvm/nvm.sh` — it will fail silently or exit 127. Use `fnm` instead:
-
-```bash
-curl -fsSL https://fnm.vercel.app/install | bash -s -- --install-dir "$HOME/.fnm" --skip-shell
-export PATH="$HOME/.fnm:$PATH" && eval "$(fnm env --use-on-cd)"
-fnm install 20 && fnm use 20
-```
-
-`fnm` downloads from `nodejs.org` directly and works for all versions including EOL.
-
-**GitHub release asset downloads may be blocked.** `release-assets.githubusercontent.com` is unreachable from hosted agents. Pre-install tools distributed as GitHub release binaries (CodeQL, Scorecard, Trivy) in a custom agent image using `agentImageRef`.
-
-**Always verify queue creation** after a GraphQL mutation by listing queues via `GET /v2/organizations/{org}/clusters/{cluster_id}/queues`. Silent GraphQL errors can leave the cluster without a hosted queue — if the list is empty, retry via the REST API.
-
-## Plugin Security Controls
-
-Restrict which plugins agents can run:
-
-- **Agent-level allowlisting** — use `allowed-plugins` in `buildkite-agent.cfg` to restrict to approved plugins
-- **`no-plugins=true`** — disable all plugins on sensitive agents
-- **Cluster-based policies** — apply different plugin restrictions per cluster based on security requirements
-
-Audit plugin repositories proactively — Buildkite does not automatically alert to plugin vulnerabilities.
-
-## Pipeline Templates
-
-Pipeline templates (Enterprise-only) standardize pipeline YAML across the organization. See `references/pipeline-templates.md`.
-
-## Audit Logging
-
-Audit logging (Enterprise-only) tracks organization-level events for compliance. Query via GraphQL or stream to a SIEM via Amazon EventBridge. See `references/audit-logging.md`.
-
-## SSO/SAML
-
-Buildkite supports SAML 2.0 (Okta, Azure AD, Google Workspace, OneLogin). See `references/sso-saml.md` for setup flow.
-
-## Cost Optimization
-
-### Cost reduction patterns
-
-| Pattern | Savings | How |
-|---------|---------|-----|
-| Right-size instance shapes | 20-40% | Match shape to actual resource needs |
-| Use `disconnect-after-job` for self-hosted | 10-20% | Ephemeral agents don't idle between jobs |
-| Pause queues during off-hours | 10-30% | `clusterQueuePauseDispatch` on nights/weekends |
-| Skip unnecessary work with `if_changed` | 10-30% | Only run tests for changed code paths |
-| Use `priority` to run critical jobs first | Indirect | Reduces developer wait time for important builds |
-
-> For `if_changed` and pipeline optimization patterns, see the **buildkite-pipelines** skill.
-
-## Observability and Queue Monitoring
-
-| Tool | Purpose | How it works |
-|------|---------|-------------|
-| `buildkite-agent-metrics` | Fleet-level queue and job metrics | Polls the Buildkite API; emits to CloudWatch, Datadog, StatsD |
-| Agent health check service | Per-agent process health | Exposes Prometheus endpoint; scrape from each agent host |
-
-**Start with queue profiling** — wait time and checkout time are the biggest, cheapest wins. Target: queue wait time under 2 minutes.
-
-### Scaling decision flow
-
-```
-Queue wait > 2 min?
-├── Yes → Check agent count
-│   ├── Agents maxed out → Scale up (add agents or increase shape)
-│   ├── Agents idle → Check for job distribution issues (tags, queue routing)
-│   └── No agents → Check token, connectivity, agent health
-└── No → Queue is healthy
-```
-
-## Common Mistakes
-
-| Mistake | Fix |
-|---------|-----|
-| Secret key starting with `buildkite` or `bk` | Use a different prefix — these are reserved |
-| Secret key with dashes or dots | Only letters, numbers, underscores allowed: `MY_SECRET_KEY` not `my-secret-key` |
-| Not storing agent token at creation time | Token is only shown once — store in secrets manager immediately |
-| Org-level tokens for clustered agents | Use cluster-scoped tokens (`clusterAgentTokenCreate`) |
-| Over-provisioning instance shapes | Start small, monitor, scale up only when builds are slow |
-| No `disconnect-after-job` on autoscaled agents | Set `disconnect-after-job=true` for ephemeral pools |
-| One large queue for all workloads | Create specialized queues per workload type |
-| Cluster creation returns HTTP 500 | List existing clusters first; rename the Default cluster via PATCH as a workaround |
-| "Upgrade to Platform Pro" on hosted queue creation | Fall back: create self-hosted queue, install `buildkite-agent` locally with `--spawn 3` |
-| Expecting cache volumes to always be warm | Design builds to work without cache — volumes are non-deterministic |
-| One IAM role for all queues | Assign different IAM roles per queue; scope secrets by `cluster_queue_key` |
-| Scaling down newest agents first | Retire oldest agents first to preserve warm caches |
-| Jobs hang "scheduled" with agents connected | Check `default_queue_id` matches the agent's queue tag; update via PATCH |
-
-## Additional Resources
-
-- **`references/graphql-mutations.md`** — GraphQL mutations for clusters, queues, tokens, templates, SSO, audit
-- **`references/instance-shapes.md`** — All hosted agent instance shapes
-- **`references/self-hosted-agents.md`** — Agent config, clustered vs. unclustered, lifecycle hooks
-- **`references/pipeline-templates.md`** — Template mutations and strategy (Enterprise)
-- **`references/audit-logging.md`** — Audit queries, SIEM/EventBridge integration (Enterprise)
-- **`references/sso-saml.md`** — SSO/SAML provider setup
-
-## Further Reading
-
-- [Buildkite Docs for LLMs](https://buildkite.com/docs/llms.txt)
-- [Manage clusters](https://buildkite.com/docs/clusters/manage-clusters.md)
-- [Manage cluster queues](https://buildkite.com/docs/clusters/manage-queues.md)
-- [Manage cluster secrets](https://buildkite.com/docs/pipelines/security/secrets/buildkite-secrets.md)
-- [Agent configuration](https://buildkite.com/docs/agent/v3/configuration.md)
-- [Agent hooks](https://buildkite.com/docs/agent/v3/hooks.md)

package/skills/buildkite-agent-infrastructure/agents/openai.yaml

@@ -1,6 +0,0 @@
-interface:
-  display_name: "Buildkite Agent Infrastructure"
-  short_description: "Clusters, queues, hosted agents, secrets, SSO, and cost optimization"
-  icon_small: "./assets/buildkite-icon-small.png"
-  icon_large: "./assets/buildkite-icon-large.png"
-  brand_color: "#00D974"

package/skills/buildkite-agent-infrastructure/references/audit-logging.md

@@ -1,87 +0,0 @@
-# Audit Logging and SIEM Integration
-
-Audit logging (Enterprise-only) tracks organization-level events for compliance and security monitoring.
-
-## Query audit events
-
-```graphql
-query {
-  organization(slug: "my-org") {
-    auditEvents(
-      first: 50
-      occurredAtFrom: "2026-03-01T00:00:00Z"
-      occurredAtTo: "2026-03-26T23:59:59Z"
-    ) {
-      edges {
-        node {
-          type
-          occurredAt
-          actor { name type uuid }
-          subject { name type uuid }
-          data
-        }
-      }
-    }
-  }
-}
-```
-
-| Filter | Description |
-|--------|-------------|
-| `occurredAtFrom` / `occurredAtTo` | ISO 8601 time range |
-| `type` | Specific audit event type (e.g., `ORGANIZATION_UPDATED`) |
-| `subjectType` | Filter by subject type (e.g., `PIPELINE`, `AGENT_TOKEN`) |
-| `subjectUUID` | Filter by specific subject |
-| `order` | `RECENTLY_OCCURRED` (default) or `OLDEST_OCCURRED` |
-
-## High-severity events to monitor
-
-| Event type | Why it matters |
-|------------|---------------|
-| `agent_token.created` / `.deleted` | Agent authentication changes |
-| `member.invited` / `.removed` | Team membership changes |
-| `sso_provider.created` / `.updated` | SSO configuration changes |
-| `pipeline_schedule.created` | New automated triggers |
-| `cluster_secret.created` / `.deleted` | Secret management changes |
-| `organization.updated` | Org-level setting changes |
-
-## SIEM integration via Amazon EventBridge
-
-Stream audit events to a SIEM in real time using EventBridge:
-
-- **Source:** `aws.partner/buildkite.com/buildkite/<partner-event-source-id>`
-- **Detail type:** `"Audit Event Logged"`
-
-Event payload structure:
-
-```json
-{
-  "organization": {
-    "uuid": "org-uuid",
-    "graphql_id": "T3JnYW5pemF0aW9u...",
-    "slug": "my-org"
-  },
-  "event": {
-    "uuid": "event-uuid",
-    "occurred_at": "2026-03-26T14:30:00Z",
-    "type": "agent_token.created",
-    "data": { },
-    "subject_type": "AgentToken",
-    "subject_uuid": "token-uuid",
-    "subject_name": "Production agents",
-    "context": {
-      "request_id": "req-uuid",
-      "request_ip": "203.0.113.42",
-      "session_user_uuid": "user-uuid",
-      "request_user_agent": "Mozilla/5.0..."
-    }
-  },
-  "actor": {
-    "name": "Jane Engineer",
-    "type": "USER",
-    "uuid": "user-uuid"
-  }
-}
-```
-
-Route high-severity events to PagerDuty, Splunk, or Datadog via EventBridge rules matching on `detail.event.type`.