Add agent presence stage 1: schema, ingest route, Claude Code reporter

Stage 1 of the agent-collaborator prototype. Gets real agent state out of the
tools a team already runs and into the database, deterministically. No world,
no realtime, no MCP yet — this exists to answer whether seeing agent state
beats reading it before anything expensive gets built.

Hooks rather than an MCP tool first: an MCP tool only reports when the model
chooses to call it, which degrades during exactly the long tasks you most want
to watch. Hooks fire deterministically, and Claude Code's Notification event
fires when it is waiting on a human — which is the blocked state a terminal
buries. Both end up as adapters onto one ingest endpoint.

- agent_spaces / agents / agent_events, deliberately separate from `spaces`
  (different product, different buyer). RLS on with no policies, so the
  service role is the only writer.
- One write path at /api/agents/ingest, bearer token per space, rate limited.
- current_task and event detail are encrypted at rest through the existing
  encryptContentFields path — they carry repo, branch and command detail.
- scripts/mumbl-report.mjs runs inside Claude Code's hook path, so it never
  blocks and never fails the session: bounded fetch, all errors swallowed,
  always exits 0.
- scripts/agent-space-create.mjs provisions a space and prints the token once.

Events are ordered by a reporter-supplied occurred_at, not created_at. Hooks
fire faster than the round-trip: five concurrent hooks were inserted in an
order that put Stop first. Implausible client clocks fall back to server time.

Verified end to end against staging — hook payloads through the reporter to
encrypted rows and back out again. Test data removed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: lladawn

app/api/agents/ingest/route.js

@@ -0,0 +1,80 @@
+import { badRequest, ok, serverError } from "../../../../src/server/http";
+import { getSupabaseAdmin } from "../../../../src/server/supabase";
+import { enforceRateLimit } from "../../../../src/server/rateLimit";
+import { cleanString } from "../../../../src/server/validation";
+import {
+  AGENT_STATUSES,
+  isValidAgentStatus,
+  recordAgentState,
+  resolveSpaceByIngestToken,
+} from "../../../../src/server/agentPresence";
+
+/**
+ * The one write path for agent state.
+ *
+ * Claude Code hooks and the MCP server are both adapters onto this — keeping a
+ * single endpoint means a new runtime is a new adapter, not a new pipeline.
+ *
+ *   POST /api/agents/ingest
+ *   Authorization: Bearer <space ingest token>
+ *   { "agent": { "id", "name", "role", "source" },
+ *     "status": "working" | "blocked" | "done" | "idle",
+ *     "task": "...", "kind": "PreToolUse", "detail": "..." }
+ */
+export async function POST(request) {
+  try {
+    const token = bearerToken(request);
+    if (!token) return unauthorized("missing bearer token");
+
+    const supabase = getSupabaseAdmin();
+    const space = await resolveSpaceByIngestToken(supabase, token);
+    if (!space) return unauthorized("unknown ingest token");
+
+    const body = await request.json().catch(() => null);
+    if (!body) return badRequest("body must be json");
+
+    const status = cleanString(body.status, 20).toLowerCase();
+    if (!isValidAgentStatus(status)) {
+      return badRequest(`status must be one of ${AGENT_STATUSES.join(", ")}`);
+    }
+
+    const agent = body.agent || {};
+    if (!cleanString(agent.id, 200)) return badRequest("agent.id is required");
+
+    // keyed on the space, so one noisy agent cannot starve the others' quota
+    // any faster than the space as a whole
+    await enforceRateLimit({ supabase, action: "agent_ingest", sessionToken: token });
+
+    const row = await recordAgentState(supabase, {
+      spaceId: space.id,
+      agent: {
+        externalId: agent.id,
+        name: agent.name,
+        role: agent.role,
+        source: agent.source,
+      },
+      status,
+      task: body.task,
+      kind: body.kind,
+      detail: body.detail,
+      occurredAt: body.occurredAt,
+    });
+
+    return ok({ ok: true, space: space.slug, agent: { id: row.id, name: row.name, status: row.status } });
+  } catch (error) {
+    if (error?.status === 429) {
+      return Response.json({ error: "too many updates" }, { status: 429 });
+    }
+    return serverError(error);
+  }
+}
+
+function bearerToken(request) {
+  const header = request.headers.get("authorization") || "";
+  const match = header.match(/^Bearer\s+(.+)$/i);
+  return match ? match[1].trim() : "";
+}
+
+function unauthorized(message) {
+  return Response.json({ error: message }, { status: 401 });
+}

