@omercnet/paseo-tell-agent 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Omer Cohen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/client/agents.ts

@@ -0,0 +1,69 @@
+import type { PaseoAgent, PaseoAgentListResult, PaseoApi } from "@getpaseo/client";
+
+export type AgentEntry = PaseoAgentListResult["entries"][number];
+type AgentSnapshot = PaseoAgent;
+
+export const AGENT_PAGE_LIMIT = 200;
+export const MAX_AGENT_PAGES = 10;
+
+export type AgentDirectoryPage = {
+  entries: AgentEntry[];
+  truncated: boolean;
+};
+
+export async function loadAgents(paseo: PaseoApi): Promise<AgentDirectoryPage> {
+  const entries: AgentEntry[] = [];
+  let cursor: string | undefined;
+  for (let page = 0; page < MAX_AGENT_PAGES; page += 1) {
+    const result = await paseo.agents.list({
+      sort: [{ key: "updated_at", direction: "desc" }],
+      page: { limit: AGENT_PAGE_LIMIT, ...(cursor ? { cursor } : {}) },
+    });
+    entries.push(...result.entries);
+    cursor = result.pageInfo.hasMore ? (result.pageInfo.nextCursor ?? undefined) : undefined;
+    if (!cursor) return { entries, truncated: false };
+  }
+  return { entries, truncated: true };
+}
+
+export function title(entry: AgentEntry): string {
+  const explicit = entry.agent.title?.trim();
+  return explicit && explicit.length > 0 ? explicit : entry.agent.id.slice(0, 7);
+}
+
+export function placement(entry: AgentEntry): string {
+  const { project } = entry;
+  const workspace = project.workspaceName?.trim();
+  const scope =
+    workspace && workspace !== project.projectName
+      ? `${project.projectName} / ${workspace}`
+      : project.projectName;
+  const branch = project.checkout.isGit ? project.checkout.currentBranch : null;
+  return branch ? `${scope} · ${branch}` : scope;
+}
+
+export function stateLabel(agent: AgentSnapshot): string {
+  const permissionCount = agent.pendingPermissions.length;
+  if (permissionCount > 0) {
+    return permissionCount === 1 ? "permission" : `${permissionCount} permissions`;
+  }
+  if (agent.status === "error") return "error";
+  if (agent.requiresAttention) return agent.attentionReason ?? "attention";
+  return agent.status === "initializing" ? "starting" : agent.status;
+}
+
+export function matches(entry: AgentEntry, needle: string): boolean {
+  if (needle.length === 0) return true;
+  return [
+    entry.agent.title ?? "",
+    entry.agent.id,
+    entry.agent.provider,
+    entry.agent.model ?? "",
+    entry.agent.cwd,
+    entry.project.projectName,
+    entry.project.workspaceName ?? "",
+  ]
+    .join(" ")
+    .toLowerCase()
+    .includes(needle);
+}

package/client/message-agent.tsx

