should be treated as `direct`, `group`, or `channel` before directory lookup.

- `messaging.targetResolver.looksLikeId(raw, normalized)` tells core whether an

input should skip straight to id-like resolution instead of directory search.

- `messaging.targetResolver.reservedLiterals` lists bare words that are

channel/session references for that provider and must fail closed before

directory or default-target fallback.

- `messaging.targetResolver.resolveTarget(...)` is the plugin fallback when

core needs a final provider-owned resolution after normalization or after a

directory miss.

describeMessageTool and action discovery

</Card>

<Card title="Target resolution" icon="crosshair" href="/plugins/architecture-internals#channel-target-resolution">

inferTargetChatType, looksLikeId, resolveTarget

inferTargetChatType, looksLikeId, reservedLiterals, resolveTarget

</Card>

<Card title="Runtime helpers" icon="settings" href="/plugins/sdk-runtime">

TTS, STT, media, subagent via api.runtime

targetResolver: {

looksLikeId: looksLikeTelegramTargetId,

hint: "<chatId>",

reservedLiterals: ["current", "self", "this", "me"],

},

},

resolver: {

expect(typeof messaging.targetResolver.hint).toBe("string");

expect(messaging.targetResolver.hint.trim()).not.toBe("");

}

if (messaging.targetResolver.reservedLiterals !== undefined) {

expect(Array.isArray(messaging.targetResolver.reservedLiterals)).toBe(true);

expect(

messaging.targetResolver.reservedLiterals.every(

(value) => typeof value === "string" && value.trim(),

),

).toBe(true);

}

if (messaging.targetResolver.resolveTarget) {

expect(typeof messaging.targetResolver.resolveTarget).toBe("function");

}

