@elizaos/app-hyperscape 1.0.0 → 2.0.0-beta.1

package/dist/index.d.ts

@@ -1,20 +1,13 @@
-import { Plugin } from '@elizaos/core';
-
+import type { Plugin } from "@elizaos/core";
 /**
- * @elizaos/app-hyperscape
+ * `@elizaos/app-hyperscape` plugin entry point.
  *
- * ElizaOS app for connecting AI agents to Hyperscape 3D multiplayer RPG worlds.
- * Agents can explore, fight, gather resources, craft items, bank, and chat.
- *
- * This is a "connect" type app — the agent plugin connects to an external
- * Hyperscape game server via WebSocket. The player opens the Hyperscape client
- * in their browser to watch their agent play.
- *
- * When the full @hyperscape/plugin-hyperscape is published to npm, this package
- * will re-export it. Until then, this provides the registry-compatible wrapper
- * with app metadata and basic configuration.
+ * Provides session resolvers for the Hyperscape game integration.
+ * The route module (`./routes.ts`) handles live session resolution
+ * by fetching data from the Hyperscape API.
  */
-
-declare const appHyperscape: Plugin;
-
-export { appHyperscape, appHyperscape as default };
+declare const hyperscapePlugin: Plugin;
+export default hyperscapePlugin;
+export * from "./routes.js";
+export * from "./ui/index.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAE5C;;;;;;GAMG;AACH,QAAA,MAAM,gBAAgB,EAAE,MAIvB,CAAC;AAEF,eAAe,gBAAgB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC"}

package/dist/index.js

