@hyperdrive.bot/paseo-server 0.2.6

package/dist/server/server/editor-targets.js

@@ -0,0 +1,109 @@
+import { existsSync } from "node:fs";
+import { posix, win32 } from "node:path";
+import { createExternalProcessEnv } from "./paseo-env.js";
+import { findExecutable } from "../executable-resolution/executable-resolution.js";
+import { spawnProcess } from "../utils/spawn.js";
+const EDITOR_TARGETS = [
+    { id: "cursor", label: "Cursor", command: "cursor" },
+    { id: "vscode", label: "VS Code", command: "code" },
+    { id: "webstorm", label: "WebStorm", command: "webstorm" },
+    { id: "zed", label: "Zed", command: "zed" },
+    { id: "finder", label: "Finder", command: "open", platforms: ["darwin"] },
+    { id: "explorer", label: "Explorer", command: "explorer", platforms: ["win32"] },
+    {
+        id: "file-manager",
+        label: "File Manager",
+        command: "xdg-open",
+        excludedPlatforms: ["darwin", "win32"],
+    },
+];
+function isAbsolutePath(value) {
+    return posix.isAbsolute(value) || win32.isAbsolute(value);
+}
+function isTargetSupportedOnPlatform(target, platform) {
+    if (target.platforms && !target.platforms.includes(platform)) {
+        return false;
+    }
+    if (target.excludedPlatforms?.includes(platform)) {
+        return false;
+    }
+    return true;
+}
+function resolveEditorTargetDefinition(editorId) {
+    const target = EDITOR_TARGETS.find((entry) => entry.id === editorId);
+    if (!target) {
+        throw new Error(`Unknown editor target: ${editorId}`);
+    }
+    return target;
+}
+export async function listAvailableEditorTargets(dependencies = {}) {
+    const platform = dependencies.platform ?? process.platform;
+    const findExecutableFn = dependencies.findExecutable ?? findExecutable;
+    const supportedTargets = EDITOR_TARGETS.filter((target) => isTargetSupportedOnPlatform(target, platform));
+    const executables = await Promise.all(supportedTargets.map((target) => findExecutableFn(target.command)));
+    const results = [];
+    for (let i = 0; i < supportedTargets.length; i += 1) {
+        if (!executables[i])
+            continue;
+        const target = supportedTargets[i];
+        results.push({
+            id: target.id,
+            label: target.label,
+        });
+    }
+    return results;
+}
+async function resolveEditorLaunch(input) {
+    const target = resolveEditorTargetDefinition(input.editorId);
+    if (!isTargetSupportedOnPlatform(target, input.platform)) {
+        throw new Error(`Editor target unavailable: ${target.label}`);
+    }
+    const executable = await input.findExecutableFn(target.command);
+    if (!executable) {
+        throw new Error(`Editor target unavailable: ${target.label}`);
+    }
+    return {
+        command: executable,
+        args: [input.path],
+    };
+}
+export async function openInEditorTarget(input, dependencies = {}) {
+    const platform = dependencies.platform ?? process.platform;
+    const pathToOpen = input.path.trim();
+    const existsSyncFn = dependencies.existsSync ?? existsSync;
+    const findExecutableFn = dependencies.findExecutable ?? findExecutable;
+    const spawnFn = dependencies.spawn ?? spawnProcess;
+    if (!pathToOpen || !isAbsolutePath(pathToOpen)) {
+        throw new Error("Editor target path must be an absolute local path");
+    }
+    if (!existsSyncFn(pathToOpen)) {
+        throw new Error(`Path does not exist: ${pathToOpen}`);
+    }
+    const launch = await resolveEditorLaunch({
+        editorId: input.editorId,
+        path: pathToOpen,
+        platform,
+        findExecutableFn,
+    });
+    await new Promise((resolve, reject) => {
+        let child;
+        try {
+            child = spawnFn(launch.command, launch.args, {
+                detached: true,
+                env: createExternalProcessEnv(process.env),
+                shell: platform === "win32",
+                stdio: "ignore",
+            });
+        }
+        catch (error) {
+            reject(error);
+            return;
+        }
+        child.once("error", reject);
+        child.once("spawn", () => {
+            child.unref();
+            resolve();
+        });
+    });
+}
+//# sourceMappingURL=editor-targets.js.map

