agentshire 1.0.0

package/src/contracts/events.ts

@@ -0,0 +1,170 @@
+// @desc AgentEvent union type — the canonical event contract for all consumers
+//
+// 来源: OpenClaw 的 agentLoop() 通过 onEvent 回调发射这些事件
+// 消费者: CLI (TerminalRenderer / App.tsx), Server (ws-handler 透传), Frontend (stream-display)
+//
+// 迁移注意:
+//   - src/core/types.ts 的 AgentEvent 已改为从本文件 re-export
+//   - 旧的 audio_delta / asr_result 已重命名为 media_delta / media_result
+//   - state_snapshot 是新增事件, OpenClaw 核心尚未发射, 预留给状态推送
+//   - tool_use.input 从 Record<string, any> 收紧为 Record<string, unknown>
+
+import type { AudioContent, VideoContent, ContentKind } from './media.js';
+import type { AgentStateSnapshot } from './agent-state.js';
+
+// ── Shared sub-types ──
+
+export interface MediaOutputMeta {
+  width?: number;
+  height?: number;
+  durationMs?: number;
+  filename?: string;
+  sizeBytes?: number;
+  alt?: string;
+  format?: string;
+  [key: string]: unknown;
+}
+
+export interface AgentStats {
+  tokensIn: number;
+  tokensOut: number;
+  contextPercent: number;
+  toolCalls: number;
+  agentSpawns: number;
+  skillCalls: number;
+  workflowCalls: number;
+  durationMs: number;
+}
+
+export interface ToolResultMeta {
+  pid?: number;
+  exitCode?: number;
+  durationMs?: number;
+  filePath?: string;
+}
+
+export interface TokenUsage {
+  inputTokens: number;
+  outputTokens: number;
+  thinkingTokens?: number;
+}
+
+export interface ASRSegment {
+  text: string;
+  start: number;
+  end: number;
+}
+
+// ── AgentEvent ──
+
+export type AgentEvent =
+  // System lifecycle
+  | { type: 'system'; subtype: 'init'; sessionId: string; model: string; persona?: string }
+  | { type: 'system'; subtype: 'done'; result: string; sessionId: string }
+  | { type: 'system'; subtype: 'heartbeat'; elapsedSec: number; waiting: boolean }
+  | { type: 'system'; subtype: 'compacting'; reason: 'auto' | 'manual' | 'micro' }
+  | { type: 'system'; subtype: 'hot_reload_requested'; reason?: string }
+
+  // Text stream
+  | { type: 'text_delta'; delta: string }
+  | { type: 'text'; content: string }
+
+  // Tool calls
+  | { type: 'tool_input_delta'; toolUseId: string; name: string; delta: string }
+  | { type: 'tool_use'; toolUseId: string; name: string; input: Record<string, unknown> }
+  | { type: 'tool_result'; toolUseId: string; name: string; output: string;
+      displayOutput?: string; meta?: ToolResultMeta }
+
+  // Context & turn
+  | { type: 'context_update'; tokens: { used: number; limit: number; percent: number };
+      usage?: TokenUsage; messagesCount: number; iteration: number; maxIterations: number }
+  | { type: 'turn_end'; usage: TokenUsage; toolCalls: number; durationMs: number }
+
+  // Sub-agents
+  | { type: 'sub_agent'; subtype: 'started'; agentId: string; agentType: string;
+      parentToolUseId: string; task: string; model: string; displayName?: string }
+  | { type: 'sub_agent'; subtype: 'progress'; agentId: string; event: AgentEvent }
+  | { type: 'sub_agent'; subtype: 'done'; agentId: string;
+      result: string; toolCalls: number; status: 'completed' | 'failed' | 'killed';
+      stats?: AgentStats }
+
+  // State snapshot
+  | { type: 'state_snapshot'; state: AgentStateSnapshot }
+
+  // Multimodal media
+  | { type: 'media_delta'; streamId: string; content: AudioContent | VideoContent; final?: boolean }
+  | { type: 'media_result'; kind: 'asr'; text: string; confidence?: number; segments?: ASRSegment[] }
+  | { type: 'media_status'; stage: 'asr' | 'tts' | 'vlm';
+      status: 'processing' | 'done' | 'error'; detail?: string }
+
+  // Thinking / reasoning stream (parallel to text_delta)
+  | { type: 'thinking_delta'; delta: string }
+
+  // LLM call lifecycle
+  | { type: 'llm_call'; subtype: 'start';
+      model: string; iteration: number; maxIterations: number;
+      messagesCount: number; toolCount: number;
+      systemPromptPreview?: string }
+  | { type: 'llm_call'; subtype: 'end';
+      iteration: number; durationMs: number;
+      stopReason: string; retryCount: number;
+      usage: TokenUsage }
+
+  // Agent-to-agent messaging
+  | { type: 'bus_message'; from: string; to: string;
+      summary: string; contentPreview: string; timestamp: number }
+  | { type: 'bus_drain'; agentName: string;
+      messageCount: number; summaries: string[] }
+
+  // Hook execution
+  | { type: 'hook'; hookType: 'pre_tool' | 'post_tool';
+      toolName: string; toolUseId: string;
+      action: 'allow' | 'block' | 'modify';
+      reason?: string }
+  | { type: 'hook'; hookType: 'stop' | 'pre_compact' | 'session_start' | 'session_end';
+      action: 'executed';
+      reason?: string }
+
+  // Hook activity state (for UI rendering)
+  | { type: 'hook_activity';
+      event: string;
+      status: 'running' | 'success' | 'error' | 'blocked';
+      icon: string;
+      toolName?: string;
+      detail?: string;
+      durationMs?: number }
+
+  // Context compaction detail (follows system.compacting)
+  | { type: 'compaction_detail';
+      reason: 'auto' | 'manual' | 'micro';
+      tokensBefore: number; tokensAfter: number;
+      messagesRemoved: number;
+      transcriptPath?: string }
+
+  // Debug catch-all
+  | { type: 'debug'; category: string; message: string;
+      data?: Record<string, unknown> }
+
+  // Token usage (streaming)
+  | { type: 'streaming_usage'; usage: TokenUsage }
+
+  // Media output (unified: images, audio, video, files)
+  | { type: 'media_output';
+      kind: ContentKind;
+      mimeType: string;
+      path: string;
+      data?: string;
+      role: 'assistant' | 'user';
+      source?: string;
+      meta?: MediaOutputMeta }
+
+  // Frontend tool awaiting result (AG-UI frontend-defined tools)
+  | { type: 'awaiting_frontend_tool'; toolCallId: string; toolName: string;
+      args: Record<string, unknown> }
+
+  // World control (time & weather)
+  | { type: 'world_control'; target: 'time'; action: 'set' | 'pause' | 'resume'; hour?: number }
+  | { type: 'world_control'; target: 'weather'; action: 'set' | 'reset'; weather?: string }
+
+  // Error
+  | { type: 'error'; message: string; recoverable: boolean };

