github/openclaw
1
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-05-06 20:31:36 +00:00
Code Issues Packages Projects Releases Wiki Activity

Agents: add nested subagent orchestration controls and reduce subagent token waste (#14447)

Browse Source 
* Agents: add subagent orchestration controls

* Agents: add subagent orchestration controls (WIP uncommitted changes)

* feat(subagents): add depth-based spawn gating for sub-sub-agents

* feat(subagents): tool policy, registry, and announce chain for nested agents

* feat(subagents): system prompt, docs, changelog for nested sub-agents

* fix(subagents): prevent model fallback override, show model during active runs, and block context overflow fallback

Bug 1: When a session has an explicit model override (e.g., gpt/openai-codex),
the fallback candidate logic in resolveFallbackCandidates silently appended the
global primary model (opus) as a backstop. On reinjection/steer with a transient
error, the session could fall back to opus which has a smaller context window
and crash. Fix: when storedModelOverride is set, pass fallbacksOverride ?? []
instead of undefined, preventing the implicit primary backstop.

Bug 2: Active subagents showed 'model n/a' in /subagents list because
resolveModelDisplay only read entry.model/modelProvider (populated after run
completes). Fix: fall back to modelOverride/providerOverride fields which are
populated at spawn time via sessions.patch.

Bug 3: Context overflow errors (prompt too long, context_length_exceeded) could
theoretically escape runEmbeddedPiAgent and be treated as failover candidates
in runWithModelFallback, causing a switch to a model with a smaller context
window. Fix: in runWithModelFallback, detect context overflow errors via
isLikelyContextOverflowError and rethrow them immediately instead of trying the
next model candidate.

* fix(subagents): track spawn depth in session store and fix announce routing for nested agents

* Fix compaction status tracking and dedupe overflow compaction triggers

* fix(subagents): enforce depth block via session store and implement cascade kill

* fix: inject group chat context into system prompt

* fix(subagents): always write model to session store at spawn time

* Preserve spawnDepth when agent handler rewrites session entry

* fix(subagents): suppress announce on steer-restart

* fix(subagents): fallback spawned session model to runtime default

* fix(subagents): enforce spawn depth when caller key resolves by sessionId

* feat(subagents): implement active-first ordering for numeric targets and enhance task display

- Added a test to verify that subagents with numeric targets follow an active-first list ordering.
- Updated `resolveSubagentTarget` to sort subagent runs based on active status and recent activity.
- Enhanced task display in command responses to prevent truncation of long task descriptions.
- Introduced new utility functions for compacting task text and managing subagent run states.

* fix(subagents): show model for active runs via run record fallback

When the spawned model matches the agent's default model, the session
store's override fields are intentionally cleared (isDefault: true).
The model/modelProvider fields are only populated after the run
completes. This left active subagents showing 'model n/a'.

Fix: store the resolved model on SubagentRunRecord at registration
time, and use it as a fallback in both display paths (subagents tool
and /subagents command) when the session store entry has no model info.

Changes:
- SubagentRunRecord: add optional model field
- registerSubagentRun: accept and persist model param
- sessions-spawn-tool: pass resolvedModel to registerSubagentRun
- subagents-tool: pass run record model as fallback to resolveModelDisplay
- commands-subagents: pass run record model as fallback to resolveModelDisplay

* feat(chat): implement session key resolution and reset on sidebar navigation

- Added functions to resolve the main session key and reset chat state when switching sessions from the sidebar.
- Updated the `renderTab` function to handle session key changes when navigating to the chat tab.
- Introduced a test to verify that the session resets to "main" when opening chat from the sidebar navigation.

* fix: subagent timeout=0 passthrough and fallback prompt duplication

Bug 1: runTimeoutSeconds=0 now means 'no timeout' instead of applying 600s default
- sessions-spawn-tool: default to undefined (not 0) when neither timeout param
  is provided; use != null check so explicit 0 passes through to gateway
- agent.ts: accept 0 as valid timeout (resolveAgentTimeoutMs already handles
  0 → MAX_SAFE_TIMEOUT_MS)

Bug 2: model fallback no longer re-injects the original prompt as a duplicate
- agent.ts: track fallback attempt index; on retries use a short continuation
  message instead of the full original prompt since the session file already
  contains it from the first attempt
- Also skip re-sending images on fallback retries (already in session)

* feat(subagents): truncate long task descriptions in subagents command output

- Introduced a new utility function to format task previews, limiting their length to improve readability.
- Updated the command handler to use the new formatting function, ensuring task descriptions are truncated appropriately.
- Adjusted related tests to verify that long task descriptions are now truncated in the output.

* refactor(subagents): update subagent registry path resolution and improve command output formatting

- Replaced direct import of STATE_DIR with a utility function to resolve the state directory dynamically.
- Enhanced the formatting of command output for active and recent subagents, adding separators for better readability.
- Updated related tests to reflect changes in command output structure.

* fix(subagent): default sessions_spawn to no timeout when runTimeoutSeconds omitted

The previous fix (75a791106) correctly handled the case where
runTimeoutSeconds was explicitly set to 0 ("no timeout"). However,
when models omit the parameter entirely (which is common since the
schema marks it as optional), runTimeoutSeconds resolved to undefined.

undefined flowed through the chain as:
  sessions_spawn → timeout: undefined (since undefined != null is false)
  → gateway agent handler → agentCommand opts.timeout: undefined
  → resolveAgentTimeoutMs({ overrideSeconds: undefined })
  → DEFAULT_AGENT_TIMEOUT_SECONDS (600s = 10 minutes)

This caused subagents to be killed at exactly 10 minutes even though
the user's intent (via TOOLS.md) was for subagents to run without a
timeout.

Fix: default runTimeoutSeconds to 0 (no timeout) when neither
runTimeoutSeconds nor timeoutSeconds is provided by the caller.
Subagent spawns are long-running by design and should not inherit the
600s agent-command default timeout.

* fix(subagent): accept timeout=0 in agent-via-gateway path (second 600s default)

* fix: thread timeout override through getReplyFromConfig dispatch path

getReplyFromConfig called resolveAgentTimeoutMs({ cfg }) with no override,
always falling back to the config default (600s). Add timeoutOverrideSeconds
to GetReplyOptions and pass it through as overrideSeconds so callers of the
dispatch chain can specify a custom timeout (0 = no timeout).

This complements the existing timeout threading in agentCommand and the
cron isolated-agent runner, which already pass overrideSeconds correctly.

* feat(model-fallback): normalize OpenAI Codex model references and enhance fallback handling

- Added normalization for OpenAI Codex model references, specifically converting "gpt-5.3-codex" to "openai-codex" before execution.
- Updated the `resolveFallbackCandidates` function to utilize the new normalization logic.
- Enhanced tests to verify the correct behavior of model normalization and fallback mechanisms.
- Introduced a new test case to ensure that the normalization process works as expected for various input formats.

* feat(tests): add unit tests for steer failure behavior in openclaw-tools

- Introduced a new test file to validate the behavior of subagents when steer replacement dispatch fails.
- Implemented tests to ensure that the announce behavior is restored correctly and that the suppression reason is cleared as expected.
- Enhanced the subagent registry with a new function to clear steer restart suppression.
- Updated related components to support the new test scenarios.

* fix(subagents): replace stop command with kill in slash commands and documentation

- Updated the `/subagents` command to replace `stop` with `kill` for consistency in controlling sub-agent runs.
- Modified related documentation to reflect the change in command usage.
- Removed legacy timeoutSeconds references from the sessions-spawn-tool schema and tests to streamline timeout handling.
- Enhanced tests to ensure correct behavior of the updated commands and their interactions.

* feat(tests): add unit tests for readLatestAssistantReply function

- Introduced a new test file for the `readLatestAssistantReply` function to validate its behavior with various message scenarios.
- Implemented tests to ensure the function correctly retrieves the latest assistant message and handles cases where the latest message has no text.
- Mocked the gateway call to simulate different message histories for comprehensive testing.

* feat(tests): enhance subagent kill-all cascade tests and announce formatting

- Added a new test to verify that the `kill-all` command cascades through ended parents to active descendants in subagents.
- Updated the subagent announce formatting tests to reflect changes in message structure, including the replacement of "Findings:" with "Result:" and the addition of new expectations for message content.
- Improved the handling of long findings and stats in the announce formatting logic to ensure concise output.
- Refactored related functions to enhance clarity and maintainability in the subagent registry and tools.

* refactor(subagent): update announce formatting and remove unused constants

- Modified the subagent announce formatting to replace "Findings:" with "Result:" and adjusted related expectations in tests.
- Removed constants for maximum announce findings characters and summary words, simplifying the announcement logic.
- Updated the handling of findings to retain full content instead of truncating, ensuring more informative outputs.
- Cleaned up unused imports in the commands-subagents file to enhance code clarity.

* feat(tests): enhance billing error handling in user-facing text

- Added tests to ensure that normal text mentioning billing plans is not rewritten, preserving user context.
- Updated the `isBillingErrorMessage` and `sanitizeUserFacingText` functions to improve handling of billing-related messages.
- Introduced new test cases for various scenarios involving billing messages to ensure accurate processing and output.
- Enhanced the subagent announce flow to correctly manage active descendant runs, preventing premature announcements.

* feat(subagent): enhance workflow guidance and auto-announcement clarity

- Added a new guideline in the subagent system prompt to emphasize trust in push-based completion, discouraging busy polling for status updates.
- Updated documentation to clarify that sub-agents will automatically announce their results, improving user understanding of the workflow.
- Enhanced tests to verify the new guidance on avoiding polling loops and to ensure the accuracy of the updated prompts.

* fix(cron): avoid announcing interim subagent spawn acks

* chore: clean post-rebase imports

* fix(cron): fall back to child replies when parent stays interim

* fix(subagents): make active-run guidance advisory

* fix(subagents): update announce flow to handle active descendants and enhance test coverage

- Modified the announce flow to defer announcements when active descendant runs are present, ensuring accurate status reporting.
- Updated tests to verify the new behavior, including scenarios where no fallback requester is available and ensuring proper handling of finished subagents.
- Enhanced the announce formatting to include an `expectFinal` flag for better clarity in the announcement process.

* fix(subagents): enhance announce flow and formatting for user updates

- Updated the announce flow to provide clearer instructions for user updates based on active subagent runs and requester context.
- Refactored the announcement logic to improve clarity and ensure internal context remains private.
- Enhanced tests to verify the new message expectations and formatting, including updated prompts for user-facing updates.
- Introduced a new function to build reply instructions based on session context, improving the overall announcement process.

* fix: resolve prep blockers and changelog placement (#14447) (thanks @tyler6204)

* fix: restore cron delivery-plan import after rebase (#14447) (thanks @tyler6204)

* fix: resolve test failures from rebase conflicts (#14447) (thanks @tyler6204)

* fix: apply formatting after rebase (#14447) (thanks @tyler6204)
This commit is contained in:
Tyler Yust
2026-02-14 22:03:45 -08:00
committed by GitHub
parent c46f395bb9
commit b8f66c260d
86 changed files with 5700 additions and 821 deletions
Download Patch File Download Diff File Expand all files Collapse all files

166
src/auto-reply/reply/abort.test.ts
View File

@@ -28,10 +28,12 @@ vi.mock("../../process/command-queue.js", () => commandQueueMocks);
const subagentRegistryMocks = vi.hoisted(() => ({
listSubagentRunsForRequester: vi.fn(() => []),
markSubagentRunTerminated: vi.fn(() => 1),
}));
vi.mock("../../agents/subagent-registry.js", () => ({
listSubagentRunsForRequester: subagentRegistryMocks.listSubagentRunsForRequester,
markSubagentRunTerminated: subagentRegistryMocks.markSubagentRunTerminated,
}));
describe("abort detection", () => {
@@ -233,4 +235,168 @@ describe("abort detection", () => {
expect(result.stoppedSubagents).toBe(1);
expect(commandQueueMocks.clearCommandLane).toHaveBeenCalledWith(`session:${childKey}`);
});
it("cascade stop kills depth-2 children when stopping depth-1 agent", async () => {
const root = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-abort-"));
const storePath = path.join(root, "sessions.json");
const cfg = { session: { store: storePath } } as OpenClawConfig;
const sessionKey = "telegram:parent";
const depth1Key = "agent:main:subagent:child-1";
const depth2Key = "agent:main:subagent:child-1:subagent:grandchild-1";
const sessionId = "session-parent";
const depth1SessionId = "session-child";
const depth2SessionId = "session-grandchild";
await fs.writeFile(
storePath,
JSON.stringify(
{
[sessionKey]: {
sessionId,
updatedAt: Date.now(),
},
[depth1Key]: {
sessionId: depth1SessionId,
updatedAt: Date.now(),
},
[depth2Key]: {
sessionId: depth2SessionId,
updatedAt: Date.now(),
},
},
null,
2,
),
);
// First call: main session lists depth-1 children
// Second call (cascade): depth-1 session lists depth-2 children
// Third call (cascade from depth-2): no further children
subagentRegistryMocks.listSubagentRunsForRequester
.mockReturnValueOnce([
{
runId: "run-1",
childSessionKey: depth1Key,
requesterSessionKey: sessionKey,
requesterDisplayKey: "telegram:parent",
task: "orchestrator",
cleanup: "keep",
createdAt: Date.now(),
},
])
.mockReturnValueOnce([
{
runId: "run-2",
childSessionKey: depth2Key,
requesterSessionKey: depth1Key,
requesterDisplayKey: depth1Key,
task: "leaf worker",
cleanup: "keep",
createdAt: Date.now(),
},
])
.mockReturnValueOnce([]);
const result = await tryFastAbortFromMessage({
ctx: buildTestCtx({
CommandBody: "/stop",
RawBody: "/stop",
CommandAuthorized: true,
SessionKey: sessionKey,
Provider: "telegram",
Surface: "telegram",
From: "telegram:parent",
To: "telegram:parent",
}),
cfg,
});
// Should stop both depth-1 and depth-2 agents (cascade)
expect(result.stoppedSubagents).toBe(2);
expect(commandQueueMocks.clearCommandLane).toHaveBeenCalledWith(`session:${depth1Key}`);
expect(commandQueueMocks.clearCommandLane).toHaveBeenCalledWith(`session:${depth2Key}`);
});
it("cascade stop traverses ended depth-1 parents to stop active depth-2 children", async () => {
subagentRegistryMocks.listSubagentRunsForRequester.mockReset();
subagentRegistryMocks.markSubagentRunTerminated.mockClear();
const root = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-abort-"));
const storePath = path.join(root, "sessions.json");
const cfg = { session: { store: storePath } } as OpenClawConfig;
const sessionKey = "telegram:parent";
const depth1Key = "agent:main:subagent:child-ended";
const depth2Key = "agent:main:subagent:child-ended:subagent:grandchild-active";
const now = Date.now();
await fs.writeFile(
storePath,
JSON.stringify(
{
[sessionKey]: {
sessionId: "session-parent",
updatedAt: now,
},
[depth1Key]: {
sessionId: "session-child-ended",
updatedAt: now,
},
[depth2Key]: {
sessionId: "session-grandchild-active",
updatedAt: now,
},
},
null,
2,
),
);
// main -> ended depth-1 parent
// depth-1 parent -> active depth-2 child
// depth-2 child -> none
subagentRegistryMocks.listSubagentRunsForRequester
.mockReturnValueOnce([
{
runId: "run-1",
childSessionKey: depth1Key,
requesterSessionKey: sessionKey,
requesterDisplayKey: "telegram:parent",
task: "orchestrator",
cleanup: "keep",
createdAt: now - 1_000,
endedAt: now - 500,
outcome: { status: "ok" },
},
])
.mockReturnValueOnce([
{
runId: "run-2",
childSessionKey: depth2Key,
requesterSessionKey: depth1Key,
requesterDisplayKey: depth1Key,
task: "leaf worker",
cleanup: "keep",
createdAt: now - 500,
},
])
.mockReturnValueOnce([]);
const result = await tryFastAbortFromMessage({
ctx: buildTestCtx({
CommandBody: "/stop",
RawBody: "/stop",
CommandAuthorized: true,
SessionKey: sessionKey,
Provider: "telegram",
Surface: "telegram",
From: "telegram:parent",
To: "telegram:parent",
}),
cfg,
});
// Should skip killing the ended depth-1 run itself, but still kill depth-2.
expect(result.stoppedSubagents).toBe(1);
expect(commandQueueMocks.clearCommandLane).toHaveBeenCalledWith(`session:${depth2Key}`);
expect(subagentRegistryMocks.markSubagentRunTerminated).toHaveBeenCalledWith(
expect.objectContaining({ runId: "run-2", childSessionKey: depth2Key }),
);
});
});

49
src/auto-reply/reply/abort.ts
View File

@@ -2,7 +2,10 @@ import type { OpenClawConfig } from "../../config/config.js";
import type { FinalizedMsgContext, MsgContext } from "../templating.js";
import { resolveSessionAgentId } from "../../agents/agent-scope.js";
import { abortEmbeddedPiRun } from "../../agents/pi-embedded.js";
import { listSubagentRunsForRequester } from "../../agents/subagent-registry.js";
import {
listSubagentRunsForRequester,
markSubagentRunTerminated,
} from "../../agents/subagent-registry.js";
import {
resolveInternalSessionKey,
resolveMainSessionAlias,
@@ -141,30 +144,42 @@ export function stopSubagentsForRequester(params: {
let stopped = 0;
for (const run of runs) {
if (run.endedAt) {
continue;
}
const childKey = run.childSessionKey?.trim();
if (!childKey || seenChildKeys.has(childKey)) {
continue;
}
seenChildKeys.add(childKey);
const cleared = clearSessionQueues([childKey]);
const parsed = parseAgentSessionKey(childKey);
const storePath = resolveStorePath(params.cfg.session?.store, { agentId: parsed?.agentId });
let store = storeCache.get(storePath);
if (!store) {
store = loadSessionStore(storePath);
storeCache.set(storePath, store);
}
const entry = store[childKey];
const sessionId = entry?.sessionId;
const aborted = sessionId ? abortEmbeddedPiRun(sessionId) : false;
if (!run.endedAt) {
const cleared = clearSessionQueues([childKey]);
const parsed = parseAgentSessionKey(childKey);
const storePath = resolveStorePath(params.cfg.session?.store, { agentId: parsed?.agentId });
let store = storeCache.get(storePath);
if (!store) {
store = loadSessionStore(storePath);
storeCache.set(storePath, store);
}
const entry = store[childKey];
const sessionId = entry?.sessionId;
const aborted = sessionId ? abortEmbeddedPiRun(sessionId) : false;
const markedTerminated =
markSubagentRunTerminated({
runId: run.runId,
childSessionKey: childKey,
reason: "killed",
}) > 0;
if (aborted || cleared.followupCleared > 0 || cleared.laneCleared > 0) {
stopped += 1;
if (markedTerminated || aborted || cleared.followupCleared > 0 || cleared.laneCleared > 0) {
stopped += 1;
}
}
// Cascade: also stop any sub-sub-agents spawned by this child.
const cascadeResult = stopSubagentsForRequester({
cfg: params.cfg,
requesterSessionKey: childKey,
});
stopped += cascadeResult.stopped;
}
if (stopped > 0) {

3
src/auto-reply/reply/agent-runner-execution.ts
View File

@@ -356,8 +356,7 @@ export async function runAgentTurnWithFallback(params: {
// Track auto-compaction completion
if (evt.stream === "compaction") {
const phase = typeof evt.data.phase === "string" ? evt.data.phase : "";
const willRetry = Boolean(evt.data.willRetry);
if (phase === "end" && !willRetry) {
if (phase === "end") {
autoCompactionCompleted = true;
}
}

3
src/auto-reply/reply/agent-runner-memory.ts
View File

@@ -153,8 +153,7 @@ export async function runMemoryFlushIfNeeded(params: {
onAgentEvent: (evt) => {
if (evt.stream === "compaction") {
const phase = typeof evt.data.phase === "string" ? evt.data.phase : "";
const willRetry = Boolean(evt.data.willRetry);
if (phase === "end" && !willRetry) {
if (phase === "end") {
memoryCompactionCompleted = true;
}
}

449
src/auto-reply/reply/commands-subagents.ts
View File

@@ -3,7 +3,13 @@ import type { SubagentRunRecord } from "../../agents/subagent-registry.js";
import type { CommandHandler } from "./commands-types.js";
import { AGENT_LANE_SUBAGENT } from "../../agents/lanes.js";
import { abortEmbeddedPiRun } from "../../agents/pi-embedded.js";
import { listSubagentRunsForRequester } from "../../agents/subagent-registry.js";
import {
clearSubagentRunSteerRestart,
listSubagentRunsForRequester,
markSubagentRunTerminated,
markSubagentRunForSteerRestart,
replaceSubagentRunAfterSteer,
} from "../../agents/subagent-registry.js";
import {
extractAssistantText,
resolveInternalSessionKey,
@@ -11,10 +17,14 @@ import {
sanitizeTextContent,
stripToolMessages,
} from "../../agents/tools/sessions-helpers.js";
import { loadSessionStore, resolveStorePath, updateSessionStore } from "../../config/sessions.js";
import {
type SessionEntry,
loadSessionStore,
resolveStorePath,
updateSessionStore,
} from "../../config/sessions.js";
import { callGateway } from "../../gateway/call.js";
import { logVerbose } from "../../globals.js";
import { formatDurationCompact } from "../../infra/format-time/format-duration.ts";
import { formatTimeAgo } from "../../infra/format-time/format-relative.ts";
import { parseAgentSessionKey } from "../../routing/session-key.js";
import { INTERNAL_MESSAGE_CHANNEL } from "../../utils/message-channel.js";
@@ -28,7 +38,163 @@ type SubagentTargetResolution = {
};
const COMMAND = "/subagents";
const ACTIONS = new Set(["list", "stop", "log", "send", "info", "help"]);
const COMMAND_KILL = "/kill";
const COMMAND_STEER = "/steer";
const COMMAND_TELL = "/tell";
const ACTIONS = new Set(["list", "kill", "log", "send", "steer", "info", "help"]);
const RECENT_WINDOW_MINUTES = 30;
const SUBAGENT_TASK_PREVIEW_MAX = 110;
const STEER_ABORT_SETTLE_TIMEOUT_MS = 5_000;
function formatDurationCompact(valueMs?: number) {
if (!valueMs || !Number.isFinite(valueMs) || valueMs <= 0) {
return "n/a";
}
const minutes = Math.max(1, Math.round(valueMs / 60_000));
if (minutes < 60) {
return `${minutes}m`;
}
const hours = Math.floor(minutes / 60);
const minutesRemainder = minutes % 60;
if (hours < 24) {
return minutesRemainder > 0 ? `${hours}h${minutesRemainder}m` : `${hours}h`;
}
const days = Math.floor(hours / 24);
const hoursRemainder = hours % 24;
return hoursRemainder > 0 ? `${days}d${hoursRemainder}h` : `${days}d`;
}
function formatTokenShort(value?: number) {
if (!value || !Number.isFinite(value) || value <= 0) {
return undefined;
}
const n = Math.floor(value);
if (n < 1_000) {
return `${n}`;
}
if (n < 10_000) {
return `${(n / 1_000).toFixed(1).replace(/\.0$/, "")}k`;
}
if (n < 1_000_000) {
return `${Math.round(n / 1_000)}k`;
}
return `${(n / 1_000_000).toFixed(1).replace(/\.0$/, "")}m`;
}
function truncateLine(value: string, maxLength: number) {
if (value.length <= maxLength) {
return value;
}
return `${value.slice(0, maxLength).trimEnd()}...`;
}
function compactLine(value: string) {
return value.replace(/\s+/g, " ").trim();
}
function formatTaskPreview(value: string) {
return truncateLine(compactLine(value), SUBAGENT_TASK_PREVIEW_MAX);
}
function resolveModelDisplay(
entry?: {
model?: unknown;
modelProvider?: unknown;
modelOverride?: unknown;
providerOverride?: unknown;
},
fallbackModel?: string,
) {
const model = typeof entry?.model === "string" ? entry.model.trim() : "";
const provider = typeof entry?.modelProvider === "string" ? entry.modelProvider.trim() : "";
let combined = model.includes("/") ? model : model && provider ? `${provider}/${model}` : model;
if (!combined) {
// Fall back to override fields which are populated at spawn time,
// before the first run completes and writes model/modelProvider.
const overrideModel =
typeof entry?.modelOverride === "string" ? entry.modelOverride.trim() : "";
const overrideProvider =
typeof entry?.providerOverride === "string" ? entry.providerOverride.trim() : "";
combined = overrideModel.includes("/")
? overrideModel
: overrideModel && overrideProvider
? `${overrideProvider}/${overrideModel}`
: overrideModel;
}
if (!combined) {
combined = fallbackModel?.trim() || "";
}
if (!combined) {
return "model n/a";
}
const slash = combined.lastIndexOf("/");
if (slash >= 0 && slash < combined.length - 1) {
return combined.slice(slash + 1);
}
return combined;
}
function resolveTotalTokens(entry?: {
totalTokens?: unknown;
inputTokens?: unknown;
outputTokens?: unknown;
}) {
if (!entry || typeof entry !== "object") {
return undefined;
}
if (typeof entry.totalTokens === "number" && Number.isFinite(entry.totalTokens)) {
return entry.totalTokens;
}
const input = typeof entry.inputTokens === "number" ? entry.inputTokens : 0;
const output = typeof entry.outputTokens === "number" ? entry.outputTokens : 0;
const total = input + output;
return total > 0 ? total : undefined;
}
function resolveIoTokens(entry?: { inputTokens?: unknown; outputTokens?: unknown }) {
if (!entry || typeof entry !== "object") {
return undefined;
}
const input =
typeof entry.inputTokens === "number" && Number.isFinite(entry.inputTokens)
? entry.inputTokens
: 0;
const output =
typeof entry.outputTokens === "number" && Number.isFinite(entry.outputTokens)
? entry.outputTokens
: 0;
const total = input + output;
if (total <= 0) {
return undefined;
}
return { input, output, total };
}
function resolveUsageDisplay(entry?: {
totalTokens?: unknown;
inputTokens?: unknown;
outputTokens?: unknown;
}) {
const io = resolveIoTokens(entry);
const promptCache = resolveTotalTokens(entry);
const parts: string[] = [];
if (io) {
const input = formatTokenShort(io.input) ?? "0";
const output = formatTokenShort(io.output) ?? "0";
parts.push(`tokens ${formatTokenShort(io.total)} (in ${input} / out ${output})`);
} else if (typeof promptCache === "number" && promptCache > 0) {
parts.push(`tokens ${formatTokenShort(promptCache)} prompt/cache`);
}
if (typeof promptCache === "number" && io && promptCache > io.total) {
parts.push(`prompt/cache ${formatTokenShort(promptCache)}`);
}
return parts.join(", ");
}
function resolveDisplayStatus(entry: SubagentRunRecord) {
const status = formatRunStatus(entry);
return status === "error" ? "failed" : status;
}
function formatTimestamp(valueMs?: number) {
if (!valueMs || !Number.isFinite(valueMs) || valueMs <= 0) {
@@ -66,17 +232,39 @@ function resolveSubagentTarget(
return { entry: sorted[0] };
}
const sorted = sortSubagentRuns(runs);
const recentCutoff = Date.now() - RECENT_WINDOW_MINUTES * 60_000;
const numericOrder = [
...sorted.filter((entry) => !entry.endedAt),
...sorted.filter((entry) => !!entry.endedAt && (entry.endedAt ?? 0) >= recentCutoff),
];
if (/^\d+$/.test(trimmed)) {
const idx = Number.parseInt(trimmed, 10);
if (!Number.isFinite(idx) || idx <= 0 || idx > sorted.length) {
if (!Number.isFinite(idx) || idx <= 0 || idx > numericOrder.length) {
return { error: `Invalid subagent index: ${trimmed}` };
}
return { entry: sorted[idx - 1] };
return { entry: numericOrder[idx - 1] };
}
if (trimmed.includes(":")) {
const match = runs.find((entry) => entry.childSessionKey === trimmed);
return match ? { entry: match } : { error: `Unknown subagent session: ${trimmed}` };
}
const lowered = trimmed.toLowerCase();
const byLabel = runs.filter((entry) => formatRunLabel(entry).toLowerCase() === lowered);
if (byLabel.length === 1) {
return { entry: byLabel[0] };
}
if (byLabel.length > 1) {
return { error: `Ambiguous subagent label: ${trimmed}` };
}
const byLabelPrefix = runs.filter((entry) =>
formatRunLabel(entry).toLowerCase().startsWith(lowered),
);
if (byLabelPrefix.length === 1) {
return { entry: byLabelPrefix[0] };
}
if (byLabelPrefix.length > 1) {
return { error: `Ambiguous subagent label prefix: ${trimmed}` };
}
const byRunId = runs.filter((entry) => entry.runId.startsWith(trimmed));
if (byRunId.length === 1) {
return { entry: byRunId[0] };
@@ -89,15 +277,19 @@ function resolveSubagentTarget(
function buildSubagentsHelp() {
return [
"🧭 Subagents",
"Subagents",
"Usage:",
"- /subagents list",
"- /subagents stop <id|#|all>",
"- /subagents kill <id|#|all>",
"- /subagents log <id|#> [limit] [tools]",
"- /subagents info <id|#>",
"- /subagents send <id|#> <message>",
"- /subagents steer <id|#> <message>",
"- /kill <id|#|all>",
"- /steer <id|#> <message>",
"- /tell <id|#> <message>",
"",
"Ids: use the list index (#), runId prefix, or full session key.",
"Ids: use the list index (#), runId/session prefix, label, or full session key.",
].join("\n");
}
@@ -158,10 +350,20 @@ function formatLogLines(messages: ChatMessage[]) {
return lines;
}
function loadSubagentSessionEntry(params: Parameters<CommandHandler>[0], childKey: string) {
type SessionStoreCache = Map<string, Record<string, SessionEntry>>;
function loadSubagentSessionEntry(
params: Parameters<CommandHandler>[0],
childKey: string,
storeCache?: SessionStoreCache,
) {
const parsed = parseAgentSessionKey(childKey);
const storePath = resolveStorePath(params.cfg.session?.store, { agentId: parsed?.agentId });
const store = loadSessionStore(storePath);
let store = storeCache?.get(storePath);
if (!store) {
store = loadSessionStore(storePath);
storeCache?.set(storePath, store);
}
return { storePath, store, entry: store[childKey] };
}
@@ -170,21 +372,39 @@ export const handleSubagentsCommand: CommandHandler = async (params, allowTextCo
return null;
}
const normalized = params.command.commandBodyNormalized;
if (!normalized.startsWith(COMMAND)) {
const handledPrefix = normalized.startsWith(COMMAND)
? COMMAND
: normalized.startsWith(COMMAND_KILL)
? COMMAND_KILL
: normalized.startsWith(COMMAND_STEER)
? COMMAND_STEER
: normalized.startsWith(COMMAND_TELL)
? COMMAND_TELL
: null;
if (!handledPrefix) {
return null;
}
if (!params.command.isAuthorizedSender) {
logVerbose(
`Ignoring /subagents from unauthorized sender: ${params.command.senderId || "<unknown>"}`,
`Ignoring ${handledPrefix} from unauthorized sender: ${params.command.senderId || "<unknown>"}`,
);
return { shouldContinue: false };
}
const rest = normalized.slice(COMMAND.length).trim();
const [actionRaw, ...restTokens] = rest.split(/\s+/).filter(Boolean);
const action = actionRaw?.toLowerCase() || "list";
if (!ACTIONS.has(action)) {
return { shouldContinue: false, reply: { text: buildSubagentsHelp() } };
const rest = normalized.slice(handledPrefix.length).trim();
const restTokens = rest.split(/\s+/).filter(Boolean);
let action = "list";
if (handledPrefix === COMMAND) {
const [actionRaw] = restTokens;
action = actionRaw?.toLowerCase() || "list";
if (!ACTIONS.has(action)) {
return { shouldContinue: false, reply: { text: buildSubagentsHelp() } };
}
restTokens.splice(0, 1);
} else if (handledPrefix === COMMAND_KILL) {
action = "kill";
} else {
action = "steer";
}
const requesterKey = resolveRequesterSessionKey(params);
@@ -198,43 +418,82 @@ export const handleSubagentsCommand: CommandHandler = async (params, allowTextCo
}
if (action === "list") {
if (runs.length === 0) {
return { shouldContinue: false, reply: { text: "🧭 Subagents: none for this session." } };
}
const sorted = sortSubagentRuns(runs);
const active = sorted.filter((entry) => !entry.endedAt);
const done = sorted.length - active.length;
const lines = ["🧭 Subagents (current session)", `Active: ${active.length} · Done: ${done}`];
sorted.forEach((entry, index) => {
const status = formatRunStatus(entry);
const label = formatRunLabel(entry);
const runtime =
entry.endedAt && entry.startedAt
? (formatDurationCompact(entry.endedAt - entry.startedAt) ?? "n/a")
: formatTimeAgo(Date.now() - (entry.startedAt ?? entry.createdAt), { fallback: "n/a" });
const runId = entry.runId.slice(0, 8);
lines.push(
`${index + 1}) ${status} · ${label} · ${runtime} · run ${runId} · ${entry.childSessionKey}`,
);
});
const now = Date.now();
const recentCutoff = now - RECENT_WINDOW_MINUTES * 60_000;
const storeCache: SessionStoreCache = new Map();
let index = 1;
const activeLines = sorted
.filter((entry) => !entry.endedAt)
.map((entry) => {
const { entry: sessionEntry } = loadSubagentSessionEntry(
params,
entry.childSessionKey,
storeCache,
);
const usageText = resolveUsageDisplay(sessionEntry);
const label = truncateLine(formatRunLabel(entry, { maxLength: 48 }), 48);
const task = formatTaskPreview(entry.task);
const runtime = formatDurationCompact(now - (entry.startedAt ?? entry.createdAt));
const status = resolveDisplayStatus(entry);
const line = `${index}. ${label} (${resolveModelDisplay(sessionEntry, entry.model)}, ${runtime}${usageText ? `, ${usageText}` : ""}) ${status}${task.toLowerCase() !== label.toLowerCase() ? ` - ${task}` : ""}`;
index += 1;
return line;
});
const recentLines = sorted
.filter((entry) => !!entry.endedAt && (entry.endedAt ?? 0) >= recentCutoff)
.map((entry) => {
const { entry: sessionEntry } = loadSubagentSessionEntry(
params,
entry.childSessionKey,
storeCache,
);
const usageText = resolveUsageDisplay(sessionEntry);
const label = truncateLine(formatRunLabel(entry, { maxLength: 48 }), 48);
const task = formatTaskPreview(entry.task);
const runtime = formatDurationCompact(
(entry.endedAt ?? now) - (entry.startedAt ?? entry.createdAt),
);
const status = resolveDisplayStatus(entry);
const line = `${index}. ${label} (${resolveModelDisplay(sessionEntry, entry.model)}, ${runtime}${usageText ? `, ${usageText}` : ""}) ${status}${task.toLowerCase() !== label.toLowerCase() ? ` - ${task}` : ""}`;
index += 1;
return line;
});
const lines = ["active subagents:", "-----"];
if (activeLines.length === 0) {
lines.push("(none)");
} else {
lines.push(activeLines.join("\n"));
}
lines.push("", `recent subagents (last ${RECENT_WINDOW_MINUTES}m):`, "-----");
if (recentLines.length === 0) {
lines.push("(none)");
} else {
lines.push(recentLines.join("\n"));
}
return { shouldContinue: false, reply: { text: lines.join("\n") } };
}
if (action === "stop") {
if (action === "kill") {
const target = restTokens[0];
if (!target) {
return { shouldContinue: false, reply: { text: "⚙️ Usage: /subagents stop <id|#|all>" } };
return {
shouldContinue: false,
reply: {
text:
handledPrefix === COMMAND
? "Usage: /subagents kill <id|#|all>"
: "Usage: /kill <id|#|all>",
},
};
}
if (target === "all" || target === "*") {
const { stopped } = stopSubagentsForRequester({
stopSubagentsForRequester({
cfg: params.cfg,
requesterSessionKey: requesterKey,
});
const label = stopped === 1 ? "subagent" : "subagents";
return {
shouldContinue: false,
reply: { text: `⚙️ Stopped ${stopped} ${label}.` },
};
return { shouldContinue: false };
}
const resolved = resolveSubagentTarget(runs, target);
if (!resolved.entry) {
@@ -246,7 +505,7 @@ export const handleSubagentsCommand: CommandHandler = async (params, allowTextCo
if (resolved.entry.endedAt) {
return {
shouldContinue: false,
reply: { text: "⚙️ Subagent already finished." },
reply: { text: `${formatRunLabel(resolved.entry)} is already finished.` },
};
}
@@ -259,7 +518,7 @@ export const handleSubagentsCommand: CommandHandler = async (params, allowTextCo
const cleared = clearSessionQueues([childKey, sessionId]);
if (cleared.followupCleared > 0 || cleared.laneCleared > 0) {
logVerbose(
`subagents stop: cleared followups=${cleared.followupCleared} lane=${cleared.laneCleared} keys=${cleared.keys.join(",")}`,
`subagents kill: cleared followups=${cleared.followupCleared} lane=${cleared.laneCleared} keys=${cleared.keys.join(",")}`,
);
}
if (entry) {
@@ -270,10 +529,17 @@ export const handleSubagentsCommand: CommandHandler = async (params, allowTextCo
nextStore[childKey] = entry;
});
}
return {
shouldContinue: false,
reply: { text: `⚙️ Stop requested for ${formatRunLabel(resolved.entry)}.` },
};
markSubagentRunTerminated({
runId: resolved.entry.runId,
childSessionKey: childKey,
reason: "killed",
});
// Cascade: also stop any sub-sub-agents spawned by this child.
stopSubagentsForRequester({
cfg: params.cfg,
requesterSessionKey: childKey,
});
return { shouldContinue: false };
}
if (action === "info") {
@@ -299,7 +565,7 @@ export const handleSubagentsCommand: CommandHandler = async (params, allowTextCo
: "n/a";
const lines = [
"ℹ️ Subagent info",
`Status: ${formatRunStatus(run)}`,
`Status: ${resolveDisplayStatus(run)}`,
`Label: ${formatRunLabel(run)}`,
`Task: ${run.task}`,
`Run: ${run.runId}`,
@@ -347,13 +613,20 @@ export const handleSubagentsCommand: CommandHandler = async (params, allowTextCo
return { shouldContinue: false, reply: { text: [header, ...lines].join("\n") } };
}
if (action === "send") {
if (action === "send" || action === "steer") {
const steerRequested = action === "steer";
const target = restTokens[0];
const message = restTokens.slice(1).join(" ").trim();
if (!target || !message) {
return {
shouldContinue: false,
reply: { text: "✉️ Usage: /subagents send <id|#> <message>" },
reply: {
text: steerRequested
? handledPrefix === COMMAND
? "Usage: /subagents steer <id|#> <message>"
: `Usage: ${handledPrefix} <id|#> <message>`
: "Usage: /subagents send <id|#> <message>",
},
};
}
const resolved = resolveSubagentTarget(runs, target);
@@ -363,6 +636,52 @@ export const handleSubagentsCommand: CommandHandler = async (params, allowTextCo
reply: { text: `⚠️ ${resolved.error ?? "Unknown subagent."}` },
};
}
if (steerRequested && resolved.entry.endedAt) {
return {
shouldContinue: false,
reply: { text: `${formatRunLabel(resolved.entry)} is already finished.` },
};
}
const { entry: targetSessionEntry } = loadSubagentSessionEntry(
params,
resolved.entry.childSessionKey,
);
const targetSessionId =
typeof targetSessionEntry?.sessionId === "string" && targetSessionEntry.sessionId.trim()
? targetSessionEntry.sessionId.trim()
: undefined;
if (steerRequested) {
// Suppress stale announce before interrupting the in-flight run.
markSubagentRunForSteerRestart(resolved.entry.runId);
// Force an immediate interruption and make steer the next run.
if (targetSessionId) {
abortEmbeddedPiRun(targetSessionId);
}
const cleared = clearSessionQueues([resolved.entry.childSessionKey, targetSessionId]);
if (cleared.followupCleared > 0 || cleared.laneCleared > 0) {
logVerbose(
`subagents steer: cleared followups=${cleared.followupCleared} lane=${cleared.laneCleared} keys=${cleared.keys.join(",")}`,
);
}
// Best effort: wait for the interrupted run to settle so the steer
// message is appended on the existing conversation state.
try {
await callGateway({
method: "agent.wait",
params: {
runId: resolved.entry.runId,
timeoutMs: STEER_ABORT_SETTLE_TIMEOUT_MS,
},
timeoutMs: STEER_ABORT_SETTLE_TIMEOUT_MS + 2_000,
});
} catch {
// Continue even if wait fails; steer should still be attempted.
}
}
const idempotencyKey = crypto.randomUUID();
let runId: string = idempotencyKey;
try {
@@ -371,10 +690,12 @@ export const handleSubagentsCommand: CommandHandler = async (params, allowTextCo
params: {
message,
sessionKey: resolved.entry.childSessionKey,
sessionId: targetSessionId,
idempotencyKey,
deliver: false,
channel: INTERNAL_MESSAGE_CHANNEL,
lane: AGENT_LANE_SUBAGENT,
timeout: 0,
},
timeoutMs: 10_000,
});
@@ -383,9 +704,29 @@ export const handleSubagentsCommand: CommandHandler = async (params, allowTextCo
runId = responseRunId;
}
} catch (err) {
if (steerRequested) {
// Replacement launch failed; restore announce behavior for the
// original run so completion is not silently suppressed.
clearSubagentRunSteerRestart(resolved.entry.runId);
}
const messageText =
err instanceof Error ? err.message : typeof err === "string" ? err : "error";
return { shouldContinue: false, reply: { text: `⚠️ Send failed: ${messageText}` } };
return { shouldContinue: false, reply: { text: `send failed: ${messageText}` } };
}
if (steerRequested) {
replaceSubagentRunAfterSteer({
previousRunId: resolved.entry.runId,
nextRunId: runId,
fallback: resolved.entry,
runTimeoutSeconds: resolved.entry.runTimeoutSeconds ?? 0,
});
return {
shouldContinue: false,
reply: {
text: `steered ${formatRunLabel(resolved.entry)} (run ${runId.slice(0, 8)}).`,
},
};
}
const waitMs = 30_000;

331
src/auto-reply/reply/commands.test.ts
View File

@@ -6,14 +6,22 @@ import type { OpenClawConfig } from "../../config/config.js";
import type { MsgContext } from "../templating.js";
import {
addSubagentRunForTests,
listSubagentRunsForRequester,
resetSubagentRegistryForTests,
} from "../../agents/subagent-registry.js";
import { updateSessionStore } from "../../config/sessions.js";
import * as internalHooks from "../../hooks/internal-hooks.js";
import { clearPluginCommands, registerPluginCommand } from "../../plugins/commands.js";
import { resetBashChatCommandForTests } from "./bash-command.js";
import { buildCommandContext, handleCommands } from "./commands.js";
import { parseInlineDirectives } from "./directive-handling.js";
const callGatewayMock = vi.fn();
vi.mock("../../gateway/call.js", () => ({
callGateway: (opts: unknown) => callGatewayMock(opts),
}));
import { buildCommandContext, handleCommands } from "./commands.js";
// Avoid expensive workspace scans during /context tests.
vi.mock("./commands-context-report.js", () => ({
buildContextReply: async (params: { command: { commandBodyNormalized: string } }) => {
@@ -256,6 +264,7 @@ describe("handleCommands context", () => {
describe("handleCommands subagents", () => {
it("lists subagents when none exist", async () => {
resetSubagentRegistryForTests();
callGatewayMock.mockReset();
const cfg = {
commands: { text: true },
channels: { whatsapp: { allowFrom: ["*"] } },
@@ -263,11 +272,43 @@ describe("handleCommands subagents", () => {
const params = buildParams("/subagents list", cfg);
const result = await handleCommands(params);
expect(result.shouldContinue).toBe(false);
expect(result.reply?.text).toContain("Subagents: none");
expect(result.reply?.text).toContain("active subagents:");
expect(result.reply?.text).toContain("active subagents:\n-----\n");
expect(result.reply?.text).toContain("recent subagents (last 30m):");
expect(result.reply?.text).toContain("\n\nrecent subagents (last 30m):");
expect(result.reply?.text).toContain("recent subagents (last 30m):\n-----\n");
});
it("truncates long subagent task text in /subagents list", async () => {
resetSubagentRegistryForTests();
callGatewayMock.mockReset();
addSubagentRunForTests({
runId: "run-long-task",
childSessionKey: "agent:main:subagent:long-task",
requesterSessionKey: "agent:main:main",
requesterDisplayKey: "main",
task: "This is a deliberately long task description used to verify that subagent list output keeps the full task text instead of appending ellipsis after a short hard cutoff.",
cleanup: "keep",
createdAt: 1000,
startedAt: 1000,
});
const cfg = {
commands: { text: true },
channels: { whatsapp: { allowFrom: ["*"] } },
} as OpenClawConfig;
const params = buildParams("/subagents list", cfg);
const result = await handleCommands(params);
expect(result.shouldContinue).toBe(false);
expect(result.reply?.text).toContain(
"This is a deliberately long task description used to verify that subagent list output keeps the full task text",
);
expect(result.reply?.text).toContain("...");
expect(result.reply?.text).not.toContain("after a short hard cutoff.");
});
it("lists subagents for the current command session over the target session", async () => {
resetSubagentRegistryForTests();
callGatewayMock.mockReset();
addSubagentRunForTests({
runId: "run-1",
childSessionKey: "agent:main:subagent:abc",
@@ -278,6 +319,16 @@ describe("handleCommands subagents", () => {
createdAt: 1000,
startedAt: 1000,
});
addSubagentRunForTests({
runId: "run-2",
childSessionKey: "agent:main:subagent:def",
requesterSessionKey: "agent:main:slack:slash:u1",
requesterDisplayKey: "agent:main:slack:slash:u1",
task: "another thing",
cleanup: "keep",
createdAt: 2000,
startedAt: 2000,
});
const cfg = {
commands: { text: true },
channels: { whatsapp: { allowFrom: ["*"] } },
@@ -289,8 +340,46 @@ describe("handleCommands subagents", () => {
params.sessionKey = "agent:main:slack:slash:u1";
const result = await handleCommands(params);
expect(result.shouldContinue).toBe(false);
expect(result.reply?.text).toContain("Subagents (current session)");
expect(result.reply?.text).toContain("agent:main:subagent:abc");
expect(result.reply?.text).toContain("active subagents:");
expect(result.reply?.text).toContain("do thing");
expect(result.reply?.text).not.toContain("\n\n2.");
});
it("formats subagent usage with io and prompt/cache breakdown", async () => {
resetSubagentRegistryForTests();
callGatewayMock.mockReset();
addSubagentRunForTests({
runId: "run-usage",
childSessionKey: "agent:main:subagent:usage",
requesterSessionKey: "agent:main:main",
requesterDisplayKey: "main",
task: "do thing",
cleanup: "keep",
createdAt: 1000,
startedAt: 1000,
});
const storePath = path.join(testWorkspaceDir, "sessions-subagents-usage.json");
await updateSessionStore(storePath, (store) => {
store["agent:main:subagent:usage"] = {
sessionId: "child-session-usage",
updatedAt: Date.now(),
inputTokens: 12,
outputTokens: 1000,
totalTokens: 197000,
model: "opencode/claude-opus-4-6",
};
});
const cfg = {
commands: { text: true },
channels: { whatsapp: { allowFrom: ["*"] } },
session: { store: storePath },
} as OpenClawConfig;
const params = buildParams("/subagents list", cfg);
const result = await handleCommands(params);
expect(result.shouldContinue).toBe(false);
expect(result.reply?.text).toContain("tokens 1k (in 12 / out 1k)");
expect(result.reply?.text).toContain("prompt/cache 197k");
expect(result.reply?.text).not.toContain("1k io");
});
it("omits subagent status line when none exist", async () => {
@@ -309,6 +398,7 @@ describe("handleCommands subagents", () => {
it("returns help for unknown subagents action", async () => {
resetSubagentRegistryForTests();
callGatewayMock.mockReset();
const cfg = {
commands: { text: true },
channels: { whatsapp: { allowFrom: ["*"] } },
@@ -321,6 +411,7 @@ describe("handleCommands subagents", () => {
it("returns usage for subagents info without target", async () => {
resetSubagentRegistryForTests();
callGatewayMock.mockReset();
const cfg = {
commands: { text: true },
channels: { whatsapp: { allowFrom: ["*"] } },
@@ -333,6 +424,7 @@ describe("handleCommands subagents", () => {
it("includes subagent count in /status when active", async () => {
resetSubagentRegistryForTests();
callGatewayMock.mockReset();
addSubagentRunForTests({
runId: "run-1",
childSessionKey: "agent:main:subagent:abc",
@@ -356,6 +448,7 @@ describe("handleCommands subagents", () => {
it("includes subagent details in /status when verbose", async () => {
resetSubagentRegistryForTests();
callGatewayMock.mockReset();
addSubagentRunForTests({
runId: "run-1",
childSessionKey: "agent:main:subagent:abc",
@@ -393,6 +486,8 @@ describe("handleCommands subagents", () => {
it("returns info for a subagent", async () => {
resetSubagentRegistryForTests();
callGatewayMock.mockReset();
const now = Date.now();
addSubagentRunForTests({
runId: "run-1",
childSessionKey: "agent:main:subagent:abc",
@@ -400,9 +495,9 @@ describe("handleCommands subagents", () => {
requesterDisplayKey: "main",
task: "do thing",
cleanup: "keep",
createdAt: 1000,
startedAt: 1000,
endedAt: 2000,
createdAt: now - 20_000,
startedAt: now - 20_000,
endedAt: now - 1_000,
outcome: { status: "ok" },
});
const cfg = {
@@ -417,6 +512,228 @@ describe("handleCommands subagents", () => {
expect(result.reply?.text).toContain("Run: run-1");
expect(result.reply?.text).toContain("Status: done");
});
it("kills subagents via /kill alias without a confirmation reply", async () => {
resetSubagentRegistryForTests();
callGatewayMock.mockReset();
addSubagentRunForTests({
runId: "run-1",
childSessionKey: "agent:main:subagent:abc",
requesterSessionKey: "agent:main:main",
requesterDisplayKey: "main",
task: "do thing",
cleanup: "keep",
createdAt: 1000,
startedAt: 1000,
});
const cfg = {
commands: { text: true },
channels: { whatsapp: { allowFrom: ["*"] } },
} as OpenClawConfig;
const params = buildParams("/kill 1", cfg);
const result = await handleCommands(params);
expect(result.shouldContinue).toBe(false);
expect(result.reply).toBeUndefined();
});
it("resolves numeric aliases in active-first display order", async () => {
resetSubagentRegistryForTests();
callGatewayMock.mockReset();
const now = Date.now();
addSubagentRunForTests({
runId: "run-active",
childSessionKey: "agent:main:subagent:active",
requesterSessionKey: "agent:main:main",
requesterDisplayKey: "main",
task: "active task",
cleanup: "keep",
createdAt: now - 120_000,
startedAt: now - 120_000,
});
addSubagentRunForTests({
runId: "run-recent",
childSessionKey: "agent:main:subagent:recent",
requesterSessionKey: "agent:main:main",
requesterDisplayKey: "main",
task: "recent task",
cleanup: "keep",
createdAt: now - 30_000,
startedAt: now - 30_000,
endedAt: now - 10_000,
outcome: { status: "ok" },
});
const cfg = {
commands: { text: true },
channels: { whatsapp: { allowFrom: ["*"] } },
} as OpenClawConfig;
const params = buildParams("/kill 1", cfg);
const result = await handleCommands(params);
expect(result.shouldContinue).toBe(false);
expect(result.reply).toBeUndefined();
});
it("sends follow-up messages to finished subagents", async () => {
resetSubagentRegistryForTests();
callGatewayMock.mockReset();
callGatewayMock.mockImplementation(async (opts: unknown) => {
const request = opts as { method?: string; params?: { runId?: string } };
if (request.method === "agent") {
return { runId: "run-followup-1" };
}
if (request.method === "agent.wait") {
return { status: "done" };
}
if (request.method === "chat.history") {
return { messages: [] };
}
return {};
});
const now = Date.now();
addSubagentRunForTests({
runId: "run-1",
childSessionKey: "agent:main:subagent:abc",
requesterSessionKey: "agent:main:main",
requesterDisplayKey: "main",
task: "do thing",
cleanup: "keep",
createdAt: now - 20_000,
startedAt: now - 20_000,
endedAt: now - 1_000,
outcome: { status: "ok" },
});
const cfg = {
commands: { text: true },
channels: { whatsapp: { allowFrom: ["*"] } },
} as OpenClawConfig;
const params = buildParams("/subagents send 1 continue with follow-up details", cfg);
const result = await handleCommands(params);
expect(result.shouldContinue).toBe(false);
expect(result.reply?.text).toContain("✅ Sent to");
const agentCall = callGatewayMock.mock.calls.find(
(call) => (call[0] as { method?: string }).method === "agent",
);
expect(agentCall?.[0]).toMatchObject({
method: "agent",
params: {
lane: "subagent",
sessionKey: "agent:main:subagent:abc",
timeout: 0,
},
});
const waitCall = callGatewayMock.mock.calls.find(
(call) =>
(call[0] as { method?: string; params?: { runId?: string } }).method === "agent.wait" &&
(call[0] as { method?: string; params?: { runId?: string } }).params?.runId ===
"run-followup-1",
);
expect(waitCall).toBeDefined();
});
it("steers subagents via /steer alias", async () => {
resetSubagentRegistryForTests();
callGatewayMock.mockReset();
callGatewayMock.mockImplementation(async (opts: unknown) => {
const request = opts as { method?: string };
if (request.method === "agent") {
return { runId: "run-steer-1" };
}
return {};
});
const storePath = path.join(testWorkspaceDir, "sessions-subagents-steer.json");
await updateSessionStore(storePath, (store) => {
store["agent:main:subagent:abc"] = {
sessionId: "child-session-steer",
updatedAt: Date.now(),
};
});
addSubagentRunForTests({
runId: "run-1",
childSessionKey: "agent:main:subagent:abc",
requesterSessionKey: "agent:main:main",
requesterDisplayKey: "main",
task: "do thing",
cleanup: "keep",
createdAt: 1000,
startedAt: 1000,
});
const cfg = {
commands: { text: true },
channels: { whatsapp: { allowFrom: ["*"] } },
session: { store: storePath },
} as OpenClawConfig;
const params = buildParams("/steer 1 check timer.ts instead", cfg);
const result = await handleCommands(params);
expect(result.shouldContinue).toBe(false);
expect(result.reply?.text).toContain("steered");
const steerWaitIndex = callGatewayMock.mock.calls.findIndex(
(call) =>
(call[0] as { method?: string; params?: { runId?: string } }).method === "agent.wait" &&
(call[0] as { method?: string; params?: { runId?: string } }).params?.runId === "run-1",
);
expect(steerWaitIndex).toBeGreaterThanOrEqual(0);
const steerRunIndex = callGatewayMock.mock.calls.findIndex(
(call) => (call[0] as { method?: string }).method === "agent",
);
expect(steerRunIndex).toBeGreaterThan(steerWaitIndex);
expect(callGatewayMock.mock.calls[steerWaitIndex]?.[0]).toMatchObject({
method: "agent.wait",
params: { runId: "run-1", timeoutMs: 5_000 },
timeoutMs: 7_000,
});
expect(callGatewayMock.mock.calls[steerRunIndex]?.[0]).toMatchObject({
method: "agent",
params: {
lane: "subagent",
sessionKey: "agent:main:subagent:abc",
sessionId: "child-session-steer",
timeout: 0,
},
});
const trackedRuns = listSubagentRunsForRequester("agent:main:main");
expect(trackedRuns).toHaveLength(1);
expect(trackedRuns[0].runId).toBe("run-steer-1");
expect(trackedRuns[0].endedAt).toBeUndefined();
});
it("restores announce behavior when /steer replacement dispatch fails", async () => {
resetSubagentRegistryForTests();
callGatewayMock.mockReset();
callGatewayMock.mockImplementation(async (opts: unknown) => {
const request = opts as { method?: string };
if (request.method === "agent.wait") {
return { status: "timeout" };
}
if (request.method === "agent") {
throw new Error("dispatch failed");
}
return {};
});
addSubagentRunForTests({
runId: "run-1",
childSessionKey: "agent:main:subagent:abc",
requesterSessionKey: "agent:main:main",
requesterDisplayKey: "main",
task: "do thing",
cleanup: "keep",
createdAt: 1000,
startedAt: 1000,
});
const cfg = {
commands: { text: true },
channels: { whatsapp: { allowFrom: ["*"] } },
} as OpenClawConfig;
const params = buildParams("/steer 1 check timer.ts instead", cfg);
const result = await handleCommands(params);
expect(result.shouldContinue).toBe(false);
expect(result.reply?.text).toContain("send failed: dispatch failed");
const trackedRuns = listSubagentRunsForRequester("agent:main:main");
expect(trackedRuns).toHaveLength(1);
expect(trackedRuns[0].runId).toBe("run-1");
expect(trackedRuns[0].suppressAnnounceReason).toBeUndefined();
});
});
describe("handleCommands /tts", () => {

2
src/auto-reply/reply/followup-runner.test.ts
View File

@@ -81,7 +81,7 @@ describe("createFollowupRunner compaction", () => {
}) => {
params.onAgentEvent?.({
stream: "compaction",
data: { phase: "end", willRetry: false },
data: { phase: "end", willRetry: true },
});
return { payloads: [{ text: "final" }], meta: {} };
},

3
src/auto-reply/reply/followup-runner.ts
View File

@@ -176,8 +176,7 @@ export function createFollowupRunner(params: {
return;
}
const phase = typeof evt.data.phase === "string" ? evt.data.phase : "";
const willRetry = Boolean(evt.data.willRetry);
if (phase === "end" && !willRetry) {
if (phase === "end") {
autoCompactionCompleted = true;
}
},

1
src/auto-reply/reply/get-reply-run.media-only.test.ts
View File

@@ -50,6 +50,7 @@ vi.mock("./body.js", () => ({
vi.mock("./groups.js", () => ({
buildGroupIntro: vi.fn().mockReturnValue(""),
buildGroupChatContext: vi.fn().mockReturnValue(""),
}));
vi.mock("./inbound-meta.js", () => ({

7
src/auto-reply/reply/get-reply-run.ts
View File

@@ -39,7 +39,7 @@ import {
import { SILENT_REPLY_TOKEN } from "../tokens.js";
import { runReplyAgent } from "./agent-runner.js";
import { applySessionHints } from "./body.js";
import { buildGroupIntro } from "./groups.js";
import { buildGroupChatContext, buildGroupIntro } from "./groups.js";
import { buildInboundMetaSystemPrompt, buildInboundUserContextPrefix } from "./inbound-meta.js";
import { resolveQueueSettings } from "./queue.js";
import { routeReply } from "./route-reply.js";
@@ -171,6 +171,9 @@ export async function runPreparedReply(
const shouldInjectGroupIntro = Boolean(
isGroupChat && (isFirstTurnInSession || sessionEntry?.groupActivationNeedsSystemIntro),
);
// Always include persistent group chat context (name, participants, reply guidance)
const groupChatContext = isGroupChat ? buildGroupChatContext({ sessionCtx }) : "";
// Behavioral intro (activation mode, lurking, etc.) only on first turn / activation needed
const groupIntro = shouldInjectGroupIntro
? buildGroupIntro({
cfg,
@@ -184,7 +187,7 @@ export async function runPreparedReply(
const inboundMetaPrompt = buildInboundMetaSystemPrompt(
isNewSession ? sessionCtx : { ...sessionCtx, ThreadStarterBody: undefined },
);
const extraSystemPrompt = [inboundMetaPrompt, groupIntro, groupSystemPrompt]
const extraSystemPrompt = [inboundMetaPrompt, groupChatContext, groupIntro, groupSystemPrompt]
.filter(Boolean)
.join("\n\n");
const baseBody = sessionCtx.BodyStripped ?? sessionCtx.Body ?? "";

2
src/auto-reply/reply/get-reply.ts
View File

@@ -105,7 +105,7 @@ export async function getReplyFromConfig(
});
const workspaceDir = workspace.dir;
const agentDir = resolveAgentDir(cfg, agentId);
const timeoutMs = resolveAgentTimeoutMs({ cfg });
const timeoutMs = resolveAgentTimeoutMs({ cfg, overrideSeconds: opts?.timeoutOverrideSeconds });
const configuredTypingSeconds =
agentCfg?.typingIntervalSeconds ?? sessionCfg?.typingIntervalSeconds;
const typingIntervalSeconds =

71
src/auto-reply/reply/groups.ts
View File

@@ -59,6 +59,51 @@ export function defaultGroupActivation(requireMention: boolean): "always" | "men
return !requireMention ? "always" : "mention";
}
/**
* Resolve a human-readable provider label from the raw provider string.
*/
function resolveProviderLabel(rawProvider: string | undefined): string {
const providerKey = rawProvider?.trim().toLowerCase() ?? "";
if (!providerKey) {
return "chat";
}
if (isInternalMessageChannel(providerKey)) {
return "WebChat";
}
const providerId = normalizeChannelId(rawProvider?.trim());
if (providerId) {
return getChannelPlugin(providerId)?.meta.label ?? providerId;
}
return `${providerKey.at(0)?.toUpperCase() ?? ""}${providerKey.slice(1)}`;
}
/**
* Build a persistent group-chat context block that is always included in the
* system prompt for group-chat sessions (every turn, not just the first).
*
* Contains: group name, participants, and an explicit instruction to reply
* directly instead of using the message tool.
*/
export function buildGroupChatContext(params: { sessionCtx: TemplateContext }): string {
const subject = params.sessionCtx.GroupSubject?.trim();
const members = params.sessionCtx.GroupMembers?.trim();
const providerLabel = resolveProviderLabel(params.sessionCtx.Provider);
const lines: string[] = [];
if (subject) {
lines.push(`You are in the ${providerLabel} group chat "${subject}".`);
} else {
lines.push(`You are in a ${providerLabel} group chat.`);
}
if (members) {
lines.push(`Participants: ${members}.`);
}
lines.push(
"Your replies are automatically sent to this group chat. Do not use the message tool to send to this same group — just reply normally.",
);
return lines.join(" ");
}
export function buildGroupIntro(params: {
cfg: OpenClawConfig;
sessionCtx: TemplateContext;
@@ -69,23 +114,7 @@ export function buildGroupIntro(params: {
const activation =
normalizeGroupActivation(params.sessionEntry?.groupActivation) ?? params.defaultActivation;
const rawProvider = params.sessionCtx.Provider?.trim();
const providerKey = rawProvider?.toLowerCase() ?? "";
const providerId = normalizeChannelId(rawProvider);
const providerLabel = (() => {
if (!providerKey) {
return "chat";
}
if (isInternalMessageChannel(providerKey)) {
return "WebChat";
}
if (providerId) {
return getChannelPlugin(providerId)?.meta.label ?? providerId;
}
return `${providerKey.at(0)?.toUpperCase() ?? ""}${providerKey.slice(1)}`;
})();
// Do not embed attacker-controlled labels (group subject, members) in system prompts.
// These labels are provided as user-role "untrusted context" blocks instead.
const subjectLine = `You are replying inside a ${providerLabel} group chat.`;
const activationLine =
activation === "always"
? "Activation: always-on (you receive every group message)."
@@ -115,15 +144,7 @@ export function buildGroupIntro(params: {
"Be a good group participant: mostly lurk and follow the conversation; reply only when directly addressed or you can add clear value. Emoji reactions are welcome when available.";
const styleLine =
"Write like a human. Avoid Markdown tables. Don't type literal \\n sequences; use real line breaks sparingly.";
return [
subjectLine,
activationLine,
providerIdsLine,
silenceLine,
cautionLine,
lurkLine,
styleLine,
]
return [activationLine, providerIdsLine, silenceLine, cautionLine, lurkLine, styleLine]
.filter(Boolean)
.join(" ")
.concat(" Address the specific sender noted in the message context.");