@getpaseo/plugin 0.8.0-beta.1 → 0.9.0-beta.1

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.
@@ -0,0 +1,64 @@
1
+ import type { ComponentType } from "react";
2
+ import type { PluginHostProps } from "./contracts.js";
3
+ export type PluginButtonContext = {
4
+ context: "workspace";
5
+ workspaceId: string;
6
+ } | {
7
+ context: "agent";
8
+ workspaceId: string;
9
+ agentId: string;
10
+ };
11
+ export type PluginButtonIconProps = PluginHostProps & PluginButtonContext & {
12
+ size: number;
13
+ color: string;
14
+ };
15
+ export type PluginButtonContentProps = PluginHostProps & PluginButtonContext & {
16
+ close(): void;
17
+ };
18
+ export type PluginButtonIcon = string | ComponentType<PluginButtonIconProps>;
19
+ export type PluginButtonBehavior = {
20
+ kind: "action";
21
+ onPress(): void | Promise<void>;
22
+ } | {
23
+ kind: "menu";
24
+ items: readonly PluginButtonMenuEntry[];
25
+ } | {
26
+ kind: "popover";
27
+ Content: ComponentType<PluginButtonContentProps>;
28
+ };
29
+ export type PluginButtonMenuEntry = {
30
+ kind: "separator";
31
+ id: string;
32
+ } | {
33
+ kind: "item";
34
+ id: string;
35
+ title: string;
36
+ icon?: PluginButtonIcon;
37
+ visible?: boolean;
38
+ disabled?: boolean;
39
+ behavior: PluginButtonBehavior;
40
+ };
41
+ export interface PluginButton {
42
+ title: string;
43
+ icon: PluginButtonIcon;
44
+ /** Omit for an icon-only header button. Composer pills use title when omitted. */
45
+ label?: string;
46
+ visible?: boolean;
47
+ disabled?: boolean;
48
+ behavior: PluginButtonBehavior;
49
+ }
50
+ export interface PluginButtonRegistration {
51
+ /** Updates presentation in place. Supply a complete behavior to replace it. */
52
+ update(patch: Partial<PluginButton>): void;
53
+ /** Idempotent. Updates after removal do nothing. */
54
+ remove(): void;
55
+ }
56
+ export interface PluginHeaderButtonContribution {
57
+ id: string;
58
+ workspaceId: string;
59
+ button: PluginButton;
60
+ }
61
+ export interface PluginComposerPillContribution extends PluginHeaderButtonContribution {
62
+ agentId: string;
63
+ }
64
+ //# sourceMappingURL=buttons.d.ts.map
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=buttons.js.map
@@ -3,6 +3,7 @@ import type { PaseoApi } from "@getpaseo/client";
3
3
  import type { AgentTimelineItem } from "@getpaseo/protocol/agent-types";
4
4
  import type { ZodType, input as ZodInput, output as ZodOutput } from "zod";
5
5
  import type { PluginRpcContract } from "../rpc.js";
6
+ import type { PluginButtonRegistration, PluginHeaderButtonContribution, PluginComposerPillContribution } from "./buttons.js";
6
7
  import type { PluginTheme, PluginWorkspaceSnapshot, PluginAgentSnapshot, PluginThemeContribution, PluginAttachmentSourceContribution, PluginTimelineTransformResult, PluginCleanup } from "../contracts.js";