@@ -1,51 +1,11 @@
-// src/index.ts
-import { logger } from "@elizaos/core";
-function env(key, fallback = "") {
-  const v = process.env[key]?.trim();
-  return v && v !== "undefined" && v !== "null" ? v : fallback;
-}
-var appHyperscape = {
+const hyperscapePlugin = {
   name: "@elizaos/app-hyperscape",
-  description: "Connect AI agents to Hyperscape 3D multiplayer RPG \u2014 explore, fight, gather, craft, and socialize",
-  config: {
-    HYPERSCAPE_SERVER_URL: env("HYPERSCAPE_SERVER_URL", "ws://localhost:5555/ws"),
-    HYPERSCAPE_AUTO_RECONNECT: env("HYPERSCAPE_AUTO_RECONNECT", "true"),
-    HYPERSCAPE_AUTH_TOKEN: env("HYPERSCAPE_AUTH_TOKEN"),
-    HYPERSCAPE_AUTONOMY_MODE: env("HYPERSCAPE_AUTONOMY_MODE", "llm")
-  },
-  init: async (_config, runtime) => {
-    const serverUrl = runtime.getSetting("HYPERSCAPE_SERVER_URL") || process.env.HYPERSCAPE_SERVER_URL || "ws://localhost:5555/ws";
-    logger.info(`[app-hyperscape] Configured for server: ${serverUrl}`);
-  },
-  app: {
-    displayName: "Hyperscape",
-    category: "game",
-    launchType: "connect",
-    launchUrl: "https://hyperscape.ai",
-    capabilities: [
-      "combat",
-      "skills",
-      "inventory",
-      "banking",
-      "social-chat",
-      "exploration",
-      "crafting"
-    ],
-    viewer: {
-      url: "http://localhost:3333",
-      embedParams: {
-        embedded: "true",
-        mode: "spectator",
-        quality: "medium"
-      },
-      postMessageAuth: true,
-      sandbox: "allow-scripts allow-same-origin allow-popups allow-forms"
-    }
-  }
+  description: "Hyperscape game session resolvers \u2014 spectate-and-steer agent sessions with live data from the Hyperscape API."
 };
-var index_default = appHyperscape;
+var index_default = hyperscapePlugin;
+export * from "./routes.js";
+export * from "./ui/index.js";
 export {
-  appHyperscape,
   index_default as default
 };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * @elizaos/app-hyperscape\n *\n * ElizaOS app for connecting AI agents to Hyperscape 3D multiplayer RPG worlds.\n * Agents can explore, fight, gather resources, craft items, bank, and chat.\n *\n * This is a \"connect\" type app — the agent plugin connects to an external\n * Hyperscape game server via WebSocket. The player opens the Hyperscape client\n * in their browser to watch their agent play.\n *\n * When the full @hyperscape/plugin-hyperscape is published to npm, this package\n * will re-export it. Until then, this provides the registry-compatible wrapper\n * with app metadata and basic configuration.\n */\n\nimport type { Plugin, IAgentRuntime } from \"@elizaos/core\";\nimport { logger } from \"@elizaos/core\";\n\n// ── Helpers ────────────────────────────────────────────────────────────────\n\n/** Read an env value, treating \"undefined\"/\"null\"/empty as missing. */\nfunction env(key: string, fallback = \"\"): string {\n  const v = process.env[key]?.trim();\n  return v && v !== \"undefined\" && v !== \"null\" ? v : fallback;\n}\n\n// ── Plugin Definition ──────────────────────────────────────────────────────\n\nexport const appHyperscape = {\n  name: \"@elizaos/app-hyperscape\",\n  description:\n    \"Connect AI agents to Hyperscape 3D multiplayer RPG — explore, fight, gather, craft, and socialize\",\n\n  config: {\n    HYPERSCAPE_SERVER_URL: env(\"HYPERSCAPE_SERVER_URL\", \"ws://localhost:5555/ws\"),\n    HYPERSCAPE_AUTO_RECONNECT: env(\"HYPERSCAPE_AUTO_RECONNECT\", \"true\"),\n    HYPERSCAPE_AUTH_TOKEN: env(\"HYPERSCAPE_AUTH_TOKEN\"),\n    HYPERSCAPE_AUTONOMY_MODE: env(\"HYPERSCAPE_AUTONOMY_MODE\", \"llm\"),\n  },\n\n  init: async (_config: Record<string, string>, runtime: IAgentRuntime) => {\n    const serverUrl =\n      runtime.getSetting(\"HYPERSCAPE_SERVER_URL\") ||\n      process.env.HYPERSCAPE_SERVER_URL ||\n      \"ws://localhost:5555/ws\";\n    logger.info(`[app-hyperscape] Configured for server: ${serverUrl}`);\n  },\n\n  app: {\n    displayName: \"Hyperscape\",\n    category: \"game\",\n    launchType: \"connect\",\n    launchUrl: \"https://hyperscape.ai\",\n    capabilities: [\n      \"combat\",\n      \"skills\",\n      \"inventory\",\n      \"banking\",\n      \"social-chat\",\n      \"exploration\",\n      \"crafting\",\n    ],\n    viewer: {\n      url: \"http://localhost:3333\",\n      embedParams: {\n        embedded: \"true\",\n        mode: \"spectator\",\n        quality: \"medium\",\n      },\n      postMessageAuth: true,\n      sandbox: \"allow-scripts allow-same-origin allow-popups allow-forms\",\n    },\n  },\n} as Plugin;\n\nexport default appHyperscape;\n"],"mappings":";AAgBA,SAAS,cAAc;AAKvB,SAAS,IAAI,KAAa,WAAW,IAAY;AAC/C,QAAM,IAAI,QAAQ,IAAI,GAAG,GAAG,KAAK;AACjC,SAAO,KAAK,MAAM,eAAe,MAAM,SAAS,IAAI;AACtD;AAIO,IAAM,gBAAgB;AAAA,EAC3B,MAAM;AAAA,EACN,aACE;AAAA,EAEF,QAAQ;AAAA,IACN,uBAAuB,IAAI,yBAAyB,wBAAwB;AAAA,IAC5E,2BAA2B,IAAI,6BAA6B,MAAM;AAAA,IAClE,uBAAuB,IAAI,uBAAuB;AAAA,IAClD,0BAA0B,IAAI,4BAA4B,KAAK;AAAA,EACjE;AAAA,EAEA,MAAM,OAAO,SAAiC,YAA2B;AACvE,UAAM,YACJ,QAAQ,WAAW,uBAAuB,KAC1C,QAAQ,IAAI,yBACZ;AACF,WAAO,KAAK,2CAA2C,SAAS,EAAE;AAAA,EACpE;AAAA,EAEA,KAAK;AAAA,IACH,aAAa;AAAA,IACb,UAAU;AAAA,IACV,YAAY;AAAA,IACZ,WAAW;AAAA,IACX,cAAc;AAAA,MACZ;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF;AAAA,IACA,QAAQ;AAAA,MACN,KAAK;AAAA,MACL,aAAa;AAAA,QACX,UAAU;AAAA,QACV,MAAM;AAAA,QACN,SAAS;AAAA,MACX;AAAA,MACA,iBAAiB;AAAA,MACjB,SAAS;AAAA,IACX;AAAA,EACF;AACF;AAEA,IAAO,gBAAQ;","names":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import type { Plugin } from \"@elizaos/core\";\n\n/**\n * `@elizaos/app-hyperscape` plugin entry point.\n *\n * Provides session resolvers for the Hyperscape game integration.\n * The route module (`./routes.ts`) handles live session resolution\n * by fetching data from the Hyperscape API.\n */\nconst hyperscapePlugin: Plugin = {\n  name: \"@elizaos/app-hyperscape\",\n  description:\n    \"Hyperscape game session resolvers — spectate-and-steer agent sessions with live data from the Hyperscape API.\",\n};\n\nexport default hyperscapePlugin;\nexport * from \"./routes.js\";\nexport * from \"./ui/index.js\";\n"],"mappings":"AASA,MAAM,mBAA2B;AAAA,EAC/B,MAAM;AAAA,EACN,aACE;AACJ;AAEA,IAAO,gBAAQ;AACf,cAAc;AACd,cAAc;","names":[]}

