@getpaseo/plugin 0.17.0-beta.1 → 0.17.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -51,6 +51,18 @@ export interface AcpOptions {
51
51
  initialCommandsTimeoutMs?: number;
52
52
  /** Allow delayed session/load updates before publishing the session as ready. */
53
53
  loadReplayQuietPeriodMs?: number;
54
+ /**
55
+ * Keep a turn open after `end_turn` while qualifying tool calls are still running,
56
+ * settling once those tools finish and the agent finishes its follow-up reply.
57
+ */
58
+ deferTurnOnRunningTools?: {
59
+ /** Delay after `usage_update` closes a follow-up reply before settling. Defaults to 500ms. */
60
+ settleDelayMs?: number;
61
+ /** Quiet limit after qualifying tools finish if no reply settles via `usage_update`. Defaults to 120_000ms. */
62
+ quietLimitMs?: number;
63
+ /** Predicate deciding whether an open tool call keeps the turn open. Defaults to all running tools. */
64
+ keepsTurnOpen?: (toolCall: AcpToolCallSnapshot) => boolean;
65
+ };
54
66
  /** An unattended mode that approves ACP allow-once requests in the specified native mode. */
55
67
  autoAcceptMode?: {
56
68
  mode: Omit<ProviderMode, "isUnattended">;
@@ -65,11 +77,15 @@ export interface AcpConfigAccess {
65
77
  read(): Promise<Readonly<Record<string, JsonValue>>>;
66
78
  set(id: string, value: JsonValue): Promise<void>;
67
79
  }
80
+ /** Sends an ACP extension request to the agent. Rejects with the agent's JSON-RPC error. */
81
+ export type AcpRequest = (method: string, params: JsonValue) => Promise<JsonValue>;
68
82
  export interface AcpDiscoveryContext extends AcpContext {
69
83
  config: AcpConfigAccess;
84
+ request: AcpRequest;
70
85
  }
71
86
  export interface AcpConfigureContext extends AcpContext {
72
87
  config: AcpConfigAccess;
88
+ request: AcpRequest;
73
89
  catalog(): ProviderCatalog;
74
90
  apply(change: AcpConfigChange): Promise<void>;
75
91
  }
@@ -123,11 +139,17 @@ export interface AcpTransformer {
123
139
  };
124
140
  discover?(catalog: ProviderCatalog, context: AcpDiscoveryContext): Promise<ProviderCatalog> | ProviderCatalog;
125
141
  configure?(change: AcpConfigChange, context: AcpConfigureContext): Promise<"handled" | "pass">;
142
+ /** Rewrites every session config snapshot before Paseo sees it. */
143
+ config?(state: ProviderConfigState, context: AcpContext): ProviderConfigState;
144
+ /** Rewrites each advertised ACP slash command before Paseo sees it. */
145
+ command?(command: ProviderCommand, context: AcpContext): ProviderCommand;
126
146
  notification?(notification: {
127
147
  method: string;
128
148
  params: JsonValue;
129
149
  }, context: AcpContext): AcpVendorUpdate | readonly AcpVendorUpdate[] | null;
130
- toolCall?(toolCall: AcpToolCallSnapshot, context: AcpContext): AcpToolCallSnapshot;
150
+ toolCall?(toolCall: AcpToolCallSnapshot, context: AcpContext & {
151
+ mcpServerNames?: readonly string[];
152
+ }): AcpToolCallSnapshot;
131
153
  }
132
154
  export declare function runAcpProvider(options: RunAcpProviderOptions): ProviderRegistration;
133
155
  export {};
@@ -5,6 +5,7 @@ import type { PluginCleanup } from "../contracts.js";
5
5
  import type { ProviderRegistration } from "./provider.js";
6
6
  import type { UsageSourceRegistration } from "./usage.js";
7
7
  import type { PluginLifecycleRegistration } from "./lifecycle.js";
8
+ import type { WorktreeManagerRegistration } from "./worktree.js";
8
9
  export interface PluginHandlerContext {
9
10
  paseo: PaseoApi;
10
11
  }
@@ -43,6 +44,7 @@ export interface PluginServerContext extends PluginLifecycleRegistration {
43
44
  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;
44
45
  registerProvider(provider: ProviderRegistration): void;
45
46
  registerUsageSource(source: UsageSourceRegistration): void;
47
+ registerWorktreeManager(manager: WorktreeManagerRegistration): () => void;
46
48
  }
47
49
  export type PluginServerContribution = (server: PluginServerContext) => PluginCleanup;
48
50
  //# sourceMappingURL=contracts.d.ts.map
@@ -4,4 +4,5 @@ export type { PluginHooks, PluginHookEvents, PluginHookRequests, PluginHookPaylo
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";
7
+ export type { PluginWorktreeContext, PluginWorktreeCreateInput, PluginWorktreeCreateResult, PluginWorktreeRemoveRequest, PluginWorktreeRemoveResult, PluginWorktreeRestoreTarget, PluginWorktreeRestoreRequest, PluginWorktreeRestoreResult, WorktreeManagerRegistration, } from "./worktree.js";
7
8
  //# sourceMappingURL=index.d.ts.map
@@ -30,6 +30,8 @@ export type PluginWorktreeCreateRequest = {
30
30
  } & ({
31
31
  kind: "branch-off";
32
32
  baseRef: string;
33
+ /** Where the new branch starts when that is not `baseRef`, such as a fork's head. */
34
+ readonly startPoint?: string;
33
35
  } | {
34
36
  kind: "checkout-branch";
35
37
  } | {
@@ -16,8 +16,88 @@ export interface ProviderRegistration {
16
16
  description?: string;
17
17
  /** Plugin-directory-relative path to a self-contained SVG file. */
18
18
  icon?: string;
19
+ /** How users install the provider's CLI and which version they run. Every member is optional. */
20
+ installation?: ProviderInstallation;
19
21
  connect(request: ProviderConnectRequest): Promise<ProviderConnection>;
20
22
  }
23
+ export interface ProviderInstallation {
24
+ /** http(s) page that explains how to install the provider. Paseo opens it; it never installs. */
25
+ installUrl?: string;
26
+ /** http(s) page that explains how to update the provider. */
27
+ updateUrl?: string;
28
+ /** Report whether the provider is installed and which version. Runs only when a user asks. */
29
+ inspect?(context: ProviderInstallationContext): Promise<ProviderInspection>;
30
+ /**
31
+ * Report whether a newer version than `installedVersion` is available. The provider decides how
32
+ * to find out and what counts as newer; Paseo shows the result as written. Return `unknown` when
33
+ * it cannot tell. Runs only when a user asks, never before a session, and only after `inspect`
34
+ * reports the provider installed. Paseo reuses the answer while `inspect` reports the same
35
+ * version.
36
+ */
37
+ checkForUpdates?(context: ProviderUpdateCheckContext): Promise<ProviderUpdateCheck>;
38
+ /**
39
+ * Update the provider, usually by running its CLI's own updater. Paseo shows everything passed
40
+ * to `report` while it runs, then the returned message. A throw is a failure with its message.
41
+ * Runs only when a user asks. Paseo sets no deadline; `signal` aborts when the daemon stops.
42
+ */
43
+ update?(context: ProviderUpdateContext): Promise<ProviderUpdateResult>;
44
+ }
45
+ export interface ProviderUpdateCheckContext extends ProviderInstallationContext {
46
+ /**
47
+ * The version `inspect` reported, as written. Absent when `inspect` reported none or the
48
+ * provider declares no `inspect`.
49
+ */
50
+ installedVersion?: string;
51
+ }
52
+ export interface ProviderUpdateContext extends ProviderInstallationContext {
53
+ /** Shows output to the user as it happens, unchanged and in order. */
54
+ report(event: ProviderUpdateReport): void;
55
+ }
56
+ export declare const ProviderUpdateReportSchema: z.ZodObject<{
57
+ type: z.ZodEnum<{
58
+ message: "message";
59
+ stdout: "stdout";
60
+ stderr: "stderr";
61
+ }>;
62
+ text: z.ZodString;
63
+ }, z.core.$strip>;
64
+ export type ProviderUpdateReport = z.infer<typeof ProviderUpdateReportSchema>;
65
+ export declare const ProviderUpdateResultSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
66
+ status: z.ZodLiteral<"succeeded">;
67
+ message: z.ZodOptional<z.ZodString>;
68
+ }, z.core.$strip>, z.ZodObject<{
69
+ status: z.ZodLiteral<"failed">;
70
+ message: z.ZodString;
71
+ }, z.core.$strip>], "status">;
72
+ export type ProviderUpdateResult = z.infer<typeof ProviderUpdateResultSchema>;
73
+ export interface ProviderInstallationContext {
74
+ /** The launch a session would use. Absent when the provider declares no `command`. */
75
+ launch?: ProviderInstallationLaunch;
76
+ /** Aborted when Paseo stops waiting for the result. */
77
+ signal: AbortSignal;
78
+ }
79
+ export interface ProviderInstallationLaunch extends ProviderLaunch {
80
+ /** False when the executable was not found; `command` is then the configured command as written. */
81
+ resolved: boolean;
82
+ }
83
+ export declare const ProviderInspectionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
84
+ status: z.ZodLiteral<"installed">;
85
+ version: z.ZodOptional<z.ZodString>;
86
+ }, z.core.$strip>, z.ZodObject<{
87
+ status: z.ZodLiteral<"not_installed">;
88
+ }, z.core.$strip>], "status">;
89
+ export type ProviderInspection = z.infer<typeof ProviderInspectionSchema>;
90
+ export declare const ProviderUpdateCheckSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
91
+ status: z.ZodLiteral<"current">;
92
+ }, z.core.$strip>, z.ZodObject<{
93
+ status: z.ZodLiteral<"available">;
94
+ versions: z.ZodOptional<z.ZodArray<z.ZodString>>;
95
+ message: z.ZodOptional<z.ZodString>;
96
+ }, z.core.$strip>, z.ZodObject<{
97
+ status: z.ZodLiteral<"unknown">;
98
+ message: z.ZodOptional<z.ZodString>;
99
+ }, z.core.$strip>], "status">;
100
+ export type ProviderUpdateCheck = z.infer<typeof ProviderUpdateCheckSchema>;
21
101
  export type ProviderCatalogOptions = {
22
102
  scope: "global";
23
103
  force?: boolean;
@@ -382,6 +462,7 @@ export interface ProviderCommand {
382
462
  name: string;
383
463
  description: string;
384
464
  argumentHint?: string;
465
+ kind?: "command" | "skill";
385
466
  }
386
467
  export interface ProviderError {
387
468
  message: string;
@@ -20,6 +20,31 @@ export const PROVIDER_CAPABILITIES = [
20
20
  "permission.tool_policy",
21
21
  "timeline.plugin",
22
22
  ];
23
+ export const ProviderUpdateReportSchema = z
24
+ .object({ type: z.enum(["stdout", "stderr", "message"]), text: z.string() })
25
+ .strip();
26
+ export const ProviderUpdateResultSchema = z.discriminatedUnion("status", [
27
+ /** `message` is shown as written, such as which version is now installed. */
28
+ z.object({ status: z.literal("succeeded"), message: z.string().optional() }).strip(),
29
+ z.object({ status: z.literal("failed"), message: z.string() }).strip(),
30
+ ]);
31
+ export const ProviderInspectionSchema = z.discriminatedUnion("status", [
32
+ /** `version` is shown as written and passed to `checkForUpdates`; Paseo does not parse it. */
33
+ z.object({ status: z.literal("installed"), version: z.string().optional() }).strip(),
34
+ z.object({ status: z.literal("not_installed") }).strip(),
35
+ ]);
36
+ export const ProviderUpdateCheckSchema = z.discriminatedUnion("status", [
37
+ z.object({ status: z.literal("current") }).strip(),
38
+ /** `versions` and `message` are shown as written; Paseo does not parse, sort or compare them. */
39
+ z
40
+ .object({
41
+ status: z.literal("available"),
42
+ versions: z.array(z.string()).optional(),
43
+ message: z.string().optional(),
44
+ })
45
+ .strip(),
46
+ z.object({ status: z.literal("unknown"), message: z.string().optional() }).strip(),
47
+ ]);
23
48
  export const ProviderLaunchSchema = z
24
49
  .object({
25
50
  /** Resolved executable path. */
@@ -497,7 +522,12 @@ const noticeSchema = z
497
522
  })
498
523
  .strip();
499
524
  const commandSchema = z
500
- .object({ name: idSchema, description: z.string(), argumentHint: z.string().optional() })
525
+ .object({
526
+ name: idSchema,
527
+ description: z.string(),
528
+ argumentHint: z.string().optional(),
529
+ kind: z.enum(["command", "skill"]).optional(),
530
+ })
501
531
  .strip();
502
532
  const usageSchema = z
503
533
  .object({
@@ -13,6 +13,8 @@ export interface UsageWindow {
13
13
  usedPct?: number | null;
14
14
  remainingPct?: number | null;
15
15
  resetsAt?: string | null;
16
+ /** Full length of the quota window when known. */
17
+ durationSeconds?: number;
16
18
  runsOutAt?: string | null;
17
19
  shortfallPct?: number | null;
18
20
  tone?: "default" | "ok" | "warning" | "danger";
@@ -48,6 +50,8 @@ export type UsageProblem = {
48
50
  export type UsageReport = {
49
51
  status: "available";
50
52
  planLabel?: string;
53
+ /** When the provider measured the quota, if the report returns a previous reading. */
54
+ observedAt?: string;
51
55
  windows: UsageWindow[];
52
56
  balances?: UsageBalance[];
53
57
  details?: UsageDetail[];
@@ -69,17 +73,29 @@ export interface UsageAccount {
69
73
  }
70
74
  export declare const UsageScopeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
71
75
  kind: z.ZodLiteral<"global">;
76
+ launch: z.ZodOptional<z.ZodObject<{
77
+ command: z.ZodString;
78
+ args: z.ZodArray<z.ZodString>;
79
+ env: z.ZodRecord<z.ZodString, z.ZodString>;
80
+ }, z.core.$strip>>;
72
81
  }, z.core.$strip>, z.ZodObject<{
73
82
  kind: z.ZodLiteral<"session">;
74
83
  provider: z.ZodString;
75
84
  model: z.ZodOptional<z.ZodString>;
76
85
  env: z.ZodRecord<z.ZodString, z.ZodString>;
86
+ launch: z.ZodOptional<z.ZodObject<{
87
+ command: z.ZodString;
88
+ args: z.ZodArray<z.ZodString>;
89
+ env: z.ZodRecord<z.ZodString, z.ZodString>;
90
+ }, z.core.$strip>>;
77
91
  }, z.core.$strip>], "kind">;
78
92
  export type UsageScope = z.infer<typeof UsageScopeSchema>;
79
93
  export interface UsageSourceRegistration {
80
94
  id: string;
81
95
  label: string;
82
96
  icon?: string;
97
+ /** Provider whose resolved launch is needed for discovery. */
98
+ provider?: string;
83
99
  input: ZodType;
84
100
  /** Accounts for this scope only. The same key in any scope identifies the same account. */
85
101
  discover(scope: UsageScope): Promise<UsageAccount[]>;
@@ -92,6 +108,7 @@ export declare function windowFromUsedPct(input: {
92
108
  shortLabel?: string;
93
109
  summary?: boolean;
94
110
  utilizationPct: number | null | undefined;
111
+ durationSeconds?: number;
95
112
  resetsAt?: string | null;
96
113
  tone?: UsageWindow["tone"];
97
114
  }): UsageWindow;
@@ -1,12 +1,14 @@
1
1
  import { createHash } from "node:crypto";
2
2
  import { z } from "zod";
3
+ import { ProviderLaunchSchema } from "./provider.js";
3
4
  export const UsageScopeSchema = z.discriminatedUnion("kind", [
4
- z.object({ kind: z.literal("global") }),
5
+ z.object({ kind: z.literal("global"), launch: ProviderLaunchSchema.optional() }),
5
6
  z.object({
6
7
  kind: z.literal("session"),
7
8
  provider: z.string(),
8
9
  model: z.string().optional(),
9
10
  env: z.record(z.string(), z.string()),
11
+ launch: ProviderLaunchSchema.optional(),
10
12
  }),
11
13
  ]);
12
14
  export function windowFromUsedPct(input) {
@@ -18,6 +20,8 @@ export function windowFromUsedPct(input) {
18
20
  remainingPct: usedPct === null ? null : Math.max(0, 100 - usedPct),
19
21
  resetsAt: input.resetsAt ?? null,
20
22
  };
23
+ if (input.durationSeconds !== undefined)
24
+ window.durationSeconds = input.durationSeconds;
21
25
  if (input.shortLabel !== undefined)
22
26
  window.shortLabel = input.shortLabel;
23
27
  if (input.summary)
@@ -32,10 +36,9 @@ export function windowFromUsedPct(input) {
32
36
  * Named API fields (weekly, monthly, etc.) use windowFromUsedPct instead.
33
37
  */
34
38
  export function windowFromReportedDuration(input) {
35
- const duration = input.durationSeconds;
36
- const name = duration !== null && Number.isFinite(duration) && duration > 0
37
- ? durationWindowName(duration)
38
- : input.unknown;
39
+ const reported = input.durationSeconds;
40
+ const duration = reported !== null && Number.isFinite(reported) && reported > 0 ? reported : undefined;
41
+ const name = duration === undefined ? input.unknown : durationWindowName(duration);
39
42
  const scope = input.scope;
40
43
  return windowFromUsedPct({
41
44
  id: scope ? `${scope.id}:${name.id}` : name.id,
@@ -44,6 +47,7 @@ export function windowFromReportedDuration(input) {
44
47
  ? `${scope.label}${name.shortLabel ? ` ${name.shortLabel}` : ""}`
45
48
  : name.shortLabel,
46
49
  utilizationPct: input.utilizationPct,
50
+ durationSeconds: duration,
47
51
  resetsAt: input.resetsAt,
48
52
  summary: input.summary,
49
53
  tone: input.tone,
@@ -0,0 +1,59 @@
1
+ import type { PluginHookContext, PluginWorktreeCreateRequest } from "./lifecycle.js";
2
+ /** Context passed to worktree manager callbacks. */
3
+ export type PluginWorktreeContext = PluginHookContext;
4
+ /** Resolved creation request handed to a worktree manager after `worktree.create.before`. */
5
+ export type PluginWorktreeCreateInput = PluginWorktreeCreateRequest & {
6
+ /** True when the worktree comes from an untrusted source such as a fork change request; skip repository-defined hooks. */
7
+ readonly untrusted: boolean;
8
+ /** Resolved remote head commit SHA for change-request checkouts when available. */
9
+ readonly headSha?: string;
10
+ };
11
+ /** Return `{ type: "created", path }` to claim creation, or `undefined` to decline. */
12
+ export interface PluginWorktreeCreateResult {
13
+ type: "created";
14
+ path: string;
15
+ }
16
+ export interface PluginWorktreeRemoveRequest {
17
+ readonly repoRoot: string | null;
18
+ readonly path: string;
19
+ readonly branch: string | null;
20
+ readonly reason: "archive" | "rollback";
21
+ readonly force: boolean;
22
+ /** True when the worktree came from an untrusted source such as a fork change request; skip repository-defined hooks. */
23
+ readonly untrusted: boolean;
24
+ }
25
+ /** Return `{ type: "removed" }` after removing the worktree, or `undefined` to fall back to Git. */
26
+ export interface PluginWorktreeRemoveResult {
27
+ type: "removed";
28
+ }
29
+ export type PluginWorktreeRestoreTarget = {
30
+ readonly type: "branch";
31
+ readonly branch: string;
32
+ } | {
33
+ readonly type: "commit";
34
+ readonly commit: string;
35
+ } | {
36
+ readonly type: "from-base";
37
+ readonly branch: string;
38
+ readonly baseRef: string;
39
+ };
40
+ export interface PluginWorktreeRestoreRequest {
41
+ readonly repoRoot: string;
42
+ /** Recorded path the worktree must be restored to. */
43
+ readonly path: string;
44
+ readonly target: PluginWorktreeRestoreTarget;
45
+ readonly baseRef: string | null;
46
+ /** True when the worktree came from an untrusted source such as a fork change request; skip repository-defined hooks. */
47
+ readonly untrusted: boolean;
48
+ }
49
+ /** Return `{ type: "restored", path }` after recreating the worktree, or `undefined` to fall back to Git. */
50
+ export interface PluginWorktreeRestoreResult {
51
+ type: "restored";
52
+ path: string;
53
+ }
54
+ export interface WorktreeManagerRegistration {
55
+ create(request: PluginWorktreeCreateInput, context: PluginWorktreeContext): Promise<PluginWorktreeCreateResult | void>;
56
+ remove?(request: PluginWorktreeRemoveRequest, context: PluginWorktreeContext): Promise<PluginWorktreeRemoveResult | void>;
57
+ restore?(request: PluginWorktreeRestoreRequest, context: PluginWorktreeContext): Promise<PluginWorktreeRestoreResult | void>;
58
+ }
59
+ //# sourceMappingURL=worktree.d.ts.map
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=worktree.js.map
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@getpaseo/plugin",
3
- "version": "0.17.0-beta.1",
3
+ "version": "0.17.0",
4
4
  "description": "Paseo plugin SDK package",
5
5
  "license": "Apache-2.0",
6
6
  "files": [
@@ -78,8 +78,8 @@
78
78
  "use-sync-external-store": "^1.6.0"
79
79
  },
80
80
  "devDependencies": {
81
- "@getpaseo/client": "0.17.0-beta.1",
82
- "@getpaseo/protocol": "0.17.0-beta.1",
81
+ "@getpaseo/client": "0.17.0",
82
+ "@getpaseo/protocol": "0.17.0",
83
83
  "@types/node": "^20.9.0",
84
84
  "@types/react": "~19.2.0",
85
85
  "react": "19.2.3",
@@ -89,8 +89,8 @@
89
89
  "zod": "^4.4.3"
90
90
  },
91
91
  "peerDependencies": {
92
- "@getpaseo/client": "0.17.0-beta.1",
93
- "@getpaseo/protocol": "0.17.0-beta.1",
92
+ "@getpaseo/client": "0.17.0",
93
+ "@getpaseo/protocol": "0.17.0",
94
94
  "react": ">=19.1.0 <20",
95
95
  "react-native": ">=0.81.5",
96
96
  "zod": "^4.4.3"