Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

16.9 KB
Raw Blame
/**
 * An Agent's installed hook packages:
 *   GET    /api/projects/:p/agents/:a/hooks               # installed packages (any member)
 *   POST   /api/projects/:p/agents/:a/hooks/archive       # install one package from an uploaded zip (any member)
 *   GET    /api/projects/:p/agents/:a/hooks/:name/archive # export one installed package as a zip (any member)
 *   DELETE /api/projects/:p/agents/:a/hooks/:name         # uninstall (any member)
 * Whether a Session runs hooks at all is not decided here: that is the Agent-level
 * `hooks.enabled` switch, written through the config route.
 * Installing from the library goes through the plugin routes (plugins.ts), which write a
 * plugin's hook package to agent_state/hooks/<plugin>/ (hooks.json + scripts). The archive
 * routes are the skills routes' pair: POST writes every zip file under hooks/<name>/ (replace
 * semantics with `overwrite`), GET packs the whole directory back under a single top-level
 * <name>/ so the download round-trips through the POST unchanged. Every mutation here
 * invalidates the Agent's cached runtimes: core reads hook packages when a model context
 * opens, so a conversation that is running would otherwise keep the old set until its next
 * compaction. Rebuilding the runtime re-reads them on the next Task instead — which is what
 * lets a package installed from this page start a goal in the conversation already open.
 */
import fs from "node:fs/promises";
import path from "node:path";
import { unzipSync, strFromU8, zipSync } from "fflate";
import { Hono } from "hono";
import {
  PLUGIN_NAME_PATTERN,
  hooksDir,
  listInstalledHooks,
  parsePluginVersion,
  removeHook,
  replaceSkillDirectory,
} from "@adelie/core";
import type { HookCommand, HookManifest } from "@adelie/core";
import type { AgentHooksResponse, HookItem } from "../../api/types.js";
import type { AppEnv } from "../../auth/middleware.js";
import type { PluginsRouteDeps } from "./plugins.js";
import { HttpError } from "../errors.js";
import { badRequest, readJson, requireString, requireValidId } from "../validate.js";
import { toHookItem } from "../../services/plugin-library.js";
import {
  MAX_ARCHIVE_FILES,
  MAX_FILE_BYTES,
  MAX_TOTAL_BYTES,
} from "../../services/skill-import-limits.js";
import { MAX_ARCHIVE_BYTES, assertSafeEntryPath } from "./skills.js";

/** The hook points a manifest lists commands for. */
const HOOK_POINTS = ["stop", "pre_tool_use", "user_prompt"] as const;

/** A hook package decoded from an uploaded zip: its name and every file keyed by path relative to the package directory. */
interface ArchiveHook {
  name: string;
  files: Map<string, Uint8Array>;
}

/** A command path as hooks.json may list it: relative, "/"-separated, no empty or ".." segment — so it resolves inside the package directory. */
function isSafeCommandPath(command: string): boolean {
  return (
    command.length > 0 &&
    !command.startsWith("/") &&
    !/^[A-Za-z]:/.test(command) &&
    !command.includes("\\") &&
    !command.split("/").some((segment) => segment === "" || segment === "..")
  );
}

/**
 * Validates an uploaded manifest against the files beside it and returns the one that is
 * written: the upload with its unknown fields kept (an export re-imports as it was), `name`
 * set to the package's name, and the hook-point lists defaulted so the loader and the Session
 * always find arrays. What is checked is what those readers rely on: a name in the
 * directory-name character set, string display fields, and every command a relative path to a
 * file inside the archive — a package whose scripts are missing or point outside its directory
 * is refused. A stray `enabled` (a package exported while the per-package switch existed) is
 * dropped: hooks are switched at the Agent level now, and the field means nothing on disk.
 */
