@nextclaw/kernel 0.5.1 → 0.5.2

package/dist/index.js

@@ -4,7 +4,7 @@ import { APP_NAME, AgentRouteResolver, BUILTIN_MAIN_AGENT_ID, CLEAR_THINKING_TOK
 import { NcpEventType, sanitizeAssistantReplyTags } from "@nextclaw/ncp";
 import { LocalAssetStore, buildAssetContentPath, buildNcpUserContent, buildOpenAiFunctionTool, ncpMessageToOpenAiMessages, validateToolArgs } from "@nextclaw/ncp-agent-runtime";
 import { createHash, createHmac, randomBytes, randomUUID, scryptSync, timingSafeEqual } from "node:crypto";
-import { EventBus, Ingress, eventKeys, ingressKeys, isRuntimeDefaultModelValue, normalizeRuntimeModelSelectionMode } from "@nextclaw/shared";
+import { CHAT_SESSION_MATERIALIZATION_METADATA_KEY, EventBus, Ingress, eventKeys, ingressKeys, isRuntimeDefaultModelValue, normalizeRuntimeModelSelectionMode } from "@nextclaw/shared";
 import { catchError, from, lastValueFrom, tap } from "rxjs";
 import { appendFileSync, chmodSync, constants, existsSync, mkdirSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { basename, delimiter, dirname, extname, isAbsolute, join, normalize, relative, resolve } from "node:path";
@@ -584,6 +584,20 @@ function readOptionalString$10(value) {
 	if (typeof value !== "string") return;
 	return value.trim() || void 0;
 }
+function readSessionMaterialization(metadata) {
+	const value = metadata[CHAT_SESSION_MATERIALIZATION_METADATA_KEY];
+	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$10(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 {
+		kind: "child",
+		parentSessionId,
+		inheritContext: true
+	};
+}
 function toRunHandle(accepted) {
 	return {
 		sessionId: accepted.sessionId,
@@ -642,18 +656,7 @@ var AgentRunRequestManager = class {
 		}));
 	};
 	send = async (request) => {
-		const session = await this.sessionManager.getOrCreateAgentRunSession({
-			sessionId: request.sessionId,
-			peerId: request.peerId,
-			agentId: request.agentId,
-			agentRuntimeId: request.agentRuntimeId,
-			channel: request.channel,
-			metadata: request.metadata,
-			model: request.model,
-			projectRoot: request.projectRoot,
-			task: readMessageTask(request.message),
-			thinkingEffort: request.thinkingEffort
-		});
+		const session = await this.getOrCreateSessionForRequest(request);
 		const sessionRun = this.sessionRunManager.getSessionRun(session.sessionId) ?? await this.sessionRunManager.createSessionRun(session.sessionId);
 		const message = {
 			...request.message,
@@ -763,6 +766,25 @@ var AgentRunRequestManager = class {
 			correlationId: request.correlationId
 		};
 	};
+	getOrCreateSessionForRequest = async (request) => {
+		const sessionMaterialization = readSessionMaterialization(request.metadata ?? {});
+		if (sessionMaterialization && (request.sessionId || request.peerId)) throw new Error("session_materialization requires a new session request.");
+		return await this.sessionManager.getOrCreateAgentRunSession({
+			sessionId: request.sessionId,
+			peerId: request.peerId,
+			agentId: request.agentId,
+			agentRuntimeId: request.agentRuntimeId,
+			channel: request.channel,
+			contextInheritance: sessionMaterialization ? {} : void 0,
+			metadata: request.metadata,
+			model: request.model,
+			parentSessionId: sessionMaterialization?.parentSessionId,
+			projectRoot: request.projectRoot,
+			sourceSessionId: sessionMaterialization?.parentSessionId,
+			task: readMessageTask(request.message),
+			thinkingEffort: request.thinkingEffort
+		});
+	};
 	abort = async (request) => {
 		this.sessionRunManager.getSessionRun(request.sessionId)?.abortRun(request.runId);
 	};
@@ -3581,6 +3603,144 @@ function readOptionalMetadataString(value) {
 function readEventSessionId$1(event) {
 	return "payload" in event && "sessionId" in event.payload ? readOptionalMetadataString(event.payload.sessionId) : void 0;
 }
+const DEFAULT_SESSION_LIFECYCLE = "persistent";
+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";
+function readThinkingEffort(metadata) {
+	return readOptionalMetadataString(metadata?.thinkingEffort) ?? readOptionalMetadataString(metadata?.preferred_thinking) ?? readOptionalMetadataString(metadata?.thinking) ?? null;
+}
+function readProjectRoot(metadata) {
+	return readOptionalMetadataString(metadata?.project_root) ?? readOptionalMetadataString(metadata?.projectRoot);
+}
+function readAgentRuntimeId(metadata) {
+	return readOptionalMetadataString(metadata?.agentRuntimeId) ?? readOptionalMetadataString(metadata?.runtime) ?? readOptionalMetadataString(metadata?.session_type);
+}
+function summarizeTask(task) {
+	const normalized = task.trim().replace(/\s+/g, " ");
+	if (!normalized) return "Session";
+	return normalized.length <= 72 ? normalized : `${normalized.slice(0, 69)}...`;
+}
+function cloneInheritedMetadata(sourceMetadata) {
+	const nextMetadata = {};
+	for (const key of [
+		"runtime",
+		"session_type",
+		"preferred_model",
+		"preferred_thinking",
+		"project_root",
+		"requested_skill_refs",
+		"codex_runtime_backend",
+		"reasoningNormalizationMode",
+		"reasoning_normalization_mode"
+	]) if (Object.prototype.hasOwnProperty.call(sourceMetadata, key)) nextMetadata[key] = structuredClone(sourceMetadata[key]);
+	return nextMetadata;
+}
+function mergeMetadataOverrides(metadata, overrides) {
+	return overrides && Object.keys(overrides).length > 0 ? {
+		...metadata,
+		...structuredClone(overrides)
+	} : metadata;
+}
+function resolveSessionType(params) {
+	const { metadata, runtime, sessionType } = params;
+	return readOptionalString$8(runtime) ?? readOptionalString$8(metadata.runtime) ?? readOptionalString$8(sessionType) ?? readOptionalString$8(metadata.session_type) ?? "native";
+}
+function applySessionOverrides(params) {
+	const { lifecycle, metadata, model, parentSessionId, projectRoot, requestId, sessionType, thinkingLevel, title } = params;
+	metadata.session_type = sessionType;
+	metadata.runtime = sessionType;
+	metadata[SESSION_METADATA_LABEL_KEY] = title;
+	metadata[CHILD_SESSION_LIFECYCLE_METADATA_KEY] = lifecycle;
+	if (parentSessionId) metadata[CHILD_SESSION_PARENT_METADATA_KEY] = parentSessionId;
+	if (requestId) metadata[CHILD_SESSION_REQUEST_METADATA_KEY] = requestId;
+	if (readOptionalString$8(model)) {
+		metadata.model = model?.trim();
+		metadata.preferred_model = model?.trim();
+	}
+	if (readOptionalString$8(thinkingLevel)) {
+		metadata.thinking = thinkingLevel?.trim();
+		metadata.preferred_thinking = thinkingLevel?.trim();
+	}
+	if (readOptionalString$8(projectRoot)) metadata.project_root = projectRoot?.trim();
+}
+//#endregion
+//#region src/utils/session-context-inheritance.utils.ts
+const CONTEXT_INHERITANCE_METADATA_KEY = "context_inheritance";
+const INHERITED_FROM_SESSION_METADATA_KEY = "inherited_from_session_id";
+const INHERITED_FROM_MESSAGE_METADATA_KEY = "inherited_from_message_id";
+function hasToolCall(message, toolCallId) {
+	return message.parts.some((part) => part.type === "tool-invocation" && part.toolCallId === toolCallId);
+}
+function findContextInheritanceAnchor(params) {
+	const anchorToolCallId = readOptionalString$8(params.anchorToolCallId);
+	if (!anchorToolCallId) return null;
+	const index = params.messages.findIndex((message) => hasToolCall(message, anchorToolCallId));
+	const message = index >= 0 ? params.messages[index] : void 0;
+	return message ? {
+		index,
+		message
+	} : null;
+}
+function createInheritedContextMessage(params) {
+	const { childSessionId, index, sourceMessage, sourceSessionId } = params;
+	const message = structuredClone(sourceMessage);
+	const metadata = structuredClone(message.metadata ?? {});
+	metadata[INHERITED_FROM_SESSION_METADATA_KEY] = sourceSessionId;
+	metadata[INHERITED_FROM_MESSAGE_METADATA_KEY] = sourceMessage.id;
+	return {
+		...message,
+		id: `${childSessionId}:inherited:${index + 1}`,
+		sessionId: childSessionId,
+		metadata
+	};
+}
+function createInheritedContextSnapshot(params) {
+	const { anchorToolCallId, childSessionId, sourceRecord } = params;
+	const anchor = findContextInheritanceAnchor({
+		anchorToolCallId,
+		messages: sourceRecord.messages
+	});
+	const messages = (anchor ? sourceRecord.messages.slice(0, anchor.index) : sourceRecord.messages).filter((message) => message.status === "final").map((sourceMessage, index) => createInheritedContextMessage({
+		childSessionId,
+		index,
+		sourceMessage,
+		sourceSessionId: sourceRecord.sessionId
+	}));
+	return {
+		messages,
+		metadata: {
+			enabled: true,
+			sourceSessionId: sourceRecord.sessionId,
+			anchorKind: anchor ? "tool_call" : "latest_persisted",
+			anchorToolCallId: readOptionalString$8(anchorToolCallId),
+			anchorMessageId: anchor?.message.id,
+			inheritedMessageCount: messages.length
+		}
+	};
+}
+function createSessionContextInheritance(params) {
+	const { childSessionId, contextInheritance, metadata, parentSessionId, sourceRecord } = params;
+	if (!contextInheritance) return {
+		messages: [],
+		metadata
+	};
+	if (!parentSessionId) throw new Error("contextInheritance requires a child session parentSessionId.");
+	if (!sourceRecord) throw new Error("Cannot inherit context because the source session was not found.");
+	const snapshot = createInheritedContextSnapshot({
+		anchorToolCallId: contextInheritance.anchorToolCallId,
+		childSessionId,
+		sourceRecord
+	});
+	return {
+		messages: snapshot.messages,
+		metadata: {
+			...metadata,
+			[CONTEXT_INHERITANCE_METADATA_KEY]: snapshot.metadata
+		}
+	};
+}
 //#endregion
 //#region src/contributions/session-activity-preview/utils/session-activity-preview-ncp-event.utils.ts
 const PREVIEW_TEXT_MAX_LENGTH = 160;
@@ -3860,69 +4020,9 @@ var SessionWorkingDirResolver = class {
 };
 //#endregion
 //#region src/managers/session.manager.ts
-const DEFAULT_SESSION_TYPE = "native";
-const DEFAULT_LIFECYCLE = "persistent";
-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";
-function readThinkingEffort(metadata) {
-	return readOptionalMetadataString(metadata?.thinkingEffort) ?? null;
-}
-function readProjectRoot(metadata) {
-	return readOptionalMetadataString(metadata?.project_root) ?? readOptionalMetadataString(metadata?.projectRoot);
-}
-function summarizeTask(task) {
-	const normalized = task.trim().replace(/\s+/g, " ");
-	if (!normalized) return "Session";
-	return normalized.length <= 72 ? normalized : `${normalized.slice(0, 69)}...`;
-}
 function buildSessionId() {
 	return `ncp-${Date.now().toString(36)}-${randomUUID().replace(/-/g, "").slice(0, 8)}`;
 }
-function cloneInheritedMetadata(sourceMetadata) {
-	const nextMetadata = {};
-	for (const key of [
-		"runtime",
-		"session_type",
-		"preferred_model",
-		"preferred_thinking",
-		"project_root",
-		"requested_skill_refs",
-		"codex_runtime_backend",
-		"reasoningNormalizationMode",
-		"reasoning_normalization_mode"
-	]) if (Object.prototype.hasOwnProperty.call(sourceMetadata, key)) nextMetadata[key] = structuredClone(sourceMetadata[key]);
-	return nextMetadata;
-}
-function mergeMetadataOverrides(metadata, overrides) {
-	return overrides && Object.keys(overrides).length > 0 ? {
-		...metadata,
-		...structuredClone(overrides)
-	} : metadata;
-}
-function resolveSessionType(params) {
-	const { metadata, runtime, sessionType } = params;
-	return readOptionalString$8(runtime) ?? readOptionalString$8(metadata.runtime) ?? readOptionalString$8(sessionType) ?? readOptionalString$8(metadata.session_type) ?? DEFAULT_SESSION_TYPE;
-}
-function applySessionOverrides(params) {
-	const { lifecycle, metadata, model, parentSessionId, projectRoot, requestId, sessionType, thinkingLevel, title } = params;
-	metadata.session_type = sessionType;
-	metadata.runtime = sessionType;
-	metadata[SESSION_METADATA_LABEL_KEY] = title;
-	metadata[CHILD_SESSION_LIFECYCLE_METADATA_KEY] = lifecycle;
-	if (parentSessionId) metadata[CHILD_SESSION_PARENT_METADATA_KEY] = parentSessionId;
-	if (requestId) metadata[CHILD_SESSION_REQUEST_METADATA_KEY] = requestId;
-	if (readOptionalString$8(model)) {
-		metadata.model = model?.trim();
-		metadata.preferred_model = model?.trim();
-	}
-	if (readOptionalString$8(thinkingLevel)) {
-		metadata.thinking = thinkingLevel?.trim();
-		metadata.preferred_thinking = thinkingLevel?.trim();
-	}
-	if (readOptionalString$8(projectRoot)) metadata.project_root = projectRoot?.trim();
-}
 function isSessionSummaryRefreshEvent(event) {
 	switch (event.type) {
 		case NcpEventType.MessageSent:
@@ -3964,7 +4064,7 @@ var SessionManager = class {
 		this.started = false;
 	};
 	createSession = async (params) => {
-		const { agentId: requestedAgentId, metadataOverrides, model, parentSessionId: rawParentSessionId, projectRoot, requestId: rawRequestId, runtime, sessionId: requestedSessionId, sessionType: requestedSessionType, sourceSessionId, sourceSessionMetadata, task, thinkingLevel, title: requestedTitle } = params;
+		const { agentId: requestedAgentId, contextInheritance, metadataOverrides, model, parentSessionId: rawParentSessionId, projectRoot, requestId: rawRequestId, runtime, sessionId: requestedSessionId, sessionType: requestedSessionType, sourceSessionId, sourceSessionMetadata, task, thinkingLevel, title: requestedTitle } = params;
 		const sourceRecord = sourceSessionId ? await this.getSessionRecord(sourceSessionId) : null;
 		const metadata = cloneInheritedMetadata(sourceSessionMetadata);
 		const title = readOptionalString$8(requestedTitle) ?? summarizeTask(task);
@@ -3976,7 +4076,7 @@ var SessionManager = class {
 			metadata
 		});
 		applySessionOverrides({
-			lifecycle: DEFAULT_LIFECYCLE,
+			lifecycle: DEFAULT_SESSION_LIFECYCLE,
 			metadata,
 			model,
 			parentSessionId: parentSessionId ?? void 0,
@@ -3990,13 +4090,20 @@ var SessionManager = class {
 		const nextMetadata = mergeMetadataOverrides(metadata, metadataOverrides);
 		const agentId = readOptionalString$8(requestedAgentId) ?? readOptionalString$8(sourceRecord?.agentId) ?? BUILTIN_MAIN_AGENT_ID;
 		const sessionId = readOptionalString$8(requestedSessionId) ?? buildSessionId();
+		const inheritedContext = createSessionContextInheritance({
+			childSessionId: sessionId,
+			contextInheritance,
+			metadata: nextMetadata,
+			parentSessionId,
+			sourceRecord
+		});
 		const record = {
 			sessionId,
 			...agentId ? { agentId } : {},
-			messages: [],
+			messages: inheritedContext.messages,
 			createdAt: now,
 			updatedAt: now,
-			metadata: nextMetadata
+			metadata: inheritedContext.metadata
 		};
 		await this.options.journalStore.importSessionSnapshot(record);
 		await this.publishSessionChange(sessionId);
@@ -4004,12 +4111,12 @@ var SessionManager = class {
 			sessionId,
 			agentId,
 			sessionType,
-			runtimeFamily: sessionType === DEFAULT_SESSION_TYPE ? "native" : "external",
+			runtimeFamily: sessionType === "native" ? "native" : "external",
 			...parentSessionId ? { parentSessionId } : {},
 			...requestId ? { spawnedByRequestId: requestId } : {},
-			lifecycle: DEFAULT_LIFECYCLE,
+			lifecycle: DEFAULT_SESSION_LIFECYCLE,
 			title,
-			metadata: nextMetadata,
+			metadata: inheritedContext.metadata,
 			createdAt: now,
 			updatedAt: now
 		};
@@ -4097,9 +4204,13 @@ var SessionManager = class {
 		};
 	};
 	createAgentRunSession = async (params) => {
-		const { agentId, agentRuntimeId: requestedAgentRuntimeId, channel, metadata, model, peerId: rawPeerId, projectRoot, sessionId, task, thinkingEffort } = params;
-		const agentRuntimeId = requestedAgentRuntimeId ?? "native";
+		const { agentId, agentRuntimeId: requestedAgentRuntimeId, channel, contextInheritance, metadata, model, parentSessionId: rawParentSessionId, peerId: rawPeerId, projectRoot, sessionId, sourceSessionId: rawSourceSessionId, sourceSessionMetadata: requestedSourceSessionMetadata, task, thinkingEffort } = params;
 		const peerId = readOptionalString$8(rawPeerId);
+		const parentSessionId = readOptionalString$8(rawParentSessionId);
+		const sourceSessionId = readOptionalString$8(rawSourceSessionId);
+		const sourceRecord = sourceSessionId ? await this.getSessionRecord(sourceSessionId) : null;
+		const sourceSessionMetadata = requestedSourceSessionMetadata ?? sourceRecord?.metadata ?? {};
+		const agentRuntimeId = requestedAgentRuntimeId ?? readAgentRuntimeId(sourceSessionMetadata) ?? "native";
 		const peerIdentity = peerId ? createAgentPeerSessionIdentity({
 			agentId,
 			channel,
@@ -4108,7 +4219,10 @@ var SessionManager = class {
 		}) : void 0;
 		const requestedSessionId = readOptionalString$8(sessionId);
 		const created = await this.createSession({
-			sourceSessionMetadata: {},
+			contextInheritance,
+			parentSessionId: parentSessionId ?? void 0,
+			sourceSessionId: sourceSessionId ?? void 0,
+			sourceSessionMetadata,
 			sessionId: requestedSessionId ?? peerIdentity?.sessionId,
 			task: task ?? "Session",
 			agentId,
@@ -4124,16 +4238,16 @@ var SessionManager = class {
 		});
 		return {
 			sessionId: created.sessionId,
-			agentId,
+			agentId: created.agentId,
 			agentRuntimeId,
 			metadata: structuredClone(created.metadata ?? {}),
-			model,
-			projectRoot,
+			model: model ?? readOptionalMetadataString(created.metadata?.model) ?? readOptionalMetadataString(created.metadata?.preferred_model),
+			projectRoot: projectRoot ?? readProjectRoot(created.metadata),
 			workingDir: this.workingDirResolver.resolve({
-				agentId,
+				agentId: created.agentId,
 				metadata: created.metadata
 			}),
-			thinkingEffort: thinkingEffort ?? null
+			thinkingEffort: thinkingEffort ?? readThinkingEffort(created.metadata)
 		};
 	};
 	getOrCreateAgentRunSession = async (params) => {
@@ -7151,7 +7265,7 @@ var SessionRequestManager = class {
 		this.options = options;
 	}
 	spawnSessionAndRequest = async (params) => {
-		const { sourceSessionId, sourceToolCallId, updateToolCallResult, sourceSessionMetadata, metadataOverrides, 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 } = params;
 		const requestId = randomUUID();
 		const createdSession = await this.options.sessionManager.createSession({
 			sourceSessionId,
@@ -7160,6 +7274,7 @@ var SessionRequestManager = class {
 			title,
 			sourceSessionMetadata,
 			...metadataOverrides ? { metadataOverrides } : {},
+			contextInheritance,
 			agentId,
 			model,
 			runtime,
@@ -9534,6 +9649,11 @@ function readSpawnNotify(value) {
 	if (notifyMode === "none" || notifyMode === "final_reply") return notifyMode;
 	throw new Error("notify must be \"none\" or \"final_reply\".");
 }
+function readInheritContext(value) {
+	if (typeof value === "undefined") return false;
+	if (typeof value === "boolean") return value;
+	throw new Error("inheritContext must be a boolean.");
+}
 var SessionSpawnTool = class {
 	name = "sessions_spawn";
 	description = "Create a new session. Use scope=\"child\" to create a child session of the current flow, and add notify when the new session should start immediately.";
@@ -9569,6 +9689,10 @@ var SessionSpawnTool = class {
 				type: "string",
 				enum: ["none", "final_reply"],
 				description: "Optional. Starts the new session immediately. Use \"final_reply\" to continue this session after the new session reaches its final reply, or \"none\" to let it run independently."
+			},
+			inheritContext: {
+				type: "boolean",
+				description: "Child sessions only. When true, the child starts with parent context inherited up to this tool call."
 			}
 		},
 		required: ["task"],
@@ -9587,11 +9711,14 @@ var SessionSpawnTool = class {
 		this.handoffDepth = params.handoffDepth ?? 0;
 	};
 	execute = async (args, context) => {
-		const { agentId: rawAgentId, model: rawModel, notify: rawNotify, runtime: rawRuntime, scope: rawScope, task: rawTask, title: rawTitle } = normalizeToolParams(args);
+		const { agentId: rawAgentId, model: rawModel, notify: rawNotify, runtime: rawRuntime, scope: rawScope, task: rawTask, title: rawTitle, inheritContext: rawInheritContext } = normalizeToolParams(args);
 		const task = readRequiredString$1(rawTask, "task");
 		const scope = readSpawnScope(rawScope);
 		const notify = readSpawnNotify(rawNotify);
+		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;
 		if (notify) return this.sessionRequestManager.spawnSessionAndRequest({
 			sourceSessionId: this.sourceSessionId,
 			sourceToolCallId: context?.toolCallId,
@@ -9602,6 +9729,7 @@ var SessionSpawnTool = class {
 			agentId: readOptionalString$2(rawAgentId),
 			model: readOptionalString$2(rawModel),
 			runtime: readOptionalString$2(rawRuntime),
+			contextInheritance,
 			handoffDepth: this.handoffDepth,
 			parentSessionId,
 			notify
@@ -9614,6 +9742,7 @@ var SessionSpawnTool = class {
 			agentId: readOptionalString$2(rawAgentId),
 			model: readOptionalString$2(rawModel),
 			runtime: readOptionalString$2(rawRuntime),
+			contextInheritance,
 			parentSessionId
 		});
 		return {