import fs from "node:fs";

import path from "node:path";

import { resolveAgentRuntimeMetadata } from "../agents/agent-runtime-metadata.js";

import {

listAgentIds,

resolveAgentConfig,

resolveAgentEffectiveModelPrimary,

resolveAgentModelFallbacksOverride,

resolveAgentWorkspaceDir,

resolveDefaultAgentId,

} from "../agents/agent-scope.js";

import { lookupContextTokens, resolveContextTokensForModel } from "../agents/context.js";

import { DEFAULT_CONTEXT_TOKENS, DEFAULT_MODEL, DEFAULT_PROVIDER } from "../agents/defaults.js";

import {

findModelCatalogEntry,

modelSupportsInput,

type ModelCatalogEntry,

} from "../agents/model-catalog.js";

import {

inferUniqueProviderFromConfiguredModels,

isCliProvider,

normalizeStoredOverrideModel,

parseModelRef,

resolveConfiguredModelRef,

resolveDefaultModelForAgent,

resolvePersistedSelectedModelRef,

resolveThinkingDefault,

} from "../agents/model-selection.js";

import {

countActiveDescendantRuns,

getSessionDisplaySubagentRunByChildSessionKey,

getSubagentSessionRuntimeMs,

getSubagentSessionStartedAt,

isSubagentRunLive,

listSubagentRunsForController,

resolveSubagentSessionStatus,

} from "../agents/subagent-registry-read.js";

import {

RECENT_ENDED_SUBAGENT_CHILD_SESSION_MS,

shouldKeepSubagentRunChildLink,

} from "../agents/subagent-run-liveness.js";

import { listThinkingLevelOptions } from "../auto-reply/thinking.js";

import { getRuntimeConfig } from "../config/io.js";

import { resolveAgentModelFallbackValues } from "../config/model-input.js";

import { resolveStateDir } from "../config/paths.js";

import {

buildGroupDisplayName,

loadSessionStore,

resolveAllAgentSessionStoreTargetsSync,

resolveAgentMainSessionKey,

resolveFreshSessionTotalTokens,

resolveStorePath,

type SessionEntry,

type SessionStoreTarget,

type SessionScope,

} from "../config/sessions.js";

import type { OpenClawConfig } from "../config/types.openclaw.js";

import { openBoundaryFileSync } from "../infra/boundary-file-read.js";

import { projectPluginSessionExtensionsSync } from "../plugins/host-hook-state.js";

import {

DEFAULT_AGENT_ID,

normalizeAgentId,

normalizeMainKey,

parseAgentSessionKey,

} from "../routing/session-key.js";

import { isCronRunSessionKey } from "../sessions/session-key-utils.js";

import {

AVATAR_MAX_BYTES,

isAvatarDataUrl,

isAvatarHttpUrl,

isPathWithinRoot,

isWorkspaceRelativeAvatarPath,

resolveAvatarMime,

} from "../shared/avatar-policy.js";

import {

normalizeLowercaseStringOrEmpty,

normalizeOptionalString,

normalizeOptionalLowercaseString,

} from "../shared/string-coerce.js";

import { normalizeSessionDeliveryFields } from "../utils/delivery-context.shared.js";

import { estimateUsageCost, resolveModelCostConfig } from "../utils/usage-format.js";

import {

canonicalizeSpawnedByForAgent,

resolveSessionStoreAgentId,

resolveSessionStoreKey,

resolveStoredSessionKeyForAgentStore,

} from "./session-store-key.js";

import {

readLatestSessionUsageFromTranscript,

readRecentSessionUsageFromTranscript,

readSessionTitleFieldsFromTranscript,

} from "./session-utils.fs.js";

import type {

GatewayAgentRow,

GatewaySessionRow,

GatewaySessionsDefaults,

SessionRunStatus,

SessionsListResult,

} from "./session-utils.types.js";

