@mduan/paseo-cli 0.11.0-fork.35 → 0.11.0-fork.36

package/dist/commands/agent/send.d.ts

@@ -1,4 +1,5 @@
 import { type Command } from "commander";
+import type { ActiveTurnBehavior } from "@getpaseo/protocol/messages";
 import type { CommandOptions, SingleResult, OutputSchema } from "../../output/index.js";
 /** Result type for agent send command */
 export interface AgentSendResult {
@@ -9,6 +10,7 @@ export interface AgentSendResult {
 /** Schema for agent send output */
 export declare const agentSendSchema: OutputSchema<AgentSendResult>;
 export interface AgentSendOptions extends CommandOptions {
+    behavior?: ActiveTurnBehavior;
     wait?: boolean;
     image?: string[];
     prompt?: string;

package/dist/commands/agent/send.js

@@ -1,3 +1,4 @@
+import { Option } from "commander";
 import { collectMultiple } from "../../utils/command-options.js";
 import { connectToDaemon } from "../../utils/client.js";
 import { readFile } from "node:fs/promises";
@@ -19,6 +20,7 @@ export function addSendOptions(cmd) {
         .option("--prompt <text>", "Provide the message inline as a flag")
         .option("--prompt-file <path>", "Read the message from a UTF-8 text file")
         .option("--image <path>", "Attach image(s) to the message", collectMultiple, [])
+        .addOption(new Option("--behavior <behavior>", "How to send into a running turn (default: steer from an agent, interrupt otherwise)").choices(["interrupt", "steer"]))
         .option("--no-wait", "Return immediately without waiting for completion");
 }
 /**
@@ -139,7 +141,12 @@ export async function runSendCommand(agentIdArg, prompt, options, _command) {
         // Read image files if provided
         const images = options.image && options.image.length > 0 ? await readImageFiles(options.image) : undefined;
         // Send the message
-        await client.sendAgentMessage(agentIdArg, promptInput, { images });
+        const sourceAgentId = process.env.PASEO_AGENT_ID?.trim() || undefined;
+        await client.sendAgentMessage(agentIdArg, promptInput, {
+            images,
+            sourceAgentId,
+            activeTurnBehavior: options.behavior ?? (sourceAgentId ? "steer" : "interrupt"),
+        });
         // If --no-wait, return immediately
         if (options.wait === false) {
             await client.close();

package/node_modules/@getpaseo/client/dist/daemon-client.d.ts

@@ -162,6 +162,8 @@ export interface SendMessageOptions {
         mimeType: string;
     }>;
     attachments?: SendAgentMessageRequest["attachments"];
+    /** The sending agent, when an agent rather than a person sends the message. */
+    sourceAgentId?: string;
 }
 export interface AgentAttentionRequiredNotification {
     agentId: string;

package/node_modules/@getpaseo/client/dist/daemon-client.js

@@ -2276,6 +2276,7 @@ export class DaemonClient {
             ...(options?.activeTurnBehavior ? { activeTurnBehavior: options.activeTurnBehavior } : {}),
             ...(options?.images ? { images: options.images } : {}),
             ...(options?.attachments ? { attachments: options.attachments } : {}),
+            ...(options?.sourceAgentId ? { sourceAgentId: options.sourceAgentId } : {}),
         });
         const payload = await this.sendRequest({
             requestId,

package/node_modules/@getpaseo/client/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/client",
-  "version": "0.11.0-fork.35",
+  "version": "0.11.0-fork.36",
   "description": "Paseo client SDK package",
   "files": [
     "dist",
@@ -44,7 +44,7 @@
     "vitest": "^4.1.6"
   },
   "dependencies": {
-    "@getpaseo/protocol": "0.11.0-fork.35",
-    "@getpaseo/relay": "0.11.0-fork.35"
+    "@getpaseo/protocol": "0.11.0-fork.36",
+    "@getpaseo/relay": "0.11.0-fork.36"
   }
 }

package/node_modules/@getpaseo/highlight/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/highlight",
-  "version": "0.11.0-fork.35",
+  "version": "0.11.0-fork.36",
   "files": [
     "dist",
     "!dist/**/*.map",

package/node_modules/@getpaseo/plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/plugin",
-  "version": "0.11.0-fork.35",
+  "version": "0.11.0-fork.36",
   "description": "Paseo plugin SDK package",
   "files": [
     "dist",
@@ -66,8 +66,8 @@
     "test": "vitest run"
   },
   "devDependencies": {
-    "@getpaseo/client": "0.11.0-fork.35",
-    "@getpaseo/protocol": "0.11.0-fork.35",
+    "@getpaseo/client": "0.11.0-fork.36",
+    "@getpaseo/protocol": "0.11.0-fork.36",
     "@types/node": "^20.9.0",
     "@types/react": "~19.2.0",
     "react": "19.1.0",

package/node_modules/@getpaseo/protocol/dist/messages.d.ts

@@ -1586,6 +1586,7 @@ export declare const SendAgentMessageRequestSchema: z.ZodObject<{
         size: number;
         path: string;
     })[], unknown>>>;
+    sourceAgentId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const WaitForFinishRequestSchema: z.ZodObject<{
     type: z.ZodLiteral<"wait_for_finish_request">;
@@ -5592,6 +5593,7 @@ export declare const SessionInboundMessageSchema: z.ZodDiscriminatedUnion<[z.Zod
         size: number;
         path: string;
     })[], unknown>>>;
+    sourceAgentId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"wait_for_finish_request">;
     requestId: z.ZodString;
@@ -39179,6 +39181,7 @@ export declare const WSSessionInboundSchema: z.ZodObject<{
             size: number;
             path: string;
         })[], unknown>>>;
+        sourceAgentId: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"wait_for_finish_request">;
         requestId: z.ZodString;
@@ -55890,6 +55893,7 @@ export declare const WSInboundMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObjec
             size: number;
             path: string;
         })[], unknown>>>;
+        sourceAgentId: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"wait_for_finish_request">;
         requestId: z.ZodString;

package/node_modules/@getpaseo/protocol/dist/messages.js

@@ -1265,6 +1265,8 @@ export const SendAgentMessageRequestSchema = z.object({
     activeTurnBehavior: ActiveTurnBehaviorSchema.optional(),
     images: z.array(ImageAttachmentSchema).optional(),
     attachments: AgentAttachmentsSchema,
+    /** Set when an agent sends this, such as `paseo send` from an agent's shell; not a human prompt. */
+    sourceAgentId: z.string().optional(),
 });
 export const WaitForFinishRequestSchema = z.object({
     type: z.literal("wait_for_finish_request"),

package/node_modules/@getpaseo/protocol/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/protocol",
-  "version": "0.11.0-fork.35",
+  "version": "0.11.0-fork.36",
   "description": "Paseo shared protocol schemas and wire types",
   "files": [
     "dist",

package/node_modules/@getpaseo/relay/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/relay",
-  "version": "0.11.0-fork.35",
+  "version": "0.11.0-fork.36",
   "description": "Paseo relay for bridging daemon and client connections",
   "files": [
     "dist",

package/node_modules/@getpaseo/server/dist/server/builtin-plugins/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/builtin-plugins",
-  "version": "0.11.0-fork.35",
+  "version": "0.11.0-fork.36",
   "private": true,
   "type": "module",
   "scripts": {

package/node_modules/@getpaseo/server/dist/server/server/agent/agent-prompt.d.ts

@@ -85,6 +85,13 @@ export interface SetupFinishNotificationParams {
     childAgentId: string;
     callerAgentId: string;
     requireParentOwnership?: boolean;
+    /**
+     * Dispatch this observation is armed ahead of — catches a turn finishing during steering
+     * admission. Notifications wait for it and are dropped if it fails.
+     */
+    dispatch?: Promise<unknown>;
+    /** How the armed prompt meets a running turn; a steer can be answered after that turn ends. */
+    activeTurnBehavior?: ActiveTurnBehavior;
     logger: Logger;
 }
 export declare function setupFinishNotification(params: SetupFinishNotificationParams): void;

package/node_modules/@getpaseo/server/dist/server/server/agent/agent-prompt.js

@@ -213,6 +213,11 @@ export async function startCreatedAgentInitialPrompt(params) {
     }
     return refreshedSnapshot;
 }
+/**
+ * Claude answers a steer that arrives after its last tool call in a follow-up turn, started
+ * once the steered turn ends. Keep observing that long so the follow-up's finish is reported.
+ */
+const STEER_FOLLOW_UP_WINDOW_MS = 10000;
 const FINISH_NOTIFICATION_MESSAGE_LIMIT = 4000;
 function formatFinishNotificationBody(params) {
     const statusLine = `Agent ${params.childAgentId} (${params.title}) ${params.reason}.`;
@@ -232,34 +237,77 @@ function formatFinishNotificationBody(params) {
         }
         sections.push(`<agent-response>\n${lastAssistantMessage}\n</agent-response>`);
     }
+    if (params.followUpPossible) {
+        sections.push("If this response does not answer the message you steered into this agent's turn, the agent may still be answering it. A follow-up report will arrive when it finishes.");
+    }
     return sections.join("\n\n");
 }
-// A caller waits on a child through one armed notification. Arming again, such as a
-// follow-up prompt while the child still runs, replaces the earlier one so the child's
-// next finish reaches the caller once.
+// One observation per caller/child pair. Re-arming (e.g. a follow-up while the child runs)
+// joins it, so the next finish notifies once even when sends overlap or fail.
 const armedFinishNotifications = new WeakMap();
 export function setupFinishNotification(params) {
-    const { agentManager, agentStorage, childAgentId, callerAgentId, requireParentOwnership = false, logger, } = params;
+    const { agentManager, agentStorage, childAgentId, callerAgentId, logger } = params;
+    const armedByManager = armedFinishNotifications.get(agentManager) ?? new Map();
+    armedFinishNotifications.set(agentManager, armedByManager);
+    const armedKey = JSON.stringify([childAgentId, callerAgentId]);
+    const armed = armedByManager.get(armedKey);
+    if (armed) {
+        armed(params);
+        return;
+    }
+    armedByManager.set(armedKey, arm);
     let hasSeenRunning = false;
     let stopped = false;
     const notifiedPermissionRequestIds = new Set();
     let unsubscribe = null;
     let notificationQueue = Promise.resolve();
-    const armedByManager = armedFinishNotifications.get(agentManager) ?? new Map();
-    armedFinishNotifications.set(agentManager, armedByManager);
-    const armedKey = JSON.stringify([childAgentId, callerAgentId]);
-    armedByManager.get(armedKey)?.();
-    armedByManager.set(armedKey, stop);
+    let requireParentOwnership = false;
+    // Accepted once any arming is not tied to a dispatch, or any tracked dispatch succeeds.
+    let accepted = false;
+    let steeredIntoRunningTurn = false;
+    let followUpWindow;
+    const dispatches = [];
+    arm(params);
+    function arm(next) {
+        requireParentOwnership = next.requireParentOwnership ?? false;
+        if (next.activeTurnBehavior === "steer" &&
+            agentManager.getAgent(childAgentId)?.lifecycle === "running") {
+            steeredIntoRunningTurn = true;
+        }
+        const { dispatch } = next;
+        if (!dispatch) {
+            accepted = true;
+            return;
+        }
+        dispatches.push(dispatch);
+        void (async () => {
+            if (!(await dispatchAccepted()))
+                stop();
+        })();
+    }
+    /** Resolves once a tracked dispatch succeeds, or false when every one has failed. */
+    async function dispatchAccepted() {
+        let tracked = 0;
+        while (!accepted && tracked < dispatches.length) {
+            tracked = dispatches.length;
+            if (await Promise.any(dispatches).then(() => true, () => false)) {
+                accepted = true;
+            }
+        }
+        return accepted;
+    }
     function stop() {
         if (stopped)
             return;
         stopped = true;
+        clearTimeout(followUpWindow);
         unsubscribe?.();
-        if (armedByManager.get(armedKey) === stop) {
-            armedByManager.delete(armedKey);
-        }
+        armedByManager.delete(armedKey);
     }
-    async function notify(reason, permissionRequest) {
+    async function notify(reason, options) {
+        if (!(await dispatchAccepted())) {
+            return;
+        }
         const callerRecord = await agentStorage.get(callerAgentId);
         if (callerRecord?.archivedAt) {
             return;
@@ -275,7 +323,8 @@ export function setupFinishNotification(params) {
             title,
             reason,
             lastAssistantMessage,
-            permissionRequest,
+            permissionRequest: options.permissionRequest,
+            followUpPossible: options.followUpPossible,
         });
         await sendPromptToAgent({
             agentManager,
@@ -293,11 +342,22 @@ export function setupFinishNotification(params) {
         if (options.terminal ?? true)
             stop();
         notificationQueue = notificationQueue
-            .then(() => notify(reason, options.permissionRequest))
+            .then(() => notify(reason, options))
             .catch((error) => {
             logger.error({ err: error, childAgentId, callerAgentId, reason }, "Failed to notify caller agent");
         });
     }
+    function notifyFinished() {
+        if (!steeredIntoRunningTurn) {
+            notifySafely("finished");
+            return;
+        }
+        steeredIntoRunningTurn = false;
+        hasSeenRunning = false;
+        notifySafely("finished", { terminal: false, followUpPossible: true });
+        followUpWindow = setTimeout(stop, STEER_FOLLOW_UP_WINDOW_MS);
+        followUpWindow.unref?.();
+    }
     unsubscribe = agentManager.subscribe((event) => {
         if (stopped) {
             return;
@@ -309,6 +369,7 @@ export function setupFinishNotification(params) {
                 }
             }
             if (event.agent.lifecycle === "running") {
+                clearTimeout(followUpWindow);
                 if (event.agent.pendingPermissions.size === 0) {
                     hasSeenRunning = true;
                 }
@@ -319,7 +380,7 @@ export function setupFinishNotification(params) {
                 return;
             }
             if (event.agent.lifecycle === "idle" && hasSeenRunning) {
-                notifySafely("finished");
+                notifyFinished();
                 return;
             }
             if (event.agent.lifecycle === "closed") {
@@ -359,6 +420,11 @@ export function setupFinishNotification(params) {
     // not have started yet (streamAgent sets a pending run before
     // transitioning to "running").
     const childSnapshot = agentManager.getAgent(childAgentId);
+    if (params.dispatch) {
+        // The dispatch may still load the child or start a turn that clears a stale error.
+        hasSeenRunning = childSnapshot?.lifecycle === "running";
+        return;
+    }
     if (!childSnapshot || childSnapshot.lifecycle === "closed") {
         stop();
         return;

package/node_modules/@getpaseo/server/dist/server/server/agent/tools/paseo-tools.js

@@ -1,7 +1,7 @@
 import { stat } from "node:fs/promises";
 import { z } from "zod";
 import { ensureValidJson } from "../../json-utils.js";
-import { AgentProfileSchema } from "@getpaseo/protocol/messages";
+import { ActiveTurnBehaviorSchema, AgentProfileSchema } from "@getpaseo/protocol/messages";
 import { AgentFeatureSchema, AgentPermissionRequestPayloadSchema, AgentListItemPayloadSchema, AgentPermissionResponseSchema, AgentSnapshotPayloadSchema, WorkspaceScriptPayloadSchema, } from "../../messages.js";
 import { buildStoredAgentPayload, toAgentListItemPayload, toAgentPayload, } from "../agent-projections.js";
 import { curateAgentActivity } from "../activity-curator.js";
@@ -797,6 +797,7 @@ export function createPaseoToolCatalog(options) {
         .object(legacyTopLevelCreateAgentInputSchema)
         .strict();
     const commonSendAgentPromptInputSchema = {
+        activeTurnBehavior: ActiveTurnBehaviorSchema.optional().describe('How to send into a running turn: "steer" joins it, falling back to interrupt when steering is unavailable; "interrupt" replaces it. Defaults to steer for agent callers and interrupt otherwise.'),
         agentId: z.string(),
         prompt: z.string(),
         sessionMode: z.string().optional().describe("Optional mode to set before running the prompt."),
@@ -1394,10 +1395,11 @@ export function createPaseoToolCatalog(options) {
                 throw new Error("unreachable");
         }
     }
+    const STEERED_BLOCKING_GUIDANCE = "If lastMessage does not answer your message, the agent may still be answering it in a follow-up turn. Check get_agent_activity before acting on this result.";
     const PROMPTED_AGENT_NOTIFICATION_GUIDANCE = "You will get notified when the prompted agent finishes, errors, or needs permission. Do not poll for status; continue with other work until the notification arrives.";
     registerTool("send_agent_prompt", {
         title: "Send agent prompt",
-        description: "Send a task to a running agent. Agent-scoped callers run in background by default; top-level callers wait by default.",
+        description: "Send a task to a running agent. Agent-scoped callers run in background and steer a running turn by default; top-level callers wait and interrupt by default.",
         inputSchema: sendAgentPromptInputSchema,
         outputSchema: {
             success: z.boolean(),
@@ -1406,8 +1408,8 @@ export function createPaseoToolCatalog(options) {
             permission: AgentPermissionRequestPayloadSchema.nullable().optional(),
             guidance: z.string().optional(),
         },
-    }, async ({ agentId, prompt, sessionMode, background = Boolean(callerAgentId), notifyOnFinish = Boolean(callerAgentId), }) => {
-        function armFinishNotification() {
+    }, async ({ agentId, prompt, sessionMode, background = Boolean(callerAgentId), notifyOnFinish = Boolean(callerAgentId), activeTurnBehavior = callerAgentId ? "steer" : "interrupt", }) => {
+        function armFinishNotification(dispatched) {
             if (!callerAgentId || !notifyOnFinish) {
                 return false;
             }
@@ -1416,18 +1418,24 @@ export function createPaseoToolCatalog(options) {
                 agentStorage,
                 childAgentId: agentId,
                 callerAgentId,
+                ...dispatched,
                 logger: childLogger,
             });
             return true;
         }
-        const { disposition } = await sendPromptToAgent({
+        const steersRunningTurn = activeTurnBehavior === "steer" && agentManager.getAgent(agentId)?.lifecycle === "running";
+        const dispatch = sendPromptToAgent({
             agentManager,
             agentStorage,
             agentId,
             prompt,
             sessionMode,
+            activeTurnBehavior,
             logger: childLogger,
         });
+        // Background callers observe before dispatch; blocking callers arm only if the wait runs out.
+        const notifying = background && armFinishNotification({ dispatch, activeTurnBehavior });
+        const { disposition } = await dispatch;
         // If not running in background, wait for completion
         if (!background) {
             const result = await waitForAgentWithTimeout(agentManager, agentId, {
@@ -1435,15 +1443,20 @@ export function createPaseoToolCatalog(options) {
             });
             // The wait ran out while the agent keeps working, so its result arrives as a
             // finish notification instead of in this response.
-            const notifying = result.timedOut &&
+            const notifyingAfterWait = result.timedOut &&
                 agentManager.getAgent(agentId)?.lifecycle === "running" &&
                 armFinishNotification();
+            let guidance;
+            if (notifyingAfterWait)
+                guidance = PROMPTED_AGENT_NOTIFICATION_GUIDANCE;
+            else if (steersRunningTurn)
+                guidance = STEERED_BLOCKING_GUIDANCE;
             const responseData = {
                 success: true,
                 status: result.status,
                 lastMessage: result.lastMessage,
                 permission: sanitizePermissionRequest(result.permission),
-                ...(notifying ? { guidance: PROMPTED_AGENT_NOTIFICATION_GUIDANCE } : {}),
+                ...(guidance ? { guidance } : {}),
             };
             const validJson = ensureValidJson(responseData);
             const response = {
@@ -1452,7 +1465,6 @@ export function createPaseoToolCatalog(options) {
             };
             return response;
         }
-        const notifying = armFinishNotification();
         // Return once the provider has accepted the turn, so the status reports it running.
         if (disposition === "turn_started") {
             await waitForAgentRunStartWithTimeout(agentManager, agentId);

package/node_modules/@getpaseo/server/dist/server/server/session.js

@@ -6692,7 +6692,8 @@ export class Session {
                 textPrefix: msg.text.slice(0, 80),
             }, "agent.session.send_agent_message");
             const send = async () => {
-                await this.recordHumanPrompt({ agentId });
+                if (!msg.sourceAgentId)
+                    await this.recordHumanPrompt({ agentId });
                 const result = await sendPromptToAgent({
                     agentManager: this.agentManager,
                     agentStorage: this.agentStorage,

package/node_modules/@getpaseo/server/dist/server/skills/paseo/SKILL.md

@@ -61,7 +61,7 @@ Detach is an explicit user action in the subagents track, not an agent tool. A c
 
 Agent-scoped `create_agent` defaults `notifyOnFinish` to true. Set it to `false` only for truly fire-and-forget agents.
 
-**`send_agent_prompt`** — `{ agentId, prompt }`. Use for follow-ups to an existing agent. Agent-scoped prompt calls default to `background: true` and `notifyOnFinish: true`; top-level calls default to blocking with no callback. For a synchronous follow-up, pass `background: false` and use the returned result.
+**`send_agent_prompt`** — `{ agentId, prompt, activeTurnBehavior? }`. Use for follow-ups to an existing agent. Agent-scoped prompt calls default to `background: true`, `notifyOnFinish: true`, and `activeTurnBehavior: "steer"`; top-level calls default to blocking, no callback, and `"interrupt"`. Steering falls back to interrupting when the provider can't steer. CLI sends from an agent use the same default and accept `--behavior steer|interrupt`. For a synchronous follow-up, pass `background: false` and use the returned result.
 
 **`update_agent`** — `{ agentId, name?, labels?, settings? }`. Use `settings` for runtime changes on an existing agent: `modeId`, `model`, `thinkingOptionId`, and provider-specific `features`. For Codex fast mode, pass `settings: { features: { "fast_mode": true } }`.