@elizaos/agent 0.25.9 → 2.0.0-alpha.144

package/packages/agent/src/api/app-package-routes.d.ts

@@ -0,0 +1,7 @@
+import type { RouteHelpers, RouteRequestMeta } from "./route-helpers.js";
+export interface AppPackageRouteContext extends RouteRequestMeta, Pick<RouteHelpers, "error" | "json" | "readJsonBody"> {
+    url: URL;
+    runtime: unknown | null;
+}
+export declare function handleAppPackageRoutes(ctx: AppPackageRouteContext): Promise<boolean>;
+//# sourceMappingURL=app-package-routes.d.ts.map

package/packages/agent/src/api/app-package-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-package-routes.d.ts","sourceRoot":"","sources":["../../../../../src/api/app-package-routes.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEzE,MAAM,WAAW,sBACf,SAAQ,gBAAgB,EACtB,IAAI,CAAC,YAAY,EAAE,OAAO,GAAG,MAAM,GAAG,cAAc,CAAC;IACvD,GAAG,EAAE,GAAG,CAAC;IACT,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;CACzB;AAiDD,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,sBAAsB,GAC1B,OAAO,CAAC,OAAO,CAAC,CAoBlB"}

package/packages/agent/src/api/app-package-routes.js

@@ -0,0 +1,59 @@
+import { importAppRouteModule, } from "../services/app-package-modules.js";
+const RESERVED_APP_ROUTE_SLUGS = new Set([
+    "",
+    "info",
+    "installed",
+    "launch",
+    "plugins",
+    "refresh",
+    "runs",
+    "search",
+    "stop",
+]);
+function extractAppSlug(pathname) {
+    const match = pathname.match(/^\/api\/apps\/([^/]+)(?:\/|$)/);
+    if (!match?.[1])
+        return null;
+    const slug = decodeURIComponent(match[1]).trim();
+    if (!slug || RESERVED_APP_ROUTE_SLUGS.has(slug)) {
+        return null;
+    }
+    return slug;
+}
+function toLegacyHandlerName(slug) {
+    const normalized = slug
+        .split(/[^a-zA-Z0-9]+/)
+        .filter((part) => part.length > 0)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join("");
+    return `handleApps${normalized}Routes`;
+}
+function resolveAppRouteHandler(routeModule, slug) {
+    if (typeof routeModule.handleAppRoutes === "function") {
+        return routeModule.handleAppRoutes;
+    }
+    const legacyHandler = routeModule[toLegacyHandlerName(slug)];
+    if (typeof legacyHandler === "function") {
+        return legacyHandler;
+    }
+    return null;
+}
+export async function handleAppPackageRoutes(ctx) {
+    const slug = extractAppSlug(ctx.pathname);
+    if (!slug)
+        return false;
+    const routeModule = await importAppRouteModule(slug);
+    if (!routeModule)
+        return false;
+    const handler = resolveAppRouteHandler(routeModule, slug);
+    if (!handler)
+        return false;
+    // App route handlers expect readJsonBody pre-bound to the current request,
+    // but the server-level helper requires (req, res) arguments.  Wrap it so
+    // handlers can call readJsonBody() with no arguments.
+    const boundCtx = {
+        ...ctx,
+        readJsonBody: (() => ctx.readJsonBody(ctx.req, ctx.res)),
+    };
+    return handler(boundCtx);
+}

package/packages/agent/src/api/apps-routes.d.ts

