// Copyright (c) 2026 Hellmai Ltd
// SPDX-License-Identifier: AGPL-3.0-only
//
// WU-2732 (INIT-060 Phase 3, ADR-013 §1 + §6 tracer bullet):
// Remote-control tool name registry and port/result shapes. The six
// tools here form the conductor-mode governance surface for the
// agent-runtime pack. Real implementations land in WU-2733; this file
// defines the wire contract the real impl must satisfy without
// re-deciding tool names or payload shapes.

import type { AgentRuntimeCleanupStatus } from '../turn-lifecycle-events.js';

/**
 * Canonical remote-control tool names. Prefixed with the pack slug per
 * ADR-013 §Event Namespacing convention (extended to tool names for
 * consistency with WU-2729 software-delivery pack exposure precedent).
 */
export const AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES = {
  RESUME_WORKFLOW: 'agent-runtime:resume_workflow',
  PAUSE_TURN: 'agent-runtime:pause_turn',
  ABORT_TURN: 'agent-runtime:abort_turn',
  ELEVATE_AUTONOMY: 'agent-runtime:elevate_autonomy',
  LOWER_AUTONOMY: 'agent-runtime:lower_autonomy',
  APPROVE_INFLIGHT: 'agent-runtime:approve_inflight',
} as const;

export type AgentRuntimeRemoteControlToolName =
  (typeof AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES)[keyof typeof AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES];

/**
 * Declaration order matters: callers (HTTP surface allowlist, conductor
 * UI) render the list in this sequence without re-sorting.
 */
export const AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAME_VALUES = [
  AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.RESUME_WORKFLOW,
  AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.PAUSE_TURN,
  AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.ABORT_TURN,
  AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.ELEVATE_AUTONOMY,
  AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.LOWER_AUTONOMY,
  AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.APPROVE_INFLIGHT,
] as const satisfies readonly AgentRuntimeRemoteControlToolName[];

/**
 * Well-known approval identifier the agent-runtime pack requests for
 * safety-critical remote controls (abort, pause, elevate). Single
 * identifier per ADR-013 §6 governance lock — cloud renders the same
 * approval gate regardless of which of the gated tools was invoked.
 */
export const AGENT_RUNTIME_REMOTE_CONTROL_APPROVAL_ID = 'agent-runtime:remote_control' as const;

/**
 * Mapping from remote-control tool name to its declared
 * `required_approvals` manifest entry. Gated tools request an explicit
 * approval identifier; safer/read-only tools declare an empty array so
 * the manifest stays minimally descriptive (matches WU-2729 convention).
 */
export const AGENT_RUNTIME_REMOTE_CONTROL_APPROVALS: Record<
  AgentRuntimeRemoteControlToolName,
  readonly string[]
> = {
  [AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.RESUME_WORKFLOW]: [],
  [AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.PAUSE_TURN]: [AGENT_RUNTIME_REMOTE_CONTROL_APPROVAL_ID],
  [AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.ABORT_TURN]: [AGENT_RUNTIME_REMOTE_CONTROL_APPROVAL_ID],
  [AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.ELEVATE_AUTONOMY]: [
    AGENT_RUNTIME_REMOTE_CONTROL_APPROVAL_ID,
  ],
  [AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.LOWER_AUTONOMY]: [],
  [AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.APPROVE_INFLIGHT]: [],
};

/**
 * Deterministic mock session identifier returned by tracer-bullet
 * implementations. The real impl in WU-2733 reads the session from the
 * input payload; the mock returns a fixed value so round-trip tests
 * pin the wire contract without leaking runtime state.
 */
export const MOCK_SESSION_ID = 'agent-runtime-remote-control-mock-session' as const;

/**
 * Shared result shape for the five non-abort remote controls. Real
 * impls may extend this — the additive-only rule lets WU-2733 land
 * without contract drift.
 */
export interface RemoteControlInvocationResult {
  status: 'ok';
  tool_name: AgentRuntimeRemoteControlToolName;
  session_id: string;
}

/**
 * abort_turn carries the ADR-013 §1 abort contract: cleanup_status +
 * recovery_action. Cloud renders recovery_action as a hint; NEVER
 * auto-executes (see ADR-013 §1 safety lock).
 */
export interface AbortTurnInvocationResult {
  status: 'ok';
  tool_name: typeof AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.ABORT_TURN;
  session_id: string;
  cleanup_status: AgentRuntimeCleanupStatus;
  recovery_action: string | null;
}

export type AnyRemoteControlInvocationResult =
  | RemoteControlInvocationResult
  | AbortTurnInvocationResult;