7
8
  export interface PluginHostProps {
8
9
  theme: PluginTheme;
@@ -18,11 +19,19 @@ export interface PluginHostProps {
18
19
  interface PluginNavigableHostProps extends PluginHostProps {
19
20
  /** Client-owned navigation. Undefined on older hosts; hide dependent affordances when absent. */
20
21
  readonly navigation?: {
22
+ /** Present only on Electron. The browser runs locally; serverId selects workspace ownership. */
23
+ readonly openBrowser?: (input: {
24
+ readonly url: string;
25
+ readonly workspaceId: string;
26
+ readonly serverId?: string;
27
+ }) => void;
21
28
  readonly openAgent: (input: {
22
29
  readonly agentId: string;
30
+ readonly serverId?: string;
23
31
  }) => void;
24
32
  readonly openWorkspace: (input: {
25
33
  readonly workspaceId: string;
34
+ readonly serverId?: string;
26
35
  }) => void;
27
36
  };
28
37
  }
@@ -52,18 +61,6 @@ export interface PluginAgentPanelProps extends PluginNavigableHostProps {
52
61
  workspaceId: string;
53
62
  agentId: string;
54
63
  }
55
- export interface PluginComposerPillProps extends PluginHostProps {
56
- workspaceId: string;
57
- agentId: string;
58
- }
59
- export interface PluginComposerPillContribution {
60
- id: string;
61
- title: string;
62
- workspaceId: string;
63
- agentId: string;
64
- Component: ComponentType<PluginComposerPillProps>;
65
- onPress(): void | Promise<void>;
66
- }
67
64
  export interface PluginClientOpenPanelOptions extends PluginOpenPanelOptions {
68
65
  workspaceId: string;
69
66
  agentId?: string;
@@ -75,7 +72,8 @@ export interface PluginClientContext extends PluginCommandCapabilities {
75
72
  addWorkspacePanel(contribution: PluginWorkspacePanelContribution): PluginCleanup;
76
73
  addCommandCenterItem(contribution: PluginCommandCenterItemContribution): PluginCleanup;
77
74
  addSlashCommand(contribution: PluginClientSlashCommandContribution): PluginCleanup;
78
- addComposerPill(contribution: PluginComposerPillContribution): PluginCleanup;
75
+ addHeaderButton(contribution: PluginHeaderButtonContribution): PluginButtonRegistration;
76
+ addComposerPill(contribution: PluginComposerPillContribution): PluginButtonRegistration;
79
77
  addAttachmentSource(contribution: PluginAttachmentSourceContribution): PluginCleanup;
80
78
  addTheme(contribution: PluginThemeContribution): PluginCleanup;
81
79
  addTimelineTransformer<ItemType extends AgentTimelineItem["type"]>(contribution: PluginTimelineTransformerContribution<ItemType>): PluginCleanup;
@@ -1,4 +1,5 @@
1
- export type { PluginHostProps, PluginSurfaceProps, PluginIconProps, PluginPanelLocation, PluginOpenPanelOptions, PluginWorkspacePanelProps, PluginAgentPanelProps, PluginComposerPillProps, PluginComposerPillContribution, PluginClientOpenPanelOptions, PluginClientContext, PluginClientContribution, PluginWorkspacePanelContribution, PluginSettingsScreenContribution, PluginSurfaceContribution, PluginSidebarContribution, PluginTimelineTransformerContribution, PluginTimelineItemProps, PluginTimelineRendererContribution, PluginCommandCapabilities, PluginGlobalCommandContext, PluginWorkspaceCommandContext, PluginAgentCommandContext, PluginCommandCenterItemContribution, PluginClientSlashCommandContribution, SettingsState, } from "./contracts.js";
1
+ 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";
2
+ export type { PluginButton, PluginButtonBehavior, PluginButtonContentProps, PluginButtonContext, PluginButtonIcon, PluginButtonIconProps, PluginButtonMenuEntry, PluginButtonRegistration, PluginComposerPillContribution, PluginHeaderButtonContribution, } from "./buttons.js";
2
3
  export { usePaseo } from "./paseo-context.js";
3
4
  export { useAgent, useWorkspace } from "./client-state.js";
4
5
  export { useRpc } from "./rpc-context.js";
@@ -6,4 +7,16 @@ import type { SettingsDefinition } from "../settings.js";
6
7
  import type { SettingsState } from "./contracts.js";
7
8
  import type { ZodType } from "zod";
8
9
  export declare function useSettings<Schema extends ZodType>(definition: SettingsDefinition<Schema>): SettingsState<Schema>;
10
+ /** Configured app host, including hosts that are currently disconnected. */
11
+ export interface PluginHostSummary {
12
+ readonly serverId: string;
13
+ readonly label: string;
14
+ readonly status: "idle" | "connecting" | "online" | "offline" | "error";
15
+ }
16
+ /** Live configured hosts. Supplied by the app's client bundle loader. */
17
+ export declare function useHosts(): readonly PluginHostSummary[];
18
+ /** Borrow an online host's API under this installation's lifetime. */
19
+ export declare function getPaseoClient(serverId: string): import("@getpaseo/client").PaseoApi;
20
+ /** Open an absolute HTTP(S) URL using the client platform’s external opener. */
21
+ export declare function openExternalUrl(url: string): Promise<void>;
9
22
  //# sourceMappingURL=index.d.ts.map
@@ -57,4 +57,12 @@ export declare const SettingsSwitch: ComponentType<SettingsSwitchProps>;
57
57
  export declare function SettingsSelect<Value extends string>(props: SettingsSelectProps<Value>): ReactNode;
58
58
  export declare const SettingsInput: ComponentType<SettingsInputProps>;
59
59
  export declare const SettingsAction: ComponentType<SettingsActionProps>;
60
+ export interface ExternalLinkProps {
61
+ href: string;
62
+ children: ReactNode;
63
+ accessibilityLabel?: string;
64
+ testID?: string;
65
+ onError?: (error: unknown) => void;
66
+ }
67
+ export declare const ExternalLink: ComponentType<ExternalLinkProps>;
60
68
  //# sourceMappingURL=ui.d.ts.map
@@ -1,6 +1,6 @@
1
1
  import { spawn } from "node:child_process";
2
2
  import { Readable, Writable } from "node:stream";
3
- import { ClientSideConnection, PROTOCOL_VERSION, ndJsonStream, } from "@agentclientprotocol/sdk";
3
+ import { ClientSideConnection, CLIENT_METHODS, PROTOCOL_VERSION, ndJsonStream, } from "@agentclientprotocol/sdk";
4
4
  import { z } from "zod";
5
5
  import { PROVIDER_PROTOCOL_VERSION, ProviderEventSchema, ProviderInputSchema, negotiateProviderCapabilities, requireProviderCapabilities, } from "../provider.js";
6
6
  const ADAPTER_CAPABILITIES = [
@@ -303,6 +303,13 @@ class AcpRuntime {
303
303
  this.modes = null;
304
304
  this.commandWaiter = null;
305
305
  this.messageSequence = 0;
306
+ /**
307
+ * Fallback ids for streamed chunks that carry no `messageId`, one per
308
+ * chunk kind. Consecutive chunks of a kind continue the same timeline
309
+ * item; a chunk of the other kind, a tool call, a plan, a user message,
310
+ * or a turn boundary ends it (#4699).
311
+ */
312
+ this.fallbackChunkIds = new Map();
306
313
  this.closing = false;
307
314
  this.processFailed = false;
308
315
  this.configTransaction = false;
@@ -317,9 +324,8 @@ class AcpRuntime {
317
324
  const client = {
318
325
  requestPermission: (request) => this.requestPermission(request),
319
326
  sessionUpdate: (notification) => this.enqueueNotification(() => this.sessionUpdate(notification)),
320
- extNotification: (method, params) => this.enqueueNotification(() => this.vendorNotification(method, params)),
321
327
  };
322
- this.connection = new ClientSideConnection(() => client, stream);
328
+ this.connection = new ClientSideConnection(() => client, routeVendorNotifications(stream, (method, params) => this.vendorNotification(method, params)));
323
329
  if (!child)
324
330
  void this.connection.closed.then(() => this.handleUnexpectedTransportClose());
325
331
  child?.on("error", (error) => {
@@ -419,6 +425,7 @@ class AcpRuntime {
419
425
  }
420
426
  const prompt = toAcpPrompt(input.prompt);
421
427
  const turnId = `acp:${input.prompt.clientMessageId}`;
428
+ this.fallbackChunkIds.clear();
422
429
  this.emit({
423
430
  type: "timeline.item",
424
431
  sessionId: this.options.boundarySessionId,
@@ -446,6 +453,7 @@ class AcpRuntime {
446
453
  });
447
454
  const settled = this.call(this.connection.prompt({ sessionId: this.nativeSessionId, prompt })).then((response) => {
448
455
  const state = response.stopReason === "cancelled" ? "canceled" : "completed";
456
+ this.fallbackChunkIds.clear();
449
457
  this.terminalizeTransientItems(state);
450
458
  this.emit({
451
459
  type: "session.turn",
@@ -455,6 +463,7 @@ class AcpRuntime {
455
463
  });
456
464
  return undefined;
457
465
  }, (error) => {
466
+ this.fallbackChunkIds.clear();
458
467
  this.terminalizeTransientItems("failed");
459
468
  this.emit({
460
469
  type: "session.turn",
@@ -709,12 +718,18 @@ class AcpRuntime {
709
718
  if (update.sessionUpdate === "agent_message_chunk" ||
710
719
  update.sessionUpdate === "agent_thought_chunk" ||
711
720
  update.sessionUpdate === "user_message_chunk") {
712
- if (update.sessionUpdate === "user_message_chunk")
721
+ if (update.sessionUpdate === "user_message_chunk") {
722
+ this.fallbackChunkIds.clear();
713
723
  return;
724
+ }
725
+ // A chunk of one kind ends the other kind's item, whatever its content
726
+ // or id: reasoning, then text, then reasoning again are three items.
727
+ this.fallbackChunkIds.delete(update.sessionUpdate === "agent_message_chunk"
728
+ ? "agent_thought_chunk"
729
+ : "agent_message_chunk");
714
730
  if (update.content.type !== "text")
715
731
  return;
716
- const fallbackId = `${update.sessionUpdate}:${++this.messageSequence}`;
717
- const id = update.messageId ?? fallbackId;
732
+ const id = this.resolveChunkId(update.sessionUpdate, update.messageId);
718
733
  const text = `${this.messages.get(id) ?? ""}${update.content.text}`;
719
734
  this.messages.set(id, text);
720
735
  this.emit({
@@ -732,11 +747,27 @@ class AcpRuntime {
732
747
  return;
733
748
  }
734
749
  if (update.sessionUpdate === "tool_call" || update.sessionUpdate === "tool_call_update") {
750
+ if (update.sessionUpdate === "tool_call")
751
+ this.fallbackChunkIds.clear();
735
752
  this.reduceToolCall(update);
736
753
  return;
737
754
  }
755
+ if (update.sessionUpdate === "plan")
756
+ this.fallbackChunkIds.clear();
738
757
  this.reduceStateUpdate(update);
739
758
  }
759
+ resolveChunkId(kind, messageId) {
760
+ if (messageId) {
761
+ this.fallbackChunkIds.delete(kind);
762
+ return messageId;
763
+ }
764
+ let id = this.fallbackChunkIds.get(kind);
765
+ if (!id) {
766
+ id = `${kind}:${++this.messageSequence}`;
767
+ this.fallbackChunkIds.set(kind, id);
768
+ }
769
+ return id;
770
+ }
740
771
  reduceStateUpdate(update) {
741
772
  if (update.sessionUpdate === "plan") {
742
773
  this.emit({
@@ -933,6 +964,28 @@ class AcpRuntime {
933
964
  });
934
965
  }
935
966
  }
967
+ function routeVendorNotifications(stream, receive) {
968
+ const clientMethods = new Set(Object.values(CLIENT_METHODS));
969
+ return {
970
+ writable: stream.writable,
971
+ readable: stream.readable.pipeThrough(new TransformStream({
972
+ transform(message, controller) {
973
+ if ("method" in message && !("id" in message) && !clientMethods.has(message.method)) {
974
+ // The SDK dispatches extensions asynchronously and can resolve a later response first.
975
+ // Run synchronous vendor transforms in wire order, inside the configuration transaction.
976
+ try {
977
+ receive(message.method, message.params);
978
+ }
979
+ catch (error) {
980
+ console.error("Error handling ACP vendor notification", error);
981
+ }
982
+ }
983
+ else
984
+ controller.enqueue(message);
985
+ },
986
+ })),
987
+ };
988
+ }
936
989
  function selectPermissionOption(options, response) {
937
990
  if (response.selectedActionId !== undefined) {
938
991
  return (options.find((option) => option.optionId === response.selectedActionId &&
@@ -7,8 +7,21 @@ import type { PluginLifecycleRegistration } from "./lifecycle.js";
7
7
  export interface PluginHandlerContext {
8
8
  paseo: PaseoApi;
9
9
  }
10
+ export type PluginSettingsState<Schema extends ZodType> = {
11
+ status: "ready";
12
+ revision: string;
13
+ values: ZodOutput<Schema>;
14
+ } | {
15
+ status: "invalid";
16
+ revision: string;
17
+ error: string;
18
+ };
19
+ export interface PluginSettings<Schema extends ZodType> {
20
+ read(): Promise<PluginSettingsState<Schema>>;
21
+ subscribe(listener: (state: PluginSettingsState<Schema>) => void | Promise<void>): PluginCleanup;
22
+ }
10
23
  export interface PluginServerContext extends PluginLifecycleRegistration {
11
- registerSettings<Schema extends ZodType>(definition: import("../settings.js").SettingsDefinition<Schema>): void;
24
+ registerSettings<Schema extends ZodType>(definition: import("../settings.js").SettingsDefinition<Schema>): PluginSettings<Schema>;
12
25
  handle<InputSchema extends ZodType, OutputSchema extends ZodType>(contract: PluginRpcContract<InputSchema, OutputSchema>, handler: (input: ZodOutput<InputSchema>, context: PluginHandlerContext) => ZodInput<OutputSchema> | Promise<ZodInput<OutputSchema>>): void;
13
26
  registerProvider(provider: ProviderRegistration): void;
14
27
  }
@@ -1,3 +1,3 @@
1
- export type { PluginHandlerContext, PluginServerContext, PluginServerContribution, } from "./contracts.js";
1
+ export type { PluginHandlerContext, PluginServerContext, PluginServerContribution, PluginSettings, PluginSettingsState, } from "./contracts.js";
2
2
  export type { PluginHookContext, PluginHookWorkspace, PluginHookAgent, PluginSessionOpenRequest, PluginTurnOutcome, PluginLifecycleEvents, PluginBeforeRequests, PluginLifecycleRegistration, } from "./lifecycle.js";
3
3
  //# sourceMappingURL=index.d.ts.map
@@ -524,7 +524,10 @@ export type ProviderEvent = {
524
524
  type: "session.opened";
525
525
  requestId?: string;
526
526
  sessionId: string;
527
+ /** Direct parent in the provider session ID namespace. */
527
528
  parentSessionId?: string;
529
+ /** ID of the spawning tool call in the direct parent's timeline. */
530
+ toolCallId?: string;
528
531
  capabilities: readonly string[];
529
532
  restoration: "core" | "parent";
530
533
  persistence?: ProviderPersistence;
@@ -706,6 +706,7 @@ export const ProviderEventSchema = z.discriminatedUnion("type", [
706
706
  requestId: idSchema.optional(),
707
707
  sessionId: idSchema,
708
708
  parentSessionId: idSchema.optional(),
709
+ toolCallId: idSchema.optional(),
709
710
  capabilities: z.array(z.string()),
710
711
  restoration: z.enum(["core", "parent"]),
711
712
  persistence: persistenceSchema.optional(),
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@getpaseo/plugin",
3
- "version": "0.8.0-beta.1",
3
+ "version": "0.9.0-beta.1",
4
4
  "description": "Paseo plugin SDK package",
5
5
  "files": [
6
6
  "dist",
@@ -65,8 +65,8 @@
65
65
  "use-sync-external-store": "^1.6.0"
66
66
  },
67
67
  "devDependencies": {
68
- "@getpaseo/client": "0.8.0-beta.1",
69
- "@getpaseo/protocol": "0.8.0-beta.1",
68
+ "@getpaseo/client": "0.9.0-beta.1",
69
+ "@getpaseo/protocol": "0.9.0-beta.1",
70
70
  "@types/node": "^20.9.0",
71
71
  "@types/react": "~19.2.0",
72
72
  "react": "19.1.0",
@@ -76,8 +76,8 @@
76
76
  "zod": "^4.4.3"
77
77
  },
78
78
  "peerDependencies": {
79
- "@getpaseo/client": "0.8.0-beta.1",
80
- "@getpaseo/protocol": "0.8.0-beta.1",
79
+ "@getpaseo/client": "0.9.0-beta.1",
80
+ "@getpaseo/protocol": "0.9.0-beta.1",
81
81
  "react": "~19.1.0",
82
82
  "react-native": ">=0.81.5",
83
83
  "zod": "^4.4.3"