@getpaseo/plugin 0.17.0 → 0.17.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.
@@ -245,7 +245,7 @@ async function openSession(input, state) {
245
245
  onRetired: () => retireSession(state, input.sessionId),
246
246
  });
247
247
  try {
248
- const capabilities = await runtime.open(input, state.capabilities);
248
+ const capabilities = await runtime.open(input, state.capabilities, state.isClosed);
249
249
  if (state.isClosed()) {
250
250
  await runtime.closeSession();
251
251
  return;
@@ -282,6 +282,7 @@ class AcpRuntime {
282
282
  let stream;
283
283
  let closeConnector = async () => { };
284
284
  let whenConnectorClosed = () => null;
285
+ let onPartialWireRead = null;
285
286
  if (options.options.command) {
286
287
  // COMPAT(pluginProviderLaunch): added in v0.10.0, remove after 2027-03-29 once plugin host floor >= v0.10.0.
287
288
  // Standalone callers and older hosts do not send a daemon-resolved launch.
@@ -298,7 +299,8 @@ class AcpRuntime {
298
299
  spawnFailure = new Promise((_resolve, reject) => child.once("error", reject));
299
300
  child.stderr.on("data", () => undefined);
300
301
  const output = Writable.toWeb(child.stdin);
301
- const input = Readable.toWeb(child.stdout);
302
+ const rawInput = Readable.toWeb(child.stdout);
303
+ const input = observePartialWireReads(rawInput, () => onPartialWireRead?.());
302
304
  stream = ndJsonStream(output, input);
303
305
  }
304
306
  else {
@@ -308,6 +310,7 @@ class AcpRuntime {
308
310
  whenConnectorClosed = owned.whenClosed;
309
311
  }
310
312
  const runtime = new AcpRuntime(stream, child, closeConnector, whenConnectorClosed, options);
313
+ onPartialWireRead = () => runtime.notePartialWireRead();
311
314
  try {
312
315
  const initialize = withTimeout(runtime.call(runtime.connection.initialize({
313
316
  protocolVersion: PROTOCOL_VERSION,
@@ -355,12 +358,14 @@ class AcpRuntime {
355
358
  * Once ready, suppress late replay rows until the first prompt.
356
359
  */
357
360
  this.replayWindow = null;
358
- this.lastLoadUpdateAt = 0;
361
+ this.lastLoadHistoryAt = 0;
362
+ this.lastPartialWireAt = 0;
359
363
  this.closing = false;
360
364
  this.closePromise = null;
361
365
  this.deferredRetirement = null;
362
366
  this.deferredFinalized = false;
363
367
  this.processFailed = false;
368
+ this.processFailureMessage = null;
364
369
  this.configTransaction = false;
365
370
  this.stagedTransformerConfig = null;
366
371
  this.notificationLane = Promise.resolve();
@@ -388,6 +393,7 @@ class AcpRuntime {
388
393
  child?.on("error", (error) => {
389
394
  const message = describeError(error);
390
395
  this.processFailed = true;
396
+ this.processFailureMessage = message;
391
397
  this.settlePendingWork(message);
392
398
  if (this.closing || !this.nativeSessionId)
393
399
  return;
@@ -402,6 +408,7 @@ class AcpRuntime {
402
408
  return;
403
409
  const message = `ACP process exited (${signal ?? code ?? "unknown"})`;
404
410
  this.processFailed = true;
411
+ this.processFailureMessage = message;
405
412
  this.settlePendingWork(message);
406
413
  this.emit({
407
414
  type: "session.runtime_failed",
@@ -410,7 +417,7 @@ class AcpRuntime {
410
417
  });
411
418
  });
412
419
  }
413
- async open(input, connectionCapabilities) {
420
+ async open(input, connectionCapabilities, isConnectionClosed) {
414
421
  const mcpServers = toAcpMcpServers(input.config);
415
422
  this.mcpServerNames = mcpServers.map((server) => server.name);
416
423
  let nativeSessionId = readNativeSessionId(input.persistence);
@@ -475,15 +482,21 @@ class AcpRuntime {
475
482
  cwd: input.config.cwd,
476
483
  });
477
484
  this.emitConfig();
485
+ await this.finishSessionOpen(isConnectionClosed);
486
+ return sessionCapabilities;
487
+ }
488
+ async finishSessionOpen(isConnectionClosed) {
478
489
  if (this.options.options.acpOptions?.waitForInitialCommands) {
479
490
  await this.waitForInitialCommands();
480
491
  }
481
492
  const quietPeriod = this.options.options.acpOptions?.loadReplayQuietPeriodMs;
482
493
  if (this.replayWindow && quietPeriod && quietPeriod > 0) {
483
- await this.waitForLoadReplay(quietPeriod);
494
+ await this.waitForLoadReplay(quietPeriod, isConnectionClosed);
484
495
  this.replayWindow = "skip";
485
496
  }
486
- return sessionCapabilities;
497
+ if (this.processFailed && !isConnectionClosed()) {
498
+ throw new Error(this.processFailureMessage ?? "ACP process exited during session open");
499
+ }
487
500
  }
488
501
  async discover(cwd) {
489
502
  if (cwd === undefined && this.options.options.acpOptions?.workspaceOnlyCatalog) {
@@ -1044,15 +1057,12 @@ class AcpRuntime {
1044
1057
  sessionUpdate(notification, wireSeq) {
1045
1058
  if (notification.sessionId !== this.nativeSessionId)
1046
1059
  return;
1047
- if (this.replayWindow)
1048
- this.lastLoadUpdateAt = performance.now();
1060
+ if (this.replayWindow && isReplayHistoryUpdate(notification.update)) {
1061
+ this.lastLoadHistoryAt = performance.now();
1062
+ }
1049
1063
  if (this.replayWindow === "skip") {
1050
- const update = notification.update;
1051
- if (update.sessionUpdate === "available_commands_update" ||
1052
- update.sessionUpdate === "config_option_update" ||
1053
- update.sessionUpdate === "current_mode_update" ||
1054
- update.sessionUpdate === "usage_update") {
1055
- this.reduceStateUpdate(update, wireSeq);
1064
+ if (isSessionStateUpdate(notification.update)) {
1065
+ this.reduceStateUpdate(notification.update, wireSeq);
1056
1066
  }
1057
1067
  return;
1058
1068
  }
@@ -1384,6 +1394,7 @@ class AcpRuntime {
1384
1394
  return;
1385
1395
  const message = "ACP transport closed unexpectedly";
1386
1396
  this.processFailed = true;
1397
+ this.processFailureMessage = message;
1387
1398
  this.settlePendingWork(message);
1388
1399
  if (!this.nativeSessionId)
1389
1400
  return;
@@ -1672,19 +1683,72 @@ class AcpRuntime {
1672
1683
  this.commandWaiter = null;
1673
1684
  });
1674
1685
  }
1675
- async waitForLoadReplay(quietPeriod) {
1686
+ notePartialWireRead() {
1687
+ if (this.replayWindow)
1688
+ this.lastPartialWireAt = performance.now();
1689
+ }
1690
+ // An agent that streams history after its session/load response sends no end marker,
1691
+ // so the history ends once a quiet period passes without a history update.
1692
+ async waitForLoadReplay(quietPeriod, isConnectionClosed) {
1676
1693
  const start = performance.now();
1677
- const deadline = start + 5 * quietPeriod;
1678
- while (!this.closing && !this.processFailed) {
1679
- const idleAt = Math.max(start, this.lastLoadUpdateAt) + quietPeriod;
1680
- const remaining = Math.min(deadline, idleAt) - performance.now();
1681
- if (remaining <= 0)
1682
- return;
1683
- await new Promise((resolve) => setTimeout(resolve, remaining));
1694
+ while (!this.closing && !this.processFailed && !isConnectionClosed()) {
1695
+ const lastActivityAt = Math.max(start, this.lastLoadHistoryAt, this.lastPartialWireAt);
1696
+ const remaining = lastActivityAt + quietPeriod - performance.now();
1697
+ // A stalled event loop reaches the quiet period with history still unread in the pipe.
1698
+ // setImmediate lets the loop read pending input once before the silence is trusted.
1699
+ await new Promise((resolve) => {
1700
+ if (remaining > 0)
1701
+ setTimeout(resolve, remaining);
1702
+ else
1703
+ setImmediate(resolve);
1704
+ });
1684
1705
  await this.notificationLane;
1706
+ if (remaining <= 0 &&
1707
+ Math.max(start, this.lastLoadHistoryAt, this.lastPartialWireAt) === lastActivityAt) {
1708
+ return;
1709
+ }
1685
1710
  }
1686
1711
  }
1687
1712
  }
1713
+ function observePartialWireReads(input, onPartialRead) {
1714
+ let incompleteLine = false;
1715
+ return input.pipeThrough(new TransformStream({
1716
+ transform(chunk, controller) {
1717
+ const wasIncomplete = incompleteLine;
1718
+ incompleteLine = hasTrailingIncompleteLine(chunk, incompleteLine);
1719
+ if (wasIncomplete || incompleteLine)
1720
+ onPartialRead();
1721
+ controller.enqueue(chunk);
1722
+ },
1723
+ }));
1724
+ }
1725
+ function hasTrailingIncompleteLine(chunk, incompleteLine) {
1726
+ const newline = chunk.lastIndexOf(0x0a);
1727
+ const start = newline === -1 ? 0 : newline + 1;
1728
+ if (newline !== -1)
1729
+ incompleteLine = false;
1730
+ for (let index = start; index < chunk.length; index += 1) {
1731
+ const byte = chunk[index];
1732
+ if (byte !== 0x20 && byte !== 0x09 && byte !== 0x0d)
1733
+ return true;
1734
+ }
1735
+ return incompleteLine;
1736
+ }
1737
+ function isReplayHistoryUpdate(update) {
1738
+ return (update.sessionUpdate === "user_message_chunk" ||
1739
+ update.sessionUpdate === "agent_message_chunk" ||
1740
+ update.sessionUpdate === "agent_thought_chunk" ||
1741
+ update.sessionUpdate === "tool_call" ||
1742
+ update.sessionUpdate === "tool_call_update" ||
1743
+ update.sessionUpdate === "plan" ||
1744
+ update.sessionUpdate === "compaction_update");
1745
+ }
1746
+ function isSessionStateUpdate(update) {
1747
+ return (update.sessionUpdate === "available_commands_update" ||
1748
+ update.sessionUpdate === "config_option_update" ||
1749
+ update.sessionUpdate === "current_mode_update" ||
1750
+ update.sessionUpdate === "usage_update");
1751
+ }
1688
1752
  function routeIncomingMessages(stream, receiveVendor, observeWire) {
1689
1753
  const clientMethods = new Set(Object.values(CLIENT_METHODS));
1690
1754
  return {
@@ -49,7 +49,10 @@ export interface AcpOptions {
49
49
  workspaceOnlyCatalog?: boolean;
50
50
  waitForInitialCommands?: boolean;
51
51
  initialCommandsTimeoutMs?: number;
52
- /** Allow delayed session/load updates before publishing the session as ready. */
52
+ /**
53
+ * For an agent that streams history after its session/load response: publish the session
54
+ * as ready once this long passes without a history update.
55
+ */
53
56
  loadReplayQuietPeriodMs?: number;
54
57
  /**
55
58
  * Keep a turn open after `end_turn` while qualifying tool calls are still running,
@@ -1,7 +1,7 @@
1
1
  import type { JsonValue } from "@getpaseo/protocol/agent-types";
2
2
  import { z } from "zod";
3
3
  export declare const PROVIDER_PROTOCOL_VERSION: 1;
4
- export declare const PROVIDER_CAPABILITIES: readonly ["prompt.message", "prompt.command", "prompt.image", "prompt.output_schema", "prompt.steer", "session.can_stop_runtime", "session.archive", "session.configure", "session.list", "session.persistence", "session.revert.both", "session.revert.conversation", "session.revert.files", "session.subsession", "session.unarchive", "permission", "permission.tool_policy", "timeline.plugin"];
4
+ export declare const PROVIDER_CAPABILITIES: readonly ["prompt.message", "prompt.command", "prompt.image", "prompt.output_schema", "prompt.steer", "session.can_stop_runtime", "session.archive", "session.configure", "session.list", "session.metrics", "session.persistence", "session.revert.both", "session.revert.conversation", "session.revert.files", "session.subsession", "session.unarchive", "permission", "permission.tool_policy", "timeline.plugin"];
5
5
  export type ProviderCapability = (typeof PROVIDER_CAPABILITIES)[number];
6
6
  export interface ProviderRegistration {
7
7
  /** Activate only while agents.providers contains this provider ID, independently of enabled. */
@@ -16,6 +16,8 @@ export interface ProviderRegistration {
16
16
  description?: string;
17
17
  /** Plugin-directory-relative path to a self-contained SVG file. */
18
18
  icon?: string;
19
+ /** http(s) page that helps users set up and troubleshoot the provider. Paseo opens it. */
20
+ docsUrl?: string;
19
21
  /** How users install the provider's CLI and which version they run. Every member is optional. */
20
22
  installation?: ProviderInstallation;
21
23
  connect(request: ProviderConnectRequest): Promise<ProviderConnection>;
@@ -514,6 +516,16 @@ export interface ProviderUsage {
514
516
  contextWindowMaxTokens?: number;
515
517
  contextWindowUsedTokens?: number;
516
518
  }
519
+ /**
520
+ * One row of provider-owned detail about a session or a turn. Format `value` for
521
+ * reading: Paseo shows it as given.
522
+ */
523
+ export interface ProviderMetric {
524
+ label: string;
525
+ value: string;
526
+ /** Colors the value. Omit it for an ordinary value. */
527
+ tone?: "default" | "ok" | "warning" | "danger";
528
+ }
517
529
  interface ProviderTimelineIdentity {
518
530
  id: string;
519
531
  revertToken?: JsonValue;
@@ -730,11 +742,21 @@ export type ProviderEvent = {
730
742
  turnId: string;
731
743
  state: "started" | "completed" | "failed" | "canceled";
732
744
  error?: ProviderError;
745
+ /** Shown on the turn's footer. Read when `state` is `"completed"`. */
746
+ metrics?: readonly ProviderMetric[];
733
747
  } | {
734
748
  type: "session.usage";
735
749
  sessionId: string;
736
750
  turnId?: string;
737
751
  usage: ProviderUsage;
752
+ } | {
753
+ type: "session.metrics";
754
+ sessionId: string;
755
+ /**
756
+ * Replaces the metrics shown for the session. An empty list clears them. Publish only when
757
+ * `session.metrics` was negotiated: a Paseo that does not offer it rejects this event.
758
+ */
759
+ metrics: readonly ProviderMetric[];
738
760
  } | {
739
761
  type: "session.config";
740
762
  sessionId: string;
@@ -10,6 +10,7 @@ export const PROVIDER_CAPABILITIES = [
10
10
  "session.archive",
11
11
  "session.configure",
12
12
  "session.list",
13
+ "session.metrics",
13
14
  "session.persistence",
14
15
  "session.revert.both",
15
16
  "session.revert.conversation",
@@ -539,6 +540,13 @@ const usageSchema = z
539
540
  contextWindowUsedTokens: z.number().optional(),
540
541
  })
541
542
  .strip();
543
+ const metricSchema = z
544
+ .object({
545
+ label: z.string(),
546
+ value: z.string(),
547
+ tone: z.enum(["default", "ok", "warning", "danger"]).optional(),
548
+ })
549
+ .strip();
542
550
  const worktreeCommandSchema = z
543
551
  .object({
544
552
  index: z.number().int().positive(),
@@ -852,6 +860,7 @@ export const ProviderEventSchema = z.discriminatedUnion("type", [
852
860
  turnId: idSchema,
853
861
  state: z.enum(["started", "completed", "failed", "canceled"]),
854
862
  error: providerErrorSchema.optional(),
863
+ metrics: z.array(metricSchema).optional(),
855
864
  })
856
865
  .strip(),
857
866
  z
@@ -862,6 +871,13 @@ export const ProviderEventSchema = z.discriminatedUnion("type", [
862
871
  usage: usageSchema,
863
872
  })
864
873
  .strip(),
874
+ z
875
+ .object({
876
+ type: z.literal("session.metrics"),
877
+ sessionId: idSchema,
878
+ metrics: z.array(metricSchema),
879
+ })
880
+ .strip(),
865
881
  z
866
882
  .object({ type: z.literal("session.config"), sessionId: idSchema, config: configStateSchema })
867
883
  .strip(),
@@ -68,6 +68,8 @@ export interface UsageAccount {
68
68
  label?: string;
69
69
  /** Harness owning this login, e.g. Codex, OpenCode, Pi or OMP. */
70
70
  harness?: string;
71
+ /** Provider ID associated with this login, used as a hint for default visibility. */
72
+ provider?: string;
71
73
  /** Store locator, opaque to the daemon. */
72
74
  input: JsonValue;
73
75
  }
@@ -96,6 +98,8 @@ export interface UsageSourceRegistration {
96
98
  icon?: string;
97
99
  /** Provider whose resolved launch is needed for discovery. */
98
100
  provider?: string;
101
+ /** Provider IDs associated with this source, used as a hint for default visibility. */
102
+ providers?: readonly string[];
99
103
  input: ZodType;
100
104
  /** Accounts for this scope only. The same key in any scope identifies the same account. */
101
105
  discover(scope: UsageScope): Promise<UsageAccount[]>;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@getpaseo/plugin",
3
- "version": "0.17.0",
3
+ "version": "0.17.2",
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",
82
- "@getpaseo/protocol": "0.17.0",
81
+ "@getpaseo/client": "0.17.2",
82
+ "@getpaseo/protocol": "0.17.2",
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",
93
- "@getpaseo/protocol": "0.17.0",
92
+ "@getpaseo/client": "0.17.2",
93
+ "@getpaseo/protocol": "0.17.2",
94
94
  "react": ">=19.1.0 <20",
95
95
  "react-native": ">=0.81.5",
96
96
  "zod": "^4.4.3"