@getpaseo/plugin 0.15.4 → 0.16.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.
Files changed (40) hide show
  1. package/LICENSE +211 -0
  2. package/dist/client/client-state.d.ts +74 -6
  3. package/dist/client/client-state.js +48 -16
  4. package/dist/client/composer.d.ts +104 -0
  5. package/dist/client/composer.js +37 -0
  6. package/dist/client/contracts.d.ts +36 -4
  7. package/dist/client/host.d.ts +9 -3
  8. package/dist/client/host.js +7 -3
  9. package/dist/client/index.d.ts +11 -3
  10. package/dist/client/index.js +4 -2
  11. package/dist/client/new-workspace.d.ts +69 -0
  12. package/dist/client/new-workspace.js +17 -0
  13. package/dist/client/paseo-context.d.ts +5 -5
  14. package/dist/client/paseo-context.js +1 -1
  15. package/dist/client/query.d.ts +26 -0
  16. package/dist/client/query.js +84 -0
  17. package/dist/client/reference-api.d.ts +38 -0
  18. package/dist/client/reference-api.js +44 -0
  19. package/dist/client/refs.d.ts +28 -0
  20. package/dist/client/refs.js +22 -0
  21. package/dist/client/rpc-context.d.ts +23 -3
  22. package/dist/client/rpc-context.js +60 -4
  23. package/dist/client/runtime-context-bridge.js +11 -3
  24. package/dist/client/ui.d.ts +65 -0
  25. package/dist/contracts.d.ts +39 -0
  26. package/dist/index.d.ts +2 -2
  27. package/dist/index.js +1 -1
  28. package/dist/refs.d.ts +16 -0
  29. package/dist/refs.js +2 -0
  30. package/dist/rpc.d.ts +40 -1
  31. package/dist/rpc.js +37 -2
  32. package/dist/server/acp-internal/connection.js +44 -19
  33. package/dist/server/contracts.d.ts +19 -2
  34. package/dist/server/index.d.ts +1 -1
  35. package/dist/server/lifecycle.d.ts +15 -2
  36. package/dist/server/provider.d.ts +44 -1
  37. package/dist/server/provider.js +29 -1
  38. package/dist/settings.d.ts +2 -2
  39. package/dist/settings.js +2 -2
  40. package/package.json +6 -5
@@ -1,3 +1,4 @@
1
+ import type { WorkspaceRef, AgentRef, ProjectRef, TerminalRef } from "./refs.js";
1
2
  import type { PluginText } from "./text.js";
2
3
  import type { JsonValue } from "@getpaseo/protocol/agent-types";
3
4
  import type { PluginSerializableIcon } from "./icons.js";
@@ -17,7 +18,21 @@ export interface PluginTheme {
17
18
  readonly statusDanger: string;
18
19
  };
19
20
  }
