@elizaos/autonomous 2.0.0-alpha.10

package/src/utils/number-parsing.ts

@@ -0,0 +1,112 @@
+export interface ParseClampedIntegerOptions {
+  min?: number;
+  max?: number;
+  fallback?: number;
+}
+
+export interface ParseClampedNumberOptions {
+  min?: number;
+  max?: number;
+  fallback?: number;
+}
+
+export interface ParsePositiveNumberOptions {
+  fallback?: number;
+  floor?: boolean;
+}
+
+function sanitizeNumericText(value: string | null | undefined): string {
+  return value == null ? "" : value.trim();
+}
+
+function normalizeFallback(fallback: number | undefined): number | undefined {
+  return Number.isFinite(fallback) ? fallback : undefined;
+}
+
+export function parseClampedInteger(
+  value: string | null | undefined,
+  options: ParseClampedIntegerOptions & { fallback: number },
+): number;
+export function parseClampedInteger(
+  value: string | null | undefined,
+  options?: ParseClampedIntegerOptions,
+): number | undefined;
+export function parseClampedInteger(
+  value: string | null | undefined,
+  options: ParseClampedIntegerOptions = {},
+): number | undefined {
+  const raw = sanitizeNumericText(value);
+  if (!raw) return normalizeFallback(options.fallback);
+
+  const parsed = Number.parseInt(raw, 10);
+  if (!Number.isFinite(parsed)) return normalizeFallback(options.fallback);
+
+  const min = options.min;
+  if (min !== undefined && parsed < min) return min;
+
+  const max = options.max;
+  if (max !== undefined && parsed > max) return max;
+
+  return parsed;
+}
+
+export function parsePositiveInteger(
+  value: string | null | undefined,
+  fallback: number,
+): number;
+export function parsePositiveInteger(
+  value: string | null | undefined,
+  fallback?: number,
+): number | undefined;
+export function parsePositiveInteger(
+  value: string | null | undefined,
+  fallback?: number,
+): number | undefined {
+  const raw = sanitizeNumericText(value);
+  if (!raw) return normalizeFallback(fallback);
+
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return normalizeFallback(fallback);
+  }
+
+  return Math.max(1, Math.floor(parsed));
+}
+
+export function parsePositiveFloat(
+  value: string | null | undefined,
+  options?: ParsePositiveNumberOptions,
+): number | undefined {
+  const raw = sanitizeNumericText(value);
+  if (!raw) return normalizeFallback(options?.fallback);
+
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return normalizeFallback(options?.fallback);
+  }
+
+  return options?.floor ? Math.floor(parsed) : parsed;
+}
+
+export function parseClampedFloat(
+  value: string | null | undefined,
+  options: ParseClampedNumberOptions & { fallback: number },
+): number;
+export function parseClampedFloat(
+  value: string | null | undefined,
+  options?: ParseClampedNumberOptions,
+): number | undefined;
+export function parseClampedFloat(
+  value: string | null | undefined,
+  options: ParseClampedNumberOptions = {},
+): number | undefined {
+  const raw = sanitizeNumericText(value);
+  if (!raw) return normalizeFallback(options.fallback);
+
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed)) return normalizeFallback(options.fallback);
+
+  const min = options.min ?? -Infinity;
+  const max = options.max ?? Infinity;
+  return Math.max(min, Math.min(max, parsed));
+}

package/src/utils/spoken-text.ts

