@hyperdrive.bot/paseo-extension-sdk 0.3.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marcelo Marra
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,51 @@
+# @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`.

package/dist/activation.d.ts

@@ -0,0 +1,22 @@
+import type { Disposable, HostApi } from "./host-api.js";
+/**
+ * The context handed to an extension's `activate()` when the extension-host
+ * loads it. `host` is the RPC-backed capability surface; `registerCommand`
+ * wires a handler for a command declared in the manifest's `contributes.commands`.
+ *
+ * Push any Disposable you create into `subscriptions`; the host disposes them
+ * all on `deactivate()` / unload.
+ */
+export interface ExtensionContext {
+    host: HostApi;
+    subscriptions: Disposable[];
+    registerCommand(id: string, handler: (...args: unknown[]) => unknown | Promise<unknown>): Disposable;
+}
+export type ActivateFn = (context: ExtensionContext) => void | Promise<void>;
+export type DeactivateFn = () => void | Promise<void>;
+/** The shape the extension-host expects from an extension's `main` module. */
+export interface ExtensionModule {
+    activate: ActivateFn;
+    deactivate?: DeactivateFn;
+}
+//# sourceMappingURL=activation.d.ts.map

package/dist/activation.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=activation.js.map

package/dist/host-api.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The HostApi is everything an extension may ask of the host, over RPC.
+ *
+ * These are CLEAN-ROOM shapes — deliberately NOT imported from the AGPL app.
+ * They are a stable, minimal projection of host capabilities. The host adapts
+ * its internal types to these at the gateway; the extension only ever sees this.
+ */
+export interface Disposable {
+    dispose(): void;
+}
+export type AgentStatus = "running" | "idle" | "waiting" | "error" | "archived" | "unknown";
+export interface AgentSummary {
+    id: string;
+    title: string | null;
+    status: AgentStatus;
+    serverId: string;
+    cwd: string | null;
+    /** ISO-8601 timestamp, or null if unknown. */
+    lastActivityAt: string | null;
+}
+export interface AgentDetail extends AgentSummary {
+    provider: string | null;
+    pendingPermissionCount: number;
+}
+export interface NotificationOptions {
+    title?: string;
+    body: string;
+}
+export interface HostFetchInit {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+}
+export interface HostFetchResponse {
+    status: number;
+    headers: Record<string, string>;
+    body: string;
+}
+/**
+ * The capability surface. v0 wraps a curated subset of the host's DaemonClient
+ * plus UI affordances. `net.fetch` is the escape hatch for an extension's OWN
+ * (possibly paid) backend — calls leave the host arms-length.
+ */
+export interface HostApi {
+    agents: {
+        list(): Promise<AgentSummary[]>;
+        get(id: string): Promise<AgentDetail | null>;
+        /** Subscribe to agent-list status changes. Returns a Disposable. */
+        onStatus(listener: (agents: AgentSummary[]) => void): Disposable;
+        archive(id: string): Promise<void>;
+    };
+    commands: {
+        /** Invoke any registered command (host or another extension's). */
+        execute(id: string, ...args: unknown[]): Promise<unknown>;
+    };
+    ui: {
+        showNotification(options: NotificationOptions): Promise<void>;
+        /** Open a contributed view (webview) by id. */
+        openView(viewId: string): Promise<void>;
+        /** Open a workspace-tab panel by kind, with optional props. */
+        openPanel(kind: string, props?: Record<string, unknown>): Promise<void>;
+    };
+    storage: {
+        /** Per-extension scoped key/value storage (host-persisted). */
+        get<T = unknown>(key: string): Promise<T | undefined>;
+        set(key: string, value: unknown): Promise<void>;
+    };
+    net: {
+        /** Arms-length network call — for the extension's own backend. */
+        fetch(url: string, init?: HostFetchInit): Promise<HostFetchResponse>;
+    };
+}
+//# sourceMappingURL=host-api.d.ts.map

package/dist/host-api.js

@@ -0,0 +1,9 @@
+/**
+ * The HostApi is everything an extension may ask of the host, over RPC.
+ *
+ * These are CLEAN-ROOM shapes — deliberately NOT imported from the AGPL app.
+ * They are a stable, minimal projection of host capabilities. The host adapts
+ * its internal types to these at the gateway; the extension only ever sees this.
+ */
+export {};
+//# sourceMappingURL=host-api.js.map

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./manifest.js";
+export * from "./host-api.js";
+export * from "./rpc.js";
+export * from "./activation.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from "./manifest.js";
+export * from "./host-api.js";
+export * from "./rpc.js";
+export * from "./activation.js";
+//# sourceMappingURL=index.js.map

package/dist/manifest.d.ts

