@getpaseo/plugin 0.15.4 → 0.16.0-beta.2

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 +45 -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 +66 -24
  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 +24 -3
  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,10 +52,20 @@ 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;
42
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;
43
69
  readonly createdAt: string;
44
70
  readonly updatedAt: string;
45
71
  readonly lastActivityAt: string;
@@ -52,6 +78,8 @@ export interface PluginAgentSnapshot {
52
78
  readonly attentionReason: "finished" | "error" | "permission" | null;
53
79
  readonly parentAgentId: string | null;
54
80
  readonly labels: Readonly<Record<string, string>>;
81
+ /** Structured data plugins store on the agent. */
82
+ readonly metadata: Readonly<Record<string, JsonValue>>;
55
83
  }
56
84
  export interface PluginThemeColors {
57
85
  background: string;
@@ -89,4 +117,21 @@ export interface PluginTimelineTransformResult {
89
117
  items: PluginTimelineItem[];
90
118
  }
91
119
  export type PluginCleanup = () => void | Promise<void>;
120
+ export interface PluginProjectSnapshot {
121
+ readonly ref: ProjectRef;
122
+ readonly hostId: string;
123
+ readonly displayName: string;
124
+ readonly rootPath: string;
125
+ readonly kind: PluginWorkspaceSnapshot["projectKind"];
126
+ readonly iconRevision: string | null;
127
+ }
128
+ export interface PluginTerminalSnapshot {
129
+ readonly ref: TerminalRef;
130
+ readonly hostId: string;
131
+ readonly workspace: WorkspaceRef;
132
+ readonly title: string;
133
+ readonly isScript: boolean;
134
+ /** Null for terminals owned by workers started before timestamps were tracked. */
135
+ readonly createdAt: string | null;
136
+ }
92
137
  //# 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
@@ -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);
@@ -546,17 +561,18 @@ class AcpRuntime {
546
561
  });
547
562
  }
548
563
  async configure(changes) {
549
- const ordered = [];
564
+ const requested = [];
550
565
  if (changes.model !== undefined)
551
- ordered.push({ target: "model", value: changes.model });
566
+ requested.push({ target: "model", value: changes.model });
552
567
  if (changes.mode !== undefined)
553
- ordered.push({ target: "mode", value: changes.mode });
568
+ requested.push({ target: "mode", value: changes.mode });
554
569
  if (changes.thinkingOption !== undefined) {
555
- ordered.push({ target: "thinking", value: changes.thinkingOption });
570
+ requested.push({ target: "thinking", value: changes.thinkingOption });
556
571
  }
557
572
  for (const [id, value] of Object.entries(changes.settings ?? {})) {
558
- ordered.push({ target: "setting", id, value });
573
+ requested.push({ target: "setting", id, value });
559
574
  }
575
+ const ordered = this.inAgentOrder(requested);
560
576
  const previousModes = this.modes ? structuredClone(this.modes) : null;
561
577
  const previousOptions = structuredClone(this.configOptions);
562
578
  this.configTransaction = true;
@@ -620,16 +636,39 @@ class AcpRuntime {
620
636
  }
621
637
  }
622
638
  async applyInitialConfig(config) {
639
+ const requested = [];
623
640
  if (config.model)
624
- await this.applyConfigChange({ target: "model", value: config.model });
641
+ requested.push({ target: "model", value: config.model });
625
642
  if (config.mode)
626
- await this.applyConfigChange({ target: "mode", value: config.mode });
643
+ requested.push({ target: "mode", value: config.mode });
627
644
  if (config.thinkingOption) {
628
- await this.applyConfigChange({ target: "thinking", value: config.thinkingOption });
645
+ requested.push({ target: "thinking", value: config.thinkingOption });
629
646
  }
630
647
  for (const [id, value] of Object.entries(config.settings)) {
631
- await this.applyConfigChange({ target: "setting", id, value });
648
+ requested.push({ target: "setting", id, value });
632
649
  }
650
+ for (const change of this.inAgentOrder(requested))
651
+ await this.applyConfigChange(change);
652
+ }
653
+ // One option can reset another: choosing an fx provider also selects that provider's saved
654
+ // model, so a model applied first would be lost. Agents list the option that decides first.
655
+ inAgentOrder(changes) {
656
+ const position = (change) => {
657
+ const configId = this.configIdFor(change);
658
+ const index = this.configOptions.findIndex((option) => option.id === configId);
659
+ return index === -1 ? this.configOptions.length : index;
660
+ };
661
+ return changes.toSorted((left, right) => position(left) - position(right));
662
+ }
663
+ configIdFor(change) {
664
+ if (change.target === "setting")
665
+ return change.id;
666
+ if (change.target === "model")
667
+ return modelOption(this.configOptions)?.id;
668
+ if (change.target === "thinking") {
669
+ return this.configOptions.find((option) => option.category === "thought_level")?.id;
670
+ }
671
+ return this.configOptions.find((option) => option.category === "mode")?.id;
633
672
  }
634
673
  async applyConfigChange(change) {
635
674
  const access = this.configAccess();
@@ -652,14 +691,7 @@ class AcpRuntime {
652
691
  this.modes = { ...this.modes, currentModeId: change.value };
653
692
  return;
654
693
  }
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;
694
+ const configId = this.configIdFor(change);
663
695
  if (!configId) {
664
696
  throw new Error(`ACP session does not expose ${change.target} configuration`);
665
697
  }
@@ -875,14 +907,16 @@ class AcpRuntime {
875
907
  return;
876
908
  }
877
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
+ };
878
916
  this.emit({
879
917
  type: "session.usage",
880
918
  sessionId: this.options.boundarySessionId,
881
- usage: {
882
- contextWindowUsedTokens: update.used,
883
- contextWindowMaxTokens: update.size,
884
- totalCostUsd: update.cost?.currency === "USD" ? update.cost.amount : undefined,
885
- },
919
+ usage: this.lastUsage,
886
920
  });
