@gpambrozio/paseo-skills 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -7,6 +7,29 @@ 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.3.0] — 2026-09-26
+
+### Changed
+
+- **The Skills pill opens a popover above the composer instead of a new tab.** It lists the same
+  skills the Skills tab does, with the same search. Pick one to see a short summary of it, type any
+  arguments and press **Invoke** — it is sent exactly as it is from the tab, and the popover closes
+  so you can watch the agent start. **← All skills** goes back to the list, and **Open tab** at the
+  top right opens the full Skills tab as the pill used to, where the whole skill is shown. The pill
+  still shows how many skills there are.
+
+## [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/README.md

@@ -49,9 +49,10 @@ plugin.
 
 ## Use
 
-Press the **Skills** pill above an agent's composer — its badge counts what the panel will list.
-The Command Center reaches the same panel: focus a workspace tab holding an agent, press ⌘K, and
-pick **Skills**.
+Press the **Skills** pill above an agent's composer — its badge counts what it will list. It opens
+a popover over the composer with the agent's skills: pick one to read it and invoke it with
+arguments, or press **Open tab** at its top right for the full Skills panel. The Command Center
+reaches the same panel: focus a workspace tab holding an agent, press ⌘K, and pick **Skills**.
 
 ## Demo
 
@@ -87,7 +88,9 @@ A failed reload stays failed; Paseo does not restore the previous code.
 | `server/resolve/skill-entry.ts`     | Entry types, skill id construction, first-wins dedupe.      |
 | `server/resolve/frontmatter.ts`     | `SKILL.md` frontmatter parsing.                             |
 | `server/resolve/reported.ts`        | Splits session-reported entries discovery did not find.     |
-| `client/panel.tsx`                  | The panel: list, search, detail, invoke.                    |
+| `client/browser.tsx`                | List, search, detail, invoke — drawn by the panel and the popover. |
+| `client/panel.tsx`                  | The panel: the browser as a whole tab.                      |
+| `client/popover.tsx`                | The pill's popover: the browser, plus a button to the panel. |
 | `client/pill.tsx`                   | The composer pill and the registration loop that owns it.   |
 | `client/skills-query.tsx`           | The `skills.list` query the panel and the pill share.       |
 

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;
+  };
+}