package/dist/routes.d.ts

@@ -1,18 +1,22 @@
-import * as http from 'node:http';
-
-interface HyperscapeRelayOptions {
-    rawBodyOverride?: string;
-    contentTypeOverride?: string;
-}
-interface AppsHyperscapeRouteContext {
-    req: http.IncomingMessage;
-    res: http.ServerResponse;
-    method: string;
-    pathname: string;
-    readJsonBody: <T extends object>(req: http.IncomingMessage, res: http.ServerResponse) => Promise<T | null>;
-    error: (res: http.ServerResponse, message: string, status?: number) => void;
-    relayHyperscapeApi: (method: "GET" | "POST", path: string, options?: HyperscapeRelayOptions) => Promise<void>;
-}
-declare function handleAppsHyperscapeRoutes(ctx: AppsHyperscapeRouteContext): Promise<boolean>;
-
-export { type AppsHyperscapeRouteContext, type HyperscapeRelayOptions, handleAppsHyperscapeRoutes };
+import type { IAgentRuntime } from "@elizaos/core";
+import type { AppLaunchDiagnostic, AppLaunchPreparation, AppLaunchResult, AppLaunchSessionContext, AppRunSessionContext, AppSessionState, AppViewerAuthMessage } from "@elizaos/shared";
+export declare function prepareLaunch(ctx: {
+    runtime: IAgentRuntime | null;
+}): Promise<AppLaunchPreparation>;
+export declare function resolveViewerAuthMessage(ctx: {
+    runtime: IAgentRuntime | null;
+}): Promise<AppViewerAuthMessage | null>;
+export declare function collectLaunchDiagnostics(ctx: {
+    viewer: AppLaunchResult["viewer"] | null;
+}): Promise<AppLaunchDiagnostic[]>;
+export declare function resolveLaunchSession(ctx: AppLaunchSessionContext): Promise<AppSessionState | null>;
+/**
+ * Called by the host app-manager when the user stops the Hyperscape run.
+ * Hyperscape is a stateless session resolver against an external API —
+ * there are no local resources (WebSockets, timers, processes) to tear
+ * down. Iframe unmount is sufficient. This hook is present so the
+ * app-manager lifecycle path stays uniform across all game apps.
+ */
+export declare function stopRun(): Promise<void>;
+export declare function refreshRunSession(ctx: AppRunSessionContext): Promise<AppSessionState | null>;
+//# sourceMappingURL=routes.d.ts.map

