@getpaseo/server 0.1.97 → 0.1.99

package/dist/server/server/agent/providers/pi/test-utils/fake-pi.d.ts

@@ -61,7 +61,7 @@ export declare class FakePiSession implements PiRuntimeSession {
     abort(): Promise<void>;
     getState(): Promise<PiSessionState>;
     getMessages(): Promise<PiAgentMessage[]>;
-    getAvailableModels(): Promise<PiModel[]>;
+    getAvailableModels(_timeoutMs?: number): Promise<PiModel[]>;
     setModel(provider: string, modelId: string): Promise<PiModel>;
     setThinkingLevel(level: string): Promise<void>;
     getSessionStats(): Promise<PiSessionStats>;

package/dist/server/server/agent/providers/pi/test-utils/fake-pi.js

@@ -100,7 +100,7 @@ export class FakePiSession {
     async getMessages() {
         return this.messages;
     }
-    async getAvailableModels() {
+    async getAvailableModels(_timeoutMs) {
         return this.models;
     }
     async setModel(provider, modelId) {

package/dist/server/server/bootstrap.d.ts

@@ -25,6 +25,7 @@ import type { AgentProviderRuntimeSettingsMap, ProviderOverride } from "./agent/
 import type { PersistedConfig } from "./persisted-config.js";
 import { type ServiceProxySubsystem } from "./service-proxy.js";
 import { WorkspaceScriptRuntimeStore } from "./workspace-script-runtime-store.js";
+import { type ManagedProcessRegistry } from "./managed-processes/managed-processes.js";
 import { type HostnamesConfig } from "./hostnames.js";
 import { type DaemonAuthConfig } from "./auth.js";
 export declare function createTerminalActivityRouteHandler(terminalManager: TerminalManager): express.RequestHandler;
@@ -97,6 +98,7 @@ export interface PaseoDaemonConfig {
     log?: PersistedConfig["log"];
     onLifecycleIntent?: (intent: DaemonLifecycleIntent) => void;
     pushNotificationSender?: PushNotificationSender;
+    managedProcesses?: ManagedProcessRegistry;
 }
 export interface PaseoDaemon {
     config: PaseoDaemonConfig;

package/dist/server/server/bootstrap.js

@@ -52,12 +52,15 @@ export function parseListenString(listen) {
     }
     // 6. host:port — TCP
     if (listen.includes(":")) {
-        const [host, portStr] = listen.split(":");
+        const lastColonIdx = listen.lastIndexOf(":");
+        const host = listen.slice(0, lastColonIdx);
+        const portStr = listen.slice(lastColonIdx + 1);
         const parsedPort = parseInt(portStr, 10);
         if (!Number.isFinite(parsedPort)) {
             throw new Error(`Invalid port in listen string: ${listen}`);
         }
-        return { type: "tcp", host: host || "127.0.0.1", port: parsedPort };
+        const cleanHost = host.startsWith("[") && host.endsWith("]") ? host.slice(1, -1) : host;
+        return { type: "tcp", host: cleanHost || "127.0.0.1", port: parsedPort };
     }
     throw new Error(`Invalid listen string: ${listen}`);
 }
@@ -105,6 +108,8 @@ import { createServiceProxySubsystem } from "./service-proxy.js";
 import { ScriptHealthMonitor } from "./script-health-monitor.js";
 import { createScriptStatusEmitter } from "./script-status-projection.js";
 import { WorkspaceScriptRuntimeStore } from "./workspace-script-runtime-store.js";
+import { createManagedProcessRegistry, createSystemManagedProcessTable, } from "./managed-processes/managed-processes.js";
+import { terminateWithTreeKill } from "../utils/tree-kill.js";
 import { isHostnameAllowed } from "./hostnames.js";
 import { createRequireBearerMiddleware, isAgentMcpRequestAuthorized, } from "./auth.js";
 const MAX_MCP_DEBUG_BATCH_ITEMS = 10;
@@ -207,6 +212,23 @@ function summarizeAgentMcpDebugBody(body) {
         ...(body.length > messages.length ? { omitted: body.length - messages.length } : {}),
     };
 }
+function createBootstrapManagedProcessRegistry(config, logger) {
+    if (config.managedProcesses) {
+        return config.managedProcesses;
+    }
+    return createManagedProcessRegistry({
+        paseoHome: config.paseoHome,
+        processTable: createSystemManagedProcessTable(),
+        terminateProcess: terminateWithTreeKill,
+        logger,
+    });
+}
+async function reconcileManagedProcessLedger(managedProcesses, logger) {
+    const reapResult = await managedProcesses.reapStale();
+    if (reapResult.checked > 0 || reapResult.errors.length > 0) {
+        logger.info(reapResult, "Managed helper process ledger reconciled");
+    }
+}
 export async function createPaseoDaemon(config, rootLogger) {
     const logger = rootLogger.child({ module: "bootstrap" });
     const bootstrapStart = performance.now();
@@ -233,6 +255,13 @@ export async function createPaseoDaemon(config, rootLogger) {
     }, logger);
     const serverId = getOrCreateServerId(config.paseoHome, { logger });
     const daemonKeyPair = await loadOrCreateDaemonKeyPair(config.paseoHome, logger);
+    const managedProcesses = createBootstrapManagedProcessRegistry(config, logger);
+    // Reconcile the helper-process ledger in the background so it never blocks the
+    // daemon from coming up; terminating a live leftover can take a few seconds.
+    // Best-effort, so a failure is logged here rather than crashing startup.
+    void reconcileManagedProcessLedger(managedProcesses, logger).catch((error) => {
+        logger.warn({ err: error }, "Failed to reconcile managed helper process ledger");
+    });
     let relayTransport = null;
     const staticDir = config.staticDir;
     const downloadTokenTtlMs = config.downloadTokenTtlMs ?? 60000;
@@ -434,6 +463,7 @@ export async function createPaseoDaemon(config, rootLogger) {
         runtimeSettings: config.agentProviderSettings,
         providerOverrides: config.providerOverrides,
         workspaceGitService,
+        managedProcesses,
         isDev: config.isDev === true,
         extraClients: config.agentClients,
     });

package/dist/server/server/managed-processes/managed-processes.d.ts

@@ -0,0 +1,76 @@
+import type { Logger } from "pino";
+import type { ProcessTerminator, TreeKillTarget } from "../../utils/tree-kill.js";
+export interface ManagedProcessSnapshot {
+    pid: number;
+    commandLine: string | null;
+    startedAt: string | null;
+}
+export type ManagedProcessInspection = {
+    status: "alive";
+    snapshot: ManagedProcessSnapshot;
+} | {
+    status: "not-found";
+} | {
+    status: "error";
+    error: unknown;
+};
+export interface ManagedProcessTable {
+    inspect(pid: number): Promise<ManagedProcessInspection>;
+}
+export interface ManagedProcessCommandRunner {
+    exec(command: string, args: string[]): Promise<{
+        stdout: string;
+        stderr: string;
+    }>;
+}
+export interface ManagedProcessOwner {
+    provider: string;
+    kind: string;
+}
+export interface ManagedProcessRecordInput {
+    owner: ManagedProcessOwner;
+    pid: number;
+    command: string;
+    args: string[];
+    metadata?: Record<string, unknown>;
+}
+export interface ManagedProcessRecord extends ManagedProcessRecordInput {
+    id: string;
+    metadata: Record<string, unknown>;
+    identity: {
+        commandLine: string | null;
+        startedAt: string | null;
+    };
+    createdAt: string;
+}
+export interface ManagedProcessReapResult {
+    checked: number;
+    dead: number;
+    mismatched: number;
+    removed: number;
+    terminated: number;
+    errors: Array<{
+        id: string;
+        message: string;
+    }>;
+}
+export interface ManagedProcessRegistry {
+    record(input: ManagedProcessRecordInput): Promise<ManagedProcessRecord>;
+    remove(id: string): Promise<void>;
+    list(): Promise<ManagedProcessRecord[]>;
+    reapStale(): Promise<ManagedProcessReapResult>;
+}
+interface ManagedProcessRegistryOptions {
+    paseoHome: string;
+    processTable: ManagedProcessTable;
+    terminateProcess: ProcessTerminator;
+    logger: Logger;
+}
+export declare function createManagedProcessRegistry(options: ManagedProcessRegistryOptions): ManagedProcessRegistry;
+export declare function createSystemManagedProcessTable(options?: {
+    platform?: NodeJS.Platform;
+    commandRunner?: ManagedProcessCommandRunner;
+}): ManagedProcessTable;
+export declare function createPidTarget(pid: number): TreeKillTarget;
+export {};
+//# sourceMappingURL=managed-processes.d.ts.map

package/dist/server/server/managed-processes/managed-processes.js

@@ -0,0 +1,326 @@
+import { randomUUID } from "node:crypto";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+import { writeJsonFileAtomic } from "../atomic-file.js";
+import { execCommand } from "../../utils/spawn.js";
+const MANAGED_PROCESS_GRACEFUL_SHUTDOWN_TIMEOUT_MS = 5000;
+const MANAGED_PROCESS_FORCE_SHUTDOWN_TIMEOUT_MS = 1000;
+const MANAGED_PROCESS_EXIT_POLL_INTERVAL_MS = 50;
+const MANAGED_PROCESS_ID_PATTERN = /^[a-zA-Z0-9_-]+$/;
+// `ps -o lstart` emits a fixed-width 24-char ctime stamp, e.g. "Sat Jun 20 10:30:40 2026".
+const POSIX_LSTART_WIDTH = 24;
+const ManagedProcessRecordSchema = z.object({
+    id: z.string().min(1),
+    owner: z.object({
+        provider: z.string().min(1),
+        kind: z.string().min(1),
+    }),
+    pid: z.number().int().positive(),
+    command: z.string().min(1),
+    args: z.array(z.string()),
+    metadata: z.record(z.string(), z.unknown()).default({}),
+    identity: z.object({
+        commandLine: z.string().nullable(),
+        startedAt: z.string().nullable(),
+    }),
+    createdAt: z.string().min(1),
+});
+const WindowsProcessSnapshotSchema = z.object({
+    ProcessId: z.number().int().positive(),
+    CommandLine: z.string().nullable().optional(),
+    CreationDate: z.string().nullable().optional(),
+});
+export function createManagedProcessRegistry(options) {
+    return new FileBackedManagedProcessRegistry(options);
+}
+export function createSystemManagedProcessTable(options) {
+    return new SystemManagedProcessTable({
+        platform: options?.platform ?? process.platform,
+        commandRunner: options?.commandRunner ?? {
+            exec: execCommand,
+        },
+    });
+}
+class SystemManagedProcessTable {
+    constructor(options) {
+        this.platform = options.platform;
+        this.commandRunner = options.commandRunner;
+    }
+    async inspect(pid) {
+        if (!Number.isInteger(pid) || pid <= 0) {
+            return { status: "not-found" };
+        }
+        try {
+            return this.platform === "win32"
+                ? await this.inspectWindows(pid)
+                : await this.inspectPosix(pid);
+        }
+        catch (error) {
+            return { status: "error", error };
+        }
+    }
+    async inspectPosix(pid) {
+        let stdout;
+        try {
+            ({ stdout } = await this.commandRunner.exec("ps", [
+                "-ww",
+                "-p",
+                String(pid),
+                "-o",
+                "lstart=",
+                "-o",
+                "command=",
+            ]));
+        }
+        catch (error) {
+            // `ps -p <pid>` exits non-zero when no process matches the pid; a numeric
+            // exit code means ps ran and found nothing, distinct from ps failing to run.
+            return isCommandExitFailure(error) ? { status: "not-found" } : { status: "error", error };
+        }
+        const line = stdout.trimEnd();
+        if (!line) {
+            return { status: "not-found" };
+        }
+        const startedAt = line.slice(0, POSIX_LSTART_WIDTH).trim();
+        const commandLine = line.slice(POSIX_LSTART_WIDTH).trim();
+        return {
+            status: "alive",
+            snapshot: {
+                pid,
+                commandLine: commandLine || null,
+                startedAt: startedAt || null,
+            },
+        };
+    }
+    async inspectWindows(pid) {
+        const command = [
+            `$process = Get-CimInstance Win32_Process -Filter 'ProcessId = ${pid}';`,
+            "if ($process) { $process | Select-Object ProcessId,CommandLine,CreationDate | ConvertTo-Json -Compress }",
+        ].join(" ");
+        const { stdout } = await this.commandRunner.exec("powershell.exe", [
+            "-NoProfile",
+            "-NonInteractive",
+            "-Command",
+            command,
+        ]);
+        const trimmed = stdout.trim();
+        if (!trimmed) {
+            return { status: "not-found" };
+        }
+        const parsed = WindowsProcessSnapshotSchema.parse(JSON.parse(trimmed));
+        return {
+            status: "alive",
+            snapshot: {
+                pid,
+                commandLine: parsed.CommandLine ?? null,
+                startedAt: parsed.CreationDate ?? null,
+            },
+        };
+    }
+}
+class FileBackedManagedProcessRegistry {
+    constructor(options) {
+        this.directory = path.join(options.paseoHome, "runtime", "managed-processes");
+        this.processTable = options.processTable;
+        this.terminateProcess = options.terminateProcess;
+        this.logger = options.logger.child({ module: "managed-processes" });
+    }
+    async record(input) {
+        const inspection = await this.processTable.inspect(input.pid);
+        const snapshot = inspection.status === "alive" ? inspection.snapshot : null;
+        const record = {
+            id: randomUUID(),
+            owner: input.owner,
+            pid: input.pid,
+            command: input.command,
+            args: input.args,
+            metadata: input.metadata ?? {},
+            identity: {
+                commandLine: snapshot?.commandLine ?? null,
+                startedAt: snapshot?.startedAt ?? null,
+            },
+            createdAt: new Date().toISOString(),
+        };
+        await writeJsonFileAtomic(this.recordPath(record.id), record);
+        return record;
+    }
+    async remove(id) {
+        await fs.rm(this.recordPath(id), { force: true });
+    }
+    async list() {
+        const entries = await this.readEntries();
+        return entries.map((entry) => entry.record);
+    }
+    async reapStale() {
+        const result = {
+            checked: 0,
+            dead: 0,
+            mismatched: 0,
+            removed: 0,
+            terminated: 0,
+            errors: [],
+        };
+        for (const entry of await this.readEntries()) {
+            result.checked += 1;
+            try {
+                const inspection = await this.processTable.inspect(entry.record.pid);
+                if (inspection.status === "not-found") {
+                    await fs.rm(entry.path, { force: true });
+                    result.dead += 1;
+                    result.removed += 1;
+                    continue;
+                }
+                if (inspection.status === "error") {
+                    // Inspection failed, so we cannot tell whether the helper is still
+                    // alive. Keep the record and retry on the next reconcile rather than
+                    // orphaning a live process by deleting its record without killing it.
+                    const message = inspection.error instanceof Error ? inspection.error.message : String(inspection.error);
+                    result.errors.push({ id: entry.record.id, message });
+                    this.logger.warn({
+                        err: inspection.error,
+                        id: entry.record.id,
+                        pid: entry.record.pid,
+                        owner: entry.record.owner,
+                    }, "Could not inspect managed helper process; leaving record for next reconcile");
+                    continue;
+                }
+                const snapshot = inspection.snapshot;
+                if (!processIdentityMatches(entry.record, snapshot)) {
+                    await fs.rm(entry.path, { force: true });
+                    result.mismatched += 1;
+                    result.removed += 1;
+                    continue;
+                }
+                await this.terminateProcess(createPidTarget(entry.record.pid), {
+                    gracefulTimeoutMs: MANAGED_PROCESS_GRACEFUL_SHUTDOWN_TIMEOUT_MS,
+                    forceTimeoutMs: MANAGED_PROCESS_FORCE_SHUTDOWN_TIMEOUT_MS,
+                    onForceSignal: () => {
+                        this.logger.warn({
+                            pid: entry.record.pid,
+                            owner: entry.record.owner,
+                            timeoutMs: MANAGED_PROCESS_GRACEFUL_SHUTDOWN_TIMEOUT_MS,
+                        }, "Managed helper process did not exit after SIGTERM; sending SIGKILL");
+                    },
+                });
+                await fs.rm(entry.path, { force: true });
+                result.terminated += 1;
+                result.removed += 1;
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                result.errors.push({ id: entry.record.id, message });
+                this.logger.warn({ err: error, id: entry.record.id, pid: entry.record.pid, owner: entry.record.owner }, "Failed to reap managed helper process");
+            }
+        }
+        return result;
+    }
+    recordPath(id) {
+        if (!MANAGED_PROCESS_ID_PATTERN.test(id)) {
+            throw new Error(`Invalid managed process record id: ${id}`);
+        }
+        return path.join(this.directory, `${id}.json`);
+    }
+    async readEntries() {
+        let fileNames;
+        try {
+            fileNames = await fs.readdir(this.directory);
+        }
+        catch (error) {
+            if (isNodeErrorWithCode(error, "ENOENT")) {
+                return [];
+            }
+            throw error;
+        }
+        const entries = [];
+        for (const fileName of fileNames) {
+            if (!fileName.endsWith(".json")) {
+                continue;
+            }
+            const filePath = path.join(this.directory, fileName);
+            try {
+                const raw = await fs.readFile(filePath, "utf8");
+                const parsed = ManagedProcessRecordSchema.parse(JSON.parse(raw));
+                entries.push({ path: filePath, record: parsed });
+            }
+            catch (error) {
+                // A single corrupt or partially-written record must not abort the whole
+                // reconcile and leave every other leftover un-reaped. Skip it.
+                this.logger.warn({ err: error, file: fileName }, "Skipping unreadable managed process record");
+            }
+        }
+        return entries;
+    }
+}
+function processIdentityMatches(record, snapshot) {
+    if (record.identity.startedAt && snapshot.startedAt) {
+        if (record.identity.startedAt !== snapshot.startedAt) {
+            return false;
+        }
+        return snapshot.commandLine ? commandLineMatchesRecord(record, snapshot.commandLine) : true;
+    }
+    if (record.identity.commandLine && snapshot.commandLine) {
+        return (normalizeCommandLine(record.identity.commandLine) ===
+            normalizeCommandLine(snapshot.commandLine));
+    }
+    return snapshot.commandLine ? commandLineMatchesRecord(record, snapshot.commandLine) : false;
+}
+function commandLineMatchesRecord(record, commandLine) {
+    // Require the command name and args as one contiguous run, not scattered
+    // tokens. Without exact process identity (lstart), a reused PID whose command
+    // line merely mentions "opencode", "serve" and the port elsewhere must not be
+    // mistaken for our leftover and killed.
+    const normalized = normalizeCommandLine(commandLine);
+    const commandName = path.basename(record.command).toLowerCase();
+    const signature = [commandName, ...record.args].map((token) => token.toLowerCase()).join(" ");
+    return normalized.includes(signature);
+}
+function normalizeCommandLine(commandLine) {
+    return commandLine.replace(/\s+/g, " ").trim().toLowerCase();
+}
+export function createPidTarget(pid) {
+    return {
+        pid,
+        exitCode: null,
+        signalCode: null,
+        kill(signal) {
+            process.kill(pid, signal);
+            return true;
+        },
+        // The reaper has no ChildProcess handle for a leftover from a previous
+        // daemon, so it observes exit by polling the pid. Without this, termination
+        // can never see a graceful SIGTERM exit and always waits out the full
+        // graceful+force window before escalating to SIGKILL.
+        once(_event, listener) {
+            const timer = setInterval(() => {
+                if (!isProcessAlive(pid)) {
+                    clearInterval(timer);
+                    listener();
+                }
+            }, MANAGED_PROCESS_EXIT_POLL_INTERVAL_MS);
+            timer.unref();
+        },
+    };
+}
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return isNodeErrorWithCode(error, "EPERM");
+    }
+}
+function isCommandExitFailure(error) {
+    // execFile rejects with a numeric `code` (the process exit status) when the
+    // command ran and exited non-zero; a string `code` (e.g. "ENOENT") means it
+    // never ran.
+    return typeof error?.code === "number";
+}
+function isNodeErrorWithCode(error, code) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === code);
+}
+//# sourceMappingURL=managed-processes.js.map