@@ -0,0 +1,363 @@
+import {
+  type PluginAgentPanelProps,
+  type PluginButtonContentProps,
+  type PluginClientContext,
+  usePaseo,
+} from "@getpaseo/plugin/client";
+import { Icon, useToast } from "@getpaseo/plugin/client/react-native";
+import { useMutation, useQuery } from "@tanstack/react-query";
+import { useEffect, useMemo, useRef, useState } from "react";
+import { Pressable, ScrollView, Text, TextInput, View } from "react-native";
+import {
+  AGENT_PAGE_LIMIT,
+  type AgentEntry,
+  loadAgents,
+  MAX_AGENT_PAGES,
+  placement,
+  stateLabel,
+  title,
+} from "./agents";
+import { formatTellInstruction, messageTargets } from "./messaging";
+import { handleTellCommand } from "./tell-command";
+
+const VISIBLE_TARGETS = 8;
+
+type MessageAgentFormProps = {
+  sourceAgentId: string;
+  theme: PluginButtonContentProps["theme"];
+  host: PluginButtonContentProps["host"];
+  close?: () => void;
+};
+
+function MessageAgentForm({ sourceAgentId, theme, host, close }: MessageAgentFormProps) {
+  const paseo = usePaseo();
+  const toast = useToast();
+  const [query, setQuery] = useState("");
+  const [targetId, setTargetId] = useState<string | null>(null);
+  const [message, setMessage] = useState("");
+  const messageInputRef = useRef<TextInput>(null);
+  const directory = useQuery({
+    queryKey: ["tell-agent", "message-targets", host.id],
+    queryFn: () => loadAgents(paseo),
+  });
+  const entries = directory.data?.entries ?? [];
+  const target = targetId ? entries.find((entry) => entry.agent.id === targetId) : undefined;
+  const matchingTargets = useMemo(
+    () => messageTargets(entries, sourceAgentId, query),
+    [entries, query, sourceAgentId],
+  );
+  const visibleTargets = matchingTargets.slice(0, VISIBLE_TARGETS);
+  useEffect(() => {
+    if (!targetId) return;
+    const focusTimer = setTimeout(() => messageInputRef.current?.focus(), 0);
+    return () => clearTimeout(focusTimer);
+  }, [targetId]);
+  const send = useMutation({
+    mutationFn: async ({ entry, text }: { entry: AgentEntry; text: string }) => {
+      await paseo.agents.ref(sourceAgentId).send(formatTellInstruction(entry.agent.id, text));
+      return entry;
+    },
+    onSuccess(entry) {
+      toast.show(`Asked current agent to tell ${title(entry)}`, { variant: "success" });
+      if (close) close();
+      else {
+        setTargetId(null);
+        setMessage("");
+      }
+    },
+  });
+  const styles = useMemo(
+    () => ({
+      body: { gap: 12 },
+      heading: { color: theme.colors.foreground, fontSize: 18, fontWeight: "600" as const },
+      detail: { color: theme.colors.foregroundMuted, fontSize: 13, lineHeight: 18 },
+      error: { color: theme.colors.statusDanger, fontSize: 13, lineHeight: 18 },
+      warning: { color: theme.colors.statusWarning, fontSize: 13, lineHeight: 18 },
+      input: {
+        minHeight: 38,
+        borderWidth: 1,
+        borderColor: theme.colors.border,
+        borderRadius: 8,
+        paddingHorizontal: 10,
+        paddingVertical: 8,
+        color: theme.colors.foreground,
+        backgroundColor: theme.colors.surface1,
+      },
+      message: {
+        minHeight: 92,
+        borderWidth: 1,
+        borderColor: theme.colors.border,
+        borderRadius: 8,
+        paddingHorizontal: 10,
+        paddingVertical: 8,
+        color: theme.colors.foreground,
+        backgroundColor: theme.colors.surface1,
+        textAlignVertical: "top" as const,
+      },
+      results: { gap: 6 },
+      row: {
+        minHeight: 48,
+        flexDirection: "row" as const,
+        alignItems: "center" as const,
+        gap: 9,
+        paddingHorizontal: 10,
+        paddingVertical: 8,
+        borderWidth: 1,
+        borderColor: theme.colors.border,
+        borderRadius: 8,
+        backgroundColor: theme.colors.surface1,
+      },
+      rowSelected: {
+        borderColor: theme.colors.accent,
+        backgroundColor: theme.colors.surface2,
+      },
+      rowText: { flex: 1, minWidth: 0, gap: 2 },
+      rowTitle: { color: theme.colors.foreground, fontWeight: "600" as const, fontSize: 13 },
+      rowDetail: { color: theme.colors.foregroundMuted, fontSize: 12 },
+      state: { color: theme.colors.foregroundMuted, fontSize: 11 },
+      actions: { flexDirection: "row" as const, justifyContent: "flex-end" as const, gap: 8 },
+      button: {
+        minHeight: 36,
+        justifyContent: "center" as const,
+        paddingHorizontal: 12,
+        borderRadius: 8,
+        borderWidth: 1,
+        borderColor: theme.colors.border,
+        backgroundColor: theme.colors.surface1,
+      },
+      primary: { borderColor: theme.colors.accent, backgroundColor: theme.colors.accent },
+      buttonText: { color: theme.colors.foreground, fontWeight: "600" as const },
+      primaryText: { color: theme.colors.accentForeground, fontWeight: "600" as const },
+      disabled: { opacity: 0.4 },
+    }),
+    [theme],
+  );
+  const canSend = Boolean(target && message.trim()) && !send.isPending;
+
+  return (
+    <View style={styles.body}>
+      <Text style={styles.heading}>Tell another agent</Text>
+      <Text style={styles.detail}>
+        Search active sessions on {host.label}. Your current agent receives the instruction and can
+        add context before contacting the selected agent.
+      </Text>
+      <TextInput
+        accessibilityLabel="Search message targets"
+        autoCapitalize="none"
+        autoCorrect={false}
+        onChangeText={setQuery}
+        placeholder="Search agent, workspace, project, or model"
+        placeholderTextColor={theme.colors.foregroundMuted}
+        value={query}
+        style={styles.input}
+      />
+      {directory.isPending ? <Text style={styles.detail}>Loading agents…</Text> : null}
+      {directory.error ? (
+        <Text accessibilityRole="alert" style={styles.error}>
+          {directory.error.message}
+        </Text>
+      ) : null}
+      {!directory.isPending && !directory.error ? (
+        <View style={styles.results}>
+          {visibleTargets.map((entry) => {
+            const selected = entry.agent.id === targetId;
+            return (
+              <Pressable
+                key={entry.agent.id}
+                accessibilityRole="button"
+                accessibilityLabel={`Select ${title(entry)} in ${placement(entry)}`}
+                accessibilityState={{ selected }}
+                onPress={() => setTargetId(entry.agent.id)}
+                style={({ pressed }) => [
+                  styles.row,
+                  selected && styles.rowSelected,
+                  pressed && styles.disabled,
+                ]}
+              >
+                <Icon
+                  name={selected ? "CircleCheck" : "MessageSquareMore"}
+                  size={16}
+                  color={selected ? theme.colors.accent : theme.colors.foregroundMuted}
+                />
+                <View style={styles.rowText}>
+                  <Text numberOfLines={1} style={styles.rowTitle}>
+                    {title(entry)}
+                  </Text>
+                  <Text numberOfLines={1} style={styles.rowDetail}>
+                    {placement(entry)}
+                  </Text>
+                </View>
+                <Text style={styles.state}>{stateLabel(entry.agent)}</Text>
+              </Pressable>
+            );
+          })}
+          {matchingTargets.length === 0 ? (
+            <Text style={styles.detail}>No active agents match this search.</Text>
+          ) : null}
+          {matchingTargets.length > VISIBLE_TARGETS ? (
+            <Text style={styles.detail}>
+              Showing {VISIBLE_TARGETS} of {matchingTargets.length}. Refine the search to narrow it.
+            </Text>
+          ) : null}
+          {directory.data?.truncated ? (
+            <Text style={styles.warning}>
+              Only the first {AGENT_PAGE_LIMIT * MAX_AGENT_PAGES} agents were searched.
+            </Text>
+          ) : null}
+        </View>
+      ) : null}
+      {target ? (
+        <TextInput
+          ref={messageInputRef}
+          accessibilityLabel={`Instruction for ${title(target)}`}
+          multiline
+          onChangeText={setMessage}
+          placeholder="What should your current agent tell this agent?"
+          placeholderTextColor={theme.colors.foregroundMuted}
+          value={message}
+          style={styles.message}
+        />
+      ) : null}
+      {send.error ? (
+        <Text accessibilityRole="alert" style={styles.error}>
+          {send.error.message}
+        </Text>
+      ) : null}
+      <View style={styles.actions}>
+        <Pressable
+          accessibilityRole="button"
+          disabled={send.isPending}
+          onPress={() => {
+            if (close) close();
+            else {
+              setTargetId(null);
+              setMessage("");
+            }
+          }}
+          style={({ pressed }) => [styles.button, pressed && styles.disabled]}
+        >
+          <Text style={styles.buttonText}>{close ? "Cancel" : "Clear"}</Text>
+        </Pressable>
+        <Pressable
+          accessibilityRole="button"
+          accessibilityLabel={
+            target ? `Ask current agent to tell ${title(target)}` : "Select a target agent"
+          }
+          disabled={!canSend}
+          onPress={() => {
+            if (target && message.trim()) send.mutate({ entry: target, text: message });
+          }}
+          style={({ pressed }) => [
+            styles.button,
+            styles.primary,
+            (!canSend || pressed) && styles.disabled,
+          ]}
+        >
+          <Text style={styles.primaryText}>
+            {send.isPending ? "Sending…" : "Ask current agent"}
+          </Text>
+        </Pressable>
+      </View>
+    </View>
+  );
+}
+
+export function MessageAgentPopover(props: PluginButtonContentProps) {
+  if (props.context !== "agent") return null;
+  return <MessageAgentForm {...props} sourceAgentId={props.agentId} />;
+}
+
+export function TellAgentPanel({ theme, host, layout, agentId }: PluginAgentPanelProps) {
+  const contentStyle = useMemo(
+    () => ({
+      flexGrow: 1,
+      padding: layout.compact ? 14 : 20,
+      backgroundColor: theme.colors.surface0,
+    }),
+    [layout.compact, theme.colors.surface0],
+  );
+  return (
+    <ScrollView contentContainerStyle={contentStyle} keyboardShouldPersistTaps="handled">
+      <MessageAgentForm sourceAgentId={agentId} theme={theme} host={host} />
+    </ScrollView>
+  );
+}
+
+export function contributeAgentMessaging(client: PluginClientContext) {
+  const removePanel = client.addWorkspacePanel({
+    id: "tell-agent",
+    title: "Tell agent",
+    icon: "MessagesSquare",
+    context: "agent",
+    locations: ["workspace", "explorer"],
+    Component: TellAgentPanel,
+  });
+  const pills = new Map<string, { workspaceId: string; remove(): void }>();
+  let stopped = false;
+
+  function removePill(agentId: string) {
+    pills.get(agentId)?.remove();
+    pills.delete(agentId);
+  }
+
+  function syncAgent(agent: {
+    id: string;
+    workspaceId?: string | null;
+    status: string;
+    archivedAt?: string | null;
+  }) {
+    if (!agent.workspaceId || agent.archivedAt || agent.status === "closed") {
+      removePill(agent.id);
+      return;
+    }
+    const next = { id: agent.id, workspaceId: agent.workspaceId };
+    const current = pills.get(agent.id);
+    if (current?.workspaceId === next.workspaceId) return;
+    removePill(agent.id);
+    const pill = client.addComposerPill({
+      id: "message-agent",
+      workspaceId: next.workspaceId,
+      agentId: next.id,
+      button: {
+        title: "Message another agent",
+        label: "Tell agent",
+        icon: "MessagesSquare",
+        behavior: { kind: "popover", Content: MessageAgentPopover },
+      },
+    });
+    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 }) => {
+      if (stopped) return;
+      for (const { agent } of entries) syncAgent(agent);
+    })
+    .catch(() => undefined);
+
+  const removeTellCommand = client.addSlashCommand({
+    name: "tell",
+    description: "Open the agent picker or message another session",
+    argumentHint: "[agent or workspace :: message]",
+    context: "agent",
+    onSubmit: handleTellCommand,
+  });
+
+  return () => {
+    if (stopped) return;
+    stopped = true;
+    removeTellCommand();
+    removePanel();
+    unsubscribe();
+    for (const pill of pills.values()) pill.remove();
+    pills.clear();
+  };
+}