export {

archiveFileOnDisk,

archiveSessionTranscripts,

attachOpenClawTranscriptMeta,

capArrayByJsonBytes,

readFirstUserMessageFromTranscript,

readLastMessagePreviewFromTranscript,

readLatestSessionUsageFromTranscript,

readRecentSessionUsageFromTranscript,

readRecentSessionMessages,

readSessionTitleFieldsFromTranscript,

readSessionPreviewItemsFromTranscript,

readSessionMessages,

resolveSessionTranscriptCandidates,

} from "./session-utils.fs.js";

export { canonicalizeSpawnedByForAgent, resolveSessionStoreKey } from "./session-store-key.js";

export type {

GatewayAgentRow,

GatewaySessionRow,

GatewaySessionsDefaults,

SessionsListResult,

SessionsPatchResult,

SessionsPreviewEntry,

SessionsPreviewResult,

} from "./session-utils.types.js";

const DERIVED_TITLE_MAX_LEN = 60;

function tryResolveExistingPath(value: string): string | null {

try {

return fs.realpathSync(value);

} catch {

return null;

}

}

function resolveIdentityAvatarUrl(

cfg: OpenClawConfig,

agentId: string,

avatar: string | undefined,

): string | undefined {

if (!avatar) {

return undefined;

}

const trimmed = normalizeOptionalString(avatar) ?? "";

if (!trimmed) {

return undefined;

}

if (isAvatarDataUrl(trimmed) || isAvatarHttpUrl(trimmed)) {

return trimmed;

}

if (!isWorkspaceRelativeAvatarPath(trimmed)) {

return undefined;

}

const workspaceDir = resolveAgentWorkspaceDir(cfg, agentId);

const workspaceRoot = tryResolveExistingPath(workspaceDir) ?? path.resolve(workspaceDir);

const resolvedCandidate = path.resolve(workspaceRoot, trimmed);

if (!isPathWithinRoot(workspaceRoot, resolvedCandidate)) {

return undefined;

}

try {

const opened = openBoundaryFileSync({

absolutePath: resolvedCandidate,

rootPath: workspaceRoot,

rootRealPath: workspaceRoot,

boundaryLabel: "workspace root",

maxBytes: AVATAR_MAX_BYTES,

skipLexicalRootCheck: true,

});

if (!opened.ok) {

return undefined;

}

try {

const buffer = fs.readFileSync(opened.fd);

const mime = resolveAvatarMime(resolvedCandidate);

return `data:${mime};base64,${buffer.toString("base64")}`;

} finally {

fs.closeSync(opened.fd);

}

} catch {

return undefined;

}

}

function formatSessionIdPrefix(sessionId: string, updatedAt?: number | null): string {

const prefix = sessionId.slice(0, 8);

if (updatedAt && updatedAt > 0) {

const d = new Date(updatedAt);

const date = d.toISOString().slice(0, 10);

return `${prefix} (${date})`;

}

return prefix;

}

function truncateTitle(text: string, maxLen: number): string {

if (text.length <= maxLen) {

return text;

}

const cut = text.slice(0, maxLen - 1);

const lastSpace = cut.lastIndexOf(" ");

if (lastSpace > maxLen * 0.6) {

return cut.slice(0, lastSpace) + "…";

}

return cut + "…";

}

export function deriveSessionTitle(

entry: SessionEntry | undefined,

firstUserMessage?: string | null,

): string | undefined {

if (!entry) {

return undefined;

}

if (normalizeOptionalString(entry.displayName)) {

return normalizeOptionalString(entry.displayName);

}

if (normalizeOptionalString(entry.subject)) {

return normalizeOptionalString(entry.subject);

}

if (firstUserMessage?.trim()) {

const normalized = firstUserMessage.replace(/\s+/g, " ").trim();

return truncateTitle(normalized, DERIVED_TITLE_MAX_LEN);

}

if (entry.sessionId) {

return formatSessionIdPrefix(entry.sessionId, entry.updatedAt);

}

return undefined;

}

function resolveSessionRuntimeMs(

run: { startedAt?: number; endedAt?: number; accumulatedRuntimeMs?: number } | null,

now: number,

) {

return getSubagentSessionRuntimeMs(run, now);

}