21
+ export type WorkspaceIndicator = "needs_input" | "failed" | "running" | "attention" | "done";
20
22
  export interface PluginWorkspaceSnapshot {
23
+ readonly ref: WorkspaceRef;
24
+ readonly hostId: string;
25
+ readonly project: ProjectRef;
26
+ readonly pinnedAt: string | null;
27
+ readonly labels: readonly string[];
28
+ readonly background: boolean;
29
+ readonly branch: string | null;
30
+ /** Null when an older host has not supplied the workspace creation time. */
31
+ readonly createdAt: string | null;
32
+ readonly lastPromptAt: string | null;
33
+ readonly parentAgent: AgentRef | null;
34
+ readonly indicator: WorkspaceIndicator;
35
+ readonly indicatorLabel: string | null;
21
36
  readonly id: string;
22
37
  readonly projectId: string;
23
38
  readonly projectDisplayName: string;
@@ -27,6 +42,7 @@ export interface PluginWorkspaceSnapshot {
27
42
  readonly kind: "directory" | "local_checkout" | "checkout" | "worktree";
28
43
  readonly name: string;
29
44
  readonly title: string | null;
45
+ /** Raw daemon status; prefer indicator for presentation. */
30
46
  readonly status: "needs_input" | "failed" | "running" | "attention" | "done";
31
47
  readonly statusEnteredAt: string | null;
32
48
  readonly archivingAt: string | null;
@@ -36,6 +52,10 @@ export interface PluginWorkspaceSnapshot {
36
52
  } | null;
37
53
  }
38
54
  export interface PluginAgentSnapshot {
55
+ readonly ref: AgentRef;
56
+ readonly hostId: string;
57
+ readonly workspace: WorkspaceRef;
58
+ readonly parentAgent: AgentRef | null;
39
59
  readonly id: string;
40
60
  readonly workspaceId: string;
41
61
  readonly provider: string;
@@ -52,6 +72,8 @@ export interface PluginAgentSnapshot {
52
72
  readonly attentionReason: "finished" | "error" | "permission" | null;
53
73
  readonly parentAgentId: string | null;
54
74
  readonly labels: Readonly<Record<string, string>>;
75
+ /** Structured data plugins store on the agent. */
76
+ readonly metadata: Readonly<Record<string, JsonValue>>;
55
77
  }
56
78
  export interface PluginThemeColors {
57
79
  background: string;
@@ -89,4 +111,21 @@ export interface PluginTimelineTransformResult {
89
111
  items: PluginTimelineItem[];
90
112
  }
91
113
  export type PluginCleanup = () => void | Promise<void>;
114
+ export interface PluginProjectSnapshot {
115
+ readonly ref: ProjectRef;
116
+ readonly hostId: string;
117
+ readonly displayName: string;
118
+ readonly rootPath: string;
119
+ readonly kind: PluginWorkspaceSnapshot["projectKind"];
120
+ readonly iconRevision: string | null;
121
+ }
122
+ export interface PluginTerminalSnapshot {
123
+ readonly ref: TerminalRef;
124
+ readonly hostId: string;
125
+ readonly workspace: WorkspaceRef;
126
+ readonly title: string;
127
+ readonly isScript: boolean;
128
+ /** Null for terminals owned by workers started before timestamps were tracked. */
129
+ readonly createdAt: string | null;
130
+ }
92
131
  //# sourceMappingURL=contracts.d.ts.map
package/dist/index.d.ts CHANGED
@@ -1,7 +1,7 @@
1
- export type { PluginTheme, PluginWorkspaceSnapshot, PluginAgentSnapshot, PluginThemeColors, PluginThemeContribution, PluginAttachmentSourceContribution, PluginTimelineData, PluginTimelineItem, PluginTimelineTransformResult, PluginCleanup, } from "./contracts.js";
1
+ export type { PluginTheme, PluginWorkspaceSnapshot, PluginAgentSnapshot, PluginProjectSnapshot, PluginTerminalSnapshot, WorkspaceIndicator, PluginThemeColors, PluginThemeContribution, PluginAttachmentSourceContribution, PluginTimelineData, PluginTimelineItem, PluginTimelineTransformResult, PluginCleanup, } from "./contracts.js";
2
2
  export { defineSettings, settingsRpc, type SettingsDefinition } from "./settings.js";
3
3
  export { defineAttachmentSource, PluginAttachmentItemSchema, PluginAttachmentSearchPayloadSchema, type PluginAttachmentItem, type PluginAttachmentSearchPayload, } from "./attachments.js";
4
- export { defineRpc, type PluginRpcContract, type RpcInput, type RpcOutput } from "./rpc.js";
4
+ export { defineRpc, defineSubscription, type PluginRpcContract, type PluginSubscriptionContract, type RpcInput, type RpcOutput, type SubscriptionEvent, type SubscriptionInput, } from "./rpc.js";
5
5
  export type { PluginText, PluginMessage } from "./text.js";
6
6
  export { findSvgIconProblem, PLUGIN_SVG_ICON_MAX_BYTES, type PluginIconProps, type PluginSerializableIcon, type PluginSvgIcon, } from "./icons.js";
7
7
  //# sourceMappingURL=index.d.ts.map
package/dist/index.js CHANGED
@@ -1,5 +1,5 @@
1
1
  export { defineSettings, settingsRpc } from "./settings.js";
2
2
  export { defineAttachmentSource, PluginAttachmentItemSchema, PluginAttachmentSearchPayloadSchema, } from "./attachments.js";
3
- export { defineRpc } from "./rpc.js";
3
+ export { defineRpc, defineSubscription, } from "./rpc.js";
4
4
  export { findSvgIconProblem, PLUGIN_SVG_ICON_MAX_BYTES, } from "./icons.js";
5
5
  //# sourceMappingURL=index.js.map
package/dist/refs.d.ts ADDED
@@ -0,0 +1,16 @@
1
+ interface EntityRef<Kind extends string> {
2
+ readonly kind: Kind;
3
+ readonly key: string;
4
+ readonly hostId: string;
5
+ readonly id: string;
6
+ }
7
+ export interface WorkspaceRef extends EntityRef<"workspace"> {
8
+ }
9
+ export interface AgentRef extends EntityRef<"agent"> {
10
+ }
11
+ export interface ProjectRef extends EntityRef<"project"> {
12
+ }
13
+ export interface TerminalRef extends EntityRef<"terminal"> {
14
+ }
15
+ export {};
16
+ //# sourceMappingURL=refs.d.ts.map
package/dist/refs.js ADDED
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=refs.js.map
package/dist/rpc.d.ts CHANGED
@@ -4,6 +4,11 @@ export interface PluginRpcContract<InputSchema extends ZodType = ZodType, Output
4
4
  input: InputSchema;
5
5
  output: OutputSchema;
6
6
  }
7
+ /**
8
+ * `z.instanceof(Uint8Array)` infers `Uint8Array<ArrayBuffer>`; values crossing the wire accept any
9
+ * `Uint8Array`, including a `Buffer` or a view of a shared buffer.
10
+ */
11
+ export type PluginWireInput<Value> = Value extends Uint8Array ? Uint8Array : Value;
7
12
  export type RpcInput<Contract extends PluginRpcContract> = ZodOutput<Contract["input"]>;
8
13
  export type RpcOutput<Contract extends PluginRpcContract> = ZodInput<Contract["output"]>;
9
14
  interface RpcDefinition<InputSchema extends ZodType, OutputSchema extends ZodType> {
@@ -12,6 +17,40 @@ interface RpcDefinition<InputSchema extends ZodType, OutputSchema extends ZodTyp
12
17
  output: OutputSchema;
13
18
  }
14
19
  export declare function defineRpc<InputSchema extends ZodType, OutputSchema extends ZodType>(definition: RpcDefinition<InputSchema, OutputSchema>): PluginRpcContract<InputSchema, OutputSchema>;
15
- 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>>;
20
+ export declare function callPluginRpc<InputSchema extends ZodType, OutputSchema extends ZodType>(contract: PluginRpcContract<InputSchema, OutputSchema>, invoke: (method: string, input: unknown) => Promise<unknown>, input: PluginWireInput<ZodInput<InputSchema>>): Promise<ZodOutput<OutputSchema>>;
21
+ export interface PluginSubscriptionContract<InputSchema extends ZodType = ZodType, EventSchema extends ZodType = ZodType> {
22
+ name: string;
23
+ input: InputSchema;
24
+ event: EventSchema;
25
+ }
26
+ export type SubscriptionInput<Contract extends PluginSubscriptionContract> = ZodOutput<Contract["input"]>;
27
+ export type SubscriptionEvent<Contract extends PluginSubscriptionContract> = ZodOutput<Contract["event"]>;
28
+ interface SubscriptionDefinition<InputSchema extends ZodType, EventSchema extends ZodType> {
29
+ name: string;
30
+ input: InputSchema;
31
+ event: EventSchema;
32
+ }
33
+ export declare function defineSubscription<InputSchema extends ZodType, EventSchema extends ZodType>(definition: SubscriptionDefinition<InputSchema, EventSchema>): PluginSubscriptionContract<InputSchema, EventSchema>;
34
+ /** One subscription from a client surface. Calling it or `release()` ends it. */
35
+ export type PluginSubscriptionHandle = (() => void) & {
36
+ /** Resolves once the plugin acknowledged the subscription; rejects if it refused. */
37
+ readonly ready: Promise<void>;
38
+ release(): Promise<void>;
39
+ };
40
+ export interface PluginSubscriptionObserver {
41
+ event(event: unknown): void;
42
+ closed(error?: Error): void;
43
+ }
44
+ export interface PluginSubscriptionClosed {
45
+ /** Set when the plugin's handler failed, the plugin stopped, or an event failed validation. */
46
+ error?: Error;
47
+ }
48
+ export interface PluginSubscribeOptions {
49
+ /** Aborting releases the subscription. */
50
+ signal?: AbortSignal;
51
+ /** Runs once when the daemon closes the subscription. Not called after a release. */
52
+ onClosed?: (closed: PluginSubscriptionClosed) => void;
53
+ }
54
+ export declare function subscribePluginRpc<InputSchema extends ZodType, EventSchema extends ZodType>(contract: PluginSubscriptionContract<InputSchema, EventSchema>, subscribe: (method: string, input: unknown, observer: PluginSubscriptionObserver) => PluginSubscriptionHandle, input: PluginWireInput<ZodInput<InputSchema>>, onEvent: (event: ZodOutput<EventSchema>) => void, options?: PluginSubscribeOptions): PluginSubscriptionHandle;
16
55
  export {};
17
56
  //# sourceMappingURL=rpc.d.ts.map
package/dist/rpc.js CHANGED
@@ -6,8 +6,43 @@ export function defineRpc(definition) {
6
6
  return { ...definition, name };
7
7
  }
8
8
  export async function callPluginRpc(contract, invoke, input) {
9
- const parsedInput = await contract.input.parseAsync(input);
10
- const output = await invoke(contract.name, parsedInput);
9
+ const output = await invoke(contract.name, input);
11
10
  return contract.output.parseAsync(output);
12
11
  }
12
+ export function defineSubscription(definition) {
13
+ const name = definition.name.trim();
14
+ if (!RPC_NAME.test(name))
15
+ throw new Error(`Invalid plugin subscription: ${definition.name}`);
16
+ return { ...definition, name };
17
+ }
18
+ export function subscribePluginRpc(contract, subscribe, input, onEvent, options = {}) {
19
+ // The plugin parses the input into the schema's output, so it receives the input as given.
20
+ contract.input.parse(input);
21
+ let closed = false;
22
+ function close(error) {
23
+ if (closed)
24
+ return;
25
+ closed = true;
26
+ options.onClosed?.(error ? { error } : {});
27
+ }
28
+ const handle = subscribe(contract.name, input, {
29
+ event(event) {
30
+ if (closed)
31
+ return;
32
+ const parsed = contract.event.safeParse(event);
33
+ if (parsed.success)
34
+ return onEvent(parsed.data);
35
+ handle();
36
+ close(new Error(`Plugin subscription ${contract.name} sent an invalid event`));
37
+ },
38
+ closed: close,
39
+ });
40
+ if (options.signal) {
41
+ if (options.signal.aborted)
42
+ handle();
43
+ else
44
+ options.signal.addEventListener("abort", () => handle(), { once: true });
45
+ }
46
+ return handle;
47
+ }
13
48
  //# sourceMappingURL=rpc.js.map
@@ -546,17 +546,18 @@ class AcpRuntime {
546
546
  });
547
547
  }
