@getpaseo/plugin 0.5.0-beta.2

package/dist/attachments.d.ts

@@ -0,0 +1,24 @@
+import { z } from "zod";
+export declare const PluginAttachmentItemSchema: z.ZodObject<{
+    id: z.ZodString;
+    identifier: z.ZodString;
+    title: z.ZodString;
+    subtitle: z.ZodOptional<z.ZodString>;
+    url: z.ZodURL;
+    text: z.ZodString;
+    resourceType: z.ZodString;
+}, z.core.$strip>;
+export declare const PluginAttachmentSearchPayloadSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        identifier: z.ZodString;
+        title: z.ZodString;
+        subtitle: z.ZodOptional<z.ZodString>;
+        url: z.ZodURL;
+        text: z.ZodString;
+        resourceType: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PluginAttachmentItem = z.infer<typeof PluginAttachmentItemSchema>;
+export type PluginAttachmentSearchPayload = z.infer<typeof PluginAttachmentSearchPayloadSchema>;
+//# sourceMappingURL=attachments.d.ts.map

package/dist/attachments.js

@@ -0,0 +1,14 @@
+import { z } from "zod";
+export const PluginAttachmentItemSchema = z.object({
+    id: z.string(),
+    identifier: z.string(),
+    title: z.string(),
+    subtitle: z.string().optional(),
+    url: z.url(),
+    text: z.string(),
+    resourceType: z.string(),
+});
+export const PluginAttachmentSearchPayloadSchema = z.object({
+    items: z.array(PluginAttachmentItemSchema),
+});
+//# sourceMappingURL=attachments.js.map

package/dist/client-state.d.ts

@@ -0,0 +1,14 @@
+import { type ReactNode } from "react";
+import type { PluginAgentSnapshot, PluginWorkspaceSnapshot } from "./contracts.js";
+export interface PluginClientStateSource {
+    subscribe(listener: () => void): () => void;
+    getWorkspace(id: string): PluginWorkspaceSnapshot | null;
+    getAgent(id: string): PluginAgentSnapshot | null;
+}
+export declare function useWorkspace<Selection>(workspaceId: string, selector: (workspace: PluginWorkspaceSnapshot) => Selection): Selection | null;
+export declare function useAgent<Selection>(agentId: string, selector: (agent: PluginAgentSnapshot) => Selection): Selection | null;
+export declare function PluginClientStateProvider({ children, source, }: {
+    children: ReactNode;
+    source: PluginClientStateSource;
+}): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=client-state.d.ts.map

package/dist/client-state.js

@@ -0,0 +1,29 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext } from "react";
+import { useSyncExternalStoreWithSelector } from "use-sync-external-store/shim/with-selector";
+import { shallowEqual } from "./shallow.js";
+const PluginClientStateContext = createContext(null);
+function usePluginEntity(input) {
+    const source = useContext(PluginClientStateContext);
+    if (!source)
+        throw new Error("Plugin state hooks must run inside a workspace panel");
+    return useSyncExternalStoreWithSelector(source.subscribe, () => input.read(source, input.id), () => input.read(source, input.id), (entity) => (entity ? input.selector(entity) : null), shallowEqual);
+}
+export function useWorkspace(workspaceId, selector) {
+    return usePluginEntity({
+        id: workspaceId,
+        read: (source, id) => source.getWorkspace(id),
+        selector,
+    });
+}
+export function useAgent(agentId, selector) {
+    return usePluginEntity({
+        id: agentId,
+        read: (source, id) => source.getAgent(id),
+        selector,
+    });
+}
+export function PluginClientStateProvider({ children, source, }) {
+    return (_jsx(PluginClientStateContext.Provider, { value: source, children: children }));
+}
+//# sourceMappingURL=client-state.js.map

package/dist/contracts.d.ts