function resolvePositiveNumber(value: number | null | undefined): number | undefined {

return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : undefined;

}

function resolveNonNegativeNumber(value: number | null | undefined): number | undefined {

return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;

}

function resolveLatestCompactionCheckpoint(

entry?: Pick<SessionEntry, "compactionCheckpoints"> | null,

): NonNullable<SessionEntry["compactionCheckpoints"]>[number] | undefined {

const checkpoints = entry?.compactionCheckpoints;

if (!Array.isArray(checkpoints) || checkpoints.length === 0) {

return undefined;

}

return checkpoints.reduce((latest, checkpoint) =>

!latest || checkpoint.createdAt > latest.createdAt ? checkpoint : latest,

);

}

function resolveEstimatedSessionCostUsd(params: {

cfg: OpenClawConfig;

provider?: string;

model?: string;

entry?: Pick<

SessionEntry,

"estimatedCostUsd" | "inputTokens" | "outputTokens" | "cacheRead" | "cacheWrite"

>;

explicitCostUsd?: number;

}): number | undefined {

const explicitCostUsd = resolveNonNegativeNumber(

params.explicitCostUsd ?? params.entry?.estimatedCostUsd,

);

if (explicitCostUsd !== undefined) {

return explicitCostUsd;

}

const input = resolvePositiveNumber(params.entry?.inputTokens);

const output = resolvePositiveNumber(params.entry?.outputTokens);

const cacheRead = resolvePositiveNumber(params.entry?.cacheRead);

const cacheWrite = resolvePositiveNumber(params.entry?.cacheWrite);

if (

input === undefined &&

output === undefined &&

cacheRead === undefined &&

cacheWrite === undefined

) {

return undefined;

}

const cost = resolveModelCostConfig({

provider: params.provider,

model: params.model,

config: params.cfg,

});

if (!cost) {

return undefined;

}

const estimated = estimateUsageCost({

usage: {

...(input !== undefined ? { input } : {}),

...(output !== undefined ? { output } : {}),

...(cacheRead !== undefined ? { cacheRead } : {}),

...(cacheWrite !== undefined ? { cacheWrite } : {}),

},

cost,

});

return resolveNonNegativeNumber(estimated);

}

const STALE_STORE_ONLY_CHILD_LINK_MS = 60 * 60 * 1_000;

function isFinitePositiveTimestamp(value: unknown): value is number {

return typeof value === "number" && Number.isFinite(value) && value > 0;

}

function isTerminalSessionStatus(status: unknown): status is Exclude<SessionRunStatus, "running"> {

return status === "done" || status === "failed" || status === "killed" || status === "timeout";

}

function shouldKeepStoreOnlyChildLink(entry: SessionEntry, now: number): boolean {

if (isTerminalSessionStatus(entry.status) || isFinitePositiveTimestamp(entry.endedAt)) {

const endedAt = isFinitePositiveTimestamp(entry.endedAt) ? entry.endedAt : entry.updatedAt;

return (

isFinitePositiveTimestamp(endedAt) && now - endedAt <= RECENT_ENDED_SUBAGENT_CHILD_SESSION_MS

);

}

if (entry.status === "running" || isFinitePositiveTimestamp(entry.startedAt)) {

return true;

}

return (

isFinitePositiveTimestamp(entry.updatedAt) &&

now - entry.updatedAt <= STALE_STORE_ONLY_CHILD_LINK_MS

);

}

function resolveRuntimeChildSessionKeys(

controllerSessionKey: string,

now = Date.now(),

): string[] | undefined {

const childSessionKeys = new Set<string>();

for (const entry of listSubagentRunsForController(controllerSessionKey)) {

const childSessionKey = normalizeOptionalString(entry.childSessionKey);

if (!childSessionKey) {

continue;

}

const latest = getSessionDisplaySubagentRunByChildSessionKey(childSessionKey);

if (!latest) {

continue;

}

const latestControllerSessionKey =

normalizeOptionalString(latest?.controllerSessionKey) ||

normalizeOptionalString(latest?.requesterSessionKey);

if (latestControllerSessionKey !== controllerSessionKey) {

continue;

}

if (

!shouldKeepSubagentRunChildLink(latest, {

activeDescendants: countActiveDescendantRuns(childSessionKey),

now,

})

) {

continue;

}

childSessionKeys.add(childSessionKey);

}

const childSessions = Array.from(childSessionKeys);

return childSessions.length > 0 ? childSessions : undefined;

}