package/src/contracts/index.ts

@@ -0,0 +1,71 @@
+// @desc Public entry — re-exports all contract types
+//
+// ─── Architecture ───
+//
+//   contracts/          <-- 你在这里：所有层的唯一类型真理之源
+//       │
+//       ├── media.ts         多模态内容块 (text/image/audio/video/file)
+//       ├── agent-state.ts   Agent 状态机 & 递归快照树
+//       ├── events.ts        AgentEvent 联合类型 (OpenClaw 核心对外契约)
+//       ├── registry.ts      中央注册表 (session ↔ project 关联)
+//       └── index.ts         本文件：公共导出入口
+//
+// ─── 消费者 ───
+//
+//   CLI 层        → events.ts + agent-state.ts + media.ts
+//   OpenClaw 层 → events.ts + agent-state.ts (src/core/types.ts re-export)
+//
+// ─── 已移除 (Phase 0 清理, 2026-03) ───
+//
+//   messages.ts — WS 新格式类型，从未被消费，已删除
+//   envelope.ts — 传输信封类型，从未被消费，已删除
+//
+
+// Media
+export type {
+  ContentKind,
+  InlineSource,
+  UrlSource,
+  StreamSource,
+  TextContent,
+  ImageContent,
+  AudioContent,
+  VideoStreamSource,
+  VideoContent,
+  FileContent,
+  MediaContent,
+  MultimodalBody,
+} from './media.js';
+
+// Agent state
+export type {
+  AgentPhase,
+  AgentActivity,
+  AgentResources,
+  AgentSnapStats,
+  AgentStateSnapshot,
+  SessionStatus,
+  SessionState,
+} from './agent-state.js';
+
+// Chat
+export type {
+  ChatMediaType,
+  ChatItemKind,
+  ChatItem,
+  ChatTextItem,
+  ChatMediaItem,
+  ChatToolItem,
+  ChatStatusItem,
+  ChatItemHistoryResult,
+} from './chat.js';
+
+// Events
+export type {
+  AgentStats,
+  ToolResultMeta,
+  TokenUsage,
+  ASRSegment,
+  AgentEvent,
+  MediaOutputMeta,
+} from './events.js';