package/dist/server/server/exports.d.ts

@@ -0,0 +1,24 @@
+export { createPaseoDaemon, type PaseoDaemon, type PaseoDaemonConfig } from "./bootstrap.js";
+export { loadConfig, type CliConfigOverrides } from "./config.js";
+export { resolvePaseoHome } from "./paseo-home.js";
+export { getOrCreateServerId } from "./server-id.js";
+export { createRootLogger, type LogLevel, type LogFormat } from "./logger.js";
+export { loadPersistedConfig, savePersistedConfig, type PersistedConfig, } from "./persisted-config.js";
+export { hashDaemonPassword, isBearerTokenValid } from "./auth.js";
+export { generateLocalPairingOffer, type LocalPairingOffer } from "./pairing-offer.js";
+export { ConnectionOfferSchema, decodeOfferFragmentPayload, parseConnectionOfferFromUrl, type ConnectionOffer, } from "@hyperdrive.bot/paseo-protocol/connection-offer";
+export { buildRelayWebSocketUrl } from "@hyperdrive.bot/paseo-protocol/daemon-endpoints";
+export { buildDaemonWebSocketUrl, deriveLabelFromEndpoint, normalizeHostPort, parseConnectionUri, shouldUseTlsForDefaultHostedRelay, } from "@hyperdrive.bot/paseo-protocol/daemon-endpoints";
+export { PARENT_AGENT_ID_LABEL } from "@hyperdrive.bot/paseo-protocol/agent-labels";
+export { DirectTcpHostConnectionSchema, type DirectTcpHostConnection, type NormalizedDirectTcpHostConnection, } from "@hyperdrive.bot/paseo-protocol/host-connection-schema";
+export { ensureLocalSpeechModels, listLocalSpeechModels, type LocalSpeechModelId, type LocalSttModelId, type LocalTtsModelId, } from "./speech/providers/local/models.js";
+export { applySherpaLoaderEnv, resolveSherpaLoaderEnv, sherpaLoaderEnvKey, sherpaPlatformArch, sherpaPlatformPackageName, type SherpaLoaderEnvKey, type SherpaLoaderEnvResolution, } from "./speech/providers/local/sherpa/sherpa-runtime-env.js";
+export { type ProviderOverride, type ProviderProfileModel, } from "./agent/provider-launch-config.js";
+export { findExecutable } from "../executable-resolution/executable-resolution.js";
+export { execCommand, spawnProcess } from "../utils/spawn.js";
+export { AGENT_PROVIDER_DEFINITIONS, BUILTIN_PROVIDER_IDS, type AgentProviderDefinition, } from "@hyperdrive.bot/paseo-protocol/provider-manifest";
+export type { AgentMode, AgentUsage, AgentCapabilityFlags, AgentPermissionRequest, AgentTimelineItem, ProviderSnapshotEntry, } from "./agent/agent-sdk-types.js";
+export { curateAgentActivity } from "./agent/activity-curator.js";
+export { getStructuredAgentResponse, StructuredAgentResponseError, StructuredAgentFallbackError, DEFAULT_STRUCTURED_GENERATION_PROVIDERS, generateStructuredAgentResponseWithFallback, type AgentCaller, type JsonSchema, type StructuredGenerationAttempt, type StructuredGenerationProvider, type StructuredAgentGenerationOptions, type StructuredAgentGenerationWithFallbackOptions, type StructuredAgentResponseOptions, } from "./agent/agent-response-loop.js";
+export type { AgentSnapshotPayload, AgentStreamEventPayload, AgentStreamMessage, } from "@hyperdrive.bot/paseo-protocol/messages";
+//# sourceMappingURL=exports.d.ts.map

