npm - agent-relay-server - Versions diffs - 0.32.1 → 0.32.3 - Mend

agent-relay-server 0.32.1 → 0.32.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (97) hide show

package/src/routes/spec.ts ADDED Viewed

@@ -0,0 +1,54 @@
+// Auto-split from routes.ts (#299). Domain: spec.
+import { error, type Handler } from "./_shared";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+let cachedSpec: { data: unknown; etag: string } | null = null;
+function loadSpec(): { data: unknown; etag: string } | null {
+  try {
+    const specPath = resolve(import.meta.dir, "../docs/openapi.json");
+    const raw = readFileSync(specPath, "utf8");
+    const data = JSON.parse(raw);
+    const etag = `"${Bun.hash(raw).toString(36)}"`;
+    return { data, etag };
+  } catch {
+    return null;
+  }
+}
+export const getApiSpec: Handler = (req) => {
+  if (!cachedSpec) cachedSpec = loadSpec();
+  if (!cachedSpec) return error("API spec not generated. Run: bun run docs:api", 404);
+  const ifNoneMatch = req.headers.get("if-none-match");
+  if (ifNoneMatch === cachedSpec.etag) {
+    return new Response(null, { status: 304, headers: { ETag: cachedSpec.etag } });
+  }
+  return Response.json(cachedSpec.data, {
+    headers: {
+      "Content-Type": "application/json",
+      ETag: cachedSpec.etag,
+      "Cache-Control": "public, max-age=60",
+    },
+  });
+};
+export const getApiDocs: Handler = () => {
+  if (!cachedSpec) cachedSpec = loadSpec();
+  const specUrl = cachedSpec ? "./spec" : "https://petstore3.swagger.io/api/v3/openapi.json";
+  const html = `<!doctype html>
+<html>
+<head>
+  <title>Agent Relay API</title>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+</head>
+<body>
+  <script id="api-reference" data-url="${specUrl}"></script>
+  <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
+</body>
+</html>`;
+  return new Response(html, {
+    headers: { "Content-Type": "text/html; charset=utf-8" },
+  });
+};

package/src/routes/sse.ts ADDED Viewed

@@ -0,0 +1,9 @@
+// Auto-split from routes.ts (#299). Domain: sse.
+import { createSSEStream } from "../sse";
+import { type Handler } from "./_shared";
+export const getEvents: Handler = (req) => {
+  const url = new URL(req.url);
+  const agentId = url.searchParams.get("for") || null;
+  return createSSEStream(agentId);
+};

package/src/routes/stats.ts ADDED Viewed

@@ -0,0 +1,32 @@
+// Auto-split from routes.ts (#299). Domain: stats.
+import { ANALYTICS_PERIODS, getAnalytics, getHealth, getStats, type AnalyticsPeriod } from "../db";
+import { error, json, type Handler } from "./_shared";
+import { listMaintenanceJobs, runLegacyMaintenanceReaper, runMaintenanceJobNow } from "../maintenance";
+export const getStatsRoute: Handler = () => json(getStats());
+export const getAnalyticsRoute: Handler = (req) => {
+  const period = new URL(req.url).searchParams.get("period") ?? "24h";
+  if (!(period in ANALYTICS_PERIODS)) {
+    return error(`period must be one of ${Object.keys(ANALYTICS_PERIODS).join(", ")}`);
+  }
+  return json(getAnalytics(period as AnalyticsPeriod));
+};
+export const getHealthRoute: Handler = () => json(getHealth());
+export const getMaintenanceJobs: Handler = () => json(listMaintenanceJobs());
+export const postMaintenanceJobRun: Handler = async (_req, params) => {
+  try {
+    const run = await runMaintenanceJobNow(params.id!);
+    return json({ run, jobs: listMaintenanceJobs() }, run.status === "failed" ? 500 : 202);
+  } catch (e) {
+    if (e instanceof Error && e.message.includes("not found")) return error(e.message, 404);
+    throw e;
+  }
+};
+export const postSystemReap: Handler = async () => {
+  return json(await runLegacyMaintenanceReaper());
+};

package/src/routes/steward.ts ADDED Viewed

