@openparachute/agent 0.1.0

package/src/web/auth.ts

@@ -0,0 +1,214 @@
+/**
+ * Hub-issued JWT validation. Paraclaw's web server as resource server: trusts
+ * tokens that the hub signs against keys we fetch from `/.well-known/jwks.json`.
+ *
+ * Shape mirrors `parachute-vault/src/hub-jwt.ts` deliberately — same trust
+ * model, same load-bearing checks (`iss` strict; `aud` parsed not enforced).
+ * The shared scope-guard library proposed in cli#59 will eventually absorb
+ * both.
+ *
+ * Hub origin resolution: `PARACHUTE_AGENT_HUB_ORIGIN` (test override; legacy
+ * `PARACLAW_HUB_ORIGIN` accepted through 0.1.x with a one-shot warning) →
+ * `PARACHUTE_HUB_ORIGIN` (the hub lifecycle stamps this on every spawned
+ * service — see `parachute-hub/src/commands/lifecycle.ts`) → loopback
+ * `http://127.0.0.1:1939`. We intentionally do NOT read services.json —
+ * the hub is the dispatcher, not a registered service in that file
+ * (matching vault's choice). Tailnet-served parachute-agent must see the
+ * hub's tailnet origin or `iss` mismatch rejects every JWT.
+ *
+ * Scope vocabulary: `agent:read` / `agent:write` / `agent:admin` with
+ * `admin ⊇ write ⊇ read` inheritance per
+ * `parachute-patterns/patterns/oauth-scopes.md`. `vault:admin` is the
+ * operator-token catch-all and satisfies any agent scope check (operator
+ * token is what local CLI/scripts present; it carries `vault:admin` per
+ * `parachute-hub/src/operator-token.ts`).
+ *
+ * Pre-0.1.0 compat: hub-issued tokens may still carry `claw:*` scopes for
+ * one cycle. `hasScope` normalizes legacy `claw:*` to `agent:*` so callers
+ * with grandfathered grants keep working. Drop the compat normalization in
+ * 0.2.0 (tracked as a follow-up at PR open time).
+ */
+import { createRemoteJWKSet, jwtVerify, type JWTPayload } from 'jose';
+
+import { readEnvWithLegacy } from '../env.js';
+
+const DEFAULT_HUB_LOOPBACK = 'http://127.0.0.1:1939';
+
+export const SCOPE_AGENT_READ = 'agent:read' as const;
+export const SCOPE_AGENT_WRITE = 'agent:write' as const;
+export const SCOPE_AGENT_ADMIN = 'agent:admin' as const;
+export const SCOPE_VAULT_ADMIN = 'vault:admin' as const;
+
+export type AgentScope = typeof SCOPE_AGENT_READ | typeof SCOPE_AGENT_WRITE | typeof SCOPE_AGENT_ADMIN;
+
+/**
+ * Pre-0.1.0 compat: map legacy `claw:*` scope grants to their `agent:*`
+ * equivalents so hub-issued tokens minted before the rename keep working.
+ * Drop in 0.2.0.
+ */
+const LEGACY_SCOPE_MAP: Record<string, string> = {
+  'claw:read': SCOPE_AGENT_READ,
+  'claw:write': SCOPE_AGENT_WRITE,
+  'claw:admin': SCOPE_AGENT_ADMIN,
+};
+function normalizeGranted(s: string): string {
+  return LEGACY_SCOPE_MAP[s] ?? s;
+}
+
+export function getHubOrigin(): string {
+  const override = readEnvWithLegacy('PARACHUTE_AGENT_HUB_ORIGIN', 'PARACLAW_HUB_ORIGIN')?.replace(/\/$/, '');
+  if (override && override.length > 0) return override;
+  const fromHub = process.env.PARACHUTE_HUB_ORIGIN?.replace(/\/$/, '');
+  if (fromHub && fromHub.length > 0) return fromHub;
+  return DEFAULT_HUB_LOOPBACK;
+}
+
+export interface HubJwtClaims {
+  sub: string;
+  scopes: string[];
+  aud: string | undefined;
+  jti: string | undefined;
+  clientId: string | undefined;
+}
+
+export class HubJwtError extends Error {
+  override name = 'HubJwtError';
+}
+
+type JwksGetter = ReturnType<typeof createRemoteJWKSet>;
+let cachedGetter: JwksGetter | null = null;
+let cachedOrigin: string | null = null;
+
+function getJwksGetter(origin: string): JwksGetter {
+  if (cachedGetter && cachedOrigin === origin) return cachedGetter;
+  cachedGetter = createRemoteJWKSet(new URL(`${origin}/.well-known/jwks.json`), {
+    cacheMaxAge: 5 * 60 * 1000,
+    cooldownDuration: 30 * 1000,
+  });
+  cachedOrigin = origin;
+  return cachedGetter;
+}
+
+export function resetJwksCache(): void {
+  cachedGetter = null;
+  cachedOrigin = null;
+}
+
+/**
+ * Verify a presented JWT against the hub's JWKS. Throws `HubJwtError` on any
+ * failure. The `iss` claim MUST equal the configured hub origin — load-bearing
+ * trust check; without it, anyone could mint a token against any RSA key and
+ * pass verification.
+ */
+export async function validateHubJwt(token: string): Promise<HubJwtClaims> {
+  const origin = getHubOrigin();
+  const getter = getJwksGetter(origin);
+
+  let payload: JWTPayload;
+  try {
+    const verified = await jwtVerify(token, getter, { issuer: origin });
+    payload = verified.payload;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new HubJwtError(`hub JWT verification failed: ${msg}`);
+  }
+
+  if (typeof payload.sub !== 'string' || payload.sub.length === 0) {
+    throw new HubJwtError('hub JWT missing required `sub` claim');
+  }
+
+  const scopeRaw = (payload as { scope?: unknown }).scope;
+  const scopes = typeof scopeRaw === 'string' ? parseScopes(scopeRaw) : [];
+  const aud = typeof payload.aud === 'string' ? payload.aud : undefined;
+  const jti = typeof payload.jti === 'string' ? payload.jti : undefined;
+  const clientIdRaw = (payload as { client_id?: unknown }).client_id;
+  const clientId = typeof clientIdRaw === 'string' ? clientIdRaw : undefined;
+
+  return { sub: payload.sub, scopes, aud, jti, clientId };
+}
+
+export function parseScopes(raw: string | null | undefined): string[] {
+  if (!raw) return [];
+  return raw
+    .split(/\s+/)
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+/**
+ * Does `granted` satisfy `required`?
+ *
+ * Inheritance rules:
+ *   - `agent:admin` ⊇ `agent:write` ⊇ `agent:read`
+ *   - `vault:admin` (operator-token catch-all) satisfies every `agent:*`
+ *   - `hub:admin` does NOT — narrow boundary; admins of the hub identity
+ *     surface aren't implicitly admins of every resource server.
+ *   - Legacy `claw:*` grants are normalized to `agent:*` (pre-0.1.0 compat;
+ *     drop in 0.2.0).
+ */
+export function hasScope(granted: string[], required: AgentScope): boolean {
+  const normalized = granted.map(normalizeGranted);
+  if (normalized.includes(required)) return true;
+  if (normalized.includes(SCOPE_VAULT_ADMIN)) return true;
+  if (required === SCOPE_AGENT_READ) {
+    return normalized.includes(SCOPE_AGENT_WRITE) || normalized.includes(SCOPE_AGENT_ADMIN);
+  }
+  if (required === SCOPE_AGENT_WRITE) {
+    return normalized.includes(SCOPE_AGENT_ADMIN);
+  }
+  return false;
+}
+
+export interface AuthOk {
+  ok: true;
+  claims: HubJwtClaims;
+}
+export interface AuthFail {
+  ok: false;
+  status: 401 | 403;
+  error: string;
+  errorType?: 'insufficient_scope';
+  requiredScope?: AgentScope;
+  grantedScopes?: string[];
+}
+export type AuthResult = AuthOk | AuthFail;
+
+function extractBearer(header: string | undefined): string | null {
+  if (!header) return null;
+  const m = header.match(/^Bearer\s+(.+)$/i);
+  return m ? m[1].trim() : null;
+}
+
+/**
+ * Single seam every `/api/*` handler runs through. Pulls `Authorization:
+ * Bearer <jwt>` off the request, validates it, checks scope. Returns
+ * structured pass/fail rather than throwing so callers can shape the
+ * response uniformly (RFC-6749-style 403 body for insufficient_scope).
+ */
+export async function authenticate(authHeader: string | undefined, required: AgentScope): Promise<AuthResult> {
+  const token = extractBearer(authHeader);
+  if (!token) {
+    return { ok: false, status: 401, error: 'missing or malformed Authorization header' };
+  }
+  let claims: HubJwtClaims;
+  try {
+    claims = await validateHubJwt(token);
+  } catch (err) {
+    return {
+      ok: false,
+      status: 401,
+      error: err instanceof HubJwtError ? err.message : 'token validation failed',
+    };
+  }
+  if (!hasScope(claims.scopes, required)) {
+    return {
+      ok: false,
+      status: 403,
+      error: `This endpoint requires the '${required}' scope.`,
+      errorType: 'insufficient_scope',
+      requiredScope: required,
+      grantedScopes: claims.scopes,
+    };
+  }
+  return { ok: true, claims };
+}

package/src/web/discord-validate.test.ts

@@ -0,0 +1,77 @@
+/**
+ * Discord token validator covers the four outcomes the wizard cares about:
+ *   1. Valid bot token → identity returned.
+ *   2. 401 from Discord → friendly "rejected token" error.
+ *   3. 200 from Discord but `bot=false` → reject (we require bots).
+ *   4. Network error → 502 surfacing the underlying message.
+ */
+import { describe, expect, it, vi } from 'vitest';
+
+import { validateDiscordBotToken } from './discord-validate.js';
+
+function makeFetchStub(body: unknown, init: { ok?: boolean; status?: number } = {}) {
+  const ok = init.ok ?? true;
+  const status = init.status ?? (ok ? 200 : 401);
+  return vi.fn().mockResolvedValue({
+    ok,
+    status,
+    statusText: ok ? 'OK' : 'Unauthorized',
+    json: async () => body,
+  } as Response) as unknown as typeof fetch;
+}
+
+describe('validateDiscordBotToken', () => {
+  it('returns identity for a valid bot token', async () => {
+    const stub = makeFetchStub({ id: '1491573333382523708', username: 'parabot', discriminator: '0', bot: true });
+    const result = await validateDiscordBotToken('test-token', stub);
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.identity.id).toBe('1491573333382523708');
+      expect(result.identity.username).toBe('parabot');
+      expect(result.identity.bot).toBe(true);
+    }
+    expect(stub).toHaveBeenCalledWith(
+      'https://discord.com/api/v10/users/@me',
+      expect.objectContaining({
+        headers: expect.objectContaining({ Authorization: 'Bot test-token' }),
+      }),
+    );
+  });
+
+  it('rejects 401 from Discord with an actionable message', async () => {
+    const stub = makeFetchStub({}, { ok: false, status: 401 });
+    const result = await validateDiscordBotToken('bad', stub);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.status).toBe(401);
+      expect(result.error).toMatch(/discord rejected/i);
+    }
+  });
+
+  it('rejects user tokens (bot=false)', async () => {
+    const stub = makeFetchStub({ id: '123', username: 'human', bot: false });
+    const result = await validateDiscordBotToken('user-token', stub);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.status).toBe(400);
+      expect(result.error).toMatch(/not a bot/i);
+    }
+  });
+
+  it('returns 502 on network error', async () => {
+    const stub = vi.fn().mockRejectedValue(new Error('ENOTFOUND')) as unknown as typeof fetch;
+    const result = await validateDiscordBotToken('whatever', stub);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.status).toBe(502);
+      expect(result.error).toMatch(/ENOTFOUND/);
+    }
+  });
+
+  it('rejects empty token without calling Discord', async () => {
+    const stub = vi.fn();
+    const result = await validateDiscordBotToken('   ', stub as unknown as typeof fetch);
+    expect(result.ok).toBe(false);
+    expect(stub).not.toHaveBeenCalled();
+  });
+});