@@ -0,0 +1,24 @@
+import type { IAgentRuntime } from "@elizaos/core";
+import type { InstallProgressLike, PluginManagerLike } from "../services/plugin-manager-types.js";
+import type { RouteHelpers, RouteRequestMeta } from "./route-helpers.js";
+export interface AppManagerLike {
+    listAvailable: (pluginManager: PluginManagerLike) => Promise<unknown>;
+    search: (pluginManager: PluginManagerLike, query: string, limit?: number) => Promise<unknown>;
+    listInstalled: (pluginManager: PluginManagerLike) => Promise<unknown>;
+    listRuns: (runtime?: IAgentRuntime | null) => Promise<unknown>;
+    getRun: (runId: string, runtime?: IAgentRuntime | null) => Promise<unknown>;
+    attachRun: (runId: string, runtime?: IAgentRuntime | null) => Promise<unknown>;
+    detachRun: (runId: string) => Promise<unknown>;
+    launch: (pluginManager: PluginManagerLike, name: string, onProgress?: (progress: InstallProgressLike) => void, runtime?: unknown | null) => Promise<unknown>;
+    stop: (pluginManager: PluginManagerLike, name: string, runId?: string) => Promise<unknown>;
+    getInfo: (pluginManager: PluginManagerLike, name: string) => Promise<unknown>;
+}
+export interface AppsRouteContext extends RouteRequestMeta, Pick<RouteHelpers, "readJsonBody" | "json" | "error"> {
+    url: URL;
+    appManager: AppManagerLike;
+    getPluginManager: () => PluginManagerLike;
+    parseBoundedLimit: (rawLimit: string | null, fallback?: number) => number;
+    runtime: unknown | null;
+}
+export declare function handleAppsRoutes(ctx: AppsRouteContext): Promise<boolean>;
+//# sourceMappingURL=apps-routes.d.ts.map

package/packages/agent/src/api/apps-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apps-routes.d.ts","sourceRoot":"","sources":["../../../../../src/api/apps-routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAUnD,OAAO,KAAK,EACV,mBAAmB,EACnB,iBAAiB,EAGlB,MAAM,qCAAqC,CAAC;AAK7C,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEzE,MAAM,WAAW,cAAc;IAC7B,aAAa,EAAE,CAAC,aAAa,EAAE,iBAAiB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACtE,MAAM,EAAE,CACN,aAAa,EAAE,iBAAiB,EAChC,KAAK,EAAE,MAAM,EACb,KAAK,CAAC,EAAE,MAAM,KACX,OAAO,CAAC,OAAO,CAAC,CAAC;IACtB,aAAa,EAAE,CAAC,aAAa,EAAE,iBAAiB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACtE,QAAQ,EAAE,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,IAAI,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/D,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,IAAI,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5E,SAAS,EAAE,CACT,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,aAAa,GAAG,IAAI,KAC3B,OAAO,CAAC,OAAO,CAAC,CAAC;IACtB,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/C,MAAM,EAAE,CACN,aAAa,EAAE,iBAAiB,EAChC,IAAI,EAAE,MAAM,EACZ,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,mBAAmB,KAAK,IAAI,EACpD,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,KACrB,OAAO,CAAC,OAAO,CAAC,CAAC;IACtB,IAAI,EAAE,CACJ,aAAa,EAAE,iBAAiB,EAChC,IAAI,EAAE,MAAM,EACZ,KAAK,CAAC,EAAE,MAAM,KACX,OAAO,CAAC,OAAO,CAAC,CAAC;IACtB,OAAO,EAAE,CAAC,aAAa,EAAE,iBAAiB,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC/E;AA4BD,MAAM,WAAW,gBACf,SAAQ,gBAAgB,EACtB,IAAI,CAAC,YAAY,EAAE,cAAc,GAAG,MAAM,GAAG,OAAO,CAAC;IACvD,GAAG,EAAE,GAAG,CAAC;IACT,UAAU,EAAE,cAAc,CAAC;IAC3B,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;IAC1C,iBAAiB,EAAE,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,EAAE,QAAQ,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAC1E,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;CACzB;AAiUD,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,gBAAgB,GACpB,OAAO,CAAC,OAAO,CAAC,CAkTlB"}

package/packages/agent/src/api/apps-routes.js