package/src/contracts/media.ts

@@ -0,0 +1,77 @@
+// @desc Multimodal content types: text, image, audio, video, file
+//
+// source 使用判别联合 (type: 'base64' | 'url' | 'stream'), 与传输层解耦
+// 同一个 AudioContent 可以在 WS JSON (base64) 或 HTTP 上传 (url) 中使用
+//
+// 迁移注意:
+//   - VideoContent / VideoStreamSource 已定义但尚无实现
+//   - MediaPipeline TTS 输出已使用 AudioContent + InlineSource (base64)
+//   - 旧的 ContentBlock (src/core/types.ts) 是 LLM 内部格式, 与本文件的
+//     MediaContent 是不同抽象层: ContentBlock = LLM API, MediaContent = 传输契约
+
+export type ContentKind = 'text' | 'image' | 'audio' | 'video' | 'file';
+
+// ── Source discriminated union (transport-agnostic) ──
+
+export type InlineSource = { type: 'base64'; data: string };
+export type UrlSource = { type: 'url'; url: string };
+export type StreamSource = { type: 'stream'; streamId: string };
+
+// ── Content blocks ──
+
+export interface TextContent {
+  kind: 'text';
+  text: string;
+}
+
+export interface ImageContent {
+  kind: 'image';
+  mimeType: 'image/png' | 'image/jpeg' | 'image/webp' | 'image/gif';
+  source: InlineSource | UrlSource;
+  width?: number;
+  height?: number;
+  alt?: string;
+}
+
+export interface AudioContent {
+  kind: 'audio';
+  format: 'mp3' | 'pcm' | 'wav' | 'webm' | 'opus';
+  source: InlineSource | UrlSource | StreamSource;
+  sampleRate?: number;
+  channels?: number;
+  durationMs?: number;
+}
+
+export type VideoStreamSource = {
+  type: 'stream';
+  streamId: string;
+  protocol: 'webrtc' | 'hls' | 'ws-binary';
+};
+
+export interface VideoContent {
+  kind: 'video';
+  format: 'mp4' | 'webm';
+  source: InlineSource | UrlSource | VideoStreamSource;
+  mimeType?: string;
+  width?: number;
+  height?: number;
+  durationMs?: number;
+  thumbnail?: ImageContent;
+}
+
+export interface FileContent {
+  kind: 'file';
+  filename: string;
+  mimeType: string;
+  source: InlineSource | UrlSource;
+  sizeBytes?: number;
+}
+
+export type MediaContent =
+  | TextContent
+  | ImageContent
+  | AudioContent
+  | VideoContent
+  | FileContent;
+
+export type MultimodalBody = MediaContent[];

package/src/contracts/registry.ts

@@ -0,0 +1,32 @@
+// @desc Central registry types for session ↔ project associations
+//
+// registry.json lives in .openclaw/ and tracks all projects (games + workspace apps).
+// It is the single source of truth for:
+//   - Server API endpoints (/projects, /sessions enrichment)
+//   - Frontend project listing and session switching
+//   - Future network service mapping (game sharing platform)
+//
+// Projects are keyed by their directory name (which already contains timestamp + random suffix).
+
+export type ProjectType = 'game' | 'app';
+export type ProjectStatus = 'active' | 'archived' | 'error';
+
+export interface ProjectEntry {
+  type: ProjectType;
+  name: string;
+  dir: string;
+  template?: string;
+  engine?: string;
+  port?: number;
+  vite: boolean;
+  createdAt: string;
+  sessionId: string;
+  status: ProjectStatus;
+  description?: string;
+}
+
+export interface Registry {
+  version: number;
+  projects: Record<string, ProjectEntry>;
+  activeGameDir?: string;
+}

