@controlflow-ai/daemon 0.1.2 → 0.1.3

package/src/local-api.ts

@@ -1,16 +1,18 @@
-import { LockClient } from './client.js';
-import { assertLocalRequest, assertLoopbackBindHost } from './local-auth.js';
+import { LockClient, type CreateHandoffRoomRequest } from './client.js';
+import { authenticateLocalRequest, assertLoopbackBindHost, type LocalApiPrincipal, type RuntimeTokenLookup } from './local-auth.js';
 import { failure, HttpError, json, numberParam, readJson, stringParam } from './http.js';
+import { ALL_AGENTS_MENTION } from './db.js';
 import { readdir, stat } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { dirname, isAbsolute, join, normalize } from 'node:path';
-import type { RemoteFileEntry, RemoteFileList, RunAction } from './types.js';
+import type { HeldDraftStatus, MessageFreshnessInput, RemoteFileEntry, RemoteFileList, RoomParticipant, RoomReminderStatus, RoomTaskStatus, RunAction } from './types.js';
 
 interface LocalApiOptions {
   serverUrl: string;
   token?: string;
-  controlToken?: string;
-  daemonAuth?: ConstructorParameters<typeof LockClient>[1];
+  controlToken?: string | (() => string | undefined);
+  daemonAuth?: ConstructorParameters<typeof LockClient>[1] | (() => ConstructorParameters<typeof LockClient>[1]);
+  runtimeTokenLookup?: RuntimeTokenLookup;
 }
 
 interface ArtifactBody {
@@ -36,12 +38,324 @@ interface SendBody {
   type?: 'message' | 'system';
   idempotency_key?: string | null;
   mentions?: string[];
+  mention_lint?: 'strict' | 'literal' | 'infer';
+  attachments?: Array<{
+    kind?: 'image' | 'file';
+    mime_type?: string;
+    filename?: string | null;
+    content_base64?: string;
+  }>;
+  messages?: Array<{
+    parent_id?: number;
+    channel_id?: string | null;
+    recipient?: string | null;
+    content?: string;
+    type?: 'message' | 'system';
+    idempotency_key?: string | null;
+    mentions?: string[];
+    attachments?: Array<{
+      kind?: 'image' | 'file';
+      mime_type?: string;
+      filename?: string | null;
+      content_base64?: string;
+    }>;
+  }>;
+  freshness?: MessageFreshnessInput;
+}
+
+interface MentionLintResult {
+  missing_mentions: string[];
+  available_mentions: string[];
+  message: string;
+}
+
+function normalizeSendAttachments(attachments: SendBody['attachments']) {
+  return attachments?.map((attachment) => ({
+    kind: attachment.kind === 'image' ? 'image' as const : 'file' as const,
+    mime_type: attachment.mime_type ?? '',
+    filename: attachment.filename,
+    content_base64: attachment.content_base64 ?? '',
+  }));
+}
+
+function normalizeMentionValue(value: unknown): string {
+  if (typeof value !== 'string') return '';
+  const mention = value.trim().replace(/^@/, '');
+  const lower = mention.toLowerCase();
+  if (lower === 'all' || lower === '_all' || mention === '所有人' || mention === ALL_AGENTS_MENTION) return ALL_AGENTS_MENTION;
+  return mention;
+}
+
+function mentionBoundaryChar(value: string | undefined): boolean {
+  if (!value) return true;
+  return !/[\p{Letter}\p{Number}._-]/u.test(value);
+}
+
+function textMentionsKey(content: string, key: string): boolean {
+  if (!key) return false;
+  let start = 0;
+  const needle = `@${key}`;
+  while (start < content.length) {
+    const index = content.indexOf(needle, start);
+    if (index < 0) return false;
+    const previous = index > 0 ? content[index - 1] : undefined;
+    const next = content[index + needle.length];
+    if (mentionBoundaryChar(previous) && mentionBoundaryChar(next)) return true;
+    start = index + 1;
+  }
+  return false;
+}
+
+function textMentionsAllAgents(content: string): boolean {
+  return /(^|[^\p{Letter}\p{Number}._-])@(?:all|_all|所有人)(?=$|[^\p{Letter}\p{Number}._-])/iu.test(content);
+}
+
+function lintAgentTextMentions(input: {
+  sender: string;
+  items: Array<{ content?: string; mentions?: string[] }>;
+  participants: RoomParticipant[];
+}): MentionLintResult | null {
+  const agentKeys = input.participants
+    .filter((participant) => participant.kind === 'agent' && participant.status === 'active')
+    .map((participant) => participant.participant_id)
+    .filter(Boolean);
+  if (!agentKeys.includes(input.sender)) return null;
+  const available = agentKeys;
+  const missing = new Set<string>();
+
+  for (const item of input.items) {
+    const content = item.content ?? '';
+    if (!content) continue;
+    const explicitMentions = new Set((item.mentions ?? []).map(normalizeMentionValue).filter(Boolean));
+    if (textMentionsAllAgents(content) && !explicitMentions.has(ALL_AGENTS_MENTION)) {
+      missing.add(ALL_AGENTS_MENTION);
+    }
+    for (const key of agentKeys) {
+      if (key === input.sender) continue;
+      if (explicitMentions.has(key)) continue;
+      if (textMentionsKey(content, key)) missing.add(key);
+    }
+  }
+
+  if (missing.size === 0) return null;
+  const display = [...missing].map((mention) => mention === ALL_AGENTS_MENTION ? 'all' : mention);
+  return {
+    missing_mentions: [...missing],
+    available_mentions: available,
+    message: `Message text contains ${display.map((mention) => `@${mention}`).join(', ')} but no matching --mention flag was provided.`,
+  };
+}
+
+async function lintLocalSendMentions(client: LockClient, principal: LocalApiPrincipal, body: SendBody): Promise<MentionLintResult | null> {
+  if (body.mention_lint === 'literal') return null;
+  const sender = body.sender?.trim() ?? '';
+  if (!sender) return null;
+  const roomRef = principal.kind === 'agent'
+    ? principal.chatId
+    : body.room_id ?? body.chat_id ?? body.room ?? body.chat;
+  if (!roomRef) return null;
+  let members: Awaited<ReturnType<LockClient['listRoomMembers']>>;
+  try {
+    members = await client.listRoomMembers(roomRef);
+  } catch (error) {
+    if (error instanceof HttpError && error.code === 'ROOM_NOT_FOUND') return null;
+    throw error;
+  }
+  const items = body.messages?.length
+    ? body.messages.map((message) => ({
+      content: message.content ?? '',
+      mentions: [...(body.mentions ?? []), ...(message.mentions ?? [])],
+    }))
+    : [{ content: body.content ?? '', mentions: body.mentions ?? [] }];
+  return lintAgentTextMentions({ sender, items, participants: members.participants });
+}
+
+function appendInferredMentions(base: string[] | undefined, missing: string[]): string[] {
+  const out: string[] = [];
+  const seen = new Set<string>();
+  for (const value of [...(base ?? []), ...missing]) {
+    const normalized = normalizeMentionValue(value);
+    if (!normalized || seen.has(normalized)) continue;
+    seen.add(normalized);
+    out.push(normalized);
+  }
+  return out;
+}
+
+interface CreateRoomTasksBody {
+  title?: string;
+  tasks?: Array<{ title?: string }>;
+  created_by?: string | null;
+  source_message_id?: number | null;
+}
+
+interface ClaimRoomTaskBody {
+  assignee?: string;
+}
+
+interface UpdateRoomTaskBody {
+  status?: RoomTaskStatus;
+}
+
+interface CreateRoomReminderBody {
+  msg_id?: number;
+  title?: string;
+  created_by?: string | null;
+  fire_at?: string | null;
+  delay_seconds?: number | null;
+  repeat?: string | null;
+}
+
+interface CreateRoomSavedMessageBody {
+  msg_id?: number;
+  source_message_id?: number;
+  saved_by?: string | null;
+  note?: string | null;
+}
+
+interface LocalHandoffRoomBody extends Partial<CreateHandoffRoomRequest> {}
+
+interface ReviseHeldDraftBody {
+  content?: string;
 }
 
 function routeNotFound(): Response {
   return Response.json({ ok: false, code: 'NOT_FOUND', message: 'not found' }, { status: 404 });
 }
 
+function requireDaemonPrincipal(principal: LocalApiPrincipal): void {
+  if (principal.kind !== 'daemon') {
+    throw new HttpError(403, 'LOCAL_AGENT_FORBIDDEN', 'agent-scoped token is not allowed for this local API route');
+  }
+}
+
+function requireMessageWritePrincipal(principal: LocalApiPrincipal, body: SendBody): void {
+  if (principal.kind === 'daemon') return;
+  const sender = body.sender?.trim();
+  const chatId = body.room_id ?? body.chat_id;
+  if (sender !== principal.agent) {
+    throw new HttpError(403, 'LOCAL_AGENT_FORBIDDEN', 'agent-scoped token can only send as its own agent');
+  }
+  if (!chatId || chatId !== principal.chatId) {
+    throw new HttpError(403, 'LOCAL_AGENT_FORBIDDEN', 'agent-scoped token can only send to its active room by chat_id');
+  }
+}
+
+function requireAgentRoomScope(principal: LocalApiPrincipal, roomRef: string): void {
+  if (principal.kind === 'daemon') return;
+  if (roomRef !== principal.chatId) {
+    throw new HttpError(403, 'LOCAL_AGENT_FORBIDDEN', 'agent-scoped token can only manage tasks in its active room by chat_id');
+  }
+}
+
+function requireAgentHandoffCreate(principal: LocalApiPrincipal, body: LocalHandoffRoomBody): void {
+  if (principal.kind === 'daemon') return;
+  if ((body.actor?.trim() || '') !== principal.agent) {
+    throw new HttpError(403, 'LOCAL_AGENT_FORBIDDEN', 'agent-scoped token can only create handoff rooms as its own agent');
+  }
+  if ((body.source_room_id?.trim() || '') !== principal.chatId) {
+    throw new HttpError(403, 'LOCAL_AGENT_FORBIDDEN', 'agent-scoped token can only create handoff rooms from its active room');
+  }
+}
+
+function requireAgentTaskCreator(principal: LocalApiPrincipal, roomRef: string, body: CreateRoomTasksBody): void {
+  requireAgentRoomScope(principal, roomRef);
+  if (principal.kind === 'daemon') return;
+  if ((body.created_by?.trim() || '') !== principal.agent) {
+    throw new HttpError(403, 'LOCAL_AGENT_FORBIDDEN', 'agent-scoped token can only create tasks as its own agent');
+  }
+}
+
+function requireAgentTaskAssignee(principal: LocalApiPrincipal, roomRef: string, body: ClaimRoomTaskBody): void {
+  requireAgentRoomScope(principal, roomRef);
+  if (principal.kind === 'daemon') return;
+  if ((body.assignee?.trim() || '') !== principal.agent) {
+    throw new HttpError(403, 'LOCAL_AGENT_FORBIDDEN', 'agent-scoped token can only claim tasks as its own agent');
+  }
+}
+
+function requireAgentReminderCreator(principal: LocalApiPrincipal, body: CreateRoomReminderBody): void {
+  if (principal.kind === 'daemon') return;
+  if ((body.created_by?.trim() || '') !== principal.agent) {
+    throw new HttpError(403, 'LOCAL_AGENT_FORBIDDEN', 'agent-scoped token can only schedule reminders as its own agent');
+  }
+}
+
+async function requireAgentReminderSource(client: LockClient, principal: LocalApiPrincipal, sourceMessageId: number): Promise<void> {
+  if (principal.kind === 'daemon') return;
+  const message = await client.getMessage(sourceMessageId, principal.agent);
+  if (message.chat_id !== principal.chatId) {
+    throw new HttpError(403, 'LOCAL_AGENT_FORBIDDEN', 'agent-scoped token can only schedule reminders from its active room');
+  }
+}
+
+async function requireAgentReminderAccess(client: LockClient, principal: LocalApiPrincipal, reminderId: string): Promise<void> {
+  if (principal.kind === 'daemon') return;
+  const reminders = await client.listReminders({
+    status: 'all',
+    created_by: principal.agent,
+    room_id: principal.chatId,
+    limit: 500,
+  });
+  if (!reminders.some((reminder) => reminder.id === reminderId)) {
+    throw new HttpError(403, 'LOCAL_AGENT_FORBIDDEN', 'agent-scoped token can only cancel reminders it scheduled in its active room');
+  }
+}
+
+function requireAgentSavedMessageCreator(principal: LocalApiPrincipal, body: CreateRoomSavedMessageBody): void {
+  if (principal.kind === 'daemon') return;
+  if ((body.saved_by?.trim() || '') !== principal.agent) {
+    throw new HttpError(403, 'LOCAL_AGENT_FORBIDDEN', 'agent-scoped token can only save messages as its own agent');
+  }
+}
+
+async function requireAgentSavedMessageSource(client: LockClient, principal: LocalApiPrincipal, sourceMessageId: number): Promise<void> {
+  if (principal.kind === 'daemon') return;
+  const message = await client.getMessage(sourceMessageId, principal.agent);
+  if (message.chat_id !== principal.chatId) {
+    throw new HttpError(403, 'LOCAL_AGENT_FORBIDDEN', 'agent-scoped token can only save messages from its active room');
+  }
+}
+
+async function requireAgentSavedMessageAccess(client: LockClient, principal: LocalApiPrincipal, savedMessageId: string): Promise<void> {
+  if (principal.kind === 'daemon') return;
+  const savedMessages = await client.listSavedMessages({
+    saved_by: principal.agent,
+    room_id: principal.chatId,
+    limit: 500,
+  });
+  if (!savedMessages.some((savedMessage) => savedMessage.id === savedMessageId)) {
+    throw new HttpError(403, 'LOCAL_AGENT_FORBIDDEN', 'agent-scoped token can only remove messages it saved in its active room');
+  }
+}
+
+async function requireAgentHeldDraftAccess(client: LockClient, principal: LocalApiPrincipal, draftId: string): Promise<void> {
+  if (principal.kind === 'daemon') return;
+  const drafts = await client.listHeldDrafts({
+    agent: principal.agent,
+    room_id: principal.chatId,
+    status: 'held',
+    limit: 500,
+  });
+  if (!drafts.some((draft) => draft.id === draftId)) {
+    throw new HttpError(403, 'LOCAL_AGENT_FORBIDDEN', 'agent-scoped token can only manage held drafts it owns in its active room');
+  }
+}
+
+async function listRoomsForPrincipal(client: LockClient, principal: LocalApiPrincipal) {
+  return principal.kind === 'agent' ? client.listRooms(principal.agent) : client.listRooms();
+}
+
+async function resolveRoomForPrincipal(client: LockClient, principal: LocalApiPrincipal, roomRef: string): Promise<string> {
+  if (principal.kind === 'daemon') return roomRef;
+  const rooms = await listRoomsForPrincipal(client, principal);
+  const room = rooms.find((candidate) => candidate.id === roomRef || candidate.name === roomRef);
+  if (!room) {
+    throw new HttpError(403, 'LOCAL_AGENT_FORBIDDEN', 'agent-scoped token can only read rooms it can participate in');
+  }
+  return room.id;
+}
+
 async function canReadDirectory(path: string): Promise<boolean> {
   try {
     await readdir(path);
@@ -99,8 +413,10 @@ async function listLocalFiles(input: { path?: string; showHidden?: boolean }): P
 
 export async function localRoute(request: Request, options: LocalApiOptions): Promise<Response> {
   try {
-    assertLocalRequest(request, [options.token, options.controlToken].filter((item): item is string => Boolean(item)));
-    const client = new LockClient(options.serverUrl, options.daemonAuth ?? null);
+    const controlToken = typeof options.controlToken === 'function' ? options.controlToken() : options.controlToken;
+    const principal = authenticateLocalRequest(request, [options.token, controlToken].filter((item): item is string => Boolean(item)), options.runtimeTokenLookup);
+    const daemonAuth = typeof options.daemonAuth === 'function' ? options.daemonAuth() : options.daemonAuth;
+    const client = new LockClient(options.serverUrl, daemonAuth ?? null);
     const url = new URL(request.url);
     const { pathname } = url;
 
@@ -109,6 +425,7 @@ export async function localRoute(request: Request, options: LocalApiOptions): Pr
     }
 
     if (request.method === 'GET' && pathname === '/local/files') {
+      requireDaemonPrincipal(principal);
       const files = await listLocalFiles({
         path: stringParam(url, 'path'),
         showHidden: url.searchParams.get('show_hidden') === 'true',
@@ -117,52 +434,254 @@ export async function localRoute(request: Request, options: LocalApiOptions): Pr
     }
 
     if (request.method === 'GET' && pathname === '/local/chats') {
+      requireDaemonPrincipal(principal);
       return json({ chats: await client.listChats() });
     }
 
     if (request.method === 'GET' && pathname === '/local/rooms') {
-      return json({ rooms: await client.listRooms() });
+      return json({ rooms: await listRoomsForPrincipal(client, principal) });
+    }
+
+    if (request.method === 'POST' && pathname === '/local/rooms/handoff') {
+      const body = await readJson<LocalHandoffRoomBody>(request);
+      requireAgentHandoffCreate(principal, body);
+      return json(await client.createHandoffRoom({
+        source_room_id: body.source_room_id ?? '',
+        source_message_id: body.source_message_id,
+        actor: body.actor ?? '',
+        purpose: body.purpose ?? '',
+        name: body.name ?? '',
+        team: body.team,
+        handoff_content: body.handoff_content,
+      }), 201);
     }
 
     const roomMembersMatch = pathname.match(/^\/local\/rooms\/([^/]+)\/members$/);
     if (request.method === 'GET' && roomMembersMatch) {
-      return json(await client.listRoomMembers(decodeURIComponent(roomMembersMatch[1]!)));
+      const roomRef = await resolveRoomForPrincipal(client, principal, decodeURIComponent(roomMembersMatch[1]!));
+      return json(await client.listRoomMembers(roomRef));
     }
 
 
     const roomInviteMatch = pathname.match(/^\/local\/rooms\/([^/]+)\/agents$/);
     if (request.method === 'POST' && roomInviteMatch) {
+      requireDaemonPrincipal(principal);
       const body = await readJson<{ agent?: string; mode?: string }>(request);
       return json(await client.inviteAgentToRoom(decodeURIComponent(roomInviteMatch[1]!), { agent: body.agent ?? '', mode: body.mode as never }), 201);
     }
 
     const roomTopicMatch = pathname.match(/^\/local\/rooms\/([^/]+)\/topics$/);
     if (request.method === 'POST' && roomTopicMatch) {
+      requireDaemonPrincipal(principal);
       const body = await readJson<{ name?: string; created_by?: string | null }>(request);
       if (!body.name?.trim()) throw new HttpError(400, 'MISSING_TOPIC_NAME', 'name is required');
       const channel = await client.createTopic(decodeURIComponent(roomTopicMatch[1]!), { name: body.name, created_by: body.created_by });
       return json({ channel }, 201);
     }
 
+    const roomTasksMatch = pathname.match(/^\/local\/rooms\/([^/]+)\/tasks$/);
+    if (request.method === 'GET' && roomTasksMatch) {
+      const roomRef = decodeURIComponent(roomTasksMatch[1]!);
+      requireAgentRoomScope(principal, roomRef);
+      return json({
+        tasks: await client.listRoomTasks(
+          roomRef,
+          (stringParam(url, 'status') ?? 'all') as RoomTaskStatus | 'all',
+          numberParam(url, 'limit', 50),
+        ),
+      });
+    }
+
+    if (request.method === 'POST' && roomTasksMatch) {
+      const roomRef = decodeURIComponent(roomTasksMatch[1]!);
+      const body = await readJson<CreateRoomTasksBody>(request);
+      requireAgentTaskCreator(principal, roomRef, body);
+      return json({
+        tasks: await client.createRoomTasks(roomRef, {
+          title: body.title,
+          tasks: body.tasks?.map((task) => ({ title: task.title ?? '' })),
+          created_by: body.created_by,
+          source_message_id: body.source_message_id,
+        }),
+      }, 201);
+    }
+
+    const roomTaskClaimMatch = pathname.match(/^\/local\/rooms\/([^/]+)\/tasks\/([^/]+)\/claim$/);
+    if (request.method === 'POST' && roomTaskClaimMatch) {
+      const roomRef = decodeURIComponent(roomTaskClaimMatch[1]!);
+      const body = await readJson<ClaimRoomTaskBody>(request);
+      requireAgentTaskAssignee(principal, roomRef, body);
+      return json({ task: await client.claimRoomTask(roomRef, Number(roomTaskClaimMatch[2]), { assignee: body.assignee ?? '' }) });
+    }
+
+    const roomTaskUnclaimMatch = pathname.match(/^\/local\/rooms\/([^/]+)\/tasks\/([^/]+)\/unclaim$/);
+    if (request.method === 'POST' && roomTaskUnclaimMatch) {
+      const roomRef = decodeURIComponent(roomTaskUnclaimMatch[1]!);
+      requireAgentRoomScope(principal, roomRef);
+      return json({ task: await client.unclaimRoomTask(roomRef, Number(roomTaskUnclaimMatch[2])) });
+    }
+
+    const roomTaskStatusMatch = pathname.match(/^\/local\/rooms\/([^/]+)\/tasks\/([^/]+)$/);
+    if (request.method === 'PATCH' && roomTaskStatusMatch) {
+      const roomRef = decodeURIComponent(roomTaskStatusMatch[1]!);
+      requireAgentRoomScope(principal, roomRef);
+      const body = await readJson<UpdateRoomTaskBody>(request);
+      return json({ task: await client.updateRoomTaskStatus(roomRef, Number(roomTaskStatusMatch[2]), body.status as RoomTaskStatus) });
+    }
+
+    const roomAgentRestartMatch = pathname.match(/^\/local\/rooms\/([^/]+)\/agents\/([^/]+)\/restart$/);
+    if (request.method === 'POST' && roomAgentRestartMatch) {
+      const roomRef = decodeURIComponent(roomAgentRestartMatch[1]!);
+      requireAgentRoomScope(principal, roomRef);
+      const restartAgent = decodeURIComponent(roomAgentRestartMatch[2]!);
+      if (principal.kind === 'agent' && restartAgent !== principal.agent) {
+        throw new HttpError(403, 'LOCAL_AGENT_FORBIDDEN', 'agent-scoped token can only restart its own runtime');
+      }
+      return json({ run: await client.restartRoomAgent(roomRef, restartAgent) });
+    }
+
+    if (request.method === 'GET' && pathname === '/local/reminders') {
+      return json({
+        reminders: await client.listReminders({
+          status: (stringParam(url, 'status') ?? 'scheduled') as RoomReminderStatus | 'all',
+          created_by: principal.kind === 'agent' ? principal.agent : stringParam(url, 'created_by'),
+          room_id: principal.kind === 'agent'
+            ? principal.chatId
+            : stringParam(url, 'room_id') ?? stringParam(url, 'chat_id'),
+          limit: numberParam(url, 'limit', 50),
+        }),
+      });
+    }
+
+    if (request.method === 'POST' && pathname === '/local/reminders') {
+      const body = await readJson<CreateRoomReminderBody>(request);
+      requireAgentReminderCreator(principal, body);
+      const sourceMessageId = Number(body.msg_id);
+      if (!Number.isInteger(sourceMessageId) || sourceMessageId < 1) {
+        throw new HttpError(400, 'INVALID_SOURCE_MESSAGE_ID', 'msg_id must be a positive integer');
+      }
+      await requireAgentReminderSource(client, principal, sourceMessageId);
+      return json({
+        reminder: await client.scheduleReminder({
+          msg_id: sourceMessageId,
+          title: body.title ?? '',
+          created_by: body.created_by,
+          fire_at: body.fire_at,
+          delay_seconds: body.delay_seconds,
+          repeat: body.repeat,
+        }),
+      }, 201);
+    }
+
+    const reminderCancelMatch = pathname.match(/^\/local\/reminders\/([^/]+)\/cancel$/);
+    if (request.method === 'POST' && reminderCancelMatch) {
+      const reminderId = decodeURIComponent(reminderCancelMatch[1]!);
+      await requireAgentReminderAccess(client, principal, reminderId);
+      return json({ reminder: await client.cancelReminder(reminderId) });
+    }
+
+    if (request.method === 'GET' && pathname === '/local/saved-messages') {
+      return json({
+        saved_messages: await client.listSavedMessages({
+          saved_by: principal.kind === 'agent' ? principal.agent : stringParam(url, 'saved_by'),
+          room_id: principal.kind === 'agent'
+            ? principal.chatId
+            : stringParam(url, 'room_id') ?? stringParam(url, 'chat_id'),
+          limit: numberParam(url, 'limit', 50),
+        }),
+      });
+    }
+
+    if (request.method === 'POST' && pathname === '/local/saved-messages') {
+      const body = await readJson<CreateRoomSavedMessageBody>(request);
+      requireAgentSavedMessageCreator(principal, body);
+      const sourceMessageId = Number(body.msg_id ?? body.source_message_id);
+      if (!Number.isInteger(sourceMessageId) || sourceMessageId < 1) {
+        throw new HttpError(400, 'INVALID_SOURCE_MESSAGE_ID', 'msg_id must be a positive integer');
+      }
+      await requireAgentSavedMessageSource(client, principal, sourceMessageId);
+      return json({
+        saved_message: await client.saveMessage({
+          msg_id: sourceMessageId,
+          saved_by: body.saved_by ?? '',
+          note: body.note,
+        }),
+      }, 201);
+    }
+
+    const savedMessageDeleteMatch = pathname.match(/^\/local\/saved-messages\/([^/]+)\/delete$/);
+    if (request.method === 'POST' && savedMessageDeleteMatch) {
+      const savedMessageId = decodeURIComponent(savedMessageDeleteMatch[1]!);
+      await requireAgentSavedMessageAccess(client, principal, savedMessageId);
+      return json({ saved_message: await client.removeSavedMessage(savedMessageId) });
+    }
+
+    if (request.method === 'GET' && pathname === '/local/held-drafts') {
+      const agent = principal.kind === 'agent'
+        ? principal.agent
+        : stringParam(url, 'agent') ?? stringParam(url, 'from') ?? stringParam(url, 'sender');
+      if (!agent) throw new HttpError(400, 'MISSING_AGENT', 'held draft list requires agent');
+      return json({
+        drafts: await client.listHeldDrafts({
+          agent,
+          room_id: principal.kind === 'agent'
+            ? principal.chatId
+            : stringParam(url, 'room_id') ?? stringParam(url, 'chat_id'),
+          status: (stringParam(url, 'status') ?? 'held') as HeldDraftStatus | 'all',
+          limit: numberParam(url, 'limit', 50),
+        }),
+      });
+    }
+
+    const heldDraftActionMatch = pathname.match(/^\/local\/held-drafts\/([^/]+)\/(abandon|stay-silent|send-anyway|revise)$/);
+    if (request.method === 'POST' && heldDraftActionMatch) {
+      const draftId = decodeURIComponent(heldDraftActionMatch[1]!);
+      const action = heldDraftActionMatch[2]!;
+      await requireAgentHeldDraftAccess(client, principal, draftId);
+      if (action === 'revise') {
+        const body = await readJson<ReviseHeldDraftBody>(request);
+        return json(await client.reviseHeldDraft(draftId, body.content ?? ''));
+      }
+      if (action === 'send-anyway') {
+        return json(await client.sendHeldDraftAnyway(draftId));
+      }
+      return json(await client.abandonHeldDraft(draftId));
+    }
+
     if (request.method === 'GET' && pathname === '/local/messages') {
       const params = new URLSearchParams();
       for (const key of ['chat', 'room', 'chat_id', 'room_id', 'parent_id', 'channel_id', 'after', 'limit', 'q']) {
         const value = url.searchParams.get(key);
         if (value !== null) params.set(key, value);
       }
+      if (principal.kind === 'agent') {
+        const chatId = params.get('chat_id') ?? params.get('room_id');
+        const chat = params.get('chat') ?? params.get('room');
+        if (!chatId && !chat) throw new HttpError(400, 'MISSING_ROOM_SCOPE', 'agent-scoped message reads require chat_id or chat');
+        params.set('agent_scope', principal.agent);
+      }
       return json({ messages: await client.getMessages(params) });
     }
 
     const messageMatch = pathname.match(/^\/local\/messages\/(\d+)$/);
     if (request.method === 'GET' && messageMatch) {
-      return json({ message: await client.getMessage(Number(messageMatch[1])) });
+      return json({ message: await client.getMessage(Number(messageMatch[1]), principal.kind === 'agent' ? principal.agent : undefined) });
     }
 
     if (request.method === 'POST' && pathname === '/local/messages') {
       const body = await readJson<SendBody>(request);
+      requireMessageWritePrincipal(principal, body);
       if (!body.sender?.trim()) throw new HttpError(400, 'MISSING_SENDER', 'sender is required');
-      if (!body.content?.trim()) throw new HttpError(400, 'MISSING_CONTENT', 'content is required');
-      const message = await client.sendMessage({
+      const hasContent = body.content?.trim()
+        || body.attachments?.length
+        || body.messages?.some((message) => message.content?.trim() || message.attachments?.length);
+      if (!hasContent) throw new HttpError(400, 'MISSING_CONTENT', 'content or attachments are required');
+      const mentionLint = await lintLocalSendMentions(client, principal, body);
+      if (mentionLint && body.mention_lint !== 'infer') {
+        return json({ mention_lint: mentionLint });
+      }
+      const inferredMentions = mentionLint?.missing_mentions ?? [];
+      const result = await client.sendMessageResult({
         chat: body.room ?? body.chat,
         room: body.room,
         chat_id: body.room_id ?? body.chat_id,
@@ -171,19 +690,29 @@ export async function localRoute(request: Request, options: LocalApiOptions): Pr
         channel_id: body.channel_id,
         sender: body.sender,
         recipient: body.recipient,
-        content: body.content,
+        content: body.content ?? '',
         type: body.type,
         idempotency_key: body.idempotency_key,
-        mentions: body.mentions,
+        mentions: appendInferredMentions(body.mentions, inferredMentions),
+        attachments: normalizeSendAttachments(body.attachments),
+        messages: body.messages?.map((message) => ({
+          ...message,
+          content: message.content ?? '',
+          mentions: appendInferredMentions(message.mentions, inferredMentions),
+          attachments: normalizeSendAttachments(message.attachments),
+        })),
+        freshness: body.freshness,
       });
-      return json({ message }, 201);
+      return json(result, result.message ? 201 : 202);
     }
 
     if (request.method === 'GET' && pathname === '/local/runs') {
+      requireDaemonPrincipal(principal);
       return json({ runs: await client.listRuns() });
     }
 
     if (request.method === 'POST' && pathname === '/local/artifacts') {
+      requireDaemonPrincipal(principal);
       const body = await readJson<ArtifactBody>(request);
       if (body.source_path || body.path) throw new HttpError(400, 'PATH_NOT_ALLOWED', 'artifact upload must include content, not a path');
       if (!body.content_base64) throw new HttpError(400, 'MISSING_CONTENT', 'content_base64 is required');
@@ -200,6 +729,7 @@ export async function localRoute(request: Request, options: LocalApiOptions): Pr
 
     const actionMatch = pathname.match(/^\/local\/runs\/([^/]+)\/(kill|restart)$/);
     if (request.method === 'POST' && actionMatch) {
+      requireDaemonPrincipal(principal);
       const run = await client.requestRunAction(actionMatch[1]!, actionMatch[2] as RunAction);
       return json({ run });
     }