package/dist/routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../src/routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnD,OAAO,KAAK,EACV,mBAAmB,EACnB,oBAAoB,EACpB,eAAe,EACf,uBAAuB,EACvB,oBAAoB,EAEpB,eAAe,EACf,oBAAoB,EACrB,MAAM,iBAAiB,CAAC;AAmczB,wBAAsB,aAAa,CAAC,GAAG,EAAE;IACvC,OAAO,EAAE,aAAa,GAAG,IAAI,CAAC;CAC/B,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAGhC;AAED,wBAAsB,wBAAwB,CAAC,GAAG,EAAE;IAClD,OAAO,EAAE,aAAa,GAAG,IAAI,CAAC;CAC/B,GAAG,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAsBvC;AAED,wBAAsB,wBAAwB,CAAC,GAAG,EAAE;IAClD,MAAM,EAAE,eAAe,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC;CAC1C,GAAG,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAYjC;AAED,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,uBAAuB,GAC3B,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CA6BjC;AAED;;;;;;GAMG;AACH,wBAAsB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAE7C;AAED,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,oBAAoB,GACxB,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAsBjC"}

package/dist/routes.js

@@ -1,88 +1,375 @@
-// src/routes.ts
-async function handleAppsHyperscapeRoutes(ctx) {
-  const {
-    req,
-    res,
-    method,
-    pathname,
-    relayHyperscapeApi,
-    readJsonBody,
-    error
-  } = ctx;
-  if (method === "GET" && pathname === "/api/apps/hyperscape/embedded-agents") {
-    await relayHyperscapeApi("GET", "/api/embedded-agents");
-    return true;
-  }
-  if (method === "POST" && pathname === "/api/apps/hyperscape/embedded-agents") {
-    await relayHyperscapeApi("POST", "/api/embedded-agents");
-    return true;
-  }
-  if (method === "POST") {
-    const embeddedActionMatch = pathname.match(
-      /^\/api\/apps\/hyperscape\/embedded-agents\/([^/]+)\/(start|stop|pause|resume|command)$/
-    );
-    if (embeddedActionMatch) {
-      const characterId = decodeURIComponent(embeddedActionMatch[1]);
-      const action = embeddedActionMatch[2];
-      await relayHyperscapeApi(
-        "POST",
-        `/api/embedded-agents/${encodeURIComponent(characterId)}/${action}`
-      );
-      return true;
-    }
-    const messageMatch = pathname.match(
-      /^\/api\/apps\/hyperscape\/agents\/([^/]+)\/message$/
-    );
-    if (messageMatch) {
-      const agentId = decodeURIComponent(messageMatch[1]);
-      const body = await readJsonBody(req, res);
-      if (!body) return true;
-      const content = body.content?.trim();
-      if (!content) {
-        error(res, "content is required");
-        return true;
+import { logger } from "@elizaos/core";
+const FETCH_TIMEOUT_MS = 8e3;
+const HYPERSCAPE_WALLET_AUTH_TIMEOUT_MS = 5e3;
+const THOUGHTS_LIMIT = 5;
+const HYPERSCAPE_SESSION_MODE = "spectate-and-steer";
+function normalizeStringSetting(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+function toAppSessionJsonValue(value, depth = 0) {
+  if (depth > 6) return null;
+  if (value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map((entry) => toAppSessionJsonValue(entry, depth + 1)).filter((entry) => entry !== void 0);
+  }
+  if (typeof value === "object") {
+    const record = {};
+    for (const [key, entry] of Object.entries(value)) {
+      const next = toAppSessionJsonValue(entry, depth + 1);
+      if (next !== void 0) {
+        record[key] = next;
       }
-      await relayHyperscapeApi(
-        "POST",
-        `/api/embedded-agents/${encodeURIComponent(agentId)}/command`,
-        {
-          rawBodyOverride: JSON.stringify({
-            command: "chat",
-            data: { message: content }
-          }),
-          contentTypeOverride: "application/json"
-        }
-      );
-      return true;
     }
+    return record;
+  }
+  return void 0;
+}
+function resolveSettingLike(runtime, key) {
+  const fromRuntime = typeof runtime?.getSetting === "function" ? runtime.getSetting(key) : null;
+  if (typeof fromRuntime === "string" && fromRuntime.trim().length > 0) {
+    return fromRuntime.trim();
+  }
+  const fromEnv = process.env[key];
+  if (typeof fromEnv === "string" && fromEnv.trim().length > 0) {
+    return fromEnv.trim();
+  }
+  return void 0;
+}
+function resolveApiBase(runtime) {
+  const rawCandidates = [
+    typeof runtime?.getSetting === "function" ? runtime.getSetting("HYPERSCAPE_API_URL") : null,
+    process.env.HYPERSCAPE_API_URL,
+    typeof runtime?.getSetting === "function" ? runtime.getSetting("HYPERSCAPE_CLIENT_URL") : null,
+    process.env.HYPERSCAPE_CLIENT_URL
+  ];
+  for (const raw of rawCandidates) {
+    const candidate = normalizeStringSetting(raw);
+    if (!candidate) continue;
+    try {
+      const parsed = new URL(candidate);
+      if (parsed.protocol !== "http:" && parsed.protocol !== "https:") continue;
+      return candidate.replace(/\/+$/, "");
+    } catch {
+    }
+  }
+  return null;
+}
+function resolveAgentId(runtime, viewer) {
+  const authMsg = viewer?.authMessage;
+  const fromViewer = typeof authMsg?.agentId === "string" ? authMsg.agentId : null;
+  const fromRuntime = typeof runtime?.agentId === "string" && runtime.agentId.trim() ? runtime.agentId.trim() : null;
+  return fromViewer || fromRuntime;
+}
+function resolveCharacterId(runtime, viewer) {
+  const authMsg = viewer?.authMessage;
+  const fromViewer = typeof authMsg?.characterId === "string" ? authMsg.characterId : null;
+  if (fromViewer) return fromViewer;
+  return normalizeStringSetting(
+    typeof runtime?.getSetting === "function" ? runtime.getSetting("HYPERSCAPE_CHARACTER_ID") : null
+  );
+}
+function normalizeAbsoluteHttpUrl(raw) {
+  if (!raw) return null;
+  try {
+    const parsed = new URL(raw);
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+      return null;
+    }
+    return raw.replace(/\/+$/, "");
+  } catch {
+    return null;
+  }
+}
+function persistCredential(runtime, key, value, secret = false) {
+  if (!runtime) {
+    return;
+  }
+  try {
+    runtime.setSetting?.(key, value, secret);
+  } catch (err) {
+    logger.error(`[hyperscape] Failed to persist credential "${key}": ${err}`);
+  }
+  const character = runtime.character;
+  if (!character.settings) {
+    character.settings = {};
+  }
+  if (!character.settings.secrets) {
+    character.settings.secrets = {};
+  }
+  character.settings.secrets[key] = value;
+  if (!character.secrets) {
+    character.secrets = {};
   }
-  if (method === "GET") {
-    const goalMatch = pathname.match(
-      /^\/api\/apps\/hyperscape\/agents\/([^/]+)\/goal$/
+  character.secrets[key] = value;
+}
+function resolveApiBaseUrl(runtime) {
+  const configuredUrl = resolveSettingLike(runtime, "HYPERSCAPE_API_URL");
+  const normalized = normalizeAbsoluteHttpUrl(configuredUrl);
+  if (configuredUrl && !normalized) {
+    logger.warn(
+      "[hyperscape] Ignoring invalid HYPERSCAPE_API_URL; expected an absolute http/https URL."
     );
-    if (goalMatch) {
-      const agentId = decodeURIComponent(goalMatch[1]);
-      await relayHyperscapeApi(
-        "GET",
-        `/api/agents/${encodeURIComponent(agentId)}/goal`
-      );
-      return true;
+  }
+  return normalized;
+}
+async function resolveRuntimeEvmAddress(runtime) {
+  let agent;
+  try {
+    if (typeof runtime.getAgent === "function" && runtime.agentId) {
+      agent = await runtime.getAgent(runtime.agentId);
     }
-    const quickActionsMatch = pathname.match(
-      /^\/api\/apps\/hyperscape\/agents\/([^/]+)\/quick-actions$/
+  } catch {
+    agent = null;
+  }
+  const walletAddresses = agent && typeof agent === "object" ? agent.walletAddresses : void 0;
+  const evm = walletAddresses?.evm?.trim();
+  if (evm) {
+    return evm;
+  }
+  const existingPk = resolveSettingLike(runtime, "EVM_PRIVATE_KEY")?.trim() || process.env.EVM_PRIVATE_KEY?.trim();
+  if (!existingPk) {
+    return null;
+  }
+  const walletApiModule = "@elizaos/agent";
+  const { deriveEvmAddress } = await import(
+    /* webpackIgnore: true */
+    walletApiModule
+  );
+  return deriveEvmAddress(existingPk);
+}
+async function prepareWalletAuthFromRuntime(runtime) {
+  if (!runtime) {
+    return;
+  }
+  if (resolveSettingLike(runtime, "HYPERSCAPE_AUTH_TOKEN")) {
+    return;
+  }
+  const base = resolveApiBaseUrl(runtime);
+  if (!base) {
+    return;
+  }
+  const evm = await resolveRuntimeEvmAddress(runtime);
+  if (!evm) {
+    logger.info(
+      "[hyperscape] Skipping wallet auth: no EVM address or EVM_PRIVATE_KEY is available."
     );
-    if (quickActionsMatch) {
-      const agentId = decodeURIComponent(quickActionsMatch[1]);
-      await relayHyperscapeApi(
-        "GET",
-        `/api/agents/${encodeURIComponent(agentId)}/quick-actions`
+    return;
+  }
+  try {
+    const walletAuthUrl = new URL("/api/agents/wallet-auth", `${base}/`);
+    const res = await fetch(walletAuthUrl, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        walletAddress: evm,
+        walletType: "evm",
+        agentName: runtime.character?.name,
+        agentId: runtime.agentId
+      }),
+      signal: AbortSignal.timeout(HYPERSCAPE_WALLET_AUTH_TIMEOUT_MS)
+    });
+    if (!res.ok) {
+      return;
+    }
+    const data = await res.json();
+    if (data.success !== true || typeof data.authToken !== "string") {
+      return;
+    }
+    persistCredential(runtime, "HYPERSCAPE_AUTH_TOKEN", data.authToken, true);
+    if (typeof data.characterId === "string" && data.characterId.trim()) {
+      persistCredential(
+        runtime,
+        "HYPERSCAPE_CHARACTER_ID",
+        data.characterId.trim()
       );
-      return true;
     }
+  } catch {
+  }
+}
+async function fetchJson(url) {
+  try {
+    const res = await fetch(url, {
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS)
+    });
+    if (!res.ok) return null;
+    return await res.json();
+  } catch {
+    return null;
+  }
+}
+async function fetchLiveData(base, agentId) {
+  const id = encodeURIComponent(agentId);
+  const [agentsRes, goalRes, quickActionsRes, thoughtsRes] = await Promise.all([
+    fetchJson(
+      `${base}/api/embedded-agents`
+    ),
+    fetchJson(`${base}/api/agents/${id}/goal`),
+    fetchJson(`${base}/api/agents/${id}/quick-actions`),
+    fetchJson(
+      `${base}/api/agents/${id}/thoughts?limit=${THOUGHTS_LIMIT}`
+    )
+  ]);
+  const agents = agentsRes?.agents ?? [];
+  const agentRecord = agents.find((a) => a.agentId === agentId) ?? (agents.length === 1 ? agents[0] : null) ?? null;
+  return {
+    agentRecord,
+    goal: goalRes?.goal ?? null,
+    goalsPaused: goalRes?.goalsPaused === true,
+    availableGoals: goalRes?.availableGoals ?? [],
+    quickCommands: quickActionsRes?.quickCommands ?? [],
+    nearbyLocations: quickActionsRes?.nearbyLocations ?? [],
+    thoughts: thoughtsRes?.thoughts ?? []
+  };
+}
+function buildSession(appName, agentId, characterId, data) {
+  const {
+    agentRecord,
+    goal,
+    goalsPaused,
+    availableGoals,
+    quickCommands,
+    nearbyLocations,
+    thoughts
+  } = data;
+  const isRunning = agentRecord?.state === "running";
+  const controls = isRunning ? ["pause"] : ["resume"];
+  const goalLabel = goal?.description ?? null;
+  const suggestedPrompts = quickCommands.filter((c) => c.available !== false && typeof c.command === "string").map((c) => c.command);
+  const recommendedGoals = availableGoals.map((g, i) => ({
+    id: `goal-${i}`,
+    type: g.type ?? "general",
+    description: g.description ?? "",
+    reason: typeof g.reason === "string" ? g.reason : null
+  }));
+  const recentThoughts = thoughts.slice(0, THOUGHTS_LIMIT).map((t) => ({
+    id: t.id,
+    type: t.type,
+    content: toAppSessionJsonValue(t.content) ?? null,
+    timestamp: t.timestamp
+  }));
+  const telemetry = {
+    goalsPaused,
+    availableGoalCount: availableGoals.length,
+    nearbyLocationCount: nearbyLocations.length
+  };
+  if (typeof agentRecord?.startedAt === "number") {
+    telemetry.startedAt = agentRecord.startedAt;
+  }
+  if (typeof agentRecord?.lastActivity === "number") {
+    telemetry.lastActivity = agentRecord.lastActivity;
+  }
+  if (recommendedGoals.length > 0) {
+    telemetry.recommendedGoals = recommendedGoals;
+  }
+  if (recentThoughts.length > 0) {
+    telemetry.recentThoughts = recentThoughts;
+  }
+  return {
+    sessionId: agentId,
+    appName,
+    mode: HYPERSCAPE_SESSION_MODE,
+    status: isRunning ? "running" : "connecting",
+    agentId,
+    characterId: characterId ?? void 0,
+    followEntity: characterId ?? void 0,
+    canSendCommands: true,
+    controls,
+    summary: isRunning ? null : "Connecting session...",
+    goalLabel,
+    suggestedPrompts,
+    telemetry
+  };
+}
+async function prepareLaunch(ctx) {
+  await prepareWalletAuthFromRuntime(ctx.runtime ?? null);
+  return {};
+}
+async function resolveViewerAuthMessage(ctx) {
+  const runtime = ctx.runtime ?? null;
+  const authToken = resolveSettingLike(runtime, "HYPERSCAPE_AUTH_TOKEN");
+  if (!authToken) {
+    return null;
+  }
+  const agentId = typeof runtime?.agentId === "string" && runtime.agentId.trim().length > 0 ? runtime.agentId.trim() : void 0;
+  if (!agentId) {
+    return null;
+  }
+  const characterId = resolveSettingLike(runtime, "HYPERSCAPE_CHARACTER_ID") ?? agentId;
+  return {
+    type: "HYPERSCAPE_AUTH",
+    authToken,
+    agentId,
+    characterId,
+    followEntity: characterId
+  };
+}
+async function collectLaunchDiagnostics(ctx) {
+  if (ctx.viewer?.postMessageAuth && !ctx.viewer.authMessage) {
+    return [
+      {
+        code: "hyperscape-auth-unavailable",
+        severity: "error",
+        message: "Hyperscape postMessage auth requires HYPERSCAPE_AUTH_TOKEN and a runtime agent id."
+      }
+    ];
+  }
+  return [];
+}
+async function resolveLaunchSession(ctx) {
+  const { appName, runtime, viewer } = ctx;
+  const base = resolveApiBase(runtime);
+  if (!base) {
+    logger.debug(
+      "[hyperscape] HYPERSCAPE_API_URL not configured; skipping live session resolution"
+    );
+    return null;
+  }
+  const agentId = resolveAgentId(runtime, viewer);
+  if (!agentId) {
+    logger.debug(
+      "[hyperscape] No agentId available; skipping live session resolution"
+    );
+    return null;
+  }
+  const characterId = resolveCharacterId(runtime, viewer);
+  try {
+    const data = await fetchLiveData(base, agentId);
+    return buildSession(appName, agentId, characterId, data);
+  } catch (err) {
+    logger.warn(
+      `[hyperscape] Failed to resolve live session: ${err instanceof Error ? err.message : String(err)}`
+    );
+    return null;
+  }
+}
+async function stopRun() {
+}
+async function refreshRunSession(ctx) {
+  const { appName, runtime, viewer, session } = ctx;
+  if (!session) return null;
+  const base = resolveApiBase(runtime);
+  if (!base) return null;
+  const agentId = session.agentId ?? resolveAgentId(runtime, viewer);
+  if (!agentId) return null;
+  const characterId = session.characterId ?? resolveCharacterId(runtime, viewer);
+  try {
+    const data = await fetchLiveData(base, agentId);
+    return buildSession(appName, agentId, characterId, data);
+  } catch (err) {
+    logger.warn(
+      `[hyperscape] Failed to refresh run session: ${err instanceof Error ? err.message : String(err)}`
+    );
+    return null;
   }
-  return false;
 }
 export {
-  handleAppsHyperscapeRoutes
+  collectLaunchDiagnostics,
+  prepareLaunch,
+  refreshRunSession,
+  resolveLaunchSession,
+  resolveViewerAuthMessage,
+  stopRun
 };
 //# sourceMappingURL=routes.js.map