function normalizeHookManifest(
  raw: unknown,
  name: string | undefined,
  files: ReadonlySet<string>,
): HookManifest {
  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
    throw badRequest("hooks.json must be a JSON object.");
  }
  const manifest = raw as Record<string, unknown>;
  const resolved = name ?? manifest.name;
  if (typeof resolved !== "string" || !PLUGIN_NAME_PATTERN.test(resolved)) {
    throw badRequest(
      `Invalid hook package name ${JSON.stringify(resolved)}: only letters, digits, "_" and "-" are allowed.`,
    );
  }
  for (const key of ["description", "description_zh", "version"] as const) {
    if (manifest[key] !== undefined && typeof manifest[key] !== "string") {
      throw badRequest(`hooks.json ${key} must be a string.`);
    }
  }
  const lists: Record<(typeof HOOK_POINTS)[number], HookCommand[]> = {
    stop: [],
    pre_tool_use: [],
    user_prompt: [],
  };
  let commands = 0;
  for (const point of HOOK_POINTS) {
    const list = manifest[point];
    if (list === undefined) continue;
    if (!Array.isArray(list)) throw badRequest(`hooks.json ${point} must be an array.`);
    for (const entry of list as unknown[]) {
      const cmd = entry as Partial<HookCommand> | null;
      if (cmd === null || typeof cmd !== "object" || typeof cmd.command !== "string") {
        throw badRequest(`hooks.json ${point} entries must be { command, timeout? } objects.`);
      }
      if (!isSafeCommandPath(cmd.command) || !files.has(cmd.command)) {
        throw badRequest(
          `hooks.json ${point} command ${JSON.stringify(cmd.command)} must name a file inside the package.`,
        );
      }
      if (cmd.timeout !== undefined && !(typeof cmd.timeout === "number" && cmd.timeout > 0)) {
        throw badRequest(`hooks.json ${point} timeout must be a positive number of seconds.`);
      }
      if (cmd.trigger !== undefined && cmd.trigger !== "prompt" && cmd.trigger !== "host") {
        throw badRequest(`hooks.json ${point} trigger must be "prompt" or "host".`);
      }
      commands += 1;
    }
    lists[point] = list as HookCommand[];
  }
  if (commands === 0) throw badRequest("hooks.json lists no hook-point commands.");
  const { enabled: _dropped, ...rest } = manifest;
  return {
    ...rest,
    name: resolved,
    description: typeof manifest.description === "string" ? manifest.description : "",
    version: typeof manifest.version === "string" ? manifest.version : "",
    ...lists,
  } as HookManifest;
}

/**
 * Decodes and validates an uploaded hook package zip. Accepted layouts: hooks.json at the zip
 * root (the name comes from the manifest), or exactly one top-level directory containing
 * hooks.json (the directory name is the package name, consistent with listInstalledHooks
 * where the directory name always wins). Directory entries are ignored (paths recreate
 * them); every file path is zip-slip-checked and the count/size limits enforced before
 * anything is returned. The manifest comes back normalized (see normalizeHookManifest) in
 * place of the uploaded bytes.
 *
 * The path and size checks run in unzipSync's `filter`, i.e. off the central directory's
 * DECLARED sizes and before a byte is inflated. A cap read off the inflated result bounds
 * nothing, in two separate ways. Honest entries: 256KB of deflated zeros — three orders of
 * magnitude under the request cap — is already 256MB on the heap by the time such a cap runs.
 * Lying entries are worse: unzipSync allocates the declared size and inflates into it, so a
 * 123-byte archive whose 5-byte entry declares 512MB allocates 512MB, and what comes back is
 * a 5-byte VIEW of that buffer — a check on the returned bytes sees 5 and installs it.
 */
