Fimeg/letta-code
1
0
Fork 0
Code Issues 2 Pull Requests Actions 4 Packages Projects Releases Wiki Activity

feat: add background task notification system (#827)

Browse Source 
Co-authored-by: Letta <noreply@letta.com>
This commit is contained in:
Charles Packer
2026-02-04 22:45:16 -08:00
committed by GitHub
parent 84e9a6d744
commit 48ccd8f220
44 changed files with 2244 additions and 234 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
src/agent/subagents/manager.ts
View File

@@ -433,6 +433,7 @@ function buildSubagentArgs(
existingAgentId?: string,
existingConversationId?: string,
preloadedSkillsContent?: string,
maxTurns?: number,
): string[] {
const args: string[] = [];
const isDeployingExisting = Boolean(
@@ -519,6 +520,11 @@ function buildSubagentArgs(
args.push("--block-value", `loaded_skills=${preloadedSkillsContent}`);
}
// Add max turns limit if specified
if (maxTurns !== undefined && maxTurns > 0) {
args.push("--max-turns", String(maxTurns));
}
return args;
}
@@ -536,6 +542,7 @@ async function executeSubagent(
signal?: AbortSignal,
existingAgentId?: string,
existingConversationId?: string,
maxTurns?: number,
): Promise<SubagentResult> {
// Check if already aborted before starting
if (signal?.aborted) {
@@ -570,6 +577,7 @@ async function executeSubagent(
existingAgentId,
existingConversationId,
preloadedSkillsContent,
maxTurns,
);
// Spawn Letta Code in headless mode.
@@ -678,6 +686,9 @@ async function executeSubagent(
subagentId,
true, // Mark as retry to prevent infinite loops
signal,
undefined, // existingAgentId
undefined, // existingConversationId
maxTurns,
);
}
}
@@ -788,6 +799,7 @@ export async function spawnSubagent(
signal?: AbortSignal,
existingAgentId?: string,
existingConversationId?: string,
maxTurns?: number,
): Promise<SubagentResult> {
const allConfigs = await getAllSubagentConfigs();
const config = allConfigs[type];
@@ -847,6 +859,7 @@ export async function spawnSubagent(
signal,
existingAgentId,
existingConversationId,
maxTurns,
);
return result;

297
src/cli/App.tsx
View File

@@ -174,12 +174,21 @@ import {
buildMemoryReminder,
parseMemoryPreference,
} from "./helpers/memoryReminder";
import {
type QueuedMessage,
setMessageQueueAdder,
} from "./helpers/messageQueueBridge";
import {
buildMessageContentFromDisplay,
clearPlaceholdersInText,
resolvePlaceholders,
} from "./helpers/pasteRegistry";
import { generatePlanFilePath } from "./helpers/planName";
import {
buildQueuedContentParts,
buildQueuedUserText,
getQueuedNotificationSummaries,
} from "./helpers/queuedMessageParts";
import { safeJsonParseOr } from "./helpers/safeJsonParse";
import { getDeviceType, getLocalTime } from "./helpers/sessionContext";
import { type ApprovalRequest, drainStreamWithResume } from "./helpers/stream";
@@ -191,10 +200,13 @@ import {
import {
clearCompletedSubagents,
clearSubagentsByIds,
getSubagentByToolCallId,
getSnapshot as getSubagentSnapshot,
hasActiveSubagents,
interruptActiveSubagents,
subscribe as subscribeToSubagents,
} from "./helpers/subagentState";
import { extractTaskNotificationsForDisplay } from "./helpers/taskNotifications";
import {
getRandomPastTenseVerb,
getRandomThinkingVerb,
@@ -689,6 +701,17 @@ function stripSystemReminders(text: string): string {
.trim();
}
function buildTextParts(
...parts: Array<string | undefined | null>
): Array<{ type: "text"; text: string }> {
const out: Array<{ type: "text"; text: string }> = [];
for (const part of parts) {
if (!part) continue;
out.push({ type: "text", text: part });
}
return out;
}
// Items that have finished rendering and no longer change
type StaticItem =
| {
@@ -708,7 +731,7 @@ type StaticItem =
id: string;
type: string;
description: string;
status: "completed" | "error";
status: "completed" | "error" | "running";
toolCount: number;
totalTokens: number;
agentURL: string | null;
@@ -1388,15 +1411,29 @@ export default function App({
const conversationBusyRetriesRef = useRef(0);
// Message queue state for queueing messages during streaming
const [messageQueue, setMessageQueue] = useState<string[]>([]);
const [messageQueue, setMessageQueue] = useState<QueuedMessage[]>([]);
const messageQueueRef = useRef<string[]>([]); // For synchronous access
const messageQueueRef = useRef<QueuedMessage[]>([]); // For synchronous access
useEffect(() => {
messageQueueRef.current = messageQueue;
}, [messageQueue]);
// Override content parts for queued submissions (to preserve part boundaries)
const overrideContentPartsRef = useRef<MessageCreate["content"] | null>(null);
// Set up message queue bridge for background tasks
// This allows non-React code (Task.ts) to add notifications to messageQueue
useEffect(() => {
// Provide a queue adder that adds to messageQueue and bumps dequeueEpoch
setMessageQueueAdder((message: QueuedMessage) => {
setMessageQueue((q) => [...q, message]);
setDequeueEpoch((e) => e + 1);
});
return () => setMessageQueueAdder(null);
}, []);
const waitingForQueueCancelRef = useRef(false);
const queueSnapshotRef = useRef<string[]>([]);
const queueSnapshotRef = useRef<QueuedMessage[]>([]);
const [restoreQueueOnCancel, setRestoreQueueOnCancel] = useState(false);
const restoreQueueOnCancelRef = useRef(restoreQueueOnCancel);
useEffect(() => {
@@ -1433,8 +1470,28 @@ export default function App({
);
}, [isExecutingTool]);
const appendTaskNotificationEvents = useCallback(
(summaries: string[]): boolean => {
if (summaries.length === 0) return false;
for (const summary of summaries) {
const eventId = uid("event");
buffersRef.current.byId.set(eventId, {
kind: "event",
id: eventId,
eventType: "task_notification",
eventData: {},
phase: "finished",
summary,
});
buffersRef.current.order.push(eventId);
}
return true;
},
[],
);
// Consume queued messages for appending to tool results (clears queue + timeout)
const consumeQueuedMessages = useCallback((): string[] | null => {
const consumeQueuedMessages = useCallback((): QueuedMessage[] | null => {
if (messageQueueRef.current.length === 0) return null;
if (queueAppendTimeoutRef.current) {
clearTimeout(queueAppendTimeoutRef.current);
@@ -1651,6 +1708,15 @@ export default function App({
// Handle Task tool_calls specially - track position but don't add individually
// (unless there's no subagent data, in which case commit as regular tool call)
if (ln.kind === "tool_call" && ln.name && isTaskTool(ln.name)) {
if (hasInProgress && ln.toolCallId) {
const subagent = getSubagentByToolCallId(ln.toolCallId);
if (subagent) {
if (firstTaskIndex === -1) {
firstTaskIndex = newlyCommitted.length;
}
continue;
}
}
// Check if this specific Task tool has subagent data (will be grouped)
const hasSubagentData = finishedTaskToolCalls.some(
(tc) => tc.lineId === id,
@@ -2860,8 +2926,11 @@ export default function App({
// Reset interrupted flag since we're starting a fresh stream
buffersRef.current.interrupted = false;
// Clear completed subagents from the UI when starting a new turn
clearCompletedSubagents();
// Clear completed subagents from the UI when starting a new turn,
// but only if no subagents are still running.
if (!hasActiveSubagents()) {
clearCompletedSubagents();
}
while (true) {
// Capture the signal BEFORE any async operations
@@ -3696,34 +3765,49 @@ export default function App({
}
// Append queued messages if any (from 15s append mode)
const queuedMessagesToAppend = consumeQueuedMessages();
if (queuedMessagesToAppend?.length) {
for (const msg of queuedMessagesToAppend) {
const userId = uid("user");
buffersRef.current.byId.set(userId, {
kind: "user",
id: userId,
text: msg,
});
buffersRef.current.order.push(userId);
}
const queuedItemsToAppend = consumeQueuedMessages();
const queuedNotifications = queuedItemsToAppend
? getQueuedNotificationSummaries(queuedItemsToAppend)
: [];
const hadNotifications =
appendTaskNotificationEvents(queuedNotifications);
const queuedUserText = queuedItemsToAppend
? buildQueuedUserText(queuedItemsToAppend)
: "";
if (queuedUserText) {
const userId = uid("user");
buffersRef.current.byId.set(userId, {
kind: "user",
id: userId,
text: queuedUserText,
});
buffersRef.current.order.push(userId);
}
if (queuedItemsToAppend && queuedItemsToAppend.length > 0) {
const queuedContentParts =
buildQueuedContentParts(queuedItemsToAppend);
setThinkingMessage(getRandomThinkingVerb());
refreshDerived();
toolResultsInFlightRef.current = true;
await processConversation(
[
{ type: "approval", approvals: allResults },
...queuedMessagesToAppend.map((msg) => ({
type: "message" as const,
role: "user" as const,
content: msg as unknown as MessageCreate["content"],
})),
{
type: "message",
role: "user",
content: queuedContentParts,
},
],
{ allowReentry: true },
);
toolResultsInFlightRef.current = false;
return;
}
if (hadNotifications || queuedUserText.length > 0) {
refreshDerived();
}
// Cancel mode - queue results and let dequeue effect handle
if (waitingForQueueCancelRef.current) {
@@ -4299,6 +4383,7 @@ export default function App({
needsEagerApprovalCheck,
queueApprovalResults,
consumeQueuedMessages,
appendTaskNotificationEvents,
maybeSyncMemoryFilesystemAfterTurn,
openTrajectorySegment,
syncTrajectoryTokenBase,
@@ -5177,6 +5262,15 @@ export default function App({
const onSubmit = useCallback(
async (message?: string): Promise<{ submitted: boolean }> => {
const msg = message?.trim() ?? "";
const overrideContentParts = overrideContentPartsRef.current;
if (overrideContentParts) {
overrideContentPartsRef.current = null;
}
const { notifications: taskNotifications, cleanedText } =
extractTaskNotificationsForDisplay(msg);
const userTextForInput = cleanedText.trim();
const isSystemOnly =
taskNotifications.length > 0 && userTextForInput.length === 0;
// Handle profile load confirmation (Enter to continue)
if (profileConfirmPending && !msg) {
@@ -5210,14 +5304,16 @@ export default function App({
if (!msg) return { submitted: false };
// Run UserPromptSubmit hooks - can block the prompt from being processed
const isCommand = msg.startsWith("/");
const hookResult = await runUserPromptSubmitHooks(
msg,
isCommand,
agentId,
conversationIdRef.current,
);
if (hookResult.blocked) {
const isCommand = userTextForInput.startsWith("/");
const hookResult = isSystemOnly
? { blocked: false, feedback: [] as string[] }
: await runUserPromptSubmitHooks(
userTextForInput,
isCommand,
agentId,
conversationIdRef.current,
);
if (!isSystemOnly && hookResult.blocked) {
// Show feedback from hook in the transcript
const feedbackId = uid("status");
const feedback = hookResult.feedback.join("\n") || "Blocked by hook";
@@ -5244,7 +5340,13 @@ export default function App({
const submissionGeneration = conversationGenerationRef.current;
// Track user input (agent_id automatically added from telemetry.currentAgentId)
telemetry.trackUserInput(msg, "user", currentModelId || "unknown");
if (!isSystemOnly && userTextForInput.length > 0) {
telemetry.trackUserInput(
userTextForInput,
"user",
currentModelId || "unknown",
);
}
// Block submission if waiting for explicit user action (approvals)
// In this case, input is hidden anyway, so this shouldn't happen
@@ -5275,11 +5377,15 @@ export default function App({
// so users can browse/view while the agent is working.
// Changes made in these overlays will be queued until end_turn.
const shouldBypassQueue =
isInteractiveCommand(msg) || isNonStateCommand(msg);
isInteractiveCommand(userTextForInput) ||
isNonStateCommand(userTextForInput);
if (isAgentBusy() && !shouldBypassQueue) {
setMessageQueue((prev) => {
const newQueue = [...prev, msg];
const newQueue: QueuedMessage[] = [
...prev,
{ kind: "user", text: msg },
];
const isSlashCommand = msg.startsWith("/");
@@ -5806,7 +5912,7 @@ export default function App({
{
type: "message",
role: "user",
content: `${systemMsg}\n\n${prompt}`,
content: buildTextParts(systemMsg, prompt),
},
]);
} else {
@@ -7183,7 +7289,7 @@ export default function App({
{
type: "message",
role: "user",
content: skillMessage,
content: buildTextParts(skillMessage),
},
]);
} catch (error) {
@@ -7241,9 +7347,12 @@ export default function App({
);
// Build system-reminder content for memory request
const rememberMessage = userText
? `${SYSTEM_REMINDER_OPEN}\n${REMEMBER_PROMPT}\n${SYSTEM_REMINDER_CLOSE}${userText}`
const rememberReminder = userText
? `${SYSTEM_REMINDER_OPEN}\n${REMEMBER_PROMPT}\n${SYSTEM_REMINDER_CLOSE}`
: `${SYSTEM_REMINDER_OPEN}\n${REMEMBER_PROMPT}\n\nThe user did not specify what to remember. Look at the recent conversation context to identify what they likely want you to remember, or ask them to clarify.\n${SYSTEM_REMINDER_CLOSE}`;
const rememberParts = userText
? buildTextParts(rememberReminder, userText)
: buildTextParts(rememberReminder);
// Mark command as finished before sending message
buffersRef.current.byId.set(cmdId, {
@@ -7263,7 +7372,7 @@ export default function App({
{
type: "message",
role: "user",
content: rememberMessage,
content: rememberParts,
},
]);
} catch (error) {
@@ -7436,7 +7545,7 @@ ${SYSTEM_REMINDER_CLOSE}`;
{
type: "message",
role: "user",
content: initMessage,
content: buildTextParts(initMessage),
},
]);
} catch (error) {
@@ -7519,7 +7628,9 @@ ${SYSTEM_REMINDER_CLOSE}`;
{
type: "message",
role: "user",
content: `${SYSTEM_REMINDER_OPEN}\n${prompt}\n${SYSTEM_REMINDER_CLOSE}`,
content: buildTextParts(
`${SYSTEM_REMINDER_OPEN}\n${prompt}\n${SYSTEM_REMINDER_CLOSE}`,
),
},
]);
} catch (error) {
@@ -7567,7 +7678,8 @@ ${SYSTEM_REMINDER_CLOSE}`;
}
// Build message content from display value (handles placeholders for text/images)
const contentParts = buildMessageContentFromDisplay(msg);
const contentParts =
overrideContentParts ?? buildMessageContentFromDisplay(msg);
// Prepend plan mode reminder if in plan mode
const planModeReminder = getPlanModeReminder();
@@ -7694,33 +7806,42 @@ ${SYSTEM_REMINDER_CLOSE}
lastNotifiedModeRef.current = currentMode;
}
// Combine reminders with content (session context first, then session start hook, then permission mode, then plan mode, then ralph mode, then skill unload, then bash commands, then hook feedback, then memory reminder, then memfs conflicts)
const allReminders =
sessionContextReminder +
sessionStartHookFeedback +
permissionModeAlert +
planModeReminder +
ralphModeReminder +
skillUnloadReminder +
bashCommandPrefix +
userPromptSubmitHookFeedback +
memoryReminderContent +
memfsConflictReminder;
// Combine reminders with content as separate text parts.
// This preserves each reminder boundary in the API payload.
// Note: Task notifications now come through messageQueue directly (added by messageQueueBridge)
const reminderParts: Array<{ type: "text"; text: string }> = [];
const pushReminder = (text: string) => {
if (!text) return;
reminderParts.push({ type: "text", text });
};
pushReminder(sessionContextReminder);
pushReminder(sessionStartHookFeedback);
pushReminder(permissionModeAlert);
pushReminder(planModeReminder);
pushReminder(ralphModeReminder);
pushReminder(skillUnloadReminder);
pushReminder(bashCommandPrefix);
pushReminder(userPromptSubmitHookFeedback);
pushReminder(memoryReminderContent);
pushReminder(memfsConflictReminder);
const messageContent =
allReminders && typeof contentParts === "string"
? allReminders + contentParts
: Array.isArray(contentParts) && allReminders
? [{ type: "text" as const, text: allReminders }, ...contentParts]
: contentParts;
reminderParts.length > 0
? [...reminderParts, ...contentParts]
: contentParts;
// Append task notifications (if any) as event lines before the user message
appendTaskNotificationEvents(taskNotifications);
// Append the user message to transcript IMMEDIATELY (optimistic update)
const userId = uid("user");
buffersRef.current.byId.set(userId, {
kind: "user",
id: userId,
text: msg,
});
buffersRef.current.order.push(userId);
if (userTextForInput) {
buffersRef.current.byId.set(userId, {
kind: "user",
id: userId,
text: userTextForInput,
});
buffersRef.current.order.push(userId);
}
// Reset token counter for this turn (only count the agent's response)
buffersRef.current.tokenCount = 0;
@@ -8334,6 +8455,7 @@ ${SYSTEM_REMINDER_CLOSE}
pendingRalphConfig,
openTrajectorySegment,
resetTrajectoryBases,
appendTaskNotificationEvents,
],
);
@@ -8343,14 +8465,18 @@ ${SYSTEM_REMINDER_CLOSE}
}, [onSubmit]);
// Process queued messages when streaming ends
// Task notifications are now added directly to messageQueue via messageQueueBridge
useEffect(() => {
// Reference dequeueEpoch to satisfy exhaustive-deps - it's used to force
// re-runs when userCancelledRef is reset (refs aren't in deps)
// Also triggers when task notifications are added to queue
void dequeueEpoch;
const hasAnythingQueued = messageQueue.length > 0;
if (
!streaming &&
messageQueue.length > 0 &&
hasAnythingQueued &&
pendingApprovals.length === 0 &&
!commandRunning &&
!isExecutingTool &&
@@ -8360,7 +8486,12 @@ ${SYSTEM_REMINDER_CLOSE}
) {
// Concatenate all queued messages into one (better UX when user types multiple
// messages quickly - they get combined into one context for the agent)
const concatenatedMessage = messageQueue.join("\n");
// Task notifications are already in the queue as XML strings
const concatenatedMessage = messageQueue
.map((item) => item.text)
.join("\n");
const queuedContentParts = buildQueuedContentParts(messageQueue);
debugLog(
"queue",
`Dequeuing ${messageQueue.length} message(s): "${concatenatedMessage.slice(0, 50)}${concatenatedMessage.length > 50 ? "..." : ""}"`,
@@ -8372,8 +8503,9 @@ ${SYSTEM_REMINDER_CLOSE}
// Submit the concatenated message using the normal submit flow
// This ensures all setup (reminders, UI updates, etc.) happens correctly
overrideContentPartsRef.current = queuedContentParts;
onSubmitRef.current(concatenatedMessage);
} else if (messageQueue.length > 0) {
} else if (hasAnythingQueued) {
// Log why dequeue was blocked (useful for debugging stuck queues)
debugLog(
"queue",
@@ -8387,7 +8519,7 @@ ${SYSTEM_REMINDER_CLOSE}
commandRunning,
isExecutingTool,
anySelectorOpen,
dequeueEpoch, // Triggered when userCancelledRef is reset while messages are queued
dequeueEpoch, // Triggered when userCancelledRef is reset OR task notifications added
]);
// Helper to send all approval results when done
@@ -8575,25 +8707,33 @@ ${SYSTEM_REMINDER_CLOSE}
waitingForQueueCancelRef.current = false;
queueSnapshotRef.current = [];
} else {
const queuedMessagesToAppend = consumeQueuedMessages();
const queuedItemsToAppend = consumeQueuedMessages();
const queuedNotifications = queuedItemsToAppend
? getQueuedNotificationSummaries(queuedItemsToAppend)
: [];
const hadNotifications =
appendTaskNotificationEvents(queuedNotifications);
const input: Array<MessageCreate | ApprovalCreate> = [
{ type: "approval", approvals: allResults as ApprovalResult[] },
];
if (queuedMessagesToAppend?.length) {
for (const msg of queuedMessagesToAppend) {
if (queuedItemsToAppend && queuedItemsToAppend.length > 0) {
const queuedUserText = buildQueuedUserText(queuedItemsToAppend);
if (queuedUserText) {
const userId = uid("user");
buffersRef.current.byId.set(userId, {
kind: "user",
id: userId,
text: msg,
text: queuedUserText,
});
buffersRef.current.order.push(userId);
input.push({
type: "message",
role: "user",
content: msg as unknown as MessageCreate["content"],
});
}
input.push({
type: "message",
role: "user",
content: buildQueuedContentParts(queuedItemsToAppend),
});
refreshDerived();
} else if (hadNotifications) {
refreshDerived();
}
toolResultsInFlightRef.current = true;
@@ -8627,6 +8767,7 @@ ${SYSTEM_REMINDER_CLOSE}
updateStreamingOutput,
queueApprovalResults,
consumeQueuedMessages,
appendTaskNotificationEvents,
syncTrajectoryElapsedBase,
closeTrajectorySegment,
openTrajectorySegment,

14
src/cli/components/EventMessage.tsx
View File

@@ -34,6 +34,20 @@ export const EventMessage = memo(({ line }: { line: EventLine }) => {
const columns = useTerminalWidth();
const rightWidth = Math.max(0, columns - 2);
if (line.eventType === "task_notification") {
const summary = line.summary || "Agent task completed";
return (
<Box flexDirection="row">
<Box width={2} flexShrink={0}>
<Text color={colors.tool.completed}>●</Text>
</Box>
<Box flexGrow={1} width={rightWidth}>
<Text bold>{summary}</Text>
</Box>
</Box>
);
}
// Only handle compaction events for now
if (line.eventType !== "compaction") {
return (

12
src/cli/components/InputRich.tsx
View File

@@ -24,6 +24,7 @@ import { OPENAI_CODEX_PROVIDER_NAME } from "../../providers/openai-codex-provide
import { ralphMode } from "../../ralph/mode";
import { settingsManager } from "../../settings-manager";
import { charsToTokens, formatCompact } from "../helpers/format";
import type { QueuedMessage } from "../helpers/messageQueueBridge";
import { useTerminalWidth } from "../hooks/useTerminalWidth";
import { colors } from "./colors";
import { InputAssist } from "./InputAssist";
@@ -236,7 +237,7 @@ export function Input({
agentName?: string | null;
currentModel?: string | null;
currentModelProvider?: string | null;
messageQueue?: string[];
messageQueue?: QueuedMessage[];
onEnterQueueEditMode?: () => void;
onEscapeCancel?: () => void;
ralphActive?: boolean;
@@ -548,7 +549,14 @@ export function Input({
) {
setAtStartBoundary(false);
// Clear the queue and load into input as one multi-line message
const queueText = messageQueue.join("\n");
const queueText = messageQueue
.filter((item) => item.kind === "user")
.map((item) => item.text.trim())
.filter((msg) => msg.length > 0)
.join("\n");
if (!queueText) {
return;
}
setValue(queueText);
// Signal to App.tsx to clear the queue
if (onEnterQueueEditMode) {

19
src/cli/components/QueuedMessages.tsx
View File

@@ -1,17 +1,26 @@
import { Box } from "ink";
import { memo } from "react";
import type { QueuedMessage } from "../helpers/messageQueueBridge";
import { Text } from "./Text";
interface QueuedMessagesProps {
messages: string[];
messages: QueuedMessage[];
}
export const QueuedMessages = memo(({ messages }: QueuedMessagesProps) => {
const maxDisplay = 5;
const displayMessages = messages
.filter((msg) => msg.kind === "user")
.map((msg) => msg.text.trim())
.filter((msg) => msg.length > 0);
if (displayMessages.length === 0) {
return null;
}
return (
<Box flexDirection="column" marginBottom={1}>
{messages.slice(0, maxDisplay).map((msg, index) => (
{displayMessages.slice(0, maxDisplay).map((msg, index) => (
<Box key={`${index}-${msg.slice(0, 50)}`} flexDirection="row">
<Box width={2} flexShrink={0}>
<Text dimColor>{">"}</Text>
@@ -22,11 +31,13 @@ export const QueuedMessages = memo(({ messages }: QueuedMessagesProps) => {
</Box>
))}
{messages.length > maxDisplay && (
{displayMessages.length > maxDisplay && (
<Box flexDirection="row">
<Box width={2} flexShrink={0} />
<Box flexGrow={1}>
<Text dimColor>...and {messages.length - maxDisplay} more</Text>
<Text dimColor>
...and {displayMessages.length - maxDisplay} more
</Text>
</Box>
</Box>
)}

14
src/cli/components/SubagentGroupDisplay.tsx
View File

@@ -111,8 +111,12 @@ const AgentRow = memo(
<Text dimColor>{" "}</Text>
{agent.status === "error" ? (
<Text color={colors.subagent.error}>Error</Text>
) : isComplete ? (
<Text dimColor>Done</Text>
) : agent.isBackground ? (
<Text dimColor>Running in the background</Text>
) : (
<Text dimColor>{isComplete ? "Done" : "Running..."}</Text>
<Text dimColor>Running...</Text>
)}
</Box>
</Box>
@@ -197,6 +201,14 @@ const AgentRow = memo(
</Text>
</Box>
</>
) : agent.isBackground ? (
<>
<Text color={colors.subagent.treeChar}>
{" "}
{continueChar}
</Text>
<Text dimColor>{" Running in the background"}</Text>
</>
) : lastTool ? (
<>
<Text color={colors.subagent.treeChar}>

15
src/cli/components/SubagentGroupStatic.tsx
View File

@@ -28,12 +28,13 @@ export interface StaticSubagent {
id: string;
type: string;
description: string;
status: "completed" | "error";
status: "completed" | "error" | "running";
toolCount: number;
totalTokens: number;
agentURL: string | null;
error?: string;
model?: string;
isBackground?: boolean;
}
interface SubagentGroupStaticProps {
@@ -91,7 +92,7 @@ const AgentRow = memo(({ agent, isLast }: AgentRowProps) => {
{/* Status line */}
<Box flexDirection="row">
{agent.status === "completed" ? (
{agent.status === "completed" && !agent.isBackground ? (
<>
<Text color={colors.subagent.treeChar}>
{" "}
@@ -99,7 +100,7 @@ const AgentRow = memo(({ agent, isLast }: AgentRowProps) => {
</Text>
<Text dimColor>{" Done"}</Text>
</>
) : (
) : agent.status === "error" ? (
<>
<Box width={gutterWidth} flexShrink={0}>
<Text>
@@ -116,6 +117,14 @@ const AgentRow = memo(({ agent, isLast }: AgentRowProps) => {
</Text>
</Box>
</>
) : (
<>
<Text color={colors.subagent.treeChar}>
{" "}
{continueChar}
</Text>
<Text dimColor>{" Running in the background"}</Text>
</>
)}
</Box>
</Box>

8
src/cli/components/ToolCallMessageRich.tsx
View File

@@ -10,6 +10,7 @@ import {
parsePatchInput,
parsePatchOperations,
} from "../helpers/formatArgsDisplay.js";
import { getSubagentByToolCallId } from "../helpers/subagentState.js";
import {
getDisplayToolName,
isFileEditTool,
@@ -112,6 +113,13 @@ export const ToolCallMessage = memo(
// and liveItems handles pending approvals via InlineGenericApproval)
if (isTaskTool(rawName)) {
const isFinished = line.phase === "finished";
const subagent = line.toolCallId
? getSubagentByToolCallId(line.toolCallId)
: undefined;
if (subagent) {
// Task tool calls with subagent data are handled by SubagentGroupDisplay/Static
return null;
}
if (!isFinished) {
// Not finished - SubagentGroupDisplay or approval UI handles this
return null;

13
src/cli/components/UserMessageRich.tsx
View File

@@ -1,6 +1,7 @@
import { memo } from "react";
import stringWidth from "string-width";
import { SYSTEM_REMINDER_CLOSE, SYSTEM_REMINDER_OPEN } from "../../constants";
import { extractTaskNotificationsForDisplay } from "../helpers/taskNotifications";
import { useTerminalWidth } from "../hooks/useTerminalWidth";
import { colors, hexToBgAnsi, hexToFgAnsi } from "./colors";
import { Text } from "./Text";
@@ -156,6 +157,11 @@ function renderBlock(
export const UserMessage = memo(({ line }: { line: UserLine }) => {
const columns = useTerminalWidth();
const contentWidth = Math.max(1, columns - 2);
const cleanedText = extractTaskNotificationsForDisplay(line.text).cleanedText;
const displayText = cleanedText.trim();
if (!displayText) {
return null;
}
// Build combined ANSI code for background + optional foreground
const { background, text: textColor } = colors.userMessage;
@@ -164,23 +170,20 @@ export const UserMessage = memo(({ line }: { line: UserLine }) => {
const colorAnsi = bgAnsi + fgAnsi;
// Split into system-reminder blocks and user content blocks
const blocks = splitSystemReminderBlocks(line.text);
const blocks = splitSystemReminderBlocks(displayText);
const allLines: string[] = [];
for (const block of blocks) {
if (!block.text.trim()) continue;
// Add blank line between blocks (not before first)
if (allLines.length > 0) {
allLines.push("");
}
const blockLines = renderBlock(
block.text,
contentWidth,
columns,
!block.isSystemReminder, // highlight user content, not system-reminder
!block.isSystemReminder,
colorAnsi,
);
allLines.push(...blockLines);

38
src/cli/helpers/backfill.ts
View File

@@ -7,6 +7,7 @@ import type {
} from "@letta-ai/letta-client/resources/agents/messages";
import { SYSTEM_REMINDER_CLOSE, SYSTEM_REMINDER_OPEN } from "../../constants";
import type { Buffers } from "./accumulator";
import { extractTaskNotificationsForDisplay } from "./taskNotifications";
/**
* Extract displayable text from tool return content.
@@ -178,9 +179,28 @@ export function backfillBuffers(buffers: Buffers, history: Message[]): void {
// user message - content parts may include text and image parts
case "user_message": {
const rawText = renderUserContentParts(msg.content);
const { notifications, cleanedText } =
extractTaskNotificationsForDisplay(rawText);
if (notifications.length > 0) {
let notifIndex = 0;
for (const summary of notifications) {
const notifId = `${lineId}-task-${notifIndex++}`;
const exists = buffers.byId.has(notifId);
buffers.byId.set(notifId, {
kind: "event",
id: notifId,
eventType: "task_notification",
eventData: {},
phase: "finished",
summary,
});
if (!exists) buffers.order.push(notifId);
}
}
// Check if this is a compaction summary message (old format embedded in user_message)
const compactionSummary = extractCompactionSummary(rawText);
const compactionSummary = extractCompactionSummary(cleanedText);
if (compactionSummary) {
// Render as a finished compaction event
const exists = buffers.byId.has(lineId);
@@ -196,13 +216,15 @@ export function backfillBuffers(buffers: Buffers, history: Message[]): void {
break;
}
const exists = buffers.byId.has(lineId);
buffers.byId.set(lineId, {
kind: "user",
id: lineId,
text: rawText,
});
if (!exists) buffers.order.push(lineId);
if (cleanedText) {
const exists = buffers.byId.has(lineId);
buffers.byId.set(lineId, {
kind: "user",
id: lineId,
text: cleanedText,
});
if (!exists) buffers.order.push(lineId);
}
break;
}

63
src/cli/helpers/messageQueueBridge.ts Normal file
View File

@@ -0,0 +1,63 @@
/**
* Message Queue Bridge
*
* Allows non-React code (like Task.ts) to add messages to the messageQueue.
* The queue adder function is set by App.tsx on mount.
*
* This enables background tasks to queue their notification XML directly
* into messageQueue, where the existing dequeue logic handles auto-firing.
*/
export type QueuedMessage = {
kind: "user" | "task_notification";
text: string;
};
type QueueAdder = (message: QueuedMessage) => void;
let queueAdder: QueueAdder | null = null;
const pendingMessages: QueuedMessage[] = [];
const MAX_PENDING_MESSAGES = 10;
/**
* Set the queue adder function. Called by App.tsx on mount.
*/
export function setMessageQueueAdder(fn: QueueAdder | null): void {
queueAdder = fn;
if (queueAdder && pendingMessages.length > 0) {
for (const message of pendingMessages) {
queueAdder(message);
}
pendingMessages.length = 0;
}
}
/**
* Add a message to the messageQueue.
* Called from Task.ts when a background task completes.
* If queue adder not set (App not mounted), message is dropped.
*/
export function addToMessageQueue(message: QueuedMessage): void {
if (queueAdder) {
queueAdder(message);
return;
}
if (pendingMessages.length >= MAX_PENDING_MESSAGES) {
pendingMessages.shift();
}
pendingMessages.push(message);
}
/**
* Check if the queue bridge is connected.
*/
export function isQueueBridgeConnected(): boolean {
return queueAdder !== null;
}
/**
* Clear any pending messages (for testing).
*/
export function clearPendingMessages(): void {
pendingMessages.length = 0;
}

44
src/cli/helpers/queuedMessageParts.ts Normal file
View File

@@ -0,0 +1,44 @@
import type { MessageCreate } from "@letta-ai/letta-client/resources/agents/agents";
import type { QueuedMessage } from "./messageQueueBridge";
import { buildMessageContentFromDisplay } from "./pasteRegistry";
import { extractTaskNotificationsForDisplay } from "./taskNotifications";
export function getQueuedNotificationSummaries(
queued: QueuedMessage[],
): string[] {
const summaries: string[] = [];
for (const item of queued) {
if (item.kind !== "task_notification") continue;
const parsed = extractTaskNotificationsForDisplay(item.text);
summaries.push(...parsed.notifications);
}
return summaries;
}
export function buildQueuedContentParts(
queued: QueuedMessage[],
): MessageCreate["content"] {
const parts: MessageCreate["content"] = [];
let isFirst = true;
for (const item of queued) {
if (!isFirst) {
parts.push({ type: "text", text: "\n" });
}
isFirst = false;
if (item.kind === "task_notification") {
parts.push({ type: "text", text: item.text });
continue;
}
const userParts = buildMessageContentFromDisplay(item.text);
parts.push(...userParts);
}
return parts;
}
export function buildQueuedUserText(queued: QueuedMessage[]): string {
return queued
.filter((item) => item.kind === "user")
.map((item) => item.text)
.filter((text) => text.length > 0)
.join("\n");
}

40
src/cli/helpers/subagentAggregation.ts
View File

@@ -5,7 +5,7 @@
import type { StaticSubagent } from "../components/SubagentGroupStatic.js";
import type { Line } from "./accumulator.js";
import { getSubagentByToolCallId } from "./subagentState.js";
import { getSubagentByToolCallId, getSubagents } from "./subagentState.js";
import { isTaskTool } from "./toolNameMapping.js";
/**
@@ -31,16 +31,37 @@ export interface SubagentGroupItem {
export function hasInProgressTaskToolCalls(
order: string[],
byId: Map<string, Line>,
emittedIds: Set<string>,
_emittedIds: Set<string>,
): boolean {
// If any foreground subagent is running, treat Task tools as in-progress.
// Background subagents shouldn't block grouping into the static area.
const hasForegroundRunning = getSubagents().some(
(agent) =>
!agent.isBackground &&
(agent.status === "pending" || agent.status === "running"),
);
if (hasForegroundRunning) {
return true;
}
for (const id of order) {
const ln = byId.get(id);
if (!ln) continue;
if (ln.kind === "tool_call" && isTaskTool(ln.name ?? "")) {
if (emittedIds.has(id)) continue;
if (ln.phase !== "finished") {
return true;
}
if (ln.toolCallId) {
const subagent = getSubagentByToolCallId(ln.toolCallId);
if (subagent) {
if (
!subagent.isBackground &&
(subagent.status === "pending" || subagent.status === "running")
) {
return true;
}
}
}
}
}
return false;
@@ -75,7 +96,13 @@ export function collectFinishedTaskToolCalls(
) {
// Check if we have subagent data in the state store
const subagent = getSubagentByToolCallId(ln.toolCallId);
if (subagent) {
if (
subagent &&
(subagent.status === "completed" ||
subagent.status === "error" ||
(subagent.isBackground &&
(subagent.status === "pending" || subagent.status === "running")))
) {
finished.push({
lineId: id,
toolCallId: ln.toolCallId,
@@ -103,12 +130,15 @@ export function createSubagentGroupItem(
id: subagent.id,
type: subagent.type,
description: subagent.description,
status: subagent.status as "completed" | "error",
status: subagent.isBackground
? "running"
: (subagent.status as "completed" | "error"),
toolCount: subagent.toolCalls.length,
totalTokens: subagent.totalTokens,
agentURL: subagent.agentURL,
error: subagent.error,
model: subagent.model,
isBackground: subagent.isBackground,
});
}
}

3
src/cli/helpers/subagentState.ts
View File

@@ -29,6 +29,7 @@ export interface SubagentState {
model?: string;
startTime: number;
toolCallId?: string; // Links this subagent to its parent Task tool call
isBackground?: boolean; // True if running in background (fire-and-forget)
}
interface SubagentStore {
@@ -106,6 +107,7 @@ export function registerSubagent(
type: string,
description: string,
toolCallId?: string,
isBackground?: boolean,
): void {
// Capitalize type for display (explore -> Explore)
const displayType = type.charAt(0).toUpperCase() + type.slice(1);
@@ -121,6 +123,7 @@ export function registerSubagent(
durationMs: 0,
startTime: Date.now(),
toolCallId,
isBackground,
};
store.agents.set(id, agent);

121
src/cli/helpers/taskNotifications.ts Normal file
View File

@@ -0,0 +1,121 @@
/**
* Task Notification Formatting
*
* Formats background task completion notifications as XML.
* The actual queueing is handled by messageQueueBridge.ts.
*/
// ============================================================================
// Types
// ============================================================================
export interface TaskNotification {
taskId: string;
status: "completed" | "failed";
summary: string;
result: string;
outputFile: string;
usage?: {
totalTokens?: number;
toolUses?: number;
durationMs?: number;
};
}
// ============================================================================
// XML Escaping
// ============================================================================
/**
* Escape special XML characters to prevent breaking the XML structure.
*/
function escapeXml(str: string): string {
return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
}
function unescapeXml(str: string): string {
return str.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&amp;/g, "&");
}
// ============================================================================
// Public API
// ============================================================================
/**
* Format a single notification as XML string for queueing.
*/
export function formatTaskNotification(notification: TaskNotification): string {
// Escape summary and result to prevent XML injection
const escapedSummary = escapeXml(notification.summary);
const escapedResult = escapeXml(notification.result);
const usageLines: string[] = [];
if (notification.usage?.totalTokens !== undefined) {
usageLines.push(`total_tokens: ${notification.usage.totalTokens}`);
}
if (notification.usage?.toolUses !== undefined) {
usageLines.push(`tool_uses: ${notification.usage.toolUses}`);
}
if (notification.usage?.durationMs !== undefined) {
usageLines.push(`duration_ms: ${notification.usage.durationMs}`);
}
const usageBlock = usageLines.length
? `\n<usage>${usageLines.join("\n")}</usage>`
: "";
return `<task-notification>
<task-id>${notification.taskId}</task-id>
<status>${notification.status}</status>
<summary>${escapedSummary}</summary>
<result>${escapedResult}</result>${usageBlock}
</task-notification>
Full transcript available at: ${notification.outputFile}`;
}
export function extractTaskNotificationsForDisplay(message: string): {
notifications: string[];
cleanedText: string;
} {
if (!message.includes("<task-notification>")) {
return { notifications: [], cleanedText: message };
}
const notificationRegex =
/<task-notification>[\s\S]*?(?:<\/task-notification>|$)(?:\s*Full transcript available at:[^\n]*\n?)?/g;
const notifications: string[] = [];
let match: RegExpExecArray | null = notificationRegex.exec(message);
while (match !== null) {
const xml = match[0];
const summaryMatch = xml.match(/<summary>([\s\S]*?)<\/summary>/);
const statusMatch = xml.match(/<status>([\s\S]*?)<\/status>/);
const status = statusMatch?.[1]?.trim();
let summary = summaryMatch?.[1]?.trim() || "";
summary = unescapeXml(summary);
const display = summary || `Agent task ${status || "completed"}`;
notifications.push(display);
match = notificationRegex.exec(message);
}
const cleanedText = message
.replace(notificationRegex, "")
.replace(/^\s*Full transcript available at:[^\n]*\n?/gm, "")
.replace(/\n{3,}/g, "\n\n")
.trim();
return { notifications, cleanedText };
}
/**
* Format multiple notifications as XML string.
* @deprecated Use formatTaskNotification and queue individually
*/
export function formatTaskNotifications(
notifications: TaskNotification[],
): string {
if (notifications.length === 0) {
return "";
}
return notifications.map(formatTaskNotification).join("\n\n");
}

60
src/headless.ts
View File

@@ -124,6 +124,7 @@ export async function handleHeadlessCommand(
"no-skills": { type: "boolean" },
memfs: { type: "boolean" },
"no-memfs": { type: "boolean" },
"max-turns": { type: "string" }, // Maximum number of agentic turns
},
strict: false,
allowPositionals: true,
@@ -262,6 +263,20 @@ export async function handleHeadlessCommand(
const memfsFlag = values.memfs as boolean | undefined;
const noMemfsFlag = values["no-memfs"] as boolean | undefined;
const fromAfFile = values["from-af"] as string | undefined;
const maxTurnsRaw = values["max-turns"] as string | undefined;
// Parse and validate max-turns if provided
let maxTurns: number | undefined;
if (maxTurnsRaw !== undefined) {
const parsed = parseInt(maxTurnsRaw, 10);
if (Number.isNaN(parsed) || parsed <= 0) {
console.error(
`Error: --max-turns must be a positive integer, got: ${maxTurnsRaw}`,
);
process.exit(1);
}
maxTurns = parsed;
}
// Handle --conv {agent-id} shorthand: --conv agent-xyz → --agent agent-xyz --conv default
if (specifiedConversationId?.startsWith("agent-")) {
@@ -1005,7 +1020,11 @@ export async function handleHeadlessCommand(
// Build message content with reminders (plan mode first, then skill unload)
const { permissionMode } = await import("./permissions/mode");
const { hasLoadedSkills } = await import("./agent/context");
let messageContent = "";
const contentParts: MessageCreate["content"] = [];
const pushPart = (text: string) => {
if (!text) return;
contentParts.push({ type: "text", text });
};
if (fromAgentId) {
const senderAgentId = fromAgentId;
@@ -1017,29 +1036,29 @@ If you need to share detailed information, include it in your response text.
${SYSTEM_REMINDER_CLOSE}
`;
messageContent += systemReminder;
pushPart(systemReminder);
}
// Add plan mode reminder if in plan mode (highest priority)
if (permissionMode.getMode() === "plan") {
const { PLAN_MODE_REMINDER } = await import("./agent/promptAssets");
messageContent += PLAN_MODE_REMINDER;
pushPart(PLAN_MODE_REMINDER);
}
// Add skill unload reminder if skills are loaded (using cached flag)
if (hasLoadedSkills()) {
const { SKILL_UNLOAD_REMINDER } = await import("./agent/promptAssets");
messageContent += SKILL_UNLOAD_REMINDER;
pushPart(SKILL_UNLOAD_REMINDER);
}
// Add user prompt
messageContent += prompt;
pushPart(prompt);
// Start with the user message
let currentInput: Array<MessageCreate | ApprovalCreate> = [
{
role: "user",
content: [{ type: "text", text: messageContent }],
content: contentParts,
},
];
@@ -1047,12 +1066,35 @@ ${SYSTEM_REMINDER_CLOSE}
let lastKnownRunId: string | null = null;
let llmApiErrorRetries = 0;
let conversationBusyRetries = 0;
markMilestone("HEADLESS_FIRST_STREAM_START");
measureSinceMilestone("headless-setup-total", "HEADLESS_CLIENT_READY");
// Helper to check max turns limit using server-side step count from buffers
const checkMaxTurns = () => {
if (maxTurns !== undefined && buffers.usage.stepCount >= maxTurns) {
if (outputFormat === "stream-json") {
const errorMsg: ErrorMessage = {
type: "error",
message: `Maximum turns limit reached (${buffers.usage.stepCount}/${maxTurns} steps)`,
stop_reason: "max_steps",
session_id: sessionId,
uuid: `error-max-turns-${crypto.randomUUID()}`,
};
console.log(JSON.stringify(errorMsg));
} else {
console.error(
`Maximum turns limit reached (${buffers.usage.stepCount}/${maxTurns} steps)`,
);
}
process.exit(1);
}
};
try {
while (true) {
// Check max turns limit before starting a new turn (uses server-side step count)
checkMaxTurns();
// Wrap sendMessageStream in try-catch to handle pre-stream errors (e.g., 409)
let stream: Awaited<ReturnType<typeof sendMessageStream>>;
try {
@@ -1283,6 +1325,10 @@ ${SYSTEM_REMINDER_CLOSE}
// Track API duration for this stream
sessionStats.endTurn(apiDurationMs);
// Check max turns after each turn (server may have taken multiple steps)
checkMaxTurns();
if (approvalPendingRecovery) {
await resolveAllPendingApprovals();
continue;

82
src/tests/cli/queuedMessageParts.test.ts Normal file
View File

@@ -0,0 +1,82 @@
import { describe, expect, test } from "bun:test";
import type { QueuedMessage } from "../../cli/helpers/messageQueueBridge";
import { allocateImage } from "../../cli/helpers/pasteRegistry";
import {
buildQueuedContentParts,
buildQueuedUserText,
getQueuedNotificationSummaries,
} from "../../cli/helpers/queuedMessageParts";
import { formatTaskNotification } from "../../cli/helpers/taskNotifications";
describe("queuedMessageParts", () => {
test("buildQueuedUserText only concatenates user messages", () => {
const queued: QueuedMessage[] = [
{ kind: "user", text: "hello" },
{
kind: "task_notification",
text: "<task-notification><summary>Agent done</summary></task-notification>",
},
{ kind: "user", text: "world" },
];
expect(buildQueuedUserText(queued)).toBe("hello\nworld");
});
test("buildQueuedContentParts preserves boundaries and images", () => {
const imageId = allocateImage({
data: "ZmFrZQ==",
mediaType: "image/png",
});
const userText = `before [Image #${imageId}] after`;
const notificationXml = formatTaskNotification({
taskId: "task_1",
status: "completed",
summary: 'Agent "Test" completed',
result: "Result line",
outputFile: "/tmp/task_1.log",
});
const queued: QueuedMessage[] = [
{ kind: "user", text: userText },
{ kind: "task_notification", text: notificationXml },
{ kind: "user", text: "second" },
];
const parts = buildQueuedContentParts(queued);
expect(parts).toHaveLength(7);
expect(parts[0]).toEqual({ type: "text", text: "before " });
expect(parts[1]).toEqual({
type: "image",
source: {
type: "base64",
media_type: "image/png",
data: "ZmFrZQ==",
},
});
expect(parts[2]).toEqual({ type: "text", text: " after" });
expect(parts[3]).toEqual({ type: "text", text: "\n" });
expect(parts[4]).toEqual({ type: "text", text: notificationXml });
expect(parts[5]).toEqual({ type: "text", text: "\n" });
expect(parts[6]).toEqual({ type: "text", text: "second" });
});
test("getQueuedNotificationSummaries extracts summaries", () => {
const notificationXml = formatTaskNotification({
taskId: "task_2",
status: "completed",
summary: 'Agent "Explore" completed',
result: "Done",
outputFile: "/tmp/task_2.log",
});
const queued: QueuedMessage[] = [
{ kind: "user", text: "hi" },
{ kind: "task_notification", text: notificationXml },
];
expect(getQueuedNotificationSummaries(queued)).toEqual([
'Agent "Explore" completed',
]);
});
});

216
src/tests/cli/taskNotifications.test.ts Normal file
View File

@@ -0,0 +1,216 @@
import { beforeEach, describe, expect, test } from "bun:test";
import {
addToMessageQueue,
clearPendingMessages,
isQueueBridgeConnected,
type QueuedMessage,
setMessageQueueAdder,
} from "../../cli/helpers/messageQueueBridge";
import {
formatTaskNotification,
formatTaskNotifications,
type TaskNotification,
} from "../../cli/helpers/taskNotifications";
describe("taskNotifications", () => {
describe("formatTaskNotification", () => {
test("formats single notification correctly", () => {
const notification: TaskNotification = {
taskId: "task_1",
status: "completed",
summary: 'Agent "Find files" completed',
result: "Found 5 files in src/",
outputFile: "/tmp/task_1.log",
};
const formatted = formatTaskNotification(notification);
expect(formatted).toContain("<task-notification>");
expect(formatted).toContain("<task-id>task_1</task-id>");
expect(formatted).toContain("<status>completed</status>");
expect(formatted).toContain(
'<summary>Agent "Find files" completed</summary>',
);
expect(formatted).toContain("<result>Found 5 files in src/</result>");
expect(formatted).toContain("</task-notification>");
expect(formatted).toContain(
"Full transcript available at: /tmp/task_1.log",
);
});
test("escapes XML special characters in summary", () => {
const notification: TaskNotification = {
taskId: "task_1",
status: "completed",
summary: 'Agent <script>alert("xss")</script> completed',
result: "Normal result",
outputFile: "/tmp/task_1.log",
};
const formatted = formatTaskNotification(notification);
// Quotes don't need escaping in XML text content, only in attributes
expect(formatted).toContain('&lt;script&gt;alert("xss")&lt;/script&gt;');
expect(formatted).not.toContain("<script>");
});
test("escapes XML special characters in result", () => {
const notification: TaskNotification = {
taskId: "task_1",
status: "completed",
summary: "Agent completed",
result: "Found items: <item1> & <item2>",
outputFile: "/tmp/task_1.log",
};
const formatted = formatTaskNotification(notification);
expect(formatted).toContain("&lt;item1&gt; &amp; &lt;item2&gt;");
expect(formatted).not.toContain("<item1>");
});
test("handles multiline results", () => {
const notification: TaskNotification = {
taskId: "task_1",
status: "completed",
summary: 'Agent "Search" completed',
result: "Line 1\nLine 2\nLine 3",
outputFile: "/tmp/task_1.log",
};
const formatted = formatTaskNotification(notification);
expect(formatted).toContain("<result>Line 1\nLine 2\nLine 3</result>");
});
test("handles failed status", () => {
const notification: TaskNotification = {
taskId: "task_1",
status: "failed",
summary: 'Agent "Test" failed',
result: "Error: Something went wrong",
outputFile: "/tmp/task_1.log",
};
const formatted = formatTaskNotification(notification);
expect(formatted).toContain("<status>failed</status>");
});
test("includes usage when provided", () => {
const notification: TaskNotification = {
taskId: "task_1",
status: "completed",
summary: 'Agent "Test" completed',
result: "Result",
outputFile: "/tmp/task_1.log",
usage: {
totalTokens: 123,
toolUses: 4,
durationMs: 5678,
},
};
const formatted = formatTaskNotification(notification);
expect(formatted).toContain("<usage>");
expect(formatted).toContain("total_tokens: 123");
expect(formatted).toContain("tool_uses: 4");
expect(formatted).toContain("duration_ms: 5678");
expect(formatted).toContain("</usage>");
});
});
describe("formatTaskNotifications", () => {
test("formats multiple notifications", () => {
const notifications: TaskNotification[] = [
{
taskId: "task_1",
status: "completed",
summary: 'Agent "Task1" completed',
result: "Result 1",
outputFile: "/tmp/task_1.log",
},
{
taskId: "task_2",
status: "failed",
summary: 'Agent "Task2" failed',
result: "Error occurred",
outputFile: "/tmp/task_2.log",
},
];
const formatted = formatTaskNotifications(notifications);
// Should have two notification blocks
expect(formatted.split("<task-notification>").length).toBe(3); // 2 blocks + 1 empty prefix
expect(formatted).toContain("<task-id>task_1</task-id>");
expect(formatted).toContain("<task-id>task_2</task-id>");
expect(formatted).toContain("<status>completed</status>");
expect(formatted).toContain("<status>failed</status>");
});
test("returns empty string for empty array", () => {
const formatted = formatTaskNotifications([]);
expect(formatted).toBe("");
});
});
});
describe("messageQueueBridge", () => {
// Reset the bridge before each test
beforeEach(() => {
setMessageQueueAdder(null);
clearPendingMessages();
});
test("isQueueBridgeConnected returns false when not set", () => {
expect(isQueueBridgeConnected()).toBe(false);
});
test("isQueueBridgeConnected returns true when set", () => {
setMessageQueueAdder(() => {});
expect(isQueueBridgeConnected()).toBe(true);
});
test("addToMessageQueue calls the adder when set", () => {
const messages: QueuedMessage[] = [];
setMessageQueueAdder((msg) => messages.push(msg));
addToMessageQueue({ kind: "user", text: "test message 1" });
addToMessageQueue({ kind: "user", text: "test message 2" });
expect(messages).toEqual([
{ kind: "user", text: "test message 1" },
{ kind: "user", text: "test message 2" },
]);
});
test("addToMessageQueue does nothing when adder not set", () => {
// Should not throw
expect(() =>
addToMessageQueue({ kind: "user", text: "test message" }),
).not.toThrow();
});
test("addToMessageQueue buffers until adder is set", () => {
const messages: QueuedMessage[] = [];
addToMessageQueue({ kind: "user", text: "early message" });
setMessageQueueAdder((msg) => messages.push(msg));
expect(messages).toEqual([{ kind: "user", text: "early message" }]);
});
test("setMessageQueueAdder can be cleared", () => {
const messages: QueuedMessage[] = [];
setMessageQueueAdder((msg) => messages.push(msg));
addToMessageQueue({ kind: "user", text: "message 1" });
setMessageQueueAdder(null);
addToMessageQueue({ kind: "user", text: "message 2" }); // Should be dropped
expect(messages).toEqual([{ kind: "user", text: "message 1" }]);
expect(isQueueBridgeConnected()).toBe(false);
});
});

39
src/tests/tools/bash-background.test.ts
View File

@@ -1,7 +1,9 @@
import { describe, expect, test } from "bun:test";
import * as fs from "node:fs";
import { bash } from "../../tools/impl/Bash";
import { bash_output } from "../../tools/impl/BashOutput";
import { kill_bash } from "../../tools/impl/KillBash";
import { backgroundProcesses } from "../../tools/impl/process_manager";
const isWindows = process.platform === "win32";
@@ -68,4 +70,41 @@ describe.skipIf(isWindows)("Bash background tools", () => {
expect(result.killed).toBe(false);
});
test("background process returns output file path", async () => {
const result = await bash({
command: "echo 'test'",
description: "Test output file",
run_in_background: true,
});
expect(result.content[0]?.text).toContain("Output file:");
expect(result.content[0]?.text).toMatch(/\.log$/);
});
test("background process writes to output file", async () => {
const startResult = await bash({
command: "echo 'file output test'",
description: "Test file writing",
run_in_background: true,
});
// Extract bash ID and get the output file path
const match = startResult.content[0]?.text.match(/bash_(\d+)/);
expect(match).toBeDefined();
const bashId = `bash_${match?.[1]}`;
// Wait for command to complete
await new Promise((resolve) => setTimeout(resolve, 300));
// Get the output file path from the background process
const bgProcess = backgroundProcesses.get(bashId);
expect(bgProcess?.outputFile).toBeDefined();
// Read the file and verify content
const outputFile = bgProcess?.outputFile;
expect(outputFile).toBeDefined();
const fileContent = fs.readFileSync(outputFile as string, "utf-8");
expect(fileContent).toContain("file output test");
});
});

394
src/tests/tools/task-background.test.ts Normal file
View File

@@ -0,0 +1,394 @@
import { afterEach, describe, expect, test } from "bun:test";
import * as fs from "node:fs";
import {
appendToOutputFile,
type BackgroundTask,
backgroundTasks,
createBackgroundOutputFile,
getNextTaskId,
} from "../../tools/impl/process_manager";
import { task_output } from "../../tools/impl/TaskOutput";
import { task_stop } from "../../tools/impl/TaskStop";
/**
* Tests for Task background execution infrastructure.
*
* Since the full task() function requires subagent infrastructure,
* these tests verify the background task tracking, output file handling,
* and integration with TaskOutput/TaskStop tools.
*/
describe("Task background infrastructure", () => {
// Clean up after each test
afterEach(() => {
// Clear all background tasks
backgroundTasks.clear();
});
test("getNextTaskId generates sequential IDs", () => {
const id1 = getNextTaskId();
const id2 = getNextTaskId();
const id3 = getNextTaskId();
expect(id1).toMatch(/^task_\d+$/);
expect(id2).toMatch(/^task_\d+$/);
expect(id3).toMatch(/^task_\d+$/);
// Extract numbers and verify they're sequential
const num1 = parseInt(id1.replace("task_", ""), 10);
const num2 = parseInt(id2.replace("task_", ""), 10);
const num3 = parseInt(id3.replace("task_", ""), 10);
expect(num2).toBe(num1 + 1);
expect(num3).toBe(num2 + 1);
});
test("createBackgroundOutputFile creates file and returns path", () => {
const taskId = getNextTaskId();
const outputFile = createBackgroundOutputFile(taskId);
expect(outputFile).toContain(taskId);
expect(outputFile).toMatch(/\.log$/);
expect(fs.existsSync(outputFile)).toBe(true);
// Clean up
fs.unlinkSync(outputFile);
});
test("appendToOutputFile writes content to file", () => {
const taskId = getNextTaskId();
const outputFile = createBackgroundOutputFile(taskId);
appendToOutputFile(outputFile, "First line\n");
appendToOutputFile(outputFile, "Second line\n");
const content = fs.readFileSync(outputFile, "utf-8");
expect(content).toBe("First line\nSecond line\n");
// Clean up
fs.unlinkSync(outputFile);
});
test("backgroundTasks map stores and retrieves tasks", () => {
const taskId = "task_test_1";
const outputFile = createBackgroundOutputFile(taskId);
const bgTask: BackgroundTask = {
description: "Test task",
subagentType: "explore",
subagentId: "subagent_1",
status: "running",
output: [],
startTime: new Date(),
outputFile,
abortController: new AbortController(),
};
backgroundTasks.set(taskId, bgTask);
expect(backgroundTasks.has(taskId)).toBe(true);
expect(backgroundTasks.get(taskId)?.description).toBe("Test task");
expect(backgroundTasks.get(taskId)?.status).toBe("running");
// Clean up
fs.unlinkSync(outputFile);
});
});
describe("TaskOutput with background tasks", () => {
afterEach(() => {
backgroundTasks.clear();
});
test("TaskOutput retrieves output from background task", async () => {
const taskId = "task_output_test_1";
const outputFile = createBackgroundOutputFile(taskId);
const bgTask: BackgroundTask = {
description: "Test retrieval",
subagentType: "explore",
subagentId: "subagent_2",
status: "completed",
output: ["Task completed successfully", "Found 5 files"],
startTime: new Date(),
outputFile,
};
backgroundTasks.set(taskId, bgTask);
const result = await task_output({
task_id: taskId,
block: false,
timeout: 1000,
});
expect(result.message).toContain("Task completed successfully");
expect(result.message).toContain("Found 5 files");
expect(result.status).toBe("completed");
// Clean up
fs.unlinkSync(outputFile);
});
test("TaskOutput includes error in output", async () => {
const taskId = "task_error_test";
const outputFile = createBackgroundOutputFile(taskId);
const bgTask: BackgroundTask = {
description: "Test error",
subagentType: "general-purpose",
subagentId: "subagent_3",
status: "failed",
output: ["Started processing"],
error: "Connection timeout",
startTime: new Date(),
outputFile,
};
backgroundTasks.set(taskId, bgTask);
const result = await task_output({
task_id: taskId,
block: false,
timeout: 1000,
});
expect(result.message).toContain("Started processing");
expect(result.message).toContain("Connection timeout");
expect(result.status).toBe("failed");
// Clean up
fs.unlinkSync(outputFile);
});
test("TaskOutput with block=true waits for task completion", async () => {
const taskId = "task_block_test";
const outputFile = createBackgroundOutputFile(taskId);
const bgTask: BackgroundTask = {
description: "Test blocking",
subagentType: "explore",
subagentId: "subagent_4",
status: "running",
output: [],
startTime: new Date(),
outputFile,
};
backgroundTasks.set(taskId, bgTask);
// Simulate task completing after 200ms
setTimeout(() => {
bgTask.status = "completed";
bgTask.output.push("Task finished");
}, 200);
const startTime = Date.now();
const result = await task_output({
task_id: taskId,
block: true,
timeout: 5000,
});
const elapsed = Date.now() - startTime;
// Should have waited for the task to complete
expect(elapsed).toBeGreaterThanOrEqual(150);
expect(result.status).toBe("completed");
expect(result.message).toContain("Task finished");
// Clean up
fs.unlinkSync(outputFile);
});
test("TaskOutput respects timeout when blocking", async () => {
const taskId = "task_timeout_test";
const outputFile = createBackgroundOutputFile(taskId);
const bgTask: BackgroundTask = {
description: "Test timeout",
subagentType: "explore",
subagentId: "subagent_5",
status: "running",
output: ["Still running..."],
startTime: new Date(),
outputFile,
};
backgroundTasks.set(taskId, bgTask);
const startTime = Date.now();
const result = await task_output({
task_id: taskId,
block: true,
timeout: 300, // Short timeout
});
const elapsed = Date.now() - startTime;
// Should have timed out around 300ms
expect(elapsed).toBeGreaterThanOrEqual(250);
expect(elapsed).toBeLessThan(1000);
expect(result.status).toBe("running"); // Still running after timeout
// Clean up
fs.unlinkSync(outputFile);
});
test("TaskOutput handles non-existent task_id", async () => {
const result = await task_output({
task_id: "nonexistent_task",
block: false,
timeout: 1000,
});
expect(result.message).toContain("No background process found");
});
});
describe("TaskStop with background tasks", () => {
afterEach(() => {
backgroundTasks.clear();
});
test("TaskStop aborts running task", async () => {
const taskId = "task_stop_test";
const outputFile = createBackgroundOutputFile(taskId);
const abortController = new AbortController();
const bgTask: BackgroundTask = {
description: "Test abort",
subagentType: "general-purpose",
subagentId: "subagent_6",
status: "running",
output: [],
startTime: new Date(),
outputFile,
abortController,
};
backgroundTasks.set(taskId, bgTask);
// Verify task is running
expect(bgTask.status).toBe("running");
expect(abortController.signal.aborted).toBe(false);
// Stop the task
const result = await task_stop({ task_id: taskId });
expect(result.killed).toBe(true);
expect(bgTask.status).toBe("failed");
expect(bgTask.error).toBe("Aborted by user");
expect(abortController.signal.aborted).toBe(true);
// Clean up
fs.unlinkSync(outputFile);
});
test("TaskStop returns false for completed task", async () => {
const taskId = "task_stop_completed";
const outputFile = createBackgroundOutputFile(taskId);
const bgTask: BackgroundTask = {
description: "Completed task",
subagentType: "explore",
subagentId: "subagent_7",
status: "completed",
output: ["Done"],
startTime: new Date(),
outputFile,
};
backgroundTasks.set(taskId, bgTask);
// Try to stop completed task
const result = await task_stop({ task_id: taskId });
expect(result.killed).toBe(false);
expect(bgTask.status).toBe("completed"); // Status unchanged
// Clean up
fs.unlinkSync(outputFile);
});
test("TaskStop returns false for task without abortController", async () => {
const taskId = "task_stop_no_abort";
const outputFile = createBackgroundOutputFile(taskId);
const bgTask: BackgroundTask = {
description: "Task without abort",
subagentType: "explore",
subagentId: "subagent_8",
status: "running",
output: [],
startTime: new Date(),
outputFile,
// No abortController
};
backgroundTasks.set(taskId, bgTask);
const result = await task_stop({ task_id: taskId });
expect(result.killed).toBe(false);
// Clean up
fs.unlinkSync(outputFile);
});
test("TaskStop handles non-existent task_id", async () => {
const result = await task_stop({ task_id: "nonexistent_task" });
expect(result.killed).toBe(false);
});
});
describe("Output file integration", () => {
afterEach(() => {
backgroundTasks.clear();
});
test("Output file contains task progress", () => {
const taskId = "task_file_test";
const outputFile = createBackgroundOutputFile(taskId);
// Simulate the output that Task.ts writes
appendToOutputFile(outputFile, `[Task started: Find auth code]\n`);
appendToOutputFile(outputFile, `[subagent_type: explore]\n\n`);
appendToOutputFile(
outputFile,
`subagent_type=explore agent_id=agent-123\n\n`,
);
appendToOutputFile(outputFile, `Found authentication code in src/auth/\n`);
appendToOutputFile(outputFile, `\n[Task completed]\n`);
const content = fs.readFileSync(outputFile, "utf-8");
expect(content).toContain("[Task started: Find auth code]");
expect(content).toContain("[subagent_type: explore]");
expect(content).toContain("agent_id=agent-123");
expect(content).toContain("Found authentication code");
expect(content).toContain("[Task completed]");
// Clean up
fs.unlinkSync(outputFile);
});
test("Output file contains error information", () => {
const taskId = "task_file_error";
const outputFile = createBackgroundOutputFile(taskId);
// Simulate error output
appendToOutputFile(outputFile, `[Task started: Complex analysis]\n`);
appendToOutputFile(outputFile, `[subagent_type: general-purpose]\n\n`);
appendToOutputFile(outputFile, `[error] Model rate limit exceeded\n`);
appendToOutputFile(outputFile, `\n[Task failed]\n`);
const content = fs.readFileSync(outputFile, "utf-8");
expect(content).toContain("[Task started: Complex analysis]");
expect(content).toContain("[error] Model rate limit exceeded");
expect(content).toContain("[Task failed]");
// Clean up
fs.unlinkSync(outputFile);
});
});

167
src/tests/tools/task-output.test.ts Normal file
View File

@@ -0,0 +1,167 @@
import { describe, expect, test } from "bun:test";
import { bash } from "../../tools/impl/Bash";
import { backgroundProcesses } from "../../tools/impl/process_manager";
import { task_output } from "../../tools/impl/TaskOutput";
import { task_stop } from "../../tools/impl/TaskStop";
const isWindows = process.platform === "win32";
describe.skipIf(isWindows)("TaskOutput and TaskStop", () => {
test("TaskOutput with block=false returns immediately without waiting", async () => {
// Start a slow background process
const startResult = await bash({
command: "sleep 2 && echo 'done'",
description: "Slow process",
run_in_background: true,
});
const match = startResult.content[0]?.text.match(/bash_(\d+)/);
expect(match).toBeDefined();
const taskId = `bash_${match?.[1]}`;
// Non-blocking call should return immediately
const startTime = Date.now();
const result = await task_output({
task_id: taskId,
block: false,
timeout: 30000,
});
const elapsed = Date.now() - startTime;
// Should return in less than 500ms (not waiting for 2s sleep)
expect(elapsed).toBeLessThan(500);
expect(result.status).toBe("running");
// Cleanup
await task_stop({ task_id: taskId });
});
test("TaskOutput with block=true waits for completion", async () => {
// Start a quick background process
const startResult = await bash({
command: "sleep 0.3 && echo 'completed'",
description: "Quick process",
run_in_background: true,
});
const match = startResult.content[0]?.text.match(/bash_(\d+)/);
expect(match).toBeDefined();
const taskId = `bash_${match?.[1]}`;
// Blocking call should wait for completion
const result = await task_output({
task_id: taskId,
block: true,
timeout: 5000,
});
// Should have waited and gotten the output
expect(result.message).toContain("completed");
expect(result.status).toBe("completed");
});
test("TaskOutput respects timeout when blocking", async () => {
// Start a long-running process
const startResult = await bash({
command: "sleep 10",
description: "Long process",
run_in_background: true,
});
const match = startResult.content[0]?.text.match(/bash_(\d+)/);
expect(match).toBeDefined();
const taskId = `bash_${match?.[1]}`;
// Block with short timeout
const startTime = Date.now();
const result = await task_output({
task_id: taskId,
block: true,
timeout: 300, // 300ms timeout
});
const elapsed = Date.now() - startTime;
// Should have timed out around 300ms, not waited for 10s
expect(elapsed).toBeLessThan(1000);
expect(elapsed).toBeGreaterThanOrEqual(250); // Allow some tolerance
expect(result.status).toBe("running"); // Still running after timeout
// Cleanup
await task_stop({ task_id: taskId });
});
test("TaskOutput handles non-existent task_id", async () => {
const result = await task_output({
task_id: "nonexistent_task",
block: false,
timeout: 1000,
});
expect(result.message).toContain("No background process found");
});
test("TaskStop terminates process using task_id", async () => {
// Start long-running process
const startResult = await bash({
command: "sleep 10",
description: "Process to kill",
run_in_background: true,
});
const match = startResult.content[0]?.text.match(/bash_(\d+)/);
const taskId = `bash_${match?.[1]}`;
// Kill using task_id
const killResult = await task_stop({ task_id: taskId });
expect(killResult.killed).toBe(true);
// Verify process is gone
expect(backgroundProcesses.has(taskId)).toBe(false);
});
test("TaskStop supports deprecated shell_id parameter", async () => {
// Start long-running process
const startResult = await bash({
command: "sleep 10",
description: "Process to kill",
run_in_background: true,
});
const match = startResult.content[0]?.text.match(/bash_(\d+)/);
const shellId = `bash_${match?.[1]}`;
// Kill using deprecated shell_id
const killResult = await task_stop({ shell_id: shellId });
expect(killResult.killed).toBe(true);
});
test("TaskStop handles non-existent task_id", async () => {
const result = await task_stop({ task_id: "nonexistent" });
expect(result.killed).toBe(false);
});
test("TaskOutput defaults to block=true", async () => {
// Start a quick background process
const startResult = await bash({
command: "sleep 0.2 && echo 'default-block-test'",
description: "Default block test",
run_in_background: true,
});
const match = startResult.content[0]?.text.match(/bash_(\d+)/);
const taskId = `bash_${match?.[1]}`;
// Call without specifying block - should default to true
const result = await task_output({
task_id: taskId,
timeout: 5000,
});
// Should have waited and gotten the output
expect(result.message).toContain("default-block-test");
expect(result.status).toBe("completed");
});
});

3
src/tools/descriptions/AskUserQuestion.md
View File

@@ -9,3 +9,6 @@ Use this tool when you need to ask the user questions during execution. This all
Usage notes:
- Users will always be able to select "Other" to provide custom text input
- Use multiSelect: true to allow multiple answers to be selected for a question
- If you recommend a specific option, make that the first option in the list and add "(Recommended)" at the end of the label
Plan mode note: In plan mode, use this tool to clarify requirements or choose between approaches BEFORE finalizing your plan. Do NOT use this tool to ask "Is my plan ready?" or "Should I proceed?" - use ExitPlanMode for plan approval.

16
src/tools/descriptions/Bash.md
View File

@@ -23,9 +23,9 @@ Before executing the command, please follow these steps:
Usage notes:
- The command argument is required.
- You can specify an optional timeout in milliseconds (up to 600000ms / 10 minutes). If not specified, commands will timeout after 120000ms (2 minutes).
- It is very helpful if you write a clear, concise description of what this command does in 5-10 words.
- It is very helpful if you write a clear, concise description of what this command does. For simple commands, keep it brief (5-10 words). For complex commands (piped commands, obscure flags, or anything hard to understand at a glance), add enough context to clarify what it does.
- If the output exceeds 30000 characters, output will be truncated before being returned to you.
- You can use the `run_in_background` parameter to run the command in the background, which allows you to continue working while the command runs. You can monitor the output using the Bash tool as it becomes available. You do not need to use '&' at the end of the command when using this parameter.
- You can use the `run_in_background` parameter to run the command in the background. Only use this if you don't need the result immediately and are OK being notified when the command completes later. You do not need to check the output right away - you'll be notified when it finishes. You do not need to use '&' at the end of the command when using this parameter.
- Avoid using Bash with the `find`, `grep`, `cat`, `head`, `tail`, `sed`, `awk`, or `echo` commands, unless explicitly instructed or when these commands are truly necessary for the task. Instead, always prefer using the dedicated tools for these commands:
- File search: Use Glob (NOT find or ls)
@@ -56,12 +56,12 @@ Git Safety Protocol:
- NEVER run destructive/irreversible git commands (like push --force, hard reset, etc) unless the user explicitly requests them
- NEVER skip hooks (--no-verify, --no-gpg-sign, etc) unless the user explicitly requests it
- NEVER run force push to main/master, warn the user if they request it
- Avoid git commit --amend. ONLY use --amend when either (1) user explicitly requested amend OR (2) adding edits from pre-commit hook (additional instructions below)
- Before amending: ALWAYS check authorship (git log -1 --format='%an %ae')
- CRITICAL: Always create NEW commits rather than amending, unless the user explicitly requests a git amend. When a pre-commit hook fails, the commit did NOT happen — so --amend would modify the PREVIOUS commit, which may result in destroying work or losing previous changes. Instead, after hook failure, fix the issue, re-stage, and create a NEW commit
- When staging files, prefer adding specific files by name rather than using "git add -A" or "git add .", which can accidentally include sensitive files (.env, credentials) or large binaries
- NEVER commit changes unless the user explicitly asks you to. It is VERY IMPORTANT to only commit when explicitly asked, otherwise the user will feel that you are being too proactive.
1. You can call multiple tools in a single response. When multiple independent pieces of information are requested and all commands are likely to succeed, run multiple tool calls in parallel for optimal performance. run the following bash commands in parallel, each using the Bash tool:
- Run a git status command to see all untracked files.
- Run a git status command to see all untracked files. IMPORTANT: Never use the -uall flag as it can cause memory issues on large repos.
- Run a git diff command to see both staged and unstaged changes that will be committed.
- Run a git log command to see recent commit messages, so that you can follow this repository's commit message style.
2. Analyze all staged changes (both previously staged and newly added) and draft a commit message:
@@ -77,16 +77,14 @@ Git Safety Protocol:
Co-Authored-By: Letta <noreply@letta.com>
- Run git status after the commit completes to verify success.
Note: git status depends on the commit completing, so run it sequentially after the commit.
4. If the commit fails due to pre-commit hook changes, retry ONCE. If it succeeds but files were modified by the hook, verify it's safe to amend:
- Check authorship: git log -1 --format='%an %ae'
- Check not pushed: git status shows "Your branch is ahead"
- If both true: amend your commit. Otherwise: create NEW commit (never amend other developers' commits)
4. If the commit fails due to pre-commit hook: fix the issue and create a NEW commit
Important notes:
- NEVER run additional commands to read or explore code, besides git bash commands
- NEVER use the TodoWrite or Task tools
- DO NOT push to the remote repository unless the user explicitly asks you to do so
- IMPORTANT: Never use git commands with the -i flag (like git rebase -i or git add -i) since they require interactive input which is not supported.
- IMPORTANT: Do not use --no-edit with git rebase commands, as the --no-edit flag is not a valid option for git rebase.
- If there are no changes to commit (i.e., no untracked files and no modifications), do not create an empty commit
- In order to ensure good formatting, ALWAYS pass the commit message via a HEREDOC, a la this example:
<example>

50
src/tools/descriptions/EnterPlanMode.md
View File

@@ -1,39 +1,46 @@
# EnterPlanMode
Use this tool when you encounter a complex task that requires careful planning and exploration before implementation. This tool transitions you into plan mode where you can thoroughly explore the codebase and design an implementation approach.
Use this tool proactively when you're about to start a non-trivial implementation task. Getting user sign-off on your approach before writing code prevents wasted effort and ensures alignment. This tool transitions you into plan mode where you can explore the codebase and design an implementation approach for user approval.
## When to Use This Tool
Use EnterPlanMode when ANY of these conditions apply:
**Prefer using EnterPlanMode** for implementation tasks unless they're simple. Use it when ANY of these conditions apply:
1. **Multiple Valid Approaches**: The task can be solved in several different ways, each with trade-offs
1. **New Feature Implementation**: Adding meaningful new functionality
- Example: "Add a logout button" - where should it go? What should happen on click?
- Example: "Add form validation" - what rules? What error messages?
2. **Multiple Valid Approaches**: The task can be solved in several different ways
- Example: "Add caching to the API" - could use Redis, in-memory, file-based, etc.
- Example: "Improve performance" - many optimization strategies possible
2. **Significant Architectural Decisions**: The task requires choosing between architectural patterns
3. **Code Modifications**: Changes that affect existing behavior or structure
- Example: "Update the login flow" - what exactly should change?
- Example: "Refactor this component" - what's the target architecture?
4. **Architectural Decisions**: The task requires choosing between patterns or technologies
- Example: "Add real-time updates" - WebSockets vs SSE vs polling
- Example: "Implement state management" - Redux vs Context vs custom solution
3. **Large-Scale Changes**: The task touches many files or systems
5. **Multi-File Changes**: The task will likely touch more than 2-3 files
- Example: "Refactor the authentication system"
- Example: "Migrate from REST to GraphQL"
- Example: "Add a new API endpoint with tests"
4. **Unclear Requirements**: You need to explore before understanding the full scope
6. **Unclear Requirements**: You need to explore before understanding the full scope
- Example: "Make the app faster" - need to profile and identify bottlenecks
- Example: "Fix the bug in checkout" - need to investigate root cause
5. **User Input Needed**: You'll need to ask clarifying questions before starting
- If you would use AskUserQuestion to clarify the approach, consider EnterPlanMode instead
7. **User Preferences Matter**: The implementation could reasonably go multiple ways
- If you would use AskUserQuestion to clarify the approach, use EnterPlanMode instead
- Plan mode lets you explore first, then present options with context
## When NOT to Use This Tool
Do NOT use EnterPlanMode for:
- Simple, straightforward tasks with obvious implementation
- Small bug fixes where the solution is clear
- Adding a single function or small feature
- Tasks you're already confident how to implement
- Research-only tasks (use the Task tool with explore agent instead)
Only skip EnterPlanMode for simple tasks:
- Single-line or few-line fixes (typos, obvious bugs, small tweaks)
- Adding a single function with clear requirements
- Tasks where the user has given very specific, detailed instructions
- Pure research/exploration tasks (use the Task tool with explore agent instead)
## What Happens in Plan Mode
@@ -49,7 +56,7 @@ In plan mode, you'll:
### GOOD - Use EnterPlanMode:
User: "Add user authentication to the app"
- This requires architectural decisions (session vs JWT, where to store tokens, middleware structure)
- Requires architectural decisions (session vs JWT, where to store tokens, middleware structure)
User: "Optimize the database queries"
- Multiple approaches possible, need to profile first, significant impact
@@ -57,6 +64,12 @@ User: "Optimize the database queries"
User: "Implement dark mode"
- Architectural decision on theme system, affects many components
User: "Add a delete button to the user profile"
- Seems simple but involves: where to place it, confirmation dialog, API call, error handling, state updates
User: "Update the error handling in the API"
- Affects multiple files, user should approve the approach
### BAD - Don't use EnterPlanMode:
User: "Fix the typo in the README"
- Straightforward, no planning needed
@@ -70,6 +83,5 @@ User: "What files handle routing?"
## Important Notes
- This tool REQUIRES user approval - they must consent to entering plan mode
- Be thoughtful about when to use it - unnecessary plan mode slows down simple tasks
- If unsure whether to use it, err on the side of starting implementation
- You can always ask the user "Would you like me to plan this out first?"
- If unsure whether to use it, err on the side of planning - it's better to get alignment upfront than to redo work
- Users appreciate being consulted before significant changes are made to their codebase

13
src/tools/descriptions/ExitPlanMode.md
View File

@@ -11,13 +11,12 @@ Use this tool when you are in plan mode and have finished writing your plan to t
## When to Use This Tool
IMPORTANT: Only use this tool when the task requires planning the implementation steps of a task that requires writing code. For research tasks where you're gathering information, searching files, reading files or in general trying to understand the codebase - do NOT use this tool.
## Handling Ambiguity in Plans
Before using this tool, ensure your plan is clear and unambiguous. If there are multiple valid approaches or unclear requirements:
1. Use the AskUserQuestion tool to clarify with the user
2. Ask about specific implementation choices (e.g., architectural patterns, which library to use)
3. Clarify any assumptions that could affect the implementation
4. Edit your plan file to incorporate user feedback
5. Only proceed with ExitPlanMode after resolving ambiguities and updating the plan file
## Before Using This Tool
Ensure your plan is complete and unambiguous:
- If you have unresolved questions about requirements or approach, use AskUserQuestion first (in earlier phases)
- Once your plan is finalized, use THIS tool to request approval
**Important:** Do NOT use AskUserQuestion to ask "Is this plan okay?" or "Should I proceed?" - that's exactly what THIS tool does. ExitPlanMode inherently requests user approval of your plan.
## Examples

2
src/tools/descriptions/Glob.md
View File

@@ -4,6 +4,6 @@
- Supports glob patterns like "**/*.js" or "src/**/*.ts"
- Returns matching file paths sorted by modification time
- Use this tool when you need to find files by name patterns
- When you are doing an open ended search that may require multiple rounds of globbing and grepping, use the Agent tool instead
- When you are doing an open ended search that may require multiple rounds of globbing and grepping, use the Task tool instead
- You have the capability to call multiple tools in a single response. It is always better to speculatively perform multiple searches as a batch that are potentially useful.
- If more than 2,000 files match the pattern, only the first 2,000 will be returned

6
src/tools/descriptions/Read.md
View File

@@ -9,8 +9,8 @@ Usage:
- You can optionally specify a line offset and limit (especially handy for long files), but it's recommended to read the whole file by not providing these parameters
- Any lines longer than 2000 characters will be truncated
- Results are returned using cat -n format, with line numbers starting at 1
- This tool allows Letta Code to read images (PNG, JPG, JPEG, GIF, WEBP, BMP). When reading an image file the contents are presented visually as Letta Code is a multimodal LLM. Large images are automatically resized to fit within API limits.
- You will regularly be asked to read screenshots. If the user provides a path to a screenshot, ALWAYS use this tool to view the file at the path. This tool will work with all temporary file paths.
- This tool can only read files, not directories. To read a directory, use the ls command via Bash.
- This tool allows Letta Code to read images (eg PNG, JPG, etc). When reading an image file the contents are presented visually as Letta Code is a multimodal LLM.
- This tool can only read files, not directories. To read a directory, use an ls command via the Bash tool.
- You can call multiple tools in a single response. It is always better to speculatively read multiple potentially useful files in parallel.
- You will regularly be asked to read screenshots. If the user provides a path to a screenshot, ALWAYS use this tool to view the file at the path. This tool will work with all temporary file paths.
- If you read a file that exists but has empty contents you will receive a system reminder warning in place of file contents.

68
src/tools/descriptions/Task.md
View File

@@ -4,54 +4,36 @@ Launch a new agent to handle complex, multi-step tasks autonomously.
The Task tool launches specialized agents (subprocesses) that autonomously handle complex tasks. Each agent type has specific capabilities and tools available to it.
## Usage
When using the Task tool, you must specify a subagent_type parameter to select which agent type to use.
The Task tool supports two commands:
## When NOT to use the Task tool:
### Run (default)
Launch a subagent to perform a task. Parameters:
- **subagent_type**: Which specialized agent to use (see Available Agents section)
- **prompt**: Detailed, self-contained instructions for the agent (agents cannot ask questions mid-execution)
- **description**: Short 3-5 word summary for tracking
- **model** (optional): Override the model for this agent
- **agent_id** (optional): Deploy an existing agent instead of creating a new one
- **conversation_id** (optional): Resume from an existing conversation
- If you want to read a specific file path, use the Read or Glob tool instead of the Task tool, to find the match more quickly
- If you are searching for a specific class definition like "class Foo", use the Glob tool instead, to find the match more quickly
- If you are searching for code within a specific file or set of 2-3 files, use the Read tool instead of the Task tool, to find the match more quickly
- Other tasks that are not related to the agent descriptions above
### Refresh
Re-scan the `.letta/agents/` directories to discover new or updated custom subagents:
```typescript
Task({ command: "refresh" })
```
Use this after creating or modifying custom subagent definitions.
## Usage notes:
## When to use this tool:
- **Codebase exploration**: Use when you need to search for files, understand code structure, or find specific patterns
- **Complex tasks**: Use when a task requires multiple steps and autonomous decision-making
- **Research tasks**: Use when you need to gather information from the codebase
- **Parallel work**: Launch multiple agents concurrently for independent tasks
## When NOT to use this tool:
- If you need to read a specific file path, use Read tool directly
- If you're searching for a specific class definition, use Glob tool directly
- If you're searching within 2-3 specific files, use Read tool directly
- For simple, single-step operations
## Important notes:
- **Stateless**: Each agent invocation is autonomous and returns a single final report
- **No back-and-forth**: You cannot communicate with agents during execution
- **Front-load instructions**: Provide complete task details upfront
- **Context-aware**: Agents see full conversation history and can reference earlier context
- **Parallel execution**: Launch multiple agents concurrently by calling Task multiple times in a single response
- **Specify return format**: Tell agents exactly what information to include in their report
- Always include a short description (3-5 words) summarizing what the agent will do
- Launch multiple agents concurrently whenever possible, to maximize performance; to do that, use a single message with multiple tool uses
- When the agent is done, it will return a single message back to you. The result returned by the agent is not visible to the user. To show the user the result, you should send a text message back to the user with a concise summary of the result.
- You can optionally run agents in the background using the run_in_background parameter. When an agent runs in the background, the tool result will include an output_file path. To check on the agent's progress or retrieve its results, use the Read tool to read the output file, or use Bash with `tail` to see recent output. You can continue working while background agents run.
- Agents can be resumed using the `conversation_id` parameter by passing the conversation ID from a previous invocation. When resumed, the agent continues with its full previous context preserved.
- When the agent is done, it will return a single message back to you along with its conversation ID. You can use this ID to resume the agent later if needed for follow-up work.
- Provide clear, detailed prompts so the agent can work autonomously and return exactly the information you need.
- Agents with "access to current context" can see the full conversation history before the tool call. When using these agents, you can write concise prompts that reference earlier context (e.g., "investigate the error discussed above") instead of repeating information. The agent will receive all prior messages and understand the context.
- The agent's outputs should generally be trusted
- Clearly tell the agent whether you expect it to write code or just to do research (search, file reads, web fetches, etc.), since it is not aware of the user's intent
- If the agent description mentions that it should be used proactively, then you should try your best to use it without the user having to ask for it first. Use your judgement.
- If the user specifies that they want you to run agents "in parallel", you MUST send a single message with multiple Task tool use content blocks. For example, if you need to launch multiple agents in parallel, send a single message with multiple Task tool calls.
## Deploying an Existing Agent
Instead of spawning a fresh subagent from a template, you can deploy an existing agent to work in your local codebase.
### Access Levels (subagent_type)
Use subagent_type to control what tools the deployed agent can access:
- **explore**: Read-only access (Read, Glob, Grep) - safer for exploration tasks
- **general-purpose**: Full read-write access (Bash, Edit, Write, etc.) - for implementation tasks
@@ -86,6 +68,7 @@ Task({
// Deploy agent with full access (default)
Task({
agent_id: "agent-abc123",
subagent_type: "general-purpose",
description: "Fix auth bug",
prompt: "Fix the bug in auth.ts"
})
@@ -98,15 +81,14 @@ Task({
})
```
## Examples:
## Example usage:
```typescript
// Good - specific and actionable with a user-specified model "gpt-5-low"
// Good - specific and actionable
Task({
subagent_type: "explore",
description: "Find authentication code",
prompt: "Search for all authentication-related code in src/. List file paths and the main auth approach used.",
model: "gpt-5-low"
prompt: "Search for all authentication-related code in src/. List file paths and the main auth approach used."
})
// Good - complex multi-step task
@@ -116,7 +98,7 @@ Task({
prompt: "Add email and password validation to the user registration form. Check existing validation patterns first, then implement consistent validation."
})
// Parallel execution - launch both at once
// Parallel execution - launch both at once in a single message
Task({ subagent_type: "explore", description: "Find frontend components", prompt: "..." })
Task({ subagent_type: "explore", description: "Find backend APIs", prompt: "..." })

9
src/tools/descriptions/TaskOutput.md Normal file
View File

@@ -0,0 +1,9 @@
# TaskOutput
- Retrieves output from a running or completed task (background shell, agent, or remote session)
- Takes a task_id parameter identifying the task
- Returns the task output along with status information
- Use block=true (default) to wait for task completion
- Use block=false for non-blocking check of current status
- Task IDs can be found using the /tasks command
- Works with all task types: background shells, async agents, and remote sessions

6
src/tools/descriptions/TaskStop.md Normal file
View File

@@ -0,0 +1,6 @@
# TaskStop
- Stops a running background task by its ID
- Takes a task_id parameter identifying the task to stop
- Returns a success or failure status
- Use this tool when you need to terminate a long-running task

24
src/tools/impl/Bash.ts
View File

@@ -1,6 +1,11 @@
import { spawn } from "node:child_process";
import { INTERRUPTED_BY_USER } from "../../constants";
import { backgroundProcesses, getNextBashId } from "./process_manager.js";
import {
appendToOutputFile,
backgroundProcesses,
createBackgroundOutputFile,
getNextBashId,
} from "./process_manager.js";
import { getShellEnv } from "./shellEnv.js";
import { buildShellLaunchers } from "./shellLaunchers.js";
import { spawnWithLauncher } from "./shellRunner.js";
@@ -168,6 +173,7 @@ export async function bash(args: BashArgs): Promise<BashResult> {
if (run_in_background) {
const bashId = getNextBashId();
const outputFile = createBackgroundOutputFile(bashId);
const launcher = getBackgroundLauncher(command);
const [executable, ...launcherArgs] = launcher;
if (!executable) {
@@ -190,26 +196,35 @@ export async function bash(args: BashArgs): Promise<BashResult> {
exitCode: null,
lastReadIndex: { stdout: 0, stderr: 0 },
startTime: new Date(),
outputFile,
});
const bgProcess = backgroundProcesses.get(bashId);
if (!bgProcess) {
throw new Error("Failed to track background process state");
}
childProcess.stdout?.on("data", (data: Buffer) => {
const lines = data.toString().split("\n").filter(Boolean);
const text = data.toString();
const lines = text.split("\n").filter(Boolean);
bgProcess.stdout.push(...lines);
// Also write to output file
appendToOutputFile(outputFile, text);
});
childProcess.stderr?.on("data", (data: Buffer) => {
const lines = data.toString().split("\n").filter(Boolean);
const text = data.toString();
const lines = text.split("\n").filter(Boolean);
bgProcess.stderr.push(...lines);
// Also write to output file (prefixed with [stderr])
appendToOutputFile(outputFile, `[stderr] ${text}`);
});
childProcess.on("exit", (code: number | null) => {
bgProcess.status = code === 0 ? "completed" : "failed";
bgProcess.exitCode = code;
appendToOutputFile(outputFile, `\n[exit code: ${code}]\n`);
});
childProcess.on("error", (err: Error) => {
bgProcess.status = "failed";
bgProcess.stderr.push(err.message);
appendToOutputFile(outputFile, `\n[error] ${err.message}\n`);
});
if (timeout && timeout > 0) {
setTimeout(() => {
@@ -217,6 +232,7 @@ export async function bash(args: BashArgs): Promise<BashResult> {
childProcess.kill("SIGTERM");
bgProcess.status = "failed";
bgProcess.stderr.push(`Command timed out after ${timeout}ms`);
appendToOutputFile(outputFile, `\n[timeout after ${timeout}ms]\n`);
}
}, timeout);
}
@@ -224,7 +240,7 @@ export async function bash(args: BashArgs): Promise<BashResult> {
content: [
{
type: "text",
text: `Command running in background with ID: ${bashId}`,
text: `Command running in background with ID: ${bashId}\nOutput file: ${outputFile}`,
},
],
status: "success",

185
src/tools/impl/BashOutput.ts
View File

@@ -1,27 +1,82 @@
import { backgroundProcesses } from "./process_manager.js";
import { backgroundProcesses, backgroundTasks } from "./process_manager.js";
import { LIMITS, truncateByChars } from "./truncation.js";
import { validateRequiredParams } from "./validation.js";
interface BashOutputArgs {
shell_id: string;
interface GetTaskOutputArgs {
task_id: string;
block?: boolean;
timeout?: number;
filter?: string;
}
interface BashOutputResult {
interface GetTaskOutputResult {
message: string;
status?: "running" | "completed" | "failed";
}
export async function bash_output(
args: BashOutputArgs,
): Promise<BashOutputResult> {
validateRequiredParams(args, ["shell_id"], "BashOutput");
const { shell_id, filter } = args;
const proc = backgroundProcesses.get(shell_id);
if (!proc)
return { message: `No background process found with ID: ${shell_id}` };
const stdout = proc.stdout.join("\n");
const stderr = proc.stderr.join("\n");
/**
* Core implementation for retrieving task/process output.
* Used by both BashOutput (legacy) and TaskOutput (new).
* Checks both backgroundProcesses (Bash) and backgroundTasks (Task).
*/
export async function getTaskOutput(
args: GetTaskOutputArgs,
): Promise<GetTaskOutputResult> {
const { task_id, block = false, timeout = 30000, filter } = args;
// Check backgroundProcesses first (for Bash background commands)
const proc = backgroundProcesses.get(task_id);
if (proc) {
return getProcessOutput(task_id, proc, block, timeout, filter);
}
// Check backgroundTasks (for Task background subagents)
const task = backgroundTasks.get(task_id);
if (task) {
return getBackgroundTaskOutput(task_id, task, block, timeout, filter);
}
return { message: `No background process found with ID: ${task_id}` };
}
/**
* Get output from a background Bash process.
*/
async function getProcessOutput(
task_id: string,
proc: typeof backgroundProcesses extends Map<string, infer V> ? V : never,
block: boolean,
timeout: number,
filter?: string,
): Promise<GetTaskOutputResult> {
// If blocking, wait for process to complete (or timeout)
if (block && proc.status === "running") {
const startTime = Date.now();
await new Promise<void>((resolve) => {
const checkInterval = setInterval(() => {
const currentProc = backgroundProcesses.get(task_id);
if (!currentProc || currentProc.status !== "running") {
clearInterval(checkInterval);
resolve();
} else if (Date.now() - startTime >= timeout) {
clearInterval(checkInterval);
resolve();
}
}, 100); // Check every 100ms
});
}
// Re-fetch in case status changed while waiting
const currentProc = backgroundProcesses.get(task_id);
if (!currentProc) {
return { message: `Process ${task_id} no longer exists` };
}
const stdout = currentProc.stdout.join("\n");
const stderr = currentProc.stderr.join("\n");
let text = stdout;
if (stderr) text = text ? `${text}\n${stderr}` : stderr;
if (filter) {
text = text
.split("\n")
@@ -31,13 +86,107 @@ export async function bash_output(
const userCwd = process.env.USER_CWD || process.cwd();
// Apply character limit to prevent excessive token usage (same as Bash)
// Apply character limit to prevent excessive token usage
const { content: truncatedOutput } = truncateByChars(
text || "(no output yet)",
LIMITS.BASH_OUTPUT_CHARS,
"BashOutput",
{ workingDirectory: userCwd, toolName: "BashOutput" },
"TaskOutput",
{ workingDirectory: userCwd, toolName: "TaskOutput" },
);
return { message: truncatedOutput };
return {
message: truncatedOutput,
status: currentProc.status,
};
}
/**
* Get output from a background Task (subagent).
*/
async function getBackgroundTaskOutput(
task_id: string,
task: typeof backgroundTasks extends Map<string, infer V> ? V : never,
block: boolean,
timeout: number,
filter?: string,
): Promise<GetTaskOutputResult> {
// If blocking, wait for task to complete (or timeout)
if (block && task.status === "running") {
const startTime = Date.now();
await new Promise<void>((resolve) => {
const checkInterval = setInterval(() => {
const currentTask = backgroundTasks.get(task_id);
if (!currentTask || currentTask.status !== "running") {
clearInterval(checkInterval);
resolve();
} else if (Date.now() - startTime >= timeout) {
clearInterval(checkInterval);
resolve();
}
}, 100); // Check every 100ms
});
}
// Re-fetch in case status changed while waiting
const currentTask = backgroundTasks.get(task_id);
if (!currentTask) {
return { message: `Task ${task_id} no longer exists` };
}
let text = currentTask.output.join("\n");
if (currentTask.error) {
text = text
? `${text}\n[error] ${currentTask.error}`
: `[error] ${currentTask.error}`;
}
if (filter) {
text = text
.split("\n")
.filter((line) => line.includes(filter))
.join("\n");
}
const userCwd = process.env.USER_CWD || process.cwd();
// Apply character limit to prevent excessive token usage
const { content: truncatedOutput } = truncateByChars(
text || "(no output yet)",
LIMITS.TASK_OUTPUT_CHARS,
"TaskOutput",
{ workingDirectory: userCwd, toolName: "TaskOutput" },
);
return {
message: truncatedOutput,
status: currentTask.status,
};
}
// Legacy BashOutput interface
interface BashOutputArgs {
shell_id: string;
filter?: string;
}
interface BashOutputResult {
message: string;
}
/**
* Legacy BashOutput function - wraps getTaskOutput with non-blocking behavior.
*/
export async function bash_output(
args: BashOutputArgs,
): Promise<BashOutputResult> {
validateRequiredParams(args, ["shell_id"], "BashOutput");
const { shell_id, filter } = args;
const result = await getTaskOutput({
task_id: shell_id,
block: false, // BashOutput is always non-blocking (legacy behavior)
filter,
});
return { message: result.message };
}

192
src/tools/impl/Task.ts
View File

@@ -11,12 +11,22 @@ import {
getAllSubagentConfigs,
} from "../../agent/subagents";
import { spawnSubagent } from "../../agent/subagents/manager";
import { addToMessageQueue } from "../../cli/helpers/messageQueueBridge.js";
import {
completeSubagent,
generateSubagentId,
getSnapshot as getSubagentSnapshot,
registerSubagent,
} from "../../cli/helpers/subagentState.js";
import { formatTaskNotification } from "../../cli/helpers/taskNotifications.js";
import { runSubagentStopHooks } from "../../hooks";
import {
appendToOutputFile,
type BackgroundTask,
backgroundTasks,
createBackgroundOutputFile,
getNextTaskId,
} from "./process_manager.js";
import { LIMITS, truncateByChars } from "./truncation.js";
import { validateRequiredParams } from "./validation";
@@ -28,6 +38,8 @@ interface TaskArgs {
model?: string;
agent_id?: string; // Deploy an existing agent instead of creating new
conversation_id?: string; // Resume from an existing conversation
run_in_background?: boolean; // Run the task in background
max_turns?: number; // Maximum number of agentic turns
toolCallId?: string; // Injected by executeTool for linking subagent to parent tool call
signal?: AbortSignal; // Injected by executeTool for interruption handling
}
@@ -108,7 +120,184 @@ export async function task(args: TaskArgs): Promise<string> {
// Register subagent with state store for UI display
const subagentId = generateSubagentId();
registerSubagent(subagentId, subagent_type, description, toolCallId);
const isBackground = args.run_in_background ?? false;
registerSubagent(
subagentId,
subagent_type,
description,
toolCallId,
isBackground,
);
// Handle background execution
if (isBackground) {
const taskId = getNextTaskId();
const outputFile = createBackgroundOutputFile(taskId);
// Create abort controller for potential cancellation
const abortController = new AbortController();
// Register background task
const bgTask: BackgroundTask = {
description,
subagentType: subagent_type,
subagentId,
status: "running",
output: [],
startTime: new Date(),
outputFile,
abortController,
};
backgroundTasks.set(taskId, bgTask);
// Write initial status to output file
appendToOutputFile(
outputFile,
`[Task started: ${description}]\n[subagent_type: ${subagent_type}]\n\n`,
);
// Fire-and-forget: run subagent without awaiting
spawnSubagent(
subagent_type,
prompt,
model,
subagentId,
abortController.signal,
args.agent_id,
args.conversation_id,
args.max_turns,
)
.then((result) => {
// Update background task state
bgTask.status = result.success ? "completed" : "failed";
if (result.error) {
bgTask.error = result.error;
}
// Build output header
const header = [
`subagent_type=${subagent_type}`,
result.agentId ? `agent_id=${result.agentId}` : undefined,
result.conversationId
? `conversation_id=${result.conversationId}`
: undefined,
]
.filter(Boolean)
.join(" ");
// Write result to output file
if (result.success) {
appendToOutputFile(outputFile, `${header}\n\n${result.report}\n`);
bgTask.output.push(result.report || "");
} else {
appendToOutputFile(
outputFile,
`[error] ${result.error || "Subagent execution failed"}\n`,
);
}
appendToOutputFile(
outputFile,
`\n[Task ${result.success ? "completed" : "failed"}]\n`,
);
// Mark subagent as completed in state store
completeSubagent(subagentId, {
success: result.success,
error: result.error,
totalTokens: result.totalTokens,
});
const subagentSnapshot = getSubagentSnapshot();
const toolUses = subagentSnapshot.agents.find(
(agent) => agent.id === subagentId,
)?.toolCalls.length;
const durationMs = Math.max(0, Date.now() - bgTask.startTime.getTime());
// Build and truncate the result (same as foreground path)
const fullResult = result.success
? `${header}\n\n${result.report || ""}`
: result.error || "Subagent execution failed";
const userCwd = process.env.USER_CWD || process.cwd();
const { content: truncatedResult } = truncateByChars(
fullResult,
LIMITS.TASK_OUTPUT_CHARS,
"Task",
{ workingDirectory: userCwd, toolName: "Task" },
);
// Format and queue notification for auto-firing when idle
const notificationXml = formatTaskNotification({
taskId,
status: result.success ? "completed" : "failed",
summary: `Agent "${description}" ${result.success ? "completed" : "failed"}`,
result: truncatedResult,
outputFile,
usage: {
totalTokens: result.totalTokens,
toolUses,
durationMs,
},
});
addToMessageQueue({ kind: "task_notification", text: notificationXml });
// Run SubagentStop hooks (fire-and-forget)
runSubagentStopHooks(
subagent_type,
subagentId,
result.success,
result.error,
result.agentId,
result.conversationId,
).catch(() => {
// Silently ignore hook errors
});
})
.catch((error) => {
const errorMessage =
error instanceof Error ? error.message : String(error);
bgTask.status = "failed";
bgTask.error = errorMessage;
appendToOutputFile(outputFile, `[error] ${errorMessage}\n`);
// Mark subagent as completed with error
completeSubagent(subagentId, { success: false, error: errorMessage });
const subagentSnapshot = getSubagentSnapshot();
const toolUses = subagentSnapshot.agents.find(
(agent) => agent.id === subagentId,
)?.toolCalls.length;
const durationMs = Math.max(0, Date.now() - bgTask.startTime.getTime());
// Format and queue notification for auto-firing when idle
const notificationXml = formatTaskNotification({
taskId,
status: "failed",
summary: `Agent "${description}" failed`,
result: errorMessage,
outputFile,
usage: {
toolUses,
durationMs,
},
});
addToMessageQueue({ kind: "task_notification", text: notificationXml });
// Run SubagentStop hooks for error case
runSubagentStopHooks(
subagent_type,
subagentId,
false,
errorMessage,
args.agent_id,
args.conversation_id,
).catch(() => {
// Silently ignore hook errors
});
});
// Return immediately with task ID and output file
return `Task running in background with ID: ${taskId}\nOutput file: ${outputFile}`;
}
try {
const result = await spawnSubagent(
@@ -119,6 +308,7 @@ export async function task(args: TaskArgs): Promise<string> {
signal,
args.agent_id,
args.conversation_id,
args.max_turns,
);
// Mark subagent as completed in state store

30
src/tools/impl/TaskOutput.ts Normal file
View File

@@ -0,0 +1,30 @@
import { getTaskOutput } from "./BashOutput.js";
import { validateRequiredParams } from "./validation.js";
interface TaskOutputArgs {
task_id: string;
block?: boolean;
timeout?: number;
}
interface TaskOutputResult {
message: string;
status?: "running" | "completed" | "failed";
}
/**
* TaskOutput - retrieves output from a running or completed background task.
* Supports blocking (wait for completion) and timeout.
*/
export async function task_output(
args: TaskOutputArgs,
): Promise<TaskOutputResult> {
validateRequiredParams(args, ["task_id"], "TaskOutput");
const { task_id, block = true, timeout = 30000 } = args;
return getTaskOutput({
task_id,
block,
timeout,
});
}

37
src/tools/impl/TaskStop.ts Normal file
View File

@@ -0,0 +1,37 @@
import { kill_bash } from "./KillBash.js";
import { backgroundTasks } from "./process_manager.js";
import { validateRequiredParams } from "./validation.js";
interface TaskStopArgs {
task_id?: string;
shell_id?: string; // deprecated, for backwards compatibility
}
interface TaskStopResult {
killed: boolean;
}
export async function task_stop(args: TaskStopArgs): Promise<TaskStopResult> {
// Support both task_id and deprecated shell_id
let id = args.task_id ?? args.shell_id;
if (!id) {
validateRequiredParams(args, ["task_id"], "TaskStop");
id = ""; // unreachable, validateRequiredParams throws
}
// Check if this is a background Task (subagent)
const task = backgroundTasks.get(id);
if (task) {
if (task.status === "running" && task.abortController) {
task.abortController.abort();
task.status = "failed";
task.error = "Aborted by user";
return { killed: true };
}
// Task exists but isn't running or doesn't have abort controller
return { killed: false };
}
// Fall back to killing a Bash background process
return kill_bash({ shell_id: id });
}

57
src/tools/impl/process_manager.ts
View File

@@ -7,8 +7,65 @@ export interface BackgroundProcess {
exitCode: number | null;
lastReadIndex: { stdout: number; stderr: number };
startTime?: Date;
outputFile?: string; // File path for persistent output
}
export interface BackgroundTask {
description: string;
subagentType: string;
subagentId: string;
status: "running" | "completed" | "failed";
output: string[];
error?: string;
startTime: Date;
outputFile: string;
abortController?: AbortController;
}
export const backgroundProcesses = new Map<string, BackgroundProcess>();
export const backgroundTasks = new Map<string, BackgroundTask>();
let bashIdCounter = 1;
export const getNextBashId = () => `bash_${bashIdCounter++}`;
let taskIdCounter = 1;
export const getNextTaskId = () => `task_${taskIdCounter++}`;
/**
* Get a temp directory for background task output files.
* Uses LETTA_SCRATCHPAD if set, otherwise falls back to os.tmpdir().
*/
export function getBackgroundOutputDir(): string {
const scratchpad = process.env.LETTA_SCRATCHPAD;
if (scratchpad) {
return scratchpad;
}
// Fall back to system temp with a letta-specific subdirectory
const os = require("node:os");
const path = require("node:path");
return path.join(os.tmpdir(), "letta-background");
}
/**
* Create a unique output file path for a background process/task.
*/
export function createBackgroundOutputFile(id: string): string {
const fs = require("node:fs");
const path = require("node:path");
const dir = getBackgroundOutputDir();
// Ensure directory exists
fs.mkdirSync(dir, { recursive: true });
const filePath = path.join(dir, `${id}.log`);
// Create empty file
fs.writeFileSync(filePath, "");
return filePath;
}
/**
* Append content to a background output file.
*/
export function appendToOutputFile(filePath: string, content: string): void {
const fs = require("node:fs");
fs.appendFileSync(filePath, content);
}

6
src/tools/manager.ts
View File

@@ -63,13 +63,13 @@ export function getInternalToolName(serverName: string): string {
export const ANTHROPIC_DEFAULT_TOOLS: ToolName[] = [
"AskUserQuestion",
"Bash",
"BashOutput",
"TaskOutput",
"Edit",
"EnterPlanMode",
"ExitPlanMode",
"Glob",
"Grep",
"KillBash",
"TaskStop",
// "MultiEdit",
// "LS",
"Read",
@@ -149,12 +149,14 @@ const TOOL_PERMISSIONS: Record<ToolName, { requiresApproval: boolean }> = {
AskUserQuestion: { requiresApproval: true },
Bash: { requiresApproval: true },
BashOutput: { requiresApproval: false },
TaskOutput: { requiresApproval: false },
Edit: { requiresApproval: true },
EnterPlanMode: { requiresApproval: true },
ExitPlanMode: { requiresApproval: false },
Glob: { requiresApproval: false },
Grep: { requiresApproval: false },
KillBash: { requiresApproval: true },
TaskStop: { requiresApproval: true },
LS: { requiresApproval: false },
MultiEdit: { requiresApproval: true },
Read: { requiresApproval: false },

1
src/tools/schemas/AskUserQuestion.json
View File

@@ -37,6 +37,7 @@
},
"multiSelect": {
"type": "boolean",
"default": false,
"description": "Set to true to allow the user to select multiple options instead of just one. Use when choices are not mutually exclusive."
}
},

4
src/tools/schemas/Bash.json
View File

@@ -11,11 +11,11 @@
},
"description": {
"type": "string",
"description": "Clear, concise description of what this command does in 5-10 words, in active voice. Examples:\nInput: ls\nOutput: List files in current directory\n\nInput: git status\nOutput: Show working tree status\n\nInput: npm install\nOutput: Install package dependencies\n\nInput: mkdir foo\nOutput: Create directory 'foo'"
"description": "Clear, concise description of what this command does in active voice. Never use words like \"complex\" or \"risk\" in the description - just describe what it does.\n\nFor simple commands (git, npm, standard CLI tools), keep it brief (5-10 words):\n- ls → \"List files in current directory\"\n- git status → \"Show working tree status\"\n- npm install → \"Install package dependencies\"\n\nFor commands that are harder to parse at a glance (piped commands, obscure flags, etc.), add enough context to clarify what it does:\n- find . -name \"*.tmp\" -exec rm {} \\; → \"Find and delete all .tmp files recursively\"\n- git reset --hard origin/main → \"Discard all local changes and match remote main\"\n- curl -s url | jq '.data[]' → \"Fetch JSON from URL and extract data array elements\""
},
"run_in_background": {
"type": "boolean",
"description": "Set to true to run this command in the background. Use BashOutput to read the output later."
"description": "Set to true to run this command in the background. Use TaskOutput to read the output later."
}
},
"required": ["command"],

6
src/tools/schemas/Grep.json
View File

@@ -27,6 +27,10 @@
"description": "Number of lines to show after each match (rg -A). Requires output_mode: \"content\", ignored otherwise."
},
"-C": {
"type": "number",
"description": "Alias for context."
},
"context": {
"type": "number",
"description": "Number of lines to show before and after each match (rg -C). Requires output_mode: \"content\", ignored otherwise."
},
@@ -44,7 +48,7 @@
},
"head_limit": {
"type": "number",
"description": "Limit output to first N lines/entries, equivalent to \"| head -N\". Works across all output modes: content (limits output lines), files_with_matches (limits file paths), count (limits count entries). Defaults to 100 (0 = unlimited)."
"description": "Limit output to first N lines/entries, equivalent to \"| head -N\". Works across all output modes: content (limits output lines), files_with_matches (limits file paths), count (limits count entries). Defaults to 0 (unlimited)."
},
"offset": {
"type": "number",

35
src/tools/schemas/Task.json
View File

@@ -1,28 +1,41 @@
{
"type": "object",
"properties": {
"command": {
"description": {
"type": "string",
"enum": ["run", "refresh"],
"description": "The operation to perform: \"run\" to spawn a subagent (default), \"refresh\" to re-scan the .letta/agents/ directories and update the available subagents list"
},
"subagent_type": {
"type": "string",
"description": "The type of specialized agent to use. Available agents are discovered from .letta/agents/ directory. Required for \"run\" command."
"description": "A short (3-5 word) description of the task"
},
"prompt": {
"type": "string",
"description": "The task for the agent to perform. Required for \"run\" command."
"description": "The task for the agent to perform"
},
"description": {
"subagent_type": {
"type": "string",
"description": "A short (3-5 word) description of the task. Required for \"run\" command."
"description": "The type of specialized agent to use for this task"
},
"model": {
"type": "string",
"description": "Optional model to use for this agent. If not specified, uses the recommended model for the subagent type."
"description": "Optional model to use for this agent. If not specified, inherits from parent. Prefer lighter models for quick, straightforward tasks to minimize cost and latency."
},
"run_in_background": {
"type": "boolean",
"description": "Set to true to run this agent in the background. The tool result will include an output_file path - use Read tool or Bash tail to check on output."
},
"agent_id": {
"type": "string",
"description": "Deploy an existing agent instead of creating a new one. Starts a new conversation with that agent."
},
"conversation_id": {
"type": "string",
"description": "Resume from an existing conversation. Does NOT require agent_id (conversation IDs are unique and encode the agent)."
},
"max_turns": {
"type": "integer",
"exclusiveMinimum": 0,
"description": "Maximum number of agentic turns (API round-trips) before stopping."
}
},
"required": ["description", "prompt", "subagent_type"],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}

24
src/tools/schemas/TaskOutput.json Normal file
View File

@@ -0,0 +1,24 @@
{
"type": "object",
"properties": {
"task_id": {
"type": "string",
"description": "The task ID to get output from"
},
"block": {
"type": "boolean",
"default": true,
"description": "Whether to wait for completion"
},
"timeout": {
"type": "number",
"default": 30000,
"minimum": 0,
"maximum": 600000,
"description": "Max wait time in ms"
}
},
"required": ["task_id"],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}

16
src/tools/schemas/TaskStop.json Normal file
View File

@@ -0,0 +1,16 @@
{
"type": "object",
"properties": {
"task_id": {
"type": "string",
"description": "The ID of the background task to stop"
},
"shell_id": {
"type": "string",
"description": "Deprecated: use task_id instead"
}
},
"required": ["task_id"],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}

16
src/tools/toolDefinitions.ts
View File

@@ -27,6 +27,8 @@ import ShellDescription from "./descriptions/Shell.md";
import ShellCommandDescription from "./descriptions/ShellCommand.md";
import SkillDescription from "./descriptions/Skill.md";
import TaskDescription from "./descriptions/Task.md";
import TaskOutputDescription from "./descriptions/TaskOutput.md";
import TaskStopDescription from "./descriptions/TaskStop.md";
import TodoWriteDescription from "./descriptions/TodoWrite.md";
import UpdatePlanDescription from "./descriptions/UpdatePlan.md";
import ViewImageDescription from "./descriptions/ViewImage.md";
@@ -62,6 +64,8 @@ import { shell } from "./impl/Shell";
import { shell_command } from "./impl/ShellCommand";
import { skill } from "./impl/Skill";
import { task } from "./impl/Task";
import { task_output } from "./impl/TaskOutput";
import { task_stop } from "./impl/TaskStop";
import { todo_write } from "./impl/TodoWrite";
import { update_plan } from "./impl/UpdatePlan";
import { view_image } from "./impl/ViewImage";
@@ -97,6 +101,8 @@ import ShellSchema from "./schemas/Shell.json";
import ShellCommandSchema from "./schemas/ShellCommand.json";
import SkillSchema from "./schemas/Skill.json";
import TaskSchema from "./schemas/Task.json";
import TaskOutputSchema from "./schemas/TaskOutput.json";
import TaskStopSchema from "./schemas/TaskStop.json";
import TodoWriteSchema from "./schemas/TodoWrite.json";
import UpdatePlanSchema from "./schemas/UpdatePlan.json";
import ViewImageSchema from "./schemas/ViewImage.json";
@@ -158,6 +164,16 @@ const toolDefinitions = {
description: KillBashDescription.trim(),
impl: kill_bash as unknown as ToolImplementation,
},
TaskOutput: {
schema: TaskOutputSchema,
description: TaskOutputDescription.trim(),
impl: task_output as unknown as ToolImplementation,
},
TaskStop: {
schema: TaskStopSchema,
description: TaskStopDescription.trim(),
impl: task_stop as unknown as ToolImplementation,
},
LS: {
schema: LSSchema,
description: LSDescription.trim(),