@gpambrozio/paseo-skills 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -7,6 +7,18 @@ follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Every version
 as `@gpambrozio/paseo-skills` and tagged here, so a version is something to install and a line to
 read before you move.
 
+## [0.2.1] — 2026-09-23
+
+### Fixed
+
+- **The Skills pill reaches agents created after the plugin loaded.** Paseo 0.9 changed
+  `agents.subscribe()` to a local listener that no longer asks the daemon for agent data, so the
+  pill only covered agents that existed at load; a new session had none until the plugin was
+  reloaded. On 0.9 clients the pill now opens its own agent observation
+  (`agents.list({ subscribe: {} })`) and follows its snapshots and updates; an 0.8 client keeps the
+  previous listen-and-seed behaviour, because sending `subscribe` from there would replace the
+  app's own agent subscription.
+
 ## [0.2.0] — 2026-09-22
 
 ### Added

package/client/agents.ts

@@ -0,0 +1,104 @@
+import type { PluginClientContext } from "@getpaseo/plugin/client";
+
+/**
+ * Following the host's agents across Paseo 0.8 and 0.9 clients.
+ *
+ * Since 0.9, `agents.subscribe()` only adds a local listener to observations
+ * that the same API instance opened with `agents.list({ subscribe: {} })`; on
+ * its own it never hears anything. The observation delivers a snapshot first
+ * and again after every reconnect, then the updates in between.
+ *
+ * A 0.8 client has no observations, and must not send `subscribe` either: the
+ * daemon keeps one agents subscription slot per legacy connection, last query
+ * wins, so a plugin asking for one would replace the app's own. The choice is
+ * therefore made before any request, from the API's shape.
+ */
+
+type Paseo = PluginClientContext["paseo"];
+type AgentListOptions = NonNullable<Parameters<Paseo["agents"]["list"]>[0]>;
+export type AgentList = Awaited<ReturnType<Paseo["agents"]["list"]>>;
+export type AgentUpdate = Parameters<Parameters<Paseo["agents"]["subscribe"]>[0]>[0];
+
+/** The 0.9 observation handle; the 0.8 typings this plugin builds against predate it. */
+type AgentObservation = {
+  subscribe(observer: {
+    snapshot(snapshot: AgentList): void;
+    update(message: { type: string; payload?: unknown }): void;
+    error?(error: unknown): void;
+  }): () => void;
+  release(): Promise<void>;
+};
+type ObservingAgents = {
+  list(
+    options: AgentListOptions & { subscribe: {}; signal: AbortSignal },
+  ): Promise<AgentList & { subscription?: AgentObservation }>;
+};
+
+const RETRY_MIN_MS = 2_000;
+const RETRY_MAX_MS = 60_000;
+
+/** `observeEvents` shipped together with observations (0.9.0-beta.1). */
+export function canObserveAgents(paseo: Paseo): boolean {
+  return typeof (paseo as { observeEvents?: unknown }).observeEvents === "function";
+}
+
+/**
+ * On a 0.9 client, keeps an agent observation open for the caller's lifetime:
+ * `snapshot` replaces the caller's view, `update` applies one change. Paseo
+ * releases an observation that fails (a re-request after reconnect, say), so it
+ * is reopened with backoff rather than left silent. On a 0.8 client it runs
+ * `legacy` instead, the pre-0.9 listener and read. Returns the cleanup.
+ */
+export function followAgents(
+  paseo: Paseo,
+  handlers: { snapshot(list: AgentList): void; update(update: AgentUpdate): void },
+  legacy: () => () => void,
+): () => void {
+  if (!canObserveAgents(paseo)) return legacy();
+
+  const lifetime = new AbortController();
+  let observation: AgentObservation | null = null;
+  let retry: ReturnType<typeof setTimeout> | null = null;
+  let retryDelay = RETRY_MIN_MS;
+
+  function reopen(error: unknown): void {
+    observation = null;
+    if (lifetime.signal.aborted || retry !== null) return;
+    console.warn("skills: agent observation failed; reopening", error);
+    retry = setTimeout(() => {
+      retry = null;
+      open();
+    }, retryDelay);
+    retryDelay = Math.min(retryDelay * 2, RETRY_MAX_MS);
+  }
+
+  function open(): void {
+    (paseo.agents as unknown as ObservingAgents)
+      .list({ subscribe: {}, signal: lifetime.signal })
+      .then(({ subscription }) => {
+        if (lifetime.signal.aborted) return;
+        if (subscription === undefined) throw new Error("the host returned no agent observation");
+        observation = subscription;
+        subscription.subscribe({
+          snapshot(list) {
+            retryDelay = RETRY_MIN_MS;
+            handlers.snapshot(list);
+          },
+          update(message) {
+            if (message.type === "agent_update") handlers.update(message.payload as AgentUpdate);
+          },
+          error: reopen,
+        });
+      })
+      .catch(reopen);
+  }
+
+  open();
+  return () => {
+    lifetime.abort();
+    if (retry !== null) clearTimeout(retry);
+    retry = null;
+    void observation?.release().catch(() => undefined);
+    observation = null;
+  };
+}

