# @hyperdrive.bot/paseo-extension-sdk

**MIT-licensed** SDK for building [Hyperpaseo](https://paseo.sh) 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
```

```ts
// 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`.