function parseHookArchive(archive: Buffer): ArchiveHook {
  let count = 0;
  let total = 0;
  let entries: Record<string, Uint8Array>;
  try {
    entries = unzipSync(new Uint8Array(archive), {
      filter: (file) => {
        if (file.name.endsWith("/")) return false;
        assertSafeEntryPath(file.name);
        count += 1;
        if (count > MAX_ARCHIVE_FILES) {
          throw badRequest(`The zip archive exceeds the ${MAX_ARCHIVE_FILES}-file limit.`);
        }
        if (file.originalSize > MAX_FILE_BYTES) {
          throw badRequest(`Zip entry exceeds the 5MB uncompressed limit: ${file.name}`);
        }
        total += file.originalSize;
        if (total > MAX_TOTAL_BYTES) {
          throw badRequest("The zip archive exceeds the 20MB uncompressed limit.");
        }
        return true;
      },
    });
  } catch (err) {
    // A cap the filter tripped is the answer; anything else means the bytes are not a zip.
    if (err instanceof HttpError) throw err;
    throw badRequest("dataBase64 is not a valid zip archive.");
  }
  const files = Object.entries(entries);
  if (files.length === 0) throw badRequest("The zip archive contains no files.");
  const names = files.map(([name]) => name);
  let prefix = "";
  let dirName: string | undefined;
  if (!names.includes("hooks.json")) {
    const topLevels = new Set(names.map((name) => name.split("/", 1)[0]!));
    dirName = topLevels.size === 1 ? [...topLevels][0] : undefined;
    if (dirName === undefined || !names.includes(`${dirName}/hooks.json`)) {
      throw badRequest(
        "The zip must contain hooks.json at its root, or exactly one top-level directory containing hooks.json.",
      );
    }
    prefix = `${dirName}/`;
    // A file entry named exactly `<dirName>` (no slash) shares the single top level with the
    // directory: stripping the prefix would leave an empty relative path, and writing it would
    // hit the staging directory itself (EISDIR) after validation had already passed.
    if (names.includes(dirName)) {
      throw badRequest(`Invalid zip entry path (it is the package directory): ${dirName}`);
    }
  }
  const relative = new Map(files.map(([n, data]) => [n.slice(prefix.length), data]));
  let raw: unknown;
  try {
    raw = JSON.parse(strFromU8(relative.get("hooks.json")!));
  } catch {
    throw badRequest("hooks.json is not valid JSON.");
  }
  const manifest = normalizeHookManifest(raw, dirName, new Set(relative.keys()));
  relative.set("hooks.json", new TextEncoder().encode(`${JSON.stringify(manifest, null, 2)}\n`));
  return { name: manifest.name, files: relative };
}

/**
 * Collects an installed package directory as zip entries under a single top-level `<name>/`
 * (subpaths preserved, "/" separators), so the export round-trips through the POST archive
 * route unchanged. Symlinks and other non-regular entries are skipped (nothing outside the
 * directory can leak). The import caps apply on the way out too — a directory exceeding them
 * could not be re-imported anyway.
 */
async function collectHookArchive(dir: string, name: string): Promise<Record<string, Uint8Array>> {
  const out: Record<string, Uint8Array> = {};
  let count = 0;
  let total = 0;
  const walk = async (abs: string, rel: string): Promise<void> => {
    for (const entry of await fs.readdir(abs, { withFileTypes: true })) {
      const absChild = path.join(abs, entry.name);
      const relChild = `${rel}/${entry.name}`;
      if (entry.isDirectory()) {
        await walk(absChild, relChild);
        continue;
      }
      if (!entry.isFile()) continue;
      count += 1;
      const data = new Uint8Array(await fs.readFile(absChild));
      total += data.byteLength;
      if (
        count > MAX_ARCHIVE_FILES ||
        data.byteLength > MAX_FILE_BYTES ||
        total > MAX_TOTAL_BYTES
      ) {
        throw new HttpError(
          413,
          "hook_too_large",
          `Hook package exceeds the archive limits (${MAX_ARCHIVE_FILES} files, 5MB per file, 20MB total).`,
        );
      }
      out[relChild] = data;
    }
  };
  await walk(dir, name);
  return out;
}