package/client/pill.tsx

@@ -6,6 +6,7 @@ import {
 import { Icon } from "@getpaseo/plugin/client/react-native";
 import { useEffect } from "react";
 
+import { followAgents, type AgentList, type AgentUpdate } from "./agents";
 import { countEntries, useSkillsQuery } from "./skills-query";
 
 /** What the pill reads before the count is known, and the accessible name throughout. */
@@ -49,13 +50,18 @@ function createPillIcon(agentId: string, pill: { current?: PluginButtonRegistrat
  * stream for the rest, and removes every registration on teardown.
  */
 export function contributePills(client: PluginClientContext) {
-  const pills = new Map<string, PluginButtonRegistration>();
+  const pills = new Map<string, { workspaceId: string; registration: PluginButtonRegistration }>();
+  let stopped = false;
 
   function addPill(agentId: string, workspaceId: string) {
+    if (stopped) return;
     // Agent updates fire on every turn of every agent. Nothing in the pill
     // depends on the snapshot, so re-registering would only unmount the icon
-    // and refire its query — and Paseo rejects a duplicate id outright.
-    if (pills.has(agentId)) return;
+    // and refire its query — and Paseo rejects a duplicate id outright. Only a
+    // move to another workspace needs a new registration, since it is baked in.
+    const current = pills.get(agentId);
+    if (current?.workspaceId === workspaceId) return;
+    if (current) removePill(agentId);
 
     // The icon needs the registration that is about to be created from it, so
     // it reaches the registration through this box rather than through a prop.
@@ -76,41 +82,65 @@ export function contributePills(client: PluginClientContext) {
         },
       },
     });
-    pills.set(agentId, pill.current);
+    pills.set(agentId, { workspaceId, registration: pill.current });
   }
 
   function removePill(agentId: string) {
-    pills.get(agentId)?.remove();
+    pills.get(agentId)?.registration.remove();
     pills.delete(agentId);
   }
 
-  const unsubscribe = client.paseo.agents.subscribe((update) => {
+  function applyUpdate(update: AgentUpdate) {
     if (update.kind === "remove") {
       removePill(update.agentId);
       return;
     }
     const { id, workspaceId } = update.agent;
     if (workspaceId) addPill(id, workspaceId);
-  });
+  }
 
-  // `subscribe` only reports change. Without this seed, an agent that was
-  // already sitting idle when the app connected would have no pill until it
-  // next did something.
-  client.paseo.agents
-    .list()
-    .then((result) => {
-      // A `for…of` body would capture the loop binding, not the entry.
-      result.entries.forEach(({ agent }) => {
-        if (agent.workspaceId) addPill(agent.id, agent.workspaceId);
-      });
-    })
-    .catch((error: unknown) => {
-      console.error("skills: could not seed composer pills", error);
+  // A snapshot arrives first and again after every reconnect, and replaces the
+  // set: agents it no longer lists lose their pill, unchanged ones keep theirs.
+  function applySnapshot(list: AgentList) {
+    if (stopped) return;
+    const listed = new Map<string, string>();
+    list.entries.forEach(({ agent }) => {
+      if (agent.workspaceId) listed.set(agent.id, agent.workspaceId);
+    });
+    [...pills.keys()].forEach((agentId) => {
+      if (!listed.has(agentId)) removePill(agentId);
     });
+    listed.forEach((workspaceId, agentId) => addPill(agentId, workspaceId));
+  }
+
+  const unfollow = followAgents(
+    client.paseo,
+    { snapshot: applySnapshot, update: applyUpdate },
+    () => {
+      const unsubscribe = client.paseo.agents.subscribe(applyUpdate);
+
+      // `subscribe` only reports change. Without this seed, an agent that was
+      // already sitting idle when the app connected would have no pill until it
+      // next did something.
+      client.paseo.agents
+        .list()
+        .then((result) => {
+          // A `for…of` body would capture the loop binding, not the entry.
+          result.entries.forEach(({ agent }) => {
+            if (agent.workspaceId) addPill(agent.id, agent.workspaceId);
+          });
+        })
+        .catch((error: unknown) => {
+          console.error("skills: could not seed composer pills", error);
+        });
+      return unsubscribe;
+    },
+  );
 
   return () => {
-    unsubscribe();
-    pills.forEach((pill) => pill.remove());
+    stopped = true;
+    unfollow();
+    pills.forEach((pill) => pill.registration.remove());
     pills.clear();
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gpambrozio/paseo-skills",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Paseo plugin: lists the skills an agent can use, shows where each comes from, renders its SKILL.md, and invokes it",
   "license": "MIT",
   "homepage": "https://github.com/gpambrozio/paseo-plugins/tree/main/skills",