package/dist/server/server/exports.js

@@ -0,0 +1,24 @@
+// CLI exports for @hyperdrive.bot/paseo-server
+export { createPaseoDaemon } from "./bootstrap.js";
+export { loadConfig } from "./config.js";
+export { resolvePaseoHome } from "./paseo-home.js";
+export { getOrCreateServerId } from "./server-id.js";
+export { createRootLogger } from "./logger.js";
+export { loadPersistedConfig, savePersistedConfig, } from "./persisted-config.js";
+export { hashDaemonPassword, isBearerTokenValid } from "./auth.js";
+export { generateLocalPairingOffer } from "./pairing-offer.js";
+export { ConnectionOfferSchema, decodeOfferFragmentPayload, parseConnectionOfferFromUrl, } from "@hyperdrive.bot/paseo-protocol/connection-offer";
+export { buildRelayWebSocketUrl } from "@hyperdrive.bot/paseo-protocol/daemon-endpoints";
+export { buildDaemonWebSocketUrl, deriveLabelFromEndpoint, normalizeHostPort, parseConnectionUri, shouldUseTlsForDefaultHostedRelay, } from "@hyperdrive.bot/paseo-protocol/daemon-endpoints";
+export { PARENT_AGENT_ID_LABEL } from "@hyperdrive.bot/paseo-protocol/agent-labels";
+export { DirectTcpHostConnectionSchema, } from "@hyperdrive.bot/paseo-protocol/host-connection-schema";
+export { ensureLocalSpeechModels, listLocalSpeechModels, } from "./speech/providers/local/models.js";
+export { applySherpaLoaderEnv, resolveSherpaLoaderEnv, sherpaLoaderEnvKey, sherpaPlatformArch, sherpaPlatformPackageName, } from "./speech/providers/local/sherpa/sherpa-runtime-env.js";
+export { findExecutable } from "../executable-resolution/executable-resolution.js";
+export { execCommand, spawnProcess } from "../utils/spawn.js";
+// Provider manifest (source of truth for provider definitions)
+export { AGENT_PROVIDER_DEFINITIONS, BUILTIN_PROVIDER_IDS, } from "@hyperdrive.bot/paseo-protocol/provider-manifest";
+// Agent activity curator for CLI logs
+export { curateAgentActivity } from "./agent/activity-curator.js";
+export { getStructuredAgentResponse, StructuredAgentResponseError, StructuredAgentFallbackError, DEFAULT_STRUCTURED_GENERATION_PROVIDERS, generateStructuredAgentResponseWithFallback, } from "./agent/agent-response-loop.js";
+//# sourceMappingURL=exports.js.map

package/dist/server/server/file-download/token-store.d.ts

@@ -0,0 +1,24 @@
+export interface DownloadTokenEntry {
+    token: string;
+    path: string;
+    absolutePath: string;
+    fileName: string;
+    mimeType: string;
+    size: number;
+    expiresAt: number;
+}
+interface DownloadTokenStoreOptions {
+    ttlMs: number;
+    now?: () => number;
+}
+export declare class DownloadTokenStore {
+    private readonly ttlMs;
+    private readonly now;
+    private readonly tokens;
+    constructor(options: DownloadTokenStoreOptions);
+    issueToken(input: Omit<DownloadTokenEntry, "token" | "expiresAt">): DownloadTokenEntry;
+    consumeToken(token: string): DownloadTokenEntry | null;
+    private pruneExpired;
+}
+export {};
+//# sourceMappingURL=token-store.d.ts.map

package/dist/server/server/file-download/token-store.js

