@nextclaw/kernel 0.10.0 → 0.10.1

package/dist/index.js

@@ -2,7 +2,7 @@ import { AUTOMATIC_UPDATE_CHECK_INTERVAL_MS, getAutomaticUpdateCheckDelay, resol
 import { n as getUnsignedUpdateManifest, r as serializeUnsignedUpdateManifest, t as UpdateManifestReader } from "./update-manifest.types-C0qPrjGQ.js";
 import { createRequire } from "node:module";
 import { APP_NAME, AgentRouteResolver, BUILTIN_MAIN_AGENT_ID, CLEAR_THINKING_TOKENS, CONTEXT_COMPACTION_METADATA_KEY, ConfigSchema, ContextCompactionService, ContextWindowBudgetService, CronService, CronTool, DEFAULT_PANELS_DIR, DEFAULT_SERVICE_APPS_DIR, DEFAULT_SESSION_SEARCH_LIMIT, DEFAULT_WORKSPACE_REPOSITORY_IDENTITY_RESOLVER, DIAGNOSTIC_CORRELATION_METADATA_KEY, DiagnosticRuntime, EditFileTool, ExecTool, ExtensionChannelAdapter, GatewayTool, InputBudgetPruner, LLMProvider, ListDirTool, LiteLLMProvider, MAX_SESSION_SEARCH_LIMIT, MemoryGetTool, MemorySearchTool, MemoryStore, MessageBus, MessageTool, ProviderModelDiscoveryService, ProviderRegistry, ReadFileTool, RequestedSkillsMetadataReader, SILENT_REPLY_TOKEN, SessionProjectContextResolver, SessionSearchService, SkillsLoader, THINKING_LEVELS, ViewImageTool, WebFetchTool, WebSearchTool, WriteFileTool, buildCompressingCompactionCheckpoint, buildConfigSchema, buildContextWindowSnapshot, buildReloadPlan, buildSessionRequestToolResult, buildToolCatalogEntries, createAgentProfile, createAssistantStreamDeltaControlMessage, createAssistantStreamResetControlMessage, createCompletedSessionRequest, createFailedSessionRequest, createRunningSessionRequest, createRuntimeChildEnv, createTypingStopControlMessage, diffConfigPaths, ensureDir, estimateInputTokens, evaluateSilentReply, expandHome, findEffectiveAgentProfile, getConfigPath, getDataDir, getDataPath, getSessionsPath, getWorkspacePath, getWorkspacePathFromConfig, isNextclawControlMessage, loadConfig, mergeExtensionConfigView, modelSupportsVision, normalizeAgentProfileId, normalizeInlineSecretRefs, normalizeModelThinkingCapability, normalizeProviderModelConfig, normalizeToolParams, parseAgentScopedSessionKey, parseThinkingLevel, readCompressedContextCompactionCheckpoint, readOptionalString, readParentSessionId, readSessionProjectRoot, redactConfigObject, removeAgentProfile, resolveConfigSecrets, resolveDefaultAgentProfileId, resolveEffectiveAgentProfiles, resolveNextclawSelfManageGuidePaths, resolveProviderRuntime, resolveRuntimeCommandLaunch, resolveSessionProjectContext, resolveSessionWorkspacePath, resolveThinkingLevel, safeFilename, sanitizeOutboundAssistantContent, saveConfig, summarizeSessionRequestTask, toExtensionConfigView, updateAgentProfile } from "@nextclaw/core";
-import { NCP_AI_EXECUTION_METADATA_KEY, NCP_INTERNAL_VISIBILITY_METADATA_KEY, NcpEventType, OBSERVATION_EVENT_EXTENSION_TYPE, createUnavailableNcpAiExecutionMetadata, isHiddenNcpMessage, normalizeAssistantText, readNcpAiExecutionMetadata, sanitizeAssistantReplyTags } from "@nextclaw/ncp";
+import { NCP_AI_EXECUTION_METADATA_KEY, NCP_INTERNAL_VISIBILITY_METADATA_KEY, NCP_RUN_TRIGGER_METADATA_KEY, NcpEventType, OBSERVATION_EVENT_EXTENSION_TYPE, createUnavailableNcpAiExecutionMetadata, isHiddenNcpMessage, normalizeAssistantText, parseNcpRunTriggerInput, readNcpAiExecutionMetadata, sanitizeAssistantReplyTags } from "@nextclaw/ncp";
 import { CHAT_CONTINUATION_TARGET_MESSAGE_METADATA_KEY, CHAT_CONVERSATION_EXCERPT_TOKEN_KIND, CHAT_INLINE_TOKENS_METADATA_KEY, CHAT_INLINE_TOKENS_SCHEMA_VERSION, CHAT_PROJECT_TOKEN_KIND, CHAT_SESSION_MATERIALIZATION_METADATA_KEY, CHAT_SYSTEM_OBJECT_TOKEN_KIND, CHAT_UI_RESOURCE_TOKEN_KIND, CHAT_WORKSPACE_DIRECTORY_TOKEN_KIND, CHAT_WORKSPACE_EXCERPT_TOKEN_KIND, CHAT_WORKSPACE_FILE_TOKEN_KIND, Contribution as Contribution$1, EventBus, EventBus as EventBus$1, Ingress, Ingress as Ingress$1, PANEL_APP_INLINE_HOST_CONTRACT, PANEL_APP_SCROLL_RESTORATION_CONTRACT, SYSTEM_OBJECT_REFERENCE_DEFAULT_LIMIT, SYSTEM_OBJECT_REFERENCE_MAX_LIMIT, SYSTEM_OBJECT_TYPE_CRON_JOB, SYSTEM_OBJECT_TYPE_INBOX_DELIVERY, UI_CONTENT_PARAMS_HOST_CONTRACT, classifyDiagnosticError, createSystemObjectReferenceUri, createTypedKey, eventKeys, eventKeys as eventKeys$1, ingressKeys, ingressKeys as ingressKeys$1, isRuntimeDefaultModelValue, isSilentReplyNcpMessage, normalizeRuntimeModelSelectionMode, parseSystemObjectReferenceUri, readChatUiResourceReference, readInlineContentHeight, readSystemObjectResolvedReference, readUiContentParams } from "@nextclaw/shared";
 import { LocalAssetStore, buildAssetContentPath, buildNcpUserContent, buildOpenAiFunctionTool, isTextLikeAsset, ncpMessageToOpenAiMessages, validateToolArgs } from "@nextclaw/ncp-agent-runtime";
 import { createHash, createHmac, randomBytes, randomUUID, scryptSync, timingSafeEqual } from "node:crypto";
@@ -1514,26 +1514,26 @@ const SESSION_ACTIVITY_PREVIEW_STATUS_KINDS = new Set([
 	"run-failed",
 	"run-interrupted"
 ]);
-function isRecord$18(value) {
+function isRecord$19(value) {
 	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
-function readOptionalString$12(value) {
+function readOptionalString$13(value) {
 	if (typeof value !== "string") return;
 	const trimmed = value.trim();
 	return trimmed.length > 0 ? trimmed : void 0;
 }
 function readSessionActivityPreviewMetadata(value) {
-	if (!isRecord$18(value)) return null;
+	if (!isRecord$19(value)) return null;
 	const state = value.state;
-	const timestamp = readOptionalString$12(value.timestamp);
+	const timestamp = readOptionalString$13(value.timestamp);
 	if (!SESSION_ACTIVITY_PREVIEW_STATES.has(state) || !timestamp) return null;
-	const statusKind = readOptionalString$12(value.statusKind);
+	const statusKind = readOptionalString$13(value.statusKind);
 	return {
 		state,
 		timestamp,
 		statusKind: SESSION_ACTIVITY_PREVIEW_STATUS_KINDS.has(statusKind) ? statusKind : void 0,
-		statusText: readOptionalString$12(value.statusText),
-		replyText: readOptionalString$12(value.replyText)
+		statusText: readOptionalString$13(value.statusText),
+		replyText: readOptionalString$13(value.replyText)
 	};
 }
 function compareIsoTimestamp(left, right) {
@@ -1617,7 +1617,7 @@ var SessionActivityPreviewEventService = class {
 //#endregion
 //#region src/managers/agent-run-session-command.manager.ts
 const CONTINUATION_PROMPT = "Continue from where you stopped. Preserve completed work and avoid repeating it.";
-function isRecord$17(value) {
+function isRecord$18(value) {
 	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 function hasSendableMessageContent(message) {
@@ -1625,7 +1625,7 @@ function hasSendableMessageContent(message) {
 }
 function readSessionActivityState(metadata) {
 	const preview = metadata?.[SESSION_ACTIVITY_PREVIEW_METADATA_KEY];
-	return isRecord$17(preview) && typeof preview.state === "string" ? preview.state : null;
+	return isRecord$18(preview) && typeof preview.state === "string" ? preview.state : null;
 }
 var AgentRunSessionCommandManager = class {
 	pendingCommands = /* @__PURE__ */ new Map();
@@ -1676,6 +1676,13 @@ var AgentRunSessionCommandManager = class {
 				role: "user",
 				status: "final",
 				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			},
+			trigger: {
+				actor: "human",
+				source: "message-edit",
+				triggeredAt: (/* @__PURE__ */ new Date()).toISOString(),
+				sourceSessionId: request.sessionId,
+				sourceMessageId: request.messageId
 			}
 		});
 	};
@@ -1685,6 +1692,7 @@ var AgentRunSessionCommandManager = class {
 		const activityState = readSessionActivityState(sourceRecord.metadata);
 		if (activityState !== "cancelled" && activityState !== "failed") throw new Error("Only a cancelled or failed session can continue running.");
 		const latestVisibleConversationMessage = [...sourceRecord.messages].reverse().find((message) => (message.role === "user" || message.role === "assistant") && !isHiddenNcpMessage(message) && !isSilentReplyNcpMessage(message));
+		const triggeredAt = (/* @__PURE__ */ new Date()).toISOString();
 		return await this.send({
 			correlationId: request.correlationId,
 			sessionId: request.sessionId,
@@ -1693,7 +1701,7 @@ var AgentRunSessionCommandManager = class {
 				sessionId: request.sessionId,
 				role: "user",
 				status: "final",
-				timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+				timestamp: triggeredAt,
 				parts: [{
 					type: "text",
 					text: CONTINUATION_PROMPT
@@ -1702,6 +1710,13 @@ var AgentRunSessionCommandManager = class {
 					[NCP_INTERNAL_VISIBILITY_METADATA_KEY]: "hidden",
 					[CHAT_CONTINUATION_TARGET_MESSAGE_METADATA_KEY]: latestVisibleConversationMessage?.role === "assistant" ? latestVisibleConversationMessage.id : void 0
 				}
+			},
+			trigger: {
+				actor: "human",
+				source: "continue-run",
+				triggeredAt,
+				sourceSessionId: request.sessionId,
+				...latestVisibleConversationMessage ? { sourceMessageId: latestVisibleConversationMessage.id } : {}
 			}
 		});
 	};
@@ -1950,13 +1965,13 @@ function createUnavailableAiExecutionMetadataEvent(params) {
 }
 //#endregion
 //#region src/utils/agent-run-request.utils.ts
-function readOptionalString$11(value) {
+function readOptionalString$12(value) {
 	if (typeof value !== "string") return;
 	return value.trim() || void 0;
 }
 function toAgentRunRequest(envelope) {
 	const metadata = envelope.metadata ?? {};
-	const peerId = readOptionalString$11(envelope.peerId);
+	const peerId = readOptionalString$12(envelope.peerId);
 	const requestMetadata = {
 		agentRuntimeId: metadata.agentRuntimeId,
 		agentId: metadata.agentId,
@@ -1968,10 +1983,10 @@ function toAgentRunRequest(envelope) {
 		maxTokens: metadata.maxTokens,
 		thinkingEffort: metadata.thinkingEffort,
 		delivery: envelope.delivery,
-		idempotencyKey: readOptionalString$11(envelope.idempotencyKey)
+		idempotencyKey: readOptionalString$12(envelope.idempotencyKey)
 	};
 	if (Array.isArray(envelope.content)) {
-		const sessionId = readOptionalString$11(envelope.sessionId);
+		const sessionId = readOptionalString$12(envelope.sessionId);
 		if (sessionId && peerId) throw new Error("agent-run.send cannot accept both sessionId and peerId.");
 		return {
 			...requestMetadata,
@@ -1989,8 +2004,8 @@ function toAgentRunRequest(envelope) {
 	}
 	const sourceMessage = envelope.message;
 	if (!sourceMessage) throw new Error("Invalid agent run send request.");
-	const envelopeSessionId = readOptionalString$11(envelope.sessionId);
-	const messageSessionId = readOptionalString$11(sourceMessage.sessionId);
+	const envelopeSessionId = readOptionalString$12(envelope.sessionId);
+	const messageSessionId = readOptionalString$12(sourceMessage.sessionId);
 	const sessionId = envelopeSessionId ?? messageSessionId;
 	if (sessionId && peerId) throw new Error("agent-run.send cannot accept both sessionId and peerId.");
 	return {
@@ -2051,7 +2066,7 @@ function readSessionMaterialization(metadata) {
 	if (!value || typeof value !== "object" || Array.isArray(value)) return null;
 	const materialization = value;
 	if (materialization.kind !== "child") throw new Error("session_materialization.kind must be \"child\".");
-	const parentSessionId = readOptionalString$11(materialization.parentSessionId);
+	const parentSessionId = readOptionalString$12(materialization.parentSessionId);
 	if (!parentSessionId) throw new Error("session_materialization.parentSessionId is required.");
 	if (materialization.inheritContext !== true) throw new Error("session_materialization.inheritContext must be true.");
 	return {
@@ -2093,7 +2108,7 @@ function resolveRunSpec(params) {
 	};
 }
 function attachRunSpecMetadata(params) {
-	const { message, modelSource, request, session, spec, startedAt } = params;
+	const { message, modelSource, request, session, spec, startedAt, trigger } = params;
 	const metadata = structuredClone(message.metadata ?? {});
 	metadata[AGENT_RUN_MESSAGE_RUN_SPEC_METADATA_KEY] = {
 		version: 1,
@@ -2112,6 +2127,7 @@ function attachRunSpecMetadata(params) {
 		correlationId: spec.correlationId ?? null,
 		execution: structuredClone(AGENT_RUN_EXECUTION_METADATA)
 	};
+	metadata[NCP_RUN_TRIGGER_METADATA_KEY] = structuredClone(trigger);
 	return {
 		...message,
 		metadata
@@ -2164,7 +2180,7 @@ var AgentRuntimeRunObserverService = class {
 				}));
 				messageCompletedSeen = true;
 			}
-			eventsToPublish.push(event);
+			eventsToPublish.push(this.projectCompletedMessage(event, sessionRun));
 			eventsToPublish.forEach(this.publishNcpEvent);
 			if (consumedSteeringInput) this.publishRunQueueUpdated(session.sessionId);
 		}), catchError(async (error) => {
@@ -2235,6 +2251,17 @@ var AgentRuntimeRunObserverService = class {
 			source: "agent-run-request"
 		});
 	};
+	projectCompletedMessage = (event, sessionRun) => {
+		if (event.type !== NcpEventType.MessageCompleted) return event;
+		const message = sessionRun.getSnapshot().messages.find((item) => item.id === event.payload.message.id);
+		return message ? {
+			...event,
+			payload: {
+				...event.payload,
+				message: structuredClone(message)
+			}
+		} : event;
+	};
 	publishNcpEvent = (event) => {
 		this.options.eventBus.emit(eventKeys$1.ncpEvent, event, {
 			emittedAt: (/* @__PURE__ */ new Date()).toISOString(),
@@ -2243,6 +2270,110 @@ var AgentRuntimeRunObserverService = class {
 	};
 };
 //#endregion
+//#region src/utils/agent-run-trigger.utils.ts
+function isRecord$17(value) {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function readOptionalString$11(value) {
+	return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
+function readSourceRunSpec(message) {
+	const value = message.metadata?.[AGENT_RUN_MESSAGE_RUN_SPEC_METADATA_KEY];
+	return isRecord$17(value) ? value : {};
+}
+const SOURCE_CONTEXT_KEYS = [
+	"channel",
+	"chatId",
+	"accountId",
+	"senderId",
+	"sessionKey",
+	"cron_job_id",
+	"cron_job_name",
+	"session_origin",
+	"observation_delivery_id",
+	"observation_subscription_id"
+];
+function readSourceContext(request) {
+	const candidates = {
+		...request.metadata ?? {},
+		...request.message.metadata ?? {},
+		...request.peerId ? { peerId: request.peerId } : {}
+	};
+	const entries = [...SOURCE_CONTEXT_KEYS, "peerId"].flatMap((key) => {
+		const value = candidates[key];
+		return value === null || typeof value === "string" || typeof value === "number" && Number.isFinite(value) || typeof value === "boolean" ? [[key, value]] : [];
+	});
+	return entries.length > 0 ? Object.fromEntries(entries) : void 0;
+}
+function createAgentToolRunTriggerInput(params) {
+	const { request, source } = params;
+	const runSpec = readSourceRunSpec(request.message);
+	const sourceSessionId = readOptionalString$11(request.sessionId);
+	const sourceRunId = readOptionalString$11(runSpec.runId);
+	const sourceModel = readOptionalString$11(runSpec.model);
+	const sourceContext = readSourceContext(request);
+	return {
+		actor: "agent",
+		source,
+		triggeredAt: (/* @__PURE__ */ new Date()).toISOString(),
+		...sourceSessionId ? { sourceSessionId } : {},
+		sourceMessageId: request.message.id,
+		...sourceRunId ? { sourceRunId } : {},
+		...sourceModel ? { sourceModel } : {},
+		...sourceContext ? { sourceContext } : {}
+	};
+}
+function createIngressRunTriggerInput(params) {
+	const { request } = params;
+	const source = request.channel ? `channel:${request.channel}` : params.source.trim() || "internal";
+	const sourceSessionId = readOptionalString$11(request.sessionId);
+	const sourceContext = readSourceContext(request);
+	const cronJobId = readOptionalString$11(request.metadata?.cron_job_id);
+	const isCron = request.metadata?.session_origin === "cron" || Boolean(cronJobId);
+	return {
+		actor: isCron ? "automation" : request.message.role === "user" ? "human" : request.message.role === "service" ? "automation" : "system",
+		source: isCron ? cronJobId ? `cron:${cronJobId}` : "cron" : source,
+		triggeredAt: request.message.timestamp,
+		...sourceSessionId ? { sourceSessionId } : {},
+		sourceMessageId: request.message.id,
+		...sourceContext ? { sourceContext } : {}
+	};
+}
+function resolveRunTriggerMetadata(params) {
+	const { request, spec, startedAt } = params;
+	const input = request.trigger ?? createIngressRunTriggerInput({
+		request,
+		source: "internal"
+	});
+	const triggeredAt = Number.isFinite(Date.parse(input.triggeredAt)) ? new Date(input.triggeredAt).toISOString() : startedAt;
+	return {
+		version: 1,
+		...structuredClone(input),
+		triggeredAt,
+		targetRunId: spec.runId
+	};
+}
+function createRunTriggerMetadataEvent(params) {
+	const { sessionId, spec, trigger } = params;
+	return {
+		occurredAt: trigger.triggeredAt,
+		type: NcpEventType.RunMetadata,
+		payload: {
+			sessionId,
+			runId: spec.runId,
+			correlationId: spec.correlationId,
+			metadata: { [NCP_RUN_TRIGGER_METADATA_KEY]: structuredClone(trigger) }
+		}
+	};
+}
+function attachSourceToolCall(trigger, sourceToolCallId) {
+	const normalizedToolCallId = readOptionalString$11(sourceToolCallId);
+	return {
+		...structuredClone(trigger),
+		...normalizedToolCallId ? { sourceToolCallId: normalizedToolCallId } : {}
+	};
+}
+//#endregion
 //#region src/managers/agent-run-request.manager.ts
 var AgentRunRequestManager = class {
 	cleanups = [];
@@ -2283,9 +2414,14 @@ var AgentRunRequestManager = class {
 		this.sessionCommandManager.dispose();
 		this.started = false;
 	};
-	handleSendRequest = async (envelope) => {
+	handleSendRequest = async (envelope, context) => {
 		if (!envelope.payload) throw new Error("Invalid agent run send request.");
-		return toRunHandle(await this.send(toAgentRunRequest(envelope.payload)));
+		const request = toAgentRunRequest(envelope.payload);
+		request.trigger = createIngressRunTriggerInput({
+			request,
+			source: context.source
+		});
+		return toRunHandle(await this.send(request));
 	};
 	handleAbortRequest = async (envelope) => {
 		if (!envelope.payload?.sessionId) throw new Error("Invalid agent run abort request.");
@@ -2312,7 +2448,8 @@ var AgentRunRequestManager = class {
 				...envelope.payload.message,
 				sessionId: envelope.payload.sessionId
 			},
-			correlationId: envelope.payload.requestId
+			correlationId: envelope.payload.requestId,
+			trigger: structuredClone(envelope.payload.trigger)
 		}));
 	};
 	send = async (request) => await this.idempotency.accept(request, this.sendOnce);
@@ -2365,6 +2502,11 @@ var AgentRunRequestManager = class {
 			runId: activeRequest.runId,
 			session
 		});
+		const trigger = resolveRunTriggerMetadata({
+			request,
+			spec,
+			startedAt: requestRunStartedAt
+		});
 		const message = attachRunSpecMetadata({
 			message: {
 				...request.message,
@@ -2375,7 +2517,8 @@ var AgentRunRequestManager = class {
 			request,
 			session,
 			spec,
-			startedAt: requestRunStartedAt
+			startedAt: requestRunStartedAt,
+			trigger
 		});
 		const providerRequest = {
 			...request,
@@ -2402,8 +2545,14 @@ var AgentRunRequestManager = class {
 			message,
 			correlationId: request.correlationId
 		});
-		await sessionRun.applyEvents([messageSentEvent]);
+		const triggerEvent = createRunTriggerMetadataEvent({
+			sessionId: session.sessionId,
+			spec,
+			trigger
+		});
+		await sessionRun.applyEvents([messageSentEvent, triggerEvent]);
 		this.publishNcpEvent(messageSentEvent);
+		this.publishNcpEvent(triggerEvent);
 		try {
 			const runtime = this.agentRuntimeManager.getOrCreate({
 				agentRuntimeId: session.agentRuntimeId,
@@ -10237,20 +10386,39 @@ function readMessageFromSummaryEvent(event) {
 function readRecordLabel(record) {
 	return readOptionalString(record.metadata?.label) ?? void 0;
 }
+function resolveRequestTrigger(params) {
+	return {
+		...params.trigger ?? {
+			actor: "system",
+			source: "session-request",
+			triggeredAt: (/* @__PURE__ */ new Date()).toISOString(),
+			sourceSessionId: params.sourceSessionId
+		},
+		sourceRequestId: params.requestId
+	};
+}
 var SessionRequestManager = class {
 	constructor(options) {
 		this.options = options;
 	}
 	spawnSessionAndRequest = async (params) => {
-		const { sourceSessionId, sourceToolCallId, updateToolCallResult, sourceSessionMetadata, metadataOverrides, contextInheritance, task, title, model, runtime, handoffDepth, sessionType, thinkingLevel, projectRoot, agentId, parentSessionId, notify } = params;
+		const { sourceSessionId, sourceToolCallId, updateToolCallResult, sourceSessionMetadata, metadataOverrides, contextInheritance, task, title, model, runtime, handoffDepth, sessionType, thinkingLevel, projectRoot, agentId, parentSessionId, notify, trigger: requestedTrigger } = params;
 		const requestId = randomUUID();
+		const trigger = resolveRequestTrigger({
+			trigger: requestedTrigger,
+			sourceSessionId,
+			requestId
+		});
 		const createdSession = await this.options.sessionManager.createSession({
 			sourceSessionId,
 			...parentSessionId ? { parentSessionId } : {},
 			task,
 			title,
 			sourceSessionMetadata,
-			...metadataOverrides ? { metadataOverrides } : {},
+			metadataOverrides: {
+				...metadataOverrides ?? {},
+				session_creation_trigger: structuredClone(trigger)
+			},
 			contextInheritance,
 			agentId,
 			model,
@@ -10273,18 +10441,25 @@ var SessionRequestManager = class {
 			agentId: createdSession.agentId,
 			isChildSession: Boolean(parentSessionId),
 			...parentSessionId ? { parentSessionId } : {},
-			spawnedByRequestId: requestId
+			spawnedByRequestId: requestId,
+			trigger
 		});
 	};
 	requestSession = async (params) => {
-		const { sourceSessionId, sourceToolCallId, updateToolCallResult, targetSessionId, task, title, notify, handoffDepth } = params;
+		const { sourceSessionId, sourceToolCallId, updateToolCallResult, targetSessionId, task, title, notify, handoffDepth, trigger: requestedTrigger } = params;
 		const normalizedTargetSessionId = targetSessionId.trim();
 		if (normalizedTargetSessionId === sourceSessionId.trim()) throw new Error("sessions_request cannot target the current session.");
 		const targetSession = await this.options.sessionManager.getSessionRecord(normalizedTargetSessionId);
 		if (!targetSession) throw new Error(`Target session not found: ${targetSessionId}`);
 		const parentSessionId = readParentSessionId(targetSession.metadata);
+		const requestId = randomUUID();
+		const trigger = resolveRequestTrigger({
+			trigger: requestedTrigger,
+			sourceSessionId,
+			requestId
+		});
 		return this.dispatchRequest({
-			requestId: randomUUID(),
+			requestId,
 			sourceSessionId,
 			sourceToolCallId,
 			updateToolCallResult,
@@ -10296,11 +10471,12 @@ var SessionRequestManager = class {
 			agentId: targetSession.agentId,
 			isChildSession: Boolean(parentSessionId),
 			parentSessionId: parentSessionId ?? void 0,
-			spawnedByRequestId: void 0
+			spawnedByRequestId: void 0,
+			trigger
 		});
 	};
 	dispatchRequest = async (params) => {
-		const { requestId, sourceSessionId, sourceToolCallId, updateToolCallResult, targetSessionId, task, title, handoffDepth, notify, agentId, isChildSession, parentSessionId, spawnedByRequestId } = params;
+		const { requestId, sourceSessionId, sourceToolCallId, updateToolCallResult, targetSessionId, task, title, handoffDepth, notify, agentId, isChildSession, parentSessionId, spawnedByRequestId, trigger } = params;
 		const request = createRunningSessionRequest({
 			requestId,
 			sourceSessionId,
@@ -10311,7 +10487,8 @@ var SessionRequestManager = class {
 			title,
 			task,
 			isChildSession,
-			parentSessionId
+			parentSessionId,
+			trigger
 		});
 		const resultContext = {
 			task,
@@ -10469,6 +10646,13 @@ function waitForAgentRuntimeSessionReply(input) {
 	};
 }
 async function dispatchAgentRuntimeSessionRequest(input) {
+	const trigger = parseNcpRunTriggerInput(input.request.metadata?.run_trigger) ?? {
+		actor: "system",
+		source: "session-request-recovery",
+		triggeredAt: input.request.createdAt,
+		sourceSessionId: input.request.sourceSessionId,
+		sourceRequestId: input.request.requestId
+	};
 	await input.ingress.handle({
 		type: ingressKeys$1.agentRun.sessionMessageRequest,
 		payload: {
@@ -10485,7 +10669,8 @@ async function dispatchAgentRuntimeSessionRequest(input) {
 				metadata: { session_request_id: input.request.requestId }
 			},
 			requestId: input.request.requestId,
-			sessionId: input.request.targetSessionId
+			sessionId: input.request.targetSessionId,
+			trigger: structuredClone(trigger)
 		}
 	}, { source: "session-request" });
 }
@@ -12826,6 +13011,7 @@ const createSelfManagementContextProvider = () => ({ provide: () => {
 } });
 const createSessionOrchestrationContextProvider = () => staticBlock([
 	"## Session Orchestration",
+	"- Only top-level sessions can create new sessions. Child sessions must complete their delegated task directly and return further delegation needs to the parent session.",
 	"- Before passing a non-default `runtime` to `sessions_spawn` or agent creation/update flows, inspect the installed runtime kinds with `nextclaw agents runtimes --json`.",
 	"- `sessions_spawn` is the unified session-creation tool. Omit `scope` or use `scope=\"standalone\"` for a regular session, and use `scope=\"child\"` when the new session should be a child session of the current flow.",
 	"- `sessions_spawn` only creates the session by default. Add top-level `notify: \"none\" | \"final_reply\"` when the new session should start working immediately.",
@@ -12977,6 +13163,9 @@ function renderWebSearchReadiness(params) {
 	if (!readSearchApiKey(searchConfig, provider)) return `web_search is not ready: provider ${provider} has no API key configured.`;
 	return `web_search is ready with provider ${provider}.`;
 }
+function renderDelegationGuidance(toolNames) {
+	return toolNames.includes("sessions_spawn") ? "If a task is more complex or takes longer, spawn a sub-agent. Completion is push-based: it will auto-announce when done." : "Sub-agent spawning is unavailable in this delegated session. Complete the assigned task directly and return any further delegation needs to the parent session.";
+}
 var ToolingContextProvider = class {
 	constructor(context) {
 		this.context = context;
@@ -12998,7 +13187,7 @@ var ToolingContextProvider = class {
 			"TOOLS.md does not control tool availability; it is user guidance for how to use external tools.",
 			"For long waits, avoid rapid poll loops: use exec with enough yieldMs.",
 			"For relative time/date scheduling requests (for example 'in 5 minutes' / '1分钟后'), first check the current local time with an available tool such as exec/date, then convert it to an absolute ISO time with timezone. Do not guess.",
-			"If a task is more complex or takes longer, spawn a sub-agent. Completion is push-based: it will auto-announce when done.",
+			renderDelegationGuidance(toolCatalog.map((tool) => tool.name)),
 			"Do not poll `subagents list` / `sessions_list` in a loop; only check status on-demand (for intervention, debugging, or when explicitly asked)."
 		].join("\n")];
 	};
@@ -13692,6 +13881,7 @@ var LearningLoopContribution = class extends Contribution$1 {
 		if (toolCallsSinceReview < runtimeConfig.toolCallThreshold) return;
 		this.inFlightSessionIds.add(sessionId);
 		try {
+			const triggeredAt = (/* @__PURE__ */ new Date()).toISOString();
 			const reviewSession = await this.sessionRequester.spawnSessionAndRequest({
 				sourceSessionId: sessionId,
 				sourceSessionMetadata: metadata,
@@ -13707,11 +13897,18 @@ var LearningLoopContribution = class extends Contribution$1 {
 					sessionId,
 					toolCallsSinceReview,
 					currentToolCallCount: totalToolCalls
-				})
+				}),
+				trigger: {
+					actor: "automation",
+					source: "learning-loop",
+					triggeredAt,
+					sourceSessionId: sessionId,
+					...typeof metadata.preferred_model === "string" && metadata.preferred_model.trim() ? { sourceModel: metadata.preferred_model.trim() } : {}
+				}
 			});
 			await this.sessionStore.updateSessionMetadata(sessionId, {
 				[LEARNING_LOOP_LAST_TOOL_CALL_COUNT_METADATA_KEY]: totalToolCalls,
-				[LEARNING_LOOP_LAST_REQUESTED_AT_METADATA_KEY]: (/* @__PURE__ */ new Date()).toISOString(),
+				[LEARNING_LOOP_LAST_REQUESTED_AT_METADATA_KEY]: triggeredAt,
 				[LEARNING_LOOP_LAST_REVIEW_SESSION_ID_METADATA_KEY]: reviewSession.sessionId
 			});
 		} finally {
@@ -14076,12 +14273,14 @@ var SessionRequestTool = class {
 	};
 	sourceSessionId = "";
 	handoffDepth = 0;
+	trigger = null;
 	constructor(manager) {
 		this.manager = manager;
 	}
 	setContext = (params) => {
 		this.sourceSessionId = params.sourceSessionId;
 		this.handoffDepth = params.handoffDepth ?? 0;
+		this.trigger = structuredClone(params.trigger);
 	};
 	execute = async (args, context) => {
 		const params = normalizeToolParams(args);
@@ -14098,9 +14297,14 @@ var SessionRequestTool = class {
 			task,
 			title: readOptionalString$6(params, "title"),
 			notify: notifyMode,
-			handoffDepth: this.handoffDepth
+			handoffDepth: this.handoffDepth,
+			trigger: attachSourceToolCall(this.readTriggerOrThrow(), context?.toolCallId)
 		});
 	};
+	readTriggerOrThrow = () => {
+		if (!this.trigger) throw new Error("sessions_request requires an active run trigger context.");
+		return structuredClone(this.trigger);
+	};
 };
 //#endregion
 //#region src/tools/session-search.tools.ts
@@ -14240,16 +14444,20 @@ var SessionSpawnTool = class {
 	sourceSessionId = "";
 	sourceSessionMetadata = {};
 	handoffDepth = 0;
+	trigger = null;
 	constructor(sessionManager, sessionRequestManager) {
 		this.sessionManager = sessionManager;
 		this.sessionRequestManager = sessionRequestManager;
 	}
 	setContext = (params) => {
-		this.sourceSessionId = params.sourceSessionId;
-		this.sourceSessionMetadata = structuredClone(params.sourceSessionMetadata);
-		this.handoffDepth = params.handoffDepth ?? 0;
+		const { handoffDepth, sourceSessionId, sourceSessionMetadata, trigger } = params;
+		this.sourceSessionId = sourceSessionId;
+		this.sourceSessionMetadata = structuredClone(sourceSessionMetadata);
+		this.handoffDepth = handoffDepth ?? 0;
+		this.trigger = structuredClone(trigger);
 	};
 	execute = async (args, context) => {
+		const { toolCallId, updateToolCallResult } = context ?? {};
 		const { agentId: rawAgentId, model: rawModel, notify: rawNotify, runtime: rawRuntime, scope: rawScope, task: rawTask, title: rawTitle, inheritContext: rawInheritContext } = normalizeToolParams(args);
 		const task = readRequiredString$4(rawTask, "task");
 		const scope = readSpawnScope(rawScope);
@@ -14257,11 +14465,12 @@ var SessionSpawnTool = class {
 		const inheritContext = readInheritContext(rawInheritContext);
 		if (inheritContext && scope !== "child") throw new Error("inheritContext=true requires scope=\"child\".");
 		const parentSessionId = scope === "child" ? this.readParentSessionIdOrThrow() : void 0;
-		const contextInheritance = inheritContext ? { anchorToolCallId: context?.toolCallId } : void 0;
+		const contextInheritance = inheritContext ? { anchorToolCallId: toolCallId } : void 0;
+		const trigger = attachSourceToolCall(this.readTriggerOrThrow(), toolCallId);
 		if (notify) return this.sessionRequestManager.spawnSessionAndRequest({
 			sourceSessionId: this.sourceSessionId,
-			sourceToolCallId: context?.toolCallId,
-			updateToolCallResult: context?.updateToolCallResult,
+			sourceToolCallId: toolCallId,
+			updateToolCallResult,
 			sourceSessionMetadata: this.sourceSessionMetadata,
 			task,
 			title: readOptionalString$5(rawTitle),
@@ -14271,7 +14480,8 @@ var SessionSpawnTool = class {
 			contextInheritance,
 			handoffDepth: this.handoffDepth,
 			parentSessionId,
-			notify
+			notify,
+			trigger
 		});
 		const session = await this.sessionManager.createSession({
 			sourceSessionId: this.sourceSessionId,
@@ -14282,7 +14492,8 @@ var SessionSpawnTool = class {
 			model: readOptionalString$5(rawModel),
 			runtime: readOptionalString$5(rawRuntime),
 			contextInheritance,
-			parentSessionId
+			parentSessionId,
+			metadataOverrides: { session_creation_trigger: structuredClone(trigger) }
 		});
 		return {
 			kind: "nextclaw.session",
@@ -14301,6 +14512,10 @@ var SessionSpawnTool = class {
 		if (!sourceSessionId) throw new Error("scope=\"child\" requires an active source session.");
 		return sourceSessionId;
 	};
+	readTriggerOrThrow = () => {
+		if (!this.trigger) throw new Error("sessions_spawn requires an active run trigger context.");
+		return structuredClone(this.trigger);
+	};
 };
 //#endregion
 //#region src/tools/session-update.tools.ts
@@ -14355,26 +14570,38 @@ var SessionToolProvider = class {
 		this.sessionSearch = sessionSearch;
 	}
 	provide = async (request) => {
-		const { toolRunContext } = await this.runContextService.resolve(request);
+		const { session, toolRunContext } = await this.runContextService.resolve(request);
 		const { handoffDepth, metadata, sessionId } = toolRunContext;
-		const sessionsSpawnTool = new SessionSpawnTool(this.sessionManager, this.sessionRequests);
-		sessionsSpawnTool.setContext({
-			sourceSessionId: sessionId,
-			sourceSessionMetadata: metadata,
-			handoffDepth
+		const isChildSession = Boolean(readParentSessionId(session?.metadata ?? metadata));
+		const requestTrigger = createAgentToolRunTriggerInput({
+			request,
+			source: "sessions_request"
 		});
 		const sessionsRequestTool = new SessionRequestTool(this.sessionRequests);
 		sessionsRequestTool.setContext({
 			sourceSessionId: sessionId,
-			handoffDepth
+			handoffDepth,
+			trigger: requestTrigger
 		});
 		const tools = [
-			sessionsSpawnTool,
 			sessionsRequestTool,
 			new SessionsListTool(this.sessionManager),
 			new SessionsHistoryTool(this.sessionManager),
 			new SessionsUpdateTool(this.sessionManager)
 		];
+		if (!isChildSession) {
+			const sessionsSpawnTool = new SessionSpawnTool(this.sessionManager, this.sessionRequests);
+			sessionsSpawnTool.setContext({
+				sourceSessionId: sessionId,
+				sourceSessionMetadata: metadata,
+				handoffDepth,
+				trigger: createAgentToolRunTriggerInput({
+					request,
+					source: "sessions_spawn"
+				})
+			});
+			tools.unshift(sessionsSpawnTool);
+		}
 		if (!this.sessionSearch.isReady()) return tools;
 		tools.push(new SessionSearchTool({ search: this.sessionSearch.search }, { currentSessionId: sessionId }));
 		return tools;
@@ -15242,6 +15469,14 @@ const SESSION_METADATA_LABEL_KEY = "label";
 const CHILD_SESSION_PARENT_METADATA_KEY = "parent_session_id";
 const CHILD_SESSION_REQUEST_METADATA_KEY = "spawned_by_request_id";
 const CHILD_SESSION_LIFECYCLE_METADATA_KEY = "session_lifecycle";
+async function assertCanCreateSessionFromLineage(parentSessionId, sourceRecord, metadataOverrides, getSessionRecord) {
+	if (Object.prototype.hasOwnProperty.call(metadataOverrides ?? {}, CHILD_SESSION_PARENT_METADATA_KEY)) throw new Error("Session parent must be set through parentSessionId.");
+	if (readOptionalMetadataString(sourceRecord?.metadata?.[CHILD_SESSION_PARENT_METADATA_KEY])) throw new Error(`Child sessions cannot create additional sessions. Source session: ${sourceRecord?.sessionId}.`);
+	if (!parentSessionId) return;
+	const parentRecord = sourceRecord?.sessionId === parentSessionId ? sourceRecord : await getSessionRecord(parentSessionId);
+	if (!parentRecord) throw new Error(`Parent session not found: ${parentSessionId}`);
+	if (readOptionalMetadataString(parentRecord.metadata?.[CHILD_SESSION_PARENT_METADATA_KEY])) throw new Error(`Child sessions cannot create additional sessions. Parent session: ${parentSessionId}.`);
+}
 function readThinkingEffort(metadata) {
 	return readOptionalMetadataString(metadata?.thinkingEffort) ?? readOptionalMetadataString(metadata?.preferred_thinking) ?? readOptionalMetadataString(metadata?.thinking) ?? null;
 }
@@ -17294,6 +17529,7 @@ var SessionManager = class {
 		const metadata = cloneInheritedMetadata(sourceSessionMetadata);
 		const title = readOptionalString$2(requestedTitle) ?? summarizeTask(task);
 		const parentSessionId = readOptionalString$2(rawParentSessionId);
+		await assertCanCreateSessionFromLineage(parentSessionId, sourceRecord, metadataOverrides, this.getSessionRecord);
 		const requestId = readOptionalString$2(rawRequestId);
 		const sessionType = resolveSessionType({
 			runtime,
@@ -17453,23 +17689,9 @@ var SessionManager = class {
 		return (liveRecord ? await this.summaryProjection.createWithContextWindow(liveRecord) : await this.getSession(sessionId))?.contextWindow ?? null;
 	};
 	getAgentRunSession = async (sessionId) => {
-		const record = await this.getSessionRecord(sessionId);
-		if (!record) throw new Error(`Session not found: ${sessionId}`);
-		const agentRuntimeId = readOptionalMetadataString(record.metadata?.agentRuntimeId) ?? "native";
-		const model = readOptionalMetadataString(record.metadata?.model);
-		return {
-			sessionId: record.sessionId,
-			agentId: record.agentId,
-			agentRuntimeId,
-			metadata: structuredClone(record.metadata ?? {}),
-			model,
-			projectRoot: readProjectRoot(record.metadata),
-			workingDir: this.workingDirResolver.resolve({
-				agentId: record.agentId,
-				metadata: record.metadata
-			}),
-			thinkingEffort: readThinkingEffort(record.metadata)
-		};
+		const summary = await this.options.journalStore.getSessionSummary(sessionId);
+		if (!summary) throw new Error(`Session not found: ${sessionId}`);
+		return this.toAgentRunSession(summary);
 	};
 	createAgentRunSession = async (params) => {
 		const { agentId, agentRuntimeId: requestedAgentRuntimeId, channel, contextInheritance, metadata, model, parentSessionId: rawParentSessionId, peerId: rawPeerId, projectRoot, sessionId, sourceSessionId: rawSourceSessionId, sourceSessionMetadata: requestedSourceSessionMetadata, task, thinkingEffort } = params;
@@ -17520,7 +17742,24 @@ var SessionManager = class {
 	};
 	getOrCreateAgentRunSession = async (params) => {
 		if (!params.sessionId) return await this.createAgentRunSession(params);
-		return await this.getSessionRecord(params.sessionId) ? await this.getAgentRunSession(params.sessionId) : await this.createAgentRunSession(params);
+		const summary = await this.options.journalStore.getSessionSummary(params.sessionId);
+		return summary ? this.toAgentRunSession(summary) : await this.createAgentRunSession(params);
+	};
+	toAgentRunSession = (summary) => {
+		const metadata = summary.metadata ?? {};
+		return {
+			sessionId: summary.sessionId,
+			agentId: summary.agentId,
+			agentRuntimeId: readOptionalMetadataString(metadata.agentRuntimeId) ?? "native",
+			metadata: structuredClone(metadata),
+			model: readOptionalMetadataString(metadata.model) ?? readOptionalMetadataString(metadata.preferred_model),
+			projectRoot: readProjectRoot(metadata),
+			workingDir: this.workingDirResolver.resolve({
+				agentId: summary.agentId,
+				metadata
+			}),
+			thinkingEffort: readThinkingEffort(metadata)
+		};
 	};
 	patchSessionMetadata = async (sessionId, patch) => {
 		if (!await this.updateSessionMetadata(sessionId, patch)) throw new Error(`Session metadata was not updated: ${sessionId}`);