targetResolver?: {

looksLikeId?: (raw: string, normalized?: string) => boolean;

hint?: string;

/** Bare words that are command/session references for this channel, not literal destinations. */

reservedLiterals?: readonly string[];

/**

* Plugin-owned fallback for explicit/native targets or post-directory-miss

* resolution. This should complement directory lookup, not duplicate it.

let resolvedTo = deliveryPlan.resolvedTo;

let effectivePlan = deliveryPlan;

let deliveryDowngradeReason: string | null = null;

let deliveryTargetResolutionError: Error | undefined;

let deliveryTargetResolutionError: Error | undefined = deliveryPlan.targetResolutionError;

if (wantsDelivery && resolvedChannel === INTERNAL_MESSAGE_CHANNEL) {

const cfgResolved = cfgForAgent ?? cfg;

}

}

if (wantsDelivery && deliveryTargetResolutionError) {

if (!bestEffortDeliver) {

respond(

false,

undefined,

errorShape(ErrorCodes.INVALID_REQUEST, String(deliveryTargetResolutionError)),

);

return;

}

deliveryDowngradeReason = String(deliveryTargetResolutionError);

resolvedChannel = INTERNAL_MESSAGE_CHANNEL;

deliveryTargetMode = undefined;

resolvedTo = undefined;

effectivePlan = {

...deliveryPlan,

resolvedChannel,

resolvedTo,

deliveryTargetMode,

};

}

if (!resolvedTo && isDeliverableMessageChannel(resolvedChannel)) {

const cfgResolved = cfgForAgent ?? cfg;

const fallback = resolveAgentOutboundTarget({

expect(plan.resolvedTo).toBe("1470130713209602050");

});

it("carries explicit target resolution errors from session-route preparation", async () => {

const targetResolutionError = new Error('reserved target "current"');

mocks.resolveOutboundChannelPlugin.mockReturnValue({

messaging: { resolveOutboundSessionRoute: vi.fn() },

});

mocks.resolveOutboundTarget.mockReturnValueOnce({

ok: false,

error: targetResolutionError,

});

const plan = await resolveAgentDeliveryPlanWithSessionRoute({

cfg: {} as OpenClawConfig,

agentId: "agent",

sessionEntry: undefined,

requestedChannel: "workspace",

explicitTo: "current",

accountId: undefined,

wantsDelivery: true,

});

expect(mocks.resolveOutboundSessionRoute).not.toHaveBeenCalled();

expect(plan.resolvedTo).toBe("current");

expect(plan.targetResolutionError).toBe(targetResolutionError);

});

it("surfaces stored explicit target errors even when explicit validation is disabled", () => {

const targetResolutionError = new Error('reserved target "current"');

const resolved = resolveAgentOutboundTarget({

cfg: {} as OpenClawConfig,

plan: {

baseDelivery: { mode: "explicit" },

resolvedChannel: "workspace",

resolvedTo: "current",

deliveryTargetMode: "explicit",

targetResolutionError,

},

targetMode: "explicit",

validateExplicitTarget: false,

});

expect(mocks.resolveOutboundTarget).not.toHaveBeenCalled();

expect(resolved.resolvedTarget).toEqual({ ok: false, error: targetResolutionError });

expect(resolved.resolvedTo).toBeUndefined();

});

it("falls back to the original plan when session-route canonicalization fails", async () => {

mocks.resolveOutboundChannelPlugin.mockReturnValue({

messaging: { resolveOutboundSessionRoute: vi.fn() },

resolvedAccountId?: string;

resolvedThreadId?: string | number;

deliveryTargetMode?: ChannelOutboundTargetMode;

targetResolutionError?: Error;

};

export function resolveAgentDeliveryPlan(params: {

mode: plan.deliveryTargetMode ?? "explicit",

});

if (!normalizedTarget.ok) {

return plan;

return { ...plan, targetResolutionError: normalizedTarget.error };

}

const explicitThreadId =

params.explicitThreadId != null && params.explicitThreadId !== ""

params.targetMode ??

params.plan.deliveryTargetMode ??

(params.plan.resolvedTo ? "explicit" : "implicit");

if (params.plan.targetResolutionError) {

return {

resolvedTarget: { ok: false, error: params.plan.targetResolutionError },

resolvedTo: undefined,

targetMode,

};

}

if (!isDeliverableMessageChannel(params.plan.resolvedChannel)) {

return {

resolvedTarget: null,

return new Error(unknownTargetMessage(provider, raw, hint));

}

export function reservedTargetLiteralMessage(provider: string, raw: string, hint?: string): string {

return `Reserved target "${raw}" for ${provider} cannot be used as a literal destination. Provide an explicit id or handle.${formatTargetHint(hint, true)}`;

}

export function reservedTargetLiteralError(provider: string, raw: string, hint?: string): Error {

return new Error(reservedTargetLiteralMessage(provider, raw, hint));

}

function formatTargetHint(hint?: string, withLabel = false): string {

const normalized = hint?.trim();

if (!normalized) {

return getLoadedChannelPluginForRead(channelId) ?? getChannelPlugin(channelId);

}

function normalizeTargetLiteral(value: string): string | undefined {

return normalizeOptionalLowercaseString(value);

}

function stripPluginTargetPrefix(raw: string, plugin: ChannelPlugin): string {

let target = raw.trim();

const prefixes = [plugin.id, ...(plugin.messaging?.targetPrefixes ?? [])]

.map((prefix) => normalizeTargetLiteral(String(prefix)))

.filter((prefix): prefix is string => Boolean(prefix));

while (target) {

const lowered = normalizeTargetLiteral(target) ?? "";

const prefix = prefixes.find((candidate) => lowered.startsWith(`${candidate}:`));

if (!prefix) {

return target;

}

target = target.slice(prefix.length + 1).trim();

}

return target;

}

export function resolveReservedTargetLiteral(params: {

raw?: string;

plugin?: ChannelPlugin;

}): string | undefined {

const raw = normalizeOptionalString(params.raw);

const plugin = params.plugin;

const reservedLiterals = plugin?.messaging?.targetResolver?.reservedLiterals;

if (!raw || !plugin || !reservedLiterals?.length) {

return undefined;

}

const stripped = stripPluginTargetPrefix(raw, plugin);

if (!stripped || /^[@#]/.test(stripped) || /^(channel|group|user):/i.test(stripped)) {

return undefined;

}

const normalized = normalizeTargetLiteral(stripped);

if (!normalized) {

return undefined;

}

const reserved = new Set(

reservedLiterals

.map(normalizeTargetLiteral)

.filter((literal): literal is string => Boolean(literal)),

);

return reserved.has(normalized) ? normalized : undefined;

}

function resetTargetNormalizerCacheForTests(): void {

targetNormalizerCacheByChannelId.clear();

}

: "pinned";

const resolver = plugin?.messaging?.targetResolver;

const hint = resolver?.hint ?? "";

const reserved = (resolver?.reservedLiterals ?? [])

.map(normalizeTargetLiteral)

.filter((literal): literal is string => Boolean(literal))

.toSorted()

.join(",");

const looksLike = resolver?.looksLikeId;

// Function source is only a cheap invalidation hint; resolver behavior still belongs to the plugin.

const source = looksLike ? looksLike.toString() : "";

return hashSignature(`${registryScope}|${hint}|${source}`);

return hashSignature(`${registryScope}|${hint}|${reserved}|${source}`);

}

function hashSignature(value: string): string {