@omercnet/paseo-tell-agent 0.3.0 → 1.0.0

package/README.md

@@ -2,39 +2,37 @@
 
 Send a message from one Paseo agent to another agent or workspace on the same daemon host.
 
-## Install
+## Screenshots
 
-### Paseo 0.9.0-beta.1 or later
+Agent and workspace names are synthetic. Both PNGs were captured from an isolated Paseo test
+daemon at 2× pixel density after browser DevTools verified that no private organization names
+remained in the rendered page.
 
-Install the npm package:
+### Choose a target
 
-```bash
-paseo plugin install npm:@omercnet/paseo-tell-agent
-```
+![Tell Agent target picker](https://raw.githubusercontent.com/omercnet/paseo-plugins/main/tell-agent/docs/images/tell-agent-picker.png)
 
-Update an npm installation by its plugin ID:
+### Compose an instruction
 
-```bash
-paseo plugin update tell-agent
-```
+![Tell Agent instruction composer](https://raw.githubusercontent.com/omercnet/paseo-plugins/main/tell-agent/docs/images/tell-agent-compose.png)
 
-Paseo 0.9's reviewed update flow shows the current and proposed revisions before asking for approval. Add `--check` to preview without applying or `--yes` to skip the approval prompt. npm installation and this reviewed update behavior are not available in Paseo 0.8.
+## Install
 
-### Paseo 0.8.x
+### Paseo 0.9.0 or later
 
-The manifest remains compatible with Paseo 0.8. Install from the Git repository:
+Install the npm package:
 
 ```bash
-paseo plugin add omercnet/paseo-plugins:tell-agent
+paseo plugin install npm:@omercnet/paseo-tell-agent
 ```
 
-Or install a local checkout on the daemon host:
+Update an npm installation by its plugin ID:
 
 ```bash
-paseo plugin install /absolute/path/to/paseo-plugins/tell-agent
+paseo plugin update tell-agent
 ```
 
-Use `paseo plugin update tell-agent` to refresh a Git installation. After changing a local checkout, use `paseo plugin reload tell-agent`.
+Paseo 0.9's reviewed update flow shows the current and proposed revisions before asking for approval. Add `--check` to preview without applying or `--yes` to skip the approval prompt.
 
 ## Use
 

package/client/agents.ts

@@ -1,10 +1,25 @@
-import type { PaseoAgent, PaseoAgentListResult, PaseoApi } from "@getpaseo/client";
+import type { PluginClientContext } from "@getpaseo/plugin/client";
 
-export type AgentEntry = PaseoAgentListResult["entries"][number];
-type AgentSnapshot = PaseoAgent;
+type PaseoApi = PluginClientContext["paseo"];
+type PaseoAgentUpdate = Parameters<Parameters<PaseoApi["agents"]["subscribe"]>[0]>[0];
+type AgentSnapshot = Extract<PaseoAgentUpdate, { kind: "upsert" }>["agent"];
+export type AgentEntry = {
+  agent: AgentSnapshot;
+  project: {
+    projectName: string;
+    workspaceName?: string | null;
+    checkout: { isGit: boolean; currentBranch: string | null };
+  };
+};
+type PaseoAgentListResult = {
+  entries: AgentEntry[];
+  pageInfo: { hasMore: boolean; nextCursor: string | null };
+};
 
 export const AGENT_PAGE_LIMIT = 200;
 export const MAX_AGENT_PAGES = 10;
+const REOPEN_MIN_MS = 2_000;
+const REOPEN_MAX_MS = 60_000;
 
 export type AgentDirectoryPage = {
   entries: AgentEntry[];
@@ -26,6 +41,146 @@ export async function loadAgents(paseo: PaseoApi): Promise<AgentDirectoryPage> {
   return { entries, truncated: true };
 }
 
+/**
+ * Continues `loadAgents` from an observation's first page, to the same cap.
+ * Returns null once `current()` turns false, so a stale read is dropped.
+ */
+async function readRemainingPages(
+  paseo: PaseoApi,
+  first: PaseoAgentListResult,
+  signal: AbortSignal,
+  current: () => boolean,
+): Promise<AgentDirectoryPage | null> {
+  const entries = [...first.entries];
+  let cursor = first.pageInfo.hasMore ? (first.pageInfo.nextCursor ?? undefined) : undefined;
+  for (let page = 1; cursor; page += 1) {
+    if (page >= MAX_AGENT_PAGES) return { entries, truncated: true };
+    const result = await paseo.agents.list({
+      sort: [{ key: "updated_at", direction: "desc" }],
+      page: { limit: AGENT_PAGE_LIMIT, cursor },
+      signal,
+    });
+    if (!current()) return null;
+    entries.push(...result.entries);
+    cursor = result.pageInfo.hasMore ? (result.pageInfo.nextCursor ?? undefined) : undefined;
+  }
+  return { entries, truncated: false };
+}
+
+export type AgentDirectoryFollower = {
+  /**
+   * The directory as listed. `complete` means it holds every agent the host
+   * has, so anything missing is gone; otherwise apply it as upserts only.
+   */
+  snapshot(agents: AgentSnapshot[], complete: boolean): void;
+  upsert(agent: AgentSnapshot): void;
+  remove(agentId: string): void;
+};
+
+/**
+ * Keeps `follower` in step with the host's agents until the returned cleanup.
+ *
+ * `agents.subscribe()` only hears observations the same API instance opened,
+ * so this opens one with `list({ subscribe: {} })`. Its snapshot, the first
+ * page, arrives first and again after every reconnect; later pages are read
+ * plainly, and updates that land meanwhile win over what those pages say.
+ * Paseo releases an observation that fails, so it is reopened with backoff.
+ */
+export function followAgentDirectory(
+  paseo: PaseoApi,
+  follower: AgentDirectoryFollower,
+): () => void {
+  let stopped = false;
+  const apply = (update: PaseoAgentUpdate) => {
+    if (update.kind === "remove") follower.remove(update.agentId);
+    else follower.upsert(update.agent);
+  };
+
+  const lifetime = new AbortController();
+  let observation: { release(): Promise<void> } | null = null;
+  let reopenTimer: ReturnType<typeof setTimeout> | null = null;
+  let reopenDelay = REOPEN_MIN_MS;
+  /** Bumped per snapshot, so a reconnect abandons the paging of the one before. */
+  let generation = 0;
+  /** What updates said while the current snapshot's later pages were read. */
+  let landed: Map<string, AgentSnapshot | null> | null = null;
+
+  const applySnapshot = async (first: PaseoAgentListResult) => {
+    const current = ++generation;
+    const isCurrent = () => !stopped && generation === current;
+    const touched = new Map<string, AgentSnapshot | null>();
+    landed = touched;
+    let listed: AgentDirectoryPage | null;
+    try {
+      listed = await readRemainingPages(paseo, first, lifetime.signal, isCurrent);
+    } catch {
+      listed = { entries: [...first.entries], truncated: true };
+    }
+    if (!listed || !isCurrent()) return;
+    landed = null;
+    const agents = new Map(listed.entries.map((entry) => [entry.agent.id, entry.agent]));
+    for (const [agentId, agent] of touched) {
+      if (agent) agents.set(agentId, agent);
+      else agents.delete(agentId);
+    }
+    follower.snapshot([...agents.values()], !listed.truncated);
+  };
+
+  const reopen = () => {
+    observation = null;
+    generation += 1;
+    landed = null;
+    if (stopped || reopenTimer !== null) return;
+    reopenTimer = setTimeout(() => {
+      reopenTimer = null;
+      open();
+    }, reopenDelay);
+    reopenDelay = Math.min(reopenDelay * 2, REOPEN_MAX_MS);
+  };
+
+  const open = () => {
+    paseo.agents
+      .list({
+        sort: [{ key: "updated_at", direction: "desc" }],
+        page: { limit: AGENT_PAGE_LIMIT },
+        subscribe: {},
+        signal: lifetime.signal,
+      })
+      .then(({ subscription }) => {
+        if (stopped) {
+          void subscription.release().catch(() => undefined);
+          return;
+        }
+        observation = subscription;
+        subscription.subscribe({
+          snapshot: (first) => {
+            reopenDelay = REOPEN_MIN_MS;
+            void applySnapshot(first);
+          },
+          update: (message) => {
+            if (stopped || message.type !== "agent_update") return;
+            const update = message.payload;
+            if (update.kind === "remove") landed?.set(update.agentId, null);
+            else landed?.set(update.agent.id, update.agent);
+            apply(update);
+          },
+          error: reopen,
+        });
+      })
+      .catch(reopen);
+  };
+
+  open();
+  return () => {
+    stopped = true;
+    lifetime.abort();
+    if (reopenTimer !== null) clearTimeout(reopenTimer);
+    reopenTimer = null;
+    void observation?.release().catch(() => undefined);
+    observation = null;
+  };
+}
+
 export function title(entry: AgentEntry): string {
   const explicit = entry.agent.title?.trim();
   return explicit && explicit.length > 0 ? explicit : entry.agent.id.slice(0, 7);

package/client/message-agent.tsx

@@ -11,6 +11,7 @@ import { Pressable, ScrollView, Text, TextInput, View } from "react-native";
 import {
   AGENT_PAGE_LIMIT,
   type AgentEntry,
+  followAgentDirectory,
   loadAgents,
   MAX_AGENT_PAGES,
   placement,
@@ -328,20 +329,18 @@ export function contributeAgentMessaging(client: PluginClientContext) {
     pills.set(agent.id, { workspaceId: next.workspaceId, remove: pill.remove });
   }
 
-  const unsubscribe = client.paseo.agents.subscribe((update) => {
-    if (update.kind === "remove") {
-      removePill(update.agentId);
-      return;
-    }
-    syncAgent(update.agent);
-  });
-
-  void loadAgents(client.paseo)
-    .then(({ entries }) => {
+  const unsubscribe = followAgentDirectory(client.paseo, {
+    snapshot(agents, complete) {
       if (stopped) return;
-      for (const { agent } of entries) syncAgent(agent);
-    })
-    .catch(() => undefined);
+      if (complete) {
+        const listed = new Set(agents.map((agent) => agent.id));
+        for (const agentId of [...pills.keys()]) if (!listed.has(agentId)) removePill(agentId);
+      }
+      for (const agent of agents) syncAgent(agent);
+    },
+    upsert: syncAgent,
+    remove: removePill,
+  });
 
   const removeTellCommand = client.addSlashCommand({
     name: "tell",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omercnet/paseo-tell-agent",
-  "version": "0.3.0",
+  "version": "1.0.0",
   "type": "module",
   "description": "Send messages to agents in other workspaces on the same Paseo host.",
   "license": "MIT",
@@ -16,7 +16,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "packageManager": "npm@11.19.1",
+  "packageManager": "bun@1.4.2",
   "engines": {
     "node": ">=24"
   },
@@ -43,11 +43,11 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.10",
-    "@getpaseo/client": "0.9.0-beta.1",
-    "@getpaseo/plugin": "0.9.0-beta.1",
-    "@getpaseo/protocol": "0.9.0-beta.1",
+    "@getpaseo/client": "0.9.0",
+    "@getpaseo/plugin": "0.9.0",
+    "@getpaseo/protocol": "0.9.0",
     "@tanstack/react-query": "^5.102.3",
-    "@types/node": "^24.5.2",
+    "@types/node": "^24.10.1",
     "@types/react": "^19.2.18",
     "react": "19.1.0",
     "react-native": "0.81.5",

package/paseo-plugin.json

@@ -1,4 +1,5 @@
 {
   "id": "tell-agent",
-  "requirements": { "paseo": "^0.8.0 || ^0.9.0-beta.1" }
+  "description": "Send messages to agents in other workspaces on the same Paseo host.",
+  "requirements": { "paseo": "^0.9.0" }
 }