function addChildSessionKey(

childSessionsByKey: Map<string, string[]>,

parentKey: string,

childKey: string,

) {

const current = childSessionsByKey.get(parentKey);

if (current) {

if (!current.includes(childKey)) {

current.push(childKey);

}

return;

}

childSessionsByKey.set(parentKey, [childKey]);

}

function buildStoreChildSessionIndex(

store: Record<string, SessionEntry>,

now = Date.now(),

): Map<string, string[]> {

const childSessionsByKey = new Map<string, string[]>();

for (const [key, entry] of Object.entries(store)) {

if (!entry) {

continue;

}

const parentKeys = [

normalizeOptionalString(entry.spawnedBy),

normalizeOptionalString(entry.parentSessionKey),

].filter((value): value is string => Boolean(value) && value !== key);

if (parentKeys.length === 0) {

continue;

}

const latest = getSessionDisplaySubagentRunByChildSessionKey(key);

let latestControllerSessionKey: string | undefined;

if (latest) {

latestControllerSessionKey =

normalizeOptionalString(latest.controllerSessionKey) ||

normalizeOptionalString(latest.requesterSessionKey);

if (

!shouldKeepSubagentRunChildLink(latest, {

activeDescendants: countActiveDescendantRuns(key),

now,

})

) {

continue;

}

} else if (!shouldKeepStoreOnlyChildLink(entry, now)) {

continue;

}

for (const parentKey of parentKeys) {

if (latestControllerSessionKey && latestControllerSessionKey !== parentKey) {

continue;

}

addChildSessionKey(childSessionsByKey, parentKey, key);

}

}

return childSessionsByKey;

}

function mergeChildSessionKeys(

runtimeChildSessions: string[] | undefined,

storeChildSessions: string[] | undefined,

): string[] | undefined {

if (!runtimeChildSessions?.length) {

return storeChildSessions?.length ? storeChildSessions : undefined;

}

if (!storeChildSessions?.length) {

return runtimeChildSessions;

}

return Array.from(new Set([...runtimeChildSessions, ...storeChildSessions]));

}

function resolveChildSessionKeys(

controllerSessionKey: string,

store: Record<string, SessionEntry>,

now = Date.now(),

): string[] | undefined {

const runtimeChildSessions = resolveRuntimeChildSessionKeys(controllerSessionKey, now);

const storeChildSessions = buildStoreChildSessionIndex(store, now).get(controllerSessionKey);

return mergeChildSessionKeys(runtimeChildSessions, storeChildSessions);

}

function resolveTranscriptUsageFallback(params: {

cfg: OpenClawConfig;

key: string;

entry?: SessionEntry;

storePath: string;

fallbackProvider?: string;

fallbackModel?: string;

maxTranscriptBytes?: number;

}): {

estimatedCostUsd?: number;

totalTokens?: number;

totalTokensFresh?: boolean;

contextTokens?: number;

modelProvider?: string;

model?: string;

} | null {

const entry = params.entry;

if (!entry?.sessionId) {

return null;

}

const parsed = parseAgentSessionKey(params.key);

const agentId = parsed?.agentId

? normalizeAgentId(parsed.agentId)

: resolveDefaultAgentId(params.cfg);

const snapshot =

typeof params.maxTranscriptBytes === "number"

? readRecentSessionUsageFromTranscript(

entry.sessionId,

params.storePath,

entry.sessionFile,

agentId,

params.maxTranscriptBytes,

)

: readLatestSessionUsageFromTranscript(

entry.sessionId,

params.storePath,

entry.sessionFile,

agentId,

);

if (!snapshot) {

return null;

}

const modelProvider = snapshot.modelProvider ?? params.fallbackProvider;

const model = snapshot.model ?? params.fallbackModel;

const contextTokens = resolveContextTokensForModel({

cfg: params.cfg,

provider: modelProvider,

model,

// Gateway/session listing is read-only; don't start async model discovery.

allowAsyncLoad: false,

});

const estimatedCostUsd = resolveEstimatedSessionCostUsd({

cfg: params.cfg,

provider: modelProvider,

model,

explicitCostUsd: snapshot.costUsd,

entry: {

inputTokens: snapshot.inputTokens,

outputTokens: snapshot.outputTokens,

cacheRead: snapshot.cacheRead,

cacheWrite: snapshot.cacheWrite,

},

});

return {

modelProvider,

model,

totalTokens: resolvePositiveNumber(snapshot.totalTokens),

totalTokensFresh: snapshot.totalTokensFresh === true,

contextTokens: resolvePositiveNumber(contextTokens),

estimatedCostUsd,

};

}