package/dist/server/server/resolve-worktree-creation-intent.d.ts

@@ -3,16 +3,19 @@ import type { WorktreeSource } from "../utils/worktree.js";
 export type WorktreeCreationIntent = WorktreeSource;
 export type ResolveWorktreeCreationIntentInput = {
     worktreeSlug: string;
+    branchName?: string;
     refName?: string;
     action?: "branch-off";
     githubPrNumber?: undefined;
 } | {
     worktreeSlug?: string;
+    branchName?: string;
     refName?: string;
     action: "checkout";
     githubPrNumber?: number;
 } | {
     worktreeSlug?: string;
+    branchName?: string;
     refName?: string;
     action?: undefined;
     githubPrNumber: number;

package/dist/server/server/resolve-worktree-creation-intent.js

@@ -10,7 +10,7 @@ export async function resolveWorktreeCreationIntent(input, repoRoot, deps) {
         return {
             kind: "branch-off",
             baseBranch: input.refName?.trim() || (await resolveDefaultBranch(repoRoot, deps)),
-            branchName: input.worktreeSlug,
+            branchName: input.branchName ?? input.worktreeSlug,
         };
     }
     if (input.action === "checkout") {
@@ -43,13 +43,13 @@ export async function resolveWorktreeCreationIntent(input, repoRoot, deps) {
         return {
             kind: "branch-off",
             baseBranch: input.refName.trim(),
-            branchName: input.worktreeSlug,
+            branchName: input.branchName ?? input.worktreeSlug,
         };
     }
     return {
         kind: "branch-off",
         baseBranch: await resolveDefaultBranch(repoRoot, deps),
-        branchName: input.worktreeSlug,
+        branchName: input.branchName ?? input.worktreeSlug,
     };
 }
 async function resolveGitHubPrCheckoutIntent(params) {

package/dist/server/server/session/agent-config/agent-config-session.d.ts

@@ -0,0 +1,50 @@
+import type pino from "pino";
+import type { AgentProviderNotice } from "../../agent/agent-sdk-types.js";
+import type { SessionInboundMessage, SessionOutboundMessage } from "../../messages.js";
+export interface AgentConfigSessionHost {
+    emit(msg: SessionOutboundMessage): void;
+}
+/**
+ * The per-agent config mutations this subsystem drives. The shell adapts these
+ * onto the live AgentManager (mode still routes through setAgentModeCommand);
+ * tests wire an in-memory fake. Mode and thinking yield a provider notice; model
+ * and feature do not.
+ */
+export interface AgentConfigOperations {
+    setMode(agentId: string, modeId: string): Promise<AgentProviderNotice | null>;
+    setModel(agentId: string, modelId: string | null): Promise<void>;
+    setFeature(agentId: string, featureId: string, value: unknown): Promise<void>;
+    setThinking(agentId: string, thinkingOptionId: string | null): Promise<AgentProviderNotice | null>;
+}
+export interface AgentConfigSessionOptions {
+    host: AgentConfigSessionHost;
+    operations: AgentConfigOperations;
+    logger: pino.Logger;
+}
+/**
+ * A client's per-agent config surface: set mode, model, feature, and thinking
+ * option. Each request shares one envelope — log, run the mutation, then emit the
+ * accepted response, or on failure emit an activity_log error frame followed by
+ * the rejected response. Reaches no state beyond the injected operations and the
+ * outbound channel.
+ */
+export declare class AgentConfigSession {
+    private readonly host;
+    private readonly operations;
+    private readonly logger;
+    constructor(options: AgentConfigSessionOptions);
+    handleSetAgentModeRequest(msg: Extract<SessionInboundMessage, {
+        type: "set_agent_mode_request";
+    }>): Promise<void>;
+    handleSetAgentModelRequest(msg: Extract<SessionInboundMessage, {
+        type: "set_agent_model_request";
+    }>): Promise<void>;
+    handleSetAgentFeatureRequest(msg: Extract<SessionInboundMessage, {
+        type: "set_agent_feature_request";
+    }>): Promise<void>;
+    handleSetAgentThinkingRequest(msg: Extract<SessionInboundMessage, {
+        type: "set_agent_thinking_request";
+    }>): Promise<void>;
+    private applyConfigChange;
+}
+//# sourceMappingURL=agent-config-session.d.ts.map