package/src/web/discord-validate.ts

@@ -0,0 +1,88 @@
+/**
+ * Validate a Discord bot token by calling Discord's `/users/@me`.
+ *
+ * The setup wizard captures a bot token from the operator and needs to verify
+ * three things before persisting it: the token authenticates, the account is
+ * a bot, and we know the bot's user id (which becomes the basis of
+ * `discord:@me:<userId>` for the proactive DM-channel wiring).
+ *
+ * Discord returns 401 for an invalid token; on 200 the body contains
+ * `{ id, username, discriminator?, bot, ... }` per the v10 reference. We do
+ * not require any extra OAuth scopes — bot tokens carry implicit identity.
+ *
+ * The fetch is injectable for tests; in production it shells through the
+ * default global `fetch`. Errors are returned, not thrown — the caller
+ * surfaces them as 4xx to the wizard step UI.
+ */
+const DISCORD_API = 'https://discord.com/api/v10';
+
+export interface DiscordIdentity {
+  id: string;
+  username: string;
+  discriminator: string | null;
+  bot: boolean;
+}
+
+export type DiscordValidateResult =
+  | { ok: true; identity: DiscordIdentity }
+  | { ok: false; status: number; error: string };
+
+interface DiscordUserBody {
+  id?: unknown;
+  username?: unknown;
+  discriminator?: unknown;
+  bot?: unknown;
+}
+
+export async function validateDiscordBotToken(
+  token: string,
+  fetchImpl: typeof fetch = fetch,
+): Promise<DiscordValidateResult> {
+  const trimmed = token.trim();
+  if (!trimmed) return { ok: false, status: 400, error: 'token is empty' };
+
+  let res: Response;
+  try {
+    res = await fetchImpl(`${DISCORD_API}/users/@me`, {
+      headers: {
+        Authorization: `Bot ${trimmed}`,
+        Accept: 'application/json',
+      },
+    });
+  } catch (err) {
+    return {
+      ok: false,
+      status: 502,
+      error: `discord unreachable: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+
+  if (res.status === 401) {
+    return { ok: false, status: 401, error: 'discord rejected token (401 Unauthorized)' };
+  }
+  if (!res.ok) {
+    return {
+      ok: false,
+      status: res.status,
+      error: `discord ${res.status} ${res.statusText}`,
+    };
+  }
+
+  const body = (await res.json()) as DiscordUserBody;
+  if (typeof body.id !== 'string' || typeof body.username !== 'string') {
+    return { ok: false, status: 502, error: 'discord returned malformed user body' };
+  }
+  if (body.bot !== true) {
+    return { ok: false, status: 400, error: 'token is not a bot token (user.bot=false)' };
+  }
+
+  return {
+    ok: true,
+    identity: {
+      id: body.id,
+      username: body.username,
+      discriminator: typeof body.discriminator === 'string' ? body.discriminator : null,
+      bot: true,
+    },
+  };
+}

package/src/web/hub-discovery.test.ts

@@ -0,0 +1,98 @@
+/**
+ * Tests the hub-discovery client. The contract under test is the
+ * well-known shape (`vaults: [{name, url, version}]`) — same as
+ * `parachute-patterns/patterns/module-protocol.md` documents — and the
+ * 30s in-process cache so we don't hammer the hub.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { clearHubDiscoveryCache, fetchHubVaults } from './hub-discovery.js';
+
+let prevHubOrigin: string | undefined;
+
+beforeEach(() => {
+  prevHubOrigin = process.env.PARACHUTE_HUB_ORIGIN;
+  delete process.env.PARACHUTE_AGENT_HUB_ORIGIN;
+  delete process.env.PARACLAW_HUB_ORIGIN;
+  process.env.PARACHUTE_HUB_ORIGIN = 'https://parachute.example';
+  clearHubDiscoveryCache();
+});
+
+afterEach(() => {
+  if (prevHubOrigin === undefined) delete process.env.PARACHUTE_HUB_ORIGIN;
+  else process.env.PARACHUTE_HUB_ORIGIN = prevHubOrigin;
+  clearHubDiscoveryCache();
+});
+
+function makeFetchStub(body: unknown, init: { ok?: boolean; status?: number } = {}) {
+  const ok = init.ok ?? true;
+  const status = init.status ?? (ok ? 200 : 500);
+  return vi.fn().mockResolvedValue({
+    ok,
+    status,
+    statusText: ok ? 'OK' : 'Error',
+    json: async () => body,
+  } as Response);
+}
+
+describe('fetchHubVaults', () => {
+  it('GETs /.well-known/parachute.json on the resolved hub origin', async () => {
+    const stub = makeFetchStub({ vaults: [] });
+    await fetchHubVaults(stub);
+    expect(stub).toHaveBeenCalledTimes(1);
+    expect(stub).toHaveBeenCalledWith(
+      'https://parachute.example/.well-known/parachute.json',
+      expect.objectContaining({ headers: { Accept: 'application/json' } }),
+    );
+  });
+
+  it('returns the vaults array as-is from the well-known doc', async () => {
+    const vaults = [
+      { name: 'default', url: 'https://parachute.example/vault/default', version: '0.3.0' },
+      { name: 'work', url: 'https://parachute.example/vault/work', version: '0.3.0' },
+    ];
+    const stub = makeFetchStub({ vaults });
+    expect(await fetchHubVaults(stub)).toEqual(vaults);
+  });
+
+  it('returns [] when the well-known has no vaults block', async () => {
+    const stub = makeFetchStub({ services: [] });
+    expect(await fetchHubVaults(stub)).toEqual([]);
+  });
+
+  it('caches results within the TTL — second call does not hit fetch', async () => {
+    const stub = makeFetchStub({ vaults: [{ name: 'default', url: 'https://h/vault/default', version: '0.3.0' }] });
+    let t = 1_000_000;
+    const now = () => t;
+    await fetchHubVaults(stub, now);
+    t += 5_000;
+    await fetchHubVaults(stub, now);
+    expect(stub).toHaveBeenCalledTimes(1);
+  });
+
+  it('refetches after the 30s TTL elapses', async () => {
+    const stub = makeFetchStub({ vaults: [] });
+    let t = 1_000_000;
+    const now = () => t;
+    await fetchHubVaults(stub, now);
+    t += 31_000;
+    await fetchHubVaults(stub, now);
+    expect(stub).toHaveBeenCalledTimes(2);
+  });
+
+  it('refetches when the hub origin changes (e.g. PARACHUTE_HUB_ORIGIN flipped)', async () => {
+    const stub = makeFetchStub({ vaults: [] });
+    let t = 1_000_000;
+    const now = () => t;
+    await fetchHubVaults(stub, now);
+    process.env.PARACHUTE_HUB_ORIGIN = 'https://other.example';
+    await fetchHubVaults(stub, now);
+    expect(stub).toHaveBeenCalledTimes(2);
+    expect(stub).toHaveBeenLastCalledWith('https://other.example/.well-known/parachute.json', expect.anything());
+  });
+
+  it('throws on non-2xx so the endpoint can surface the error to the UI', async () => {
+    const stub = makeFetchStub({}, { ok: false, status: 503 });
+    await expect(fetchHubVaults(stub)).rejects.toThrow(/503/);
+  });
+});

package/src/web/hub-discovery.ts

@@ -0,0 +1,69 @@
+/**
+ * Read the hub's discovery doc to enumerate registered vaults.
+ *
+ * Source of truth: `<hubOrigin>/.well-known/parachute.json` (the documented
+ * discovery contract per `parachute-patterns/patterns/module-protocol.md`).
+ * The hub stamps `PARACHUTE_HUB_ORIGIN` on every lifecycle-spawned service
+ * (paraclaw#19); we resolve via `getHubOrigin()` so tailnet-hosted paraclaw
+ * sees its tailnet-routable hub origin.
+ *
+ * Why not `~/.parachute/services.json` directly: that file holds **port +
+ * loopback path**, which gives `http://127.0.0.1:<port>/vault/...`. The
+ * vault URL chosen here gets baked into each agent container's
+ * `container.json` as the MCP target. Loopback works only when the agent
+ * shares the host network namespace; for any non-host-network container
+ * (or peer-tailnet vault) the agent can't reach it. The well-known doc
+ * surfaces the public-routable URL (`https://<host>/vault/<label>`),
+ * which is the right thing to bake in.
+ *
+ * Cache: 30s in-process. Discovery is approximately static between
+ * installs — refreshing every few seconds would be wasteful, but caching
+ * forever would silently miss a freshly-installed vault. 30s is a balance
+ * users won't notice, and per-process restart clears it anyway.
+ */
+import { getHubOrigin } from './auth.js';
+
+export interface VaultListing {
+  name: string;
+  url: string;
+  version: string;
+}
+
+interface ParachuteDiscovery {
+  vaults?: VaultListing[];
+}
+
+const CACHE_TTL_MS = 30_000;
+
+interface CacheEntry {
+  origin: string;
+  fetchedAt: number;
+  vaults: VaultListing[];
+}
+
+let cache: CacheEntry | null = null;
+
+export function clearHubDiscoveryCache(): void {
+  cache = null;
+}
+
+export type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+
+export async function fetchHubVaults(
+  fetchImpl: FetchLike = fetch,
+  now: () => number = Date.now,
+): Promise<VaultListing[]> {
+  const origin = getHubOrigin();
+  if (cache && cache.origin === origin && now() - cache.fetchedAt < CACHE_TTL_MS) {
+    return cache.vaults;
+  }
+  const url = `${origin}/.well-known/parachute.json`;
+  const res = await fetchImpl(url, { headers: { Accept: 'application/json' } });
+  if (!res.ok) {
+    throw new Error(`hub discovery ${res.status} ${res.statusText} from ${url}`);
+  }
+  const doc = (await res.json()) as ParachuteDiscovery;
+  const vaults = Array.isArray(doc.vaults) ? doc.vaults : [];
+  cache = { origin, fetchedAt: now(), vaults };
+  return vaults;
+}

package/src/web/routes/activity.ts

@@ -0,0 +1,106 @@
+/**
+ * /api/groups/:folder/activity and /api/sessions/:id/activity — read-only
+ * tool-invocation feed. Rows are merged into central agent_activity by the
+ * delivery loop in src/delivery.ts; this route just paginates them out.
+ *
+ * Auth: agent:read. Listing tool calls leaks no plaintext (target is the
+ * tool name, summary is null today), but it does expose what the agent has
+ * been doing — operator-only by design.
+ */
+import http from 'node:http';
+
+import { listActivityByAgentGroup, listActivityBySession } from '../../db/agent-activity.js';
+import { getAgentGroupByFolder } from '../../db/agent-groups.js';
+import { getSession } from '../../db/sessions.js';
+
+const DEFAULT_LIMIT = 100;
+const MAX_LIMIT = 500;
+
+interface ActivityView {
+  id: string;
+  agentGroupId: string;
+  sessionId: string;
+  kind: string;
+  target: string | null;
+  summary: string | null;
+  createdAt: string;
+}
+
+function toView(r: {
+  id: string;
+  agent_group_id: string;
+  session_id: string;
+  kind: string;
+  target: string | null;
+  summary: string | null;
+  created_at: string;
+}): ActivityView {
+  return {
+    id: r.id,
+    agentGroupId: r.agent_group_id,
+    sessionId: r.session_id,
+    kind: r.kind,
+    target: r.target,
+    summary: r.summary,
+    createdAt: r.created_at,
+  };
+}
+
+const json = (res: http.ServerResponse, status: number, body: unknown): void => {
+  res.writeHead(status, { 'content-type': 'application/json' });
+  res.end(JSON.stringify(body));
+};
+
+const error = (res: http.ServerResponse, status: number, message: string): void =>
+  json(res, status, { error: message });
+
+function parseLimit(raw: string | null): number {
+  if (!raw) return DEFAULT_LIMIT;
+  const n = Number.parseInt(raw, 10);
+  if (!Number.isFinite(n) || n <= 0) return DEFAULT_LIMIT;
+  return Math.min(n, MAX_LIMIT);
+}
+
+export interface ActivityRouteContext {
+  pathname: string;
+  method: string;
+  url: URL;
+  res: http.ServerResponse;
+}
+
+export async function handleActivityRoute(ctx: ActivityRouteContext): Promise<boolean> {
+  const { pathname, method, url, res } = ctx;
+  if (method !== 'GET') return false;
+
+  const groupMatch = pathname.match(/^\/api\/groups\/([^/]+)\/activity$/);
+  if (groupMatch) {
+    const folder = decodeURIComponent(groupMatch[1]);
+    const group = getAgentGroupByFolder(folder);
+    if (!group) {
+      error(res, 404, `agent group not found: ${folder}`);
+      return true;
+    }
+    const since = url.searchParams.get('since') ?? undefined;
+    const limit = parseLimit(url.searchParams.get('limit'));
+    const rows = listActivityByAgentGroup(group.id, { since, limit });
+    json(res, 200, { activity: rows.map(toView) });
+    return true;
+  }
+
+  const sessionMatch = pathname.match(/^\/api\/sessions\/([^/]+)\/activity$/);
+  if (sessionMatch) {
+    const id = decodeURIComponent(sessionMatch[1]);
+    const session = getSession(id);
+    if (!session) {
+      error(res, 404, `session not found: ${id}`);
+      return true;
+    }
+    const since = url.searchParams.get('since') ?? undefined;
+    const limit = parseLimit(url.searchParams.get('limit'));
+    const rows = listActivityBySession(id, { since, limit });
+    json(res, 200, { activity: rows.map(toView) });
+    return true;
+  }
+
+  return false;
+}