/**

* Returns the owning agent id if the session key belongs to an agent that is no

* longer present in config (deleted). Returns null for non-agent legacy/global

* keys, or when the owning agent still exists (#65524).

*/

export function resolveDeletedAgentIdFromSessionKey(

cfg: OpenClawConfig,

sessionKey: string,

): string | null {

const parsed = parseAgentSessionKey(sessionKey);

if (!parsed) {

return null;

}

const agentId = normalizeAgentId(parsed.agentId);

if (listAgentIds(cfg).includes(agentId)) {

return null;

}

return agentId;

}

export function loadSessionEntry(sessionKey: string) {

const cfg = getRuntimeConfig();

const key = normalizeOptionalString(sessionKey) ?? "";

const target = resolveGatewaySessionStoreTarget({

cfg,

key,

});

const storePath = target.storePath;

const store = loadSessionStore(storePath);

const freshestMatch = resolveFreshestSessionStoreMatchFromStoreKeys(store, target.storeKeys);

const legacyKey = freshestMatch?.key !== target.canonicalKey ? freshestMatch?.key : undefined;

return {

cfg,

storePath,

store,

entry: freshestMatch?.entry,

canonicalKey: target.canonicalKey,

legacyKey,

};

}

export function resolveFreshestSessionStoreMatchFromStoreKeys(

store: Record<string, SessionEntry>,

storeKeys: string[],

): { key: string; entry: SessionEntry } | undefined {

let freshest: { key: string; entry: SessionEntry } | undefined;

for (const key of storeKeys) {

const entry = store[key];

if (!entry) {

continue;

}

const match = { key, entry };

if (!freshest || (match.entry.updatedAt ?? 0) > (freshest.entry.updatedAt ?? 0)) {

freshest = match;

}

}

return freshest;

}

export function resolveFreshestSessionEntryFromStoreKeys(

store: Record<string, SessionEntry>,

storeKeys: string[],

): SessionEntry | undefined {

return resolveFreshestSessionStoreMatchFromStoreKeys(store, storeKeys)?.entry;

}

function findFreshestStoreMatch(

store: Record<string, SessionEntry>,

...candidates: string[]

): { entry: SessionEntry; key: string } | undefined {

const matches = new Map<string, { entry: SessionEntry; key: string }>();

for (const candidate of candidates) {

const trimmed = normalizeOptionalString(candidate) ?? "";

if (!trimmed) {

continue;

}

const exact = store[trimmed];

if (exact) {

matches.set(trimmed, { entry: exact, key: trimmed });

}

for (const key of findStoreKeysIgnoreCase(store, trimmed)) {

const entry = store[key];

if (entry) {

matches.set(key, { entry, key });

}

}

}

if (matches.size === 0) {

return undefined;

}

let freshest: { entry: SessionEntry; key: string } | undefined;

for (const match of matches.values()) {

if (!freshest || (match.entry.updatedAt ?? 0) > (freshest.entry.updatedAt ?? 0)) {

freshest = match;

}

}

return freshest;

}

