@camerontaylor/paseo-plugin 0.10.1-fork.1 → 0.11.0-beta.1.fork.1

package/dist/client/contracts.d.ts

@@ -35,8 +35,39 @@ interface PluginNavigableHostProps extends PluginHostProps {
         }) => void;
     };
 }
+/** String keys and values: params travel in the screen's URL. */
+export type PluginScreenParams = Record<string, string>;
+export interface PluginOpenScreenInput {
+    screenId: string;
+    params?: PluginScreenParams;
+}
+export interface PluginScreenLocation {
+    screenId: string;
+    params: PluginScreenParams;
+}
 export interface PluginSurfaceProps extends PluginNavigableHostProps {
 }
+export interface PluginScreenProps extends PluginSurfaceProps {
+    /** The params the screen was opened with; `{}` when none. */
+    params: PluginScreenParams;
+}
+export interface PluginPopoverProps extends PluginHostProps {
+    close(): void;
+    openScreen(input: PluginOpenScreenInput): void;
+}
+export interface PluginSidebarItemProps extends PluginHostProps {
+    /** This plugin's screen open on this item's host, with its params, else null. */
+    currentScreen: PluginScreenLocation | null;
+    openScreen(input: PluginOpenScreenInput): void;
+    /** Anchored to the item on wide layouts; a bottom sheet on compact layouts. */
+    openPopover(Content: ComponentType<PluginPopoverProps>): void;
+}
+export interface PluginSidebarItemContribution {
+    id: string;
+    /** Settings row label, accessibility label, and default label for SidebarRow. */
+    title: string;
+    Component: ComponentType<PluginSidebarItemProps>;
+}
 export interface PluginIconProps {
     name: string;
     size?: number;
@@ -65,10 +96,17 @@ export interface PluginClientOpenPanelOptions extends PluginOpenPanelOptions {
     workspaceId: string;
     agentId?: string;
 }
-export interface PluginClientContext extends PluginCommandCapabilities {
-    addSettingsScreen(contribution: PluginSettingsScreenContribution): PluginCleanup;
+interface PluginClientContextAliases {
+    /** @deprecated Use `addScreen`. */
     addSurface(id: string, Component: ComponentType<PluginSurfaceProps>): PluginCleanup;
+    /** @deprecated Use `addSidebarHeaderItem`. */
     addSidebarItem(contribution: PluginSidebarContribution): PluginCleanup;
+}
+export interface PluginClientContext extends PluginCommandCapabilities, PluginClientContextAliases {
+    addSettingsScreen(contribution: PluginSettingsScreenContribution): PluginCleanup;
+    addScreen(contribution: PluginScreenContribution): PluginCleanup;
+    addSidebarHeaderItem(contribution: PluginSidebarItemContribution): PluginCleanup;
+    addSidebarFooterItem(contribution: PluginSidebarItemContribution): PluginCleanup;
     addWorkspacePanel(contribution: PluginWorkspacePanelContribution): PluginCleanup;
     addCommandCenterItem(contribution: PluginCommandCenterItemContribution): PluginCleanup;
     addSlashCommand(contribution: PluginClientSlashCommandContribution): PluginCleanup;
@@ -94,10 +132,18 @@ export interface PluginSettingsScreenContribution {
     icon: string;
     Component: ComponentType<PluginSurfaceProps>;
 }
+/** The screen header's title: fixed, or derived from the params the screen was opened with. */
+export type PluginScreenTitle = string | ((params: PluginScreenParams) => string);
+export interface PluginScreenContribution {
+    id: string;
+    title: PluginScreenTitle;
+    Component: ComponentType<PluginScreenProps>;
+}
 export interface PluginSurfaceContribution {
     id: string;
     Component: ComponentType<PluginSurfaceProps>;
 }
+/** @deprecated Use `PluginSidebarItemContribution` with `addSidebarHeaderItem`. */
 export interface PluginSidebarContribution {
     id: string;
     title: string;
@@ -135,6 +181,8 @@ export interface PluginTimelineRendererContribution<Schema extends ZodType = Zod
 export interface PluginCommandCapabilities {
     paseo: PaseoApi;
     rpc<InputSchema extends ZodType, OutputSchema extends ZodType>(contract: PluginRpcContract<InputSchema, OutputSchema>, input: ZodInput<InputSchema>): Promise<ZodOutput<OutputSchema>>;
+    openScreen(input: PluginOpenScreenInput): void;
+    /** @deprecated Use `openScreen`. */
     openSurface(id: string): void;
     openSettings(id: string): void;
 }

package/dist/client/index.d.ts

@@ -1,4 +1,4 @@
-export type { PluginHostProps, PluginSurfaceProps, PluginIconProps, PluginPanelLocation, PluginOpenPanelOptions, PluginWorkspacePanelProps, PluginAgentPanelProps, PluginClientOpenPanelOptions, PluginClientContext, PluginClientContribution, PluginWorkspacePanelContribution, PluginSettingsScreenContribution, PluginSurfaceContribution, PluginSidebarContribution, PluginTimelineTransformerContribution, PluginTimelineItemProps, PluginTimelineRendererContribution, PluginCommandCapabilities, PluginGlobalCommandContext, PluginWorkspaceCommandContext, PluginAgentCommandContext, PluginCommandCenterItemContribution, PluginClientSlashCommandContribution, SettingsState, } from "./contracts.js";
+export type { PluginHostProps, PluginSurfaceProps, PluginScreenProps, PluginPopoverProps, PluginScreenParams, PluginOpenScreenInput, PluginScreenLocation, PluginSidebarItemProps, PluginSidebarItemContribution, PluginIconProps, PluginPanelLocation, PluginOpenPanelOptions, PluginWorkspacePanelProps, PluginAgentPanelProps, PluginClientOpenPanelOptions, PluginClientContext, PluginClientContribution, PluginWorkspacePanelContribution, PluginSettingsScreenContribution, PluginSurfaceContribution, PluginScreenContribution, PluginScreenTitle, PluginSidebarContribution, PluginTimelineTransformerContribution, PluginTimelineItemProps, PluginTimelineRendererContribution, PluginCommandCapabilities, PluginGlobalCommandContext, PluginWorkspaceCommandContext, PluginAgentCommandContext, PluginCommandCenterItemContribution, PluginClientSlashCommandContribution, SettingsState, } from "./contracts.js";
 export type { PluginButton, PluginButtonBehavior, PluginButtonContentProps, PluginButtonContext, PluginButtonIcon, PluginButtonIconProps, PluginButtonMenuEntry, PluginButtonRegistration, PluginComposerPillContribution, PluginHeaderButtonContribution, } from "./buttons.js";
 export { usePaseo } from "./paseo-context.js";
 export { useAgent, useWorkspace } from "./client-state.js";

package/dist/client/ui.d.ts

@@ -65,4 +65,27 @@ export interface ExternalLinkProps {
     onError?: (error: unknown) => void;
 }
 export declare const ExternalLink: ComponentType<ExternalLinkProps>;
+export type SidebarIcon = string | ComponentType<{
+    size: number;
+    color: string;
+}>;
+export interface SidebarRowProps {
+    /**
+     * Tells rows of one item apart when the item renders several: "bot-2". Unique within the item.
+     * Omit it when the item renders one row.
+     */
+    id?: string;
+    /** A Lucide icon name or a component. */
+    icon?: SidebarIcon;
+    /** Defaults to the item's registered title. */
+    label?: string;
+    onPress(): void;
+    active?: boolean;
+    /** Right slot. Renders beside the row's pressable, so a button here presses on its own. */
+    trailing?: ReactNode;
+}
+/** A sidebar navigation row. Render it from a sidebar item's `Component`. */
+export declare const SidebarRow: ComponentType<SidebarRowProps>;
+/** A line between groups of rows. Render it from a sidebar item's `Component`. */
+export declare const SidebarSeparator: ComponentType;
 //# sourceMappingURL=ui.d.ts.map

package/dist/server/acp-internal/connection.js

@@ -15,6 +15,7 @@ export async function createAcpProviderConnection(options, request) {
     }
     const probe = await AcpRuntime.start({
         options,
+        launch: request.launch,
         boundarySessionId: "capability-probe",
         env: {},
         emit: () => undefined,
@@ -45,6 +46,7 @@ export async function createAcpProviderConnection(options, request) {
     };
     const state = {
         options,
+        launch: request.launch,
         capabilities,
         sessions,
         emit,
@@ -170,6 +172,7 @@ async function dispatch(input, state) {
 async function discover(input, state) {
     const runtime = await AcpRuntime.start({
         options: state.options,
+        launch: state.launch,
         boundarySessionId: "catalog",
         env: {},
         emit: state.emit,
@@ -191,6 +194,7 @@ async function discover(input, state) {
 async function listSessions(input, state) {
     const runtime = await AcpRuntime.start({
         options: state.options,
+        launch: state.launch,
         boundarySessionId: "sessions",
         env: {},
         emit: state.emit,
@@ -218,6 +222,7 @@ async function openSession(input, state) {
         throw new Error(`Session already exists: ${input.sessionId}`);
     const runtime = await AcpRuntime.start({
         options: state.options,
+        launch: state.launch,
         boundarySessionId: input.sessionId,
         env: input.config.env,
         emit: state.emit,
@@ -257,9 +262,15 @@ class AcpRuntime {
         let stream;
         let closeConnector = async () => { };
         if (options.options.command) {
-            const [executable, ...args] = options.options.command;
-            child = spawn(executable, args, {
-                env: { ...process.env, ...options.env },
+            // COMPAT(pluginProviderLaunch): added in v0.10.0, remove after 2027-03-29 once plugin host floor >= v0.10.0.
+            // Standalone callers and older hosts do not send a daemon-resolved launch.
+            const launch = options.launch ?? {
+                command: options.options.command[0],
+                args: options.options.command.slice(1),
+                env: process.env,
+            };
+            child = spawn(launch.command, launch.args, {
+                env: { ...launch.env, ...options.env },
                 stdio: ["pipe", "pipe", "pipe"],
             });
             spawnFailure = new Promise((_resolve, reject) => child.once("error", reject));

package/dist/server/acp.js

@@ -13,6 +13,7 @@ export function runAcpProvider(options) {
         label: options.label,
         description: options.description,
         icon: options.icon,
+        command: options.command,
         connect(request) {
             return createAcpProviderConnection(options, request);
         },

package/dist/server/contracts.d.ts

@@ -3,6 +3,7 @@ import type { ZodType, input as ZodInput, output as ZodOutput } from "zod";
 import type { PluginRpcContract } from "../rpc.js";
 import type { PluginCleanup } from "../contracts.js";
 import type { ProviderRegistration } from "./provider.js";
+import type { UsageSourceRegistration } from "./usage.js";
 import type { PluginLifecycleRegistration } from "./lifecycle.js";
 export interface PluginHandlerContext {
     paseo: PaseoApi;
@@ -24,6 +25,7 @@ export interface PluginServerContext extends PluginLifecycleRegistration {
     registerSettings<Schema extends ZodType>(definition: import("../settings.js").SettingsDefinition<Schema>): PluginSettings<Schema>;
     handle<InputSchema extends ZodType, OutputSchema extends ZodType>(contract: PluginRpcContract<InputSchema, OutputSchema>, handler: (input: ZodOutput<InputSchema>, context: PluginHandlerContext) => ZodInput<OutputSchema> | Promise<ZodInput<OutputSchema>>): void;
     registerProvider(provider: ProviderRegistration): void;
+    registerUsageSource(source: UsageSourceRegistration): void;
 }
 export type PluginServerContribution = (server: PluginServerContext) => PluginCleanup;
 //# sourceMappingURL=contracts.d.ts.map

package/dist/server/index.d.ts

@@ -1,3 +1,4 @@
+export type { UsageSourceRegistration, UsageReport, UsageWindow, UsageBalance, UsageDetail, } from "./usage.js";
 export type { PluginHandlerContext, PluginServerContext, PluginServerContribution, PluginSettings, PluginSettingsState, } from "./contracts.js";
 export type { PluginHookContext, PluginHookWorkspace, PluginHookAgent, PluginSessionOpenRequest, PluginTurnOutcome, PluginLifecycleEvents, PluginBeforeRequests, PluginLifecycleRegistration, } from "./lifecycle.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/server/provider.d.ts

@@ -6,6 +6,9 @@ export type ProviderCapability = (typeof PROVIDER_CAPABILITIES)[number];
 export interface ProviderRegistration {
     /** Equal keys share discovery within this provider. Include effective configuration and execution environment. */
     getCatalogCacheKey?(options: ProviderCatalogOptions): Promise<string | undefined>;
+    /** Default executable and arguments; the daemon resolves overrides before status/connect. */
+    command?: readonly [string, ...string[]];
+    status?(request: ProviderStatusRequest): Promise<ProviderStatus>;
     id: string;
     label: string;
     description?: string;
@@ -16,12 +19,32 @@ export interface ProviderRegistration {
 export type ProviderCatalogOptions = {
     scope: "global";
     force?: boolean;
+    launch?: ProviderLaunch;
 } | {
     scope: "workspace";
     cwd: string;
     force?: boolean;
+    launch?: ProviderLaunch;
 };
+export declare const ProviderLaunchSchema: z.ZodObject<{
+    command: z.ZodString;
+    args: z.ZodArray<z.ZodString>;
+    env: z.ZodRecord<z.ZodString, z.ZodString>;
+}, z.core.$strip>;
+export type ProviderLaunch = z.infer<typeof ProviderLaunchSchema>;
+export interface ProviderStatusRequest {
+    launch?: ProviderLaunch;
+}
+export declare const ProviderStatusSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    available: z.ZodLiteral<true>;
+    diagnostic: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    available: z.ZodLiteral<false>;
+    diagnostic: z.ZodString;
+}, z.core.$strip>], "available">;
+export type ProviderStatus = z.infer<typeof ProviderStatusSchema>;
 export interface ProviderConnectRequest {
+    launch?: ProviderLaunch;
     versions: readonly number[];
     capabilities: readonly string[];
 }
@@ -65,7 +88,7 @@ export interface ProviderSessionConfig {
     mode?: string;
     thinkingOption?: string;
     settings: Readonly<Record<string, JsonValue>>;
-    providerOptions?: Readonly<Record<string, JsonValue>>;
+    providerOptions?: Readonly<Record<string, unknown>>;
     title?: string;
     persist: boolean;
 }

package/dist/server/provider.js

@@ -19,6 +19,19 @@ export const PROVIDER_CAPABILITIES = [
     "permission.tool_policy",
     "timeline.plugin",
 ];
+export const ProviderLaunchSchema = z
+    .object({
+    /** Resolved executable path. */
+    command: z.string().min(1),
+    args: z.array(z.string()),
+    /** Complete daemon-owned environment, including overrides and parent-session stripping. */
+    env: z.record(z.string(), z.string()),
+})
+    .strip();
+export const ProviderStatusSchema = z.discriminatedUnion("available", [
+    z.object({ available: z.literal(true), diagnostic: z.string().optional() }).strip(),
+    z.object({ available: z.literal(false), diagnostic: z.string().min(1) }).strip(),
+]);
 export function negotiateProviderCapabilities(offered, supported) {
     const known = new Set(PROVIDER_CAPABILITIES);
     const supportedCapabilities = new Set(supported.filter((capability) => known.has(capability)));
@@ -151,7 +164,7 @@ const sessionConfigSchema = z
     mode: z.string().optional(),
     thinkingOption: z.string().optional(),
     settings: jsonObjectSchema,
-    providerOptions: jsonObjectSchema.optional(),
+    providerOptions: z.record(z.string(), z.unknown()).optional(),
     title: z.string().optional(),
     persist: z.boolean(),
 })

package/dist/server/usage.d.ts

@@ -0,0 +1,85 @@
+import type { ZodType } from "zod";
+import type { JsonValue } from "@camerontaylor/paseo-protocol/agent-types";
+export interface UsageWindow {
+    id: string;
+    label: string;
+    /**
+     * A few characters naming the window where space is tight, e.g. "5h" or "wk". An empty string
+     * shows the percent alone; leaving it out shows `label`.
+     */
+    shortLabel?: string;
+    /** Shown in the usage summary until the user pins windows of their own. */
+    summary?: boolean;
+    usedPct?: number | null;
+    remainingPct?: number | null;
+    resetsAt?: string | null;
+    runsOutAt?: string | null;
+    shortfallPct?: number | null;
+    tone?: "default" | "ok" | "warning" | "danger";
+}
+export interface UsageBalance {
+    id: string;
+    label: string;
+    used?: number | null;
+    remaining?: number | null;
+    limit?: number | null;
+    unit: "usd" | "credits" | "requests" | "tokens";
+    resetsAt?: string | null;
+    tone?: UsageWindow["tone"];
+}
+export interface UsageDetail {
+    id: string;
+    label: string;
+    value: string;
+    tone?: UsageWindow["tone"];
+}
+export interface UsageReport {
+    status: "available" | "unavailable" | "error";
+    planLabel?: string;
+    windows: UsageWindow[];
+    balances?: UsageBalance[];
+    details?: UsageDetail[];
+    error?: string;
+}
+export interface UsageSourceRegistration {
+    id: string;
+    label: string;
+    icon?: string;
+    input: ZodType;
+    /** Stable account identity, resolved without fetching usage. */
+    identify(input: unknown): Promise<{
+        key: string;
+        label?: string;
+    } | null>;
+    fetch(input: unknown): Promise<UsageReport>;
+    discover(): Promise<JsonValue[]>;
+}
+export declare function windowFromUsedPct(input: {
+    id: string;
+    label: string;
+    shortLabel?: string;
+    summary?: boolean;
+    utilizationPct: number | null | undefined;
+    resetsAt?: string | null;
+    tone?: UsageWindow["tone"];
+}): UsageWindow;
+/**
+ * The tone scale for anything measured against a known limit, windows and balances alike.
+ *
+ * Thresholds match `deriveTone` in the app's provider-usage/tone.ts, which is what the
+ * client falls back to when a window arrives without a tone. Healthy is "ok" rather than
+ * "default" because that is what every provider setting a tone has always sent, and it is
+ * what the bars render today below their thresholds.
+ */
+export declare function toneFromUsedPct(usedPct: number | null | undefined): UsageWindow["tone"];
+/**
+ * Tone for a balance with no known limit, where a percentage cannot be computed and the
+ * only signal is whether anything is left. Prefer `toneFromUsedPct` when a limit exists:
+ * this one stays "ok" until the balance is completely spent.
+ */
+export declare function balanceToneFromRemaining(remaining: number | null | undefined): UsageBalance["tone"];
+/** Percentage of a limit consumed, or null when either side is unknown. */
+export declare function usedPctOf(used: number | null | undefined, limit: number | null | undefined): number | null;
+export declare function hashAccountKey(value: string): string;
+export declare function unavailableUsage(): UsageReport;
+//# sourceMappingURL=usage.d.ts.map

package/dist/server/usage.js

@@ -0,0 +1,65 @@
+import { createHash } from "node:crypto";
+export function windowFromUsedPct(input) {
+    const usedPct = typeof input.utilizationPct === "number" ? input.utilizationPct : null;
+    const window = {
+        id: input.id,
+        label: input.label,
+        usedPct,
+        remainingPct: usedPct === null ? null : Math.max(0, 100 - usedPct),
+        resetsAt: input.resetsAt ?? null,
+    };
+    if (input.shortLabel !== undefined)
+        window.shortLabel = input.shortLabel;
+    if (input.summary)
+        window.summary = true;
+    if (input.tone)
+        window.tone = input.tone;
+    return window;
+}
+/**
+ * The tone scale for anything measured against a known limit, windows and balances alike.
+ *
+ * Thresholds match `deriveTone` in the app's provider-usage/tone.ts, which is what the
+ * client falls back to when a window arrives without a tone. Healthy is "ok" rather than
+ * "default" because that is what every provider setting a tone has always sent, and it is
+ * what the bars render today below their thresholds.
+ */
+export function toneFromUsedPct(usedPct) {
+    if (typeof usedPct !== "number")
+        return "default";
+    if (usedPct > 90)
+        return "danger";
+    if (usedPct >= 70)
+        return "warning";
+    return "ok";
+}
+/**
+ * Tone for a balance with no known limit, where a percentage cannot be computed and the
+ * only signal is whether anything is left. Prefer `toneFromUsedPct` when a limit exists:
+ * this one stays "ok" until the balance is completely spent.
+ */
+export function balanceToneFromRemaining(remaining) {
+    if (typeof remaining !== "number")
+        return "default";
+    if (remaining <= 0)
+        return "danger";
+    return "ok";
+}
+/** Percentage of a limit consumed, or null when either side is unknown. */
+export function usedPctOf(used, limit) {
+    if (typeof used !== "number" || typeof limit !== "number" || limit <= 0)
+        return null;
+    return (used / limit) * 100;
+}
+export function hashAccountKey(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+export function unavailableUsage() {
+    return {
+        status: "unavailable",
+        windows: [],
+        balances: [],
+        details: [],
+    };
+}
+//# sourceMappingURL=usage.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camerontaylor/paseo-plugin",
-  "version": "0.10.1-fork.1",
+  "version": "0.11.0-beta.1.fork.1",
   "description": "Paseo plugin SDK package",
   "files": [
     "dist",
@@ -23,6 +23,11 @@
       "source": "./src/server/provider.ts",
       "default": "./dist/server/provider.js"
     },
+    "./server/usage": {
+      "types": "./dist/server/usage.d.ts",
+      "source": "./src/server/usage.ts",
+      "default": "./dist/server/usage.js"
+    },
     "./server/acp": {
       "types": "./dist/server/acp.d.ts",
       "source": "./src/server/acp.ts",
@@ -65,8 +70,8 @@
     "use-sync-external-store": "^1.6.0"
   },
   "devDependencies": {
-    "@camerontaylor/paseo-client": "0.10.1-fork.1",
-    "@camerontaylor/paseo-protocol": "0.10.1-fork.1",
+    "@camerontaylor/paseo-client": "0.11.0-beta.1.fork.1",
+    "@camerontaylor/paseo-protocol": "0.11.0-beta.1.fork.1",
     "@types/node": "^20.9.0",
     "@types/react": "~19.2.0",
     "react": "19.1.0",
@@ -76,8 +81,8 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@camerontaylor/paseo-client": "0.10.1-fork.1",
-    "@camerontaylor/paseo-protocol": "0.10.1-fork.1",
+    "@camerontaylor/paseo-client": "0.11.0-beta.1.fork.1",
+    "@camerontaylor/paseo-protocol": "0.11.0-beta.1.fork.1",
     "react": "~19.1.0",
     "react-native": ">=0.81.5",
     "zod": "^4.4.3"