@@ -0,0 +1,103 @@
+import { z } from "zod";
+/**
+ * The extension manifest (`hyperpaseo.json`). Pure declaration — the host reads
+ * this to know what an extension contributes WITHOUT executing any extension
+ * code. This is the arms-length seam: contributions are data, not linked code.
+ */
+export declare const CommandContribution: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    icon: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type CommandContribution = z.infer<typeof CommandContribution>;
+export declare const SidebarItemContribution: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    icon: z.ZodOptional<z.ZodString>;
+    command: z.ZodOptional<z.ZodString>;
+    view: z.ZodOptional<z.ZodString>;
+    order: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export type SidebarItemContribution = z.infer<typeof SidebarItemContribution>;
+export declare const ViewContribution: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    location: z.ZodDefault<z.ZodEnum<{
+        sidebar: "sidebar";
+        panel: "panel";
+    }>>;
+    ui: z.ZodString;
+}, z.core.$strip>;
+export type ViewContribution = z.infer<typeof ViewContribution>;
+export declare const Contributes: z.ZodObject<{
+    commands: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        icon: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    sidebarItems: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        icon: z.ZodOptional<z.ZodString>;
+        command: z.ZodOptional<z.ZodString>;
+        view: z.ZodOptional<z.ZodString>;
+        order: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>>;
+    views: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        location: z.ZodDefault<z.ZodEnum<{
+            sidebar: "sidebar";
+            panel: "panel";
+        }>>;
+        ui: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type Contributes = z.infer<typeof Contributes>;
+export declare const ExtensionManifest: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    version: z.ZodString;
+    publisher: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    engines: z.ZodObject<{
+        hyperpaseo: z.ZodString;
+    }, z.core.$strip>;
+    main: z.ZodOptional<z.ZodString>;
+    contributes: z.ZodDefault<z.ZodObject<{
+        commands: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            title: z.ZodString;
+            icon: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+        sidebarItems: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            title: z.ZodString;
+            icon: z.ZodOptional<z.ZodString>;
+            command: z.ZodOptional<z.ZodString>;
+            view: z.ZodOptional<z.ZodString>;
+            order: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>>>;
+        views: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            title: z.ZodString;
+            location: z.ZodDefault<z.ZodEnum<{
+                sidebar: "sidebar";
+                panel: "panel";
+            }>>;
+            ui: z.ZodString;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ExtensionManifest = z.infer<typeof ExtensionManifest>;
+/** Parse + validate a raw manifest object. Throws ZodError on invalid input. */
+export declare function parseManifest(raw: unknown): ExtensionManifest;
+/** Safe variant — returns a typed result instead of throwing. */
+export declare function safeParseManifest(raw: unknown): {
+    ok: true;
+    manifest: ExtensionManifest;
+} | {
+    ok: false;
+    error: string;
+};
+//# sourceMappingURL=manifest.d.ts.map

package/dist/manifest.js

@@ -0,0 +1,66 @@
+import { z } from "zod";
+/**
+ * The extension manifest (`hyperpaseo.json`). Pure declaration — the host reads
+ * this to know what an extension contributes WITHOUT executing any extension
+ * code. This is the arms-length seam: contributions are data, not linked code.
+ */
+export const CommandContribution = z.object({
+    /** Stable command id, namespaced by extension, e.g. "meetings.openInbox". */
+    id: z.string(),
+    /** Human-readable label shown in the command palette. */
+    title: z.string(),
+    /** Optional host icon token (e.g. "plus", "calendar"). */
+    icon: z.string().optional(),
+});
+export const SidebarItemContribution = z.object({
+    id: z.string(),
+    title: z.string(),
+    icon: z.string().optional(),
+    /** Selecting the item runs this command id... */
+    command: z.string().optional(),
+    /** ...or opens this view id (a webview). Exactly one of command|view. */
+    view: z.string().optional(),
+    /** Lower sorts first; host items occupy 0..99, extensions default to 100+. */
+    order: z.number().default(100),
+});
+export const ViewContribution = z.object({
+    id: z.string(),
+    title: z.string(),
+    /** Where the view mounts. */
+    location: z.enum(["sidebar", "panel"]).default("panel"),
+    /** Relative path to the sandboxed webview HTML entry inside the extension. */
+    ui: z.string(),
+});
+export const Contributes = z.object({
+    commands: z.array(CommandContribution).default([]),
+    sidebarItems: z.array(SidebarItemContribution).default([]),
+    views: z.array(ViewContribution).default([]),
+});
+export const ExtensionManifest = z.object({
+    /** Reverse-DNS unique id, e.g. "com.hyperpaseo.meetings". */
+    id: z.string(),
+    name: z.string(),
+    version: z.string(),
+    publisher: z.string().optional(),
+    description: z.string().optional(),
+    /** Host compatibility range, semver against the app version. */
+    engines: z.object({ hyperpaseo: z.string() }),
+    /**
+     * Entry that runs in the extension-host (Node). Exports activate()/deactivate().
+     * Omit for purely-declarative or pure-webview extensions.
+     */
+    main: z.string().optional(),
+    contributes: Contributes.default({ commands: [], sidebarItems: [], views: [] }),
+});
+/** Parse + validate a raw manifest object. Throws ZodError on invalid input. */
+export function parseManifest(raw) {
+    return ExtensionManifest.parse(raw);
+}
+/** Safe variant — returns a typed result instead of throwing. */
+export function safeParseManifest(raw) {
+    const result = ExtensionManifest.safeParse(raw);
+    if (result.success)
+        return { ok: true, manifest: result.data };
+    return { ok: false, error: result.error.message };
+}
+//# sourceMappingURL=manifest.js.map

package/dist/rpc.d.ts

@@ -0,0 +1,39 @@
+import type { Disposable, HostApi } from "./host-api.js";
+/**
+ * Transport-agnostic RPC. The same wire contract works over:
+ *  - extension-host process stdio (Node)        — extension logic
+ *  - webview postMessage (sandboxed iframe)      — extension UI
+ *
+ * The host implements the other end of these messages against its DaemonClient.
+ */
+export interface RpcTransport {
+    post(message: unknown): void;
+    /** Register an inbound-message handler. Returns a Disposable. */
+    subscribe(handler: (message: unknown) => void): Disposable;
+}
+export interface CallMessage {
+    kind: "call";
+    id: number;
+    path: string[];
+    args: unknown[];
+}
+export interface ResultMessage {
+    kind: "result";
+    id: number;
+    ok: boolean;
+    value?: unknown;
+    error?: string;
+}
+export interface EventMessage {
+    kind: "event";
+    channel: string;
+    payload: unknown;
+}
+export type HostInboundMessage = ResultMessage | EventMessage;
+/**
+ * Build a HostApi proxy backed by an RpcTransport. Outbound method calls become
+ * `call` messages; the host replies with `result`; `onStatus` subscribes to an
+ * `event` channel. No host code is linked — only the wire shapes above.
+ */
+export declare function createHostApi(transport: RpcTransport): HostApi;
+//# sourceMappingURL=rpc.d.ts.map

package/dist/rpc.js

@@ -0,0 +1,80 @@
+const SUBSCRIBE_PATH = "__subscribe__";
+/**
+ * Build a HostApi proxy backed by an RpcTransport. Outbound method calls become
+ * `call` messages; the host replies with `result`; `onStatus` subscribes to an
+ * `event` channel. No host code is linked — only the wire shapes above.
+ */
+export function createHostApi(transport) {
+    let nextId = 1;
+    const pending = new Map();
+    const channels = new Map();
+    transport.subscribe((raw) => {
+        const message = raw;
+        if (!message || typeof message !== "object")
+            return;
+        if (message.kind === "result") {
+            const pendingCall = pending.get(message.id);
+            if (!pendingCall)
+                return;
+            pending.delete(message.id);
+            if (message.ok)
+                pendingCall.resolve(message.value);
+            else
+                pendingCall.reject(new Error(message.error ?? "host call failed"));
+            return;
+        }
+        if (message.kind === "event") {
+            const listeners = channels.get(message.channel);
+            if (!listeners)
+                return;
+            for (const listener of listeners)
+                listener(message.payload);
+        }
+    });
+    function call(path, args) {
+        const id = nextId++;
+        return new Promise((resolve, reject) => {
+            pending.set(id, { resolve, reject });
+            const message = { kind: "call", id, path, args };
+            transport.post(message);
+        });
+    }
+    function subscribe(channel, listener) {
+        let listeners = channels.get(channel);
+        if (!listeners) {
+            listeners = new Set();
+            channels.set(channel, listeners);
+        }
+        listeners.add(listener);
+        void call([SUBSCRIBE_PATH], [channel]);
+        return {
+            dispose: () => {
+                listeners?.delete(listener);
+            },
+        };
+    }
+    return {
+        agents: {
+            list: () => call(["agents", "list"], []),
+            get: (id) => call(["agents", "get"], [id]),
+            onStatus: (listener) => subscribe("agents.status", (payload) => listener(payload)),
+            archive: (id) => call(["agents", "archive"], [id]),
+        },
+        commands: {
+            execute: (id, ...args) => call(["commands", "execute"], [id, ...args]),
+        },
+        ui: {
+            showNotification: (options) => call(["ui", "showNotification"], [options]),
+            openView: (viewId) => call(["ui", "openView"], [viewId]),
+            openPanel: (kind, props) => call(["ui", "openPanel"], [kind, props]),
+        },
+        storage: {
+            get: (key) => call(["storage", "get"], [key]),
+            set: (key, value) => call(["storage", "set"], [key, value]),
+        },
+        net: {
+            fetch: (url, init) => call(["net", "fetch"], [url, init]),
+        },
+    };
+}
+//# sourceMappingURL=rpc.js.map

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@hyperdrive.bot/paseo-extension-sdk",
+  "version": "0.3.3",
+  "description": "MIT SDK for building Hyperpaseo extensions. Extensions run arms-length (separate extension-host process / sandboxed webview) and talk to the host over RPC — they never link the AGPL app.",
+  "license": "MIT",
+  "files": [
+    "dist",
+    "!dist/**/*.map",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist',{ recursive: true, force: true })\" && tsc -p tsconfig.json --incremental false",
+    "prepack": "npm run build",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^20.9.0",
+    "typescript": "^5.2.2"
+  }
+}