@@ -0,0 +1,40 @@
+import { randomUUID } from "node:crypto";
+export class DownloadTokenStore {
+    constructor(options) {
+        this.tokens = new Map();
+        this.ttlMs = options.ttlMs;
+        this.now = options.now ?? (() => Date.now());
+    }
+    issueToken(input) {
+        this.pruneExpired();
+        const token = randomUUID();
+        const expiresAt = this.now() + this.ttlMs;
+        const entry = {
+            ...input,
+            token,
+            expiresAt,
+        };
+        this.tokens.set(token, entry);
+        return entry;
+    }
+    consumeToken(token) {
+        const entry = this.tokens.get(token);
+        if (!entry) {
+            return null;
+        }
+        this.tokens.delete(token);
+        if (entry.expiresAt <= this.now()) {
+            return null;
+        }
+        return entry;
+    }
+    pruneExpired() {
+        const now = this.now();
+        for (const [token, entry] of this.tokens) {
+            if (entry.expiresAt <= now) {
+                this.tokens.delete(token);
+            }
+        }
+    }
+}
+//# sourceMappingURL=token-store.js.map

package/dist/server/server/file-explorer/file-download-frames.d.ts

@@ -0,0 +1,27 @@
+import type { z } from "zod";
+import { type FileBeginMetadataSchema } from "@hyperdrive.bot/paseo-protocol/binary-frames/index";
+export interface EncodeFileDownloadFramesParams {
+    requestId: string;
+    metadata: z.infer<typeof FileBeginMetadataSchema>;
+    read: (buf: Buffer, offset: number, length: number, position: number) => Promise<{
+        bytesRead: number;
+    }>;
+    chunkSize?: number;
+}
+/**
+ * Encode a file download as a relay-safe stream of binary frames:
+ * `FileBegin` (carrying the metadata) → N × `FileChunk` (each ≤ chunkSize) → `FileEnd`.
+ *
+ * This is the download-direction twin of the upload chunker — it consumes the same
+ * `encodeFileTransferFrame` codec and the same `UPLOAD_CHUNK_SIZE_BYTES` constant, so
+ * no single frame's payload can exceed the 256 KiB ceiling (keeping it well under the
+ * relay's 32 MiB per-message cap and preventing head-of-line blocking of voice/terminal
+ * frames on the shared WebSocket).
+ *
+ * The byte source is supplied via `read` (positioned reads from offset 0) so the caller
+ * owns the file handle and the helper stays pure/testable with an in-memory buffer.
+ *
+ * @returns an async generator yielding the encoded frames in order.
+ */
+export declare function encodeFileDownloadFrames({ requestId, metadata, read, chunkSize, }: EncodeFileDownloadFramesParams): AsyncGenerator<Uint8Array>;
+//# sourceMappingURL=file-download-frames.d.ts.map

package/dist/server/server/file-explorer/file-download-frames.js

@@ -0,0 +1,47 @@
+import { encodeFileTransferFrame, FileTransferOpcode, } from "@hyperdrive.bot/paseo-protocol/binary-frames/index";
+import { UPLOAD_CHUNK_SIZE_BYTES } from "@hyperdrive.bot/paseo-protocol/binary-frames/chunk-size";
+/**
+ * Encode a file download as a relay-safe stream of binary frames:
+ * `FileBegin` (carrying the metadata) → N × `FileChunk` (each ≤ chunkSize) → `FileEnd`.
+ *
+ * This is the download-direction twin of the upload chunker — it consumes the same
+ * `encodeFileTransferFrame` codec and the same `UPLOAD_CHUNK_SIZE_BYTES` constant, so
+ * no single frame's payload can exceed the 256 KiB ceiling (keeping it well under the
+ * relay's 32 MiB per-message cap and preventing head-of-line blocking of voice/terminal
+ * frames on the shared WebSocket).
+ *
+ * The byte source is supplied via `read` (positioned reads from offset 0) so the caller
+ * owns the file handle and the helper stays pure/testable with an in-memory buffer.
+ *
+ * @returns an async generator yielding the encoded frames in order.
+ */
+export async function* encodeFileDownloadFrames({ requestId, metadata, read, chunkSize = UPLOAD_CHUNK_SIZE_BYTES, }) {
+    yield encodeFileTransferFrame({
+        opcode: FileTransferOpcode.FileBegin,
+        requestId,
+        metadata,
+    });
+    // One reusable read buffer for the whole stream. This is safe because
+    // encodeFileTransferFrame copies the payload (`bytes.set(payload, …)` in
+    // file-transfer.ts) — the subarray handed to each FileChunk is never aliased
+    // after the yield. Do NOT "fix" this into a per-chunk allocation.
+    const buffer = Buffer.allocUnsafe(chunkSize);
+    let position = 0;
+    for (;;) {
+        const { bytesRead } = await read(buffer, 0, chunkSize, position);
+        if (bytesRead === 0) {
+            break;
+        }
+        position += bytesRead;
+        yield encodeFileTransferFrame({
+            opcode: FileTransferOpcode.FileChunk,
+            requestId,
+            payload: buffer.subarray(0, bytesRead),
+        });
+    }
+    yield encodeFileTransferFrame({
+        opcode: FileTransferOpcode.FileEnd,
+        requestId,
+    });
+}
+//# sourceMappingURL=file-download-frames.js.map

