@getpaseo/plugin 0.16.0-beta.1 → 0.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -93,6 +93,20 @@ export interface PluginSidebarViewContribution<Text extends PluginText = string>
93
93
  description?: Text;
94
94
  Component: ComponentType<PluginSidebarViewProps>;
95
95
  }
96
+ export interface PluginWorkspaceRowBadgeItemProps extends PluginHostProps {
97
+ workspaceId: string;
98
+ }
99
+ /**
100
+ * Part of the line under a workspace's title in the sidebar, on every workspace of the plugin's host.
101
+ * Render `WorkspaceRowBadge`, or nothing when there is nothing to say about this workspace.
102
+ */
103
+ export interface PluginWorkspaceRowBadgeItemContribution<Text extends PluginText = string> {
104
+ id: string;
105
+ /** The item's toggle in the sidebar's Show menu. */
106
+ title: Text;
107
+ icon: PluginIcon;
108
+ Component: ComponentType<PluginWorkspaceRowBadgeItemProps>;
109
+ }
96
110
  /**
97
111
  * A Lucide icon name, inline SVG markup, or a component. Components receive the surface's size
98
112
  * and color; buttons widen the props with their host and target context.
@@ -178,6 +192,7 @@ export interface PluginClientContext extends PluginCommandCapabilities, PluginCl
178
192
  addSidebarHeaderItem(contribution: PluginSidebarItemContribution<PluginText>): PluginCleanup;
179
193
  addSidebarFooterItem(contribution: PluginSidebarItemContribution<PluginText>): PluginCleanup;
180
194
  addAgentPanel(contribution: PluginAgentPanelContribution<PluginText>): PluginCleanup;
195
+ addWorkspaceRowBadgeItem(contribution: PluginWorkspaceRowBadgeItemContribution<PluginText>): PluginCleanup;
181
196
  addWorkspacePanel(contribution: PluginWorkspacePanelContribution<PluginText>): PluginCleanup;
182
197
  addCommandCenterItem(contribution: PluginCommandCenterItemContribution<PluginText>): PluginCleanup;
183
198
  addSlashCommand(contribution: PluginClientSlashCommandContribution<PluginText>): PluginCleanup;
@@ -1,4 +1,4 @@
1
- export type { PluginHostProps, PluginTab, PluginPanelProps, PluginWorkspacePanelParams, PluginAgentPanelParams, PluginFilePanelParams, PluginAgentPanelContribution, PluginFilePanelContribution, PluginFilePanelProps, PluginSurfaceProps, PluginScreenProps, PluginPopoverProps, PluginScreenParams, PluginOpenScreenInput, PluginScreenLocation, PluginSidebarItemProps, PluginSidebarViewProps, PluginSidebarViewContribution, PluginSidebarItemContribution, PluginIcon, 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";
1
+ export type { PluginHostProps, PluginTab, PluginPanelProps, PluginWorkspacePanelParams, PluginAgentPanelParams, PluginFilePanelParams, PluginAgentPanelContribution, PluginFilePanelContribution, PluginFilePanelProps, PluginSurfaceProps, PluginScreenProps, PluginPopoverProps, PluginScreenParams, PluginOpenScreenInput, PluginScreenLocation, PluginSidebarItemProps, PluginSidebarViewProps, PluginSidebarViewContribution, PluginSidebarItemContribution, PluginWorkspaceRowBadgeItemProps, PluginWorkspaceRowBadgeItemContribution, PluginIcon, 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";
2
2
  export type { PluginButton, PluginButtonBehavior, PluginButtonContentProps, PluginButtonContext, PluginButtonIcon, PluginButtonIconProps, PluginButtonMenuEntry, PluginButtonRegistration, PluginComposerPillContribution, PluginHeaderButtonContribution, } from "./buttons.js";
3
3
  export type { PluginIconProps, PluginSerializableIcon, PluginSvgIcon } from "../icons.js";
4
4
  export type { PluginFile, PluginFileBytesState, PluginFileEvent, PluginFileTextState, PluginFileUrlState, PluginFileWriteOptions, } from "./file.js";
@@ -144,6 +144,18 @@ export interface SidebarRowProps {
144
144
  export declare const SidebarRow: ComponentType<SidebarRowProps>;
145
145
  /** A line between groups of rows. Render it from a sidebar item's `Component`. */
