Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Owner administration for `gbrain serve --http`: the cookie-session guard
* (`requireAdmin`), password login, the /admin/api/* dashboard endpoints and
* the /admin/events SSE feed. Every /admin/api route here carries requireAdmin
* first (test/serve-http-admin-route-guard.test.ts).
*/
import express, { type Express, type Request, type RequestHandler, type Response } from 'express';
import { createHash, randomBytes } from 'crypto';
import type { BrainEngine } from '../core/engine.ts';
import { safeHexEqual } from '../core/timing-safe.ts';
import { normalizeTokenScopes } from '../core/legacy-token-scope.ts';
import { rescopeClientGrant } from '../core/grants/service.ts';
import { resolveOwnerHolder } from '../core/owner-holder.ts';
import { sqlQueryForEngine } from '../core/sql-query.ts';
import { lifetimeUsage, readMcpLogRetentionDays } from '../core/mcp-request-log-retention.ts';
import { readMcpUsageCoverage } from '../core/mcp-usage.ts';
import { VERSION } from '../version.ts';
import { mountAdminApiKeys } from './serve-http-api-keys.ts';
import { mountAdminClients } from './serve-http-clients.ts';
import { mountAdminRegistration } from './serve-http-registration.ts';
import { parseAdminGrantRequest, grantHttpStatus, GRANT_TOKEN_IMPLICATIONS, mountAdminGrantDiscovery, mountAdminGrantEdits } from './serve-http-grants.ts';
import { mountAdminAccess, mountAdminMemoryProposals } from './serve-http-access.ts';
import { probeHealth } from './serve-http-metrics.ts';
import type { ServeHttpContext } from './serve-http.ts';
/** Narrowest contract the handshake consumes. */
type AdminSseResponse = {
setHeader(name: string, value: string): unknown;
flushHeaders(): void;
write(chunk: string): unknown;
};
/**
* Complete the admin EventSource handshake immediately.
*
* `flushHeaders()` alone can leave reverse proxies and browsers waiting for
* the first response body bytes. An SSE comment is protocol-valid, ignored by
* EventSource consumers, and makes the stream observable end-to-end without
* fabricating an application event.
*/
export function openAdminSseStream(res: AdminSseResponse): void {
res.setHeader('Content-Type', 'text/event-stream');
res.setHeader('Cache-Control', 'no-cache');
res.setHeader('Connection', 'keep-alive');
res.flushHeaders();
res.write(': connected\n\n');
}
/**
* v0.38 Slice 4 — per-OAuth-client agent spend snapshot. Exported so the
* admin endpoint and `test/admin-agents-spend.test.ts` share the same SQL
* (single source of truth for the spend query shape).
*
* Returns one row per OAuth client that EITHER has the `agent` scope OR
* has at least one `bound_*` column set (the legacy admin client could
* also have bindings without scope='agent' on a partially-migrated brain;
* we want it visible in the viewer).
*
* Fields:
* - client_id, client_name
* - cap_usd_per_day: number | null (daily budget cap; NULL = no cap)
* - spent_cents_today: number (sum from mcp_spend_log, UTC-day-aligned)
* - pending_cents: number (sum of in-flight reservations, non-expired)
* - inflight_count: number (active subagent jobs owned by this client)
*
* Falls back to `[]` on any SQL error (pre-v0.38 brains where the v82-v84
* tables/columns don't yet exist).
*/
/** The `/admin/api/health-indicators` body; SQL lives here so tests pin the served query. */
export async function queryHealthIndicators(engine: BrainEngine): Promise<{
expiring_soon: number; error_rate: string; pending_writes: number;
oldest_pending_write_age_seconds: number; pending_writes_later_failed: number;
}> {
const sql = sqlQueryForEngine(engine);
const now = Math.floor(Date.now() / 1000);
const [expiring] = await sql`SELECT count(*)::int as count FROM oauth_tokens WHERE token_type = 'access' AND expires_at BETWEEN ${now} AND ${now + 86400}`;
// Excluded from the error numerator: success, success_with_warnings
// (a warn-mode success) and accepted_pending (#5249: an admitted write
// still in flight; its eventual failure is counted separately below);
// denied_after_list stays counted — a denied call IS a failure signal.
// surface_change is an OPERATION value (audit rows carry
// status='success'), so audit rows are excluded from BOTH counts —
// they are records of operator/self actions, not traffic.
const [errors] = await sql`SELECT count(*)::int as count FROM mcp_request_log WHERE status NOT IN ('success', 'success_with_warnings', 'accepted_pending') AND operation != 'surface_change' AND created_at > now() - interval '24 hours'`;
const [total] = await sql`SELECT count(*)::int as count FROM mcp_request_log WHERE operation != 'surface_change' AND created_at > now() - interval '24 hours'`;
const errorRate = (total as any).count > 0 ? ((errors as any).count / (total as any).count * 100).toFixed(1) : '0';
// #5249/O-CEO-14: pending writes are tracked apart from the error rate —
// how many are still in flight, how old the oldest is, and how many
// reported as pending in the last 24 hours later ended without committing.
const [pending] = await sql`SELECT count(*)::int AS count,
COALESCE(floor(extract(epoch FROM now() - min(created_at))), 0)::int AS oldest_age_seconds
FROM persistence_requests WHERE state IN ('queued', 'deferred', 'running', 'recovering')`;
const [laterFailed] = await sql`SELECT count(DISTINCT r.id)::int AS count FROM mcp_request_log l
JOIN persistence_requests r ON r.request_id::text = l.params->>'write_request_id'
WHERE l.status = 'accepted_pending' AND l.created_at > now() - interval '24 hours'
AND r.state IN ('conflict', 'failed', 'cancelled')`;
return {
expiring_soon: (expiring as any).count,
error_rate: `${errorRate}%`,
pending_writes: (pending as any).count,
oldest_pending_write_age_seconds: (pending as any).oldest_age_seconds,
pending_writes_later_failed: (laterFailed as any).count,
};
}
export interface AgentClientSpend {
client_id: string;
client_name: string;
cap_usd_per_day: number | null;
spent_cents_today: number;
pending_cents: number;
unknown_count: number;
inflight_count: number;
}
export async function queryAgentClientSpend(engine: BrainEngine): Promise<AgentClientSpend[]> {
const sql = sqlQueryForEngine(engine);
const rows = await sql`
SELECT
c.client_id,
c.client_name,
COALESCE(c.budget_usd_per_day, NULL) AS cap_usd_per_day,
COALESCE((
SELECT SUM(spend_cents)::text
FROM mcp_spend_log
WHERE client_id = c.client_id
-- Double AT TIME ZONE: the inner one yields NAIVE UTC-midnight;
-- the outer one converts it back to a timestamptz INSTANT. Without
-- it, the naive value is reinterpreted in the SESSION timezone, so
-- any non-UTC session (host-tz PGLite, a tz-configured Postgres
-- role) shifts the day boundary by the offset and today's spend
-- underreports every evening.
AND created_at >= date_trunc('day', now() AT TIME ZONE 'UTC') AT TIME ZONE 'UTC'
), '0') AS spent_cents_today,
COALESCE((
SELECT SUM(estimated_cents)::text
FROM mcp_spend_reservations
WHERE client_id = c.client_id
AND status IN ('pending', 'expired')
), '0') AS pending_cents,
(SELECT COUNT(*)::int FROM mcp_spend_reservations
WHERE client_id = c.client_id AND status IN ('pending', 'expired')
AND estimate_known = false) AS unknown_count,
COALESCE((
SELECT COUNT(*)::int
FROM minion_jobs
WHERE name = 'subagent'
AND status IN ('waiting', 'active', 'waiting-children', 'delayed', 'paused')
AND data->>'__owner_client_id' = c.client_id
), 0) AS inflight_count
FROM oauth_clients c
WHERE c.deleted_at IS NULL
AND ('agent' = ANY (string_to_array(c.scope, ' ')) OR c.bound_tools IS NOT NULL)
ORDER BY c.client_name ASC
`;
return rows.map(r => ({
client_id: String(r.client_id),
client_name: String(r.client_name ?? r.client_id),
cap_usd_per_day: r.cap_usd_per_day !== null && r.cap_usd_per_day !== undefined
? parseFloat(String(r.cap_usd_per_day))
: null,
spent_cents_today: parseFloat(String(r.spent_cents_today ?? '0')),
pending_cents: parseFloat(String(r.pending_cents ?? '0')),
unknown_count: Number(r.unknown_count ?? 0),
inflight_count: Number(r.inflight_count ?? 0),
}));
}
/** Admin auth middleware over the server's cookie-session map (sessionId -> expiresAt). */
export function createRequireAdmin(adminSessions: Map<string, number>): RequestHandler {
return function requireAdmin(req: express.Request, res: express.Response, next: express.NextFunction) {
const sessionId = (req.cookies as Record<string, string>)?.gbrain_admin;
if (!sessionId || !adminSessions.has(sessionId)) {
res.status(401).json({ error: 'Admin authentication required' });
return;
}
const expiresAt = adminSessions.get(sessionId)!;
if (Date.now() > expiresAt) {
adminSessions.delete(sessionId);
res.status(401).json({ error: 'Session expired' });
return;
}
next();
};
}
/** POST /admin/login: bootstrap-credential login that opens a cookie session. */
export function mountAdminLogin(app: Express, ctx: ServeHttpContext): void {
const { adminLimits, bootstrapHash, adminSessions, adminCookie } = ctx;
// ---------------------------------------------------------------------------
// Admin authentication (cookie-based)
// ---------------------------------------------------------------------------
// v0.40 D15.5: safeHexEqual extracted to src/core/timing-safe.ts so the new
// /webhooks/github HMAC verifier reuses the same constant-time compare.
// POST /admin/login — JSON body with token (for programmatic/UI login).
// Independent limits: 60 total requests and 10 failed authentications/min/IP.
app.post('/admin/login', adminLimits.total, adminLimits.failures, express.json(), (req, res) => {
const token = req.body?.token;
if (!token || typeof token !== 'string') {
res.status(400).json({ error: 'Token required' });
return;
}
const tokenHash = createHash('sha256').update(token).digest('hex');
if (!safeHexEqual(tokenHash, bootstrapHash)) {
res.status(401).json({ error: 'Owner credential rejected. Use the protected bootstrap credential configured for this running server; an OAuth token cannot administer it.' });
return;
}
res.locals.ownerAuthenticated = true;
const sessionId = randomBytes(32).toString('hex');
const expiresAt = Date.now() + 24 * 60 * 60 * 1000; // 24 hours
adminSessions.set(sessionId, expiresAt);
res.cookie('gbrain_admin', sessionId, adminCookie(req, 24 * 60 * 60 * 1000));
res.json({ status: 'authenticated' });
});
}
/** The /admin/api/* dashboard endpoints and the /admin/events SSE feed, in registration order. */
export function mountAdminApi(app: Express, ctx: ServeHttpContext): void {
const { requireAdmin, sseClients } = ctx;
mountAdminOverviewApi(app, ctx);
mountAdminCalibrationApi(app, ctx);
mountAdminKeyApi(app, ctx);
mountAdminClientApi(app, ctx);
// ---------------------------------------------------------------------------
// SSE live activity feed
// ---------------------------------------------------------------------------
app.get('/admin/events', requireAdmin, (req: Request, res: Response) => {
openAdminSseStream(res);
sseClients.add(res);
req.on('close', () => sseClients.delete(res));
});
}
function mountAdminOverviewApi(app: Express, ctx: ServeHttpContext): void {
const { engine, config, sql, requireAdmin, adminSessions } = ctx;
// ---------------------------------------------------------------------------
// Admin API endpoints
// ---------------------------------------------------------------------------
// Sign-out-everywhere: nuke ALL active admin sessions in-memory. Every
// browser/tab fails its next request, gets 401, redirects to login.
// The bootstrap token itself is unaffected (still valid for new
// magic-link mints) — this only revokes existing cookie sessions.
app.post('/admin/api/sign-out-everywhere', requireAdmin, (_req: Request, res: Response) => {
const count = adminSessions.size;
adminSessions.clear();
res.json({ revoked_sessions: count });
});
app.get('/admin/api/agents', requireAdmin, async (_req: Request, res: Response) => {
try {
// Unified view: OAuth clients + legacy API keys
const oauthClients = await sql`
SELECT c.client_id as id, c.client_name as name, 'oauth' as auth_type,
c.grant_types, c.scope, c.source_id, c.federated_read,
c.created_at, c.token_ttl,
CASE WHEN c.deleted_at IS NOT NULL THEN 'revoked' ELSE 'active' END as status,
(SELECT count(*)::int FROM mcp_request_log WHERE token_name = c.client_id AND created_at > now() - interval '24 hours') as requests_today
FROM oauth_clients c ORDER BY c.created_at DESC
`;
const legacyKeys = await sql`
SELECT a.id, a.name, 'api_key' as auth_type,
'{"bearer"}' as grant_types,
a.scopes,
a.created_at, null as token_ttl,
CASE WHEN a.revoked_at IS NOT NULL THEN 'revoked' ELSE 'active' END as status,
a.last_used_at,
(SELECT count(*)::int FROM mcp_request_log WHERE token_name = a.name AND created_at > now() - interval '24 hours') as requests_today
FROM access_tokens a ORDER BY a.created_at DESC
`;
// #6770: lifetime totals = rows still in the log + the pruned tally (mcp-request-log-retention.ts).
const lifetime = await lifetimeUsage(engine, [...oauthClients.map(c => String(c.id)), ...legacyKeys.map(k => String(k.name))]);
res.json([
...oauthClients.map(c => ({ ...c, last_used_at: lifetime.get(String(c.id))?.last_used_at ?? null, total_requests: lifetime.get(String(c.id))?.requests ?? 0 })),
...legacyKeys.map(({ scopes, ...key }) => ({
...key,
total_requests: lifetime.get(String(key.name))?.requests ?? 0,
// The SAME normalizer the verify path uses — the dashboard must
// never display a grant the serve doesn't enforce (NULL =
// grandfathered full access; damaged/deny rows show empty).
scope: normalizeTokenScopes(scopes)?.join(' ') ?? 'read write admin',
source_id: null,
federated_read: [],
})),
]);
} catch (e) {
res.status(503).json({ error: 'service_unavailable' });
}
});
app.get('/admin/api/sources', requireAdmin, async (_req: Request, res: Response) => {
try {
const { listSources } = await import('../core/sources-ops.ts');
const sources = await listSources(engine);
res.json(sources.map(({ id, name, federated }) => ({ id, name, federated })));
} catch {
res.status(503).json({ error: 'service_unavailable' });
}
});
// v0.38 Slice 4 — per-OAuth-client agent spend viewer. Pre-computes today's
// spend (committed + pending reservations) per client so the Agents tab
// can render a "$X / $Y today" cell. Read-side endpoint only — no mutation.
// Falls back to an empty array on pre-v0.38 brains where mcp_spend_log
// exists but agent dispatch hasn't recorded anything.
app.get('/admin/api/agents/spend', requireAdmin, async (_req: Request, res: Response) => {
try {
const rows = await queryAgentClientSpend(engine);
res.json(rows);
} catch (e) {
// Pre-v0.38 brains: tables may not exist yet. Return empty so the UI
// renders gracefully instead of erroring.
res.json([]);
}
});
app.get('/admin/api/stats', requireAdmin, async (_req: Request, res: Response) => {
try {
const [clients] = await sql`SELECT count(*)::int as count FROM oauth_clients`;
const [tokens] = await sql`SELECT count(*)::int as count FROM oauth_tokens WHERE token_type = 'access' AND expires_at > ${Math.floor(Date.now() / 1000)}`;
const [requests] = await sql`SELECT count(*)::int as count FROM mcp_request_log WHERE created_at > now() - interval '24 hours'`;
const [apiKeys] = await sql`SELECT count(*)::int as count FROM access_tokens WHERE revoked_at IS NULL`;
res.json({
connected_agents: (clients as any).count,
active_tokens: (tokens as any).count,
active_api_keys: (apiKeys as any).count,
requests_today: (requests as any).count,
});
} catch {
res.status(503).json({ error: 'service_unavailable' });
}
});
app.get('/admin/api/health-indicators', requireAdmin, async (_req: Request, res: Response) => {
try {
res.json(await queryHealthIndicators(engine));
} catch {
res.status(503).json({ error: 'service_unavailable' });
}
});
// #6696 B2: the full ops snapshot (doctor ops tier + capacity view), cached 60 s per engine (doctor/ops-snapshot.ts).
app.get('/admin/api/ops', requireAdmin, async (_req: Request, res: Response) => {
try {
res.json(await (await import('./doctor/ops-snapshot.ts')).cachedOpsSnapshot(engine));
} catch {
res.status(503).json({ error: 'service_unavailable' });
}
});
// Full engine stats. v0.28.10 moved this off /health (which is now liveness
// only — see probeLiveness) so dashboards needing page_count / chunk_count
// / etc. authenticate as admin and call this endpoint. probeHealth races
// engine.getStats() against HEALTH_TIMEOUT_MS so a saturated pool returns
// 503 rather than hanging.
app.get('/admin/api/full-stats', requireAdmin, async (_req: Request, res: Response) => {
const result = await probeHealth(engine, config.engine || 'pglite', VERSION);
res.status(result.status).json(result.body);
});
// v0.41 D2 — live jobs dashboard data. Shares readSnapshot() with the
// TTY `gbrain jobs watch` command so the two surfaces stay 1:1.
app.get('/admin/api/jobs/watch', requireAdmin, async (_req: Request, res: Response) => {
try {
const { readSnapshot } = await import('./jobs-watch.ts');
const snap = await readSnapshot(engine);
res.json(snap);
} catch (e) {
const msg = e instanceof Error ? e.message : String(e);
res.status(500).json({ error: msg });
}
});
}
function mountAdminCalibrationApi(app: Express, ctx: ServeHttpContext): void {
const { engine, requireAdmin } = ctx;
// v0.36.1.0 (T15 / E6 / D23) — Calibration tab data endpoints.
// Server-rendered SVG charts; admin SPA renders via TrustedSVG wrapper.
// v0.36.1.0 (TD3) — pattern drill-down. Returns the source takes that
// produced the pattern statement at index `id` of the active profile.
// v0.36.1.0 ship state: returns the top N takes in the holder's overall
// takes table, sorted by weight desc. v0.37+ will store per-pattern
// source_take_ids on calibration_profiles_patterns so the drill-down
// shows the EXACT takes that drove the pattern.
app.get('/admin/api/calibration/pattern/:id', requireAdmin, async (req: Request, res: Response) => {
try {
const { getLatestProfile } = await import('./calibration.ts');
const holder = resolveOwnerHolder({ override: (req.query.holder as string) || undefined, configValue: await engine.getConfig('emotional_weight.user_holder') });
const profile = await getLatestProfile(engine, { holder });
if (!profile) {
res.status(404).json({ error: 'no_profile' });
return;
}
const rawId = req.params.id;
const idStr = Array.isArray(rawId) ? rawId[0] : rawId;
const idx = Number.parseInt(idStr ?? '', 10) - 1;
if (!Number.isFinite(idx) || idx < 0 || idx >= profile.pattern_statements.length) {
res.status(400).json({ error: 'invalid_pattern_index', max: profile.pattern_statements.length });
return;
}
const statement = profile.pattern_statements[idx];
// v0.36.1.0 ship state: surface the top resolved takes for the
// holder as drill-down evidence. Per-pattern provenance is v0.37.
const takes = await engine.executeRaw<{
id: string;
page_slug: string;
row_num: number;
claim: string;
weight: number;
resolved_quality: string | null;
since_date: string | null;
}>(
// `takes` has no page_slug column — it comes from the joined page.
// id::text — it's a BIGSERIAL (bigint); res.json() below can't serialize a
// raw bigint ("cannot serialize BigInt"), so project it as a string.
`SELECT t.id::text AS id, p.slug AS page_slug, t.row_num, t.claim, t.weight, t.resolved_quality, t.since_date
FROM takes t JOIN pages p ON p.id = t.page_id
WHERE t.holder = $1 AND t.active = true AND t.resolved_at IS NOT NULL
ORDER BY t.weight DESC, t.since_date DESC
LIMIT 25`,
[holder],
);
res.json({
pattern_statement: statement,
pattern_index: idx + 1,
holder,
provenance_note: 'v0.36.1.0 ship state shows top-25 resolved takes for this holder; per-pattern source_take_ids land in v0.37.',
takes,
});
} catch (err) {
res.status(500).json({ error: err instanceof Error ? err.message : 'unknown' });
}
});
app.get('/admin/api/calibration/profile', requireAdmin, async (req: Request, res: Response) => {
try {
const { getLatestProfile } = await import('./calibration.ts');
const holder = resolveOwnerHolder({ override: (req.query.holder as string) || undefined, configValue: await engine.getConfig('emotional_weight.user_holder') });
const profile = await getLatestProfile(engine, { holder });
res.json(profile);
} catch (err) {
res.status(500).json({ error: err instanceof Error ? err.message : 'unknown' });
}
});
app.get('/admin/api/calibration/charts/:type', requireAdmin, async (req: Request, res: Response) => {
try {
const { getLatestProfile } = await import('./calibration.ts');
const {
renderBrierTrend,
renderDomainBars,
renderAbandonedThreadsCard,
renderPatternStatementsCard,
} = await import('../core/calibration/svg-renderer.ts');
const holder = resolveOwnerHolder({ override: (req.query.holder as string) || undefined, configValue: await engine.getConfig('emotional_weight.user_holder') });
const type = req.params.type;
const profile = await getLatestProfile(engine, { holder });
res.setHeader('Content-Type', 'image/svg+xml; charset=utf-8');
res.setHeader('Cache-Control', 'private, max-age=60');
if (type === 'brier-trend') {
// v0.36.1.0 ship state: 1-point series from the active profile. A
// proper 90-day time series will read from calibration_profiles
// generated_at history in v0.37 once we have multiple snapshots.
const series = profile?.brier !== null && profile?.brier !== undefined
// generated_at comes back from the engine as a Date (TIMESTAMPTZ), not
// a string — `.slice` would throw. Normalize to a YYYY-MM-DD string.
? [{ date: new Date(profile.generated_at).toISOString().slice(0, 10), brier: profile.brier }]
: [];
return res.send(renderBrierTrend({ series }));
}
if (type === 'domain-bars') {
// v0.36.1.0 ship state: domain_scorecards JSONB is a placeholder
// (per-domain rendering comes when batchGetTakesScorecards lands in
// a follow-up). Render empty for now.
return res.send(renderDomainBars({ bars: [] }));
}
if (type === 'pattern-statements') {
return res.send(
renderPatternStatementsCard(
(profile?.pattern_statements ?? []).map((text: string) => ({ text })),
),
);
}
if (type === 'abandoned-threads') {
// v0.36.1.0 ship state: pull abandoned threads inline via a small
// SQL query (the doctor check counts them; this surfaces details).
const rows = await engine.executeRaw<{
id: number;
page_slug: string;
claim: string;
weight: number;
since_date: string;
}>(
// `takes` has no page_slug column — it comes from the joined page.
// since_date is TEXT and may be month-precision ('YYYY-MM'); '2026-06'::date
// throws "invalid input syntax for type date", so normalize to the 1st
// before casting.
`SELECT t.id, p.slug AS page_slug, t.claim, t.weight, t.since_date
FROM takes t JOIN pages p ON p.id = t.page_id
WHERE t.active = true AND t.resolved_at IS NULL AND t.superseded_by IS NULL
AND t.weight >= 0.7
AND (t.since_date || CASE WHEN length(t.since_date) = 7 THEN '-01' ELSE '' END)::date
< (now() - INTERVAL '12 months')
ORDER BY t.since_date ASC
LIMIT 5`,
);
const now = new Date();
const threads = rows.map(r => {
const since = new Date((r.since_date.length === 7 ? r.since_date + '-15' : r.since_date));
const monthsSilent = Math.max(0, Math.floor((now.getTime() - since.getTime()) / (1000 * 60 * 60 * 24 * 30)));
return {
takeId: r.id,
pageSlug: r.page_slug,
claim: r.claim,
monthsSilent,
conviction: r.weight,
};
});
return res.send(renderAbandonedThreadsCard(threads));
}
res.status(400).json({ error: 'unknown_chart_type', supported: ['brier-trend', 'domain-bars', 'pattern-statements', 'abandoned-threads'] });
return;
} catch (err) {
res.status(500).json({ error: err instanceof Error ? err.message : 'unknown' });
return;
}
});
}
function mountAdminKeyApi(app: Express, ctx: ServeHttpContext): void {
const { engine, sql, requireAdmin } = ctx;
app.get('/admin/api/requests', requireAdmin, async (req: Request, res: Response) => {
try {
const page = parseInt(req.query.page as string) || 1;
const limit = 50;
const offset = (page - 1) * limit;
const agent = req.query.agent as string;
const operation = req.query.operation as string;
const status = req.query.status as string;
// Dynamic filtering: SqlQuery is deliberately scalar-only and does not
// support fragment composition (the prior `sql\`AND ... = ${v}\`` shape).
// Build the WHERE clause with positional placeholders + a params array.
// `WHERE 1=1` lets us always have a WHERE clause and conditionally
// append `AND col = $N` fragments — still parameterized, still escaped
// by the driver, no sql.unsafe.
const filters: string[] = [];
const params: (string | number)[] = [];
if (agent && agent !== 'all') {
filters.push(`AND token_name = $${params.length + 1}`);
params.push(agent);
}
if (operation && operation !== 'all') {
filters.push(`AND operation = $${params.length + 1}`);
params.push(operation);
}
if (status && status !== 'all') {
filters.push(`AND status = $${params.length + 1}`);
params.push(status);
}
const filterSql = filters.join(' ');
const limitParam = `$${params.length + 1}`;
const offsetParam = `$${params.length + 2}`;
const rows = await engine.executeRaw(
`SELECT id, token_name, COALESCE(agent_name, token_name) as agent_name,
operation, latency_ms, status, params, error_message, created_at
FROM mcp_request_log
WHERE 1=1 ${filterSql}
ORDER BY created_at DESC LIMIT ${limitParam} OFFSET ${offsetParam}`,
[...params, limit, offset],
);
const [countResult] = await engine.executeRaw<{ total: number }>(
`SELECT count(*)::int as total FROM mcp_request_log
WHERE 1=1 ${filterSql}`,
params,
);
const [retention_days, pruned_before] = await Promise.all([readMcpLogRetentionDays(engine), readMcpUsageCoverage(engine, 1).then(c => c.pruned_before)]);
res.json({ rows, total: countResult.total, page, pages: Math.ceil(countResult.total / limit), retention_days, pruned_before });
} catch {
res.status(503).json({ error: 'service_unavailable' });
}
});
mountAdminApiKeys(app, requireAdmin, engine);
}
function mountAdminClientApi(app: Express, ctx: ServeHttpContext): void {
const { engine, requireAdmin, oauthProvider, issuerUrl, mcpResourceUrl } = ctx;
mountAdminGrantDiscovery(app, requireAdmin, engine, mcpResourceUrl.toString());
mountAdminClients(app, requireAdmin, engine, mcpResourceUrl.toString());
mountAdminRegistration(app, requireAdmin, engine, mcpResourceUrl, issuerUrl);
// Update client TTL
app.post('/admin/api/update-client-ttl', requireAdmin, express.json(), async (req: Request, res: Response) => {
try {
const { clientId, tokenTtl } = req.body;
if (!clientId) { res.status(400).json({ error: 'clientId required' }); return; }
if (tokenTtl === undefined) { res.status(400).json({ error: 'tokenTtl required' }); return; }
const request = parseAdminGrantRequest(req.body);
const result = await rescopeClientGrant(engine, clientId, { tokenTtlSeconds: request.patch.tokenTtlSeconds }, { actor: 'admin-api', expectedRevision: request.expectedRevision, dryRun: request.dryRun });
res.json(request.dryRun ? { ...result, tokenImplications: GRANT_TOKEN_IMPLICATIONS } : { updated: true, tokenTtl: result.after.tokenTtlSeconds, ...(request.expectedRevision !== undefined ? { revision: result.revision } : {}) });
} catch (e) {
res.status(grantHttpStatus(e)).json({ error: e instanceof Error ? e.message : 'Update failed' });
}
});
mountAdminGrantEdits(app, requireAdmin, engine, oauthProvider);
mountAdminAccess(app, requireAdmin, engine);
mountAdminMemoryProposals(app, requireAdmin, engine);
// Revoke OAuth client
app.post('/admin/api/revoke-client', requireAdmin, express.json(), async (req: Request, res: Response) => {
try {
const { clientId } = req.body;
if (!clientId) { res.status(400).json({ error: 'clientId required' }); return; }
await oauthProvider.revokeClient(clientId);
res.json({ revoked: true });
} catch (e) {
res.status(500).json({ error: e instanceof Error ? e.message : 'Revoke failed' });
}
});
}