@hadooppei/hwcode 0.2.4 → 1.0.0

package/.pi/extensions/cloud.ts

@@ -1,629 +0,0 @@
-import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { basename, isAbsolute, resolve } from "node:path";
-
-import { Type } from "@earendil-works/pi-ai";
-import { defineTool, type ExtensionAPI, type ExtensionCommandContext, type ExtensionContext, type Theme } from "@earendil-works/pi-coding-agent";
-import { CURSOR_MARKER, Input, type Component, type TUI } from "@earendil-works/pi-tui";
-
-import { checkProviderCli, formatValidationFailure, prepareCloudExecution, validateCloudCredentials, type TemporaryCredentialStore } from "../lib/cloud/adapters.ts";
-import { runProcess, truncateOutput, type ProcessResult } from "../lib/cloud/process.ts";
-import {
-	cloudPromptTemplateSource, expandCloudPromptTemplate, listCloudPromptTemplates, saveCloudPromptTemplate, updateCloudPromptTemplate,
-	type CloudPromptTemplate,
-} from "../lib/cloud/templates.ts";
-import { saveCloudWorkflowTemplate } from "../lib/cloud/template-save.ts";
-import {
-	CLOUD_EXECUTABLES, CLOUD_PROVIDERS, classifyCloudOperation, containsCloudCommand,
-	getCloudProvider, inaccessibleCloudCliMessage, missingCloudCliMessage, redactCredentialValues,
-	type CloudCredentials, type CloudOperation, type CloudVendorId,
-} from "../lib/cloud-providers.ts";
-import {
-	cloudCredentialProfileLabel, cloudVaultExists, createEmptyVault, defaultCloudVaultPath,
-	listCloudCredentialProfiles, readCloudVault, saveCloudCredentialProfile, writeCloudVault,
-	type CloudCredentialProfile,
-} from "../lib/cloud-vault.ts";
-import { canonicalizeWorkspaceRoot } from "../lib/workflow-guard.ts";
-import { modelConfigurationIssue } from "../lib/models/readiness.ts";
-import {
-	WORKFLOW_EXTERNAL_AUDIT_TYPE, WORKFLOW_STATE_TYPE, activeWorkflow, createCloudWorkflowState, updateWorkflowState,
-	type CloudWorkflowDetails, type WorkflowState,
-} from "../lib/workflows/state.ts";
-import { evaluateCommandArgumentsAccess } from "../lib/workspace/access-policy.ts";
-import { getWorkingDirectory } from "../lib/working-directory.ts";
-
-const LEGACY_CLOUD_STATE_TYPE = "hwcode-cloud-state";
-const CLOUD_AUDIT_TYPE = "hwcode-cloud-audit";
-const MAX_FAILED_APPROACHES = 3;
-const MAX_SUCCESSFUL_STEPS = 100;
-const ORCHESTRATION_COMMANDS = new Set(["terraform", "tofu", "pulumi", "kubectl", "helm"]);
-const SENSITIVE_ARGUMENT = /^--?(?:access[-_]?key|secret(?:[-_]?(?:access|key))?|client[-_]?secret|password|credential|token)(?:=|$)/iu;
-
-interface LegacyCloudWorkflowState {
-	version: 1;
-	active: true;
-	root: string;
-	vendor: CloudVendorId;
-	deployCurrentProject: boolean;
-	request: string;
-	allowNonDeleteChanges: boolean;
-	failedApproaches: CloudWorkflowDetails["failedApproaches"];
-	terminalFailure: boolean;
-	activatedAt: string;
-}
-
-class MaskedInput implements Component {
-	private readonly input = new Input();
-	private _focused = true;
-	private readonly tui: TUI;
-	private readonly theme: Theme;
-	private readonly title: string;
-
-	constructor(tui: TUI, theme: Theme, title: string, done: (value: string | undefined) => void) {
-		this.tui = tui;
-		this.theme = theme;
-		this.title = title;
-		this.input.onSubmit = (value) => done(value);
-		this.input.onEscape = () => done(undefined);
-		this.input.focused = true;
-	}
-
-	get focused(): boolean { return this._focused; }
-	set focused(value: boolean) { this._focused = value; this.input.focused = value; }
-	handleInput(data: string): void { this.input.handleInput(data); this.tui.requestRender(); }
-	invalidate(): void { this.input.invalidate(); }
-	render(width: number): string[] {
-		const masked = "•".repeat(Math.min(Array.from(this.input.getValue()).length, Math.max(1, width - 1)));
-		return [this.theme.fg("accent", this.title), `${masked}${CURSOR_MARKER}`, this.theme.fg("dim", "Enter 确认 · Esc 取消 · 输入内容不会显示")];
-	}
-}
-
-function notify(ctx: ExtensionContext, message: string, level: "info" | "warning" | "error" = "info"): void {
-	if (ctx.hasUI) ctx.ui.notify(message, level);
-}
-
-function cloudDetails(state: WorkflowState): CloudWorkflowDetails | undefined {
-	return state.mode === "cloud" ? state.details : undefined;
-}
-
-function formatTemplateTime(value: string): string {
-	const date = new Date(value);
-	if (Number.isNaN(date.valueOf())) return value;
-	const pad = (part: number) => String(part).padStart(2, "0");
-	return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`;
-}
-
-function restoreCloudWorkflow(ctx: ExtensionContext): WorkflowState | undefined {
-	const state = activeWorkflow(ctx.sessionManager.getEntries());
-	return state?.mode === "cloud" && state.details ? state : undefined;
-}
-
-function decodeLegacyCloudState(value: unknown): LegacyCloudWorkflowState | undefined {
-	if (!value || typeof value !== "object") return undefined;
-	const data = value as Record<string, unknown>;
-	if (data.version !== 1 || data.active !== true || typeof data.root !== "string"
-		|| typeof data.vendor !== "string" || !CLOUD_PROVIDERS.some((provider) => provider.id === data.vendor)
-		|| typeof data.deployCurrentProject !== "boolean" || typeof data.request !== "string"
-		|| typeof data.allowNonDeleteChanges !== "boolean" || !Array.isArray(data.failedApproaches)
-		|| typeof data.terminalFailure !== "boolean" || typeof data.activatedAt !== "string") return undefined;
-	return data as unknown as LegacyCloudWorkflowState;
-}
-
-function restoreLegacyCloudWorkflow(ctx: ExtensionContext): WorkflowState | undefined {
-	for (const entry of [...ctx.sessionManager.getEntries()].reverse()) {
-		if (entry.type !== "custom" || entry.customType !== LEGACY_CLOUD_STATE_TYPE) continue;
-		const legacy = decodeLegacyCloudState(entry.data);
-		if (!legacy) return undefined;
-		return {
-			version: 2, status: "active", mode: "cloud", root: legacy.root,
-			phase: legacy.terminalFailure ? "failed" : "connected",
-			activatedAt: legacy.activatedAt, updatedAt: legacy.activatedAt,
-			details: {
-				vendor: legacy.vendor, deployCurrentProject: legacy.deployCurrentProject,
-				request: legacy.request, allowNonDeleteChanges: legacy.allowNonDeleteChanges,
-				failedApproaches: legacy.failedApproaches, successfulSteps: [], terminalFailure: legacy.terminalFailure,
-			},
-		};
-	}
-	return undefined;
-}
-
-function appendWorkflowState(pi: ExtensionAPI, state: WorkflowState): void {
-	pi.appendEntry<WorkflowState>(WORKFLOW_STATE_TYPE, state);
-}
-
-async function secretInput(ctx: ExtensionContext, title: string): Promise<string | undefined> {
-	if (ctx.mode !== "tui") return undefined;
-	return ctx.ui.custom<string | undefined>((tui, theme, _keybindings, done) => new MaskedInput(tui, theme, title, done));
-}
-
-async function unlockVault(ctx: ExtensionCommandContext): Promise<{ password: string; payload: ReturnType<typeof createEmptyVault> } | undefined> {
-	const vaultPath = defaultCloudVaultPath();
-	if (!cloudVaultExists(vaultPath)) {
-		while (true) {
-			const password = await secretInput(ctx, "创建云凭据主密码（至少 8 个字符）");
-			if (password === undefined) return undefined;
-			if (password.length < 8) { notify(ctx, "主密码至少需要 8 个字符。", "warning"); continue; }
-			const confirmation = await secretInput(ctx, "再次输入主密码");
-			if (confirmation === undefined) return undefined;
-			if (confirmation !== password) { notify(ctx, "两次输入的主密码不一致。", "warning"); continue; }
-			return { password, payload: createEmptyVault() };
-		}
-	}
-
-	while (true) {
-		const password = await secretInput(ctx, "输入云凭据主密码以解锁");
-		if (password === undefined) return undefined;
-		try { return { password, payload: readCloudVault(password, vaultPath) }; }
-		catch (error) {
-			notify(ctx, error instanceof Error ? error.message : String(error), "error");
-			if (!(await ctx.ui.confirm("重新输入主密码？", "凭据未解锁，HWCode Cloud 尚未启动。"))) return undefined;
-		}
-	}
-}
-
-async function collectCredentials(vendor: CloudVendorId, root: string, ctx: ExtensionCommandContext): Promise<CloudCredentials | undefined> {
-	const credentials: CloudCredentials = {};
-	for (const field of getCloudProvider(vendor).credentialFields) {
-		let value = field.secret ? await secretInput(ctx, field.label) : await ctx.ui.input(field.label, field.placeholder);
-		if (value === undefined) return undefined;
-		value = value.trim();
-		if (!value && !field.optional) { notify(ctx, `${field.label} 不能为空。`, "warning"); return collectCredentials(vendor, root, ctx); }
-		if (!value) continue;
-		if (field.fileContents) {
-			const path = isAbsolute(value) ? value : resolve(root, value);
-			try { const contents = readFileSync(path, "utf8"); JSON.parse(contents); credentials[field.key] = contents; }
-			catch (error) {
-				notify(ctx, `无法读取有效的 JSON 凭据文件 ${path}: ${error instanceof Error ? error.message : String(error)}`, "error");
-				return collectCredentials(vendor, root, ctx);
-			}
-		} else credentials[field.key] = value;
-	}
-	if (vendor === "gcp") {
-		const account = JSON.parse(credentials.serviceAccountJson) as Record<string, unknown>;
-		credentials.projectId ||= typeof account.project_id === "string" ? account.project_id : "";
-		if (!credentials.projectId) { notify(ctx, "Service Account JSON 中没有 project_id，请重新输入。", "error"); return collectCredentials(vendor, root, ctx); }
-	}
-	return credentials;
-}
-
-function activationPrompt(state: WorkflowState): string {
-	const details = cloudDetails(state)!;
-	const guidance = details.templateGuidance
-		? `\n\nReusable template guidance (${details.sourceTemplate?.name ?? "saved template"}):\n${details.templateGuidance}`
-		: "";
-	return `/skill:hwcode-cloud HWCode Cloud workflow activated.\n\nLocked project root: ${state.root}\nCloud provider: ${getCloudProvider(details.vendor).label}\nDeploy current project: ${details.deployCurrentProject ? "yes" : "no"}\nUser objective:\n${details.request}${guidance}\n\nCredentials were validated and remain outside model context. Use hwcode_cloud_exec for every cloud or infrastructure command.`;
-}
-
-async function approveOperation(operation: CloudOperation, params: { command: string; args: string[]; intent: string }, state: WorkflowState, ctx: ExtensionContext): Promise<"allow" | "allow-session" | "deny"> {
-	if (operation === "read") return "allow";
-	if (!ctx.hasUI) return "deny";
-	const details = cloudDetails(state)!;
-	const command = `${params.command} ${params.args.join(" ")}`;
-	if (operation === "delete") return await ctx.ui.confirm("确认删除云资源？", `目标：${params.intent}\n命令：${command}\n\n删除操作始终逐次确认。`) ? "allow" : "deny";
-	if (details.allowNonDeleteChanges) return "allow";
-	const choice = await ctx.ui.select("允许修改云账号内资源？", ["仅允许本次", "允许本会话后续非删除变更，不再询问", "拒绝"]);
-	if (choice === "仅允许本次") return "allow";
-	if (choice === "允许本会话后续非删除变更，不再询问") return "allow-session";
-	return "deny";
-}
-
-function normalizeApproach(value: string): string { return value.trim().toLowerCase().replace(/\s+/gu, " ").slice(0, 160); }
-function safeStepText(value: string, credentials: CloudCredentials): string {
-	return redactCredentialValues(value.replace(/[\r\n]+/gu, " ").slice(0, 2_000), credentials);
-}
-
-export default function cloudExtension(pi: ExtensionAPI) {
-	let activeState: WorkflowState | undefined;
-	let activeCredentials: CloudCredentials | undefined;
-	const credentialDirectories = new Set<string>();
-	const temporaryStore: TemporaryCredentialStore = {
-		createDirectory(prefix) {
-			const directory = mkdtempSync(`${tmpdir()}/${prefix}`);
-			credentialDirectories.add(directory);
-			return directory;
-		},
-		cleanupDirectory(directory) {
-			if (existsSync(directory)) rmSync(directory, { recursive: true, force: true });
-			credentialDirectories.delete(directory);
-		},
-	};
-
-	function cleanupCredentialDirectories(): void {
-		for (const directory of [...credentialDirectories]) temporaryStore.cleanupDirectory(directory);
-	}
-
-	function replaceDetails(state: WorkflowState, details: CloudWorkflowDetails, phase = state.phase): WorkflowState {
-		const updated = updateWorkflowState(state, { details, phase });
-		activeState = updated;
-		appendWorkflowState(pi, updated);
-		return updated;
-	}
-
-	async function ensureConversationModel(ctx: ExtensionCommandContext): Promise<boolean> {
-		let environment: Record<string, string | undefined> = {};
-		if (ctx.model) {
-			try {
-				environment = (await ctx.modelRegistry.getProviderAuth(ctx.model.provider))?.env ?? {};
-			} catch {
-				// The readiness check below reports the actionable model configuration error.
-			}
-		}
-		const issue = modelConfigurationIssue(ctx.model, environment);
-		if (!issue) return true;
-		notify(
-			ctx,
-			`${issue}。HWCode 不会替你选择或覆盖默认模型；请先使用 Pi 原生 /model 切换模型，或补全该 provider 的 endpoint 配置。`,
-			"error",
-		);
-		return false;
-	}
-
-	async function chooseTemplate(ctx: ExtensionCommandContext): Promise<CloudPromptTemplate | undefined> {
-		const templates = listCloudPromptTemplates();
-		if (templates.length === 0) {
-			notify(ctx, "还没有本地 Cloud Prompt Template。成功执行任务后使用 /hwcode-cloud-save-template 保存。", "warning");
-			return undefined;
-		}
-		const labels = templates.map((template) => `${template.name} · ${formatTemplateTime(template.updatedAt)}`);
-		const selected = await ctx.ui.select(
-			"选择已验证的 Cloud Prompt Template",
-			labels,
-		);
-		const selectedIndex = selected ? labels.indexOf(selected) : -1;
-		return selectedIndex >= 0 ? templates[selectedIndex] : undefined;
-	}
-
-	async function activate(args: string, ctx: ExtensionCommandContext, initialTemplate?: CloudPromptTemplate): Promise<void> {
-		if (ctx.mode !== "tui") { notify(ctx, "HWCode Cloud 要求在交互式 TUI 中启动，以安全遮罩凭据输入。", "error"); return; }
-		if (!ctx.isIdle()) { notify(ctx, "请等待当前响应完成后再启动 HWCode Cloud。", "warning"); return; }
-		if (!(await ensureConversationModel(ctx))) return;
-
-		const root = canonicalizeWorkspaceRoot(getWorkingDirectory(ctx.sessionManager));
-		const currentWorkflow = activeWorkflow(ctx.sessionManager.getEntries());
-		if (currentWorkflow && currentWorkflow.mode !== "cloud") {
-			notify(ctx, `当前会话已有 ${currentWorkflow.mode} workflow。请新建 session 后再启动 HWCode Cloud。`, "warning");
-			return;
-		}
-		const storedState = restoreCloudWorkflow(ctx) ?? restoreLegacyCloudWorkflow(ctx);
-		let resumedState: WorkflowState | undefined;
-		if (storedState && storedState.root === root && !cloudDetails(storedState)?.terminalFailure) {
-			const storedDetails = cloudDetails(storedState)!;
-			const choice = await ctx.ui.select("发现当前会话中未完成的 HWCode Cloud workflow", [
-				`恢复 ${getCloudProvider(storedDetails.vendor).label}：${storedDetails.request.slice(0, 60)}`,
-				"开始新的 Cloud workflow",
-				"取消",
-			]);
-			if (!choice || choice === "取消") return;
-			if (choice.startsWith("恢复 ")) resumedState = storedState;
-		}
-
-		let template = initialTemplate;
-		if (!resumedState && !template && !args.trim() && listCloudPromptTemplates().length > 0) {
-			const source = await ctx.ui.select("Cloud 任务来源", ["新建任务", "使用已有 Prompt Template", "取消"]);
-			if (!source || source === "取消") return;
-			if (source === "使用已有 Prompt Template") {
-				template = await chooseTemplate(ctx);
-				if (!template) return;
-			}
-		}
-
-		let vendor: CloudVendorId;
-		let deployCurrentProject: boolean;
-		let request: string;
-		let templateGuidance: string | undefined;
-		if (resumedState) {
-			const details = cloudDetails(resumedState)!;
-			vendor = details.vendor;
-			deployCurrentProject = details.deployCurrentProject;
-			request = details.request;
-		} else if (template) {
-			vendor = template.vendor;
-			deployCurrentProject = template.deployCurrentProject;
-			request = template.objective || template.name;
-			templateGuidance = expandCloudPromptTemplate(template, args);
-		} else {
-			const label = await ctx.ui.select("选择需要对接的云计算厂商", CLOUD_PROVIDERS.map((provider) => provider.label));
-			if (!label) return;
-			vendor = CLOUD_PROVIDERS.find((provider) => provider.label === label)!.id;
-			const deployment = await ctx.ui.select("是否部署当前项目？", ["是，部署当前项目", "否，执行其他云任务"]);
-			if (!deployment) return;
-			deployCurrentProject = deployment.startsWith("是");
-			const entered = (await ctx.ui.editor("描述需要执行的具体需求", args.trim()))?.trim();
-			if (!entered) { notify(ctx, "必须提供明确的云任务需求，HWCode Cloud 未启动。", "warning"); return; }
-			request = entered;
-		}
-
-		const vendorLabel = getCloudProvider(vendor).label;
-		const cliCheck = await checkProviderCli(vendor, root);
-		if (cliCheck.spawnErrorCode === "ENOENT") { notify(ctx, missingCloudCliMessage(vendor), "error"); return; }
-		if (cliCheck.spawnErrorCode === "EACCES") { notify(ctx, inaccessibleCloudCliMessage(vendor), "error"); return; }
-
-		const vaultPath = defaultCloudVaultPath();
-		if (!(await ctx.ui.confirm("安全保存云账户信息？", [
-			`当前项目根目录将锁定为：\n${root}`,
-			`凭据将使用主密码派生密钥，以 AES-256-GCM 加密保存到：\n${vaultPath}`,
-			"文件权限限制为当前用户读写，不会发送给模型或上传至 HWCode 服务。",
-			"连接校验和后续命令只会把凭据提交给所选云厂商的官方认证端点或 CLI。",
-			"如果忘记主密码，加密凭据无法恢复。",
-		].join("\n\n")))) return;
-
-		const unlocked = await unlockVault(ctx);
-		if (!unlocked) return;
-		const profiles = listCloudCredentialProfiles(unlocked.payload, vendor);
-		let selectedProfile: CloudCredentialProfile | undefined;
-		let credentials: CloudCredentials | undefined;
-		if (profiles.length > 0) {
-			const labels = profiles.map((profile, index) => cloudCredentialProfileLabel(profile, index, profiles.length));
-			const choice = await ctx.ui.select(`选择 ${vendorLabel} 凭据`, [...labels, "新建凭据", "取消"]);
-			if (!choice || choice === "取消") return;
-			const selectedIndex = labels.indexOf(choice);
-			if (selectedIndex >= 0) {
-				selectedProfile = profiles[selectedIndex];
-				credentials = { ...selectedProfile.credentials };
-			}
-		}
-
-		while (true) {
-			credentials ??= await collectCredentials(vendor, root, ctx);
-			if (!credentials) return;
-			notify(ctx, `正在校验 ${vendorLabel} 连接…`);
-			const validation = await validateCloudCredentials(vendor, { root, credentials, temporaryStore });
-			if (validation.code === 0) break;
-			if (validation.spawnErrorCode === "ENOENT") { notify(ctx, missingCloudCliMessage(vendor), "error"); return; }
-			if (validation.spawnErrorCode === "EACCES") { notify(ctx, inaccessibleCloudCliMessage(vendor), "error"); return; }
-			notify(ctx, `连接校验失败：${formatValidationFailure(validation, credentials)}`, "error");
-			if (!(await ctx.ui.confirm("重新输入账户信息？", "连接尚未建立。请检查凭据、账号状态、网络及对应云 CLI。"))) return;
-			credentials = undefined;
-		}
-
-		writeCloudVault(
-			saveCloudCredentialProfile(unlocked.payload, vendor, credentials, selectedProfile?.id),
-			unlocked.password,
-			vaultPath,
-		);
-		cleanupCredentialDirectories();
-		activeCredentials = credentials;
-		activeState = resumedState ?? createCloudWorkflowState(
-			root,
-			vendor,
-			deployCurrentProject,
-			request,
-			template && templateGuidance ? {
-				source: cloudPromptTemplateSource(template),
-				guidance: templateGuidance,
-			} : undefined,
-		);
-		appendWorkflowState(pi, activeState);
-		notify(ctx, `${vendorLabel} 连接成功。凭据已加密保存，项目根目录锁定为 ${root}。`);
-		pi.sendUserMessage(activationPrompt(activeState), { expandPromptTemplates: true });
-	}
-
-	pi.registerCommand("hwcode-cloud", {
-		description: "Start or resume the guarded HWCode cloud workflow",
-		handler: (args, ctx) => activate(args, ctx),
-	});
-	pi.registerCommand("hwcode-cloud-template", {
-		description: "Start HWCode Cloud from a locally saved successful template",
-		handler: async (args, ctx) => {
-			const template = await chooseTemplate(ctx);
-			if (template) await activate(args, ctx, template);
-		},
-	});
-	pi.registerCommand("hwcode-cloud-save-template", {
-		description: "Save the successful Cloud execution path as a local Cloud Prompt Template",
-		handler: async (args, ctx) => {
-			activeState = restoreCloudWorkflow(ctx) ?? activeState;
-			const details = activeState && cloudDetails(activeState);
-			if (!activeState || !details || details.successfulSteps.length === 0) {
-				notify(ctx, "当前 Cloud workflow 还没有成功执行步骤，无法生成可复用模板。", "warning");
-				return;
-			}
-
-			const result = await saveCloudWorkflowTemplate({
-				state: activeState,
-				requestedName: args,
-				redact: activeCredentials
-					? (value) => redactCredentialValues(value, activeCredentials!)
-					: undefined,
-				interaction: {
-					async chooseSourceAction(source) {
-						const updateLabel = `更新原模板「${source.name}」`;
-						const choice = await ctx.ui.select(
-							`当前会话关联模板「${details.sourceTemplate?.name ?? source.name}」`,
-							[updateLabel, "创建新模板", "取消"],
-						);
-						if (!choice || choice === "取消") return "cancel";
-						return choice === updateLabel ? "update" : "create";
-					},
-					inputName: (defaultName) => ctx.ui.input("模板名称", defaultName),
-					editNotes: (initialNotes) => ctx.ui.editor(
-						"补充必要前置条件、成功经验及必须避免的高消耗错误路径（可留空；不得包含凭据）",
-						initialNotes,
-					),
-					sourceMissing(sourceName) {
-						notify(ctx, `本次使用的原模板「${sourceName}」已不存在，将创建新模板。`, "warning");
-					},
-				},
-				store: {
-					list: () => listCloudPromptTemplates(),
-					create: (name, state, notes) => saveCloudPromptTemplate(name, state, undefined, notes),
-					update: (template, state, notes) => updateCloudPromptTemplate(template, state, notes),
-				},
-			});
-			if (result.status === "cancelled") return;
-			activeState = replaceDetails(activeState, result.details);
-			const action = result.action === "updated" ? "已更新" : "已创建";
-			notify(ctx, `${action}模板「${result.template.name}」（${formatTemplateTime(result.template.updatedAt)}）。使用 /hwcode-cloud-template 可立即复用。`);
-		},
-	});
-
-	pi.registerTool(defineTool({
-		name: "hwcode_cloud_exec",
-		label: "HWCode Cloud",
-		description: "Run one cloud or infrastructure CLI command with isolated credentials and unified workspace/resource approvals.",
-		promptSnippet: "Execute credential-isolated cloud CLI commands with mandatory resource-change approvals.",
-		parameters: Type.Object({
-			command: Type.String({ description: "Executable name only" }),
-			args: Type.Array(Type.String(), { description: "Argument vector; never include credentials or shell syntax" }),
-			operation: Type.Union([Type.Literal("read"), Type.Literal("change"), Type.Literal("delete")]),
-			intent: Type.String({ description: "Concise description of what this command inspects or changes" }),
-			approach: Type.String({ description: "Stable name for this technical approach" }),
-		}),
-		executionMode: "sequential",
-		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
-			activeState = restoreCloudWorkflow(ctx) ?? activeState;
-			let details = activeState && cloudDetails(activeState);
-			if (!activeState || !details) {
-				return { content: [{ type: "text", text: "HWCode Cloud is not active. Run /hwcode-cloud first." }], isError: true, details: {} };
-			}
-			if (details.terminalFailure) {
-				return { content: [{ type: "text", text: "HWCode Cloud stopped after three distinct failed approaches. Summarize the reason, progress, and changes; do not execute more cloud operations." }], isError: true, details: { terminalFailure: true } };
-			}
-			if (!activeCredentials) {
-				return { content: [{ type: "text", text: "Cloud credentials are locked after restoration. Run /hwcode-cloud to unlock and validate them." }], isError: true, details: {} };
-			}
-			if (basename(params.command) !== params.command || !CLOUD_EXECUTABLES.has(params.command)) {
-				return { content: [{ type: "text", text: `Unsupported executable: ${params.command}` }], isError: true, details: {} };
-			}
-			const providerCli = getCloudProvider(details.vendor).cli;
-			if (params.command !== providerCli && !ORCHESTRATION_COMMANDS.has(params.command)) {
-				return { content: [{ type: "text", text: `${params.command} does not match the active ${details.vendor} provider.` }], isError: true, details: {} };
-			}
-			if (params.args.some((argument) => SENSITIVE_ARGUMENT.test(argument))) {
-				return { content: [{ type: "text", text: "Credential-like command arguments are forbidden. HWCode injects credentials outside model context." }], isError: true, details: {} };
-			}
-
-			const operation = classifyCloudOperation(params.command, params.args, params.operation as CloudOperation);
-			const external = evaluateCommandArgumentsAccess(params.command, params.args, activeState.root);
-			if (external.length > 0) {
-				const summary = external.map((entry) => `• ${entry.raw} → ${entry.resolved}`).join("\n");
-				if (!ctx.hasUI || !(await ctx.ui.confirm(
-					"允许本次云工具访问项目目录之外的路径？",
-					`项目根目录：${activeState.root}\n\n${summary}\n\n该授权仅适用于本次命令。`,
-				))) {
-					return { content: [{ type: "text", text: `User denied external path access:\n${summary}` }], isError: true, details: { denied: true } };
-				}
-				pi.appendEntry(WORKFLOW_EXTERNAL_AUDIT_TYPE, {
-					mode: "cloud", root: activeState.root, toolName: "hwcode_cloud_exec", external,
-					approvedAt: new Date().toISOString(),
-				});
-			}
-
-			const approval = await approveOperation(operation, params, activeState, ctx);
-			if (approval === "deny") {
-				return { content: [{ type: "text", text: `User denied ${operation} operation: ${params.intent}` }], isError: true, details: { denied: true, operation } };
-			}
-			if (approval === "allow-session") {
-				activeState = replaceDetails(activeState, { ...details, allowNonDeleteChanges: true });
-				details = cloudDetails(activeState)!;
-			}
-
-			const prepared = await prepareCloudExecution(details.vendor, params.command, params.args, {
-				root: activeState.root, credentials: activeCredentials, temporaryStore, signal,
-			});
-			let result: ProcessResult;
-			try {
-				result = prepared.error
-					? { stdout: "", stderr: prepared.error, code: 1, killed: false }
-					: await runProcess(params.command, prepared.args, { cwd: activeState.root, env: prepared.env, signal });
-			} finally { prepared.cleanup?.(); }
-
-			const stdout = truncateOutput(redactCredentialValues(result.stdout, activeCredentials));
-			const stderr = truncateOutput(redactCredentialValues(result.stderr, activeCredentials));
-			pi.appendEntry(CLOUD_AUDIT_TYPE, {
-				vendor: details.vendor, command: params.command, operation, intent: params.intent,
-				approach: params.approach, exitCode: result.code, executedAt: new Date().toISOString(),
-			});
-
-			if (result.code !== 0) {
-				const normalized = normalizeApproach(params.approach);
-				const alreadyFailed = details.failedApproaches.some((failure) => normalizeApproach(failure.approach) === normalized);
-				const failedApproaches = !alreadyFailed && normalized
-					? [...details.failedApproaches, {
-						approach: params.approach.trim(),
-						reason: (stderr.trim() || stdout.trim() || `exit code ${result.code}`).slice(0, 1_000),
-						failedAt: new Date().toISOString(),
-					}]
-					: details.failedApproaches;
-				const terminalFailure = failedApproaches.length >= MAX_FAILED_APPROACHES;
-				replaceDetails(activeState, { ...details, failedApproaches, terminalFailure }, terminalFailure ? "failed" : "executing");
-				const suffix = terminalFailure
-					? "\n\nTERMINAL FAILURE: Three materially different approaches failed. Explain causes and summarize progress and changes. Do not try another cloud operation."
-					: `\n\nDistinct failed approaches: ${failedApproaches.length}/${MAX_FAILED_APPROACHES}.`;
-				return {
-					content: [{ type: "text", text: `Cloud command failed with exit code ${result.code}.\n${stderr || stdout}${suffix}` }],
-					isError: true,
-					details: { operation, exitCode: result.code, terminalFailure },
-				};
-			}
-
-			const successfulSteps = [...details.successfulSteps, {
-				command: safeStepText(params.command, activeCredentials),
-				args: params.args.map((argument) => safeStepText(argument, activeCredentials)),
-				operation,
-				intent: safeStepText(params.intent, activeCredentials),
-				approach: safeStepText(params.approach, activeCredentials),
-				completedAt: new Date().toISOString(),
-			}].slice(-MAX_SUCCESSFUL_STEPS);
-			replaceDetails(activeState, { ...details, successfulSteps }, "executing");
-			return {
-				content: [{ type: "text", text: stdout.trim() || stderr.trim() || "Cloud command completed successfully." }],
-				details: { operation, exitCode: 0 },
-			};
-		},
-	}));
-
-	pi.on("session_start", async (_event, ctx) => {
-		activeState = restoreCloudWorkflow(ctx);
-		if (!activeState) {
-			activeState = restoreLegacyCloudWorkflow(ctx);
-			if (activeState) appendWorkflowState(pi, activeState);
-		}
-		activeCredentials = undefined;
-		cleanupCredentialDirectories();
-		if (!activeState) return;
-		const root = canonicalizeWorkspaceRoot(getWorkingDirectory(ctx.sessionManager));
-		if (root !== activeState.root) {
-			appendWorkflowState(pi, updateWorkflowState(activeState, {
-				status: "cancelled", phase: "root-changed", reason: "working directory changed",
-			}));
-			activeState = undefined;
-			notify(ctx, "Stored HWCode Cloud workflow disabled because the current directory changed.", "warning");
-			return;
-		}
-		const details = cloudDetails(activeState)!;
-		if (!details.terminalFailure) {
-			notify(ctx, `HWCode Cloud session restored for ${getCloudProvider(details.vendor).label}. Credentials are locked; run /hwcode-cloud to unlock before continuing.`, "warning");
-		}
-	});
-
-	pi.on("before_agent_start", async (event, ctx) => {
-		activeState = restoreCloudWorkflow(ctx) ?? activeState;
-		const details = activeState && cloudDetails(activeState);
-		if (!activeState || !details) return undefined;
-		const failureRule = details.terminalFailure
-			? "Three distinct approaches already failed. Only summarize causes, progress, and changes; do not continue execution."
-			: `Distinct failed approaches: ${details.failedApproaches.length}/${MAX_FAILED_APPROACHES}. After the third distinct approach fails, stop and summarize.`;
-		return {
-			systemPrompt: `${event.systemPrompt}\n\nHWCODE CLOUD ACTIVE\nProvider: ${details.vendor}\nObjective: ${details.request}\nCredentials must never be requested in chat, printed, placed in tool arguments, or read from the vault. Use hwcode_cloud_exec for all cloud and infrastructure operations. Resource creates and changes require approval unless the user opted out; deletion always requires approval. After success, offer /hwcode-cloud-save-template to preserve the validated path locally. ${failureRule}`,
-		};
-	});
-
-	pi.on("tool_call", async (event, ctx) => {
-		activeState = restoreCloudWorkflow(ctx) ?? activeState;
-		if (!activeState || event.toolName !== "bash") return undefined;
-		const input = event.input as Record<string, unknown>;
-		if (typeof input.command !== "string" || !containsCloudCommand(input.command)) return undefined;
-		return {
-			block: true,
-			reason: "Direct cloud and infrastructure CLI use is blocked during HWCode Cloud. Use hwcode_cloud_exec so credentials remain isolated and approvals are enforced.",
-		};
-	});
-
-	pi.on("session_shutdown", async () => {
-		activeState = undefined;
-		activeCredentials = undefined;
-		cleanupCredentialDirectories();
-	});
-}