@hyperdrive.bot/paseo-server 0.2.6

package/dist/server/executable-resolution/executable-resolution.js

@@ -0,0 +1,118 @@
+import { createRequire } from "node:module";
+import { existsSync } from "node:fs";
+import { execCommand } from "../utils/spawn.js";
+import { isWindowsCommandScript } from "../utils/windows-command.js";
+import { windowsExecutableResolution } from "./windows.js";
+export { quoteWindowsArgument, quoteWindowsCommand } from "../utils/windows-command.js";
+const require = createRequire(import.meta.url);
+const which = require("which");
+const PROBE_TIMEOUT_MS = 2000;
+function hasPathSeparator(value) {
+    return value.includes("/") || value.includes("\\");
+}
+async function enumerateCandidates(name) {
+    if (process.platform !== "win32" && existsSync("/usr/bin/which")) {
+        return enumerateCandidatesViaSystemWhich(name);
+    }
+    return enumerateCandidatesViaLibrary(name);
+}
+async function enumerateCandidatesViaSystemWhich(name) {
+    try {
+        const { stdout } = await execCommand("/usr/bin/which", ["-a", name], {
+            timeout: 3000,
+            killSignal: "SIGKILL",
+        });
+        return Array.from(new Set(stdout.trim().split("\n").filter(Boolean)));
+    }
+    catch {
+        return [];
+    }
+}
+async function enumerateCandidatesViaLibrary(name) {
+    let candidates;
+    try {
+        candidates = await which(name, { all: true });
+    }
+    catch (error) {
+        // `which` throws ENOENT when the command is absent from PATH.
+        if (error.code === "ENOENT") {
+            return [];
+        }
+        throw error;
+    }
+    const seen = new Set();
+    return candidates.filter((candidate) => {
+        if (seen.has(candidate)) {
+            return false;
+        }
+        seen.add(candidate);
+        return true;
+    });
+}
+export async function probeExecutable(executablePath, timeoutMs = PROBE_TIMEOUT_MS) {
+    try {
+        await execCommand(executablePath, ["--version"], {
+            timeout: timeoutMs,
+            killSignal: "SIGKILL",
+            maxBuffer: 64 * 1024,
+            shell: isWindowsCommandScript(executablePath),
+        });
+        return true;
+    }
+    catch (error) {
+        return classifyProbeError(error);
+    }
+}
+function classifyProbeError(error) {
+    const err = error;
+    if (err.killed) {
+        return true;
+    }
+    if (typeof err.code === "number") {
+        return true;
+    }
+    if (err.code === "ENOENT" ||
+        err.code === "EACCES" ||
+        err.code === "ENOEXEC" ||
+        err.code === "UNKNOWN") {
+        return false;
+    }
+    return false;
+}
+/**
+ * Check a literal executable path. PATH search is handled by findExecutable().
+ */
+export function executableExists(executablePath, exists = existsSync) {
+    if (process.platform === "win32") {
+        return windowsExecutableResolution.exists(executablePath, { exists });
+    }
+    return exists(executablePath) ? executablePath : null;
+}
+export async function findExecutable(name, probeTimeoutMs = PROBE_TIMEOUT_MS) {
+    const trimmed = name.trim();
+    if (!trimmed) {
+        return null;
+    }
+    if (process.platform === "win32") {
+        return windowsExecutableResolution.find(trimmed, {
+            enumeratePathCandidates: enumerateCandidates,
+            probeExecutable,
+            exists: existsSync,
+            probeTimeoutMs,
+        });
+    }
+    if (hasPathSeparator(trimmed)) {
+        return (await probeExecutable(trimmed, probeTimeoutMs)) ? trimmed : null;
+    }
+    const candidates = await enumerateCandidates(trimmed);
+    for (const candidate of candidates) {
+        if (await probeExecutable(candidate, probeTimeoutMs)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+export async function isCommandAvailable(command) {
+    return (await findExecutable(command)) !== null;
+}
+//# sourceMappingURL=executable-resolution.js.map

package/dist/server/executable-resolution/windows.d.ts

@@ -0,0 +1,18 @@
+interface WindowsFindExecutableOptions {
+    enumeratePathCandidates: (name: string) => Promise<string[]>;
+    probeExecutable: (executablePath: string, timeoutMs: number) => Promise<boolean>;
+    exists: (path: string) => boolean;
+    localAppData?: string;
+    probeTimeoutMs: number;
+}
+interface WindowsExecutableExistsOptions {
+    exists: (path: string) => boolean;
+}
+declare function find(input: string, options: WindowsFindExecutableOptions): Promise<string | null>;
+declare function exists(executablePath: string, options: WindowsExecutableExistsOptions): string | null;
+export declare const windowsExecutableResolution: {
+    exists: typeof exists;
+    find: typeof find;
+};
+export {};
+//# sourceMappingURL=windows.d.ts.map

package/dist/server/executable-resolution/windows.js

@@ -0,0 +1,65 @@
+import { readdirSync } from "node:fs";
+import { extname, join } from "node:path";
+function hasPathSeparator(value) {
+    return value.includes("/") || value.includes("\\");
+}
+function enumerateLiteralPathCandidates(executablePath) {
+    if (extname(executablePath)) {
+        return [executablePath];
+    }
+    return [executablePath, `${executablePath}.exe`, `${executablePath}.cmd`];
+}
+function enumerateWingetPackageCandidates(name, localAppData) {
+    if (!localAppData) {
+        return [];
+    }
+    const wingetPackages = join(localAppData, "Microsoft", "WinGet", "Packages");
+    let packageDirs;
+    try {
+        packageDirs = readdirSync(wingetPackages, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name);
+    }
+    catch {
+        return [];
+    }
+    const exeName = `${name}.exe`;
+    return packageDirs.map((packageDir) => join(wingetPackages, packageDir, exeName));
+}
+async function find(input, options) {
+    if (hasPathSeparator(input)) {
+        return findFirstProbeable(enumerateLiteralPathCandidates(input), options);
+    }
+    const pathCandidates = await options.enumeratePathCandidates(input);
+    const wingetCandidates = enumerateWingetPackageCandidates(input, options.localAppData ?? process.env.LOCALAPPDATA).filter(options.exists);
+    return findFirstProbeable([...pathCandidates, ...wingetCandidates], options);
+}
+async function findFirstProbeable(candidates, options) {
+    const seen = new Set();
+    for (const candidate of candidates) {
+        if (seen.has(candidate)) {
+            continue;
+        }
+        seen.add(candidate);
+        if (!options.exists(candidate)) {
+            continue;
+        }
+        if (await options.probeExecutable(candidate, options.probeTimeoutMs)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+function exists(executablePath, options) {
+    for (const candidate of enumerateLiteralPathCandidates(executablePath)) {
+        if (options.exists(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+export const windowsExecutableResolution = {
+    exists,
+    find,
+};
+//# sourceMappingURL=windows.js.map

package/dist/server/extensions/daemon-backend.d.ts

@@ -0,0 +1,11 @@
+import type { Logger } from "pino";
+import type { AgentManager } from "../server/agent/agent-manager.js";
+import type { ExtensionHostBackend } from "./extension-host-manager.js";
+export interface DaemonExtensionBackendDeps {
+    agentManager: Pick<AgentManager, "listAgents" | "getAgent" | "archiveAgent">;
+    serverId: string;
+    paseoHome: string;
+    logger: Logger;
+}
+export declare function createDaemonExtensionBackend(deps: DaemonExtensionBackendDeps): ExtensionHostBackend;
+//# sourceMappingURL=daemon-backend.d.ts.map

package/dist/server/extensions/daemon-backend.js

@@ -0,0 +1,146 @@
+/**
+ * Daemon-side ExtensionHostBackend — the real implementation of the host API
+ * that extension-host child processes call over RPC.
+ *
+ * Licensing boundary: this is AGPL host code. It adapts the daemon's internal
+ * AgentManager (ManagedAgent) to the clean-room SDK shapes (AgentSummary /
+ * AgentDetail) the extension sees. The extension never imports these internals.
+ */
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+const STATUS_POLL_INTERVAL_MS = 2000;
+function mapStatus(agent) {
+    if (agent.pendingPermissions.size > 0)
+        return "waiting";
+    switch (agent.lifecycle) {
+        case "running":
+            return "running";
+        case "idle":
+        case "initializing":
+            return "idle";
+        case "error":
+            return "error";
+        case "closed":
+            return "unknown";
+        default:
+            return "unknown";
+    }
+}
+function toSummary(agent, serverId) {
+    const lastActivity = agent.lastUserMessageAt ?? agent.updatedAt;
+    return {
+        id: agent.id,
+        // ManagedAgent carries no first-class title; the app derives one from the
+        // session. v0 leaves it null rather than fabricate — enrich later.
+        title: null,
+        status: mapStatus(agent),
+        serverId,
+        cwd: agent.cwd,
+        lastActivityAt: lastActivity ? lastActivity.toISOString() : null,
+    };
+}
+function toDetail(agent, serverId) {
+    return {
+        ...toSummary(agent, serverId),
+        provider: agent.provider,
+        pendingPermissionCount: agent.pendingPermissions.size,
+    };
+}
+/** Per-extension JSON KV file under $PASEO_HOME/extension-storage/. */
+function storePath(paseoHome, extensionId) {
+    const safe = extensionId.replace(/[^a-zA-Z0-9._-]/g, "_");
+    return path.join(paseoHome, "extension-storage", `${safe}.json`);
+}
+export function createDaemonExtensionBackend(deps) {
+    const { agentManager, serverId, paseoHome, logger } = deps;
+    const liveSummaries = () => agentManager
+        .listAgents()
+        .filter((agent) => !agent.internal)
+        .map((agent) => toSummary(agent, serverId));
+    async function readStore(extensionId) {
+        try {
+            const raw = await readFile(storePath(paseoHome, extensionId), "utf8");
+            return JSON.parse(raw);
+        }
+        catch {
+            return {};
+        }
+    }
+    return {
+        agents: {
+            list: async () => liveSummaries(),
+            get: async (id) => {
+                const agent = agentManager.getAgent(id);
+                return agent ? toDetail(agent, serverId) : null;
+            },
+            archive: async (id) => {
+                await agentManager.archiveAgent(id);
+            },
+            onStatus: (listener) => {
+                // Poll-and-diff: dependency-light, no coupling to the AgentManager
+                // event surface. Emits immediately, then on every change.
+                let previous = "";
+                const tick = () => {
+                    const summaries = liveSummaries();
+                    const snapshot = JSON.stringify(summaries);
+                    if (snapshot !== previous) {
+                        previous = snapshot;
+                        try {
+                            listener(summaries);
+                        }
+                        catch (err) {
+                            logger.warn({ err }, "extension agents.onStatus listener threw");
+                        }
+                    }
+                };
+                const interval = setInterval(tick, STATUS_POLL_INTERVAL_MS);
+                if (typeof interval.unref === "function")
+                    interval.unref();
+                tick();
+                return { dispose: () => clearInterval(interval) };
+            },
+        },
+        ui: {
+            // COMPAT(extensionUiPush): the daemon has no client-push channel for these
+            // yet (would need a new outbound protocol message + capability flag). v0
+            // records them server-side; client-surfacing is a follow-up feature.
+            showNotification: async (options) => {
+                logger.info({ notification: options }, "extension notification");
+            },
+            openView: async (viewId) => {
+                logger.info({ viewId }, "extension requested openView (not yet surfaced to client)");
+            },
+            openPanel: async (kind, props) => {
+                logger.info({ kind, props }, "extension requested openPanel (not yet surfaced to client)");
+            },
+        },
+        storage: {
+            get: async (extensionId, key) => {
+                const store = await readStore(extensionId);
+                return store[key];
+            },
+            set: async (extensionId, key, value) => {
+                const store = await readStore(extensionId);
+                store[key] = value;
+                const file = storePath(paseoHome, extensionId);
+                await mkdir(path.dirname(file), { recursive: true });
+                await writeFile(file, JSON.stringify(store, null, 2));
+            },
+        },
+        net: {
+            fetch: async (url, init) => {
+                const response = await fetch(url, {
+                    method: init?.method,
+                    headers: init?.headers,
+                    body: init?.body,
+                });
+                const headers = {};
+                response.headers.forEach((value, headerKey) => {
+                    headers[headerKey] = value;
+                });
+                return { status: response.status, headers, body: await response.text() };
+            },
+        },
+    };
+}
+//# sourceMappingURL=daemon-backend.js.map

package/dist/server/extensions/extension-host-manager.d.ts

@@ -0,0 +1,48 @@
+import type { AgentDetail, AgentSummary, ExtensionManifest, HostFetchInit, HostFetchResponse } from "@hyperpaseo/extension-sdk";
+export interface ExtensionHostBackend {
+    agents: {
+        list(): Promise<AgentSummary[]>;
+        get(id: string): Promise<AgentDetail | null>;
+        archive(id: string): Promise<void>;
+        onStatus(listener: (agents: AgentSummary[]) => void): {
+            dispose(): void;
+        };
+    };
+    ui: {
+        showNotification(options: {
+            title?: string;
+            body: string;
+        }): Promise<void>;
+        openView(viewId: string): Promise<void>;
+        openPanel(kind: string, props?: Record<string, unknown>): Promise<void>;
+    };
+    storage: {
+        get(extensionId: string, key: string): Promise<unknown>;
+        set(extensionId: string, key: string, value: unknown): Promise<void>;
+    };
+    net: {
+        fetch(url: string, init?: HostFetchInit): Promise<HostFetchResponse>;
+    };
+}
+export interface ExtensionHostHandle {
+    readonly manifest: ExtensionManifest;
+    /** Resolves with the extension's registered command ids once it has activated. */
+    readonly whenReady: Promise<string[]>;
+    executeCommand(commandId: string, args?: unknown[]): Promise<unknown>;
+    dispose(): void;
+}
+export interface SpawnExtensionHostOptions {
+    manifest: ExtensionManifest;
+    /** Absolute path to the extension's manifest file. */
+    manifestPath: string;
+    /** Absolute path to the compiled extension-host-runtime.js. */
+    runtimeEntry: string;
+    /** Absolute path to the extension's `main` (if any). */
+    mainPath?: string;
+    backend: ExtensionHostBackend;
+    /** node executable to use (e.g. process.execPath with ELECTRON_RUN_AS_NODE). */
+    nodePath?: string;
+    onError?: (error: string) => void;
+}
+export declare function spawnExtensionHost(options: SpawnExtensionHostOptions): ExtensionHostHandle;
+//# sourceMappingURL=extension-host-manager.d.ts.map

package/dist/server/extensions/extension-host-manager.js

@@ -0,0 +1,141 @@
+/**
+ * Extension-host manager — the PARENT side. Spawns the extension-host child
+ * process, bridges its stdio JSON-RPC to host capabilities, and exposes command
+ * execution back to the host UI.
+ *
+ * The host capabilities are injected as an `ExtensionHostBackend` so this module
+ * stays decoupled from daemon internals and unit-testable. The thin adapter that
+ * implements `ExtensionHostBackend` against the real daemon / DaemonClient is the
+ * one documented wiring point (see `daemon-backend.ts`, to be wired at startup).
+ */
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+const SUBSCRIBE_PATH = "__subscribe__";
+export function spawnExtensionHost(options) {
+    const { manifest, manifestPath, runtimeEntry, mainPath, backend } = options;
+    const child = spawn(options.nodePath ?? process.execPath, [runtimeEntry], {
+        stdio: ["pipe", "pipe", "pipe"],
+        env: {
+            ...process.env,
+            ELECTRON_RUN_AS_NODE: "1",
+            HYPERPASEO_EXT_MANIFEST: manifestPath,
+            ...(mainPath ? { HYPERPASEO_EXT_MAIN: mainPath } : {}),
+        },
+    });
+    let nextCommandId = 1;
+    const pendingCommands = new Map();
+    const subscriptions = [];
+    let resolveReady = () => undefined;
+    const whenReady = new Promise((resolve) => {
+        resolveReady = resolve;
+    });
+    function post(message) {
+        child.stdin?.write(`${JSON.stringify(message)}\n`);
+    }
+    async function handleCall(message) {
+        const [head, method] = message.path;
+        // Channel subscription request (e.g. agents.status).
+        if (head === SUBSCRIBE_PATH) {
+            const channel = message.args[0];
+            if (channel === "agents.status") {
+                const sub = backend.agents.onStatus((agents) => post({ kind: "event", channel, payload: agents }));
+                subscriptions.push(sub);
+            }
+            post({ kind: "result", id: message.id, ok: true, value: null });
+            return;
+        }
+        try {
+            const value = await route(head, method, message.args);
+            post({ kind: "result", id: message.id, ok: true, value });
+        }
+        catch (error) {
+            post({
+                kind: "result",
+                id: message.id,
+                ok: false,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    async function route(head, method, args) {
+        switch (`${head}.${method}`) {
+            case "agents.list":
+                return backend.agents.list();
+            case "agents.get":
+                return backend.agents.get(args[0]);
+            case "agents.archive":
+                return backend.agents.archive(args[0]);
+            case "ui.showNotification":
+                return backend.ui.showNotification(args[0]);
+            case "ui.openView":
+                return backend.ui.openView(args[0]);
+            case "ui.openPanel":
+                return backend.ui.openPanel(args[0], args[1]);
+            case "storage.get":
+                return backend.storage.get(manifest.id, args[0]);
+            case "storage.set":
+                return backend.storage.set(manifest.id, args[0], args[1]);
+            case "net.fetch":
+                return backend.net.fetch(args[0], args[1]);
+            default:
+                throw new Error(`unknown host method "${head}.${method}"`);
+        }
+    }
+    const rl = createInterface({ input: child.stdout });
+    rl.on("line", (line) => {
+        if (!line.trim())
+            return;
+        let message;
+        try {
+            message = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        const kind = message.kind;
+        if (kind === "call") {
+            void handleCall(message);
+            return;
+        }
+        if (kind === "commandResult") {
+            const result = message;
+            const pending = pendingCommands.get(result.id);
+            if (!pending)
+                return;
+            pendingCommands.delete(result.id);
+            if (result.ok)
+                pending.resolve(result.value);
+            else
+                pending.reject(new Error(result.error ?? "command failed"));
+            return;
+        }
+        if (kind === "ready") {
+            const commands = message.commands ?? [];
+            resolveReady(commands);
+            return;
+        }
+        if (kind === "fatal") {
+            options.onError?.(String(message.error));
+        }
+    });
+    child.stderr?.on("data", (data) => {
+        options.onError?.(data.toString());
+    });
+    return {
+        manifest,
+        whenReady,
+        executeCommand(commandId, args) {
+            const id = nextCommandId++;
+            return new Promise((resolve, reject) => {
+                pendingCommands.set(id, { resolve, reject });
+                post({ kind: "invokeCommand", id, commandId, args: args ?? [] });
+            });
+        },
+        dispose() {
+            for (const sub of subscriptions)
+                sub.dispose();
+            child.kill("SIGTERM");
+        },
+    };
+}
+//# sourceMappingURL=extension-host-manager.js.map

package/dist/server/extensions/extension-loader.d.ts

@@ -0,0 +1,11 @@
+import { type ExtensionManifest } from "@hyperpaseo/extension-sdk";
+export interface DiscoveredExtension {
+    dir: string;
+    manifestPath: string;
+    manifest: ExtensionManifest;
+    /** Absolute path to the extension's `main` entry, if it declares one. */
+    mainPath?: string;
+}
+export declare function extensionsRoot(): string;
+export declare function discoverExtensions(root?: string): Promise<DiscoveredExtension[]>;
+//# sourceMappingURL=extension-loader.d.ts.map

package/dist/server/extensions/extension-loader.js

@@ -0,0 +1,47 @@
+/**
+ * Extension discovery. Reads installed extensions from the extensions dir
+ * (default `$PASEO_HOME/extensions`, override with HYPERPASEO_EXTENSIONS_DIR).
+ * Each extension is a directory containing a `hyperpaseo.json` manifest.
+ *
+ * Discovery is pure metadata — no extension code is executed here. That happens
+ * later, arms-length, in the spawned extension-host child.
+ */
+import { readdir, readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+import { parseManifest } from "@hyperpaseo/extension-sdk";
+function resolveMainPath(dir, main) {
+    if (!main)
+        return undefined;
+    return isAbsolute(main) ? main : resolve(dir, main);
+}
+export function extensionsRoot() {
+    if (process.env.HYPERPASEO_EXTENSIONS_DIR) {
+        return process.env.HYPERPASEO_EXTENSIONS_DIR;
+    }
+    const paseoHome = process.env.PASEO_HOME ?? join(homedir(), ".paseo");
+    return join(paseoHome, "extensions");
+}
+export async function discoverExtensions(root = extensionsRoot()) {
+    const entries = await readdir(root, { withFileTypes: true }).catch(() => null);
+    if (entries === null)
+        return [];
+    const discovered = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const dir = join(root, entry.name);
+        const manifestPath = join(dir, "hyperpaseo.json");
+        try {
+            const raw = JSON.parse(await readFile(manifestPath, "utf8"));
+            const manifest = parseManifest(raw);
+            const mainPath = resolveMainPath(dir, manifest.main);
+            discovered.push({ dir, manifestPath, manifest, mainPath });
+        }
+        catch {
+            // Skip extensions with a missing/invalid manifest. Loader stays resilient.
+        }
+    }
+    return discovered;
+}
+//# sourceMappingURL=extension-loader.js.map

package/dist/server/extensions/extension-service.d.ts

@@ -0,0 +1,17 @@
+import type { Logger } from "pino";
+import type { AgentManager } from "../server/agent/agent-manager.js";
+export interface ExtensionServiceDeps {
+    agentManager: Pick<AgentManager, "listAgents" | "getAgent" | "archiveAgent">;
+    serverId: string;
+    paseoHome: string;
+    logger: Logger;
+}
+export interface ExtensionService {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /** Execute a command contributed by some installed extension. */
+    executeCommand(commandId: string, args?: unknown[]): Promise<unknown>;
+    listExtensionIds(): string[];
+}
+export declare function createExtensionService(deps: ExtensionServiceDeps): ExtensionService;
+//# sourceMappingURL=extension-service.d.ts.map