@cydm/magic-shell-agent-node 0.1.18 → 0.1.20

package/dist/primary-pie-extension/magic-shell-agent/index.js

@@ -0,0 +1,1019 @@
+import { execFile } from "node:child_process";
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import os from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+import { fileURLToPath } from "node:url";
+
+const execFileAsync = promisify(execFile);
+const pieRequireBase = (() => {
+	try {
+		if (process.argv[1]) {
+			return fs.realpathSync(process.argv[1]);
+		}
+	} catch {
+		// fall through
+	}
+	return import.meta.url;
+})();
+const require = createRequire(pieRequireBase);
+const { Type } = require("@sinclair/typebox");
+const sessionsDir = path.join(os.homedir(), ".pie", "sessions");
+const inboxPollers = new Map();
+const activeRequests = new Map();
+const delegatedTurnState = new Map();
+
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function appendDebugLog(message) {
+	try {
+		fs.appendFileSync("/tmp/magic-shell-agent-extension.log", `${new Date().toISOString()} ${message}\n`);
+	} catch {
+		// ignore debug logging failures
+	}
+}
+
+function safeCwd(ctx) {
+	try {
+		return ctx?.cwd || process.cwd();
+	} catch {
+		return process.cwd();
+	}
+}
+
+function tryDirectory(candidate) {
+	try {
+		if (candidate && fs.existsSync(candidate) && fs.statSync(candidate).isDirectory()) {
+			return candidate;
+		}
+	} catch {
+		// ignore bad candidate
+	}
+	return null;
+}
+
+function looksLikeStandaloneRepo(directory) {
+	try {
+		if (!directory) return false;
+		return fs.existsSync(path.join(directory, ".git")) || fs.existsSync(path.join(directory, "package.json"));
+	} catch {
+		return false;
+	}
+}
+
+function findNamedDirectoryNear(directoryName, startCwd) {
+	if (!directoryName || !startCwd) return null;
+	let current = startCwd;
+	while (current && current !== path.dirname(current)) {
+		const directChild = tryDirectory(path.join(current, directoryName));
+		const siblingUnderParent = tryDirectory(path.join(path.dirname(current), directoryName));
+		if (directChild && siblingUnderParent) {
+			if (looksLikeStandaloneRepo(siblingUnderParent) && !looksLikeStandaloneRepo(directChild)) {
+				return siblingUnderParent;
+			}
+			return directChild;
+		}
+		if (siblingUnderParent) return siblingUnderParent;
+		if (directChild) return directChild;
+
+		current = path.dirname(current);
+	}
+	return null;
+}
+
+function findMagicShellRoot(startCwd) {
+	let current = startCwd;
+	while (current && current !== path.dirname(current)) {
+		const packageJsonPath = path.join(current, "package.json");
+		const cliPath = path.join(current, "packages", "cli", "dist", "cli.js");
+		if (fs.existsSync(packageJsonPath) && fs.existsSync(cliPath)) {
+			return current;
+		}
+		current = path.dirname(current);
+	}
+	return startCwd;
+}
+
+function getExtensionRuntimeDir() {
+	try {
+		return path.dirname(fileURLToPath(import.meta.url));
+	} catch {
+		return process.cwd();
+	}
+}
+
+function findExistingFile(candidates) {
+	for (const candidate of candidates) {
+		if (!candidate) continue;
+		try {
+			if (fs.existsSync(candidate)) {
+				return candidate;
+			}
+		} catch {
+			// ignore invalid candidate
+		}
+	}
+	return null;
+}
+
+function getCliPath(cwd) {
+	const runtimeDir = getExtensionRuntimeDir();
+	const siblingPackagedCli = path.resolve(runtimeDir, "../../../../../magic-shell/dist/cli.js");
+	const nestedPackagedCli = path.resolve(runtimeDir, "../../../../../../dist/cli.js");
+	const devCli = path.resolve(runtimeDir, "../../../../cli/dist/cli.js");
+	const envCli = process.env.MAGIC_SHELL_CLI_PATH
+		? path.resolve(process.env.MAGIC_SHELL_CLI_PATH)
+		: null;
+	const discovered = findExistingFile([
+		envCli,
+		siblingPackagedCli,
+		nestedPackagedCli,
+		devCli,
+	]);
+	if (discovered) {
+		return discovered;
+	}
+
+	const root = findMagicShellRoot(cwd);
+	return path.join(root, "packages", "cli", "dist", "cli.js");
+}
+
+function getCliWorkingDirectory(cwd, cliPath) {
+	if (!cliPath) {
+		return cwd || process.cwd();
+	}
+	if (process.env.MAGIC_SHELL_CLI_PATH && fs.existsSync(process.env.MAGIC_SHELL_CLI_PATH)) {
+		return cwd || process.cwd();
+	}
+	if (cliPath.includes(`${path.sep}dist${path.sep}cli.js`)) {
+		const packageRoot = path.resolve(path.dirname(cliPath), "..");
+		if (fs.existsSync(path.join(packageRoot, "package.json"))) {
+			return packageRoot;
+		}
+	}
+	return findMagicShellRoot(cwd);
+}
+
+function inferTargetDirectory(task, cwd) {
+	const text = String(task || "").trim();
+	if (!text) return null;
+	const lowered = text.toLowerCase();
+
+	const homePathMatches = text.match(/~\/[^\s"'`，。；、]+/g) || [];
+	for (const candidate of homePathMatches) {
+		const expanded = path.join(os.homedir(), candidate.slice(2));
+		try {
+			if (fs.existsSync(expanded) && fs.statSync(expanded).isDirectory()) {
+				return expanded;
+			}
+		} catch {
+			// ignore bad candidate
+		}
+	}
+
+	if (
+		text === "~"
+		|| lowered.includes("home directory")
+		|| lowered.includes("home dir")
+		|| text.includes("家目录")
+		|| text.includes("主目录")
+	) {
+		return os.homedir();
+	}
+
+	const absolutePathMatches = text.match(/\/[^\s"'`，。；、]+/g) || [];
+	for (const candidate of absolutePathMatches) {
+		try {
+			if (fs.existsSync(candidate) && fs.statSync(candidate).isDirectory()) {
+				return candidate;
+			}
+		} catch {
+			// ignore bad candidate
+		}
+	}
+
+	const locatedUnderMatch = text.match(/([A-Za-z0-9._-]+)\s*目录在\s*([A-Za-z0-9._-]+)\s*下面/u);
+	if (locatedUnderMatch) {
+		const childName = locatedUnderMatch[1];
+		const parentName = locatedUnderMatch[2];
+		let current = cwd;
+		while (current && current !== path.dirname(current)) {
+			if (path.basename(current) === parentName) {
+				const candidate = tryDirectory(path.join(current, childName));
+				if (candidate) return candidate;
+			}
+			const parentSibling = tryDirectory(path.join(path.dirname(current), parentName, childName));
+			if (parentSibling) return parentSibling;
+			current = path.dirname(current);
+		}
+	}
+
+	const namedDirectoryMatch = text.match(/(?:去|到|在|进|进入|spawn.*?到|在)\s*([A-Za-z0-9._-]+)\s*目录/u)
+		|| text.match(/\b([A-Za-z0-9._-]+)\s+directory\b/i)
+		|| text.match(/\b([A-Za-z0-9._-]+)\b(?=.*\b(?:repo|repository|目录|folder|directory)\b)/i);
+	if (namedDirectoryMatch?.[1]) {
+		const nearby = findNamedDirectoryNear(namedDirectoryMatch[1], cwd);
+		if (nearby) {
+			return nearby;
+		}
+	}
+
+	return null;
+}
+
+function normalizeDelegatedCwd(rawCwd, baseCwd) {
+	const value = String(rawCwd || "").trim();
+	if (!value) return null;
+
+	if (value === "~") {
+		return os.homedir();
+	}
+	if (value.startsWith("~/")) {
+		return tryDirectory(path.join(os.homedir(), value.slice(2)));
+	}
+	if (path.isAbsolute(value)) {
+		const absolute = tryDirectory(value);
+		if (!absolute) {
+			return null;
+		}
+		if (!looksLikeStandaloneRepo(absolute)) {
+			let current = baseCwd || process.cwd();
+			while (current && current !== path.dirname(current)) {
+				const sibling = tryDirectory(path.join(path.dirname(current), path.basename(absolute)));
+				if (sibling && sibling !== absolute && looksLikeStandaloneRepo(sibling)) {
+					return sibling;
+				}
+				current = path.dirname(current);
+			}
+		}
+		return absolute;
+	}
+	const resolved = path.resolve(baseCwd || process.cwd(), value);
+	if (tryDirectory(resolved)) {
+		if (!looksLikeStandaloneRepo(resolved)) {
+			let current = baseCwd || process.cwd();
+			while (current && current !== path.dirname(current)) {
+				const sibling = tryDirectory(path.join(path.dirname(current), path.basename(resolved)));
+				if (sibling && sibling !== resolved && looksLikeStandaloneRepo(sibling)) {
+					return sibling;
+				}
+				current = path.dirname(current);
+			}
+		}
+		return resolved;
+	}
+	const basename = path.basename(value);
+	if (basename) {
+		const nearby = findNamedDirectoryNear(basename, baseCwd || process.cwd());
+		if (nearby) {
+			return nearby;
+		}
+	}
+	return null;
+}
+
+function inferWorkerName(task) {
+	const text = String(task || "").trim();
+	if (!text) return null;
+	const match = text.match(/(?:叫|名叫|叫做|名字是|named|call(?:ed)?)(?:\s*[:：]?\s*)([A-Za-z0-9_\-\u4e00-\u9fa5]{2,20})/iu);
+	if (!match?.[1]) return null;
+	return match[1].trim();
+}
+
+function inferMentionedWorkerName(task, snapshot) {
+	const text = String(task || "").trim();
+	if (!text) return null;
+	const workers = Array.isArray(snapshot?.workers) ? snapshot.workers : [];
+	const liveNames = workers
+		.filter((worker) => worker?.status !== "stopped" && worker?.status !== "failed" && worker?.displayName)
+		.map((worker) => String(worker.displayName).trim())
+		.filter(Boolean)
+		.sort((a, b) => b.length - a.length);
+	for (const name of liveNames) {
+		if (text.includes(name)) {
+			return name;
+		}
+	}
+	return null;
+}
+
+function buildDelegationCacheKey({ sessionId, workerName, cwd, mode, task }) {
+	return JSON.stringify({
+		sessionId: sessionId || null,
+		workerName: workerName || null,
+		cwd: cwd || null,
+		mode: mode || "steer",
+		task: normalizeDelegatedText(task || ""),
+	});
+}
+
+function getCurrentSessionId() {
+	const args = process.argv.slice(2);
+	const flagIndex = args.indexOf("--session-id");
+	return flagIndex >= 0 && args[flagIndex + 1] ? args[flagIndex + 1] : null;
+}
+
+function getInboxPath(sessionId) {
+	return path.join(sessionsDir, `${sessionId}.magic-shell-inbox.json`);
+}
+
+function getStatePath(sessionId) {
+	return path.join(sessionsDir, `${sessionId}.magic-shell-state.json`);
+}
+
+function writeSessionControlState(sessionId, patch) {
+	fs.mkdirSync(sessionsDir, { recursive: true });
+	const statePath = getStatePath(sessionId);
+	let current = {};
+	if (fs.existsSync(statePath)) {
+		try {
+			current = JSON.parse(fs.readFileSync(statePath, "utf8"));
+		} catch {
+			current = {};
+		}
+	}
+	const next = {
+		sessionId,
+		updatedAt: Date.now(),
+		...current,
+		...patch,
+	};
+	fs.writeFileSync(statePath, JSON.stringify(next, null, 2));
+}
+
+function extractAssistantText(message) {
+	if (!message || !Array.isArray(message.content)) {
+		return "";
+	}
+	return message.content
+		.filter((item) => item?.type === "text" && typeof item.text === "string")
+		.map((item) => item.text.trim())
+		.filter(Boolean)
+		.join("\n\n")
+		.trim();
+}
+
+function startInboxPoller(ctx, sessionId) {
+	if (!sessionId || inboxPollers.has(sessionId)) {
+		return;
+	}
+	fs.mkdirSync(sessionsDir, { recursive: true });
+	const tick = () => {
+		if (!ctx.isIdle()) {
+			return;
+		}
+		const inboxPath = getInboxPath(sessionId);
+		if (!fs.existsSync(inboxPath)) {
+			return;
+		}
+
+		try {
+			const command = JSON.parse(fs.readFileSync(inboxPath, "utf8"));
+			if (!command?.requestId || !command?.message) {
+				return;
+			}
+			const current = activeRequests.get(sessionId);
+			if (current?.requestId === command.requestId) {
+				return;
+			}
+			activeRequests.set(sessionId, command);
+			writeSessionControlState(sessionId, {
+				activeRequestId: command.requestId,
+				status: "busy",
+				lastError: null,
+			});
+			fs.unlinkSync(inboxPath);
+			ctx.sendUserMessage(command.message);
+		} catch (error) {
+			writeSessionControlState(sessionId, {
+				lastError: error instanceof Error ? error.message : String(error),
+			});
+		}
+	};
+	const interval = setInterval(tick, 250);
+	inboxPollers.set(sessionId, interval);
+	writeSessionControlState(sessionId, {
+		activeRequestId: null,
+		status: "idle",
+	});
+}
+
+async function runMagicShellCli(cwd, args) {
+	const cliPath = getCliPath(cwd);
+	if (!fs.existsSync(cliPath)) {
+		throw new Error(`Magic Shell CLI is unavailable: ${cliPath}. Start via magic-shell or set MAGIC_SHELL_CLI_PATH.`);
+	}
+
+	const { stdout, stderr } = await execFileAsync(process.execPath, [cliPath, ...args], {
+		cwd: getCliWorkingDirectory(cwd, cliPath),
+		env: {
+			...process.env,
+			MAGIC_SHELL_CLI_PATH: cliPath,
+		},
+		maxBuffer: 1024 * 1024 * 4,
+	});
+	const output = String(stdout || "").trim();
+	if (!output) {
+		if (stderr?.trim()) {
+			throw new Error(stderr.trim());
+		}
+		throw new Error("Magic Shell CLI returned empty output");
+	}
+
+	try {
+		return JSON.parse(output);
+	} catch (error) {
+		throw new Error(`Magic Shell CLI returned invalid JSON: ${output.slice(0, 240)}`);
+	}
+}
+
+function pickWorker(snapshot, preferredSessionId, pluginName, desiredCwd, workerName, { allowExactReuseAcrossCwd = false } = {}) {
+	const workers = Array.isArray(snapshot?.workers) ? snapshot.workers : [];
+	const pluginMatches = (worker) => !pluginName || !worker?.agentType || worker.agentType === pluginName;
+	const cwdMatches = (worker) => !desiredCwd || !worker?.cwd || path.resolve(worker.cwd) === path.resolve(desiredCwd);
+	if (preferredSessionId) {
+		const exact = workers.find((worker) =>
+			worker.sessionId === preferredSessionId
+			&& pluginMatches(worker)
+			&& worker.status !== "stopped"
+			&& worker.status !== "failed",
+		);
+		if (exact) {
+			if (allowExactReuseAcrossCwd || cwdMatches(exact)) {
+				return exact;
+			}
+			return null;
+		}
+	}
+	if (workerName) {
+		const named = workers.find((worker) =>
+			worker.displayName === workerName
+			&& pluginMatches(worker)
+			&& worker.status !== "stopped"
+			&& worker.status !== "failed",
+		);
+		if (named) {
+			if (allowExactReuseAcrossCwd || cwdMatches(named)) {
+				return named;
+			}
+			return null;
+		}
+	}
+	return null;
+}
+
+function shouldPreferExistingWorker(task, preferredSessionId, workerName) {
+	if (preferredSessionId || workerName) {
+		return true;
+	}
+	const text = String(task || "");
+	return text.includes("继续")
+		|| text.includes("接着")
+		|| text.includes("再")
+		|| text.includes("让他")
+		|| text.includes("让她")
+		|| text.toLowerCase().includes("follow up");
+}
+
+function shouldTreatAsSpawnRequest(task) {
+	const text = String(task || "").trim();
+	if (!text) return false;
+	const lowered = text.toLowerCase();
+	return text.includes("spawn")
+		|| text.includes("启动")
+		|| text.includes("创建")
+		|| text.includes("新建")
+		|| lowered.includes("create worker")
+		|| lowered.includes("start worker");
+}
+
+function resolveDelegatedCwd(rawCwd, task, baseCwd, existingWorker = null) {
+	const normalized = normalizeDelegatedCwd(rawCwd, baseCwd);
+	if (normalized) {
+		return normalized;
+	}
+	if (existingWorker?.cwd && shouldPreferExistingWorker(task, existingWorker.sessionId, existingWorker.displayName)) {
+		return existingWorker.cwd;
+	}
+	return inferTargetDirectory(task, baseCwd);
+}
+
+function buildFirstTurnMessage(task) {
+	return `${task}
+
+Work in your own session. Complete the task and return the actual findings in this same turn. If you inspect files or run commands, report the concrete result directly instead of restating the task. If the task cannot be completed, explain the real failure briefly.`;
+}
+
+function normalizeDelegatedText(value) {
+	return String(value || "").replace(/\s+/g, " ").trim();
+}
+
+function looksLikeDelegatedNoise(value) {
+	const normalized = normalizeDelegatedText(value).toLowerCase();
+	if (!normalized) return true;
+	return normalized.includes("queued message for")
+		|| normalized.includes("message_update")
+		|| normalized.includes("looks ready for input")
+		|| normalized.includes("work in your own session")
+		|| normalized.includes("reply to the primary agent now")
+		|| normalized.startsWith("the user asked me")
+		|| normalized.startsWith("用户要求我");
+}
+
+function hasUsableDelegatedText(value) {
+	const normalized = normalizeDelegatedText(value);
+	return !!normalized && !looksLikeDelegatedNoise(normalized);
+}
+
+function isUsableDelegatedTurn(result) {
+	return hasUsableDelegatedText(result?.message) || hasUsableDelegatedText(result?.summary);
+}
+
+async function readDelegatedSessionResult(cwd, sessionId) {
+	const [messageResult, summaryResult] = await Promise.all([
+		runMagicShellCli(cwd, ["session-message", "--session", sessionId, "--json"]),
+		runMagicShellCli(cwd, ["session-summary", "--session", sessionId, "--json"]),
+	]);
+	return {
+		sessionId,
+		message: messageResult?.message || null,
+		summary: summaryResult?.summary || null,
+	};
+}
+
+async function waitForDelegatedSessionResult(cwd, sessionId, timeoutMs = 20000) {
+	const deadline = Date.now() + timeoutMs;
+	while (Date.now() <= deadline) {
+		const snapshot = await readDelegatedSessionResult(cwd, sessionId);
+		if (isUsableDelegatedTurn(snapshot)) {
+			return snapshot;
+		}
+		await sleep(750);
+	}
+	return null;
+}
+
+async function waitForWorkerSession(cwd, sessionId, timeoutMs = 12000) {
+	const deadline = Date.now() + timeoutMs;
+	while (Date.now() <= deadline) {
+		try {
+			const workersResult = await runMagicShellCli(cwd, ["workers", "--json"]);
+			const workers = Array.isArray(workersResult) ? workersResult : [];
+			const worker = workers.find((entry) => entry?.sessionId === sessionId);
+			if (worker && worker.status !== "stopped" && worker.status !== "failed") {
+				return worker;
+			}
+		} catch {
+			// ignore transient lookup failures and keep waiting
+		}
+		await sleep(500);
+	}
+	return null;
+}
+
+function formatDelegatedResult(result) {
+	const parts = [];
+	if (hasUsableDelegatedText(result.message)) {
+		parts.push(`Worker reply:\n${result.message}`);
+	}
+	if (hasUsableDelegatedText(result.summary) && result.summary !== result.message) {
+		parts.push(`Worker summary:\n${result.summary}`);
+	}
+	if (!parts.length) {
+		parts.push("The worker completed a turn, but it did not produce a visible assistant reply.");
+	}
+	return parts.join("\n\n");
+}
+
+function taskNeedsExplicitPathResolution(task) {
+	const text = String(task || "").trim();
+	if (!text) return false;
+	const lowered = text.toLowerCase();
+	return text.includes("目录")
+		|| text.includes("路径")
+		|| text.includes("文件夹")
+		|| text.includes("在")
+		|| text.includes("~/")
+		|| lowered.includes("directory")
+		|| lowered.includes("folder")
+		|| lowered.includes("path");
+}
+
+function isSpawnOnlyDelegation(task) {
+	const text = String(task || "").trim();
+	if (!text) return false;
+	const lowered = text.toLowerCase();
+	const asksToSpawn = text.includes("spawn")
+		|| text.includes("启动")
+		|| text.includes("创建")
+		|| text.includes("新建")
+		|| lowered.includes("create worker")
+		|| lowered.includes("start worker");
+	const alsoRequestsWork = text.includes("看看")
+		|| text.includes("查看")
+		|| text.includes("检查")
+		|| text.includes("读")
+		|| text.includes("统计")
+		|| text.includes("运行")
+		|| text.includes("执行")
+		|| lowered.includes("inspect")
+		|| lowered.includes("check")
+		|| lowered.includes("read")
+		|| lowered.includes("list")
+		|| lowered.includes("summarize")
+		|| lowered.includes("run ");
+	return asksToSpawn && !alsoRequestsWork;
+}
+
+function buildDelegatedFailureText({ phase, recoverable, reason, message, cwd, task }) {
+	const lines = [
+		`Delegated worker turn failed.`,
+		`phase: ${phase}`,
+		`recoverable: ${recoverable ? "yes" : "no"}`,
+		`reason: ${reason}`,
+		message,
+	];
+	if (cwd) {
+		lines.push(`cwd: ${cwd}`);
+	}
+	if (task) {
+		lines.push(`task: ${task}`);
+	}
+	lines.push("You should continue reasoning from this tool result instead of stopping. If recoverable is yes, either refine the target path or try a new worker turn with corrected arguments.");
+	return lines.filter(Boolean).join("\n");
+}
+
+function buildDelegatedFailureResult({ phase, recoverable, reason, message, cwd, task, sessionId = null, spawned = false, pluginName = "pie", mode = "steer" }) {
+	return {
+		content: [{
+			type: "text",
+			text: buildDelegatedFailureText({ phase, recoverable, reason, message, cwd, task }),
+		}],
+		details: {
+			ok: false,
+			phase,
+			recoverable,
+			reason,
+			message,
+			cwd: cwd || null,
+			task: task || null,
+			sessionId,
+			spawned,
+			pluginName,
+			mode,
+		},
+		isError: false,
+	};
+}
+
+function clearDelegatedTurnProgress(sessionId) {
+	if (!sessionId) return;
+	const current = delegatedTurnState.get(sessionId) || { cachedResults: {} };
+	delegatedTurnState.set(sessionId, {
+		inProgress: false,
+		cachedResults: current.cachedResults || {},
+	});
+}
+
+export default function magicShellAgentExtension(ctx) {
+	ctx.log("Magic Shell delegated-turn extension loaded");
+	const currentSessionId = getCurrentSessionId();
+	const isPrimarySession = !!currentSessionId && currentSessionId.startsWith("primary-");
+	appendDebugLog(`load session=${currentSessionId || "unknown"} cwd=${safeCwd(ctx)}`);
+
+	ctx.on("tool:call", async (event) => {
+		if (!isPrimarySession) {
+			return undefined;
+		}
+		if (event.toolName === "magic_shell_delegate_worker_turn") {
+			return undefined;
+		}
+		appendDebugLog(`blocked tool=${event.toolName} session=${currentSessionId || "unknown"}`);
+		return {
+			block: true,
+			reason: "The protected primary agent must use magic_shell_delegate_worker_turn for execution tasks instead of calling other tools directly.",
+		};
+	});
+
+	if (currentSessionId) {
+		startInboxPoller(ctx, currentSessionId);
+		if (isPrimarySession) {
+			ctx.on("agent:start", async () => {
+				appendDebugLog(`agent:start session=${currentSessionId} setActiveTools=magic_shell_delegate_worker_turn`);
+				ctx.setActiveTools(["magic_shell_delegate_worker_turn"]);
+			});
+		}
+		ctx.on("turn:start", async () => {
+			const active = activeRequests.get(currentSessionId);
+			delegatedTurnState.set(currentSessionId, {
+				inProgress: false,
+				cachedResults: {},
+			});
+			writeSessionControlState(currentSessionId, {
+				activeRequestId: active?.requestId || null,
+				status: "busy",
+			});
+		});
+		ctx.on("turn:end", async (event) => {
+			const active = activeRequests.get(currentSessionId);
+			writeSessionControlState(currentSessionId, {
+				activeRequestId: null,
+				lastCompletedRequestId: active?.requestId || null,
+				lastTurnIndex: typeof event?.turnIndex === "number" ? event.turnIndex : null,
+				lastAssistantText: extractAssistantText(event?.message) || null,
+				lastError: null,
+				status: "idle",
+			});
+			delegatedTurnState.delete(currentSessionId);
+			activeRequests.delete(currentSessionId);
+		});
+		ctx.on("agent:end", async () => {
+			delegatedTurnState.delete(currentSessionId);
+			writeSessionControlState(currentSessionId, {
+				status: "idle",
+			});
+		});
+	}
+
+	if (!isPrimarySession) {
+		return;
+	}
+
+	ctx.registerTool({
+		name: "magic_shell_delegate_worker_turn",
+		description: `Delegate one worker turn through Magic Shell and return the result in the same conversation turn.
+
+Use this when the user wants the primary agent to inspect files, run commands, continue work, or ask another session to do something concrete.`,
+		parameters: Type.Object({
+			task: Type.String({
+				description: "The concrete task or instruction for the worker session.",
+			}),
+			sessionId: Type.Optional(Type.String({
+				description: "Preferred worker session ID to reuse when continuing an existing task.",
+			})),
+			cwd: Type.Optional(Type.String({
+				description: "Optional working directory for a new worker session.",
+			})),
+			workerName: Type.Optional(Type.String({
+				description: "Optional display name for the worker session.",
+			})),
+			pluginName: Type.Optional(Type.String({
+				description: "Worker plugin name to use when spawning. Defaults to pie.",
+			})),
+			mode: Type.Optional(Type.Union([
+				Type.Literal("steer"),
+				Type.Literal("follow_up"),
+			], {
+				description: "Delegation mode. Use steer for a fresh task and follow_up for a continuation.",
+			})),
+		}, {
+			additionalProperties: false,
+		}),
+		category: "agent",
+		async execute(args, context) {
+			const turnState = currentSessionId
+				? (delegatedTurnState.get(currentSessionId) || { inProgress: false, cachedResults: {} })
+				: { inProgress: false, cachedResults: {} };
+			const pluginName = args.pluginName || "pie";
+			const mode = args.mode === "follow_up" ? "follow_up" : "steer";
+			let runtimeSnapshot;
+			try {
+				runtimeSnapshot = await runMagicShellCli(context.cwd, ["status", "--json"]);
+			} catch (error) {
+				clearDelegatedTurnProgress(currentSessionId);
+				return buildDelegatedFailureResult({
+					phase: "runtime_snapshot",
+					recoverable: true,
+					reason: "runtime_unavailable",
+					message: error instanceof Error ? error.message : String(error),
+					cwd: null,
+					task: args.task,
+					pluginName,
+					mode,
+				});
+			}
+			const workerName = args.workerName
+				|| inferWorkerName(args.task)
+				|| inferMentionedWorkerName(args.task, runtimeSnapshot);
+			let worker = pickWorker(runtimeSnapshot, args.sessionId, pluginName, null, workerName, {
+				allowExactReuseAcrossCwd: true,
+			});
+			const delegatedCwd = resolveDelegatedCwd(args.cwd, args.task, context.cwd, worker);
+			const cacheKey = buildDelegationCacheKey({
+				sessionId: args.sessionId,
+				workerName,
+				cwd: delegatedCwd,
+				mode,
+				task: args.task,
+			});
+			const cachedResult = currentSessionId ? turnState.cachedResults?.[cacheKey] : null;
+			if (currentSessionId && cachedResult) {
+				appendDebugLog(`tool reuse cached session=${currentSessionId} key=${cacheKey}`);
+				return {
+					...cachedResult,
+					details: {
+						...(cachedResult.details || {}),
+						reusedWithinTurn: true,
+					},
+				};
+			}
+
+			appendDebugLog(`tool execute session=${currentSessionId || "unknown"} task=${String(args.task || "").slice(0, 120)}`);
+			appendDebugLog(`tool plan session=${currentSessionId || "unknown"} cwd=${delegatedCwd || "(default)"} mode=${mode}`);
+			if (currentSessionId) {
+				delegatedTurnState.set(currentSessionId, {
+					...turnState,
+					inProgress: true,
+				});
+			}
+			context.reportProgress({ message: "Checking runtime" });
+
+			if (!delegatedCwd && taskNeedsExplicitPathResolution(args.task)) {
+				clearDelegatedTurnProgress(currentSessionId);
+				return buildDelegatedFailureResult({
+					phase: "resolve_path",
+					recoverable: true,
+					reason: "target_path_unresolved",
+					message: "Could not resolve the target directory from the task description. First determine the concrete path, then call the worker tool again.",
+					cwd: null,
+					task: args.task,
+					pluginName,
+					mode,
+				});
+			}
+
+			worker = pickWorker(runtimeSnapshot, args.sessionId, pluginName, delegatedCwd, workerName, {
+				allowExactReuseAcrossCwd: !shouldTreatAsSpawnRequest(args.task),
+			}) || worker;
+			let spawned = false;
+
+			if (!worker) {
+				context.reportProgress({ message: "Spawning worker" });
+				let spawnResult;
+				try {
+					spawnResult = await runMagicShellCli(context.cwd, [
+						"spawn",
+						"--plugin", pluginName,
+						"--task", args.task,
+						...(workerName ? ["--name", workerName] : []),
+						...(delegatedCwd ? ["--cwd", delegatedCwd] : []),
+						"--json",
+					]);
+				} catch (error) {
+					clearDelegatedTurnProgress(currentSessionId);
+					return buildDelegatedFailureResult({
+						phase: "spawn_worker",
+						recoverable: true,
+						reason: "spawn_failed",
+						message: error instanceof Error ? error.message : String(error),
+						cwd: delegatedCwd,
+						task: args.task,
+						pluginName,
+						mode,
+						spawned: false,
+					});
+				}
+				const sessionId = spawnResult?.sessionId;
+				if (!sessionId) {
+					clearDelegatedTurnProgress(currentSessionId);
+					return buildDelegatedFailureResult({
+						phase: "spawn_worker",
+						recoverable: true,
+						reason: "missing_session_id",
+						message: "Magic Shell did not return a worker session ID after spawn.",
+						cwd: delegatedCwd,
+						task: args.task,
+						pluginName,
+						mode,
+						spawned: false,
+					});
+				}
+				spawned = true;
+				worker = { sessionId, agentType: pluginName };
+				const readyWorker = await waitForWorkerSession(context.cwd, sessionId, 12000);
+				if (readyWorker) {
+					worker = readyWorker;
+				} else {
+					await sleep(1200);
+				}
+			}
+
+			const sessionId = worker.sessionId;
+			if (isSpawnOnlyDelegation(args.task)) {
+				const response = {
+					content: [{
+						type: "text",
+						text: [
+							`Spawned worker session ${sessionId}.`,
+							workerName ? `Worker name: ${workerName}` : null,
+							delegatedCwd ? `Working directory: ${delegatedCwd}` : null,
+							"Worker is ready for follow-up tasks.",
+						].filter(Boolean).join("\n"),
+					}],
+					details: {
+						ok: true,
+						sessionId,
+						spawned,
+						pluginName,
+						displayName: workerName || null,
+						cwd: delegatedCwd || null,
+						mode,
+						spawnOnly: true,
+					},
+					isError: false,
+				};
+				if (currentSessionId) {
+					delegatedTurnState.set(currentSessionId, {
+						inProgress: false,
+						cachedResults: {
+							...(turnState.cachedResults || {}),
+							[cacheKey]: response,
+						},
+					});
+				}
+				return response;
+			}
+			context.reportProgress({ message: `Delegating turn to ${sessionId.slice(0, 8)}...` });
+
+			const attemptArgs = [
+				"session-turn",
+				"--session", sessionId,
+				"--mode", mode,
+				"--data",
+			];
+			let first;
+			try {
+				first = await runMagicShellCli(context.cwd, [
+					...attemptArgs,
+					buildFirstTurnMessage(args.task),
+					"--timeout-ms", "35000",
+					"--poll-interval-ms", "250",
+					"--json",
+				]);
+			} catch (error) {
+				clearDelegatedTurnProgress(currentSessionId);
+				return buildDelegatedFailureResult({
+					phase: "delegate_turn",
+					recoverable: true,
+					reason: "session_turn_failed",
+					message: error instanceof Error ? error.message : String(error),
+					cwd: delegatedCwd,
+					task: args.task,
+					pluginName,
+					mode,
+					sessionId,
+					spawned,
+				});
+			}
+
+			let finalTurn = first;
+			if (!isUsableDelegatedTurn(finalTurn)) {
+				context.reportProgress({ message: "Waiting for the worker to settle the delegated turn" });
+				const settled = await waitForDelegatedSessionResult(context.cwd, sessionId, 12000);
+				if (settled) {
+					finalTurn = {
+						...finalTurn,
+						...settled,
+						changed: true,
+						timedOut: false,
+					};
+				}
+			}
+
+			const text = [
+				`Delegated to worker session ${sessionId}.`,
+				formatDelegatedResult(finalTurn),
+			].join("\n\n");
+
+			const response = {
+				content: [{ type: "text", text }],
+				details: {
+					ok: true,
+					sessionId,
+					spawned,
+					pluginName,
+					displayName: workerName || null,
+					cwd: delegatedCwd || null,
+					mode,
+					message: finalTurn?.message || null,
+					summary: finalTurn?.summary || null,
+					timedOut: !!finalTurn?.timedOut,
+				},
+				isError: !!finalTurn?.timedOut && !finalTurn?.message && !finalTurn?.summary,
+			};
+			if (currentSessionId) {
+				delegatedTurnState.set(currentSessionId, {
+					inProgress: false,
+					cachedResults: {
+						...(turnState.cachedResults || {}),
+						[cacheKey]: response,
+					},
+				});
+			}
+			return response;
+		},
+	});
+}