agent-relay-server 0.82.0 → 0.83.1

package/src/agent-drive-arbiter.ts

@@ -0,0 +1,112 @@
+// Concurrency arbitration — "two humans driving one agent safely" (#388 users wave 5, #394).
+//
+// THE single decision home for "may this user drive this agent right now?". It composes three
+// things the routes must never re-derive piecemeal:
+//   1. the single-vs-multi-user switch (`isMultiUserWorld`) — single-user is a COMPLETE no-op,
+//   2. the per-agent drive lease (`src/db/drive-leases.ts`) — the soft-lock / "X is driving",
+//   3. role (`resolveViewer`) — an admin overrides a held wheel.
+//
+// The drive routes (prompt submit, interrupt, plan-approve/answer) and the explicit handoff
+// endpoint both call `arbitrateDrive`, so the lock can never be enforced in one seam and skipped
+// in another.
+//
+// Back-compat (load-bearing): with a single user `arbitrateDrive` returns `allowed` WITHOUT
+// touching the lease table — the solo operator always holds the wheel, prompt/interrupt/approve
+// flow exactly as before, and no expiry can ever strand them out of their own agent. Arbitration
+// only engages once a second user exists.
+import { canonicalHumanAgentId, userSinkId } from "agent-relay-sdk";
+import { isMultiUserWorld } from "./db/agent-ownership.ts";
+import { resolveViewer } from "./agent-authz.ts";
+import { getUser } from "./db/users.ts";
+import {
+  acquireDriveLease,
+  getDriveLease,
+  releaseDriveLease,
+  takeOverDriveLease,
+  type DriveLeaseRecord,
+} from "./db/drive-leases.ts";
+
+/** Who holds (or held) the wheel, resolved for human-readable "X is driving" messaging. */
+interface DriveHolder {
+  /** Relational `users.id`. */
+  userId: string;
+  /** Canonical human message address (`user` / `user:<id>`). */
+  address: string;
+  /** Friendly name when the user row resolves. */
+  displayName?: string;
+}
+
+/**
+ * The outcome of an arbitration. `mode` records WHY it was allowed so the route can audit a steal
+ * distinctly from an ordinary acquire:
+ * - `solo`     — single-user world, no lease written (back-compat no-op).
+ * - `holder`   — caller already held the wheel; lease refreshed.
+ * - `acquired` — wheel was free; caller took it.
+ * - `override` — caller is an admin who stole a live lease from another driver.
+ */
+export type DriveArbitration =
+  | { allowed: true; mode: "solo" | "holder" | "acquired" | "override"; lease: DriveLeaseRecord | null; previousHolder?: DriveHolder }
+  | { allowed: false; heldBy: DriveHolder; lease: DriveLeaseRecord };
+
+/** Resolve a `users.id` into a displayable drive holder. */
+function driveHolder(userId: string): DriveHolder {
+  const user = getUser(userId);
+  const holder: DriveHolder = { userId, address: canonicalHumanAgentId(userSinkId(userId)) };
+  const name = user?.displayName ?? user?.handle;
+  if (name) holder.displayName = name;
+  return holder;
+}
+
+/** A short "X is driving this agent" phrase for the 409 body / UI. */
+export function drivingMessage(holder: DriveHolder): string {
+  return `${holder.displayName ?? holder.address} is driving this agent`;
+}
+
+/**
+ * Decide whether `userId` may drive `agentId` now, taking/refreshing the lease as a side effect on
+ * success. An admin always wins (stealing a live lease → `override`); a non-admin wins only when
+ * the wheel is free or already theirs, otherwise it is `denied` with who holds it.
+ *
+ * Callers pass an already-`drive`-authorized user (the #392 gate runs first); arbitration is the
+ * second, concurrency layer on top.
+ */
+export function arbitrateDrive(userId: string, agentId: string, opts: { now?: number } = {}): DriveArbitration {
+  // Single-user world → no-op. No lease row is written, so a vanished/expired lease can NEVER
+  // strand the solo user out of their own agent (the load-bearing back-compat invariant).
+  if (!isMultiUserWorld()) return { allowed: true, mode: "solo", lease: null };
+
+  const now = opts.now;
+  const before = getDriveLease(agentId, now);
+  const acq = acquireDriveLease({ agentId, userId, now });
+  if (acq.ok) {
+    return { allowed: true, mode: before?.holderUserId === userId ? "holder" : "acquired", lease: acq.lease };
+  }
+
+  // Blocked by another live holder. An admin overrides and steals the wheel; everyone else waits.
+  if (resolveViewer(userId)?.role === "admin") {
+    const { lease, previousHolderUserId } = takeOverDriveLease({ agentId, userId, now });
+    const result: DriveArbitration = { allowed: true, mode: "override", lease };
+    if (previousHolderUserId) result.previousHolder = driveHolder(previousHolderUserId);
+    return result;
+  }
+  return { allowed: false, heldBy: driveHolder(acq.lease.holderUserId), lease: acq.lease };
+}
+
+/**
+ * Explicit release of the wheel ("let go"). A holder releases their own lease; an admin may force
+ * a reset (no `userId` guard). Single-user is a no-op. Returns the holder that was released, if any.
+ */
+export function releaseDrive(userId: string, agentId: string, opts: { force?: boolean } = {}): { released: boolean; previousHolder?: DriveHolder } {
+  if (!isMultiUserWorld()) return { released: false };
+  const current = getDriveLease(agentId);
+  const isAdmin = resolveViewer(userId)?.role === "admin";
+  const released = releaseDriveLease(opts.force && isAdmin ? { agentId } : { agentId, userId });
+  return released && current ? { released, previousHolder: driveHolder(current.holderUserId) } : { released };
+}
+
+/** Current driver of an agent (null = free, or single-user world where it is implicitly self). */
+export function currentDriver(agentId: string, opts: { now?: number } = {}): DriveHolder | null {
+  if (!isMultiUserWorld()) return null;
+  const lease = getDriveLease(agentId, opts.now);
+  return lease ? driveHolder(lease.holderUserId) : null;
+}