package/src/plugin/AGENTS.md

@@ -0,0 +1,192 @@
+# Plugin 层架构指南
+
+> OpenClaw 插件的 Node.js 端：Hook 监听、WebSocket 广播、AI 工具、编辑器 API、居民 Agent 管理。
+
+## 目录结构
+
+```
+src/plugin/
+├── channel.ts                 # ChannelPlugin 实现（startAccount启动WS/注册回调）
+├── hook-translator.ts         # 纯函数：OpenClaw Hook名 → AgentEvent
+├── ws-server.ts               # WebSocket服务器 + 会话绑定 + 消息路由
+├── tools.ts                   # AI工具注册（11个工具）
+├── auto-config.ts             # 零配置：自动创建town-steward Agent + Binding
+├── plan-manager.ts            # 多Agent计划状态机（步骤/批次/enriched task）
+├── citizen-agent-manager.ts   # 独立居民Agent CRUD（写openclaw.json）
+├── citizen-chat-router.ts     # 用户↔居民Agent消息路由
+├── citizen-workshop-manager.ts # 居民工坊配置持久化（citizen-config.json）
+├── editor-serve.ts            # 编辑器HTTP API（1176行，资产/工坊/发布）
+├── llm-agent-proxy.ts         # LLM代理（走OpenClaw embedded agent runtime，2并发+10队列）
+├── session-history.ts         # 跨会话聊天历史加载（管家+居民）
+├── soul-prompt-template.ts    # 灵魂文件AI生成模板
+├── outbound-adapter.ts        # 出站适配（text→AgentEvent, media→deliverable_card）
+├── subagent-tracker.ts        # 子Agent会话日志实时转发
+├── session-log-watcher.ts     # JSONL日志增量读取（300ms轮询）
+├── custom-asset-manager.ts    # 自定义GLB资产管理（最多20个，10MB限制）
+├── town-session.ts            # Session ID标准化/解析
+└── runtime.ts                 # Runtime注入（getter/setter）
+```
+
+## 核心数据流
+
+```
+index.ts register(api)
+ ├─ api.registerChannel(agentTownPlugin)   → channel.ts
+ ├─ registerHooks(api)                      → 监听8种Hook
+ ├─ api.registerTool(createTownTools())     → tools.ts
+ ├─ ensureTownAgentConfig()                 → auto-config.ts
+ ├─ subagent_spawning hook                  → town-souls.ts 注入灵魂
+ └─ api.registerService("agentshire-frontend") → HTTP服务器(:55210)
+     └─ handleEditorRequest()               → editor-serve.ts
+
+Hook事件流：
+ OpenClaw Hook → isStewardDirect() 判断
+  ├─ 管家直接事件 → dispatchSteward() → hookToAgentEvent() → broadcastAgentEvent()
+  └─ 居民Agent事件 → dispatchCitizen() → 附加npcId → broadcastAgentEvent()
+
+子Agent生命周期：
+ subagent_spawned → pendingSpawnTasks缓存task → onSubagentSpawned()
+   → SessionLogWatcher监听JSONL → broadcastAgentEvent(子事件)
+ subagent_ended → onSubagentEnded() → plan-manager.onAgentCompleted()
+   → 批次完成？→ scheduleNudge(10s后提醒next_step)
+```
+
+## Hook 翻译表（hook-translator.ts）
+
+| Hook名 | AgentEvent类型 | 备注 |
+|--------|---------------|------|
+| `before_agent_start` | `system.init` | sessionId/model/persona |
+| `agent_end` | `turn_end` (+可选error) | usage/toolCalls/durationMs |
+| `llm_input` | `thinking_delta` | 提取thinking/reasoning字段 |
+| `llm_output` | `text` | assistantTexts最后一项 |
+| `before_tool_call` | `tool_use` | name/input |
+| `after_tool_call` | `tool_result` (+可选media_output) | 自动检测媒体文件 |
+| `subagent_spawned` | `sub_agent.started` | label/task/agentId |
+| `subagent_ended` | `sub_agent.done` | outcome→status映射 |
+| `message_sending` | `text` | 发送中的消息 |
+| `session_end` | `system.done` | — |
+
+## AI 工具（tools.ts）
+
+| 工具名 | 功能 | 发出的事件 |
+|--------|------|-----------|
+| `town_announce` | 广播消息 | `text` |
+| `town_spawn_npc` | 生成NPC | `sub_agent.started`(模拟) |
+| `town_effect` | 触发VFX | `fx` |
+| `town_set_time` | 控制时钟 | `world_control.time` |
+| `town_set_weather` | 控制天气 | `world_control.weather` |
+| `town_status` | 查看状态 | —（返回文本） |
+| `register_project` | 注册项目 | — |
+| `create_project` | 创建项目目录 | — |
+| `create_plan` | 创建多Agent计划 | — |
+| `next_step` | 获取下一步指令 | — |
+| `project_complete` | 宣布完成 | `tool_result`(触发publishing) |
+
+## plan-manager：多 Agent 计划编排
+
+```
+create_plan(steps) → 验证(多Agent步骤必须有files且不重叠)
+  → 存储计划(追加隐含_complete步骤)
+
+next_step() → 生成当前进度报告 + 下一批spawn指令
+  → buildEnrichedTask(角色人设+项目目录+文件边界+通用规则)
+
+onAgentStarted(label) → 标记agent为active
+onAgentCompleted(label, success) → 标记完成 → isCurrentBatchDone()?
+  → 是 → index.ts scheduleNudge(10s后提醒管家)
+
+支持 parallel 标记：步骤可与前一步并行执行
+```
+
+## editor-serve：编辑器 HTTP API
+
+路由结构（全部走 `handleEditorRequest()`）：
+
+| 路径前缀 | 功能 |
+|---------|------|
+| `/ext-assets/*` | 角色/地图资产静态文件 |
+| `/citizen-workshop/avatars/*` | 用户上传头像 |
+| `/custom-assets/_api/{action}` | 自定义资产CRUD + GLB优化(@gltf-transform) |
+| `/custom-assets/*` | 自定义资产静态文件 |
+| `/citizen-workshop/_api/load` | 加载工坊草稿配置 |
+| `/citizen-workshop/_api/save` | 保存工坊草稿 |
+| `/citizen-workshop/_api/publish` | **发布**：changeset检测→Agent CRUD→同步town-defaults |
+| `/citizen-workshop/_api/load-published` | 加载已发布配置 |
+| `/citizen-workshop/_api/generate-soul` | AI生成灵魂文件 |
+| `/citizen-workshop/_api/upload-avatar` | 上传头像 |
+| `/citizen-workshop/_api/upload-anim` | 上传动画文件 |
+| `/citizen-workshop/_api/agents` | 查询Agent列表 |
+| `/citizen-workshop/_api/buildings` | 查询建筑列表 |
+| `/citizen-workshop/_api/media` | 媒体文件代理 |
+
+**发布流程**：
+1. 构建 `PublishedCitizenConfig`（bake所有URL）
+2. 比较新旧配置，检测 changeset（create/disable/update_soul）
+3. 调用 `citizen-agent-manager.applyAgentChanges()` 执行Agent CRUD
+4. 管家人设变更时更新管家SOUL.md
+5. 同步 `town-defaults.json`
+
+## citizen-agent-manager：独立居民 Agent
+
+居民不只是子Agent（工作时），也可以是独立Agent（有自己的工作区和会话）。
+
+| 操作 | 行为 |
+|------|------|
+| `create` | 创建 `~/.openclaw/workspace-citizen-{id}/` + SOUL.md + 注册到openclaw.json |
+| `disable` | 从 openclaw.json agents.list 中移除 |
+| `update_soul` | 更新 SOUL.md 文件 |
+
+`citizen-chat-router.ts` 路由用户消息到居民Agent的独立会话（SessionKey = `agent:{agentId}:main`）。
+
+## WebSocket 协议（ws-server.ts）
+
+**浏览器 → 服务端**：
+
+| 消息类型 | 说明 |
+|---------|------|
+| `town_session_init` | 绑定会话，回复 `town_session_bound` + `work_snapshot` |
+| `chat` | 用户消息 → onChat回调 → 管家Agent |
+| `multimodal` | 多模态消息（图片/视频/音频） |
+| `citizen_chat` | 居民聊天 → citizen-chat-router |
+| `implicit_chat_request` | 前端隐式LLM请求 → llm-agent-proxy |
+| `chat_history_request` | 请求历史消息 → session-history |
+| `command` | 命令消息（`/xxx`） |
+| `abort` | 中止当前请求 |
+
+**服务端 → 浏览器**：
+
+| 消息类型 | 说明 |
+|---------|------|
+| `agent_event` | 主事件流（AgentEvent） |
+| `work_snapshot` | 工作状态快照（子Agent列表+活动日志） |
+| `chat_new_messages` | 新消息增量推送 |
+| `chat_history` | 历史消息（含分页cursor） |
+| `implicit_chat_response` | 隐式LLM响应 |
+
+## Nudge 机制（index.ts）
+
+当一批子Agent全部完成（`isCurrentBatchDone()`）但管家 10 秒内未响应时，自动发送系统通知"请调用 next_step()"。管家恢复活动（`before_agent_start` / `before_tool_call` / `llm_input`）时自动取消。
+
+## 常见改动
+
+| 要做的事 | 改哪里 |
+|---------|--------|
+| 新增Hook→AgentEvent映射 | `hook-translator.ts` |
+| 新增AI工具 | `tools.ts` |
+| 修改计划编排/enriched task | `plan-manager.ts` |
+| 修改编辑器API | `editor-serve.ts` |
+| 修改居民Agent创建/销毁 | `citizen-agent-manager.ts` |
+| 修改居民聊天路由 | `citizen-chat-router.ts` |
+| 修改隐式LLM调用格式 | `llm-agent-proxy.ts` |
+| 修改聊天历史解析 | `session-history.ts` |
+| 修改灵魂文件生成模板 | `soul-prompt-template.ts` |
+| 修改WS消息路由 | `ws-server.ts` |
+| 修改出站消息格式 | `outbound-adapter.ts` |
+| 修改自定义资产限制 | `custom-asset-manager.ts` |
+
+## 测试
+
+```
+src/plugin/__tests__/
+└── hook-translator.test.ts   # Hook名 → AgentEvent 映射
+```

