/**
 * ActionPlan — 结构化行动意图。
 *
 * LoopKernel 的 ActionRouter 输出 ActionPlan，不直接触发工具。
 * ControlFrame 消费 ActionPlan 和 GateDecision 决定执行。
 *
 * @see docs/AGENT_GATE_LOOP_REFACTOR_PLAN.md — "Action Interfaces"
 */

// ---------------------------------------------------------------------------
// Gate event types (inline; will migrate to ../kernel/events.ts when ready)
// ---------------------------------------------------------------------------

/** 门禁严重度。 */
export type GateSeverity = "hard-deny" | "soft-deny" | "evidence-required" | "warning";

/** 门禁检查点。 */
export type GateCheckpoint =
	| "pre-input"
	| "pre-plan"
	| "pre-phase-transition"
	| "pre-tool"
	| "post-tool"
	| "pre-write"
	| "post-write"
	| "pre-verify-command"
	| "post-verify-result"
	| "pre-delegation"
	| "post-delegation"
	| "pre-context-compile"
	| "post-context-compile";

// ---------------------------------------------------------------------------
// ActionPlan
// ---------------------------------------------------------------------------

/** ActionPlanKind — LoopKernel 可调度的行动类型。 */
export type ActionPlanKind = "write-code" | "ask-user" | "read-context" | "verify" | "delegate" | "stop";

/**
 * ActionPlan — 通过门禁的结构化行动意图。
 *
 * 每个 ActionPlan 必须：
 * - 绑定一个 CompletionPromise（completionPromiseId）。
 * - 携带门禁追踪 ID（gateTraceId）。
 * - 声明明确的 kind 和 intent。
 */
export interface ActionPlan {
	/** 唯一标识，格式：plan-{timestamp}-{random_hex_4}。 */
	planId: string;

	/** 行动类型。 */
	kind: ActionPlanKind;

	/** 意图描述——人类可读，说明本次行动要做什么。 */
	intent: string;

	/** 关联的 Completion Promise ID。 */
	completionPromiseId: string;

	/** 关联的门禁决策追踪 ID。 */
	gateTraceId: string;

	/** 行动参数，结构由 kind 决定。 */
	parameters: Record<string, unknown>;

	/** 行动约束。 */
	constraints: ActionPlanConstraints;
}

/** ActionPlan 的执行约束。 */
export interface ActionPlanConstraints {
	/** 最大工具调用次数。 */
	maxToolCalls?: number;

	/** 是否允许写入文件。 */
	allowWrite: boolean;

	/** 允许写入的路径列表（glob 模式）。 */
	allowedPaths?: string[];

	/** 最大委派次数。 */
	maxDelegations?: number;
}

// ---------------------------------------------------------------------------
// Plan ID generation
// ---------------------------------------------------------------------------

/**
 * 生成 planId：plan-{timestamp}-{random_hex_4}。
 *
 * @example "plan-1717980000000-a3f1"
 */
export function generatePlanId(): string {
	const timestamp = Date.now();
	const randomHex = Math.floor(Math.random() * 0x10000)
		.toString(16)
		.padStart(4, "0");
	return `plan-${timestamp}-${randomHex}`;
}

// ---------------------------------------------------------------------------
// Factory
// ---------------------------------------------------------------------------

/**
 * 创建 ActionPlan 实例。
 *
 * @param kind - 行动类型。
 * @param intent - 意图描述。
 * @param completionPromiseId - 关联的 Completion Promise ID。
 * @param gateTraceId - 关联的门禁追踪 ID。
 * @param parameters - 行动参数。
 * @param constraints - 执行约束。
 * @returns 新建的 ActionPlan。
 */
export function createActionPlan(
	kind: ActionPlanKind,
	intent: string,
	completionPromiseId: string,
	gateTraceId: string,
	parameters: Record<string, unknown>,
	constraints: ActionPlanConstraints,
): ActionPlan {
	return {
		planId: generatePlanId(),
		kind,
		intent,
		completionPromiseId,
		gateTraceId,
		parameters,
		constraints,
	};
}