@hyperdrive.bot/paseo-extension-sdk

MIT-licensed SDK for building Hyperpaseo extensions.

This package is the contract between an extension and the host app — a VS Code–style plugin model. It contains only interfaces, the manifest schema, and a thin RPC client. It does not import any host (AGPL) code.

Why this is a separate package (the licensing boundary)

The Hyperpaseo desktop app is AGPL-3.0. Extensions are not derivative works of it because they run arms-length:

• extension logic runs in a separate extension-host process (not in the app),
• extension UI runs in a sandboxed webview,
• both communicate with the host only over the RPC contract defined here.

An extension depends on @hyperdrive.bot/paseo-extension-sdk (MIT) and the wire protocol — never on the app's source. Therefore an extension may be licensed however its author wants, including closed-source and paid. (Same boundary VS Code uses between Code-OSS and its extension ecosystem.)

Do NOT import host internals into an extension. The moment an extension links the AGPL app in-process, it becomes a derivative work and must be AGPL. Talk to the host only through the HostApi defined here.

Anatomy of an extension

my-extension/
  package.json            # name, version
  hyperpaseo.json         # the manifest (contributions)
  dist/extension.js       # runs in the extension-host (Node) — exports activate()
  ui/index.html           # optional sandboxed webview UI

// extension.ts — runs in the extension-host process
import type { ExtensionContext } from "@hyperdrive.bot/paseo-extension-sdk";

export async function activate(ctx: ExtensionContext): Promise<void> {
  ctx.registerCommand("hello.ping", async () => {
    const agents = await ctx.host.agents.list();
    await ctx.host.ui.showNotification({ body: `You have ${agents.length} agents.` });
  });
}

export function deactivate(): void {}

See src/ for the full surface: manifest, host-api, activation, rpc.