@@ -0,0 +1,152 @@
+import type { ComponentType } from "react";
+import type { PaseoApi } from "@getpaseo/client";
+import type { ZodType, input as ZodInput, output as ZodOutput } from "zod";
+import type { PluginRpcContract } from "./rpc.js";
+export interface PluginTheme {
+    readonly colors: {
+        readonly surface0: string;
+        readonly foreground: string;
+        readonly foregroundMuted: string;
+        readonly accent: string;
+        readonly accentForeground: string;
+        readonly statusDanger: string;
+    };
+}
+export interface PluginHostProps {
+    theme: PluginTheme;
+    host: {
+        id: string;
+        label: string;
+    };
+    layout: {
+        compact: boolean;
+        platform: "ios" | "android" | "web";
+    };
+}
+export interface PluginSurfaceProps extends PluginHostProps {
+}
+export interface PluginWorkspaceSnapshot {
+    readonly id: string;
+    readonly projectId: string;
+    readonly projectDisplayName: string;
+    readonly projectRootPath: string;
+    readonly directory: string;
+    readonly projectKind: "git" | "non_git" | "directory";
+    readonly kind: "directory" | "local_checkout" | "checkout" | "worktree";
+    readonly name: string;
+    readonly title: string | null;
+    readonly status: "needs_input" | "failed" | "running" | "attention" | "done";
+    readonly statusEnteredAt: string | null;
+    readonly archivingAt: string | null;
+    readonly diffStat: {
+        readonly additions: number;
+        readonly deletions: number;
+    } | null;
+}
+export interface PluginAgentSnapshot {
+    readonly id: string;
+    readonly workspaceId: string;
+    readonly provider: string;
+    readonly status: "initializing" | "idle" | "running" | "error" | "closed";
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly lastActivityAt: string;
+    readonly title: string | null;
+    readonly cwd: string;
+    readonly model: string | null;
+    readonly currentModeId: string | null;
+    readonly thinkingOptionId: string | null;
+    readonly requiresAttention: boolean;
+    readonly attentionReason: "finished" | "error" | "permission" | null;
+    readonly parentAgentId: string | null;
+    readonly labels: Readonly<Record<string, string>>;
+}
+interface PluginWorkspacePanelBase {
+    id: string;
+    title: string;
+    icon: string;
+}
+export interface PluginWorkspacePanelProps extends PluginHostProps {
+    context: "workspace";
+    workspaceId: string;
+}
+export interface PluginAgentPanelProps extends PluginHostProps {
+    context: "agent";
+    workspaceId: string;
+    agentId: string;
+}
+export type PluginWorkspacePanelContribution = (PluginWorkspacePanelBase & {
+    context: "workspace";
+    Component: ComponentType<PluginWorkspacePanelProps>;
+}) | (PluginWorkspacePanelBase & {
+    context: "agent";
+    Component: ComponentType<PluginAgentPanelProps>;
+});
+export interface PluginSurfaceContribution {
+    id: string;
+    Component: ComponentType<PluginSurfaceProps>;
+}
+export interface PluginSidebarContribution {
+    id: string;
+    title: string;
+    icon: string;
+    surface: string;
+}
+export interface PluginAttachmentSourceContribution {
+    id: string;
+    title: string;
+    icon: string;
+    pickerTitle: string;
+    searchPlaceholder: string;
+    search: PluginRpcContract;
+}
+export interface PluginCommandCapabilities {
+    paseo: PaseoApi;
+    rpc<InputSchema extends ZodType, OutputSchema extends ZodType>(contract: PluginRpcContract<InputSchema, OutputSchema>, input: ZodInput<InputSchema>): Promise<ZodOutput<OutputSchema>>;
+    openSurface(id: string): void;
+}
+export interface PluginGlobalCommandContext extends PluginCommandCapabilities {
+    context: "global";
+}
+export interface PluginWorkspaceCommandContext extends PluginCommandCapabilities {
+    context: "workspace";
+    workspace: PluginWorkspaceSnapshot;
+    openPanel(id: string): void;
+}
+export interface PluginAgentCommandContext extends PluginCommandCapabilities {
+    context: "agent";
+    workspace: PluginWorkspaceSnapshot;
+    agent: PluginAgentSnapshot;
+    openPanel(id: string): void;
+}
+interface PluginCommandCenterItemBase {
+    id: string;
+    title: string;
+    icon: string;
+    keywords?: readonly string[];
+}
+export type PluginCommandCenterItemContribution = (PluginCommandCenterItemBase & {
+    context: "global";
+    onSelect(context: PluginGlobalCommandContext): void | Promise<void>;
+}) | (PluginCommandCenterItemBase & {
+    context: "workspace";
+    onSelect(context: PluginWorkspaceCommandContext): void | Promise<void>;
+}) | (PluginCommandCenterItemBase & {
+    context: "agent";
+    onSelect(context: PluginAgentCommandContext): void | Promise<void>;
+});
+export interface PluginHandlerContext {
+    paseo: PaseoApi;
+}
+export interface PluginContext {
+    handle<InputSchema extends ZodType, OutputSchema extends ZodType>(contract: PluginRpcContract<InputSchema, OutputSchema>, handler: (input: ZodOutput<InputSchema>, context: PluginHandlerContext) => ZodInput<OutputSchema> | Promise<ZodInput<OutputSchema>>): void;
+    addSurface(id: string, Component: ComponentType<PluginSurfaceProps>): void;
+    addSidebarItem(contribution: PluginSidebarContribution): void;
+    addWorkspacePanel(contribution: PluginWorkspacePanelContribution): void;
+    addCommandCenterItem(contribution: PluginCommandCenterItemContribution): void;
+    addAttachmentSource(contribution: PluginAttachmentSourceContribution): void;
+}
+export type PluginCleanup = () => void | Promise<void>;
+export type PluginContribution = (plugin: PluginContext) => PluginCleanup;
+export {};
+//# sourceMappingURL=contracts.d.ts.map