@@ -0,0 +1,45 @@
+// Auto-split from routes.ts (#299). Domain: steward.
+import { ValidationError } from "../db";
+import { cleanString } from "../validation";
+import { emitConfigChanged } from "../sse";
+import { error, json, parseBody, type Handler } from "./_shared";
+import { getStewardConfigEntry, getWorkspaceConfigEntry, setStewardConfig, setWorkspaceConfig } from "../config-store";
+import { isRecord } from "agent-relay-sdk";
+export const getStewardConfigRoute: Handler = () => json(getStewardConfigEntry());
+export const putStewardConfigRoute: Handler = async (req) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    const value = isRecord(parsed.body) && Object.prototype.hasOwnProperty.call(parsed.body, "value")
+      ? parsed.body.value
+      : parsed.body;
+    const updatedBy = isRecord(parsed.body) ? cleanString(parsed.body.updatedBy, "updatedBy", { max: 200 }) : undefined;
+    const entry = setStewardConfig(value, updatedBy);
+    emitConfigChanged(entry.namespace, entry.key, entry.version);
+    return json(entry, entry.version === 1 ? 201 : 200);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+export const getWorkspaceConfigRoute: Handler = () => json(getWorkspaceConfigEntry());
+export const putWorkspaceConfigRoute: Handler = async (req) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    const value = isRecord(parsed.body) && Object.prototype.hasOwnProperty.call(parsed.body, "value")
+      ? parsed.body.value
+      : parsed.body;
+    const updatedBy = isRecord(parsed.body) ? cleanString(parsed.body.updatedBy, "updatedBy", { max: 200 }) : undefined;
+    const entry = setWorkspaceConfig(value, updatedBy);
+    emitConfigChanged(entry.namespace, entry.key, entry.version);
+    return json(entry, entry.version === 1 ? 201 : 200);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};

package/src/routes/tasks.ts ADDED Viewed