548
548
  async configure(changes) {
549
- const ordered = [];
549
+ const requested = [];
550
550
  if (changes.model !== undefined)
551
- ordered.push({ target: "model", value: changes.model });
551
+ requested.push({ target: "model", value: changes.model });
552
552
  if (changes.mode !== undefined)
553
- ordered.push({ target: "mode", value: changes.mode });
553
+ requested.push({ target: "mode", value: changes.mode });
554
554
  if (changes.thinkingOption !== undefined) {
555
- ordered.push({ target: "thinking", value: changes.thinkingOption });
555
+ requested.push({ target: "thinking", value: changes.thinkingOption });
556
556
  }
557
557
  for (const [id, value] of Object.entries(changes.settings ?? {})) {
558
- ordered.push({ target: "setting", id, value });
558
+ requested.push({ target: "setting", id, value });
559
559
  }
560
+ const ordered = this.inAgentOrder(requested);
560
561
  const previousModes = this.modes ? structuredClone(this.modes) : null;
561
562
  const previousOptions = structuredClone(this.configOptions);
562
563
  this.configTransaction = true;
@@ -620,16 +621,39 @@ class AcpRuntime {
620
621
  }
621
622
  }
622
623
  async applyInitialConfig(config) {
624
+ const requested = [];
623
625
  if (config.model)
624
- await this.applyConfigChange({ target: "model", value: config.model });
626
+ requested.push({ target: "model", value: config.model });
625
627
  if (config.mode)
626
- await this.applyConfigChange({ target: "mode", value: config.mode });
628
+ requested.push({ target: "mode", value: config.mode });
627
629
  if (config.thinkingOption) {
628
- await this.applyConfigChange({ target: "thinking", value: config.thinkingOption });
630
+ requested.push({ target: "thinking", value: config.thinkingOption });
629
631
  }
630
632
  for (const [id, value] of Object.entries(config.settings)) {
631
- await this.applyConfigChange({ target: "setting", id, value });
633
+ requested.push({ target: "setting", id, value });
632
634
  }
635
+ for (const change of this.inAgentOrder(requested))
636
+ await this.applyConfigChange(change);
637
+ }
638
+ // One option can reset another: choosing an fx provider also selects that provider's saved
639
+ // model, so a model applied first would be lost. Agents list the option that decides first.
640
+ inAgentOrder(changes) {
641
+ const position = (change) => {
642
+ const configId = this.configIdFor(change);
643
+ const index = this.configOptions.findIndex((option) => option.id === configId);
644
+ return index === -1 ? this.configOptions.length : index;
645
+ };
646
+ return changes.toSorted((left, right) => position(left) - position(right));
647
+ }
648
+ configIdFor(change) {
649
+ if (change.target === "setting")
650
+ return change.id;
651
+ if (change.target === "model")
652
+ return modelOption(this.configOptions)?.id;
653
+ if (change.target === "thinking") {
654
+ return this.configOptions.find((option) => option.category === "thought_level")?.id;
655
+ }
656
+ return this.configOptions.find((option) => option.category === "mode")?.id;
633
657
  }
