@camerontaylor/paseo-server 0.8.0-fork.1

package/dist/server/server/plugins/lifecycle/index.js

@@ -0,0 +1,200 @@
+import { z } from "zod";
+import { CreateAgentRequestMessageSchema } from "@camerontaylor/paseo-protocol/messages";
+import { PARENT_AGENT_ID_LABEL } from "@camerontaylor/paseo-protocol/agent-labels";
+import { WorkspaceCreateRequestSchema } from "@camerontaylor/paseo-protocol/messages";
+export const lifecycleEventNames = [
+    "agent.created",
+    "agent.turn_started",
+    "agent.turn_ended",
+    "agent.permission_requested",
+    "agent.permission_resolved",
+    "agent.archived",
+    "workspace.created",
+    "workspace.archived",
+];
+export const beforeHookNames = ["agent.create", "agent.session_open", "workspace.create"];
+const beforeSchemas = {
+    "agent.create": CreateAgentRequestMessageSchema.pick({ config: true, env: true }).strict(),
+    "agent.session_open": z
+        .object({
+        agentId: z.string(),
+        workspaceId: z.string().nullable(),
+        provider: z.string(),
+        cwd: z.string(),
+        reason: z.enum(["create", "resume", "refresh", "import"]),
+        purpose: z.enum(["interactive", "history"]),
+        env: z.record(z.string(), z.string()),
+    })
+        .strict(),
+    "workspace.create": WorkspaceCreateRequestSchema.omit({ type: true, requestId: true }).strict(),
+};
+export function validateBeforeRequest(name, value) {
+    return beforeSchemas[name].parse(value);
+}
+export function describeHookWorkspace(workspace) {
+    return {
+        id: workspace.workspaceId,
+        projectId: workspace.projectId,
+        cwd: workspace.cwd,
+        name: workspace.title,
+        archivedAt: workspace.archivedAt,
+    };
+}
+export function describeHookAgent(agent) {
+    return {
+        id: agent.id,
+        workspaceId: agent.workspaceId ?? null,
+        parentAgentId: agent.labels[PARENT_AGENT_ID_LABEL] ?? null,
+        provider: agent.provider,
+        cwd: agent.cwd,
+        title: agent.title ?? null,
+    };
+}
+export function publishAgentStream(lifecycle, agent, event, timeline) {
+    if (event.type === "turn_started") {
+        lifecycle.emit("agent.turn_started", { agent, turnId: event.turnId ?? null });
+    }
+    else if (event.type === "turn_completed") {
+        lifecycle.emit("agent.turn_ended", {
+            agent,
+            turnId: event.turnId ?? null,
+            timeline,
+            outcome: { kind: "completed" },
+        });
+    }
+    else if (event.type === "turn_failed") {
+        lifecycle.emit("agent.turn_ended", {
+            agent,
+            turnId: event.turnId ?? null,
+            timeline,
+            outcome: { kind: "failed", error: { message: event.error, code: event.code } },
+        });
+    }
+    else if (event.type === "turn_canceled") {
+        lifecycle.emit("agent.turn_ended", {
+            agent,
+            turnId: event.turnId ?? null,
+            timeline,
+            outcome: { kind: "canceled", reason: event.reason },
+        });
+    }
+    else if (event.type === "permission_requested") {
+        lifecycle.emit("agent.permission_requested", { agent, request: event.request });
+    }
+    else if (event.type === "permission_resolved") {
+        lifecycle.emit("agent.permission_resolved", {
+            agent,
+            requestId: event.requestId,
+            resolution: event.resolution,
+        });
+    }
+}
+export function validateBeforeResult(name, input, output) {
+    const result = validateBeforeRequest(name, output);
+    if (name === "agent.session_open") {
+        const previous = beforeSchemas["agent.session_open"].parse(input);
+        const next = beforeSchemas["agent.session_open"].parse(result);
+        if (previous.agentId !== next.agentId ||
+            previous.workspaceId !== next.workspaceId ||
+            previous.provider !== next.provider ||
+            previous.cwd !== next.cwd ||
+            previous.reason !== next.reason ||
+            previous.purpose !== next.purpose) {
+            throw new Error("agent.session_open hooks can only change env");
+        }
+    }
+    if (name === "agent.create") {
+        const previous = beforeSchemas["agent.create"].parse(input);
+        const next = beforeSchemas["agent.create"].parse(result);
+        if (previous.config.cwd !== next.config.cwd) {
+            throw new Error("agent.create hooks cannot change the workspace directory");
+        }
+    }
+    return result;
+}
+export class PluginHookHandlers {
+    constructor(changed) {
+        this.events = new Map();
+        this.transforms = new Map();
+        this.active = new Map();
+        this.on = (name, handler) => {
+            if (!lifecycleEventNames.includes(name)) {
+                throw new Error(`Unknown lifecycle event: ${name}`);
+            }
+            return this.register(this.events, name, handler);
+        };
+        this.before = (name, handler) => {
+            if (!beforeHookNames.includes(name)) {
+                throw new Error(`Unknown before hook: ${name}`);
+            }
+            return this.register(this.transforms, name, handler);
+        };
+        this.changed = changed;
+    }
+    catalog() {
+        return { events: [...this.events.keys()], before: [...this.transforms.keys()] };
+    }
+    async invoke(id, kind, name, input, paseo) {
+        const controller = new AbortController();
+        this.active.set(id, controller);
+        try {
+            if (kind === "before") {
+                if (!beforeHookNames.includes(name)) {
+                    throw new Error(`Unknown before hook: ${name}`);
+                }
+                const hookName = name;
+                let request = validateBeforeRequest(hookName, input);
+                for (const handler of this.transforms.get(name) ?? []) {
+                    controller.signal.throwIfAborted();
+                    const result = await handler({ request: structuredClone(request) }, { paseo, signal: controller.signal });
+                    if (result !== undefined) {
+                        request = validateBeforeResult(hookName, request, result);
+                    }
+                }
+                return request;
+            }
+            for (const handler of this.events.get(name) ?? []) {
+                controller.signal.throwIfAborted();
+                try {
+                    await handler(structuredClone(input), { paseo, signal: controller.signal });
+                }
+                catch (error) {
+                    console.error(`Lifecycle hook ${name} failed`, error);
+                }
+            }
+            return null;
+        }
+        finally {
+            this.active.delete(id);
+        }
+    }
+    cancel(id) {
+        this.active.get(id)?.abort();
+    }
+    close() {
+        for (const controller of this.active.values()) {
+            controller.abort();
+        }
+        this.events.clear();
+        this.transforms.clear();
+    }
+    register(registry, name, handler) {
+        let handlers = registry.get(name);
+        if (!handlers) {
+            handlers = new Set();
+            registry.set(name, handlers);
+        }
+        handlers.add(handler);
+        this.changed();
+        return () => {
+            if (!handlers.delete(handler)) {
+                return;
+            }
+            if (handlers.size === 0) {
+                registry.delete(name);
+            }
+            this.changed();
+        };
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/server/server/plugins/managed-source.d.ts

@@ -0,0 +1,50 @@
+import { z } from "zod";
+import { type PluginSourceStatusItem } from "@camerontaylor/paseo-protocol/messages";
+import type { PluginManifest } from "./manifest.js";
+declare const ManagedPluginRecordSchema: z.ZodObject<{
+    remote: z.ZodString;
+    requestedRef: z.ZodNullable<z.ZodString>;
+    trackingBranch: z.ZodNullable<z.ZodString>;
+    commit: z.ZodString;
+    pluginPath: z.ZodString;
+    checkoutRoot: z.ZodString;
+}, z.core.$strict>;
+export interface ManagedPluginRecord extends z.infer<typeof ManagedPluginRecordSchema> {
+}
+export interface ManagedPluginCandidate {
+    build: PluginManifest["build"];
+    defaultId: string;
+    directory: string;
+    record: ManagedPluginRecord;
+    versionRoot: string;
+}
+interface InstallInput {
+    source: string;
+    ref?: string;
+    pluginPath?: string;
+}
+export declare class ManagedPluginSources {
+    private readonly root;
+    private readonly metadataPath;
+    private readonly records;
+    constructor(paseoHome: string);
+    get(pluginId: string): ManagedPluginRecord | null;
+    displayRemote(pluginId: string): string | null;
+    prepareInstall(input: InstallInput): Promise<ManagedPluginCandidate>;
+    place(pluginId: string, candidate: ManagedPluginCandidate): Promise<ManagedPluginCandidate>;
+    status(pluginId: string, configuredPath: string): Promise<PluginSourceStatusItem>;
+    prepareUpdate(pluginId: string, configuredPath: string): Promise<{
+        candidate: ManagedPluginCandidate | null;
+        commits: number;
+    }>;
+    commit(pluginId: string, record: ManagedPluginRecord): void;
+    discard(candidate: ManagedPluginCandidate): Promise<void>;
+    removeVersion(record: ManagedPluginRecord): Promise<void>;
+    remove(pluginId: string): Promise<void>;
+    private prepareCommit;
+    private createStagingRoot;
+    private readRecords;
+    private writeRecords;
+}
+export {};
+//# sourceMappingURL=managed-source.d.ts.map

package/dist/server/server/plugins/managed-source.js

@@ -0,0 +1,327 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { mkdir, rename, rm } from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { PluginIdSchema } from "@camerontaylor/paseo-protocol/messages";
+import { runGitCommand } from "../../utils/run-git-command.js";
+import { ensurePrivateDirectory, writePrivateFileAtomicSync } from "../private-files.js";
+import { readPluginManifest } from "./manifest.js";
+const GIT_TIMEOUT_MS = 120000;
+const GIT_ENV = { GIT_TERMINAL_PROMPT: "0" };
+const ManagedPluginRecordSchema = z
+    .object({
+    remote: z.string().min(1),
+    requestedRef: z.string().min(1).nullable(),
+    trackingBranch: z.string().min(1).nullable(),
+    commit: z.string().regex(/^[0-9a-f]{40,64}$/),
+    pluginPath: z.string(),
+    checkoutRoot: z.string().min(1),
+})
+    .strict();
+const ManagedPluginRecordsSchema = z.record(PluginIdSchema, ManagedPluginRecordSchema);
+export class ManagedPluginSources {
+    constructor(paseoHome) {
+        this.root = path.join(paseoHome, "plugins");
+        this.metadataPath = path.join(this.root, "sources.json");
+        this.records = this.readRecords();
+    }
+    get(pluginId) {
+        return this.records[pluginId] ?? null;
+    }
+    displayRemote(pluginId) {
+        const remote = this.records[pluginId]?.remote;
+        return remote ? redactRemoteCredentials(remote) : null;
+    }
+    async prepareInstall(input) {
+        const remote = normalizeGitSource(input.source);
+        const pluginPath = normalizePluginPath(input.pluginPath);
+        const stagingRoot = await this.createStagingRoot();
+        try {
+            const checkoutRoot = path.join(stagingRoot, "checkout");
+            await clone(remote, checkoutRoot);
+            const resolution = await resolveRequestedRef(checkoutRoot, input.ref);
+            await checkout(checkoutRoot, resolution.commit);
+            const directory = path.resolve(checkoutRoot, pluginPath);
+            assertPluginPath(checkoutRoot, directory);
+            const { id: defaultId, build } = await readPluginManifest(directory);
+            return {
+                build,
+                defaultId,
+                directory,
+                record: {
+                    remote,
+                    requestedRef: resolution.requestedRef,
+                    trackingBranch: resolution.trackingBranch,
+                    commit: resolution.commit,
+                    pluginPath,
+                    checkoutRoot,
+                },
+                versionRoot: stagingRoot,
+            };
+        }
+        catch (error) {
+            await rm(stagingRoot, { recursive: true, force: true });
+            throw error;
+        }
+    }
+    async place(pluginId, candidate) {
+        const pluginRoot = path.join(this.root, pluginId);
+        ensurePrivateDirectory(pluginRoot);
+        const versionRoot = path.join(pluginRoot, `${candidate.record.commit.slice(0, 12)}-${randomUUID()}`);
+        await rename(candidate.versionRoot, versionRoot);
+        const checkoutRoot = path.join(versionRoot, "checkout");
+        const directory = path.resolve(checkoutRoot, candidate.record.pluginPath);
+        return {
+            ...candidate,
+            directory,
+            versionRoot,
+            record: { ...candidate.record, checkoutRoot },
+        };
+    }
+    async status(pluginId, configuredPath) {
+        const record = this.records[pluginId];
+        if (!record)
+            return { id: pluginId, source: "directory", path: configuredPath };
+        if (!record.trackingBranch) {
+            return {
+                id: pluginId,
+                source: "git",
+                path: configuredPath,
+                remote: redactRemoteCredentials(record.remote),
+                ref: record.requestedRef ?? record.commit,
+                currentCommit: record.commit,
+                latestCommit: record.commit,
+                commitsBehind: 0,
+                updateAvailable: false,
+            };
+        }
+        await fetchOrigin(record.checkoutRoot);
+        const latestCommit = await revParse(record.checkoutRoot, `refs/remotes/origin/${record.trackingBranch}^{commit}`);
+        const commitsBehind = await countCommits(record.checkoutRoot, record.commit, latestCommit);
+        return {
+            id: pluginId,
+            source: "git",
+            path: configuredPath,
+            remote: redactRemoteCredentials(record.remote),
+            ref: record.requestedRef ?? record.trackingBranch,
+            currentCommit: record.commit,
+            latestCommit,
+            commitsBehind,
+            updateAvailable: latestCommit !== record.commit,
+        };
+    }
+    async prepareUpdate(pluginId, configuredPath) {
+        const record = this.records[pluginId];
+        if (!record)
+            throw new Error(`Plugin is not managed by Git: ${pluginId}`);
+        const status = await this.status(pluginId, configuredPath);
+        const latestCommit = status.latestCommit;
+        if (!latestCommit || latestCommit === record.commit)
+            return { candidate: null, commits: 0 };
+        const candidate = await this.prepareCommit(record, latestCommit);
+        return { candidate, commits: status.commitsBehind ?? 0 };
+    }
+    commit(pluginId, record) {
+        this.records[pluginId] = record;
+        this.writeRecords();
+    }
+    async discard(candidate) {
+        await rm(candidate.versionRoot, { recursive: true, force: true });
+    }
+    async removeVersion(record) {
+        const versionRoot = path.dirname(record.checkoutRoot);
+        const pluginRoot = path.dirname(versionRoot);
+        const expectedRoot = path.resolve(this.root);
+        if (path.dirname(pluginRoot) !== expectedRoot) {
+            throw new Error(`Managed plugin checkout is outside the plugin store: ${record.checkoutRoot}`);
+        }
+        await rm(versionRoot, { recursive: true, force: true });
+    }
+    async remove(pluginId) {
+        if (!this.records[pluginId])
+            return;
+        delete this.records[pluginId];
+        this.writeRecords();
+        await rm(path.join(this.root, pluginId), { recursive: true, force: true });
+    }
+    async prepareCommit(record, commit) {
+        const stagingRoot = await this.createStagingRoot();
+        try {
+            const checkoutRoot = path.join(stagingRoot, "checkout");
+            await clone(record.remote, checkoutRoot);
+            const resolvedCommit = await revParse(checkoutRoot, `${commit}^{commit}`);
+            if (resolvedCommit !== commit)
+                throw new Error(`Git source no longer contains commit ${commit}`);
+            await checkout(checkoutRoot, commit);
+            const directory = path.resolve(checkoutRoot, record.pluginPath);
+            assertPluginPath(checkoutRoot, directory);
+            const { id: defaultId, build } = await readPluginManifest(directory);
+            return {
+                build,
+                defaultId,
+                directory,
+                versionRoot: stagingRoot,
+                record: { ...record, commit, checkoutRoot },
+            };
+        }
+        catch (error) {
+            await rm(stagingRoot, { recursive: true, force: true });
+            throw error;
+        }
+    }
+    async createStagingRoot() {
+        const stagingRoot = path.join(this.root, ".staging", randomUUID());
+        await mkdir(stagingRoot, { recursive: true, mode: 0o700 });
+        return stagingRoot;
+    }
+    readRecords() {
+        if (!existsSync(this.metadataPath))
+            return {};
+        return ManagedPluginRecordsSchema.parse(JSON.parse(readFileSync(this.metadataPath, "utf8")));
+    }
+    writeRecords() {
+        writePrivateFileAtomicSync(this.metadataPath, `${JSON.stringify(this.records, null, 2)}\n`);
+    }
+}
+function normalizeGitSource(source) {
+    const github = /^([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)$/.exec(source);
+    if (github) {
+        const repository = github[2].replace(/\.git$/, "");
+        return `https://github.com/${github[1]}/${repository}.git`;
+    }
+    const isUrl = /^(?:https?|ssh|git|file):\/\//.test(source);
+    const isScpStyle = /^[^/@\s]+@[^:\s]+:.+$/.test(source);
+    if (isUrl || isScpStyle)
+        return source;
+    throw new Error(`Plugin source is neither an existing directory nor a Git URL: ${source}`);
+}
+function redactRemoteCredentials(remote) {
+    if (!/^(?:https?|ssh|git|file):\/\//.test(remote))
+        return remote;
+    const url = new URL(remote);
+    url.username = "";
+    url.password = "";
+    return url.href;
+}
+function normalizePluginPath(pluginPath) {
+    if (!pluginPath || pluginPath === ".")
+        return ".";
+    if (path.isAbsolute(pluginPath))
+        throw new Error("Plugin path must be relative to the repository");
+    const normalized = path.normalize(pluginPath);
+    if (normalized === ".." || normalized.startsWith(`..${path.sep}`)) {
+        throw new Error("Plugin path must stay inside the repository");
+    }
+    return normalized;
+}
+function assertPluginPath(checkoutRoot, directory) {
+    const relative = path.relative(checkoutRoot, directory);
+    if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+        throw new Error("Plugin path escapes the repository");
+    }
+}
+async function clone(remote, checkoutRoot) {
+    const publicRemote = redactRemoteCredentials(remote);
+    const cloneRemote = publicRemote === remote ? remote : "https://paseo.invalid/plugin.git";
+    const envOverlay = cloneRemote === remote
+        ? GIT_ENV
+        : {
+            ...GIT_ENV,
+            GIT_CONFIG_COUNT: "1",
+            GIT_CONFIG_KEY_0: `url.${remote}.insteadOf`,
+            GIT_CONFIG_VALUE_0: cloneRemote,
+        };
+    try {
+        await runGitCommand(["clone", "--no-checkout", "--", cloneRemote, checkoutRoot], {
+            cwd: path.dirname(checkoutRoot),
+            envOverlay,
+            timeout: GIT_TIMEOUT_MS,
+        });
+    }
+    catch (error) {
+        throw redactRemoteError(error, remote);
+    }
+}
+function redactRemoteError(error, remote) {
+    let message = error instanceof Error ? error.message : String(error);
+    const publicRemote = redactRemoteCredentials(remote);
+    message = message.split(remote).join(publicRemote);
+    if (!/^(?:https?|ssh|git|file):\/\//.test(remote))
+        return new Error(message);
+    const url = new URL(remote);
+    for (const credential of [url.username, url.password]) {
+        if (!credential)
+            continue;
+        message = message.split(credential).join("[redacted]");
+        let decoded = credential;
+        try {
+            decoded = decodeURIComponent(credential);
+        }
+        catch {
+            // URL credentials can contain a literal percent sign.
+        }
+        if (decoded !== credential)
+            message = message.split(decoded).join("[redacted]");
+    }
+    return new Error(message);
+}
+async function checkout(checkoutRoot, commit) {
+    await runGitCommand(["checkout", "--detach", commit], {
+        cwd: checkoutRoot,
+        envOverlay: GIT_ENV,
+        timeout: GIT_TIMEOUT_MS,
+    });
+    await runGitCommand(["submodule", "update", "--init", "--recursive"], {
+        cwd: checkoutRoot,
+        envOverlay: GIT_ENV,
+        timeout: GIT_TIMEOUT_MS,
+    });
+}
+async function resolveRequestedRef(checkoutRoot, requestedRef) {
+    if (!requestedRef) {
+        const { stdout } = await runGitCommand(["symbolic-ref", "--short", "refs/remotes/origin/HEAD"], { cwd: checkoutRoot });
+        const trackingBranch = stdout.trim().replace(/^origin\//, "");
+        const commit = await revParse(checkoutRoot, `refs/remotes/origin/${trackingBranch}^{commit}`);
+        return { commit, requestedRef: null, trackingBranch };
+    }
+    if (requestedRef.startsWith("-"))
+        throw new Error("Plugin Git ref cannot start with '-'");
+    const branchRef = `refs/remotes/origin/${requestedRef}`;
+    if (await refExists(checkoutRoot, branchRef)) {
+        const commit = await revParse(checkoutRoot, `${branchRef}^{commit}`);
+        return { commit, requestedRef, trackingBranch: requestedRef };
+    }
+    const tagRef = `refs/tags/${requestedRef}`;
+    if (await refExists(checkoutRoot, tagRef)) {
+        const commit = await revParse(checkoutRoot, `${tagRef}^{commit}`);
+        return { commit, requestedRef, trackingBranch: null };
+    }
+    const commit = await revParse(checkoutRoot, `${requestedRef}^{commit}`);
+    return { commit, requestedRef, trackingBranch: null };
+}
+async function refExists(cwd, ref) {
+    const result = await runGitCommand(["show-ref", "--verify", "--quiet", ref], {
+        cwd,
+        acceptExitCodes: [0, 1],
+    });
+    return result.exitCode === 0;
+}
+async function revParse(cwd, ref) {
+    const { stdout } = await runGitCommand(["rev-parse", "--verify", ref], { cwd });
+    return stdout.trim();
+}
+async function fetchOrigin(cwd) {
+    await runGitCommand(["fetch", "--prune", "--tags", "origin"], {
+        cwd,
+        envOverlay: GIT_ENV,
+        timeout: GIT_TIMEOUT_MS,
+    });
+}
+async function countCommits(cwd, current, latest) {
+    if (current === latest)
+        return 0;
+    const { stdout } = await runGitCommand(["rev-list", "--count", `${current}..${latest}`], { cwd });
+    return Number.parseInt(stdout.trim(), 10);
+}
+//# sourceMappingURL=managed-source.js.map

package/dist/server/server/plugins/manifest.d.ts

@@ -0,0 +1,12 @@
+import { z } from "zod";
+declare const PluginManifestSchema: z.ZodObject<{
+    id: z.ZodString;
+    requirements: z.ZodOptional<z.ZodObject<{
+        paseo: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    build: z.ZodOptional<z.ZodArray<z.ZodArray<z.ZodString>>>;
+}, z.core.$strict>;
+export type PluginManifest = z.infer<typeof PluginManifestSchema>;
+export declare function readPluginManifest(directory: string): Promise<PluginManifest>;
+export {};
+//# sourceMappingURL=manifest.d.ts.map

package/dist/server/server/plugins/manifest.js

@@ -0,0 +1,26 @@
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { PluginIdSchema, PluginRequirementsSchema } from "@camerontaylor/paseo-protocol/messages";
+import { validatePluginRequirements } from "@camerontaylor/paseo-protocol/plugin-requirements";
+const MANIFEST_FILENAME = "paseo-plugin.json";
+const PluginBuildCommandSchema = z
+    .array(z.string().refine((argument) => argument.trim().length > 0))
+    .min(1);
+const PluginManifestSchema = z
+    .object({
+    id: PluginIdSchema,
+    requirements: PluginRequirementsSchema.strict().optional(),
+    build: z.array(PluginBuildCommandSchema).min(1).optional(),
+})
+    .strict();
+export async function readPluginManifest(directory) {
+    const manifestPath = path.join(directory, MANIFEST_FILENAME);
+    const info = await stat(manifestPath).catch(() => null);
+    if (!info?.isFile())
+        throw new Error(`Plugin manifest is missing: ${manifestPath}`);
+    const manifest = PluginManifestSchema.parse(JSON.parse(await readFile(manifestPath, "utf8")));
+    validatePluginRequirements(manifest.requirements);
+    return manifest;
+}
+//# sourceMappingURL=manifest.js.map