@@ -0,0 +1,174 @@
+// Auto-split from routes.ts (#299). Domain: tasks.
+import { MAX_BODY_BYTES } from "../config";
+import { VALID_TASK_STATUSES, agentSessionStatus, auditEvent, dispatchTaskCallbacks, emitCommand, error, json, normalizeAgentSessionGuard, parseBody, parseId, parseQueryInt, type Handler } from "./_shared";
+import { ValidationError, claimTask, getMessage, getTask, listTaskEvents, listTasks, recordTaskEvent, renewTaskClaim, updateTaskStatus } from "../db";
+import { captureTaskResultMemory, injectMemoryForTaskClaim } from "../memory-service";
+import { cleanEpoch, cleanMeta, cleanString, optionalEnum } from "../validation";
+import { emitMessageClaimed, emitTaskChanged } from "../sse";
+import { errMessage, isRecord } from "agent-relay-sdk";
+import { type AgentSessionGuard, type TaskStatus, type TaskStatusInput } from "../types";
+function normalizeTaskStatusInput(body: unknown): TaskStatusInput {
+  if (!isRecord(body)) throw new ValidationError("JSON object body required");
+  const status = optionalEnum(body.status, "status", VALID_TASK_STATUSES);
+  if (!status) throw new ValidationError("status required");
+  return {
+    status: status as TaskStatus,
+    agentId: cleanString(body.agentId, "agentId", { max: 200 }),
+    instanceId: cleanString(body.instanceId, "instanceId", { max: 200 }),
+    epoch: cleanEpoch(body.epoch, "epoch"),
+    result: cleanString(body.result, "result", { max: MAX_BODY_BYTES }),
+    body: cleanString(body.body, "body", { max: MAX_BODY_BYTES }),
+    metadata: cleanMeta(body.metadata),
+  };
+}
+export const getTasks: Handler = (req) => {
+  const url = new URL(req.url);
+  const limitRaw = parseQueryInt(url.searchParams.get("limit"), { min: 1, max: 500 });
+  if (Number.isNaN(limitRaw)) return error("limit must be an integer between 1 and 500");
+  return json(listTasks({
+    status: url.searchParams.get("status") ?? undefined,
+    source: url.searchParams.get("source") ?? undefined,
+    target: url.searchParams.get("target") ?? undefined,
+    limit: limitRaw ?? 100,
+  }));
+};
+export const getTaskById: Handler = (_req, params) => {
+  const id = parseId(params.id);
+  if (id === null) return error("invalid task id");
+  const task = getTask(id);
+  return task ? json(task) : error("task not found", 404);
+};
+export const getTaskEvents: Handler = (_req, params) => {
+  const id = parseId(params.id);
+  if (id === null) return error("invalid task id");
+  if (!getTask(id)) return error("task not found", 404);
+  return json(listTaskEvents(id));
+};
+export const postClaimTask: Handler = async (req, params) => {
+  const id = parseId(params.id);
+  if (id === null) return error("invalid task id");
+  const parsed = await parseBody<{ agentId: string }>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  const agentId = parsed.body?.agentId;
+  if (!agentId) return error("agentId required");
+  let guard: AgentSessionGuard | undefined;
+  try {
+    guard = normalizeAgentSessionGuard(req, parsed.body);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+  const result = claimTask(id, agentId, guard);
+  if (!result.ok) {
+    const status = result.error === "task not found" ? 404 : result.error?.includes("race") || result.error === "stale agent instance" ? 409 : 400;
+    return error(result.error!, status);
+  }
+  emitTaskChanged(result.task!, "task.claimed");
+  auditEvent({
+    clientId: "server-task-" + id + "-claimed-" + agentId,
+    kind: "task",
+    title: "Task claimed",
+    body: result.task!.title,
+    meta: "by " + agentId,
+    icon: "ti-user-check",
+    view: "work",
+    taskId: id,
+    agentId,
+  });
+  if (result.task!.messageId) {
+    emitMessageClaimed(result.task!.messageId, agentId, getMessage(result.task!.messageId)?.claimExpiresAt);
+  }
+  try {
+    const memoryInjection = await injectMemoryForTaskClaim(result.task!, agentId);
+    if (memoryInjection) emitCommand(memoryInjection.command);
+  } catch (e) {
+    console.warn(`[memory] automatic task context assembly failed: ${errMessage(e)}`);
+  }
+  void dispatchTaskCallbacks(id, "task.claimed");
+  return json(result.task);
+};
+export const postRenewTaskClaim: Handler = async (req, params) => {
+  const id = parseId(params.id);
+  if (id === null) return error("invalid task id");
+  const parsed = await parseBody<{ agentId: string }>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  const agentId = parsed.body?.agentId;
+  if (!agentId) return error("agentId required");
+  let guard: AgentSessionGuard | undefined;
+  try {
+    guard = normalizeAgentSessionGuard(req, parsed.body);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+  const result = renewTaskClaim(id, agentId, guard);
+  if (!result.ok) {
+    const status = result.error === "task not found" ? 404 : 409;
+    return error(result.error!, status);
+  }
+  emitTaskChanged(result.task!, "task.updated");
+  if (result.task!.messageId) {
+    emitMessageClaimed(result.task!.messageId, agentId, getMessage(result.task!.messageId)?.claimExpiresAt);
+  }
+  return json(result.task);
+};
+export const patchTaskStatus: Handler = async (req, params) => {
+  const id = parseId(params.id);
+  if (id === null) return error("invalid task id");
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    const result = updateTaskStatus(id, normalizeTaskStatusInput(parsed.body));
+    if (!result.ok) return error(result.error!, result.error === "task not found" ? 404 : agentSessionStatus(result.error));
+    emitTaskChanged(result.task!, "task.status");
+    const capturedMemory = result.task!.status === "done"
+      ? await captureTaskResultMemory(result.task!, result.task!.result)
+      : null;
+    const shouldRecordMemoryEvent = capturedMemory && !listTaskEvents(id).some((event) =>
+      event.type === "memory.captured" && event.metadata?.memoryId === capturedMemory.id);
+    const memoryEvent = shouldRecordMemoryEvent
+      ? recordTaskEvent(id, {
+        source: "memory-broker",
+        type: "memory.captured",
+        severity: result.task!.severity,
+        title: "Memory captured",
+        body: capturedMemory.title,
+        metadata: {
+          memoryId: capturedMemory.id,
+          memory: {
+            id: capturedMemory.id,
+            type: capturedMemory.type,
+            scope: capturedMemory.scope,
+            title: capturedMemory.title,
+            tags: capturedMemory.tags,
+            sensitivity: capturedMemory.sensitivity,
+          },
+        },
+      })
+      : null;
+    auditEvent({
+      clientId: "server-task-" + id + "-status-" + result.task!.status + "-" + Date.now(),
+      kind: "task",
+      title: "Task " + result.task!.status,
+      body: result.task!.title,
+      meta: capturedMemory ? `captured ${capturedMemory.id}` : result.task!.claimedBy ? "by " + result.task!.claimedBy : result.task!.target,
+      icon: "ti-arrows-exchange",
+      view: "work",
+      taskId: id,
+      agentId: result.task!.claimedBy,
+      metadata: capturedMemory ? { memoryId: capturedMemory.id } : undefined,
+    });
+    void dispatchTaskCallbacks(id, "task.status");
+    return json({ task: result.task, event: result.event, ...(capturedMemory ? { memory: capturedMemory, memoryEvent } : {}) });
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};

package/src/routes/tokens.ts ADDED Viewed

@@ -0,0 +1,311 @@
+// Auto-split from routes.ts (#299). Domain: tokens.
+import { SPAWN_PROVIDERS, isRecord } from "agent-relay-sdk";
+import { ValidationError, getOrchestrator, upsertIntegrationRegistry } from "../db";
+import { auditEvent, authAuditMetadata, authorizeRoute, error, isRootCredentialRequest, json, parseBody, type Handler } from "./_shared";
+import { cleanString, cleanStringArray, cleanTokenConstraints, optionalEnum } from "../validation";
+import { createToken, deleteTokenProfile, getToken, getTokenProfile, listTokenProfiles, listTokens, renewToken, revokeToken, updateTokenProfile, upsertTokenProfile } from "../token-db";
+import { getComponentAuth } from "../security";
+import { issueIntegrationRuntimeToken, issueInteractiveRunnerRuntimeToken, issueMcpRuntimeToken, reissueRunnerRuntimeToken } from "../runtime-tokens";
+import { type SpawnProvider } from "../types";
+export const getTokens: Handler = () => json(listTokens());
+function cleanTtlSeconds(value: unknown): number | undefined {
+  if (value === undefined || value === null || value === "") return undefined;
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) {
+    throw new ValidationError("ttlSeconds must be a positive integer");
+  }
+  return value;
+}
+function cleanTokenProfileInput(body: unknown, partial = false) {
+  if (!isRecord(body)) throw new ValidationError("token profile body required");
+  const id = partial ? cleanString(body.id, "id", { max: 120 }) : cleanString(body.id, "id", { max: 120 });
+  const name = cleanString(body.name, "name", { required: !partial, max: 120 });
+  const description = cleanString(body.description, "description", { max: 500 });
+  const role = cleanString(body.role, "role", { required: !partial, max: 80 });
+  const scope = cleanStringArray(body.scope ?? body.scopes, "scope", { itemMax: 80, maxItems: 50 });
+  if (!partial && !scope?.length) throw new ValidationError("scope must contain at least one scope");
+  const constraints = body.constraints === null ? undefined : cleanTokenConstraints(body.constraints);
+  const ttlSeconds = cleanTtlSeconds(body.ttlSeconds);
+  const createdBy = cleanString(body.createdBy, "createdBy", { max: 120 });
+  return { id, name, description, role, scope, constraints, ttlSeconds, createdBy };
+}
+export const getTokenById: Handler = (_req, params) => {
+  const token = getToken(params.jti!);
+  return token ? json(token) : error("token not found", 404);
+};
+export const postToken: Handler = async (req) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    if (!isRecord(parsed.body)) return error("token body required");
+    const profileId = cleanString(parsed.body.profileId ?? parsed.body.profile, "profileId", { max: 120 });
+    const profile = profileId ? getTokenProfile(profileId) : null;
+    if (profileId && !profile) return error("token profile not found", 404);
+    const role = cleanString(parsed.body.role, "role", { max: 80 }) ?? profile?.role;
+    if (!role) return error("role required");
+    const sub = cleanString(parsed.body.sub, "sub", { max: 160 }) ?? role;
+    const scope = cleanStringArray(parsed.body.scope ?? parsed.body.scopes, "scope", { itemMax: 80, maxItems: 50 });
+    const constraints = cleanTokenConstraints(parsed.body.constraints);
+    const createdBy = cleanString(parsed.body.createdBy, "createdBy", { max: 120 });
+    const ttlSeconds = cleanTtlSeconds(parsed.body.ttlSeconds);
+    return json(createToken({ sub, role, scope, constraints, ttlSeconds, createdBy, profileId }), 201);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+export const postRuntimeTokenRenew: Handler = async (req) => {
+  const auth = getComponentAuth(req);
+  if (!auth?.jti) return error("scoped runtime token required", 403);
+  if (auth.role !== "provider") return error("provider runtime token required", 403);
+  const renewed = renewToken({
+    jti: auth.jti,
+    allowedProfileIds: ["provider-agent", "provider-interactive"],
+    createdBy: `renew:${auth.jti}`,
+  });
+  if (!renewed) return error("runtime token cannot be renewed", 403);
+  auditEvent({
+    clientId: "server-runtime-token-renew-" + auth.jti + "-" + Date.now(),
+    kind: "state",
+    title: "Runtime token renewed",
+    body: renewed.record.profileId ?? auth.role,
+    meta: renewed.record.jti,
+    icon: "ti-key",
+    view: "security",
+    metadata: {
+      previousJti: renewed.previous.jti,
+      previousExpiresAt: renewed.previous.expiresAt,
+      profileId: renewed.record.profileId,
+      jti: renewed.record.jti,
+      sub: renewed.record.sub,
+      ...authAuditMetadata(req),
+    },
+  });
+  return json({
+    token: renewed.token,
+    record: renewed.record,
+    previous: {
+      jti: renewed.previous.jti,
+      expiresAt: renewed.previous.expiresAt,
+    },
+  }, 201);
+};
+export const postOrchestratorRunnerToken: Handler = async (req, params) => {
+  const orch = getOrchestrator(params.id!);
+  if (!orch) return error("orchestrator not found", 404);
+  const denied = authorizeRoute(req, { scope: "command:write", resource: { orchestratorId: orch.id } });
+  if (denied) return denied;
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  if (!isRecord(parsed.body)) return error("body required");
+  const token = cleanString(parsed.body.token, "token", { required: true, max: 8192 })!;
+  const result = reissueRunnerRuntimeToken({
+    expiredToken: token,
+    orchestratorId: orch.id,
+    createdBy: `orchestrator-remint:${orch.id}`,
+  });
+  if ("error" in result) return error(result.error, 403);
+  auditEvent({
+    clientId: "server-runner-token-remint-" + result.record.jti + "-" + Date.now(),
+    kind: "state",
+    title: "Runner token re-minted",
+    body: result.record.sub,
+    meta: result.record.jti,
+    icon: "ti-key",
+    view: "security",
+    metadata: { orchestratorId: orch.id, jti: result.record.jti, sub: result.record.sub, ...authAuditMetadata(req) },
+  });
+  return json(result, 201);
+};
+export const postInteractiveRunnerRuntimeToken: Handler = async (req) => {
+  if (!isRootCredentialRequest(req)) return error("root credential required for runtime token exchange", 403);
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    if (!isRecord(parsed.body)) return error("runtime token body required");
+    const provider = optionalEnum(parsed.body.provider, "provider", SPAWN_PROVIDERS)! as SpawnProvider;
+    const cwd = cleanString(parsed.body.cwd, "cwd", { required: true, max: 500 })!;
+    const runnerId = cleanString(parsed.body.runnerId, "runnerId", { required: true, max: 240 })!;
+    const agentId = cleanString(parsed.body.agentId, "agentId", { max: 240 });
+    const label = cleanString(parsed.body.label, "label", { max: 120 });
+    const host = cleanString(parsed.body.host, "host", { max: 120 });
+    const runtimeToken = issueInteractiveRunnerRuntimeToken({
+      provider,
+      cwd,
+      runnerId,
+      agentId,
+      label,
+      host,
+      createdBy: `interactive:${runnerId}`,
+    });
+    auditEvent({
+      clientId: "server-runtime-token-interactive-" + runnerId + "-" + Date.now(),
+      kind: "state",
+      title: "Interactive runner token issued",
+      body: provider,
+      meta: runnerId,
+      icon: "ti-key",
+      view: "security",
+      metadata: {
+        provider,
+        runnerId,
+        agentId: agentId ?? runnerId,
+        profileId: runtimeToken.record.profileId,
+        jti: runtimeToken.record.jti,
+        ...authAuditMetadata(req),
+      },
+    });
+    return json(runtimeToken, 201);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+export const postMcpRuntimeToken: Handler = async (req) => {
+  if (!isRootCredentialRequest(req)) return error("root credential required for runtime token exchange", 403);
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    if (!isRecord(parsed.body)) return error("runtime token body required");
+    const sessionId = cleanString(parsed.body.sessionId, "sessionId", { required: true, max: 240 })!;
+    const agentId = cleanString(parsed.body.agentId, "agentId", { max: 240 });
+    const targets = cleanStringArray(parsed.body.targets, "targets", { itemMax: 80, maxItems: 50 });
+    const channels = cleanStringArray(parsed.body.channels, "channels", { itemMax: 80, maxItems: 50 });
+    const memoryScopes = cleanStringArray(parsed.body.memoryScopes, "memoryScopes", { itemMax: 80, maxItems: 50 });
+    const runtimeToken = issueMcpRuntimeToken({
+      sessionId,
+      agentId,
+      targets,
+      channels,
+      memoryScopes,
+      createdBy: `mcp:${sessionId}`,
+    });
+    auditEvent({
+      clientId: "server-runtime-token-mcp-" + sessionId + "-" + Date.now(),
+      kind: "state",
+      title: "MCP session token issued",
+      body: agentId ?? sessionId,
+      meta: sessionId,
+      icon: "ti-key",
+      view: "security",
+      metadata: {
+        sessionId,
+        agentId,
+        profileId: runtimeToken.record.profileId,
+        jti: runtimeToken.record.jti,
+        ...authAuditMetadata(req),
+      },
+    });
+    return json(runtimeToken, 201);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+export const postIntegrationRuntimeToken: Handler = async (req) => {
+  if (!isRootCredentialRequest(req)) return error("root credential required for runtime token exchange", 403);
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    if (!isRecord(parsed.body)) return error("runtime token body required");
+    const name = cleanString(parsed.body.name, "name", { required: true, max: 120 })!;
+    const targets = cleanStringArray(parsed.body.targets, "targets", { itemMax: 80, maxItems: 50 });
+    const channels = cleanStringArray(parsed.body.channels, "channels", { itemMax: 80, maxItems: 50 });
+    const runtimeToken = issueIntegrationRuntimeToken({
+      name,
+      targets,
+      channels,
+      createdBy: `integration:${name}`,
+    });
+    upsertIntegrationRegistry({
+      name,
+      scopes: runtimeToken.record.scope,
+      targets,
+      channels,
+      source: "api",
+    });
+    auditEvent({
+      clientId: "server-runtime-token-integration-" + name + "-" + Date.now(),
+      kind: "state",
+      title: "Integration token issued",
+      body: name,
+      meta: name,
+      icon: "ti-key",
+      view: "security",
+      metadata: {
+        integration: name,
+        profileId: runtimeToken.record.profileId,
+        jti: runtimeToken.record.jti,
+        ...authAuditMetadata(req),
+      },
+    });
+    return json(runtimeToken, 201);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+export const getTokenProfiles: Handler = () => json(listTokenProfiles());
+export const postTokenProfile: Handler = async (req) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    const input = cleanTokenProfileInput(parsed.body);
+    return json(upsertTokenProfile({
+      id: input.id,
+      name: input.name!,
+      description: input.description,
+      role: input.role!,
+      scope: input.scope!,
+      constraints: input.constraints,
+      ttlSeconds: input.ttlSeconds,
+      createdBy: input.createdBy,
+    }), 201);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    if (e instanceof Error) return error(e.message, 400);
+    throw e;
+  }
+};
+export const patchTokenProfile: Handler = async (req, params) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    const patch = cleanTokenProfileInput(parsed.body, true);
+    const updated = updateTokenProfile(params.id!, {
+      name: patch.name,
+      description: patch.description,
+      role: patch.role,
+      scope: patch.scope,
+      constraints: patch.constraints,
+      ttlSeconds: patch.ttlSeconds,
+      createdBy: patch.createdBy,
+    });
+    return updated ? json(updated) : error("token profile not found", 404);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    if (e instanceof Error) return error(e.message, e.message.includes("built-in") ? 409 : 400);
+    throw e;
+  }
+};
+export const deleteTokenProfileRoute: Handler = (_req, params) => {
+  return deleteTokenProfile(params.id!) ? json({ ok: true }) : error("token profile not found or built-in", 404);
+};
+export const postTokenRevoke: Handler = (_req, params) => {
+  if (!revokeToken(params.jti!)) return error("token not found or already revoked", 404);
+  return json({ ok: true });
+};