/**

* Find all on-disk store keys that match the given key case-insensitively.

* Returns every key from the store whose lowercased form equals the target's lowercased form.

*/

export function findStoreKeysIgnoreCase(

store: Record<string, unknown>,

targetKey: string,

): string[] {

const lowered = normalizeLowercaseStringOrEmpty(targetKey);

const matches: string[] = [];

for (const key of Object.keys(store)) {

if (normalizeLowercaseStringOrEmpty(key) === lowered) {

matches.push(key);

}

}

return matches;

}

/**

* Remove legacy key variants for one canonical session key.

* Candidates can include aliases (for example, "agent:ops:main" when canonical is "agent:ops:work").

*/

export function pruneLegacyStoreKeys(params: {

store: Record<string, unknown>;

canonicalKey: string;

candidates: Iterable<string>;

}) {

const keysToDelete = new Set<string>();

for (const candidate of params.candidates) {

const trimmed = normalizeOptionalString(candidate ?? "") ?? "";

if (!trimmed) {

continue;

}

if (trimmed !== params.canonicalKey) {

keysToDelete.add(trimmed);

}

for (const match of findStoreKeysIgnoreCase(params.store, trimmed)) {

if (match !== params.canonicalKey) {

keysToDelete.add(match);

}

}

}

for (const key of keysToDelete) {

delete params.store[key];

}

}

export function migrateAndPruneGatewaySessionStoreKey(params: {

cfg: OpenClawConfig;

key: string;

store: Record<string, SessionEntry>;

}) {

const target = resolveGatewaySessionStoreTarget({

cfg: params.cfg,

key: params.key,

store: params.store,

});

const primaryKey = target.canonicalKey;

const freshestMatch = resolveFreshestSessionStoreMatchFromStoreKeys(

params.store,

target.storeKeys,

);

if (freshestMatch) {

const currentPrimary = params.store[primaryKey];

if (!currentPrimary || (freshestMatch.entry.updatedAt ?? 0) > (currentPrimary.updatedAt ?? 0)) {

params.store[primaryKey] = freshestMatch.entry;

}

}

pruneLegacyStoreKeys({

store: params.store,

canonicalKey: primaryKey,

candidates: target.storeKeys,

});

return { target, primaryKey, entry: params.store[primaryKey] };

}

export function classifySessionKey(key: string, entry?: SessionEntry): GatewaySessionRow["kind"] {

if (key === "global") {

return "global";

}

if (key === "unknown") {

return "unknown";

}

if (entry?.chatType === "group" || entry?.chatType === "channel") {

return "group";

}

if (key.includes(":group:") || key.includes(":channel:")) {

return "group";

}

return "direct";

}

export function parseGroupKey(

key: string,

): { channel?: string; kind?: "group" | "channel"; id?: string } | null {

const agentParsed = parseAgentSessionKey(key);

const rawKey = agentParsed?.rest ?? key;

const parts = rawKey.split(":").filter(Boolean);

if (parts.length >= 3) {

const [channel, kind, ...rest] = parts;

if (kind === "group" || kind === "channel") {

const id = rest.join(":");

return { channel, kind, id };

}

}

return null;

}

function isStorePathTemplate(store?: string): boolean {

return typeof store === "string" && store.includes("{agentId}");

}

function listExistingAgentIdsFromDisk(): string[] {

const root = resolveStateDir();

const agentsDir = path.join(root, "agents");

try {

const entries = fs.readdirSync(agentsDir, { withFileTypes: true });

return entries

.filter((entry) => entry.isDirectory())

.map((entry) => normalizeAgentId(entry.name))

.filter(Boolean);

} catch {

return [];

}

}

function listConfiguredAgentIds(cfg: OpenClawConfig): string[] {

const ids = new Set<string>();

const defaultId = normalizeAgentId(resolveDefaultAgentId(cfg));

ids.add(defaultId);

for (const entry of cfg.agents?.list ?? []) {

if (entry?.id) {

ids.add(normalizeAgentId(entry.id));

}

}

for (const id of listExistingAgentIdsFromDisk()) {

ids.add(id);

}

const sorted = Array.from(ids).filter(Boolean);

sorted.sort((a, b) => a.localeCompare(b));

return sorted.includes(defaultId)

? [defaultId, ...sorted.filter((id) => id !== defaultId)]

: sorted;

}