package/src/db/artifacts.ts

@@ -81,10 +81,10 @@ import type {
 
 // --- Artifacts ---
 
-export const VALID_ARTIFACT_KINDS = new Set<ArtifactKind>(["image", "audio", "video", "document", "archive", "other"]);
+export const VALID_ARTIFACT_KINDS = new Set<ArtifactKind>(["avatar", "image", "audio", "video", "document", "archive", "other"]);
 const VALID_ARTIFACT_VISIBILITIES = new Set<ArtifactVisibility>(["private", "project", "org"]);
 export const VALID_ARTIFACT_SENSITIVITIES = new Set<ArtifactSensitivity>(["public", "normal", "sensitive", "secret"]);
-const VALID_ARTIFACT_LINK_ENTITY_TYPES = new Set<ArtifactLink["entityType"]>(["message", "task", "recipeRun", "recipeStep", "channelEvent"]);
+const VALID_ARTIFACT_LINK_ENTITY_TYPES = new Set<ArtifactLink["entityType"]>(["message", "task", "recipeRun", "recipeStep", "channelEvent", "user"]);
 export const VALID_ARTIFACT_ROLES = new Set<NonNullable<ArtifactLink["role"]>>(["media", "patch", "report", "log", "output", "input"]);
 
 export function artifactId(): string {
@@ -339,4 +339,3 @@ export function linkAttachmentRefs(entityType: ArtifactLink["entityType"], entit
 }
 
 // --- Messages ---
-

package/src/db/drive-leases.ts

@@ -0,0 +1,165 @@
+// Agent drive lease — the soft-lock behind "X is driving this agent" (#388 users wave 5, #394).
+//
+// More than one human can now target the same agent (#392 ownership lets two operators share a
+// worker). This is the per-agent, single-writer hold that keeps two drivers from corrupting one
+// turn: prompt submit, interrupt, and plan-approve/answer all funnel through it so only the lease
+// HOLDER (or an admin override) acts. It is a *leased* hold — refreshed on every drive action and
+// expiring after `CLAIM_LEASE_MS` of silence — so a vanished driver never locks the wheel forever
+// (the same vanish-safety the message claim lease gives, reused here rather than re-invented).
+//
+// This module owns PERSISTENCE only. The arbitration decision (single-user no-op, holder/refresh,
+// admin override, blocked) lives in `src/agent-drive-arbiter.ts`, the one home both the drive
+// routes and the explicit handoff endpoint call.
+//
+// Back-compat: the arbiter never even calls acquire while the relay is single-user, so this table
+// stays empty and the solo operator can never be stranded out of their own agent by an expiry.
+import { CLAIM_LEASE_MS } from "../config";
+import { getDb } from "./connection.ts";
+
+export interface DriveLeaseRecord {
+  agentId: string;
+  /** The relational `users.id` currently holding the wheel. */
+  holderUserId: string;
+  acquiredAt: number;
+  updatedAt: number;
+  expiresAt: number;
+}
+
+interface DriveLeaseRow {
+  agent_id: string;
+  holder_user_id: string;
+  acquired_at: number;
+  updated_at: number;
+  expires_at: number;
+}
+
+function rowToDriveLease(row: DriveLeaseRow): DriveLeaseRecord {
+  return {
+    agentId: row.agent_id,
+    holderUserId: row.holder_user_id,
+    acquiredAt: row.acquired_at,
+    updatedAt: row.updated_at,
+    expiresAt: row.expires_at,
+  };
+}
+
+/**
+ * Single DDL home for the `agent_drive_leases` table (#394). Called from applyMigrations after the
+ * `agents` table exists. ON DELETE CASCADE drops the lease when its agent is removed, so a hold
+ * never outlives the agent (no need to release on shutdown).
+ */
+export function ensureDriveLeaseSchema(): void {
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS agent_drive_leases (
+      agent_id TEXT PRIMARY KEY REFERENCES agents(id) ON DELETE CASCADE,
+      holder_user_id TEXT NOT NULL,
+      acquired_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      expires_at INTEGER NOT NULL
+    )
+  `);
+}
+
+/** The LIVE lease for an agent, or null. Expired rows read as null (lazy expiry — a driver who
+ * went silent past the lease has already let go of the wheel, the next acquire overwrites). */
+export function getDriveLease(agentId: string, now: number = Date.now()): DriveLeaseRecord | null {
+  const row = getDb()
+    .query("SELECT * FROM agent_drive_leases WHERE agent_id = ? AND expires_at > ?")
+    .get(agentId, now) as DriveLeaseRow | null;
+  return row ? rowToDriveLease(row) : null;
+}
+
+/** All live drive leases (for status/observability). */
+export function listDriveLeases(now: number = Date.now()): DriveLeaseRecord[] {
+  return (getDb()
+    .query("SELECT * FROM agent_drive_leases WHERE expires_at > ? ORDER BY acquired_at DESC")
+    .all(now) as DriveLeaseRow[]).map(rowToDriveLease);
+}
+
+/**
+ * Atomically take or refresh the wheel. Wins iff the wheel is free/expired OR already held by this
+ * same user (a refresh, preserving the original `acquired_at`). Loses to a live lease held by
+ * someone else — returned so the caller can say who is driving. Serialized in a transaction so two
+ * concurrent first-drivers can't both win (the concurrent-drive race).
+ */
+export function acquireDriveLease(input: {
+  agentId: string;
+  userId: string;
+  ttlMs?: number;
+  now?: number;
+}): { ok: true; lease: DriveLeaseRecord } | { ok: false; lease: DriveLeaseRecord } {
+  return getDb().transaction(() => {
+    const now = input.now ?? Date.now();
+    const existing = getDriveLease(input.agentId, now);
+    if (existing && existing.holderUserId !== input.userId) return { ok: false as const, lease: existing };
+    return { ok: true as const, lease: writeLease(input.agentId, input.userId, existing, now, input.ttlMs) };
+  })();
+}
+
+/**
+ * Force-grab the wheel regardless of the current holder — the admin override / explicit take-over.
+ * Always succeeds; returns the displaced holder (if any) so the caller can make the handoff
+ * visible. A self take-over is just a refresh (keeps `acquired_at`).
+ */
+export function takeOverDriveLease(input: {
+  agentId: string;
+  userId: string;
+  ttlMs?: number;
+  now?: number;
+}): { lease: DriveLeaseRecord; previousHolderUserId?: string } {
+  return getDb().transaction(() => {
+    const now = input.now ?? Date.now();
+    const existing = getDriveLease(input.agentId, now);
+    const previousHolderUserId = existing && existing.holderUserId !== input.userId ? existing.holderUserId : undefined;
+    const lease = writeLease(input.agentId, input.userId, existing, now, input.ttlMs);
+    return previousHolderUserId ? { lease, previousHolderUserId } : { lease };
+  })();
+}
+
+/** Shared upsert. A same-holder write refreshes the lease while preserving the first `acquired_at`. */
+function writeLease(
+  agentId: string,
+  userId: string,
+  existing: DriveLeaseRecord | null,
+  now: number,
+  ttlMs?: number,
+): DriveLeaseRecord {
+  const acquiredAt = existing?.holderUserId === userId ? existing.acquiredAt : now;
+  const expiresAt = now + (ttlMs ?? CLAIM_LEASE_MS);
+  getDb()
+    .query(
+      `INSERT INTO agent_drive_leases (agent_id, holder_user_id, acquired_at, updated_at, expires_at)
+       VALUES (?, ?, ?, ?, ?)
+       ON CONFLICT(agent_id) DO UPDATE SET
+         holder_user_id = excluded.holder_user_id,
+         acquired_at = excluded.acquired_at,
+         updated_at = excluded.updated_at,
+         expires_at = excluded.expires_at`,
+    )
+    .run(agentId, userId, acquiredAt, now, expiresAt);
+  return getDriveLease(agentId, now)!;
+}
+
+/**
+ * Explicit release ("let go of the wheel"). Guarded by `userId` so a stale release can't drop a
+ * newer holder's lease — only the current holder clears their own. Pass no `userId` to force-clear
+ * (admin reset). Returns whether a row was removed.
+ */
+export function releaseDriveLease(opts: { agentId: string; userId?: string }): boolean {
+  if (opts.userId) {
+    return getDb()
+      .query("DELETE FROM agent_drive_leases WHERE agent_id = ? AND holder_user_id = ?")
+      .run(opts.agentId, opts.userId).changes > 0;
+  }
+  return getDb().query("DELETE FROM agent_drive_leases WHERE agent_id = ?").run(opts.agentId).changes > 0;
+}
+
+/** Sweep expired leases (maintenance tidy-up; correctness already comes from lazy expiry). */
+export function releaseExpiredDriveLeases(now: number = Date.now()): string[] {
+  const expired = getDb()
+    .query("SELECT agent_id FROM agent_drive_leases WHERE expires_at <= ?")
+    .all(now) as Array<{ agent_id: string }>;
+  if (!expired.length) return [];
+  getDb().query("DELETE FROM agent_drive_leases WHERE expires_at <= ?").run(now);
+  return expired.map((r) => r.agent_id);
+}

package/src/db/index.ts

@@ -18,6 +18,7 @@ export * from "./message-reads.ts";
 export * from "./inbox.ts";
 export * from "./users.ts";
 export * from "./agent-ownership.ts";
+export * from "./drive-leases.ts";
 export * from "./activity.ts";
 export * from "./stats.ts";
 export * from "./orchestrators.ts";

package/src/db/migrations.ts

@@ -17,6 +17,7 @@ import { matchAgents } from "../agent-ref";
 import { getDb } from "./connection.ts";
 import { ensureUsersSchema, seedDefaultUser } from "./users.ts";
 import { ensureAgentOwnershipSchema, seedDefaultAgentOwnership } from "./agent-ownership.ts";
+import { ensureDriveLeaseSchema } from "./drive-leases.ts";
 import { ensureContinuationArchiveSearchSchema } from "./continuation-archives.ts";
 import { normalizeReactionEmoji } from "./mappers.ts";
 import { normalizeProviderQuotaAccountKeys } from "./provider-quotas.ts";
@@ -804,6 +805,11 @@ export function applyMigrations(): void {
   // agents are in, so they can be excluded from ownership.
   ensureAgentOwnershipSchema();
 
+  // Per-agent drive lease — the "X is driving this agent" soft-lock (#394). FK-references agents,
+  // so it ensures after the agents table exists. Empty in a single-user world (the arbiter never
+  // writes it), so it adds nothing to the legacy flow.
+  ensureDriveLeaseSchema();
+
   // Built-in agents — registered unconditionally so sends from these ids
   // pass the sendMessage validation. The reaper exempts these by checking
   // meta.builtin (or by id for "user").

package/src/db/users.ts

@@ -51,6 +51,7 @@ function rowToUser(row: UserRow): User {
     status: row.status as UserStatus,
     tenantId: row.tenant_id,
     avatarArtifactId: row.avatar_artifact_id,
+    avatarUrl: row.avatar_artifact_id ? `/users/${encodeURIComponent(row.id)}/avatar` : null,
     createdAt: row.created_at,
     updatedAt: row.updated_at,
   };
@@ -98,6 +99,31 @@ export function createUser(input: CreateUserInput): User {
   return created;
 }
 
+export function updateUserProfile(input: {
+  id: string;
+  displayName?: string;
+  avatarArtifactId?: string | null;
+}): User {
+  const current = getUser(input.id);
+  if (!current) throw new ValidationError("user not found");
+  const updates: string[] = [];
+  const params: Array<string | number | null> = [];
+  if (input.displayName !== undefined) {
+    if (!input.displayName.trim()) throw new ValidationError("displayName required");
+    updates.push("display_name = ?");
+    params.push(input.displayName.trim());
+  }
+  if (input.avatarArtifactId !== undefined) {
+    updates.push("avatar_artifact_id = ?");
+    params.push(input.avatarArtifactId);
+  }
+  if (!updates.length) return current;
+  updates.push("updated_at = ?");
+  params.push(Date.now(), input.id);
+  getDb().query(`UPDATE users SET ${updates.join(", ")} WHERE id = ?`).run(...params);
+  return getUser(input.id)!;
+}
+
 /**
  * Seed the admin-level default user mapped to the existing single human (#393 P0).
  * Idempotent (ON CONFLICT DO NOTHING) so it runs safely on every boot/migration — the

package/src/maintenance/jobs.ts

@@ -13,6 +13,7 @@ import {
   reapStaleAgents,
   reapStaleOrchestrators,
   releaseExpiredClaims,
+  releaseExpiredDriveLeases,
   releaseOrphanedTasks,
   runDbMaintenance,
   sweepArtifacts,
@@ -87,6 +88,16 @@ export const definitions: MaintenanceJobDefinition[] = [
     },
   },
   MERGE_PAUSE_MAINTENANCE_JOB,
+  {
+    id: "drive-lease-expiration",
+    title: "Drive lease expiration",
+    description: "Release expired \"X is driving this agent\" soft-locks (#394).",
+    intervalMs: REAP_INTERVAL_MS,
+    runOnStart: true,
+    handler() {
+      return { releasedDriveLeaseAgentIds: releaseExpiredDriveLeases() };
+    },
+  },
   {
     id: "task-orphan-release",
     title: "Orphaned task release",

package/src/routes/_shared.ts

@@ -205,7 +205,7 @@ export const VALID_AGENT_ACTIONS = ["restart", "shutdown", "reconnect", "compact
 
 export const VALID_TASK_STATUSES = ["open", "claimed", "in_progress", "blocked", "orphaned", "done", "failed", "canceled"] as const;
 
-export const VALID_ARTIFACT_KINDS = ["image", "audio", "video", "document", "archive", "other"] as const;
+export const VALID_ARTIFACT_KINDS = ["avatar", "image", "audio", "video", "document", "archive", "other"] as const;
 
 export const VALID_ARTIFACT_ROLES = ["media", "patch", "report", "log", "output", "input"] as const;
 

package/src/routes/agent-sessions.ts

@@ -1,6 +1,7 @@
 // Auto-split from routes.ts (#299). Domain: agent-sessions.
 import { RELAY_TOKEN_HEADER, isRecord } from "agent-relay-sdk";
-import { VALID_AGENT_ACTIONS, agentControlActionIcon, auditEvent, authAuditMetadata, authorizeAgentRoute, authorizeRoute, cleanAttachmentRefs, dashboardAttribution, emitCommand, error, json, metaString, parseBody, requestUserAddress, spawnRequestId, type AgentControlAction, type Handler } from "./_shared";
+import { VALID_AGENT_ACTIONS, agentControlActionIcon, auditEvent, authAuditMetadata, authorizeAgentRoute, authorizeRoute, canViewAgentRoute, cleanAttachmentRefs, dashboardAttribution, emitCommand, error, json, metaString, parseBody, requestUserAddress, requestUserId, spawnRequestId, type AgentControlAction, type Handler } from "./_shared";
+import { arbitrateDrive, currentDriver, drivingMessage, releaseDrive, type DriveArbitration } from "../agent-drive-arbiter";
 import { ValidationError, getAgent, getAgentTimeline, getOrchestrator, markReady, mergeAgentMeta, sendMessage, withResolvedProvisioning } from "../db";
 import { announcePresence, viewersForAgent } from "../dashboard-presence";
 import { buildManagedSpawnParams } from "../managed-policy";
@@ -19,6 +20,12 @@ import { relayToken } from "../config";
 
 const CLAUDE_RESUME_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
+// 409 when a second human tries to drive an agent another user is already driving (#394). The
+// blocked driver learns who holds the wheel so the UI can show "X is driving" + offer "request".
+function driveBlockedResponse(arb: Extract<DriveArbitration, { allowed: false }>): Response {
+  return json({ error: drivingMessage(arb.heldBy), code: "agent-being-driven", heldBy: arb.heldBy }, 409);
+}
+
 function metaStringArray(meta: Record<string, unknown> | undefined, key: string): string[] {
   const value = meta?.[key];
   return Array.isArray(value) ? value.filter((item): item is string => typeof item === "string" && item.trim().length > 0) : [];
@@ -214,6 +221,13 @@ export const postAgentAction: Handler = async (req, params) => {
     const driveDenied = authorizeAgentRoute(req, agent.id, "drive");
     if (driveDenied) return driveDenied;
     if (!agentCanReceiveControlAction(agent, action)) return error(`agent does not support ${action}`, 400);
+    // #394: interrupt is a turn-drive action — only the lease holder (or an admin override) may cut
+    // the active turn. Lifecycle actions (restart/shutdown/compact/clearContext/resume) stay on the
+    // #392 authz gate only; they manage the agent rather than driving its turn.
+    if (action === "interrupt") {
+      const arb = arbitrateDrive(requestUserId(req), agent.id);
+      if (!arb.allowed) return driveBlockedResponse(arb);
+    }
 
     // Shutdown converges on the shutdownAgent service (epic #342, #347): one #221
     // parent→child gate + canonical orchestrator resolution + payload, shared with the
@@ -319,6 +333,11 @@ export const postAgentPrompt: Handler = async (req, params) => {
     // #392: only a user authorized to drive this agent may prompt it (fail-open single-user).
     const driveDenied = authorizeAgentRoute(req, agent.id, "drive");
     if (driveDenied) return driveDenied;
+    // #394: submitting a prompt takes/refreshes the drive lease. A second human driving the same
+    // agent is blocked here (single-user is a no-op), so two operators can't double-submit into one
+    // turn. The holder's own re-submit just refreshes the lease — busy-state handling is unchanged.
+    const arb = arbitrateDrive(requestUserId(req), agent.id);
+    if (!arb.allowed) return driveBlockedResponse(arb);
     if (agent.status === "offline") return error("agent is offline", 422);
     const denied = authorizeRoute(req, {
       scope: "message:send",
@@ -388,6 +407,10 @@ export const postAgentPermissionDecision: Handler = async (req, params) => {
     // #392: approving/denying a permission is driving the agent (fail-open single-user).
     const driveDenied = authorizeAgentRoute(req, agent.id, "drive");
     if (driveDenied) return driveDenied;
+    // #394: a plan-approve / AskUserQuestion answer drives the turn — only the lease holder (or an
+    // admin override) may answer, so two humans can't race competing decisions into one prompt.
+    const arb = arbitrateDrive(requestUserId(req), agent.id);
+    if (!arb.allowed) return driveBlockedResponse(arb);
     if (!agentIsControlEligible(agent)) return error("agent cannot receive permission decisions", 400);
     const pendingApproval = isRecord(agent.meta?.providerState) && isRecord(agent.meta.providerState.pendingApproval)
       ? agent.meta.providerState.pendingApproval
@@ -470,6 +493,79 @@ export const getAgentPresence: Handler = (_req, params) => {
   return json({ agentId: agent.id, viewers: viewersForAgent(agent.id) });
 };
 
+// Drive lease status (#394): who currently holds the wheel on this agent. `driver: null` means the
+// wheel is free, or the relay is single-user (the lone operator implicitly always holds it).
+export const getAgentDrive: Handler = (req, params) => {
+  const agent = getAgent(params.id!);
+  if (!agent) return error("agent not found", 404);
+  if (!canViewAgentRoute(req, agent.id)) return error("agent not found", 404);
+  const driver = currentDriver(agent.id);
+  const me = requestUserId(req);
+  return json({ agentId: agent.id, driver, isHolder: driver ? driver.userId === me : true });
+};
+
+// Explicit, visible handoff of the wheel (#394): `takeover` (take/refresh the lease — admins steal
+// a held one, others succeed only when it is free), `release` (let go), `request` (ask the current
+// holder to release). Single-user is a no-op throughout, so the solo operator is never affected.
+export const postAgentDrive: Handler = async (req, params) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    if (!isRecord(parsed.body)) return error("action required");
+    const action = optionalEnum(parsed.body.action, "action", ["takeover", "release", "request"] as const);
+    if (!action) return error("action required");
+    const agent = getAgent(params.id!);
+    if (!agent) return error("agent not found", 404);
+    // Driving the wheel requires the same #392 drive authorization the prompt/interrupt routes use.
+    const driveDenied = authorizeAgentRoute(req, agent.id, "drive");
+    if (driveDenied) return driveDenied;
+    const userId = requestUserId(req);
+
+    if (action === "release") {
+      const result = releaseDrive(userId, agent.id);
+      auditDriveEvent(req, agent.id, "release", { released: result.released });
+      return json({ ok: true, action, released: result.released, driver: currentDriver(agent.id) }, 200);
+    }
+
+    if (action === "request") {
+      const holder = currentDriver(agent.id);
+      auditDriveEvent(req, agent.id, "request", { heldBy: holder?.address });
+      return json({ ok: true, action, requested: true, driver: holder }, 202);
+    }
+
+    // takeover
+    const arb = arbitrateDrive(userId, agent.id);
+    if (!arb.allowed) return driveBlockedResponse(arb);
+    auditDriveEvent(req, agent.id, arb.mode === "override" ? "override" : "takeover", {
+      ...(arb.previousHolder ? { from: arb.previousHolder.address } : {}),
+    });
+    return json({ ok: true, action, mode: arb.mode, driver: currentDriver(agent.id) }, 200);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+function auditDriveEvent(req: Request, agentId: string, kind: "takeover" | "override" | "release" | "request", extra: Record<string, unknown>): void {
+  const titles: Record<typeof kind, string> = {
+    takeover: "Agent wheel taken",
+    override: "Agent wheel overridden (admin)",
+    release: "Agent wheel released",
+    request: "Agent wheel requested",
+  };
+  auditEvent({
+    clientId: `server-agent-${agentId}-drive-${kind}-${Date.now()}`,
+    kind: "state",
+    title: titles[kind],
+    body: kind,
+    meta: agentId,
+    icon: kind === "release" ? "ti-steering-wheel-off" : "ti-steering-wheel",
+    view: "chat",
+    agentId,
+    metadata: { drive: kind, requestedByUser: requestUserAddress(req), ...extra, ...authAuditMetadata(req) },
+  });
+}
+
 export const postAgentTerminalSession: Handler = async (req, params) => {
   try {
     const agent = getAgent(params.id!);

package/src/routes/artifacts.ts

@@ -18,7 +18,7 @@ function artifactActor(req: Request): string {
   return "server";
 }
 
-function inferArtifactKind(mediaType: string, filename?: string): ArtifactKind {
+export function inferArtifactKind(mediaType: string, filename?: string): ArtifactKind {
   const lowerName = filename?.toLowerCase() ?? "";
   if (mediaType.startsWith("image/")) return "image";
   if (mediaType.startsWith("audio/")) return "audio";
@@ -32,10 +32,14 @@ function inferArtifactKind(mediaType: string, filename?: string): ArtifactKind {
   return "other";
 }
 
-function sniffMediaType(bytes: Uint8Array, hinted?: string, filename?: string): string {
+export function sniffMediaType(bytes: Uint8Array, hinted?: string, filename?: string): string {
   if (bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) return "image/jpeg";
   if (bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e && bytes[3] === 0x47) return "image/png";
   if (bytes[0] === 0x47 && bytes[1] === 0x49 && bytes[2] === 0x46) return "image/gif";
+  if (
+    bytes[0] === 0x52 && bytes[1] === 0x49 && bytes[2] === 0x46 && bytes[3] === 0x46 &&
+    bytes[8] === 0x57 && bytes[9] === 0x45 && bytes[10] === 0x42 && bytes[11] === 0x50
+  ) return "image/webp";
   if (bytes[0] === 0x25 && bytes[1] === 0x50 && bytes[2] === 0x44 && bytes[3] === 0x46) return "application/pdf";
   if (bytes[0] === 0x50 && bytes[1] === 0x4b) return "application/zip";
   const lower = filename?.toLowerCase() ?? "";
@@ -52,7 +56,7 @@ function safeDispositionFilename(filename: string | undefined): string {
   return cleaned || "artifact";
 }
 
-function artifactContentDisposition(filename: string | undefined, mediaType: string): string {
+export function artifactContentDisposition(filename: string | undefined, mediaType: string): string {
   const disposition = mediaType.startsWith("image/") && mediaType !== "image/svg+xml" ? "inline" : "attachment";
   return `${disposition}; filename="${safeDispositionFilename(filename)}"`;
 }

package/src/routes/index.ts

@@ -1,8 +1,8 @@
 // Auto-split from routes.ts (#299). Router: route table + matchRoute dispatch.
 import { deleteAgentActiveMemories, deleteAgentById, findAgents, getAgentActiveMemories, getAgentById, getAgentChatHistory, getAgentContextSnapshots, getAgentQuotaSnapshots, getAgentReplyObligations, getAgentTimelineRoute, getAgents, getMessageArtifactsRoute, getTaskArtifactsRoute, patchAgentLabel, patchAgentReady, patchAgentStatus, patchAgentTags, postHeartbeat } from "./agents";
 import { deleteAgentProfileRoute, getAgentProfileRoute, getAgentProfilesRoute, putAgentProfileRoute } from "./agent-profiles";
-import { deleteAgentTerminalSession, getAgentPresence, postAgentAction, postAgentPermissionDecision, postAgentPresence, postAgentPrompt, postAgentTerminalSession } from "./agent-sessions";
-import { getUsers } from "./users";
+import { deleteAgentTerminalSession, getAgentDrive, getAgentPresence, postAgentAction, postAgentDrive, postAgentPermissionDecision, postAgentPresence, postAgentPrompt, postAgentTerminalSession } from "./agent-sessions";
+import { deleteMyAvatar, deleteUserAvatarById, getMe, getUserAvatar, getUsers, headUserAvatar, patchMe, patchUserById, postMyAvatar, postUserAvatarById } from "./users";
 import { deleteArtifactById, getArtifactById, getArtifactContent, getArtifacts, headArtifactContent, postArtifact } from "./artifacts";
 import { deleteAutomationById, getAutomationById, getAutomationRuns, getAutomations, patchAutomation, postAutomation, postAutomationRun } from "./automations";
 import { deleteCommandById, deleteProviderModelRoute, getProviderConfigRoute, getProviderConfigsRoute, getProvidersRoute, patchProviderModelRoute, postProviderConfigTestRoute, putProviderConfigRoute, putProviderModelRoute } from "./provider-config";
@@ -87,6 +87,15 @@ const routes: Route[] = [
   route("DELETE", "/api/memories/:id", deleteMemoryRoute),
 
   route("GET", "/api/users", getUsers),
+  route("GET", "/api/users/me", getMe),
+  route("PATCH", "/api/users/me", patchMe),
+  route("POST", "/api/users/me/avatar", postMyAvatar),
+  route("DELETE", "/api/users/me/avatar", deleteMyAvatar),
+  route("GET", "/api/users/:id/avatar", getUserAvatar),
+  route("HEAD", "/api/users/:id/avatar", headUserAvatar),
+  route("PATCH", "/api/users/:id", patchUserById),
+  route("POST", "/api/users/:id/avatar", postUserAvatarById),
+  route("DELETE", "/api/users/:id/avatar", deleteUserAvatarById),
 
   route("POST", "/api/agents", postAgent),
   route("POST", "/api/agents/spawn", postAgentSpawn),
@@ -116,6 +125,8 @@ const routes: Route[] = [
   route("POST", "/api/agents/:id/permission-decision", postAgentPermissionDecision),
   route("GET", "/api/agents/:id/presence", getAgentPresence),
   route("POST", "/api/agents/:id/presence", postAgentPresence),
+  route("GET", "/api/agents/:id/drive", getAgentDrive),
+  route("POST", "/api/agents/:id/drive", postAgentDrive),
   route("POST", "/api/agents/:id/terminal-session", postAgentTerminalSession),
   route("DELETE", "/api/agents/:id/terminal-session/:session", deleteAgentTerminalSession),
   route("DELETE", "/api/agents/:id", deleteAgentById),