package/client/messaging.ts

@@ -0,0 +1,63 @@
+import { type AgentEntry, matches, title } from "./agents";
+
+export type TellArguments = { target: string; message: string };
+
+export type TargetResolution =
+  | { kind: "match"; entry: AgentEntry }
+  | { kind: "none" }
+  | { kind: "ambiguous"; entries: AgentEntry[] };
+
+export function isMessageable(entry: AgentEntry, sourceAgentId: string): boolean {
+  const agent = entry.agent;
+  return agent.id !== sourceAgentId && !agent.archivedAt && agent.status !== "closed";
+}
+
+export function messageTargets(
+  entries: readonly AgentEntry[],
+  sourceAgentId: string,
+  query: string,
+): AgentEntry[] {
+  const needle = query.trim().replace(/^@/, "").toLowerCase();
+  return entries
+    .filter((entry) => isMessageable(entry, sourceAgentId) && matches(entry, needle))
+    .sort((left, right) => {
+      const leftTitle = title(left).toLowerCase();
+      const rightTitle = title(right).toLowerCase();
+      const leftExact = left.agent.id.toLowerCase() === needle || leftTitle === needle;
+      const rightExact = right.agent.id.toLowerCase() === needle || rightTitle === needle;
+      if (leftExact !== rightExact) return leftExact ? -1 : 1;
+      return Date.parse(right.agent.updatedAt) - Date.parse(left.agent.updatedAt);
+    });
+}
+
+export function resolveMessageTarget(
+  entries: readonly AgentEntry[],
+  sourceAgentId: string,
+  query: string,
+): TargetResolution {
+  const needle = query.trim().replace(/^@/, "").toLowerCase();
+  if (!needle) return { kind: "none" };
+  const candidates = entries.filter((entry) => isMessageable(entry, sourceAgentId));
+  const idMatches = candidates.filter((entry) => entry.agent.id.toLowerCase().startsWith(needle));
+  if (idMatches.length === 1) return { kind: "match", entry: idMatches[0] as AgentEntry };
+  if (idMatches.length > 1) return { kind: "ambiguous", entries: idMatches };
+  const titleMatches = candidates.filter((entry) => title(entry).toLowerCase() === needle);
+  if (titleMatches.length === 1) return { kind: "match", entry: titleMatches[0] as AgentEntry };
+  if (titleMatches.length > 1) return { kind: "ambiguous", entries: titleMatches };
+  const fuzzyMatches = messageTargets(candidates, sourceAgentId, needle);
+  if (fuzzyMatches.length === 1) return { kind: "match", entry: fuzzyMatches[0] as AgentEntry };
+  if (fuzzyMatches.length > 1) return { kind: "ambiguous", entries: fuzzyMatches };
+  return { kind: "none" };
+}
+
+export function parseTellArguments(args: string): TellArguments | null {
+  const separator = args.indexOf("::");
+  if (separator < 1) return null;
+  const target = args.slice(0, separator).trim();
+  const message = args.slice(separator + 2).trim();
+  return target && message ? { target, message } : null;
+}
+
+export function formatTellInstruction(targetAgentId: string, message: string): string {
+  return `tell ${targetAgentId}: ${message.trim()}`;
+}