function normalizeFallbackList(values: readonly string[]): string[] {

const out: string[] = [];

const seen = new Set<string>();

for (const value of values) {

const trimmed = value.trim();

if (!trimmed) {

continue;

}

const key = normalizeLowercaseStringOrEmpty(trimmed);

if (seen.has(key)) {

continue;

}

seen.add(key);

out.push(trimmed);

}

return out;

}

function resolveGatewayAgentModel(

cfg: OpenClawConfig,

agentId: string,

): GatewayAgentRow["model"] | undefined {

const primary = resolveAgentEffectiveModelPrimary(cfg, agentId)?.trim();

const fallbackOverride = resolveAgentModelFallbacksOverride(cfg, agentId);

const defaultFallbacks = resolveAgentModelFallbackValues(cfg.agents?.defaults?.model);

const fallbacks = normalizeFallbackList(fallbackOverride ?? defaultFallbacks);

if (!primary && fallbacks.length === 0) {

return undefined;

}

return {

...(primary ? { primary } : {}),

...(fallbacks.length > 0 ? { fallbacks } : {}),

};

}

export function listAgentsForGateway(cfg: OpenClawConfig): {

defaultId: string;

mainKey: string;

scope: SessionScope;

agents: GatewayAgentRow[];

} {

const defaultId = normalizeAgentId(resolveDefaultAgentId(cfg));

const mainKey = normalizeMainKey(cfg.session?.mainKey);

const scope = cfg.session?.scope ?? "per-sender";

const configuredById = new Map<

string,

{ name?: string; identity?: GatewayAgentRow["identity"] }

>();

for (const entry of cfg.agents?.list ?? []) {

if (!entry?.id) {

continue;

}

const identity = entry.identity

? {

name: normalizeOptionalString(entry.identity.name),

theme: normalizeOptionalString(entry.identity.theme),

emoji: normalizeOptionalString(entry.identity.emoji),

avatar: normalizeOptionalString(entry.identity.avatar),

avatarUrl: resolveIdentityAvatarUrl(

cfg,

normalizeAgentId(entry.id),

normalizeOptionalString(entry.identity.avatar),

),

}

: undefined;

configuredById.set(normalizeAgentId(entry.id), {

name: normalizeOptionalString(entry.name),

identity,

});

}

const explicitIds = new Set(

(cfg.agents?.list ?? [])

.map((entry) => (entry?.id ? normalizeAgentId(entry.id) : ""))

.filter(Boolean),

);

const allowedIds = explicitIds.size > 0 ? new Set([...explicitIds, defaultId]) : null;

let agentIds = listConfiguredAgentIds(cfg).filter((id) =>

allowedIds ? allowedIds.has(id) : true,

);

if (mainKey && !agentIds.includes(mainKey) && (!allowedIds || allowedIds.has(mainKey))) {

agentIds = [...agentIds, mainKey];

}

const agents = agentIds.map((id) => {

const meta = configuredById.get(id);

const model = resolveGatewayAgentModel(cfg, id);

return Object.assign(

{

id,

name: meta?.name,

identity: meta?.identity,

workspace: resolveAgentWorkspaceDir(cfg, id),

agentRuntime: resolveAgentRuntimeMetadata(cfg, id),

},

model ? { model } : {},

);

});

return { defaultId, mainKey, scope, agents };

}

function buildGatewaySessionStoreScanTargets(params: {

cfg: OpenClawConfig;

key: string;

canonicalKey: string;

agentId: string;

}): string[] {

const targets = new Set<string>();

if (params.canonicalKey) {

targets.add(params.canonicalKey);

}

if (params.key && params.key !== params.canonicalKey) {

targets.add(params.key);

}

if (params.canonicalKey === "global" || params.canonicalKey === "unknown") {

return [...targets];

}

const agentMainKey = resolveAgentMainSessionKey({ cfg: params.cfg, agentId: params.agentId });

if (params.canonicalKey === agentMainKey) {

targets.add(`agent:${params.agentId}:main`);

}

return [...targets];

}