docs/agent-presence-stage-1.md

@@ -0,0 +1,136 @@
+# Agent Presence — Stage 1
+
+Stage 1 of the agent-collaborator prototype: get **real** agent state out of the
+tools a team already runs and into a database, deterministically.
+
+No world, no realtime, no MCP yet. This stage exists to answer one question
+before anything expensive gets built:
+
+> Does seeing agent state beat reading it?
+
+If the answer is no, nothing downstream is worth building.
+
+---
+
+## Why hooks and not MCP first
+
+Mumbl will ship an MCP server — it is the breadth play, one protocol instead of
+one integration per framework, and it is the line in the pitch.
+
+But an MCP tool only reports **when the model chooses to call it.** That is
+unreliable, costs tokens, and degrades during long tasks — exactly when you most
+want to see what is happening.
+
+Claude Code hooks fire **deterministically**, outside the model's control. In
+particular `Notification` fires when Claude is waiting on a human, which is the
+`blocked` state — the one a terminal buries and a room can surface.
+
+So both are adapters onto one ingest endpoint. Hooks make it real today; MCP
+makes it broad later.
+
+---
+
+## Pieces
+
+| Piece | Path |
+|---|---|
+| Schema | `supabase/migrations/0004_agent_presence.sql`, `0005_agent_event_occurred_at.sql` |
+| Write path | `app/api/agents/ingest/route.js` |
+| Server helpers | `src/server/agentPresence.js` |
+| Reporter | `scripts/mumbl-report.mjs` |
+| Provisioning | `scripts/agent-space-create.mjs` |
+
+`agents` is *where a collaborator is now* (what the world will render).
+`agent_events` is *what it has been doing* (what a side panel will read). Both
+are written together, so the world can never show a state with no trail.
+
+---
+
+## Setup
+
+**1. Apply migrations**
+
+```bash
+npm run db:push
+```
+
+**2. Create a space and keep the token**
+
+```bash
+node scripts/agent-space-create.mjs my-team "My Team"
+```
+
+The ingest token is printed once. Only its HMAC is stored, so it cannot be
+recovered — create a new space if it is lost.
+
+**3. Point Claude Code at it**
+
+In `~/.claude/settings.json` (or a project `.claude/settings.json`):
+
+```json
+{
+  "env": {
+    "MUMBL_INGEST_TOKEN": "<token from step 2>"
+  },
+  "hooks": {
+    "SessionStart":  [{ "hooks": [{ "type": "command", "command": "node /abs/path/scripts/mumbl-report.mjs" }] }],
+    "PreToolUse":    [{ "matcher": "*", "hooks": [{ "type": "command", "command": "node /abs/path/scripts/mumbl-report.mjs" }] }],
+    "Notification":  [{ "hooks": [{ "type": "command", "command": "node /abs/path/scripts/mumbl-report.mjs" }] }],
+    "Stop":          [{ "hooks": [{ "type": "command", "command": "node /abs/path/scripts/mumbl-report.mjs" }] }]
+  }
+}
+```
+
+Set `MUMBL_INGEST_URL` to `http://127.0.0.1:3000/api/agents/ingest` to test
+against a local dev server.
+
+---
+
+## The contract
+
+```
+POST /api/agents/ingest
+Authorization: Bearer <space ingest token>
+
+{
+  "agent":  { "id": "claude-code:<session>", "name": "...", "role": "...", "source": "claude-code" },
+  "status": "idle" | "working" | "blocked" | "done",
+  "task":   "Refactoring the auth module",
+  "kind":   "PreToolUse",
+  "detail": "Edit · auth/session.ts",
+  "occurredAt": "2026-08-07T12:00:00.000Z"
+}
+```
+
+Any new runtime is a new adapter onto this endpoint, not a new pipeline.
+
+### Event ordering
+
+`occurredAt` is stamped by the reporter, not the server. Hooks fire faster than
+the round-trip: in testing, five concurrent hooks were inserted in an order that
+put `Stop` **first**. Order the activity log by `occurred_at`, never
+`created_at`. Implausible client clocks (>5 min future, >24 h past) fall back to
+server time.
+
+### Privacy
+
+`current_task` and event `detail` carry repo, branch and command detail, so both
+are encrypted at rest via the existing `encryptContentFields` path — the same
+one posts use. Rows are readable only through the service role; RLS is on with
+no policies.
+
+---
+
+## Known limits
+
+- **Agent status is last-write-wins by arrival, not by `occurred_at`.** Real
+  hooks fire sequentially per session so this is fine in practice, but two
+  concurrent reports for one agent can settle on the older status. Fix with a
+  conditional update when it starts mattering.
+- **No read path yet.** Nothing renders this. That is the next piece.
+- **Rate limit is per space** (`agent_ingest`, 300/min), so one noisy agent
+  consumes the space's budget.
+- **Realtime is not wired.** Stage 2 needs RLS read policies before a browser
+  can subscribe — do that deliberately rather than loosening stage 1's.
+- This breaks the posture in `free-tier-compromises.md` on purpose; see that
+  doc's "future improvements" note.