package/client/tell-command.ts

@@ -0,0 +1,33 @@
+import type { PluginAgentCommandContext } from "@getpaseo/plugin/client";
+import { loadAgents, placement, title } from "./agents";
+import { formatTellInstruction, parseTellArguments, resolveMessageTarget } from "./messaging";
+
+export async function handleTellCommand({
+  args,
+  agent,
+  paseo,
+  openPanel,
+}: PluginAgentCommandContext & { args: string }) {
+  if (!args.trim()) {
+    openPanel("tell-agent");
+    return;
+  }
+  const parsed = parseTellArguments(args);
+  if (!parsed) {
+    throw new Error("Usage: /tell <agent or workspace> :: <message>");
+  }
+  const { entries } = await loadAgents(paseo);
+  const resolution = resolveMessageTarget(entries, agent.id, parsed.target);
+  if (resolution.kind === "none") {
+    throw new Error(`No active agent matches “${parsed.target}”.`);
+  }
+  if (resolution.kind === "ambiguous") {
+    const examples = resolution.entries
+      .slice(0, 3)
+      .map((entry) => `${title(entry)} (${placement(entry)})`)
+      .join(", ");
+    throw new Error(`More than one agent matches “${parsed.target}”: ${examples}. Refine it.`);
+  }
+  const target = resolution.entry;
+  await paseo.agents.ref(agent.id).send(formatTellInstruction(target.agent.id, parsed.message));
+}