package/src/plugin/__tests__/editor-serve-megapack.test.ts

@@ -0,0 +1,150 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { join } from 'node:path'
+import { mkdirSync, writeFileSync, rmSync, existsSync } from 'node:fs'
+
+const TEST_PLUGIN_DIR = join(import.meta.dirname, '__fixtures_megapack__')
+const MAP1_DIR = join(TEST_PLUGIN_DIR, 'assets', 'Map_1')
+
+function createMockRes() {
+  const res: any = {
+    _status: 0,
+    _headers: {} as Record<string, string>,
+    _body: null as Buffer | string | null,
+    writeHead(status: number, headers?: Record<string, string>) {
+      res._status = status
+      if (headers) Object.assign(res._headers, headers)
+    },
+    end(body?: any) {
+      res._body = body ?? null
+    },
+  }
+  return res
+}
+
+function createMockReq(method: string, url: string): any {
+  return { method, url }
+}
+
+describe('editor-serve megapack route', () => {
+  beforeEach(() => {
+    mkdirSync(join(MAP1_DIR, 'Buildings', 'Building 1'), { recursive: true })
+    writeFileSync(
+      join(MAP1_DIR, 'Buildings', 'Building 1', 'Building_1.gltf'),
+      '{"asset":{"version":"2.0"}}',
+    )
+    writeFileSync(
+      join(MAP1_DIR, 'Buildings', 'Building 1', 'Building_1.bin'),
+      Buffer.from([0x00, 0x01, 0x02]),
+    )
+    mkdirSync(join(MAP1_DIR, 'Roads'), { recursive: true })
+    writeFileSync(
+      join(MAP1_DIR, 'Roads', 'Road_Straight.gltf'),
+      '{"asset":{"version":"2.0"}}',
+    )
+    mkdirSync(join(TEST_PLUGIN_DIR, 'town-data', 'custom-assets', 'models'), { recursive: true })
+    mkdirSync(join(TEST_PLUGIN_DIR, 'town-data', 'custom-assets', 'characters'), { recursive: true })
+    mkdirSync(join(TEST_PLUGIN_DIR, 'town-data', 'custom-assets', 'animations'), { recursive: true })
+    mkdirSync(join(TEST_PLUGIN_DIR, 'town-data', 'souls'), { recursive: true })
+    mkdirSync(join(TEST_PLUGIN_DIR, 'town-souls'), { recursive: true })
+    mkdirSync(join(TEST_PLUGIN_DIR, 'town-data', 'citizen-workshop', 'avatars'), { recursive: true })
+    if (!existsSync(join(TEST_PLUGIN_DIR, 'town-data', 'custom-assets', '_catalog.json'))) {
+      writeFileSync(
+        join(TEST_PLUGIN_DIR, 'town-data', 'custom-assets', '_catalog.json'),
+        '{"version":1,"assets":[]}',
+      )
+    }
+  })
+
+  afterEach(() => {
+    rmSync(TEST_PLUGIN_DIR, { recursive: true, force: true })
+  })
+
+  async function handle(method: string, url: string) {
+    const { handleEditorRequest } = await import('../editor-serve.js')
+    const req = createMockReq(method, url)
+    const res = createMockRes()
+    const handled = await handleEditorRequest(req, res, TEST_PLUGIN_DIR)
+    return { handled, res }
+  }
+
+  it('serves megapack gltf file when assets exist', async () => {
+    const { handled, res } = await handle(
+      'GET',
+      '/assets/models/megapack/gltf/Buildings/Building%201/Building_1.gltf',
+    )
+    expect(handled).toBe(true)
+    expect(res._status).toBe(200)
+    expect(res._headers['Content-Type']).toContain('gltf')
+  })
+
+  it('serves megapack bin file when assets exist', async () => {
+    const { handled, res } = await handle(
+      'GET',
+      '/assets/models/megapack/gltf/Buildings/Building%201/Building_1.bin',
+    )
+    expect(handled).toBe(true)
+    expect(res._status).toBe(200)
+    expect(res._headers['Content-Type']).toBe('application/octet-stream')
+  })
+
+  it('returns 404 for non-existent megapack file', async () => {
+    const { handled, res } = await handle(
+      'GET',
+      '/assets/models/megapack/gltf/Buildings/NoSuch/model.gltf',
+    )
+    expect(handled).toBe(true)
+    expect(res._status).toBe(404)
+  })
+
+  it('correctly decodes URL-encoded paths with spaces', async () => {
+    const { handled, res } = await handle(
+      'GET',
+      '/assets/models/megapack/gltf/Buildings/Building%201/Building_1.gltf',
+    )
+    expect(handled).toBe(true)
+    expect(res._status).toBe(200)
+  })
+
+  it('blocks path traversal attempts', async () => {
+    const { handled, res } = await handle(
+      'GET',
+      '/assets/models/megapack/gltf/../../../../../../etc/passwd',
+    )
+    expect(handled).toBe(true)
+    expect(res._status).toBe(404)
+  })
+
+  it('does not intercept non-megapack asset requests', async () => {
+    const { handled } = await handle(
+      'GET',
+      '/assets/models/buildings/building_A.gltf',
+    )
+    expect(handled).toBe(false)
+  })
+
+  it('does not intercept ext-assets requests (existing route)', async () => {
+    const { handled, res } = await handle(
+      'GET',
+      '/ext-assets/Characters_1/gLTF/Animations/Animations.glb',
+    )
+    expect(handled).toBe(true)
+    expect(res._status).toBe(404)
+  })
+
+  it('serves simple path without URL encoding', async () => {
+    const { handled, res } = await handle(
+      'GET',
+      '/assets/models/megapack/gltf/Roads/Road_Straight.gltf',
+    )
+    expect(handled).toBe(true)
+    expect(res._status).toBe(200)
+  })
+
+  it('sets cache header on megapack responses', async () => {
+    const { res } = await handle(
+      'GET',
+      '/assets/models/megapack/gltf/Roads/Road_Straight.gltf',
+    )
+    expect(res._headers['Cache-Control']).toBe('public, max-age=86400')
+  })
+})