@@ -0,0 +1,477 @@
+import { hasAppInterface, packageNameToAppRouteSlug, } from "../contracts/apps.js";
+import { importAppRouteModule } from "../services/app-package-modules.js";
+import { setOverlayAppPresence } from "../services/overlay-app-presence.js";
+import { scoreEntries, toSearchResults, } from "../services/registry-client-queries.js";
+function isNonAppRegistryPlugin(plugin) {
+    return !hasAppInterface(plugin);
+}
+function actionResultStatus(result) {
+    if (result &&
+        typeof result === "object" &&
+        "success" in result &&
+        result.success === false) {
+        return 404;
+    }
+    return 200;
+}
+function createCapturedResponse() {
+    const headers = new Map();
+    let body = "";
+    let statusCode = 200;
+    const response = {
+        get statusCode() {
+            return statusCode;
+        },
+        set statusCode(value) {
+            statusCode = value;
+        },
+        headers: Object.create(null),
+        body,
+        setHeader(name, value) {
+            const normalized = Array.isArray(value)
+                ? value.join(", ")
+                : String(value);
+            headers.set(name.toLowerCase(), normalized);
+            response.headers[name.toLowerCase()] = normalized;
+        },
+        getHeader(name) {
+            return headers.get(name.toLowerCase());
+        },
+        removeHeader(name) {
+            headers.delete(name.toLowerCase());
+            delete response.headers[name.toLowerCase()];
+        },
+        writeHead(nextStatusCode, nextHeaders) {
+            statusCode = nextStatusCode;
+            if (nextHeaders) {
+                for (const [name, value] of Object.entries(nextHeaders)) {
+                    response.setHeader(name, value.toString());
+                }
+            }
+            return response;
+        },
+        end(chunk) {
+            if (chunk === undefined || chunk === null) {
+                response.body = body;
+                return;
+            }
+            body += Buffer.isBuffer(chunk)
+                ? chunk.toString("utf8")
+                : typeof chunk === "string"
+                    ? chunk
+                    : String(chunk);
+            response.body = body;
+        },
+    };
+    return response;
+}
+function parseCapturedBody(body) {
+    const trimmed = body.trim();
+    if (!trimmed)
+        return null;
+    try {
+        const parsed = JSON.parse(trimmed);
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+function readSteeringContent(body) {
+    const content = typeof body?.content === "string"
+        ? body.content
+        : typeof body?.message === "string"
+            ? body.message
+            : null;
+    const trimmed = content?.trim() ?? "";
+    return trimmed.length > 0 ? trimmed : null;
+}
+function readSteeringAction(body) {
+    const action = typeof body?.action === "string" ? body.action.trim() : "";
+    if (action === "pause" || action === "resume")
+        return action;
+    return null;
+}
+function isAppRunSummary(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.runId === "string" &&
+        typeof value.appName === "string" &&
+        typeof value.displayName === "string");
+}
+function resolveRunSteeringTarget(run, subroute) {
+    const routeSlug = packageNameToAppRouteSlug(run.appName) ?? run.appName;
+    if (!routeSlug)
+        return null;
+    if (routeSlug === "babylon") {
+        if (subroute === "message") {
+            return {
+                pathname: `/api/apps/${encodeURIComponent(routeSlug)}/agent/chat`,
+            };
+        }
+        if (subroute === "control") {
+            return {
+                pathname: `/api/apps/${encodeURIComponent(routeSlug)}/agent/toggle`,
+            };
+        }
+        return null;
+    }
+    if (!run.session?.sessionId) {
+        return null;
+    }
+    return {
+        pathname: `/api/apps/${encodeURIComponent(routeSlug)}/session/${encodeURIComponent(run.session.sessionId)}/${subroute}`,
+    };
+}
+function buildSteeringDisposition(run, subroute, upstreamStatus, upstreamBody) {
+    const upstreamMessage = typeof upstreamBody?.message === "string"
+        ? upstreamBody.message.toLowerCase()
+        : typeof upstreamBody?.error === "string"
+            ? upstreamBody.error.toLowerCase()
+            : "";
+    const upstreamDisposition = upstreamBody?.disposition;
+    if (upstreamDisposition === "accepted" ||
+        upstreamDisposition === "queued" ||
+        upstreamDisposition === "rejected" ||
+        upstreamDisposition === "unsupported") {
+        return upstreamDisposition;
+    }
+    if (upstreamStatus === 202)
+        return "queued";
+    if (upstreamStatus === 404) {
+        return upstreamMessage.includes("not found") ||
+            upstreamMessage.includes("not available") ||
+            upstreamMessage.includes("unavailable")
+            ? "unsupported"
+            : "rejected";
+    }
+    if (upstreamStatus >= 500)
+        return "unsupported";
+    if (upstreamStatus >= 400)
+        return "rejected";
+    const success = upstreamBody?.success === true || upstreamBody?.ok === true;
+    if (!success) {
+        return upstreamStatus >= 500 ? "unsupported" : "rejected";
+    }
+    if (run.appName === "@elizaos/app-2004scape" && subroute === "message") {
+        return "queued";
+    }
+    return "accepted";
+}
+async function proxyRunSteeringRequest(ctx, run, subroute, body) {
+    const target = resolveRunSteeringTarget(run, subroute);
+    if (!target) {
+        return {
+            success: false,
+            message: subroute === "message"
+                ? `Run-scoped messaging is unavailable for "${run.displayName}".`
+                : `Run-scoped controls are unavailable for "${run.displayName}".`,
+            disposition: "unsupported",
+            status: 501,
+            run,
+            session: run.session ?? null,
+        };
+    }
+    const routeModule = await importAppRouteModule(run.appName);
+    if (typeof routeModule?.handleAppRoutes !== "function") {
+        return {
+            success: false,
+            message: subroute === "message"
+                ? `Run-scoped messaging is unavailable for "${run.displayName}" because its route module does not expose a steering handler.`
+                : `Run-scoped controls are unavailable for "${run.displayName}" because its route module does not expose a steering handler.`,
+            disposition: "unsupported",
+            status: 501,
+            run,
+            session: run.session ?? null,
+        };
+    }
+    const captured = createCapturedResponse();
+    const syntheticUrl = new URL(ctx.url.toString());
+    syntheticUrl.pathname = target.pathname;
+    const syntheticCtx = {
+        ...ctx,
+        pathname: target.pathname,
+        url: syntheticUrl,
+        res: captured,
+        readJsonBody: async () => body,
+        json: (response, data, status = 200) => {
+            response.writeHead(status, { "Content-Type": "application/json" });
+            response.end(JSON.stringify(data));
+        },
+        error: (response, message, status = 500) => {
+            response.writeHead(status, { "Content-Type": "application/json" });
+            response.end(JSON.stringify({ error: message }));
+        },
+    };
+    const handled = await routeModule.handleAppRoutes(syntheticCtx);
+    if (!handled) {
+        return {
+            success: false,
+            message: subroute === "message"
+                ? `Run-scoped messaging is unavailable for "${run.displayName}".`
+                : `Run-scoped controls are unavailable for "${run.displayName}".`,
+            disposition: "unsupported",
+            status: 501,
+            run,
+            session: run.session ?? null,
+        };
+    }
+    const upstreamBody = parseCapturedBody(captured.body);
+    const refreshedRunCandidate = await ctx.appManager.getRun(run.runId, ctx.runtime);
+    const refreshedRun = isAppRunSummary(refreshedRunCandidate)
+        ? refreshedRunCandidate
+        : run;
+    const disposition = buildSteeringDisposition(refreshedRun, subroute, captured.statusCode, upstreamBody);
+    const success = upstreamBody?.success === true || upstreamBody?.ok === true
+        ? true
+        : disposition === "accepted" || disposition === "queued";
+    const message = typeof upstreamBody?.message === "string" && upstreamBody.message.trim()
+        ? upstreamBody.message.trim()
+        : disposition === "queued"
+            ? "Command queued."
+            : disposition === "accepted"
+                ? "Command accepted."
+                : disposition === "unsupported"
+                    ? "This run does not support that steering channel."
+                    : "Command rejected.";
+    return {
+        success,
+        message,
+        disposition,
+        status: disposition === "queued"
+            ? 202
+            : disposition === "rejected" && captured.statusCode < 400
+                ? 409
+                : disposition === "unsupported"
+                    ? Math.max(captured.statusCode, 501)
+                    : captured.statusCode,
+        run: refreshedRun,
+        session: upstreamBody?.session ??
+            refreshedRun.session ??
+            null,
+    };
+}
+export async function handleAppsRoutes(ctx) {
+    const { req, res, method, pathname, url, appManager, getPluginManager, parseBoundedLimit, readJsonBody, json, error, runtime, } = ctx;
+    if (method === "GET" && pathname === "/api/apps") {
+        const pluginManager = getPluginManager();
+        const apps = await appManager.listAvailable(pluginManager);
+        json(res, apps);
+        return true;
+    }
+    if (method === "GET" && pathname === "/api/apps/search") {
+        const query = url.searchParams.get("q") ?? "";
+        if (!query.trim()) {
+            json(res, []);
+            return true;
+        }
+        const limit = parseBoundedLimit(url.searchParams.get("limit"));
+        const pluginManager = getPluginManager();
+        const results = await appManager.search(pluginManager, query, limit);
+        json(res, results);
+        return true;
+    }
+    if (method === "GET" && pathname === "/api/apps/installed") {
+        const pluginManager = getPluginManager();
+        const installed = await appManager.listInstalled(pluginManager);
+        json(res, installed);
+        return true;
+    }
+    if (method === "GET" && pathname === "/api/apps/runs") {
+        const runs = await appManager.listRuns(runtime);
+        json(res, runs);
+        return true;
+    }
+    // Dashboard heartbeat for overlay apps (companion, etc.) — no AppManager run.
+    if (method === "POST" && pathname === "/api/apps/overlay-presence") {
+        const body = await readJsonBody(req, res);
+        if (!body)
+            return true;
+        const raw = body.appName;
+        const appName = typeof raw === "string" && raw.trim().length > 0 ? raw.trim() : null;
+        setOverlayAppPresence(appName);
+        json(res, { ok: true, appName });
+        return true;
+    }
+    if (method === "GET" && pathname.startsWith("/api/apps/runs/")) {
+        const parts = pathname.split("/").filter(Boolean);
+        const runId = parts[3] ? decodeURIComponent(parts[3]) : "";
+        const subroute = parts[4] ?? "";
+        if (!runId) {
+            error(res, "runId is required");
+            return true;
+        }
+        if (!subroute) {
+            const run = await appManager.getRun(runId, runtime);
+            if (!run) {
+                error(res, `App run "${runId}" not found`, 404);
+                return true;
+            }
+            json(res, run);
+            return true;
+        }
+        if (subroute === "health") {
+            const run = await appManager.getRun(runId, runtime);
+            if (!run || typeof run !== "object" || run === null) {
+                error(res, `App run "${runId}" not found`, 404);
+                return true;
+            }
+            const health = "health" in run
+                ? run.health
+                : null;
+            json(res, health);
+            return true;
+        }
+    }
+    if (method === "POST" && pathname.startsWith("/api/apps/runs/")) {
+        const parts = pathname.split("/").filter(Boolean);
+        const runId = parts[3] ? decodeURIComponent(parts[3]) : "";
+        const subroute = parts[4] ?? "";
+        if (!runId || !subroute) {
+            error(res, "runId is required");
+            return true;
+        }
+        if (subroute === "attach") {
+            const result = await appManager.attachRun(runId, runtime);
+            json(res, result, actionResultStatus(result));
+            return true;
+        }
+        if (subroute === "message" || subroute === "control") {
+            const run = (await appManager.getRun(runId, runtime));
+            if (!run) {
+                error(res, `App run "${runId}" not found`, 404);
+                return true;
+            }
+            const body = subroute === "message"
+                ? await readJsonBody(req, res)
+                : await readJsonBody(req, res);
+            if (!body)
+                return true;
+            const normalizedBody = subroute === "message"
+                ? {
+                    content: readSteeringContent(body),
+                }
+                : {
+                    action: readSteeringAction(body),
+                };
+            if ((subroute === "message" && !normalizedBody.content) ||
+                (subroute === "control" && !normalizedBody.action)) {
+                error(res, subroute === "message"
+                    ? "content is required"
+                    : "action must be pause or resume", 400);
+                return true;
+            }
+            const result = await proxyRunSteeringRequest(ctx, run, subroute, normalizedBody);
+            if (!result) {
+                error(res, "Run steering failed", 500);
+                return true;
+            }
+            json(res, result, result.status);
+            return true;
+        }
+        if (subroute === "detach") {
+            const result = await appManager.detachRun(runId);
+            json(res, result, actionResultStatus(result));
+            return true;
+        }
+        if (subroute === "stop") {
+            const pluginManager = getPluginManager();
+            const result = await appManager.stop(pluginManager, "", runId);
+            json(res, result);
+            return true;
+        }
+    }
+    if (method === "POST" && pathname === "/api/apps/launch") {
+        try {
+            const body = await readJsonBody(req, res);
+            if (!body)
+                return true;
+            if (!body.name?.trim()) {
+                error(res, "name is required");
+                return true;
+            }
+            const pluginManager = getPluginManager();
+            const result = await appManager.launch(pluginManager, body.name.trim(), (_progress) => { }, runtime);
+            json(res, result);
+        }
+        catch (e) {
+            error(res, e instanceof Error ? e.message : "Failed to launch app", 500);
+        }
+        return true;
+    }
+    if (method === "POST" && pathname === "/api/apps/stop") {
+        const body = await readJsonBody(req, res);
+        if (!body)
+            return true;
+        if (!body.name?.trim() && !body.runId?.trim()) {
+            error(res, "name or runId is required");
+            return true;
+        }
+        const appName = body.name?.trim() ?? "";
+        const runId = body.runId?.trim();
+        const pluginManager = getPluginManager();
+        const result = await appManager.stop(pluginManager, appName, runId);
+        json(res, result);
+        return true;
+    }
+    if (method === "GET" && pathname.startsWith("/api/apps/info/")) {
+        const appName = decodeURIComponent(pathname.slice("/api/apps/info/".length));
+        if (!appName) {
+            error(res, "app name is required");
+            return true;
+        }
+        const pluginManager = getPluginManager();
+        const info = await appManager.getInfo(pluginManager, appName);
+        if (!info) {
+            error(res, `App "${appName}" not found in registry`, 404);
+            return true;
+        }
+        json(res, info);
+        return true;
+    }
+    if (method === "GET" && pathname === "/api/apps/plugins") {
+        try {
+            const pluginManager = getPluginManager();
+            const registry = await pluginManager.refreshRegistry();
+            const plugins = Array.from(registry.values()).filter(isNonAppRegistryPlugin);
+            json(res, plugins);
+        }
+        catch (err) {
+            error(res, `Failed to list plugins: ${err instanceof Error ? err.message : String(err)}`, 502);
+        }
+        return true;
+    }
+    if (method === "GET" && pathname === "/api/apps/plugins/search") {
+        const query = url.searchParams.get("q") ?? "";
+        if (!query.trim()) {
+            json(res, []);
+            return true;
+        }
+        try {
+            const limit = parseBoundedLimit(url.searchParams.get("limit"));
+            const pluginManager = getPluginManager();
+            const registry = await pluginManager.refreshRegistry();
+            const results = scoreEntries(Array.from(registry.values()).filter(isNonAppRegistryPlugin), query, limit);
+            json(res, toSearchResults(results));
+        }
+        catch (err) {
+            error(res, `Plugin search failed: ${err instanceof Error ? err.message : String(err)}`, 502);
+        }
+        return true;
+    }
+    if (method === "POST" && pathname === "/api/apps/refresh") {
+        try {
+            const pluginManager = getPluginManager();
+            const registry = await pluginManager.refreshRegistry();
+            const count = Array.from(registry.values()).filter(isNonAppRegistryPlugin).length;
+            json(res, { ok: true, count });
+        }
+        catch (err) {
+            error(res, `Refresh failed: ${err instanceof Error ? err.message : String(err)}`, 502);
+        }
+        return true;
+    }
+    return false;
+}

package/packages/agent/src/api/auth-routes.d.ts

@@ -0,0 +1,11 @@
+import type { RouteRequestContext } from "./route-helpers.js";
+export interface AuthRouteContext extends RouteRequestContext {
+    pairingEnabled: () => boolean;
+    ensurePairingCode: () => string | null;
+    normalizePairingCode: (code: string) => string;
+    rateLimitPairing: (ip: string | null) => boolean;
+    getPairingExpiresAt: () => number;
+    clearPairing: () => void;
+}
+export declare function handleAuthRoutes(ctx: AuthRouteContext): Promise<boolean>;
+//# sourceMappingURL=auth-routes.d.ts.map

package/packages/agent/src/api/auth-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-routes.d.ts","sourceRoot":"","sources":["../../../../../src/api/auth-routes.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAM9D,MAAM,WAAW,gBAAiB,SAAQ,mBAAmB;IAC3D,cAAc,EAAE,MAAM,OAAO,CAAC;IAC9B,iBAAiB,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IACvC,oBAAoB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IAC/C,gBAAgB,EAAE,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,KAAK,OAAO,CAAC;IACjD,mBAAmB,EAAE,MAAM,MAAM,CAAC;IAClC,YAAY,EAAE,MAAM,IAAI,CAAC;CAC1B;AAED,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,gBAAgB,GACpB,OAAO,CAAC,OAAO,CAAC,CA2FlB"}

package/packages/agent/src/api/auth-routes.js

@@ -0,0 +1,74 @@
+import crypto from "node:crypto";
+import { resolveApiToken } from "../config/runtime-env.js";
+import { isCloudProvisionedContainer } from "./cloud-provisioning.js";
+function getConfiguredApiToken() {
+    return resolveApiToken(process.env) ?? undefined;
+}
+export async function handleAuthRoutes(ctx) {
+    const { req, res, method, pathname, readJsonBody, json, error, pairingEnabled, ensurePairingCode, normalizePairingCode, rateLimitPairing, getPairingExpiresAt, clearPairing, } = ctx;
+    if (!pathname.startsWith("/api/auth/"))
+        return false;
+    if (method === "GET" && pathname === "/api/auth/status") {
+        if (isCloudProvisionedContainer()) {
+            // Steward-managed cloud containers enforce API auth upstream, but the
+            // local pairing flow is intentionally unavailable there. Reporting
+            // required=true would strand app-core clients in PairingView.
+            json(res, {
+                required: false,
+                pairingEnabled: false,
+                expiresAt: null,
+            });
+            return true;
+        }
+        const required = Boolean(getConfiguredApiToken());
+        const enabled = pairingEnabled();
+        if (enabled)
+            ensurePairingCode();
+        json(res, {
+            required,
+            pairingEnabled: enabled,
+            expiresAt: enabled ? getPairingExpiresAt() : null,
+        });
+        return true;
+    }
+    if (method === "POST" && pathname === "/api/auth/pair") {
+        const body = await readJsonBody(req, res);
+        if (!body)
+            return true;
+        if (isCloudProvisionedContainer()) {
+            error(res, "Pairing disabled", 403);
+            return true;
+        }
+        const token = getConfiguredApiToken();
+        if (!token) {
+            error(res, "Pairing not enabled", 400);
+            return true;
+        }
+        if (!pairingEnabled()) {
+            error(res, "Pairing disabled", 403);
+            return true;
+        }
+        if (!rateLimitPairing(req.socket.remoteAddress ?? null)) {
+            error(res, "Too many attempts. Try again later.", 429);
+            return true;
+        }
+        const provided = normalizePairingCode(body.code ?? "");
+        const current = ensurePairingCode();
+        if (!current || Date.now() > getPairingExpiresAt()) {
+            ensurePairingCode();
+            error(res, "Pairing code expired. Check server logs for a new code.", 410);
+            return true;
+        }
+        const expected = normalizePairingCode(current);
+        const a = Buffer.from(expected, "utf8");
+        const b = Buffer.from(provided, "utf8");
+        if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
+            error(res, "Invalid pairing code", 403);
+            return true;
+        }
+        clearPairing();
+        json(res, { token });
+        return true;
+    }
+    return false;
+}

package/packages/agent/src/api/avatar-routes.d.ts

@@ -0,0 +1,11 @@
+import type http from "node:http";
+export interface AvatarRouteContext {
+    req: http.IncomingMessage;
+    res: http.ServerResponse;
+    method: string;
+    pathname: string;
+    json: (res: http.ServerResponse, data: unknown, status?: number) => void;
+    error: (res: http.ServerResponse, message: string, status?: number) => void;
+}
+export declare function handleAvatarRoutes(ctx: AvatarRouteContext): Promise<boolean>;
+//# sourceMappingURL=avatar-routes.d.ts.map