function resolveGatewaySessionStoreCandidates(

cfg: OpenClawConfig,

agentId: string,

): SessionStoreTarget[] {

const storeConfig = cfg.session?.store;

const defaultTarget = {

agentId,

storePath: resolveStorePath(storeConfig, { agentId }),

};

if (!isStorePathTemplate(storeConfig)) {

return [defaultTarget];

}

const targets = new Map<string, SessionStoreTarget>();

targets.set(defaultTarget.storePath, defaultTarget);

for (const target of resolveAllAgentSessionStoreTargetsSync(cfg)) {

if (target.agentId === agentId) {

targets.set(target.storePath, target);

}

}

return [...targets.values()];

}

function resolveGatewaySessionStoreLookup(params: {

cfg: OpenClawConfig;

key: string;

canonicalKey: string;

agentId: string;

initialStore?: Record<string, SessionEntry>;

}): {

storePath: string;

store: Record<string, SessionEntry>;

match: { entry: SessionEntry; key: string } | undefined;

} {

const scanTargets = buildGatewaySessionStoreScanTargets(params);

const candidates = resolveGatewaySessionStoreCandidates(params.cfg, params.agentId);

const fallback = candidates[0] ?? {

agentId: params.agentId,

storePath: resolveStorePath(params.cfg.session?.store, { agentId: params.agentId }),

};

let selectedStorePath = fallback.storePath;

let selectedStore = params.initialStore ?? loadSessionStore(fallback.storePath);

let selectedMatch = findFreshestStoreMatch(selectedStore, ...scanTargets);

let selectedUpdatedAt = selectedMatch?.entry.updatedAt ?? Number.NEGATIVE_INFINITY;

for (let index = 1; index < candidates.length; index += 1) {

const candidate = candidates[index];

if (!candidate) {

continue;

}

const store = loadSessionStore(candidate.storePath);

const match = findFreshestStoreMatch(store, ...scanTargets);

if (!match) {

continue;

}

const updatedAt = match.entry.updatedAt ?? 0;

// Mirror combined-store merge behavior so follow-up mutations target the

// same backing store that won the listing merge when ids collide.

if (!selectedMatch || updatedAt >= selectedUpdatedAt) {

selectedStorePath = candidate.storePath;

selectedStore = store;

selectedMatch = match;

selectedUpdatedAt = updatedAt;

}

}

return {

storePath: selectedStorePath,

store: selectedStore,

match: selectedMatch,

};

}

function resolveExplicitDeletedLegacyMainStoreTarget(params: {

cfg: OpenClawConfig;

key: string;

scanLegacyKeys?: boolean;

}): {

agentId: string;

storePath: string;

canonicalKey: string;

storeKeys: string[];

} | null {

const parsed = parseAgentSessionKey(params.key);

const legacyAgentId = normalizeAgentId(parsed?.agentId);

if (

!parsed ||

legacyAgentId !== DEFAULT_AGENT_ID ||

listAgentIds(params.cfg).includes(legacyAgentId)

) {

return null;

}

// Only preserve agent:main:* when it is backed by a discovered deleted-main store.

// Shared-store legacy aliases should continue remapping to the configured default agent.

const canonicalKey = resolveStoredSessionKeyForAgentStore({

cfg: params.cfg,

agentId: legacyAgentId,

sessionKey: params.key,

});

const agentMainKey = resolveAgentMainSessionKey({ cfg: params.cfg, agentId: legacyAgentId });

const legacyAgentMainKey = `agent:${legacyAgentId}:main`;

const lookupSeeds = Array.from(

new Set([params.key, canonicalKey, agentMainKey, legacyAgentMainKey]),

);

let best:

| {

storePath: string;

store: Record<string, SessionEntry>;