887
921
  return;
888
922
  }
@@ -1174,7 +1208,7 @@ function readNativeSessionId(persistence) {
1174
1208
  return typeof persistence.data.sessionId === "string" ? persistence.data.sessionId : null;
1175
1209
  }
1176
1210
  function toProviderConfigState(modes, options) {
1177
- const model = options.find((option) => option.category === "model");
1211
+ const model = modelOption(options);
1178
1212
  const thinking = options.find((option) => option.category === "thought_level");
1179
1213
  return {
1180
1214
  model: selectedValue(model),
@@ -1191,10 +1225,18 @@ function toProviderConfigState(modes, options) {
1191
1225
  label: option.label,
1192
1226
  })),
1193
1227
  settings: options
1194
- .filter((option) => option.category !== "model" && option.category !== "thought_level")
1228
+ .filter((option) => option !== model &&
1229
+ option.category !== "thought_level" &&
1230
+ !(modes && option.category === "mode"))
1195
1231
  .map(toProviderSetting),
1196
1232
  };
1197
1233
  }
1234
+ // ACP's category is a grouping hint, so one category can hold several controls. fx files its
1235
+ // provider first, then the model, Fast, and Ultrafast under "model".
1236
+ function modelOption(options) {
1237
+ const candidates = options.filter((option) => option.category === "model");
1238
+ return candidates.find((option) => option.id === "model") ?? candidates[0];
1239
+ }
1198
1240
  function toProviderCatalog(modes, options) {
1199
1241
  const state = toProviderConfigState(modes, options);
1200
1242
  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,10 @@ export interface PluginHookAgent {
64
66
  provider: string;
65
67
  cwd: string;
66
68
  title: string | null;
69
+ /** A helper hidden from tabs, lists and attention. Fixed at creation. */
70
+ readonly background: boolean;
71
+ /** Data plugins stored on the agent. Paseo never reads a key. */
72
+ metadata: Record<string, JsonValue>;
67
73
  }
68
74
  export interface PluginSessionOpenRequest {
69
75
  agentId: string;
@@ -73,7 +79,10 @@ export interface PluginSessionOpenRequest {
73
79
  reason: "create" | "resume" | "refresh" | "import";
74
80
  purpose: "interactive" | "history";
75
81
  readonly title: string | null;
82
+ /** A helper hidden from tabs, lists and attention. Fixed at creation. */
83
+ readonly background: boolean;
76
84
  readonly labels: Readonly<Record<string, string>>;
85
+ readonly metadata: Readonly<Record<string, JsonValue>>;
77
86
  tools: AgentToolDefinition[];
78
87
  env: Record<string, string>;
79
88
  mcpServers: NonNullable<AgentSessionConfig["mcpServers"]>;
@@ -136,14 +145,23 @@ export interface PluginHookRequests {
136
145
  "agent.create.before": {
137
146
  config: AgentSessionConfig;
138
147
  env?: Record<string, string>;
148
+ /** Stored on the new agent. Always present in the payload; return it changed to change it. */
149
+ metadata?: Record<string, JsonValue>;
139
150
  };
140
151
  "agent.open.before": PluginSessionOpenRequest;
141
152
  "workspace.create.before": Omit<WorkspaceCreateRequest, "type" | "requestId">;
142
153
  }
154
+ /** What a hook may return. An omitted `metadata` stays as it was. */
155
+ type PluginHookRequestResults = Omit<PluginHookRequests, "agent.open.before"> & {
156
+ "agent.open.before": Omit<PluginSessionOpenRequest, "metadata" | "background"> & {
157
+ readonly background?: boolean;
158
+ metadata?: Readonly<Record<string, JsonValue>>;
159
+ };
160
+ };
143
161
  export type PluginHooks = {
144
162
  [Name in keyof PluginHookRequests]: {
145
163
  request: PluginHookRequests[Name];
146
- result: PluginHookRequests[Name];
164
+ result: PluginHookRequestResults[Name];
147
165
  };
148
166
  } & {
149
167
  [Name in keyof PluginHookEvents]: {
@@ -180,7 +198,7 @@ export interface PluginLifecycleRegistration {
180
198
  /** @deprecated Use addHook with the renamed hook. Removed after 2027-04-30. */
181
199
  before<Name extends keyof PluginBeforeRequests>(name: Name, handler: (input: {
182
200
  request: PluginBeforeRequests[Name];
183
- }, context: PluginHookContext) => PluginBeforeRequests[Name] | void | Promise<PluginBeforeRequests[Name] | void>): () => void;
201
+ }, context: PluginHookContext) => PluginBeforeResults[Name] | void | Promise<PluginBeforeResults[Name] | void>): () => void;
184
202
  }
185
203
  /** @internal Lifecycle policy shared by the daemon and plugin process. */
186
204
  export declare const pluginHookRegistry: {
@@ -249,6 +267,9 @@ export type PluginLifecycleEvents = {
249
267
  export type PluginBeforeRequests = {
250
268
  [Name in keyof typeof legacyRequests]: PluginHookRequests[(typeof legacyRequests)[Name]];
251
269
  };
270
+ type PluginBeforeResults = {
271
+ [Name in keyof typeof legacyRequests]: PluginHookRequestResults[(typeof legacyRequests)[Name]];
272
+ };
252
273
  /** @internal SDK adapter for the daemon's hook registry. */
253
274
  export declare function createLifecycleRegistration(register: (name: keyof PluginHooks, handler: (input: never, context: PluginHookContext) => unknown) => () => void): PluginLifecycleRegistration;
254
275
  export {};
@@ -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>;