@getpaseo/plugin 0.14.0-beta.2 → 0.15.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.
@@ -1,6 +1,6 @@
1
1
  export type { UsageSourceRegistration, UsageReport, UsageWindow, UsageBalance, UsageDetail, } from "./usage.js";
2
2
  export type { PluginHandlerContext, PluginServerContext, PluginServerContribution, PluginSettings, PluginSettingsState, } from "./contracts.js";
3
- export type { PluginHookContext, PluginHookWorkspace, PluginHookAgent, PluginSessionOpenRequest, PluginTurnOutcome, PluginLifecycleEvents, PluginBeforeRequests, PluginLifecycleRegistration, } from "./lifecycle.js";
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";
6
6
  export type { AgentToolDefinition, AgentToolResult, AgentToolContext } from "./agent-tools.js";
@@ -13,6 +13,50 @@ export interface PluginHookWorkspace {
13
13
  name: string | null;
14
14
  archivedAt: string | null;
15
15
  }
16
+ export interface PluginHookWorktree {
17
+ path: string;
18
+ branch: string;
19
+ sourceCheckout: string;
20
+ }
21
+ /** Resolved creation options before Git fetches refs or chooses a unique branch name. */
22
+ export type PluginWorktreeCreateRequest = {
23
+ readonly repoRoot: string;
24
+ readonly sourceCheckout: string;
25
+ branch: string;
26
+ slug: string;
27
+ path: string;
28
+ } & ({
29
+ kind: "branch-off";
30
+ baseRef: string;
31
+ } | {
32
+ kind: "checkout-branch";
33
+ } | {
34
+ kind: "checkout-change-request";
35
+ baseRef: string;
36
+ forge: string;
37
+ changeRequestNumber: number;
38
+ headRef: string;
39
+ headRepositoryOwner?: string;
40
+ headRepository?: string;
41
+ checkoutRefs?: {
42
+ remoteName?: string;
43
+ remoteRef: string;
44
+ }[];
45
+ pushRemoteUrl?: string;
46
+ trackOriginHead?: boolean;
47
+ } | {
48
+ kind: "checkout-github-pr";
49
+ baseRef: string;
50
+ githubPrNumber: number;
51
+ headRef: string;
52
+ headRepositoryOwner?: string;
53
+ checkoutRefs?: {
54
+ remoteName?: string;
55
+ remoteRef: string;
56
+ }[];
57
+ pushRemoteUrl?: string;
58
+ trackOriginHead?: boolean;
59
+ });
16
60
  export interface PluginHookAgent {
17
61
  id: string;
18
62
  workspaceId: string | null;
@@ -46,12 +90,12 @@ export type PluginTurnOutcome = {
46
90
  kind: "canceled";
47
91
  reason: string;
48
92
  };
49
- export interface PluginLifecycleEvents {
50
- "agent.turn_started": {
93
+ export interface PluginHookEvents {
94
+ "agent.turn.before": {
51
95
  agent: PluginHookAgent;
52
96
  turnId: string | null;
53
97
  };
54
- "agent.turn_ended": {
98
+ "agent.turn.after": {
55
99
  agent: PluginHookAgent;
56
100
  turnId: string | null;
57
101
  outcome: PluginTurnOutcome;
@@ -61,44 +105,151 @@ export interface PluginLifecycleEvents {
61
105
  */
62
106
  timeline: readonly AgentTimelineItem[];
63
107
  };
64
- "agent.permission_requested": {
108
+ "agent.permission.before": {
65
109
  agent: PluginHookAgent;
66
110
  request: AgentPermissionRequest;
67
111
  };
68
- "agent.permission_resolved": {
112
+ "agent.permission.after": {
69
113
  agent: PluginHookAgent;
70
114
  requestId: string;
71
115
  resolution: AgentPermissionResponse;
72
116
  };
73
- "agent.archived": {
117
+ "agent.archive.after": {
74
118
  agent: PluginHookAgent;
75
119
  archivedAt: string;
76
120
  };
77
- "agent.created": {
121
+ "agent.create.after": {
78
122
  agent: PluginHookAgent;
79
123
  };
80
- "agent.closed": {
124
+ "agent.close.after": {
81
125
  agent: PluginHookAgent;
82
126
  };
83
- "workspace.created": {
127
+ "workspace.create.after": {
84
128
  workspace: PluginHookWorkspace;
85
129
  };
86
- "workspace.archived": {
130
+ "workspace.archive.after": {
87
131
  workspace: PluginHookWorkspace;
88
132
  };
89
133
  }
90
- export interface PluginBeforeRequests {
91
- "agent.create": {
134
+ export interface PluginHookRequests {
135
+ "worktree.create.before": PluginWorktreeCreateRequest;
136
+ "agent.create.before": {
92
137
  config: AgentSessionConfig;
93
138
  env?: Record<string, string>;
94
139
  };
95
- "agent.session_open": PluginSessionOpenRequest;
96
- "workspace.create": Omit<WorkspaceCreateRequest, "type" | "requestId">;
140
+ "agent.open.before": PluginSessionOpenRequest;
141
+ "workspace.create.before": Omit<WorkspaceCreateRequest, "type" | "requestId">;
97
142
  }
143
+ export type PluginHooks = {
144
+ [Name in keyof PluginHookRequests]: {
145
+ request: PluginHookRequests[Name];
146
+ result: PluginHookRequests[Name];
147
+ };
148
+ } & {
149
+ [Name in keyof PluginHookEvents]: {
150
+ payload: PluginHookEvents[Name];
151
+ };
152
+ } & {
153
+ "worktree.create.after": {
154
+ payload: {
155
+ worktree: PluginHookWorktree;
156
+ };
157
+ };
158
+ };
159
+ export type PluginHookPayload<Name extends keyof PluginHooks> = {
160
+ [Key in keyof PluginHooks]: PluginHooks[Key] extends {
161
+ request: infer Request;
162
+ } ? {
163
+ request: Request;
164
+ } : PluginHooks[Key] extends {
165
+ payload: infer Payload;
166
+ } ? Payload : never;
167
+ }[Name];
168
+ export type PluginHookResult<Name extends keyof PluginHooks> = {
169
+ [Key in keyof PluginHooks]: PluginHooks[Key] extends {
170
+ result: infer Result;
171
+ } ? Result | void : void;
172
+ }[Name];
173
+ type HookHandlers = {
174
+ [Name in keyof PluginHooks]: (payload: PluginHookPayload<Name>, context: PluginHookContext) => Promise<PluginHookResult<Name>>;
175
+ };
98
176
  export interface PluginLifecycleRegistration {
177
+ addHook<Name extends keyof PluginHooks>(name: Name, handler: HookHandlers[Name]): () => void;
178
+ /** @deprecated Use addHook with the renamed hook. Removed after 2027-04-30. */
99
179
  on<Name extends keyof PluginLifecycleEvents>(name: Name, handler: (event: PluginLifecycleEvents[Name], context: PluginHookContext) => void | Promise<void>): () => void;
180
+ /** @deprecated Use addHook with the renamed hook. Removed after 2027-04-30. */
100
181
  before<Name extends keyof PluginBeforeRequests>(name: Name, handler: (input: {
101
182
  request: PluginBeforeRequests[Name];
102
183
  }, context: PluginHookContext) => PluginBeforeRequests[Name] | void | Promise<PluginBeforeRequests[Name] | void>): () => void;
103
184
  }
185
+ /** @internal Lifecycle policy shared by the daemon and plugin process. */
186
+ export declare const pluginHookRegistry: {
187
+ readonly "workspace.create.before": {
188
+ readonly waits: true;
189
+ };
190
+ readonly "workspace.create.after": {
191
+ readonly waits: false;
192
+ };
193
+ readonly "workspace.archive.after": {
194
+ readonly waits: false;
195
+ };
196
+ readonly "worktree.create.before": {
197
+ readonly waits: true;
198
+ };
199
+ readonly "worktree.create.after": {
200
+ readonly waits: true;
201
+ };
202
+ readonly "agent.create.before": {
203
+ readonly waits: true;
204
+ };
205
+ readonly "agent.create.after": {
206
+ readonly waits: false;
207
+ };
208
+ readonly "agent.open.before": {
209
+ readonly waits: true;
210
+ };
211
+ readonly "agent.close.after": {
212
+ readonly waits: false;
213
+ };
214
+ readonly "agent.archive.after": {
215
+ readonly waits: false;
216
+ };
217
+ readonly "agent.turn.before": {
218
+ readonly waits: false;
219
+ };
220
+ readonly "agent.turn.after": {
221
+ readonly waits: false;
222
+ };
223
+ readonly "agent.permission.before": {
224
+ readonly waits: false;
225
+ };
226
+ readonly "agent.permission.after": {
227
+ readonly waits: false;
228
+ };
229
+ };
230
+ declare const legacyEvents: {
231
+ readonly "workspace.created": "workspace.create.after";
232
+ readonly "workspace.archived": "workspace.archive.after";
233
+ readonly "agent.created": "agent.create.after";
234
+ readonly "agent.closed": "agent.close.after";
235
+ readonly "agent.archived": "agent.archive.after";
236
+ readonly "agent.turn_started": "agent.turn.before";
237
+ readonly "agent.turn_ended": "agent.turn.after";
238
+ readonly "agent.permission_requested": "agent.permission.before";
239
+ readonly "agent.permission_resolved": "agent.permission.after";
240
+ };
241
+ declare const legacyRequests: {
242
+ readonly "workspace.create": "workspace.create.before";
243
+ readonly "agent.create": "agent.create.before";
244
+ readonly "agent.session_open": "agent.open.before";
245
+ };
246
+ export type PluginLifecycleEvents = {
247
+ [Name in keyof typeof legacyEvents]: PluginHookEvents[(typeof legacyEvents)[Name]];
248
+ };
249
+ export type PluginBeforeRequests = {
250
+ [Name in keyof typeof legacyRequests]: PluginHookRequests[(typeof legacyRequests)[Name]];
251
+ };
252
+ /** @internal SDK adapter for the daemon's hook registry. */
253
+ export declare function createLifecycleRegistration(register: (name: keyof PluginHooks, handler: (input: never, context: PluginHookContext) => unknown) => () => void): PluginLifecycleRegistration;
254
+ export {};
104
255
  //# sourceMappingURL=lifecycle.d.ts.map
@@ -1,2 +1,56 @@
1
- export {};
1
+ /** @internal Lifecycle policy shared by the daemon and plugin process. */
2
+ export const pluginHookRegistry = {
3
+ "workspace.create.before": { waits: true },
4
+ "workspace.create.after": { waits: false },
5
+ "workspace.archive.after": { waits: false },
6
+ "worktree.create.before": { waits: true },
7
+ "worktree.create.after": { waits: true },
8
+ "agent.create.before": { waits: true },
9
+ "agent.create.after": { waits: false },
10
+ "agent.open.before": { waits: true },
11
+ "agent.close.after": { waits: false },
12
+ "agent.archive.after": { waits: false },
13
+ "agent.turn.before": { waits: false },
14
+ "agent.turn.after": { waits: false },
15
+ "agent.permission.before": { waits: false },
16
+ "agent.permission.after": { waits: false },
17
+ };
18
+ // COMPAT(pluginHookNames): added in v0.14, remove after 2027-04-30
19
+ const legacyEvents = {
20
+ "workspace.created": "workspace.create.after",
21
+ "workspace.archived": "workspace.archive.after",
22
+ "agent.created": "agent.create.after",
23
+ "agent.closed": "agent.close.after",
24
+ "agent.archived": "agent.archive.after",
25
+ "agent.turn_started": "agent.turn.before",
26
+ "agent.turn_ended": "agent.turn.after",
27
+ "agent.permission_requested": "agent.permission.before",
28
+ "agent.permission_resolved": "agent.permission.after",
29
+ };
30
+ const legacyRequests = {
31
+ "workspace.create": "workspace.create.before",
32
+ "agent.create": "agent.create.before",
33
+ "agent.session_open": "agent.open.before",
34
+ };
35
+ /** @internal SDK adapter for the daemon's hook registry. */
36
+ export function createLifecycleRegistration(register) {
37
+ const names = new Set(Object.keys(pluginHookRegistry));
38
+ return {
39
+ addHook(name, handler) {
40
+ if (!names.has(name))
41
+ throw new Error(`Unknown lifecycle hook: ${name}`);
42
+ return register(name, handler);
43
+ },
44
+ on(name, handler) {
45
+ if (!Object.hasOwn(legacyEvents, name))
46
+ throw new Error(`Unknown lifecycle event: ${name}`);
47
+ return register(legacyEvents[name], handler);
48
+ },
49
+ before(name, handler) {
50
+ if (!Object.hasOwn(legacyRequests, name))
51
+ throw new Error(`Unknown before hook: ${name}`);
52
+ return register(legacyRequests[name], handler);
53
+ },
54
+ };
55
+ }
2
56
  //# sourceMappingURL=lifecycle.js.map
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@getpaseo/plugin",
3
- "version": "0.14.0-beta.2",
3
+ "version": "0.15.0-beta.1",
4
4
  "description": "Paseo plugin SDK package",
5
5
  "files": [
6
6
  "dist",
@@ -52,6 +52,11 @@
52
52
  "types": "./dist/client/index.d.ts",
53
53
  "source": "./src/client/index.ts",
54
54
  "default": "./dist/client/index.js"
55
+ },
56
+ "./internal/lifecycle": {
57
+ "types": "./dist/server/lifecycle.d.ts",
58
+ "source": "./src/server/lifecycle.ts",
59
+ "default": "./dist/server/lifecycle.js"
55
60
  }
56
61
  },
57
62
  "publishConfig": {
@@ -72,8 +77,8 @@
72
77
  "use-sync-external-store": "^1.6.0"
73
78
  },
74
79
  "devDependencies": {
75
- "@getpaseo/client": "0.14.0-beta.2",
76
- "@getpaseo/protocol": "0.14.0-beta.2",
80
+ "@getpaseo/client": "0.15.0-beta.1",
81
+ "@getpaseo/protocol": "0.15.0-beta.1",
77
82
  "@types/node": "^20.9.0",
78
83
  "@types/react": "~19.2.0",
79
84
  "react": "19.2.3",
@@ -83,8 +88,8 @@
83
88
  "zod": "^4.4.3"
84
89
  },
85
90
  "peerDependencies": {
86
- "@getpaseo/client": "0.14.0-beta.2",
87
- "@getpaseo/protocol": "0.14.0-beta.2",
91
+ "@getpaseo/client": "0.15.0-beta.1",
92
+ "@getpaseo/protocol": "0.15.0-beta.1",
88
93
  "react": ">=19.1.0 <20",
89
94
  "react-native": ">=0.81.5",
90
95
  "zod": "^4.4.3"