package/index.client.tsx

@@ -0,0 +1,6 @@
+import type { PluginClientContext } from "@getpaseo/plugin/client";
+import { contributeAgentMessaging } from "./client/message-agent";
+
+export default function contribute(client: PluginClientContext) {
+  return contributeAgentMessaging(client);
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@omercnet/paseo-tell-agent",
+  "version": "0.2.0",
+  "type": "module",
+  "description": "Tell agents in other Paseo workspaces.",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "packageManager": "bun@1.4.0",
+  "engines": {
+    "bun": ">=1.4.0"
+  },
+  "author": "Omer Cohen",
+  "keywords": [
+    "paseo",
+    "paseo-plugin",
+    "tell-agent",
+    "coding-agents",
+    "orchestration"
+  ],
+  "files": [
+    "index.client.tsx",
+    "client",
+    "paseo-plugin.json",
+    "LICENSE"
+  ],
+  "scripts": {
+    "check": "biome check .",
+    "check:write": "biome check --write .",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.10",
+    "@getpaseo/client": "0.8.0",
+    "@getpaseo/plugin": "0.8.0",
+    "@getpaseo/protocol": "0.8.0",
+    "@tanstack/react-query": "^5.102.3",
+    "@types/bun": "^1.4.0",
+    "@types/react": "^19.2.18",
+    "react": "19.1.0",
+    "react-native": "0.81.5",
+    "typescript": "^7.0.2"
+  }
+}

package/paseo-plugin.json

@@ -0,0 +1,4 @@
+{
+  "id": "tell-agent",
+  "requirements": { "paseo": "^0.8.0" }
+}