/** /api/projects/:p/agents/:a/hooks: read, import/export and uninstall are all Project-member operations. */
export function agentHooksRoutes(deps: PluginsRouteDeps): Hono<AppEnv> {
  const app = new Hono<AppEnv>();

  const installedItems = async (projectId: string, agentId: string): Promise<HookItem[]> =>
    (await listInstalledHooks(deps.config.root, projectId, agentId)).map(toHookItem);

  /** The install criterion every per-package route shares, the one listInstalledHooks uses: hooks/<name>/hooks.json exists. Returns the package directory. */
  const requireInstalled = async (
    projectId: string,
    agentId: string,
    name: string,
  ): Promise<string> => {
    const dir = path.join(hooksDir(deps.config.root, projectId, agentId), name);
    try {
      await fs.access(path.join(dir, "hooks.json"));
    } catch {
      throw new HttpError(404, "not_found", `Hook package is not installed: ${name}`);
    }
    return dir;
  };

  app.get("/", async (c) => {
    // Defensive id validation happens before any path construction: prevents path traversal for cross-Project privilege escalation.
    const projectId = requireValidId(c, "projectId");
    const agentId = requireValidId(c, "agentId");
    deps.access.requireProjectAccess(c.var.user.userId, projectId);
    await deps.agentConfigService.requireExists(projectId, agentId);
    return c.json({ hooks: await installedItems(projectId, agentId) } satisfies AgentHooksResponse);
  });

  // Install one package from an uploaded zip (member-level, like the skills archive route).
  app.post("/archive", async (c) => {
    const projectId = requireValidId(c, "projectId");
    const agentId = requireValidId(c, "agentId");
    deps.access.requireProjectAccess(c.var.user.userId, projectId);
    await deps.agentConfigService.requireExists(projectId, agentId);
    const body = await readJson(c);
    const dataBase64 = requireString(body, "dataBase64", { minLen: 1, maxLen: 20 * 1024 * 1024 });
    const overwrite = body.overwrite === true;
    let archive: Buffer;
    try {
      archive = Buffer.from(dataBase64, "base64");
    } catch {
      throw badRequest("dataBase64 is not valid base64.");
    }
    if (archive.byteLength === 0) throw badRequest("The zip archive is empty.");
    if (archive.byteLength > MAX_ARCHIVE_BYTES) {
      throw badRequest("The zip archive exceeds the 14MB limit.");
    }
    const hook = parseHookArchive(archive);
    const dir = path.join(hooksDir(deps.config.root, projectId, agentId), hook.name);
    if (!overwrite) {
      const installed = await fs.access(path.join(dir, "hooks.json")).then(
        () => true,
        () => false,
      );
      if (installed) {
        // The name sits at the end of the message: the web tab reads it from there for the
        // overwrite confirmation copy.
        throw new HttpError(409, "hook_exists", `Hook package is already installed: ${hook.name}`);
      }
    }
    // Replace semantics (the same as reinstalling from the library): the archive's files are
    // staged and swapped in, so no stale file survives and an interrupted import leaves no
    // half-written package behind.
    await replaceSkillDirectory(dir, hook.files);
    deps.manager.invalidateAgentRuntimes(projectId, agentId);
    return c.json(
      { hooks: await installedItems(projectId, agentId) } satisfies AgentHooksResponse,
      201,
    );
  });

  // Export one installed package as a zip: a direct binary attachment (the shape of the skill
  // export), re-importable byte-compatibly through the POST archive route.
  app.get("/:name/archive", async (c) => {
    const projectId = requireValidId(c, "projectId");
    const agentId = requireValidId(c, "agentId");
    deps.access.requireProjectAccess(c.var.user.userId, projectId);
    const name = requireValidId(c, "name");
    const dir = await requireInstalled(projectId, agentId, name);
    const archiveFiles = await collectHookArchive(dir, name);
    // A -v<version> suffix only when the manifest carries a real version — in the current
    // `YYYY.MM.DD.N` spelling or the legacy one an older installed copy has (the header is the
    // authority on the filename — the web tab reads it from Content-Disposition).
    let version = "";
    try {
      const manifest = JSON.parse(strFromU8(archiveFiles[`${name}/hooks.json`]!)) as {
        version?: unknown;
      };
      if (typeof manifest.version === "string") version = manifest.version;
    } catch {
      // An unparseable manifest still exports (the files are what the user asked for); it just gets the bare filename.
    }
    const fileName =
      parsePluginVersion(version) !== null ? `${name}-v${version}.zip` : `${name}.zip`;
    const zip = zipSync(archiveFiles);
    return new Response(new Uint8Array(zip), {
      headers: {
        "Content-Type": "application/zip",
        // The name is id-validated ([A-Za-z0-9_-]+), so the encoded filename is itself.
        "Content-Disposition": `attachment; filename*=UTF-8''${encodeURIComponent(fileName)}`,
        "X-Content-Type-Options": "nosniff",
      },
    });
  });

  app.delete("/:name", async (c) => {
    const projectId = requireValidId(c, "projectId");
    const agentId = requireValidId(c, "agentId");
    deps.access.requireProjectAccess(c.var.user.userId, projectId);
    const name = requireValidId(c, "name");
    await requireInstalled(projectId, agentId, name);
    await removeHook(deps.config.root, projectId, agentId, name);
    deps.manager.invalidateAgentRuntimes(projectId, agentId);
    return c.body(null, 204);
  });

  return app;
}