@@ -0,0 +1,65 @@
+function collapseWhitespace(input: string): string {
+  return input.replace(/\s+/g, " ").trim();
+}
+
+function stripUrls(input: string): string {
+  return input.replace(/\bhttps?:\/\/\S+/gi, " ");
+}
+
+function stripThinkingAndMarkup(input: string): string {
+  let text = input;
+  text = text.replace(/<think\b[^>]*>[\s\S]*?<\/think>/gi, " ");
+  text = text.replace(
+    /<(analysis|reasoning|scratchpad|tool_calls?|tools?)\b[^>]*>[\s\S]*?<\/\1>/gi,
+    " ",
+  );
+  text = text.replace(/```[\s\S]*?```/g, " ");
+  text = text.replace(/`([^`]+)`/g, "$1");
+  text = text.replace(/\[([^\]]+)\]\([^)]+\)/g, "$1");
+  text = text.replace(/<[^>\n]+>/g, " ");
+  text = stripUrls(text);
+  return text;
+}
+
+const NON_SPEECH_SEGMENT_PATTERNS = [
+  /\*{1,2}[^*\n]+\*{1,2}/g,
+  /\([^()]*\)/g,
+  /\[[^[\]]*\]/g,
+  /\{[^{}]*\}/g,
+];
+
+function stripNonSpeechDirections(input: string): string {
+  let text = input;
+  while (true) {
+    const previous = text;
+    for (const pattern of NON_SPEECH_SEGMENT_PATTERNS) {
+      text = text.replace(pattern, " ");
+    }
+    if (text === previous) {
+      break;
+    }
+  }
+  return text.replace(/[*()[\]{}]+/g, " ");
+}
+
+function sanitizeSpeechPunctuation(input: string): string {
+  let text = input;
+  text = text.replace(/[•·■▪◦]/g, " ");
+  text = text.replace(/[“”]/g, '"');
+  text = text.replace(/[‘’]/g, "'");
+  text = text.replace(/[…]/g, "...");
+  text = text.replace(/[–—]/g, ", ");
+  text = text.replace(/\s*([,;:])\s*/g, "$1 ");
+  text = text.replace(/\s*([.!?])\s*/g, "$1 ");
+  text = text.replace(/[^\p{L}\p{N}\s.,!?'"%/$:+-]/gu, " ");
+  text = text.replace(/([,.!?])\1+/g, "$1");
+  text = text.replace(/^[,;:.!?]+/g, " ");
+  return text;
+}
+
+export function sanitizeSpeechText(input: string): string {
+  const normalized = input.normalize("NFKC");
+  const stripped = stripThinkingAndMarkup(normalized);
+  const withoutDirections = stripNonSpeechDirections(stripped);
+  return collapseWhitespace(sanitizeSpeechPunctuation(withoutDirections));
+}

package/src/version-resolver.ts

@@ -0,0 +1,60 @@
+import { createRequire } from "node:module";
+import process from "node:process";
+
+declare const __MILADY_VERSION__: string | undefined;
+
+const PACKAGE_JSON_CANDIDATE = "../../package.json";
+const BUILD_INFO_CANDIDATES = [
+  "../../build-info.json",
+  "../build-info.json",
+  "./build-info.json",
+] as const;
+
+function isModuleNotFound(err: unknown): boolean {
+  return (
+    typeof err === "object" &&
+    err !== null &&
+    "code" in err &&
+    (err as NodeJS.ErrnoException).code === "MODULE_NOT_FOUND"
+  );
+}
+
+function readVersionFromPackageJson(requireFn: NodeRequire): string | null {
+  try {
+    const pkg = requireFn(PACKAGE_JSON_CANDIDATE) as { version?: string };
+    return pkg.version ?? null;
+  } catch (err) {
+    if (isModuleNotFound(err)) {
+      return null;
+    }
+    throw err;
+  }
+}
+
+function readVersionFromBuildInfo(requireFn: NodeRequire): string | null {
+  for (const candidate of BUILD_INFO_CANDIDATES) {
+    try {
+      const info = requireFn(candidate) as { version?: string };
+      if (info.version) {
+        return info.version;
+      }
+    } catch (err) {
+      if (!isModuleNotFound(err)) {
+        throw err;
+      }
+    }
+  }
+  return null;
+}
+
+export function resolveMiladyVersion(moduleUrl: string): string {
+  const requireFn = createRequire(moduleUrl);
+
+  return (
+    (typeof __MILADY_VERSION__ === "string" && __MILADY_VERSION__) ||
+    process.env.MILADY_BUNDLED_VERSION ||
+    readVersionFromPackageJson(requireFn) ||
+    readVersionFromBuildInfo(requireFn) ||
+    "0.0.0"
+  );
+}

package/test/api/agent-admin-routes.test.ts

@@ -0,0 +1,160 @@
+import { describe, test, expect, vi } from "vitest";
+import {
+  createMockIncomingMessage,
+  createMockHttpResponse,
+} from "../../src/test-support/test-helpers";
+import { handleAgentAdminRoutes } from "../../src/api/agent-admin-routes";
+import type { AgentAdminRouteContext } from "../../src/api/agent-admin-routes";
+
+function buildCtx(
+  method: string,
+  pathname: string,
+  overrides?: Partial<AgentAdminRouteContext>,
+): AgentAdminRouteContext & { getStatus: () => number; getJson: () => unknown } {
+  const { res, getStatus, getJson } = createMockHttpResponse();
+  const req = createMockIncomingMessage({ method, url: pathname });
+  const ctx = {
+    req,
+    res,
+    method,
+    pathname,
+    json: vi.fn((r, data, status = 200) => {
+      r.writeHead(status);
+      r.end(JSON.stringify(data));
+    }),
+    error: vi.fn((r, msg, status = 500) => {
+      r.writeHead(status);
+      r.end(JSON.stringify({ error: msg }));
+    }),
+    state: {
+      runtime: null,
+      config: {},
+      agentState: "running" as const,
+      agentName: "TestAgent",
+      model: "gpt-4",
+      startedAt: Date.now(),
+      chatRoomId: null,
+      chatUserId: null,
+      chatConnectionReady: null,
+      chatConnectionPromise: null,
+      pendingRestartReasons: [],
+    },
+    onRestart: undefined,
+    onRuntimeSwapped: undefined,
+    resolveStateDir: () => "/tmp/milady-state",
+    resolvePath: (value: string) => value,
+    getHomeDir: () => "/home/test",
+    isSafeResetStateDir: () => true,
+    stateDirExists: () => false,
+    removeStateDir: vi.fn(),
+    logWarn: vi.fn(),
+    ...overrides,
+  } as AgentAdminRouteContext & {
+    getStatus: () => number;
+    getJson: () => unknown;
+  };
+  (ctx as any).getStatus = getStatus;
+  (ctx as any).getJson = getJson;
+  return ctx;
+}
+
+describe("agent-admin-routes", () => {
+  describe("POST /api/agent/restart", () => {
+    test("returns 501 when no onRestart handler is registered", async () => {
+      const ctx = buildCtx("POST", "/api/agent/restart");
+      const handled = await handleAgentAdminRoutes(ctx);
+      expect(handled).toBe(true);
+      expect(ctx.error).toHaveBeenCalledOnce();
+      const args = (ctx.error as ReturnType<typeof vi.fn>).mock.calls[0];
+      expect(args[2]).toBe(501);
+      expect(args[1]).toContain("not supported");
+    });
+
+    test("returns 409 when agent is already restarting", async () => {
+      const ctx = buildCtx("POST", "/api/agent/restart", {
+        onRestart: vi.fn(async () => null),
+        state: {
+          runtime: null,
+          config: {},
+          agentState: "restarting",
+          agentName: "TestAgent",
+          model: "gpt-4",
+          startedAt: Date.now(),
+          chatRoomId: null,
+          chatUserId: null,
+          chatConnectionReady: null,
+          chatConnectionPromise: null,
+          pendingRestartReasons: [],
+        },
+      });
+      const handled = await handleAgentAdminRoutes(ctx);
+      expect(handled).toBe(true);
+      expect(ctx.error).toHaveBeenCalledOnce();
+      const args = (ctx.error as ReturnType<typeof vi.fn>).mock.calls[0];
+      expect(args[2]).toBe(409);
+      expect(args[1]).toContain("already in progress");
+    });
+
+    test("returns success when onRestart returns a new runtime", async () => {
+      const mockRuntime = {
+        character: { name: "NewAgent" },
+        getSetting: () => undefined,
+        modelProvider: "openai",
+      } as any;
+      const onRestart = vi.fn(async () => mockRuntime);
+      const onRuntimeSwapped = vi.fn();
+      const ctx = buildCtx("POST", "/api/agent/restart", {
+        onRestart,
+        onRuntimeSwapped,
+      });
+      const handled = await handleAgentAdminRoutes(ctx);
+      expect(handled).toBe(true);
+      expect(ctx.json).toHaveBeenCalledOnce();
+      const payload = (ctx.json as ReturnType<typeof vi.fn>).mock.calls[0][1];
+      expect(payload.ok).toBe(true);
+      expect(payload.pendingRestart).toBe(false);
+      expect(ctx.state.agentState).toBe("running");
+      expect(onRuntimeSwapped).toHaveBeenCalled();
+    });
+
+    test("returns 500 when onRestart returns null", async () => {
+      const ctx = buildCtx("POST", "/api/agent/restart", {
+        onRestart: vi.fn(async () => null),
+      });
+      const handled = await handleAgentAdminRoutes(ctx);
+      expect(handled).toBe(true);
+      expect(ctx.error).toHaveBeenCalledOnce();
+      const args = (ctx.error as ReturnType<typeof vi.fn>).mock.calls[0];
+      expect(args[2]).toBe(500);
+      expect(args[1]).toContain("failed to re-initialize");
+      expect(ctx.state.agentState).toBe("running");
+    });
+
+    test("returns 500 when onRestart throws", async () => {
+      const ctx = buildCtx("POST", "/api/agent/restart", {
+        onRestart: vi.fn(async () => {
+          throw new Error("boom");
+        }),
+      });
+      const handled = await handleAgentAdminRoutes(ctx);
+      expect(handled).toBe(true);
+      expect(ctx.error).toHaveBeenCalledOnce();
+      const args = (ctx.error as ReturnType<typeof vi.fn>).mock.calls[0];
+      expect(args[2]).toBe(500);
+      expect(args[1]).toContain("boom");
+      expect(ctx.state.agentState).toBe("running");
+    });
+  });
+
+  describe("routing", () => {
+    test("unrelated path returns false", async () => {
+      const ctx = buildCtx("GET", "/api/other");
+      expect(await handleAgentAdminRoutes(ctx)).toBe(false);
+    });
+
+    test("GET to restart endpoint returns false (wrong method)", async () => {
+      const ctx = buildCtx("GET", "/api/agent/restart");
+      expect(await handleAgentAdminRoutes(ctx)).toBe(false);
+    });
+  });
+});

package/test/api/agent-lifecycle-routes.test.ts

@@ -0,0 +1,164 @@
+import { describe, test, expect, vi } from "vitest";
+import {
+  createMockIncomingMessage,
+  createMockHttpResponse,
+} from "../../src/test-support/test-helpers";
+import { handleAgentLifecycleRoutes } from "../../src/api/agent-lifecycle-routes";
+import type {
+  AgentLifecycleRouteContext,
+  AgentLifecycleRouteState,
+} from "../../src/api/agent-lifecycle-routes";
+
+function buildState(
+  overrides?: Partial<AgentLifecycleRouteState>,
+): AgentLifecycleRouteState {
+  return {
+    runtime: null,
+    agentState: "not_started",
+    agentName: "test-agent",
+    model: undefined,
+    startedAt: undefined,
+    ...overrides,
+  };
+}
+
+function buildCtx(
+  method: string,
+  pathname: string,
+  state: AgentLifecycleRouteState,
+  overrides?: Partial<AgentLifecycleRouteContext>,
+): AgentLifecycleRouteContext {
+  const { res } = createMockHttpResponse();
+  return {
+    req: createMockIncomingMessage({ method, url: pathname }),
+    res,
+    method,
+    pathname,
+    json: vi.fn((r, data, status = 200) => {
+      r.writeHead(status);
+      r.end(JSON.stringify(data));
+    }),
+    error: vi.fn((r, msg, status = 500) => {
+      r.writeHead(status);
+      r.end(JSON.stringify({ error: msg }));
+    }),
+    readJsonBody: vi.fn(async () => ({})),
+    state,
+    ...overrides,
+  } as AgentLifecycleRouteContext;
+}
+
+describe("agent-lifecycle-routes", () => {
+  describe("POST /api/agent/start", () => {
+    test("transitions to paused and sets startedAt", async () => {
+      const state = buildState({ agentState: "not_started" });
+      const ctx = buildCtx("POST", "/api/agent/start", state);
+      const handled = await handleAgentLifecycleRoutes(ctx);
+      expect(handled).toBe(true);
+      expect(state.agentState).toBe("paused");
+      expect(state.startedAt).toBeDefined();
+      expect(ctx.json).toHaveBeenCalled();
+      const payload = (ctx.json as ReturnType<typeof vi.fn>).mock.calls[0][1];
+      expect(payload.ok).toBe(true);
+      expect(payload.status.state).toBe("paused");
+    });
+  });
+
+  describe("POST /api/agent/stop", () => {
+    test("transitions to stopped and clears model/startedAt", async () => {
+      const state = buildState({
+        agentState: "running",
+        startedAt: Date.now(),
+        model: "gpt-4",
+      });
+      const ctx = buildCtx("POST", "/api/agent/stop", state);
+      await handleAgentLifecycleRoutes(ctx);
+      expect(state.agentState).toBe("stopped");
+      expect(state.startedAt).toBeUndefined();
+      expect(state.model).toBeUndefined();
+    });
+  });
+
+  describe("POST /api/agent/pause", () => {
+    test("transitions to paused and preserves startedAt", async () => {
+      const started = Date.now() - 5000;
+      const state = buildState({
+        agentState: "running",
+        startedAt: started,
+        model: "gpt-4",
+      });
+      const ctx = buildCtx("POST", "/api/agent/pause", state);
+      await handleAgentLifecycleRoutes(ctx);
+      expect(state.agentState).toBe("paused");
+      expect(state.startedAt).toBe(started);
+    });
+  });
+
+  describe("POST /api/agent/resume", () => {
+    test("transitions to running", async () => {
+      const state = buildState({ agentState: "paused" });
+      const ctx = buildCtx("POST", "/api/agent/resume", state);
+      await handleAgentLifecycleRoutes(ctx);
+      expect(state.agentState).toBe("running");
+    });
+  });
+
+  describe("GET /api/agent/autonomy", () => {
+    test("returns enabled false when no runtime", async () => {
+      const state = buildState();
+      const ctx = buildCtx("GET", "/api/agent/autonomy", state);
+      await handleAgentLifecycleRoutes(ctx);
+      expect(ctx.json).toHaveBeenCalled();
+      const payload = (ctx.json as ReturnType<typeof vi.fn>).mock.calls[0][1];
+      expect(payload.enabled).toBe(false);
+    });
+
+    test("returns enabled true when runtime has autonomy", async () => {
+      const state = buildState({
+        runtime: { enableAutonomy: true } as any,
+      });
+      const ctx = buildCtx("GET", "/api/agent/autonomy", state);
+      await handleAgentLifecycleRoutes(ctx);
+      const payload = (ctx.json as ReturnType<typeof vi.fn>).mock.calls[0][1];
+      expect(payload.enabled).toBe(true);
+    });
+  });
+
+  describe("POST /api/agent/autonomy", () => {
+    test("sets autonomy on runtime", async () => {
+      const runtime = { enableAutonomy: false } as any;
+      const state = buildState({ runtime });
+      const ctx = buildCtx("POST", "/api/agent/autonomy", state, {
+        readJsonBody: vi.fn(async () => ({ enabled: true })),
+      });
+      await handleAgentLifecycleRoutes(ctx);
+      expect(runtime.enableAutonomy).toBe(true);
+    });
+
+    test("rejects non-boolean enabled", async () => {
+      const state = buildState({ runtime: {} as any });
+      const ctx = buildCtx("POST", "/api/agent/autonomy", state, {
+        readJsonBody: vi.fn(async () => ({ enabled: "yes" })),
+      });
+      await handleAgentLifecycleRoutes(ctx);
+      expect(ctx.error).toHaveBeenCalled();
+    });
+
+    test("rejects when no runtime", async () => {
+      const state = buildState();
+      const ctx = buildCtx("POST", "/api/agent/autonomy", state, {
+        readJsonBody: vi.fn(async () => ({ enabled: true })),
+      });
+      await handleAgentLifecycleRoutes(ctx);
+      expect(ctx.error).toHaveBeenCalled();
+    });
+  });
+
+  describe("routing", () => {
+    test("unrelated path returns false", async () => {
+      const state = buildState();
+      const ctx = buildCtx("GET", "/api/other", state);
+      expect(await handleAgentLifecycleRoutes(ctx)).toBe(false);
+    });
+  });
+});

package/test/api/agent-transfer-routes.test.ts

@@ -0,0 +1,136 @@
+import { describe, test, expect, vi } from "vitest";
+import {
+  createMockIncomingMessage,
+  createMockHttpResponse,
+} from "../../src/test-support/test-helpers";
+import { handleAgentTransferRoutes } from "../../src/api/agent-transfer-routes";
+import type { AgentTransferRouteContext } from "../../src/api/agent-transfer-routes";
+
+function buildCtx(
+  method: string,
+  pathname: string,
+  overrides?: Partial<AgentTransferRouteContext>,
+): AgentTransferRouteContext & {
+  getStatus: () => number;
+  getJson: () => unknown;
+} {
+  const { res, getStatus, getJson } = createMockHttpResponse();
+  const req = createMockIncomingMessage({ method, url: pathname });
+  const ctx = {
+    req,
+    res,
+    method,
+    pathname,
+    json: vi.fn((r, data, status = 200) => {
+      r.writeHead(status);
+      r.end(JSON.stringify(data));
+    }),
+    error: vi.fn((r, msg, status = 500) => {
+      r.writeHead(status);
+      r.end(JSON.stringify({ error: msg }));
+    }),
+    readJsonBody: vi.fn(async () => null),
+    state: {
+      runtime: null,
+    },
+    exportAgent: vi.fn(async () => Buffer.from("exported")),
+    estimateExportSize: vi.fn(async () => ({ estimatedBytes: 1024 })),
+    importAgent: vi.fn(async () => ({ ok: true })),
+    isAgentExportError: () => false,
+    ...overrides,
+  } as AgentTransferRouteContext & {
+    getStatus: () => number;
+    getJson: () => unknown;
+  };
+  (ctx as any).getStatus = getStatus;
+  (ctx as any).getJson = getJson;
+  return ctx;
+}
+
+describe("agent-transfer-routes", () => {
+  describe("POST /api/agent/export", () => {
+    test("returns 503 when no runtime", async () => {
+      const ctx = buildCtx("POST", "/api/agent/export");
+      const handled = await handleAgentTransferRoutes(ctx);
+      expect(handled).toBe(true);
+      expect(ctx.error).toHaveBeenCalledOnce();
+      const args = (ctx.error as ReturnType<typeof vi.fn>).mock.calls[0];
+      expect(args[2]).toBe(503);
+      expect(args[1]).toContain("not running");
+    });
+
+    test("returns 400 when password is missing", async () => {
+      const mockRuntime = { character: { name: "Agent" } } as any;
+      const ctx = buildCtx("POST", "/api/agent/export", {
+        state: { runtime: mockRuntime },
+        readJsonBody: vi.fn(async () => ({})),
+      });
+      const handled = await handleAgentTransferRoutes(ctx);
+      expect(handled).toBe(true);
+      expect(ctx.error).toHaveBeenCalledOnce();
+      const args = (ctx.error as ReturnType<typeof vi.fn>).mock.calls[0];
+      expect(args[2]).toBe(400);
+    });
+
+    test("exports successfully with valid password", async () => {
+      const mockRuntime = { character: { name: "Agent" } } as any;
+      const ctx = buildCtx("POST", "/api/agent/export", {
+        state: { runtime: mockRuntime },
+        readJsonBody: vi.fn(async () => ({
+          password: "secret1234",
+          includeLogs: false,
+        })),
+      });
+      const handled = await handleAgentTransferRoutes(ctx);
+      expect(handled).toBe(true);
+      expect(ctx.exportAgent).toHaveBeenCalledOnce();
+      expect(ctx.error).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("GET /api/agent/export/estimate", () => {
+    test("returns 503 when no runtime", async () => {
+      const ctx = buildCtx("GET", "/api/agent/export/estimate");
+      const handled = await handleAgentTransferRoutes(ctx);
+      expect(handled).toBe(true);
+      expect(ctx.error).toHaveBeenCalledOnce();
+      const args = (ctx.error as ReturnType<typeof vi.fn>).mock.calls[0];
+      expect(args[2]).toBe(503);
+    });
+
+    test("returns estimate when runtime is available", async () => {
+      const mockRuntime = { character: { name: "Agent" } } as any;
+      const ctx = buildCtx("GET", "/api/agent/export/estimate", {
+        state: { runtime: mockRuntime },
+      });
+      const handled = await handleAgentTransferRoutes(ctx);
+      expect(handled).toBe(true);
+      expect(ctx.json).toHaveBeenCalledOnce();
+      expect(ctx.estimateExportSize).toHaveBeenCalledWith(mockRuntime);
+    });
+  });
+
+  describe("POST /api/agent/import", () => {
+    test("returns 503 when no runtime", async () => {
+      const ctx = buildCtx("POST", "/api/agent/import");
+      const handled = await handleAgentTransferRoutes(ctx);
+      expect(handled).toBe(true);
+      expect(ctx.error).toHaveBeenCalledOnce();
+      const args = (ctx.error as ReturnType<typeof vi.fn>).mock.calls[0];
+      expect(args[2]).toBe(503);
+      expect(args[1]).toContain("not running");
+    });
+  });
+
+  describe("routing", () => {
+    test("unrelated path returns false", async () => {
+      const ctx = buildCtx("GET", "/api/other");
+      expect(await handleAgentTransferRoutes(ctx)).toBe(false);
+    });
+
+    test("wrong method for export returns false", async () => {
+      const ctx = buildCtx("GET", "/api/agent/export");
+      expect(await handleAgentTransferRoutes(ctx)).toBe(false);
+    });
+  });
+});