634
658
  async applyConfigChange(change) {
635
659
  const access = this.configAccess();
@@ -652,14 +676,7 @@ class AcpRuntime {
652
676
  this.modes = { ...this.modes, currentModeId: change.value };
653
677
  return;
654
678
  }
655
- let category = null;
656
- if (change.target === "model")
657
- category = "model";
658
- if (change.target === "thinking")
659
- category = "thought_level";
660
- const configId = change.target === "setting"
661
- ? change.id
662
- : this.configOptions.find((option) => option.category === category)?.id;
679
+ const configId = this.configIdFor(change);
663
680
  if (!configId) {
664
681
  throw new Error(`ACP session does not expose ${change.target} configuration`);
665
682
  }
@@ -1174,7 +1191,7 @@ function readNativeSessionId(persistence) {
1174
1191
  return typeof persistence.data.sessionId === "string" ? persistence.data.sessionId : null;
1175
1192
  }
1176
1193
  function toProviderConfigState(modes, options) {
1177
- const model = options.find((option) => option.category === "model");
1194
+ const model = modelOption(options);
1178
1195
  const thinking = options.find((option) => option.category === "thought_level");
1179
1196
  return {
1180
1197
  model: selectedValue(model),
@@ -1191,10 +1208,18 @@ function toProviderConfigState(modes, options) {
1191
1208
  label: option.label,
1192
1209
  })),
1193
1210
  settings: options
1194
- .filter((option) => option.category !== "model" && option.category !== "thought_level")
1211
+ .filter((option) => option !== model &&
1212
+ option.category !== "thought_level" &&
1213
+ !(modes && option.category === "mode"))
1195
1214
  .map(toProviderSetting),
1196
1215
  };
