@omercnet/paseo-tell-agent 1.1.0 → 1.2.0-next.227.1

package/OVERVIEW.md

@@ -0,0 +1,11 @@
+Tell Agent lets one agent pass a message to another agent on the same Paseo host. From an agent's composer, run `/tell [--interrupt] <agent or workspace> :: <message>`. The target matches an active agent's title or ID, or a project or workspace name, and the command fails if a name matches more than one agent. Running `/tell` with no arguments opens a panel for choosing a target and writing the message.
+
+## How it works
+
+The plugin does not write into the target's session. It asks the agent you are typing in (the source agent) to forward your message to the target, and the source agent carries that out. If the source agent is busy, the request is added to its running turn. Put `--interrupt` first to replace its current turn instead.
+
+## Reads and sends
+
+- Reads the titles, workspace and project names and IDs of agents on the host you are connected to.
+- Sends your message and the target agent's ID to the source agent over the existing host connection.
+- Only agents on the same host are reachable. It reads no files and contacts no other service.

package/README.md

@@ -43,7 +43,7 @@ Paseo 0.9 and 0.10 use the reviewed update flow to show the current and proposed
 Run the slash command from an agent composer:
 
 ```text
-/tell <agent or workspace> :: <message>
+/tell [--interrupt] <agent or workspace> :: <message>
 ```
 
 For example:
@@ -58,6 +58,14 @@ The target can match an active agent's title or ID, or its project or workspace
 
 The plugin asks the source agent to forward the message to the resolved target. The source agent remains responsible for executing that instruction; the plugin does not inject the text directly into the target session.
 
+If the source agent is busy, `/tell` and the Tell agent panel send that instruction with `activeTurnBehavior: "steer"`. Paseo tries to add it to the running turn instead of interrupting it, and the agent picks it up at its next step, which can be after its current tool call finishes. Steering is best effort: Paseo still replaces the turn when the provider cannot steer. Put `--interrupt` first to replace the source agent's current turn instead:
+
+```text
+/tell --interrupt Payments :: Stop and review the authentication change.
+```
+
+Either choice only applies to the source agent. Its later message to the target is a separate send and can still interrupt the target. Paseo 0.9 and later hosts accept both behaviors.
+
 ## Trust
 
 Paseo plugins run as trusted, unsandboxed code. Installing this package trusts its code, dependencies, and future updates. Review the package and update preview before approving an installation or update.

package/client/message-agent.tsx

@@ -18,7 +18,7 @@ import {
   stateLabel,
   title,
 } from "./agents";
-import { formatTellInstruction, messageTargets } from "./messaging";
+import { formatTellInstruction, messageTargets, sourceSendOptions } from "./messaging";
 import { handleTellCommand } from "./tell-command";
 
 const VISIBLE_TARGETS = 8;
@@ -55,7 +55,9 @@ function MessageAgentForm({ sourceAgentId, theme, host, close }: MessageAgentFor
   }, [targetId]);
   const send = useMutation({
     mutationFn: async ({ entry, text }: { entry: AgentEntry; text: string }) => {
-      await paseo.agents.ref(sourceAgentId).send(formatTellInstruction(entry.agent.id, text));
+      await paseo.agents
+        .ref(sourceAgentId)
+        .send(formatTellInstruction(entry.agent.id, text), sourceSendOptions());
       return entry;
     },
     onSuccess(entry) {
@@ -345,7 +347,7 @@ export function contributeAgentMessaging(client: PluginClientContext) {
   const removeTellCommand = client.addSlashCommand({
     name: "tell",
     description: "Open the agent picker or message another session",
-    argumentHint: "[agent or workspace :: message]",
+    argumentHint: "[--interrupt] [agent or workspace :: message]",
     context: "agent",
     onSubmit: handleTellCommand,
   });

package/client/messaging.ts

@@ -1,6 +1,11 @@
 import { type AgentEntry, matches, title } from "./agents";
 
-export type TellArguments = { target: string; message: string };
+export type TellArguments = { target: string; message: string; interrupt: boolean };
+
+// Best effort: the host may still replace the active turn when the provider cannot steer.
+export function sourceSendOptions(interrupt = false) {
+  return { activeTurnBehavior: interrupt ? "interrupt" : "steer" } as const;
+}
 
 export type TargetResolution =
   | { kind: "match"; entry: AgentEntry }
@@ -51,11 +56,13 @@ export function resolveMessageTarget(
 }
 
 export function parseTellArguments(args: string): TellArguments | null {
-  const separator = args.indexOf("::");
+  const flag = /^\s*--interrupt(?=\s)/.exec(args);
+  const rest = flag ? args.slice(flag[0].length) : args;
+  const separator = rest.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;
+  const target = rest.slice(0, separator).trim();
+  const message = rest.slice(separator + 2).trim();
+  return target && message ? { target, message, interrupt: Boolean(flag) } : null;
 }
 
 export function formatTellInstruction(targetAgentId: string, message: string): string {

package/client/tell-command.ts

@@ -1,6 +1,11 @@
 import type { PluginAgentCommandContext } from "@getpaseo/plugin/client";
 import { loadAgents, placement, title } from "./agents";
-import { formatTellInstruction, parseTellArguments, resolveMessageTarget } from "./messaging";
+import {
+  formatTellInstruction,
+  parseTellArguments,
+  resolveMessageTarget,
+  sourceSendOptions,
+} from "./messaging";
 
 export async function handleTellCommand({
   args,
@@ -14,7 +19,7 @@ export async function handleTellCommand({
   }
   const parsed = parseTellArguments(args);
   if (!parsed) {
-    throw new Error("Usage: /tell <agent or workspace> :: <message>");
+    throw new Error("Usage: /tell [--interrupt] <agent or workspace> :: <message>");
   }
   const { entries } = await loadAgents(paseo);
   const resolution = resolveMessageTarget(entries, agent.id, parsed.target);
@@ -29,5 +34,10 @@ export async function handleTellCommand({
     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));
+  await paseo.agents
+    .ref(agent.id)
+    .send(
+      formatTellInstruction(target.agent.id, parsed.message),
+      sourceSendOptions(parsed.interrupt),
+    );
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omercnet/paseo-tell-agent",
-  "version": "1.1.0",
+  "version": "1.2.0-next.227.1",
   "type": "module",
   "description": "Send messages to agents in other workspaces on the same Paseo host.",
   "license": "MIT",
@@ -33,7 +33,8 @@
     "client",
     "paseo-plugin.json",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "OVERVIEW.md"
   ],
   "scripts": {
     "check": "biome check .",
@@ -43,9 +44,9 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.10",
-    "@getpaseo/client": "0.10.1",
-    "@getpaseo/plugin": "0.10.1",
-    "@getpaseo/protocol": "0.10.1",
+    "@getpaseo/client": "0.11.0-beta.5",
+    "@getpaseo/plugin": "0.11.0-beta.5",
+    "@getpaseo/protocol": "0.11.0-beta.5",
     "@tanstack/react-query": "^5.102.3",
     "@types/node": "^24.10.1",
     "@types/react": "^19.2.18",

package/paseo-plugin.json

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