package/dist/contracts.js

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

package/dist/host.d.ts

@@ -0,0 +1,34 @@
+export { PluginClientStateProvider, type PluginClientStateSource } from "./client-state.js";
+import type { PluginAttachmentSourceContribution, PluginCommandCenterItemContribution, PluginContext, PluginSidebarContribution, PluginSurfaceContribution, PluginSurfaceProps, PluginWorkspacePanelContribution } from "./contracts.js";
+import { PluginRpcProvider } from "./rpc-context.js";
+import { PaseoApiProvider } from "./paseo-context.js";
+import { callPluginRpc } from "./rpc.js";
+import type { ComponentType } from "react";
+interface PluginCollector {
+    addSurface(id: string, Component: ComponentType<PluginSurfaceProps>): void;
+    addSidebarItem(contribution: PluginSidebarContribution): void;
+    addWorkspacePanel(contribution: PluginWorkspacePanelContribution): void;
+    addCommandCenterItem(contribution: PluginCommandCenterItemContribution): void;
+    addAttachmentSource(contribution: PluginAttachmentSourceContribution): void;
+}
+export interface PluginRegistrationCollector {
+    surfaces: PluginSurfaceContribution[];
+    sidebarItems: PluginSidebarContribution[];
+    workspacePanels: PluginWorkspacePanelContribution[];
+    commandCenterItems: PluginCommandCenterItemContribution[];
+    attachmentSources: PluginAttachmentSourceContribution[];
+}
+export declare function createPluginContext(collector: PluginCollector): Pick<PluginContext, "addSurface" | "addSidebarItem" | "addWorkspacePanel" | "addCommandCenterItem" | "addAttachmentSource">;
+export declare function searchPluginAttachments(source: PluginAttachmentSourceContribution, invoke: (method: string, input: unknown) => Promise<unknown>, query: string): Promise<{
+    items: {
+        id: string;
+        identifier: string;
+        title: string;
+        url: string;
+        text: string;
+        resourceType: string;
+        subtitle?: string | undefined;
+    }[];
+}>;
+export { callPluginRpc, PaseoApiProvider, PluginRpcProvider };
+//# sourceMappingURL=host.d.ts.map

package/dist/host.js

@@ -0,0 +1,30 @@
+import { PluginAttachmentSearchPayloadSchema } from "./attachments.js";
+export { PluginClientStateProvider } from "./client-state.js";
+import { PluginRpcProvider } from "./rpc-context.js";
+import { PaseoApiProvider } from "./paseo-context.js";
+import { callPluginRpc } from "./rpc.js";
+export function createPluginContext(collector) {
+    return {
+        addSurface(id, Component) {
+            collector.addSurface(id, Component);
+        },
+        addSidebarItem(contribution) {
+            collector.addSidebarItem(contribution);
+        },
+        addWorkspacePanel(contribution) {
+            collector.addWorkspacePanel(contribution);
+        },
+        addCommandCenterItem(contribution) {
+            collector.addCommandCenterItem(contribution);
+        },
+        addAttachmentSource(contribution) {
+            collector.addAttachmentSource(contribution);
+        },
+    };
+}
+export async function searchPluginAttachments(source, invoke, query) {
+    const output = await callPluginRpc(source.search, invoke, { query });
+    return PluginAttachmentSearchPayloadSchema.parseAsync(output);
+}
+export { callPluginRpc, PaseoApiProvider, PluginRpcProvider };
+//# sourceMappingURL=host.js.map

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { PluginAttachmentItemSchema, PluginAttachmentSearchPayloadSchema, defineAttachmentSource, defineRpc, type PluginAttachmentItem, type PluginAttachmentSearchPayload, type PluginRpcContract, } from "./server.js";
+export type { PluginAttachmentSourceContribution, PluginAgentCommandContext, PluginAgentPanelProps, PluginAgentSnapshot, PluginCleanup, PluginCommandCapabilities, PluginCommandCenterItemContribution, PluginContribution, PluginContext, PluginGlobalCommandContext, PluginHandlerContext, PluginHostProps, PluginTheme, PluginSidebarContribution, PluginSurfaceContribution, PluginSurfaceProps, PluginWorkspaceCommandContext, PluginWorkspacePanelContribution, PluginWorkspacePanelProps, PluginWorkspaceSnapshot, } from "./contracts.js";
+export { usePaseo } from "./paseo-context.js";
+export { useAgent, useWorkspace } from "./client-state.js";
+export { useRpc } from "./rpc-context.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,5 @@
+export { PluginAttachmentItemSchema, PluginAttachmentSearchPayloadSchema, defineAttachmentSource, defineRpc, } from "./server.js";
+export { usePaseo } from "./paseo-context.js";
+export { useAgent, useWorkspace } from "./client-state.js";
+export { useRpc } from "./rpc-context.js";
+//# sourceMappingURL=index.js.map