1197
1216
  }
1217
+ // ACP's category is a grouping hint, so one category can hold several controls. fx files its
1218
+ // provider first, then the model, Fast, and Ultrafast under "model".
1219
+ function modelOption(options) {
1220
+ const candidates = options.filter((option) => option.category === "model");
1221
+ return candidates.find((option) => option.id === "model") ?? candidates[0];
1222
+ }
1198
1223
  function toProviderCatalog(modes, options) {
1199
1224
  const state = toProviderConfigState(modes, options);
1200
1225
  return {
@@ -1,6 +1,6 @@
1
1
  import type { PaseoApi } from "@getpaseo/client";
2
2
  import type { ZodType, input as ZodInput, output as ZodOutput } from "zod";
3
- import type { PluginRpcContract } from "../rpc.js";
3
+ import type { PluginRpcContract, PluginSubscriptionContract, PluginWireInput } from "../rpc.js";
4
4
  import type { PluginCleanup } from "../contracts.js";
5
5
  import type { ProviderRegistration } from "./provider.js";
6
6
  import type { UsageSourceRegistration } from "./usage.js";
@@ -8,6 +8,17 @@ import type { PluginLifecycleRegistration } from "./lifecycle.js";
8
8
  export interface PluginHandlerContext {
9
9
  paseo: PaseoApi;
10
10
  }
11
+ /** What a subscription handler receives beside its input. */
12
+ export interface PluginSubscriptionContext<Event = unknown> extends PluginHandlerContext {
13
+ /**
14
+ * Sends one event to this subscriber. A `Uint8Array` event travels as a binary frame; any other
15
+ * event is JSON and must not contain a `Uint8Array`. Resolves once the event left the plugin
16
+ * process. Events pushed after `signal` aborts are dropped.
17
+ */
18
+ push(event: Event): Promise<void>;
19
+ /** Aborts when the subscriber releases, disconnects, or the plugin stops. */
20
+ signal: AbortSignal;
21
+ }
11
22
  export type PluginSettingsState<Schema extends ZodType> = {
12
23
  status: "ready";
13
24
  revision: string;
@@ -23,7 +34,13 @@ export interface PluginSettings<Schema extends ZodType> {
23
34
  }
24
35
  export interface PluginServerContext extends PluginLifecycleRegistration {
25
36
  registerSettings<Schema extends ZodType>(definition: import("../settings.js").SettingsDefinition<Schema>): PluginSettings<Schema>;
26
- handle<InputSchema extends ZodType, OutputSchema extends ZodType>(contract: PluginRpcContract<InputSchema, OutputSchema>, handler: (input: ZodOutput<InputSchema>, context: PluginHandlerContext) => ZodInput<OutputSchema> | Promise<ZodInput<OutputSchema>>): void;
37
+ /**
38
+ * Serves a subscription. The handler starts the work and returns; the subscription stays open
39
+ * until `signal` aborts. A handler that throws refuses the subscription. When it returns a
40
+ * promise, settling the promise closes the subscription, with the rejection as its error.
41
+ */
42
+ handle<InputSchema extends ZodType, EventSchema extends ZodType>(contract: PluginSubscriptionContract<InputSchema, EventSchema>, handler: (input: ZodOutput<InputSchema>, context: PluginSubscriptionContext<PluginWireInput<ZodInput<EventSchema>>>) => void | Promise<void>): void;
43
+ handle<InputSchema extends ZodType, OutputSchema extends ZodType>(contract: PluginRpcContract<InputSchema, OutputSchema>, handler: (input: ZodOutput<InputSchema>, context: PluginHandlerContext) => PluginWireInput<ZodInput<OutputSchema>> | Promise<PluginWireInput<ZodInput<OutputSchema>>>): void;
27
44
  registerProvider(provider: ProviderRegistration): void;
28
45
  registerUsageSource(source: UsageSourceRegistration): void;
29
46
  }
@@ -1,5 +1,5 @@
1
1
  export type { UsageSourceRegistration, UsageReport, UsageWindow, UsageBalance, UsageDetail, } from "./usage.js";
2
- export type { PluginHandlerContext, PluginServerContext, PluginServerContribution, PluginSettings, PluginSettingsState, } from "./contracts.js";
2
+ export type { PluginHandlerContext, PluginServerContext, PluginServerContribution, PluginSettings, PluginSettingsState, PluginSubscriptionContext, } from "./contracts.js";
3
3
  export type { PluginHooks, PluginHookEvents, PluginHookRequests, PluginHookPayload, PluginHookResult, PluginHookContext, PluginHookWorkspace, PluginHookWorktree, PluginWorktreeCreateRequest, PluginHookAgent, PluginSessionOpenRequest, PluginTurnOutcome, PluginLifecycleEvents, PluginBeforeRequests, PluginLifecycleRegistration, } from "./lifecycle.js";
4
4
  export { spawnProcess, execCommand, terminateProcess } from "./process.js";
5
5
  export { defineAgentTool } from "./agent-tools.js";
@@ -1,5 +1,5 @@
1
1
  import type { AgentToolDefinition } from "./agent-tools.js";
2
- import type { AgentPermissionRequest, AgentPermissionResponse, AgentTimelineItem, AgentSessionConfig } from "@getpaseo/protocol/agent-types";
2
+ import type { AgentPermissionRequest, AgentPermissionResponse, AgentTimelineItem, 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 {
@@ -12,6 +12,8 @@ export interface PluginHookWorkspace {
12
12
  cwd: string;
13
13
  name: string | null;
14
14
  archivedAt: string | null;
15
+ /** Data plugins stored on the workspace. Paseo never reads a key. */
16
+ metadata: Record<string, JsonValue>;
15
17
  }
16
18
  export interface PluginHookWorktree {
17
19
  path: string;
@@ -64,6 +66,8 @@ export interface PluginHookAgent {
64
66
  provider: string;
65
67
  cwd: string;
66
68
  title: string | null;
69
+ /** Data plugins stored on the agent. Paseo never reads a key. */
70
+ metadata: Record<string, JsonValue>;
67
71
  }
68
72
  export interface PluginSessionOpenRequest {
69
73
  agentId: string;
@@ -74,6 +78,7 @@ export interface PluginSessionOpenRequest {
74
78
  purpose: "interactive" | "history";
75
79
  readonly title: string | null;
76
80
  readonly labels: Readonly<Record<string, string>>;
81
+ readonly metadata: Readonly<Record<string, JsonValue>>;
77
82
  tools: AgentToolDefinition[];
78
83
  env: Record<string, string>;
79
84
  mcpServers: NonNullable<AgentSessionConfig["mcpServers"]>;
@@ -136,14 +141,22 @@ export interface PluginHookRequests {
136
141
  "agent.create.before": {
137
142
  config: AgentSessionConfig;
138
143
  env?: Record<string, string>;
144
+ /** Stored on the new agent. Always present in the payload; return it changed to change it. */
145
+ metadata?: Record<string, JsonValue>;
139
146
  };
140
147
  "agent.open.before": PluginSessionOpenRequest;
141
148
  "workspace.create.before": Omit<WorkspaceCreateRequest, "type" | "requestId">;
142
149
  }
150
+ /** What a hook may return. An omitted `metadata` stays as it was. */
151
+ type PluginHookRequestResults = Omit<PluginHookRequests, "agent.open.before"> & {
152
+ "agent.open.before": Omit<PluginSessionOpenRequest, "metadata"> & {
153
+ metadata?: Readonly<Record<string, JsonValue>>;
154
+ };
155
+ };
143
156
  export type PluginHooks = {
144
157
  [Name in keyof PluginHookRequests]: {
145
158
  request: PluginHookRequests[Name];
146
- result: PluginHookRequests[Name];
159
+ result: PluginHookRequestResults[Name];
147
160
  };
148
161
  } & {
149
162
  [Name in keyof PluginHookEvents]: {
@@ -89,7 +89,9 @@ export interface ProviderSessionConfig {
89
89
  model?: string;
90
90
  mode?: string;
91
91
  thinkingOption?: string;
92
+ /** @deprecated The same values as `providerOptions`. */
92
93
  settings: Readonly<Record<string, JsonValue>>;
94
+ /** The agent's options, the provider defaults from `config.json` included. */
93
95
  providerOptions?: Readonly<Record<string, unknown>>;
94
96
  title?: string;
95
97
  persist: boolean;
@@ -98,6 +100,13 @@ export interface ProviderConfigChanges {
98
100
  model?: string | null;
99
101
  mode?: string | null;
100
102
  thinkingOption?: string | null;
103
+ /**
104
+ * The option keys to change on the running session, with or without a control. Apply every key
105
+ * or fail the whole request, for a key you only read when a session opens. `null` returns the
106
+ * key to the provider's own default. The committed values come back in `session.config`.
107
+ */
108
+ providerOptions?: Readonly<Record<string, JsonValue>>;
109
+ /** @deprecated Sent next to `providerOptions` to a provider that reports `settings`. */
101
110
  settings?: Readonly<Record<string, JsonValue>>;
102
111
  }
103
112
  export interface ProviderPrompt {
@@ -294,6 +303,35 @@ export interface ProviderMode {
294
303
  colorTier?: string;
295
304
  isUnattended?: boolean;
296
305
  }
306
+ /**
307
+ * Draws one top-level option key in the composer. The control holds no value: Paseo reads it
308
+ * from the agent's options.
309
+ */
310
+ export type ProviderOptionControl = {
311
+ type: "toggle";
312
+ key: string;
313
+ label: string;
314
+ description?: string;
315
+ /** A Lucide icon name. */
316
+ icon?: string;
317
+ /** Shown while the key has no value. */
318
+ defaultValue?: boolean;
319
+ } | {
320
+ type: "select";
321
+ key: string;
322
+ label: string;
323
+ description?: string;
324
+ /** A Lucide icon name. */
325
+ icon?: string;
326
+ /** The choice shown while the key has no value. */
327
+ defaultValue?: string;
328
+ choices: ReadonlyArray<{
329
+ value: string;
330
+ label: string;
331
+ description?: string;
332
+ }>;
333
+ };
334
+ /** @deprecated Report `controls` and `providerOptions` instead. */
297
335
  export type ProviderSetting = {
298
336
  type: "toggle";
299
337
  id: string;
@@ -318,7 +356,12 @@ export interface ProviderConfigState {
318
356
  models: readonly ProviderModel[];
319
357
  modes: readonly ProviderMode[];
320
358
  thinkingOptions: readonly ProviderThinkingOption[];
321
- settings: readonly ProviderSetting[];
359
+ /** The option keys that get a composer control. May change at runtime, for example per model. */
360
+ controls?: readonly ProviderOptionControl[];
361
+ /** What the session runs with now, for the keys it reports. Publish the committed values. */
362
+ providerOptions?: Readonly<Record<string, JsonValue>>;
363
+ /** @deprecated Report `controls` and `providerOptions`. Each setting id is an option key. */
364
+ settings?: readonly ProviderSetting[];
322
365
  }
323
366
  export interface ProviderCatalog {
324
367
  models: readonly ProviderModel[];
@@ -304,6 +304,7 @@ const configChangesSchema = z
304
304
  model: z.string().nullable().optional(),
305
305
  mode: z.string().nullable().optional(),
306
306
  thinkingOption: z.string().nullable().optional(),
307
+ providerOptions: jsonObjectSchema.optional(),
307
308
  settings: jsonObjectSchema.optional(),
308
309
  })
309
310
  .strict();
@@ -438,6 +439,31 @@ const settingSchema = z.discriminatedUnion("type", [
438
439
  })
439
440
  .strip(),
440
441
  ]);
442
+ const controlSchema = z.discriminatedUnion("type", [
443
+ z
444
+ .object({
445
+ type: z.literal("toggle"),
446
+ key: idSchema,
447
+ label: z.string(),
448
+ description: z.string().optional(),
449
+ icon: z.string().optional(),
450
+ defaultValue: z.boolean().optional(),
451
+ })
452
+ .strip(),
453
+ z
454
+ .object({
455
+ type: z.literal("select"),
456
+ key: idSchema,
457
+ label: z.string(),
458
+ description: z.string().optional(),
459
+ icon: z.string().optional(),
460
+ defaultValue: z.string().optional(),
461
+ choices: z.array(z
462
+ .object({ value: z.string(), label: z.string(), description: z.string().optional() })
463
+ .strip()),
464
+ })
465
+ .strip(),
466
+ ]);
441
467
  const configStateSchema = z
442
468
  .object({
443
469
  model: z.string().optional(),
@@ -446,7 +472,9 @@ const configStateSchema = z
446
472
  models: z.array(modelSchema),
447
473
  modes: z.array(modeSchema),
448
474
  thinkingOptions: z.array(selectOptionSchema),
449
- settings: z.array(settingSchema),
475
+ controls: z.array(controlSchema).optional(),
476
+ providerOptions: jsonObjectSchema.optional(),
477
+ settings: z.array(settingSchema).optional(),
450
478
  })
451
479
  .strip();
452
480
  const catalogSchema = z
@@ -2,10 +2,10 @@ import { z } from "zod";
2
2
  import type { ZodType } from "zod";
3
3
  export interface SettingsDefinition<Schema extends ZodType = ZodType> {
4
4
  id: string;
5
- scope: "host";
5
+ scope: "host" | "device";
6
6
  version: number;
7
7
  schema: Schema;
8
- /** Convert a previous stored version to the current schema. Runs on the host. */
8
+ /** Convert a previous stored version to the current schema. Runs in the selected scope. */
9
9
  migrate?: (values: unknown, fromVersion: number) => unknown | Promise<unknown>;
10
10
  }
11
11
  export declare function defineSettings<Schema extends ZodType>(definition: SettingsDefinition<Schema>): SettingsDefinition<Schema>;
package/dist/settings.js CHANGED
@@ -3,8 +3,8 @@ import { defineRpc } from "./rpc.js";
3
3
  export function defineSettings(definition) {
4
4
  if (!/^[a-z][a-z0-9_-]*$/.test(definition.id))
5
5
  throw new Error("Invalid settings ID");
6
- if (definition.scope !== "host")
7
- throw new Error("Only host-scoped settings are supported");
6
+ if (definition.scope !== "host" && definition.scope !== "device")
7
+ throw new Error("Invalid settings scope");
8
8
  if (!Number.isSafeInteger(definition.version) || definition.version < 1)
9
9
  throw new Error("Invalid settings version");
10
10
  return definition;
package/package.json CHANGED
@@ -1,7 +1,8 @@
1
1
  {
2
2
  "name": "@getpaseo/plugin",
3
- "version": "0.15.4",
3
+ "version": "0.16.0-beta.1",
4
4
  "description": "Paseo plugin SDK package",
5
+ "license": "Apache-2.0",
5
6
  "files": [
6
7
  "dist",
7
8
  "!dist/**/*.map"
@@ -77,8 +78,8 @@
77
78
  "use-sync-external-store": "^1.6.0"
78
79
  },
79
80
  "devDependencies": {
80
- "@getpaseo/client": "0.15.4",
81
- "@getpaseo/protocol": "0.15.4",
81
+ "@getpaseo/client": "0.16.0-beta.1",
82
+ "@getpaseo/protocol": "0.16.0-beta.1",
82
83
  "@types/node": "^20.9.0",
83
84
  "@types/react": "~19.2.0",
84
85
  "react": "19.2.3",
@@ -88,8 +89,8 @@
88
89
  "zod": "^4.4.3"
89
90
  },
90
91
  "peerDependencies": {
91
- "@getpaseo/client": "0.15.4",
92
- "@getpaseo/protocol": "0.15.4",
92
+ "@getpaseo/client": "0.16.0-beta.1",
93
+ "@getpaseo/protocol": "0.16.0-beta.1",
93
94
  "react": ">=19.1.0 <20",
94
95
  "react-native": ">=0.81.5",
95
96
  "zod": "^4.4.3"