146
146
  export declare const SidebarSeparator: ComponentType;
147
+ export type WorkspaceRowBadgeTone = "muted" | "success" | "warning" | "danger" | "info";
148
+ export interface WorkspaceRowBadgeProps {
149
+ /** A Lucide icon name, inline SVG, or a component. */
150
+ icon?: SidebarIcon;
151
+ label?: string;
152
+ /** Default "muted". */
153
+ tone?: WorkspaceRowBadgeTone;
154
+ /** Defaults to `label`, then the item's `title`. */
155
+ accessibilityLabel?: string;
156
+ }
157
+ /** One item on a sidebar workspace row's meta line. Render it from a workspace row badge item's `Component`. */
158
+ export declare const WorkspaceRowBadge: ComponentType<WorkspaceRowBadgeProps>;
147
159
  /** Paseo's loading state. Fills the panel; the panel decides when to show it. */
148
160
  export declare const Loading: ComponentType;
149
161
  /** Render a local document URL in an isolated frame. */
@@ -60,6 +60,12 @@ export interface PluginAgentSnapshot {
60
60
  readonly workspaceId: string;
61
61
  readonly provider: string;
62
62
  readonly status: "initializing" | "idle" | "running" | "error" | "closed";
63
+ /** Shells and monitors the agent left running after its turn. 0 when none are live. */
64
+ readonly backgroundWork: {
65
+ readonly count: number;
66
+ };
67
+ /** A helper hidden from tabs, lists and attention. Fixed at creation. */
68
+ readonly background: boolean;
63
69
  readonly createdAt: string;
64
70
  readonly updatedAt: string;
65
71
  readonly lastActivityAt: string;
@@ -84,6 +90,12 @@ export interface PluginThemeColors {
84
90
  accent?: string;
85
91
  mutedForeground: string;
86
92
  ring: string;
93
+ sidebar?: string;
94
+ sidebarHover?: string;
95
+ sidebarSelected?: string;
96
+ surface3?: string;
97
+ surface4?: string;
98
+ foregroundExtraMuted?: string;
87
99
  }
88
100
  export interface PluginThemeContribution<Text extends PluginText = string> {
89
101
  id: string;
@@ -336,6 +336,7 @@ class AcpRuntime {
336
336
  this.notificationLane = Promise.resolve();
337
337
  this.promptLane = Promise.resolve();
338
338
  this.activePrompt = null;
339
+ this.lastUsage = {};
339
340
  this.child = child;
340
341
  this.closeConnector = closeConnector;
341
342
  this.emit = options.emit;
@@ -486,6 +487,20 @@ class AcpRuntime {
486
487
  // while earlier session updates are still queued. Apply them before the turn ends.
487
488
  const settled = this.call(this.connection.prompt({ sessionId: this.nativeSessionId, prompt })).then(async (response) => {
488
489
  await this.drainNotifications();
490
+ if (response.usage) {
491
+ this.lastUsage = {
492
+ ...this.lastUsage,
493
+ inputTokens: response.usage.inputTokens,
494
+ outputTokens: response.usage.outputTokens,
495
+ cachedInputTokens: response.usage.cachedReadTokens ?? undefined,
496
+ };
497
+ this.emit({
498
+ type: "session.usage",
499
+ sessionId: this.options.boundarySessionId,
500
+ turnId,
501
+ usage: this.lastUsage,
502
+ });
503
+ }
489
504
  const state = response.stopReason === "cancelled" ? "canceled" : "completed";
490
505
  this.fallbackChunkIds.clear();
491
506
  this.terminalizeTransientItems(state);
@@ -892,14 +907,16 @@ class AcpRuntime {
892
907
  return;
893
908
  }
894
909
  if (update.sessionUpdate === "usage_update") {
910
+ this.lastUsage = {
911
+ ...this.lastUsage,
912
+ contextWindowUsedTokens: update.used,
913
+ contextWindowMaxTokens: update.size,
914
+ totalCostUsd: update.cost?.currency === "USD" ? update.cost.amount : undefined,
915
+ };
895
916
  this.emit({
896
917
  type: "session.usage",
897
918
  sessionId: this.options.boundarySessionId,
898
- usage: {
899
- contextWindowUsedTokens: update.used,
900
- contextWindowMaxTokens: update.size,
901
- totalCostUsd: update.cost?.currency === "USD" ? update.cost.amount : undefined,
902
- },
919
+ usage: this.lastUsage,
903
920
  });
904
921
  return;
905
922
  }
@@ -1285,8 +1302,9 @@ function toolTimelineItem(snapshot) {
1285
1302
  name: snapshot.name ?? snapshot.title,
1286
1303
  detail,
1287
1304
  };
1288
- if (status === "failed")
1289
- return { ...base, status, error: snapshot.output };
1305
+ if (status === "failed") {
1306
+ return { ...base, status, error: snapshot.output ?? { message: "Tool failed" } };
1307
+ }
1290
1308
  return { ...base, status, error: null };
1291
1309
  }
1292
1310
  // A row the turn left open ends with the turn. The wire contract requires a non-null error on a
@@ -1,5 +1,5 @@
1
1
  import type { AgentToolDefinition } from "./agent-tools.js";
2
- import type { AgentPermissionRequest, AgentPermissionResponse, AgentTimelineItem, AgentSessionConfig, JsonValue } from "@getpaseo/protocol/agent-types";
2
+ import type { AgentPermissionRequest, AgentPermissionResponse, AgentSessionConfig, JsonValue } from "@getpaseo/protocol/agent-types";
3
3
  import type { PaseoApi } from "@getpaseo/client";
4
4
  import type { WorkspaceCreateRequest } from "@getpaseo/protocol/messages";
5
5
  export interface PluginHookContext {
@@ -66,6 +66,8 @@ export interface PluginHookAgent {
66
66
  provider: string;
67
67
  cwd: string;
68
68
  title: string | null;
69
+ /** A helper hidden from tabs, lists and attention. Fixed at creation. */
70
+ readonly background: boolean;
69
71
  /** Data plugins stored on the agent. Paseo never reads a key. */
70
72
  metadata: Record<string, JsonValue>;
71
73
  }
@@ -77,6 +79,8 @@ export interface PluginSessionOpenRequest {
77
79
  reason: "create" | "resume" | "refresh" | "import";
78
80
  purpose: "interactive" | "history";
79
81
  readonly title: string | null;
82
+ /** A helper hidden from tabs, lists and attention. Fixed at creation. */
83
+ readonly background: boolean;
80
84
  readonly labels: Readonly<Record<string, string>>;
81
85
  readonly metadata: Readonly<Record<string, JsonValue>>;
82
86
  tools: AgentToolDefinition[];
@@ -103,12 +107,13 @@ export interface PluginHookEvents {
103
107
  "agent.turn.after": {
104
108
  agent: PluginHookAgent;
105
109
  turnId: string | null;
106
- outcome: PluginTurnOutcome;
107
110
  /**
108
- * @deprecated Always empty. Fetch history on demand with
109
- * context.paseo.agents.ref(agent.id).timeline.refetch({ direction: "tail", limit: 20 }).
111
+ * The payload carries no history. Read the turn with
112
+ * `paseo.agents.ref(agent.id).timeline.refetch({ direction: "tail", limit: 1, wholeTurns: true })`
113
+ * and keep the entries whose `turnId` equals this `turnId`. The result is empty when a newer turn
114
+ * started before the read, or when `turnId` is `null`.
110
115
  */
111
- timeline: readonly AgentTimelineItem[];
116
+ outcome: PluginTurnOutcome;
112
117
  };
113
118
  "agent.permission.before": {
114
119
  agent: PluginHookAgent;
@@ -149,7 +154,8 @@ export interface PluginHookRequests {
149
154
  }
150
155
  /** What a hook may return. An omitted `metadata` stays as it was. */
151
156
  type PluginHookRequestResults = Omit<PluginHookRequests, "agent.open.before"> & {
152
- "agent.open.before": Omit<PluginSessionOpenRequest, "metadata"> & {
157
+ "agent.open.before": Omit<PluginSessionOpenRequest, "metadata" | "background"> & {
158
+ readonly background?: boolean;
153
159
  metadata?: Readonly<Record<string, JsonValue>>;
154
160
  };
155
161
  };
@@ -193,7 +199,7 @@ export interface PluginLifecycleRegistration {
193
199
  /** @deprecated Use addHook with the renamed hook. Removed after 2027-04-30. */
194
200
  before<Name extends keyof PluginBeforeRequests>(name: Name, handler: (input: {
195
201
  request: PluginBeforeRequests[Name];
196
- }, context: PluginHookContext) => PluginBeforeRequests[Name] | void | Promise<PluginBeforeRequests[Name] | void>): () => void;
202
+ }, context: PluginHookContext) => PluginBeforeResults[Name] | void | Promise<PluginBeforeResults[Name] | void>): () => void;
197
203
  }
198
204
  /** @internal Lifecycle policy shared by the daemon and plugin process. */
199
205
  export declare const pluginHookRegistry: {
@@ -262,6 +268,9 @@ export type PluginLifecycleEvents = {
262
268
  export type PluginBeforeRequests = {
263
269
  [Name in keyof typeof legacyRequests]: PluginHookRequests[(typeof legacyRequests)[Name]];
264
270
  };
271
+ type PluginBeforeResults = {
272
+ [Name in keyof typeof legacyRequests]: PluginHookRequestResults[(typeof legacyRequests)[Name]];
273
+ };
265
274
  /** @internal SDK adapter for the daemon's hook registry. */
266
275
  export declare function createLifecycleRegistration(register: (name: keyof PluginHooks, handler: (input: never, context: PluginHookContext) => unknown) => () => void): PluginLifecycleRegistration;
267
276
  export {};
@@ -183,7 +183,7 @@ interface ProviderReviewAttachment {
183
183
  type: "review";
184
184
  mimeType: "application/paseo-review";
185
185
  cwd: string;
186
- mode: "uncommitted" | "base";
186
+ mode: "uncommitted" | "base" | "all";
187
187
  baseRef?: string | null;
188
188
  comments: Array<{
189
189
  filePath: string;
@@ -257,7 +257,7 @@ const providerContentSchema = z.union([
257
257
  type: z.literal("review"),
258
258
  mimeType: z.literal("application/paseo-review"),
259
259
  cwd: z.string(),
260
- mode: z.enum(["uncommitted", "base"]),
260
+ mode: z.enum(["uncommitted", "base", "all"]),
261
261
  baseRef: z.string().nullable().optional(),
262
262
  comments: z.array(z
263
263
  .object({
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@getpaseo/plugin",
3
- "version": "0.16.0-beta.1",
3
+ "version": "0.16.0",
4
4
  "description": "Paseo plugin SDK package",
5
5
  "license": "Apache-2.0",
6
6
  "files": [
@@ -78,8 +78,8 @@
78
78
  "use-sync-external-store": "^1.6.0"
79
79
  },
80
80
  "devDependencies": {
81
- "@getpaseo/client": "0.16.0-beta.1",
82
- "@getpaseo/protocol": "0.16.0-beta.1",
81
+ "@getpaseo/client": "0.16.0",
82
+ "@getpaseo/protocol": "0.16.0",
83
83
  "@types/node": "^20.9.0",
84
84
  "@types/react": "~19.2.0",
85
85
  "react": "19.2.3",
@@ -89,8 +89,8 @@
89
89
  "zod": "^4.4.3"
90
90
  },
91
91
  "peerDependencies": {
92
- "@getpaseo/client": "0.16.0-beta.1",
93
- "@getpaseo/protocol": "0.16.0-beta.1",
92
+ "@getpaseo/client": "0.16.0",
93
+ "@getpaseo/protocol": "0.16.0",
94
94
  "react": ">=19.1.0 <20",
95
95
  "react-native": ">=0.81.5",
96
96
  "zod": "^4.4.3"