package/dist/paseo-context.d.ts

@@ -0,0 +1,8 @@
+import type { PaseoApi } from "@getpaseo/client";
+import { type ReactNode } from "react";
+export declare function PaseoApiProvider({ children, paseo }: {
+    children: ReactNode;
+    paseo: PaseoApi;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function usePaseo(): PaseoApi;
+//# sourceMappingURL=paseo-context.d.ts.map

package/dist/paseo-context.js

@@ -0,0 +1,13 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext } from "react";
+const PaseoApiContext = createContext(null);
+export function PaseoApiProvider({ children, paseo }) {
+    return _jsx(PaseoApiContext.Provider, { value: paseo, children: children });
+}
+export function usePaseo() {
+    const paseo = useContext(PaseoApiContext);
+    if (!paseo)
+        throw new Error("usePaseo must run inside a contributed plugin surface");
+    return paseo;
+}
+//# sourceMappingURL=paseo-context.js.map

package/dist/rpc-context.d.ts

@@ -0,0 +1,9 @@
+import { type ReactNode } from "react";
+import type { ZodType, input as ZodInput, output as ZodOutput } from "zod";
+import { type PluginRpcContract } from "./rpc.js";
+export declare function PluginRpcProvider({ children, invoke, }: {
+    children: ReactNode;
+    invoke(method: string, input: unknown): Promise<unknown>;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function useRpc<InputSchema extends ZodType, OutputSchema extends ZodType>(contract: PluginRpcContract<InputSchema, OutputSchema>): (input: ZodInput<InputSchema>) => Promise<ZodOutput<OutputSchema>>;
+//# sourceMappingURL=rpc-context.d.ts.map

package/dist/rpc-context.js

@@ -0,0 +1,15 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useCallback, useContext, useMemo } from "react";
+import { callPluginRpc } from "./rpc.js";
+const PluginRpcContext = createContext(null);
+export function PluginRpcProvider({ children, invoke, }) {
+    const value = useMemo(() => ({ invoke }), [invoke]);
+    return _jsx(PluginRpcContext.Provider, { value: value, children: children });
+}
+export function useRpc(contract) {
+    const context = useContext(PluginRpcContext);
+    if (!context)
+        throw new Error("useRpc must run inside a contributed plugin surface");
+    return useCallback((input) => callPluginRpc(contract, context.invoke, input), [context, contract]);
+}
+//# sourceMappingURL=rpc-context.js.map

package/dist/rpc.d.ts

@@ -0,0 +1,15 @@
+import type { ZodType, input as ZodInput, output as ZodOutput } from "zod";
+export interface PluginRpcContract<InputSchema extends ZodType = ZodType, OutputSchema extends ZodType = ZodType> {
+    name: string;
+    input: InputSchema;
+    output: OutputSchema;
+}
+interface RpcDefinition<InputSchema extends ZodType, OutputSchema extends ZodType> {
+    name: string;
+    input: InputSchema;
+    output: OutputSchema;
+}
+export declare function defineRpc<InputSchema extends ZodType, OutputSchema extends ZodType>(definition: RpcDefinition<InputSchema, OutputSchema>): PluginRpcContract<InputSchema, OutputSchema>;
+export declare function callPluginRpc<InputSchema extends ZodType, OutputSchema extends ZodType>(contract: PluginRpcContract<InputSchema, OutputSchema>, invoke: (method: string, input: unknown) => Promise<unknown>, input: ZodInput<InputSchema>): Promise<ZodOutput<OutputSchema>>;
+export {};
+//# sourceMappingURL=rpc.d.ts.map

package/dist/rpc.js

@@ -0,0 +1,13 @@
+const RPC_NAME = /^[a-z][a-z0-9._-]*$/;
+export function defineRpc(definition) {
+    const name = definition.name.trim();
+    if (!RPC_NAME.test(name))
+        throw new Error(`Invalid plugin RPC method: ${definition.name}`);
+    return { ...definition, name };
+}
+export async function callPluginRpc(contract, invoke, input) {
+    const parsedInput = await contract.input.parseAsync(input);
+    const output = await invoke(contract.name, parsedInput);
+    return contract.output.parseAsync(output);
+}
+//# sourceMappingURL=rpc.js.map

package/dist/server.d.ts

@@ -0,0 +1,6 @@
+import type { PluginAttachmentSourceContribution } from "./contracts.js";
+export { PluginAttachmentItemSchema, PluginAttachmentSearchPayloadSchema, type PluginAttachmentItem, type PluginAttachmentSearchPayload, } from "./attachments.js";
+export type { PluginAttachmentSourceContribution, PluginHandlerContext } from "./contracts.js";
+export { defineRpc, type PluginRpcContract } from "./rpc.js";
+export declare function defineAttachmentSource<Definition extends PluginAttachmentSourceContribution>(definition: Definition): Definition;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.js

@@ -0,0 +1,6 @@
+export { PluginAttachmentItemSchema, PluginAttachmentSearchPayloadSchema, } from "./attachments.js";
+export { defineRpc } from "./rpc.js";
+export function defineAttachmentSource(definition) {
+    return definition;
+}
+//# sourceMappingURL=server.js.map

package/dist/shallow.d.ts

@@ -0,0 +1,2 @@
+export declare function shallowEqual(left: unknown, right: unknown): boolean;
+//# sourceMappingURL=shallow.d.ts.map

package/dist/shallow.js

@@ -0,0 +1,45 @@
+function isIterable(value) {
+    return Symbol.iterator in value;
+}
+function hasEntries(value) {
+    return "entries" in value;
+}
+function compareEntries(left, right) {
+    const leftEntries = left instanceof Map ? left : new Map(left.entries());
+    const rightEntries = right instanceof Map ? right : new Map(right.entries());
+    if (leftEntries.size !== rightEntries.size)
+        return false;
+    for (const [key, value] of leftEntries) {
+        if (!rightEntries.has(key) || !Object.is(value, rightEntries.get(key)))
+            return false;
+    }
+    return true;
+}
+function compareIterables(left, right) {
+    const leftIterator = left[Symbol.iterator]();
+    const rightIterator = right[Symbol.iterator]();
+    let leftValue = leftIterator.next();
+    let rightValue = rightIterator.next();
+    while (!leftValue.done && !rightValue.done) {
+        if (!Object.is(leftValue.value, rightValue.value))
+            return false;
+        leftValue = leftIterator.next();
+        rightValue = rightIterator.next();
+    }
+    return Boolean(leftValue.done && rightValue.done);
+}
+export function shallowEqual(left, right) {
+    if (Object.is(left, right))
+        return true;
+    if (!left || !right || typeof left !== "object" || typeof right !== "object")
+        return false;
+    if (Object.getPrototypeOf(left) !== Object.getPrototypeOf(right))
+        return false;
+    if (isIterable(left) && isIterable(right)) {
+        if (hasEntries(left) && hasEntries(right))
+            return compareEntries(left, right);
+        return compareIterables(left, right);
+    }
+    return compareEntries({ entries: () => Object.entries(left) }, { entries: () => Object.entries(right) });
+}
+//# sourceMappingURL=shallow.js.map

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@getpaseo/plugin",
+  "version": "0.5.0-beta.2",
+  "description": "Paseo plugin SDK package",
+  "files": [
+    "dist",
+    "!dist/**/*.map"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "source": "./src/index.ts",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "source": "./src/server.ts",
+      "default": "./dist/server.js"
+    },
+    "./host": {
+      "types": "./dist/host.d.ts",
+      "source": "./src/host.ts",
+      "default": "./dist/host.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "clean": "node ../../scripts/clean-package-dist.mjs",
+    "build": "tsc -p tsconfig.json --incremental false",
+    "build:clean": "npm run clean && npm run build",
+    "prepack": "npm run build:clean",
+    "typecheck": "tsgo --noEmit && tsgo -p tsconfig.examples.json --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "use-sync-external-store": "^1.6.0"
+  },
+  "devDependencies": {
+    "@getpaseo/client": "0.5.0-beta.2",
+    "@types/node": "^20.9.0",
+    "@types/react": "~19.2.0",
+    "react": "19.1.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.6",
+    "zod": "^4.4.3"
+  },
+  "peerDependencies": {
+    "@getpaseo/client": "0.5.0-beta.2",
+    "react": "19.1.0",
+    "zod": "^4.4.3"
+  }
+}