package/dist/server/server/file-explorer/service.d.ts

@@ -0,0 +1,75 @@
+import type { FileHandle } from "fs/promises";
+export type ExplorerEntryKind = "file" | "directory";
+export type ExplorerFileKind = "text" | "image" | "binary";
+export type ExplorerEncoding = "utf-8" | "base64" | "none";
+export interface ListDirectoryParams {
+    root: string;
+    relativePath?: string;
+}
+export interface ReadFileParams {
+    root: string;
+    relativePath: string;
+}
+export interface FileExplorerEntry {
+    name: string;
+    path: string;
+    kind: ExplorerEntryKind;
+    size: number;
+    modifiedAt: string;
+}
+export interface FileExplorerDirectory {
+    path: string;
+    entries: FileExplorerEntry[];
+}
+export interface FileExplorerFile {
+    path: string;
+    kind: ExplorerFileKind;
+    encoding: ExplorerEncoding;
+    content?: string;
+    mimeType?: string;
+    size: number;
+    modifiedAt: string;
+}
+export interface FileExplorerFileBytes {
+    path: string;
+    kind: ExplorerFileKind;
+    encoding: "utf-8" | "binary";
+    bytes: Uint8Array;
+    mimeType: string;
+    size: number;
+    modifiedAt: string;
+}
+export declare function listDirectoryEntries({ root, relativePath, }: ListDirectoryParams): Promise<FileExplorerDirectory>;
+export declare function readExplorerFile({ root, relativePath, }: ReadFileParams): Promise<FileExplorerFile>;
+export declare function readExplorerFileBytes({ root, relativePath, }: ReadFileParams): Promise<FileExplorerFileBytes>;
+export interface OpenExplorerFileForDownload {
+    handle: FileHandle;
+    metadata: {
+        mime: string;
+        size: number;
+        encoding: "utf-8" | "binary";
+        modifiedAt: string;
+    };
+    path: string;
+}
+/**
+ * Open a file for a streaming binary download. Mirrors `readExplorerFileBytes`'s
+ * mime/kind/encoding detection but NEVER loads the whole file: it classifies the
+ * file from a bounded detection prefix and returns the still-open handle so the
+ * caller can stream chunk-sized positioned reads (see `encodeFileDownloadFrames`).
+ *
+ * The returned handle is the caller's to close — the success path transfers
+ * ownership; only the error path closes it here to avoid leaking a descriptor.
+ *
+ * @returns the open file handle, FileBegin metadata, and the workspace-relative path.
+ * @throws if the path resolves outside the workspace or is not a regular file.
+ */
+export declare function openExplorerFileForDownload({ root, relativePath, }: ReadFileParams): Promise<OpenExplorerFileForDownload>;
+export declare function getDownloadableFileInfo({ root, relativePath }: ReadFileParams): Promise<{
+    path: string;
+    absolutePath: string;
+    fileName: string;
+    mimeType: string;
+    size: number;
+}>;
+//# sourceMappingURL=service.d.ts.map