scripts/agent-space-create.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+/**
+ * Create an agent space and print its ingest token once.
+ *
+ * Admin operation, not a product surface — it writes with the service role, so
+ * it stays a local script rather than an API route until there is a real
+ * onboarding flow.
+ *
+ *   node scripts/agent-space-create.mjs <slug> [name] [envFile]
+ */
+
+import { readFileSync } from "node:fs";
+import { createHmac, randomBytes } from "node:crypto";
+
+const [, , slugArg, nameArg, envFileArg] = process.argv;
+
+if (!slugArg) {
+  console.error("Usage: node scripts/agent-space-create.mjs <slug> [name] [envFile]");
+  process.exit(1);
+}
+
+const envFile = envFileArg || ".env.local";
+const env = readEnv(envFile);
+
+const supabaseUrl = env.NEXT_PUBLIC_SUPABASE_URL;
+const serviceKey = env.SUPABASE_SERVICE_ROLE_KEY;
+const hashSecret = env.MUMBL_TOKEN_HASH_SECRET;
+
+for (const [key, value] of Object.entries({ NEXT_PUBLIC_SUPABASE_URL: supabaseUrl, SUPABASE_SERVICE_ROLE_KEY: serviceKey, MUMBL_TOKEN_HASH_SECRET: hashSecret })) {
+  if (!value) {
+    console.error(`Missing ${key} in ${envFile}`);
+    process.exit(1);
+  }
+}
+
+const slug = slugArg.toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-|-$/g, "");
+const token = randomBytes(32).toString("base64url");
+
+// Must match hashToken() in src/server/hash.js — that file is the source of
+// truth; it is duplicated here because it imports extensionless paths that
+// plain Node ESM cannot resolve.
+const tokenHash = createHmac("sha256", hashSecret).update(token).digest("hex");
+
+const response = await fetch(`${supabaseUrl}/rest/v1/agent_spaces`, {
+  method: "POST",
+  headers: {
+    apikey: serviceKey,
+    authorization: `Bearer ${serviceKey}`,
+    "content-type": "application/json",
+    prefer: "return=representation",
+  },
+  body: JSON.stringify({ slug, name: nameArg || slug, ingest_token_hash: tokenHash }),
+});
+
+const payload = await response.json();
+
+if (!response.ok) {
+  console.error(`Failed (${response.status}):`, payload?.message || payload);
+  process.exit(1);
+}
+
+const created = Array.isArray(payload) ? payload[0] : payload;
+
+console.log("");
+console.log(`  space   ${created.slug}  (${created.id})`);
+console.log(`  env     ${envFile}`);
+console.log("");
+console.log("  Ingest token — shown once, store it now:");
+console.log("");
+console.log(`  export MUMBL_INGEST_TOKEN=${token}`);
+console.log("");
+
+function readEnv(path) {
+  let raw = "";
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch {
+    console.error(`Cannot read ${path}`);
+    process.exit(1);
+  }
+
+  const out = {};
+  for (const line of raw.split("\n")) {
+    const match = line.match(/^([A-Z0-9_]+)=(.*)$/);
+    if (match) out[match[1]] = match[2].trim().replace(/^["']|["']$/g, "");
+  }
+  return out;
+}